@thinkai/tai-api-contract 2.5.1 → 2.5.16

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.5.1
+  version: 2.5.16
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -574,587 +574,779 @@ paths:
         "401":
           $ref: "#/components/responses/Unauthorized"
 
-  /workspaces/{workspaceId}/company-profile:
+  /workspaces/{workspaceId}/insights/productivity-insights/aggregated-teams:
     get:
-      tags: [CompanyProfile]
-      summary: Get company profile
-      operationId: getCompanyProfile
+      tags: [Workspace]
+      summary: Productivity insights — aggregated team weekly metrics
+      description: >
+        Team-level rollup for Productivity insights (Aggregated Teams view on /phase-c/c4).
+        Returns weekly merged PR counts and fail rates per engineering team, filtered by the
+        same department, team, and range controls as the Measure UI.
+      operationId: getProductivityInsightsAggregatedTeams
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - name: rangeId
+          in: query
+          description: Measure time range (maps to weekly bucket count).
+          schema:
+            type: string
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
+          in: query
+          description: Team name filter; send `All teams` to include every team.
+          schema:
+            type: string
+            default: All teams
+        - name: windowEnd
+          in: query
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
+          schema:
+            type: string
+            format: date-time
       responses:
         "200":
-          description: >
-            Company profile DTO, or JSON `null` when the workspace exists but no profile
-            has been saved yet. Clients should treat `null` as the empty initial state
-            (the wizard renders blank inputs); they MUST NOT treat the absence of a
-            saved profile as a 404.
+          description: Aggregated team productivity series
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/CompanyProfileDto"
-              examples:
-                sample:
-                  summary: Saved profile
-                  value:
-                    companyName: Acme
-                    industry: software
-                    companySize: "51-200"
-                    engineeringHC: "42"
-                    headquarters: "Austin, TX"
+                $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsDto"
         "400":
-          description: Malformed workspaceId
+          description: Invalid query parameters
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                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
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
-    put:
-      tags: [CompanyProfile]
-      summary: Upsert company profile
-      operationId: putCompanyProfile
+          description: Workspace does not exist or malformed workspaceId
+
+  /workspaces/{workspaceId}/insights/productivity-insights/merged-pr-trends:
+    get:
+      tags: [Workspace]
+      summary: Productivity insights — merged PR trends (portfolio + contributors)
       description: >
-        Idempotent upsert of the workspace's company profile. On success, also
-        synchronizes `tai_workspaces.name` to the new `companyName` so subsequent
-        calls to `GET /me/workspaces` reflect the updated display name. Repeated
-        PUTs replace the stored payload entirely.
+        Weekly merged PR counts for the Measure "Merged PR Trends" widget on /phase-c/c4
+        Individual Contributors. Returns a portfolio aggregate series plus per-contributor weekly
+        counts, filtered by the same department, team, and range controls as the Measure UI.
+      operationId: getProductivityInsightsMergedPrTrends
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/CompanyProfileDto"
+        - name: rangeId
+          in: query
+          description: Measure time range (maps to weekly bucket count).
+          schema:
+            type: string
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
+          in: query
+          description: Team name filter; send `All teams` to include every team.
+          schema:
+            type: string
+            default: All teams
+        - name: windowEnd
+          in: query
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
+          schema:
+            type: string
+            format: date-time
       responses:
-        "204":
-          description: Saved
+        "200":
+          description: Portfolio and per-contributor merged PR weekly series
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProductivityInsightsMergedPrTrendsDto"
         "400":
-          description: Body fails validation (missing/invalid required field, bad enum, conditional rule)
+          description: Invalid query parameters
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                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
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+          description: Workspace does not exist or malformed workspaceId
 
-  /workspaces/{workspaceId}/integrations/github:
+  /workspaces/{workspaceId}/insights/productivity-insights/teams:
     get:
-      tags: [Integrations]
-      summary: GitHub App installation status for workspace
-      operationId: getWorkspaceGithubInstallationStatus
+      tags: [Workspace]
+      summary: Productivity insights — top teams and team drilldown
       description: >
-        Returns whether a GitHub App installation is linked and cached repo metadata.
-        When no installation exists, returns 200 with `installed: false` (never 404 for missing install).
-        Use `refresh=true` to bypass cache and re-list repositories from GitHub.
+        Without `teamId`: returns the top-ranked teams by average weekly merged PR count for the
+        Measure **Top teams** widget on /phase-c/c4 and /phase-c/c7. With `teamId`: returns weekly
+        rollup and summary for a single team (powers `/phase-c/c4/teams/:teamId` drilldown).
+      operationId: getProductivityInsightsTeams
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: refresh
+        - name: teamId
           in: query
-          required: false
-          description: When true, bypass `tai_workspace_vcs_repos_cache` and re-fetch from GitHub.
+          description: >
+            When set, return drilldown for this org-chart team id instead of the top-team list.
           schema:
-            type: boolean
-            default: false
+            type: string
+        - name: limit
+          in: query
+          description: Maximum top-team rows when `teamId` is omitted (UI default 3).
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 10
+            default: 3
+        - name: rangeId
+          in: query
+          description: Measure time range (maps to weekly bucket count).
+          schema:
+            type: string
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
+          in: query
+          description: Team name filter; send `All teams` to include every team.
+          schema:
+            type: string
+            default: All teams
+        - name: windowEnd
+          in: query
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
+          schema:
+            type: string
+            format: date-time
       responses:
         "200":
-          description: Installation status
+          description: Top teams list or single-team drilldown
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/GithubInstallationStatusDto"
+                $ref: "#/components/schemas/ProductivityInsightsTeamsResponseDto"
+        "400":
+          description: Invalid query parameters
+          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
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+          description: Workspace or team not found
 
-    delete:
-      tags: [Integrations]
-      summary: Disconnect GitHub App installation for workspace
-      operationId: deleteWorkspaceGithubInstallation
+  /workspaces/{workspaceId}/insights/productivity-insights/contributors/{contributorId}:
+    get:
+      tags: [Workspace]
+      summary: Productivity insights — contributor drilldown
       description: >
-        Removes the workspace GitHub App integration row (and cascaded VCS connection + repos cache).
-        Idempotent: returns 204 when no installation exists. Does not uninstall the app on GitHub;
-        use the manage URL or GitHub settings to revoke the app there if required.
-      security:
-        - bearerAuth: []
+        Weekly and daily activity rollups for a single contributor on
+        `/phase-c/c4/contributors/:id`. Distributes weekly merged PR counts from
+        precomputed person metrics across weekdays; includes fail-rate signals and
+        period-over-period summary deltas. Uses org-chart person ids (typically email).
+      operationId: getProductivityInsightsContributor
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: installationId
+        - name: contributorId
+          in: path
+          required: true
+          description: Org-chart person id (e.g. email from `person_id` external id).
+          schema:
+            type: string
+        - name: rangeId
           in: query
-          required: false
-          description: Optional installation id to disconnect a single linked installation.
+          description: Measure time range (maps to weekly bucket count).
           schema:
             type: string
-        - name: all
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
           in: query
-          required: false
-          description: When true, disconnect all linked GitHub installations for this workspace.
+          description: Team name filter; send `All teams` to include every team.
           schema:
-            type: boolean
+            type: string
+            default: All teams
+        - name: windowEnd
+          in: query
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
+          schema:
+            type: string
+            format: date-time
       responses:
-        "204":
-          description: Installation removed or was already absent
+        "200":
+          description: Contributor activity drilldown
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProductivityInsightsContributorDetailDto"
+        "400":
+          description: Invalid query parameters
+          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
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+          description: Workspace or contributor not found
 
-  /workspaces/{workspaceId}/integrations/github/install-url:
-    post:
-      tags: [Integrations]
-      summary: Create GitHub App installation URL
-      operationId: postGithubInstallUrl
+  /workspaces/{workspaceId}/insights/productivity-insights/needs-attention:
+    get:
+      tags: [Workspace]
+      summary: Productivity insights — needs attention (bottom performers)
       description: >
-        Creates a GitHub App installation URL scoped to the workspace and caller.
-        Body is optional; when omitted, defaults to `/phase-a/p3` return path.
-      security:
-        - bearerAuth: []
+        Bottom performers for the Measure "Needs attention" widget on /phase-c/c4
+        (LeadersLaggards laggards column). Returns the lowest-ranked teams or contributors
+        by average weekly merged PR count for the selected filters and range.
+      operationId: getProductivityInsightsNeedsAttention
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-      requestBody:
-        required: false
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/GithubInstallUrlRequestDto"
+        - name: entityType
+          in: query
+          description: Rank teams (Aggregated Teams tab) or contributors (Individual Contributors tab).
+          schema:
+            type: string
+            enum: [teams, contributors]
+            default: contributors
+        - name: limit
+          in: query
+          description: Maximum number of laggard rows to return (UI default 3).
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 10
+            default: 3
+        - name: rangeId
+          in: query
+          description: Measure time range (maps to weekly bucket count).
+          schema:
+            type: string
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
+          in: query
+          description: Team name filter; send `All teams` to include every team.
+          schema:
+            type: string
+            default: All teams
+        - name: windowEnd
+          in: query
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
+          schema:
+            type: string
+            format: date-time
       responses:
         "200":
-          description: Installation URL + signed state
+          description: Bottom performers for the needs-attention widget
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/GithubInstallUrlResponseDto"
+                $ref: "#/components/schemas/ProductivityInsightsNeedsAttentionDto"
         "400":
-          description: Request validation failed
+          description: Invalid query parameters
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                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
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/refresh:
-    post:
-      tags: [Integrations]
-      summary: Refresh AI tool integration snapshots
-      operationId: refreshWorkspaceAiTool
+  /workspaces/{workspaceId}/insights/ai-usage-spend/aggregated-teams:
+    get:
+      tags: [Workspace]
+      summary: AI usage & spend insights — aggregated team weekly rollups
       description: >
-        Provider-agnostic refresh. Returns 409 when an advisory-lock refresh is already in progress.
-        On upstream auth/rate/network failures, returns `200` with `{ ok:false, error }` so the SPA can render inline error.
+        Team-level AI adoption, token volume, and spend for the Measure **Aggregated Teams**
+        view on `/phase-c/c7` and the dashboard AI Usage & Spend card. Aggregates stored
+        AI-tool integration snapshots (daily usage + billing spend) by org-chart team using
+        member email. Same filter params as other Measure insights routes.
+      operationId: getAiUsageSpendAggregatedTeams
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: provider
-          in: path
-          required: true
+        - name: rangeId
+          in: query
+          description: Measure time range (maps to weekly bucket count).
           schema:
             type: string
-            enum: [cursor]
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
+          in: query
+          description: Team name filter; send `All teams` to include every team.
+          schema:
+            type: string
+            default: All teams
+        - name: windowEnd
+          in: query
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
+          schema:
+            type: string
+            format: date-time
       responses:
         "200":
-          description: Refresh result
+          description: Aggregated team AI usage and spend series
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AiToolRefreshResponseDto"
-              examples:
-                ok:
-                  value: { ok: true }
-                invalid_token:
-                  value: { ok: false, error: invalid_token }
+                $ref: "#/components/schemas/AiUsageSpendAggregatedTeamsDto"
+        "400":
+          description: Invalid query parameters
+          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: Provider source missing for this workspace
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/AiToolRefreshResponseDto"
-              example:
-                ok: false
-                error: no_source
-        "409":
-          description: Refresh already in progress
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/AiToolRefreshResponseDto"
-              example:
-                ok: false
-                error: already_in_progress
+          description: Workspace does not exist or malformed workspaceId
 
-  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/seats:
+  /workspaces/{workspaceId}/insights/ai-usage-spend/aggregated-contributors:
     get:
-      tags: [Integrations]
-      summary: List latest AI-tool seats
-      operationId: getWorkspaceAiToolSeats
+      tags: [Workspace]
+      summary: AI usage & spend insights — aggregated contributor weekly rollups
+      description: >
+        Per-contributor AI adoption, token volume, and spend for the Measure **Individual
+        Contributors** view on `/phase-c/c7`. Aggregates stored AI-tool integration snapshots
+        (daily usage + billing spend) by org-chart person id (typically email). Same filter
+        params as other Measure insights routes.
+      operationId: getAiUsageSpendAggregatedContributors
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: provider
-          in: path
-          required: true
+        - name: rangeId
+          in: query
+          description: Measure time range (maps to weekly bucket count).
           schema:
             type: string
-            enum: [cursor]
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
+          in: query
+          description: Team name filter; send `All teams` to include every team.
+          schema:
+            type: string
+            default: All teams
+        - name: windowEnd
+          in: query
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
+          schema:
+            type: string
+            format: date-time
       responses:
         "200":
-          description: Seats
+          description: Aggregated contributor AI usage and spend series
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiUsageSpendAggregatedContributorsDto"
+        "400":
+          description: Invalid query parameters
           content:
             application/json:
               schema:
                 type: object
-                required: [seats]
+                required: [error]
                 properties:
-                  seats:
-                    type: array
-                    items:
-                      $ref: "#/components/schemas/AiToolSeatDto"
+                  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}/daily-usage:
+  /workspaces/{workspaceId}/insights/ai-usage-spend/contributor-tool-heatmap:
     get:
-      tags: [Integrations]
-      summary: List AI-tool daily usage
-      operationId: getWorkspaceAiToolDailyUsage
+      tags: [Workspace]
+      summary: AI usage & spend insights — contributor × week heatmap rows
+      description: >
+        Contributor × week heatmap rows for the Measure **Individual Contributors** tool
+        heatmap on `/phase-c/c7`. Same aggregation as aggregated-contributors; returns
+        weekly token, spend, and active-user counts per org-chart person.
+      operationId: getAiUsageSpendContributorToolHeatmap
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: provider
-          in: path
-          required: true
-          schema:
-            type: string
-            enum: [cursor]
-        - name: from
+        - name: rangeId
           in: query
-          required: false
+          description: Measure time range (maps to weekly bucket count).
           schema:
             type: string
-            format: date
-        - name: to
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
           in: query
-          required: false
+          description: Team name filter; send `All teams` to include every team.
           schema:
             type: string
-            format: date
-        - name: externalId
+            default: All teams
+        - name: windowEnd
           in: query
-          required: false
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
           schema:
             type: string
+            format: date-time
       responses:
         "200":
-          description: Usage rows
+          description: Contributor heatmap rows for AI usage and spend
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiUsageSpendContributorToolHeatmapDto"
+        "400":
+          description: Invalid query parameters
           content:
             application/json:
               schema:
                 type: object
-                required: [rows]
+                required: [error]
                 properties:
-                  rows:
-                    type: array
-                    items:
-                      $ref: "#/components/schemas/AiToolDailyUsageRowDto"
+                  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}/spend:
+  /workspaces/{workspaceId}/insights/ai-usage-spend/key-insights:
     get:
-      tags: [Integrations]
-      summary: List AI-tool spend
-      operationId: getWorkspaceAiToolSpend
+      tags: [Workspace]
+      summary: AI usage & spend insights — key insights panel
+      description: >
+        Narrative insight cards for the Measure **Key insights** panel on `/phase-c/c7`
+        (AI Usage & Spend). Derived from scoped AI-tool usage/spend snapshots and
+        productivity metrics for the selected filters and range.
+      operationId: getAiUsageSpendKeyInsights
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: provider
-          in: path
-          required: true
+        - name: rangeId
+          in: query
+          description: Measure time range (maps to weekly bucket count).
           schema:
             type: string
-            enum: [cursor]
-        - name: cycleStartMs
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
           in: query
-          required: false
+          description: Team name filter; send `All teams` to include every team.
           schema:
-            type: integer
-            format: int64
+            type: string
+            default: All teams
+        - name: windowEnd
+          in: query
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
+          schema:
+            type: string
+            format: date-time
       responses:
         "200":
-          description: Spend rows
+          description: Key insight cards for the AI usage & spend panel
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiUsageSpendKeyInsightsDto"
+        "400":
+          description: Invalid query parameters
           content:
             application/json:
               schema:
                 type: object
-                required: [rows]
+                required: [error]
                 properties:
-                  rows:
-                    type: array
-                    items:
-                      $ref: "#/components/schemas/AiToolSpendRowDto"
+                  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}/status:
+  /workspaces/{workspaceId}/insights/ai-usage-spend/ai-assisted-code-percentage:
     get:
-      tags: [Integrations]
-      summary: Get last refresh status
-      operationId: getWorkspaceAiToolRefreshStatus
+      tags: [Workspace]
+      summary: AI usage & spend insights — AI-assisted code percentage
+      description: >
+        Period and weekly AI-assisted code percentage for the Measure **AI-assisted code**
+        card on `/phase-c/c7` and the **AI impact** curve on `/phase-c/c4`. When scoped
+        productivity metrics include `aiAssistedContributionRatioPercent`, values are
+        **measured** from ingest; otherwise the API falls back to token→LOC heuristics and
+        sets `dataQuality` to **estimated**. Clients should not present estimated series as
+        Cursor-measured signal.
+      operationId: getAiUsageSpendAiAssistedCodePercentage
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: provider
-          in: path
-          required: true
+        - name: rangeId
+          in: query
+          description: Measure time range (maps to weekly bucket count).
           schema:
             type: string
-            enum: [cursor]
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
+          in: query
+          description: Team name filter; send `All teams` to include every team.
+          schema:
+            type: string
+            default: All teams
+        - name: windowEnd
+          in: query
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
+          schema:
+            type: string
+            format: date-time
       responses:
         "200":
-          description: Refresh status
+          description: AI-assisted code percentage series
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiUsageSpendAiAssistedCodePercentageDto"
+        "400":
+          description: Invalid query parameters
           content:
             application/json:
               schema:
                 type: object
-                required: [status]
+                required: [error]
                 properties:
-                  status:
-                    $ref: "#/components/schemas/AiToolRefreshStatusDto"
+                  error: { type: string, example: invalid_query }
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
         "404":
-          description: No refresh status yet (or provider source missing)
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/AiToolRefreshResponseDto"
-              example:
-                ok: false
-                error: no_source
+          description: Workspace does not exist or malformed workspaceId
 
-  /integrations/github/callback:
+  /workspaces/{workspaceId}/insights/ai-usage-spend/ai-tool-usage-spend:
     get:
-      tags: [Integrations]
-      summary: GitHub App installation callback
-      operationId: getGithubInstallCallback
+      tags: [Workspace]
+      summary: AI usage & spend insights — AI tool usage and spend by provider/model
       description: >
-        Public callback endpoint used by GitHub App installation flow.
-        Resolves and consumes install state, persists workspace installation linkage,
-        then redirects to configured SPA origin with status markers.
+        Scoped portfolio rollups of AI-tool token usage and spend by registered provider
+        and by model (from daily usage `mostUsedModel`) for the **Provider / Model usage + spend**
+        chart on `/phase-c/c4` and `/phase-c/c7`. Reads stored AI-tool integration snapshots
+        (`tai_workspace_ai_tool_daily_usage`, `tai_workspace_ai_tool_spend`).
+      operationId: getAiUsageSpendAiToolUsageSpend
       parameters:
-        - name: state
-          in: query
-          required: true
-          schema:
-            type: string
-        - name: installation_id
-          in: query
-          required: false
-          schema:
-            type: string
-        - name: setup_action
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: rangeId
           in: query
-          required: false
+          description: Measure time range (maps to weekly bucket count).
           schema:
             type: string
-        - name: error
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
           in: query
-          required: false
+          description: Team name filter; send `All teams` to include every team.
           schema:
             type: string
-        - name: error_description
+            default: All teams
+        - name: windowEnd
           in: query
-          required: false
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
           schema:
             type: string
+            format: date-time
       responses:
-        "302":
-          description: Redirect to ThinkAI SPA return path with GitHub connection status
-        "501":
-          description: Workspace store not configured
+        "200":
+          description: Provider and model AI tool usage/spend rollups
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
-        "503":
-          description: SPA origin configuration missing
+                $ref: "#/components/schemas/AiUsageSpendAiToolUsageSpendDto"
+        "400":
+          description: Invalid query parameters
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                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
 
-  /integrations/github/webhook:
-    post:
-      tags: [Integrations]
-      summary: GitHub App webhook receiver
-      operationId: postGithubWebhook
+  /workspaces/{workspaceId}/insights/ai-usage-spend/team-tool-heatmap:
+    get:
+      tags: [Workspace]
+      summary: AI usage & spend insights — team weekly heatmap
       description: >
-        Public webhook endpoint that verifies `X-Hub-Signature-256` and updates or
-        removes workspace GitHub integration/cache state for installation events.
+        Team × week rollups of AI-tool token volume, spend, and active users for the
+        **Team tool heatmap** on `/phase-c/c4` and `/phase-c/c7`. Aggregates stored
+        AI-tool integration snapshots by org-chart team. Same filter params as other
+        Measure insights routes.
+      operationId: getAiUsageSpendTeamToolHeatmap
       parameters:
-        - name: X-Hub-Signature-256
-          in: header
-          required: true
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: rangeId
+          in: query
+          description: Measure time range (maps to weekly bucket count).
           schema:
             type: string
-        - name: X-GitHub-Event
-          in: header
-          required: true
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
+          in: query
+          description: Team name filter; send `All teams` to include every team.
           schema:
             type: string
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              type: object
-              additionalProperties: true
+            default: All teams
+        - name: windowEnd
+          in: query
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
+          schema:
+            type: string
+            format: date-time
       responses:
         "200":
-          description: Webhook accepted
-        "400":
-          description: Invalid payload
+          description: Team weekly AI usage heatmap rows
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
-        "401":
-          description: Invalid webhook signature
+                $ref: "#/components/schemas/AiUsageSpendTeamToolHeatmapDto"
+        "400":
+          description: Invalid query parameters
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
-        "501":
-          description: Workspace store not configured
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
-        "503":
-          description: Missing GitHub webhook secret or GitHub App configuration
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                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}/ai-readiness:
+  /workspaces/{workspaceId}/insights/ai-usage-spend/roi-productivity-signal:
     get:
-      tags: [AIReadiness]
-      summary: Get AI readiness
-      operationId: getAiReadiness
+      tags: [Workspace]
+      summary: AI usage & spend insights — ROI and productivity signal
+      description: >
+        Connects scoped AI-tool usage and spend to engineering throughput (merged PRs)
+        for the **ROI & Productivity Signal** panel on `/phase-c/c4` and `/phase-c/c7`.
+        Returns spend efficiency metrics, adoption counts, and weekly usage vs PR series.
+        Same filter params as other Measure insights routes.
+      operationId: getAiUsageSpendRoiProductivitySignal
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - name: rangeId
+          in: query
+          description: Measure time range (maps to weekly bucket count).
+          schema:
+            type: string
+            enum: [4w, 8w, q]
+            default: 4w
+        - $ref: "#/components/parameters/InsightsDepartmentFilter"
+        - name: team
+          in: query
+          description: Team name filter; send `All teams` to include every team.
+          schema:
+            type: string
+            default: All teams
+        - name: windowEnd
+          in: query
+          description: ISO timestamp for the end of the last weekly bucket; omit for current week.
+          schema:
+            type: string
+            format: date-time
       responses:
         "200":
-          description: State or JSON null
+          description: ROI and productivity signal rollups
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AIReadinessDto"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-    put:
-      tags: [AIReadiness]
-      summary: Upsert AI readiness
-      operationId: putAiReadiness
-      parameters:
-        - $ref: "#/components/parameters/WorkspaceId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/AIReadinessDto"
-      responses:
-        "204":
-          description: Saved
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-
-  /workspaces/{workspaceId}/ai-readiness/maturity:
-    post:
-      tags: [AIReadiness]
-      summary: Compute maturity level
-      operationId: postAiReadinessMaturity
-      parameters:
-        - $ref: "#/components/parameters/WorkspaceId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/AIReadinessDto"
-      responses:
-        "200":
-          description: Derived level
+                $ref: "#/components/schemas/AiUsageSpendRoiProductivitySignalDto"
+        "400":
+          description: Invalid query parameters
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AiMaturityResultDto"
+                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}/tech-stack:
+  /workspaces/{workspaceId}/company-profile:
     get:
-      tags: [TechStack]
-      summary: Get tech stack
-      operationId: getTechStack
+      tags: [CompanyProfile]
+      summary: Get company profile
+      operationId: getCompanyProfile
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
           description: >
-            Saved tech stack DTO, or JSON `null` when the workspace exists but no stack
-            has been saved yet. Clients should merge `null` with their empty defaults.
+            Company profile DTO, or JSON `null` when the workspace exists but no profile
+            has been saved yet. Clients should treat `null` as the empty initial state
+            (the wizard renders blank inputs); they MUST NOT treat the absence of a
+            saved profile as a 404.
           content:
             application/json:
               schema:
-                nullable: true
-                allOf:
-                  - $ref: "#/components/schemas/TechStackDto"
+                $ref: "#/components/schemas/CompanyProfileDto"
+              examples:
+                sample:
+                  summary: Saved profile
+                  value:
+                    companyName: Acme
+                    industry: software
+                    companySize: "51-200"
+                    engineeringHC: "42"
+                    headquarters: "Austin, TX"
         "400":
           description: Malformed workspaceId
           content:
@@ -1172,9 +1364,14 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
     put:
-      tags: [TechStack]
-      summary: Upsert tech stack
-      operationId: putTechStack
+      tags: [CompanyProfile]
+      summary: Upsert company profile
+      operationId: putCompanyProfile
+      description: >
+        Idempotent upsert of the workspace's company profile. On success, also
+        synchronizes `tai_workspaces.name` to the new `companyName` so subsequent
+        calls to `GET /me/workspaces` reflect the updated display name. Repeated
+        PUTs replace the stored payload entirely.
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       requestBody:
@@ -1182,12 +1379,12 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/TechStackDto"
+              $ref: "#/components/schemas/CompanyProfileDto"
       responses:
         "204":
           description: Saved
         "400":
-          description: Body fails validation (unknown keys, bounds, missing required fields)
+          description: Body fails validation (missing/invalid required field, bad enum, conditional rule)
           content:
             application/json:
               schema:
@@ -1203,406 +1400,522 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/nda:
+  /workspaces/{workspaceId}/integrations/github:
     get:
-      tags: [NDA]
-      summary: Get NDA completion state
-      operationId: getNda
+      tags: [Integrations]
+      summary: GitHub App installation status for workspace
+      operationId: getWorkspaceGithubInstallationStatus
+      description: >
+        Returns whether a GitHub App installation is linked and cached repo metadata.
+        When no installation exists, returns 200 with `installed: false` (never 404 for missing install).
+        Use `refresh=true` to bypass cache and re-list repositories from GitHub.
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - name: refresh
+          in: query
+          required: false
+          description: When true, bypass `tai_workspace_vcs_repos_cache` and re-fetch from GitHub.
+          schema:
+            type: boolean
+            default: false
+        - name: permissionsRefresh
+          in: query
+          required: false
+          description: >
+            When true, re-fetch GitHub App and installation permission metadata (used by the
+            login permission gate after the user approves on GitHub).
+          schema:
+            type: boolean
+            default: false
       responses:
         "200":
-          description: Completion or JSON null
+          description: Installation status
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/NdaCompletionDto"
+                $ref: "#/components/schemas/GithubInstallationStatusDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/nda/template:
-    get:
-      tags: [NDA]
-      summary: NDA template for display
-      operationId: getNdaTemplate
+    delete:
+      tags: [Integrations]
+      summary: Disconnect GitHub App installation for workspace
+      operationId: deleteWorkspaceGithubInstallation
+      description: >
+        Removes the workspace GitHub App integration row (and cascaded VCS connection + repos cache).
+        Idempotent: returns 204 when no installation exists. Does not uninstall the app on GitHub;
+        use the manage URL or GitHub settings to revoke the app there if required.
+      security:
+        - bearerAuth: []
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - name: installationId
+          in: query
+          required: false
+          description: Optional installation id to disconnect a single linked installation.
+          schema:
+            type: string
+        - name: all
+          in: query
+          required: false
+          description: When true, disconnect all linked GitHub installations for this workspace.
+          schema:
+            type: boolean
       responses:
-        "200":
-          description: Template
+        "204":
+          description: Installation removed or was already absent
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/NdaTemplateDto"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
+                $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/nda/sign:
+  /workspaces/{workspaceId}/integrations/github/install-url:
     post:
-      tags: [NDA]
-      summary: Electronic NDA signature
-      operationId: postNdaSign
+      tags: [Integrations]
+      summary: Create GitHub App installation URL
+      operationId: postGithubInstallUrl
+      description: >
+        Creates a GitHub App installation URL scoped to the workspace and caller.
+        Body is optional; when omitted, defaults to `/phase-a/p3` return path.
+      security:
+        - bearerAuth: []
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       requestBody:
-        required: true
+        required: false
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/NdaSignatureDto"
+              $ref: "#/components/schemas/GithubInstallUrlRequestDto"
       responses:
         "200":
-          description: Completion record
+          description: Installation URL + signed state
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/NdaCompletionDto"
+                $ref: "#/components/schemas/GithubInstallUrlResponseDto"
+        "400":
+          description: Request validation failed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist or malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/nda/external:
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/refresh:
     post:
-      tags: [NDA]
-      summary: External NDA path (after Supabase upload)
+      tags: [Integrations]
+      summary: Refresh AI tool integration snapshots
+      operationId: refreshWorkspaceAiTool
       description: >
-        Preferred body uses `storagePath` after client upload to the `nda-documents` bucket (§14).
-        Multipart variant may be supported by the server as an alternative.
-      operationId: postNdaExternal
-      parameters:
-        - $ref: "#/components/parameters/WorkspaceId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/NdaExternalBodyDto"
-      responses:
-        "200":
-          description: Completion record
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/NdaCompletionDto"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-
-  /workspaces/{workspaceId}/readiness/repos:
-    get:
-      tags: [RepositoryReadiness]
-      summary: List repo readiness scores
-      operationId: listReadinessRepos
+        Provider-agnostic refresh. Returns 409 when an advisory-lock refresh is already in progress.
+        On upstream auth/rate/network failures, returns `200` with `{ ok:false, error }` so the SPA can render inline error.
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [cursor]
       responses:
         "200":
-          description: Repositories analyzed
+          description: Refresh result
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/AiToolRefreshResponseDto"
+              examples:
+                ok:
+                  value: { ok: true }
+                invalid_token:
+                  value: { ok: false, error: invalid_token }
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
         "404":
-          description: Workspace does not exist
+          description: Provider source missing for this workspace
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                $ref: "#/components/schemas/AiToolRefreshResponseDto"
+              example:
+                ok: false
+                error: no_source
+        "409":
+          description: Refresh already in progress
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiToolRefreshResponseDto"
+              example:
+                ok: false
+                error: already_in_progress
 
-  /workspaces/{workspaceId}/readiness/analyze:
-    post:
-      tags: [RepositoryReadiness]
-      summary: Enqueue AI readiness analysis for one repository
-      description: >
-        User-triggered "Run now" path. Requires workspace editor/admin access and an active GitHub App
-        connection. Prefer `repoId`; `providerSlug` is accepted for compatibility only when it resolves
-        to a repository in the workspace.
-      operationId: postReadinessAnalyze
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/seats:
+    get:
+      tags: [Integrations]
+      summary: List latest AI-tool seats
+      operationId: getWorkspaceAiToolSeats
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/ReadinessAnalyzeBodyDto"
-            examples:
-              byRepoId:
-                value:
-                  repoId: "11111111-1111-4111-8111-111111111111"
-              byProviderSlug:
-                value:
-                  providerSlug: "thinkai-llc/thinkai-platform-backend"
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [cursor]
       responses:
-        "202":
-          description: Run queued
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ReadinessAnalyzeResponseDto"
-        "400":
-          description: Invalid body, missing GitHub connection, unsupported provider, or active run conflict inputs
+        "200":
+          description: Seats
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                type: object
+                required: [seats]
+                properties:
+                  seats:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/AiToolSeatDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
-        "404":
-          description: Workspace or repository not found
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
-        "409":
-          description: A queued/running readiness analysis already exists for this repository slug
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/readiness/runs/{runId}:
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/daily-usage:
     get:
-      tags: [RepositoryReadiness]
-      summary: Get readiness analysis run status
-      operationId: getReadinessRun
+      tags: [Integrations]
+      summary: List AI-tool daily usage
+      operationId: getWorkspaceAiToolDailyUsage
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: runId
+        - name: provider
           in: path
           required: true
           schema:
             type: string
-            format: uuid
+            enum: [cursor]
+        - name: from
+          in: query
+          required: false
+          schema:
+            type: string
+            format: date
+        - name: to
+          in: query
+          required: false
+          schema:
+            type: string
+            format: date
+        - name: externalId
+          in: query
+          required: false
+          schema:
+            type: string
       responses:
         "200":
-          description: Run status
+          description: Usage rows
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ReadinessRunSummaryDto"
+                type: object
+                required: [rows]
+                properties:
+                  rows:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/AiToolDailyUsageRowDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
-        "404":
-          description: Workspace or run not found
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/readiness/repos/{repoId}:
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/spend:
     get:
-      tags: [RepositoryReadiness]
-      summary: Single repo readiness
-      description: >
-        Returns one stored repository scorecard with all eight dimensions and nested issues.
-        Unknown `repoId` or a repo that belongs to another workspace returns `404` (no cross-tenant leakage).
-      operationId: getReadinessRepo
+      tags: [Integrations]
+      summary: List AI-tool spend
+      operationId: getWorkspaceAiToolSpend
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - $ref: "#/components/parameters/RepoId"
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [cursor]
+        - name: cycleStartMs
+          in: query
+          required: false
+          schema:
+            type: integer
+            format: int64
       responses:
         "200":
-          description: Repo score
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/RepoReadinessScoreDto"
-        "400":
-          description: Malformed `repoId` (not a UUID)
+          description: Spend rows
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                type: object
+                required: [rows]
+                properties:
+                  rows:
+                    type: array
+                    items:
+                      $ref: "#/components/schemas/AiToolSpendRowDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
-        "404":
-          description: Workspace or repository not found
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/agentic-foundation/dashboard:
+  /workspaces/{workspaceId}/integrations/ai-tool/{provider}/status:
     get:
-      tags: [AgenticFoundation]
-      summary: Agentic Foundation dashboard
-      description: >
-        Returns stored repository readiness scorecards plus a flattened issue queue for the
-        Agentic Foundation dashboard surfaces. This is read-only and does not run scoring on
-        the request path (issue #279). Field `generatedAt` is the server timestamp when this JSON
-        payload was assembled; it is not the same as per-repo `lastAnalyzed` on `RepoReadinessScoreDto`.
-      operationId: getAgenticFoundationDashboard
+      tags: [Integrations]
+      summary: Get last refresh status
+      operationId: getWorkspaceAiToolRefreshStatus
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - name: provider
+          in: path
+          required: true
+          schema:
+            type: string
+            enum: [cursor]
       responses:
         "200":
-          description: Dashboard scorecards and issue queue
+          description: Refresh status
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AgenticFoundationDashboardDto"
-              examples:
-                emptyWorkspace:
-                  summary: No repos analyzed yet
-                  value:
-                    workspaceId: 00000000-0000-0000-0000-000000000001
-                    generatedAt: "2026-05-12T12:00:00.000Z"
-                    summary:
-                      repoCount: 0
-                      averageOverallScore: 0
-                      issueCount: 0
-                      criticalIssueCount: 0
-                    repos: []
-                    issueQueue: []
+                type: object
+                required: [status]
+                properties:
+                  status:
+                    $ref: "#/components/schemas/AiToolRefreshStatusDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
         "404":
-          description: Workspace does not exist
+          description: No refresh status yet (or provider source missing)
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                $ref: "#/components/schemas/AiToolRefreshResponseDto"
+              example:
+                ok: false
+                error: no_source
 
-  /workspaces/{workspaceId}/agentic-foundation/agentic-readiness:
+  /integrations/github/callback:
     get:
-      tags: [AgenticFoundation]
-      summary: Agentic readiness pillar (stored dimension slice)
+      tags: [Integrations]
+      summary: GitHub App installation callback
+      operationId: getGithubInstallCallback
       description: >
-        Returns `RepoReadinessScoreDto` rows with only the `ai-agent-readiness` dimension populated
-        per repo. Same auth and persistence source as `GET .../readiness/repos` (issue #280).
-      operationId: getAgenticFoundationAgenticReadiness
+        Public callback endpoint used by GitHub App installation flow.
+        Resolves and consumes install state, persists workspace installation linkage,
+        then redirects to configured SPA origin with status markers.
       parameters:
-        - $ref: "#/components/parameters/WorkspaceId"
+        - name: state
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: installation_id
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: setup_action
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: error
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: error_description
+          in: query
+          required: false
+          schema:
+            type: string
       responses:
-        "200":
-          description: Repositories with ai-agent-readiness slice
+        "302":
+          description: Redirect to ThinkAI SPA return path with GitHub connection status
+        "501":
+          description: Workspace store not configured
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
-              examples:
-                singleRepoSlice:
-                  summary: One repo, single pillar dimension
-                  value:
-                    - repoId: 00000000-0000-0000-0000-000000000002
-                      repoName: api-gateway
-                      language: typescript
-                      overallScore: 67
-                      dimensions:
-                        - dimensionId: ai-agent-readiness
-                          score: 2
-                          maxScore: 3
-                          issues: []
-                      lastAnalyzed: "2026-05-12T12:00:00.000Z"
-                      teamId: null
-                      provider:
-                        kind: github
-                        slug: acme/api-gateway
-                        webUrl: https://github.com/acme/api-gateway
-                        defaultBranch: main
-                        externalId: null
-                        hostBaseUrl: null
-                      analysisStatus: idle
-                      activeRunId: null
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
-        "404":
-          description: Workspace does not exist
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: SPA origin configuration missing
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/agentic-foundation/repository-health:
-    get:
-      tags: [AgenticFoundation]
-      summary: Repository health pillar (repo-hygiene slice)
-      description: Returns per-repo `repo-hygiene` dimension only (issue #281).
-      operationId: getAgenticFoundationRepositoryHealth
+  /integrations/github/webhook:
+    post:
+      tags: [Integrations]
+      summary: GitHub App webhook receiver
+      operationId: postGithubWebhook
+      description: >
+        Public webhook endpoint that verifies `X-Hub-Signature-256` and updates or
+        removes workspace GitHub integration/cache state for installation events.
       parameters:
-        - $ref: "#/components/parameters/WorkspaceId"
+        - name: X-Hub-Signature-256
+          in: header
+          required: true
+          schema:
+            type: string
+        - name: X-GitHub-Event
+          in: header
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: true
       responses:
         "200":
-          description: Repositories with repo-hygiene slice
+          description: Webhook accepted
+        "400":
+          description: Invalid payload
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
-          $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
-        "404":
-          description: Workspace does not exist
+          description: Invalid webhook signature
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "501":
+          description: Workspace store not configured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: Missing GitHub webhook secret or GitHub App configuration
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/agentic-foundation/codebase-quality:
+  /workspaces/{workspaceId}/ai-readiness:
     get:
-      tags: [AgenticFoundation]
-      summary: Codebase quality pillar (stack-quality slice)
-      description: Returns per-repo `stack-quality` dimension only (issue #282).
-      operationId: getAgenticFoundationCodebaseQuality
+      tags: [AIReadiness]
+      summary: Get AI readiness
+      operationId: getAiReadiness
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Repositories with stack-quality slice
+          description: State or JSON null
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/AIReadinessDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
-        "404":
-          description: Workspace does not exist
+    put:
+      tags: [AIReadiness]
+      summary: Upsert AI readiness
+      operationId: putAiReadiness
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AIReadinessDto"
+      responses:
+        "204":
+          description: Saved
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/ai-readiness/maturity:
+    post:
+      tags: [AIReadiness]
+      summary: Compute maturity level
+      operationId: postAiReadinessMaturity
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AIReadinessDto"
+      responses:
+        "200":
+          description: Derived level
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                $ref: "#/components/schemas/AiMaturityResultDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
 
-  /workspaces/{workspaceId}/agentic-foundation/test-qa:
+  /workspaces/{workspaceId}/tech-stack:
     get:
-      tags: [AgenticFoundation]
-      summary: Test and QA pillar (tests-qa slice)
-      description: Returns per-repo `tests-qa` dimension only (issue #283).
-      operationId: getAgenticFoundationTestQa
+      tags: [TechStack]
+      summary: Get tech stack
+      operationId: getTechStack
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Repositories with tests-qa slice
+          description: >
+            Saved tech stack DTO, or JSON `null` when the workspace exists but no stack
+            has been saved yet. Clients should merge `null` with their empty defaults.
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                nullable: true
+                allOf:
+                  - $ref: "#/components/schemas/TechStackDto"
+        "400":
+          description: Malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -1613,24 +1926,27 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
-
-  /workspaces/{workspaceId}/agentic-foundation/observability:
-    get:
-      tags: [AgenticFoundation]
-      summary: Observability pillar (observability slice)
-      description: Returns per-repo `observability` dimension only (issue #284).
-      operationId: getAgenticFoundationObservability
+    put:
+      tags: [TechStack]
+      summary: Upsert tech stack
+      operationId: putTechStack
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/TechStackDto"
       responses:
-        "200":
-          description: Repositories with observability slice
+        "204":
+          description: Saved
+        "400":
+          description: Body fails validation (unknown keys, bounds, missing required fields)
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -1642,103 +1958,99 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/agentic-foundation/api-contract:
+  /workspaces/{workspaceId}/nda:
     get:
-      tags: [AgenticFoundation]
-      summary: API contract pillar (api-contracts slice)
-      description: Returns per-repo `api-contracts` dimension only (issue #285).
-      operationId: getAgenticFoundationApiContract
+      tags: [NDA]
+      summary: Get NDA completion state
+      operationId: getNda
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Repositories with api-contracts slice
+          description: Completion or JSON null
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/NdaCompletionDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
-        "404":
-          description: Workspace does not exist
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/agentic-foundation/platform-governance:
+  /workspaces/{workspaceId}/nda/template:
     get:
-      tags: [AgenticFoundation]
-      summary: Platform governance pillar (platform-governance slice)
-      description: Returns per-repo `platform-governance` dimension only (issue #286).
-      operationId: getAgenticFoundationPlatformGovernance
+      tags: [NDA]
+      summary: NDA template for display
+      operationId: getNdaTemplate
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Repositories with platform-governance slice
+          description: Template
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/NdaTemplateDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
-        "404":
-          description: Workspace does not exist
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/agentic-foundation/delivery-governance:
-    get:
-      tags: [AgenticFoundation]
-      summary: Delivery governance pillar (delivery slice)
-      description: Returns per-repo `delivery` dimension only (issue #287).
-      operationId: getAgenticFoundationDeliveryGovernance
+  /workspaces/{workspaceId}/nda/sign:
+    post:
+      tags: [NDA]
+      summary: Electronic NDA signature
+      operationId: postNdaSign
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/NdaSignatureDto"
       responses:
         "200":
-          description: Repositories with delivery slice
+          description: Completion record
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/NdaCompletionDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
-        "403":
-          $ref: "#/components/responses/Forbidden"
-        "404":
-          description: Workspace does not exist
+
+  /workspaces/{workspaceId}/nda/external:
+    post:
+      tags: [NDA]
+      summary: External NDA path (after Supabase upload)
+      description: >
+        Preferred body uses `storagePath` after client upload to the `nda-documents` bucket (§14).
+        Multipart variant may be supported by the server as an alternative.
+      operationId: postNdaExternal
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/NdaExternalBodyDto"
+      responses:
+        "200":
+          description: Completion record
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                $ref: "#/components/schemas/NdaCompletionDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
 
-  /workspaces/{workspaceId}/agentic-foundation/ai-resolution-hub:
+  /workspaces/{workspaceId}/readiness/repos:
     get:
-      tags: [AgenticFoundation]
-      summary: AI resolution hub (full readiness scorecards)
-      description: >
-        Returns the same payload as `GET .../readiness/repos` (all dimensions per repo) for
-        cross-pillar hub views (issue #288).
-      operationId: getAgenticFoundationAiResolutionHub
+      tags: [RepositoryReadiness]
+      summary: List repo readiness scores
+      operationId: listReadinessRepos
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Full repository readiness scorecards
+          description: Repositories analyzed
           content:
             application/json:
               schema:
@@ -1756,94 +2068,111 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/readiness/dimensions:
-    get:
+  /workspaces/{workspaceId}/readiness/analyze:
+    post:
       tags: [RepositoryReadiness]
-      summary: Readiness dimensions catalog
+      summary: Enqueue AI readiness analysis for one repository
       description: >
-        Returns static rubric metadata (id, name, description, maxScore) aligned with the readiness
-        scanner dimensions. Does not run scoring on the request path.
-      operationId: listReadinessDimensions
+        User-triggered "Run now" path. Requires workspace editor/admin access and an active GitHub App
+        connection. Prefer `repoId`; `providerSlug` is accepted for compatibility only when it resolves
+        to a repository in the workspace.
+      operationId: postReadinessAnalyze
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ReadinessAnalyzeBodyDto"
+            examples:
+              byRepoId:
+                value:
+                  repoId: "11111111-1111-4111-8111-111111111111"
+              byProviderSlug:
+                value:
+                  providerSlug: "thinkai-llc/thinkai-platform-backend"
       responses:
-        "200":
-          description: Dimensions
+        "202":
+          description: Run queued
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/ReadinessDimensionDto"
+                $ref: "#/components/schemas/ReadinessAnalyzeResponseDto"
+        "400":
+          description: Invalid body, missing GitHub connection, unsupported provider, or active run conflict inputs
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
         "404":
-          description: Workspace does not exist
+          description: Workspace or repository not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: A queued/running readiness analysis already exists for this repository slug
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/readiness/fixes:
+  /workspaces/{workspaceId}/readiness/runs/{runId}:
     get:
       tags: [RepositoryReadiness]
-      summary: List fix requests
-      description: >
-        Returns persisted fix-queue rows for the workspace (newest first). Empty array when none exist.
-      operationId: listReadinessFixes
+      summary: Get readiness analysis run status
+      operationId: getReadinessRun
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - name: runId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
       responses:
         "200":
-          description: Fix queue
+          description: Run status
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/FixRequestDto"
+                $ref: "#/components/schemas/ReadinessRunSummaryDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
         "404":
-          description: Workspace does not exist
+          description: Workspace or run not found
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
-    post:
+
+  /workspaces/{workspaceId}/readiness/repos/{repoId}:
+    get:
       tags: [RepositoryReadiness]
-      summary: Enqueue fix for an issue
+      summary: Single repo readiness
       description: >
-        Creates a fix request with `status: queued` when `issueId` belongs to `repoId` in this workspace.
-        Requires workspace editor or admin. Re-posting the same `issueId` and `repoId` returns the
-        existing row (idempotent).
-      operationId: postReadinessFix
+        Returns one stored repository scorecard with all eight dimensions and nested issues.
+        Unknown `repoId` or a repo that belongs to another workspace returns `404` (no cross-tenant leakage).
+      operationId: getReadinessRepo
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/CreateFixRequestBodyDto"
-            examples:
-              enqueue:
-                value:
-                  issueId: "22222222-2222-2222-2222-222222222222"
-                  repoId: "11111111-1111-4111-8111-111111111111"
+        - $ref: "#/components/parameters/RepoId"
       responses:
         "200":
-          description: Fix request created or existing row returned
+          description: Repo score
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/FixRequestDto"
+                $ref: "#/components/schemas/RepoReadinessScoreDto"
         "400":
-          description: Invalid body or malformed `repoId` (not a UUID)
+          description: Malformed `repoId` (not a UUID)
           content:
             application/json:
               schema:
@@ -1853,239 +2182,182 @@ paths:
         "403":
           $ref: "#/components/responses/Forbidden"
         "404":
-          description: Workspace not found, or issue/repo pair not in workspace
+          description: Workspace or repository not found
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/readiness/fixes/{fixId}/retry:
-    post:
-      tags: [RepositoryReadiness]
-      summary: Retry a failed fix request
+  /workspaces/{workspaceId}/agentic-foundation/dashboard:
+    get:
+      tags: [AgenticFoundation]
+      summary: Agentic Foundation dashboard
       description: >
-        Re-queues a fix with `status: failed` when `errorCode` is one of
-        `FixRetryableErrorCode` (`PROVIDER_TIMEOUT`, `RATE_LIMITED`, `TRANSIENT_NETWORK`,
-        `RUNNER_INTERRUPTED`). Idempotent for the same failed row. Requires workspace editor or admin.
-      operationId: postReadinessFixRetry
+        Returns stored repository readiness scorecards plus a flattened issue queue for the
+        Agentic Foundation dashboard surfaces. This is read-only and does not run scoring on
+        the request path (issue #279). Field `generatedAt` is the server timestamp when this JSON
+        payload was assembled; it is not the same as per-repo `lastAnalyzed` on `RepoReadinessScoreDto`.
+      operationId: getAgenticFoundationDashboard
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - $ref: "#/components/parameters/FixId"
       responses:
         "200":
-          description: Fix re-queued
+          description: Dashboard scorecards and issue queue
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/FixRequestDto"
+                $ref: "#/components/schemas/AgenticFoundationDashboardDto"
+              examples:
+                emptyWorkspace:
+                  summary: No repos analyzed yet
+                  value:
+                    workspaceId: 00000000-0000-0000-0000-000000000001
+                    generatedAt: "2026-05-12T12:00:00.000Z"
+                    summary:
+                      repoCount: 0
+                      averageOverallScore: 0
+                      issueCount: 0
+                      criticalIssueCount: 0
+                    repos: []
+                    issueQueue: []
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
           $ref: "#/components/responses/Forbidden"
         "404":
-          description: Fix not found in workspace
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
-        "409":
-          description: Fix is not in a retryable state
+          description: Workspace does not exist
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/squad:
+  /workspaces/{workspaceId}/agentic-foundation/agentic-readiness:
     get:
-      tags: [SquadProjects]
-      summary: Get squad configuration
-      operationId: getSquad
-      parameters:
-        - $ref: "#/components/parameters/WorkspaceId"
-      responses:
-        "200":
-          description: Squad
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/SquadDto"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-    put:
-      tags: [SquadProjects]
-      summary: Upsert squad
-      operationId: putSquad
-      parameters:
-        - $ref: "#/components/parameters/WorkspaceId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/SquadDto"
-      responses:
-        "204":
-          description: Saved
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-
-  /workspaces/{workspaceId}/projects:
-    get:
-      tags: [SquadProjects]
-      summary: List projects
-      operationId: listProjects
+      tags: [AgenticFoundation]
+      summary: Agentic readiness pillar (stored dimension slice)
+      description: >
+        Returns `RepoReadinessScoreDto` rows with only the `ai-agent-readiness` dimension populated
+        per repo. Same auth and persistence source as `GET .../readiness/repos` (issue #280).
+      operationId: getAgenticFoundationAgenticReadiness
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Projects
+          description: Repositories with ai-agent-readiness slice
           content:
             application/json:
               schema:
                 type: array
                 items:
-                  $ref: "#/components/schemas/ProjectDto"
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+              examples:
+                singleRepoSlice:
+                  summary: One repo, single pillar dimension
+                  value:
+                    - repoId: 00000000-0000-0000-0000-000000000002
+                      repoName: api-gateway
+                      language: typescript
+                      overallScore: 67
+                      dimensions:
+                        - dimensionId: ai-agent-readiness
+                          score: 2
+                          maxScore: 3
+                          issues: []
+                      lastAnalyzed: "2026-05-12T12:00:00.000Z"
+                      teamId: null
+                      provider:
+                        kind: github
+                        slug: acme/api-gateway
+                        webUrl: https://github.com/acme/api-gateway
+                        defaultBranch: main
+                        externalId: null
+                        hostBaseUrl: null
+                      analysisStatus: idle
+                      activeRunId: null
         "401":
           $ref: "#/components/responses/Unauthorized"
-    post:
-      tags: [SquadProjects]
-      summary: Create project
-      operationId: createProject
-      parameters:
-        - $ref: "#/components/parameters/WorkspaceId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/ProjectDto"
-      responses:
-        "200":
-          description: Created project
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ProjectDto"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
+                $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/projects/{projectId}:
-    patch:
-      tags: [SquadProjects]
-      summary: Update project
-      operationId: patchProject
+  /workspaces/{workspaceId}/agentic-foundation/repository-health:
+    get:
+      tags: [AgenticFoundation]
+      summary: Repository health pillar (repo-hygiene slice)
+      description: Returns per-repo `repo-hygiene` dimension only (issue #281).
+      operationId: getAgenticFoundationRepositoryHealth
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - $ref: "#/components/parameters/ProjectId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/ProjectPatchDto"
       responses:
         "200":
-          description: Updated project
+          description: Repositories with repo-hygiene slice
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ProjectDto"
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/notifications:
+  /workspaces/{workspaceId}/agentic-foundation/codebase-quality:
     get:
-      tags: [Notifications]
-      summary: Paginated notifications
-      operationId: listNotifications
+      tags: [AgenticFoundation]
+      summary: Codebase quality pillar (stack-quality slice)
+      description: Returns per-repo `stack-quality` dimension only (issue #282).
+      operationId: getAgenticFoundationCodebaseQuality
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - name: limit
-          in: query
-          schema: { type: integer, minimum: 1 }
-        - name: offset
-          in: query
-          schema: { type: integer, minimum: 0 }
       responses:
         "200":
-          description: Page of notifications
+          description: Repositories with stack-quality slice
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/NotificationListDto"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-
-  /workspaces/{workspaceId}/notifications/{id}/read:
-    post:
-      tags: [Notifications]
-      summary: Mark notification read
-      operationId: postNotificationRead
-      parameters:
-        - $ref: "#/components/parameters/WorkspaceId"
-        - $ref: "#/components/parameters/NotificationId"
-      responses:
-        "204":
-          description: Updated
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-
-  /workspaces/{workspaceId}/notifications/read-all:
-    post:
-      tags: [Notifications]
-      summary: Mark all notifications read
-      operationId: postNotificationsReadAll
-      parameters:
-        - $ref: "#/components/parameters/WorkspaceId"
-      responses:
-        "204":
-          description: Updated
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
-
-  /workspaces/{workspaceId}/ai-strategy/recommend:
-    post:
-      tags: [AIStrategy]
-      summary: Generate AI strategy recommendations
-      operationId: postAiStrategyRecommend
-      parameters:
-        - $ref: "#/components/parameters/WorkspaceId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/AiStrategyRecommendBodyDto"
-      responses:
-        "200":
-          description: Plan
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AiStrategyPlanDto"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
+                $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/journey/progress:
+  /workspaces/{workspaceId}/agentic-foundation/test-qa:
     get:
-      tags: [Journey]
-      summary: Journey step completion
-      operationId: getJourneyProgress
+      tags: [AgenticFoundation]
+      summary: Test and QA pillar (tests-qa slice)
+      description: Returns per-repo `tests-qa` dimension only (issue #283).
+      operationId: getAgenticFoundationTestQa
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Progress (empty completedSteps when no row exists yet; updatedAt is synthetic in that case)
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/JourneyProgressDto"
-        "400":
-          description: Malformed workspaceId
+          description: Repositories with tests-qa slice
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2096,34 +2368,24 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
-    put:
-      tags: [Journey]
-      summary: Replace completed steps
-      operationId: putJourneyProgress
-      description: >
-        Idempotent replace-all of completed route strings. Returns the persisted
-        JourneyProgressDto including updatedAt.
+
+  /workspaces/{workspaceId}/agentic-foundation/observability:
+    get:
+      tags: [AgenticFoundation]
+      summary: Observability pillar (observability slice)
+      description: Returns per-repo `observability` dimension only (issue #284).
+      operationId: getAgenticFoundationObservability
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/JourneyProgressUpdateDto"
       responses:
         "200":
-          description: Saved progress
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/JourneyProgressDto"
-        "400":
-          description: Body fails validation (non-array, invalid entries, too many steps)
+          description: Repositories with observability slice
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2135,55 +2397,186 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
-  /me/preferences:
+  /workspaces/{workspaceId}/agentic-foundation/api-contract:
     get:
-      tags: [Preferences]
-      summary: Get preferences for current user
-      operationId: getMyPreferences
+      tags: [AgenticFoundation]
+      summary: API contract pillar (api-contracts slice)
+      description: Returns per-repo `api-contracts` dimension only (issue #285).
+      operationId: getAgenticFoundationApiContract
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Preferences
+          description: Repositories with api-contracts slice
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/PreferencesDto"
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
-    put:
-      tags: [Preferences]
-      summary: Upsert preferences
-      operationId: putMyPreferences
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/PreferencesDto"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/agentic-foundation/platform-governance:
+    get:
+      tags: [AgenticFoundation]
+      summary: Platform governance pillar (platform-governance slice)
+      description: Returns per-repo `platform-governance` dimension only (issue #286).
+      operationId: getAgenticFoundationPlatformGovernance
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Saved preferences
+          description: Repositories with platform-governance slice
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/PreferencesDto"
-        "400":
-          description: Validation failed
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/PreferencesValidationErrorDto"
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/agentic-foundation/delivery-governance:
+    get:
+      tags: [AgenticFoundation]
+      summary: Delivery governance pillar (delivery slice)
+      description: Returns per-repo `delivery` dimension only (issue #287).
+      operationId: getAgenticFoundationDeliveryGovernance
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Repositories with delivery slice
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/org-chart/import:
+  /workspaces/{workspaceId}/agentic-foundation/ai-resolution-hub:
+    get:
+      tags: [AgenticFoundation]
+      summary: AI resolution hub (full readiness scorecards)
+      description: >
+        Returns the same payload as `GET .../readiness/repos` (all dimensions per repo) for
+        cross-pillar hub views (issue #288).
+      operationId: getAgenticFoundationAiResolutionHub
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Full repository readiness scorecards
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/readiness/dimensions:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Readiness dimensions catalog
+      description: >
+        Returns static rubric metadata (id, name, description, maxScore) aligned with the readiness
+        scanner dimensions. Does not run scoring on the request path.
+      operationId: listReadinessDimensions
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Dimensions
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/ReadinessDimensionDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/readiness/fixes:
+    get:
+      tags: [RepositoryReadiness]
+      summary: List fix requests
+      description: >
+        Returns persisted fix-queue rows for the workspace (newest first). Empty array when none exist.
+      operationId: listReadinessFixes
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Fix queue
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/FixRequestDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
     post:
-      tags: [OrgChartImport]
-      summary: Import org chart from Supabase storage path
+      tags: [RepositoryReadiness]
+      summary: Enqueue fix for an issue
       description: >
-        Parse-only. Downloads the CSV at `storagePath` from the `org-charts` bucket and returns
-        `persons` and `errors`. Does not persist to `spa_org_chart` or `org_chart`. The SPA
-        derives teams client-side and saves the org structure via `POST /workspaces/{workspaceId}/org-chart`.
-      operationId: postOrgChartImport
+        Creates a fix request with `status: queued` when `issueId` belongs to `repoId` in this workspace.
+        Requires workspace editor or admin. Re-posting the same `issueId` and `repoId` returns the
+        existing row (idempotent).
+      operationId: postReadinessFix
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       requestBody:
@@ -2191,16 +2584,21 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/OrgChartImportBodyDto"
+              $ref: "#/components/schemas/CreateFixRequestBodyDto"
+            examples:
+              enqueue:
+                value:
+                  issueId: "22222222-2222-2222-2222-222222222222"
+                  repoId: "11111111-1111-4111-8111-111111111111"
       responses:
         "200":
-          description: Parsed persons from uploaded CSV (not persisted server-side)
+          description: Fix request created or existing row returned
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/OrgChartImportResultDto"
+                $ref: "#/components/schemas/FixRequestDto"
         "400":
-          description: Invalid body or storage path
+          description: Invalid body or malformed `repoId` (not a UUID)
           content:
             application/json:
               schema:
@@ -2210,57 +2608,417 @@ paths:
         "403":
           $ref: "#/components/responses/Forbidden"
         "404":
-          description: Storage object not found
+          description: Workspace not found, or issue/repo pair not in workspace
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
-        "502":
-          description: Failed to download file from storage
+
+  /workspaces/{workspaceId}/readiness/fixes/{fixId}/retry:
+    post:
+      tags: [RepositoryReadiness]
+      summary: Retry a failed fix request
+      description: >
+        Re-queues a fix with `status: failed` when `errorCode` is one of
+        `FixRetryableErrorCode` (`PROVIDER_TIMEOUT`, `RATE_LIMITED`, `TRANSIENT_NETWORK`,
+        `RUNNER_INTERRUPTED`). Idempotent for the same failed row. Requires workspace editor or admin.
+      operationId: postReadinessFixRetry
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/FixId"
+      responses:
+        "200":
+          description: Fix re-queued
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FixRequestDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Fix not found in workspace
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
-        "503":
-          description: Storage import not configured or service unavailable
+        "409":
+          description: Fix is not in a retryable state
           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
-    RepoId:
-      name: repoId
-      in: path
-      required: true
-      schema:
-        type: string
-        format: uuid
-    ProjectId:
-      name: projectId
-      in: path
-      required: true
-      schema:
-        type: string
-    NotificationId:
-      name: id
-      in: path
-      required: true
-      schema:
+  /workspaces/{workspaceId}/squad:
+    get:
+      tags: [SquadProjects]
+      summary: Get squad configuration
+      operationId: getSquad
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Squad
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SquadDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    put:
+      tags: [SquadProjects]
+      summary: Upsert squad
+      operationId: putSquad
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SquadDto"
+      responses:
+        "204":
+          description: Saved
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/projects:
+    get:
+      tags: [SquadProjects]
+      summary: List projects
+      operationId: listProjects
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Projects
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/ProjectDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    post:
+      tags: [SquadProjects]
+      summary: Create project
+      operationId: createProject
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ProjectDto"
+      responses:
+        "200":
+          description: Created project
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProjectDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/projects/{projectId}:
+    patch:
+      tags: [SquadProjects]
+      summary: Update project
+      operationId: patchProject
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/ProjectId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ProjectPatchDto"
+      responses:
+        "200":
+          description: Updated project
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProjectDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/notifications:
+    get:
+      tags: [Notifications]
+      summary: Paginated notifications
+      operationId: listNotifications
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: limit
+          in: query
+          schema: { type: integer, minimum: 1 }
+        - name: offset
+          in: query
+          schema: { type: integer, minimum: 0 }
+      responses:
+        "200":
+          description: Page of notifications
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NotificationListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/notifications/{id}/read:
+    post:
+      tags: [Notifications]
+      summary: Mark notification read
+      operationId: postNotificationRead
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/NotificationId"
+      responses:
+        "204":
+          description: Updated
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/notifications/read-all:
+    post:
+      tags: [Notifications]
+      summary: Mark all notifications read
+      operationId: postNotificationsReadAll
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "204":
+          description: Updated
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/ai-strategy/recommend:
+    post:
+      tags: [AIStrategy]
+      summary: Generate AI strategy recommendations
+      operationId: postAiStrategyRecommend
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AiStrategyRecommendBodyDto"
+      responses:
+        "200":
+          description: Plan
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiStrategyPlanDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/journey/progress:
+    get:
+      tags: [Journey]
+      summary: Journey step completion
+      operationId: getJourneyProgress
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Progress (empty completedSteps when no row exists yet; updatedAt is synthetic in that case)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JourneyProgressDto"
+        "400":
+          description: Malformed workspaceId
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    put:
+      tags: [Journey]
+      summary: Replace completed steps
+      operationId: putJourneyProgress
+      description: >
+        Idempotent replace-all of completed route strings. Returns the persisted
+        JourneyProgressDto including updatedAt.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/JourneyProgressUpdateDto"
+      responses:
+        "200":
+          description: Saved progress
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JourneyProgressDto"
+        "400":
+          description: Body fails validation (non-array, invalid entries, too many steps)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /me/preferences:
+    get:
+      tags: [Preferences]
+      summary: Get preferences for current user
+      operationId: getMyPreferences
+      responses:
+        "200":
+          description: Preferences
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PreferencesDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    put:
+      tags: [Preferences]
+      summary: Upsert preferences
+      operationId: putMyPreferences
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PreferencesDto"
+      responses:
+        "200":
+          description: Saved preferences
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PreferencesDto"
+        "400":
+          description: Validation failed
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PreferencesValidationErrorDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/org-chart/import:
+    post:
+      tags: [OrgChartImport]
+      summary: Import org chart from Supabase storage path
+      description: >
+        Parse-only. Downloads the CSV at `storagePath` from the `org-charts` bucket and returns
+        `persons` and `errors`. Does not persist to `spa_org_chart` or `org_chart`. The SPA
+        derives teams client-side and saves the org structure via `POST /workspaces/{workspaceId}/org-chart`.
+        Required columns: employee_id, name, email, title, department, team, manager_id, location.
+        Optional: github_username (GitHub login for productivity ingest). Saving the SPA snapshot
+        also materializes a scoring `org_chart` tree for team/person metrics when import members are present.
+      operationId: postOrgChartImport
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OrgChartImportBodyDto"
+      responses:
+        "200":
+          description: Parsed persons from uploaded CSV (not persisted server-side)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OrgChartImportResultDto"
+        "400":
+          description: Invalid body or storage path
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Storage object not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "502":
+          description: Failed to download file from storage
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: Storage import not configured or service unavailable
+          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
+    RepoId:
+      name: repoId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+    ProjectId:
+      name: projectId
+      in: path
+      required: true
+      schema:
+        type: string
+    NotificationId:
+      name: id
+      in: path
+      required: true
+      schema:
         type: string
     FixId:
       name: fixId
@@ -2269,390 +3027,1305 @@ components:
       schema:
         type: string
         format: uuid
+    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
+
+  responses:
+    Unauthorized:
+      description: Missing or invalid bearer token
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorMessageDto"
+    Forbidden:
+      description: Authenticated but not allowed
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorMessageDto"
+
+  schemas:
+    ErrorMessageDto:
+      type: object
+      required: [error]
+      properties:
+        error:
+          type: string
+
+    TeamMemberDto:
+      type: object
+      required: [id, name, email, role]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        email:
+          type: string
+        role:
+          type: string
+          enum: [admin, editor, viewer]
+
+    TeamMemberListDto:
+      type: object
+      required: [members]
+      properties:
+        members:
+          type: array
+          items:
+            $ref: "#/components/schemas/TeamMemberDto"
+
+    InviteTeamMemberBodyDto:
+      type: object
+      required: [email, role]
+      properties:
+        email:
+          type: string
+        role:
+          type: string
+          enum: [admin, editor, viewer]
+
+    UpdateTeamMemberRoleBodyDto:
+      type: object
+      required: [role]
+      properties:
+        role:
+          type: string
+          enum: [admin, editor, viewer]
+
+    OrgChartNodeDto:
+      type: object
+      additionalProperties: false
+      required: [id, name, type]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        type:
+          type: string
+          enum: [org, department, team, person]
+        external_ids:
+          type: object
+          additionalProperties: { type: string }
+        children:
+          type: array
+          items:
+            $ref: "#/components/schemas/OrgChartNodeDto"
+
+    OrgChartTreeNodeDto:
+      type: object
+      required: [id]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        type:
+          type: string
+        person_id:
+          type: string
+        team:
+          type: string
+        role:
+          type: string
+        level:
+          type: string
+        external_ids:
+          type: object
+          additionalProperties: { type: string }
+        children:
+          type: array
+          items:
+            $ref: "#/components/schemas/OrgChartTreeNodeDto"
+
+    ScoringOrgChartDto:
+      type: object
+      additionalProperties: false
+      required: [root]
+      properties:
+        root:
+          $ref: "#/components/schemas/OrgChartTreeNodeDto"
+
+    OrgChartDto:
+      type: object
+      additionalProperties: false
+      required: [root]
+      properties:
+        root:
+          $ref: "#/components/schemas/OrgChartNodeDto"
+
+    OrgChartPersonDto:
+      type: object
+      additionalProperties: false
+      required: [employeeId, name, email, title, department, team, managerId, location]
+      properties:
+        employeeId:
+          type: string
+          description: Stable HR identifier; referenced by manager_id for reporting lines.
+        name:
+          type: string
+        email:
+          type: string
+          description: Work email; used as canonical person_id in productivity ingest when present.
+        title:
+          type: string
+          description: Job title; used for contributor rows and leadership (enabler) hints.
+        department:
+          type: string
+          description: Department filter on Productivity insights.
+        team:
+          type: string
+          description: Engineering team name for Aggregated Teams and team drill-downs.
+        managerId:
+          type: string
+          description: employee_id of the person's manager; leave empty for top-level leaders.
+        location:
+          type: string
+        githubUsername:
+          type: string
+          description: GitHub login (no @) to map merged PRs and reviews to this person in productivity ingest.
+
+    OrgChartImportResultDto:
+      type: object
+      additionalProperties: false
+      required: [persons, errors]
+      properties:
+        persons:
+          type: array
+          items:
+            $ref: "#/components/schemas/OrgChartPersonDto"
+        errors:
+          type: array
+          items:
+            type: string
+
+    OrgChartSaveResultDto:
+      type: object
+      additionalProperties: false
+      required: [ok, tenantId]
+      properties:
+        ok:
+          type: boolean
+        tenantId:
+          type: string
+          format: uuid
+
+    TenantSourceEntryDto:
+      type: object
+      required: [type]
+      properties:
+        type:
+          type: string
+      additionalProperties: true
+
+    CursorSourceDto:
+      type: object
+      description: >
+        Cursor (AI Tools) source entry for `PUT /workspaces/{workspaceId}/sources`
+        and `POST /workspaces/{workspaceId}/sources/test`. The `token` field
+        carries a literal Cursor API key on writes; reads from
+        `GET /workspaces/{workspaceId}/config` redact it to `***`.
+        Runtime calls use the Cursor Admin API at `https://api.cursor.com` (HTTP Basic); do not rely on `baseUrl`.
+      required: [type, token]
+      additionalProperties: false
+      properties:
+        type:
+          type: string
+          enum: [cursor]
+        token:
+          type: string
+          minLength: 1
+          maxLength: 256
+          description: Cursor API key (literal). Whitespace and `env:` prefix are rejected.
+        baseUrl:
+          type: string
+          deprecated: true
+          description: >
+            Deprecated. Historically suggested an API base URL; the server ignores this field
+            and always uses the Cursor Admin API host. Kept so older clients can submit payloads unchanged.
+          default: "https://api.cursor.com"
+
+    WorkspaceConfigDto:
+      type: object
+      required: [sources]
+      properties:
+        sources:
+          type: array
+          items:
+            $ref: "#/components/schemas/TenantSourceEntryDto"
+        orgChart:
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/ScoringOrgChartDto"
+        region:
+          type: string
+          nullable: true
+          enum: [us, eu, me]
+
+    TestConnectionResponseDto:
+      type: object
+      required: [success]
+      properties:
+        success:
+          type: boolean
+        error:
+          type: string
+
+    AiToolSeatDto:
+      type: object
+      required: [externalId, email, isRemoved]
+      properties:
+        externalId:
+          type: string
+        email:
+          type: string
+        displayName:
+          type: string
+          nullable: true
+        role:
+          type: string
+          nullable: true
+        isRemoved:
+          type: boolean
+        payload:
+          type: object
+          additionalProperties: true
 
-  responses:
-    Unauthorized:
-      description: Missing or invalid bearer token
-      content:
-        application/json:
-          schema:
-            $ref: "#/components/schemas/ErrorMessageDto"
-    Forbidden:
-      description: Authenticated but not allowed
-      content:
-        application/json:
-          schema:
-            $ref: "#/components/schemas/ErrorMessageDto"
+    AiToolDailyUsageRowDto:
+      type: object
+      required: [day, externalId, isActive]
+      properties:
+        day:
+          type: string
+          format: date
+        externalId:
+          type: string
+        email:
+          type: string
+          nullable: true
+        isActive:
+          type: boolean
+        mostUsedModel:
+          type: string
+          nullable: true
+        payload:
+          type: object
+          additionalProperties: true
+
+    AiToolSpendRowDto:
+      type: object
+      required: [billingCycleStartMs, externalId, spendCents]
+      properties:
+        billingCycleStartMs:
+          type: integer
+          format: int64
+        externalId:
+          type: string
+        email:
+          type: string
+          nullable: true
+        spendCents:
+          type: integer
+          format: int64
+        payload:
+          type: object
+          additionalProperties: true
+
+    AiToolRefreshStatusDto:
+      type: object
+      required: [lastAttemptAt, counts]
+      properties:
+        lastAttemptAt:
+          type: string
+          format: date-time
+        lastSuccessAt:
+          type: string
+          format: date-time
+          nullable: true
+        lastErrorKind:
+          type: string
+          nullable: true
+        lastErrorMessage:
+          type: string
+          nullable: true
+        durationMs:
+          type: integer
+          format: int64
+          nullable: true
+        counts:
+          type: object
+          additionalProperties: true
+
+    AiToolRefreshResponseDto:
+      type: object
+      required: [ok]
+      properties:
+        ok:
+          type: boolean
+        error:
+          type: string
+          nullable: true
+
+    DashboardProductivityMetricsDto:
+      type: object
+      description: Nested metric groups; see TypeScript `DashboardProductivityMetricsDto` in @thinkai/tai-api-contract.
+      additionalProperties: true
+
+    DashboardProductivityDto:
+      type: object
+      required: [workspaceId, windowStart, windowEnd, scope, metrics]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+          description: Response generation time (RFC 3339).
+        windowStart:
+          type: string
+          format: date-time
+        windowEnd:
+          type: string
+          format: date-time
+        scope:
+          type: string
+          enum: [org, team, person]
+        metrics:
+          $ref: "#/components/schemas/DashboardProductivityMetricsDto"
+        meta:
+          type: object
+          additionalProperties: true
+
+    DashboardProductivityHistoryDto:
+      type: object
+      required: [workspaceId, bucket, buckets]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        bucket:
+          type: string
+          enum: [day, week, month]
+        buckets:
+          type: array
+          items:
+            type: object
+            required: [bucketStart, bucketEnd, metrics]
+            properties:
+              bucketStart:
+                type: string
+                format: date-time
+              bucketEnd:
+                type: string
+                format: date-time
+              metrics:
+                $ref: "#/components/schemas/DashboardProductivityMetricsDto"
+
+    ProductivityInsightsAggregatedTeamsScopeDto:
+      type: object
+      additionalProperties: false
+      required: [department, team]
+      properties:
+        department:
+          type: string
+          description: >
+            Applied department filter from the Measure UI. Backend scopes via CSV import
+            (`thinkai_org_structure`) or SPA `department` nodes; unknown departments yield
+            empty scoped results rather than org-wide rollups.
+        team:
+          type: string
+          description: Applied team name filter from the Measure UI.
+
+    ProductivityInsightsAggregatedTeamWeekDto:
+      type: object
+      additionalProperties: false
+      required: [bucketStart, bucketEnd, mergedPrCount, failRatePercent]
+      properties:
+        bucketStart:
+          type: string
+          format: date-time
+        bucketEnd:
+          type: string
+          format: date-time
+        weekLabel:
+          type: string
+          description: Short label for the week column (MM/DD), aligned with Measure charts.
+        mergedPrCount:
+          type: number
+        failRatePercent:
+          type: number
+
+    ProductivityInsightsAggregatedTeamRowDto:
+      type: object
+      additionalProperties: false
+      required: [teamId, teamName, headcount, weeks]
+      properties:
+        teamId:
+          type: string
+        teamName:
+          type: string
+        headcount:
+          type: integer
+          minimum: 0
+        managerLabel:
+          type: string
+        weeks:
+          type: array
+          items:
+            $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamWeekDto"
+
+    ProductivityInsightsAggregatedTeamsDto:
+      type: object
+      additionalProperties: false
+      required: [workspaceId, range, scope, generatedAt, teams]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        range:
+          type: string
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        generatedAt:
+          type: string
+          format: date-time
+        teams:
+          type: array
+          items:
+            $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamRowDto"
+
+    ProductivityInsightsMergedPrTrendWeekDto:
+      type: object
+      additionalProperties: false
+      required: [bucketStart, bucketEnd, mergedPrCount]
+      properties:
+        bucketStart:
+          type: string
+          format: date-time
+        bucketEnd:
+          type: string
+          format: date-time
+        weekLabel:
+          type: string
+          description: Short label for the week column (MM/DD), aligned with Measure charts.
+        mergedPrCount:
+          type: number
+
+    ProductivityInsightsMergedPrContributorRowDto:
+      type: object
+      additionalProperties: false
+      required: [personId, personName, weeks]
+      properties:
+        personId:
+          type: string
+          description: Canonical person identifier (matches org chart person_id / employeeId).
+        personName:
+          type: string
+        teamName:
+          type: string
+        weeks:
+          type: array
+          items:
+            $ref: "#/components/schemas/ProductivityInsightsMergedPrTrendWeekDto"
+
+    ProductivityInsightsMergedPrTrendsDto:
+      type: object
+      additionalProperties: false
+      required: [workspaceId, range, scope, generatedAt, weeks, contributors]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        range:
+          type: string
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        generatedAt:
+          type: string
+          format: date-time
+        weeks:
+          type: array
+          description: Portfolio aggregate merged PR counts (sum of filtered contributors per week).
+          items:
+            $ref: "#/components/schemas/ProductivityInsightsMergedPrTrendWeekDto"
+        contributors:
+          type: array
+          items:
+            $ref: "#/components/schemas/ProductivityInsightsMergedPrContributorRowDto"
+
+    ProductivityInsightsTeamLeaderItemDto:
+      type: object
+      additionalProperties: false
+      required:
+        [rank, teamId, teamName, periodAvgMergedPrs, deltaVsPeriodAvgPercent]
+      properties:
+        rank:
+          type: integer
+          minimum: 1
+          description: 1-based rank within the top-teams list (1 = highest performer).
+        teamId:
+          type: string
+        teamName:
+          type: string
+        subtitle:
+          type: string
+          description: Optional context line (e.g. headcount or manager).
+        periodAvgMergedPrs:
+          type: number
+          description: Average weekly merged PR count over the selected range.
+        deltaVsPeriodAvgPercent:
+          type: number
+          description: Percent change of the latest week vs the period average.
+        avgFailRatePercent:
+          type: number
+          description: Average change failure rate over the range when available.
+
+    ProductivityInsightsTeamSummaryDto:
+      type: object
+      additionalProperties: false
+      required: [totalMergedPrs, avgMergedPrsPerWeek, avgFailRatePercent, headcount]
+      properties:
+        totalMergedPrs:
+          type: number
+        avgMergedPrsPerWeek:
+          type: number
+        avgFailRatePercent:
+          type: number
+        headcount:
+          type: integer
+          minimum: 0
 
-  schemas:
-    ErrorMessageDto:
+    ProductivityInsightsTeamDetailDto:
       type: object
-      required: [error]
+      additionalProperties: false
+      required: [teamId, teamName, headcount, weeks, summary]
       properties:
-        error:
+        teamId:
+          type: string
+        teamName:
+          type: string
+        headcount:
+          type: integer
+          minimum: 0
+        managerLabel:
           type: string
+        weeks:
+          type: array
+          items:
+            $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamWeekDto"
+        summary:
+          $ref: "#/components/schemas/ProductivityInsightsTeamSummaryDto"
 
-    TeamMemberDto:
+    ProductivityInsightsTeamsResponseDto:
       type: object
-      required: [id, name, email, role]
+      additionalProperties: false
+      required: [workspaceId, range, scope, generatedAt]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        range:
+          type: string
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        generatedAt:
+          type: string
+          format: date-time
+        items:
+          type: array
+          description: Present when `teamId` query is omitted — top-ranked teams.
+          items:
+            $ref: "#/components/schemas/ProductivityInsightsTeamLeaderItemDto"
+        team:
+          description: Present when `teamId` query is set — single-team drilldown.
+          allOf:
+            - $ref: "#/components/schemas/ProductivityInsightsTeamDetailDto"
+
+    ProductivityInsightsContributorProfileDto:
+      type: object
+      additionalProperties: false
+      required: [id, name]
       properties:
         id:
           type: string
+          description: Org-chart person id (typically email).
         name:
           type: string
-        email:
+        title:
           type: string
-        role:
+        team:
+          type: string
+        department:
           type: string
-          enum: [admin, editor, viewer]
 
-    TeamMemberListDto:
+    ProductivityInsightsContributorActivityDayDto:
       type: object
-      required: [members]
+      additionalProperties: false
+      required:
+        [date, dayIndex, mergedPrCount, mergedPrs, absent, failureSignal, failures]
       properties:
-        members:
+        date:
+          type: string
+          format: date
+        dayIndex:
+          type: integer
+          minimum: 0
+          maximum: 6
+        mergedPrCount:
+          type: integer
+          minimum: 0
+        mergedPrs:
           type: array
           items:
-            $ref: "#/components/schemas/TeamMemberDto"
+            type: string
+        absent:
+          type: boolean
+        absenceType:
+          type: string
+        failureSignal:
+          type: boolean
+        failures:
+          type: array
+          items:
+            type: string
 
-    InviteTeamMemberBodyDto:
+    ProductivityInsightsContributorActivityWeekDto:
       type: object
-      required: [email, role]
+      additionalProperties: false
+      required: [label, bucketStart, bucketEnd, days]
       properties:
-        email:
+        label:
           type: string
-        role:
+        bucketStart:
           type: string
-          enum: [admin, editor, viewer]
+          format: date-time
+        bucketEnd:
+          type: string
+          format: date-time
+        days:
+          type: array
+          items:
+            $ref: "#/components/schemas/ProductivityInsightsContributorActivityDayDto"
 
-    UpdateTeamMemberRoleBodyDto:
+    ProductivityInsightsContributorActivitySummaryDto:
       type: object
-      required: [role]
+      additionalProperties: false
+      required:
+        - totalMergedPrs
+        - avgMergedPrsPerWeek
+        - totalAbsenceDays
+        - avgFailRate
+        - mergedPrDelta
+        - avgMergedPrsPerWeekDelta
+        - totalAbsenceDaysDelta
+        - avgFailRateDelta
       properties:
-        role:
-          type: string
-          enum: [admin, editor, viewer]
+        totalMergedPrs:
+          type: integer
+          minimum: 0
+        avgMergedPrsPerWeek:
+          type: number
+        totalAbsenceDays:
+          type: integer
+          minimum: 0
+        avgFailRate:
+          type: number
+        mergedPrDelta:
+          type: number
+        avgMergedPrsPerWeekDelta:
+          type: number
+        totalAbsenceDaysDelta:
+          type: number
+        avgFailRateDelta:
+          type: number
 
-    OrgChartNodeDto:
+    ProductivityInsightsContributorDetailDto:
       type: object
       additionalProperties: false
-      required: [id, name, type]
+      required:
+        - workspaceId
+        - contributorId
+        - range
+        - scope
+        - generatedAt
+        - contributor
+        - weeks
+        - summary
       properties:
-        id:
+        workspaceId:
           type: string
-        name:
+          format: uuid
+        contributorId:
           type: string
-        type:
+        range:
           type: string
-          enum: [org, department, team, person]
-        external_ids:
-          type: object
-          additionalProperties: { type: string }
-        children:
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        generatedAt:
+          type: string
+          format: date-time
+        contributor:
+          $ref: "#/components/schemas/ProductivityInsightsContributorProfileDto"
+        weeks:
           type: array
           items:
-            $ref: "#/components/schemas/OrgChartNodeDto"
+            $ref: "#/components/schemas/ProductivityInsightsContributorActivityWeekDto"
+        summary:
+          $ref: "#/components/schemas/ProductivityInsightsContributorActivitySummaryDto"
 
-    OrgChartTreeNodeDto:
+    ProductivityInsightsNeedsAttentionItemDto:
       type: object
-      required: [id]
+      additionalProperties: false
+      required:
+        [rank, entityId, entityType, name, periodAvgMergedPrs, deltaVsPeriodAvgPercent]
       properties:
-        id:
+        rank:
+          type: integer
+          minimum: 1
+          description: 1-based rank within the laggards list (1 = lowest performer).
+        entityId:
+          type: string
+          description: Org chart team id or canonical person id.
+        entityType:
           type: string
+          enum: [team, contributor]
         name:
           type: string
-        type:
+        subtitle:
           type: string
-        person_id:
+          description: Optional context line (e.g. headcount or job title).
+        periodAvgMergedPrs:
+          type: number
+          description: Mean weekly merged PR count across the selected range.
+        deltaVsPeriodAvgPercent:
+          type: number
+          description: Percent change of the latest week vs the period mean.
+        avgFailRatePercent:
+          type: number
+          description: Mean weekly change-failure rate when available.
+
+    ProductivityInsightsNeedsAttentionDto:
+      type: object
+      additionalProperties: false
+      required: [workspaceId, range, scope, entityType, generatedAt, items]
+      properties:
+        workspaceId:
           type: string
-        team:
+          format: uuid
+        range:
           type: string
-        role:
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        entityType:
           type: string
-        level:
+          enum: [teams, contributors]
+        generatedAt:
           type: string
-        external_ids:
-          type: object
-          additionalProperties: { type: string }
-        children:
+          format: date-time
+        items:
           type: array
           items:
-            $ref: "#/components/schemas/OrgChartTreeNodeDto"
+            $ref: "#/components/schemas/ProductivityInsightsNeedsAttentionItemDto"
 
-    ScoringOrgChartDto:
+    AiUsageSpendAggregatedTeamWeekDto:
       type: object
       additionalProperties: false
-      required: [root]
+      required: [bucketStart, bucketEnd, tokenCount, spendCents, activeUsers]
       properties:
-        root:
-          $ref: "#/components/schemas/OrgChartTreeNodeDto"
+        bucketStart:
+          type: string
+          format: date-time
+        bucketEnd:
+          type: string
+          format: date-time
+        weekLabel:
+          type: string
+          description: Short label for table headers (e.g. MM/DD).
+        tokenCount:
+          type: integer
+          minimum: 0
+          description: Total tokens consumed in the bucket (from AI-tool daily usage payloads when available).
+        spendCents:
+          type: integer
+          minimum: 0
+          description: Estimated spend in USD cents attributed to the bucket.
+        activeUsers:
+          type: integer
+          minimum: 0
+          description: Distinct engineers with active AI-tool usage in the bucket.
 
-    OrgChartDto:
+    AiUsageSpendAggregatedTeamRowDto:
       type: object
       additionalProperties: false
-      required: [root]
+      required: [teamId, teamName, headcount, weeks]
       properties:
-        root:
-          $ref: "#/components/schemas/OrgChartNodeDto"
+        teamId:
+          type: string
+        teamName:
+          type: string
+        headcount:
+          type: integer
+          minimum: 0
+        managerLabel:
+          type: string
+        weeks:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendAggregatedTeamWeekDto"
 
-    OrgChartPersonDto:
+    AiUsageSpendAggregatedTeamsSummaryDto:
       type: object
       additionalProperties: false
-      required: [employeeId, name, email, title, department, team, managerId, location]
+      required:
+        [totalTokenCount, totalSpendCents, activeUsers, activeTools, totalEngineers]
       properties:
-        employeeId:
+        totalTokenCount:
+          type: integer
+          minimum: 0
+        totalSpendCents:
+          type: integer
+          minimum: 0
+        activeUsers:
+          type: integer
+          minimum: 0
+          description: Distinct engineers with any active usage in the selected range.
+        activeTools:
+          type: integer
+          minimum: 0
+          description: Count of connected AI-tool providers with usage or spend in range.
+        totalEngineers:
+          type: integer
+          minimum: 0
+          description: Sum of org-chart headcount across returned teams.
+
+    AiUsageSpendAggregatedTeamsDto:
+      type: object
+      additionalProperties: false
+      required: [workspaceId, range, scope, generatedAt, teams, summary]
+      properties:
+        workspaceId:
           type: string
-        name:
+          format: uuid
+        range:
           type: string
-        email:
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        generatedAt:
           type: string
-        title:
+          format: date-time
+        teams:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendAggregatedTeamRowDto"
+        summary:
+          $ref: "#/components/schemas/AiUsageSpendAggregatedTeamsSummaryDto"
+
+    AiUsageSpendAggregatedContributorRowDto:
+      type: object
+      additionalProperties: false
+      required: [contributorId, contributorName, weeks]
+      properties:
+        contributorId:
           type: string
-        department:
+          description: Org-chart person id (typically email).
+        contributorName:
           type: string
-        team:
+        title:
           type: string
-        managerId:
+        team:
           type: string
-        location:
+        department:
           type: string
+        weeks:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendAggregatedTeamWeekDto"
 
-    OrgChartImportResultDto:
+    AiUsageSpendAggregatedContributorsDto:
       type: object
       additionalProperties: false
-      required: [persons, errors]
+      required: [workspaceId, range, scope, generatedAt, contributors, summary]
       properties:
-        persons:
-          type: array
-          items:
-            $ref: "#/components/schemas/OrgChartPersonDto"
-        errors:
+        workspaceId:
+          type: string
+          format: uuid
+        range:
+          type: string
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        generatedAt:
+          type: string
+          format: date-time
+        contributors:
           type: array
           items:
-            type: string
+            $ref: "#/components/schemas/AiUsageSpendAggregatedContributorRowDto"
+        summary:
+          $ref: "#/components/schemas/AiUsageSpendAggregatedTeamsSummaryDto"
 
-    OrgChartSaveResultDto:
+    AiUsageSpendContributorToolHeatmapDto:
       type: object
       additionalProperties: false
-      required: [ok, tenantId]
+      required:
+        - workspaceId
+        - range
+        - scope
+        - generatedAt
+        - contributors
       properties:
-        ok:
-          type: boolean
-        tenantId:
+        workspaceId:
           type: string
           format: uuid
-
-    TenantSourceEntryDto:
-      type: object
-      required: [type]
-      properties:
-        type:
+        range:
           type: string
-      additionalProperties: true
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        generatedAt:
+          type: string
+          format: date-time
+        contributors:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendAggregatedContributorRowDto"
 
-    CursorSourceDto:
+    AiUsageSpendKeyInsightItemDto:
       type: object
-      description: >
-        Cursor (AI Tools) source entry for `PUT /workspaces/{workspaceId}/sources`
-        and `POST /workspaces/{workspaceId}/sources/test`. The `token` field
-        carries a literal Cursor API key on writes; reads from
-        `GET /workspaces/{workspaceId}/config` redact it to `***`.
-        Runtime calls use the Cursor Admin API at `https://api.cursor.com` (HTTP Basic); do not rely on `baseUrl`.
-      required: [type, token]
       additionalProperties: false
+      required: [id, tone, text]
       properties:
-        type:
+        id:
           type: string
-          enum: [cursor]
-        token:
+          description: Stable insight key (e.g. spend-leader, spend-vs-output).
+        tone:
           type: string
-          minLength: 1
-          maxLength: 256
-          description: Cursor API key (literal). Whitespace and `env:` prefix are rejected.
-        baseUrl:
+          enum: [positive, warning, neutral]
+        text:
           type: string
-          deprecated: true
-          description: >
-            Deprecated. Historically suggested an API base URL; the server ignores this field
-            and always uses the Cursor Admin API host. Kept so older clients can submit payloads unchanged.
-          default: "https://api.cursor.com"
+          description: Human-readable insight sentence for the UI panel.
 
-    WorkspaceConfigDto:
+    AiUsageSpendKeyInsightsDto:
       type: object
-      required: [sources]
+      additionalProperties: false
+      required: [workspaceId, range, scope, generatedAt, items]
       properties:
-        sources:
+        workspaceId:
+          type: string
+          format: uuid
+        range:
+          type: string
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        generatedAt:
+          type: string
+          format: date-time
+        items:
           type: array
           items:
-            $ref: "#/components/schemas/TenantSourceEntryDto"
-        orgChart:
-          nullable: true
-          allOf:
-            - $ref: "#/components/schemas/ScoringOrgChartDto"
-        region:
-          type: string
-          nullable: true
-          enum: [us, eu, me]
+            $ref: "#/components/schemas/AiUsageSpendKeyInsightItemDto"
 
-    TestConnectionResponseDto:
-      type: object
-      required: [success]
-      properties:
-        success:
-          type: boolean
-        error:
-          type: string
+    AiAssistedCodeDataQuality:
+      type: string
+      enum: [estimated, measured]
+      description: >
+        **measured** — derived from scoped productivity ingest
+        (`aiAdoption.aiAssistedContributionRatioPercent`). **estimated** — derived from
+        AI-tool token volume heuristics when ingest ratios are absent for that bucket.
 
-    AiToolSeatDto:
+    AiUsageSpendAiAssistedCodeWeekDto:
       type: object
-      required: [externalId, email, isRemoved]
+      additionalProperties: false
+      required:
+        [
+          bucketStart,
+          bucketEnd,
+          aiAssistedCodePercent,
+          totalLoc,
+          aiLoc,
+          humanLoc,
+          dataQuality,
+        ]
       properties:
-        externalId:
+        bucketStart:
           type: string
-        email:
-          type: string
-        displayName:
+          format: date-time
+        bucketEnd:
           type: string
-          nullable: true
-        role:
+          format: date-time
+        weekLabel:
           type: string
-          nullable: true
-        isRemoved:
-          type: boolean
-        payload:
-          type: object
-          additionalProperties: true
+        aiAssistedCodePercent:
+          type: number
+          minimum: 0
+          maximum: 100
+        totalLoc:
+          type: integer
+          minimum: 0
+        aiLoc:
+          type: integer
+          minimum: 0
+        humanLoc:
+          type: integer
+          minimum: 0
+        dataQuality:
+          $ref: "#/components/schemas/AiAssistedCodeDataQuality"
 
-    AiToolDailyUsageRowDto:
+    AiUsageSpendAiAssistedCodePercentageDto:
       type: object
-      required: [day, externalId, isActive]
+      additionalProperties: false
+      required:
+        - workspaceId
+        - range
+        - scope
+        - generatedAt
+        - aiAssistedCodePercent
+        - deltaVsPriorPeriodPercent
+        - totalLoc
+        - aiLoc
+        - humanLoc
+        - dataQuality
+        - weeks
       properties:
-        day:
-          type: string
-          format: date
-        externalId:
+        workspaceId:
           type: string
-        email:
+          format: uuid
+        range:
           type: string
-          nullable: true
-        isActive:
-          type: boolean
-        mostUsedModel:
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        generatedAt:
           type: string
-          nullable: true
-        payload:
-          type: object
-          additionalProperties: true
+          format: date-time
+        aiAssistedCodePercent:
+          type: number
+          minimum: 0
+          maximum: 100
+          description: Portfolio AI-assisted code share for the selected period (0–100).
+        dataQuality:
+          description: >
+            Period rollup quality. **measured** only when every weekly bucket in `weeks`
+            used ingest ratios; otherwise **estimated** (including mixed ingest/heuristic weeks).
+          allOf:
+            - $ref: "#/components/schemas/AiAssistedCodeDataQuality"
+        deltaVsPriorPeriodPercent:
+          type: number
+          description: Change in AI-assisted code share vs the prior half of the range (percentage points).
+        totalLoc:
+          type: integer
+          minimum: 0
+        aiLoc:
+          type: integer
+          minimum: 0
+        humanLoc:
+          type: integer
+          minimum: 0
+        targetMinPercent:
+          type: number
+          default: 50
+        targetMaxPercent:
+          type: number
+          default: 75
+        weeks:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendAiAssistedCodeWeekDto"
 
-    AiToolSpendRowDto:
+    AiUsageSpendAiToolUsageSpendProviderItemDto:
       type: object
-      required: [billingCycleStartMs, externalId, spendCents]
+      additionalProperties: false
+      required: [providerId, providerName, tokenCount, spendCents, activeUsers]
       properties:
-        billingCycleStartMs:
-          type: integer
-          format: int64
-        externalId:
+        providerId:
           type: string
-        email:
+        providerName:
           type: string
-          nullable: true
+        tokenCount:
+          type: integer
+          minimum: 0
         spendCents:
           type: integer
-          format: int64
-        payload:
-          type: object
-          additionalProperties: true
+          minimum: 0
+        activeUsers:
+          type: integer
+          minimum: 0
 
-    AiToolRefreshStatusDto:
+    AiUsageSpendAiToolUsageSpendModelItemDto:
       type: object
-      required: [lastAttemptAt, counts]
+      additionalProperties: false
+      required: [providerId, providerName, modelName, tokenCount, spendCents]
       properties:
-        lastAttemptAt:
-          type: string
-          format: date-time
-        lastSuccessAt:
+        providerId:
           type: string
-          format: date-time
-          nullable: true
-        lastErrorKind:
+        providerName:
           type: string
-          nullable: true
-        lastErrorMessage:
+        modelName:
           type: string
-          nullable: true
-        durationMs:
+        tokenCount:
           type: integer
-          format: int64
-          nullable: true
-        counts:
-          type: object
-          additionalProperties: true
+          minimum: 0
+        spendCents:
+          type: integer
+          minimum: 0
 
-    AiToolRefreshResponseDto:
+    AiUsageSpendAiToolUsageSpendDto:
       type: object
-      required: [ok]
+      additionalProperties: false
+      required:
+        - workspaceId
+        - range
+        - scope
+        - generatedAt
+        - totalEngineers
+        - providers
+        - models
       properties:
-        ok:
-          type: boolean
-        error:
+        workspaceId:
           type: string
-          nullable: true
-
-    DashboardProductivityMetricsDto:
-      type: object
-      description: Nested metric groups; see TypeScript `DashboardProductivityMetricsDto` in @thinkai/tai-api-contract.
-      additionalProperties: true
+          format: uuid
+        range:
+          type: string
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        generatedAt:
+          type: string
+          format: date-time
+        totalEngineers:
+          type: integer
+          minimum: 0
+        providers:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendAiToolUsageSpendProviderItemDto"
+        models:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendAiToolUsageSpendModelItemDto"
 
-    DashboardProductivityDto:
+    AiUsageSpendTeamToolHeatmapDto:
       type: object
-      required: [workspaceId, windowStart, windowEnd, scope, metrics]
+      additionalProperties: false
+      required:
+        - workspaceId
+        - range
+        - scope
+        - generatedAt
+        - teams
       properties:
         workspaceId:
           type: string
           format: uuid
+        range:
+          type: string
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
         generatedAt:
           type: string
           format: date-time
-          description: Response generation time (RFC 3339).
-        windowStart:
+        teams:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiUsageSpendAggregatedTeamRowDto"
+
+    AiUsageSpendRoiProductivitySignalWeekDto:
+      type: object
+      additionalProperties: false
+      required: [bucketStart, bucketEnd, mergedPrCount, tokenCount]
+      properties:
+        bucketStart:
           type: string
           format: date-time
-        windowEnd:
+        bucketEnd:
           type: string
           format: date-time
-        scope:
+        weekLabel:
           type: string
-          enum: [org, team, person]
-        metrics:
-          $ref: "#/components/schemas/DashboardProductivityMetricsDto"
-        meta:
-          type: object
-          additionalProperties: true
+        mergedPrCount:
+          type: integer
+          minimum: 0
+          description: Estimated merged PR count in the bucket from dashboard velocity metrics.
+        tokenCount:
+          type: integer
+          minimum: 0
+          description: Total AI-tool tokens consumed in the bucket.
 
-    DashboardProductivityHistoryDto:
+    AiUsageSpendRoiProductivitySignalDto:
       type: object
-      required: [workspaceId, bucket, buckets]
+      additionalProperties: false
+      required:
+        - workspaceId
+        - range
+        - scope
+        - generatedAt
+        - totalMergedPrs
+        - totalSpendCents
+        - activeUsers
+        - totalEngineers
+        - aiAssistedPrRatio
+        - prThroughputDeltaPercent
+        - usageDeltaPercent
+        - weeks
       properties:
         workspaceId:
           type: string
           format: uuid
-        bucket:
+        range:
           type: string
-          enum: [day, week, month]
-        buckets:
+          enum: [4w, 8w, q]
+        scope:
+          $ref: "#/components/schemas/ProductivityInsightsAggregatedTeamsScopeDto"
+        generatedAt:
+          type: string
+          format: date-time
+        totalMergedPrs:
+          type: integer
+          minimum: 0
+        totalSpendCents:
+          type: integer
+          minimum: 0
+        activeUsers:
+          type: integer
+          minimum: 0
+        totalEngineers:
+          type: integer
+          minimum: 0
+        aiAssistedPrRatio:
+          type: number
+          minimum: 0
+          maximum: 1
+          description: Share of merged PRs estimated to be AI-assisted (0–1).
+        prThroughputDeltaPercent:
+          type: number
+          description: Percent change in merged PR throughput (recent half vs prior half of range).
+        usageDeltaPercent:
+          type: number
+          description: Percent change in token usage (recent half vs prior half of range).
+        weeks:
           type: array
           items:
-            type: object
-            required: [bucketStart, bucketEnd, metrics]
-            properties:
-              bucketStart:
-                type: string
-                format: date-time
-              bucketEnd:
-                type: string
-                format: date-time
-              metrics:
-                $ref: "#/components/schemas/DashboardProductivityMetricsDto"
+            $ref: "#/components/schemas/AiUsageSpendRoiProductivitySignalWeekDto"
 
     MeProfileDto:
       type: object
@@ -2772,9 +4445,26 @@ components:
           type: boolean
           nullable: true
 
+    GithubMissingPermissionDto:
+      type: object
+      additionalProperties: false
+      required: [name, required]
+      properties:
+        name:
+          type: string
+          description: GitHub App permission key (e.g. contents, pull_requests).
+        required:
+          type: string
+          enum: [read, write, admin]
+        granted:
+          type: string
+          enum: [read, write, admin]
+          nullable: true
+          description: Null when the installation has not granted this permission.
+
     GithubInstallationSummaryDto:
       type: object
-      required: [installationId, account, repos]
+      required: [installationId, account, repos, permissionsUpgradeRequired]
       properties:
         installationId:
           type: string
@@ -2793,10 +4483,23 @@ components:
           type: string
           format: date-time
           nullable: true
+        permissionsUpgradeRequired:
+          type: boolean
+          description: >
+            True when this installation's granted permissions are below what the ThinkAI GitHub App
+            currently requests.
+        missingPermissions:
+          type: array
+          items:
+            $ref: "#/components/schemas/GithubMissingPermissionDto"
+        upgradeMessage:
+          type: string
+          nullable: true
+          description: Human-readable summary for UI when permissionsUpgradeRequired is true.
 
     GithubInstallationStatusDto:
       type: object
-      required: [installed, installations]
+      required: [installed, installations, permissionsUpgradeRequired]
       properties:
         installed:
           type: boolean
@@ -2804,6 +4507,9 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/GithubInstallationSummaryDto"
+        permissionsUpgradeRequired:
+          type: boolean
+          description: True if any connected installation is under-permissioned.
         installationId:
           type: string
           nullable: true