@thinkai/tai-api-contract 2.63.0 → 2.65.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.63.0
+  version: 2.65.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -56,6 +56,12 @@ tags:
     description: Your AI Journey dashboard aggregators (epic #267); composes readiness, metrics, and AI-spend data for the /dashboard page
   - name: SdlcInsights
     description: SDLC Engineering Health insights — DORA, CI, collaboration, security, governance, and operational metrics for `/insights/sdlc/overview`.
+  - name: InsightsRecommendations
+    description: >
+      Cross-analysis Insights & Recommendations page (`/insights-recommendations`).
+      Seven workspace-scoped GET resources under `/insights/recommendations-page/*`
+      with shared date/org/provider filters. Numbers are computed from dashboard metrics,
+      AI-tool usage/spend, org chart, and readiness — never mock payloads.
   - name: WorkspaceActivity
     description: Workspace-wide lifecycle activity log — repo add/remove/re-add and integration lifecycle events (issue #515).
   - name: PlatformAdmin
@@ -2721,6 +2727,303 @@ paths:
         "404":
           description: Workspace or metric not found
 
+  /workspaces/{workspaceId}/insights/recommendations-page/verdict-summary:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — verdict summary cards
+      description: >
+        Top status cards for `/insights-recommendations`. `productivityMultiplier` is the
+        merged-PR volume ratio versus the previous equal-length window (not AI-active vs
+        non-users). `ciFailRatePct` is portfolio CI fail rate percent. Cost statuses compare
+        AI spend per merged PR to the prior window. Status thresholds match the product UI:
+        productivity ≥1.5 healthy / ≥1.0 watch / else at-risk; CI fail <15 healthy / ≤30 watch /
+        else at-risk; cost change ≤0 healthy / <20% watch / else at-risk (prev≤0 → watch).
+      operationId: getInsightsRecommendationsVerdictSummary
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: Verdict summary with `_meta.isMock=false`
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsVerdictSummaryResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/recommendations-page/roi-quadrant:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — AI spend vs delivery output
+      description: >
+        Per-engineer AI spend (USD) and merged PR counts for the scatter / ROI quadrant.
+        Includes engineers with spend>0 or mergedPrs>0. Medians are over the returned set
+        (n<2 uses the single point or zeros when empty). `id` is the stable org person id.
+      operationId: getInsightsRecommendationsRoiQuadrant
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: ROI quadrant payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsRoiQuadrantResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/recommendations-page/velocity-quality:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — velocity vs quality weekly series
+      description: >
+        Weekly merged PR volume and CI fail rate for the filter window. Weeks follow the
+        Measure calendar-week bucket convention. `targetFailRatePct` is the org target (15).
+        `volumeGrowthPct` is percent change vs the prior equal-length period.
+      operationId: getInsightsRecommendationsVelocityQuality
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: Velocity vs quality payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsVelocityQualityResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/recommendations-page/review-pipeline:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — review bottleneck funnel
+      description: >
+        Review funnel stages `open-review`, `review-approval`, `approval-merge`, and `merged`.
+        Wait stages use delivery-health hours (`avgReviewWaitHours`, `avgApprovalHours`, and
+        approval→merge as max(0, avgTimeToMergeHours − wait − approval)). The `merged` stage
+        uses `medianHours=0` (volume is not hours). `bottleneckStageId` is the wait stage with
+        the highest median hours. `reviewerLoad` comes from persisted `deliveryHealth.topReviewers`
+        when available; otherwise an empty array (never invented reviewers).
+      operationId: getInsightsRecommendationsReviewPipeline
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: Review pipeline payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsReviewPipelineResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/recommendations-page/cost-per-pr:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — cost per merged PR by team
+      description: >
+        Org and per-team AI spend / merged PRs. Teams with zero merged PRs in the window are
+        omitted. `costPerPrUsd = spendUsd / mergedPrs`. `activeAi` is distinct AI-active members
+        on the team in the window (provider filter applied).
+      operationId: getInsightsRecommendationsCostPerPr
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: Cost per PR payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsCostPerPrResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/recommendations-page/adoption-gap:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — AI adoption gap by team
+      description: >
+        Headcount vs AI-active contributors and per-team readiness/output. `readinessPct` is the
+        mean latest overallScore of repos with matching `teamId` (workspace mean fallback).
+        `outputPerEngPerWeek` is team merged PRs / headcount / weeks in window. `upliftPct`
+        estimates additional PR volume if non-adopters matched leader-team output
+        (teams with >50% adoption).
+      operationId: getInsightsRecommendationsAdoptionGap
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: Adoption gap payload
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsAdoptionGapResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/recommendations-page/recommendations:
+    get:
+      tags: [InsightsRecommendations]
+      summary: Insights recommendations — deterministic action items
+      description: >
+        Deterministic rules engine (no LLM). Emits module-anchored recommendations with
+        `moduleId` in {mod-spend-vs-output, mod-velocity-vs-quality, mod-review-bottleneck,
+        mod-cost-per-pr, mod-adoption-gap}. Action items must cite one AI metric and one
+        delivery metric in `observed`. Evidence chips use kinds user-spend|team|contributor|repo|module
+        with real target ids when available.
+      operationId: getInsightsRecommendationsRecommendations
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/InsightsRecommendationsDepartments"
+        - $ref: "#/components/parameters/InsightsRecommendationsTeams"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateFrom"
+        - $ref: "#/components/parameters/InsightsRecommendationsDateTo"
+        - $ref: "#/components/parameters/InsightsRecommendationsProvider"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeUnmapped"
+        - $ref: "#/components/parameters/InsightsRecommendationsIncludeBots"
+      responses:
+        "200":
+          description: Recommendation items
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/InsightsRecommendationsListResponse"
+        "400":
+          description: Invalid filter or date range
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [error]
+                properties:
+                  error: { type: string, example: invalid_query }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+
   /workspaces/{workspaceId}/integrations/ai-tool/{provider}/members:
     get:
       tags: [Workspace]
@@ -7218,6 +7521,71 @@ components:
       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:
+          type: string
+      style: form
+      explode: true
+    InsightsRecommendationsIncludeUnmapped:
+      name: includeUnmapped
+      in: query
+      description: Include contributors / AI rows not mapped to a team.
+      schema:
+        type: boolean
+        default: true
+    InsightsRecommendationsIncludeBots:
+      name: includeBots
+      in: query
+      description: Include bot accounts in PR/CI stats.
+      schema:
+        type: boolean
+        default: false
     PaginationLimit:
       name: limit
       in: query
@@ -11495,6 +11863,27 @@ components:
         productivityRefreshInProgress:
           type: boolean
           description: True while another session holds the workspace productivity ingest advisory lock.
+        productivityIngestPendingRepoCount:
+          type: integer
+          minimum: 0
+          nullable: true
+          description: Repos remaining in the staged backfill queue.
+        productivityIngestSkippedRepoCount:
+          type: integer
+          minimum: 0
+          nullable: true
+          description: Repos benign-skipped or quarantined during backfill.
+        productivityIngestFailedRepoCount:
+          type: integer
+          minimum: 0
+          nullable: true
+          description: Repos with transient failures awaiting retry in the current phase.
+        productivityIngestCoveragePercent:
+          type: number
+          minimum: 0
+          maximum: 100
+          nullable: true
+          description: Percent of eligible repos with merged-PR productivity data (excludes skipped/quarantined).
 
     GithubInstallUrlRequestDto:
       type: object
@@ -13899,6 +14288,8 @@ components:
         - productivity.ingest.completed
         - productivity.ingest.failed
         - productivity.ingest.skipped
+        - productivity.ingest.repo_skipped
+        - productivity.ingest.coverage_gap_detected
         - integrations.newrelic.added
         - integrations.newrelic.removed
         - integrations.newrelic.sync_completed
@@ -14503,3 +14894,317 @@ components:
             $ref: "#/components/schemas/SdlcDrilldownItemDto"
         nextCursor:
           type: string
+
+    InsightsResponseMeta:
+      type: object
+      required: [syncedAt, isMock]
+      properties:
+        syncedAt:
+          type: string
+          format: date-time
+          description: ISO timestamp when numbers were computed server-side
+        isMock:
+          type: boolean
+          description: Must be false for production handlers
+          enum: [false]
+
+    InsightsVerdictStatus:
+      type: string
+      enum: [healthy, watch, at-risk]
+
+    InsightsRecommendationsVerdictSummary:
+      type: object
+      required:
+        - productivityMultiplier
+        - productivityStatus
+        - ciFailRatePct
+        - qualityStatus
+        - spendPerMergedPrUsd
+        - spendPerMergedPrPrevUsd
+        - costStatus
+      properties:
+        productivityMultiplier:
+          type: number
+          description: >
+            Merged-PR volume ratio vs prior equal-length window (current/prior).
+            When priorMergedPrs is 0, value is 1.0 and productivityStatus is watch.
+        productivityStatus:
+          $ref: "#/components/schemas/InsightsVerdictStatus"
+        ciFailRatePct:
+          type: number
+        qualityStatus:
+          $ref: "#/components/schemas/InsightsVerdictStatus"
+        spendPerMergedPrUsd:
+          type: number
+        spendPerMergedPrPrevUsd:
+          type: number
+        costStatus:
+          $ref: "#/components/schemas/InsightsVerdictStatus"
+
+    InsightsRecommendationsVerdictSummaryResponse:
+      allOf:
+        - $ref: "#/components/schemas/InsightsRecommendationsVerdictSummary"
+        - type: object
+          required: [_meta]
+          properties:
+            _meta:
+              $ref: "#/components/schemas/InsightsResponseMeta"
+
+    InsightsRoiEngineerPoint:
+      type: object
+      required: [id, name, team, spendUsd, mergedPrs]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        team: { type: string }
+        spendUsd: { type: number }
+        mergedPrs: { type: number }
+
+    InsightsRecommendationsRoiQuadrant:
+      type: object
+      required: [medianSpendUsd, medianMergedPrs, engineers, correlationHint]
+      properties:
+        medianSpendUsd: { type: number }
+        medianMergedPrs: { type: number }
+        engineers:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsRoiEngineerPoint"
+        correlationHint: { type: string }
+
+    InsightsRecommendationsRoiQuadrantResponse:
+      allOf:
+        - $ref: "#/components/schemas/InsightsRecommendationsRoiQuadrant"
+        - type: object
+          required: [_meta]
+          properties:
+            _meta:
+              $ref: "#/components/schemas/InsightsResponseMeta"
+
+    InsightsVelocityQualityWeek:
+      type: object
+      required: [weekStartIso, mergedPrs, ciFailRatePct]
+      properties:
+        weekStartIso: { type: string, format: date }
+        mergedPrs: { type: number }
+        ciFailRatePct: { type: number }
+
+    InsightsRecommendationsVelocityQuality:
+      type: object
+      required: [weeks, targetFailRatePct, volumeGrowthPct]
+      properties:
+        weeks:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsVelocityQualityWeek"
+        targetFailRatePct: { type: number }
+        volumeGrowthPct: { type: number }
+
+    InsightsRecommendationsVelocityQualityResponse:
+      allOf:
+        - $ref: "#/components/schemas/InsightsRecommendationsVelocityQuality"
+        - type: object
+          required: [_meta]
+          properties:
+            _meta:
+              $ref: "#/components/schemas/InsightsResponseMeta"
+
+    InsightsReviewStageId:
+      type: string
+      enum: [open-review, review-approval, approval-merge, merged]
+
+    InsightsReviewStage:
+      type: object
+      required: [id, name, medianHours, trendPct]
+      properties:
+        id:
+          $ref: "#/components/schemas/InsightsReviewStageId"
+        name: { type: string }
+        medianHours:
+          type: number
+          description: Wait hours for funnel stages; 0 for the merged volume stage
+        trendPct: { type: number }
+
+    InsightsReviewerLoadItem:
+      type: object
+      required: [id, name, reviewsCount, sharePct]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        reviewsCount: { type: number }
+        sharePct: { type: number }
+
+    InsightsRecommendationsReviewPipeline:
+      type: object
+      required: [stages, bottleneckStageId, reviewerLoad]
+      properties:
+        stages:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsReviewStage"
+        bottleneckStageId:
+          $ref: "#/components/schemas/InsightsReviewStageId"
+        reviewerLoad:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsReviewerLoadItem"
+
+    InsightsRecommendationsReviewPipelineResponse:
+      allOf:
+        - $ref: "#/components/schemas/InsightsRecommendationsReviewPipeline"
+        - type: object
+          required: [_meta]
+          properties:
+            _meta:
+              $ref: "#/components/schemas/InsightsResponseMeta"
+
+    InsightsCostPerPrTeam:
+      type: object
+      required: [id, name, activeAi, spendUsd, mergedPrs, costPerPrUsd, changePct]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        activeAi: { type: number }
+        spendUsd: { type: number }
+        mergedPrs: { type: number }
+        costPerPrUsd: { type: number }
+        changePct: { type: number }
+
+    InsightsRecommendationsCostPerPr:
+      type: object
+      required: [orgAvgCostUsd, orgAvgPrevUsd, teams]
+      properties:
+        orgAvgCostUsd: { type: number }
+        orgAvgPrevUsd: { type: number }
+        teams:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsCostPerPrTeam"
+
+    InsightsRecommendationsCostPerPrResponse:
+      allOf:
+        - $ref: "#/components/schemas/InsightsRecommendationsCostPerPr"
+        - type: object
+          required: [_meta]
+          properties:
+            _meta:
+              $ref: "#/components/schemas/InsightsResponseMeta"
+
+    InsightsAdoptionTeam:
+      type: object
+      required: [id, name, activeAi, totalMembers, readinessPct, outputPerEngPerWeek]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        activeAi: { type: number }
+        totalMembers: { type: number }
+        readinessPct: { type: number }
+        outputPerEngPerWeek: { type: number }
+
+    InsightsRecommendationsAdoptionGap:
+      type: object
+      required: [totalContributors, activeContributors, upliftPct, teams]
+      properties:
+        totalContributors: { type: number }
+        activeContributors: { type: number }
+        upliftPct: { type: number }
+        teams:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsAdoptionTeam"
+
+    InsightsRecommendationsAdoptionGapResponse:
+      allOf:
+        - $ref: "#/components/schemas/InsightsRecommendationsAdoptionGap"
+        - type: object
+          required: [_meta]
+          properties:
+            _meta:
+              $ref: "#/components/schemas/InsightsResponseMeta"
+
+    InsightsRecommendationModuleId:
+      type: string
+      enum:
+        - mod-spend-vs-output
+        - mod-velocity-vs-quality
+        - mod-review-bottleneck
+        - mod-cost-per-pr
+        - mod-adoption-gap
+
+    InsightsRecommendationImpact:
+      type: string
+      enum: [high, medium]
+
+    InsightsRecommendationTone:
+      type: string
+      enum: [action, no-action]
+
+    InsightsEvidenceLinkKind:
+      type: string
+      enum: [user-spend, team, contributor, repo, module]
+
+    InsightsEvidenceChip:
+      type: object
+      required: [label, kind, targetId]
+      properties:
+        label: { type: string }
+        kind:
+          $ref: "#/components/schemas/InsightsEvidenceLinkKind"
+        targetId: { type: string }
+
+    InsightsRecommendationEvidenceGroup:
+      type: object
+      required: [title, chips]
+      properties:
+        title: { type: string }
+        chips:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsEvidenceChip"
+
+    InsightsRecommendationDto:
+      type: object
+      required:
+        - moduleId
+        - moduleName
+        - tone
+        - impact
+        - headline
+        - observed
+        - action
+        - benefit
+        - confidencePct
+        - evidence
+      properties:
+        moduleId:
+          $ref: "#/components/schemas/InsightsRecommendationModuleId"
+        moduleName: { type: string }
+        tone:
+          $ref: "#/components/schemas/InsightsRecommendationTone"
+        impact:
+          $ref: "#/components/schemas/InsightsRecommendationImpact"
+        headline: { type: string }
+        observed:
+          type: string
+          description: For tone=action must cite one AI metric and one delivery metric
+        action: { type: string }
+        benefit: { type: string }
+        confidencePct:
+          type: number
+          minimum: 0
+          maximum: 100
+        evidence:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsRecommendationEvidenceGroup"
+
+    InsightsRecommendationsListResponse:
+      type: object
+      required: [items, _meta]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/InsightsRecommendationDto"
+        _meta:
+          $ref: "#/components/schemas/InsightsResponseMeta"