@thinkai/tai-api-contract 2.34.0-pr.810.e54f7dcd → 2.35.0-pr.811.d57af044

package/openapi/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: ThinkAI API
-  version: 2.34.0
+  version: 2.35.0
   description: >
     Contract surface for the AI Driven SDLC backend used by ThinkAI.
     Workspace-scoped routes use `/workspaces/{workspaceId}/...`.
@@ -1172,17 +1172,16 @@ paths:
       summary: Productivity insights — contributor drilldown
       description: >
         Weekly and daily activity rollups for a single contributor on
-        `/phase-c/c4/contributors/:id`. Distributes weekly merged PR counts from
-        precomputed person metrics across weekdays; includes fail-rate signals and
-        period-over-period summary deltas. Accepts org-chart person ids (typically email)
-        and synthetic GitHub scopes (`__github:{login}`) for contributors not in the org chart.
+        `/insights/productivity/contributors/:loginOrId`. Accepts GitHub login slugs
+        (preferred public URL), org-chart person ids (typically email), and synthetic
+        GitHub scopes (`__github:{login}`) for contributors not in the org chart.
       operationId: getProductivityInsightsContributor
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
         - name: contributorId
           in: path
           required: true
-          description: Org-chart person id or synthetic GitHub scope id (`__github:{login}`).
+          description: GitHub login slug, org-chart person id, or synthetic `__github:{login}` scope id.
           schema:
             type: string
         - $ref: "#/components/parameters/InsightsProductivityRangeId"
@@ -1916,7 +1915,7 @@ paths:
       operationId: postGithubInstallUrl
       description: >
         Creates a GitHub App installation URL scoped to the workspace and caller.
-        Body is optional; when omitted, defaults to `/phase-a/p4` return path.
+        Body is optional; when omitted, defaults to `/onboarding/integrations` return path.
         Optional `pickerSession` (from user OAuth org picker) recovers `returnPath` from the server-side picker snapshot when the multi-hop authorize→install flow should return to the page where OAuth started.
       security:
         - bearerAuth: []
@@ -2969,6 +2968,41 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/readiness/repos/by-slug/{providerSlug}:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Single repo readiness by provider slug
+      description: >
+        Returns one stored repository scorecard keyed by `providerSlug` (`owner/repo`).
+        Same response as `GET .../readiness/repos/{repoId}`. Unknown slug returns `404`.
+      operationId: getReadinessRepoBySlug
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - $ref: "#/components/parameters/ProviderSlug"
+      responses:
+        "200":
+          description: Repo score
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RepoReadinessScoreDetailDto"
+        "400":
+          description: Malformed providerSlug
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace or repository not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/readiness/repos/{repoId}:
     get:
       tags: [RepositoryReadiness]
@@ -3209,12 +3243,33 @@ paths:
       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 `eventType`, `actorUserId`, or date range (`since`/`until`).
+        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
+          required: false
+          description: >
+            Coarse product-area grouping filter (#156). `integration` = GitHub + AI-tool key events;
+            `agentic_foundation` = repos, readiness scans, fixes; `workspace_team` = members + HRIS;
+            `productivity` = productivity ingest lifecycle events. Omit (or pass `all`) for every area.
+          schema:
+            type: string
+            enum: [integration, agentic_foundation, workspace_team, productivity, all]
         - name: eventType
           in: query
           description: Filter to a specific event type.
@@ -3245,6 +3300,20 @@ paths:
             Filter by event namespace prefix (e.g. "fix", "repo", "integration", "readiness", "config", "member").
           schema:
             type: string
+        - name: eventSubcategory
+          in: query
+          required: false
+          description: >
+            Filter by a dotted event-type *subgroup* (#156): a strict prefix of an event type with one
+            or more segments (shorter than the full event type), matching every lifecycle event under it
+            in a single call. Single-segment values (e.g. `fix`, `readiness`, `repo`, `productivity`)
+            overlap with `eventCategory` so the same control can filter at any depth. Example:
+            `integrations.cursor.execution_key` returns `integrations.cursor.execution_key.added`,
+            `.updated`, `.removed`, and `.check_failed`; `integrations.cursor` returns all Cursor key
+            events; `fix` returns all fix lifecycle events. Must be one of the known subcategories or the
+            request is rejected (400).
+          schema:
+            type: string
         - name: search
           in: query
           required: false
@@ -3278,6 +3347,100 @@ paths:
               schema:
                 $ref: "#/components/schemas/ErrorMessageDto"
 
+  /workspaces/{workspaceId}/activity/export:
+    get:
+      tags: [WorkspaceActivity]
+      summary: Export workspace activity log as CSV
+      operationId: exportWorkspaceActivity
+      description: >
+        Export the workspace activity log as an RFC 4180 CSV file (one row per event). Accepts the
+        same filters as `GET /workspaces/{workspaceId}/activity` (`eventType`, `eventCategory`,
+        `eventSubcategory`, `productArea`, `actorUserId`, `since`, `until`, `search`, `sort`, `order`);
+        `limit`/`offset` are ignored — the export returns up to 50000 matching rows within the sort.
+        Columns: occurredAt, eventType, eventCategory, actorType, actorName, actorEmail, repoName,
+        integrationType, metadata. Opaque internal identifiers (actorUserId, repoId, integrationId,
+        fixRequestId, issueId, readinessRunId) are omitted — the human-readable equivalents are
+        already present and the IDs carry no value in a user-facing export.
+        The response sets `Content-Disposition: attachment` with a `.csv` filename.
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+        - name: sort
+          in: query
+          required: false
+          schema:
+            type: string
+            enum: [when, who, what, why, where]
+        - $ref: "#/components/parameters/PaginationOrder"
+        - name: productArea
+          in: query
+          required: false
+          schema:
+            type: string
+            enum: [integration, agentic_foundation, workspace_team, productivity, all]
+        - name: eventType
+          in: query
+          required: false
+          schema:
+            $ref: "#/components/schemas/ActivityLogEventTypeDto"
+        - name: eventCategory
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: eventSubcategory
+          in: query
+          required: false
+          description: Dotted event-type subgroup prefix (see the activity list endpoint).
+          schema:
+            type: string
+        - name: actorUserId
+          in: query
+          required: false
+          schema:
+            type: string
+            format: uuid
+        - name: since
+          in: query
+          required: false
+          schema:
+            type: string
+            format: date-time
+        - name: until
+          in: query
+          required: false
+          schema:
+            type: string
+            format: date-time
+        - name: search
+          in: query
+          required: false
+          schema:
+            type: string
+            maxLength: 200
+      responses:
+        "200":
+          description: CSV file of activity log entries
+          content:
+            text/csv:
+              schema:
+                type: string
+        "400":
+          description: Invalid query parameters
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          description: Workspace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
   /workspaces/{workspaceId}/readiness/score-history:
     get:
       tags: [RepositoryReadiness]
@@ -4045,6 +4208,130 @@ paths:
         "403":
           $ref: "#/components/responses/Forbidden"
 
+  /workspaces/{workspaceId}/repo-eligibility:
+    get:
+      tags: [RepositoryReadiness]
+      summary: Get repo-sync eligibility gate (defaults + per-workspace overrides)
+      description: >
+        Returns the effective repo-sync eligibility gate (archived / fork / size / count) for the
+        workspace: the global `defaults`, any per-workspace `overrides`, the merged `effective`
+        values, and whether the caller can edit without platform-admin (`canEditUnrestricted`).
+        Member-level read access.
+      operationId: getWorkspaceRepoEligibility
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      responses:
+        "200":
+          description: Effective repo-eligibility configuration
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/WorkspaceRepoEligibilityDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+    put:
+      tags: [RepositoryReadiness]
+      summary: Set per-workspace repo-sync eligibility overrides
+      description: >
+        Set (or clear, with an empty `overrides`) the per-workspace repo-sync eligibility overrides.
+        **Platform admins** may set any value (raise caps, `0` = unlimited, include archived/forks).
+        **Workspace admins** may only make the gate *more restrictive* than the platform defaults
+        (lower caps, exclude archived/forks) — exceeding a platform limit returns `403`
+        (`repo_eligibility_bound_exceeded`). Requires workspace admin or platform admin.
+      operationId: putWorkspaceRepoEligibility
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [overrides]
+              properties:
+                overrides:
+                  $ref: "#/components/schemas/RepoEligibilityOverridesDto"
+      responses:
+        "200":
+          description: Overrides saved
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [overrides, effective]
+                properties:
+                  overrides:
+                    $ref: "#/components/schemas/RepoEligibilityOverridesDto"
+                  effective:
+                    $ref: "#/components/schemas/RepoEligibilityConfigDto"
+        "400":
+          description: Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          description: Forbidden, or a workspace-admin value exceeds a platform limit (`repo_eligibility_bound_exceeded`)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+
+  /workspaces/{workspaceId}/repo-eligibility/refresh-languages:
+    post:
+      tags: [RepositoryReadiness]
+      summary: Force a language/stack re-detection on the next sync
+      description: >
+        Admin maintenance action: invalidate the cached language/stack freshness marker so the
+        next GitHub repo sync re-fetches `GET /repos/{owner}/{repo}/languages` and recomputes the
+        per-language breakdown and supported stacks. Use after adding a newly-supported language
+        to a repo, or when a repo's stack detection looks stale. Optionally scope to a single repo
+        via `repoSlug` (`owner/name`); omit it to reset every repo in the workspace. Requires
+        workspace admin or platform admin. The refresh itself happens on the next sync (e.g. when
+        the GitHub repo list is loaded with `refresh=true`); the readiness scan also refreshes the
+        breakdown on each successful run.
+      operationId: refreshWorkspaceRepoLanguages
+      parameters:
+        - $ref: "#/components/parameters/WorkspaceId"
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                repoSlug:
+                  type: string
+                  description: Optional `owner/name` to scope the refresh to a single repo. Omit to reset all repos.
+      responses:
+        "200":
+          description: Freshness invalidated; languages will be re-detected on the next sync.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, reposReset]
+                properties:
+                  ok:
+                    type: boolean
+                  reposReset:
+                    type: integer
+                    description: Number of repo rows whose language/stack cache was invalidated.
+        "400":
+          description: Invalid request body
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorMessageDto"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+
   /workspaces/{workspaceId}/readiness/cursor-key-usage:
     get:
       tags: [RepositoryReadiness]
@@ -4247,7 +4534,7 @@ paths:
         - $ref: "#/components/parameters/WorkspaceId"
       responses:
         "200":
-          description: Progress (empty completedSteps when no row exists yet; updatedAt is synthetic in that case)
+          description: Progress (empty completedStepIds when no row exists yet; updatedAt is synthetic in that case)
           content:
             application/json:
               schema:
@@ -4554,8 +4841,10 @@ paths:
       tags: [YourAiJourney]
       summary: Workspace journey step completion
       description: >
-        Returns the workspace-scoped journey progress state. Returns an empty `completedSteps`
-        list with a synthetic `updatedAt` if no row exists yet. Covers issue #271.
+        Returns the workspace-scoped journey progress state. Returns an empty `completedStepIds`
+        array when no row exists yet (updatedAt is synthetic in that case). Values are canonical
+        step IDs (see `JourneyStepId`); legacy route strings are accepted on PUT and normalized.
+        Covers issue #271.
       operationId: getYourAiJourneyProgress
       parameters:
         - $ref: "#/components/parameters/WorkspaceId"
@@ -4860,6 +5149,19 @@ components:
       schema:
         type: string
         format: uuid
+    ProviderSlug:
+      name: providerSlug
+      in: path
+      required: true
+      description: >
+        Provider repository slug in `owner/repo` form (GitHub). Used for shareable public URLs;
+        resolves to the same row as `repoId` UUID internally.
+      schema:
+        type: string
+        minLength: 1
+        maxLength: 512
+        pattern: '^[^/]+/[^/]+$'
+        example: thinkai-llc/thinkai-platform-backend
     ProjectId:
       name: projectId
       in: path
@@ -5732,16 +6034,6 @@ components:
           type: number
         failRatePercent:
           type: number
-          description: DORA change failure rate (deployments/incidents), not CI build failures.
-        ciFailRatePercent:
-          type: number
-          description: >
-            GitHub Actions / Checks CI build failure rate for the week bucket
-            (failed runs / (failed + passed) * 100). Zero when GitHub Actions CI is disabled.
-        ciBuildFailuresCount:
-          type: integer
-          minimum: 0
-          description: Count of build.failed events in the week bucket when CI ingest is enabled.
         avgReviewWaitHours:
           type: number
           description: Mean hours from PR creation to first review in this week bucket.
@@ -5801,9 +6093,6 @@ components:
         generatedAt:
           type: string
           format: date-time
-        githubActionsCiEnabled:
-          type: boolean
-          description: True when the workspace has opted in to GitHub Actions CI ingest.
         teams:
           type: array
           items:
@@ -5897,9 +6186,6 @@ components:
         avgFailRatePercent:
           type: number
           description: Average change failure rate over the range when available.
-        avgCiFailRatePercent:
-          type: number
-          description: Average GitHub Actions CI build failure rate over the range when CI ingest is enabled.
 
     ProductivityInsightsTeamSummaryDto:
       type: object
@@ -5912,10 +6198,6 @@ components:
           type: number
         avgFailRatePercent:
           type: number
-          description: Average DORA change failure rate over the range when available.
-        avgCiFailRatePercent:
-          type: number
-          description: Average GitHub Actions CI build failure rate over the range when CI ingest is enabled.
         headcount:
           type: integer
           minimum: 0
@@ -5976,9 +6258,6 @@ components:
         generatedAt:
           type: string
           format: date-time
-        githubActionsCiEnabled:
-          type: boolean
-          description: True when the workspace has opted in to GitHub Actions CI ingest.
         items:
           type: array
           description: Present when `teamId` query is omitted — top-ranked teams.
@@ -6100,10 +6379,6 @@ components:
           minimum: 0
         avgFailRate:
           type: number
-          description: Average DORA change failure rate over the range when available.
-        avgCiFailRate:
-          type: number
-          description: Average GitHub Actions CI build failure rate over the range when CI ingest is enabled.
         mergedPrDelta:
           type: number
         avgMergedPrsPerWeekDelta:
@@ -6112,9 +6387,6 @@ components:
           type: number
         avgFailRateDelta:
           type: number
-        avgCiFailRateDelta:
-          type: number
-          description: Change in average CI build failure rate vs the prior comparison window.
 
     ProductivityInsightsContributorDetailDto:
       type: object
@@ -6146,9 +6418,6 @@ components:
         generatedAt:
           type: string
           format: date-time
-        githubActionsCiEnabled:
-          type: boolean
-          description: True when the workspace has opted in to GitHub Actions CI ingest.
         contributor:
           $ref: "#/components/schemas/ProductivityInsightsContributorProfileDto"
         weeks:
@@ -6185,9 +6454,6 @@ components:
         avgFailRatePercent:
           type: number
           description: Mean weekly change-failure rate when available.
-        avgCiFailRatePercent:
-          type: number
-          description: Mean weekly GitHub Actions CI build failure rate when CI ingest is enabled.
 
     ProductivityInsightsNeedsAttentionDto:
       type: object
@@ -6207,9 +6473,6 @@ components:
         generatedAt:
           type: string
           format: date-time
-        githubActionsCiEnabled:
-          type: boolean
-          description: True when GitHub Actions CI ingest is enabled for this workspace.
         items:
           type: array
           items:
@@ -6843,6 +7106,195 @@ components:
           format: date-time
           nullable: true
           description: Last push or metadata update from GitHub when available.
+        archived:
+          type: boolean
+          nullable: true
+          description: True when the repository is archived (read-only on GitHub).
+        fork:
+          type: boolean
+          nullable: true
+          description: True when the repository is a fork of another repository.
+        disabled:
+          type: boolean
+          nullable: true
+          description: True when the repository is disabled on GitHub.
+        size:
+          type: integer
+          nullable: true
+          description: Repository size in KB as reported by GitHub.
+        ineligibleReasons:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: >
+            Hard structural reasons this repo cannot be analyzed (archived, disabled, too-large,
+            workspace repo cap). Each entry is a human-readable explanation (e.g. "This repo is
+            archived"). Empty or absent means no hard block. Forks and unsupported-language repos
+            are NOT listed here — they are advisory `warnings` (#729) and remain analyzable.
+        warnings:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: >
+            Non-blocking advisories shown alongside an otherwise-analyzable repo (#729). Includes
+            forks ("results reflect the forked code") and repos with no v1-supported stack, where
+            the message embeds the GitHub language mix in percent. Absent/empty when there are no
+            warnings. Unlike `ineligibleReasons`, warnings do NOT disable analyze/score/fix actions.
+        eligibilityStatus:
+          type: string
+          enum: [eligible, ineligible]
+          nullable: true
+          description: >
+            Whether the repo can be analyzed (issue #44/#729). `ineligible` only for HARD
+            structural gates (archived, disabled, too-large, workspace repo cap) — such repos render
+            read-only in the AF list. A repo with no supported stack or that is a fork is `eligible`
+            and carries a non-blocking `warnings` entry instead of being blocked.
+        eligibilityReason:
+          type: string
+          nullable: true
+          description: >
+            Human-readable explanation when `eligibilityStatus` is `ineligible` (e.g. "This repo
+            is archived"). For advisory language/fork notices see `warnings`, not this field.
+        primaryStack:
+          type: string
+          nullable: true
+          description: >
+            Dominant supported stack (by GitHub language bytes), one of
+            backend_jvm | ios_app | web_spa | backend_go | backend_python. Null when no supported
+            stack was detected.
+        secondaryStack:
+          type: string
+          nullable: true
+          description: Second supported stack for a multi-stack repo, or null.
+        supportedStacks:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: >
+            All supported stacks detected for the repo (ordered, primary first). Empty/null
+            when no supported stack is present. Drives multi-stack scanning and the orange
+            mixed-monorepo box in the AF UI.
+        languageBreakdown:
+          type: array
+          nullable: true
+          description: >
+            Per-language share of the repo from GitHub's `GET /repos/{owner}/{repo}/languages`
+            byte counts, ordered by share descending (#729). Powers the "language mix" shown in
+            the unsupported-stack warning. Absent/null until the repo has been synced with a
+            language resolver.
+          items:
+            type: object
+            required: [language, percent, supported]
+            properties:
+              language:
+                type: string
+                description: GitHub language name (e.g. "TypeScript", "Go").
+              percent:
+                type: number
+                format: float
+                description: >
+                  Share of total language bytes, rounded to four decimal places (e.g. 64.2153). The
+                  extra precision keeps small/near-tied languages distinguishable for a hover tag;
+                  render it rounded for compact labels. May not sum to exactly 100 due to rounding.
+              supported:
+                type: boolean
+                description: >
+                  True when this language maps to a v1-supported stack; false when the language
+                  is not supported. Lets the UI flag exactly which languages are not (fully)
+                  supported in a mixed/monorepo.
+              stack:
+                type: string
+                nullable: true
+                description: >
+                  The supported stack this language maps to
+                  (backend_jvm | ios_app | web_spa | backend_go | backend_python), or null when
+                  the language is unsupported.
+
+    RepoEligibilityConfigDto:
+      type: object
+      description: Resolved repo-sync eligibility gate (defaults or effective). All fields present.
+      required: [excludeArchived, excludeForks, maxRepoSizeKb, maxReposPerWorkspace]
+      properties:
+        excludeArchived:
+          type: boolean
+          description: Skip archived repos during GitHub repo sync.
+        excludeForks:
+          type: boolean
+          description: Skip forked repos. Forks are included by default.
+        maxRepoSizeKb:
+          type: integer
+          description: Max repo size in KB (GitHub-reported). 0 = no limit.
+        maxReposPerWorkspace:
+          type: integer
+          description: Max repos materialized per workspace per sync. 0 = no limit.
+
+    RepoEligibilityOverridesDto:
+      type: object
+      additionalProperties: false
+      description: >
+        Per-workspace overrides for the repo-sync eligibility gate. Any field present wins over the
+        global default; omit a field to inherit the default. An empty object clears all overrides.
+      properties:
+        excludeArchived:
+          type: boolean
+          nullable: true
+        excludeForks:
+          type: boolean
+          nullable: true
+        maxRepoSizeKb:
+          type: integer
+          minimum: 0
+          nullable: true
+        maxReposPerWorkspace:
+          type: integer
+          minimum: 0
+          nullable: true
+
+    WorkspaceRepoEligibilityDto:
+      type: object
+      required: [defaults, overrides, effective, canEditUnrestricted]
+      properties:
+        defaults:
+          $ref: "#/components/schemas/RepoEligibilityConfigDto"
+        overrides:
+          $ref: "#/components/schemas/RepoEligibilityOverridesDto"
+        effective:
+          $ref: "#/components/schemas/RepoEligibilityConfigDto"
+        canEditUnrestricted:
+          type: boolean
+          description: True when the caller is a platform admin (may set any value, incl. raising caps).
+
+    RepoEligibilityLimitsDto:
+      type: object
+      additionalProperties: false
+      description: >
+        Effective repo-eligibility limits applied to the GitHub repo list, plus the current count
+        of eligible repos. Lets the UI render per-repo "size / limit" (compare each repo's `size`
+        in `GithubInstalledRepoDto` to `maxRepoSizeKb`) and workspace "N / cap" usage
+        (`eligibleRepoCount` / `maxReposPerWorkspace`).
+      required: [maxRepoSizeKb, maxReposPerWorkspace, excludeArchived, excludeForks, eligibleRepoCount]
+      properties:
+        maxRepoSizeKb:
+          type: integer
+          description: Per-repo size cap in KB (GitHub-reported). 0 = no limit.
+        maxReposPerWorkspace:
+          type: integer
+          description: Max repos that can be eligible per workspace. 0 = no limit.
+        excludeArchived:
+          type: boolean
+          description: Whether archived repos are treated as a hard block.
+        excludeForks:
+          type: boolean
+          description: Whether forked repos are excluded by the sync gate (forks are a warning, not a block).
+        eligibleRepoCount:
+          type: integer
+          minimum: 0
+          description: >
+            Repos currently counting as eligible (eligibilityStatus != "ineligible"), i.e. those that
+            count toward `maxReposPerWorkspace`.
 
     GithubMissingPermissionDto:
       type: object
@@ -7013,6 +7465,14 @@ components:
           allOf:
             - $ref: "#/components/schemas/GithubInstalledRepoListDto"
           description: Paginated merged installation repositories when `installed` is true.
+        eligibilityLimits:
+          nullable: true
+          allOf:
+            - $ref: "#/components/schemas/RepoEligibilityLimitsDto"
+          description: >
+            Effective size/count limits and current eligible-repo usage for the repo list. Present
+            when `installed` is true. Pair with each repo's `size` and `eligibilityStatus` to show
+            "size / limit" and "N / cap" in the UI.
         manageUrl:
           type: string
           format: uri
@@ -7685,10 +8145,8 @@ components:
           type: array
           description: >
             Individual rubric criterion outcomes from the latest successful scan.
-            Always present on the single-repo detail endpoint. When the repo has a
-            succeeded scan but a dimension was not evaluated (e.g. Section I on older
-            runs), the API returns full rubric placeholders with status `blocked`.
-            Empty array only when the repo has no succeeded scan yet.
+            Always present on the single-repo detail endpoint; empty array when no
+            scan has completed yet for this dimension.
           items:
             $ref: "#/components/schemas/CriterionDetailDto"
         issues:
@@ -7873,6 +8331,79 @@ components:
           nullable: true
           enum: [github_removed, installation_disconnected, installation_replaced, superseded]
           description: Why the repo was archived. Only present when `archivedAt` is set.
+        eligibilityStatus:
+          type: string
+          enum: [eligible, ineligible]
+          nullable: true
+          description: >
+            Whether the repo can be analyzed (#44/#729). Language support no longer makes a repo
+            `ineligible` — a missing v1-supported stack is surfaced via `warnings` and the repo
+            stays analyzable. It becomes `ineligible` when the most recent scan hit a hard
+            size/file-count limit (e.g. code-size or file-count exceeded): the repo is then
+            restricted here too so this surface matches the GitHub connect list's size gate after
+            the scan. Null until the first sync/scan computes it.
+        eligibilityReason:
+          type: string
+          nullable: true
+          description: >
+            Human-readable explanation when `eligibilityStatus` is `ineligible` (e.g. the size /
+            file-count limit message from the last scan). For advisory language notices see
+            `warnings`.
+        warnings:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: >
+            Non-blocking advisories for an analyzable repo (#729): no v1-supported stack (with the
+            language mix), and hard-limit run outcomes (code size / file count exceeded) carried from
+            the last run. Absent/empty when there are no warnings.
+        primaryStack:
+          type: string
+          nullable: true
+          description: Dominant supported stack — backend_jvm | ios_app | web_spa | backend_go | backend_python. Null when no supported stack/uncomputed.
+        secondaryStack:
+          type: string
+          nullable: true
+          description: Second supported stack for a multi-stack repo, or null.
+        supportedStacks:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: All supported stacks detected (ordered, primary first). Empty/null when none.
+        languageBreakdown:
+          type: array
+          nullable: true
+          description: >
+            Per-language share from GitHub languages (#729), ordered by share descending. Each entry
+            has `supported`/`stack` so the UI can tag which languages are (not) supported. Absent
+            until the repo has been synced with a language resolver.
+          items:
+            type: object
+            required: [language, percent, supported]
+            properties:
+              language:
+                type: string
+              percent:
+                type: number
+                format: float
+                description: Share of total language bytes, rounded to four decimal places (e.g. 64.2153).
+              supported:
+                type: boolean
+              stack:
+                type: string
+                nullable: true
+        sizeKb:
+          type: integer
+          nullable: true
+          minimum: 0
+          description: >
+            GitHub-reported repository size in KB (includes git history), refreshed on each readiness
+            scan (#729). Compare against `eligibilityLimits.maxRepoSizeKb` on the list response to show
+            per-repo "size / limit". When the size exceeds the limit the latest scan is recorded as
+            `partial_failed` with `lastRunErrorCode = exceeded_repo_size_limit` and the repo is marked
+            `ineligible`. Null until a scan has populated it.
 
     RepoReadinessScoreDetailDto:
       type: object
@@ -7943,6 +8474,55 @@ components:
           type: string
           nullable: true
           enum: [github_removed, installation_disconnected, installation_replaced, superseded]
+        eligibilityStatus:
+          type: string
+          enum: [eligible, ineligible]
+          nullable: true
+          description: See RepoReadinessScoreDto.eligibilityStatus. Language support is advisory (#729) and surfaced via `warnings`.
+        eligibilityReason:
+          type: string
+          nullable: true
+        warnings:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: Non-blocking advisories (no v1-supported stack, hard-limit run outcomes). See RepoReadinessScoreDto.warnings.
+        primaryStack:
+          type: string
+          nullable: true
+        secondaryStack:
+          type: string
+          nullable: true
+        supportedStacks:
+          type: array
+          nullable: true
+          items:
+            type: string
+        languageBreakdown:
+          type: array
+          nullable: true
+          description: Per-language share with `supported`/`stack` tags. See RepoReadinessScoreDto.languageBreakdown.
+          items:
+            type: object
+            required: [language, percent, supported]
+            properties:
+              language:
+                type: string
+              percent:
+                type: number
+                format: float
+                description: Share of total language bytes, rounded to four decimal places (e.g. 64.2153).
+              supported:
+                type: boolean
+              stack:
+                type: string
+                nullable: true
+        sizeKb:
+          type: integer
+          nullable: true
+          minimum: 0
+          description: GitHub-reported repository size in KB, refreshed on each scan. See RepoReadinessScoreDto.sizeKb.
 
     AgenticFoundationDashboardSummaryDto:
       type: object
@@ -8006,6 +8586,34 @@ components:
           type: integer
           minimum: 0
 
+    ReadinessEligibilityLimitsDto:
+      type: object
+      additionalProperties: false
+      description: >
+        Effective size/code limits enforced by readiness scans (#729). Lets the UI render per-repo
+        "size / limit" (compare each repo's `sizeKb` to `maxRepoSizeKb`) and explain why a repo is
+        `ineligible` due to a hard size/file-count limit. A repo over `maxRepoSizeKb` is skipped on the
+        next scan (recorded `partial_failed` with `exceeded_repo_size_limit`); code-line/file counts are
+        evaluated post-clone via `cloc`.
+      required: [maxRepoSizeKb, maxLinesOfCode, maxFileCount, maxReposPerWorkspace]
+      properties:
+        maxRepoSizeKb:
+          type: integer
+          minimum: 0
+          description: Per-repo GitHub size cap in KB (includes git history). 0 = no limit.
+        maxLinesOfCode:
+          type: integer
+          minimum: 0
+          description: Max total lines of code (cloc) before a scan is skipped. 0 = no limit.
+        maxFileCount:
+          type: integer
+          minimum: 0
+          description: Max source file count (cloc) before a scan is skipped. 0 = no limit.
+        maxReposPerWorkspace:
+          type: integer
+          minimum: 0
+          description: Max repos that can be eligible per workspace. 0 = no limit.
+
     ReadinessRepoListDto:
       allOf:
         - $ref: "#/components/schemas/PageMetaDto"
@@ -8016,6 +8624,8 @@ components:
               type: array
               items:
                 $ref: "#/components/schemas/RepoReadinessScoreDto"
+            eligibilityLimits:
+              $ref: "#/components/schemas/ReadinessEligibilityLimitsDto"
 
     ReadinessRepoDetailListDto:
       description: >
@@ -8584,12 +9194,38 @@ components:
           items:
             $ref: "#/components/schemas/AiStrategyPhaseBlockDto"
 
+    JourneyStepId:
+      type: string
+      description: Canonical journey step identifier (stable across URL reshuffles).
+      enum:
+        - onboarding.workspace
+        - onboarding.ai_readiness
+        - onboarding.integrations
+        - readiness.dashboard
+        - readiness.fix_queue
+        - readiness.activity
+        - insights.productivity
+        - insights.productivity.by_user
+        - insights.productivity.by_team
+        - insights.ai_usage
+        - insights.ai_usage.by_user
+        - insights.ai_usage.by_team
+        - insights.ai_usage.by_model
+
     JourneyProgressDto:
       type: object
-      required: [completedSteps, updatedAt]
+      required: [completedStepIds, updatedAt]
       properties:
+        completedStepIds:
+          type: array
+          items:
+            $ref: "#/components/schemas/JourneyStepId"
+          description: Canonical completed journey step IDs.
         completedSteps:
           type: array
+          deprecated: true
+          description: >
+            Deprecated alias of completedStepIds (legacy clients). Omitted on new responses when empty.
           items:
             type: string
         updatedAt:
@@ -8598,12 +9234,22 @@ components:
 
     JourneyProgressUpdateDto:
       type: object
-      required: [completedSteps]
       properties:
+        completedStepIds:
+          type: array
+          items:
+            $ref: "#/components/schemas/JourneyStepId"
+          description: Idempotent replace-all of completed step IDs.
         completedSteps:
           type: array
+          deprecated: true
+          description: >
+            Deprecated input alias — route strings and legacy `/phase-*` paths are normalized to step IDs.
           items:
             type: string
+      anyOf:
+        - required: [completedStepIds]
+        - required: [completedSteps]
 
     ThemePreference:
       type: string
@@ -8852,10 +9498,15 @@ components:
           format: date-time
         journey:
           type: object
-          required: [completedSteps, updatedAt]
+          required: [completedStepIds, updatedAt]
           properties:
+            completedStepIds:
+              type: array
+              items:
+                $ref: "#/components/schemas/JourneyStepId"
             completedSteps:
               type: array
+              deprecated: true
               items:
                 type: string
             updatedAt:
@@ -9003,18 +9654,39 @@ components:
         - readiness.scan_completed
         - readiness.scan_failed
         - readiness.scan_partial
-        - config.cursor.added
-        - config.cursor.updated
-        - config.cursor.removed
-        - config.cursor.platform_key_enabled
-        - config.cursor.platform_key_disabled
-        - config.claude.added
-        - config.claude.updated
-        - config.claude.removed
-        - config.agent_execution.provider_changed
+        - integrations.agent_execution.provider_changed
+        - integrations.repo_eligibility.overrides_changed
+        - integrations.repo_eligibility.languages_refresh_requested
+        - integrations.cursor.platform_key_enabled
+        - integrations.cursor.platform_key_disabled
         - member.invited
         - member.role_changed
         - member.removed
+        - hris.personio.sync_started
+        - hris.personio.sync_completed
+        - hris.personio.sync_failed
+        - hris.sync_started
+        - hris.sync_completed
+        - hris.sync_failed
+        - repo.sync_skipped
+        - integrations.cursor.execution_key.added
+        - integrations.cursor.execution_key.updated
+        - integrations.cursor.execution_key.removed
+        - integrations.cursor.execution_key.check_failed
+        - integrations.cursor.admin_key.added
+        - integrations.cursor.admin_key.updated
+        - integrations.cursor.admin_key.removed
+        - integrations.claude.execution_key.added
+        - integrations.claude.execution_key.updated
+        - integrations.claude.execution_key.removed
+        - integrations.claude.execution_key.check_failed
+        - integrations.claude.admin_key.added
+        - integrations.claude.admin_key.updated
+        - integrations.claude.admin_key.removed
+        - readiness.scan_precheck_failed
+        - productivity.ingest.completed
+        - productivity.ingest.failed
+        - productivity.ingest.skipped
 
     ActivityLogActorDto:
       type: object