@thinkai/tai-api-contract 1.0.0

package/openapi/openapi.yaml

@@ -0,0 +1,2277 @@
+openapi: 3.0.3
+info:
+  title: ThinkAI API
+  version: 0.16.0
+  description: >
+    Contract surface for the Performance Intelligence Platform backend used by ThinkAI.
+    Tenant-scoped routes use `/tenants/{tenantId}/...` and require membership.
+    Admin routes use `/admin/...` and require role `admin`.
+    Legacy HTTP routes that exist on the server but are not listed here (for example
+    `PUT /tenants/{tenantId}/dashboard-settings`) remain supported for existing PIP clients;
+    prefer OpenAPI-documented equivalents where available. Removal will be coordinated with ThinkAI releases.
+security:
+  - bearerAuth: []
+tags:
+  - name: Tenant
+    description: Workspace bootstrap (§13)
+  - name: CompanyProfile
+    description: Company profile (§1)
+  - name: AIReadiness
+    description: AI readiness assessment (§2)
+  - name: TechStack
+    description: Tech stack (§3)
+  - name: NDA
+    description: NDA flows (§4, §14 storagePath)
+  - name: RepositoryReadiness
+    description: Repository readiness (§5)
+  - name: SquadProjects
+    description: Squad and projects (§6)
+  - name: Notifications
+    description: Notifications (§7)
+  - name: AdminReviewer
+    description: Admin review queue (§8)
+  - name: AIStrategy
+    description: AI strategy recommendations (§9)
+  - name: Journey
+    description: Journey progress (§10)
+  - name: Me
+    description: Authenticated user profile (§11)
+  - name: Preferences
+    description: Per-user per-tenant preferences (§12)
+  - name: OrgChartImport
+    description: Org chart import via storage path (§14)
+
+paths:
+  /tenants:
+    post:
+      tags: [Tenant]
+      summary: Create tenant
+      operationId: createTenant
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateTenantBodyDto"
+      responses:
+        "201":
+          description: Tenant created or acknowledged (idempotent; same body if already existed)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreateTenantResponseDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /me:
+    get:
+      tags: [Me]
+      summary: Current user profile
+      operationId: getMe
+      responses:
+        "200":
+          description: Profile
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MeProfileDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    put:
+      tags: [Me]
+      summary: Update current user profile
+      operationId: updateMe
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateMeBodyDto"
+      responses:
+        "204":
+          description: Updated
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /me/workspaces:
+    get:
+      tags: [Me]
+      summary: Workspaces visible to the authenticated user
+      operationId: listMyWorkspaces
+      responses:
+        "200":
+          description: Workspace list for switcher
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspacesForUserDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces:
+    post:
+      tags: [Tenant]
+      summary: Create workspace
+      operationId: createWorkspace
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateWorkspaceBodyDto"
+      responses:
+        "201":
+          description: Workspace created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceSummaryDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/organization:
+    get:
+      tags: [CompanyProfile]
+      summary: Get workspace organization profile
+      operationId: getWorkspaceOrganization
+      parameters:
+        - name: workspaceId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: Organization profile or null if unset
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OrganizationDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    put:
+      tags: [CompanyProfile]
+      summary: Upsert workspace organization profile
+      operationId: putWorkspaceOrganization
+      parameters:
+        - name: workspaceId
+          in: path
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OrganizationDto"
+      responses:
+        "204":
+          description: Updated
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/members:
+    get:
+      tags: [Tenant]
+      summary: List tenant team members
+      operationId: listTenantMembers
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      responses:
+        "200":
+          description: Team members for tenant
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TeamMemberListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /tenants/{tenantId}/members/invite:
+    post:
+      tags: [Tenant]
+      summary: Invite member to tenant
+      operationId: inviteTenantMember
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/InviteTeamMemberBodyDto"
+      responses:
+        "201":
+          description: Invited member row
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TeamMemberDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /tenants/{tenantId}/members/{memberId}:
+    patch:
+      tags: [Tenant]
+      summary: Update tenant member role
+      operationId: updateTenantMemberRole
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - name: memberId
+          in: path
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/UpdateTeamMemberRoleBodyDto"
+      responses:
+        "200":
+          description: Updated member row
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TeamMemberDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Member not found
+    delete:
+      tags: [Tenant]
+      summary: Remove member from tenant
+      operationId: removeTenantMember
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - name: memberId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        "204":
+          description: Removed
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Member not found
+
+  /tenants/{tenantId}/org-chart:
+    get:
+      tags: [Tenant]
+      summary: Get org chart tree
+      operationId: getTenantOrgChart
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - name: withScores
+          in: query
+          schema: { type: boolean }
+      responses:
+        "200":
+          description: Org chart (optionally with per-node scores)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OrgChartDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Tenant not found
+    post:
+      tags: [Tenant]
+      summary: Save org chart tree
+      operationId: postTenantOrgChart
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OrgChartDto"
+      responses:
+        "200":
+          description: Saved
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, tenantId]
+                properties:
+                  ok: { type: boolean }
+                  tenantId: { type: string }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/sources:
+    put:
+      tags: [Tenant]
+      summary: Replace tenant data sources
+      operationId: putTenantSources
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [sources]
+              properties:
+                sources:
+                  type: array
+                  items:
+                    $ref: "#/components/schemas/TenantSourceEntryDto"
+      responses:
+        "200":
+          description: Saved
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, tenantId]
+                properties:
+                  ok: { type: boolean }
+                  tenantId: { type: string }
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/sources/test:
+    post:
+      tags: [Tenant]
+      summary: Test one source connection (does not persist)
+      operationId: postTenantSourceTest
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/TenantSourceEntryDto"
+      responses:
+        "200":
+          description: Connection test result
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TestConnectionResponseDto"
+        "400":
+          description: Invalid body or missing env for token refs
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/dashboard/productivity:
+    get:
+      tags: [Tenant]
+      summary: CTO dashboard productivity snapshot
+      operationId: getDashboardProductivity
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - name: scope
+          in: query
+          schema:
+            type: string
+            enum: [org, team, person]
+        - name: teamId
+          in: query
+          schema: { type: string }
+        - name: personId
+          in: query
+          schema: { type: string }
+        - name: windowEnd
+          in: query
+          schema: { type: string, format: date-time }
+      responses:
+        "200":
+          description: Productivity metrics
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DashboardProductivityDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/dashboard/productivity/history:
+    get:
+      tags: [Tenant]
+      summary: CTO dashboard productivity time series
+      operationId: getDashboardProductivityHistory
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - name: bucket
+          in: query
+          schema: { type: string, enum: [day, week, month] }
+        - name: limit
+          in: query
+          schema: { type: integer, minimum: 1 }
+        - name: scope
+          in: query
+          schema:
+            type: string
+            enum: [org, team, person]
+        - name: teamId
+          in: query
+          schema: { type: string }
+        - name: personId
+          in: query
+          schema: { type: string }
+        - name: windowEnd
+          in: query
+          schema: { type: string, format: date-time }
+      responses:
+        "200":
+          description: Bucketed history
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/DashboardProductivityHistoryDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /admin/reviews:
+    get:
+      tags: [AdminReviewer]
+      summary: Admin review queue
+      operationId: listAdminReviews
+      parameters:
+        - name: status
+          in: query
+          schema: { type: string }
+        - name: priority
+          in: query
+          schema: { type: string }
+        - name: reviewer
+          in: query
+          schema: { type: string }
+      responses:
+        "200":
+          description: Queue and reviewer list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AdminDashboardDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /admin/reviews/{id}:
+    get:
+      tags: [AdminReviewer]
+      summary: Single review submission
+      operationId: getAdminReview
+      parameters:
+        - $ref: "#/components/parameters/ReviewId"
+      responses:
+        "200":
+          description: Review detail
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReviewSubmissionDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    patch:
+      tags: [AdminReviewer]
+      summary: Update review metadata
+      operationId: patchAdminReview
+      parameters:
+        - $ref: "#/components/parameters/ReviewId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PatchAdminReviewBodyDto"
+      responses:
+        "200":
+          description: Updated review
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReviewSubmissionDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /admin/reviews/{id}/sections/{sectionId}/comments:
+    post:
+      tags: [AdminReviewer]
+      summary: Add section comment
+      operationId: postAdminReviewComment
+      parameters:
+        - $ref: "#/components/parameters/ReviewId"
+        - $ref: "#/components/parameters/SectionId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AdminCommentBodyDto"
+      responses:
+        "200":
+          description: Created comment
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CommentDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /admin/reviews/{id}/sections/{sectionId}/decision:
+    put:
+      tags: [AdminReviewer]
+      summary: Set section decision
+      operationId: putAdminReviewSectionDecision
+      parameters:
+        - $ref: "#/components/parameters/ReviewId"
+        - $ref: "#/components/parameters/SectionId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SectionDecisionBodyDto"
+      responses:
+        "204":
+          description: Saved
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /admin/reviews/{id}/pricing:
+    put:
+      tags: [AdminReviewer]
+      summary: Update pricing lines
+      operationId: putAdminReviewPricing
+      parameters:
+        - $ref: "#/components/parameters/ReviewId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PricingUpdateBodyDto"
+      responses:
+        "204":
+          description: Saved
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /admin/reviews/{id}/deployment:
+    put:
+      tags: [AdminReviewer]
+      summary: Update deployment plan
+      operationId: putAdminReviewDeployment
+      parameters:
+        - $ref: "#/components/parameters/ReviewId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/DeploymentPlanDto"
+      responses:
+        "204":
+          description: Saved
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
+  /tenants/{tenantId}/company-profile:
+    get:
+      tags: [CompanyProfile]
+      summary: Get company profile
+      operationId: getCompanyProfile
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      responses:
+        "200":
+          description: Profile or JSON null if unset
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CompanyProfileDto"
+              examples:
+                sample:
+                  value:
+                    companyName: Acme
+                    industry: software
+                    companySize: "51-200"
+                    engineeringHC: "42"
+                    headquarters: "Austin, TX"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    put:
+      tags: [CompanyProfile]
+      summary: Upsert company profile
+      operationId: putCompanyProfile
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CompanyProfileDto"
+      responses:
+        "204":
+          description: Saved
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/ai-readiness:
+    get:
+      tags: [AIReadiness]
+      summary: Get AI readiness
+      operationId: getAiReadiness
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      responses:
+        "200":
+          description: State or JSON null
+          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/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AIReadinessDto"
+      responses:
+        "204":
+          description: Saved
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/ai-readiness/maturity:
+    post:
+      tags: [AIReadiness]
+      summary: Compute maturity level
+      operationId: postAiReadinessMaturity
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AIReadinessDto"
+      responses:
+        "200":
+          description: Derived level
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AiMaturityResultDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/tech-stack:
+    get:
+      tags: [TechStack]
+      summary: Get tech stack
+      operationId: getTechStack
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      responses:
+        "200":
+          description: Stack or JSON null
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/TechStackDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    put:
+      tags: [TechStack]
+      summary: Upsert tech stack
+      operationId: putTechStack
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/TechStackDto"
+      responses:
+        "204":
+          description: Saved
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/nda:
+    get:
+      tags: [NDA]
+      summary: Get NDA completion state
+      operationId: getNda
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      responses:
+        "200":
+          description: Completion or JSON null
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NdaCompletionDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/nda/template:
+    get:
+      tags: [NDA]
+      summary: NDA template for display
+      operationId: getNdaTemplate
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      responses:
+        "200":
+          description: Template
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NdaTemplateDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/nda/sign:
+    post:
+      tags: [NDA]
+      summary: Electronic NDA signature
+      operationId: postNdaSign
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/NdaSignatureDto"
+      responses:
+        "200":
+          description: Completion record
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/NdaCompletionDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/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/TenantId"
+      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"
+
+  /tenants/{tenantId}/readiness/repos:
+    get:
+      tags: [RepositoryReadiness]
+      summary: List repo readiness scores
+      operationId: listReadinessRepos
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      responses:
+        "200":
+          description: Repositories analyzed
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/readiness/repos/{repoId}:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Single repo readiness
+      operationId: getReadinessRepo
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - $ref: "#/components/parameters/RepoId"
+      responses:
+        "200":
+          description: Repo score
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RepoReadinessScoreDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/readiness/dimensions:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Readiness dimensions catalog
+      operationId: listReadinessDimensions
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      responses:
+        "200":
+          description: Dimensions
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/ReadinessDimensionDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/readiness/fixes:
+    get:
+      tags: [RepositoryReadiness]
+      summary: List fix requests
+      operationId: listReadinessFixes
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      responses:
+        "200":
+          description: Fix queue
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/FixRequestDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    post:
+      tags: [RepositoryReadiness]
+      summary: Enqueue fix for an issue
+      operationId: postReadinessFix
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateFixRequestBodyDto"
+      responses:
+        "200":
+          description: Fix request created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/FixRequestDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/squad:
+    get:
+      tags: [SquadProjects]
+      summary: Get squad configuration
+      operationId: getSquad
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      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/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SquadDto"
+      responses:
+        "204":
+          description: Saved
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/projects:
+    get:
+      tags: [SquadProjects]
+      summary: List projects
+      operationId: listProjects
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      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/TenantId"
+      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"
+
+  /tenants/{tenantId}/projects/{projectId}:
+    patch:
+      tags: [SquadProjects]
+      summary: Update project
+      operationId: patchProject
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - $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"
+
+  /tenants/{tenantId}/notifications:
+    get:
+      tags: [Notifications]
+      summary: Paginated notifications
+      operationId: listNotifications
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - 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"
+
+  /tenants/{tenantId}/notifications/{id}/read:
+    post:
+      tags: [Notifications]
+      summary: Mark notification read
+      operationId: postNotificationRead
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+        - $ref: "#/components/parameters/NotificationId"
+      responses:
+        "204":
+          description: Updated
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/notifications/read-all:
+    post:
+      tags: [Notifications]
+      summary: Mark all notifications read
+      operationId: postNotificationsReadAll
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      responses:
+        "204":
+          description: Updated
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/ai-strategy/recommend:
+    post:
+      tags: [AIStrategy]
+      summary: Generate AI strategy recommendations
+      operationId: postAiStrategyRecommend
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      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"
+
+  /tenants/{tenantId}/journey/progress:
+    get:
+      tags: [Journey]
+      summary: Journey step completion
+      operationId: getJourneyProgress
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      responses:
+        "200":
+          description: Progress
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JourneyProgressDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    put:
+      tags: [Journey]
+      summary: Replace completed steps
+      operationId: putJourneyProgress
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/JourneyProgressUpdateDto"
+      responses:
+        "204":
+          description: Saved
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/me/preferences:
+    get:
+      tags: [Preferences]
+      summary: Get preferences for current user in tenant
+      operationId: getMyPreferences
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      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
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PreferencesDto"
+      responses:
+        "204":
+          description: Saved
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /tenants/{tenantId}/org-chart/import:
+    post:
+      tags: [OrgChartImport]
+      summary: Import org chart from Supabase storage path
+      operationId: postOrgChartImport
+      parameters:
+        - $ref: "#/components/parameters/TenantId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OrgChartImportBodyDto"
+      responses:
+        "200":
+          description: Parsed persons (shape TBD; align with backend)
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: true
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: Supabase access token (`Authorization` header).
+
+  parameters:
+    TenantId:
+      name: tenantId
+      in: path
+      required: true
+      schema:
+        type: string
+    RepoId:
+      name: repoId
+      in: path
+      required: true
+      schema:
+        type: string
+    ProjectId:
+      name: projectId
+      in: path
+      required: true
+      schema:
+        type: string
+    ReviewId:
+      name: id
+      in: path
+      required: true
+      schema:
+        type: string
+    SectionId:
+      name: sectionId
+      in: path
+      required: true
+      schema:
+        type: string
+    NotificationId:
+      name: id
+      in: path
+      required: true
+      schema:
+        type: string
+
+  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
+
+    CreateTenantBodyDto:
+      type: object
+      required: [tenantId]
+      properties:
+        tenantId:
+          type: string
+
+    CreateTenantResponseDto:
+      type: object
+      required: [tenantId, ok]
+      properties:
+        tenantId:
+          type: string
+        ok:
+          type: boolean
+
+    TeamMemberRoleDto:
+      type: string
+      enum: [admin, editor, viewer]
+
+    TeamMemberDto:
+      type: object
+      required: [id, name, email, role]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        email:
+          type: string
+        role:
+          $ref: "#/components/schemas/TeamMemberRoleDto"
+
+    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:
+          $ref: "#/components/schemas/TeamMemberRoleDto"
+
+    UpdateTeamMemberRoleBodyDto:
+      type: object
+      required: [role]
+      properties:
+        role:
+          $ref: "#/components/schemas/TeamMemberRoleDto"
+
+    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"
+
+    OrgChartDto:
+      type: object
+      required: [root]
+      properties:
+        root:
+          $ref: "#/components/schemas/OrgChartTreeNodeDto"
+
+    TenantSourceEntryDto:
+      type: object
+      required: [type]
+      properties:
+        type:
+          type: string
+      additionalProperties: true
+
+    TestConnectionResponseDto:
+      type: object
+      required: [success]
+      properties:
+        success:
+          type: boolean
+        error:
+          type: string
+
+    DashboardProductivityMetricsDto:
+      type: object
+      description: Nested metric groups; see TypeScript `DashboardProductivityMetricsDto` in @thinkai/tai-api-contract.
+      additionalProperties: true
+
+    DashboardProductivityDto:
+      type: object
+      required: [tenantId, windowStart, windowEnd, scope, metrics]
+      properties:
+        tenantId:
+          type: string
+        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: [buckets]
+      properties:
+        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"
+
+    MeProfileDto:
+      type: object
+      required: [id, email, name, roles]
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+        name:
+          type: string
+        roles:
+          type: array
+          items:
+            type: string
+        defaultWorkspaceId:
+          type: string
+          nullable: true
+
+    UpdateMeBodyDto:
+      type: object
+      properties:
+        name:
+          type: string
+        email:
+          type: string
+        defaultWorkspaceId:
+          type: string
+          nullable: true
+
+    WorkspaceSummaryDto:
+      type: object
+      required: [id, slug, name, status]
+      properties:
+        id:
+          type: string
+        slug:
+          type: string
+        name:
+          type: string
+        status:
+          type: string
+
+    WorkspacesForUserDto:
+      type: object
+      required: [workspaces]
+      properties:
+        workspaces:
+          type: array
+          items:
+            $ref: "#/components/schemas/WorkspaceSummaryDto"
+
+    CreateWorkspaceBodyDto:
+      type: object
+      required: [slug, name]
+      properties:
+        slug:
+          type: string
+        name:
+          type: string
+
+    OrganizationDto:
+      type: object
+      required: [workspaceId, legalName]
+      properties:
+        workspaceId:
+          type: string
+        legalName:
+          type: string
+        industry:
+          type: string
+        companySize:
+          type: string
+        engineeringHeadcount:
+          type: integer
+          nullable: true
+        headquarters:
+          type: string
+        metadata:
+          type: object
+          additionalProperties: true
+
+    CompanyProfileDto:
+      type: object
+      required: [companyName, industry, companySize, engineeringHC, headquarters]
+      properties:
+        companyName:
+          type: string
+        industry:
+          type: string
+        industryOther:
+          type: string
+        companySize:
+          type: string
+          description: "One of 1-50 | 51-200 | 201-500 | 501-1000 | 1000+"
+        engineeringHC:
+          type: string
+        headquarters:
+          type: string
+
+    AIReadinessDto:
+      type: object
+      required:
+        - currentUsage
+        - tools
+        - satisfaction
+        - painPointPhases
+        - maturityLevel
+        - maturityConfirmed
+      properties:
+        currentUsage:
+          type: string
+        tools:
+          type: array
+          items:
+            type: string
+        customTools:
+          type: string
+        models:
+          type: string
+        spend:
+          type: string
+        satisfaction:
+          type: integer
+          minimum: 0
+          maximum: 5
+        painPointPhases:
+          type: array
+          items:
+            type: string
+        maturityLevel:
+          type: integer
+          minimum: -1
+          maximum: 4
+        maturityConfirmed:
+          type: boolean
+          nullable: true
+        challenges:
+          type: string
+        goals:
+          type: string
+
+    AiMaturityResultDto:
+      type: object
+      required: [level, needsConfirmation]
+      properties:
+        level:
+          type: integer
+          minimum: 0
+          maximum: 4
+        needsConfirmation:
+          type: boolean
+
+    TechCategoryDto:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items:
+            type: string
+
+    TechStackDto:
+      type: object
+      required: [sourceControl, cicd, pm, monitoring, knowledgeDocs, hrPeople]
+      properties:
+        sourceControl:
+          $ref: "#/components/schemas/TechCategoryDto"
+        cicd:
+          $ref: "#/components/schemas/TechCategoryDto"
+        pm:
+          type: object
+          required: [items, methodology, sprintLength]
+          properties:
+            items:
+              type: array
+              items:
+                type: string
+            methodology:
+              type: string
+            sprintLength:
+              type: string
+        monitoring:
+          $ref: "#/components/schemas/TechCategoryDto"
+        knowledgeDocs:
+          $ref: "#/components/schemas/TechCategoryDto"
+        hrPeople:
+          $ref: "#/components/schemas/TechCategoryDto"
+
+    NdaTemplateDto:
+      type: object
+      required: [title, body]
+      properties:
+        title:
+          type: string
+        body:
+          type: array
+          items:
+            type: string
+
+    NdaSignatureDto:
+      type: object
+      required: [fullName, date, ipAddress, signed]
+      properties:
+        fullName:
+          type: string
+        date:
+          type: string
+        ipAddress:
+          type: string
+        signed:
+          type: boolean
+        electronicAcknowledgements:
+          type: object
+          additionalProperties:
+            type: boolean
+
+    NdaUploadedDocumentDto:
+      type: object
+      required: [fileName, mimeType, size, uploadedAt]
+      properties:
+        fileName:
+          type: string
+        mimeType:
+          type: string
+        size:
+          type: integer
+        uploadedAt:
+          type: string
+        dataUrl:
+          type: string
+
+    NdaCompletionDto:
+      oneOf:
+        - $ref: "#/components/schemas/NdaCompletionElectronicDto"
+        - $ref: "#/components/schemas/NdaCompletionExternalDto"
+      discriminator:
+        propertyName: mode
+        mapping:
+          electronic: "#/components/schemas/NdaCompletionElectronicDto"
+          external: "#/components/schemas/NdaCompletionExternalDto"
+
+    NdaCompletionElectronicDto:
+      type: object
+      required: [mode, signature]
+      properties:
+        mode:
+          type: string
+          enum: [electronic]
+        signature:
+          $ref: "#/components/schemas/NdaSignatureDto"
+
+    NdaCompletionExternalDto:
+      type: object
+      required: [mode, attestedAt, confirmedBy, confirmed, personalDataDpaAck, uploadedDocument]
+      properties:
+        mode:
+          type: string
+          enum: [external]
+        attestedAt:
+          type: string
+        confirmedBy:
+          type: string
+        confirmed:
+          type: boolean
+          enum: [true]
+        personalDataDpaAck:
+          type: boolean
+          enum: [true]
+        uploadedDocument:
+          $ref: "#/components/schemas/NdaUploadedDocumentDto"
+
+    NdaExternalBodyDto:
+      type: object
+      required: [confirmedBy, personalDataDpaAck, storagePath]
+      properties:
+        confirmedBy:
+          type: string
+        personalDataDpaAck:
+          type: boolean
+        storagePath:
+          type: string
+          description: Path in `nda-documents` bucket after Supabase upload
+
+    ReadinessDimensionDto:
+      type: object
+      required: [id, name, description, maxScore]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        maxScore:
+          type: number
+
+    ReadinessIssueDto:
+      type: object
+      required: [id, dimensionId, severity, title, description, fixStatus]
+      properties:
+        id:
+          type: string
+        dimensionId:
+          type: string
+        severity:
+          type: string
+          enum: [critical, high, medium, low]
+        title:
+          type: string
+        description:
+          type: string
+        filePath:
+          type: string
+        fixStatus:
+          type: string
+          enum: [open, pr-pending, fixed]
+
+    DimensionScoreDto:
+      type: object
+      required: [dimensionId, score, maxScore, issues]
+      properties:
+        dimensionId:
+          type: string
+        score:
+          type: number
+        maxScore:
+          type: number
+        issues:
+          type: array
+          items:
+            $ref: "#/components/schemas/ReadinessIssueDto"
+
+    RepoReadinessScoreDto:
+      type: object
+      required: [repoId, repoName, language, overallScore, dimensions, lastAnalyzed]
+      properties:
+        repoId:
+          type: string
+        repoName:
+          type: string
+        language:
+          type: string
+        overallScore:
+          type: number
+        dimensions:
+          type: array
+          items:
+            $ref: "#/components/schemas/DimensionScoreDto"
+        lastAnalyzed:
+          type: string
+          format: date-time
+        teamId:
+          type: string
+
+    FixRequestDto:
+      type: object
+      required: [id, issueId, repoId, repoName, issueTitle, dimensionId, severity, status, createdAt]
+      properties:
+        id:
+          type: string
+        issueId:
+          type: string
+        repoId:
+          type: string
+        repoName:
+          type: string
+        issueTitle:
+          type: string
+        dimensionId:
+          type: string
+        severity:
+          type: string
+          enum: [critical, high, medium, low]
+        status:
+          type: string
+          enum: [queued, generating, pr-created, merged]
+        prUrl:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+
+    CreateFixRequestBodyDto:
+      type: object
+      required: [issueId, repoId]
+      properties:
+        issueId:
+          type: string
+        repoId:
+          type: string
+
+    PhaseRoleDto:
+      type: object
+      required: [phase, assignment]
+      properties:
+        phase:
+          type: string
+        assignment:
+          type: string
+          enum: [orchestrate, review, both, none]
+
+    SquadMemberDto:
+      type: object
+      required: [id, role, roleLabel, description, count, phases]
+      properties:
+        id:
+          type: string
+        role:
+          type: string
+        roleLabel:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        count:
+          type: integer
+        phases:
+          type: array
+          items:
+            $ref: "#/components/schemas/PhaseRoleDto"
+        custom:
+          type: boolean
+
+    CustomWorkStreamTaskDto:
+      type: object
+      required: [id, name, summary]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        summary:
+          type: string
+
+    PhaseWorkStreamConfigDto:
+      type: object
+      properties:
+        deselectedCatalogIds:
+          type: array
+          items:
+            type: string
+        customTasks:
+          type: array
+          items:
+            $ref: "#/components/schemas/CustomWorkStreamTaskDto"
+
+    SquadDto:
+      type: object
+      required: [members, hrConnected]
+      properties:
+        members:
+          type: array
+          items:
+            $ref: "#/components/schemas/SquadMemberDto"
+        hrConnected:
+          type: boolean
+        selectedPhases:
+          type: array
+          items:
+            type: string
+        phaseWorkStreams:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/PhaseWorkStreamConfigDto"
+
+    WorkflowDto:
+      type: object
+      required: [id, name, kinds, typeDescription, roles]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        kinds:
+          type: array
+          items:
+            type: string
+            enum: [greenfield, brownfield]
+        typeDescription:
+          type: string
+        roles:
+          type: array
+          items:
+            type: string
+
+    ProjectDto:
+      type: object
+      required: [id, name, description, startDate, workflows, createdAt]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        startDate:
+          type: string
+        workflows:
+          type: array
+          items:
+            $ref: "#/components/schemas/WorkflowDto"
+        createdAt:
+          type: string
+          format: date-time
+
+    ProjectPatchDto:
+      type: object
+      description: Partial update; all properties optional
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        description:
+          type: string
+        startDate:
+          type: string
+        workflows:
+          type: array
+          items:
+            $ref: "#/components/schemas/WorkflowDto"
+        createdAt:
+          type: string
+          format: date-time
+
+    NotificationDto:
+      type: object
+      required: [id, type, title, message, read, createdAt]
+      properties:
+        id:
+          type: string
+        type:
+          type: string
+          enum: [status, comment, activity, integration, system]
+        title:
+          type: string
+        message:
+          type: string
+        read:
+          type: boolean
+        createdAt:
+          type: string
+          format: date-time
+        route:
+          type: string
+
+    NotificationListDto:
+      type: object
+      required: [items, total]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/components/schemas/NotificationDto"
+        total:
+          type: integer
+
+    ReviewQueueItemDto:
+      type: object
+      required: [id, client, project, workflows, submittedAt, reviewer, status, priority]
+      properties:
+        id:
+          type: string
+        client:
+          type: string
+        project:
+          type: string
+        workflows:
+          type: array
+          items:
+            type: string
+            enum: [greenfield, brownfield]
+        submittedAt:
+          type: string
+          format: date-time
+        reviewer:
+          type: string
+          nullable: true
+        status:
+          type: string
+          enum: [pending, in_review, approved, changes_requested]
+        priority:
+          type: string
+          enum: [high, medium, low]
+
+    AdminDashboardDto:
+      type: object
+      required: [queue, reviewers]
+      properties:
+        queue:
+          type: array
+          items:
+            $ref: "#/components/schemas/ReviewQueueItemDto"
+        reviewers:
+          type: array
+          items:
+            type: string
+
+    PatchAdminReviewBodyDto:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [pending, in_review, approved, changes_requested]
+        reviewer:
+          type: string
+        priority:
+          type: string
+          enum: [high, medium, low]
+
+    CommentDto:
+      type: object
+      required: [id, sectionId, author, text, timestamp]
+      properties:
+        id:
+          type: string
+        sectionId:
+          type: string
+        author:
+          type: string
+        text:
+          type: string
+        timestamp:
+          type: string
+          format: date-time
+
+    AdminCommentBodyDto:
+      type: object
+      required: [text]
+      properties:
+        text:
+          type: string
+
+    SectionDecisionBodyDto:
+      type: object
+      required: [decision]
+      properties:
+        decision:
+          type: string
+          enum: [pending, approved, changes_requested, rejected]
+
+    PricingLineDto:
+      type: object
+      required: [id, label, rate, hours]
+      properties:
+        id:
+          type: string
+        label:
+          type: string
+        rate:
+          type: number
+        hours:
+          type: number
+
+    PricingUpdateBodyDto:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items:
+            type: object
+            required: [id, rate, hours]
+            properties:
+              id:
+                type: string
+              rate:
+                type: number
+              hours:
+                type: number
+
+    DeploymentPlanDto:
+      type: object
+      required: [startDate, endDate, milestones]
+      properties:
+        startDate:
+          type: string
+        endDate:
+          type: string
+        milestones:
+          type: array
+          items:
+            type: string
+
+    ReviewSectionDto:
+      type: object
+      required: [id, label, detail, decision, comments]
+      properties:
+        id:
+          type: string
+        label:
+          type: string
+        detail:
+          type: string
+        decision:
+          type: string
+          enum: [pending, approved, changes_requested, rejected]
+        comments:
+          type: array
+          items:
+            $ref: "#/components/schemas/CommentDto"
+
+    ReviewSubmissionDto:
+      type: object
+      required:
+        - id
+        - client
+        - project
+        - workflows
+        - status
+        - isResubmission
+        - context
+        - sections
+        - pricing
+        - deployment
+      properties:
+        id:
+          type: string
+        client:
+          type: string
+        project:
+          type: string
+        workflows:
+          type: array
+          items:
+            type: string
+            enum: [greenfield, brownfield]
+        status:
+          type: string
+          enum: [pending, in_review, approved, changes_requested]
+        isResubmission:
+          type: boolean
+        context:
+          type: array
+          items:
+            type: object
+            required: [text]
+            properties:
+              text:
+                type: string
+        sections:
+          type: array
+          items:
+            $ref: "#/components/schemas/ReviewSectionDto"
+        pricing:
+          type: array
+          items:
+            $ref: "#/components/schemas/PricingLineDto"
+        deployment:
+          $ref: "#/components/schemas/DeploymentPlanDto"
+
+    EffectiveTaskRowDto:
+      type: object
+      required: [id, name, summary, source]
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        summary:
+          type: string
+        source:
+          type: string
+          enum: [catalog, custom]
+
+    EffectivePhaseTasksBlockDto:
+      type: object
+      required: [phaseName, icon, tasks]
+      properties:
+        phaseName:
+          type: string
+        icon:
+          type: string
+        tasks:
+          type: array
+          items:
+            $ref: "#/components/schemas/EffectiveTaskRowDto"
+
+    AiStrategyRecommendBodyDto:
+      type: object
+      required: [phases]
+      properties:
+        phases:
+          type: array
+          items:
+            $ref: "#/components/schemas/EffectivePhaseTasksBlockDto"
+
+    AiStrategyTaskRecommendationDto:
+      type: object
+      required: [taskId, taskName, summary, source, tool, engagement]
+      properties:
+        taskId:
+          type: string
+        taskName:
+          type: string
+        summary:
+          type: string
+        source:
+          type: string
+          enum: [catalog, custom]
+        tool:
+          type: string
+        engagement:
+          type: string
+          enum: [AI assisted, AI delegated]
+        rationale:
+          type: string
+
+    AiStrategyPhaseBlockDto:
+      type: object
+      required: [phaseName, icon, tasks]
+      properties:
+        phaseName:
+          type: string
+        icon:
+          type: string
+        tasks:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiStrategyTaskRecommendationDto"
+
+    AiStrategyPlanDto:
+      type: object
+      required: [phases]
+      properties:
+        phases:
+          type: array
+          items:
+            $ref: "#/components/schemas/AiStrategyPhaseBlockDto"
+
+    JourneyProgressDto:
+      type: object
+      required: [completedSteps, updatedAt]
+      properties:
+        completedSteps:
+          type: array
+          items:
+            type: string
+        updatedAt:
+          type: string
+          format: date-time
+
+    JourneyProgressUpdateDto:
+      type: object
+      required: [completedSteps]
+      properties:
+        completedSteps:
+          type: array
+          items:
+            type: string
+
+    PreferencesDto:
+      type: object
+      required: [theme, sidebarCollapsed, timezone, notifications]
+      properties:
+        theme:
+          type: string
+          enum: [light, dark, system]
+        sidebarCollapsed:
+          type: boolean
+        timezone:
+          type: string
+          description: IANA timezone name
+        notifications:
+          type: object
+          required: [status, comment, activity, system]
+          properties:
+            status:
+              type: boolean
+            comment:
+              type: boolean
+            activity:
+              type: boolean
+            system:
+              type: boolean
+
+    OrgChartImportBodyDto:
+      type: object
+      required: [storagePath]
+      properties:
+        storagePath:
+          type: string
+          description: Path in `org-charts` bucket after Supabase upload