openapi: 3.1.0
info:
  title: ItWorx Knowledge Hub API
  version: 0.1.0-draft
  description: |
    Versioned API for the ItWorx Knowledge Hub web client and scoped automation.
    This is not an MCP transport. The future MCP service will consume this API.
servers:
  - url: /api/v1
tags:
  - name: System
  - name: Setup
  - name: Auth
  - name: Admin
  - name: Search
  - name: Rag
  - name: Pages
  - name: Drafts
  - name: Templates
  - name: Attachments
  - name: Imports
  - name: Source batch purge
  - name: Projects
  - name: Decisions
  - name: Runbooks
  - name: Service accounts
  - name: Backups
  - name: Infrastructure
  - name: Activity
  - name: Workspace
  - name: Ingestion proposals
security:
  - cookieAuth: []
  - bearerAuth: []
paths:
  /ingestion-proposals:
    get:
      tags: [Ingestion proposals]
      operationId: listIngestionProposals
      description: Human review queue only. Page/pageSize and all filters are evaluated server-side; cursor/limit remain supported for existing clients. Project and risk are accepted but return no matches until this version persists those attributes, rather than fabricating filter results.
      parameters:
        - name: status
          in: query
          schema: { type: string }
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
        - name: page
          in: query
          schema: { type: integer, minimum: 1, maximum: 10000, default: 1 }
        - name: pageSize
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 50 }
        - name: projectId
          in: query
          schema: { type: string, format: uuid }
        - name: submitterId
          in: query
          schema: { type: string, format: uuid }
        - name: minAgeDays
          in: query
          description: Minimum proposal age, calculated from the first immutable proposal revision.
          schema: { type: integer, minimum: 0, maximum: 3650 }
        - name: risk
          in: query
          schema: { type: string, enum: [low, medium, high] }
        - name: documentType
          in: query
          schema: { type: string, maxLength: 64 }
      responses:
        "200": { description: Review queue, content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalListResponse" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
    post:
      tags: [Ingestion proposals]
      operationId: createIngestionProposal
      description: >-
        Requires an Idempotency-Key and an editor cookie or an ingestion:write service
        token. Repeating the same request with the same caller and key replays the
        original 201 response. Reusing that key with a different request body returns
        a 409 problem with type https://itworx.dev/problems/idempotency-key-conflict.
      parameters:
        - $ref: "#/components/parameters/RequiredIdempotencyKey"
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/CreateIngestionProposalRequest" } } }
      responses:
        "201": { description: Proposal created, headers: { ETag: { $ref: "#/components/headers/ETag" } }, content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalDetail" } } } }
        "400": { description: Idempotency-Key is missing or invalid, content: { application/problem+json: { schema: { $ref: "#/components/schemas/ProblemDetails" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "409":
          description: Idempotency-Key was already used with a different request body.
          content:
            application/problem+json:
              schema: { $ref: "#/components/schemas/ProblemDetails" }
              examples:
                idempotencyKeyConflict:
                  value:
                    type: https://itworx.dev/problems/idempotency-key-conflict
                    title: Idempotency-Key hergebruikt met een andere aanvraag.
                    status: 409
                    correlationId: pilot-contract
                    detail: Deze Idempotency-Key is eerder gebruikt voor een andere aanvraag-inhoud.
        "422": { $ref: "#/components/responses/BadRequest" }
  /ingestion-proposals/{proposalId}:
    parameters:
      - name: proposalId
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      tags: [Ingestion proposals]
      operationId: getIngestionProposal
      description: A human reviewer may read any workspace proposal. An ingestion:write token may read only the proposal it submitted.
      responses:
        "200": { description: Complete metadata-only review/status dossier, headers: { ETag: { $ref: "#/components/headers/ETag" } }, content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalDetail" } } } }
        "404": { $ref: "#/components/responses/NotFound" }
    patch:
      tags: [Ingestion proposals]
      operationId: patchIngestionProposal
      description: >-
        Requires If-Match. Human editors may change manifest/rationale; an edit to an
        Approved proposal clears its approval and returns it to ReadyForReview. Only
        the submitting ingestion:write account may submit analysis, which advances the
        proposal to ReadyForReview. A stale proposal ETag returns 412 with type
        https://itworx.local/problems/ingestion-concurrency-conflict.
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/PatchIngestionProposalRequest" } } }
      responses:
        "200": { description: Updated proposal, headers: { ETag: { $ref: "#/components/headers/ETag" } }, content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalDetail" } } } }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "412":
          description: Proposal ETag does not match the current version.
          content:
            application/problem+json:
              schema: { $ref: "#/components/schemas/ProblemDetails" }
              examples:
                ingestionConcurrencyConflict:
                  value:
                    type: https://itworx.local/problems/ingestion-concurrency-conflict
                    title: Versieconflict.
                    status: 412
                    correlationId: pilot-contract
  /ingestion-proposals/{proposalId}/sources:
    post:
      tags: [Ingestion proposals]
      operationId: stageIngestionProposalSource
      description: Requires If-Match and Idempotency-Key. Upload is quarantined, signature-validated and stored only as immutable metadata plus a content-addressed attachment reference; neither bytes nor storage paths are returned.
      parameters:
        - name: proposalId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: "#/components/parameters/IfMatch"
        - $ref: "#/components/parameters/RequiredIdempotencyKey"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties: { file: { type: string, format: binary } }
      responses:
        "200": { description: Source staged, headers: { ETag: { $ref: "#/components/headers/ETag" } }, content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalDetail" } } } }
        "413": { description: Source exceeds the configured size limit }
        "422": { $ref: "#/components/responses/BadRequest" }
  /ingestion-proposals/{proposalId}/submit:
    post:
      tags: [Ingestion proposals]
      operationId: submitManualIngestionProposal
      description: >-
        Human submitter only. Moves a proposal with publication details and at least
        one staged source into ReadyForReview without claiming automated analysis.
        Requires If-Match. A separate human review and approval remain mandatory.
      parameters:
        - name: proposalId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: "#/components/parameters/IfMatch"
      responses:
        "200": { description: Submitted for review, headers: { ETag: { $ref: "#/components/headers/ETag" } }, content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalDetail" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "412": { $ref: "#/components/responses/PreconditionFailed" }
        "428": { $ref: "#/components/responses/PreconditionRequired" }
  /ingestion-proposals/{proposalId}/request-changes:
    post:
      tags: [Ingestion proposals]
      operationId: requestIngestionProposalChanges
      description: >-
        Human reviewer only. Requires If-Match and returns the updated metadata-only
        dossier. Stale ETags return 412 with type
        https://itworx.local/problems/ingestion-concurrency-conflict.
      parameters:
        - name: proposalId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalDecisionRequest" } } }
      responses:
        "200": { description: Change request recorded, headers: { ETag: { $ref: "#/components/headers/ETag" } }, content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalDetail" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "412": { $ref: "#/components/responses/PreconditionFailed" }
        "428": { $ref: "#/components/responses/PreconditionRequired" }
  /ingestion-proposals/{proposalId}/approve:
    post:
      tags: [Ingestion proposals]
      operationId: approveIngestionProposal
      description: >-
        Human reviewer only. Service accounts cannot approve. Requires If-Match and
        approves a ReadyForReview proposal without publishing it. Stale ETags return
        412 with type https://itworx.local/problems/ingestion-concurrency-conflict.
      parameters:
        - name: proposalId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalDecisionRequest" } } }
      responses:
        "200": { description: Proposal approved for later publication, headers: { ETag: { $ref: "#/components/headers/ETag" } }, content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalDetail" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "412": { $ref: "#/components/responses/PreconditionFailed" }
        "428": { $ref: "#/components/responses/PreconditionRequired" }
  /ingestion-proposals/{proposalId}/reject:
    post:
      tags: [Ingestion proposals]
      operationId: rejectIngestionProposal
      description: >-
        Human reviewer only. Service accounts cannot reject. Requires If-Match and
        records the rejection comment on the metadata-only proposal dossier. Stale
        ETags return 412 with type
        https://itworx.local/problems/ingestion-concurrency-conflict.
      parameters:
        - name: proposalId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalDecisionRequest" } } }
      responses:
        "200": { description: Proposal rejected, headers: { ETag: { $ref: "#/components/headers/ETag" } }, content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalDetail" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "412": { $ref: "#/components/responses/PreconditionFailed" }
        "428": { $ref: "#/components/responses/PreconditionRequired" }
  /ingestion-proposals/{proposalId}/retry:
    post:
      tags: [Ingestion proposals]
      operationId: retryIngestionProposal
      description: Requires If-Match. An ingestion:write caller can retry only its own eligible failed proposal; a human editor may retry an eligible proposal. An optional Idempotency-Key safely replays a successful retry response.
      parameters:
        - name: proposalId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: "#/components/parameters/IfMatch"
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200": { description: Eligible proposal reset for re-analysis, headers: { ETag: { $ref: "#/components/headers/ETag" } }, content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalDetail" } } } }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
        "412": { $ref: "#/components/responses/PreconditionFailed" }
        "428": { $ref: "#/components/responses/PreconditionRequired" }
  /ingestion-proposals/{proposalId}/publish:
    post:
      tags: [Ingestion proposals]
      operationId: publishIngestionProposal
      description: >-
        Human review only. Requires a human editor cookie session, If-Match and
        Idempotency-Key; service accounts are forbidden from publishing. A replay with
        the same key and request body returns the original success response even when
        it carries the original now-stale If-Match value, and does not create a second
        page revision. Reusing the key with a different body returns a typed
        idempotency conflict. A stale target page ETag returns 409 with type
        https://itworx.local/problems/ingestion-target-stale and moves the proposal
        back to ReadyForReview.
      parameters:
        - name: proposalId
          in: path
          required: true
          schema: { type: string, format: uuid }
        - $ref: "#/components/parameters/IfMatch"
        - $ref: "#/components/parameters/RequiredIdempotencyKey"
      responses:
        "200": { description: Approved proposal published, headers: { ETag: { $ref: "#/components/headers/ETag" } }, content: { application/json: { schema: { $ref: "#/components/schemas/IngestionProposalDetail" } } } }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "403": { $ref: "#/components/responses/Forbidden" }
        "404": { $ref: "#/components/responses/NotFound" }
        "409":
          description: >-
            Invalid state transition, stale target, or idempotency-key conflict. Typed
            problem types are https://itworx.local/problems/ingestion-invalid-transition,
            https://itworx.local/problems/ingestion-target-stale, and
            https://itworx.dev/problems/idempotency-key-conflict.
          content:
            application/problem+json:
              schema: { $ref: "#/components/schemas/ProblemDetails" }
              examples:
                staleTarget:
                  value:
                    type: https://itworx.local/problems/ingestion-target-stale
                    title: Publicatiedoel is gewijzigd.
                    status: 409
                    correlationId: pilot-contract
                    detail: Het voorstel is teruggezet naar de reviewwachtrij.
                invalidTransition:
                  value:
                    type: https://itworx.local/problems/ingestion-invalid-transition
                    title: Conflict.
                    status: 409
                    correlationId: pilot-contract
                idempotencyKeyConflict:
                  value:
                    type: https://itworx.dev/problems/idempotency-key-conflict
                    title: Idempotency-Key hergebruikt met een andere aanvraag.
                    status: 409
                    correlationId: pilot-contract
                    detail: Deze Idempotency-Key is eerder gebruikt voor een andere aanvraag-inhoud.
        "412":
          description: Proposal ETag is stale.
          content:
            application/problem+json:
              schema: { $ref: "#/components/schemas/ProblemDetails" }
              examples:
                ingestionConcurrencyConflict:
                  value:
                    type: https://itworx.local/problems/ingestion-concurrency-conflict
                    title: Versieconflict.
                    status: 412
                    correlationId: pilot-contract
        "428": { $ref: "#/components/responses/PreconditionRequired" }
  /system/info:
    get:
      tags: [System]
      operationId: getSystemInfo
      responses:
        "200":
          description: Permission-filtered system information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemInfo"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /setup/status:
    get:
      tags: [Setup]
      operationId: getSetupStatus
      security: []
      description: >-
        Reveals only whether first-run setup is still required. Never reveals any other
        installation detail to an unauthenticated caller.
      responses:
        "200":
          description: Setup status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SetupStatus"
  /setup/complete:
    post:
      tags: [Setup]
      operationId: completeSetup
      security: []
      description: >-
        Single-use first-run owner setup. Requires CSRF protection and is rate limited.
        Permanently fails once setup has completed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CompleteSetupRequest"
      responses:
        "200":
          description: Installation completed; caller is signed in
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CompleteSetupResponse"

        "409":
          description: Setup already completed
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "422":
          description: Validation failed (email/password/workspace name)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "429":
          $ref: "#/components/responses/RateLimited"
  /auth/csrf:
    get:
      tags: [Auth]
      operationId: getCsrfToken
      security: []
      description: Issues the double-submit anti-forgery token required on cookie-authenticated mutations.
      responses:
        "200":
          description: Anti-forgery token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CsrfToken"
  /auth/session:
    get:
      tags: [Auth]
      operationId: getSession
      security: []
      description: >-
        Always returns 200. An unauthenticated caller only ever sees
        `authenticated: false` plus whether setup is required — never whether a
        specific account exists.
      responses:
        "200":
          description: Current session state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionResponse"
  /auth/login:
    post:
      tags: [Auth]
      operationId: login
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
      responses:
        "200":
          description: Signed in
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionResponse"
        "401":
          description: Invalid credentials (also returned for an unknown account and a disabled account)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "429":
          $ref: "#/components/responses/RateLimited"
  /auth/logout:
    post:
      tags: [Auth]
      operationId: logout
      responses:
        "200":
          description: Signed out
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /auth/recovery/redeem:
    post:
      tags: [Auth]
      operationId: redeemRecoveryToken
      security: []
      description: Consumes a single-use operator-issued recovery token and sets a new password.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RecoveryRedeemRequest"
      responses:
        "200":
          description: Password reset; all prior sessions for this account are invalidated
        "400":
          description: Invalid or expired token
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "422":
          description: New password rejected
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "429":
          $ref: "#/components/responses/RateLimited"
  /admin/users:
    get:
      tags: [Admin]
      operationId: listUsers
      description: Administrator only.
      responses:
        "200":
          description: Workspace members
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/UserSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      tags: [Admin]
      operationId: createUser
      description: >-
        Administrator only. There is no invite email; the administrator sets an initial
        password and communicates it out of band.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "200":
          description: User created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/BadRequest"
  /admin/users/{userId}:
    patch:
      tags: [Admin]
      operationId: updateUser
      description: >-
        Administrator only. Changes role and/or enabled state. Refuses a change that
        would leave zero enabled administrators.
      parameters:
        - $ref: "#/components/parameters/UserId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserRequest"
      responses:
        "200":
          description: Updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Would remove the last enabled administrator
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /admin/users/{userId}/recovery-tokens:
    post:
      tags: [Admin]
      operationId: issueRecoveryToken
      description: >-
        Administrator only. Issues a single-use, one-hour password-recovery token for
        another account. The raw token is returned exactly once, in this response.
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "200":
          description: Token issued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IssueRecoveryTokenResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /admin/trash/purge:
    post:
      tags: [Admin]
      operationId: purgeTrash
      description: >-
        Administrator only. The explicit administrative purge
        (docs/09-data-safety: never a permanent delete through a normal UI flow).
        Permanently removes every trashed page in the workspace whose retention
        window has already elapsed; never a page still within retention, never a
        page that was never trashed.
      responses:
        "200":
          description: Purge completed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TrashPurgeResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /admin/staging-cleanup/status:
    get:
      tags: [Admin]
      operationId: getStagingCleanupStatus
      description: >-
        Administrator only (docs/adr/ADR-029-v2-r5-final-hardening.md). Live counts of
        currently-open and expired-pending-cleanup page-creation staging sessions, plus
        the most recent cleanup run (scheduled or manual) and its result. The "last run"
        fields are in-memory only and reset on application restart — an accepted,
        documented limitation; the cleanup guarantee itself does not depend on this
        history.
      responses:
        "200":
          description: Current staging-cleanup status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StagingCleanupStatusResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /admin/staging-cleanup/run:
    post:
      tags: [Admin]
      operationId: runStagingCleanup
      description: >-
        Administrator only, CSRF-protected (docs/adr/ADR-029-v2-r5-final-hardening.md).
        Runs the exact same reclamation logic as the periodic background worker, once,
        synchronously. `dryRun: true` only counts currently-expired, claimable sessions
        — it claims nothing, deletes nothing and is safe to call as often as wanted;
        never expose a destructive "run now" action without this dry-run mode.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RunStagingCleanupRequest"
      responses:
        "200":
          description: Cleanup run (or dry-run preview) result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunStagingCleanupResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /activity:
    get:
      tags: [Activity]
      operationId: listActivity
      description: >-
        Requires a reader cookie session or an `audit:read` service-token scope. The
        most recent audit/activity events across the workspace (page/project/decision
        mutations, imports, backups, staging-session cleanup, etc.), newest first —
        the same durable `audit_events` trail every mutation writes to
        (docs/12-auth-security.md "Logging and privacy": never a password, raw token or
        session identifier).
      parameters:
        - name: limit
          in: query
          required: false
          description: Defaults to 100.
          schema:
            type: integer
            minimum: 1
            maximum: 500
      responses:
        "200":
          description: Recent activity, newest first
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActivityListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /workspace/members:
    get:
      tags: [Workspace]
      operationId: searchWorkspaceMembers
      description: >-
        Requires a reader cookie session — deliberately not reachable by a
        service-account bearer token (no automation use case has been named for this
        yet). Backs the accessible owner picker (docs/adr/ADR-029-v2-r5-final-hardening.md,
        replacing manual `OwnerId`/GUID entry): only enabled members of the current
        workspace, matched case-insensitively against display name or email, capped at
        25 results. Never discloses accounts outside the workspace or disabled
        accounts. An empty/omitted `q` returns the first 25 members alphabetically (the
        picker's initial open state, before typing).
      parameters:
        - name: q
          in: query
          required: false
          schema:
            type: string
      responses:
        "200":
          description: Matching workspace members
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceMemberListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /search:
    get:
      tags: [Search]
      operationId: searchKnowledge
      description: >-
        PostgreSQL full-text (weighted title/tags/body) plus trigram typo-tolerant
        title matching. Authorization is entirely SQL-level: always scoped to the
        caller's workspace, always excludes trashed pages
        (docs/10-search-and-indexing.md). An empty or absent `q` returns all
        permitted, non-trashed pages (browsing by tag/type filter alone).
      parameters:
        - $ref: "#/components/parameters/CorrelationId"
        - name: q
          in: query
          schema:
            type: string
            maxLength: 500
        - name: type
          in: query
          description: A single DocumentType value.
          schema:
            $ref: "#/components/schemas/DocumentType"
        - name: tag
          in: query
          description: A single exact tag match.
          schema:
            type: string
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Permission-filtered search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /rag/publication-manifest:
    get:
      tags: [Rag]
      operationId: getRagPublicationManifest
      description: >-
        A narrow, read-only view of every page tagged `rag:publish`
        (docs/32-rag-publication-convention.md), built for RAGcore's n8n sync — the
        one reliable way to discover the full curated publication set, since this API
        has no `GET /pages` enumeration (only `/pages/roots` plus a tree walk). Reuses
        the existing `pages:read` scope; no new scope was added. A page that still
        carries `rag:publish` but is trashed, still a draft, awaiting review, archived,
        or deprecated without the `rag:allow-deprecated` tag comes back with
        `retired: true` and a `retiredReason`, and its `markdown`/`checksum` are
        `null` — so a sync consumer can safely withdraw previously ingested content
        instead of only ever learning about new content.
      parameters:
        - $ref: "#/components/parameters/CorrelationId"
        - name: space
          in: query
          description: >-
            A single `rag:space:` tag suffix. Case-sensitive lowercase slug; an
            invalid shape is rejected with 422 rather than passed into the array-
            containment filter.
          schema:
            type: string
            maxLength: 64
        - $ref: "#/components/parameters/Cursor"
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 100
      responses:
        "200":
          description: Publication manifest page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RagPublicationManifestResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          description: Invalid `space` parameter
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /pages/roots:
    get:
      tags: [Pages]
      operationId: listRootPages
      description: Top-level pages (no parent), cursor-paginated.
      parameters:
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Root pages
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageChildrenResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /pages/preview:
    post:
      tags: [Pages]
      operationId: previewMarkdown
      description: >-
        Requires a reader cookie session or a `pages:read` service-token scope. Renders
        arbitrary Markdown through the exact same server-side pipeline (Markdig with
        `.DisableHtml()` plus the allowlist `HtmlSanitizer` pass) used for a published
        page revision — safe to call with unsaved editor content, never persists
        anything. The same safe pipeline is reused for project free-text Markdown
        fields (`currentStateMarkdown`, `summaryMarkdown`, etc. —
        docs/adr/ADR-029-v2-r5-final-hardening.md).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PreviewMarkdownRequest"
      responses:
        "200":
          description: Rendered, sanitized HTML
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PreviewMarkdownResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /pages:
    post:
      tags: [Pages]
      operationId: createPage
      parameters:
        - $ref: "#/components/parameters/CorrelationId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePageRequest"
      responses:
        "200":
          description: Page created and published as revision 1
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          description: Validation failed, or an unknown templateKey was supplied
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /pages/{pageId}:
    parameters:
      - $ref: "#/components/parameters/PageId"
      - $ref: "#/components/parameters/CorrelationId"
    get:
      tags: [Pages]
      operationId: getPage
      responses:
        "200":
          description: Current page, with server-sanitized rendered HTML
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      tags: [Pages]
      operationId: updatePage
      description: Publishes a new revision. Requires If-Match with the page's current ETag.
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdatePageRequest"
      responses:
        "200":
          description: Updated page
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Page is trashed and must be restored before it can be edited
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "422":
          $ref: "#/components/responses/BadRequest"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /pages/{pageId}/children:
    get:
      tags: [Pages]
      operationId: listPageChildren
      parameters:
        - $ref: "#/components/parameters/PageId"
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Direct children, cursor-paginated (proven at 10,000-child scale, docs/27-acceptance-matrix.md M2-A07)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageChildrenResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /pages/{pageId}/move:
    post:
      tags: [Pages]
      operationId: movePage
      description: >-
        Reparents and/or reorders a page among its siblings. Rejects a move that would
        make a page its own descendant. Requires If-Match with the page's current ETag.
      parameters:
        - $ref: "#/components/parameters/PageId"
        - $ref: "#/components/parameters/CorrelationId"
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MovePageRequest"
      responses:
        "200":
          description: Moved page
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: The requested move would make the page its own descendant (a cycle)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /pages/{pageId}/trash:
    post:
      tags: [Pages]
      operationId: trashPage
      description: >-
        Moves a page to the trash/retention model. Never a permanent delete
        (docs/09-data-safety). Requires If-Match with the page's current ETag and
        accepts either an editor cookie session or a `pages:write` service token,
        enabling bounded import rollback without permanent deletion.
      parameters:
        - $ref: "#/components/parameters/PageId"
        - $ref: "#/components/parameters/CorrelationId"
        - $ref: "#/components/parameters/IfMatch"
      responses:
        "200":
          description: Page trashed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /pages/{pageId}/restore:
    post:
      tags: [Pages]
      operationId: restorePage
      description: Restores a trashed page. Requires If-Match with the page's current ETag.
      parameters:
        - $ref: "#/components/parameters/PageId"
        - $ref: "#/components/parameters/CorrelationId"
        - $ref: "#/components/parameters/IfMatch"
      responses:
        "200":
          description: Page restored
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /pages/{pageId}/revisions:
    get:
      tags: [Pages]
      operationId: listPageRevisions
      description: Immutable revision history, most recent first (M3-A01/M3-A02).
      parameters:
        - $ref: "#/components/parameters/PageId"
        - $ref: "#/components/parameters/CorrelationId"
      responses:
        "200":
          description: Revisions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/PageRevisionSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /pages/{pageId}/revisions/{revisionNumber}:
    get:
      tags: [Pages]
      operationId: getPageRevision
      parameters:
        - $ref: "#/components/parameters/PageId"
        - $ref: "#/components/parameters/RevisionNumber"
        - $ref: "#/components/parameters/CorrelationId"
      responses:
        "200":
          description: One revision's full content, server-rendered
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageRevisionDetailResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /pages/{pageId}/revisions/{revisionNumber}/restore:
    post:
      tags: [Pages]
      operationId: restorePageRevision
      description: >-
        Publishes a new current revision whose content matches the chosen past
        snapshot. Never rewrites history: the state right before this call is itself
        preserved as its own revision. Requires If-Match with the page's current ETag.
      parameters:
        - $ref: "#/components/parameters/PageId"
        - $ref: "#/components/parameters/RevisionNumber"
        - $ref: "#/components/parameters/CorrelationId"
        - $ref: "#/components/parameters/IfMatch"
      responses:
        "200":
          description: Restored page
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Page is trashed and must be restored before it can be edited
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /pages/{pageId}/backlinks:
    get:
      tags: [Pages]
      operationId: getPageBacklinks
      description: >-
        "What links here": pages whose most recently published content contains a
        resolved internal link to this page (M3-A03).
      parameters:
        - $ref: "#/components/parameters/PageId"
        - $ref: "#/components/parameters/CorrelationId"
      responses:
        "200":
          description: Backlinks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BacklinksResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /drafts/{draftKey}:
    parameters:
      - $ref: "#/components/parameters/DraftKey"
      - $ref: "#/components/parameters/CorrelationId"
    get:
      tags: [Drafts]
      operationId: getDraft
      description: >-
        Private per-user autosaved draft. A draft never overwrites the published
        revision (docs/27-acceptance-matrix.md, M2-A04).
      responses:
        "200":
          description: Draft
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DraftResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      tags: [Drafts]
      operationId: saveDraft
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SaveDraftRequest"
      responses:
        "200":
          description: >-
            Draft saved. `baseRevisionIsStale` is true when the page has been published
            again since this draft's base revision, without blocking the save.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DraftResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    delete:
      tags: [Drafts]
      operationId: discardDraft
      responses:
        "200":
          description: Draft discarded
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /templates:
    get:
      tags: [Templates]
      operationId: listTemplates
      description: Starter document templates available when creating a new page.
      responses:
        "200":
          description: Available templates
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/TemplateSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /pages/{pageId}/attachments:
    parameters:
      - $ref: "#/components/parameters/PageId"
      - $ref: "#/components/parameters/CorrelationId"
    get:
      tags: [Attachments]
      operationId: listPageAttachments
      description: Requires a reader cookie session or an `attachments:read` service-token scope.
      responses:
        "200":
          description: Attachments referenced by this page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttachmentListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Attachments]
      operationId: uploadAttachment
      description: >-
        Requires an editor cookie session or an `attachments:write` service-token
        scope.
        The upload pipeline from docs/13-attachments.md: streams once to quarantine
        while hashing, verifies size, detects the real signature (never trusting the
        declared type/extension alone), applies delivery policy, then commits.
        Identical content deduplicates to one physical blob while still creating an
        independent logical reference.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Uploaded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttachmentSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "413":
          description: File exceeds the configured maximum upload size
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "422":
          description: Rejected content (unsafe signature) or an invalid filename
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /pages/staged:
    post:
      tags: [Pages]
      operationId: beginPageCreationSession
      description: >-
        Opens a staging session for creating a new page that may need attachments
        inserted before the page is ever visible to a reader
        (docs/adr/ADR-025-v2-r1-data-integrity-remediation.md). Requires an editor
        cookie session or a `pages:write` service-token scope.
      parameters:
        - $ref: "#/components/parameters/CorrelationId"
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BeginPageCreationSessionRequest"
      responses:
        "200":
          description: Session opened
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageCreationSessionResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          description: The supplied parentPageId does not exist
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /pages/staged/{sessionId}/attachments:
    parameters:
      - $ref: "#/components/parameters/SessionId"
      - $ref: "#/components/parameters/CorrelationId"
    post:
      tags: [Attachments]
      operationId: uploadStagedAttachment
      description: >-
        The same real, immediately-addressable attachment as
        `POST /pages/{pageId}/attachments` — owned by an open page-creation session
        instead of an existing page until that session's commit re-points ownership
        atomically. Requires an editor cookie session or an `attachments:write`
        service-token scope.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Uploaded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AttachmentSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The session does not exist, is no longer open, or has expired
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "413":
          description: File exceeds the configured maximum upload size
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "422":
          description: Rejected content (unsafe signature) or an invalid filename
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /pages/staged/{sessionId}/commit:
    parameters:
      - $ref: "#/components/parameters/SessionId"
      - $ref: "#/components/parameters/CorrelationId"
    post:
      tags: [Pages]
      operationId: commitPageCreationSession
      description: >-
        The single explicit publication action: atomically creates the page and
        re-points every attachment already uploaded into this session to it, in one
        transaction — no half-published page with broken attachment links can ever
        become visible (docs/adr/ADR-025-v2-r1-data-integrity-remediation.md).
        Requires an editor cookie session or a `pages:write` service-token scope.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommitPageCreationSessionRequest"
      responses:
        "200":
          description: Page created and published, with every staged attachment now owned by it
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PageDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The session does not exist
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "409":
          description: The session is no longer open (already committed, discarded, or expired)
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "422":
          $ref: "#/components/responses/BadRequest"
  /pages/staged/{sessionId}/discard:
    parameters:
      - $ref: "#/components/parameters/SessionId"
      - $ref: "#/components/parameters/CorrelationId"
    post:
      tags: [Pages]
      operationId: discardPageCreationSession
      description: >-
        Explicit compensation for an abandoned session: removes every attachment
        uploaded into it that is not used elsewhere, then marks the session
        discarded. Idempotent — discarding an already-discarded session is a safe
        no-op. Requires an editor cookie session or a `pages:write` service-token
        scope.
      parameters:
        - $ref: "#/components/parameters/IdempotencyKey"
      responses:
        "200":
          description: Session discarded (or already was)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DiscardPageCreationSessionResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: The session does not exist
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "409":
          description: The session was already committed and can no longer be discarded
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /infrastructure/overview:
    get:
      tags: [Infrastructure]
      operationId: getInfrastructureOverview
      description: >-
        Requires a reader cookie session or an `infrastructure:read` service-token
        scope. The dashboard summary: the most recent inventory snapshot (if any),
        every known host, and aggregate service counts (total, proposed/unreviewed,
        missing, unhealthy, unprotected-by-backup). Returns an all-zero/empty response
        rather than an error when no workspace exists yet.
      responses:
        "200":
          description: Infrastructure overview
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfrastructureOverviewResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /infrastructure/services:
    get:
      tags: [Infrastructure]
      operationId: listInfrastructureServices
      description: >-
        Requires a reader cookie session or an `infrastructure:read` service-token
        scope. Cursor-paginated services catalog
        (docs/adr/ADR-026-v2-r2-infrastructure-scale-and-sync-durability.md) — proven
        at real production scale (InfrastructureCatalogReleaseScaleTests.cs, 50,000
        services) with an index-order scan, never a full in-memory load. `projectId`,
        `search` and `status` are applied server-side on the same paginated query;
        filter results never depend on pages already loaded by the client.
      parameters:
        - name: includeHidden
          in: query
          required: false
          description: Defaults to false — hidden/archived services are excluded from the default catalog view.
          schema:
            type: boolean
        - name: projectId
          in: query
          required: false
          description: Only services whose editorial profile links this project.
          schema:
            type: string
            format: uuid
        - name: search
          in: query
          required: false
          description: Case-insensitive match against detected name, image reference, and editorial display name/category.
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Server-side operational status filter.
          schema:
            type: string
            enum: [attention, healthy, missing]
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: A page of services, newest-`(DetectedName, Id)`-ordered
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfrastructureServiceListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /infrastructure/storage:
    get:
      tags: [Infrastructure]
      operationId: listInfrastructureStorage
      description: >-
        Requires a reader cookie session or an `infrastructure:read` service-token
        scope. Cursor-paginated storage listing (V2-R5,
        docs/adr/ADR-029-v2-r5-final-hardening.md) — every known volume across every
        service, each row carrying its owning service's ID/name for display.
      parameters:
        - name: search
          in: query
          required: false
          description: Case-insensitive match against the owning service's detected name and the volume's own name/mount path, applied server-side.
          schema:
            type: string
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: A page of storage volumes
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfrastructureStorageListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /infrastructure/services/{serviceId}:
    get:
      tags: [Infrastructure]
      operationId: getInfrastructureService
      description: >-
        Requires a reader cookie session or an `infrastructure:read` service-token
        scope. The full fact graph for one service: editorial profile, manual
        overrides, components, endpoints, networks, volumes, databases, dependencies,
        health observations, deployment references and backup coverage, each fact
        carrying its own provenance (source key, confidence, last-seen snapshot,
        observed-at). The `ETag` response header is the editorial profile's
        optimistic-concurrency token, required as `If-Match` on
        `PUT .../editorial-profile`.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Full service detail
          headers:
            ETag:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfrastructureServiceDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /infrastructure/services/{serviceId}/editorial-profile:
    put:
      tags: [Infrastructure]
      operationId: updateInfrastructureEditorialProfile
      description: >-
        Editor role or `infrastructure:write` service-token scope required, CSRF- and
        `If-Match`-protected. Updates the human-authored editorial layer for a service
        (display name, summary, category, purpose, owning project, procedures, tags,
        favorite/hidden/archived flags) — automatically-detected facts are never
        touched by this endpoint. A stale `If-Match` is a 412, never a silent overwrite.
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateEditorialProfileRequest"
      responses:
        "200":
          description: Updated service detail
          headers:
            ETag:
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InfrastructureServiceDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          description: If-Match did not match the current editorial profile ETag
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "422":
          $ref: "#/components/responses/ValidationFailed"
        "428":
          description: If-Match header is required and was missing
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /infrastructure/services/{serviceId}/overrides:
    post:
      tags: [Infrastructure]
      operationId: setManualOverride
      description: >-
        Editor role or `infrastructure:write` service-token scope required,
        CSRF-protected. Sets (creates or replaces) one field-level manual correction
        over an automatically-detected fact, validated against the exact allowlist
        `GET /infrastructure/overrides/catalog` returns for this object kind — an
        inventory sync never overwrites or removes an existing override
        (docs/adr/ADR-025-v2-r1-data-integrity-remediation.md, audit finding H2).
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetManualOverrideRequest"
      responses:
        "200":
          description: The created/updated override's ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                required: [id]
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationFailed"
  /infrastructure/overrides:
    post:
      tags: [Infrastructure]
      operationId: setInfrastructureOverride
      description: >-
        Editor role or `infrastructure:write` service-token scope required,
        CSRF-protected. The generic sibling of
        `POST /infrastructure/services/{serviceId}/overrides` (V2-R5,
        docs/adr/ADR-029-v2-r5-final-hardening.md): sets a field-level manual
        correction for any `InfrastructureObjectKind` (Host, Network, Volume, Database,
        Endpoint, Component, Deployment, Backup), not only a Service reached through
        its own nested route — validated against the exact allowlist
        `GET /infrastructure/overrides/catalog?targetKind=...` returns for that kind.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetInfrastructureOverrideRequest"
      responses:
        "200":
          description: The created/updated override's ID
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                required: [id]
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationFailed"
  /infrastructure/overrides/{overrideId}:
    delete:
      tags: [Infrastructure]
      operationId: removeManualOverride
      description: >-
        Editor role or `infrastructure:write` service-token scope required,
        CSRF-protected. Removes one manual override, reverting that field to its
        automatically-detected value (if any).
      parameters:
        - name: overrideId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "204":
          description: Override removed
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /infrastructure/services/{serviceId}/review:
    post:
      tags: [Infrastructure]
      operationId: reviewInfrastructureService
      description: >-
        Administrator only, CSRF-protected. Accepts or rejects a `Proposed` (newly
        detected, unreviewed) service — the deliberate human-in-the-loop gate before an
        automatically-detected container becomes part of the confirmed catalog. A
        name match alone is never treated as a high-confidence relationship
        (docs/adr/ADR-029-v2-r5-final-hardening.md).
      parameters:
        - name: serviceId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReviewInfrastructureServiceRequest"
      responses:
        "200":
          description: The service's resulting presence state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReviewInfrastructureServiceResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationFailed"
  /infrastructure/inventory/snapshots:
    post:
      tags: [Infrastructure]
      operationId: synchronizeInfrastructureInventory
      description: >-
        Administrator only, CSRF- and `Idempotency-Key`-protected. Imports one
        inventory snapshot (hosts + services + every nested fact) captured by the
        external, read-only inventory tooling — never destructive: existing editorial
        profiles and manual overrides are always preserved, a previously-seen service
        that is missing from this snapshot is marked missing (not deleted), and
        replaying the same `sourceKey`/`sourceHash` is a safe no-op
        (`alreadyImported: true`), not a duplicate import.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SynchronizeInventoryRequest"
      responses:
        "200":
          description: Synchronization result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InventorySyncResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: Idempotency-Key reused with a different request body
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "422":
          $ref: "#/components/responses/ValidationFailed"
  /infrastructure/inventory/curated-package:
    post:
      tags: [Infrastructure]
      operationId: importCuratedInventoryPackage
      description: >-
        Administrator only, CSRF- and `Idempotency-Key`-protected. A single bounded
        call that both synchronizes a raw inventory snapshot and applies a curated set
        of editorial profiles/review decisions on top of it in one step — the
        mechanism the curated-infrastructure-wiki publication used
        (docs/deployments/2026-08-02-curated-infrastructure-wiki.md). Never overwrites
        an editorial profile a human has since hand-edited.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ImportCuratedInventoryRequest"
      responses:
        "200":
          description: Combined synchronization + curation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImportCuratedInventoryResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: Idempotency-Key reused with a different request body
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "422":
          $ref: "#/components/responses/ValidationFailed"
  /infrastructure/changes:
    get:
      tags: [Infrastructure]
      operationId: listInfrastructureChanges
      description: >-
        Requires a reader cookie session or an `infrastructure:read` service-token
        scope. The most recent inventory-sync change log entries (new/changed/missing
        objects), newest first, each naming its target kind/ID, source key, change
        kind and the specific fields that changed.
      parameters:
        - name: limit
          in: query
          required: false
          description: Defaults to 100.
          schema:
            type: integer
            minimum: 1
            maximum: 500
      responses:
        "200":
          description: Recent inventory changes, newest first
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/InventoryChangeResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /infrastructure/overrides/catalog:
    get:
      tags: [Infrastructure]
      operationId: getManualOverrideFieldCatalog
      description: >-
        The exact, server-authoritative set of fields a ManualOverride may target for
        the given InfrastructureObjectKind, with each field's JSON value kind, max
        length and (for enum fields) allowed values
        (docs/adr/ADR-025-v2-r1-data-integrity-remediation.md, audit finding H3). The
        frontend fetches this instead of keeping its own list, so the two can never
        independently drift. Requires a reader cookie session or an
        `infrastructure:read` service-token scope.
      parameters:
        - name: targetKind
          in: query
          required: false
          description: Defaults to Service, the only kind reachable through the current UI/API.
          schema:
            type: string
            enum: [Host, Service, Component, Endpoint, Network, Volume, Database, Deployment, Backup]
      responses:
        "200":
          description: Field catalog for the requested target kind
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ManualOverrideFieldCatalogResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          description: Unknown targetKind
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /attachments/{attachmentId}/content:
    get:
      tags: [Attachments]
      operationId: getAttachmentContent
      description: >-
        Requires a reader cookie session or an `attachments:read` service-token scope.
        Every request re-authorizes the logical reference (docs/13-attachments.md) —
        a content hash alone is never sufficient permission to retrieve a blob. Served
        with a safe Content-Disposition (inline only for a known-safe raster image,
        attachment otherwise) and X-Content-Type-Options: nosniff.
      parameters:
        - name: attachmentId
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: The raw file content
          content:
            application/octet-stream: {}
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /admin/imports/preflight:
    post:
      tags: [Imports]
      operationId: preflightImport
      description: >-
        Administrator only. Discovers and fingerprints a read-only source beneath the
        operator-mounted imports directory, selects an adapter, and builds a plan —
        no target mutation occurs (docs/17-leafwiki-migration.md).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PreflightImportRequest"
      responses:
        "200":
          description: Plan ready (or an idempotent repeat of an already-preflighted request)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImportPreflightResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          description: Invalid source path, or no adapter can interpret this source
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /admin/imports/{jobId}:
    get:
      tags: [Imports]
      operationId: getImportJob
      parameters:
        - $ref: "#/components/parameters/ImportJobId"
      responses:
        "200":
          description: Import job status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ImportJobSummaryResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /admin/imports/{jobId}/execute:
    post:
      tags: [Imports]
      operationId: executeImport
      description: >-
        Administrator only. Re-verifies the source fingerprint and plan hash have not
        changed since preflight, then creates each planned page — parents before
        children — with full provenance for rollback. Never overwrites an existing
        page; an item already imported with unchanged content is skipped idempotently.
      parameters:
        - $ref: "#/components/parameters/ImportJobId"
        - name: sourceRelativePath
          in: query
          required: true
          description: The same relative path supplied to preflight, re-verified against its recorded fingerprint.
          schema:
            type: string
      responses:
        "200":
          description: Execution result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExecuteImportResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: The source or plan changed since preflight, or the job is not in a plan-ready state
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /admin/imports/{jobId}/rollback:
    post:
      tags: [Imports]
      operationId: rollbackImport
      description: >-
        Administrator only. Removes exactly the pages/attachments this job's own
        provenance created — never a page a user has since edited, which is preserved
        instead (docs/17-leafwiki-migration.md).
      parameters:
        - $ref: "#/components/parameters/ImportJobId"
      responses:
        "200":
          description: Rollback result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RollbackImportResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: There is nothing to roll back for this job
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /admin/source-batches/purge/dry-run:
    post:
      tags: [Source batch purge]
      operationId: dryRunSourceBatchPurge
      description: >-
        Administrator only. Inspects an explicitly supplied, independently recorded
        page-ID list for one source batch. It blocks on missing or unlisted source
        pages, derived content outside the list, retained backlinks or project links.
        This endpoint never writes data.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SourceBatchPurgeRequest"
      responses:
        "200":
          description: Immutable-scope dry-run and confirmation hash
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceBatchPurgeDryRunResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /admin/source-batches/purge/execute:
    post:
      tags: [Source batch purge]
      operationId: executeSourceBatchPurge
      description: >-
        Administrator only. Permanently removes only the pages and attachment
        references proven by the preceding dry-run. The confirmation hash binds the
        request to the current page hashes and attachment graph; any change requires a
        new dry-run. Physical blobs are hash-verified and removed only after their
        database references have been committed as absent.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExecuteSourceBatchPurgeRequest"
      responses:
        "200":
          description: Completed source-batch purge
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SourceBatchPurgeResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: The dry-run changed or the source scope is ambiguous
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /projects:
    get:
      tags: [Projects]
      operationId: listProjects
      parameters:
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/ProjectStatus"
        - name: priority
          in: query
          schema:
            $ref: "#/components/schemas/ProjectPriority"
        - name: ownerId
          in: query
          schema:
            type: string
            format: uuid
        - name: search
          in: query
          description: Case-insensitive match against project name or summary, applied before cursor pagination.
          schema:
            type: string
        - name: updatedAfter
          in: query
          description: Only projects updated at or after this ISO-8601 timestamp.
          schema:
            type: string
            format: date-time
        - name: sort
          in: query
          schema:
            type: string
            enum: [name, updatedAt]
      responses:
        "200":
          description: Project collection
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Projects]
      operationId: createProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProjectRequest"
      responses:
        "200":
          description: Created project (full bundle)
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectDetail"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /projects/totals:
    get:
      tags: [Projects]
      operationId: getProjectCatalogTotals
      description: Authoritative workspace totals for dashboard KPI rendering; independent of cursor-paginated catalog pages.
      responses:
        "200":
          description: Total and active project counts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectCatalogTotalsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
  /projects/{projectId}:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    get:
      tags: [Projects]
      operationId: getProject
      description: >-
        The project's bounded context bundle — structured data plus stable citations
        into linked pages, never a copy of their content (docs/15-project-hub.md
        "Project context bundle", M5-A05).
      responses:
        "200":
          description: Project detail bundle (documents, recent updates, milestones, decisions)
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
    put:
      tags: [Projects]
      operationId: updateProject
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProjectRequest"
      responses:
        "200":
          description: Updated project
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectDetail"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /projects/{projectId}/context:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    get:
      tags: [Projects]
      operationId: getProjectContext
      description: >-
        A bounded, single-call context bundle for automation and future MCP-server
        consumers (docs/09-api-contract.md "Project context", docs/24-mcp-readiness.md,
        M6-A04). Update/decision/document counts are clamped; the response reports
        what was truncated instead of ever growing unbounded. Distinct from the
        unbounded `GET /projects/{projectId}` detail bundle.
      responses:
        "200":
          description: Bounded project context bundle with stable citations
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectContextResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /projects/{projectId}/icon:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    post:
      tags: [Projects]
      operationId: uploadProjectIcon
      description: >-
        Replaces the current project icon using the attachment quarantine and
        byte-signature validation pipeline. Accepts only PNG, JPEG, GIF or WebP up to
        2 MiB. The response points to same-origin, workspace-authorized attachment
        content. Requires the project's current ETag.
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Project icon replaced
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectIconResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "413":
          description: Icon file exceeds 2 MiB
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "422":
          description: Unsupported or invalid image content
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /projects/{projectId}/status:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    post:
      tags: [Projects]
      operationId: changeProjectStatus
      description: Only the documented lifecycle transitions are accepted (docs/15-project-hub.md).
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status:
                  $ref: "#/components/schemas/ProjectStatus"
      responses:
        "200":
          description: Updated project
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: The requested transition is not allowed from the project's current status
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /projects/{projectId}/documents:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    post:
      tags: [Projects]
      operationId: linkProjectDocument
      description: >-
        Links a page to the project with a role; the page remains canonical, only the
        relationship is stored (docs/15-project-hub.md).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LinkProjectDocumentRequest"
      responses:
        "200":
          description: Created link
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectDocumentSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /projects/documents/{documentId}:
    parameters:
      - name: documentId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    delete:
      tags: [Projects]
      operationId: unlinkProjectDocument
      description: Removes only the relationship — the linked page is never touched or deleted.
      responses:
        "200":
          description: Unlinked
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /projects/{projectId}/updates:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    get:
      tags: [Projects]
      operationId: getProjectUpdates
      description: Ordered, attributable, linkable timeline (M5-A02).
      parameters:
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: Update timeline page
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectUpdatesResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Projects]
      operationId: createProjectUpdate
      description: >-
        Immutable, append-only entry. Setting supersedesUpdateId marks the earlier
        update Superseded without rewriting it (docs/15-project-hub.md).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProjectUpdateRequest"
      responses:
        "200":
          description: Created update
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectUpdateSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /projects/{projectId}/milestones:
    parameters:
      - $ref: "#/components/parameters/ProjectId"
    get:
      tags: [Projects]
      operationId: getProjectMilestones
      responses:
        "200":
          description: Milestones, in their stable sort order
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ProjectMilestoneSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Projects]
      operationId: createProjectMilestone
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProjectMilestoneRequest"
      responses:
        "200":
          description: Created milestone
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectMilestoneSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /projects/milestones/{milestoneId}:
    parameters:
      - name: milestoneId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    put:
      tags: [Projects]
      operationId: updateProjectMilestone
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProjectMilestoneRequest"
      responses:
        "200":
          description: Updated milestone
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectMilestoneSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /decisions:
    get:
      tags: [Decisions]
      operationId: listDecisions
      parameters:
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
        - name: projectId
          in: query
          schema:
            type: string
            format: uuid
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/DecisionStatus"
      responses:
        "200":
          description: Decision collection
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Decisions]
      operationId: createDecision
      description: >-
        Creates one ArchitectureDecision page plus its lifecycle profile in one step
        (docs/16-runbooks-and-adrs.md "unique page profile").
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDecisionRequest"
      responses:
        "200":
          description: Created decision (full detail, including rendered content)
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionDetail"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /decisions/{decisionId}:
    parameters:
      - name: decisionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      tags: [Decisions]
      operationId: getDecision
      description: Includes lineage (supersedes/supersededBy) — links are bidirectional and cycle-free.
      responses:
        "200":
          description: Decision detail with lineage
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /decisions/{decisionId}/accept:
    parameters:
      - name: decisionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      tags: [Decisions]
      operationId: acceptDecision
      description: >-
        If this decision supersedes another, that decision must currently be Accepted
        and is atomically flipped to Superseded with bidirectional links
        (docs/16-runbooks-and-adrs.md).
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      responses:
        "200":
          description: Accepted decision
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Only a Proposed decision can be accepted
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /decisions/{decisionId}/reject:
    parameters:
      - name: decisionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      tags: [Decisions]
      operationId: rejectDecision
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      responses:
        "200":
          description: Rejected decision
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Only a Proposed decision can be rejected
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /decisions/{decisionId}/withdraw:
    parameters:
      - name: decisionId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      tags: [Decisions]
      operationId: withdrawDecision
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      responses:
        "200":
          description: Withdrawn decision
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DecisionDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: Only a Proposed or Accepted decision can be withdrawn
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /runbooks:
    get:
      tags: [Runbooks]
      operationId: listRunbooks
      parameters:
        - $ref: "#/components/parameters/Cursor"
        - $ref: "#/components/parameters/Limit"
        - name: riskLevel
          in: query
          schema:
            $ref: "#/components/schemas/RunbookRiskLevel"
        - name: status
          in: query
          schema:
            $ref: "#/components/schemas/RunbookStatus"
      responses:
        "200":
          description: Runbook collection
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunbookListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      tags: [Runbooks]
      operationId: createRunbook
      description: >-
        Creates one Runbook page plus its validation/risk profile in one step
        (docs/16-runbooks-and-adrs.md "unique page profile").
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRunbookRequest"
      responses:
        "200":
          description: Created runbook (full detail, including rendered content)
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunbookDetail"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
  /runbooks/{runbookId}:
    parameters:
      - name: runbookId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    get:
      tags: [Runbooks]
      operationId: getRunbook
      description: >-
        isStale is true whenever the linked page has a newer revision than the last
        validation, or was never validated (docs/16-runbooks-and-adrs.md).
      responses:
        "200":
          description: Runbook detail
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunbookDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
  /runbooks/{runbookId}/validate:
    parameters:
      - name: runbookId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      tags: [Runbooks]
      operationId: validateRunbook
      description: >-
        Records that a human reviewed the current revision — the platform never
        executes any step (docs/16-runbooks-and-adrs.md).
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      responses:
        "200":
          description: Validated runbook
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunbookDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /runbooks/{runbookId}/profile:
    parameters:
      - name: runbookId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    put:
      tags: [Runbooks]
      operationId: updateRunbookProfile
      parameters:
        - $ref: "#/components/parameters/IfMatch"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRunbookProfileRequest"
      responses:
        "200":
          description: Updated runbook
          headers:
            ETag:
              $ref: "#/components/headers/ETag"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunbookDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "412":
          $ref: "#/components/responses/PreconditionFailed"
        "428":
          $ref: "#/components/responses/PreconditionRequired"
  /service-accounts:
    get:
      tags: [Service accounts]
      operationId: listServiceAccounts
      description: Administrator-only, cookie-authenticated — never reachable by a service token itself (docs/09-api-contract.md).
      responses:
        "200":
          description: Service accounts and their (secret-free) tokens
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ServiceAccountListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      tags: [Service accounts]
      operationId: createServiceAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateServiceAccountRequest"
      responses:
        "200":
          description: Service account and its one-time raw token — never retrievable again
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedServiceAccountToken"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          description: One or more requested scopes are not recognized
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
  /service-accounts/{serviceAccountId}/tokens:
    parameters:
      - name: serviceAccountId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      tags: [Service accounts]
      operationId: issueServiceAccountToken
      description: >-
        Rotation pattern: issue a new token, update the client, then revoke the old
        one — a credential is never briefly unusable.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IssueServiceAccountTokenRequest"
      responses:
        "200":
          description: New token — its one-time raw value
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatedServiceAccountToken"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /service-accounts/tokens/{tokenId}/revoke:
    parameters:
      - name: tokenId
        in: path
        required: true
        schema:
          type: string
          format: uuid
    post:
      tags: [Service accounts]
      operationId: revokeServiceAccountToken
      description: Takes effect on the very next request using this token — tokens are verified live against the database, never cached as valid.
      responses:
        "200":
          description: Revoked
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /admin/backups:
    get:
      tags: [Backups]
      operationId: listBackups
      description: >-
        Administrator-only (docs/18-backup-restore.md). Never includes a filesystem
        path or connection string — only what an administrator needs to judge backup
        health.
      responses:
        "200":
          description: Completed backups, newest first
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BackupListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      tags: [Backups]
      operationId: createBackup
      description: >-
        Synchronously creates and verifies a full backup (every table plus every
        content-addressed attachment blob), then applies retention. A failed backup
        never replaces the last known-good one. Restore is intentionally not exposed
        here — it runs as a separate maintenance-mode invocation of the same
        deployable image (docs/18-backup-restore.md; ADR-016 decision 4).
      responses:
        "200":
          description: The newly created, verified backup
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BackupSummaryResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: A backup is already in progress
          content:
            application/problem+json:
              schema:
                $ref: "#/components/schemas/ProblemDetails"
components:
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: ikh_auth
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: IKH service token
  parameters:
    CorrelationId:
      name: X-Correlation-ID
      in: header
      required: false
      schema:
        type: string
        maxLength: 100
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        minLength: 16
        maxLength: 200
    RequiredIdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 200
    Cursor:
      name: cursor
      in: query
      required: false
      schema:
        type: string
        maxLength: 2048
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
    PageId:
      name: pageId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    SessionId:
      name: sessionId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    RevisionNumber:
      name: revisionNumber
      in: path
      required: true
      schema:
        type: integer
        format: int64
        minimum: 1
    ImportJobId:
      name: jobId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ProjectId:
      name: projectId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    UserId:
      name: userId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    DraftKey:
      name: draftKey
      in: path
      required: true
      description: The page ID in edit mode, or a client-generated key for an unpublished new page.
      schema:
        type: string
    IfMatch:
      name: If-Match
      in: header
      required: true
      schema:
        type: string
  headers:
    ETag:
      description: Strong entity version tag
      schema:
        type: string
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    Unauthorized:
      description: Authentication required
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    Forbidden:
      description: Insufficient permission
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    NotFound:
      description: Resource not found or not disclosed
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    Conflict:
      description: Idempotency or domain conflict
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    PreconditionFailed:
      description: ETag does not match the current resource
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    PreconditionRequired:
      description: If-Match is required
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    ValidationFailed:
      description: Request failed validation
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
    RateLimited:
      description: Request rate limited
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/ProblemDetails"
  schemas:
    CreateIngestionProposalRequest:
      type: object
      required: [manifest]
      properties:
        manifest: { type: string, minLength: 1, maxLength: 100000 }
        correlationId: { type: [string, "null"], maxLength: 200 }
        publication: { oneOf: [{ $ref: "#/components/schemas/IngestionPublicationRequest" }, { type: "null" }] }
    IngestionPublicationRequest:
      type: object
      required: [title, markdown, documentType, documentStatus, mutationKind]
      properties:
        title: { type: string, minLength: 1, maxLength: 200 }
        markdown: { type: string, minLength: 1, maxLength: 100000 }
        documentType: { $ref: "#/components/schemas/DocumentType" }
        documentStatus: { $ref: "#/components/schemas/DocumentStatus" }
        mutationKind: { type: string, enum: [CreatePage, UpdatePage] }
        parentPageId: { type: [string, "null"], format: uuid }
        targetPageId: { type: [string, "null"], format: uuid }
        expectedTargetETag: { type: [string, "null"], maxLength: 32 }
    PatchIngestionProposalRequest:
      type: object
      description: Human callers use manifest/rationale; the submitting service account uses analysis only.
      properties:
        manifest: { type: [string, "null"], maxLength: 100000 }
        rationale: { type: [string, "null"], maxLength: 2000 }
        analysis: { type: [string, "null"], maxLength: 100000 }
    IngestionProposalDecisionRequest:
      type: object
      properties:
        comment: { type: [string, "null"], maxLength: 2000 }
    IngestionProposalSourceDetail:
      type: object
      required: [id, fileName, mimeType, byteSize, digestSha256, scanResult, attachmentReferenceId]
      properties:
        id: { type: string, format: uuid }
        fileName: { type: string }
        mimeType: { type: string }
        byteSize: { type: integer, format: int64 }
        digestSha256: { type: string, pattern: '^[a-f0-9]{64}$' }
        scanResult: { type: string }
        attachmentReferenceId: { type: string, format: uuid }
    IngestionProposalRevisionDetail:
      type: object
      required: [revisionNumber, status, operation, actorId, occurredAt]
      properties:
        revisionNumber: { type: integer, format: int64 }
        status: { type: string }
        operation: { type: string }
        actorId: { type: string, format: uuid }
        occurredAt: { type: string, format: date-time }
    IngestionProposalSummary:
      type: object
      required: [id, correlationId, status, revisionNumber, sourceCount, submitterId, createdAt, destination, metadata, mutationKind]
      properties:
        id: { type: string, format: uuid }
        correlationId: { type: string }
        status: { type: string }
        revisionNumber: { type: integer, format: int64 }
        sourceCount: { type: integer }
        submitterId: { type: string, format: uuid }
        createdAt: { type: string, format: date-time }
        destination: { oneOf: [{ $ref: "#/components/schemas/IngestionProposalDestination" }, { type: "null" }] }
        metadata: { $ref: "#/components/schemas/IngestionProposalMetadata" }
        mutationKind: { type: [string, "null"], enum: [CreatePage, UpdatePage, null] }
    IngestionProposalListResponse:
      type: object
      required: [items, nextCursor, page, pageSize, total, correlationId]
      properties:
        items: { type: array, items: { $ref: "#/components/schemas/IngestionProposalSummary" } }
        nextCursor: { type: [string, "null"] }
        page: { type: integer, minimum: 1 }
        pageSize: { type: integer, minimum: 1, maximum: 100 }
        total: { type: integer, format: int64, minimum: 0 }
        correlationId: { type: string }
    IngestionProposalDestination:
      type: object
      required: [pageId, parentPageId, title]
      properties:
        pageId: { type: [string, "null"], format: uuid }
        parentPageId: { type: [string, "null"], format: uuid }
        title: { type: [string, "null"] }
    IngestionProposalMetadata:
      type: object
      description: Project and risk are currently unavailable persisted attributes and are therefore explicitly null.
      required: [documentType, documentStatus, projectId, risk]
      properties:
        documentType: { type: [string, "null"] }
        documentStatus: { type: [string, "null"] }
        projectId: { type: [string, "null"], format: uuid }
        risk: { type: [string, "null"], enum: [low, medium, high, null] }
    IngestionProposalCitation:
      type: object
      required: [label, pageId, excerpt, confidence]
      properties:
        label: { type: string }
        pageId: { type: [string, "null"], format: uuid }
        excerpt: { type: [string, "null"] }
        confidence: { type: [number, "null"] }
    IngestionProposalWarning:
      type: object
      required: [code, message, severity]
      properties:
        code: { type: string }
        message: { type: string }
        severity: { type: [string, "null"], enum: [low, medium, high, null] }
    IngestionProposalCandidate:
      type: object
      required: [pageId, title, kind]
      properties:
        pageId: { type: [string, "null"], format: uuid }
        title: { type: [string, "null"] }
        kind: { type: [string, "null"] }
    IngestionProposalDiff:
      type: object
      required: [before, after, summary]
      properties:
        before: { type: [string, "null"] }
        after: { type: [string, "null"] }
        summary: { type: [string, "null"] }
    IngestionProposalPermissions:
      type: object
      required: [canEdit, canDecide, canPublish]
      properties:
        canEdit: { type: boolean }
        canDecide: { type: boolean }
        canPublish: { type: boolean }
    IngestionProposalDetail:
      type: object
      description: Safe dossier metadata only; it never contains source bytes, paths, URLs, credentials, or tokens.
      required: [id, correlationId, status, revisionNumber, manifest, retryCount, maxPublishRetries, isRetryEligible, sources, revisions, etag, submitterId, createdAt, destination, metadata, mutationKind, attachments, expectedTargetETag, citations, warnings, duplicateCandidates, conflictCandidates, diff, permissions]
      properties:
        id: { type: string, format: uuid }
        correlationId: { type: string }
        status: { type: string }
        revisionNumber: { type: integer, format: int64 }
        manifest: { type: string }
        analysis: { type: [string, "null"] }
        reviewerComment: { type: [string, "null"] }
        retryCount: { type: integer }
        maxPublishRetries: { type: integer }
        isRetryEligible: { type: boolean }
        failedLifecycleStatus: { type: [string, "null"] }
        failedProcessingStage: { type: [string, "null"] }
        failureErrorType: { type: [string, "null"] }
        failureMessage: { type: [string, "null"] }
        sources: { type: array, items: { $ref: "#/components/schemas/IngestionProposalSourceDetail" } }
        revisions: { type: array, items: { $ref: "#/components/schemas/IngestionProposalRevisionDetail" } }
        etag: { type: string }
        publishedPageId: { type: [string, "null"], format: uuid }
        publishedPageRevisionNumber: { type: [integer, "null"], format: int64 }
        submitterId: { type: string, format: uuid }
        createdAt: { type: string, format: date-time }
        destination: { oneOf: [{ $ref: "#/components/schemas/IngestionProposalDestination" }, { type: "null" }] }
        metadata: { $ref: "#/components/schemas/IngestionProposalMetadata" }
        mutationKind: { type: [string, "null"], enum: [CreatePage, UpdatePage, null] }
        attachments: { type: array, items: { $ref: "#/components/schemas/IngestionProposalSourceDetail" } }
        expectedTargetETag: { type: [string, "null"] }
        citations: { type: array, items: { $ref: "#/components/schemas/IngestionProposalCitation" } }
        warnings: { type: array, items: { $ref: "#/components/schemas/IngestionProposalWarning" } }
        duplicateCandidates: { type: array, items: { $ref: "#/components/schemas/IngestionProposalCandidate" } }
        conflictCandidates: { type: array, items: { $ref: "#/components/schemas/IngestionProposalCandidate" } }
        diff:
          description: after contains the proposed publication Markdown. before is null when no current target snapshot is available.
          oneOf: [{ $ref: "#/components/schemas/IngestionProposalDiff" }, { type: "null" }]
        permissions: { $ref: "#/components/schemas/IngestionProposalPermissions" }
    SystemInfo:
      type: object
      required: [product, version, commit, schemaVersion, environment, primaryLocale, timeZone, uptimeSeconds, release]
      properties:
        product:
          type: string
          const: ItWorx Knowledge Hub
        version:
          type: string
        commit:
          type: string
        schemaVersion:
          type: string
        environment:
          type: string
        primaryLocale:
          type: string
        timeZone:
          type: string
        uptimeSeconds:
          type: integer
        release:
          $ref: "#/components/schemas/ReleaseIdentity"
    ReleaseIdentity:
      type: object
      description: >-
        The canonical, machine-readable release identity
        (docs/adr/ADR-029-v2-r5-final-hardening.md). Every field is honestly nullable —
        a value not actually known at build or deploy time is never fabricated.
      required: [semanticVersion, releaseTag, sourceCommit, imageRepository, imageTag, imageId, imageDigest, buildTimestamp, deploymentTimestamp, openApiVersion, openApiHash, frontendBuildHash, databaseMigrationRange, inventorySnapshotId, backupId]
      properties:
        semanticVersion:
          type: [string, "null"]
        releaseTag:
          type: [string, "null"]
        sourceCommit:
          type: [string, "null"]
        imageRepository:
          type: [string, "null"]
        imageTag:
          type: [string, "null"]
        imageId:
          type: [string, "null"]
        imageDigest:
          type: [string, "null"]
        buildTimestamp:
          type: [string, "null"]
          format: date-time
        deploymentTimestamp:
          type: [string, "null"]
          format: date-time
        openApiVersion:
          type: [string, "null"]
        openApiHash:
          type: [string, "null"]
        frontendBuildHash:
          type: [string, "null"]
        databaseMigrationRange:
          type: [string, "null"]
          description: "The first and last applied EF Core migration for the database this instance is actually connected to, formatted as 'first..last' (or a single migration name if only one has been applied)."
        inventorySnapshotId:
          type: [string, "null"]
        backupId:
          type: [string, "null"]
          format: int64
          minimum: 0
    DocumentType:
      type: string
      enum:
        - WikiPage
        - StudyNote
        - CourseModule
        - ProjectDocument
        - ArchitectureDecision
        - Runbook
        - Troubleshooting
        - Reference
        - ChangeLog
        - SessionNote
        - Checklist
    DocumentStatus:
      type: string
      enum: [Draft, Active, NeedsReview, Deprecated, Archived]
    PageSummary:
      type: object
      required: [id, parentPageId, title, slug, documentType, documentStatus, hasChildren, updatedAt]
      properties:
        id:
          type: string
          format: uuid
        parentPageId:
          type: [string, "null"]
          format: uuid
        title:
          type: string
        slug:
          type: string
        documentType:
          $ref: "#/components/schemas/DocumentType"
        documentStatus:
          $ref: "#/components/schemas/DocumentStatus"
        hasChildren:
          type: boolean
        updatedAt:
          type: string
          format: date-time
    PageChildrenResponse:
      type: object
      required: [items, nextCursor]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/PageSummary"
        nextCursor:
          type: [string, "null"]
    BreadcrumbEntry:
      type: object
      required: [id, title]
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
    PageDetail:
      type: object
      required:
        - id
        - workspaceId
        - parentPageId
        - title
        - slug
        - markdown
        - renderedHtml
        - documentType
        - documentStatus
        - currentRevisionNumber
        - tags
        - breadcrumb
        - createdBy
        - updatedBy
        - createdAt
        - updatedAt
        - publishedAt
        - trashedAt
        - eTag
      properties:
        id:
          type: string
          format: uuid
        workspaceId:
          type: string
          format: uuid
        parentPageId:
          type: [string, "null"]
          format: uuid
        title:
          type: string
        slug:
          type: string
        markdown:
          type: string
        renderedHtml:
          type: string
          description: Server-rendered and sanitized. Never render untrusted Markdown as HTML client-side.
        documentType:
          $ref: "#/components/schemas/DocumentType"
        documentStatus:
          $ref: "#/components/schemas/DocumentStatus"
        currentRevisionNumber:
          type: integer
          format: int64
        tags:
          type: array
          items:
            type: string
        breadcrumb:
          type: array
          items:
            $ref: "#/components/schemas/BreadcrumbEntry"
        createdBy:
          type: [string, "null"]
          format: uuid
        updatedBy:
          type: [string, "null"]
          format: uuid
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        publishedAt:
          type: [string, "null"]
          format: date-time
        trashedAt:
          type: [string, "null"]
          format: date-time
          description: Null unless the page is in the trash/retention model.
        eTag:
          type: string
          description: Also present as the response ETag header; included in the body so clients need not parse headers.
    CreatePageRequest:
      type: object
      required: [parentPageId, title, documentType, markdown, templateKey]
      description: >-
        Either supply documentType and markdown directly, or supply templateKey to seed
        the page from a starter template (in which case documentType/markdown are
        ignored and may be null).
      properties:
        parentPageId:
          type: [string, "null"]
          format: uuid
        title:
          type: string
          minLength: 1
          maxLength: 300
        documentType:
          oneOf:
            - $ref: "#/components/schemas/DocumentType"
            - type: "null"
        markdown:
          type: [string, "null"]
          maxLength: 2097152
        templateKey:
          type: [string, "null"]
        tags:
          type: array
          items:
            type: string
          maxItems: 25
    BeginPageCreationSessionRequest:
      type: object
      properties:
        parentPageId:
          type: [string, "null"]
          format: uuid
    PageCreationSessionResponse:
      type: object
      required: [sessionId, expiresAt]
      properties:
        sessionId:
          type: string
          format: uuid
        expiresAt:
          type: string
          format: date-time
    CommitPageCreationSessionRequest:
      type: object
      required: [title]
      description: >-
        No parentPageId (fixed at session-begin time) or templateKey (a template and
        pre-publish attachments are mutually exclusive, matching the existing
        product behavior).
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 300
        documentType:
          oneOf:
            - $ref: "#/components/schemas/DocumentType"
            - type: "null"
        markdown:
          type: [string, "null"]
          maxLength: 2097152
        tags:
          type: array
          items:
            type: string
          maxItems: 25
    DiscardPageCreationSessionResponse:
      type: object
      required: [attachmentsRemoved]
      properties:
        attachmentsRemoved:
          type: integer
    UpdatePageRequest:
      type: object
      required: [title, markdown, documentType, documentStatus, changeSummary]
      properties:
        title:
          type: string
          minLength: 1
          maxLength: 300
        markdown:
          type: string
          maxLength: 2097152
        documentType:
          $ref: "#/components/schemas/DocumentType"
        documentStatus:
          $ref: "#/components/schemas/DocumentStatus"
        changeSummary:
          type: [string, "null"]
          maxLength: 500
        tags:
          type: array
          items:
            type: string
          maxItems: 25
          description: Omitted or null leaves the page's tags unchanged.
    MovePageRequest:
      type: object
      required: [newParentPageId, afterSiblingId]
      properties:
        newParentPageId:
          type: [string, "null"]
          format: uuid
        afterSiblingId:
          type: [string, "null"]
          format: uuid
          description: Null means "first among the new siblings".
    TemplateSummary:
      type: object
      required: [key, name, documentType, description]
      properties:
        key:
          type: string
        name:
          type: string
        documentType:
          $ref: "#/components/schemas/DocumentType"
        description:
          type: string
    DraftResponse:
      type: object
      required: [draftKey, pageId, baseRevisionNumber, title, markdown, updatedAt, expiresAt, baseRevisionIsStale]
      properties:
        draftKey:
          type: string
        pageId:
          type: [string, "null"]
          format: uuid
        baseRevisionNumber:
          type: [integer, "null"]
          format: int64
        title:
          type: string
        markdown:
          type: string
        updatedAt:
          type: string
          format: date-time
        expiresAt:
          type: string
          format: date-time
        baseRevisionIsStale:
          type: boolean
          description: True when the page has published a newer revision since this draft's base.
    SaveDraftRequest:
      type: object
      required: [pageId, baseRevisionNumber, title, markdown]
      properties:
        pageId:
          type: [string, "null"]
          format: uuid
        baseRevisionNumber:
          type: [integer, "null"]
          format: int64
        title:
          type: string
        markdown:
          type: string
    PageRevisionSummary:
      type: object
      required: [revisionNumber, title, documentType, documentStatus, authoredBy, changeSummary, createdAt]
      properties:
        revisionNumber:
          type: integer
          format: int64
        title:
          type: string
        documentType:
          $ref: "#/components/schemas/DocumentType"
        documentStatus:
          $ref: "#/components/schemas/DocumentStatus"
        authoredBy:
          type: [string, "null"]
          format: uuid
        changeSummary:
          type: [string, "null"]
        createdAt:
          type: string
          format: date-time
    PageRevisionDetailResponse:
      type: object
      required: [revisionNumber, title, markdown, renderedHtml, documentType, documentStatus, authoredBy, changeSummary, createdAt]
      properties:
        revisionNumber:
          type: integer
          format: int64
        title:
          type: string
        markdown:
          type: string
        renderedHtml:
          type: string
          description: >-
            Server-rendered and sanitized without re-resolving internal links against
            today's link table (a historical snapshot's links are not live).
        documentType:
          $ref: "#/components/schemas/DocumentType"
        documentStatus:
          $ref: "#/components/schemas/DocumentStatus"
        authoredBy:
          type: [string, "null"]
          format: uuid
        changeSummary:
          type: [string, "null"]
        createdAt:
          type: string
          format: date-time
    BacklinkEntry:
      type: object
      required: [id, title, slug, documentType]
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        slug:
          type: string
        documentType:
          $ref: "#/components/schemas/DocumentType"
    BacklinksResponse:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/BacklinkEntry"
    TrashPurgeResponse:
      type: object
      required: [purgedCount]
      properties:
        purgedCount:
          type: integer
    AttachmentDeliveryPolicy:
      type: string
      enum: [InlinePreviewEligible, DownloadOnly, Unknown]
    AttachmentSummary:
      type: object
      required: [id, filename, mediaType, deliveryPolicy, byteLength, description, altText, createdAt]
      properties:
        id:
          type: string
          format: uuid
        filename:
          type: string
          description: The sanitized, stored display filename — never necessarily identical to what the client declared.
        mediaType:
          type: string
          description: The detected media type from the byte signature, not the caller-declared Content-Type.
        deliveryPolicy:
          $ref: "#/components/schemas/AttachmentDeliveryPolicy"
        byteLength:
          type: integer
          format: int64
        description:
          type: [string, "null"]
        altText:
          type: [string, "null"]
        createdAt:
          type: string
          format: date-time
    AttachmentListResponse:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/AttachmentSummary"
    ManualOverrideFieldCatalogEntry:
      type: object
      required: [fieldName, displayLabel, valueKind, maxStringLength, allowedEnumValues]
      properties:
        fieldName:
          type: string
        displayLabel:
          type: string
        valueKind:
          type: string
          enum: [Text, Enum]
        maxStringLength:
          type: integer
          description: 0 for an Enum-kind field, where length is governed by allowedEnumValues instead.
        allowedEnumValues:
          type: [array, "null"]
          items:
            type: string
    ManualOverrideFieldCatalogResponse:
      type: object
      required: [targetKind, fields]
      properties:
        targetKind:
          type: string
        fields:
          type: array
          items:
            $ref: "#/components/schemas/ManualOverrideFieldCatalogEntry"
    FactProvenance:
      type: object
      required: [sourceKey, confidence, lastSnapshotId, observedAt]
      properties:
        sourceKey:
          type: string
        confidence:
          type: string
          enum: [Observed, Inferred, Declared, Unknown]
        lastSnapshotId:
          type: string
          format: uuid
        observedAt:
          type: string
          format: date-time
    InventorySnapshotSummary:
      type: object
      required: [id, sourceKey, sourceHash, capturedAt, importedAt, hostCount, serviceCount]
      properties:
        id:
          type: string
          format: uuid
        sourceKey:
          type: string
        sourceHash:
          type: string
        capturedAt:
          type: string
          format: date-time
        importedAt:
          type: string
          format: date-time
        hostCount:
          type: integer
        serviceCount:
          type: integer
    InfrastructureHostSummary:
      type: object
      required: [id, sourceKey, hostname, operatingSystem, kernelVersion, architecture, logicalCpuCount, totalMemoryBytes, presence, lastSeenAt]
      properties:
        id:
          type: string
          format: uuid
        sourceKey:
          type: string
        hostname:
          type: string
        operatingSystem:
          type: string
        kernelVersion:
          type: string
        architecture:
          type: string
        logicalCpuCount:
          type: integer
        totalMemoryBytes:
          type: integer
          format: int64
        presence:
          type: string
          enum: [Present, Missing]
        lastSeenAt:
          type: string
          format: date-time
    InfrastructureOverviewResponse:
      type: object
      required: [latestSnapshot, hosts, serviceCount, proposedServiceCount, missingServiceCount, unhealthyServiceCount, unprotectedServiceCount]
      properties:
        latestSnapshot:
          type: [object, "null"]
          allOf:
            - $ref: "#/components/schemas/InventorySnapshotSummary"
        hosts:
          type: array
          items:
            $ref: "#/components/schemas/InfrastructureHostSummary"
        serviceCount:
          type: integer
        proposedServiceCount:
          type: integer
        missingServiceCount:
          type: integer
        unhealthyServiceCount:
          type: integer
        unprotectedServiceCount:
          type: integer
    InfrastructureServiceSummary:
      type: object
      required: [id, sourceKey, name, detectedName, category, summary, runtimeKind, runtimeStatus, health, presence, confidence, imageReference, projectId, projectName, backupStatus, primaryEndpointUrl, isFavorite, isHidden, componentCount, endpointCount, volumeCount, databaseCount, lastSeenAt]
      properties:
        id:
          type: string
          format: uuid
        sourceKey:
          type: string
        name:
          type: string
          description: Editorial display name if set, otherwise the detected name.
        detectedName:
          type: string
        category:
          type: string
        summary:
          type: string
        runtimeKind:
          type: string
        runtimeStatus:
          type: string
        health:
          type: string
          enum: [Healthy, Degraded, Unhealthy, Unknown]
        presence:
          type: string
          enum: [Present, Proposed, Missing]
        confidence:
          type: string
          enum: [Observed, Inferred, Declared, Unknown]
        imageReference:
          type: string
        projectId:
          type: [string, "null"]
          format: uuid
        projectName:
          type: [string, "null"]
        backupStatus:
          type: string
        primaryEndpointUrl:
          type: [string, "null"]
        isFavorite:
          type: boolean
        isHidden:
          type: boolean
        componentCount:
          type: integer
        endpointCount:
          type: integer
        volumeCount:
          type: integer
        databaseCount:
          type: integer
        lastSeenAt:
          type: string
          format: date-time
    InfrastructureServiceListResponse:
      type: object
      required: [items, nextCursor, totalCount]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/InfrastructureServiceSummary"
        nextCursor:
          type: [string, "null"]
        totalCount:
          type: integer
          description: >-
            How many services match the current `search`/`status`/`projectId`/
            `includeHidden` filters in total (OUX-4). Counted server-side before
            cursor pagination, so it is the size of the filtered catalog rather than
            of the returned page, and stays stable while paging through it.
    InfrastructureStorageRow:
      type: object
      required: [id, serviceId, serviceName, name, mountPath, storageClass, readOnly, sizeBytes, provenance]
      properties:
        id:
          type: string
          format: uuid
        serviceId:
          type: string
          format: uuid
        serviceName:
          type: string
        name:
          type: string
        mountPath:
          type: string
        storageClass:
          type: string
        readOnly:
          type: boolean
        sizeBytes:
          type: [integer, "null"]
          format: int64
        provenance:
          $ref: "#/components/schemas/FactProvenance"
    InfrastructureStorageListResponse:
      type: object
      required: [items, nextCursor]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/InfrastructureStorageRow"
        nextCursor:
          type: [string, "null"]
    EditorialProfileResponse:
      type: object
      required: [id, displayName, summary, category, purpose, ownerId, projectId, repositoryUrl, liveUrl, backupStatus, monitoringUrl, maintenanceNotes, knownRisks, updateProcedure, rollbackProcedure, tags, isFavorite, isHidden, isArchived, updatedAt, etag]
      properties:
        id:
          type: string
          format: uuid
        displayName:
          type: string
        summary:
          type: string
        category:
          type: string
        purpose:
          type: string
        ownerId:
          type: [string, "null"]
          format: uuid
        projectId:
          type: [string, "null"]
          format: uuid
        repositoryUrl:
          type: string
        liveUrl:
          type: string
        backupStatus:
          type: string
        monitoringUrl:
          type: string
        maintenanceNotes:
          type: string
        knownRisks:
          type: string
        updateProcedure:
          type: string
        rollbackProcedure:
          type: string
        tags:
          type: array
          items:
            type: string
        isFavorite:
          type: boolean
        isHidden:
          type: boolean
        isArchived:
          type: boolean
        updatedAt:
          type: string
          format: date-time
        etag:
          type: string
    ManualOverrideResponse:
      type: object
      required: [id, fieldName, value, reason, createdBy, updatedAt]
      properties:
        id:
          type: string
          format: uuid
        fieldName:
          type: string
        value:
          description: The overridden value — any JSON scalar, array or object, matching the field's ManualOverrideFieldCatalogEntry.valueKind.
        reason:
          type: string
        createdBy:
          type: string
          format: uuid
        updatedAt:
          type: string
          format: date-time
    ServiceComponentResponse:
      type: object
      required: [id, name, kind, runtimeId, status, imageReference, provenance]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        kind:
          type: string
        runtimeId:
          type: string
        status:
          type: string
        imageReference:
          type: string
        provenance:
          $ref: "#/components/schemas/FactProvenance"
    InfrastructureEndpointResponse:
      type: object
      required: [id, scheme, host, publishedPort, targetPort, url, isPublic, provenance]
      properties:
        id:
          type: string
          format: uuid
        scheme:
          type: string
        host:
          type: string
        publishedPort:
          type: [integer, "null"]
        targetPort:
          type: [integer, "null"]
        url:
          type: string
        isPublic:
          type: boolean
        provenance:
          $ref: "#/components/schemas/FactProvenance"
    InfrastructureNetworkResponse:
      type: object
      required: [id, name, driver, scope, internal, provenance]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        driver:
          type: string
        scope:
          type: string
        internal:
          type: boolean
        provenance:
          $ref: "#/components/schemas/FactProvenance"
    InfrastructureVolumeResponse:
      type: object
      required: [id, name, mountPath, storageClass, readOnly, sizeBytes, provenance]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        mountPath:
          type: string
        storageClass:
          type: string
        readOnly:
          type: boolean
        sizeBytes:
          type: [integer, "null"]
          format: int64
        provenance:
          $ref: "#/components/schemas/FactProvenance"
    InfrastructureDatabaseResponse:
      type: object
      required: [id, name, engine, version, host, port, hostPortPublished, provenance]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        engine:
          type: string
        version:
          type: string
        host:
          type: string
        port:
          type: [integer, "null"]
        hostPortPublished:
          type: boolean
        provenance:
          $ref: "#/components/schemas/FactProvenance"
    ServiceDependencyResponse:
      type: object
      required: [id, dependsOnServiceId, dependsOnSourceKey, kind, provenance]
      properties:
        id:
          type: string
          format: uuid
        dependsOnServiceId:
          type: [string, "null"]
          format: uuid
        dependsOnSourceKey:
          type: string
        kind:
          type: string
        provenance:
          $ref: "#/components/schemas/FactProvenance"
    HealthObservationResponse:
      type: object
      required: [id, state, checkKind, responseTimeMilliseconds, provenance]
      properties:
        id:
          type: string
          format: uuid
        state:
          type: string
          enum: [Healthy, Degraded, Unhealthy, Unknown]
        checkKind:
          type: string
        responseTimeMilliseconds:
          type: [integer, "null"]
        provenance:
          $ref: "#/components/schemas/FactProvenance"
    DeploymentReferenceResponse:
      type: object
      required: [id, repositoryUrl, commit, imageReference, imageDigest, deployedAt, provenance]
      properties:
        id:
          type: string
          format: uuid
        repositoryUrl:
          type: string
        commit:
          type: string
        imageReference:
          type: string
        imageDigest:
          type: string
        deployedAt:
          type: [string, "null"]
          format: date-time
        provenance:
          $ref: "#/components/schemas/FactProvenance"
    BackupCoverageResponse:
      type: object
      required: [id, method, schedule, lastSuccessfulAt, restoreTested, provenance]
      properties:
        id:
          type: string
          format: uuid
        method:
          type: string
        schedule:
          type: string
        lastSuccessfulAt:
          type: [string, "null"]
          format: date-time
        restoreTested:
          type: boolean
        provenance:
          $ref: "#/components/schemas/FactProvenance"
    InfrastructureServiceDetail:
      type: object
      required: [service, editorialProfile, editorialETag, overrides, components, endpoints, networks, volumes, databases, dependencies, healthObservations, deployments, backups]
      properties:
        service:
          $ref: "#/components/schemas/InfrastructureServiceSummary"
        editorialProfile:
          type: [object, "null"]
          allOf:
            - $ref: "#/components/schemas/EditorialProfileResponse"
        editorialETag:
          type: string
        overrides:
          type: array
          items:
            $ref: "#/components/schemas/ManualOverrideResponse"
        components:
          type: array
          items:
            $ref: "#/components/schemas/ServiceComponentResponse"
        endpoints:
          type: array
          items:
            $ref: "#/components/schemas/InfrastructureEndpointResponse"
        networks:
          type: array
          items:
            $ref: "#/components/schemas/InfrastructureNetworkResponse"
        volumes:
          type: array
          items:
            $ref: "#/components/schemas/InfrastructureVolumeResponse"
        databases:
          type: array
          items:
            $ref: "#/components/schemas/InfrastructureDatabaseResponse"
        dependencies:
          type: array
          items:
            $ref: "#/components/schemas/ServiceDependencyResponse"
        healthObservations:
          type: array
          items:
            $ref: "#/components/schemas/HealthObservationResponse"
        deployments:
          type: array
          items:
            $ref: "#/components/schemas/DeploymentReferenceResponse"
        backups:
          type: array
          items:
            $ref: "#/components/schemas/BackupCoverageResponse"
    UpdateEditorialProfileRequest:
      type: object
      required: [isFavorite, isHidden, isArchived]
      description: Every field besides the three booleans is optional — omit a field to leave it unchanged.
      properties:
        displayName:
          type: [string, "null"]
        summary:
          type: [string, "null"]
        category:
          type: [string, "null"]
        purpose:
          type: [string, "null"]
        ownerId:
          type: [string, "null"]
          format: uuid
        projectId:
          type: [string, "null"]
          format: uuid
        repositoryUrl:
          type: [string, "null"]
        liveUrl:
          type: [string, "null"]
        backupStatus:
          type: [string, "null"]
        monitoringUrl:
          type: [string, "null"]
        maintenanceNotes:
          type: [string, "null"]
        knownRisks:
          type: [string, "null"]
        updateProcedure:
          type: [string, "null"]
        rollbackProcedure:
          type: [string, "null"]
        tags:
          type: [array, "null"]
          items:
            type: string
        isFavorite:
          type: boolean
        isHidden:
          type: boolean
        isArchived:
          type: boolean
    SetManualOverrideRequest:
      type: object
      required: [fieldName, value]
      properties:
        fieldName:
          type: string
          description: Must be one of the field names GET /infrastructure/overrides/catalog returns for the target's object kind.
        value:
          description: Any JSON scalar, array or object, validated server-side against the field's catalog entry (valueKind, maxStringLength, allowedEnumValues).
        reason:
          type: [string, "null"]
    SetInfrastructureOverrideRequest:
      type: object
      required: [targetKind, targetId, fieldName, value]
      properties:
        targetKind:
          type: string
          enum: [Host, Service, Component, Endpoint, Network, Volume, Database, Deployment, Backup]
        targetId:
          type: string
          format: uuid
        fieldName:
          type: string
          description: Must be one of the field names GET /infrastructure/overrides/catalog?targetKind=... returns for this targetKind.
        value:
          description: Any JSON scalar, array or object, validated server-side against the field's catalog entry (valueKind, maxStringLength, allowedEnumValues).
        reason:
          type: [string, "null"]
    ReviewInfrastructureServiceRequest:
      type: object
      required: [decision]
      properties:
        decision:
          type: string
          enum: [Accept, Reject]
        reason:
          type: [string, "null"]
    ReviewInfrastructureServiceResponse:
      type: object
      required: [serviceId, presence]
      properties:
        serviceId:
          type: string
          format: uuid
        presence:
          type: string
          enum: [Present, Missing]
    InventoryChangeResponse:
      type: object
      required: [id, snapshotId, targetKind, targetId, sourceKey, changeKind, changedFields, recordedAt]
      properties:
        id:
          type: string
          format: uuid
        snapshotId:
          type: string
          format: uuid
        targetKind:
          type: string
        targetId:
          type: string
          format: uuid
        sourceKey:
          type: string
        changeKind:
          type: string
          enum: [Added, Updated, Missing, Unchanged]
        changedFields:
          type: array
          items:
            type: string
        recordedAt:
          type: string
          format: date-time
    InventoryHostRequest:
      type: object
      required: [sourceKey, hostname, logicalCpuCount, totalMemoryBytes]
      properties:
        sourceKey:
          type: string
        hostname:
          type: string
        operatingSystem:
          type: [string, "null"]
        kernelVersion:
          type: [string, "null"]
        architecture:
          type: [string, "null"]
        logicalCpuCount:
          type: integer
        totalMemoryBytes:
          type: integer
          format: int64
    InventoryFactConfidence:
      type: string
      enum: [Observed, Inferred, Declared, Unknown]
    InventoryComponentRequest:
      type: object
      required: [sourceKey, name, confidence]
      properties:
        sourceKey:
          type: string
        name:
          type: string
        kind:
          type: [string, "null"]
        runtimeId:
          type: [string, "null"]
        status:
          type: [string, "null"]
        imageReference:
          type: [string, "null"]
        confidence:
          $ref: "#/components/schemas/InventoryFactConfidence"
    InventoryEndpointRequest:
      type: object
      required: [sourceKey, isPublic, confidence]
      properties:
        sourceKey:
          type: string
        scheme:
          type: [string, "null"]
        host:
          type: [string, "null"]
        publishedPort:
          type: [integer, "null"]
        targetPort:
          type: [integer, "null"]
        url:
          type: [string, "null"]
        isPublic:
          type: boolean
        confidence:
          $ref: "#/components/schemas/InventoryFactConfidence"
    InventoryNetworkRequest:
      type: object
      required: [sourceKey, name, internal, confidence]
      properties:
        sourceKey:
          type: string
        name:
          type: string
        driver:
          type: [string, "null"]
        scope:
          type: [string, "null"]
        internal:
          type: boolean
        confidence:
          $ref: "#/components/schemas/InventoryFactConfidence"
    InventoryVolumeRequest:
      type: object
      required: [sourceKey, name, readOnly, confidence]
      properties:
        sourceKey:
          type: string
        name:
          type: string
        mountPath:
          type: [string, "null"]
        storageClass:
          type: [string, "null"]
        readOnly:
          type: boolean
        sizeBytes:
          type: [integer, "null"]
          format: int64
        confidence:
          $ref: "#/components/schemas/InventoryFactConfidence"
    InventoryDatabaseRequest:
      type: object
      required: [sourceKey, name, hostPortPublished, confidence]
      properties:
        sourceKey:
          type: string
        name:
          type: string
        engine:
          type: [string, "null"]
        version:
          type: [string, "null"]
        host:
          type: [string, "null"]
        port:
          type: [integer, "null"]
        hostPortPublished:
          type: boolean
        confidence:
          $ref: "#/components/schemas/InventoryFactConfidence"
    InventoryDependencyRequest:
      type: object
      required: [sourceKey, dependsOnSourceKey, confidence]
      properties:
        sourceKey:
          type: string
        dependsOnSourceKey:
          type: string
        kind:
          type: [string, "null"]
        confidence:
          $ref: "#/components/schemas/InventoryFactConfidence"
    InventoryHealthRequest:
      type: object
      required: [sourceKey, state, confidence]
      properties:
        sourceKey:
          type: string
        state:
          type: string
          enum: [Healthy, Degraded, Unhealthy, Unknown]
        checkKind:
          type: [string, "null"]
        responseTimeMilliseconds:
          type: [integer, "null"]
        confidence:
          $ref: "#/components/schemas/InventoryFactConfidence"
    InventoryDeploymentRequest:
      type: object
      required: [sourceKey, confidence]
      properties:
        sourceKey:
          type: string
        repositoryUrl:
          type: [string, "null"]
        commit:
          type: [string, "null"]
        imageReference:
          type: [string, "null"]
        imageDigest:
          type: [string, "null"]
        deployedAt:
          type: [string, "null"]
          format: date-time
        confidence:
          $ref: "#/components/schemas/InventoryFactConfidence"
    InventoryBackupRequest:
      type: object
      required: [sourceKey, restoreTested, confidence]
      properties:
        sourceKey:
          type: string
        method:
          type: [string, "null"]
        schedule:
          type: [string, "null"]
        lastSuccessfulAt:
          type: [string, "null"]
          format: date-time
        restoreTested:
          type: boolean
        confidence:
          $ref: "#/components/schemas/InventoryFactConfidence"
    InventoryServiceRequest:
      type: object
      required: [sourceKey, detectedName, health, readOnlyRootFilesystem, noNewPrivileges, privileged, confidence]
      properties:
        sourceKey:
          type: string
        hostSourceKey:
          type: [string, "null"]
        detectedName:
          type: string
        runtimeKind:
          type: [string, "null"]
        runtimeStatus:
          type: [string, "null"]
        health:
          type: string
          enum: [Healthy, Degraded, Unhealthy, Unknown]
        imageReference:
          type: [string, "null"]
        imageDigest:
          type: [string, "null"]
        runtimeUser:
          type: [string, "null"]
        readOnlyRootFilesystem:
          type: boolean
        noNewPrivileges:
          type: boolean
        privileged:
          type: boolean
        confidence:
          $ref: "#/components/schemas/InventoryFactConfidence"
        components:
          type: [array, "null"]
          items:
            $ref: "#/components/schemas/InventoryComponentRequest"
        endpoints:
          type: [array, "null"]
          items:
            $ref: "#/components/schemas/InventoryEndpointRequest"
        networks:
          type: [array, "null"]
          items:
            $ref: "#/components/schemas/InventoryNetworkRequest"
        volumes:
          type: [array, "null"]
          items:
            $ref: "#/components/schemas/InventoryVolumeRequest"
        databases:
          type: [array, "null"]
          items:
            $ref: "#/components/schemas/InventoryDatabaseRequest"
        dependencies:
          type: [array, "null"]
          items:
            $ref: "#/components/schemas/InventoryDependencyRequest"
        healthObservations:
          type: [array, "null"]
          items:
            $ref: "#/components/schemas/InventoryHealthRequest"
        deployments:
          type: [array, "null"]
          items:
            $ref: "#/components/schemas/InventoryDeploymentRequest"
        backups:
          type: [array, "null"]
          items:
            $ref: "#/components/schemas/InventoryBackupRequest"
    SynchronizeInventoryRequest:
      type: object
      required: [sourceKey, sourceHash, capturedAt]
      properties:
        sourceKey:
          type: string
        sourceHash:
          type: string
        capturedAt:
          type: string
          format: date-time
        hosts:
          type: [array, "null"]
          items:
            $ref: "#/components/schemas/InventoryHostRequest"
        services:
          type: [array, "null"]
          items:
            $ref: "#/components/schemas/InventoryServiceRequest"
    InventorySyncResponse:
      type: object
      required: [snapshotId, alreadyImported, addedServices, updatedServices, missingServices, preservedEditorialProfiles, preservedOverrides]
      properties:
        snapshotId:
          type: string
          format: uuid
        alreadyImported:
          type: boolean
        addedServices:
          type: integer
        updatedServices:
          type: integer
        missingServices:
          type: integer
        preservedEditorialProfiles:
          type: integer
        preservedOverrides:
          type: integer
    CuratedServiceProfileRequest:
      type: object
      required: [sourceKey, reviewed, archived]
      properties:
        sourceKey:
          type: string
        displayName:
          type: [string, "null"]
        summary:
          type: [string, "null"]
        category:
          type: [string, "null"]
        purpose:
          type: [string, "null"]
        repositoryUrl:
          type: [string, "null"]
        liveUrl:
          type: [string, "null"]
        tags:
          type: [array, "null"]
          items:
            type: string
        reviewed:
          type: boolean
        archived:
          type: boolean
    ImportCuratedInventoryRequest:
      type: object
      required: [inventory]
      properties:
        inventory:
          $ref: "#/components/schemas/SynchronizeInventoryRequest"
        services:
          type: [array, "null"]
          items:
            $ref: "#/components/schemas/CuratedServiceProfileRequest"
    ImportCuratedInventoryResponse:
      type: object
      required: [inventory, createdEditorialProfiles, confirmedServices, archivedServices]
      properties:
        inventory:
          $ref: "#/components/schemas/InventorySyncResponse"
        createdEditorialProfiles:
          type: integer
        confirmedServices:
          type: integer
        archivedServices:
          type: integer
    ActivityItemResponse:
      type: object
      required: [id, actorKind, actorId, source, action, targetType, targetId, summary, occurredAt]
      properties:
        id:
          type: integer
          format: int64
        actorKind:
          type: string
          enum: [System, User, ServiceAccount]
        actorId:
          type: [string, "null"]
          format: uuid
        source:
          type: string
        action:
          type: string
        targetType:
          type: [string, "null"]
        targetId:
          type: [string, "null"]
        summary:
          type: string
        occurredAt:
          type: string
          format: date-time
    ActivityListResponse:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ActivityItemResponse"
    WorkspaceMemberSummary:
      type: object
      required: [id, displayName, email]
      properties:
        id:
          type: string
          format: uuid
        displayName:
          type: string
        email:
          type: string
    WorkspaceMemberListResponse:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceMemberSummary"
    PreviewMarkdownRequest:
      type: object
      required: [markdown]
      properties:
        markdown:
          type: string
    PreviewMarkdownResponse:
      type: object
      required: [renderedHtml]
      properties:
        renderedHtml:
          type: string
          description: Sanitized HTML — safe to render directly, matching the same pipeline a published page revision uses.
    StagingCleanupRunSummary:
      type: object
      required: [sessionsExpired, sessionsClaimed, sessionsLostRace, attachmentReferencesRemoved, blobsRemoved, warnings]
      properties:
        sessionsExpired:
          type: integer
        sessionsClaimed:
          type: integer
        sessionsLostRace:
          type: integer
          description: Expired sessions this run observed but a concurrent run claimed first — never lost, just processed elsewhere.
        attachmentReferencesRemoved:
          type: integer
        blobsRemoved:
          type: integer
        warnings:
          type: array
          items:
            type: string
    StagingCleanupStatusResponse:
      type: object
      required: [activeSessionCount, expiredPendingCleanupCount, runInProgress, lastRunStartedAt, lastRunCompletedAt, lastRunTrigger, lastResult]
      properties:
        activeSessionCount:
          type: integer
        expiredPendingCleanupCount:
          type: integer
        runInProgress:
          type: boolean
        lastRunStartedAt:
          type: [string, "null"]
          format: date-time
        lastRunCompletedAt:
          type: [string, "null"]
          format: date-time
        lastRunTrigger:
          type: [string, "null"]
          enum: [scheduled, manual, null]
        lastResult:
          type: [object, "null"]
          allOf:
            - $ref: "#/components/schemas/StagingCleanupRunSummary"
    RunStagingCleanupRequest:
      type: object
      required: [dryRun]
      properties:
        dryRun:
          type: boolean
    RunStagingCleanupResponse:
      type: object
      required: [dryRun, result]
      properties:
        dryRun:
          type: boolean
        result:
          $ref: "#/components/schemas/StagingCleanupRunSummary"
    PreflightImportRequest:
      type: object
      required: [sourceRelativePath, idempotencyKey]
      properties:
        sourceRelativePath:
          type: string
          description: Resolved beneath the operator-mounted KnowledgeHub:Paths:Imports directory — never an arbitrary filesystem path.
        idempotencyKey:
          type: string
    ImportPlanItemResponse:
      type: object
      required: [sourceIdentity, kind, proposedTitle, proposedParentSourceIdentity, conflict, conflictDetail]
      properties:
        sourceIdentity:
          type: string
        kind:
          type: string
          enum: [Markdown, SqliteRow, Asset, Unsupported]
        proposedTitle:
          type: string
        proposedParentSourceIdentity:
          type: [string, "null"]
        conflict:
          type: string
          enum: [NoConflict, ExactRerunDuplicate, SamePathDifferentContent, ExistingUserPage, AmbiguousLink, Unsupported]
        conflictDetail:
          type: [string, "null"]
    ImportPreflightResponse:
      type: object
      required: [status, jobId, adapterName, discoveredCount, plannedCount, items, warnings, blockers]
      properties:
        status:
          type: string
          enum: [Success, NoApplicableAdapter, AlreadyPreflighted]
        jobId:
          type: [string, "null"]
          format: uuid
        adapterName:
          type: [string, "null"]
        discoveredCount:
          type: integer
        plannedCount:
          type: integer
        items:
          type: array
          items:
            $ref: "#/components/schemas/ImportPlanItemResponse"
        warnings:
          type: array
          items:
            type: string
        blockers:
          type: array
          items:
            type: string
    ExecuteImportResponse:
      type: object
      required: [status, imported, skipped, failed, sourceUnchangedAfterExecution, diagnostics]
      properties:
        status:
          type: string
          enum: [Success, JobNotFound, NotPlanReady, SourceChanged, PlanChanged]
        imported:
          type: integer
        skipped:
          type: integer
        failed:
          type: integer
        sourceUnchangedAfterExecution:
          type: boolean
          description: A re-fingerprint comparison proving the source was never mutated during import (M4-A08).
        diagnostics:
          type: array
          items:
            type: string
    RollbackImportResponse:
      type: object
      required: [status, removedPages, preservedPages, removedAttachments]
      properties:
        status:
          type: string
          enum: [Success, JobNotFound, NothingToRollBack]
        removedPages:
          type: integer
        preservedPages:
          type: integer
          description: Pages this import created but a user has since edited — never deleted by rollback.
        removedAttachments:
          type: integer
    ImportJobSummaryResponse:
      type: object
      required: [id, adapterName, status, discoveredCount, plannedCount, importedCount, skippedCount, failedCount, createdAt, startedAt, completedAt]
      properties:
        id:
          type: string
          format: uuid
        adapterName:
          type: string
        status:
          type: string
          enum: [Discovered, PlanReady, Executing, Completed, Failed, RolledBack]
        discoveredCount:
          type: integer
        plannedCount:
          type: integer
        importedCount:
          type: integer
        skippedCount:
          type: integer
        failedCount:
          type: integer
        createdAt:
          type: string
          format: date-time
        startedAt:
          type: [string, "null"]
          format: date-time
        completedAt:
          type: [string, "null"]
          format: date-time
    SourceBatchPurgeRequest:
      type: object
      required: [batchId, source, pages]
      properties:
        batchId:
          type: string
          minLength: 1
        source:
          type: string
          pattern: "^[a-z0-9-]{1,64}$"
        pages:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/SourceBatchPurgePageEvidence"
    SourceBatchPurgePageEvidence:
      type: object
      required: [pageId, contentHash]
      properties:
        pageId:
          type: string
          format: uuid
        contentHash:
          type: string
          pattern: "^[a-fA-F0-9]{64}$"
    ExecuteSourceBatchPurgeRequest:
      allOf:
        - $ref: "#/components/schemas/SourceBatchPurgeRequest"
        - type: object
          required: [confirmationHash]
          properties:
            confirmationHash:
              type: string
              pattern: "^[a-f0-9]{64}$"
    SourceBatchPurgeDryRunResponse:
      type: object
      required: [safe, confirmationHash, pages, descendantPages, revisions, drafts, links, attachmentUsages, attachmentReferences, orphanedBlobs, sharedBlobs, importJobs, importItems, provenanceRecords, sourceTagAssignments, searchIndexRecords, generatedSourceDerivedPages, retainedPages, blockers]
      properties:
        safe:
          type: boolean
        confirmationHash:
          type: string
        pages:
          type: integer
        descendantPages:
          type: integer
        revisions:
          type: integer
        drafts:
          type: integer
        links:
          type: integer
        attachmentUsages:
          type: integer
        attachmentReferences:
          type: integer
        orphanedBlobs:
          type: integer
        sharedBlobs:
          type: integer
        importJobs:
          type: integer
        importItems:
          type: integer
        provenanceRecords:
          type: integer
        sourceTagAssignments:
          type: integer
        searchIndexRecords:
          type: integer
        generatedSourceDerivedPages:
          type: integer
        retainedPages:
          type: integer
        blockers:
          type: array
          items:
            type: string
    SourceBatchPurgeResponse:
      type: object
      required: [status, dryRun, removedPages, removedRevisions, removedDrafts, removedLinks, removedAttachmentUsages, removedAttachmentReferences, removedImportJobs, removedImportItems, removedProvenanceRecords, removedBlobs]
      properties:
        status:
          type: string
          enum: [purged]
        dryRun:
          $ref: "#/components/schemas/SourceBatchPurgeDryRunResponse"
        removedPages:
          type: integer
        removedRevisions:
          type: integer
        removedDrafts:
          type: integer
        removedLinks:
          type: integer
        removedAttachmentUsages:
          type: integer
        removedAttachmentReferences:
          type: integer
        removedImportJobs:
          type: integer
        removedImportItems:
          type: integer
        removedProvenanceRecords:
          type: integer
        removedBlobs:
          type: integer
    SearchResultItem:
      type: object
      required: [id, parentPageId, title, slug, documentType, documentStatus, tags, updatedAt, snippet]
      properties:
        id:
          type: string
          format: uuid
        parentPageId:
          type: [string, "null"]
          format: uuid
        title:
          type: string
        slug:
          type: string
        documentType:
          $ref: "#/components/schemas/DocumentType"
        documentStatus:
          $ref: "#/components/schemas/DocumentStatus"
        tags:
          type: array
          items:
            type: string
        updatedAt:
          type: string
          format: date-time
        snippet:
          type: string
          description: >-
            May contain the safe server-generated highlight markers `**` around
            matched terms. Never raw HTML — clients must escape this text before
            rendering and only then interpret the `**` markers.
    SearchResponse:
      type: object
      required: [items, nextCursor]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/SearchResultItem"
        nextCursor:
          type: [string, "null"]
    RagPublicationManifestItem:
      type: object
      description: >-
        docs/32-rag-publication-convention.md. `markdown` and `checksum` are always
        `null` when `retired` is `true`.
      required:
        - contentId
        - documentType
        - documentStatus
        - title
        - slug
        - canonicalUrl
        - markdown
        - revision
        - checksum
        - locale
        - space
        - updatedAt
        - publishedAt
        - retired
        - retiredReason
      properties:
        contentId:
          type: string
          format: uuid
        documentType:
          $ref: "#/components/schemas/DocumentType"
        documentStatus:
          $ref: "#/components/schemas/DocumentStatus"
        title:
          type: string
        slug:
          type: string
        canonicalUrl:
          type: string
        markdown:
          type: [string, "null"]
        revision:
          type: integer
          format: int64
        checksum:
          type: [string, "null"]
          description: Lowercase-hex SHA-256 of `markdown` (Page.ContentHash). Null when retired.
        locale:
          type: string
          description: >-
            The page's own `locale:` tag, or the configured
            `KnowledgeHub:PrimaryLocale` when it declares none. Never silently `en`.
        space:
          type: [string, "null"]
          description: The page's own `rag:space:` tag suffix, if any.
        updatedAt:
          type: string
          format: date-time
        publishedAt:
          type: [string, "null"]
          format: date-time
        retired:
          type: boolean
        retiredReason:
          type: [string, "null"]
          enum: [null, trashed, draft, needs-review, deprecated, archived]
    RagPublicationManifestResponse:
      type: object
      required: [items, nextCursor]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/RagPublicationManifestItem"
        nextCursor:
          type: [string, "null"]
    ProjectStatus:
      type: string
      description: docs/15-project-hub.md lifecycle diagram. Archived is terminal in v1 (ADR-014 decision 6).
      enum: [Concept, Planned, Active, Blocked, Maintenance, Paused, Completed, Archived]
    ProjectPriority:
      type: string
      enum: [Low, Medium, High, Critical]
    ProjectDocumentRole:
      type: string
      enum:
        - Overview
        - CurrentState
        - Architecture
        - Deployment
        - Infrastructure
        - Security
        - Testing
        - Troubleshooting
        - Release
        - UserDocumentation
        - Other
    ProjectUpdateCategory:
      type: string
      enum: [Progress, Feature, Fix, Deployment, Validation, Release, Decision, Risk, Blocker, Documentation, Maintenance]
    ProjectUpdateVerificationStatus:
      type: string
      description: The UI must distinguish reported claims from validated evidence (docs/15-project-hub.md).
      enum: [Reported, Verified, Superseded]
    ProjectMilestoneState:
      type: string
      enum: [Planned, InProgress, Completed, Cancelled]
    DecisionStatus:
      type: string
      enum: [Proposed, Accepted, Rejected, Superseded, Withdrawn]
    RunbookRiskLevel:
      type: string
      enum: [Low, Medium, High, Critical]
    RunbookStatus:
      type: string
      enum: [Draft, Active, Deprecated]
    ProjectSummary:
      type: object
      required: [id, name, slug, summary, status, priority, ownerId, repositoryUrl, liveUrl, updatedAt, iconAttachmentId]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        slug: { type: string }
        summary: { type: string }
        status: { $ref: "#/components/schemas/ProjectStatus" }
        priority: { $ref: "#/components/schemas/ProjectPriority" }
        ownerId: { type: string, format: uuid }
        repositoryUrl: { type: [string, "null"], format: uri }
        liveUrl: { type: [string, "null"], format: uri }
        updatedAt: { type: string, format: date-time }
        iconAttachmentId: { type: [string, "null"], format: uuid, description: "Same-origin attachment content is served at /api/v1/attachments/{iconAttachmentId}/content." }
    ProjectListResponse:
      type: object
      required: [items, nextCursor, totalCount]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ProjectSummary"
        nextCursor:
          type: [string, "null"]
        totalCount:
          type: integer
          minimum: 0
          description: >-
            How many projects match the current filters in total (OUX-4), counted
            server-side before cursor pagination. Not a substitute for
            `/projects/totals`, which answers the unfiltered dashboard question.
    ProjectCatalogTotalsResponse:
      type: object
      required: [totalCount, activeCount]
      properties:
        totalCount: { type: integer, minimum: 0 }
        activeCount: { type: integer, minimum: 0 }
    ProjectDocumentSummary:
      type: object
      required: [id, pageId, pageTitle, pageSlug, pageDocumentType, role]
      properties:
        id: { type: string, format: uuid }
        pageId: { type: string, format: uuid }
        pageTitle: { type: string }
        pageSlug: { type: string }
        pageDocumentType: { $ref: "#/components/schemas/DocumentType" }
        role: { $ref: "#/components/schemas/ProjectDocumentRole" }
    ProjectUpdateSummary:
      type: object
      required: [id, category, title, summaryMarkdown, verificationStatus, actorId, occurredAt]
      properties:
        id: { type: string, format: uuid }
        category: { $ref: "#/components/schemas/ProjectUpdateCategory" }
        title: { type: string }
        summaryMarkdown: { type: string }
        verificationStatus: { $ref: "#/components/schemas/ProjectUpdateVerificationStatus" }
        actorId: { type: string, format: uuid }
        occurredAt: { type: string, format: date-time }
        commitSha: { type: [string, "null"] }
        releaseTag: { type: [string, "null"] }
        issueIdentifier: { type: [string, "null"] }
        url: { type: [string, "null"] }
        pageId: { type: [string, "null"], format: uuid }
        decisionRecordId: { type: [string, "null"], format: uuid }
        milestoneId: { type: [string, "null"], format: uuid }
        attachmentReferenceId: { type: [string, "null"], format: uuid }
        supersedesUpdateId: { type: [string, "null"], format: uuid }
    ProjectUpdatesResponse:
      type: object
      required: [items, nextCursor]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ProjectUpdateSummary"
        nextCursor:
          type: [string, "null"]
    ProjectMilestoneSummary:
      type: object
      required: [id, name, state, summary, successCriteria, eTag]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        state: { $ref: "#/components/schemas/ProjectMilestoneState" }
        targetDate: { type: [string, "null"], format: date }
        completionDate: { type: [string, "null"], format: date }
        summary: { type: string }
        successCriteria: { type: string }
        eTag:
          type: string
          description: Also present as the response ETag header.
    ProjectDecisionSummary:
      type: object
      required: [id, decisionNumber, status, summary]
      properties:
        id: { type: string, format: uuid }
        decisionNumber: { type: integer }
        status: { $ref: "#/components/schemas/DecisionStatus" }
        summary: { type: string }
    ProjectDetail:
      type: object
      required:
        - id
        - name
        - slug
        - summary
        - status
        - priority
        - currentStateMarkdown
        - ownerId
        - technologies
        - documents
        - recentUpdates
        - milestones
        - decisions
        - createdAt
        - updatedAt
        - eTag
        - iconAttachmentId
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        slug: { type: string }
        summary: { type: string }
        status: { $ref: "#/components/schemas/ProjectStatus" }
        priority: { $ref: "#/components/schemas/ProjectPriority" }
        currentStateMarkdown: { type: string }
        ownerId: { type: string, format: uuid }
        startDate: { type: [string, "null"], format: date }
        targetDate: { type: [string, "null"], format: date }
        completionDate: { type: [string, "null"], format: date }
        repositoryUrl: { type: [string, "null"] }
        liveUrl: { type: [string, "null"] }
        documentationUrl: { type: [string, "null"] }
        issueTrackerUrl: { type: [string, "null"] }
        technologies:
          type: array
          items: { type: string }
        documents:
          type: array
          items:
            $ref: "#/components/schemas/ProjectDocumentSummary"
        recentUpdates:
          type: array
          items:
            $ref: "#/components/schemas/ProjectUpdateSummary"
        milestones:
          type: array
          items:
            $ref: "#/components/schemas/ProjectMilestoneSummary"
        decisions:
          type: array
          items:
            $ref: "#/components/schemas/ProjectDecisionSummary"
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        eTag:
          type: string
          description: Also present as the response ETag header; included in the body so clients need not parse headers.
        iconAttachmentId: { type: [string, "null"], format: uuid }
    ProjectIconResponse:
      type: object
      required: [iconAttachmentId, eTag]
      properties:
        iconAttachmentId: { type: string, format: uuid }
        eTag: { type: string, description: Current project ETag after the icon change. }
    CreateProjectRequest:
      type: object
      required: [name, summary, priority, currentStateMarkdown, ownerId]
      properties:
        name: { type: string, minLength: 1, maxLength: 200 }
        summary: { type: string }
        priority: { $ref: "#/components/schemas/ProjectPriority" }
        currentStateMarkdown: { type: string }
        ownerId: { type: string, format: uuid }
    UpdateProjectRequest:
      type: object
      required: [name, summary, priority, currentStateMarkdown, ownerId]
      properties:
        name: { type: string, minLength: 1, maxLength: 200 }
        summary: { type: string }
        priority: { $ref: "#/components/schemas/ProjectPriority" }
        currentStateMarkdown: { type: string }
        ownerId: { type: string, format: uuid }
        startDate: { type: [string, "null"], format: date }
        targetDate: { type: [string, "null"], format: date }
        completionDate: { type: [string, "null"], format: date }
        repositoryUrl: { type: [string, "null"] }
        liveUrl: { type: [string, "null"] }
        documentationUrl: { type: [string, "null"] }
        issueTrackerUrl: { type: [string, "null"] }
        technologies:
          type: [array, "null"]
          items: { type: string }
    LinkProjectDocumentRequest:
      type: object
      required: [pageId, role]
      properties:
        pageId: { type: string, format: uuid }
        role: { $ref: "#/components/schemas/ProjectDocumentRole" }
    CreateProjectUpdateRequest:
      type: object
      required: [category, title, summaryMarkdown, verificationStatus]
      properties:
        category: { $ref: "#/components/schemas/ProjectUpdateCategory" }
        title: { type: string, maxLength: 200 }
        summaryMarkdown: { type: string }
        verificationStatus: { $ref: "#/components/schemas/ProjectUpdateVerificationStatus" }
        occurredAt: { type: [string, "null"], format: date-time }
        commitSha: { type: [string, "null"] }
        releaseTag: { type: [string, "null"] }
        issueIdentifier: { type: [string, "null"] }
        url: { type: [string, "null"] }
        pageId: { type: [string, "null"], format: uuid }
        decisionRecordId: { type: [string, "null"], format: uuid }
        milestoneId: { type: [string, "null"], format: uuid }
        attachmentReferenceId: { type: [string, "null"], format: uuid }
        supersedesUpdateId: { type: [string, "null"], format: uuid }
    CreateProjectMilestoneRequest:
      type: object
      required: [name, summary, successCriteria]
      properties:
        name: { type: string, minLength: 1 }
        targetDate: { type: [string, "null"], format: date }
        summary: { type: string }
        successCriteria: { type: string }
    UpdateProjectMilestoneRequest:
      type: object
      required: [name, summary, successCriteria, state]
      properties:
        name: { type: string, minLength: 1 }
        targetDate: { type: [string, "null"], format: date }
        summary: { type: string }
        successCriteria: { type: string }
        state: { $ref: "#/components/schemas/ProjectMilestoneState" }
    DecisionLineageEntry:
      type: object
      required: [id, decisionNumber, status, summary]
      properties:
        id: { type: string, format: uuid }
        decisionNumber: { type: integer }
        status: { $ref: "#/components/schemas/DecisionStatus" }
        summary: { type: string }
    DecisionDetail:
      type: object
      required:
        - id
        - workspaceId
        - pageId
        - decisionNumber
        - status
        - decisionDate
        - title
        - markdown
        - renderedHtml
        - summary
        - createdAt
        - updatedAt
        - eTag
      properties:
        id: { type: string, format: uuid }
        workspaceId: { type: string, format: uuid }
        projectId: { type: [string, "null"], format: uuid }
        pageId: { type: string, format: uuid }
        decisionNumber: { type: integer }
        status: { $ref: "#/components/schemas/DecisionStatus" }
        decisionDate: { type: string, format: date }
        title: { type: string }
        markdown: { type: string }
        renderedHtml:
          type: string
          description: Server-sanitized HTML — the same rendering pipeline as an ordinary Page.
        summary: { type: string }
        supersedes:
          oneOf:
            - $ref: "#/components/schemas/DecisionLineageEntry"
            - type: "null"
        supersededBy:
          oneOf:
            - $ref: "#/components/schemas/DecisionLineageEntry"
            - type: "null"
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        eTag: { type: string }
    DecisionSummary:
      type: object
      required: [id, decisionNumber, status, title, decisionDate, summary, updatedAt]
      properties:
        id: { type: string, format: uuid }
        projectId: { type: [string, "null"], format: uuid }
        decisionNumber: { type: integer }
        status: { $ref: "#/components/schemas/DecisionStatus" }
        title: { type: string }
        decisionDate: { type: string, format: date }
        summary: { type: string }
        updatedAt: { type: string, format: date-time }
    DecisionListResponse:
      type: object
      required: [items, nextCursor]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/DecisionSummary"
        nextCursor:
          type: [string, "null"]
    CreateDecisionRequest:
      type: object
      required: [title, summary]
      properties:
        parentPageId: { type: [string, "null"], format: uuid }
        projectId: { type: [string, "null"], format: uuid }
        title: { type: string, minLength: 1 }
        markdown: { type: [string, "null"] }
        summary: { type: string }
        supersedesDecisionId: { type: [string, "null"], format: uuid }
    RunbookDetail:
      type: object
      required:
        - id
        - pageId
        - owner
        - riskLevel
        - status
        - requiresMaintenanceWindow
        - isStale
        - title
        - markdown
        - renderedHtml
        - currentRevisionNumber
        - createdAt
        - updatedAt
        - eTag
      properties:
        id: { type: string, format: uuid }
        pageId: { type: string, format: uuid }
        owner: { type: string, format: uuid }
        riskLevel: { $ref: "#/components/schemas/RunbookRiskLevel" }
        status: { $ref: "#/components/schemas/RunbookStatus" }
        requiresMaintenanceWindow: { type: boolean }
        estimatedDurationMinutes: { type: [integer, "null"] }
        reviewDueAt: { type: [string, "null"], format: date-time }
        lastValidatedAt: { type: [string, "null"], format: date-time }
        validatedBy: { type: [string, "null"], format: uuid }
        isStale:
          type: boolean
          description: True whenever the linked page has a newer revision than the last validation, or was never validated.
        title: { type: string }
        markdown: { type: string }
        renderedHtml:
          type: string
          description: Server-sanitized HTML — the same rendering pipeline as an ordinary Page. Never executed.
        currentRevisionNumber: { type: integer, format: int64 }
        createdAt: { type: string, format: date-time }
        updatedAt: { type: string, format: date-time }
        eTag: { type: string }
    RunbookSummary:
      type: object
      required: [id, pageId, title, riskLevel, status, isStale, updatedAt]
      properties:
        id: { type: string, format: uuid }
        pageId: { type: string, format: uuid }
        title: { type: string }
        riskLevel: { $ref: "#/components/schemas/RunbookRiskLevel" }
        status: { $ref: "#/components/schemas/RunbookStatus" }
        isStale: { type: boolean }
        lastValidatedAt: { type: [string, "null"], format: date-time }
        updatedAt: { type: string, format: date-time }
    RunbookListResponse:
      type: object
      required: [items, nextCursor]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/RunbookSummary"
        nextCursor:
          type: [string, "null"]
    CreateRunbookRequest:
      type: object
      required: [title, riskLevel]
      properties:
        parentPageId: { type: [string, "null"], format: uuid }
        title: { type: string, minLength: 1 }
        markdown: { type: [string, "null"] }
        templateKey: { type: [string, "null"] }
        riskLevel: { $ref: "#/components/schemas/RunbookRiskLevel" }
        requiresMaintenanceWindow: { type: boolean }
        estimatedDurationMinutes: { type: [integer, "null"] }
    UpdateRunbookProfileRequest:
      type: object
      required: [owner, riskLevel, status, requiresMaintenanceWindow]
      properties:
        owner: { type: string, format: uuid }
        riskLevel: { $ref: "#/components/schemas/RunbookRiskLevel" }
        status: { $ref: "#/components/schemas/RunbookStatus" }
        requiresMaintenanceWindow: { type: boolean }
        estimatedDurationMinutes: { type: [integer, "null"] }
        reviewDueAt: { type: [string, "null"], format: date-time }
    CreateServiceAccountRequest:
      type: object
      required: [name, description, scopes]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
        description:
          type: string
          maxLength: 1000
        scopes:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            description: "One of the known scope constants, e.g. pages:read, pages:write, projects:read, runbooks:write (see docs/09-api-contract.md)."
    IssueServiceAccountTokenRequest:
      type: object
      required: [scopes]
      properties:
        scopes:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
    CreatedServiceAccountToken:
      type: object
      description: The raw token is only ever present in this one response — it is never persisted in the clear and is not retrievable again.
      required: [serviceAccountId, tokenId, rawToken]
      properties:
        serviceAccountId:
          type: string
          format: uuid
        tokenId:
          type: string
          format: uuid
        rawToken:
          type: string
          description: "Format ikh_<publicId>_<secret>. Present exactly once."
    ServiceAccountTokenSummary:
      type: object
      required: [id, publicId, scopes, createdAt]
      properties:
        id:
          type: string
          format: uuid
        publicId:
          type: string
          description: Safe, non-secret identifier — never the raw secret.
        scopes:
          type: array
          items:
            type: string
        createdAt:
          type: string
          format: date-time
        lastUsedAt:
          type: [string, "null"]
          format: date-time
        expiresAt:
          type: [string, "null"]
          format: date-time
        revokedAt:
          type: [string, "null"]
          format: date-time
    ServiceAccountSummary:
      type: object
      required: [id, name, description, enabled, createdAt, tokens]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        enabled:
          type: boolean
        createdAt:
          type: string
          format: date-time
        tokens:
          type: array
          items:
            $ref: "#/components/schemas/ServiceAccountTokenSummary"
    ServiceAccountListResponse:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ServiceAccountSummary"
    CitationResponse:
      type: object
      description: A stable, citable pointer to a document or decision included in a project context bundle.
      required: [kind, id, title, canonicalPath, updatedAt]
      properties:
        kind:
          type: string
          enum: [Page, DecisionRecord, RunbookProfile]
        id:
          type: string
          format: uuid
        revision:
          type: [integer, "null"]
          format: int64
        title:
          type: string
        canonicalPath:
          type: string
        updatedAt:
          type: string
          format: date-time
    ProjectContextProjectSummary:
      type: object
      required: [id, name, status, summary, currentStateMarkdown, updatedAt]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          type: string
        summary:
          type: string
        currentStateMarkdown:
          type: string
        updatedAt:
          type: string
          format: date-time
    ProjectContextTruncation:
      type: object
      required: [truncated, omittedCounts]
      properties:
        truncated:
          type: boolean
        omittedCounts:
          type: object
          additionalProperties:
            type: integer
          description: "Counts of items omitted per collection (e.g. updates, decisions), keyed by collection name."
    ProjectContextResponse:
      type: object
      description: "A bounded, permission-filtered bundle of the current project state, suitable for a single-call context fetch (docs/09-api-contract.md 'Project context', M6-A04). Unlike the unbounded project overview, this response always reports what was truncated rather than growing unbounded."
      required: [project, recentUpdates, activeMilestones, decisions, runbooks, documents, citations, truncation]
      properties:
        project:
          $ref: "#/components/schemas/ProjectContextProjectSummary"
        recentUpdates:
          type: array
          items:
            $ref: "#/components/schemas/ProjectUpdateSummary"
        activeMilestones:
          type: array
          items:
            $ref: "#/components/schemas/ProjectMilestoneSummary"
        decisions:
          type: array
          items:
            $ref: "#/components/schemas/ProjectDecisionSummary"
        runbooks:
          type: array
          items:
            $ref: "#/components/schemas/ProjectDocumentSummary"
        documents:
          type: array
          items:
            $ref: "#/components/schemas/ProjectDocumentSummary"
        citations:
          type: array
          items:
            $ref: "#/components/schemas/CitationResponse"
        truncation:
          $ref: "#/components/schemas/ProjectContextTruncation"
    BackupSummaryResponse:
      type: object
      description: Never includes a filesystem path, connection string or other private detail.
      required: [backupId, createdAt, totalSizeBytes, tableCount, totalRowCount, attachmentCount, schemaVersion, productVersion]
      properties:
        backupId:
          type: string
        createdAt:
          type: string
          format: date-time
        totalSizeBytes:
          type: integer
          format: int64
        tableCount:
          type: integer
        totalRowCount:
          type: integer
          format: int64
        attachmentCount:
          type: integer
        schemaVersion:
          type: string
        productVersion:
          type: string
    BackupListResponse:
      type: object
      required: [items]
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/BackupSummaryResponse"
    ProblemDetails:
      type: object
      required: [type, title, status, correlationId]
      properties:
        type:
          type: string
          format: uri-reference
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        instance:
          type: string
          format: uri-reference
        correlationId:
          type: string
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
    SetupStatus:
      type: object
      required: [setupRequired]
      properties:
        setupRequired:
          type: boolean
    CompleteSetupRequest:
      type: object
      required: [workspaceName, displayName, email, password]
      properties:
        workspaceName:
          type: string
          minLength: 1
          maxLength: 200
        displayName:
          type: string
          minLength: 1
          maxLength: 200
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 12
    CompleteSetupResponse:
      type: object
      required: [workspaceId, userId]
      properties:
        workspaceId:
          type: string
          format: uuid
        userId:
          type: string
          format: uuid
    CsrfToken:
      type: object
      required: [token, headerName]
      properties:
        token:
          type: string
        headerName:
          type: string
    WorkspaceRole:
      type: string
      enum: [Reader, Editor, Administrator]
    SessionResponse:
      type: object
      required: [authenticated, setupRequired]
      properties:
        authenticated:
          type: boolean
        setupRequired:
          type: boolean
        userId:
          type: [string, "null"]
          format: uuid
        displayName:
          type: [string, "null"]
        email:
          type: [string, "null"]
        workspaceId:
          type: [string, "null"]
          format: uuid
        role:
          oneOf:
            - $ref: "#/components/schemas/WorkspaceRole"
            - type: "null"
    LoginRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
        password:
          type: string
    RecoveryRedeemRequest:
      type: object
      required: [token, newPassword]
      properties:
        token:
          type: string
        newPassword:
          type: string
          minLength: 12
    UserSummary:
      type: object
      required: [id, displayName, email, role, enabled, createdAt]
      properties:
        id:
          type: string
          format: uuid
        displayName:
          type: string
        email:
          type: string
        role:
          $ref: "#/components/schemas/WorkspaceRole"
        enabled:
          type: boolean
        createdAt:
          type: string
          format: date-time
        lastLoginAt:
          type: [string, "null"]
          format: date-time
    CreateUserRequest:
      type: object
      required: [displayName, email, password, role]
      properties:
        displayName:
          type: string
          minLength: 1
          maxLength: 200
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 12
        role:
          $ref: "#/components/schemas/WorkspaceRole"
    UpdateUserRequest:
      type: object
      properties:
        role:
          oneOf:
            - $ref: "#/components/schemas/WorkspaceRole"
            - type: "null"
        enabled:
          type: [boolean, "null"]
    IssueRecoveryTokenResponse:
      type: object
      required: [token, expiresAt]
      properties:
        token:
          type: string
          description: Shown once, at issuance. Never retrievable again.
        expiresAt:
          type: string
          format: date-time