@thinkai/tai-api-contract 2.77.0 → 2.78.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.77.0
+  version: 2.78.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -73,6 +73,11 @@ tags:
     description: >
       Data subject access / erasure / portability request intake and privacy-ops management (DSAR, issue #611).
       Public and authenticated submission; platform-admin queue, export, and fulfillment.
+  - name: CodeChat
+    description: >
+      Standalone Code Chat for indexed GitHub repositories from the readiness repo list.
+      Indexes via Graphify when available, otherwise a builtin file/symbol graph; answers via graph
+      retrieval plus the workspace agent execution key (Claude or Cursor).
   - name: Platform
     description: Platform-wide banner surfaces (global outage/maintenance banner, issue #284).
 
@@ -6743,17 +6748,544 @@ paths:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Squad
+          description: Squad
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SquadDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    put:
+      tags: [SquadProjects]
+      summary: Upsert squad
+      operationId: putSquad
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SquadDto"
+      responses:
+        "204":
+          description: Saved
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/projects:
+    get:
+      tags: [SquadProjects]
+      summary: List projects
+      operationId: listProjects
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Projects
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/ProjectDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    post:
+      tags: [SquadProjects]
+      summary: Create project
+      operationId: createProject
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ProjectDto"
+      responses:
+        "200":
+          description: Created project
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProjectDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/projects/{projectId}:
+    patch:
+      tags: [SquadProjects]
+      summary: Update project
+      operationId: patchProject
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/ProjectId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ProjectPatchDto"
+      responses:
+        "200":
+          description: Updated project
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProjectDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+
+  /workspaces/{workspaceId}/code-chat/indexes:
+    get:
+      tags: [CodeChat]
+      summary: List code indexes for the workspace
+      operationId: listCodeChatIndexes
+      x-test-coverage-skip: lightweight MVP; covered by package unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Index list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatIndexListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    post:
+      tags: [CodeChat]
+      summary: Start indexing a connected repository
+      operationId: createCodeChatIndex
+      x-test-coverage-skip: lightweight MVP; covered by package unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CodeChatCreateIndexBodyDto"
+      responses:
+        "202":
+          description: Indexing accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatIndexDto"
+        "400":
+          description: Invalid request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/code-chat/indexes/sync:
+    post:
+      tags: [CodeChat]
+      summary: Enqueue indexing for all (or selected) readiness GitHub repos
+      operationId: syncCodeChatIndexes
+      x-test-coverage-skip: lightweight MVP; covered by package unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CodeChatSyncIndexesBodyDto"
+      responses:
+        "202":
+          description: Sync accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatSyncIndexesResultDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/code-chat/indexes/{indexId}:
+    get:
+      tags: [CodeChat]
+      summary: Get code index status
+      operationId: getCodeChatIndex
+      x-test-coverage-skip: lightweight MVP; covered by package unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: indexId
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: Index
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatIndexDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/code-chat/threads:
+    get:
+      tags: [CodeChat]
+      summary: List code chat threads for the current user
+      operationId: listCodeChatThreads
+      x-test-coverage-skip: lightweight MVP; covered by package unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Thread list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatThreadListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+    post:
+      tags: [CodeChat]
+      summary: Create a code chat thread against a ready index
+      operationId: createCodeChatThread
+      x-test-coverage-skip: lightweight MVP; covered by package unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CodeChatCreateThreadBodyDto"
+      responses:
+        "201":
+          description: Thread created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatThreadDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: Index not ready
+
+  /workspaces/{workspaceId}/code-chat/threads/{threadId}:
+    get:
+      tags: [CodeChat]
+      summary: Get a code chat thread with messages
+      operationId: getCodeChatThread
+      x-test-coverage-skip: lightweight MVP; covered by package unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: threadId
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: Thread with messages
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatThreadDetailDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    delete:
+      tags: [CodeChat]
+      summary: Delete a code chat thread and its messages
+      operationId: deleteCodeChatThread
+      x-test-coverage-skip: ownership and RLS enforced by the store
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: threadId
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "204":
+          description: Thread deleted
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Not found
+
+  /workspaces/{workspaceId}/code-chat/threads/{threadId}/messages:
+    post:
+      tags: [CodeChat]
+      summary: Send a message and receive an assistant reply
+      operationId: postCodeChatMessage
+      x-test-coverage-skip: lightweight MVP; covered by package unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: threadId
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CodeChatPostMessageBodyDto"
+      responses:
+        "200":
+          description: Assistant message
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatMessageReplyDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: Index not ready
+
+  /workspaces/{workspaceId}/code-chat/indexes/{indexId}/wiki:
+    get:
+      tags: [CodeChat]
+      summary: List wiki pages for an index (generates skeleton if missing)
+      operationId: listCodeChatWikiPages
+      x-test-coverage-skip: covered by code-context wiki unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: indexId
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: Wiki page list
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatWikiPageListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Not found
+
+  /workspaces/{workspaceId}/code-chat/indexes/{indexId}/wiki/{slug}:
+    get:
+      tags: [CodeChat]
+      summary: Get a wiki page by slug
+      operationId: getCodeChatWikiPage
+      x-test-coverage-skip: covered by code-context wiki unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: indexId
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+        - name: slug
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        "200":
+          description: Wiki page
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatWikiPageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Not found
+
+  /workspaces/{workspaceId}/code-chat/indexes/{indexId}/wiki/generate:
+    post:
+      tags: [CodeChat]
+      summary: Regenerate wiki pages from the stored code graph
+      operationId: generateCodeChatWiki
+      x-test-coverage-skip: covered by code-context wiki unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: indexId
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: Generated wiki pages
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatWikiPageListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "409":
+          description: Index not ready
+
+  /workspaces/{workspaceId}/code-chat/analyze/symbols:
+    post:
+      tags: [CodeChat]
+      summary: Find symbols across the ready corpus
+      operationId: analyzeCodeChatSymbols
+      x-test-coverage-skip: covered by code-context analysis unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CodeChatSymbolQueryBodyDto"
+      responses:
+        "200":
+          description: Symbol hits
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatSymbolHitListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "409":
+          description: Corpus not ready
+
+  /workspaces/{workspaceId}/code-chat/analyze/references:
+    post:
+      tags: [CodeChat]
+      summary: Find references for a symbol
+      operationId: analyzeCodeChatReferences
+      x-test-coverage-skip: covered by code-context analysis unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CodeChatReferenceQueryBodyDto"
+      responses:
+        "200":
+          description: Reference hits
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatReferenceHitListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "409":
+          description: Corpus not ready
+
+  /workspaces/{workspaceId}/code-chat/analyze/blast-radius:
+    post:
+      tags: [CodeChat]
+      summary: Analyze blast radius (intra or gated cross-repo)
+      operationId: analyzeCodeChatBlastRadius
+      x-test-coverage-skip: covered by code-context analysis unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CodeChatBlastRadiusBodyDto"
+      responses:
+        "200":
+          description: Blast radius result (always marked partial/unknown until eval gates)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatBlastRadiusResultDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Symbol not found
+        "409":
+          description: Corpus not ready
+
+  /workspaces/{workspaceId}/code-chat/analyze/semantic-diff:
+    post:
+      tags: [CodeChat]
+      summary: Map changed paths onto graph symbols and blast hints
+      operationId: analyzeCodeChatSemanticDiff
+      x-test-coverage-skip: covered by code-context analysis unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CodeChatSemanticDiffBodyDto"
+      responses:
+        "200":
+          description: Semantic diff analysis
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeChatSemanticDiffResultDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "409":
+          description: Corpus not ready
+
+  /workspaces/{workspaceId}/code-chat/analyze/recommendations:
+    post:
+      tags: [CodeChat]
+      summary: Test impact and BDD/contract recommendations
+      operationId: analyzeCodeChatRecommendations
+      x-test-coverage-skip: covered by code-context analysis unit tests
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CodeChatRecommendationsBodyDto"
+      responses:
+        "200":
+          description: Recommendations
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/SquadDto"
+                $ref: "#/components/schemas/CodeChatRecommendationsResultDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
-    put:
-      tags: [SquadProjects]
-      summary: Upsert squad
-      operationId: putSquad
+        "409":
+          description: Corpus not ready
+
+  /workspaces/{workspaceId}/code-chat/analyze/visualize:
+    post:
+      tags: [CodeChat]
+      summary: Structured graph diagrams (SVG-ready nodes/edges) or Obsidian-style atlas stubs
+      operationId: analyzeCodeChatVisualize
+      x-test-coverage-skip: covered by code-context analysis unit tests
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       requestBody:
@@ -6761,76 +7293,70 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/SquadDto"
-      responses:
-        "204":
-          description: Saved
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-
-  /workspaces/{workspaceId}/projects:
-    get:
-      tags: [SquadProjects]
-      summary: List projects
-      operationId: listProjects
-      parameters:
-        - $ref: "#/components/parameters/WorkspaceId"
+              $ref: "#/components/schemas/CodeChatVisualizeBodyDto"
       responses:
         "200":
-          description: Projects
+          description: Visualization payload
           content:
             application/json:
               schema:
-                type: array
-                items:
-                  $ref: "#/components/schemas/ProjectDto"
+                $ref: "#/components/schemas/CodeChatVisualizeResultDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "409":
+          description: Corpus not ready
+
+  /workspaces/{workspaceId}/code-chat/analyze/cross-edges:
     post:
-      tags: [SquadProjects]
-      summary: Create project
-      operationId: createProject
+      tags: [CodeChat]
+      summary: Resolve heuristic cross-process edges across ready repos
+      operationId: analyzeCodeChatCrossEdges
+      x-test-coverage-skip: covered by code-context analysis unit tests
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       requestBody:
-        required: true
+        required: false
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/ProjectDto"
+              $ref: "#/components/schemas/CodeChatCrossEdgesBodyDto"
       responses:
         "200":
-          description: Created project
+          description: Cross-process edge candidates
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ProjectDto"
+                $ref: "#/components/schemas/CodeChatCrossEdgesResultDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "409":
+          description: Need two ready indexes
 
-  /workspaces/{workspaceId}/projects/{projectId}:
-    patch:
-      tags: [SquadProjects]
-      summary: Update project
-      operationId: patchProject
+  /workspaces/{workspaceId}/code-chat/tools/get_context_pack:
+    post:
+      tags: [CodeChat]
+      summary: MCP/agent tool — compact context pack from the corpus
+      operationId: codeChatGetContextPack
+      x-test-coverage-skip: covered by code-context analysis unit tests
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - $ref: "#/components/parameters/ProjectId"
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/ProjectPatchDto"
+              $ref: "#/components/schemas/CodeChatContextPackBodyDto"
       responses:
         "200":
-          description: Updated project
+          description: Context pack
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ProjectDto"
+                $ref: "#/components/schemas/CodeChatContextPackDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
+        "409":
+          description: Corpus not ready
 
   /workspaces/{workspaceId}/notifications:
     get:
@@ -16143,3 +16669,448 @@ components:
           $ref: "#/components/schemas/InsightsRecommendationsPageBundleRecommendations"
         _meta:
           $ref: "#/components/schemas/InsightsResponseMeta"
+
+    CodeChatIndexStatus:
+      type: string
+      enum: [pending, indexing, ready, failed]
+
+    CodeChatIndexer:
+      type: string
+      enum: [graphify, builtin]
+      nullable: true
+
+    CodeChatIndexDto:
+      type: object
+      required: [id, workspaceId, repoId, providerSlug, repoName, status, nodeCount, edgeCount, createdAt, updatedAt]
+      properties:
+        id: { type: string, format: uuid }
+        workspaceId: { type: string, format: uuid }
+        repoId: { type: string, format: uuid }
+        providerSlug: { type: string }
+        repoName: { type: string }
+        status: { $ref: "#/components/schemas/CodeChatIndexStatus" }
+        indexer: { $ref: "#/components/schemas/CodeChatIndexer" }
+        nodeCount: { type: integer }
+        edgeCount: { type: integer }
+        commitSha: { type: string, nullable: true }
+        errorMessage: { type: string, nullable: true }
+        indexedAt: { type: string, format: date-time, nullable: true }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+        hasCodeExcerpts:
+          type: boolean
+          description: True when the indexed graph stores durable code excerpts (required for useful chat answers).
+
+    CodeChatIndexListDto:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items: { $ref: "#/components/schemas/CodeChatIndexDto" }
+
+    CodeChatCreateIndexBodyDto:
+      type: object
+      required: [repoId]
+      properties:
+        repoId: { type: string, format: uuid }
+
+    CodeChatSyncIndexesBodyDto:
+      type: object
+      properties:
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+          description: Optional subset; omit or empty to enqueue all readiness GitHub repos.
+
+    CodeChatSyncIndexesResultDto:
+      type: object
+      required: [enqueued]
+      properties:
+        enqueued: { type: integer, minimum: 0 }
+        items:
+          type: array
+          items: { $ref: "#/components/schemas/CodeChatIndexDto" }
+
+    CodeChatThreadDto:
+      type: object
+      required: [id, workspaceId, repoIds, title, createdAt, updatedAt]
+      properties:
+        id: { type: string, format: uuid }
+        workspaceId: { type: string, format: uuid }
+        indexId: { type: string, format: uuid, nullable: true }
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+          description: Empty means all ready repos in the workspace.
+        revisionRef: { type: string, nullable: true }
+        title: { type: string }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+
+    CodeChatThreadListDto:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items: { $ref: "#/components/schemas/CodeChatThreadDto" }
+
+    CodeChatCreateThreadBodyDto:
+      type: object
+      properties:
+        indexId:
+          type: string
+          format: uuid
+          description: Legacy single-index bind; prefer repoIds for workspace scope.
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+          description: Empty or omitted = all ready repos.
+        revisionRef: { type: string }
+        title: { type: string }
+
+    CodeChatCitationDto:
+      type: object
+      required: [path, label, score]
+      properties:
+        path: { type: string }
+        label: { type: string }
+        score: { type: number }
+        repoId: { type: string, format: uuid }
+        repoName: { type: string }
+        providerSlug: { type: string }
+        commitSha: { type: string, nullable: true }
+        startLine: { type: integer }
+        endLine: { type: integer }
+        confidence: { type: string, enum: [fact, inference, possibility, unknown] }
+
+    CodeChatMessageDto:
+      type: object
+      required: [id, role, content, citations, createdAt]
+      properties:
+        id: { type: string, format: uuid }
+        role: { type: string, enum: [user, assistant] }
+        content: { type: string }
+        citations:
+          type: array
+          items: { $ref: "#/components/schemas/CodeChatCitationDto" }
+        createdAt: { type: string, format: date-time }
+
+    CodeChatThreadDetailDto:
+      allOf:
+        - $ref: "#/components/schemas/CodeChatThreadDto"
+        - type: object
+          required: [messages]
+          properties:
+            messages:
+              type: array
+              items: { $ref: "#/components/schemas/CodeChatMessageDto" }
+
+    CodeChatPostMessageBodyDto:
+      type: object
+      required: [content]
+      properties:
+        content: { type: string, minLength: 1, maxLength: 8000 }
+
+    CodeChatMessageReplyDto:
+      allOf:
+        - $ref: "#/components/schemas/CodeChatMessageDto"
+        - type: object
+          required: [mode]
+          properties:
+            mode: { type: string, enum: [llm, retrieval] }
+
+    CodeChatWikiPageDto:
+      type: object
+      required: [id, indexId, workspaceId, slug, title, bodyMd, sortOrder, sourcePaths, createdAt, updatedAt]
+      properties:
+        id: { type: string, format: uuid }
+        indexId: { type: string, format: uuid }
+        workspaceId: { type: string, format: uuid }
+        slug: { type: string }
+        title: { type: string }
+        bodyMd: { type: string }
+        sortOrder: { type: integer }
+        sourcePaths:
+          type: array
+          items: { type: string }
+        diagramMermaid: { type: string, nullable: true }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+
+    CodeChatWikiPageListDto:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items: { $ref: "#/components/schemas/CodeChatWikiPageDto" }
+
+    CodeChatSymbolQueryBodyDto:
+      type: object
+      required: [query]
+      properties:
+        query: { type: string, minLength: 1 }
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+
+    CodeChatSymbolHitDto:
+      type: object
+      required: [id, name, path, kind]
+      properties:
+        id: { type: string }
+        name: { type: string }
+        path: { type: string }
+        kind: { type: string }
+        summary: { type: string }
+        startLine: { type: integer }
+        repoId: { type: string, format: uuid }
+        repoName: { type: string }
+        commitSha: { type: string, nullable: true }
+
+    CodeChatSymbolHitListDto:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items: { $ref: "#/components/schemas/CodeChatSymbolHitDto" }
+
+    CodeChatReferenceQueryBodyDto:
+      type: object
+      required: [symbol]
+      properties:
+        symbol: { type: string, minLength: 1 }
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+
+    CodeChatReferenceHitDto:
+      type: object
+      required: [fromId, fromLabel, toId, toLabel, relation, certainty]
+      properties:
+        fromId: { type: string }
+        fromLabel: { type: string }
+        toId: { type: string }
+        toLabel: { type: string }
+        relation: { type: string }
+        certainty: { type: string, enum: [EXTRACTED, INFERRED] }
+        repoId: { type: string, format: uuid }
+        repoName: { type: string }
+
+    CodeChatReferenceHitListDto:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items: { $ref: "#/components/schemas/CodeChatReferenceHitDto" }
+
+    CodeChatBlastRadiusBodyDto:
+      type: object
+      required: [symbol]
+      properties:
+        symbol: { type: string, minLength: 1 }
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+        crossRepo: { type: boolean }
+
+    CodeChatBlastRadiusResultDto:
+      type: object
+      required: [mode, completeness]
+      properties:
+        mode: { type: string, enum: [intra_repo, cross_repo] }
+        completeness: { type: string, enum: [partial, unknown] }
+        gateNote: { type: string }
+        repoId: { type: string, format: uuid }
+        repoName: { type: string }
+        originId: { type: string }
+        originLabel: { type: string }
+        truncated: { type: boolean }
+        edgesUsed: { type: integer }
+        nodes:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+
+    CodeChatSemanticDiffBodyDto:
+      type: object
+      required: [changedPaths]
+      properties:
+        changedPaths:
+          type: array
+          items: { type: string }
+          minItems: 1
+        indexId: { type: string, format: uuid }
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+        baseCommit: { type: string }
+        headCommit: { type: string }
+
+    CodeChatSemanticDiffResultDto:
+      type: object
+      required: [files, blastHints]
+      properties:
+        baseCommit: { type: string }
+        headCommit: { type: string }
+        files:
+          type: array
+          items:
+            type: object
+            required: [path, changeType, symbolsTouched, summary]
+            properties:
+              path: { type: string }
+              changeType: { type: string, enum: [added, removed, modified] }
+              symbolsTouched:
+                type: array
+                items: { type: string }
+              summary: { type: string }
+        blastHints:
+          type: array
+          items:
+            type: object
+            required: [symbol, affectedCount]
+            properties:
+              symbol: { type: string }
+              affectedCount: { type: integer }
+
+    CodeChatRecommendationsBodyDto:
+      type: object
+      properties:
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+        changedPaths:
+          type: array
+          items: { type: string }
+        symbol: { type: string }
+
+    CodeChatRecommendationsResultDto:
+      type: object
+      required: [testImpact, recommendations]
+      properties:
+        repoId: { type: string, format: uuid }
+        repoName: { type: string }
+        testImpact:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        recommendations:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+
+    CodeChatVisualizeBodyDto:
+      type: object
+      properties:
+        kind: { type: string, enum: [dependency, blast, atlas] }
+        symbol: { type: string }
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+
+    CodeChatVisualizeResultDto:
+      type: object
+      properties:
+        repoId: { type: string, format: uuid }
+        diagram:
+          type: object
+          required: [format, title, source, nodes, edges]
+          properties:
+            format: { type: string, enum: [graph, mermaid] }
+            title: { type: string }
+            source: { type: string, description: Mermaid source kept for export/copy }
+            note:
+              type: string
+              description: Set when dependency edges could not be resolved and a fallback view is shown.
+            nodes:
+              type: array
+              items:
+                type: object
+                required: [id, label]
+                properties:
+                  id: { type: string }
+                  label: { type: string }
+                  kind: { type: string }
+            edges:
+              type: array
+              items:
+                type: object
+                required: [from, to]
+                properties:
+                  from: { type: string }
+                  to: { type: string }
+                  label: { type: string }
+        atlas:
+          type: array
+          items:
+            type: object
+            properties:
+              path: { type: string }
+              body: { type: string }
+
+    CodeChatCrossEdgesBodyDto:
+      type: object
+      properties:
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+
+    CodeChatCrossEdgesResultDto:
+      type: object
+      required: [items, completeness]
+      properties:
+        items:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        completeness: { type: string, enum: [partial, unknown] }
+        gateNote: { type: string }
+
+    CodeChatContextPackBodyDto:
+      type: object
+      properties:
+        question: { type: string }
+        symbol: { type: string }
+        maxTokensApprox: { type: integer }
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+
+    CodeChatContextPackDto:
+      type: object
+      required: [summary, symbols, references, citations, snippets]
+      properties:
+        repoId: { type: string, format: uuid }
+        repoName: { type: string }
+        commitSha: { type: string, nullable: true }
+        summary: { type: string }
+        symbols:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        references:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        blastRadiusPreview:
+          type: object
+          additionalProperties: true
+        citations:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+        snippets:
+          type: array
+          items: { type: string }