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: 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/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}/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/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 chromem-go 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 (chromem cosine) 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
      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}/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
    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"
    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

    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
        - 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.
        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
      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 }

    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

    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.

    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.
        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: Resolved chromem-go collection directory for this project. 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

    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.

    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.

    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"

    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