@thinkai/tai-api-contract 2.182.0 → 2.183.0

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.182.0
+  version: 2.183.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -65,6 +65,8 @@ tags:
       AI-tool usage/spend, org chart, and readiness — never mock payloads.
   - name: WorkspaceActivity
     description: Workspace-wide lifecycle activity log — repo add/remove/re-add and integration lifecycle events (issue #515).
+  - name: AssessmentReports
+    description: Encrypted stored assessment buyer PDFs, secure link delivery, and hide/restore (issue #486).
   - name: PlatformAdmin
     description: Platform-admin operations restricted to PLATFORM_ADMIN_EMAILS. Callers must present a valid JWT from an email on that allowlist; all other callers receive 403.
   - name: HRIS
@@ -430,7 +432,10 @@ paths:
         are ignored, so an unscanned source cannot be marked fresh. The
         five-business-day clock uses Monday–Friday in America/New_York and is
         stored on the first passing result. A later blocker does not clear it.
-        Active-engineer counts stay unloaded until stored activity can be counted.
+        The active-engineer count is loaded from stored commit authors and merged
+        pull requests in the 90-day baseline window (bots and identities not on the
+        org chart excluded). It stays unloaded until commit ingest covers the whole
+        window for every non-archived repository.
 
         **Authorization:** Bearer JWT required. Caller email must appear in `PLATFORM_ADMIN_EMAILS`.
       parameters:
@@ -602,7 +607,16 @@ paths:
                     items:
                       type: object
                       required:
-                        [workspaceId, offerId, ready, blocker, nextAction, dueDate, evaluatedAt]
+                        [
+                          workspaceId,
+                          offerId,
+                          ready,
+                          blocker,
+                          nextAction,
+                          clockStartedOn,
+                          dueDate,
+                          evaluatedAt,
+                        ]
                       properties:
                         workspaceId:
                           type: string
@@ -625,6 +639,11 @@ paths:
                             href:
                               type: string
                               nullable: true
+                        clockStartedOn:
+                          type: string
+                          nullable: true
+                          format: date
+                          description: America/New_York day the five-business-day clock started.
                         dueDate:
                           type: string
                           nullable: true
@@ -668,174 +687,14 @@ paths:
         content:
           application/json:
             schema:
-              type: object
-              required:
-                - manifest
-                - workspaceId
-                - expectedWorkspaceId
-                - expectedRepositoryIds
-                - soldWindowComplete
-                - premiumAiAssessable
-                - namedPersonSectionIds
-                - tolerances
-              properties:
-                manifest:
-                  type: object
-                  required:
-                    - offerId
-                    - dictionaryVersion
-                    - validation
-                    - shareMode
-                    - watermark
-                    - scope
-                    - windows
-                    - sources
-                    - consent
-                    - sections
-                  properties:
-                    offerId:
-                      type: string
-                      enum: [engineering_readiness_baseline, agentic_ai_roi]
-                    dictionaryVersion:
-                      type: string
-                    validation:
-                      type: string
-                      enum: [validated, not_validated]
-                    shareMode:
-                      type: string
-                      enum: [internal, external]
-                    watermark:
-                      type: string
-                      nullable: true
-                      enum: ["NOT VALIDATED", "SAMPLE · SYNTHETIC DATA"]
-                    scope:
-                      type: object
-                      required: [repositories, excluded]
-                      properties:
-                        repositories:
-                          type: array
-                          items:
-                            type: object
-                            required: [id, name]
-                            properties:
-                              id: { type: string }
-                              name: { type: string }
-                        excluded:
-                          type: array
-                          items:
-                            type: object
-                            required: [id, name, reason]
-                            properties:
-                              id: { type: string }
-                              name: { type: string }
-                              reason: { type: string }
-                    windows:
-                      type: object
-                      required: [pre, post, transitionDays]
-                      properties:
-                        pre:
-                          type: object
-                          nullable: true
-                          required: [start, end]
-                          properties:
-                            start: { type: string }
-                            end: { type: string }
-                        post:
-                          type: object
-                          nullable: true
-                          required: [start, end]
-                          properties:
-                            start: { type: string }
-                            end: { type: string }
-                        transitionDays:
-                          type: integer
-                    sources:
-                      type: array
-                      items:
-                        type: object
-                        required: [provider, status, freshAt]
-                        properties:
-                          provider: { type: string }
-                          status: { type: string }
-                          freshAt: { type: string, nullable: true }
-                    consent:
-                      type: object
-                      required: [aggregateUse, recordedAt]
-                      properties:
-                        aggregateUse:
-                          type: string
-                          enum: [opt_in, opt_out, unset]
-                        recordedAt:
-                          type: string
-                          nullable: true
-                    sections:
-                      type: array
-                      items:
-                        type: object
-                        required: [id, status]
-                        properties:
-                          id: { type: string }
-                          status:
-                            type: string
-                            enum: [ok, failed, omitted]
-                          reason: { type: string }
-                workspaceId:
-                  type: string
-                expectedWorkspaceId:
-                  type: string
-                expectedRepositoryIds:
-                  type: array
-                  items:
-                    type: string
-                soldWindowComplete:
-                  type: boolean
-                premiumAiAssessable:
-                  type: boolean
-                namedPersonSectionIds:
-                  type: array
-                  items:
-                    type: string
-                tolerances:
-                  type: array
-                  items:
-                    type: object
-                    required: [id, status]
-                    properties:
-                      id:
-                        type: string
-                      status:
-                        type: string
-                        enum: [unset, exceeded, within]
+              $ref: "#/components/schemas/AssessmentManifestValidationBodyDto"
       responses:
         "200":
           description: Validation result. Client validation and watermark inputs are ignored.
           content:
             application/json:
               schema:
-                type: object
-                required: [buyerDeliverable, validation, watermark, reasons, contentHash]
-                properties:
-                  buyerDeliverable:
-                    type: boolean
-                  validation:
-                    type: string
-                    enum: [validated, not_validated]
-                  watermark:
-                    type: string
-                    nullable: true
-                    enum: ["NOT VALIDATED"]
-                  reasons:
-                    type: array
-                    items:
-                      type: object
-                      required: [code, message]
-                      properties:
-                        code:
-                          type: string
-                        message:
-                          type: string
-                  contentHash:
-                    type: string
+                $ref: "#/components/schemas/AssessmentManifestValidationResultDto"
         "400":
           description: Body failed validation.
           content:
@@ -861,6 +720,180 @@ paths:
                 error: Forbidden
                 code: forbidden
 
+  /workspaces/{workspaceId}/assessment-manifest/validate:
+    post:
+      tags: [Workspace]
+      summary: Validate this workspace's assessment manifest
+      operationId: validateWorkspaceAssessmentManifest
+      description: >
+        Runs the same fail-closed manifest check as `runAssessmentManifestValidation`
+        for the workspace in the path. The server ignores `manifest.validation` and
+        `manifest.watermark` from the client. `buyerDeliverable` is true only when
+        the result is validated and `shareMode` is internal. An external share-safe
+        result can be validated and is never the buyer file. Unset or exceeded
+        tolerances fail. No numeric tolerance is assumed. GitLab and Bitbucket
+        fixtures are not part of this operation.
+
+        `workspaceId` and `expectedWorkspaceId` in the body must equal the path
+        workspace. A body that names another workspace is rejected. Comparing two
+        workspaces stays on `runAssessmentManifestValidation`.
+
+        **Authorization:** Bearer JWT required. Caller must be a workspace admin,
+        or a platform admin who is a member of this workspace. Members who are not
+        workspace admins receive 403. Non-members of an existing workspace receive
+        403. Unknown workspaces receive 404.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AssessmentManifestValidationBodyDto"
+      responses:
+        "200":
+          description: Validation result. Client validation and watermark inputs are ignored.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AssessmentManifestValidationResultDto"
+        "400":
+          description: Body failed validation.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: manifest.offerId is not a known assessment offer
+                code: invalid_body
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller cannot validate this workspace.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              examples:
+                not_member:
+                  value:
+                    error: Forbidden
+                workspace_admin_required:
+                  value:
+                    error: Forbidden
+                    code: workspace_admin_required
+                cross_workspace_forbidden:
+                  value:
+                    error: Forbidden
+                    code: cross_workspace_forbidden
+        "404":
+          description: Workspace does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Not found
+
+  /workspaces/{workspaceId}/assessment-manifest/build:
+    post:
+      tags: [Workspace]
+      summary: Build and validate this workspace's assessment manifest from stored evidence
+      operationId: buildWorkspaceAssessmentManifest
+      description: >
+        The client sends only the offer, share mode, the render status of each selected
+        section, and the matched-period ROI chapter it printed. The server fills scope,
+        excluded repositories, windows, sources with freshness, consent,
+        `expectedRepositoryIds`, `soldWindowComplete`, `premiumAiAssessable`, and
+        tolerances from stored data, then runs the same fail-closed check as
+        `validateWorkspaceAssessmentManifest`.
+
+
+        Scope is the non-archived workspace repositories. Above 50 repositories or 500
+        active engineers fails (custom quote). For the premium offer, repositories without
+        merged pull requests in both matched windows are listed in `excluded` and left out
+        of scope. Baseline windows: `pre` is null, `post` is the 90 calendar days ending
+        yesterday (America/New_York), and `transitionDays` is 0. Premium windows come from
+        the confirmed rollout day. Freshness: source control 24 hours, AI usage 7 days,
+        readiness scans 30 days. Aggregate-use consent is reported as stored; no row is
+        `unset`.
+
+
+        `premiumAiAssessable` needs fresh Cursor, Claude, or Copilot usage in the post
+        window and complete matched-period evidence. A live ROI refusal for incomplete
+        data blocks validation (`rollout_unset`, `window_missing`,
+        `ship_weight_incomplete`, `active_engineers_unknown`, `confounder_inputs_missing`,
+        `normalization_unset`, `output_unit_mismatch`). A refusal that is a legitimate
+        result does not (`non_positive_output`, `confounder`, `missing_cost`,
+        `non_usd_cost`, `cost_not_attributable`); the report prints "not assessable" with
+        no figure. The premium `roi` tolerance is `unset` when the ROI section did not
+        render or `roi` is missing, `exceeded` when the printed chapter differs from the
+        server result (USD figures within the dictionary money tolerance), and `within`
+        otherwise. Named-person sections always fail.
+
+
+        Send `result.contentHash` with the PDF to `storeAssessmentReport`, which rebuilds
+        the manifest and stores only when it is still a validated internal buyer file
+        with the same hash.
+
+
+        **Authorization:** Bearer JWT required. Caller must be a workspace admin, or a
+        platform admin who is a member of this workspace. Members who are not workspace
+        admins receive 403. Non-members of an existing workspace receive 403. Unknown
+        workspaces receive 404.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/BuildAssessmentManifestBodyDto"
+      responses:
+        "200":
+          description: Server-built manifest body and its validation result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BuildAssessmentManifestResponseDto"
+        "400":
+          description: Body failed validation.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: offerId is not a known assessment offer
+                code: invalid_body
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Caller cannot build this workspace's manifest.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Forbidden
+                code: workspace_admin_required
+        "404":
+          description: Workspace does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Not found
+        "503":
+          description: Stored evidence could not be loaded (no database or a load failure).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+              example:
+                error: Service unavailable
+                code: evidence_unavailable
+
   /admin/readiness/token-usage:
     get:
       tags: [PlatformAdmin]
@@ -7154,26 +7187,25 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/aggregate-use-consent:
+  /workspaces/{workspaceId}/assessment-rollout:
     get:
       tags: [Workspace]
-      summary: Read anonymized aggregate-use permission
-      operationId: getAggregateUseConsent
+      summary: Read the customer-confirmed assessment rollout day
+      operationId: getWorkspaceAssessmentRollout
       description: >
-        Returns whether ThinkAI may use this workspace's anonymized aggregate results in
-        marketing and peer benchmarks. A workspace that never chose returns `unset`, which
-        behaves as opted out (`effective: false`). The permission never covers company name,
-        logo, quote, raw report, repository or person identity, or customer reference.
-        Any workspace member may read it.
+        Returns the AI rollout day the customer confirmed for the Agentic AI ROI
+        assessment, interpreted at 00:00 America/New_York, plus who set it and when.
+        This is the only rollout source for the matched pre and post windows.
+        `rolloutDay` is null until an admin sets it. Any workspace member may read it.
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Current permission and the sentence reports must print
+          description: Current rollout day
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AggregateUseConsentDto"
+                $ref: "#/components/schemas/AssessmentRolloutDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -7184,17 +7216,21 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
+        "503":
+          description: Rollout storage is not configured
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
     put:
       tags: [Workspace]
-      summary: Set anonymized aggregate-use permission
-      operationId: putAggregateUseConsent
+      summary: Set the customer-confirmed assessment rollout day
+      operationId: putWorkspaceAssessmentRollout
       description: >
-        Workspace admins opt in or out. Every change writes one
-        `workspace.aggregate_use.changed` activity-log row in the same transaction.
-        Moving from `opt_in` to `opt_out` records a withdrawal and stops future extraction.
-        Opt-in requires the current legal-approved notice version; while no notice is
-        approved, opt-in returns `409 aggregate_use_notice_unapproved`. Opt-out is always
-        accepted. A refusal does not change price, delivery, support, or assessment output.
+        Workspace admins, or platform admins who are workspace members, set the rollout
+        day. The day must be a real calendar date that has already started in
+        America/New_York. Each save records the caller and time and writes one
+        `workspace.assessment_rollout.changed` activity-log row.
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
       requestBody:
@@ -7202,16 +7238,16 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/AggregateUseConsentPutDto"
+              $ref: "#/components/schemas/AssessmentRolloutPutDto"
       responses:
         "200":
-          description: Saved permission
+          description: Saved rollout day
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AggregateUseConsentDto"
+                $ref: "#/components/schemas/AssessmentRolloutDto"
         "400":
-          description: "Invalid body (`code`: `invalid_input`)"
+          description: "Invalid body, impossible date, or future day (`code`: `invalid_input`)"
           content:
             application/json:
               schema:
@@ -7230,45 +7266,38 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
-        "409":
-          description: >
-            Opt-in refused because no notice is approved (`aggregate_use_notice_unapproved`)
-            or the submitted notice version is not current (`aggregate_use_notice_stale`).
+        "503":
+          description: Rollout storage is not configured
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/report-center/exports:
-    post:
-      tags: [WorkspaceActivity]
-      summary: Record a Report Center PDF export
-      operationId: recordReportCenterExport
+  /workspaces/{workspaceId}/assessment-roi:
+    get:
+      tags: [Workspace]
+      summary: Read the matched-period ROI from stored evidence
+      operationId: getWorkspaceAssessmentRoi
       description: >
-        Workspace admin (or platform admin) records that a Report Center PDF was downloaded.
-        Inserts one `report.exported` activity-log row with the request body as secret-free metadata.
-        Does not store PDF bytes. Members who are not workspace admins receive 403.
+        Derives the 90-day pre window, the 14-day transition, and the 90-day post
+        window from the confirmed rollout day, then loads calendar-day coverage,
+        merged pull request Ship Weight per window, and recorded USD AI spend for the
+        post window. The figure is USD cost per incremental normalized Ship Weight
+        (per active engineer and Mon–Fri America/New_York working day). Fails closed:
+        `status` is `not_assessable` with a `reason` when a window is incomplete, cost
+        is missing, non-USD, or not attributable by day, Ship Weight is unscored,
+        active engineers are not countable, incremental output is not positive, or a
+        confounder is flagged or cannot be checked. Cost is never estimated. Any
+        workspace member may read it.
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/ReportCenterExportRecordBodyDto"
       responses:
-        "201":
-          description: Export recorded
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/ReportCenterExportRecordResponseDto"
-        "400":
-          description: Invalid body
+        "200":
+          description: Matched-period ROI result
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ErrorMessageDto"
+                $ref: "#/components/schemas/AssessmentRoiDto"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "403":
@@ -7279,37 +7308,521 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
-        "501":
-          description: Activity log is not supported by this backend build
+        "503":
+          description: Evidence storage is not configured or could not be read
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
-  /workspaces/{workspaceId}/activity:
+  /workspaces/{workspaceId}/aggregate-use-consent:
     get:
-      tags: [WorkspaceActivity]
-      summary: Workspace activity log (paginated)
-      operationId: listWorkspaceActivity
+      tags: [Workspace]
+      summary: Read anonymized aggregate-use permission
+      operationId: getAggregateUseConsent
       description: >
-        Paginated, chronological feed of workspace-scoped lifecycle events: repository add/remove/re-add
-        and GitHub integration add/remove. Inactive repos remain visible in this log.
-        Filter by a single `eventType`, a coarse `eventCategory`/`productArea`, an `eventSubcategory`
-        (a dotted event-type prefix that matches a whole lifecycle subgroup in one call, e.g.
-        `integrations.cursor.execution_key`), `actorUserId`, or date range (`since`/`until`).
+        Returns whether ThinkAI may use this workspace's anonymized aggregate results in
+        marketing and peer benchmarks. A workspace that never chose returns `unset`, which
+        behaves as opted out (`effective: false`). The permission never covers company name,
+        logo, quote, raw report, repository or person identity, or customer reference.
+        Any workspace member may read it.
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
-        - $ref: "#/components/parameters/PaginationLimit"
-        - $ref: "#/components/parameters/PaginationOffset"
-        - $ref: "#/components/parameters/PaginationOrder"
-        - name: sort
-          in: query
-          required: false
-          description: >
-            Server-side sort column (the activity "5 W's"). Combined with `order` (asc/desc).
-            Defaults to `when` (occurredAt). `occurredAt`/`id` is always the tiebreaker.
-          schema:
-            type: string
+      responses:
+        "200":
+          description: Current permission and the sentence reports must print
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AggregateUseConsentDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    put:
+      tags: [Workspace]
+      summary: Set anonymized aggregate-use permission
+      operationId: putAggregateUseConsent
+      description: >
+        Workspace admins opt in or out. Every change writes one
+        `workspace.aggregate_use.changed` activity-log row in the same transaction.
+        Moving from `opt_in` to `opt_out` records a withdrawal and stops future extraction.
+        Opt-in requires the current legal-approved notice version; while no notice is
+        approved, opt-in returns `409 aggregate_use_notice_unapproved`. Opt-out is always
+        accepted. A refusal does not change price, delivery, support, or assessment output.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AggregateUseConsentPutDto"
+      responses:
+        "200":
+          description: Saved permission
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AggregateUseConsentDto"
+        "400":
+          description: "Invalid body (`code`: `invalid_input`)"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: "Caller is not a workspace admin (`code`: `workspace_admin_required`)"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: >
+            Opt-in refused because no notice is approved (`aggregate_use_notice_unapproved`)
+            or the submitted notice version is not current (`aggregate_use_notice_stale`).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/report-center/exports:
+    post:
+      tags: [WorkspaceActivity]
+      summary: Record a Report Center PDF export
+      operationId: recordReportCenterExport
+      description: >
+        Workspace admin (or platform admin) records that a Report Center PDF was downloaded.
+        Inserts one `report.exported` activity-log row with the request body as secret-free metadata.
+        Does not store PDF bytes. Members who are not workspace admins receive 403.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ReportCenterExportRecordBodyDto"
+      responses:
+        "201":
+          description: Export recorded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ReportCenterExportRecordResponseDto"
+        "400":
+          description: Invalid body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "501":
+          description: Activity log is not supported by this backend build
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/assessment-reports:
+    get:
+      tags: [AssessmentReports]
+      summary: List stored assessment reports and their secure links
+      operationId: listAssessmentReports
+      description: >
+        Workspace admin (or platform admin who is a workspace member). Lists stored buyer PDFs
+        (metadata only, never bytes) with every secure link grant. Link tokens and token hashes are
+        never returned. A hidden report stays listed: `hidden_restorable` until `restoreUntil`,
+        then `restore_window_ended`. The restore window is restore capability, not erasure.
+        Responses carry `Cache-Control: no-store`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Stored reports, newest first
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AssessmentReportListDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "501":
+          description: Stored reports are not supported by this backend build (no database)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+    post:
+      tags: [AssessmentReports]
+      summary: Store a validated buyer PDF for secure delivery
+      operationId: storeAssessmentReport
+      description: >
+        Workspace admin (or platform admin who is a workspace member). The client never supplies
+        evidence: the server rebuilds the manifest from stored data with the same builder as
+        `buildWorkspaceAssessmentManifest`, using only `build` (offer, share mode, section
+        status, printed ROI), and stores the PDF only when `buyerDeliverable` is true (validated
+        and internal) and the rebuilt `contentHash` equals the one sent. An external
+        share-safe file is never stored here. The PDF is encrypted with AES-256-GCM and kept in
+        Postgres with its sha256; it is limited to 10 MiB. Records `report.assessment_stored`
+        without report content.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/StoreAssessmentReportBodyDto"
+      responses:
+        "201":
+          description: Report stored
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AssessmentReportDto"
+        "400":
+          description: Body is not valid, or the file is not a PDF or is too large
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "422":
+          description: >
+            `not_buyer_deliverable` (the rebuilt manifest did not validate as an internal buyer
+            file; includes `reasons`) or `manifest_changed` (stored evidence changed since the PDF
+            was built, so `contentHash` differs; export again).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StoreAssessmentReportRejectedDto"
+        "503":
+          description: Stored evidence could not be loaded to rebuild the manifest.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "501":
+          description: Stored reports are not supported by this backend build (no database)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/assessment-reports/{reportId}/links:
+    post:
+      tags: [AssessmentReports]
+      summary: Create a secure link and email it to a workspace member
+      operationId: createAssessmentReportLink
+      description: >
+        Workspace admin (or platform admin who is a workspace member). Creates one link grant for a
+        current workspace member and emails them the link only: generic text and
+        `{siteUrl}/reports/secure?t=<opaque token>`. The email carries no PDF attachment, report
+        name, metrics, repository, or person names. Only the sha256 of the token is stored and the
+        token is never returned. Expiry defaults to 14 days and can be shorter. When SMTP is not
+        configured the grant still stands and `email` says why it was skipped. Hidden reports
+        cannot be shared (`409 report_hidden`).
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/AssessmentReportId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateAssessmentReportLinkBodyDto"
+      responses:
+        "201":
+          description: Link created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CreateAssessmentReportLinkResponseDto"
+        "400":
+          description: Body is not valid
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or report not found (`report_not_found`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: The report is hidden (`report_hidden`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "422":
+          description: The recipient is not a current workspace member (`recipient_not_member`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "501":
+          description: Stored reports or member listing are not supported by this backend build
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/assessment-reports/{reportId}/links/{grantId}/revoke:
+    post:
+      tags: [AssessmentReports]
+      summary: Revoke a secure link
+      operationId: revokeAssessmentReportLink
+      description: >
+        Workspace admin (or platform admin who is a workspace member). The link stops working
+        immediately. Idempotent: revoking again keeps the first `revokedAt`. Revoking a link does
+        not affect a file the recipient already downloaded. Records `report.assessment_link_revoked`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/AssessmentReportId"
+        - name: grantId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        "200":
+          description: Revoked link
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AssessmentReportLinkDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace, report, or link not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "501":
+          description: Stored reports are not supported by this backend build (no database)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/assessment-reports/{reportId}/hide:
+    post:
+      tags: [AssessmentReports]
+      summary: Hide a stored report
+      operationId: hideAssessmentReport
+      description: >
+        Workspace admin (or platform admin who is a workspace member). Same semantics as workspace
+        delete: the report is hidden immediately and every link stops downloading. It can be
+        restored for 30 days (`restoreUntil`). That window is restore capability, not erasure; no
+        backup purge date is promised, and a file the buyer already downloaded stays with them.
+        Idempotent. Records `report.assessment_hidden`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/AssessmentReportId"
+      responses:
+        "200":
+          description: Hidden report (`links` is empty in this response; list again for links)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AssessmentReportDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or report not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "501":
+          description: Stored reports are not supported by this backend build (no database)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/assessment-reports/{reportId}/restore:
+    post:
+      tags: [AssessmentReports]
+      summary: Restore a hidden report within the 30-day window
+      operationId: restoreAssessmentReport
+      description: >
+        Workspace admin (or platform admin who is a workspace member). Allowed only before
+        `restoreUntil`; afterwards it fails with `409 restore_window_ended`. Links that were not
+        revoked or expired work again after restore. Records `report.assessment_restored`.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/AssessmentReportId"
+      responses:
+        "200":
+          description: Restored report (`links` is empty in this response; list again for links)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AssessmentReportDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or report not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "409":
+          description: "`not_hidden` or `restore_window_ended`"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "501":
+          description: Stored reports are not supported by this backend build (no database)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /assessment-reports/secure:
+    get:
+      tags: [AssessmentReports]
+      summary: Download a stored report through a secure link
+      operationId: downloadAssessmentReport
+      description: >
+        Bearer JWT required. The caller must be the link recipient and a current member of the
+        report's workspace. Access follows `decideReportAccess`: `leaked_token`, `removed_member`,
+        and `wrong_workspace` answer 403; `expired` and `revoked` answer 410; `invalid_grant`
+        answers 404. A hidden report answers `410 report_hidden`. Every response carries
+        `Cache-Control: no-store`. Records `report.assessment_downloaded` without report content.
+      parameters:
+        - name: t
+          in: query
+          required: true
+          description: Opaque link token from the email (`secureLinkQuery`).
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The decrypted PDF
+          headers:
+            Cache-Control:
+              schema:
+                type: string
+                enum: [no-store]
+          content:
+            application/pdf:
+              schema:
+                type: string
+                format: binary
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: "`leaked_token`, `removed_member`, or `wrong_workspace`"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AssessmentReportAccessErrorDto"
+        "404":
+          description: "`invalid_grant`"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AssessmentReportAccessErrorDto"
+        "410":
+          description: "`expired`, `revoked`, or `report_hidden`"
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AssessmentReportAccessErrorDto"
+        "500":
+          description: The stored report could not be decrypted (`report_unreadable`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "501":
+          description: Stored reports are not supported by this backend build (no database)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/activity:
+    get:
+      tags: [WorkspaceActivity]
+      summary: Workspace activity log (paginated)
+      operationId: listWorkspaceActivity
+      description: >
+        Paginated, chronological feed of workspace-scoped lifecycle events: repository add/remove/re-add
+        and GitHub integration add/remove. Inactive repos remain visible in this log.
+        Filter by a single `eventType`, a coarse `eventCategory`/`productArea`, an `eventSubcategory`
+        (a dotted event-type prefix that matches a whole lifecycle subgroup in one call, e.g.
+        `integrations.cursor.execution_key`), `actorUserId`, or date range (`since`/`until`).
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/PaginationLimit"
+        - $ref: "#/components/parameters/PaginationOffset"
+        - $ref: "#/components/parameters/PaginationOrder"
+        - name: sort
+          in: query
+          required: false
+          description: >
+            Server-side sort column (the activity "5 W's"). Combined with `order` (asc/desc).
+            Defaults to `when` (occurredAt). `occurredAt`/`id` is always the tiebreaker.
+          schema:
+            type: string
             enum: [when, who, what, why, where]
         - name: productArea
           in: query
@@ -10989,7 +11502,7 @@ paths:
         derives teams client-side and saves the org structure via `POST /workspaces/{workspaceId}/org-chart`.
         Required columns: employee_id, name, email, title, department, team, manager_id, location.
         Optional: github_username (GitHub login for productivity ingest), bitbucket_nickname,
-        bitbucket_uuid, alternate_emails (comma-separated alternate work emails for AI tool spend
+        bitbucket_uuid, gitlab_username (GitLab.com or self-managed username), alternate_emails (comma-separated alternate work emails for AI tool spend
         attribution). Saving the SPA snapshot also materializes a scoring `org_chart` tree for
         team/person metrics when import members are present. Parse-only responses may include
         duplicateEmailWarnings, identityEmailPreview (cross-check against connected AI tool seat
@@ -12005,6 +12518,106 @@ paths:
         "403":
           $ref: "#/components/responses/Forbidden"
 
+  /workspaces/{workspaceId}/sources/discover:
+    post:
+      tags: [Workspace]
+      summary: List repositories a GitLab or Bitbucket source can read (does not persist)
+      description: >
+        Lists projects (GitLab.com, self-managed GitLab) or repositories (Bitbucket Cloud,
+        Bitbucket Data Center) for repository selection. Nothing is stored. Self-managed and
+        Data Center `baseUrl` must be `https`, public, and without credentials; private,
+        loopback, and link-local hosts are rejected before any request. `env:` token
+        references are rejected for self-hosted providers and never resolved from the request
+        for cloud providers. A blank or `***` token reuses the stored source with the same
+        provider, host, and account, and requires the editor or admin role. The list covers
+        the whole account (group or workspace/project key), not only `projects`/`repos`.
+        `repoCap` is the standard repository cap (50); ingest refuses to auto-select more
+        than that. Tokens are never returned.
+      operationId: postWorkspaceVcsRepoDiscovery
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/GitVcsSourceDto"
+            examples:
+              gitlabSelfManaged:
+                summary: Self-managed GitLab group
+                value:
+                  type: gitlab
+                  deployment: self_managed
+                  baseUrl: https://gitlab.example.com
+                  group: platform
+                  token: glpat-example
+              bitbucketDataCenter:
+                summary: Bitbucket Data Center project
+                value:
+                  type: bitbucket
+                  deployment: data_center
+                  baseUrl: https://bitbucket.example.com
+                  workspace: PLAT
+                  token: "***"
+      responses:
+        "200":
+          description: Repositories the source can read
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/VcsRepoDiscoveryResponseDto"
+        "400":
+          description: >
+            Invalid source (`error` is a code such as `base_url_required`, `base_url_invalid`,
+            `base_url_not_https`, `base_url_has_credentials`, `base_url_has_path`,
+            `base_url_host_blocked`, `env_ref_not_allowed`, `account_missing`, `token_missing`,
+            `unsupported_type`).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "502":
+          description: >
+            The provider rejected or failed the listing (`error` is `unauthorized`, `forbidden`,
+            `not_found`, `rate_limited`, or `discovery_failed`).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/vcs-provider-coverage:
+    get:
+      tags: [Workspace]
+      summary: GitLab and Bitbucket Data Coverage freshness (server-computed)
+      operationId: getWorkspaceVcsProviderCoverage
+      description: >
+        One row per configured GitLab or Bitbucket source. Freshness is computed on the server
+        from batch-written sync rows and succeeded readiness runs; no request field can mark a
+        row fresh. Git is fresh when the last complete ingest finished within
+        `gitFreshnessHours` (24) and no error was recorded after it. A readiness scan is fresh
+        within `readinessScanFreshnessDays` (30, America/New_York calendar days); `scansFresh`
+        requires every in-scope repository to have a fresh scan. A source with an invalid base
+        URL or missing account is `misconfigured`. Requires workspace membership.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Server-computed provider coverage
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/VcsProviderCoverageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "501":
+          description: Store does not support provider coverage
+
   /workspaces/{workspaceId}/ingest/productivity/repos/{slug}/retry:
     post:
       tags: [Workspace]
@@ -12915,6 +13528,14 @@ components:
       required: true
       schema:
         type: string
+    AssessmentReportId:
+      name: reportId
+      in: path
+      required: true
+      schema:
+        type: string
+        format: uuid
+      description: Stored assessment report id (`tai_workspace_assessment_reports.id`).
     EvalSuiteId:
       name: suiteId
       in: path
@@ -13315,29 +13936,196 @@ components:
         enum: [asc, desc]
         default: asc
 
-  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"
-    ZenHrSyncInProgress:
-      description: HRIS sync or ZenHR OAuth refresh already in progress for this workspace
-      content:
-        application/json:
-          schema:
-            $ref: "#/components/schemas/ErrorMessageDto"
-          example:
-            error: zenhr_sync_in_progress
+  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"
+    ZenHrSyncInProgress:
+      description: HRIS sync or ZenHR OAuth refresh already in progress for this workspace
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ErrorMessageDto"
+          example:
+            error: zenhr_sync_in_progress
+
+  schemas:
+    AssessmentManifestValidationBodyDto:
+      description: Body of runAssessmentManifestValidation; buildWorkspaceAssessmentManifest returns the server-built object as `validation`.
+      type: object
+      required:
+        - manifest
+        - workspaceId
+        - expectedWorkspaceId
+        - expectedRepositoryIds
+        - soldWindowComplete
+        - premiumAiAssessable
+        - namedPersonSectionIds
+        - tolerances
+      properties:
+        manifest:
+          type: object
+          required:
+            - offerId
+            - dictionaryVersion
+            - validation
+            - shareMode
+            - watermark
+            - scope
+            - windows
+            - sources
+            - consent
+            - sections
+          properties:
+            offerId:
+              type: string
+              enum: [engineering_readiness_baseline, agentic_ai_roi]
+            dictionaryVersion:
+              type: string
+            validation:
+              type: string
+              enum: [validated, not_validated]
+            shareMode:
+              type: string
+              enum: [internal, external]
+            watermark:
+              type: string
+              nullable: true
+              enum: ["NOT VALIDATED", "SAMPLE · SYNTHETIC DATA"]
+            scope:
+              type: object
+              required: [repositories, excluded]
+              properties:
+                repositories:
+                  type: array
+                  items:
+                    type: object
+                    required: [id, name]
+                    properties:
+                      id: { type: string }
+                      name: { type: string }
+                excluded:
+                  type: array
+                  items:
+                    type: object
+                    required: [id, name, reason]
+                    properties:
+                      id: { type: string }
+                      name: { type: string }
+                      reason: { type: string }
+            windows:
+              type: object
+              required: [pre, post, transitionDays]
+              properties:
+                pre:
+                  type: object
+                  nullable: true
+                  required: [start, end]
+                  properties:
+                    start: { type: string }
+                    end: { type: string }
+                post:
+                  type: object
+                  nullable: true
+                  required: [start, end]
+                  properties:
+                    start: { type: string }
+                    end: { type: string }
+                transitionDays:
+                  type: integer
+            sources:
+              type: array
+              items:
+                type: object
+                required: [provider, status, freshAt]
+                properties:
+                  provider: { type: string }
+                  status: { type: string }
+                  freshAt: { type: string, nullable: true }
+            consent:
+              type: object
+              required: [aggregateUse, recordedAt]
+              properties:
+                aggregateUse:
+                  type: string
+                  enum: [opt_in, opt_out, unset]
+                recordedAt:
+                  type: string
+                  nullable: true
+            sections:
+              type: array
+              items:
+                type: object
+                required: [id, status]
+                properties:
+                  id: { type: string }
+                  status:
+                    type: string
+                    enum: [ok, failed, omitted]
+                  reason: { type: string }
+        workspaceId:
+          type: string
+        expectedWorkspaceId:
+          type: string
+        expectedRepositoryIds:
+          type: array
+          items:
+            type: string
+        soldWindowComplete:
+          type: boolean
+        premiumAiAssessable:
+          type: boolean
+        namedPersonSectionIds:
+          type: array
+          items:
+            type: string
+        tolerances:
+          type: array
+          items:
+            type: object
+            required: [id, status]
+            properties:
+              id:
+                type: string
+              status:
+                type: string
+                enum: [unset, exceeded, within]
+
+    AssessmentManifestValidationResultDto:
+      type: object
+      required: [buyerDeliverable, validation, watermark, reasons, contentHash]
+      properties:
+        buyerDeliverable:
+          type: boolean
+        validation:
+          type: string
+          enum: [validated, not_validated]
+        watermark:
+          type: string
+          nullable: true
+          enum: ["NOT VALIDATED"]
+        reasons:
+          type: array
+          items:
+            type: object
+            required: [code, message]
+            properties:
+              code:
+                type: string
+              message:
+                type: string
+        contentHash:
+          type: string
 
-  schemas:
     TeamsInstallUrlDto:
       type: object
       required: [url]
@@ -13678,6 +14466,9 @@ components:
         bitbucketUuid:
           type: string
           description: Bitbucket account UUID (e.g. "{aeefb6b0-...}") to attribute merged PRs and reviews to this person in productivity ingest. Preferred over bitbucketNickname — Bitbucket PR payloads expose a stable uuid but not nickname. Resolves to the same person_id (email) as githubUsername.
+        gitlabUsername:
+          type: string
+          description: GitLab username (no @; GitLab.com or self-managed) to map merged merge requests and commits to this person in productivity ingest and the assessment active-engineer count. Stored lowercased. Resolves to the same person_id (email) as githubUsername.
         alternateEmails:
           type: string
           description: Optional comma-separated work emails that map to the same person for AI tool spend/usage (mirrors multi-login github_username). Primary email remains canonical person_id.
@@ -13752,6 +14543,8 @@ components:
           type: string
         bitbucketUuid:
           type: string
+        gitlabUsername:
+          type: string
         alternateEmails:
           type: string
           description: Comma-separated alternate work emails for AI tool attribution.
@@ -19072,17 +19865,199 @@ components:
         - platform-governance
         - delivery
 
+    ExternalVcsProviderDto:
+      type: string
+      enum: [gitlab_cloud, gitlab_self_managed, bitbucket_cloud, bitbucket_server]
+      description: >
+        `bitbucket_server` is Bitbucket Data Center. Self-hosted providers
+        (`gitlab_self_managed`, `bitbucket_server`) always carry `hostBaseUrl`.
+
+    GitVcsSourceDto:
+      type: object
+      description: >
+        GitLab or Bitbucket tenant source entry. GitLab: optional `group` (full path) and
+        `projects` (`group/sub/project`). Bitbucket: `workspace` (Cloud workspace or Data Center
+        project key) and optional `repos` (repository slugs). `deployment` selects self-hosted;
+        it then requires `baseUrl`.
+      required: [type]
+      additionalProperties: true
+      properties:
+        type:
+          type: string
+          enum: [gitlab, bitbucket]
+        deployment:
+          type: string
+          enum: [cloud, self_managed, data_center]
+        baseUrl:
+          type: string
+          maxLength: 512
+        group:
+          type: string
+          maxLength: 512
+        projects:
+          type: array
+          items:
+            type: string
+            maxLength: 512
+        workspace:
+          type: string
+          maxLength: 256
+        repos:
+          type: array
+          items:
+            type: string
+            maxLength: 256
+        token:
+          type: string
+          maxLength: 4096
+          description: Personal / project / HTTP access token, or `***` to reuse the stored token.
+
+    VcsDiscoveredRepoDto:
+      type: object
+      required: [slug, name, defaultBranch, webUrl]
+      properties:
+        slug:
+          type: string
+          description: "`group/sub/project` (GitLab) or `workspace/repo` / `PROJECT/repo` (Bitbucket)"
+        name:
+          type: string
+        defaultBranch:
+          type: string
+          nullable: true
+        webUrl:
+          type: string
+          nullable: true
+
+    VcsRepoDiscoveryResponseDto:
+      type: object
+      required: [provider, hostBaseUrl, account, truncated, repoCap, repositories]
+      properties:
+        provider:
+          $ref: "#/components/schemas/ExternalVcsProviderDto"
+        hostBaseUrl:
+          type: string
+          nullable: true
+        account:
+          type: string
+          description: GitLab group path (empty = token membership), Bitbucket workspace, or project key
+        truncated:
+          type: boolean
+          description: True when the provider page limit was reached; the list is incomplete.
+        repoCap:
+          type: integer
+        repositories:
+          type: array
+          items:
+            $ref: "#/components/schemas/VcsDiscoveredRepoDto"
+
+    VcsProviderCoverageRowDto:
+      type: object
+      required:
+        - provider
+        - hostBaseUrl
+        - account
+        - selfHosted
+        - state
+        - isFresh
+        - lastIngestSuccessAt
+        - lastErrorKind
+        - lastDiscoveryAt
+        - discoveredRepoCount
+        - staleForMs
+        - repoCount
+        - scannedRepoCount
+        - freshScanRepoCount
+        - scansFresh
+        - mergedHistorySince
+        - commitHistorySince
+      properties:
+        provider:
+          $ref: "#/components/schemas/ExternalVcsProviderDto"
+        hostBaseUrl:
+          type: string
+          nullable: true
+        account:
+          type: string
+        selfHosted:
+          type: boolean
+        state:
+          type: string
+          enum: [fresh, stale, never_synced, error, misconfigured]
+        isFresh:
+          type: boolean
+          description: Server-computed; true only when `state` is `fresh`.
+        lastIngestSuccessAt:
+          type: string
+          format: date-time
+          nullable: true
+        lastErrorKind:
+          type: string
+          nullable: true
+        lastDiscoveryAt:
+          type: string
+          format: date-time
+          nullable: true
+        discoveredRepoCount:
+          type: integer
+          nullable: true
+        staleForMs:
+          type: integer
+          nullable: true
+          description: Milliseconds past the Git freshness limit when `state` is `stale`.
+        repoCount:
+          type: integer
+          description: In-scope repositories stored for this source.
+        scannedRepoCount:
+          type: integer
+        freshScanRepoCount:
+          type: integer
+        scansFresh:
+          type: boolean
+        mergedHistorySince:
+          type: string
+          format: date-time
+          nullable: true
+          description: >-
+            Earliest merge time reached by the assessment merged-request history backfill for this
+            source; null when no backfill window has been written.
+        commitHistorySince:
+          type: string
+          format: date-time
+          nullable: true
+          description: >-
+            Instant from which every in-scope repository of this source has contiguous
+            default-branch commit-author coverage (latest per-repo coverage start); null when any
+            repository has no coverage.
+
+    VcsProviderCoverageDto:
+      type: object
+      required: [generatedAt, gitFreshnessHours, readinessScanFreshnessDays, sources]
+      properties:
+        generatedAt:
+          type: string
+          format: date-time
+        gitFreshnessHours:
+          type: integer
+        readinessScanFreshnessDays:
+          type: integer
+        sources:
+          type: array
+          items:
+            $ref: "#/components/schemas/VcsProviderCoverageRowDto"
+
     RepoProviderDto:
       type: object
       required: [kind, slug, webUrl]
       properties:
         kind:
           type: string
-          enum: [github, bitbucket_cloud, bitbucket_server]
+          enum: [github, bitbucket_cloud, bitbucket_server, gitlab_cloud, gitlab_self_managed]
         slug:
           type: string
           maxLength: 256
-          description: owner/repo (GitHub), workspace/repo_slug (Bitbucket Cloud), or PROJECT_KEY/repo_slug (Bitbucket Server)
+          description: >
+            owner/repo (GitHub), workspace/repo_slug (Bitbucket Cloud), PROJECT_KEY/repo_slug
+            (Bitbucket Server / Data Center), or group/sub/project (GitLab)
         webUrl:
           type: string
           format: uri
@@ -19100,7 +20075,9 @@ components:
           type: string
           format: uri
           nullable: true
-          description: Required for bitbucket_server (self-hosted); null for cloud providers
+          description: >
+            Required for bitbucket_server and gitlab_self_managed (self-hosted); null for cloud
+            providers
 
     ReadinessAnalyzeBodyDto:
       type: object
@@ -22277,29 +23254,309 @@ components:
         - integrations.zelt.added
         - integrations.zelt.removed
         - report.exported
+        - report.assessment_stored
+        - report.assessment_link_sent
+        - report.assessment_link_revoked
+        - report.assessment_downloaded
+        - report.assessment_hidden
+        - report.assessment_restored
         - workspace.aggregate_use.changed
+        - workspace.assessment_rollout.changed
+
+    AggregateUseNoticeStatusDto:
+      type: object
+      additionalProperties: false
+      required: [status]
+      description: Current legal-approved opt-in notice, or `unset` while opt-in is unavailable.
+      properties:
+        status:
+          type: string
+          enum: [approved, unset]
+        version:
+          type: string
+          description: Present only when `status` is `approved`. Send it back on opt-in.
+
+    AssessmentNamedEventDto:
+      type: string
+      enum: [major_release, migration, acquisition, policy_change]
+      description: Confounder-relevant named event from the assessment dictionary.
+
+    AssessmentRolloutDto:
+      type: object
+      additionalProperties: false
+      required:
+        - rolloutDay
+        - timezone
+        - boundary
+        - startsAt
+        - setBy
+        - setAt
+        - namedEvents
+        - namedEventsConfirmedBy
+        - namedEventsConfirmedAt
+      properties:
+        rolloutDay:
+          type: string
+          format: date
+          nullable: true
+          description: Confirmed rollout day (`YYYY-MM-DD`); null until set.
+        timezone:
+          type: string
+          enum: [America/New_York]
+        boundary:
+          type: string
+          enum: [midnight]
+        startsAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: UTC instant of 00:00 America/New_York on `rolloutDay`.
+        setBy:
+          type: object
+          nullable: true
+          additionalProperties: false
+          required: [userId, displayName]
+          properties:
+            userId:
+              type: string
+              format: uuid
+            displayName:
+              type: string
+              nullable: true
+        setAt:
+          type: string
+          format: date-time
+          nullable: true
+        namedEvents:
+          type: array
+          nullable: true
+          items:
+            $ref: "#/components/schemas/AssessmentNamedEventDto"
+          description: >
+            Named events confirmed during either matched window. Null means
+            the customer or operator has not confirmed yet, so the ROI
+            confounder check reports `confounder_inputs_missing`. An empty
+            array confirms none occurred.
+        namedEventsConfirmedBy:
+          type: object
+          nullable: true
+          additionalProperties: false
+          required: [userId, displayName]
+          properties:
+            userId:
+              type: string
+              format: uuid
+            displayName:
+              type: string
+              nullable: true
+        namedEventsConfirmedAt:
+          type: string
+          format: date-time
+          nullable: true
+
+    AssessmentRolloutPutDto:
+      type: object
+      additionalProperties: false
+      required: [rolloutDay]
+      properties:
+        rolloutDay:
+          type: string
+          format: date
+          description: Real calendar date, not after today in America/New_York.
+        namedEvents:
+          type: array
+          items:
+            $ref: "#/components/schemas/AssessmentNamedEventDto"
+          description: >
+            Omit to leave the stored named-event confirmation unchanged. Send
+            an empty array to confirm no named event occurred during either
+            matched window, or the events that did.
+
+    AssessmentRoiReasonDto:
+      type: string
+      enum:
+        - rollout_unset
+        - window_missing
+        - missing_cost
+        - non_usd_cost
+        - cost_not_attributable
+        - ship_weight_incomplete
+        - active_engineers_unknown
+        - non_positive_output
+        - normalization_unset
+        - confounder
+        - confounder_inputs_missing
+        - output_unit_mismatch
+      description: >
+        Why the matched-period ROI is not assessable. `cost_not_attributable` means a
+        billing-cycle bill (GitHub Copilot) overlaps the post window and cannot be split
+        by day. `active_engineers_unknown` means stored identities cannot yet be counted.
+        `confounder_inputs_missing` means a named-event, headcount, or repository-scope
+        check has no stored input.
+
+    AssessmentRoiDayRangeDto:
+      type: object
+      additionalProperties: false
+      required: [from, to]
+      properties:
+        from:
+          type: string
+          format: date
+        to:
+          type: string
+          format: date
+
+    AssessmentRoiWindowDto:
+      type: object
+      additionalProperties: false
+      required:
+        - from
+        - to
+        - requiredDays
+        - coveredDays
+        - complete
+        - workingDays
+        - activeEngineers
+        - mergedPullRequests
+        - shipWeight
+        - normalizedShipWeight
+      properties:
+        from:
+          type: string
+          format: date
+        to:
+          type: string
+          format: date
+        requiredDays:
+          type: integer
+          description: Calendar days in the window (90).
+        coveredDays:
+          type: integer
+          description: Calendar days with stored evidence.
+        complete:
+          type: boolean
+          description: Every calendar day is covered and the window ended before today.
+        workingDays:
+          type: integer
+          description: Monday–Friday days in America/New_York. No holidays.
+        activeEngineers:
+          type: integer
+          nullable: true
+        mergedPullRequests:
+          type: integer
+        shipWeight:
+          type: number
+          nullable: true
+          description: Sum of stored Ship Weight for unique merged pull requests; null if any is unscored.
+        normalizedShipWeight:
+          type: number
+          nullable: true
+          description: Ship Weight per active engineer per working day.
 
-    UnsetAssessmentDecisionDto:
+    AssessmentRoiDto:
       type: object
       additionalProperties: false
-      required: [status]
+      required:
+        - dictionaryVersion
+        - rolloutDay
+        - rolloutBoundary
+        - windows
+        - cost
+        - confounders
+        - status
+        - reason
+        - incrementalNormalizedShipWeight
+        - costPerIncrementalShipWeightUsd
+        - costPerMergedPullRequestUsd
       properties:
-        status:
+        dictionaryVersion:
           type: string
-          enum: [unset]
-
-    AggregateUseNoticeStatusDto:
-      type: object
-      additionalProperties: false
-      required: [status]
-      description: Current legal-approved opt-in notice, or `unset` while opt-in is unavailable.
-      properties:
-        status:
+        rolloutDay:
           type: string
-          enum: [approved, unset]
-        version:
+          format: date
+          nullable: true
+        rolloutBoundary:
+          type: object
+          additionalProperties: false
+          required: [timezone, boundary, startsAt]
+          properties:
+            timezone:
+              type: string
+              enum: [America/New_York]
+            boundary:
+              type: string
+              enum: [midnight]
+            startsAt:
+              type: string
+              format: date-time
+              nullable: true
+        windows:
+          type: object
+          additionalProperties: false
+          required: [pre, transition, post]
+          properties:
+            pre:
+              allOf:
+                - $ref: "#/components/schemas/AssessmentRoiWindowDto"
+              nullable: true
+            transition:
+              allOf:
+                - $ref: "#/components/schemas/AssessmentRoiDayRangeDto"
+              nullable: true
+            post:
+              allOf:
+                - $ref: "#/components/schemas/AssessmentRoiWindowDto"
+              nullable: true
+        cost:
+          type: object
+          additionalProperties: false
+          required: [amountUsd, currency, providers]
+          description: Recorded daily AI spend inside the post window. Never estimated.
+          properties:
+            amountUsd:
+              type: number
+              nullable: true
+            currency:
+              type: string
+              enum: [USD]
+              nullable: true
+            providers:
+              type: array
+              items:
+                type: string
+        confounders:
+          type: object
+          additionalProperties: false
+          required: [namedEvent, headcountChangeRatio, repositoryScopeChangeRatio]
+          properties:
+            namedEvent:
+              type: boolean
+              nullable: true
+              description: Null when no named-event input is stored.
+            headcountChangeRatio:
+              type: number
+              nullable: true
+            repositoryScopeChangeRatio:
+              type: number
+              nullable: true
+              description: Repositories with merged pull requests in only one window, over pre-window repositories.
+        status:
           type: string
-          description: Present only when `status` is `approved`. Send it back on opt-in.
+          enum: [assessable, not_assessable]
+        reason:
+          allOf:
+            - $ref: "#/components/schemas/AssessmentRoiReasonDto"
+          nullable: true
+        incrementalNormalizedShipWeight:
+          type: number
+          nullable: true
+        costPerIncrementalShipWeightUsd:
+          type: number
+          nullable: true
+        costPerMergedPullRequestUsd:
+          type: number
+          nullable: true
+          description: Separate correlation. Never the sold ROI figure.
 
     AggregateUseConsentDto:
       type: object
@@ -22404,7 +23661,7 @@ components:
       properties:
         version:
           type: string
-          enum: ["2026-10-20.1"]
+          enum: ["2026-10-24.1"]
         periodDays:
           type: integer
           enum: [90]
@@ -22576,9 +23833,21 @@ components:
             - countryAllowList
           properties:
             baselinePrice:
-              $ref: "#/components/schemas/UnsetAssessmentDecisionDto"
+              type: object
+              additionalProperties: false
+              required: [status, amountUsd, taxes]
+              properties:
+                status: { type: string, enum: [set] }
+                amountUsd: { type: integer, enum: [4999] }
+                taxes: { type: string, enum: [extra] }
             premiumPrice:
-              $ref: "#/components/schemas/UnsetAssessmentDecisionDto"
+              type: object
+              additionalProperties: false
+              required: [status, amountUsd, taxes]
+              properties:
+                status: { type: string, enum: [set] }
+                amountUsd: { type: integer, enum: [9999] }
+                taxes: { type: string, enum: [extra] }
             currency:
               type: object
               additionalProperties: false
@@ -22641,7 +23910,18 @@ components:
                     enum: [monday, tuesday, wednesday, thursday, friday]
                 holidays: { type: string, enum: [none] }
             countryAllowList:
-              $ref: "#/components/schemas/UnsetAssessmentDecisionDto"
+              type: object
+              additionalProperties: false
+              required: [status, countries, counselAccepted]
+              description: Owner decision without counsel acceptance; `counselAccepted` stays false.
+              properties:
+                status: { type: string, enum: [set] }
+                countries:
+                  type: array
+                  items:
+                    type: string
+                    enum: [US, BH, KW, OM, QA, SA, AE]
+                counselAccepted: { type: boolean, enum: [false] }
 
     ReportCenterExportRecordBodyDto:
       type: object
@@ -22727,6 +24007,286 @@ components:
             minLength: 1
             maxLength: 256
 
+    StoreAssessmentReportBodyDto:
+      type: object
+      additionalProperties: false
+      required: [pdfBase64, build, contentHash]
+      properties:
+        pdfBase64:
+          type: string
+          description: The buyer PDF, base64-encoded. Must start with `%PDF-`; at most 10 MiB decoded.
+        build:
+          $ref: "#/components/schemas/BuildAssessmentManifestBodyDto"
+        contentHash:
+          type: string
+          pattern: "^[0-9a-f]{64}$"
+          description: >
+            `result.contentHash` from the `buildWorkspaceAssessmentManifest` call the PDF was
+            rendered from. The server rebuilds the manifest and rejects a different hash.
+
+    BuildAssessmentManifestBodyDto:
+      type: object
+      additionalProperties: false
+      required: [offerId, shareMode, sections]
+      properties:
+        offerId:
+          type: string
+          enum: [engineering_readiness_baseline, agentic_ai_roi]
+        shareMode:
+          type: string
+          enum: [internal, external]
+        sections:
+          type: array
+          minItems: 1
+          maxItems: 64
+          description: Every selected section with its render status. Ids are unique.
+          items:
+            type: object
+            additionalProperties: false
+            required: [id, status]
+            properties:
+              id:
+                type: string
+                minLength: 1
+                maxLength: 128
+              status:
+                type: string
+                enum: [ok, failed, omitted]
+              reason:
+                type: string
+                maxLength: 500
+        roi:
+          description: >
+            The matched-period ROI chapter as printed, copied from the
+            `getWorkspaceAssessmentRoi` result it rendered. Null or omitted when the chapter
+            did not print one.
+          allOf:
+            - $ref: "#/components/schemas/PrintedAssessmentRoiDto"
+          nullable: true
+
+    PrintedAssessmentRoiDto:
+      type: object
+      additionalProperties: false
+      required:
+        - status
+        - reason
+        - incrementalNormalizedShipWeight
+        - costPerIncrementalShipWeightUsd
+        - costPerMergedPullRequestUsd
+      properties:
+        status:
+          type: string
+          enum: [assessable, not_assessable]
+        reason:
+          type: string
+          nullable: true
+        incrementalNormalizedShipWeight:
+          type: number
+          nullable: true
+        costPerIncrementalShipWeightUsd:
+          type: number
+          nullable: true
+        costPerMergedPullRequestUsd:
+          type: number
+          nullable: true
+
+    BuildAssessmentManifestResponseDto:
+      type: object
+      required: [validation, result]
+      properties:
+        validation:
+          $ref: "#/components/schemas/AssessmentManifestValidationBodyDto"
+        result:
+          $ref: "#/components/schemas/AssessmentManifestValidationResultDto"
+
+    StoreAssessmentReportRejectedDto:
+      type: object
+      required: [error, code]
+      properties:
+        error:
+          type: string
+        code:
+          type: string
+          enum: [not_buyer_deliverable, manifest_changed]
+        validation:
+          type: string
+          enum: [validated, not_validated]
+        reasons:
+          type: array
+          items:
+            type: object
+            required: [code, message]
+            properties:
+              code:
+                type: string
+              message:
+                type: string
+
+    AssessmentReportLinkDto:
+      type: object
+      required:
+        [
+          id,
+          reportId,
+          recipientUserId,
+          recipientEmail,
+          recipientName,
+          expiresAt,
+          revokedAt,
+          createdAt,
+          lastAccessedAt,
+          status,
+        ]
+      properties:
+        id:
+          type: string
+          format: uuid
+        reportId:
+          type: string
+          format: uuid
+        recipientUserId:
+          type: string
+          format: uuid
+        recipientEmail:
+          type: string
+          nullable: true
+          description: Null when the recipient is no longer a workspace member.
+        recipientName:
+          type: string
+          nullable: true
+        expiresAt:
+          type: string
+          format: date-time
+        revokedAt:
+          type: string
+          format: date-time
+          nullable: true
+        createdAt:
+          type: string
+          format: date-time
+        lastAccessedAt:
+          type: string
+          format: date-time
+          nullable: true
+        status:
+          type: string
+          enum: [active, expired, revoked]
+
+    AssessmentReportDto:
+      type: object
+      required:
+        [
+          id,
+          offerId,
+          sizeBytes,
+          sha256,
+          manifestHash,
+          createdAt,
+          createdBy,
+          hiddenAt,
+          restoreUntil,
+          status,
+          links,
+        ]
+      properties:
+        id:
+          type: string
+          format: uuid
+        offerId:
+          type: string
+          enum: [engineering_readiness_baseline, agentic_ai_roi]
+        sizeBytes:
+          type: integer
+        sha256:
+          type: string
+          description: sha256 of the plaintext PDF.
+        manifestHash:
+          type: string
+          description: "`contentHash` of the validated manifest."
+        createdAt:
+          type: string
+          format: date-time
+        createdBy:
+          type: string
+          format: uuid
+          nullable: true
+        hiddenAt:
+          type: string
+          format: date-time
+          nullable: true
+        restoreUntil:
+          type: string
+          format: date-time
+          nullable: true
+          description: End of the restore window. Not an erasure or backup purge date.
+        status:
+          type: string
+          enum: [available, hidden_restorable, restore_window_ended]
+        links:
+          type: array
+          items:
+            $ref: "#/components/schemas/AssessmentReportLinkDto"
+
+    AssessmentReportListDto:
+      type: object
+      required: [restoreWindowDays, secureLinkDays, reports]
+      properties:
+        restoreWindowDays:
+          type: integer
+          enum: [30]
+        secureLinkDays:
+          type: integer
+          enum: [14]
+          description: Default and maximum secure link lifetime in days.
+        reports:
+          type: array
+          items:
+            $ref: "#/components/schemas/AssessmentReportDto"
+
+    CreateAssessmentReportLinkBodyDto:
+      type: object
+      additionalProperties: false
+      required: [recipientUserId]
+      properties:
+        recipientUserId:
+          type: string
+          format: uuid
+          description: A current workspace member (`TeamMemberDto.id`).
+        expiresInDays:
+          type: integer
+          minimum: 1
+          maximum: 14
+          default: 14
+
+    CreateAssessmentReportLinkResponseDto:
+      type: object
+      required: [link, email]
+      properties:
+        link:
+          $ref: "#/components/schemas/AssessmentReportLinkDto"
+        email:
+          type: string
+          enum: [sent, skipped_missing_smtp, skipped_missing_base_url, failed]
+
+    AssessmentReportAccessErrorDto:
+      type: object
+      required: [error, code]
+      properties:
+        error:
+          type: string
+        code:
+          type: string
+          enum:
+            [
+              leaked_token,
+              removed_member,
+              wrong_workspace,
+              expired,
+              revoked,
+              invalid_grant,
+              report_hidden,
+            ]
+
     ReportCenterExportRecordResponseDto:
       type: object
       required: [ok, activityEntryId]