openapi.yaml

openapi: 3.0.3
info:
  title: cix-server API
  version: v1
  description: |
    HTTP API for the `cix-server` semantic code-index daemon.

    The wire format is byte-stable across server versions; the `api_version`
    field in `/api/v1/status` ticks independently from `server_version` when
    a backwards-incompatible change lands.

    ## Authentication

    Two parallel auth paths back the same identity model:

    - **Browsers / dashboard**: `POST /api/v1/auth/login` with email +
      password issues an HttpOnly cookie `cix_session`. The cookie is sent
      automatically on subsequent same-origin requests. Sessions roll
      forward 14 days from the last request.
    - **CLI / SDK**: `Authorization: Bearer <api_key>` where the key was
      issued by `POST /api/v1/api-keys`. Keys are owner-scoped and can be
      revoked individually without affecting other clients.

    Public endpoints (no auth required): `GET /health`, `GET /docs`,
    `GET /openapi.yaml`, `GET /api/v1/auth/bootstrap-status`,
    `POST /api/v1/auth/login`. Setting `CIX_AUTH_DISABLED=true` skips the
    check on every endpoint (development only — a warning is logged).

    When the server starts with an empty users table it requires
    `CIX_BOOTSTRAP_ADMIN_EMAIL` + `CIX_BOOTSTRAP_ADMIN_PASSWORD` to seed
    the first admin (forced to change password on first login). A legacy
    `CIX_API_KEY` set on a fresh database is imported as a single
    `env-bootstrap` API key owned by that admin.

    ## Project addressing

    Project `host_path` values contain slashes that cannot be embedded in
    URL segments cleanly, so project-scoped endpoints take a `{path}` URL
    parameter that is the **first 16 hex chars of `SHA1(host_path)`**.
    Compute it with `internal/projects.HashPath`.

    ## Streaming indexing

    `POST /api/v1/projects/{path}/index/files` honours the `Accept` header:
    sending `Accept: application/x-ndjson` switches the response to a
    newline-delimited stream of `IndexProgressEvent` objects, with a
    `heartbeat` event every 10 seconds. Old clients that send no Accept
    header (or `application/json`) get the legacy single-JSON response.

    ## Errors

    All error responses use the same body shape: `{"detail": "<message>"}`.
    `GET /health` is the only exception — the unhealthy variant additionally
    carries `{"reason": "..."}`.

servers:
  # Relative URL — Swagger UI's "Try it out" sends requests to whatever
  # origin served /openapi.json, so localhost:8001, localhost:21847, and a
  # remote deployment all just work without CORS preflight surprises.
  - url: /
    description: Same-origin (auto-detected from the URL serving this spec)

security:
  - bearerAuth: []

tags:
  - name: probe
    description: Health and status probes
  - name: projects
    description: Project lifecycle (CRUD)
  - name: search
    description: Symbol, definition, reference, file, and semantic search
  - name: indexing
    description: Three-phase indexing protocol
  - name: search-stats
    description: |
      Per-project search counters: how often each project is searched and
      which of its files keep coming back in the results. Counters only —
      no query text and no per-request log is kept anywhere.

      Two tiers are served from the same endpoints. `window=all` reads
      cumulative totals that are never pruned; the other windows read a
      rolling 7-day series bucketed at 30 minutes. The numbers live in
      their own SQLite file so that recording them can never contend with
      indexing or with a database compaction — search has to keep serving
      through both.
  - name: docs
    description: API documentation
  - name: auth
    description: Sessions, login/logout, password change, current user
  - name: admin
    description: Admin-only user management
  - name: api-keys
    description: Issue and revoke owner-scoped API keys for CLI/SDK use
  - name: workspaces
    description: |
      Workspaces group GitHub repositories for cross-project semantic search.
      Server-wide shared — every authenticated user can list, create, and
      modify any workspace. PR1 ships CRUD only; repository attachment,
      webhooks, and the two-stage search endpoint land in subsequent
      releases of the workspaces feature branch.
  - name: groups
    description: |
      View-groups: admin-managed sets of users. External projects and
      workspaces are shared to a group, granting its members read/search
      access. Group CRUD and membership are admin-only; GET /groups is
      member-scoped for regular users so the share picker can populate.
  - name: github-tokens
    description: |
      GitHub Personal Access Tokens used by the workspaces feature for
      cloning private repos and (optionally) registering webhooks. Stored
      encrypted-at-rest via AES-GCM; the plaintext is surfaced exactly
      once on POST and never returned thereafter.
  - name: tunnels
    description: |
      Managed Tunnels — a server-orchestrated outbound tunnel that gives
      the server a public URL while it sits behind NAT. Cloudflare Tunnel
      ships now; ngrok is reserved. The live tunnel URL is the preferred
      origin for GitHub webhook delivery URLs.

paths:
  /health:
    get:
      operationId: getHealth
      tags: [probe]
      summary: Liveness probe (public)
      description: |
        Returns `{"status":"ok"}` when the server can reach SQLite within 1
        second. Returns 503 with `{"status":"unhealthy","reason":"..."}` when
        the DB ping fails. Public — no `Authorization` header required.
      security: []
      responses:
        "200":
          description: Server is healthy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
        "503":
          description: Server is unhealthy (e.g. DB unreachable)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"

  /api/v1/status:
    get:
      operationId: getStatus
      tags: [probe]
      summary: Server / sidecar status (authenticated)
      description: |
        Returns server metadata: version, configured embedding model, whether
        the llama-server sidecar is reachable (`model_loaded`), number of
        registered projects, and number of currently-running indexing jobs.
      responses:
        "200":
          description: Status payload
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/auth/bootstrap-status:
    get:
      operationId: getBootstrapStatus
      tags: [auth]
      summary: Whether the dashboard needs first-run bootstrap (public)
      description: |
        Returns `{"needs_bootstrap": true}` when the users table is empty.
        The dashboard renders an explanatory screen in that case ("ask the
        operator to deploy with CIX_BOOTSTRAP_ADMIN_* env vars and
        restart"). No authentication required.
      security: []
      responses:
        "200":
          description: Bootstrap status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BootstrapStatusResponse"

  /api/v1/auth/login:
    post:
      operationId: login
      tags: [auth]
      summary: Exchange email + password for a session cookie (public)
      description: |
        On success, sets `Set-Cookie: cix_session=<id>; HttpOnly;
        SameSite=Strict; Path=/`. Returns the user payload plus a
        `must_change_password` flag — when true, the dashboard forces a
        change-password screen before any other action.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
      responses:
        "200":
          description: Logged in
          headers:
            Set-Cookie:
              schema:
                type: string
              description: Session cookie (HttpOnly, SameSite=Strict)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/Unprocessable"

  /api/v1/auth/logout:
    post:
      operationId: logout
      tags: [auth]
      summary: End the current session
      description: |
        Deletes the server-side session row and instructs the browser to
        clear `cix_session` via `Set-Cookie: cix_session=; Max-Age=0`.
      responses:
        "204":
          description: Session ended
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/auth/me:
    get:
      operationId: getMe
      tags: [auth]
      summary: Current authenticated user
      description: |
        Returns the user attached to the active session OR API key.
        Includes `must_change_password` so the dashboard knows whether to
        gate further navigation behind a change-password screen.
      responses:
        "200":
          description: Current user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MeResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/auth/change-password:
    post:
      operationId: changePassword
      tags: [auth]
      summary: Change the current user's password
      description: |
        Verifies `current_password`, updates to `new_password`, clears
        `must_change_password`, and revokes every other session of this
        user (the cookie carrying the change-password request is kept
        alive). Does NOT touch API keys — those are revoked individually.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChangePasswordRequest"
      responses:
        "204":
          description: Password updated
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/Unprocessable"

  /api/v1/auth/sessions:
    get:
      operationId: listMySessions
      tags: [auth]
      summary: Active sessions of the current user
      description: |
        Returns every non-expired session of the caller, newest-first, with
        `last_seen_at`, `last_seen_ip`, and `last_seen_ua` so the user can
        spot unfamiliar logins. The `is_current` flag marks the session
        carrying this request.
      responses:
        "200":
          description: Session list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/auth/sessions/{id}:
    delete:
      operationId: deleteMySession
      tags: [auth]
      summary: End one of my sessions (sign out a single device)
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Session ended
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/admin/users:
    get:
      operationId: listUsers
      tags: [admin]
      summary: List all users (admin only)
      responses:
        "200":
          description: User list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      operationId: createUser
      tags: [admin]
      summary: Invite a new user (admin only)
      description: |
        The admin sets an `initial_password` and shares it out-of-band.
        The new user is flagged `must_change_password=true` and will be
        forced to change it on first login.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Unprocessable"

  /api/v1/admin/users/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    patch:
      operationId: updateUser
      tags: [admin]
      summary: Change role or disabled flag (admin only)
      description: |
        Refuses to demote or disable the last enabled admin in the system.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserRequest"
      responses:
        "200":
          description: Updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"
    delete:
      operationId: deleteUser
      tags: [admin]
      summary: Delete a user (admin only)
      description: |
        Cascades to the user's sessions and API keys. Refuses to delete
        the last enabled admin.
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/admin/users/{id}/reset-password:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: resetUserPassword
      tags: [admin]
      summary: Reset a user's password (admin only)
      description: |
        Sets a new admin-chosen temporary password and forces the user to
        change it on next login (must_change_password=true), mirroring the
        invite flow. Any admin may reset any user, including another admin.
        The target user's existing sessions are revoked.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResetUserPasswordRequest"
      responses:
        "200":
          description: Password reset
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"

  /api/v1/admin/login-locks:
    get:
      operationId: listLoginLocks
      tags: [admin]
      summary: List active login rate-limit locks (admin only)
      description: |
        Returns the in-memory login-limiter counters that are currently at or
        over their threshold — the IPs and (IP, email) pairs a login would be
        rejected for right now with 429. State is per-process and self-heals as
        the sliding windows expire, so this is a point-in-time snapshot.
      responses:
        "200":
          description: Active locks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginLockListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/admin/login-locks/reset:
    post:
      operationId: resetLoginLock
      tags: [admin]
      summary: Clear a login rate-limit lock (admin only)
      description: |
        Lifts a single lock surfaced by `GET /admin/login-locks`. `type` picks
        the counter: `ip` clears the per-IP horizontal-sweep counter; `ip_email`
        clears the per-(IP, email) counter for one account. The admin selects
        the exact row to clear — the server never clears across keys.
        Idempotent: clearing a key that is no longer locked returns 204.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResetLoginLockRequest"
      responses:
        "204":
          description: Lock cleared (or already absent)
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/Unprocessable"

  /api/v1/admin/runtime-config:
    get:
      operationId: getRuntimeConfig
      tags: [admin]
      summary: Read effective runtime config (admin only)
      description: |
        Returns the resolved runtime config (DB row → env → recommended) the
        sidecar is currently configured against, plus a `source` map labelling
        each field's origin so the dashboard can render the "DB" / "Env" /
        "Recommended" pill next to every value.
      responses:
        "200":
          description: Effective runtime config
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeConfig"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    put:
      operationId: putRuntimeConfig
      tags: [admin]
      summary: Save runtime config overrides (admin only)
      description: |
        Replaces the runtime_settings row. Fields omitted from the request
        clear their override (= fall back to env / recommended on next Get).
        Does NOT restart the sidecar — the dashboard issues a separate
        POST /admin/sidecar/restart after a successful PUT.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RuntimeConfigUpdate"
      responses:
        "200":
          description: Updated config
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeConfig"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/Unprocessable"

  /api/v1/admin/sidecar/restart:
    post:
      operationId: restartSidecar
      tags: [admin]
      summary: Restart the llama-server sidecar (admin only)
      description: |
        Drains the embedding queue (30s timeout), terminates the current
        child process, and respawns with the latest runtime config.
        Returns 202 immediately; poll GET /admin/sidecar/status to observe
        the running → restarting → running transition. In-flight indexing
        batches at the moment of restart will fail with ErrSupervisor and
        must be re-driven by the operator (`cix reindex <project>`).
      responses:
        "202":
          description: Restart accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestartAccepted"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "503":
          description: Embeddings disabled at boot — restart is a no-op
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/admin/sidecar/status:
    get:
      operationId: getSidecarStatus
      tags: [admin]
      summary: Sidecar process status (admin only)
      responses:
        "200":
          description: Status snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SidecarStatus"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/admin/models:
    get:
      operationId: listModels
      tags: [admin]
      summary: List GGUF model files cached on disk (admin only)
      description: |
        Walks `CIX_GGUF_CACHE_DIR` and returns one entry per .gguf file. Used
        by the dashboard's embedding-model picker so admins don't have to
        type HF repo IDs by hand. Empty list when the cache is empty —
        dashboard falls back to a free-text path input in that case.
      responses:
        "200":
          description: Cached model list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/admin/resources:
    get:
      operationId: getResourceUsage
      tags: [admin]
      summary: Report memory and disk usage (admin only)
      description: |
        What the server is using right now: Go heap figures, resident set size
        where the platform exposes it cheaply, the four storage locations with
        their sizes and free space, and the resident vector-store totals.

        The vector store is an in-memory database — every document of every
        collection is decoded into the heap at startup and never evicted — so
        `memory.heap_alloc_bytes` tracks the size of the loaded index almost
        one-for-one, and `vector_store.documents` is the number that explains
        it. Document counts are read from memory and free; the directory sizes
        are real filesystem walks and can take several seconds on a large
        index, so render this behind a loading state rather than polling it.
      responses:
        "200":
          description: Current usage
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceUsage"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "503":
          $ref: "#/components/responses/ResourcesUnavailable"

  /api/v1/admin/resources/analyze:
    post:
      operationId: analyzeReclaimable
      tags: [admin]
      summary: Find reclaimable garbage (admin only)
      description: |
        Reconciles what is on disk and in memory against what the database
        still knows about, and returns the reclaimable garbage grouped into
        categories the admin can select individually.

        Synchronous and expensive — it walks the vector store and the clone
        directory. Concurrent calls collapse into a single scan.

        The returned `analysis_id` is passed back to
        `POST /api/v1/admin/resources/clean`. It is an identity for "the
        picture the admin was shown", not a safety mechanism: every item is
        re-validated against live state immediately before it is deleted, so a
        project that comes back between analyze and clean is skipped rather
        than wiped.
      responses:
        "200":
          description: Analysis complete
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReclaimAnalysis"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "503":
          $ref: "#/components/responses/ResourcesUnavailable"

  /api/v1/admin/resources/clean:
    post:
      operationId: cleanResources
      tags: [admin]
      summary: Delete the selected reclaimable categories (admin only)
      description: |
        Deletes the selected categories from a previous analysis.

        Returns `200` even when individual items failed or were skipped — the
        per-category counts carry that detail, and failing the whole call would
        hide the items that were successfully reclaimed. `409` means the
        analysis expired or was already spent; re-run analyze.

        Deleting orphaned collections releases heap immediately — the server
        forces a GC afterwards, so `heap_alloc_bytes` drops right away. How far
        `rss_bytes` follows is platform-dependent: on Linux the pages go back to
        the OS and resident memory drops with the heap; on macOS they are marked
        reclaimable and stay resident until something else needs them.
        Everything else is disk only.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CleanRequest"
      responses:
        "200":
          description: Clean finished (possibly with per-item failures)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CleanResult"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          $ref: "#/components/responses/ResourcesUnavailable"

  /api/v1/admin/database:
    get:
      operationId: getDatabaseState
      tags: [admin]
      summary: Report SQLite size, wasted space and compaction advice (admin only)
      description: |
        Deleting rows does not shrink a SQLite file. The pages go on the
        freelist and are reused by later writes, so a database that has lost
        more data than it has since gained stays large and mostly empty. This
        endpoint reports how much of the file is waste and whether it is worth
        doing anything about it.

        Cheap: `page_count` and `freelist_pages` are header reads, not scans,
        so this is safe to poll.

        `auto_vacuum` is a property of the database file itself, not a stored
        setting — it is read live, so it always reflects reality even on a
        server that was upgraded into this feature. `none` means the file can
        only be shrunk by a full rebuild; `incremental` means free pages can
        additionally be returned to the filesystem in small bounded chunks
        (see `POST /api/v1/admin/database/reclaim`).

        `blocked_reason` is non-null when compaction cannot start right now —
        an indexing or clone job is in flight, or the filesystem does not have
        room for the copy. Render it instead of enabling the button.
      responses:
        "200":
          description: Current database state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DatabaseState"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "503":
          $ref: "#/components/responses/ResourcesUnavailable"

  /api/v1/admin/database/compact:
    post:
      operationId: compactDatabase
      tags: [admin]
      summary: Rebuild the database to reclaim free pages (admin only)
      description: |
        Starts a background rebuild and returns immediately with `202`. Poll
        `GET /maintenance/status` for progress.

        What the admin is agreeing to, and what the confirmation dialog must
        say before this is called:

        * For the long part the server is **read-only**, not down. Search,
          browsing and every read keep working. New logins and every write are
          rejected with `503` and a `Retry-After`; indexing and scheduled
          polling pause. Existing sessions and API keys keep working — their
          last-seen timestamps simply stop being refreshed for the duration,
          which is invisible against a 14-day session lifetime.
        * Then the server **restarts itself** to adopt the new file, and is
          fully unavailable while it comes back up.
        * Expect roughly a minute per 8 GB on a warm SSD for the copy, plus
          the usual startup time; `estimated_seconds` on `DatabaseState`
          carries the current estimate.

        The restart is not a fallback, it is the mechanism. Swapping the file
        under a live server would leave every service holding an open handle
        to the old one, so the swap is performed at boot, before anything
        opens the database — no pool, no services, no concurrency. The process
        re-executes itself rather than exiting, so a container keeps its PID 1
        and no restart policy or supervisor is involved.

        The read-only window matters because the rebuild copies a *snapshot*:
        anything committed after the copy begins is absent from the new file,
        and swapping it in would silently discard those writes. It is enforced
        in three layers rather than one, because the obvious single mechanism
        is wrong in both available forms.

        A route gate refuses the endpoints that write, and is what keeps
        latency sane — it is classified per route, never by HTTP method, since
        search is a POST and is one of the things that must keep working.
        Background work is stopped and drained before the copy starts. Finally
        the compactor holds a write transaction on a connection of its own, so
        anything that slips past the first two layers is refused by SQLite
        itself rather than landing outside the snapshot.

        Compaction does not change the database's reclaim mode. It reclaims
        space and leaves the mode exactly as it found it — that is a separate
        setting, changed through
        `PUT /api/v1/admin/database/auto-vacuum`.

        Crash safety: progress is journalled to a state file beside the
        database, written atomically, and every combination of that state and
        the files actually present on disk maps to exactly one recovery
        action. An interrupted copy is discarded; an interrupted swap is
        carried forward or rolled back. The original is deleted last, so no
        interruption leaves the server without a database. Nothing is resumed
        — the operation is all-or-nothing and is simply re-run.

        The state lives in a file rather than a table precisely because the
        database is the thing being replaced: a row describing the operation
        could not survive the swap, could not be written during the read-only
        window, and could not be read back during the restart.
      responses:
        "202":
          description: Compaction started
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MaintenanceOperation"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: |
            Already running, or held back because clone/index jobs are in
            flight. `DatabaseState.blocked_reason` carries the same detail.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "507":
          $ref: "#/components/responses/InsufficientStorage"
        "503":
          $ref: "#/components/responses/ResourcesUnavailable"

  /api/v1/admin/database/reclaim:
    post:
      operationId: reclaimFreePages
      tags: [admin]
      summary: Return free pages to the filesystem in bounded chunks (admin only)
      description: |
        Runs `PRAGMA incremental_vacuum`, which moves free pages to the end of
        the file, followed by a WAL checkpoint. Synchronous, bounded and
        cheap: it holds an ordinary write lock for the pages it moves, not an
        exclusive lock on the whole database, so it does not need a
        maintenance window.

        The checkpoint is part of the operation, not an extra. In WAL mode the
        page moves and the truncation both land in the log, so the database
        file does not shrink until the log is folded back in — without it a
        small reclaim reports bytes freed while the file on disk is unchanged.

        Requires the file to be in incremental auto-vacuum mode; `409`
        otherwise, with compaction as the remedy.

        This reclaims space but does not defragment — a full compaction still
        rebuilds the file and improves read locality. The point of incremental
        reclaim is to make that rare rather than routine.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReclaimRequest"
      responses:
        "200":
          description: Reclaim finished
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReclaimResult"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: The database is not in incremental auto-vacuum mode
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          $ref: "#/components/responses/ResourcesUnavailable"

  /api/v1/admin/database/auto-vacuum:
    put:
      operationId: setAutoVacuumMode
      tags: [admin]
      summary: Change the database's reclaim mode (admin only)
      description: |
        Incremental mode lets free pages be returned to the filesystem without
        a rebuild — it is what makes
        `POST /api/v1/admin/database/reclaim` possible. It is not free: it
        maintains pointer-map pages, so every page allocated or freed carries
        an extra write, measured at +1.5% on an indexing-shaped workload.

        **Asking for the mode the database is already in does nothing** and
        answers `200`. Only an actual change costs anything.

        A change costs a full rebuild, in either direction, because that is
        the only way SQLite can change the mode of a populated database. So a
        `202` here means the same interruption as
        `POST /api/v1/admin/database/compact`: a read-only window, then a
        restart. The space that rebuild happens to reclaim is a side effect,
        not the point.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AutoVacuumRequest"
      responses:
        "200":
          description: |
            The database is already in the requested mode. Nothing was done and
            the returned operation is `idle`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MaintenanceOperation"
        "202":
          description: A rebuild has started to apply the change.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MaintenanceOperation"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: |
            Already running, or held back because clone/index jobs are in
            flight.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "507":
          $ref: "#/components/responses/InsufficientStorage"
        "503":
          $ref: "#/components/responses/ResourcesUnavailable"

  /api/v1/admin/schedules:
    get:
      operationId: listSchedules
      tags: [admin]
      summary: List every recurring task and when it next runs (admin only)
      description: |
        One entry per task the server knows how to run on a schedule. The
        timing is a crontab expression, and `next_runs` is computed by the
        same parser that will actually fire it — a client must not evaluate
        the expression itself, or its preview and the server's behaviour can
        disagree.

        `configured` is false while a task is still on its built-in or
        environment default, which is how an upgraded server reports
        automation nobody has opted into.
      responses:
        "200":
          description: Registered tasks
          content:
            application/json:
              schema:
                type: object
                required: [tasks]
                properties:
                  tasks:
                    type: array
                    items:
                      $ref: "#/components/schemas/ScheduledTask"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "503":
          $ref: "#/components/responses/ResourcesUnavailable"

  /api/v1/admin/schedules/{name}:
    put:
      operationId: updateSchedule
      tags: [admin]
      summary: Change when a recurring task runs (admin only)
      description: |
        Absent fields are left unchanged.

        An expression that parses but can never match — 30 February is the
        honest example — is refused with `422` rather than accepted as a
        schedule that silently never fires. Saving re-arms the task
        immediately, so the next run returned here is the one the server will
        actually keep.

        Timing is interpreted in the server's local timezone. Crontab
        semantics apply: a slot that passes while the process is not running
        is not queued up and fired late, except for tasks that declare
        `catch_up` — those are cheap enough that running one late is better
        than a laptop asleep at 00:00 never running them at all.
      parameters:
        - name: name
          in: path
          required: true
          schema: { type: string }
          description: Task identifier, e.g. `db.reclaim`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScheduleUpdate"
      responses:
        "200":
          description: The task as it now resolves
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScheduledTask"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          $ref: "#/components/responses/ResourcesUnavailable"


  /maintenance/status:
    get:
      operationId: getMaintenanceStatus
      tags: [system]
      summary: Progress of a running maintenance operation (public)
      description: |
        Public and deliberately so. It reads a state file next to the database
        and touches neither the database nor the session table, so it answers
        throughout the read-only window and again the moment the restarted
        server is listening. Anything authenticated would `401` while sessions
        are unwritable, and anything DB-backed would block behind the freeze.

        It cannot answer *during* the restart itself: the router is built
        after the database is opened and the listener binds at the end of
        startup, so a client sees a connection failure until the server is
        back. A poller is expected to render that as "reconnecting" rather
        than as an error — the journal it reads is durable, so the first
        successful poll after the gap reports what happened.

        This is also how the result of a compaction reaches the dashboard at
        all: the outcome is only known after the snapshot the new database was
        built from, so it exists in the state file and nowhere else.

        `phase` is `idle` when nothing is happening. `interrupted` means a
        previous run did not finish and the next boot brought the database
        back to a consistent state; it is informational, not an error to
        clear.
      responses:
        "200":
          description: Current maintenance state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MaintenanceOperation"

  /api/v1/admin/embedding-providers:
    get:
      operationId: listEmbeddingProviders
      tags: [admin]
      summary: List registered embedding-provider kinds (admin only)
      description: |
        Returns one entry per registered provider kind with its config
        schema and the names of the env vars it reads for credentials,
        plus whether those env vars are currently set on the server.
        The dashboard uses this to render the kind dropdown, the
        per-kind form, and the "set CIX_VOYAGE_API_KEY before saving"
        banner when a key is missing.
      responses:
        "200":
          description: List of registered providers
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmbeddingProviderList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/admin/embedding-providers/active:
    get:
      operationId: getActiveEmbeddingProvider
      tags: [admin]
      summary: Get the currently active embedding provider (admin only)
      description: |
        Returns the persisted provider selection (kind + JSON config
        blob) and the live `Provider.ID()` fingerprint. API keys are
        never persisted, so the config blob carries env-var NAMES
        only — safe to surface to admin clients verbatim.
      responses:
        "200":
          description: Currently active provider
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActiveEmbeddingProvider"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "503":
          description: Embeddings service not wired (e.g. CIX_EMBEDDINGS_ENABLED=false)
    put:
      operationId: switchEmbeddingProvider
      tags: [admin]
      summary: Switch to a different embedding provider (admin only)
      description: |
        Atomic switch. The server validates the submitted config, persists
        it, then swaps the live Service over (drains the queue first).
        On any error the existing provider stays untouched.

        Switching changes the active `Provider.ID()` fingerprint; every
        project's `indexed_with_model` becomes stale and the next
        clone job per project triggers a full reindex
        (`mode=full, reason=model-change`).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SwitchEmbeddingProviderRequest"
      responses:
        "202":
          description: Switch accepted; new provider is live
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActiveEmbeddingProvider"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/admin/embedding-providers/{kind}/test:
    post:
      operationId: testEmbeddingProvider
      tags: [admin]
      summary: Validate an embedding-provider config without persisting (admin only)
      description: |
        Builds a throw-away provider from the submitted config, calls
        Start (one short embed for HTTP providers; spawning a child for
        ollama), then Stops it. Returns the detected dimension and an
        ok flag. Use this from the dashboard before calling PUT
        /embedding-providers/active so the admin sees an actionable
        error (bad key, wrong URL, missing env var) before the swap.
      parameters:
        - name: kind
          in: path
          required: true
          schema:
            type: string
            enum: [ollama, openai, voyage]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: Provider-specific config blob (shape varies by kind).
              additionalProperties: true
      responses:
        "200":
          description: Connect test succeeded
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestEmbeddingProviderResponse"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "502":
          description: |
            Connect test failed against the upstream service (auth
            rejected, network unreachable, etc).

  /api/v1/api-keys:
    get:
      operationId: listApiKeys
      tags: [api-keys]
      summary: List my API keys (or all keys if admin)
      parameters:
        - name: owner
          in: query
          required: false
          description: |
            `all` — admin-only, returns every key in the system.
            Anything else (or unset) returns the caller's keys.
          schema:
            type: string
            enum: [all]
      responses:
        "200":
          description: Key list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      operationId: createApiKey
      tags: [api-keys]
      summary: Issue a new API key
      description: |
        Returns the **plaintext** `full_key` exactly once in the response.
        The dashboard shows it with a copy button and a "this is the only
        time you will see this value" warning. Subsequent reads only
        return the `prefix`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateApiKeyRequest"
      responses:
        "201":
          description: Key created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyCreated"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "422":
          $ref: "#/components/responses/Unprocessable"

  /api/v1/api-keys/{id}:
    delete:
      operationId: revokeApiKey
      tags: [api-keys]
      summary: Revoke an API key
      description: |
        The owner can revoke their own keys. An admin can revoke any
        key. Revoking is permanent — the row stays in the table marked
        with `revoked_at` so the audit trail is preserved, but
        subsequent Bearer auth attempts with the value fail with 401.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: Revoked
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/projects:
    post:
      operationId: createProject
      tags: [projects]
      summary: Register a new project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateProjectRequest"
      responses:
        "201":
          description: Project created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: |
            The caller's account has `local_project_disabled=true`
            (cannot create local projects). Admins are exempt.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: A project with this `host_path` already exists
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "500":
          $ref: "#/components/responses/InternalError"
    get:
      operationId: listProjects
      tags: [projects]
      summary: List all registered projects
      responses:
        "200":
          description: Project list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    get:
      operationId: getProject
      tags: [projects]
      summary: Get one project by hash
      responses:
        "200":
          description: Project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    patch:
      operationId: updateProject
      tags: [projects]
      summary: Patch project settings (admin only)
      description: |
        Admin-only. Settings changes can shrink the indexing surface
        (exclude_patterns, max_file_size); viewers must not be able to
        silently de-index a project.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateProjectRequest"
      responses:
        "200":
          description: Updated project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      operationId: deleteProject
      tags: [projects]
      summary: Delete a project and all its indexed data (admin only)
      description: |
        Admin-only. Drops the project plus its symbols, refs, file hashes,
        and embeddings. Destructive enough that viewer-scoped sessions and
        API keys must not reach it.
      responses:
        "204":
          description: Deleted (no body)
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}/summary:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    get:
      operationId: getProjectSummary
      tags: [projects]
      summary: Project overview (top dirs, recent symbols, totals)
      responses:
        "200":
          description: Summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}/file:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    post:
      operationId: readProjectFile
      tags: [projects]
      summary: Read a file (whole or line range) from an external project's checkout
      description: |
        Returns the contents of a file from the server-side git checkout of an
        EXTERNAL (GitHub-backed) project. LOCAL projects are not served — their
        files live on the caller's machine, not on the server — and return 409
        with a `detail` telling the caller to read the file with their own
        filesystem tools. Omit `start`/`end` to read the whole file; otherwise
        both are 1-based inclusive line numbers. Output is capped by server
        size/line limits (`truncated: true` when hit).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FileReadRequest"
      responses:
        "200":
          description: File content
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileContent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: |
            The project is local (its files are not on the server) or its
            checkout is not yet available. `detail` explains which and what
            to do instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}/tree:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    post:
      operationId: listProjectTree
      tags: [projects]
      summary: List a directory (one level) in an external project's checkout
      description: |
        Lists the immediate entries of a directory in the server-side git
        checkout of an EXTERNAL (GitHub-backed) project — ls-like, one level,
        no recursion. Omit `dir` (or pass empty) for the repo root. LOCAL
        projects return 409 (see the file endpoint). Entry count is capped
        (`truncated: true` when hit); the `.git` directory is omitted.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TreeRequest"
      responses:
        "200":
          description: Directory listing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DirectoryListing"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: |
            The project is local or its checkout is not yet available.
            `detail` explains which and what to do instead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}/workspaces:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    get:
      operationId: listProjectWorkspaces
      tags: [projects]
      summary: List workspaces that contain this project
      description: |
        Returns every workspace that has this project attached, owned or
        linked. The project page uses this to show "Workspaces" chips
        the user can click to jump to the workspace detail page.

        Empty list when the project isn't part of any workspace yet —
        either it was indexed directly via /projects without ever being
        linked, or all its memberships have been detached.
      responses:
        "200":
          description: Memberships
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectWorkspaceList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/search-stats:
    get:
      operationId: getSearchStats
      tags: [search-stats]
      summary: Per-project search counters, filtered and sorted server-side
      description: |
        One row per project that has been searched at least once, carrying the
        query count, how many files came back in total, and that project's
        most-returned files.

        Every filter, the sort and the pagination are applied in SQL before the
        page is built, so `limit` bounds what is computed, not merely what is
        transmitted.

        Access: a regular user sees only the projects they can already search —
        their own, plus external projects shared to a view-group they belong
        to. An admin sees every project. Projects that have never been searched
        are absent from `projects` and counted in `projects_without_activity`.

        A file's hit count is the number of SEARCHES it appeared in, not the
        number of matching chunks, so it can never exceed the project's query
        count: "this file came back in 42 of the project's 128 searches".
      parameters:
        - name: window
          in: query
          required: false
          description: |
            `all` reads the cumulative totals — every search ever recorded.
            The others read the rolling 30-minute-bucket tier, which retains
            seven days; nothing older than that is kept, so a longer window
            would silently be the same as `7d`.
          schema:
            type: string
            enum: [all, 1h, 24h, 7d]
            default: all
        - name: kinds
          in: query
          required: false
          description: |
            Comma-separated list of search kinds to include. Omit for all of
            them. `workspace` is one project's slice of a workspace fan-out:
            every project a workspace query actually scanned records one,
            whether or not it made the answer.
          schema:
            type: string
            example: semantic,workspace
        - name: project
          in: query
          required: false
          description: |
            Case-insensitive substring, matched against the project's display
            name and its host path. Applied before pagination.
          schema:
            type: string
        - name: min_queries
          in: query
          required: false
          schema: { type: integer, format: int64, minimum: 0 }
        - name: max_queries
          in: query
          required: false
          schema: { type: integer, format: int64, minimum: 0 }
        - name: min_file_hits
          in: query
          required: false
          description: Bounds on the project's TOTAL file appearances.
          schema: { type: integer, format: int64, minimum: 0 }
        - name: max_file_hits
          in: query
          required: false
          schema: { type: integer, format: int64, minimum: 0 }
        - name: min_top_file_hits
          in: query
          required: false
          description: |
            Bounds on the hit count of the project's single most-returned
            file — the number shown against the first entry of `top_files`.
          schema: { type: integer, format: int64, minimum: 0 }
        - name: max_top_file_hits
          in: query
          required: false
          schema: { type: integer, format: int64, minimum: 0 }
        - name: top_files
          in: query
          required: false
          description: How many of each project's most-returned files to attach.
          schema:
            type: integer
            minimum: 0
            maximum: 20
            default: 5
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum: [project, queries, results, file_hits, top_file_hits, distinct_files, last_seen]
            default: queries
        - name: order
          in: query
          required: false
          schema:
            type: string
            enum: [asc, desc]
            default: desc
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        "200":
          description: One page of the statistics table
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchStatsResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "503":
          description: Search statistics are disabled on this server

  /api/v1/search-stats/series:
    get:
      operationId: getSearchStatsSeries
      tags: [search-stats]
      summary: Query counts over the retained window, one point per bucket
      description: |
        Summed over every project the caller can see, or over one project when
        `project_hash` is given. Buckets with no activity are omitted rather
        than sent as zeroes — `bucket_seconds` is enough to reconstruct the
        gaps, and a quiet week would otherwise be 336 empty points.

        Access is the same as `GET /search-stats`.
      parameters:
        - name: window
          in: query
          required: false
          schema:
            type: string
            enum: [1h, 24h, 7d]
            default: 7d
        - name: kinds
          in: query
          required: false
          schema:
            type: string
        - name: project_hash
          in: query
          required: false
          description: Restrict to one project, by its 16-hex path hash.
          schema:
            type: string
      responses:
        "200":
          description: The windowed series
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchStatsSeriesResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          description: Search statistics are disabled on this server

  /api/v1/search-stats/settings:
    get:
      operationId: getSearchStatsSettings
      tags: [search-stats]
      summary: Whether search counters are being recorded
      description: |
        Readable by any authenticated user, because the statistics page has to
        explain why it is empty. Changing it is admin-only.

        `source` says what decided the current state: `database` — an admin used
        the toggle, and that outranks the environment from then on;
        `environment` — nobody has decided, and `CIX_SEARCH_STATS_ENABLED` is
        speaking; `default` — nobody has decided and the variable is unset, so
        the feature is off.
      responses:
        "200":
          description: The resolved setting
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchStatsSettings"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/admin/search-stats/settings:
    put:
      operationId: setSearchStatsSettings
      tags: [search-stats]
      summary: Switch search counters on or off (admin only)
      description: |
        Takes effect immediately — no restart. Enabling opens the statistics
        database, creating it on first use; disabling flushes whatever is
        buffered and closes it, keeping the counters already collected.

        The decision is persisted and outranks `CIX_SEARCH_STATS_ENABLED` from
        then on, so a redeploy carrying the old environment cannot silently undo
        it.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetSearchStatsSettingsRequest"
      responses:
        "200":
          description: The resolved setting after the change
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchStatsSettings"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/admin/search-stats/reset:
    post:
      operationId: resetSearchStats
      tags: [search-stats]
      summary: Discard every recorded search counter (admin only)
      description: |
        Empties both tiers. There is nothing to recover afterwards and nothing
        else depends on the numbers — they are derived from traffic that has
        already been served.

        Works whether or not collection is currently on. Discarding what was
        collected must not require switching collection back on, or stopping and
        disposing become the same lever. A server that never enabled the feature
        has nothing to discard and gets a 204 without a database being created.
      responses:
        "204":
          description: Counters cleared
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "503":
          description: Search statistics are disabled on this server

  /api/v1/projects/{path}/search:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    post:
      operationId: semanticSearch
      tags: [search]
      summary: Semantic (vector) search
      description: |
        Embeds the query and runs an approximate nearest-neighbour search
        against the project's vector collection. Results are
        post-filtered by `min_score`, `paths` (whitelist, prefix-OR-substring
        match), `excludes` (blacklist, same matching), and `languages` —
        then merged into per-file groups and ranked by best match score.

        `min_score` semantics:
          - omitted → server default `0.2` (light relevance floor that
            doesn't silently drop abstract natural-language queries
            whose best chunks score in [0.25, 0.35])
          - explicit `0` → return everything above HNSW floor
          - explicit positive → that floor (use `0.4+` for strict
            code-symbol searches calibrated for CodeRankEmbed-Q8)

        `query_time_ms` is rounded to 1 decimal place.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SemanticSearchRequest"
      responses:
        "200":
          description: Per-file grouped semantic results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SemanticSearchResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          description: |
            Embeddings disabled, vector store missing, or sidecar busy
            (Retry-After header set).
          headers:
            Retry-After:
              schema: { type: integer }
              description: Seconds to wait when the embedder is busy
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}/search/symbols:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    post:
      operationId: searchSymbols
      tags: [search]
      summary: Symbol search by name (prefix/substring)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SymbolSearchRequest"
      responses:
        "200":
          description: Matching symbols
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SymbolSearchResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}/search/definitions:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    post:
      operationId: searchDefinitions
      tags: [search]
      summary: Go-to-definition by symbol name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DefinitionRequest"
      responses:
        "200":
          description: Matching definitions
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DefinitionResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}/search/references:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    post:
      operationId: searchReferences
      tags: [search]
      summary: Find references to a symbol
      description: |
        Returns the locations where `symbol` appears as an identifier token.
        `content` is intentionally empty and `end_line == start_line` —
        populating snippets here would require a full file re-read per
        result; clients should follow up with semantic search or read the
        file directly.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReferenceRequest"
      responses:
        "200":
          description: References
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReferenceResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}/search/files:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    post:
      operationId: searchFiles
      tags: [search]
      summary: File-path substring search
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FileSearchRequest"
      responses:
        "200":
          description: Matching file paths
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FileSearchResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}/index/begin:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    post:
      operationId: indexBegin
      tags: [indexing]
      summary: Open an indexing session
      description: |
        Returns a `run_id` and the map of currently-stored content hashes
        (`stored_hashes`) so the client can compute a delta. Pass `full:true`
        to wipe project state before indexing. Body is optional.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IndexBeginRequest"
      responses:
        "200":
          description: Session opened
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IndexBeginResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: |
            The caller's account has `local_project_disabled=true`
            (cannot index/reindex), or the caller can read the project but
            is not its owner. Admins are exempt from the former.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          description: An indexing session is already active for this project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          $ref: "#/components/responses/IndexerUnavailable"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}/index/files:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    post:
      operationId: indexFiles
      tags: [indexing]
      summary: Submit a batch of files (max 50)
      description: |
        Sends a batch of file payloads belonging to the open `run_id`.
        Maximum 50 files per call.

        **Streaming negotiation**: send `Accept: application/x-ndjson` to
        receive a newline-delimited stream of `IndexProgressEvent` objects
        (one event per line, plus a `heartbeat` every 10 s). Without that
        header (or with `Accept: application/json`) the response is the
        legacy single-JSON `IndexFilesResponse` returned after the batch
        completes.
      parameters:
        - in: header
          name: Accept
          required: false
          schema:
            type: string
            enum: [application/json, application/x-ndjson]
          description: |
            `application/x-ndjson` switches to a streamed response
            (one `IndexProgressEvent` per line). Default: `application/json`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IndexFilesRequest"
      responses:
        "200":
          description: |
            Either a single JSON summary (default) or a stream of NDJSON
            events (when the client opted in via `Accept: application/x-ndjson`).
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IndexFilesResponse"
            application/x-ndjson:
              schema:
                $ref: "#/components/schemas/IndexProgressEvent"
              examples:
                stream:
                  summary: NDJSON stream (one event per line)
                  value: |
                    {"event":"file_started","run_id":"r-1","path":"main.go","file_index":1,"batch_size":20}
                    {"event":"file_chunked","path":"main.go","chunks":12}
                    {"event":"file_embedded","path":"main.go","chunks":12,"embed_ms":540}
                    {"event":"file_done","path":"main.go","chunks":12}
                    {"event":"heartbeat","ts":"2026-04-27T17:25:00Z"}
                    {"event":"batch_done","files_accepted":20,"chunks_created":347,"files_processed_total":300}
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: Project not found OR run_id not found / project mismatch
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          description: |
            Indexer disabled, or GPU sidecar busy. When busy, `Retry-After`
            header is set with a suggested wait (seconds).
          headers:
            Retry-After:
              schema: { type: integer }
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}/index/finish:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    post:
      operationId: indexFinish
      tags: [indexing]
      summary: Commit the indexing session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IndexFinishRequest"
      responses:
        "200":
          description: Session committed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IndexFinishResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: Project not found OR run_id unknown / project mismatch
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          $ref: "#/components/responses/IndexerUnavailable"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}/index/cancel:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    post:
      operationId: indexCancel
      tags: [indexing]
      summary: Cancel any active indexing session (idempotent)
      description: |
        Open to any authenticated user. Returns `{"cancelled": true}` if a
        session was killed, `false` if none was active. The CLI calls this
        in defer-cleanup on early exit, so gating it on admin would leave
        run locks hanging for viewers until the 1-hour TTL.
      responses:
        "200":
          description: Cancellation result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IndexCancelResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/v1/projects/{path}/index/status:
    parameters:
      - $ref: "#/components/parameters/ProjectHash"
    get:
      operationId: indexStatus
      tags: [indexing]
      summary: Live progress of the current run, or last completed run
      description: |
        When a session is active: returns mid-run progress with
        `phase`, `files_discovered/processed/total`, `chunks_created`,
        `elapsed_seconds`, and `run_id`. When no session is active:
        falls back to the most recent `index_runs` row, returning only
        `files_processed/total` and `chunks_created`. If the project
        has no history at all: `{"status":"idle"}`.
      responses:
        "200":
          description: Progress payload (or idle)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IndexProgressResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/workspaces:
    get:
      operationId: listWorkspaces
      tags: [workspaces]
      summary: List all workspaces
      description: |
        Returns every workspace in the system, newest first. Server-wide
        shared visibility — the caller sees workspaces created by any user.
      responses:
        "200":
          description: Workspace list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"
    post:
      operationId: createWorkspace
      tags: [workspaces]
      summary: Create a new workspace
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkspaceRequest"
      responses:
        "201":
          description: Workspace created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/workspaces/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Workspace ID (ULID-like string returned by createWorkspace).
    get:
      operationId: getWorkspace
      tags: [workspaces]
      summary: Get a single workspace
      responses:
        "200":
          description: Workspace
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"
    patch:
      operationId: updateWorkspace
      tags: [workspaces]
      summary: Update workspace metadata
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWorkspaceRequest"
      responses:
        "200":
          description: Updated workspace
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Workspace"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"
    delete:
      operationId: deleteWorkspace
      tags: [workspaces]
      summary: Delete a workspace
      description: |
        Removes the workspace row. workspace_projects memberships
        referencing this workspace are removed via ON DELETE CASCADE;
        the underlying projects, git_repos peers, and on-disk clones
        are preserved (delete those explicitly via /projects/{path}
        when desired).
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/groups:
    get:
      operationId: listGroups
      tags: [groups]
      summary: List view-groups
      description: |
        Admins see every group; a regular user sees only the groups they
        belong to (so the dashboard's "share to group" picker can populate).
      responses:
        "200":
          description: Group list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
    post:
      operationId: createGroup
      tags: [groups]
      summary: Create a view-group (admin only)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateGroupRequest"
      responses:
        "201":
          description: Group created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Unprocessable"

  /api/v1/groups/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: View-group ID.
    get:
      operationId: getGroup
      tags: [groups]
      summary: Get a view-group (admin only)
      responses:
        "200":
          description: Group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    patch:
      operationId: updateGroup
      tags: [groups]
      summary: Update a view-group (admin only)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateGroupRequest"
      responses:
        "200":
          description: Updated group
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Group"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Unprocessable"
    delete:
      operationId: deleteGroup
      tags: [groups]
      summary: Delete a view-group (admin only)
      description: |
        Cascades to memberships and project/workspace shares referencing
        the group.
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/v1/groups/{id}/members:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: View-group ID.
    get:
      operationId: listGroupMembers
      tags: [groups]
      summary: List members of a view-group (admin only)
      responses:
        "200":
          description: Member list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupMemberListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      operationId: addGroupMember
      tags: [groups]
      summary: Add a user to a view-group (admin only)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddGroupMemberRequest"
      responses:
        "204":
          description: Member added (idempotent)
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"

  /api/v1/groups/{id}/members/{userId}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: View-group ID.
      - name: userId
        in: path
        required: true
        schema:
          type: string
        description: User ID to remove.
    delete:
      operationId: removeGroupMember
      tags: [groups]
      summary: Remove a user from a view-group (admin only)
      responses:
        "204":
          description: Member removed (idempotent)
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/projects/{hash}/shares:
    parameters:
      - name: hash
        in: path
        required: true
        schema:
          type: string
        description: Project path hash.
    get:
      operationId: listProjectShares
      tags: [groups]
      summary: List the view-groups an external project is shared to (admin only)
      responses:
        "200":
          description: Group ids the project is shared to
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupIdListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
    post:
      operationId: shareProjectToGroup
      tags: [groups]
      summary: Share an external project to a view-group (admin only)
      description: |
        Only EXTERNAL projects (with a git_repos peer) may be shared — sharing
        a personal/local project returns 422.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ShareToGroupRequest"
      responses:
        "204":
          description: Shared (idempotent)
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"

  /api/v1/projects/{hash}/shares/{groupId}:
    parameters:
      - name: hash
        in: path
        required: true
        schema:
          type: string
        description: Project path hash.
      - name: groupId
        in: path
        required: true
        schema:
          type: string
        description: View-group ID.
    delete:
      operationId: unshareProjectFromGroup
      tags: [groups]
      summary: Revoke a project↔group share (admin only)
      responses:
        "204":
          description: Unshared (idempotent)
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"

  /api/v1/projects/{hash}/owner:
    parameters:
      - name: hash
        in: path
        required: true
        schema:
          type: string
        description: Project path hash.
    put:
      operationId: reassignProjectOwner
      tags: [projects]
      summary: Reassign the owner of a local project (admin only)
      description: |
        Only LOCAL projects (no git_repos peer) can be reassigned — external
        projects are ownerless by design and return 422.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ReassignOwnerRequest"
      responses:
        "200":
          description: Updated project
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Project"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"

  /api/v1/workspaces/{id}/shares:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Workspace ID.
    get:
      operationId: listWorkspaceShares
      tags: [workspaces]
      summary: List the view-groups a workspace is shared to
      responses:
        "200":
          description: Group ids the workspace is shared to
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GroupIdListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"
    post:
      operationId: shareWorkspaceToGroup
      tags: [workspaces]
      summary: Share a workspace to a view-group
      description: |
        The workspace owner may share to a group they belong to; an admin may
        share to any group. Visibility only — each project inside the workspace
        is still access-checked per viewer.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ShareToGroupRequest"
      responses:
        "204":
          description: Shared (idempotent)
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/workspaces/{id}/shares/{groupId}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Workspace ID.
      - name: groupId
        in: path
        required: true
        schema:
          type: string
        description: View-group ID.
    delete:
      operationId: unshareWorkspaceFromGroup
      tags: [workspaces]
      summary: Revoke a workspace↔group share (owner or admin)
      responses:
        "204":
          description: Unshared (idempotent)
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/git-repos:
    post:
      operationId: addGitRepo
      tags: [projects]
      summary: Clone + index a GitHub repository as a standalone project
      description: |
        Inserts a projects row (status=pending), a matching git_repos
        row, and enqueues a `clone_repo` background job that is chained
        to an `index_repo` job on success. The resulting project lives
        in `/api/v1/projects` and is initially attached to no
        workspaces — link it into specific workspaces via
        `/api/v1/workspaces/{id}/projects` if desired.

        `token_id` is required for private repos; `webhook_mode`
        defaults to `manual`. The response carries a one-shot
        `webhook_url` + `webhook_secret` so the operator can register
        the webhook in GitHub by hand (`auto` mode does it for them).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddGitRepoRequest"
      responses:
        "201":
          description: Project created + clone enqueued
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GitRepoCreated"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/workspaces/{id}/projects:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Workspace ID.
    get:
      operationId: listWorkspaceProjects
      tags: [workspaces]
      summary: List projects currently linked to a workspace
      responses:
        "200":
          description: Workspace project list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceProjectListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"
    post:
      operationId: linkProjectToWorkspace
      tags: [workspaces]
      summary: Link an existing project into this workspace
      description: |
        Inserts a (workspace_id, project_path) row into
        `workspace_projects`. The project must already exist and be in
        `status='indexed'`. Duplicates return 409. The project itself
        is untouched — workspaces are pure membership collections.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LinkProjectRequest"
      responses:
        "201":
          description: Linked
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceProjectMembership"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/workspaces/{id}/projects/{hash}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: hash
        in: path
        required: true
        schema:
          type: string
        description: Project's path_hash.
    delete:
      operationId: unlinkProjectFromWorkspace
      tags: [workspaces]
      summary: Remove a project from this workspace (does not delete the project)
      description: |
        Drops the (workspace_id, project_path) row. The project itself,
        its clone on disk, its indexed content, and its memberships in
        other workspaces are all untouched.
      responses:
        "204":
          description: Unlinked
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/workspaces/{id}/search:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: workspaceSearch
      tags: [workspaces]
      summary: Hybrid BM25+dense search across all repos in a workspace
      description: |
        Embeds the query, then fans out two parallel sub-queries per
        project: dense (cosine over stored vectors) and sparse (SQLite FTS5 BM25
        over chunks_fts). Per-project the two ranked lists are fused
        via Reciprocal Rank Fusion (k=60).

        Across projects an α-blended candidacy score (`α × bm25_norm
        + (1-α) × dense_norm` with α=0.5, both signals min-max
        normalized per query) plus a relative threshold
        (`candidacy ≥ best × 0.4`) drops projects that share no
        semantic and no lexical overlap with the query. Pure-dense
        fan-out returned the N nearest vectors regardless of
        absolute distance, so workspaces routinely surfaced
        irrelevant repos at noise-level cosine similarity; the BM25
        gate fixes that by requiring at least one of the two
        signals to be a meaningful fraction of the best.

        The chunks list is then built by round-robin interleaving:
        rank-1 from every surviving project before any rank-2, etc.,
        capped per-project so one dominant repo can't take every
        slot. Always live — no background rebuild job, no debounce.
      parameters:
        - name: q
          in: query
          required: true
          schema:
            type: string
            minLength: 1
        - name: top_projects
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
        - name: top_chunks
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 20
        - name: min_score
          in: query
          required: false
          description: |
            Floor on raw cosine similarity. Chunks below this are
            dropped before aggregation. Default 0.4 — symmetric with
            per-project search default so an unfiltered workspace
            query doesn't return cross-repo noise that a single-repo
            query would have rejected. Pass 0 explicitly for
            intentional cross-project sweeps that need long-tail
            recall (e.g. "authentication and authorization" across a
            mixed-domain workspace).
          schema:
            type: number
            format: float
            minimum: 0
            maximum: 1
            default: 0.4
        - name: timings
          in: query
          required: false
          description: |
            Attach a per-phase breakdown of where the query spent its
            time (see WorkspaceSearchTimings). Diagnostic, not API
            surface: it exists so a slow workspace query can be taken
            apart, and it is off unless asked for. The server logs the
            same breakdown by itself whenever a query is slow, so
            catching a regression does not depend on someone having
            passed this flag at the right moment.
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceSearchResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/projects/{hash}/git-repo:
    parameters:
      - name: hash
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getProjectGitRepo
      tags: [projects]
      summary: Read the git_repos metadata for an external project
      description: |
        Returns clone + webhook metadata. 404 when the project is local
        (has no git_repos row). The webhook_secret is included so the
        operator can paste it into GitHub Settings → Webhooks.
      responses:
        "200":
          description: git_repos row
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GitRepo"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"
    patch:
      operationId: updateProjectGitRepoSync
      tags: [projects]
      summary: Reconfigure how an external project is kept in sync
      description: |
        Switches the project's sync method directly from the project page:

        - `webhook` — GitHub push webhooks trigger reindex. Sets
          webhook_mode='auto' and attempts to auto-register the hook
          (needs CIX_PUBLIC_URL / a live tunnel and a PAT with
          admin:repo_hook). If registration fails, the server falls back to
          polling and says so in `note`.
        - `polling` — the shared scheduler fetches on an interval
          (`poll_interval_seconds`, optional). Sets webhook_mode='disabled'.
        - `manual` — no automatic sync; reindex on demand. Sets
          webhook_mode='disabled', polling off.

        Switching away from `webhook` best-effort de-registers any hook the
        server previously created. 404 when the project is local.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateGitRepoSyncRequest"
      responses:
        "200":
          description: Updated sync configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpdateGitRepoSyncResult"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          description: Invalid sync_method
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/projects/{hash}/git-repo/token:
    parameters:
      - name: hash
        in: path
        required: true
        schema:
          type: string
    put:
      operationId: updateProjectGitRepoToken
      tags: [projects]
      summary: Re-point an external project at a different stored GitHub PAT
      description: |
        Changes which stored token (`git_repos.token_id`) an external project
        uses to clone/fetch and to register webhooks, without deleting and
        re-creating the project. Pass `token_id: null` (or omit) to detach the
        token and clone the repo as public. 422 when the supplied token id does
        not exist; 404 when the project is local (no git_repos row).

        The webhook is left as-is: a hook already registered on GitHub keeps
        delivering regardless of which PAT the server holds. The new token is
        used by the next clone/fetch and by any later webhook re-register or
        delete (re-save the sync method to re-register under the new token).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateGitRepoTokenRequest"
      responses:
        "200":
          description: Updated git_repos row
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GitRepo"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/projects/{hash}/webhook-info:
    parameters:
      - name: hash
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getProjectWebhookInfo
      tags: [projects]
      summary: Webhook URL + secret for manual GitHub setup
      description: |
        Returns the publicly-reachable webhook URL and the HMAC secret
        for an external (GitHub-cloned) project. Only projects with a
        `git_repos` peer participate in webhook delivery — local-path
        projects have no clone lifecycle and no webhook.

        The handler returns 404 in two distinct cases, indistinguishable
        on the wire: (a) the `path_hash` doesn't resolve to any project
        at all, and (b) the project exists but is local. Callers that
        need to disambiguate must query `GET /projects/{hash}` first to
        confirm existence, then treat a subsequent webhook-info 404 as
        "local project, no webhook to configure".
      responses:
        "200":
          description: Webhook coordinates
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookInfoResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: |
            Either the project does not exist, OR the project exists but
            is local (no `git_repos` row, no webhook to surface).
            Disambiguate by checking `GET /projects/{hash}` first.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/projects/{hash}/reindex:
    parameters:
      - name: hash
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: reindexProject
      tags: [projects]
      summary: Manually re-trigger the clone + index pipeline
      description: |
        Enqueues a fresh `clone_repo` job for the matching git_repos
        row. 422 when the project is local (no clone pipeline — local
        projects reindex via the CLI). Dedupe collapses repeated
        triggers into the existing in-flight job.

        Normally the clone job decides incremental vs full automatically
        (incremental when an `indexed_sha` is recorded and tree.Diff
        succeeds; full on first-index, partial-failure recovery,
        or embedding-model change). Pass `full=true` to force a full
        reindex — useful when index drift is suspected. The endpoint
        clears `git_repos.indexed_sha` synchronously so the next
        clone+index pass starts from a clean slate.
      parameters:
        - name: full
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: |
            When true, clears `indexed_sha` for this repo before
            enqueueing so the next index_repo run does a full reindex
            (re-embeds every file, wipes prior chunks/symbols/refs/
            file_hashes). Use to recover from suspected drift.
      responses:
        "202":
          description: Reindex enqueued (or already running — dedupe)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ReindexEnqueuedResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/projects/{hash}/force-stop:
    parameters:
      - name: hash
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: forceStopIndex
      tags: [projects]
      summary: Force-stop an in-flight index for an external project
      description: |
        Hard-aborts the clone + index pipeline for an external
        (GitHub-cloned) project. 422 when the project is local — local
        projects index via the CLI and have no server-side pipeline to
        stop (use the CLI's own cancel/Ctrl-C).

        Two effects, both best-effort:
          1. Pending/running `clone_repo` + `index_repo` jobs for this
             repo are deleted from the queue so the pipeline cannot
             retry or resume.
          2. The active in-process index session (if any) is cancelled,
             which unblocks the next `cix index/begin` and flips the
             project status back to a terminal state.

        Already-committed chunks/symbols are NOT rolled back (matches
        the CLI's cancel semantics) — a subsequent sync/reindex
        overwrites them.
      responses:
        "202":
          description: Force-stop processed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ForceStopResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/webhooks/github/{hash}:
    parameters:
      - name: hash
        in: path
        required: true
        schema:
          type: string
        description: Project's path_hash (16 hex chars).
    post:
      operationId: receiveGithubWebhook
      tags: [projects]
      summary: Receive a GitHub webhook delivery (public, HMAC-authenticated)
      description: |
        Public endpoint — auth is bypassed. The `X-Hub-Signature-256`
        header must be HMAC-SHA256 of the request body keyed by the
        project's `git_repos.webhook_secret`. Mismatched signatures
        return 401; an unknown `hash` returns 404. On a valid `push`
        for the tracked branch the server enqueues a `clone_repo` job
        (dedupe collapses burst deliveries).

        GitHub `ping` deliveries return 200 with no side effects so
        the setup confirmation flow works.
      security: []
      parameters:
        - name: X-Hub-Signature-256
          in: header
          required: false
          schema:
            type: string
          description: HMAC-SHA256 over the body, hex-encoded with sha256= prefix.
        - name: X-GitHub-Event
          in: header
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
      responses:
        "202":
          description: Delivery accepted (enqueued or already in flight)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookAccepted"
        "200":
          description: Ping or no-op delivery
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookAccepted"
        "401":
          description: HMAC signature mismatch
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Unknown project hash
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/jobs:
    get:
      operationId: listJobs
      tags: [workspaces]
      summary: List background jobs (status / type filter)
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum: [pending, running, completed, failed]
        - name: type
          in: query
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
      responses:
        "200":
          description: Job list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/github-tokens:
    get:
      operationId: listGithubTokens
      tags: [github-tokens]
      summary: List stored GitHub PATs (metadata only)
      description: |
        Returns metadata for every stored token — name, scopes, timestamps.
        Plaintext values are NEVER returned by this endpoint; the only time
        plaintext is surfaced is the response to POST /api/v1/github-tokens.
      responses:
        "200":
          description: Token list
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GithubTokenListResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"
    post:
      operationId: createGithubToken
      tags: [github-tokens]
      summary: Store a new GitHub PAT (encrypted-at-rest)
      description: |
        Accepts a plaintext token in the request body. The server encrypts
        it with AES-GCM via internal/secrets and persists only the
        ciphertext. The response carries metadata only — the plaintext is
        already in the caller's hands. Scope validation against the GitHub
        API is deferred to a later release; PR1 stores the supplied scopes
        verbatim if any.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateGithubTokenRequest"
      responses:
        "201":
          description: Token stored
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GithubToken"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          $ref: "#/components/responses/Conflict"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/github-tokens/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    put:
      operationId: updateGithubToken
      tags: [github-tokens]
      summary: Rotate the secret of a stored GitHub PAT
      description: |
        Replaces the encrypted secret value of an existing token in place,
        keeping the same id and name. The new plaintext is validated against
        GitHub (GET /user) exactly like creation, and the stored scopes are
        refreshed from the X-OAuth-Scopes response header. Because the id is
        unchanged, every external project bound to this token keeps working —
        no re-binding required. Use this when a PAT expires or is regenerated.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateGithubTokenRequest"
      responses:
        "200":
          description: Token rotated (metadata only — plaintext is never echoed)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GithubToken"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/Unprocessable"
        "502":
          description: Could not reach GitHub to validate the token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"
    delete:
      operationId: deleteGithubToken
      tags: [github-tokens]
      summary: Delete a stored GitHub PAT
      description: |
        Permanently removes the encrypted blob. Subsequent workspaces
        operations that reference this token id will fail. The
        git_repos.token_id FK uses ON DELETE SET NULL, so existing
        rows survive token revocation but their re-clone / webhook
        flows that need GitHub auth will fail until a token is
        re-attached.
      responses:
        "204":
          description: Deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/github-tokens/{id}/accounts:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: listTokenAccounts
      tags: [github-tokens]
      summary: List the GitHub accounts visible to a stored PAT
      description: |
        Returns the PAT owner's personal account plus every organisation
        the PAT can see. The dashboard renders this as the first step of
        the add-repo flow so the operator can drill into a specific
        account before picking a repository — useful when /user/repos
        doesn't surface every org repo (e.g. SAML-protected orgs only
        appear under /orgs/{login}/repos).

        The PAT plaintext never leaves the server; the dashboard only
        addresses the token by id.
      responses:
        "200":
          description: A list of accounts (1 user + 0..N orgs)
          content:
            application/json:
              schema:
                type: object
                required: [accounts, total]
                properties:
                  accounts:
                    type: array
                    items:
                      $ref: "#/components/schemas/GithubAccount"
                  total:
                    type: integer
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          description: GitHub rejected the token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: Could not reach GitHub
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/github-tokens/{id}/repos:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: listTokenRepos
      tags: [github-tokens]
      summary: List GitHub repositories visible to a stored PAT
      description: |
        Returns the repos the PAT can see, ordered by most recently
        pushed. Used by the dashboard's add-repo flow to populate the
        repo picker.

        When `account` is omitted the response is the affiliations-
        aggregated view (GET /user/repos) — every repo the PAT can
        see as owner, collaborator, or organization member. When
        `account` is set the server hits `/users/{login}/repos` for
        a user account or `/orgs/{login}/repos` for an org, depending
        on `account_type`. Use the account-scoped call when /user/repos
        misses an org repo (typical for SAML-protected orgs).

        The PAT plaintext never leaves the server; the dashboard only
        addresses the token by id. Up to 500 repos are returned (5 pages
        of 100). Larger affiliations should rely on client-side text
        filtering or pick a more specific account.
      parameters:
        - name: q
          in: query
          required: false
          description: Optional case-insensitive substring filter on full_name.
          schema:
            type: string
        - name: account
          in: query
          required: false
          description: |
            Optional account login to scope the listing to. When set,
            `account_type` must also be set.
          schema:
            type: string
        - name: account_type
          in: query
          required: false
          description: |
            Required when `account` is set; ignored otherwise.
          schema:
            type: string
            enum: [user, org]
      responses:
        "200":
          description: A list of repositories
          content:
            application/json:
              schema:
                type: object
                required: [repos, total]
                properties:
                  repos:
                    type: array
                    items:
                      $ref: "#/components/schemas/GithubRepo"
                  total:
                    type: integer
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          description: GitHub rejected the token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "502":
          description: Could not reach GitHub
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/tunnels:
    get:
      operationId: listTunnels
      tags: [tunnels]
      summary: List tunnel providers and their status
      description: |
        Returns one entry per known provider (cloudflare, ngrok). The
        active provider carries live status; others are reported as
        unavailable / "coming soon".
      responses:
        "200":
          description: Provider catalog
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TunnelCatalog"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/tunnels/config:
    get:
      operationId: getTunnelConfig
      tags: [tunnels]
      summary: Get the dashboard-managed tunnel configuration
      description: |
        Returns the persisted tunnel config (enable/mode/hostname). The
        connector token is never returned — `token_set` reports whether one
        is stored.
      responses:
        "200":
          description: Current config
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TunnelConfig"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"
    put:
      operationId: updateTunnelConfig
      tags: [tunnels]
      summary: Update tunnel configuration and apply it
      description: |
        Persists the config and immediately applies it: enabling starts the
        tunnel, disabling stops it, changing mode/hostname/token restarts it.
        Omit `token` to keep the existing one; send an empty string to clear.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TunnelConfigUpdate"
      responses:
        "200":
          description: Applied; returns the resulting status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TunnelStatus"
        "400":
          description: Invalid configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/tunnels/binaries:
    get:
      operationId: listTunnelBinaries
      tags: [tunnels]
      summary: Agent-binary status per provider
      description: |
        Reports whether each provider's agent binary (cloudflared, ngrok) is
        present on this server, its path/version, and whether the server can
        install/update it from the UI (managed mode — set by the Docker
        images). When not installed and not managed, the dashboard shows
        manual install instructions (local runs only).
      responses:
        "200":
          description: Per-provider binary status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TunnelBinaryList"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/tunnels/binaries/{provider}/install:
    post:
      operationId: installTunnelBinary
      tags: [tunnels]
      summary: Download/install a provider's agent binary (managed mode)
      description: |
        Downloads the latest stable agent binary into the managed directory.
        Only available when binary management is enabled
        (CIX_TUNNEL_BIN_MANAGED=true); otherwise returns 409.
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
            enum: [cloudflare, ngrok]
      responses:
        "200":
          description: Installed; returns the new binary status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TunnelBinaryList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          description: Binary management is disabled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Download/install failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/tunnels/binaries/{provider}/update:
    post:
      operationId: updateTunnelBinary
      tags: [tunnels]
      summary: Update a provider's agent binary to the latest (managed mode)
      description: |
        Re-downloads the latest stable agent binary, replacing the managed
        copy. Restart the tunnel afterwards to run the new version. Only
        available when CIX_TUNNEL_BIN_MANAGED=true.
      parameters:
        - name: provider
          in: path
          required: true
          schema:
            type: string
            enum: [cloudflare, ngrok]
      responses:
        "200":
          description: Updated; returns the new binary status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TunnelBinaryList"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          description: Binary management is disabled
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Download/update failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/tunnels/status:
    get:
      operationId: getTunnelStatus
      tags: [tunnels]
      summary: Active tunnel status snapshot
      responses:
        "200":
          description: Active provider status (or disabled placeholder)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TunnelStatus"
        "401":
          $ref: "#/components/responses/Unauthorized"

  /api/v1/tunnels/test:
    post:
      operationId: testTunnel
      tags: [tunnels]
      summary: End-to-end connectivity test through the tunnel
      description: |
        Issues a GET to the tunnel's public URL + `/health`; the request
        egresses to the provider edge and routes back through the tunnel
        to this server — a true round-trip, not just a liveness check.
      responses:
        "200":
          description: Test result (ok=false when unreachable)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TunnelTestResult"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          description: No active tunnel
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/tunnels/restart:
    post:
      operationId: restartTunnel
      tags: [tunnels]
      summary: Restart the active tunnel subprocess
      responses:
        "200":
          description: Restarted; returns the new status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TunnelStatus"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "409":
          description: No active tunnel
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: Restart failed
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/v1/github/webhooks/reconcile:
    post:
      operationId: reconcileWebhooks
      tags: [tunnels]
      summary: Re-register all webhook_mode=auto repos against the current public URL
      description: |
        Re-points every `webhook_mode=auto` repository's GitHub webhook at
        the current public base URL (the live tunnel URL when present, else
        CIX_PUBLIC_URL). Idempotent. Runs automatically on boot and on
        tunnel URL changes; this endpoint triggers it manually.
      responses:
        "200":
          description: Reconcile outcome
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookReconcileResult"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "503":
          $ref: "#/components/responses/WorkspacesDisabled"

  /api/v1/github/webhooks/origin:
    get:
      operationId: getWebhookOrigin
      tags: [tunnels]
      summary: Effective public origin for GitHub webhook delivery
      description: |
        Reports the public origin that webhook delivery URLs are built
        against, and where it comes from: a live managed tunnel, the
        operator-set CIX_PUBLIC_URL (i.e. the server is made public by
        infrastructure — reverse proxy, ingress, static IP), or none.

        A managed tunnel is OPTIONAL: when CIX_PUBLIC_URL is set, webhooks
        work without any tunnel. The dashboard uses this to avoid presenting
        "no tunnel" as a problem when the origin is provided by infra.
      responses:
        "200":
          description: Effective webhook delivery origin
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookOrigin"
        "401":
          $ref: "#/components/responses/Unauthorized"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: "API key passed as `Authorization: Bearer <CIX_API_KEY>`"

  parameters:
    ProjectHash:
      name: path
      in: path
      required: true
      description: |
        First 16 hex chars of `SHA1(host_path)`. See
        `internal/projects.HashPath`.
      schema:
        type: string
        pattern: "^[a-f0-9]{16}$"
        example: "5b7d2c9e1a3f8042"

  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unprocessable:
      description: Malformed request body or missing required fields
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    BadRequest:
      description: Invalid request (missing fields, unknown kind, bad config)
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalError:
      description: Unhandled server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    IndexerUnavailable:
      description: Indexing service not configured
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: Authenticated, but lacks the required role
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Conflict:
      description: Resource already exists (e.g. email taken)
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InsufficientStorage:
      description: |
        Not enough free space to hold the compacted copy alongside the
        original. `DatabaseState.required_disk_bytes` and `free_disk_bytes`
        carry the numbers.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ResourcesUnavailable:
      description: |
        Resource accounting is not wired on this server (no config in the
        handler dependencies — happens in partial-test contexts).
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    WorkspacesDisabled:
      description: |
        Required service is not configured on this server (commonly an
        encryption-key boot failure preventing github_tokens from
        wiring, or a partial-test Deps in non-production contexts).
        Check the server logs and restart.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    Error:
      type: object
      required: [detail]
      properties:
        detail:
          type: string

    SearchStatsSettings:
      type: object
      required: [enabled, source]
      properties:
        enabled:
          type: boolean
        has_stored_counters:
          type: boolean
          description: |
            Whether a statistics database exists on this server — so whether
            there is anything to read or discard. True whenever collection is
            on; when it is off, true means counters were collected earlier and
            are still on disk, readable again by switching collection back on
            and discardable at any time via the reset endpoint.

            Sent to admins only. `enabled` and `source` are the whole of why a
            page is empty, which is why this endpoint is readable by everyone;
            whether there is a file to dispose of is operator information, and
            no control a regular user has acts on it.
        source:
          type: string
          enum: [database, environment, default]
          description: What decided the current state.
        updated_at:
          type: string
          description: |
            When an admin last changed it. Sent to admins only — when this
            server was last administered is not part of explaining why the
            page is empty. Also absent unless `source` is `database`.
        updated_by:
          type: string
          description: |
            Which admin last changed it. Sent to admins only: it is an email
            address, and a regular user reading this endpoint is asking why
            their page is empty, not who runs the server.

    SetSearchStatsSettingsRequest:
      type: object
      required: [enabled]
      properties:
        enabled:
          type: boolean

    SearchStatsFile:
      type: object
      required: [file_path, hits]
      properties:
        file_path:
          type: string
        hits:
          type: integer
          format: int64
          description: |
            How many searches this file appeared in. One per search, however
            many chunks of the file matched — so it is directly comparable to
            the project's `queries`.

    SearchStatsProject:
      type: object
      required:
        [project_path, path_hash, name, queries, results, file_hits,
         distinct_files, top_file_hits, last_seen, top_files]
      properties:
        project_path:
          type: string
          description: The project's host_path — the key the counters are stored under.
        path_hash:
          type: string
          description: |
            16-hex identifier, the same one the project and search endpoints
            take in their URLs. Present so the dashboard can link a row
            straight to the project without re-deriving it.
        name:
          type: string
          description: |
            Display name, resolved from the projects table at request time.
        kind:
          type: string
          enum: [local, external]
        queries:
          type: integer
          format: int64
        results:
          type: integer
          format: int64
          description: Total files returned across every recorded search.
        file_hits:
          type: integer
          format: int64
          description: |
            Total file appearances counted on the per-file tier. Normally equal
            to `results`, which is counted on the project tier — but not an
            integrity check, because two documented behaviours separate them by
            design: the server drops per-file detail (never query counts) when
            its pending buffer is full, and empty paths are excluded from the
            file tier while still counting toward `results`.
        distinct_files:
          type: integer
          format: int64
        top_file_hits:
          type: integer
          format: int64
          description: Hit count of the single most-returned file.
        last_seen:
          type: integer
          format: int64
          description: |
            Unix seconds of the most recent recorded search, from the
            cumulative tier — an exact instant, not a bucket floor. Zero when
            nothing has been recorded. Unaffected by `window`.
        top_files:
          type: array
          items:
            $ref: "#/components/schemas/SearchStatsFile"

    SearchStatsResponse:
      type: object
      required: [projects, total, window, bucket_seconds, retention_seconds]
      properties:
        projects:
          type: array
          items:
            $ref: "#/components/schemas/SearchStatsProject"
        total:
          type: integer
          description: |
            How many projects matched the filters before `limit`/`offset` —
            what the pagination control needs.
        window:
          type: string
          description: The window that was applied, echoed back.
        bucket_seconds:
          type: integer
          description: Resolution of the windowed tier.
        retention_seconds:
          type: integer
          description: |
            How far back the windowed tier keeps data. A `window` longer than
            this is silently clamped, because nothing older exists.
        projects_without_activity:
          type: integer
          description: |
            Accessible projects that have never been searched, and so have no
            row above. Reported rather than padded in as zero rows: they would
            otherwise dominate the first page of any ascending sort.
        totals:
          $ref: "#/components/schemas/SearchStatsTotals"

    SearchStatsTotals:
      type: object
      required: [queries, results]
      description: |
        Sums across every project the caller can see and the current filters —
        not just the page.
      properties:
        queries:
          type: integer
          format: int64
        results:
          type: integer
          format: int64

    SearchStatsSeriesPoint:
      type: object
      required: [bucket, queries]
      properties:
        bucket:
          type: integer
          format: int64
          description: Unix seconds of the bucket's start.
        queries:
          type: integer
          format: int64

    SearchStatsSeriesResponse:
      type: object
      required: [points, bucket_seconds, window_seconds]
      properties:
        points:
          type: array
          items:
            $ref: "#/components/schemas/SearchStatsSeriesPoint"
        bucket_seconds:
          type: integer
        window_seconds:
          type: integer

    BootstrapStatusResponse:
      type: object
      required: [needs_bootstrap]
      properties:
        needs_bootstrap:
          type: boolean
          description: True when the users table is empty.

    User:
      type: object
      required: [id, email, role, must_change_password, created_at, updated_at, disabled, local_project_disabled]
      properties:
        id:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user]
        must_change_password:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        disabled:
          type: boolean
          description: |
            True when `disabled_at` is set. Disabled users cannot
            authenticate via password OR API key.
        disabled_at:
          type: string
          format: date-time
          nullable: true
        local_project_disabled:
          type: boolean
          description: |
            When true, the user may not create local projects or
            index/reindex any project (both return 403). Search of
            already-indexed projects and workspace creation remain
            allowed. Admins are always exempt regardless of this flag.
            Defaults to false; existing users created before this field
            was introduced are false (allowed) for backward compatibility.

    UserWithStats:
      allOf:
        - $ref: "#/components/schemas/User"
        - type: object
          required: [active_sessions_count, api_keys_count]
          properties:
            last_login_at:
              type: string
              format: date-time
              nullable: true
              description: |
                Most recent session creation timestamp (RFC3339).
                Null if the user has never logged in.
            active_sessions_count:
              type: integer
              minimum: 0
              description: Count of non-expired sessions for this user.
            api_keys_count:
              type: integer
              minimum: 0
              description: Count of non-revoked API keys owned by this user.

    UserListResponse:
      type: object
      required: [users, total]
      properties:
        users:
          type: array
          items:
            $ref: "#/components/schemas/UserWithStats"
        total:
          type: integer

    LoginRequest:
      type: object
      required: [email, password]
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          minLength: 1

    LoginResponse:
      type: object
      required: [user]
      properties:
        user:
          $ref: "#/components/schemas/User"

    MeResponse:
      type: object
      required: [user, auth_method, groups]
      properties:
        user:
          $ref: "#/components/schemas/User"
        auth_method:
          type: string
          enum: [session, api_key]
          description: |
            Tells the dashboard whether to surface "logout" (session) or
            hide it (api_key access — there's nothing to log out of).
        groups:
          type: array
          description: |
            View-groups the caller belongs to. Lets the dashboard scope the
            "share to group" picker without a second round-trip. Empty for a
            user in no groups; admins still only list their own memberships
            here (the full group list comes from GET /groups).
          items:
            $ref: "#/components/schemas/Group"

    ChangePasswordRequest:
      type: object
      required: [current_password, new_password]
      properties:
        current_password:
          type: string
          minLength: 1
        new_password:
          type: string
          minLength: 8
          description: Minimum 8 characters. No upper bound.

    CreateUserRequest:
      type: object
      required: [email, initial_password, role]
      properties:
        email:
          type: string
          format: email
        initial_password:
          type: string
          minLength: 8
          description: |
            One-time password the new user must change on first login.
            The admin shares this out-of-band.
        role:
          type: string
          enum: [admin, user]

    ResetUserPasswordRequest:
      type: object
      required: [new_password]
      properties:
        new_password:
          type: string
          minLength: 8
          description: |
            One-time password the user must change on next login.
            The admin shares this out-of-band.

    LoginLock:
      type: object
      required: [type, ip, attempts, limit, expires_at]
      properties:
        type:
          type: string
          enum: [ip, ip_email]
          description: |
            `ip` — the per-IP horizontal-sweep counter (many emails from one
            source). `ip_email` — the per-(IP, email) counter for one account.
        ip:
          type: string
          description: Source IP the lock is keyed on.
        email:
          type: string
          description: Lower-cased email; present only for type `ip_email`.
        attempts:
          type: integer
          description: Attempts currently inside the sliding window.
        limit:
          type: integer
          description: The cap that tripped the lock.
        expires_at:
          type: string
          format: date-time
          description: RFC3339 — when the oldest attempt ages out and a slot frees.

    LoginLockListResponse:
      type: object
      required: [locks, total]
      properties:
        locks:
          type: array
          items:
            $ref: "#/components/schemas/LoginLock"
        total:
          type: integer

    ResetLoginLockRequest:
      type: object
      required: [type, ip]
      properties:
        type:
          type: string
          enum: [ip, ip_email]
          description: Which counter to clear — matches the `type` from the list.
        ip:
          type: string
          description: Source IP of the lock to clear.
        email:
          type: string
          description: Required when `type` is `ip_email`; ignored otherwise.

    UpdateUserRequest:
      type: object
      properties:
        role:
          type: string
          enum: [admin, user]
          description: |
            New role for the user. Refused for the last enabled admin
            when set to `user`.
        disabled:
          type: boolean
          description: |
            When true, the user can no longer authenticate. Refused for
            the last enabled admin when set to true.
        local_project_disabled:
          type: boolean
          description: |
            When true, the user may not create local projects or
            index/reindex any project. Search and workspace creation stay
            allowed; admins are always exempt. Has no last-admin guard.

    RuntimeConfig:
      type: object
      required:
        - embedding_model
        - llama_ctx_size
        - llama_n_gpu_layers
        - llama_n_threads
        - max_embedding_concurrency
        - llama_batch_size
        - index_embed_batch_chunks
        - chunk_max_concurrent
        - llama_cache_ram_mib
        - source
      properties:
        embedding_model:
          type: string
          description: HF repo ID or absolute filesystem path to a .gguf file.
        llama_ctx_size:
          type: integer
          minimum: 1
        llama_n_gpu_layers:
          type: integer
          description: -1 = all layers (Metal/CUDA), 0 = CPU only.
        llama_n_threads:
          type: integer
          minimum: 0
          description: 0 = let llama-server auto-detect.
        max_embedding_concurrency:
          type: integer
          minimum: 1
        llama_batch_size:
          type: integer
          minimum: 1
        index_embed_batch_chunks:
          type: integer
          minimum: 0
          description: Cross-file embed-batch size for repo indexing (chunks per embed call). 0 = one call per file.
        chunk_max_concurrent:
          type: integer
          minimum: 0
          description: Chunker (tree-sitter wasm) instance-concurrency cap, decoupled from embedding concurrency. Each instance holds ~69 MiB. 0 = recommended (3).
        llama_cache_ram_mib:
          type: integer
          minimum: -1
          description: llama-server host prompt-cache cap in MiB (--cache-ram). 0 = disabled (recommended for embeddings — prompts are never reused, and llama's upstream 8 GiB default grows RSS until the container OOMs), -1 = unlimited.
        source:
          type: object
          additionalProperties:
            type: string
            enum: [db, env, recommended]
          description: |
            Per-field origin label so the dashboard can render a "DB" /
            "Env" / "Recommended" pill next to each value. Keys match the
            other field names: `embedding_model`, `llama_ctx_size`, ...
        recommended:
          $ref: "#/components/schemas/RuntimeConfigRecommended"
        updated_at:
          type: string
          format: date-time
          nullable: true
          description: When the runtime_settings row was last written, or null when only env/recommended are in effect.
        updated_by:
          type: string
          nullable: true
          description: Who issued the last PUT, captured from the active session.

    RuntimeConfigRecommended:
      type: object
      required:
        - embedding_model
        - llama_ctx_size
        - llama_n_gpu_layers
        - llama_n_threads
        - max_embedding_concurrency
        - llama_batch_size
        - index_embed_batch_chunks
        - chunk_max_concurrent
        - llama_cache_ram_mib
      properties:
        embedding_model: { type: string }
        llama_ctx_size: { type: integer }
        llama_n_gpu_layers: { type: integer }
        llama_n_threads: { type: integer }
        max_embedding_concurrency: { type: integer }
        llama_batch_size: { type: integer }
        index_embed_batch_chunks: { type: integer }
        chunk_max_concurrent: { type: integer }
        llama_cache_ram_mib: { type: integer }

    RuntimeConfigUpdate:
      type: object
      description: |
        All fields optional. Send a value to set/replace the override for
        that field, send `""` (string fields) or `0` (numeric fields) to
        CLEAR the override (next read falls back to env / recommended).
        Omitted fields keep their current value.
      properties:
        embedding_model:
          type: string
          nullable: true
        llama_ctx_size:
          type: integer
          nullable: true
        llama_n_gpu_layers:
          type: integer
          nullable: true
        llama_n_threads:
          type: integer
          nullable: true
        max_embedding_concurrency:
          type: integer
          nullable: true
        llama_batch_size:
          type: integer
          nullable: true
        index_embed_batch_chunks:
          type: integer
          nullable: true
        chunk_max_concurrent:
          type: integer
          nullable: true
        llama_cache_ram_mib:
          type: integer
          nullable: true
          description: MiB; 0 clears the override (falls back to env / recommended = disabled), -1 = unlimited.

    SidecarStatus:
      type: object
      required: [state, ready, in_flight]
      properties:
        state:
          type: string
          enum: [running, starting, restarting, failed, disabled]
        pid:
          type: integer
          minimum: 0
          description: 0 when no child process is alive (failed / disabled).
        uptime_seconds:
          type: integer
          minimum: 0
        model:
          type: string
        ready:
          type: boolean
        last_error:
          type: string
        in_flight:
          type: integer
          minimum: 0
          description: Embedding queue depth at the moment of sampling.
        restart_in_flight:
          type: boolean
          description: True between accept of POST /sidecar/restart and respawn completion.

    RestartAccepted:
      type: object
      required: [restart_id]
      properties:
        restart_id:
          type: string
          description: Opaque ID; future versions may expose per-restart progress under this id.

    ModelEntry:
      type: object
      required: [id, path, size_bytes]
      properties:
        id:
          type: string
          description: HF repo ID derived from the cache directory name (e.g. owner/model).
        path:
          type: string
          description: Absolute path to the .gguf file on disk.
        size_bytes:
          type: integer
          format: int64
          minimum: 0

    ModelList:
      type: object
      required: [models, cache_dir]
      properties:
        models:
          type: array
          items:
            $ref: "#/components/schemas/ModelEntry"
        cache_dir:
          type: string
          description: The CIX_GGUF_CACHE_DIR that was scanned. Empty list with non-empty cache_dir = no .gguf files found.

    MemoryUsage:
      type: object
      required:
        [
          heap_alloc_bytes,
          heap_inuse_bytes,
          heap_idle_bytes,
          heap_released_bytes,
          sys_bytes,
          num_gc,
          num_goroutine,
        ]
      description: |
        Go runtime memory. heap_alloc_bytes is the meaningful figure for this
        server: the vector store lives entirely in the heap, so it tracks the
        size of the loaded index. sys_bytes and rss_bytes run higher because
        the runtime holds freed spans before returning them to the OS.
      properties:
        heap_alloc_bytes: { type: integer, format: int64, minimum: 0 }
        heap_inuse_bytes: { type: integer, format: int64, minimum: 0 }
        heap_idle_bytes: { type: integer, format: int64, minimum: 0 }
        heap_released_bytes: { type: integer, format: int64, minimum: 0 }
        sys_bytes: { type: integer, format: int64, minimum: 0 }
        num_gc: { type: integer, format: int64, minimum: 0 }
        num_goroutine: { type: integer, minimum: 0 }
        rss_bytes:
          type: integer
          format: int64
          description: |
            Current resident set size. Absent where it cannot be read without
            cgo (macOS keeps it behind mach's task_info) — render "n/a", never
            treat a missing field as zero.
        peak_rss_bytes:
          type: integer
          format: int64
          description: |
            High-water resident set size from getrusage. Available on Linux and
            macOS. It only ever rises, so it must be labelled as a peak and
            never substituted for rss_bytes.

    DiskUsage:
      type: object
      required: [id, label, path, exists]
      properties:
        id:
          type: string
          enum: [sqlite, chroma, repos, gguf]
        label: { type: string }
        path: { type: string }
        exists: { type: boolean }
        used_bytes:
          type: integer
          format: int64
          description: |
            Size of the tree. Absent when it could not be walked, which keeps
            "unreadable" distinguishable from "empty". The SQLite entry
            includes the -wal and -shm sidecars.
        partial:
          type: boolean
          description: |
            True when used_bytes undercounts because some entries inside the
            tree were unreadable and skipped. Absent means the sum is
            complete.
        fs_total_bytes: { type: integer, format: int64 }
        fs_free_bytes: { type: integer, format: int64 }

    VectorStoreUsage:
      type: object
      required: [collections, documents, active_namespace_path]
      description: Resident vector-store totals, read from memory — no I/O.
      properties:
        collections: { type: integer, minimum: 0 }
        documents: { type: integer, format: int64, minimum: 0 }
        active_namespace_path: { type: string }

    ResourceUsage:
      type: object
      required: [generated_at, memory, disks, vector_store]
      properties:
        generated_at: { type: string, format: date-time }
        memory: { $ref: "#/components/schemas/MemoryUsage" }
        disks:
          type: array
          items: { $ref: "#/components/schemas/DiskUsage" }
        vector_store: { $ref: "#/components/schemas/VectorStoreUsage" }

    ReclaimCategoryId:
      type: string
      enum:
        [
          orphan_collections,
          orphan_repos,
          stale_namespaces,
          legacy_chromem,
          stale_jobs,
          unused_models,
        ]

    ReclaimItem:
      type: object
      required: [key, label, size_bytes]
      properties:
        key:
          type: string
          description: Server-side identity — collection name, path_hash, directory or model file.
        label: { type: string }
        detail: { type: string }
        size_bytes: { type: integer, format: int64, minimum: 0 }

    ReclaimCategory:
      type: object
      required:
        [
          id,
          label,
          description,
          item_count,
          size_bytes,
          default_selected,
          destructive,
          items,
          items_truncated,
        ]
      properties:
        id: { $ref: "#/components/schemas/ReclaimCategoryId" }
        label: { type: string }
        description:
          type: string
          description: |
            Server-authored explanation, including why a category is disabled
            when it is. Render it as-is; the reasoning lives on the server so
            the rules are decided in one place.
        item_count:
          type: integer
          minimum: 0
          description: Total items found — may exceed the length of `items`.
        size_bytes: { type: integer, format: int64, minimum: 0 }
        estimated_ram_bytes:
          type: integer
          format: int64
          deprecated: true
          x-deprecated-reason: >-
            Always absent since the vector store moved off the Go heap; kept
            for wire compatibility with older dashboard builds and slated for
            removal in the next breaking API revision.
          description: |
            Deprecated, and always absent. It reported heap attributable to
            these items back when the vector store held every document in
            memory; nothing has set it since the store moved to SQLite, whose
            footprint is not proportional to what it holds. Kept in the schema
            only so an older dashboard build does not break on a missing field,
            and a candidate for removal in the next breaking API revision.
            Clients must not display it.
        default_selected:
          type: boolean
          description: Whether the dashboard should pre-tick this category.
        destructive:
          type: boolean
          description: Expensive or impossible to regenerate; the confirm dialog warns extra.
        items:
          type: array
          description: A sample for display, capped server-side. Cleaning always acts on the full set.
          items: { $ref: "#/components/schemas/ReclaimItem" }
        items_truncated: { type: boolean }

    ReclaimAnalysis:
      type: object
      required:
        [
          analysis_id,
          generated_at,
          expires_at,
          duration_ms,
          total_reclaimable_bytes,
          categories,
        ]
      properties:
        analysis_id: { type: string }
        generated_at: { type: string, format: date-time }
        expires_at: { type: string, format: date-time }
        duration_ms: { type: integer, minimum: 0 }
        total_reclaimable_bytes: { type: integer, format: int64, minimum: 0 }
        categories:
          type: array
          items: { $ref: "#/components/schemas/ReclaimCategory" }
        warnings:
          type: array
          description: Non-fatal problems, e.g. a directory that could not be read.
          items: { type: string }

    CleanRequest:
      type: object
      required: [analysis_id, categories]
      properties:
        analysis_id: { type: string }
        categories:
          type: array
          minItems: 1
          items: { $ref: "#/components/schemas/ReclaimCategoryId" }

    CleanOutcome:
      type: object
      required: [key, reason]
      properties:
        key: { type: string }
        reason: { type: string }

    CleanCategoryResult:
      type: object
      required:
        [id, deleted_count, skipped_count, failed_count, reclaimed_bytes]
      properties:
        id: { $ref: "#/components/schemas/ReclaimCategoryId" }
        deleted_count: { type: integer, minimum: 0 }
        skipped_count:
          type: integer
          minimum: 0
          description: Re-validation at delete time said it was no longer safe.
        failed_count: { type: integer, minimum: 0 }
        reclaimed_bytes: { type: integer, format: int64, minimum: 0 }
        skipped:
          type: array
          items: { $ref: "#/components/schemas/CleanOutcome" }
        failures:
          type: array
          items: { $ref: "#/components/schemas/CleanOutcome" }

    CleanResult:
      type: object
      required:
        [started_at, finished_at, duration_ms, reclaimed_bytes, categories]
      properties:
        started_at: { type: string, format: date-time }
        finished_at: { type: string, format: date-time }
        duration_ms: { type: integer, minimum: 0 }
        reclaimed_bytes: { type: integer, format: int64, minimum: 0 }
        categories:
          type: array
          items: { $ref: "#/components/schemas/CleanCategoryResult" }

    DatabaseState:
      type: object
      required:
        [
          path,
          file_bytes,
          wal_bytes,
          page_size,
          page_count,
          freelist_pages,
          reclaimable_bytes,
          reclaimable_percent,
          auto_vacuum,
          verdict,
          verdict_reason,
          free_disk_bytes,
          required_disk_bytes,
          estimated_seconds,
        ]
      properties:
        path: { type: string }
        file_bytes: { type: integer, format: int64, minimum: 0 }
        wal_bytes:
          type: integer
          format: int64
          minimum: 0
          description: |
            Size of the `-wal` sidecar. Large on its own is not a problem —
            it is checkpointed automatically — but it is the cheapest thing
            to reclaim when it is not.
        page_size: { type: integer, minimum: 0 }
        page_count: { type: integer, format: int64, minimum: 0 }
        freelist_pages:
          type: integer
          format: int64
          minimum: 0
          description: Pages that are allocated but hold no data.
        reclaimable_bytes:
          type: integer
          format: int64
          minimum: 0
          description: "`freelist_pages` × `page_size` — waste, not a projection of the final size."
        reclaimable_percent: { type: number, minimum: 0, maximum: 100 }
        auto_vacuum:
          type: string
          enum: [none, incremental, full]
          description: |
            Read live from the database file, never from stored settings, so
            it is correct on any server regardless of how it got here.
        verdict:
          type: string
          enum: [ok, recommended, urgent]
        verdict_reason:
          type: string
          description: One sentence explaining the verdict, safe to render as-is.
        free_disk_bytes: { type: integer, format: int64, minimum: 0 }
        required_disk_bytes:
          type: integer
          format: int64
          minimum: 0
          description: |
            Room a compaction needs: the copy is written alongside the
            original, so both exist at once.
        estimated_seconds:
          type: integer
          minimum: 0
          description: |
            Estimated copy time, excluding the restart. Derived from the
            database size and a measured throughput figure, so it is an
            order-of-magnitude guide rather than a promise.
        blocked_reason:
          type: string
          nullable: true
          description: |
            Why compaction cannot start right now — an in-flight clone or
            index job, insufficient disk, or an operation already running.
            Null when it can start.
        operation:
          allOf: [{ $ref: "#/components/schemas/MaintenanceOperation" }]
          nullable: true
          description: The running or most recent operation, if any.

    AutoVacuumRequest:
      type: object
      required: [mode]
      properties:
        mode:
          type: string
          enum: [none, incremental]

    MaintenanceOperation:
      type: object
      required: [run_id, kind, phase]
      properties:
        run_id:
          type: string
          description: |
            Identifies one attempt. It changes on every run, so a client can
            tell a fresh operation from a stale state file left by a process
            that did not survive.
        kind:
          type: string
          enum: [compact, reclaim, checkpoint]
        phase:
          type: string
          enum:
            [
              idle,
              preparing,
              copying,
              ready_to_swap,
              swapping,
              restarting,
              done,
              failed,
              interrupted,
            ]
          description: |
            `preparing` is draining background work; `copying` is the
            read-only window; `ready_to_swap` onwards happens around and
            during the restart. `interrupted` is a previous run that did not
            finish — the database was brought back to a consistent state and
            the operation can simply be re-run.
        started_at:
          type: string
          format: date-time
          nullable: true
          description: |
            Absent when nothing has run. A zero date would read as a bug
            rather than as "nothing has happened".
        finished_at: { type: string, format: date-time, nullable: true }
        bytes_total:
          type: integer
          format: int64
          nullable: true
          description: Expected size of the copy, for a progress bar.
        bytes_done: { type: integer, format: int64, nullable: true }
        percent: { type: number, minimum: 0, maximum: 100, nullable: true }
        freed_bytes: { type: integer, format: int64, nullable: true }
        auto_vacuum:
          type: string
          enum: [none, incremental, full]
          nullable: true
          description: |
            The reclaim mode this run leaves the database in. `full` never
            appears on a request — it cannot be set through this API — but a
            compaction of a database already in that mode preserves it, and
            says so here.
        message:
          type: string
          nullable: true
          description: Human-readable description of the current step.
        error: { type: string, nullable: true }
        events:
          type: array
          description: |
            Ordered trail of what happened, most recent last. Appended to a
            file beside the database, so it spans the restart that the
            operation performs — the server log alone is split across two
            process lifetimes, and the interesting half is usually the one
            that did not come back. Truncated to the most recent entries;
            the full trail stays on disk.
          items:
            $ref: "#/components/schemas/MaintenanceEvent"

    MaintenanceEvent:
      type: object
      required: [at, level, phase, message]
      properties:
        at: { type: string, format: date-time }
        level: { type: string, enum: [info, warn, error] }
        phase: { type: string }
        message: { type: string }

    ReclaimRequest:
      type: object
      properties:
        max_pages:
          type: integer
          minimum: 1
          description: |
            Upper bound on pages returned to the filesystem in this call.
            Omit to drain the whole freelist. Bounding it keeps the write
            lock short on a database with a very large freelist.

    ReclaimResult:
      type: object
      required: [pages_freed, bytes_freed, file_bytes, freelist_pages]
      properties:
        pages_freed: { type: integer, format: int64, minimum: 0 }
        bytes_freed: { type: integer, format: int64, minimum: 0 }
        file_bytes: { type: integer, format: int64, minimum: 0 }
        freelist_pages:
          type: integer
          format: int64
          minimum: 0
          description: What is left on the freelist after this call.

    ScheduledTask:
      type: object
      required: [name, title, cron, enabled, configured, catch_up, next_runs, last_run_at]
      properties:
        name:
          type: string
          description: |
            Stable identifier, used as the path parameter. It outlives renames
            of whatever implements the task.
        title: { type: string }
        description: { type: string }
        cron:
          type: string
          description: |
            Standard five-field crontab expression, in the server's local
            timezone. `@daily` and friends are accepted.
        enabled: { type: boolean }
        configured:
          type: boolean
          description: |
            False while the task is still on its built-in or environment
            default, i.e. nobody has chosen this schedule.
        catch_up:
          type: boolean
          description: |
            Whether a slot missed while the server was down runs late. False
            follows crontab exactly; true is reserved for tasks cheap enough
            that skipping them entirely would be worse.
        next_runs:
          type: array
          description: |
            The next few runs, computed server-side by the parser that fires
            them. Empty when the task is disabled.
          items: { type: string, format: date-time }
        last_run_at: { type: string, format: date-time, nullable: true }
        last_status:
          type: string
          enum: [running, ok, failed, interrupted]
          description: |
            `interrupted` is a run the server did not survive — the status is
            written before the handler and cleared after it, so anything still
            marked running at startup belongs to a process that did not return.
        last_error: { type: string }
        last_millis: { type: integer, format: int64 }
        updated_by:
          type: string
          description: Who last saved this schedule. Absent while it is still on a default.
        running:
          type: boolean
          description: True while the task's handler is executing.

    ScheduleUpdate:
      type: object
      description: Absent fields are left unchanged.
      properties:
        cron: { type: string }
        enabled: { type: boolean }


    EmbeddingProviderList:
      type: object
      required: [providers]
      properties:
        providers:
          type: array
          items:
            $ref: "#/components/schemas/EmbeddingProviderInfo"

    EmbeddingProviderInfo:
      type: object
      required: [kind, schema, secret_envs]
      properties:
        kind:
          type: string
          enum: [ollama, openai, voyage]
        schema:
          type: object
          description: |
            ConfigSchema as JSON — describes the form fields the
            provider accepts. Shape is `{fields: [{name, label, kind,
            required, default, enum, description}]}`. Hardcoded React
            forms ignore this; it's exposed for external tooling.
          additionalProperties: true
        secret_envs:
          type: array
          description: |
            Env-var names this provider reads for credentials, with a
            flag telling whether each is currently set on the server.
            Used by the dashboard to render the missing-key banner
            before save.
          items:
            $ref: "#/components/schemas/EmbeddingProviderSecretEnv"

    EmbeddingProviderSecretEnv:
      type: object
      required: [name, set]
      properties:
        name:
          type: string
          description: Env-var name (e.g. `CIX_VOYAGE_API_KEY`).
        set:
          type: boolean
          description: True when the env var is present (and non-empty) on the server.

    ActiveEmbeddingProvider:
      type: object
      required: [kind, id]
      properties:
        kind:
          type: string
          enum: [ollama, openai, voyage]
        id:
          type: string
          description: |
            `Provider.ID()` fingerprint, e.g. `voyage:voyage-code-3:1024:float`.
            Matches `embedding_model` on /status.
        config:
          type: object
          description: |
            Persisted provider config blob. Shape varies by kind; API
            keys are NOT stored — only env-var names are.
          additionalProperties: true

    SwitchEmbeddingProviderRequest:
      type: object
      required: [kind, config]
      properties:
        kind:
          type: string
          enum: [ollama, openai, voyage]
        config:
          type: object
          additionalProperties: true

    TestEmbeddingProviderResponse:
      type: object
      required: [ok]
      properties:
        ok:
          type: boolean
        dimension:
          type: integer
          minimum: 0
          description: |
            Embedding dimension as reported by the provider after
            Start. 0 when the provider learns the dimension lazily.

    Session:
      type: object
      required: [id, created_at, expires_at, last_seen_at, is_current]
      properties:
        id:
          type: string
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        last_seen_at:
          type: string
          format: date-time
        last_seen_ip:
          type: string
          nullable: true
        last_seen_ua:
          type: string
          nullable: true
        is_current:
          type: boolean
          description: True for the session carrying this request.

    SessionListResponse:
      type: object
      required: [sessions, total]
      properties:
        sessions:
          type: array
          items:
            $ref: "#/components/schemas/Session"
        total:
          type: integer

    ApiKey:
      type: object
      required: [id, owner_user_id, name, prefix, created_at, revoked]
      properties:
        id:
          type: string
        owner_user_id:
          type: string
        name:
          type: string
        prefix:
          type: string
          description: |
            Display-only prefix of the full key (e.g. `cix_a1b2c3d4`).
            Long enough to recognise in lists, short enough that it
            cannot reconstruct the original.
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
          nullable: true
        last_used_ip:
          type: string
          nullable: true
        last_used_ua:
          type: string
          nullable: true
        revoked:
          type: boolean
        revoked_at:
          type: string
          format: date-time
          nullable: true

    ApiKeyListResponse:
      type: object
      required: [api_keys, total]
      properties:
        api_keys:
          type: array
          items:
            $ref: "#/components/schemas/ApiKey"
        total:
          type: integer

    CreateApiKeyRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
          description: |
            Human-friendly label shown in the dashboard. The full key
            value is generated server-side and returned exactly once.

    ApiKeyCreated:
      type: object
      required: [api_key, full_key]
      properties:
        api_key:
          $ref: "#/components/schemas/ApiKey"
        full_key:
          type: string
          description: |
            The plaintext key value. **Returned exactly once.** Store it
            securely — there is no way to retrieve it later.

    HealthResponse:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [ok, unhealthy]
        reason:
          type: string
          description: Set only when `status` is `unhealthy`.

    StatusResponse:
      type: object
      required:
        - status
        - backend
        - server_version
        - api_version
        - model_loaded
        - embedding_model
        - projects
        - active_indexing_jobs
      properties:
        status:
          type: string
          enum: [ok]
        backend:
          type: string
          description: Backend identifier (e.g. `go`).
        server_version:
          type: string
        api_version:
          type: string
          example: v1
        model_loaded:
          type: boolean
          description: |
            Whether the llama-server sidecar reports ready within 500 ms.
            False when the sidecar is starting or has crashed.
        embedding_model:
          type: string
          description: |
            Active provider fingerprint — formerly the HuggingFace repo id,
            now `Provider.ID()` e.g. `ollama:CodeRankEmbed`,
            `openai:text-embedding-3-small`, `voyage:voyage-code-3:1024:float`.
            Used by the dashboard to compare against each project's
            `indexed_with_model` and render the stale-model badge.
        embedding_provider:
          type: string
          description: |
            Active provider kind: `ollama`, `openai`, or `voyage`. Empty
            when the embedding service is disabled or the fake fixtures
            substitute a non-Service implementation.
        embedding_provider_manages_process:
          type: boolean
          description: |
            True when the active provider owns an in-process child
            (currently only `ollama`). The footer renders a green/red
            liveness dot when true, and a permanent green dot otherwise
            (HTTP-only providers have no process to die — Ready failures
            surface at request time, not on every footer poll).
        projects:
          type: integer
          minimum: 0
          description: Total registered projects.
        active_indexing_jobs:
          type: integer
          minimum: 0
          description: Currently-running `index_runs` rows.
        update_available:
          type: boolean
          description: |
            True when the version-check service has found a `server/v*`
            release on GitHub strictly newer than the running server.
            Field is omitted entirely when version-check is not wired
            (set `CIX_VERSION_CHECK_ENABLED=false` to disable polling).
        latest_version:
          type: string
          nullable: true
          description: |
            Latest released server version (without the `server/v` prefix,
            e.g. `0.5.1`). Null until the first successful poll completes.
        release_url:
          type: string
          nullable: true
          description: GitHub release page URL for `latest_version`. Null when unknown.
        version_check:
          $ref: "#/components/schemas/VersionCheckStatus"

    VersionCheckStatus:
      type: object
      required: [enabled]
      properties:
        enabled:
          type: boolean
          description: Whether the periodic GitHub poll is running.
        checked_at:
          type: string
          format: date-time
          nullable: true
          description: Last poll timestamp (UTC, RFC 3339). Null before the first poll.
        error:
          type: string
          nullable: true
          description: Last error message, if the most recent poll failed. Null on success.

    ProjectSettings:
      type: object
      required: [exclude_patterns, max_file_size]
      properties:
        exclude_patterns:
          type: array
          items: { type: string }
        max_file_size:
          type: integer
          minimum: 0

    ProjectStats:
      type: object
      required: [total_files, indexed_files, total_chunks, total_symbols]
      properties:
        total_files:
          type: integer
          minimum: 0
        indexed_files:
          type: integer
          minimum: 0
        total_chunks:
          type: integer
          minimum: 0
        total_symbols:
          type: integer
          minimum: 0

    Project:
      type: object
      required:
        - path_hash
        - host_path
        - container_path
        - languages
        - settings
        - stats
        - status
        - created_at
        - updated_at
        - last_indexed_at
        # owner_user_id is required-but-nullable so external (ownerless)
        # projects serialize as `"owner_user_id": null` rather than the
        # field being absent. Lets TS clients use `string | null` instead
        # of `string | undefined`.
        - owner_user_id
      properties:
        path_hash:
          type: string
          pattern: "^[a-f0-9]{16}$"
          description: First 16 hex chars of SHA1(host_path) — stable URL identifier.
        host_path:
          type: string
          description: Absolute filesystem path on the operator's machine.
        container_path:
          type: string
          description: Path inside the container (often equal to host_path).
        languages:
          type: array
          items: { type: string }
        settings:
          $ref: "#/components/schemas/ProjectSettings"
        stats:
          $ref: "#/components/schemas/ProjectStats"
        status:
          type: string
          enum: [created, indexing, indexed, error]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        last_indexed_at:
          type: string
          format: date-time
          nullable: true
        indexed_with_model:
          type: string
          nullable: true
          description: |
            Embedding model identifier active when this project was last
            (re)indexed. NULL on rows that pre-date drift tracking — the
            dashboard treats NULL as "Unknown" rather than as drift.
        owner_user_id:
          type: string
          nullable: true
          description: |
            User who owns this personal (locally indexed) project. NULL means
            ownerless — the canonical state for EXTERNAL projects (those with a
            git_repos peer), which are admin-administered and reachable only via
            a view-group share.
        display_path:
          type: string
          description: |
            Human-readable path. The real filesystem path for local projects,
            the github path for external ones. host_path is the identity key
            (namespaced per machine for locals) — clients should show this.
        machine_id:
          type: string
          nullable: true
          description: Per-machine UUID a local project was indexed on. NULL for external/legacy.
        machine_label:
          type: string
          nullable: true
          description: os.Hostname() of the indexing machine — display only.
        full_sync_required:
          type: boolean
          description: |
            True when this project's index is format-stale (e.g. the
            chunker/embedding format changed under it) and needs a complete
            rebuild. Informational only — it drives the dashboard "out of sync"
            badge; the admin triggers the resync, which clears the flag on the
            next successful full run. Absent/false means in sync.
        full_sync_reason:
          type: string
          nullable: true
          description: |
            Human-readable explanation shown with the out-of-sync badge.
            NULL when full_sync_required is false.
        sqlite_path:
          type: string
          nullable: true
          description: Resolved SQLite database path for the active model. NULL on dashboards that don't expose storage info.
        chroma_path:
          type: string
          nullable: true
          description: |
            Path of the SQLite vector database holding this project's
            collection. NULL when not computed.
        sqlite_size_bytes:
          type: integer
          format: int64
          nullable: true
          minimum: 0
        chroma_size_bytes:
          type: integer
          format: int64
          nullable: true
          minimum: 0

    ProjectListResponse:
      type: object
      required: [projects, total]
      properties:
        projects:
          type: array
          items:
            $ref: "#/components/schemas/Project"
        total:
          type: integer
          minimum: 0

    CreateProjectRequest:
      type: object
      required: [host_path]
      properties:
        host_path:
          type: string
          description: The real filesystem path being registered (becomes display_path).
        machine_id:
          type: string
          description: |
            Per-machine UUID supplied by the CLI (from ~/.cix/machine_id). When
            present the project is LOCAL and its identity key is namespaced
            local:{machine_id}:{host_path} so the same path on different
            machines/users does not collide. Omit for external repos.
        machine_label:
          type: string
          description: os.Hostname() of the indexing machine — display only.

    UpdateProjectRequest:
      type: object
      properties:
        settings:
          $ref: "#/components/schemas/ProjectSettings"

    DirEntry:
      type: object
      required: [path, file_count]
      properties:
        path:
          type: string
        file_count:
          type: integer
          minimum: 0

    SymbolEntry:
      type: object
      required: [name, kind, file_path, language]
      properties:
        name:
          type: string
        kind:
          type: string
        file_path:
          type: string
        language:
          type: string

    ProjectSummary:
      type: object
      required:
        - path_hash
        - host_path
        - status
        - languages
        - total_files
        - total_chunks
        - total_symbols
        - top_directories
        - recent_symbols
      properties:
        path_hash:
          type: string
          pattern: "^[a-f0-9]{16}$"
          description: First 16 hex chars of SHA1(host_path) — stable URL identifier.
        host_path:
          type: string
        status:
          type: string
        languages:
          type: array
          items: { type: string }
        total_files:
          type: integer
          minimum: 0
        total_chunks:
          type: integer
          minimum: 0
        total_symbols:
          type: integer
          minimum: 0
        top_directories:
          type: array
          items:
            $ref: "#/components/schemas/DirEntry"
        recent_symbols:
          type: array
          items:
            $ref: "#/components/schemas/SymbolEntry"

    SymbolSearchRequest:
      type: object
      required: [query]
      properties:
        query:
          type: string
          minLength: 1
        kinds:
          type: array
          items: { type: string }
        limit:
          type: integer
          minimum: 0
          default: 20

    SymbolResultItem:
      type: object
      required: [name, kind, file_path, line, end_line, language]
      properties:
        name: { type: string }
        kind: { type: string }
        file_path: { type: string }
        line: { type: integer }
        end_line: { type: integer }
        language: { type: string }
        signature: { type: string }
        parent_name: { type: string }

    SymbolSearchResponse:
      type: object
      required: [results, total]
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/SymbolResultItem"
        total:
          type: integer
          minimum: 0

    DefinitionRequest:
      type: object
      required: [symbol]
      properties:
        symbol:
          type: string
          minLength: 1
        kind:
          type: string
        file_path:
          type: string
        limit:
          type: integer
          minimum: 0
          default: 10

    DefinitionItem:
      type: object
      required: [name, kind, file_path, line, end_line, language]
      properties:
        name: { type: string }
        kind: { type: string }
        file_path: { type: string }
        line: { type: integer }
        end_line: { type: integer }
        language: { type: string }
        signature: { type: string }
        parent_name: { type: string }

    DefinitionResponse:
      type: object
      required: [results, total]
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/DefinitionItem"
        total:
          type: integer
          minimum: 0

    ReferenceRequest:
      type: object
      required: [symbol]
      properties:
        symbol:
          type: string
          minLength: 1
        limit:
          type: integer
          minimum: 0
          default: 50
        file_path:
          type: string

    ReferenceItem:
      type: object
      required:
        - file_path
        - start_line
        - end_line
        - content
        - chunk_type
        - symbol_name
        - language
      properties:
        file_path: { type: string }
        start_line: { type: integer }
        end_line:
          type: integer
          description: Always equal to `start_line` (refs table stores tokens, not ranges).
        content:
          type: string
          description: Always empty — see endpoint description.
        chunk_type:
          type: string
          enum: [reference]
        symbol_name: { type: string }
        language: { type: string }

    ReferenceResponse:
      type: object
      required: [results, total]
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/ReferenceItem"
        total:
          type: integer
          minimum: 0

    FileSearchRequest:
      type: object
      required: [query]
      properties:
        query:
          type: string
          minLength: 1
          description: Substring matched against `file_path`.
        limit:
          type: integer
          minimum: 0
          default: 20

    FileResultItem:
      type: object
      required: [file_path, language]
      properties:
        file_path: { type: string }
        language:
          type: string
          nullable: true
          description: Detected language, or null if undetected.

    FileSearchResponse:
      type: object
      required: [results, total]
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/FileResultItem"
        total:
          type: integer
          minimum: 0

    FileReadRequest:
      type: object
      required: [file]
      properties:
        file:
          type: string
          minLength: 1
          description: Repo-relative path of the file to read.
        start:
          type: integer
          minimum: 1
          description: First line, 1-based inclusive. Omit for start of file.
        end:
          type: integer
          minimum: 1
          description: Last line, 1-based inclusive. Omit for end of file.

    FileContent:
      type: object
      required: [file_path, start_line, end_line, total_lines, truncated, content]
      properties:
        file_path: { type: string }
        language:
          type: string
          nullable: true
          description: Detected language, or null if undetected.
        start_line:
          type: integer
          description: First line returned (1-based inclusive).
        end_line:
          type: integer
          description: Last line returned (1-based inclusive).
        total_lines:
          type: integer
          description: Total line count of the file on disk.
        truncated:
          type: boolean
          description: True when output was capped by server size/line limits.
        content: { type: string }

    TreeRequest:
      type: object
      properties:
        dir:
          type: string
          description: Repo-relative directory. Omit/empty for the repo root.

    TreeEntry:
      type: object
      required: [name, type]
      properties:
        name: { type: string }
        type:
          type: string
          enum: [file, dir]
        size:
          type: integer
          description: Size in bytes (files only; 0 for directories).
        language:
          type: string
          nullable: true
          description: Detected language for files, or null.

    DirectoryListing:
      type: object
      required: [dir, entries, truncated]
      properties:
        dir:
          type: string
          description: The listed directory (repo-relative; empty = root).
        entries:
          type: array
          items:
            $ref: "#/components/schemas/TreeEntry"
        truncated:
          type: boolean
          description: True when the entry count was capped.

    SemanticSearchRequest:
      type: object
      required: [query]
      properties:
        query:
          type: string
          minLength: 1
        limit:
          type: integer
          minimum: 0
          default: 10
          description: Maximum number of FILE groups (not chunks) to return.
        languages:
          type: array
          items: { type: string }
        paths:
          type: array
          items: { type: string }
          description: Whitelist — keep only results whose path matches any prefix or substring.
        excludes:
          type: array
          items: { type: string }
          description: Blacklist — drop results whose path matches any prefix or substring.
        min_score:
          type: number
          format: float
          description: |
            Minimum cosine similarity. Omit for server default (0.2 —
            light floor that keeps abstract NL queries non-empty). Send
            `0` to disable; pass `0.4+` for strict code-symbol searches
            calibrated for CodeRankEmbed-Q8.

    NestedHit:
      type: object
      required: [start_line, end_line, chunk_type, score]
      properties:
        start_line: { type: integer }
        end_line: { type: integer }
        symbol_name: { type: string }
        chunk_type: { type: string }
        score:
          type: number
          format: float

    FileMatch:
      type: object
      required: [start_line, end_line, content, score, chunk_type]
      properties:
        start_line: { type: integer }
        end_line: { type: integer }
        content: { type: string }
        score:
          type: number
          format: float
        chunk_type: { type: string }
        symbol_name: { type: string }
        nested_hits:
          type: array
          items:
            $ref: "#/components/schemas/NestedHit"

    FileGroupResult:
      type: object
      required: [file_path, best_score, matches]
      properties:
        file_path: { type: string }
        language: { type: string }
        best_score:
          type: number
          format: float
        matches:
          type: array
          items:
            $ref: "#/components/schemas/FileMatch"

    SemanticSearchResponse:
      type: object
      required: [results, total, query_time_ms]
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/FileGroupResult"
        total:
          type: integer
          minimum: 0
        query_time_ms:
          type: number
          format: double
          description: Wall-clock query latency, rounded to 1 decimal place.

    IndexBeginRequest:
      type: object
      properties:
        full:
          type: boolean
          default: false
          description: When true, wipes existing project state before opening the session.

    IndexBeginResponse:
      type: object
      required: [run_id, stored_hashes]
      properties:
        run_id:
          type: string
        stored_hashes:
          type: object
          additionalProperties:
            type: string
          description: |
            Map from file path → SHA-256 of currently-stored content. Empty
            when the project has never been indexed (or `full:true` was passed).

    FilePayload:
      type: object
      required: [path, content, content_hash, size]
      properties:
        path:
          type: string
        content:
          type: string
          description: UTF-8 text. Binary files should not be submitted.
        content_hash:
          type: string
          description: SHA-256 hex digest of `content`.
        language:
          type: string
        size:
          type: integer
          minimum: 0

    IndexFilesRequest:
      type: object
      required: [run_id, files]
      properties:
        run_id:
          type: string
          minLength: 1
        files:
          type: array
          maxItems: 50
          items:
            $ref: "#/components/schemas/FilePayload"

    IndexFilesResponse:
      type: object
      required: [files_accepted, chunks_created, files_processed_total]
      properties:
        files_accepted:
          type: integer
          minimum: 0
        chunks_created:
          type: integer
          minimum: 0
        files_processed_total:
          type: integer
          minimum: 0

    IndexFinishRequest:
      type: object
      required: [run_id]
      properties:
        run_id:
          type: string
          minLength: 1
        deleted_paths:
          type: array
          items: { type: string }
        total_files_discovered:
          type: integer
          minimum: 0

    IndexFinishResponse:
      type: object
      required: [status, files_processed, chunks_created]
      properties:
        status:
          type: string
          enum: [completed]
        files_processed:
          type: integer
          minimum: 0
        chunks_created:
          type: integer
          minimum: 0

    IndexCancelResponse:
      type: object
      required: [cancelled]
      properties:
        cancelled:
          type: boolean

    IndexProgressInfo:
      type: object
      description: |
        Progress payload. The active-session variant carries every field;
        the historical-fallback variant only carries `files_processed`,
        `files_total`, and `chunks_created`.
      properties:
        phase:
          type: string
          enum: [receiving, completed]
        files_discovered:
          type: integer
          minimum: 0
        files_processed:
          type: integer
          minimum: 0
        files_total:
          type: integer
          minimum: 0
        chunks_created:
          type: integer
          minimum: 0
        elapsed_seconds:
          type: number
          format: double
        run_id:
          type: string
        current_files:
          type: array
          items:
            type: string
          description: |
            Most recent files being indexed, newest first; up to 3. Lets a UI
            show live forward motion during a run. Empty on the
            historical-fallback variant.

    IndexProgressResponse:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [idle, indexing, completed, cancelled, failed, running]
          description: |
            `idle` — no session ever / fallback unavailable.
            `indexing` — session active.
            `completed`/`cancelled`/`failed`/`running` — last-run status from `index_runs`.
        progress:
          $ref: "#/components/schemas/IndexProgressInfo"

    IndexProgressEvent:
      type: object
      description: |
        One event in the NDJSON stream emitted by `POST /index/files` when
        the client sends `Accept: application/x-ndjson`. The `event` field
        discriminates the variant; other fields are populated as relevant.
      required: [event]
      properties:
        event:
          type: string
          enum:
            - file_started
            - file_chunked
            - file_embedded
            - file_done
            - file_error
            - heartbeat
            - batch_done
            - error
        run_id:
          type: string
        path:
          type: string
        file_index:
          type: integer
        batch_size:
          type: integer
        chunks:
          type: integer
        embed_ms:
          type: integer
          format: int64
        ts:
          type: string
          format: date-time
        message:
          type: string
        fatal:
          type: boolean
        files_accepted:
          type: integer
        chunks_created:
          type: integer
        files_processed_total:
          type: integer

    Workspace:
      type: object
      # owner_user_id is required-but-nullable for the same reason as on
      # Project — clients can rely on the field being present and use
      # `string | null` instead of optional.
      required: [id, name, description, created_at, updated_at, owner_user_id]
      properties:
        id:
          type: string
          description: ULID-like opaque identifier.
        name:
          type: string
          description: Unique workspace name.
        description:
          type: string
          description: Free-form description. Empty string when absent.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        owner_user_id:
          type: string
          nullable: true
          description: |
            User who created the workspace. NULL only when orphaned by a user
            deletion. Visible to the owner, members of any view-group it is
            shared to, and admins.

    WorkspaceListResponse:
      type: object
      required: [workspaces, total]
      properties:
        workspaces:
          type: array
          items:
            $ref: "#/components/schemas/Workspace"
        total:
          type: integer

    CreateWorkspaceRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
        description:
          type: string
          description: Optional free-form description.

    UpdateWorkspaceRequest:
      type: object
      description: |
        Both fields are optional — omitting a field leaves the existing
        value unchanged. Passing an empty string for `description` clears
        it. `name` must be non-empty when provided.
      properties:
        name:
          type: string
          minLength: 1
        description:
          type: string

    Group:
      type: object
      required: [id, name, description, created_at, updated_at]
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
          description: Free-form description. Empty string when absent.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    GroupMember:
      type: object
      required: [user_id, email, role, added_at]
      properties:
        user_id:
          type: string
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, user]
        added_at:
          type: string
          format: date-time

    GroupListResponse:
      type: object
      required: [groups, total]
      properties:
        groups:
          type: array
          items:
            $ref: "#/components/schemas/Group"
        total:
          type: integer

    GroupMemberListResponse:
      type: object
      required: [members, total]
      properties:
        members:
          type: array
          items:
            $ref: "#/components/schemas/GroupMember"
        total:
          type: integer

    CreateGroupRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
        description:
          type: string

    UpdateGroupRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
        description:
          type: string

    AddGroupMemberRequest:
      type: object
      required: [user_id]
      properties:
        user_id:
          type: string

    ShareToGroupRequest:
      type: object
      required: [group_id]
      properties:
        group_id:
          type: string

    GroupIdListResponse:
      type: object
      required: [group_ids]
      properties:
        group_ids:
          type: array
          items:
            type: string

    ReassignOwnerRequest:
      type: object
      required: [owner_user_id]
      properties:
        owner_user_id:
          type: string
          description: New owner; must be an existing, enabled user.

    GithubToken:
      type: object
      required: [id, name, scopes, created_at]
      properties:
        id:
          type: string
        name:
          type: string
        scopes:
          type: array
          items:
            type: string
          description: |
            Best-effort scope list. PR1 stores whatever the client supplies;
            later releases populate this by calling GitHub's /user endpoint
            with the plaintext token.
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
          nullable: true

    GithubTokenListResponse:
      type: object
      required: [tokens, total]
      properties:
        tokens:
          type: array
          items:
            $ref: "#/components/schemas/GithubToken"
        total:
          type: integer

    CreateGithubTokenRequest:
      type: object
      required: [name, token]
      properties:
        name:
          type: string
          minLength: 1
          description: Human-friendly label shown in the dashboard.
        token:
          type: string
          minLength: 1
          description: |
            The plaintext PAT. The server encrypts it with AES-GCM before
            persisting; this is the only request body that ever carries
            the plaintext value.
        scopes:
          type: array
          items:
            type: string
          deprecated: true
          description: |
            Ignored. The server now derives real scopes from GitHub's
            X-OAuth-Scopes response header by calling GET /user with the
            supplied token, so user-supplied scope hints are no longer
            consulted. Kept for backwards compatibility with older
            clients that still send it.

    UpdateGithubTokenRequest:
      type: object
      required: [token]
      properties:
        token:
          type: string
          minLength: 1
          description: |
            The new plaintext PAT. Validated against GitHub and encrypted at
            rest exactly like creation; the stored scopes are refreshed from
            the X-OAuth-Scopes header. The token's id and name are unchanged.

    GitRepo:
      type: object
      required:
        - project_path
        - path_hash
        - github_url
        - branch
        - auto_webhook
        - webhook_mode
        - created_at
        - updated_at
      description: |
        Clone + webhook metadata for an external (git-cloned) project.
        Exactly 1:1 with the matching projects row; local projects have
        no GitRepo row.
      properties:
        project_path:
          type: string
          description: |
            Matches projects.host_path — canonical
            "github.com/owner/repo@branch" string.
        path_hash:
          type: string
          description: 16-hex SHA1 prefix of project_path, used in URLs.
        github_url:
          type: string
        branch:
          type: string
        token_id:
          type: string
          nullable: true
        auto_webhook:
          type: boolean
          description: Legacy alias for `webhook_mode == "auto"`.
        webhook_mode:
          type: string
          enum: [manual, auto, disabled]
        last_sha:
          type: string
          nullable: true
        last_error:
          type: string
          nullable: true
        polling_enabled:
          type: boolean
          description: |
            When true, the shared poll scheduler fetches this repo on an
            interval (the alternative to webhooks for non-admin repos).
            Mutually exclusive with webhook_mode != 'disabled'.
        poll_interval_seconds:
          type: integer
          nullable: true
          description: |
            Per-repo poll cadence in seconds. Null → server default
            (CIX_DEFAULT_POLL_INTERVAL). Always clamped up to the floor
            (CIX_MIN_POLL_INTERVAL).
        next_poll_at:
          type: string
          format: date-time
          nullable: true
          description: |
            Absolute time this repo is next due for a poll. Null when
            polling is disabled. Measured from the end of the last index run.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    AddGitRepoRequest:
      type: object
      required: [github_url, branch]
      properties:
        github_url:
          type: string
          description: https://github.com/owner/repo URL.
        branch:
          type: string
          minLength: 1
        token_id:
          type: string
          description: Optional id of a stored GitHub PAT (required for private repos).
        webhook_mode:
          type: string
          enum: [manual, auto, disabled]
          default: manual
        polling_enabled:
          type: boolean
          description: |
            Enable polling sync. Requires webhook_mode='disabled'
            (webhook XOR polling); otherwise the request is rejected 422.
        poll_interval_seconds:
          type: integer
          description: Optional per-repo poll cadence in seconds (0/omitted → server default).

    UpdateGitRepoSyncRequest:
      type: object
      required: [sync_method]
      properties:
        sync_method:
          type: string
          enum: [webhook, polling, manual]
          description: |
            How the project should be kept in sync. `webhook` → push-driven
            (auto-register, fall back to polling on failure); `polling` →
            server fetches on an interval; `manual` → reindex on demand only.
        poll_interval_seconds:
          type: integer
          description: |
            Per-repo poll cadence in seconds (0/omitted → server default).
            Only meaningful when sync_method is `polling` (also used as the
            interval if `webhook` falls back to polling).

    UpdateGitRepoSyncResult:
      type: object
      required: [git_repo]
      properties:
        git_repo:
          $ref: "#/components/schemas/GitRepo"
        note:
          type: string
          description: |
            Human-readable note about the outcome — e.g. that webhook
            auto-registration failed and the server fell back to polling.

    UpdateGitRepoTokenRequest:
      type: object
      properties:
        token_id:
          type: string
          nullable: true
          description: |
            Id of the stored GitHub PAT this project should use. Null or
            omitted detaches the token (token_id → NULL) and clones the repo
            as public. 422 when the id does not match a stored token.

    GithubRepo:
      type: object
      required: [full_name, default_branch, private, html_url]
      description: A repository visible to a stored PAT.
      properties:
        full_name:
          type: string
          description: "owner/name"
        default_branch:
          type: string
          description: |
            The repo's default branch; the dashboard pre-fills the branch
            input with this when the user picks a repo from the list.
        private:
          type: boolean
        html_url:
          type: string
        description:
          type: string

    GithubAccount:
      type: object
      required: [login, type]
      description: |
        A GitHub account the PAT can see. The user owning the PAT is
        returned first, followed by every org accessible via /user/orgs.
        The dashboard's add-repo flow shows these in a Select before
        the repository picker so the operator can drill into a specific
        org instead of relying on the affiliations-aggregated view.
      properties:
        login:
          type: string
          description: GitHub login (user name or org slug).
        type:
          type: string
          enum: [user, org]
          description: |
            "user" for the PAT owner; "org" for organisations.
        avatar_url:
          type: string

    GitRepoCreated:
      type: object
      required: [project, git_repo, webhook_url, webhook_secret]
      properties:
        project:
          $ref: "#/components/schemas/Project"
        git_repo:
          $ref: "#/components/schemas/GitRepo"
        webhook_url:
          type: string
          description: |
            Publicly-reachable POST endpoint to register in GitHub when
            doing webhook setup manually.
        webhook_secret:
          type: string
          description: |
            HMAC secret. **Returned once on create + once via
            /projects/{hash}/webhook-info.**
        auto_registered:
          type: boolean
          description: |
            True when webhook_mode was 'auto' AND the server
            successfully registered the hook with GitHub.
        auto_register_note:
          type: string
          description: Human-readable reason when auto_registered is false.

    WorkspaceProjectMembership:
      type: object
      required: [workspace_id, project_path, added_at]
      properties:
        workspace_id:
          type: string
        project_path:
          type: string
        added_at:
          type: string
          format: date-time

    WorkspaceProject:
      type: object
      required: [project, added_at]
      description: |
        A project listed under a workspace, decorated with the membership
        timestamp. The embedded Project carries the full project info
        (status, languages, last_indexed_at) so the dashboard doesn't
        need a second roundtrip.
      properties:
        project:
          $ref: "#/components/schemas/Project"
        added_at:
          type: string
          format: date-time

    WorkspaceProjectListResponse:
      type: object
      required: [projects, total]
      properties:
        projects:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceProject"
        total:
          type: integer

    LinkProjectRequest:
      type: object
      required: [project_hash]
      properties:
        project_hash:
          type: string
          minLength: 16
          maxLength: 16
          description: |
            The 16-hex `path_hash` of an indexed project. The server
            resolves it to host_path and inserts the (workspace_id,
            project_path) row. The project must be in status='indexed'.

    ProjectWorkspaceList:
      type: object
      required: [workspaces]
      properties:
        workspaces:
          type: array
          items:
            $ref: "#/components/schemas/ProjectWorkspaceEntry"

    ProjectWorkspaceEntry:
      type: object
      required: [workspace_id, workspace_name, added_at]
      properties:
        workspace_id:
          type: string
        workspace_name:
          type: string
        added_at:
          type: string
          format: date-time

    ReindexEnqueuedResponse:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [enqueued, already_running]
        mode:
          type: string
          enum: [full, incremental]
          description: |
            Which reindex flavour the server will run. `full` is set
            when the request used `?full=true` (the server cleared
            `indexed_sha` before enqueueing); otherwise `incremental`
            and the clone-job's mode-determination picks the real
            mode (still may resolve to full at runtime for first-index,
            model-change, or partial-failure cases).
        project:
          $ref: "#/components/schemas/Project"

    ForceStopResponse:
      type: object
      required: [cancelled, jobs_cleared]
      properties:
        cancelled:
          type: boolean
          description: |
            True when an active in-process index session was found and
            cancelled. False when nothing was indexing (the job-queue
            cleanup still ran — see `jobs_cleared`).
        jobs_cleared:
          type: integer
          description: |
            Count of pending/running clone_repo + index_repo jobs that
            were deleted from the queue for this repo.
        project:
          $ref: "#/components/schemas/Project"

    Job:
      type: object
      required:
        - id
        - type
        - status
        - attempts
        - max_attempts
        - scheduled_at
        - created_at
      properties:
        id:
          type: string
        type:
          type: string
        status:
          type: string
          enum: [pending, running, completed, failed]
        dedupe_key:
          type: string
          nullable: true
        payload:
          type: object
          additionalProperties: true
          description: |
            Raw JSON payload — shape depends on `type`. Render as-is in
            the dashboard; don't assume structure.
        attempts:
          type: integer
          minimum: 0
        max_attempts:
          type: integer
          minimum: 0
        last_error:
          type: string
          nullable: true
        scheduled_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time

    JobListResponse:
      type: object
      required: [jobs, total]
      properties:
        jobs:
          type: array
          items:
            $ref: "#/components/schemas/Job"
        total:
          type: integer

    WebhookInfoResponse:
      type: object
      required: [webhook_url, webhook_secret, auto_registered]
      properties:
        webhook_url:
          type: string
          description: |
            Full URL to paste into GitHub's webhook config. Empty path-only
            value when CIX_PUBLIC_URL is unset — prepend your tunnel origin.
        webhook_secret:
          type: string
          description: HMAC secret. Treat as sensitive — rotates on repo recreate.
        auto_registered:
          type: boolean
          description: |
            True when the server successfully auto-registered the webhook
            against the GitHub API (auto_webhook=true on create + PAT had
            admin:repo_hook). When false, the operator must register manually.

    WebhookAccepted:
      type: object
      required: [status]
      properties:
        status:
          type: string
          enum: [enqueued, already_running, ignored, ping]
        repo_id:
          type: string

    TunnelStatus:
      type: object
      required: [provider, state, available]
      properties:
        provider:
          type: string
          enum: [cloudflare, ngrok]
        state:
          type: string
          enum: [disabled, connecting, live, failed]
        mode:
          type: string
          description: '"named" or "quick" for cloudflare; omitted otherwise.'
        public_url:
          type: string
          description: Public base URL (no trailing slash) when live.
        pid:
          type: integer
        uptime_sec:
          type: integer
          format: int64
        last_error:
          type: string
        available:
          type: boolean
          description: False for providers that are not yet implemented.
        note:
          type: string

    TunnelCatalog:
      type: object
      required: [providers]
      properties:
        providers:
          type: array
          items:
            $ref: "#/components/schemas/TunnelStatus"

    TunnelBinary:
      type: object
      required: [provider, installed, managed]
      properties:
        provider:
          type: string
          enum: [cloudflare, ngrok]
        installed:
          type: boolean
        managed:
          type: boolean
          description: Whether the server can install/update this binary from the UI.
        path:
          type: string
        version:
          type: string

    TunnelBinaryList:
      type: object
      required: [binaries]
      properties:
        binaries:
          type: array
          items:
            $ref: "#/components/schemas/TunnelBinary"

    TunnelConfig:
      type: object
      required: [enabled, provider, mode, hostname, token_set]
      properties:
        enabled:
          type: boolean
        provider:
          type: string
          enum: [cloudflare, ngrok]
        mode:
          type: string
          enum: [named, quick]
        hostname:
          type: string
          description: Named-tunnel public hostname (named mode only).
        token_set:
          type: boolean
          description: Whether a connector token is stored (never returned).
        updated_at:
          type: string
        updated_by:
          type: string

    TunnelConfigUpdate:
      type: object
      properties:
        enabled:
          type: boolean
        provider:
          type: string
          enum: [cloudflare, ngrok]
        mode:
          type: string
          enum: [named, quick]
        hostname:
          type: string
        token:
          type: string
          description: |
            Cloudflare named-tunnel connector token. Omit to keep the
            existing token; send "" to clear it.

    TunnelTestResult:
      type: object
      required: [ok]
      properties:
        ok:
          type: boolean
        public_url:
          type: string
        status_code:
          type: integer
        latency_ms:
          type: integer
          format: int64
        detail:
          type: string

    WebhookReconcileOutcome:
      type: object
      required: [project_path, action]
      properties:
        project_path:
          type: string
        action:
          type: string
          enum: [updated, created, skipped, failed]
        note:
          type: string

    WebhookReconcileResult:
      type: object
      required: [base_url, total, created, updated, skipped, failed]
      properties:
        base_url:
          type: string
        total:
          type: integer
        created:
          type: integer
        updated:
          type: integer
        skipped:
          type: integer
        failed:
          type: integer
        outcomes:
          type: array
          items:
            $ref: "#/components/schemas/WebhookReconcileOutcome"

    WebhookOrigin:
      type: object
      required: [origin, source]
      properties:
        origin:
          type: string
          description: |
            The public base URL webhook delivery URLs are built against
            (no trailing slash). Empty when source is "none".
        source:
          type: string
          enum: [tunnel, public_url, none]
          description: |
            Where `origin` comes from. `tunnel` — a live managed tunnel.
            `public_url` — the operator-set CIX_PUBLIC_URL (infrastructure
            provides public reachability; a tunnel is not needed). `none` —
            no public origin is configured, so webhooks can't be delivered.

    WorkspaceSearchResponse:
      type: object
      required: [status, projects, chunks]
      properties:
        status:
          type: string
          enum: [ok, empty, partial_failure]
          description: |
            `ok` — results follow. `empty` — workspace queried fine but
            nothing cleared the `min_score` floor. `partial_failure` —
            no chunks returned but at least one repo errored out during
            the fan-out (see `failed_repos`).
        projects:
          type: array
          description: |
            Top projects ranked by `project_score`. Surfaces which repos
            in the workspace the query is most relevant to, independent
            of which individual chunks rank highest globally.
          items:
            $ref: "#/components/schemas/WorkspaceSearchProject"
        chunks:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceSearchChunk"
        pending_repos:
          type: array
          description: |
            Repos that belong to the workspace but weren't queryable
            yet — clone or index hasn't completed (or the last attempt
            failed). Their matches will appear once they reach
            `status=indexed`. Empty if every repo is ready.
          items:
            $ref: "#/components/schemas/WorkspaceSearchPendingRepo"
        failed_repos:
          type: array
          description: |
            Repos whose per-project vector search returned an error
            during this request (e.g. corrupt collection on disk). The
            rest of the workspace is still aggregated; surface this so
            the operator knows the result set is incomplete.
          items:
            $ref: "#/components/schemas/WorkspaceSearchFailedRepo"
        stale_fts_repos:
          type: array
          description: |
            Repos that were indexed before the BM25 mirror
            (`chunks_fts`) was added: they're queryable via dense
            search but the sparse half of the hybrid is empty, which
            collapses the algorithm to pure-dense fan-out for these
            entries. Trigger a reindex on each to backfill the FTS
            side. Empty once every workspace repo has been reindexed
            under the new schema.
          items:
            $ref: "#/components/schemas/WorkspaceSearchStaleFTSRepo"
        timings:
          $ref: "#/components/schemas/WorkspaceSearchTimings"

    WorkspaceSearchTimings:
      type: object
      description: |
        Where this query spent its time, in milliseconds. Returned only
        when the request passes `timings=true` AND the query actually ran
        a search — a workspace with no queryable project reports nothing
        rather than a block of zeroes that would read as "instant".

        The fan-out phases report a sum AND a max, and both are needed: the
        sum is how much work the query did across every project, the max is
        how long it waited for the slowest one. With perfect parallelism the
        wall time is the max; with none it is the sum; in practice it is
        between them, and one number alone cannot say which.

        `projects_scanned` versus `projects_returned` is the ratio that says
        how much of the work was discarded: the fan-out runs dense and BM25
        over every project in the workspace and then thresholds the answer
        down to the relevant ones. `projects_in_panel` is a separate,
        smaller question — how many of those the caller was actually shown,
        after the `top_projects` cap.

        The named phases do not sum to `wall_ms`. The remainder is the
        workspace visibility check, assembling the projects panel, the
        round-robin interleave and writing the response — all in memory and,
        on the load-test fixture, ~19 ms of ~9,900 ms.
      properties:
        wall_ms:
          type: integer
          description: The whole handler, from its first line to its last.
        embed_ms:
          type: integer
          description: Round-trip to the embedding provider for the query text.
        resolve_ms:
          type: integer
          description: |
            Loading the workspace's project memberships and applying the
            per-user access filter. Separate from the rest because it is the
            one pre-fan-out step that grows with how many projects the
            caller can see, rather than with the workspace.
        stale_fts_ms:
          type: integer
          description: The pre-fan-out probe for repos with no BM25 mirror.
        fanout_ms:
          type: integer
          description: Wall time of the parallel per-project phase.
        dense_sum_ms:
          type: integer
          description: |
            Vector-store search summed across projects, including hydration
            of each project's winning rows, and including projects whose
            query failed — the time was spent either way, and omitting it
            would put the sums permanently below the wall time they explain.
        dense_max_ms:
          type: integer
          description: |
            The slowest single project's dense search. May belong to a
            project whose query failed; the fan-out logs a warning of its
            own for those.
        bm25_ms:
          type: integer
          description: |
            The workspace's BM25 search. One FTS5 statement covering every
            project, partitioned per project by a window function — not a
            sum over projects, which is why it has no matching `_max`
            field. `MATCH` is evaluated over the whole server's index
            whatever the scope, so asking once per project repeated the
            same global work N times and the N queries contended over one
            index on top of that.
        fuse_ms:
          type: integer
          description: Normalisation, candidacy blending and thresholding.
        projects_scanned:
          type: integer
          description: Projects the fan-out searched.
        projects_returned:
          type: integer
          description: |
            Projects that survived the relevance threshold — NOT the number
            the caller was shown. Capping this at `top_projects` would peg
            the scanned:returned ratio to a request parameter instead of
            measuring how much of the fan-out's work was discarded.
        projects_in_panel:
          type: integer
          description: |
            Projects present in the response's `projects` array, i.e.
            `min(projects_returned, top_projects)`.

    WorkspaceSearchPendingRepo:
      type: object
      required: [project_path, status]
      properties:
        project_path:
          type: string
        status:
          type: string
          enum: [pending, cloning, indexing, failed]
          description: |
            Current per-project status. Anything other than `indexed`
            means the project hasn't contributed to this response.

    WorkspaceSearchFailedRepo:
      type: object
      required: [project_path, reason]
      properties:
        project_path:
          type: string
        reason:
          type: string
          description: |
            Short category for the failure — `vectorstore_error`,
            `timeout`, etc. Intentionally not the raw error message so
            internal details don't leak; check the server logs by
            `workspace_id` for the full error.

    WorkspaceSearchStaleFTSRepo:
      type: object
      required: [project_path]
      properties:
        project_path:
          type: string

    WorkspaceSearchProject:
      type: object
      required: [project_path, label, project_score, num_hits, bm25_score, dense_score]
      properties:
        project_path:
          type: string
        label:
          type: string
          description: |
            Short human-readable label derived from the project_path's
            last segment (e.g. "owner/repo@main" → "repo@main").
        project_score:
          type: number
          format: float
          description: |
            Hybrid candidacy in [0,1] — the α-blend of per-query
            min-max normalized BM25 and dense signals (α=0.5) the
            project-relevance gate ranks by. The "Top projects"
            panel sorts by this value.
        num_hits:
          type: integer
          description: |
            Chunks from this project that survived the per-project
            chunk cap and made it into the global chunks list.
        bm25_score:
          type: number
          format: float
          description: |
            Mean of the top-N raw BM25 scores in this project (sign
            flipped from SQLite's bm25() so positive = better).
            Surfaced so the dashboard can show "this repo surfaced
            on literal token overlap" vs. "pure semantic similarity".
        dense_score:
          type: number
          format: float
          description: |
            Mean of the top-N raw cosine similarities in this
            project. Together with `bm25_score`, the two raw signals
            that feed into `project_score`.

    WorkspaceSearchChunk:
      type: object
      required:
        - project_path
        - file_path
        - start_line
        - end_line
        - score
        - content
      properties:
        project_path:
          type: string
        file_path:
          type: string
        start_line:
          type: integer
        end_line:
          type: integer
        symbol_name:
          type: string
        language:
          type: string
        score:
          type: number
          format: float
          description: |
            Raw cosine similarity between the query and this chunk —
            the value chunks are sorted by. No per-project boost is
            applied (a previous revision multiplied this by
            project_score, which let one repo dominate every result
            for short queries like product-name acronyms).
        content:
          type: string