@thinkai/tai-api-contract 2.110.0 → 2.111.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.110.0
+  version: 2.111.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -7202,6 +7202,37 @@ paths:
         "403":
           $ref: "#/components/responses/Forbidden"
 
+  /workspaces/{workspaceId}/code-intelligence/token-usage/summary:
+    get:
+      tags: [CodeChat]
+      summary: ECG token usage rollup for this workspace
+      description: >
+        Member-readable totals and per-operation breakdown from
+        `tai_workspace_code_intelligence_token_usage` (Ask, wiki enrich, PRD, workspace KB,
+        wiki.json outline). Default window is 30 days (max 90).
+      operationId: getCodeIntelligenceTokenUsageSummary
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: days
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 90
+            default: 30
+      responses:
+        "200":
+          description: Token usage summary
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CodeIntelligenceTokenUsageSummaryDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
   /workspaces/{workspaceId}/repo-eligibility:
     get:
       tags: [RepositoryReadiness]
@@ -7713,6 +7744,187 @@ paths:
         "404":
           description: Not found
 
+  /workspaces/{workspaceId}/code-chat/indexes/{indexId}/wiki-config:
+    get:
+      tags: [CodeChat]
+      summary: Effective wiki.json for an index (server + repo + workspace)
+      operationId: getCodeChatEffectiveWikiConfig
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: indexId
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: Effective wiki config
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EffectiveWikiConfigDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          description: Graph not ready
+
+  /workspaces/{workspaceId}/knowledge-pages:
+    get:
+      tags: [CodeChat]
+      summary: List workspace knowledge base pages (no repo pick)
+      operationId: listWorkspaceKnowledgePages
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Workspace knowledge pages
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceKnowledgePageListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+
+  /workspaces/{workspaceId}/knowledge-pages/generate:
+    post:
+      tags: [CodeChat]
+      summary: Generate the cross-repo workspace knowledge base
+      description: >-
+        Synthesizes workspace-level pages from the repository wikis that already exist.
+        Does not clone or re-index. Replaces the whole workspace knowledge base.
+      operationId: generateWorkspaceKnowledgePages
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/GenerateWorkspaceKnowledgePagesBodyDto"
+      responses:
+        "200":
+          description: Generated workspace knowledge pages
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GenerateWorkspaceKnowledgePagesResultDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Code Intelligence is disabled for this workspace
+        "409":
+          description: No ready repository index in scope
+
+  /workspaces/{workspaceId}/knowledge-pages/prd/generate:
+    post:
+      tags: [CodeChat]
+      summary: Generate a workspace-scoped PRD draft
+      description: >-
+        Builds a PRD draft from ready repository wikis, code graphs, and platform evidence
+        (readiness, quality, delivery, AI adoption, monitoring). Upserts one workspace
+        knowledge page (`prd-<slug>` / `prd-draft`) without replacing the whole knowledge base.
+      operationId: generatePrdDraft
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/GeneratePrdDraftBodyDto"
+      responses:
+        "200":
+          description: Generated PRD draft page
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/GeneratePrdDraftResultDto"
+        "400":
+          description: Missing or invalid featureIntent
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Code Intelligence is disabled for this workspace
+        "409":
+          description: No ready repository index in scope
+
+  /workspaces/{workspaceId}/code-intelligence/repo-wiki-json:
+    get:
+      tags: [CodeChat]
+      summary: List repositories with an admin wiki.json override (admin only)
+      operationId: listRepoWikiJsonSummaries
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Override summaries
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RepoWikiJsonSummaryListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Workspace admin required
+
+  /workspaces/{workspaceId}/code-intelligence/repos/{repoId}/wiki-json:
+    get:
+      tags: [CodeChat]
+      summary: Get the admin wiki.json override for a repository (admin only)
+      operationId: getRepoWikiJson
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: repoId
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      responses:
+        "200":
+          description: Stored override (document is null when unset)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RepoWikiJsonDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Workspace admin required
+        "404":
+          description: Repository not found
+    put:
+      tags: [CodeChat]
+      summary: Write or clear the admin wiki.json override for a repository (admin only)
+      description: >-
+        Sits between workspace guidance and the in-repo `.aidrivensdlc/wiki.json`, so a
+        file committed to the repository still wins.
+      operationId: putRepoWikiJson
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: repoId
+          in: path
+          required: true
+          schema: { type: string, format: uuid }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PutRepoWikiJsonDto"
+      responses:
+        "200":
+          description: Stored override
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RepoWikiJsonDto"
+        "400":
+          description: Invalid document
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Workspace admin required
+        "404":
+          description: Repository not found
+
   /workspaces/{workspaceId}/code-chat/indexes/{indexId}/wiki/export:
     get:
       tags: [CodeChat]
@@ -10728,6 +10940,47 @@ components:
           type: string
           nullable: true
           minLength: 1
+        wikiGuidance:
+          allOf:
+            - $ref: "#/components/schemas/CodeWikiGuidanceDto"
+          nullable: true
+          description: >
+            Deep Wiki documentation focus for this workspace. Steers topic planning when
+            generating Engineering Context wiki pages. Optional in-repo `.aidrivensdlc/wiki.json`
+            still overrides the topic outline when present.
+
+    CodeWikiGuidanceTopicDto:
+      type: object
+      required: [title, purpose]
+      properties:
+        title:
+          type: string
+          minLength: 1
+          maxLength: 120
+        purpose:
+          type: string
+          minLength: 1
+          maxLength: 800
+        parentTitle:
+          type: string
+          nullable: true
+          maxLength: 120
+          description: Title of the parent topic for hierarchy (must match another topic title).
+
+    CodeWikiGuidanceDto:
+      type: object
+      properties:
+        guidance:
+          type: string
+          maxLength: 10000
+          description: Free-form notes describing what the wiki should emphasize.
+          default: ""
+        topics:
+          type: array
+          maxItems: 30
+          items:
+            $ref: "#/components/schemas/CodeWikiGuidanceTopicDto"
+          description: Preferred topic outline for Deep Wiki pages.
 
     WorkspaceConfigDto:
       type: object
@@ -10806,6 +11059,12 @@ components:
             Federated-readiness delivery topology: which connected repos hold terraform /
             gitops / ci_templates / api_contracts truth for this workspace. Null when not
             configured. Change via `PUT /workspaces/{workspaceId}/delivery-topology`.
+        codeWikiGuidance:
+          allOf:
+            - $ref: "#/components/schemas/CodeWikiGuidanceDto"
+          description: >
+            Deep Wiki documentation focus for this workspace (guidance notes + optional topic outline).
+            Saved via `PUT /workspaces/{workspaceId}/code-intelligence` (`wikiGuidance`).
 
     DeliveryRoleConfigDto:
       type: object
@@ -18300,6 +18559,13 @@ components:
           description: >
             Human-readable indexing stage while a job is running (queued, clone, graph,
             save, wiki). Cleared when the index is ready or failed.
+        knowledgeJob:
+          allOf:
+            - $ref: "#/components/schemas/CodeKnowledgeJobDto"
+          nullable: true
+          description: >
+            Active knowledge job for this repo when status is queued/running — phase, tracks,
+            and token/cost rollups for SPA transparency (Wave 1).
         indexedAt: { type: string, format: date-time, nullable: true }
         createdAt: { type: string, format: date-time }
         updatedAt: { type: string, format: date-time }
@@ -18307,6 +18573,60 @@ components:
           type: boolean
           description: True when the indexed graph stores durable code excerpts (required for useful chat answers).
 
+    CodeKnowledgeJobDto:
+      type: object
+      required:
+        - id
+        - workspaceId
+        - repoId
+        - status
+        - inputTokensTotal
+        - outputTokensTotal
+        - estimatedCostUsdTotal
+        - llmInvocationCount
+        - createdAt
+        - updatedAt
+      properties:
+        id: { type: string, format: uuid }
+        workspaceId: { type: string, format: uuid }
+        repoId: { type: string, format: uuid }
+        indexId: { type: string, format: uuid, nullable: true }
+        status:
+          type: string
+          enum: [queued, running, completed, failed]
+        phase:
+          type: string
+          nullable: true
+          enum: [cloning, indexing, track_a, track_b, completing]
+          description: Coarse UX phase while status=running.
+        phaseDetail:
+          type: string
+          nullable: true
+          description: Human-readable detail (e.g. enriching · page 3/8 · how-it-works).
+        phaseUpdatedAt: { type: string, format: date-time, nullable: true }
+        trackAStatus:
+          $ref: "#/components/schemas/CodeKnowledgeTrackStatus"
+        trackBStatus:
+          $ref: "#/components/schemas/CodeKnowledgeTrackStatus"
+        graphStatus:
+          $ref: "#/components/schemas/CodeKnowledgeTrackStatus"
+        inputTokensTotal: { type: integer, minimum: 0 }
+        outputTokensTotal: { type: integer, minimum: 0 }
+        estimatedCostUsdTotal: { type: number, minimum: 0 }
+        llmInvocationCount: { type: integer, minimum: 0 }
+        lastProvider: { type: string, nullable: true }
+        lastModel: { type: string, nullable: true }
+        lastKeySource: { type: string, nullable: true }
+        errorMessage: { type: string, nullable: true }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+
+    CodeKnowledgeTrackStatus:
+      type: string
+      nullable: true
+      enum: [pending, running, completed, skipped, failed]
+      description: Per-track status for dual-track Deep Wiki (Track A skeleton, Track B enrich, graph index).
+
     CodeChatIndexListDto:
       type: object
       required: [items]
@@ -18439,6 +18759,10 @@ components:
       required: [content]
       properties:
         content: { type: string, minLength: 1, maxLength: 8000 }
+        persona:
+          type: string
+          enum: [engineer, lead, pm]
+          description: Optional Ask tone preference (FE localStorage / request — not a DB role)
 
     CodeChatMessageReplyDto:
       allOf:
@@ -18463,6 +18787,25 @@ components:
               type: array
               items: { type: string }
               description: Repository names whose wiki pages grounded the answer
+            groundedInPlatform:
+              type: boolean
+              description: True when platform evidence tools P–U contributed facts
+            platformToolIds:
+              type: array
+              items: { type: string }
+              description: Tool ids that returned data (e.g. readiness_summary)
+            intent:
+              type: string
+              enum:
+                - inventory_apis
+                - inventory_modules
+                - explain
+                - platform_ops
+                - feature_impact
+                - prd_request
+              description: Classified Ask intent for the turn
+            usage:
+              $ref: "#/components/schemas/CodeIntelligenceUsageDto"
 
     CodeChatApiRouteRowDto:
       type: object
@@ -18533,9 +18876,298 @@ components:
           type: array
           items: { type: string }
         diagramMermaid: { type: string, nullable: true }
+        enrichmentStatus:
+          type: string
+          enum: [skeleton, enriched, shallow, needs_review]
+          description: Deep Wiki page quality chip (D6 / D12).
         createdAt: { type: string, format: date-time }
         updatedAt: { type: string, format: date-time }
 
+    EffectiveWikiConfigDto:
+      type: object
+      required: [sources, document]
+      properties:
+        sources:
+          type: array
+          description: >-
+            Layers that contributed, in applied order. Later layers win:
+            server_default → workspace_guidance → admin_repo → repo_override.
+          items:
+            type: string
+            enum: [server_default, workspace_guidance, admin_repo, repo_override]
+        repoOverridePath: { type: string, nullable: true }
+        document:
+          type: object
+          additionalProperties: true
+          description: Effective wiki.json document (version, pages, slugAllowlist, diagramPolicies).
+
+    RepoWikiJsonDto:
+      type: object
+      description: Admin-authored wiki.json override stored for a single repository.
+      required: [repoId, repoName, providerSlug, document, hasOverride, updatedAt, updatedBy]
+      properties:
+        repoId: { type: string, format: uuid }
+        repoName: { type: string }
+        providerSlug: { type: string }
+        document:
+          type: object
+          nullable: true
+          additionalProperties: true
+          description: Stored wiki.json document, or null when no override is set.
+        hasOverride: { type: boolean }
+        updatedAt: { type: string, format: date-time, nullable: true }
+        updatedBy: { type: string, format: uuid, nullable: true }
+
+    PutRepoWikiJsonDto:
+      type: object
+      description: >-
+        Wiki.json override to store. Send `document: null`, or a document with no usable
+        pages, notes, allowlist, or diagram policies, to clear the override.
+      properties:
+        document:
+          type: object
+          nullable: true
+          additionalProperties: true
+
+    RepoWikiJsonSummaryDto:
+      type: object
+      required: [repoId, repoName, providerSlug, hasOverride, updatedAt, updatedBy]
+      properties:
+        repoId: { type: string, format: uuid }
+        repoName: { type: string }
+        providerSlug: { type: string }
+        hasOverride: { type: boolean }
+        updatedAt: { type: string, format: date-time, nullable: true }
+        updatedBy: { type: string, format: uuid, nullable: true }
+
+    RepoWikiJsonSummaryListDto:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items: { $ref: "#/components/schemas/RepoWikiJsonSummaryDto" }
+
+    GenerateWorkspaceKnowledgePagesBodyDto:
+      type: object
+      properties:
+        repoIds:
+          type: array
+          description: Ready repository indexes to synthesize from. Omit or send empty for all ready indexes.
+          items: { type: string, format: uuid }
+
+    GenerateWorkspaceKnowledgePagesResultDto:
+      type: object
+      required: [items, mode, repoIds]
+      properties:
+        items:
+          type: array
+          items: { $ref: "#/components/schemas/WorkspaceKnowledgePageDto" }
+        mode:
+          type: string
+          enum: [deterministic, llm]
+          description: llm when a model produced page bodies; deterministic when synthesized from wiki text alone.
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+        platformToolIds:
+          type: array
+          items: { type: string }
+          description: Platform evidence tool ids that contributed facts (P–U)
+        usage:
+          $ref: "#/components/schemas/CodeIntelligenceUsageDto"
+
+    GeneratePrdDraftBodyDto:
+      type: object
+      required: [featureIntent]
+      properties:
+        featureIntent:
+          type: string
+          minLength: 1
+          maxLength: 4000
+          description: Feature or change the PRD should describe
+        repoIds:
+          type: array
+          description: Ready repository indexes to analyze. Omit or send empty for all ready indexes.
+          items: { type: string, format: uuid }
+        persona:
+          type: string
+          enum: [engineer, lead, pm]
+          description: Draft voice preference (FE localStorage / request)
+
+    GeneratePrdDraftResultDto:
+      type: object
+      required: [item, mode, repoIds, slug]
+      properties:
+        item: { $ref: "#/components/schemas/WorkspaceKnowledgePageDto" }
+        mode:
+          type: string
+          enum: [deterministic, llm]
+        repoIds:
+          type: array
+          items: { type: string, format: uuid }
+        slug:
+          type: string
+          description: Persisted workspace knowledge page slug (prd-draft or prd-<safe-slug>)
+        usage:
+          $ref: "#/components/schemas/CodeIntelligenceUsageDto"
+
+    WorkspaceKnowledgePageDto:
+      type: object
+      required:
+        [
+          id,
+          workspaceId,
+          slug,
+          title,
+          bodyMd,
+          sortOrder,
+          sourceRepoIds,
+          status,
+          createdAt,
+          updatedAt,
+        ]
+      properties:
+        id: { type: string, format: uuid }
+        workspaceId: { type: string, format: uuid }
+        slug: { type: string }
+        title: { type: string }
+        bodyMd: { type: string }
+        sortOrder: { type: integer }
+        sourceRepoIds:
+          type: array
+          items: { type: string, format: uuid }
+        status:
+          type: string
+          enum: [draft, published, needs_review]
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+        excerpt:
+          type: string
+          description: First readable prose sentence for list previews
+        sourceRepoNames:
+          type: array
+          items: { type: string }
+          description: Display names for sourceRepoIds when resolvable
+
+    WorkspaceKnowledgeSystemContextDto:
+      type: object
+      required: [indexes, platformToolIds, platformMissingToolIds]
+      properties:
+        indexes:
+          type: array
+          items:
+            type: object
+            required: [repoId, repoName, indexId, nodeCount, edgeCount]
+            properties:
+              repoId: { type: string, format: uuid }
+              repoName: { type: string }
+              indexId: { type: string, format: uuid }
+              nodeCount: { type: integer }
+              edgeCount: { type: integer }
+              commitSha: { type: string, nullable: true }
+              indexer: { type: string, nullable: true }
+              knowledgeJobPhase: { type: string, nullable: true }
+              knowledgeJobStatus: { type: string, nullable: true }
+        platformToolIds:
+          type: array
+          items: { type: string }
+        platformMissingToolIds:
+          type: array
+          items: { type: string }
+        platformSnippet:
+          type: string
+          description: Bounded markdown summary of platform evidence for the system panel
+
+    WorkspaceKnowledgePageListDto:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items: { $ref: "#/components/schemas/WorkspaceKnowledgePageDto" }
+        systemContext:
+          $ref: "#/components/schemas/WorkspaceKnowledgeSystemContextDto"
+
+    CodeIntelligenceUsageDto:
+      type: object
+      required: [operation, provider, inputTokens, outputTokens]
+      properties:
+        operation:
+          type: string
+          description: Ledger operation key (code_chat, prd_generate, workspace_kb, wiki_json_outline, wiki_enrich, …)
+        provider: { type: string }
+        model: { type: string, nullable: true }
+        inputTokens: { type: integer, minimum: 0 }
+        outputTokens: { type: integer, minimum: 0 }
+        estimatedCostUsd: { type: number, nullable: true }
+        estimated: { type: boolean }
+
+    CodeIntelligenceTokenUsageByOperationDto:
+      type: object
+      required: [operation, inputTokens, outputTokens, estimatedCostUsd, invocationCount]
+      properties:
+        operation: { type: string }
+        inputTokens: { type: integer, minimum: 0 }
+        outputTokens: { type: integer, minimum: 0 }
+        estimatedCostUsd: { type: number }
+        invocationCount: { type: integer, minimum: 0 }
+
+    CodeIntelligenceTokenUsageByRepoDto:
+      type: object
+      required:
+        - repoId
+        - inputTokens
+        - outputTokens
+        - estimatedCostUsd
+        - invocationCount
+        - byOperation
+      properties:
+        repoId: { type: string, format: uuid }
+        repoName: { type: string, nullable: true }
+        inputTokens: { type: integer, minimum: 0 }
+        outputTokens: { type: integer, minimum: 0 }
+        estimatedCostUsd: { type: number }
+        invocationCount: { type: integer, minimum: 0 }
+        byOperation:
+          type: array
+          items: { $ref: "#/components/schemas/CodeIntelligenceTokenUsageByOperationDto" }
+
+    CodeIntelligenceTokenUsageSummaryDto:
+      type: object
+      required:
+        - days
+        - inputTokensTotal
+        - outputTokensTotal
+        - estimatedCostUsdTotal
+        - invocationCountTotal
+        - byOperation
+        - byRepo
+      properties:
+        days: { type: integer, minimum: 1, maximum: 90 }
+        inputTokensTotal: { type: integer, minimum: 0 }
+        outputTokensTotal: { type: integer, minimum: 0 }
+        estimatedCostUsdTotal: { type: number }
+        invocationCountTotal: { type: integer, minimum: 0 }
+        costEstimated:
+          type: boolean
+          description: >-
+            True when any cost was derived from published model rates because the provider
+            reported tokens without a price (for example the Cursor agent CLI).
+        costBasis:
+          type: string
+          nullable: true
+          description: Rate basis used for the derived cost, for display in tooltips.
+        byOperation:
+          type: array
+          items: { $ref: "#/components/schemas/CodeIntelligenceTokenUsageByOperationDto" }
+        byRepo:
+          type: array
+          description: >-
+            Per-repository split (wiki generation, conversations, outline). Only rows with
+            repository attribution appear here; workspace-wide operations stay in totals.
+          items: { $ref: "#/components/schemas/CodeIntelligenceTokenUsageByRepoDto" }
+
     CodeChatWikiPageListDto:
       type: object
       required: [items]
@@ -18735,7 +19367,26 @@ components:
       properties:
         kind:
           type: string
-          enum: [auto, dependency, module, focus, impact, blast, atlas]
+          enum:
+            [
+              auto,
+              dependency,
+              module,
+              focus,
+              impact,
+              blast,
+              atlas,
+              call_graph,
+              cfg_lite,
+              dataflow,
+              ssa,
+              terraform_deps,
+              layers,
+              domain,
+              runtime,
+              communication,
+              delivery,
+            ]
           description: >-
             Omit or send `auto` to let the server pick the most informative view for the
             repository. `blast` traces `query` as a symbol and falls back to a focused
@@ -18774,7 +19425,24 @@ components:
                 deterministic reading of hubs and areas from the graph.
             kind:
               type: string
-              enum: [dependency, module, focus, impact, blast]
+              enum:
+                [
+                  dependency,
+                  module,
+                  focus,
+                  impact,
+                  blast,
+                  call_graph,
+                  cfg_lite,
+                  dataflow,
+                  ssa,
+                  terraform_deps,
+                  layers,
+                  domain,
+                  runtime,
+                  communication,
+                  delivery,
+                ]
               description: >-
                 Which reading of the repository this diagram is. `module` rolls files up
                 into source groups when too few file dependencies resolved for a file map,
@@ -18784,6 +19452,69 @@ components:
               type: array
               description: Measured facts about the graph — hubs, dependency coverage, test share, route count.
               items: { type: string }
+            structurePanel:
+              type: object
+              description: >-
+                Deterministic reading beside the canvas for layers, domains, dataflow, and SSA.
+                Coverage, heatmaps, and ledgers are derived from the indexed graph — no LLM.
+              required: [kind]
+              properties:
+                kind:
+                  type: string
+                  enum: [layers, domain, dataflow, ssa]
+                coverage:
+                  type: object
+                  required:
+                    [totalFiles, connectedFiles, dependencyEdges, connectedShare, rollupEdges]
+                  properties:
+                    totalFiles: { type: integer }
+                    connectedFiles: { type: integer }
+                    dependencyEdges: { type: integer }
+                    connectedShare: { type: number }
+                    rollupEdges:
+                      type: integer
+                      description: Cross-bucket edges in this roll-up, or relation edges shown for dataflow/SSA.
+                axes:
+                  type: array
+                  description: Ordered axis labels for the heatmap.
+                  items: { type: string }
+                matrix:
+                  type: array
+                  items:
+                    type: object
+                    required: [from, to, weight]
+                    properties:
+                      from: { type: string }
+                      to: { type: string }
+                      weight: { type: integer }
+                focusBuckets:
+                  type: array
+                  description: >-
+                    Layers or domains that own the selected node / query, so roll-up views
+                    still answer a selection instead of silently ignoring it.
+                  items: { type: string }
+                violations:
+                  type: array
+                  description: Layer-stack edges that climb the usual API → Service → Data → UI order.
+                  items:
+                    type: object
+                    required: [from, to, weight, reason]
+                    properties:
+                      from: { type: string }
+                      to: { type: string }
+                      weight: { type: integer }
+                      reason: { type: string }
+                ledger:
+                  type: array
+                  description: Top dataflow / SSA flows with relation and certainty.
+                  items:
+                    type: object
+                    required: [from, to]
+                    properties:
+                      from: { type: string }
+                      to: { type: string }
+                      relation: { type: string }
+                      certainty: { type: string }
             focus:
               type: object
               description: Present when free text drove the view.