@thinkai/tai-api-contract 2.5.17 → 2.7.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.5.17
+  version: 2.7.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -50,6 +50,8 @@ tags:
     description: Org chart import via storage path (§14)
   - name: AgenticFoundation
     description: Agentic Foundation pillars (epic #278); reads stored repository readiness snapshots
+  - name: YourAiJourney
+    description: Your AI Journey dashboard aggregators (epic #267); composes readiness, metrics, and AI-spend data for the /dashboard page
 
 paths:
   /me:
@@ -1503,6 +1505,10 @@ paths:
           schema:
             type: boolean
             default: false
+        - $ref: "#/components/parameters/GithubRepoLimit"
+        - $ref: "#/components/parameters/GithubRepoOffset"
+        - $ref: "#/components/parameters/GithubRepoSort"
+        - $ref: "#/components/parameters/GithubRepoOrder"
       responses:
         "200":
           description: Installation status
@@ -2120,19 +2126,33 @@ paths:
   /workspaces/{workspaceId}/readiness/repos:
     get:
       tags: [RepositoryReadiness]
-      summary: List repo readiness scores
+      summary: List repo readiness scores (paginated)
       operationId: listReadinessRepos
+      description: >
+        Returns a page of repository readiness scorecards. Use `GET .../readiness/repos/{repoId}`
+        for a single repo. Summary aggregates on the Agentic Foundation dashboard use separate
+        aggregate queries over the full workspace (#403).
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/ReadinessRepoSort"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - $ref: "#/components/parameters/ReadinessRepoSearch"
+        - $ref: "#/components/parameters/ReadinessRepoLanguage"
       responses:
         "200":
-          description: Repositories analyzed
+          description: Paginated repositories analyzed
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/ReadinessRepoListDto"
+        "400":
+          description: Invalid pagination or sort query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2267,18 +2287,19 @@ paths:
   /workspaces/{workspaceId}/agentic-foundation/dashboard:
     get:
       tags: [AgenticFoundation]
-      summary: Agentic Foundation dashboard
+      summary: Agentic Foundation dashboard summary
       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`.
+        Returns workspace-level readiness summary, per-dimension aggregate bars, and fix status
+        counts for Agentic Foundation dashboard surfaces. Repository and issue lists are paginated
+        on `GET .../readiness/repos` and related segment routes (#403). Read-only; does not run
+        scoring on the request path (issue #279). Field `generatedAt` is the server timestamp when
+        this JSON payload was assembled.
       operationId: getAgenticFoundationDashboard
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Dashboard scorecards and issue queue
+          description: Dashboard summary and aggregates
           content:
             application/json:
               schema:
@@ -2294,8 +2315,14 @@ paths:
                       averageOverallScore: 0
                       issueCount: 0
                       criticalIssueCount: 0
-                    repos: []
-                    issueQueue: []
+                    dimensionAggregates: []
+                    fixStatusSummary:
+                      queued: 0
+                      generating: 0
+                      prCreated: 0
+                      merged: 0
+                      failed: 0
+                      total: 0
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2317,39 +2344,53 @@ paths:
       operationId: getAgenticFoundationAgenticReadiness
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/ReadinessRepoSort"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - $ref: "#/components/parameters/ReadinessRepoSearch"
+        - $ref: "#/components/parameters/ReadinessRepoLanguage"
       responses:
         "200":
-          description: Repositories with ai-agent-readiness slice
+          description: Paginated repositories with ai-agent-readiness slice
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/ReadinessRepoListDto"
               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
+                    total: 1
+                    limit: 25
+                    offset: 0
+                    items:
+                      - 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
+        "400":
+          description: Invalid pagination or sort query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2369,15 +2410,25 @@ paths:
       operationId: getAgenticFoundationRepositoryHealth
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/ReadinessRepoSort"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - $ref: "#/components/parameters/ReadinessRepoSearch"
+        - $ref: "#/components/parameters/ReadinessRepoLanguage"
       responses:
         "200":
-          description: Repositories with repo-hygiene slice
+          description: Paginated repositories with repo-hygiene slice
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/ReadinessRepoListDto"
+        "400":
+          description: Invalid pagination or sort query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2397,15 +2448,25 @@ paths:
       operationId: getAgenticFoundationCodebaseQuality
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/ReadinessRepoSort"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - $ref: "#/components/parameters/ReadinessRepoSearch"
+        - $ref: "#/components/parameters/ReadinessRepoLanguage"
       responses:
         "200":
-          description: Repositories with stack-quality slice
+          description: Paginated repositories with stack-quality slice
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/ReadinessRepoListDto"
+        "400":
+          description: Invalid pagination or sort query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2425,15 +2486,25 @@ paths:
       operationId: getAgenticFoundationTestQa
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/ReadinessRepoSort"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - $ref: "#/components/parameters/ReadinessRepoSearch"
+        - $ref: "#/components/parameters/ReadinessRepoLanguage"
       responses:
         "200":
-          description: Repositories with tests-qa slice
+          description: Paginated repositories with tests-qa slice
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/ReadinessRepoListDto"
+        "400":
+          description: Invalid pagination or sort query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2453,15 +2524,25 @@ paths:
       operationId: getAgenticFoundationObservability
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/ReadinessRepoSort"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - $ref: "#/components/parameters/ReadinessRepoSearch"
+        - $ref: "#/components/parameters/ReadinessRepoLanguage"
       responses:
         "200":
-          description: Repositories with observability slice
+          description: Paginated repositories with observability slice
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/ReadinessRepoListDto"
+        "400":
+          description: Invalid pagination or sort query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2481,15 +2562,25 @@ paths:
       operationId: getAgenticFoundationApiContract
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/ReadinessRepoSort"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - $ref: "#/components/parameters/ReadinessRepoSearch"
+        - $ref: "#/components/parameters/ReadinessRepoLanguage"
       responses:
         "200":
-          description: Repositories with api-contracts slice
+          description: Paginated repositories with api-contracts slice
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/ReadinessRepoListDto"
+        "400":
+          description: Invalid pagination or sort query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2509,15 +2600,25 @@ paths:
       operationId: getAgenticFoundationPlatformGovernance
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/ReadinessRepoSort"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - $ref: "#/components/parameters/ReadinessRepoSearch"
+        - $ref: "#/components/parameters/ReadinessRepoLanguage"
       responses:
         "200":
-          description: Repositories with platform-governance slice
+          description: Paginated repositories with platform-governance slice
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/ReadinessRepoListDto"
+        "400":
+          description: Invalid pagination or sort query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2537,15 +2638,25 @@ paths:
       operationId: getAgenticFoundationDeliveryGovernance
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/ReadinessRepoSort"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - $ref: "#/components/parameters/ReadinessRepoSearch"
+        - $ref: "#/components/parameters/ReadinessRepoLanguage"
       responses:
         "200":
-          description: Repositories with delivery slice
+          description: Paginated repositories with delivery slice
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/ReadinessRepoListDto"
+        "400":
+          description: Invalid pagination or sort query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2567,15 +2678,25 @@ paths:
       operationId: getAgenticFoundationAiResolutionHub
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/ReadinessRepoSort"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - $ref: "#/components/parameters/ReadinessRepoSearch"
+        - $ref: "#/components/parameters/ReadinessRepoLanguage"
       responses:
         "200":
           description: Full repository readiness scorecards
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+                $ref: "#/components/schemas/ReadinessRepoListDto"
+        "400":
+          description: Invalid pagination or sort query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -2620,21 +2741,32 @@ paths:
   /workspaces/{workspaceId}/readiness/fixes:
     get:
       tags: [RepositoryReadiness]
-      summary: List fix requests
+      summary: List fix requests (paginated)
       description: >
-        Returns persisted fix-queue rows for the workspace (newest first). Empty array when none exist.
+        Returns a page of persisted fix-queue rows for the workspace (default newest first).
       operationId: listReadinessFixes
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/ReadinessFixSort"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - $ref: "#/components/parameters/ReadinessFixSearch"
+        - $ref: "#/components/parameters/ReadinessFixStatusFilter"
+        - $ref: "#/components/parameters/ReadinessFixRepoIdFilter"
       responses:
         "200":
-          description: Fix queue
+          description: Paginated fix queue
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/FixRequestDto"
+                $ref: "#/components/schemas/ReadinessFixListDto"
+        "400":
+          description: Invalid pagination or sort query
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -3054,9 +3186,275 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
-        "503":
-          description: Storage import not configured or service unavailable
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: Storage import not configured or service unavailable
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  # ── Your AI Journey (/dashboard) — epic #267 ─────────────────────────────
+
+  /workspaces/{workspaceId}/your-ai-journey/analytics:
+    get:
+      tags: [YourAiJourney]
+      summary: Combined analytics summary for the /dashboard page
+      description: >
+        Returns a single aggregated payload combining journey step progress, readiness summary,
+        and PR-signal headline metrics. Covers issue #268. Results are cached for 60 seconds.
+      operationId: getYourAiJourneyAnalytics
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Analytics summary
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/YourAiJourneyAnalyticsDto"
+        "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}/your-ai-journey/pr-signals:
+    get:
+      tags: [YourAiJourney]
+      summary: Weekly PR velocity and change-failure-rate time series
+      description: >
+        Returns a per-week time series of PR throughput and DORA change-failure-rate metrics,
+        sourced from stored dashboard metrics. Covers issue #269. Results are cached for 60 seconds.
+      operationId: getYourAiJourneyPrSignals
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: limit
+          in: query
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 52
+            default: 8
+          description: Number of weekly buckets to return (1–52; default 8).
+      responses:
+        "200":
+          description: Weekly PR signals
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/YourAiJourneyPrSignalsDto"
+        "400":
+          description: Invalid query parameter (limit out of range)
+          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"
+
+  /workspaces/{workspaceId}/your-ai-journey/readiness/aggregate:
+    get:
+      tags: [YourAiJourney]
+      summary: Per-dimension readiness aggregate across all repos
+      description: >
+        Aggregates stored readiness scores across all workspace repos by dimension.
+        Covers issue #270. Results are cached for 60 seconds.
+      operationId: getYourAiJourneyReadinessAggregate
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Readiness aggregate
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/YourAiJourneyReadinessAggregateDto"
+        "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}/your-ai-journey/journey/progress:
+    get:
+      tags: [YourAiJourney]
+      summary: Workspace journey step completion
+      description: >
+        Returns the workspace-scoped journey progress state. Returns an empty `completedSteps`
+        list with a synthetic `updatedAt` if no row exists yet. Covers issue #271.
+      operationId: getYourAiJourneyProgress
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Journey progress
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JourneyProgressDto"
+        "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: [YourAiJourney]
+      summary: Replace workspace journey completed steps
+      description: >
+        Idempotent replace-all of completed route strings for the workspace journey.
+        Requires editor role. Covers issue #271.
+      operationId: putYourAiJourneyProgress
+      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"
+
+  /workspaces/{workspaceId}/your-ai-journey/agentic-foundation:
+    get:
+      tags: [YourAiJourney]
+      summary: Agentic foundation dashboard slice for /dashboard
+      description: >
+        Returns the same `AgenticFoundationDashboardDto` payload as
+        `GET /agentic-foundation/dashboard`, scoped to the /dashboard page context.
+        Covers issue #272. Results are cached for 60 seconds.
+      operationId: getYourAiJourneyAgenticFoundation
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Agentic foundation dashboard
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgenticFoundationDashboardDto"
+        "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}/your-ai-journey/productivity:
+    get:
+      tags: [YourAiJourney]
+      summary: Workspace productivity metrics for /dashboard
+      description: >
+        Returns the most recent stored dashboard productivity metrics snapshot that overlaps the
+        requested window (defaults to the trailing 7 days). Same schema as
+        `GET /dashboard/productivity`. Covers issue #273. Results are cached for 60 seconds.
+      operationId: getYourAiJourneyProductivity
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: windowEnd
+          in: query
+          schema:
+            type: string
+            format: date-time
+          description: Upper bound of the requested window (ISO 8601; defaults to now).
+      responses:
+        "200":
+          description: Productivity metrics snapshot
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DashboardProductivityDto"
+        "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}/your-ai-journey/ai-spend:
+    get:
+      tags: [YourAiJourney]
+      summary: AI tool spend and usage aggregated by week and provider
+      description: >
+        Returns token usage and spend aggregated from connected AI tool sources (e.g. Cursor)
+        over the requested range, broken down by week and provider. Covers issue #274.
+        Results are cached for 60 seconds.
+      operationId: getYourAiJourneyAiSpend
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: rangeId
+          in: query
+          schema:
+            type: string
+            enum: [4w, 8w, q]
+            default: 4w
+          description: Time range — `4w` (4 weeks), `8w` (8 weeks), or `q` (quarter, 12 weeks).
+      responses:
+        "200":
+          description: AI spend aggregation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/YourAiJourneyAiSpendDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
           content:
             application/json:
               schema:
@@ -3123,6 +3521,129 @@ components:
       schema:
         type: string
         default: All departments
+    PaginationLimit:
+      name: limit
+      in: query
+      required: false
+      description: Page size (default 25, max 100).
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 25
+    PaginationOffset:
+      name: offset
+      in: query
+      required: false
+      description: Zero-based row offset into the filtered, sorted result set.
+      schema:
+        type: integer
+        minimum: 0
+        default: 0
+    PaginationOrder:
+      name: order
+      in: query
+      required: false
+      description: Sort direction.
+      schema:
+        type: string
+        enum: [asc, desc]
+        default: desc
+    ReadinessRepoSort:
+      name: sort
+      in: query
+      required: false
+      description: Allowlisted repository sort field.
+      schema:
+        type: string
+        enum: [repoName, overallScore, lastAnalyzed, language]
+        default: overallScore
+    ReadinessRepoSearch:
+      name: search
+      in: query
+      required: false
+      description: Case-insensitive filter on repository name, language, or provider slug.
+      schema:
+        type: string
+        maxLength: 256
+    ReadinessRepoLanguage:
+      name: language
+      in: query
+      required: false
+      description: Exact language filter (e.g. `typescript`).
+      schema:
+        type: string
+        maxLength: 64
+    ReadinessFixSort:
+      name: sort
+      in: query
+      required: false
+      description: Allowlisted fix-queue sort field.
+      schema:
+        type: string
+        enum: [createdAt, repoName, severity, status]
+        default: createdAt
+    ReadinessFixStatusFilter:
+      name: status
+      in: query
+      required: false
+      description: Filter fixes by workflow status.
+      schema:
+        type: string
+        enum: [queued, generating, pr-created, merged, failed]
+    ReadinessFixRepoIdFilter:
+      name: repoId
+      in: query
+      required: false
+      description: Filter fixes to a single workspace repository id.
+      schema:
+        type: string
+        format: uuid
+    ReadinessFixSearch:
+      name: search
+      in: query
+      required: false
+      description: Case-insensitive filter on repo name, issue title, label, or description.
+      schema:
+        type: string
+        maxLength: 256
+    GithubRepoLimit:
+      name: repoLimit
+      in: query
+      required: false
+      description: Page size for the nested installation repo list (default 25, max 100).
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 25
+    GithubRepoOffset:
+      name: repoOffset
+      in: query
+      required: false
+      description: Zero-based offset into the merged installation repo list.
+      schema:
+        type: integer
+        minimum: 0
+        default: 0
+    GithubRepoSort:
+      name: repoSort
+      in: query
+      required: false
+      description: Allowlisted GitHub repo sort field.
+      schema:
+        type: string
+        enum: [name, updatedAt]
+        default: name
+    GithubRepoOrder:
+      name: repoOrder
+      in: query
+      required: false
+      description: Sort direction for the nested installation repo list.
+      schema:
+        type: string
+        enum: [asc, desc]
+        default: asc
 
   responses:
     Unauthorized:
@@ -3624,6 +4145,12 @@ components:
           type: string
         teamName:
           type: string
+        notInOrgChart:
+          type: boolean
+          description: True when the contributor GitHub login is not mapped in the org chart.
+        githubLogin:
+          type: string
+          description: GitHub login for unattributed contributors (when notInOrgChart is true).
         weeks:
           type: array
           items:
@@ -3647,7 +4174,7 @@ components:
           format: date-time
         weeks:
           type: array
-          description: Portfolio aggregate merged PR counts (sum of filtered contributors per week).
+          description: Portfolio aggregate merged PR counts from org-scope metrics (all merged PRs in window).
           items:
             $ref: "#/components/schemas/ProductivityInsightsMergedPrTrendWeekDto"
         contributors:
@@ -4532,6 +5059,11 @@ components:
         private:
           type: boolean
           nullable: true
+        updatedAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: Last push or metadata update from GitHub when available.
 
     GithubMissingPermissionDto:
       type: object
@@ -4560,9 +5092,9 @@ components:
           allOf:
             - $ref: "#/components/schemas/GithubAccountDto"
         repos:
-          type: array
-          items:
-            $ref: "#/components/schemas/GithubInstalledRepoDto"
+          allOf:
+            - $ref: "#/components/schemas/GithubInstalledRepoListDto"
+          description: Paginated repositories granted on this installation (same repoLimit/repoOffset as top-level repos).
         manageUrl:
           type: string
           format: uri
@@ -4606,10 +5138,10 @@ components:
           allOf:
             - $ref: "#/components/schemas/GithubAccountDto"
         repos:
-          type: array
-          items:
-            $ref: "#/components/schemas/GithubInstalledRepoDto"
           nullable: true
+          allOf:
+            - $ref: "#/components/schemas/GithubInstalledRepoListDto"
+          description: Paginated merged installation repositories when `installed` is true.
         manageUrl:
           type: string
           format: uri
@@ -5157,9 +5689,98 @@ components:
           type: string
           enum: [open, pr-pending, fixed]
 
+    PageMetaDto:
+      type: object
+      required: [total, limit, offset]
+      properties:
+        total:
+          type: integer
+          minimum: 0
+          description: Total rows matching filters (full workspace, not just this page).
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 100
+        offset:
+          type: integer
+          minimum: 0
+
+    ReadinessRepoListDto:
+      allOf:
+        - $ref: "#/components/schemas/PageMetaDto"
+        - type: object
+          required: [items]
+          properties:
+            items:
+              type: array
+              items:
+                $ref: "#/components/schemas/RepoReadinessScoreDto"
+
+    ReadinessFixListDto:
+      allOf:
+        - $ref: "#/components/schemas/PageMetaDto"
+        - type: object
+          required: [items]
+          properties:
+            items:
+              type: array
+              items:
+                $ref: "#/components/schemas/FixRequestDto"
+
+    AgenticFoundationDimensionAggregateDto:
+      type: object
+      required: [dimensionId, averageScorePercent, repoCount]
+      properties:
+        dimensionId:
+          $ref: "#/components/schemas/ReadinessDimensionId"
+        averageScorePercent:
+          type: integer
+          minimum: 0
+          maximum: 100
+          description: Mean dimension score percent across repos with maxScore > 0.
+        repoCount:
+          type: integer
+          minimum: 0
+          description: Repositories with a scored row for this dimension.
+
+    ReadinessFixStatusSummaryDto:
+      type: object
+      required: [queued, generating, prCreated, merged, failed, total]
+      properties:
+        queued:
+          type: integer
+          minimum: 0
+        generating:
+          type: integer
+          minimum: 0
+        prCreated:
+          type: integer
+          minimum: 0
+          description: Count of fixes with status `pr-created`.
+        merged:
+          type: integer
+          minimum: 0
+        failed:
+          type: integer
+          minimum: 0
+        total:
+          type: integer
+          minimum: 0
+
+    GithubInstalledRepoListDto:
+      allOf:
+        - $ref: "#/components/schemas/PageMetaDto"
+        - type: object
+          required: [items]
+          properties:
+            items:
+              type: array
+              items:
+                $ref: "#/components/schemas/GithubInstalledRepoDto"
+
     AgenticFoundationDashboardDto:
       type: object
-      required: [workspaceId, generatedAt, summary, repos, issueQueue]
+      required: [workspaceId, generatedAt, summary, dimensionAggregates, fixStatusSummary]
       properties:
         workspaceId:
           type: string
@@ -5169,14 +5790,13 @@ components:
           format: date-time
         summary:
           $ref: "#/components/schemas/AgenticFoundationDashboardSummaryDto"
-        repos:
-          type: array
-          items:
-            $ref: "#/components/schemas/RepoReadinessScoreDto"
-        issueQueue:
+        dimensionAggregates:
           type: array
           items:
-            $ref: "#/components/schemas/AgenticFoundationDashboardIssueDto"
+            $ref: "#/components/schemas/AgenticFoundationDimensionAggregateDto"
+          description: Per-dimension average score bars for overview UI (full workspace aggregates).
+        fixStatusSummary:
+          $ref: "#/components/schemas/ReadinessFixStatusSummaryDto"
 
     FixRequestDto:
       type: object
@@ -5613,3 +6233,219 @@ components:
         storagePath:
           type: string
           description: Path in `org-charts` bucket after Supabase upload
+
+    # ── Your AI Journey schemas ─────────────────────────────────────────────
+
+    YourAiJourneyPrSignalsWeekDto:
+      type: object
+      required: [bucketStart, bucketEnd, weekLabel, prsPerDeveloperPerWeek, changeFailureRatePercent]
+      properties:
+        bucketStart:
+          type: string
+          format: date-time
+        bucketEnd:
+          type: string
+          format: date-time
+        weekLabel:
+          type: string
+          description: Display label in MM/DD format.
+        prsPerDeveloperPerWeek:
+          type: number
+        changeFailureRatePercent:
+          type: number
+
+    YourAiJourneyPrSignalsDto:
+      type: object
+      required: [workspaceId, generatedAt, windowStart, windowEnd, weeks, summary]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        windowStart:
+          type: string
+          format: date-time
+        windowEnd:
+          type: string
+          format: date-time
+        weeks:
+          type: array
+          items:
+            $ref: "#/components/schemas/YourAiJourneyPrSignalsWeekDto"
+        summary:
+          type: object
+          required: [avgPrsPerDeveloperPerWeek, avgFailureRatePercent, prVelocityDeltaPercent]
+          properties:
+            avgPrsPerDeveloperPerWeek:
+              type: number
+            avgFailureRatePercent:
+              type: number
+            prVelocityDeltaPercent:
+              type: number
+
+    YourAiJourneyReadinessDimensionDto:
+      type: object
+      required: [dimensionId, name, totalScore, maxScore, percent]
+      properties:
+        dimensionId:
+          type: string
+        name:
+          type: string
+        totalScore:
+          type: number
+        maxScore:
+          type: number
+        percent:
+          type: number
+          description: Rounded percentage 0–100.
+
+    YourAiJourneyReadinessAggregateDto:
+      type: object
+      required: [workspaceId, generatedAt, dimensions, summary]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        dimensions:
+          type: array
+          items:
+            $ref: "#/components/schemas/YourAiJourneyReadinessDimensionDto"
+        summary:
+          type: object
+          required: [avgScore, repoCount, fixRate, totalOpenIssues, totalFixedIssues]
+          properties:
+            avgScore:
+              type: number
+            repoCount:
+              type: integer
+            fixRate:
+              type: number
+            totalOpenIssues:
+              type: integer
+            totalFixedIssues:
+              type: integer
+
+    YourAiJourneyAnalyticsDto:
+      type: object
+      required: [workspaceId, generatedAt, windowStart, windowEnd, journey, readiness, prSignals]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        windowStart:
+          type: string
+          format: date-time
+        windowEnd:
+          type: string
+          format: date-time
+        journey:
+          type: object
+          required: [completedSteps, updatedAt]
+          properties:
+            completedSteps:
+              type: array
+              items:
+                type: string
+            updatedAt:
+              type: string
+              format: date-time
+              nullable: true
+        readiness:
+          type: object
+          required: [avgScore, repoCount, fixRate, totalOpenIssues, totalFixedIssues]
+          properties:
+            avgScore:
+              type: number
+            repoCount:
+              type: integer
+            fixRate:
+              type: number
+            totalOpenIssues:
+              type: integer
+            totalFixedIssues:
+              type: integer
+        prSignals:
+          type: object
+          required: [avgPrsPerDeveloperPerWeek, prVelocityDeltaPercent, avgFailureRatePercent]
+          properties:
+            avgPrsPerDeveloperPerWeek:
+              type: number
+            prVelocityDeltaPercent:
+              type: number
+            avgFailureRatePercent:
+              type: number
+
+    YourAiJourneyAiSpendWeekDto:
+      type: object
+      required: [bucketStart, bucketEnd, weekLabel, mergedPrCount, tokenCount]
+      properties:
+        bucketStart:
+          type: string
+          format: date-time
+        bucketEnd:
+          type: string
+          format: date-time
+        weekLabel:
+          type: string
+        mergedPrCount:
+          type: integer
+        tokenCount:
+          type: integer
+
+    YourAiJourneyAiSpendDto:
+      type: object
+      required: [workspaceId, generatedAt, windowStart, windowEnd, totalSpendCents, totalTokenCount, activeUsers, aiAssistedPrRatio, prThroughputDeltaPercent, usageDeltaPercent, weeks, providers]
+      properties:
+        workspaceId:
+          type: string
+          format: uuid
+        generatedAt:
+          type: string
+          format: date-time
+        windowStart:
+          type: string
+          format: date-time
+        windowEnd:
+          type: string
+          format: date-time
+        totalSpendCents:
+          type: integer
+        totalTokenCount:
+          type: integer
+        activeUsers:
+          type: integer
+        aiAssistedPrRatio:
+          type: number
+          description: Fraction 0–1 of PRs that are AI-assisted.
+        prThroughputDeltaPercent:
+          type: number
+        usageDeltaPercent:
+          type: number
+        weeks:
+          type: array
+          items:
+            $ref: "#/components/schemas/YourAiJourneyAiSpendWeekDto"
+        providers:
+          type: array
+          items:
+            type: object
+            required: [providerId, providerName, tokenCount, spendCents, activeUsers]
+            properties:
+              providerId:
+                type: string
+              providerName:
+                type: string
+              tokenCount:
+                type: integer
+              spendCents:
+                type: integer
+              activeUsers:
+                type: integer