fix(vv): resolve all 6 V&V issues — field trial unblocked

All findings from the inaugural LeadValidator audit resolved and
confirmed. Release gate: PASS.

VV_ISSUE_002 (BLOCKER): 15 OpenAPI specs verified present covering
all 20 route groups (46 endpoints documented in docs/openapi/)

VV_ISSUE_003 (MAJOR): Remove any types from src/db/pool.ts —
replaced pool.query shim with unknown[] + Object.defineProperty,
zero any types, eslint-disable suppressions removed

VV_ISSUE_004 (MAJOR): Remove raw Pool from ScaffoldController and
HealthDetailedController — injected AgentRepository/CredentialRepository
and DbProbe interface respectively; added CredentialRepository.findActiveClientId()

VV_ISSUE_005 (MAJOR): Add unit tests for 5 untested services —
ComplianceStatusStore, EventPublisher, MarketplaceService,
OIDCTrustPolicyService, UsageService

VV_ISSUE_006 (MAJOR): Add integration tests for 7 missing route
groups — analytics, billing, tiers, webhooks, marketplace,
oidc-trust-policies, oidc-token-exchange

VV_ISSUE_001 (MINOR): Create missing design.md and tasks.md in 4
OpenSpec archives — all archives now complete

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/openapi/scaffold.yaml

@@ -0,0 +1,257 @@
+openapi: "3.0.3"
+
+info:
+  title: SentryAgent.ai — SDK Scaffold Generator
+  version: 1.0.0
+  description: |
+    SDK scaffold generator endpoint for the SentryAgent.ai AgentIdP platform.
+
+    The scaffold endpoint generates a ready-to-run agent project ZIP archive
+    pre-configured with the agent's credentials, API URL, and chosen SDK.
+
+    The generated scaffold includes:
+    - Language-specific project structure (TypeScript / Python / Go / Java / Rust)
+    - Pre-filled `.env.example` with `CLIENT_ID` and `API_URL`
+    - Agent authentication boilerplate using the SentryAgent.ai SDK
+    - README with quickstart instructions
+    - Docker / CI configuration (where applicable)
+
+    **Authentication:** Requires a valid Bearer JWT.
+    **Rate limit:** 10 requests per minute per tenant (separate from the global limit).
+    The scaffold endpoint responds with `Retry-After` on rate limit.
+
+    **Supported languages:** `typescript`, `python`, `go`, `java`, `rust`
+
+servers:
+  - url: http://localhost:3000/api/v1
+    description: Local development server
+  - url: https://api.sentryagent.ai/v1
+    description: Production server
+
+tags:
+  - name: SDK Scaffold
+    description: Generate a ready-to-run agent SDK project scaffold
+
+components:
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: |
+        JWT access token obtained via `POST /token`.
+        Include as `Authorization: Bearer <token>`.
+
+  schemas:
+    ScaffoldLanguage:
+      type: string
+      enum:
+        - typescript
+        - python
+        - go
+        - java
+        - rust
+      description: Target programming language for the scaffold project.
+      example: typescript
+
+    ErrorResponse:
+      type: object
+      description: Standard error response envelope.
+      required:
+        - code
+        - message
+      properties:
+        code:
+          type: string
+          example: "AGENT_NOT_FOUND"
+        message:
+          type: string
+          example: "Agent with the specified ID was not found."
+        details:
+          type: object
+          additionalProperties: true
+
+  responses:
+    Unauthorized:
+      description: Missing or invalid Bearer token.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            code: "UNAUTHORIZED"
+            message: "A valid Bearer token is required to access this resource."
+
+    Forbidden:
+      description: Valid token but insufficient permissions.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            code: "FORBIDDEN"
+            message: "You do not have permission to access this agent's scaffold."
+
+    NotFound:
+      description: Agent not found.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            code: "AGENT_NOT_FOUND"
+            message: "Agent with the specified ID was not found."
+
+    TooManyRequests:
+      description: |
+        Scaffold-specific rate limit exceeded (10 requests per minute per tenant).
+        Retry after the duration specified in the `Retry-After` header.
+      headers:
+        Retry-After:
+          schema:
+            type: integer
+          description: Number of seconds to wait before retrying.
+          example: 60
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            code: "RATE_LIMIT_EXCEEDED"
+            message: "Scaffold rate limit exceeded. Please retry after 60 seconds."
+
+    InternalServerError:
+      description: Unexpected server error.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ErrorResponse'
+          example:
+            code: "INTERNAL_SERVER_ERROR"
+            message: "An unexpected error occurred. Please try again later."
+
+security:
+  - BearerAuth: []
+
+paths:
+  /sdk/scaffold/{agentId}:
+    get:
+      operationId: getAgentScaffold
+      tags:
+        - SDK Scaffold
+      summary: Generate and download an agent SDK scaffold ZIP
+      description: |
+        Generates a ready-to-run agent project scaffold for the specified agent
+        and streams it as a ZIP file download.
+
+        The scaffold is customized with:
+        - The agent's `CLIENT_ID` pre-filled in `.env.example`
+        - The platform API URL (`API_URL`) configured for the environment
+        - The agent's name, type, and capabilities reflected in project metadata
+        - Language-specific SDK integration boilerplate
+
+        **Rate limit:** 10 requests per minute per tenant.
+        Exceeding this limit returns `429 Too Many Requests` with a `Retry-After` header.
+
+        **Language selection:** Pass the desired `language` query parameter.
+        Defaults to `typescript` when omitted.
+
+        **Authorization:** The authenticated agent (from Bearer token) must belong to
+        the same organization as the target agent (`agentId`). Cross-tenant scaffold
+        generation is not permitted.
+      parameters:
+        - name: agentId
+          in: path
+          required: true
+          description: UUID of the agent to generate a scaffold for.
+          schema:
+            type: string
+            format: uuid
+          example: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+        - name: language
+          in: query
+          required: false
+          description: |
+            Target programming language for the scaffold.
+            Defaults to `typescript` when omitted.
+          schema:
+            $ref: '#/components/schemas/ScaffoldLanguage'
+          example: typescript
+      responses:
+        '200':
+          description: |
+            Scaffold ZIP archive generated and streamed successfully.
+
+            The response body is a ZIP archive containing the generated project files.
+            Save it locally and unzip to get started:
+            ```
+            curl -O -J -H "Authorization: Bearer <token>" \
+              "https://api.sentryagent.ai/v1/sdk/scaffold/a1b2c3d4-e5f6-7890-abcd-ef1234567890?language=typescript"
+            unzip screener-001-scaffold.zip
+            cd screener-001-scaffold && npm install
+            ```
+          headers:
+            Content-Disposition:
+              schema:
+                type: string
+              description: |
+                Filename for the ZIP download.
+                Format: `attachment; filename="<agent-name>-scaffold.zip"`
+              example: 'attachment; filename="screener-001-scaffold.zip"'
+            Content-Type:
+              schema:
+                type: string
+              example: "application/zip"
+            X-RateLimit-Limit:
+              schema:
+                type: integer
+              description: Scaffold rate limit (requests per minute per tenant).
+              example: 10
+            X-RateLimit-Remaining:
+              schema:
+                type: integer
+              description: Remaining scaffold requests in the current window.
+              example: 9
+          content:
+            application/zip:
+              schema:
+                type: string
+                format: binary
+                description: ZIP archive of the generated scaffold project.
+        '400':
+          description: Invalid `language` query parameter.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              example:
+                code: "VALIDATION_ERROR"
+                message: "Invalid language. Supported languages are: typescript, python, go, java, rust."
+                details:
+                  field: "language"
+                  provided: "ruby"
+                  supported:
+                    - typescript
+                    - python
+                    - go
+                    - java
+                    - rust
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '422':
+          description: Agent is decommissioned — cannot generate scaffold for inactive agents.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              example:
+                code: "AGENT_DECOMMISSIONED"
+                message: "Cannot generate scaffold for a decommissioned agent."
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalServerError'