@thinkai/tai-api-contract 2.170.0 → 2.172.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.170.0
+  version: 2.172.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -92,6 +92,12 @@ tags:
       classified test-file inventory (unit, integration, acceptance/BDD, contract, E2E)
       with count-based presence and advisory 70/20/10 shape. Distinct from Agentic
       Foundation readiness `/readiness/test-pyramid*` (signal-inclusive presence).
+  - name: Evals
+    description: >
+      Workspace prompt/model eval suites (`/evals/*`) — authored golden cases with
+      deterministic expected-signal scoring, async runs (never scored on the request
+      path), and an Insights surface for regressions and token efficiency. Distinct
+      from AI Usage & Spend ingest and Agentic Foundation Token Efficiency (rubric I).
 
 paths:
   /admin/users/{userId}:
@@ -412,6 +418,162 @@ paths:
                 error: Forbidden
                 code: forbidden
 
+  /admin/assessment-manifest-validation:
+    post:
+      tags: [PlatformAdmin]
+      summary: Validate an assessment manifest before export
+      operationId: runAssessmentManifestValidation
+      description: >
+        Runs the fail-closed manifest check for one sold assessment. The server
+        ignores `manifest.validation` and `manifest.watermark` from the client.
+        `buyerDeliverable` is true only when the result is validated and
+        `shareMode` is internal. An external share-safe result can be validated
+        and is never the buyer file. Unset or exceeded tolerances fail. No
+        numeric tolerance is assumed. GitLab and Bitbucket fixtures are not part
+        of this operation.
+
+        **Authorization:** Bearer JWT required. Caller email must appear in `PLATFORM_ADMIN_EMAILS`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required:
+                - manifest
+                - workspaceId
+                - expectedWorkspaceId
+                - expectedRepositoryIds
+                - soldWindowComplete
+                - premiumAiAssessable
+                - namedPersonSectionIds
+                - tolerances
+              properties:
+                manifest:
+                  type: object
+                  required:
+                    - offerId
+                    - dictionaryVersion
+                    - validation
+                    - shareMode
+                    - watermark
+                    - scope
+                    - windows
+                    - sources
+                    - consent
+                    - sections
+                  properties:
+                    offerId:
+                      type: string
+                      enum: [engineering_readiness_baseline, agentic_ai_roi]
+                    dictionaryVersion:
+                      type: string
+                    validation:
+                      type: string
+                      enum: [validated, not_validated]
+                    shareMode:
+                      type: string
+                      enum: [internal, external]
+                    watermark:
+                      type: string
+                      nullable: true
+                      enum: ["NOT VALIDATED", "SAMPLE · SYNTHETIC DATA"]
+                    scope:
+                      type: object
+                    windows:
+                      type: object
+                    sources:
+                      type: array
+                      items:
+                        type: object
+                    consent:
+                      type: object
+                    sections:
+                      type: array
+                      items:
+                        type: object
+                workspaceId:
+                  type: string
+                expectedWorkspaceId:
+                  type: string
+                expectedRepositoryIds:
+                  type: array
+                  items:
+                    type: string
+                soldWindowComplete:
+                  type: boolean
+                premiumAiAssessable:
+                  type: boolean
+                namedPersonSectionIds:
+                  type: array
+                  items:
+                    type: string
+                tolerances:
+                  type: array
+                  items:
+                    type: object
+                    required: [id, status]
+                    properties:
+                      id:
+                        type: string
+                      status:
+                        type: string
+                        enum: [unset, exceeded, within]
+      responses:
+        "200":
+          description: Validation result. Client validation and watermark inputs are ignored.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [buyerDeliverable, validation, watermark, reasons, contentHash]
+                properties:
+                  buyerDeliverable:
+                    type: boolean
+                  validation:
+                    type: string
+                    enum: [validated, not_validated]
+                  watermark:
+                    type: string
+                    nullable: true
+                    enum: ["NOT VALIDATED"]
+                  reasons:
+                    type: array
+                    items:
+                      type: object
+                      required: [code, message]
+                      properties:
+                        code:
+                          type: string
+                        message:
+                          type: string
+                  contentHash:
+                    type: string
+        "400":
+          description: Body failed validation.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: manifest.offerId is not a known assessment offer
+                code: invalid_body
+        "401":
+          description: Missing or invalid JWT.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "403":
+          description: Caller is not a platform admin.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: forbidden
+
   /admin/readiness/token-usage:
     get:
       tags: [PlatformAdmin]
@@ -11783,189 +11945,557 @@ paths:
         "403":
           $ref: "#/components/responses/Forbidden"
 
-components:
-  securitySchemes:
-    bearerAuth:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
-      description: Supabase access token (`Authorization` header).
-
-  parameters:
-    WorkspaceId:
-      name: workspaceId
-      in: path
-      required: true
-      schema:
-        type: string
-    RepoId:
-      name: repoId
-      in: path
-      required: true
-      schema:
-        type: string
-        format: uuid
-    ProviderSlug:
-      name: providerSlug
-      in: path
-      required: true
-      description: >
-        Provider repository slug in `owner/repo` form (GitHub). Used for shareable public URLs;
-        resolves to the same row as `repoId` UUID internally.
-      schema:
-        type: string
-        minLength: 1
-        maxLength: 512
-        pattern: "^[^/]+/[^/]+$"
-        example: thinkai-llc/thinkai-platform-backend
-    ProjectId:
-      name: projectId
-      in: path
-      required: true
-      schema:
-        type: string
-    NotificationId:
-      name: id
-      in: path
-      required: true
-      schema:
-        type: string
-    WorkspaceMemberId:
-      name: memberId
-      in: path
-      required: true
-      schema:
-        type: string
-        format: uuid
-      description: Workspace member user id (`tai_users.id`).
-    WorkspaceInvitationToken:
-      name: token
-      in: path
-      required: true
-      schema:
-        type: string
-        minLength: 32
-      description: >
-        Opaque workspace invitation token from the emailed accept link. Only its SHA-256
-        hash is stored server-side; the plaintext is shown exactly once, in the email.
-    PrivacyRequestId:
-      name: requestId
-      in: path
-      required: true
-      schema:
-        type: string
-        format: uuid
-      description: Privacy request id (`tai_privacy_requests.id`).
-    FixId:
-      name: fixId
-      in: path
-      required: true
-      schema:
-        type: string
-        format: uuid
-    ReadinessIssueId:
-      name: issueId
-      in: path
-      required: true
-      schema:
-        type: string
-        format: uuid
-      description: Readiness issue id (`tai_workspace_repo_issues.id`).
-    InsightsProductivityRangeId:
-      name: rangeId
-      in: query
+  /workspaces/{workspaceId}/evals/suites:
+    get:
+      tags: [Evals]
+      summary: List eval suites for a workspace
       description: >
-        Productivity insights time range. Daily windows: `7d`, `30d`, `90d`, `180d`, or custom
-        `cr:YYYY-MM-DD:YYYY-MM-DD`. Weekly legacy: `4w`, `8w`, `q` (12 weeks), `12w`, `16w`.
-        Omit when using explicit `from`/`to` day bounds.
-      schema:
-        type: string
-        default: 4w
-    InsightsProductivityFrom:
-      name: from
-      in: query
+        Returns the latest version of each eval suite in the workspace (max 50 suites).
+        Requires workspace membership (`requireWorkspaceMember`). Empty workspace →
+        `{ "suites": [] }`.
+      operationId: listEvalSuites
+      x-test-coverage-skip: contract-only; HTTP/store coverage lands with evals-storage-api
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Suite list (latest version per suite)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalSuiteListDto"
+              example:
+                suites: []
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    post:
+      tags: [Evals]
+      summary: Create an eval suite
       description: >
-        Inclusive start of a daily window (`YYYY-MM-DD`). When set with `to`, overrides `rangeId`
-        for day-mode responses (max 180 days).
-      schema:
-        type: string
-        format: date
-    InsightsProductivityTo:
-      name: to
-      in: query
+        Creates a suite at `version: 1`. Requires workspace editor or admin
+        (`requireWorkspaceEditor`). Rejects when both `target.promptBody` is empty
+        and model fields are missing; when `cases` is empty (`400`
+        `eval_suite_cases_required`); or when the workspace already has 50 suites.
+        Each case must include at least one expected signal.
+      operationId: createEvalSuite
+      x-test-coverage-skip: contract-only; HTTP/store coverage lands with evals-storage-api
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateEvalSuiteBodyDto"
+            example:
+              name: Greeting quality
+              description: Fixture-backed smoke suite for the support greeting prompt
+              target:
+                promptBody: "You are a support agent. Greet the user by name."
+                promptKey: support-greeting
+                provider: cursor
+                modelName: gpt-4.1-mini
+              cases:
+                - id: case-hello
+                  name: Hello Alice
+                  input: '{"name":"Alice"}'
+                  fixtureCompletion: "Hello Alice, how can I help you today?"
+                  expectedSignals:
+                    - id: sig-contains-hello
+                      kind: contains
+                      value: "Hello Alice"
+                    - id: sig-not-sorry
+                      kind: not_contains
+                      value: "I cannot"
+      responses:
+        "201":
+          description: Suite created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalSuiteDto"
+        "400":
+          description: >
+            Validation failed — empty cases (`eval_suite_cases_required`), missing
+            target (prompt and model), invalid name/description lengths, case/signal
+            bounds, or malformed body.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              examples:
+                cases_required:
+                  value:
+                    error: At least one case is required
+                    code: eval_suite_cases_required
+                target_required:
+                  value:
+                    error: Suite target requires promptBody or provider+modelName
+                    code: eval_suite_target_required
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Authenticated but not a workspace editor/admin
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace editor role required
+                code: workspace_editor_required
+        "404":
+          description: Workspace not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: Workspace already has the maximum of 50 suites
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Maximum of 50 eval suites per workspace
+                code: eval_suite_limit_reached
+
+  /workspaces/{workspaceId}/evals/suites/{suiteId}:
+    get:
+      tags: [Evals]
+      summary: Get an eval suite (latest version)
       description: >
-        Inclusive end of a daily window (`YYYY-MM-DD`). When set with `from`, overrides `rangeId`
-        for day-mode responses (max 180 days).
+        Returns the latest version of the suite. Historical versions are retained for
+        runs via `suiteVersion` + snapshot on each run; this endpoint does not expose
+        prior versions. Requires workspace membership.
+      operationId: getEvalSuite
+      x-test-coverage-skip: contract-only; HTTP/store coverage lands with evals-storage-api
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/EvalSuiteId"
+      responses:
+        "200":
+          description: Suite (latest version)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalSuiteDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or suite not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    put:
+      tags: [Evals]
+      summary: Update an eval suite
+      description: >
+        Replaces mutable suite fields. Requires workspace editor or admin.
+        Changing `target`, `cases`, or `promptBody` increments `version` by 1 and
+        keeps prior versions immutable for historical runs. Cosmetic
+        name/description-only updates do not bump `version`. Same validation rules
+        as create (cases required, target required, bounds).
+      operationId: updateEvalSuite
+      x-test-coverage-skip: contract-only; HTTP/store coverage lands with evals-storage-api
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/EvalSuiteId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateEvalSuiteBodyDto"
+      responses:
+        "200":
+          description: Suite updated (possibly with bumped version)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalSuiteDto"
+        "400":
+          description: Validation failed (same codes as create)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Authenticated but not a workspace editor/admin
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace editor role required
+                code: workspace_editor_required
+        "404":
+          description: Workspace or suite not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/evals/suites/{suiteId}/runs:
+    get:
+      tags: [Evals]
+      summary: List recent eval runs for a suite
+      description: >
+        Returns the last 50 runs for the suite (newest first). Empty → `{ "runs": [] }`.
+        Requires workspace membership. Does not trigger scoring.
+      operationId: listEvalRuns
+      x-test-coverage-skip: contract-only; HTTP/store coverage lands with evals-storage-api
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/EvalSuiteId"
+      responses:
+        "200":
+          description: Run history (max 50)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalRunListDto"
+              example:
+                runs: []
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or suite not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    post:
+      tags: [Evals]
+      summary: Enqueue an eval suite run
+      description: >
+        Enqueues an async eval run. Returns `202` with `{ runId, status: "queued" }`.
+        Never scores on the request path — a worker claims the run, uses
+        `fixtureCompletion` when present (or live completion when provider credentials
+        exist), applies deterministic expected-signal scoring, and persists results.
+        Requires workspace editor or admin. At most one active (`queued`|`running`)
+        run per suite; a second POST returns `409` `eval_run_in_progress`.
+      operationId: enqueueEvalRun
+      x-test-coverage-skip: contract-only; HTTP/store coverage lands with evals-storage-api
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/EvalSuiteId"
+      responses:
+        "202":
+          description: Run queued
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalRunEnqueueResponseDto"
+              example:
+                runId: "22222222-2222-4222-8222-222222222222"
+                status: queued
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Authenticated but not a workspace editor/admin
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Workspace editor role required
+                code: workspace_editor_required
+        "404":
+          description: Workspace or suite not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: An active queued or running eval already exists for this suite
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: An eval run is already in progress for this suite
+                code: eval_run_in_progress
+
+  /workspaces/{workspaceId}/evals/suites/{suiteId}/runs/{runId}:
+    get:
+      tags: [Evals]
+      summary: Get an eval run with case results
+      description: >
+        Returns persisted run status and case results. While `queued` or `running`,
+        `caseResults` may be empty and `score` null. Requires workspace membership.
+        Does not trigger scoring.
+      operationId: getEvalRun
+      x-test-coverage-skip: contract-only; HTTP/store coverage lands with evals-storage-api
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/EvalSuiteId"
+        - $ref: "#/components/parameters/EvalRunId"
+      responses:
+        "200":
+          description: Run detail
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalRunDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace, suite, or run not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/evals/insights:
+    get:
+      tags: [Evals]
+      summary: Eval insights (regressions, tips, efficiency, model comparison)
+      description: >
+        Workspace-level Insights for prompt/model evals. Computes regressions when
+        prior score − current score ≥ 0.10 on the same suiteId+suiteVersion case set
+        (or suite score drop ≥ 0.10); prompt tips from failed signal notes / case
+        names; token efficiency averages over successful cases in the last succeeded
+        run per suite; and model comparison rollups. No succeeded runs → empty arrays
+        and null `tokenEfficiency`. Requires workspace membership. Distinct from
+        `/insights-recommendations` and AI Usage & Spend.
+      operationId: getEvalInsights
+      x-test-coverage-skip: contract-only; HTTP/store coverage lands with evals-storage-api
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Insights payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EvalInsightsDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: Supabase access token (`Authorization` header).
+
+  parameters:
+    WorkspaceId:
+      name: workspaceId
+      in: path
+      required: true
       schema:
         type: string
-        format: date
-    InsightsSdlcRangeId:
-      name: rangeId
-      in: query
-      description: >
-        Day-level Measure window. Presets: `7d`, `30d`, `90d`, `180d`. Custom inclusive
-        calendar range: `cr:YYYY-MM-DD:YYYY-MM-DD` (max span 180 days).
+    EvalSuiteId:
+      name: suiteId
+      in: path
+      required: true
       schema:
         type: string
-        default: 30d
-        example: 30d
-    InsightsDepartmentFilter:
-      name: department
-      in: query
-      description: >
-        Department filter; send `All departments` to include every department. Scoped using
-        imported `thinkai_org_structure` members when present, otherwise SPA org chart
-        `department` nodes and their descendant teams. When neither source defines the
-        requested department, insights return no scoped teams or contributors (not org-wide
-        data).
+        format: uuid
+      description: Eval suite id (`tai_workspace_eval_suites.id`).
+    EvalRunId:
+      name: runId
+      in: path
+      required: true
       schema:
         type: string
-        default: All departments
-    InsightsRecommendationsDepartments:
-      name: departments
-      in: query
-      description: >
-        Org-chart department ids (repeat param or comma-separated). Empty/omitted = all departments.
+        format: uuid
+      description: Eval run id (`tai_workspace_eval_runs.id`).
+    RepoId:
+      name: repoId
+      in: path
+      required: true
       schema:
-        type: array
-        items:
-          type: string
-      style: form
-      explode: true
-    InsightsRecommendationsTeams:
-      name: teams
-      in: query
+        type: string
+        format: uuid
+    ProviderSlug:
+      name: providerSlug
+      in: path
+      required: true
       description: >
-        Org-chart team ids (repeat param or comma-separated). Empty/omitted = all teams in department scope.
+        Provider repository slug in `owner/repo` form (GitHub). Used for shareable public URLs;
+        resolves to the same row as `repoId` UUID internally.
       schema:
-        type: array
-        items:
-          type: string
-      style: form
-      explode: true
-    InsightsRecommendationsDateFrom:
-      name: dateFrom
-      in: query
-      description: >
-        Inclusive window start (`YYYY-MM-DD`). Required with `dateTo`. Maps to Measure day-mode
-        custom range (`from`/`to`). Max span 180 days.
+        type: string
+        minLength: 1
+        maxLength: 512
+        pattern: "^[^/]+/[^/]+$"
+        example: thinkai-llc/thinkai-platform-backend
+    ProjectId:
+      name: projectId
+      in: path
       required: true
       schema:
         type: string
-        format: date
-    InsightsRecommendationsDateTo:
-      name: dateTo
-      in: query
-      description: Inclusive window end (`YYYY-MM-DD`). Required with `dateFrom`.
+    NotificationId:
+      name: id
+      in: path
       required: true
       schema:
         type: string
-        format: date
-    InsightsRecommendationsProvider:
-      name: provider
-      in: query
+    WorkspaceMemberId:
+      name: memberId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+      description: Workspace member user id (`tai_users.id`).
+    WorkspaceInvitationToken:
+      name: token
+      in: path
+      required: true
+      schema:
+        type: string
+        minLength: 32
       description: >
-        AI provider ids (e.g. `cursor`, `copilot`). Empty/omitted = all configured providers.
+        Opaque workspace invitation token from the emailed accept link. Only its SHA-256
+        hash is stored server-side; the plaintext is shown exactly once, in the email.
+    PrivacyRequestId:
+      name: requestId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+      description: Privacy request id (`tai_privacy_requests.id`).
+    FixId:
+      name: fixId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+    ReadinessIssueId:
+      name: issueId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+      description: Readiness issue id (`tai_workspace_repo_issues.id`).
+    InsightsProductivityRangeId:
+      name: rangeId
+      in: query
+      description: >
+        Productivity insights time range. Daily windows: `7d`, `30d`, `90d`, `180d`, or custom
+        `cr:YYYY-MM-DD:YYYY-MM-DD`. Weekly legacy: `4w`, `8w`, `q` (12 weeks), `12w`, `16w`.
+        Omit when using explicit `from`/`to` day bounds.
+      schema:
+        type: string
+        default: 4w
+    InsightsProductivityFrom:
+      name: from
+      in: query
+      description: >
+        Inclusive start of a daily window (`YYYY-MM-DD`). When set with `to`, overrides `rangeId`
+        for day-mode responses (max 180 days).
+      schema:
+        type: string
+        format: date
+    InsightsProductivityTo:
+      name: to
+      in: query
+      description: >
+        Inclusive end of a daily window (`YYYY-MM-DD`). When set with `from`, overrides `rangeId`
+        for day-mode responses (max 180 days).
+      schema:
+        type: string
+        format: date
+    InsightsSdlcRangeId:
+      name: rangeId
+      in: query
+      description: >
+        Day-level Measure window. Presets: `7d`, `30d`, `90d`, `180d`. Custom inclusive
+        calendar range: `cr:YYYY-MM-DD:YYYY-MM-DD` (max span 180 days).
+      schema:
+        type: string
+        default: 30d
+        example: 30d
+    InsightsDepartmentFilter:
+      name: department
+      in: query
+      description: >
+        Department filter; send `All departments` to include every department. Scoped using
+        imported `thinkai_org_structure` members when present, otherwise SPA org chart
+        `department` nodes and their descendant teams. When neither source defines the
+        requested department, insights return no scoped teams or contributors (not org-wide
+        data).
+      schema:
+        type: string
+        default: All departments
+    InsightsRecommendationsDepartments:
+      name: departments
+      in: query
+      description: >
+        Org-chart department ids (repeat param or comma-separated). Empty/omitted = all departments.
+      schema:
+        type: array
+        items:
+          type: string
+      style: form
+      explode: true
+    InsightsRecommendationsTeams:
+      name: teams
+      in: query
+      description: >
+        Org-chart team ids (repeat param or comma-separated). Empty/omitted = all teams in department scope.
+      schema:
+        type: array
+        items:
+          type: string
+      style: form
+      explode: true
+    InsightsRecommendationsDateFrom:
+      name: dateFrom
+      in: query
+      description: >
+        Inclusive window start (`YYYY-MM-DD`). Required with `dateTo`. Maps to Measure day-mode
+        custom range (`from`/`to`). Max span 180 days.
+      required: true
+      schema:
+        type: string
+        format: date
+    InsightsRecommendationsDateTo:
+      name: dateTo
+      in: query
+      description: Inclusive window end (`YYYY-MM-DD`). Required with `dateFrom`.
+      required: true
+      schema:
+        type: string
+        format: date
+    InsightsRecommendationsProvider:
+      name: provider
+      in: query
+      description: >
+        AI provider ids (e.g. `cursor`, `copilot`). Empty/omitted = all configured providers.
       schema:
         type: array
         items:
@@ -24494,842 +25024,1378 @@ components:
               path: { type: string }
               body: { type: string }
 
-    CodeChatCrossEdgesBodyDto:
+    CodeChatCrossEdgesBodyDto:
+      type: object
+      properties:
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+
+    CodeChatCrossEdgesResultDto:
+      type: object
+      required: [items, completeness]
+      properties:
+        items:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        completeness: { type: string, enum: [partial, unknown] }
+        gateNote: { type: string }
+
+    CodeChatContextPackBodyDto:
+      type: object
+      properties:
+        question: { type: string }
+        symbol: { type: string }
+        maxTokensApprox: { type: integer }
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+
+    CodeChatContextPackDto:
+      type: object
+      required: [summary, symbols, references, citations, snippets]
+      properties:
+        repoId: { type: string, format: uuid }
+        repoName: { type: string }
+        commitSha: { type: string, nullable: true }
+        summary: { type: string }
+        symbols:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        references:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        blastRadiusPreview:
+          type: object
+          additionalProperties: true
+        citations:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        snippets:
+          type: array
+          items: { type: string }
+
+    CodeInsightsMetricProvenance:
+      type: string
+      enum: [measured, derived, estimated, unavailable]
+      description: >
+        Where a metric value came from: `measured` (direct tool output),
+        `derived` (computed from measured inputs, e.g. the maintainability band),
+        `estimated` (heuristic proxy, e.g. test-to-source ratio), or `unavailable`
+        (tool missing/failed, or the language is unsupported). Keyed per metric in
+        `CodeInsightsMetricsDto.provenance`.
+
+    CodeInsightsMaintainabilityBand:
+      type: string
+      enum: [green, yellow, red]
+      description: CC/LOC-derived maintainability band (documented heuristic, not Halstead MI).
+
+    CodeInsightsMetricsStatus:
+      type: string
+      enum: [ok, failed, skipped]
+      description: >
+        Outcome of the repo's latest metrics scan: `ok` (at least one tool measured),
+        `failed` (every tool failed — metric fields are null with `unavailable`
+        provenance), `skipped` (stage ran but found no measurable source).
+
+    CodeInsightsFindingSeverity:
+      type: string
+      enum: [critical, high, medium, low]
+
+    CodeInsightsFindingCategory:
+      type: string
+      enum:
+        [
+          duplication,
+          complexity,
+          proliferation,
+          coverage,
+          anemic_domain,
+          context_leak,
+          tx_boundary,
+          error_handling,
+          config_cohesion,
+          resilience_patterns,
+          circular_deps,
+          fan_in_hotspot,
+        ]
+      description: >
+        Deterministic categories (`duplication`, `complexity`, `proliferation`,
+        `coverage`, `circular_deps`, `fan_in_hotspot`) plus LLM semantic detectors
+        (`anemic_domain`, `context_leak`, `tx_boundary`, `error_handling`,
+        `config_cohesion`, `resilience_patterns`). Coupling categories are written
+        only by Design risks runs (`source=deterministic` on the design run id).
+
+    CodeInsightsFindingSource:
+      type: string
+      enum: [deterministic, llm]
+      description: >
+        `deterministic` = measured Code Insights rules; `llm` = AI-detected
+        semantic findings (separate agent pass; never blended in scoring).
+
+    CodeInsightsMetricsDto:
+      type: object
+      required: [runId, measuredAt, metricsStatus, structureCounts, provenance, toolVersions]
+      properties:
+        runId:
+          type: string
+          description: Readiness run that produced this metrics row.
+        defaultBranch:
+          type: string
+          nullable: true
+          description: >
+            Default branch at scan time from the linked readiness run, when
+            `runId` matches a row in `tai_workspace_readiness_runs`.
+        scannedCommitSha:
+          type: string
+          nullable: true
+          description: >
+            Git commit (default branch tip) analyzed by the readiness run, when
+            known. Null for seed runs or when the run record is missing.
+        measuredAt:
+          type: string
+          format: date-time
+        metricsStatus:
+          $ref: "#/components/schemas/CodeInsightsMetricsStatus"
+        locTotal:
+          type: integer
+          nullable: true
+        filesTotal:
+          type: integer
+          nullable: true
+        ccAvg:
+          type: number
+          nullable: true
+          description: Mean cyclomatic complexity across analyzed functions.
+        ccMax:
+          type: integer
+          nullable: true
+        ccP90:
+          type: number
+          nullable: true
+          description: 90th percentile function cyclomatic complexity (nearest-rank).
+        dupPct:
+          type: number
+          nullable: true
+          description: Duplicated lines as a percentage of analyzed lines (0–100).
+        maintainabilityBand:
+          allOf:
+            - $ref: "#/components/schemas/CodeInsightsMaintainabilityBand"
+          nullable: true
+        coveragePct:
+          type: number
+          nullable: true
+          description: Reserved for per-repo SonarQube enrichment (v2); null in v1.
+        debtRatio:
+          type: number
+          nullable: true
+          description: Reserved for per-repo SonarQube enrichment (v2); null in v1.
+        structureCounts:
+          type: object
+          additionalProperties: true
+          description: >
+            Heuristic structure counters: dto/mapper/config/exception file + LOC
+            counts, test/source LOC split, per-language LOC, functions_analyzed,
+            test_ratio, dto_mapper_share_pct.
+        provenance:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/CodeInsightsMetricProvenance"
+          description: Per-metric provenance keyed by DTO field name (e.g. `ccAvg`, `dupPct`, `testRatio`).
+        toolVersions:
+          type: object
+          additionalProperties: { type: string }
+          description: Tool name → version string for the tools that produced this row.
+
+    CodeInsightsHotspotDto:
+      type: object
+      required: [filePath, flags]
+      properties:
+        filePath:
+          type: string
+          description: Repo-relative file path.
+        loc:
+          type: integer
+          nullable: true
+        ccMax:
+          type: integer
+          nullable: true
+          description: Max function cyclomatic complexity in the file.
+        paramsMax:
+          type: integer
+          nullable: true
+        nestingMax:
+          type: integer
+          nullable: true
+          description: Max nested control structures (null when the analyzer does not report nesting).
+        dupPct:
+          type: number
+          nullable: true
+          description: Estimated per-file duplicated line share (0–100).
+        flags:
+          type: array
+          items: { type: string }
+          description: Subset of `god_file`, `high_cc`, `long_params`, `deep_nesting`.
+        peakFunction:
+          type: string
+          nullable: true
+          description: Name of the function that owns `ccMax` (lizard). Null on snapshots taken before peak-function capture.
+        peakStartLine:
+          type: integer
+          nullable: true
+          description: 1-based start line of `peakFunction`.
+        peakEndLine:
+          type: integer
+          nullable: true
+          description: 1-based end line of `peakFunction`.
+        peakParams:
+          type: integer
+          nullable: true
+          description: Parameter count of `peakFunction` (not file-wide `paramsMax`). Null on older snapshots.
+
+    CodeInsightsFindingDto:
+      type: object
+      required: [id, severity, category, title, explanation, evidence, source, runId, createdAt]
+      properties:
+        id:
+          type: string
+          format: uuid
+        severity:
+          $ref: "#/components/schemas/CodeInsightsFindingSeverity"
+        category:
+          $ref: "#/components/schemas/CodeInsightsFindingCategory"
+        title:
+          type: string
+        explanation:
+          type: string
+        evidence:
+          type: object
+          additionalProperties: true
+          description: Measured values and thresholds backing the finding.
+        remediation:
+          type: string
+          nullable: true
+        source:
+          $ref: "#/components/schemas/CodeInsightsFindingSource"
+        runId:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+
+    CodeInsightsFindingsBySeverityDto:
+      type: object
+      required: [critical, high, medium, low]
+      properties:
+        critical: { type: integer, minimum: 0 }
+        high: { type: integer, minimum: 0 }
+        medium: { type: integer, minimum: 0 }
+        low: { type: integer, minimum: 0 }
+
+    CodeInsightsRepoListItemDto:
+      type: object
+      required:
+        [repoId, repoName, language, providerSlug, webUrl, badges, findingsBySeverity, provenance]
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        repoName:
+          type: string
+        language:
+          type: string
+        providerSlug:
+          type: string
+          description: "owner/repo on the VCS provider."
+        webUrl:
+          type: string
+        lastMeasuredAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: Null when the repo is pending its first metrics scan.
+        metricsStatus:
+          allOf:
+            - $ref: "#/components/schemas/CodeInsightsMetricsStatus"
+          nullable: true
+        locTotal:
+          type: integer
+          nullable: true
+        ccAvg:
+          type: number
+          nullable: true
+        ccMax:
+          type: integer
+          nullable: true
+        dupPct:
+          type: number
+          nullable: true
+        maintainabilityBand:
+          allOf:
+            - $ref: "#/components/schemas/CodeInsightsMaintainabilityBand"
+          nullable: true
+        badges:
+          type: array
+          items: { type: string }
+          description: >
+            Active threshold badges from the latest scan: subset of `god_files`,
+            `high_complexity`, `duplication`, `proliferation`, `low_test_ratio`.
+        findingsBySeverity:
+          $ref: "#/components/schemas/CodeInsightsFindingsBySeverityDto"
+        provenance:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/CodeInsightsMetricProvenance"
+
+    CodeInsightsRepoListDto:
+      allOf:
+        - $ref: "#/components/schemas/PageMetaDto"
+        - type: object
+          required: [items]
+          properties:
+            items:
+              type: array
+              items:
+                $ref: "#/components/schemas/CodeInsightsRepoListItemDto"
+
+    CodeInsightsRepoDetailDto:
+      type: object
+      required:
+        [
+          repoId,
+          repoName,
+          language,
+          providerSlug,
+          webUrl,
+          metrics,
+          hotspots,
+          findings,
+          designAnalysis,
+        ]
+      properties:
+        repoId:
+          type: string
+          format: uuid
+        repoName:
+          type: string
+        language:
+          type: string
+        providerSlug:
+          type: string
+        webUrl:
+          type: string
+        metrics:
+          allOf:
+            - $ref: "#/components/schemas/CodeInsightsMetricsDto"
+          nullable: true
+          description: Null when the repo is pending its first metrics scan.
+        hotspots:
+          type: array
+          items:
+            $ref: "#/components/schemas/CodeInsightsHotspotDto"
+        findings:
+          type: array
+          items:
+            $ref: "#/components/schemas/CodeInsightsFindingDto"
+          description: >
+            Deterministic findings from the latest metrics scan plus LLM findings from the
+            latest **succeeded** Design risks run only. Stale LLM rows from older design runs
+            are not returned.
+        designAnalysis:
+          allOf:
+            - $ref: "#/components/schemas/CodeInsightsDesignAnalysisDto"
+          nullable: true
+          description: >
+            Latest Design risks run of any status (for UI polling). Null when Design risks
+            has never been enqueued for this repo.
+
+    CodeInsightsDesignAnalysisDto:
+      type: object
+      required: [runId, status, finishedAt, errorCode, errorDetail]
+      properties:
+        runId:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [queued, running, succeeded, failed, partial_failed]
+        finishedAt:
+          type: string
+          format: date-time
+          nullable: true
+        errorCode:
+          type: string
+          nullable: true
+        errorDetail:
+          type: string
+          nullable: true
+
+    CodeInsightsDesignAnalyzeResponseDto:
+      type: object
+      required: [runId]
+      properties:
+        runId:
+          type: string
+          format: uuid
+          description: Enqueued Design risks run id (`tai_workspace_readiness_runs.id`).
+
+    CodeInsightsOrgHotspotDto:
+      allOf:
+        - $ref: "#/components/schemas/CodeInsightsHotspotDto"
+        - type: object
+          required: [repoId, repoName]
+          properties:
+            repoId:
+              type: string
+              format: uuid
+            repoName:
+              type: string
+
+    CodeInsightsSonarDto:
       type: object
+      required: [connected]
       properties:
-        repoIds:
-          type: array
-          items: { type: string, format: uuid }
+        connected:
+          type: boolean
+          description: Whether a SonarQube source is configured for the workspace.
+        coveragePct:
+          type: number
+          nullable: true
+          description: Org-level SonarQube coverage from the latest precomputed quality snapshot.
+        techDebtRatioPct:
+          type: number
+          nullable: true
+          description: Org-level SonarQube SQALE technical debt ratio from the latest quality snapshot.
 
-    CodeChatCrossEdgesResultDto:
+    CodeInsightsSummaryDto:
       type: object
-      required: [items, completeness]
+      required: [reposMeasured, reposPending, findingsBySeverity, topHotspots, sonar]
       properties:
-        items:
+        reposMeasured:
+          type: integer
+          minimum: 0
+          description: Active repos whose latest metrics scan completed (`ok`).
+        reposPending:
+          type: integer
+          minimum: 0
+          description: Active repos without a completed metrics scan (never scanned, or only failed/skipped).
+        ccAvgMedian:
+          type: number
+          nullable: true
+          description: Unweighted median of latest `ccAvg` across measured repos (null when none measured).
+        dupPctMedian:
+          type: number
+          nullable: true
+          description: Unweighted median of latest `dupPct` across measured repos (null when none measured).
+        findingsBySeverity:
+          $ref: "#/components/schemas/CodeInsightsFindingsBySeverityDto"
+        topHotspots:
           type: array
           items:
-            type: object
-            additionalProperties: true
-        completeness: { type: string, enum: [partial, unknown] }
-        gateNote: { type: string }
+            $ref: "#/components/schemas/CodeInsightsOrgHotspotDto"
+          description: Org top-10 complexity hotspots by `ccMax` (current per-repo snapshots).
+        sonar:
+          $ref: "#/components/schemas/CodeInsightsSonarDto"
 
-    CodeChatContextPackBodyDto:
+    InsightsTestPyramidMaturityDto:
+      type: string
+      enum: [missing, emerging, established, mature]
+      description: >
+        Presence maturity (model A) using count-based layer presence
+        (`fileCount > 0`), not AF signal-inclusive `present`.
+
+    InsightsTestPyramidShapeLabelDto:
+      type: string
+      enum: [insufficient_data, base_heavy, balanced, top_heavy, middle_heavy]
+      description: >
+        Advisory shape label vs fixed 70/20/10. `insufficient_data` when total
+        classified test files < 10 (band percents are null).
+
+    InsightsTestPyramidShapeDto:
       type: object
+      required: [label, totalClassifiedFiles, basePercent, middlePercent, topPercent, targets]
       properties:
-        question: { type: string }
-        symbol: { type: string }
-        maxTokensApprox: { type: integer }
-        repoIds:
+        label:
+          $ref: "#/components/schemas/InsightsTestPyramidShapeLabelDto"
+        totalClassifiedFiles:
+          type: integer
+          minimum: 0
+          description: Sum of classified test **files** across the five layers (not test cases).
+        basePercent:
+          type: number
+          nullable: true
+          description: Share of classified files in unit (base). Null when insufficient_data.
+        middlePercent:
+          type: number
+          nullable: true
+          description: >
+            Share in integration + contract + acceptance_bdd (middle). Null when
+            insufficient_data.
+        topPercent:
+          type: number
+          nullable: true
+          description: Share in e2e (top). Null when insufficient_data.
+        targets:
+          type: object
+          required: [basePercent, middlePercent, topPercent]
+          properties:
+            basePercent: { type: number, enum: [70] }
+            middlePercent: { type: number, enum: [20] }
+            topPercent: { type: number, enum: [10] }
+
+    InsightsTestPyramidLayerCountsDto:
+      type: object
+      required: [unit, integration, acceptance_bdd, contract, e2e]
+      properties:
+        unit: { type: integer, minimum: 0 }
+        integration: { type: integer, minimum: 0 }
+        acceptance_bdd: { type: integer, minimum: 0 }
+        contract: { type: integer, minimum: 0 }
+        e2e: { type: integer, minimum: 0 }
+
+    InsightsTestPyramidLayerPresentDto:
+      type: object
+      required: [unit, integration, acceptance_bdd, contract, e2e]
+      properties:
+        unit: { type: boolean }
+        integration: { type: boolean }
+        acceptance_bdd: { type: boolean }
+        contract: { type: boolean }
+        e2e: { type: boolean }
+
+    InsightsTestPyramidLayerPresenceDto:
+      type: object
+      required: [presentRepos, applicableRepos, percent, missingRepoIds, missingRepoNames]
+      properties:
+        presentRepos: { type: integer, minimum: 0 }
+        applicableRepos: { type: integer, minimum: 0 }
+        percent:
+          type: integer
+          nullable: true
+          minimum: 0
+          maximum: 100
+        missingRepoIds:
           type: array
           items: { type: string, format: uuid }
+        missingRepoNames:
+          type: array
+          items: { type: string }
 
-    CodeChatContextPackDto:
+    InsightsTestPyramidGapRepoDto:
       type: object
-      required: [summary, symbols, references, citations, snippets]
+      required: [repoId, repoName]
       properties:
         repoId: { type: string, format: uuid }
         repoName: { type: string }
-        commitSha: { type: string, nullable: true }
-        summary: { type: string }
-        symbols:
+
+    InsightsTestPyramidGapsByLayerDto:
+      type: object
+      required: [unit, integration, acceptance_bdd, contract, e2e]
+      properties:
+        unit:
           type: array
-          items:
-            type: object
-            additionalProperties: true
-        references:
+          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
+        integration:
           type: array
-          items:
-            type: object
-            additionalProperties: true
-        blastRadiusPreview:
-          type: object
-          additionalProperties: true
-        citations:
+          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
+        acceptance_bdd:
           type: array
-          items:
-            type: object
-            additionalProperties: true
-        snippets:
+          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
+        contract:
           type: array
-          items: { type: string }
-
-    CodeInsightsMetricProvenance:
-      type: string
-      enum: [measured, derived, estimated, unavailable]
-      description: >
-        Where a metric value came from: `measured` (direct tool output),
-        `derived` (computed from measured inputs, e.g. the maintainability band),
-        `estimated` (heuristic proxy, e.g. test-to-source ratio), or `unavailable`
-        (tool missing/failed, or the language is unsupported). Keyed per metric in
-        `CodeInsightsMetricsDto.provenance`.
-
-    CodeInsightsMaintainabilityBand:
-      type: string
-      enum: [green, yellow, red]
-      description: CC/LOC-derived maintainability band (documented heuristic, not Halstead MI).
-
-    CodeInsightsMetricsStatus:
-      type: string
-      enum: [ok, failed, skipped]
-      description: >
-        Outcome of the repo's latest metrics scan: `ok` (at least one tool measured),
-        `failed` (every tool failed — metric fields are null with `unavailable`
-        provenance), `skipped` (stage ran but found no measurable source).
+          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
+        e2e:
+          type: array
+          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
 
-    CodeInsightsFindingSeverity:
-      type: string
-      enum: [critical, high, medium, low]
+    InsightsTestPyramidMaturityCountsDto:
+      type: object
+      required: [missing, emerging, established, mature]
+      properties:
+        missing: { type: integer, minimum: 0 }
+        emerging: { type: integer, minimum: 0 }
+        established: { type: integer, minimum: 0 }
+        mature: { type: integer, minimum: 0 }
 
-    CodeInsightsFindingCategory:
-      type: string
-      enum:
-        [
-          duplication,
-          complexity,
-          proliferation,
-          coverage,
-          anemic_domain,
-          context_leak,
-          tx_boundary,
-          error_handling,
-          config_cohesion,
-          resilience_patterns,
-          circular_deps,
-          fan_in_hotspot,
-        ]
-      description: >
-        Deterministic categories (`duplication`, `complexity`, `proliferation`,
-        `coverage`, `circular_deps`, `fan_in_hotspot`) plus LLM semantic detectors
-        (`anemic_domain`, `context_leak`, `tx_boundary`, `error_handling`,
-        `config_cohesion`, `resilience_patterns`). Coupling categories are written
-        only by Design risks runs (`source=deterministic` on the design run id).
+    InsightsTestPyramidLayerPresenceMapDto:
+      type: object
+      required: [unit, integration, acceptance_bdd, contract, e2e]
+      properties:
+        unit: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
+        integration: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
+        acceptance_bdd: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
+        contract: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
+        e2e: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
 
-    CodeInsightsFindingSource:
+    InsightsTestPyramidMaturityDeltaDto:
       type: string
-      enum: [deterministic, llm]
+      enum: [up, down, unchanged, none]
       description: >
-        `deterministic` = measured Code Insights rules; `llm` = AI-detected
-        semantic findings (separate agent pass; never blended in scoring).
+        Insights maturity rank change vs the immediately previous pyramid point
+        (missing 0, emerging 1, established 2, mature 3). `none` when the repo
+        has no previous succeeded/partial_failed/failed point.
 
-    CodeInsightsMetricsDto:
+    InsightsTestPyramidConfidenceDto:
+      type: string
+      enum: [high, medium, low]
+
+    InsightsTestPyramidLayerConfidenceDto:
       type: object
-      required: [runId, measuredAt, metricsStatus, structureCounts, provenance, toolVersions]
+      required: [unit, integration, acceptance_bdd, contract, e2e]
       properties:
-        runId:
-          type: string
-          description: Readiness run that produced this metrics row.
-        defaultBranch:
-          type: string
+        unit: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
+        integration: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
+        acceptance_bdd: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
+        contract: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
+        e2e: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
+
+    InsightsTestPyramidCoverageRollupDto:
+      type: object
+      required: [reposWithCoverage, medianLinePercent]
+      properties:
+        reposWithCoverage:
+          type: integer
+          minimum: 0
+          description: Repos whose overlaid `lineCoverage` is non-null.
+        medianLinePercent:
+          type: number
           nullable: true
+          minimum: 0
+          maximum: 100
           description: >
-            Default branch at scan time from the linked readiness run, when
-            `runId` matches a row in `tai_workspace_readiness_runs`.
-        scannedCommitSha:
-          type: string
-          nullable: true
+            Median of repo `linePercent` among repos that have coverage. Null when
+            `reposWithCoverage` is 0.
+
+    InsightsTestPyramidCiQualityDto:
+      type: object
+      nullable: true
+      required: [ciFailureRatePercent, bucketEnd]
+      properties:
+        ciFailureRatePercent:
+          type: number
+          minimum: 0
+          maximum: 100
           description: >
-            Git commit (default branch tip) analyzed by the readiness run, when
-            known. Null for seed runs or when the run record is missing.
-        measuredAt:
+            Latest org dashboard `quality.ciFailureRatePercent`, falling back to
+            `quality.ciBuildFailRatePercent`.
+        ciFlakinessPercent:
+          type: number
+          minimum: 0
+          maximum: 100
+          description: Included only when `quality.ciFlakinessPercent` is a finite number.
+        bucketEnd:
           type: string
-          format: date-time
-        metricsStatus:
-          $ref: "#/components/schemas/CodeInsightsMetricsStatus"
-        locTotal:
+          description: Dashboard metrics bucket end for the org snapshot.
+
+    InsightsTestPyramidSummaryDto:
+      type: object
+      required:
+        - workspaceId
+        - generatedAt
+        - reposWithPyramid
+        - reposFromDegradedRuns
+        - totalClassifiedFiles
+        - shape
+        - layerPresence
+        - maturityCounts
+        - gapsByLayer
+        - newestScannedAt
+        - maturedRepoCount
+        - slippedRepoCount
+        - previousShape
+        - coverage
+        - e2eCrossRepoCandidateCount
+        - reposWithHotspots
+        - ciQuality
+      properties:
+        workspaceId: { type: string, format: uuid }
+        generatedAt: { type: string, format: date-time }
+        reposWithPyramid: { type: integer, minimum: 0 }
+        reposFromDegradedRuns:
+          type: array
+          items: { type: string, format: uuid }
+          description: Repos whose newest pyramid came from a non-succeeded readiness run.
+        totalClassifiedFiles:
           type: integer
+          minimum: 0
+          description: Workspace sum of classified test files (not cases).
+        shape:
+          $ref: "#/components/schemas/InsightsTestPyramidShapeDto"
+        layerPresence:
+          $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceMapDto"
+        maturityCounts:
+          $ref: "#/components/schemas/InsightsTestPyramidMaturityCountsDto"
+        gapsByLayer:
+          $ref: "#/components/schemas/InsightsTestPyramidGapsByLayerDto"
+        newestScannedAt:
+          type: string
+          format: date-time
           nullable: true
-        filesTotal:
+          description: Latest per-repo `scannedAt`. Null when `reposWithPyramid` is 0.
+        maturedRepoCount:
           type: integer
-          nullable: true
-        ccAvg:
-          type: number
-          nullable: true
-          description: Mean cyclomatic complexity across analyzed functions.
-        ccMax:
+          minimum: 0
+          description: Repos whose Insights maturity rank increased vs the previous point.
+        slippedRepoCount:
           type: integer
-          nullable: true
-        ccP90:
-          type: number
-          nullable: true
-          description: 90th percentile function cyclomatic complexity (nearest-rank).
-        dupPct:
-          type: number
-          nullable: true
-          description: Duplicated lines as a percentage of analyzed lines (0–100).
-        maintainabilityBand:
+          minimum: 0
+          description: Repos whose Insights maturity rank decreased vs the previous point.
+        previousShape:
           allOf:
-            - $ref: "#/components/schemas/CodeInsightsMaintainabilityBand"
-          nullable: true
-        coveragePct:
-          type: number
-          nullable: true
-          description: Reserved for per-repo SonarQube enrichment (v2); null in v1.
-        debtRatio:
-          type: number
+            - $ref: "#/components/schemas/InsightsTestPyramidShapeDto"
           nullable: true
-          description: Reserved for per-repo SonarQube enrichment (v2); null in v1.
-        structureCounts:
-          type: object
-          additionalProperties: true
           description: >
-            Heuristic structure counters: dto/mapper/config/exception file + LOC
-            counts, test/source LOC split, per-language LOC, functions_analyzed,
-            test_ratio, dto_mapper_share_pct.
-        provenance:
-          type: object
-          additionalProperties:
-            $ref: "#/components/schemas/CodeInsightsMetricProvenance"
-          description: Per-metric provenance keyed by DTO field name (e.g. `ccAvg`, `dupPct`, `testRatio`).
-        toolVersions:
-          type: object
-          additionalProperties: { type: string }
-          description: Tool name → version string for the tools that produced this row.
+            Insights workspace shape from previous-point file totals for repos that
+            have a previous point. Null when no repo has a previous point.
+        coverage:
+          $ref: "#/components/schemas/InsightsTestPyramidCoverageRollupDto"
+        e2eCrossRepoCandidateCount:
+          type: integer
+          minimum: 0
+        reposWithHotspots:
+          type: integer
+          minimum: 0
+          description: Repos whose latest Code Insights snapshot has `hotspotCount` > 0.
+        ciQuality:
+          $ref: "#/components/schemas/InsightsTestPyramidCiQualityDto"
 
-    CodeInsightsHotspotDto:
+    InsightsTestPyramidRepoItemDto:
       type: object
-      required: [filePath, flags]
+      required:
+        - repoId
+        - repoName
+        - scannedAt
+        - currentRunStatus
+        - maturity
+        - layerFileCounts
+        - layerPresent
+        - totalClassifiedFiles
+        - shape
+        - previousMaturity
+        - maturityDelta
+        - previousShapeLabel
+        - lineCoverage
+        - lowestConfidence
+        - layerConfidence
+        - evidenceCount
+        - frameworks
+        - layerApplicable
+        - e2eCrossRepoCandidate
+        - hotspotCount
       properties:
-        filePath:
-          type: string
-          description: Repo-relative file path.
-        loc:
-          type: integer
-          nullable: true
-        ccMax:
-          type: integer
+        repoId: { type: string, format: uuid }
+        repoName: { type: string }
+        scannedAt: { type: string, format: date-time }
+        currentRunStatus:
+          $ref: "#/components/schemas/TestPyramidRunStatusDto"
+        maturity:
+          $ref: "#/components/schemas/InsightsTestPyramidMaturityDto"
+        previousMaturity:
+          allOf:
+            - $ref: "#/components/schemas/InsightsTestPyramidMaturityDto"
           nullable: true
-          description: Max function cyclomatic complexity in the file.
-        paramsMax:
-          type: integer
+        maturityDelta:
+          $ref: "#/components/schemas/InsightsTestPyramidMaturityDeltaDto"
+        previousShapeLabel:
+          allOf:
+            - $ref: "#/components/schemas/InsightsTestPyramidShapeLabelDto"
           nullable: true
-        nestingMax:
+        layerFileCounts:
+          $ref: "#/components/schemas/InsightsTestPyramidLayerCountsDto"
+        layerPresent:
+          $ref: "#/components/schemas/InsightsTestPyramidLayerPresentDto"
+        layerApplicable:
+          allOf:
+            - $ref: "#/components/schemas/InsightsTestPyramidLayerPresentDto"
+          description: Snapshot `layers.*.applicable` for each layer.
+        totalClassifiedFiles: { type: integer, minimum: 0 }
+        shape:
+          $ref: "#/components/schemas/InsightsTestPyramidShapeDto"
+        lineCoverage:
+          allOf:
+            - $ref: "#/components/schemas/TestPyramidLineCoverageDto"
+          description: >
+            Same overlay as AF progress — latest Sonar row first, else snapshot
+            `testPyramid.lineCoverage`. Null when both are missing. Not Code Insights
+            `coveragePct`.
+        lowestConfidence:
+          allOf:
+            - $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto"
+          description: >
+            Minimum confidence among layers with Insights presence (`fileCount > 0`);
+            if none present, minimum of applicable layers. Order low < medium < high.
+        layerConfidence:
+          $ref: "#/components/schemas/InsightsTestPyramidLayerConfidenceDto"
+        evidenceCount:
           type: integer
-          nullable: true
-          description: Max nested control structures (null when the analyzer does not report nesting).
-        dupPct:
-          type: number
-          nullable: true
-          description: Estimated per-file duplicated line share (0–100).
-        flags:
+          minimum: 0
+          description: Sum of layer `evidence[]` lengths on the latest snapshot.
+        frameworks:
           type: array
+          maxItems: 8
           items: { type: string }
-          description: Subset of `god_file`, `high_cc`, `long_params`, `deep_nesting`.
-        peakFunction:
-          type: string
-          nullable: true
-          description: Name of the function that owns `ccMax` (lizard). Null on snapshots taken before peak-function capture.
-        peakStartLine:
-          type: integer
-          nullable: true
-          description: 1-based start line of `peakFunction`.
-        peakEndLine:
-          type: integer
-          nullable: true
-          description: 1-based end line of `peakFunction`.
-        peakParams:
+          description: Unique framework names across layers, capped at 8.
+        e2eCrossRepoCandidate: { type: boolean }
+        hotspotCount:
           type: integer
           nullable: true
-          description: Parameter count of `peakFunction` (not file-wide `paramsMax`). Null on older snapshots.
+          minimum: 0
+          description: >
+            Row count in `tai_workspace_repo_code_hotspots` for the repo's latest
+            Code Insights metrics snapshot. Null when the repo has no metrics snapshot.
 
-    CodeInsightsFindingDto:
+    InsightsTestPyramidRepoListDto:
       type: object
-      required: [id, severity, category, title, explanation, evidence, source, runId, createdAt]
+      required: [items, total, limit, offset]
       properties:
-        id:
-          type: string
-          format: uuid
-        severity:
-          $ref: "#/components/schemas/CodeInsightsFindingSeverity"
-        category:
-          $ref: "#/components/schemas/CodeInsightsFindingCategory"
-        title:
-          type: string
-        explanation:
-          type: string
-        evidence:
-          type: object
-          additionalProperties: true
-          description: Measured values and thresholds backing the finding.
-        remediation:
-          type: string
-          nullable: true
-        source:
-          $ref: "#/components/schemas/CodeInsightsFindingSource"
-        runId:
-          type: string
-        createdAt:
-          type: string
-          format: date-time
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsTestPyramidRepoItemDto"
+        total: { type: integer, minimum: 0 }
+        limit: { type: integer, minimum: 1 }
+        offset: { type: integer, minimum: 0 }
+    EvalExpectedSignalKindDto:
+      type: string
+      description: >
+        Deterministic scorer kinds for golden-case expected signals. Case pass =
+        all signals pass. No LLM-as-judge in v1.
+      enum: [contains, not_contains, regex, json_path_equals]
 
-    CodeInsightsFindingsBySeverityDto:
-      type: object
-      required: [critical, high, medium, low]
-      properties:
-        critical: { type: integer, minimum: 0 }
-        high: { type: integer, minimum: 0 }
-        medium: { type: integer, minimum: 0 }
-        low: { type: integer, minimum: 0 }
+    EvalAiProviderDto:
+      type: string
+      description: >
+        Model provider vocabulary aligned with AI Usage `modelName` surfaces
+        (`cursor` | `claude`).
+      enum: [cursor, claude]
 
-    CodeInsightsRepoListItemDto:
+    EvalExpectedSignalDto:
       type: object
-      required:
-        [repoId, repoName, language, providerSlug, webUrl, badges, findingsBySeverity, provenance]
+      additionalProperties: false
+      required: [id, kind]
+      description: >
+        One expected signal on a golden case. Use `value` for `contains` /
+        `not_contains` (substring) and for `json_path_equals` (expected value as
+        string). Use `pattern` for `regex`. Use `path` (JSONPath) for
+        `json_path_equals`.
       properties:
-        repoId:
-          type: string
-          format: uuid
-        repoName:
-          type: string
-        language:
+        id:
           type: string
-        providerSlug:
+          minLength: 1
+          maxLength: 64
+        kind:
+          $ref: "#/components/schemas/EvalExpectedSignalKindDto"
+        value:
           type: string
-          description: "owner/repo on the VCS provider."
-        webUrl:
+          maxLength: 8000
+          description: >
+            Substring for `contains` / `not_contains`, or expected value for
+            `json_path_equals`.
+        pattern:
           type: string
-        lastMeasuredAt:
+          maxLength: 2000
+          description: Regular expression source for `regex`.
+        path:
           type: string
-          format: date-time
-          nullable: true
-          description: Null when the repo is pending its first metrics scan.
-        metricsStatus:
-          allOf:
-            - $ref: "#/components/schemas/CodeInsightsMetricsStatus"
-          nullable: true
-        locTotal:
-          type: integer
-          nullable: true
-        ccAvg:
-          type: number
-          nullable: true
-        ccMax:
-          type: integer
-          nullable: true
-        dupPct:
-          type: number
-          nullable: true
-        maintainabilityBand:
-          allOf:
-            - $ref: "#/components/schemas/CodeInsightsMaintainabilityBand"
-          nullable: true
-        badges:
-          type: array
-          items: { type: string }
-          description: >
-            Active threshold badges from the latest scan: subset of `god_files`,
-            `high_complexity`, `duplication`, `proliferation`, `low_test_ratio`.
-        findingsBySeverity:
-          $ref: "#/components/schemas/CodeInsightsFindingsBySeverityDto"
-        provenance:
-          type: object
-          additionalProperties:
-            $ref: "#/components/schemas/CodeInsightsMetricProvenance"
-
-    CodeInsightsRepoListDto:
-      allOf:
-        - $ref: "#/components/schemas/PageMetaDto"
-        - type: object
-          required: [items]
-          properties:
-            items:
-              type: array
-              items:
-                $ref: "#/components/schemas/CodeInsightsRepoListItemDto"
+          maxLength: 500
+          description: JSONPath expression for `json_path_equals`.
 
-    CodeInsightsRepoDetailDto:
+    EvalCaseDto:
       type: object
-      required:
-        [
-          repoId,
-          repoName,
-          language,
-          providerSlug,
-          webUrl,
-          metrics,
-          hotspots,
-          findings,
-          designAnalysis,
-        ]
+      additionalProperties: false
+      required: [id, name, input, expectedSignals]
+      description: >
+        One golden case in a suite. 1–20 cases per suite; each case requires ≥1
+        expected signal. When `fixtureCompletion` is set, the worker scores that
+        text without calling a live model (CI/demo path).
       properties:
-        repoId:
-          type: string
-          format: uuid
-        repoName:
+        id:
           type: string
-        language:
+          minLength: 1
+          maxLength: 64
+        name:
           type: string
-        providerSlug:
+          minLength: 1
+          maxLength: 200
+        input:
           type: string
-        webUrl:
+          minLength: 1
+          maxLength: 20000
+          description: Case input payload (opaque string; often JSON text).
+        fixtureCompletion:
           type: string
-        metrics:
-          allOf:
-            - $ref: "#/components/schemas/CodeInsightsMetricsDto"
-          nullable: true
-          description: Null when the repo is pending its first metrics scan.
-        hotspots:
-          type: array
-          items:
-            $ref: "#/components/schemas/CodeInsightsHotspotDto"
-        findings:
+          maxLength: 100000
+          description: >
+            Optional fixture completion. When present, the worker uses it instead
+            of a live provider call.
+        expectedSignals:
           type: array
+          minItems: 1
+          maxItems: 20
           items:
-            $ref: "#/components/schemas/CodeInsightsFindingDto"
-          description: >
-            Deterministic findings from the latest metrics scan plus LLM findings from the
-            latest **succeeded** Design risks run only. Stale LLM rows from older design runs
-            are not returned.
-        designAnalysis:
-          allOf:
-            - $ref: "#/components/schemas/CodeInsightsDesignAnalysisDto"
-          nullable: true
-          description: >
-            Latest Design risks run of any status (for UI polling). Null when Design risks
-            has never been enqueued for this repo.
+            $ref: "#/components/schemas/EvalExpectedSignalDto"
 
-    CodeInsightsDesignAnalysisDto:
+    EvalSuiteTargetDto:
       type: object
-      required: [runId, status, finishedAt, errorCode, errorDetail]
+      additionalProperties: false
+      description: >
+        Suite target — at least one of prompt or model. Prompt path requires
+        non-empty `promptBody` (text snapshot) and may include optional `promptKey`
+        slug. Model path requires `provider` + `modelName` (vendor string, same
+        vocabulary as AI Usage `modelName`). Create/update reject when both
+        prompt body is empty and model fields are missing. No separate
+        prompt-template registry in v1; versioning is the suite `version`.
       properties:
-        runId:
-          type: string
-          format: uuid
-        status:
+        promptBody:
           type: string
-          enum: [queued, running, succeeded, failed, partial_failed]
-        finishedAt:
+          maxLength: 100000
+          description: Prompt text snapshot. Empty string allowed only when model fields are set.
+        promptKey:
           type: string
-          format: date-time
+          maxLength: 120
           nullable: true
-        errorCode:
+          description: Optional slug for the prompt (not a registry foreign key in v1).
+        provider:
           type: string
           nullable: true
-        errorDetail:
+          enum: [cursor, claude]
+          description: Model provider; null when suite is prompt-only.
+        modelName:
           type: string
+          maxLength: 200
           nullable: true
+          description: Vendor model id string (aligned with AI Usage `modelName`).
 
-    CodeInsightsDesignAnalyzeResponseDto:
+    EvalSuiteDto:
       type: object
-      required: [runId]
+      additionalProperties: false
+      required:
+        - id
+        - name
+        - description
+        - version
+        - createdAt
+        - updatedAt
+        - createdByUserId
+        - target
+        - cases
+      description: >
+        Latest version of a workspace eval suite. Max 50 suites per workspace.
+        Name 1–120 chars; description ≤ 2000; version starts at 1.
       properties:
-        runId:
+        id:
           type: string
           format: uuid
-          description: Enqueued Design risks run id (`tai_workspace_readiness_runs.id`).
+        name:
+          type: string
+          minLength: 1
+          maxLength: 120
+        description:
+          type: string
+          maxLength: 2000
+        version:
+          type: integer
+          minimum: 1
+          description: Monotonic suite version; bumps when target/cases/promptBody change.
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+        createdByUserId:
+          type: string
+          format: uuid
+        target:
+          $ref: "#/components/schemas/EvalSuiteTargetDto"
+        cases:
+          type: array
+          minItems: 1
+          maxItems: 20
+          items:
+            $ref: "#/components/schemas/EvalCaseDto"
 
-    CodeInsightsOrgHotspotDto:
-      allOf:
-        - $ref: "#/components/schemas/CodeInsightsHotspotDto"
-        - type: object
-          required: [repoId, repoName]
-          properties:
-            repoId:
-              type: string
-              format: uuid
-            repoName:
-              type: string
+    EvalSuiteListDto:
+      type: object
+      additionalProperties: false
+      required: [suites]
+      properties:
+        suites:
+          type: array
+          maxItems: 50
+          items:
+            $ref: "#/components/schemas/EvalSuiteDto"
 
-    CodeInsightsSonarDto:
+    CreateEvalSuiteBodyDto:
       type: object
-      required: [connected]
+      additionalProperties: false
+      required: [name, target, cases]
       properties:
-        connected:
-          type: boolean
-          description: Whether a SonarQube source is configured for the workspace.
-        coveragePct:
-          type: number
-          nullable: true
-          description: Org-level SonarQube coverage from the latest precomputed quality snapshot.
-        techDebtRatioPct:
-          type: number
-          nullable: true
-          description: Org-level SonarQube SQALE technical debt ratio from the latest quality snapshot.
+        name:
+          type: string
+          minLength: 1
+          maxLength: 120
+        description:
+          type: string
+          maxLength: 2000
+          default: ""
+        target:
+          $ref: "#/components/schemas/EvalSuiteTargetDto"
+        cases:
+          type: array
+          minItems: 1
+          maxItems: 20
+          items:
+            $ref: "#/components/schemas/EvalCaseDto"
 
-    CodeInsightsSummaryDto:
+    UpdateEvalSuiteBodyDto:
       type: object
-      required: [reposMeasured, reposPending, findingsBySeverity, topHotspots, sonar]
+      additionalProperties: false
+      required: [name, target, cases]
+      description: >
+        Full replace of mutable suite fields. Version bumps only when `target`,
+        `cases`, or `promptBody` change versus the stored latest version.
       properties:
-        reposMeasured:
-          type: integer
-          minimum: 0
-          description: Active repos whose latest metrics scan completed (`ok`).
-        reposPending:
-          type: integer
-          minimum: 0
-          description: Active repos without a completed metrics scan (never scanned, or only failed/skipped).
-        ccAvgMedian:
-          type: number
-          nullable: true
-          description: Unweighted median of latest `ccAvg` across measured repos (null when none measured).
-        dupPctMedian:
-          type: number
-          nullable: true
-          description: Unweighted median of latest `dupPct` across measured repos (null when none measured).
-        findingsBySeverity:
-          $ref: "#/components/schemas/CodeInsightsFindingsBySeverityDto"
-        topHotspots:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 120
+        description:
+          type: string
+          maxLength: 2000
+          default: ""
+        target:
+          $ref: "#/components/schemas/EvalSuiteTargetDto"
+        cases:
           type: array
+          minItems: 1
+          maxItems: 20
           items:
-            $ref: "#/components/schemas/CodeInsightsOrgHotspotDto"
-          description: Org top-10 complexity hotspots by `ccMax` (current per-repo snapshots).
-        sonar:
-          $ref: "#/components/schemas/CodeInsightsSonarDto"
+            $ref: "#/components/schemas/EvalCaseDto"
 
-    InsightsTestPyramidMaturityDto:
+    EvalRunStatusDto:
       type: string
-      enum: [missing, emerging, established, mature]
-      description: >
-        Presence maturity (model A) using count-based layer presence
-        (`fileCount > 0`), not AF signal-inclusive `present`.
+      enum: [queued, running, succeeded, failed, cancelled]
 
-    InsightsTestPyramidShapeLabelDto:
+    EvalCaseResultStatusDto:
       type: string
-      enum: [insufficient_data, base_heavy, balanced, top_heavy, middle_heavy]
       description: >
-        Advisory shape label vs fixed 70/20/10. `insufficient_data` when total
-        classified test files < 10 (band percents are null).
+        Per-case outcome. `error` is used when completion is unavailable
+        (`code: completion_unavailable`) or another non-score failure occurs.
+      enum: [passed, failed, error]
 
-    InsightsTestPyramidShapeDto:
+    EvalCaseResultDto:
       type: object
-      required: [label, totalClassifiedFiles, basePercent, middlePercent, topPercent, targets]
+      additionalProperties: false
+      required:
+        - caseId
+        - name
+        - status
+        - pass
+        - failedSignalIds
+      description: >
+        Persisted result for one case. `pass` is true only when `status` is
+        `passed` (all expected signals matched). On signal failure, `pass` is
+        false and `failedSignalIds` lists the failing signal ids. On
+        `completion_unavailable`, `status` is `error` and `code` is set.
       properties:
-        label:
-          $ref: "#/components/schemas/InsightsTestPyramidShapeLabelDto"
-        totalClassifiedFiles:
+        caseId:
+          type: string
+        name:
+          type: string
+        status:
+          $ref: "#/components/schemas/EvalCaseResultStatusDto"
+        pass:
+          type: boolean
+        failedSignalIds:
+          type: array
+          items:
+            type: string
+        completion:
+          type: string
+          nullable: true
+          description: Completion text used for scoring (fixture or live).
+        inputTokens:
           type: integer
+          nullable: true
           minimum: 0
-          description: Sum of classified test **files** across the five layers (not test cases).
-        basePercent:
-          type: number
+        outputTokens:
+          type: integer
           nullable: true
-          description: Share of classified files in unit (base). Null when insufficient_data.
-        middlePercent:
+          minimum: 0
+        costCents:
           type: number
           nullable: true
+          minimum: 0
+          description: Provider-reported cost in cents when available.
+        code:
+          type: string
+          nullable: true
           description: >
-            Share in integration + contract + acceptance_bdd (middle). Null when
-            insufficient_data.
-        topPercent:
-          type: number
+            Machine-readable error when `status` is `error`
+            (e.g. `completion_unavailable`).
+        error:
+          type: string
           nullable: true
-          description: Share in e2e (top). Null when insufficient_data.
-        targets:
-          type: object
-          required: [basePercent, middlePercent, topPercent]
-          properties:
-            basePercent: { type: number, enum: [70] }
-            middlePercent: { type: number, enum: [20] }
-            topPercent: { type: number, enum: [10] }
-
-    InsightsTestPyramidLayerCountsDto:
-      type: object
-      required: [unit, integration, acceptance_bdd, contract, e2e]
-      properties:
-        unit: { type: integer, minimum: 0 }
-        integration: { type: integer, minimum: 0 }
-        acceptance_bdd: { type: integer, minimum: 0 }
-        contract: { type: integer, minimum: 0 }
-        e2e: { type: integer, minimum: 0 }
+          description: Human-readable error detail when `status` is `error`.
 
-    InsightsTestPyramidLayerPresentDto:
+    EvalSuiteSnapshotDto:
       type: object
-      required: [unit, integration, acceptance_bdd, contract, e2e]
+      additionalProperties: false
+      required: [name, description, version, target, cases]
+      description: >
+        Immutable suite snapshot pinned on a run (`suiteVersion` + JSON). Used so
+        historical runs stay interpretable after later suite edits.
       properties:
-        unit: { type: boolean }
-        integration: { type: boolean }
-        acceptance_bdd: { type: boolean }
-        contract: { type: boolean }
-        e2e: { type: boolean }
+        name:
+          type: string
+        description:
+          type: string
+        version:
+          type: integer
+          minimum: 1
+        target:
+          $ref: "#/components/schemas/EvalSuiteTargetDto"
+        cases:
+          type: array
+          items:
+            $ref: "#/components/schemas/EvalCaseDto"
 
-    InsightsTestPyramidLayerPresenceDto:
+    EvalRunDto:
       type: object
-      required: [presentRepos, applicableRepos, percent, missingRepoIds, missingRepoNames]
+      additionalProperties: false
+      required:
+        - id
+        - suiteId
+        - suiteVersion
+        - status
+        - startedAt
+        - finishedAt
+        - passCount
+        - failCount
+        - errorCount
+        - score
+        - caseResults
+      description: >
+        Persisted eval run. Suite score = `passedCases / scoredCases` in [0,1]
+        when at least one case was scored; `null` when the run ends with all
+        cases in `error` (status `failed`). List endpoints return at most the
+        last 50 runs per suite.
       properties:
-        presentRepos: { type: integer, minimum: 0 }
-        applicableRepos: { type: integer, minimum: 0 }
-        percent:
+        id:
+          type: string
+          format: uuid
+        suiteId:
+          type: string
+          format: uuid
+        suiteVersion:
           type: integer
+          minimum: 1
+        status:
+          $ref: "#/components/schemas/EvalRunStatusDto"
+        startedAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: Set when the worker claims the run (`running`).
+        finishedAt:
+          type: string
+          format: date-time
           nullable: true
+        passCount:
+          type: integer
           minimum: 0
-          maximum: 100
-        missingRepoIds:
-          type: array
-          items: { type: string, format: uuid }
-        missingRepoNames:
-          type: array
-          items: { type: string }
-
-    InsightsTestPyramidGapRepoDto:
-      type: object
-      required: [repoId, repoName]
-      properties:
-        repoId: { type: string, format: uuid }
-        repoName: { type: string }
-
-    InsightsTestPyramidGapsByLayerDto:
-      type: object
-      required: [unit, integration, acceptance_bdd, contract, e2e]
-      properties:
-        unit:
-          type: array
-          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
-        integration:
-          type: array
-          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
-        acceptance_bdd:
-          type: array
-          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
-        contract:
-          type: array
-          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
-        e2e:
+        failCount:
+          type: integer
+          minimum: 0
+        errorCount:
+          type: integer
+          minimum: 0
+        score:
+          type: number
+          nullable: true
+          minimum: 0
+          maximum: 1
+          description: >
+            `passedCases / scoredCases` in [0,1], or null when no case was scored
+            (all-error run).
+        caseResults:
           type: array
-          items: { $ref: "#/components/schemas/InsightsTestPyramidGapRepoDto" }
-
-    InsightsTestPyramidMaturityCountsDto:
-      type: object
-      required: [missing, emerging, established, mature]
-      properties:
-        missing: { type: integer, minimum: 0 }
-        emerging: { type: integer, minimum: 0 }
-        established: { type: integer, minimum: 0 }
-        mature: { type: integer, minimum: 0 }
-
-    InsightsTestPyramidLayerPresenceMapDto:
-      type: object
-      required: [unit, integration, acceptance_bdd, contract, e2e]
-      properties:
-        unit: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
-        integration: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
-        acceptance_bdd: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
-        contract: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
-        e2e: { $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceDto" }
-
-    InsightsTestPyramidMaturityDeltaDto:
-      type: string
-      enum: [up, down, unchanged, none]
-      description: >
-        Insights maturity rank change vs the immediately previous pyramid point
-        (missing 0, emerging 1, established 2, mature 3). `none` when the repo
-        has no previous succeeded/partial_failed/failed point.
+          items:
+            $ref: "#/components/schemas/EvalCaseResultDto"
+        suiteSnapshot:
+          type: object
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/EvalSuiteSnapshotDto"
+          description: Pinned suite snapshot for this run (present on persisted runs).
 
-    InsightsTestPyramidConfidenceDto:
-      type: string
-      enum: [high, medium, low]
+    EvalRunListDto:
+      type: object
+      additionalProperties: false
+      required: [runs]
+      properties:
+        runs:
+          type: array
+          maxItems: 50
+          items:
+            $ref: "#/components/schemas/EvalRunDto"
 
-    InsightsTestPyramidLayerConfidenceDto:
+    EvalRunEnqueueResponseDto:
       type: object
-      required: [unit, integration, acceptance_bdd, contract, e2e]
+      additionalProperties: false
+      required: [runId, status]
       properties:
-        unit: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
-        integration: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
-        acceptance_bdd: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
-        contract: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
-        e2e: { $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto" }
+        runId:
+          type: string
+          format: uuid
+        status:
+          type: string
+          enum: [queued]
+          description: Always `queued` on enqueue; poll GET run for progress.
 
-    InsightsTestPyramidCoverageRollupDto:
+    EvalRegressionDto:
       type: object
-      required: [reposWithCoverage, medianLinePercent]
+      additionalProperties: false
+      required:
+        - suiteId
+        - suiteVersion
+        - priorScore
+        - currentScore
+        - scoreDrop
+      description: >
+        Regression when prior score − current score ≥ 0.10 on the same
+        suiteId+suiteVersion case set, or suite score drop ≥ 0.10.
       properties:
-        reposWithCoverage:
+        suiteId:
+          type: string
+          format: uuid
+        suiteName:
+          type: string
+        suiteVersion:
           type: integer
-          minimum: 0
-          description: Repos whose overlaid `lineCoverage` is non-null.
-        medianLinePercent:
-          type: number
+          minimum: 1
+        caseId:
+          type: string
+          nullable: true
+          description: Set for case-level regressions; null for suite-level score drops.
+        caseName:
+          type: string
           nullable: true
+        priorRunId:
+          type: string
+          format: uuid
+        currentRunId:
+          type: string
+          format: uuid
+        priorScore:
+          type: number
           minimum: 0
-          maximum: 100
-          description: >
-            Median of repo `linePercent` among repos that have coverage. Null when
-            `reposWithCoverage` is 0.
-
-    InsightsTestPyramidCiQualityDto:
-      type: object
-      nullable: true
-      required: [ciFailureRatePercent, bucketEnd]
-      properties:
-        ciFailureRatePercent:
+          maximum: 1
+        currentScore:
           type: number
           minimum: 0
-          maximum: 100
-          description: >
-            Latest org dashboard `quality.ciFailureRatePercent`, falling back to
-            `quality.ciBuildFailRatePercent`.
-        ciFlakinessPercent:
+          maximum: 1
+        scoreDrop:
           type: number
           minimum: 0
-          maximum: 100
-          description: Included only when `quality.ciFlakinessPercent` is a finite number.
-        bucketEnd:
-          type: string
-          description: Dashboard metrics bucket end for the org snapshot.
+          maximum: 1
+          description: priorScore − currentScore (always ≥ 0.10 for listed items).
 
-    InsightsTestPyramidSummaryDto:
+    EvalPromptTipDto:
       type: object
-      required:
-        - workspaceId
-        - generatedAt
-        - reposWithPyramid
-        - reposFromDegradedRuns
-        - totalClassifiedFiles
-        - shape
-        - layerPresence
-        - maturityCounts
-        - gapsByLayer
-        - newestScannedAt
-        - maturedRepoCount
-        - slippedRepoCount
-        - previousShape
-        - coverage
-        - e2eCrossRepoCandidateCount
-        - reposWithHotspots
-        - ciQuality
+      additionalProperties: false
+      required: [suiteId, message]
+      description: Tip derived from failed signal notes / case names on recent runs.
       properties:
-        workspaceId: { type: string, format: uuid }
-        generatedAt: { type: string, format: date-time }
-        reposWithPyramid: { type: integer, minimum: 0 }
-        reposFromDegradedRuns:
-          type: array
-          items: { type: string, format: uuid }
-          description: Repos whose newest pyramid came from a non-succeeded readiness run.
-        totalClassifiedFiles:
-          type: integer
-          minimum: 0
-          description: Workspace sum of classified test files (not cases).
-        shape:
-          $ref: "#/components/schemas/InsightsTestPyramidShapeDto"
-        layerPresence:
-          $ref: "#/components/schemas/InsightsTestPyramidLayerPresenceMapDto"
-        maturityCounts:
-          $ref: "#/components/schemas/InsightsTestPyramidMaturityCountsDto"
-        gapsByLayer:
-          $ref: "#/components/schemas/InsightsTestPyramidGapsByLayerDto"
-        newestScannedAt:
+        suiteId:
+          type: string
+          format: uuid
+        suiteName:
+          type: string
+        caseId:
           type: string
-          format: date-time
           nullable: true
-          description: Latest per-repo `scannedAt`. Null when `reposWithPyramid` is 0.
-        maturedRepoCount:
-          type: integer
-          minimum: 0
-          description: Repos whose Insights maturity rank increased vs the previous point.
-        slippedRepoCount:
-          type: integer
+        caseName:
+          type: string
+          nullable: true
+        signalId:
+          type: string
+          nullable: true
+        message:
+          type: string
+          maxLength: 2000
+
+    EvalTokenEfficiencyDto:
+      type: object
+      additionalProperties: false
+      required: [avgInputTokens, avgOutputTokens, avgCostCents]
+      description: >
+        Averages over successful cases in the last succeeded run per suite
+        (workspace rollup). Nullables when token/cost fields were not returned.
+      properties:
+        avgInputTokens:
+          type: number
+          nullable: true
           minimum: 0
-          description: Repos whose Insights maturity rank decreased vs the previous point.
-        previousShape:
-          allOf:
-            - $ref: "#/components/schemas/InsightsTestPyramidShapeDto"
+        avgOutputTokens:
+          type: number
           nullable: true
-          description: >
-            Insights workspace shape from previous-point file totals for repos that
-            have a previous point. Null when no repo has a previous point.
-        coverage:
-          $ref: "#/components/schemas/InsightsTestPyramidCoverageRollupDto"
-        e2eCrossRepoCandidateCount:
-          type: integer
           minimum: 0
-        reposWithHotspots:
-          type: integer
+        avgCostCents:
+          type: number
+          nullable: true
           minimum: 0
-          description: Repos whose latest Code Insights snapshot has `hotspotCount` > 0.
-        ciQuality:
-          $ref: "#/components/schemas/InsightsTestPyramidCiQualityDto"
 
-    InsightsTestPyramidRepoItemDto:
+    EvalModelComparisonDto:
       type: object
-      required:
-        - repoId
-        - repoName
-        - scannedAt
-        - currentRunStatus
-        - maturity
-        - layerFileCounts
-        - layerPresent
-        - totalClassifiedFiles
-        - shape
-        - previousMaturity
-        - maturityDelta
-        - previousShapeLabel
-        - lineCoverage
-        - lowestConfidence
-        - layerConfidence
-        - evidenceCount
-        - frameworks
-        - layerApplicable
-        - e2eCrossRepoCandidate
-        - hotspotCount
+      additionalProperties: false
+      required: [provider, modelName, suiteCount, avgScore]
       properties:
-        repoId: { type: string, format: uuid }
-        repoName: { type: string }
-        scannedAt: { type: string, format: date-time }
-        currentRunStatus:
-          $ref: "#/components/schemas/TestPyramidRunStatusDto"
-        maturity:
-          $ref: "#/components/schemas/InsightsTestPyramidMaturityDto"
-        previousMaturity:
-          allOf:
-            - $ref: "#/components/schemas/InsightsTestPyramidMaturityDto"
-          nullable: true
-        maturityDelta:
-          $ref: "#/components/schemas/InsightsTestPyramidMaturityDeltaDto"
-        previousShapeLabel:
-          allOf:
-            - $ref: "#/components/schemas/InsightsTestPyramidShapeLabelDto"
-          nullable: true
-        layerFileCounts:
-          $ref: "#/components/schemas/InsightsTestPyramidLayerCountsDto"
-        layerPresent:
-          $ref: "#/components/schemas/InsightsTestPyramidLayerPresentDto"
-        layerApplicable:
-          allOf:
-            - $ref: "#/components/schemas/InsightsTestPyramidLayerPresentDto"
-          description: Snapshot `layers.*.applicable` for each layer.
-        totalClassifiedFiles: { type: integer, minimum: 0 }
-        shape:
-          $ref: "#/components/schemas/InsightsTestPyramidShapeDto"
-        lineCoverage:
-          allOf:
-            - $ref: "#/components/schemas/TestPyramidLineCoverageDto"
-          description: >
-            Same overlay as AF progress — latest Sonar row first, else snapshot
-            `testPyramid.lineCoverage`. Null when both are missing. Not Code Insights
-            `coveragePct`.
-        lowestConfidence:
-          allOf:
-            - $ref: "#/components/schemas/InsightsTestPyramidConfidenceDto"
-          description: >
-            Minimum confidence among layers with Insights presence (`fileCount > 0`);
-            if none present, minimum of applicable layers. Order low < medium < high.
-        layerConfidence:
-          $ref: "#/components/schemas/InsightsTestPyramidLayerConfidenceDto"
-        evidenceCount:
+        provider:
+          $ref: "#/components/schemas/EvalAiProviderDto"
+        modelName:
+          type: string
+        suiteCount:
           type: integer
           minimum: 0
-          description: Sum of layer `evidence[]` lengths on the latest snapshot.
-        frameworks:
-          type: array
-          maxItems: 8
-          items: { type: string }
-          description: Unique framework names across layers, capped at 8.
-        e2eCrossRepoCandidate: { type: boolean }
-        hotspotCount:
-          type: integer
+        avgScore:
+          type: number
           nullable: true
           minimum: 0
-          description: >
-            Row count in `tai_workspace_repo_code_hotspots` for the repo's latest
-            Code Insights metrics snapshot. Null when the repo has no metrics snapshot.
+          maximum: 1
+          description: Average suite score across succeeded runs for this model; null when none.
 
-    InsightsTestPyramidRepoListDto:
+    EvalInsightsDto:
       type: object
-      required: [items, total, limit, offset]
+      additionalProperties: false
+      required: [regressions, promptTips, tokenEfficiency, modelComparison]
+      description: >
+        Insights hub payload for Prompt & model evals. Empty succeeded-run history
+        → empty arrays and null `tokenEfficiency`.
       properties:
-        items:
+        regressions:
           type: array
           items:
-            $ref: "#/components/schemas/InsightsTestPyramidRepoItemDto"
-        total: { type: integer, minimum: 0 }
-        limit: { type: integer, minimum: 1 }
-        offset: { type: integer, minimum: 0 }
+            $ref: "#/components/schemas/EvalRegressionDto"
+        promptTips:
+          type: array
+          items:
+            $ref: "#/components/schemas/EvalPromptTipDto"
+        tokenEfficiency:
+          type: object
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/EvalTokenEfficiencyDto"
+        modelComparison:
+          type: array
+          items:
+            $ref: "#/components/schemas/EvalModelComparisonDto"