core/server/static/openapi.yaml

openapi: 3.0.3
info:
  title: Chat Switchboard API
  description: 'Multi-provider AI chat platform with team workspaces, workflow automation,

    and extensibility via Starlark packages.


    ## Authentication


    Three authentication modes, selected by the `AUTH_MODE` environment variable.

    All three produce the same JWT-based session — downstream middleware is

    auth-mode-agnostic.


    **Builtin (default):** Username/password via `POST /api/v1/auth/login`.

    Include the returned token as `Authorization: Bearer <token>`.


    **OIDC:** Authorization code flow via `GET /api/v1/auth/oidc/login`.

    Compatible with any OpenID Connect provider (tested with Keycloak).


    **mTLS:** Mutual TLS via reverse proxy headers. No explicit login — user

    identity is extracted from the client certificate on every request.


    ## WebSocket


    Real-time events are delivered over WebSocket at `/ws`. Obtain a single-use

    ticket (30s TTL) via `POST /api/v1/ws/ticket` and connect with

    `?ticket=<id>`. Cross-pod safe (v0.32.0).


    ## Response Conventions


    - **List endpoints** return `{ "data": [...] }` with an array under `data`.

    - **Single-object endpoints** return the object directly.

    - **Composite endpoints** use named keys (e.g. `{ "settings": {...} }`).

    - **Errors** return `{ "error": "description" }`.

    '
  version: ${VERSION}
  contact:
    name: Chat Switchboard
servers:
- url: /
  description: Current instance
tags:
- name: Auth
  description: Authentication and session management
- name: Profile
  description: User profile, preferences, and credentials
- name: Channels
  description: Chat channel CRUD and messaging
- name: Messages
  description: Message CRUD, editing, regeneration, and tree navigation
- name: Completions
  description: AI completion requests (streaming and non-streaming)
- name: Personas
  description: AI persona CRUD, system prompts, tool config, KB bindings
- name: Models
  description: Model catalog, preferences, and capability management
- name: Providers
  description: Provider config CRUD (BYOK) and model fetching
- name: Notes
  description: Obsidian-style notes with wikilinks, backlinks, and graph
- name: Knowledge Bases
  description: Document ingestion, embedding, and semantic search
- name: Memory
  description: Conversation memory extraction, review, and compaction
- name: Projects
  description: Project containers for channels, KBs, notes, and files
- name: Workspaces
  description: File workspaces with git integration
- name: Tasks
  description: Scheduled and on-demand task execution (Go + Starlark)
- name: Workflows
  description: Multi-stage workflow definitions, instances, and assignments
- name: Teams
  description: Team CRUD, membership, roles, and scoped resources
- name: Extensions
  description: Package install, permissions, secrets, and lifecycle
- name: Surfaces
  description: Extension surface mounting and management
- name: Notifications
  description: User notification list, preferences, and read state
- name: Files
  description: File upload, download, and metadata
- name: Health
  description: System health, readiness, and metrics
- name: Admin
  description: Platform administration (requires admin role)
- name: Usage
  description: Token usage and cost tracking
- name: WebSocket
  description: Real-time event delivery
- name: Data Portability
  description: Export, import, GDPR compliance
paths:
  /api/v1/auth/register:
    post:
      tags:
      - Auth
      summary: Register a new user
      description: 'Builtin auth only. Gated by `allow_registration` policy.

        A unique `handle` is auto-generated from `username`.

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - username
              - password
              - email
              properties:
                username:
                  type: string
                  minLength: 3
                password:
                  type: string
                  minLength: 8
                  maxLength: 128
                email:
                  type: string
                  format: email
                display_name:
                  type: string
            example:
              username: jdoe
              password: s3cure-p@ss
              email: jdoe@example.com
              display_name: Jane Doe
      responses:
        '201':
          description: User created and logged in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          description: Registration disabled by policy
        '409':
          description: Username or email already taken
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/auth/login:
    post:
      tags:
      - Auth
      summary: Authenticate and obtain JWT tokens
      description: 'Builtin auth. Accepts `login` (username or email) and `password`.

        Returns an access token (15m TTL) and a refresh token (7d TTL).

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - login
              - password
              properties:
                login:
                  type: string
                  description: Username or email address
                password:
                  type: string
            example:
              login: jdoe
              password: s3cure-p@ss
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Invalid credentials
        '403':
          description: Account inactive (awaiting admin approval)
        '429':
          $ref: '#/components/responses/RateLimited'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/auth/refresh:
    post:
      tags:
      - Auth
      summary: Refresh an expired access token
      description: 'Exchanges a valid refresh token for a new token pair. The old

        refresh token is invalidated (rotation).

        '
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - refresh_token
              properties:
                refresh_token:
                  type: string
      responses:
        '200':
          description: New token pair
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '401':
          description: Invalid or expired refresh token
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/auth/logout:
    post:
      tags:
      - Auth
      summary: Invalidate the current session
      description: Revokes the provided refresh token.
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                refresh_token:
                  type: string
      responses:
        '200':
          description: Logged out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/auth/oidc/login:
    get:
      tags:
      - Auth
      summary: Initiate OIDC authorization code flow
      description: 'Redirects to the configured OIDC identity provider. Stores `state`

        and `nonce` for CSRF protection. Only available when `AUTH_MODE=oidc`.

        '
      responses:
        '302':
          description: Redirect to IdP authorization endpoint
        '500':
          description: OIDC not configured or discovery failed
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
  /api/v1/auth/oidc/callback:
    get:
      tags:
      - Auth
      summary: OIDC authorization code callback
      description: 'Receives the authorization code from the IdP, exchanges it for tokens,

        validates the ID token via JWKS, and auto-provisions the user on first

        login. Returns an HTML fragment that passes tokens to the frontend via

        URL fragment.

        '
      parameters:
      - name: code
        in: query
        required: true
        schema:
          type: string
      - name: state
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: HTML with embedded tokens
          content:
            text/html:
              schema:
                type: string
        '400':
          description: Invalid state or code
        '500':
          description: Token exchange or validation failed
  /api/v1/profile:
    get:
      tags:
      - Profile
      summary: Get current user's profile
      security:
      - bearerAuth: []
      responses:
        '200':
          description: User profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Profile
      summary: Update profile fields
      description: 'Partial update — only provided fields are changed.

        Supports `display_name` and `email`.

        '
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                display_name:
                  type: string
                email:
                  type: string
                  format: email
            example:
              display_name: Jane D.
              email: jane@newdomain.com
      responses:
        '200':
          description: Updated profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '409':
          $ref: '#/components/responses/Conflict'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/profile/password:
    post:
      tags:
      - Profile
      summary: Change password
      description: 'Builtin auth only. Validates current password, then updates.

        Re-wraps the User Encryption Key (UEK) so BYOK-encrypted

        provider keys remain accessible.

        '
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - current_password
              - new_password
              properties:
                current_password:
                  type: string
                new_password:
                  type: string
                  minLength: 8
                  maxLength: 128
      responses:
        '200':
          description: Password updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Current password incorrect
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/profile/avatar:
    post:
      tags:
      - Profile
      summary: Upload avatar
      description: 'Accepts a base64 data URI or raw base64 string. The server decodes,

        resizes to 128x128 PNG, and stores as a data URI. Max input 2 MB.

        '
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - image
              properties:
                image:
                  type: string
                  description: Base64 data URI or raw base64 string
      responses:
        '200':
          description: Avatar stored
          content:
            application/json:
              schema:
                type: object
                properties:
                  avatar:
                    type: string
                    description: Data URI of the stored avatar
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
    delete:
      tags:
      - Profile
      summary: Remove avatar
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Avatar removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/settings:
    get:
      tags:
      - Profile
      summary: Get user preferences
      description: 'Returns user-level preferences wrapped in a `settings` key.

        Value is `{}` if the user has never saved preferences.

        '
      security:
      - bearerAuth: []
      responses:
        '200':
          description: User settings
          content:
            application/json:
              schema:
                type: object
                required:
                - settings
                properties:
                  settings:
                    type: object
                    additionalProperties: true
              example:
                settings:
                  theme: dark
                  editor_keybindings: vim
                  default_model: claude-sonnet-4-5
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Profile
      summary: Update user preferences
      description: 'Shallow merge — incoming keys overwrite existing, unmentioned keys

        are preserved. Returns the full merged settings object.

        '
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
            example:
              theme: light
              font_size: 14
      responses:
        '200':
          description: Updated settings
          content:
            application/json:
              schema:
                type: object
                required:
                - settings
                properties:
                  settings:
                    type: object
                    additionalProperties: true
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/settings/public:
    get:
      tags:
      - Profile
      summary: Get public platform settings
      description: 'Returns platform-level settings visible to authenticated users

        (e.g. allowed registration, default model, branding).

        '
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Public settings
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/channels:
    get:
      tags:
      - Channels
      summary: List channels accessible to the current user
      security:
      - bearerAuth: []
      parameters:
      - name: type
        in: query
        schema:
          type: string
          enum:
          - direct
          - group
          - workflow
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: Channel list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Channel'
                  page:
                    type: integer
                  per_page:
                    type: integer
                  total:
                    type: integer
                  total_pages:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Channels
      summary: Create a new channel
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                type:
                  type: string
                  enum:
                  - direct
                  - group
                  default: direct
                system_prompt:
                  type: string
      responses:
        '201':
          description: Channel created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/channels/{id}:
    get:
      tags:
      - Channels
      summary: Get channel details
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Channel details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Channels
      summary: Update channel settings
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                system_prompt:
                  type: string
                ai_mode:
                  type: string
                  enum:
                  - auto
                  - false
                  - mention_only
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Channels
      summary: Delete or leave a channel
      description: |
        Owner: deletes (or archives for retention when TTL > 0).
        Non-owner participant: leaves the channel.
        When retention_ttl_days > 0, all channels are archived and purged after TTL.
        Only Personal (BYOK) provider channels are exempt and always immediately deleted.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted, archived for retention, or left channel
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    enum:
                    - channel deleted
                    - channel archived for retention
                    - left channel
                  purge_after:
                    type: string
                    format: date-time
                    description: Only present when archived for retention
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/chat/completions:
    post:
      tags:
      - Completions
      summary: Send a message and get an AI completion
      description: 'Streams SSE events by default. Set `stream: false` for a single JSON

        response. Supports tool calling, @mentions, multi-model routing, and

        workflow integration.

        '
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
      responses:
        '200':
          description: '**Streaming:** SSE events (`data: {"content":"..."}`, `data: [DONE]`).

            **Non-streaming:** OpenAI-compatible JSON response.

            '
          content:
            text/event-stream:
              schema:
                type: string
            application/json:
              schema:
                $ref: '#/components/schemas/CompletionResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '429':
          $ref: '#/components/responses/RateLimited'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /health:
    get:
      tags:
      - Health
      summary: Basic health check
      description: Public, no auth required. Also mirrored at `/api/v1/health`.
      responses:
        '200':
          description: System status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
                  version:
                    type: string
                  database:
                    type: boolean
                  schema_version:
                    type: integer
  /healthz/live:
    get:
      tags:
      - Health
      summary: Kubernetes liveness probe
      responses:
        '200':
          description: Process alive
          content:
            application/json:
              schema:
                type: object
  /healthz/ready:
    get:
      tags:
      - Health
      summary: Kubernetes readiness probe
      description: Pings the database with a 2s timeout. Returns 503 if unreachable.
      responses:
        '200':
          description: Ready to serve traffic
          content:
            application/json:
              schema:
                type: object
        '503':
          description: Database unavailable
  /metrics:
    get:
      tags:
      - Health
      summary: Prometheus metrics endpoint
      description: 'Returns all `switchboard_*` metrics in Prometheus text exposition format.

        Includes HTTP request latency, WebSocket connections, completion tokens,

        DB pool stats, and provider health gauges.

        '
      responses:
        '200':
          description: Prometheus text format
          content:
            text/plain:
              schema:
                type: string
  /api/v1/ws/ticket:
    post:
      tags:
      - WebSocket
      summary: Obtain a WebSocket connection ticket
      description: 'Returns a single-use ticket (30s TTL) for authenticating the WebSocket

        upgrade at `/ws?ticket=<id>`. Stored in PG for cross-pod validation

        (v0.32.0).

        '
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Ticket issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  ticket:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/export:
    post:
      tags:
      - Data Portability
      summary: Convert markdown to PDF or DOCX
      description: 'Uses pandoc to convert markdown content to the requested format.

        Returns the binary file with appropriate Content-Type.

        '
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - content
              - format
              properties:
                content:
                  type: string
                  description: Markdown content to convert
                format:
                  type: string
                  enum:
                  - pdf
                  - docx
                filename:
                  type: string
                  description: Output filename (without extension)
      responses:
        '200':
          description: Converted document
          content:
            application/pdf:
              schema:
                type: string
                format: binary
            application/vnd.openxmlformats-officedocument.wordprocessingml.document:
              schema:
                type: string
                format: binary
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/channels/{id}/mark-read:
    post:
      tags:
      - Channels
      summary: Mark channel as read
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Read cursor updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/channels/{id}/typing:
    post:
      tags:
      - Channels
      summary: Broadcast typing indicator
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Typing event sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/channels/{id}/summarize:
    post:
      tags:
      - Channels
      summary: Trigger conversation summarization
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Summary created
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  summary_id:
                    type: string
                    format: uuid
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/channels/{id}/generate-title:
    post:
      tags:
      - Channels
      summary: Auto-generate channel title from first exchange
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Title generated
          content:
            application/json:
              schema:
                type: object
                properties:
                  title:
                    type: string
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/channels/{id}/path:
    get:
      tags:
      - Messages
      summary: Get active message path (tree walk)
      description: Returns messages along the active branch from root to leaf.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Active message path
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/channels/{id}/messages:
    get:
      tags:
      - Messages
      summary: List all messages (flat, all branches)
      description: Debug/legacy endpoint. Returns every message regardless of branch.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: All messages in channel
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
                  page:
                    type: integer
                  per_page:
                    type: integer
                  total:
                    type: integer
                  total_pages:
                    type: integer
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Messages
      summary: Create a message
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - role
              - content
              properties:
                role:
                  type: string
                  enum:
                  - user
                  - system
                content:
                  type: string
                parent_id:
                  type: string
                  format: uuid
                  nullable: true
                attachments:
                  type: array
                  items:
                    type: string
                    format: uuid
      responses:
        '201':
          description: Message created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/channels/{id}/messages/{msgId}/edit:
    post:
      tags:
      - Messages
      summary: Edit a message (creates sibling branch)
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: msgId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - content
              properties:
                content:
                  type: string
      responses:
        '201':
          description: Sibling message created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/channels/{id}/messages/{msgId}/regenerate:
    post:
      tags:
      - Messages
      summary: Regenerate an assistant response (creates sibling)
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: msgId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  type: string
                provider_config_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Streaming regeneration started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/channels/{id}/messages/{msgId}/siblings:
    get:
      tags:
      - Messages
      summary: List siblings at a branch point
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: msgId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Sibling messages
          content:
            application/json:
              schema:
                type: object
                properties:
                  siblings:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/channels/{id}/cursor:
    put:
      tags:
      - Messages
      summary: Switch active branch
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - active_leaf_id
              properties:
                active_leaf_id:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Cursor updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/tools:
    get:
      tags:
      - Completions
      summary: List available tools
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Tool definitions
          content:
            application/json:
              schema:
                type: object
                properties:
                  tools:
                    type: array
                    items:
                      $ref: '#/components/schemas/ToolDef'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/channels/{id}/models:
    get:
      tags:
      - Channels
      summary: List channel model roster
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Channel model roster
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Channel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Channels
      summary: Add model to channel roster
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - model
              - provider_config_id
              properties:
                model:
                  type: string
                provider_config_id:
                  type: string
                  format: uuid
                display_name:
                  type: string
      responses:
        '201':
          description: Model added to roster
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/channels/{id}/models/{modelId}:
    patch:
      tags:
      - Channels
      summary: Update channel model entry
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: modelId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Channels
      summary: Remove model from channel roster
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: modelId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/channels/{id}/participants:
    get:
      tags:
      - Channels
      summary: List channel participants
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Participant list
          content:
            application/json:
              schema:
                type: object
                properties:
                  participants:
                    type: array
                    items:
                      $ref: '#/components/schemas/Participant'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Channels
      summary: Add participant to channel
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - participant_type
              - participant_id
              properties:
                participant_type:
                  type: string
                  enum:
                  - user
                  - persona
                participant_id:
                  type: string
                  format: uuid
                role:
                  type: string
                  enum:
                  - member
                  - observer
                  default: member
      responses:
        '201':
          description: Participant added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/channels/{id}/participants/{participantId}:
    patch:
      tags:
      - Channels
      summary: Update participant role
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: participantId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  enum:
                  - member
                  - observer
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Channels
      summary: Remove participant
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: participantId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/channels/{id}/knowledge-bases:
    get:
      tags:
      - Channels
      - Knowledge Bases
      summary: List KB bindings for channel
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Channel KB bindings
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Channel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Channels
      - Knowledge Bases
      summary: Set channel KB bindings (replace all)
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - kb_ids
              properties:
                kb_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
      responses:
        '200':
          description: Bindings updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/channels/{id}/files:
    post:
      tags:
      - Files
      summary: Upload file to channel
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: File uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileObject'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
    get:
      tags:
      - Files
      summary: List files in channel
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: origin
        in: query
        schema:
          type: string
          enum:
          - user_upload
          - tool_output
          - system
      responses:
        '200':
          description: Channel files
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FileObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/files:
    get:
      tags:
      - Files
      summary: List all files owned by user
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      responses:
        '200':
          description: User file list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FileObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/files/{id}:
    get:
      tags:
      - Files
      summary: Get file metadata
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: File metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Files
      summary: Delete file
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/files/{id}/download:
    get:
      tags:
      - Files
      summary: Download file
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/messages/{id}/files:
    get:
      tags:
      - Files
      summary: List files attached to a message
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Message files
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/FileObject'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/folders:
    get:
      tags:
      - Channels
      summary: List chat folders
      security:
      - bearerAuth: []
      responses:
        '200':
          description: User folders
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Channel'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Channels
      summary: Create folder
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                sort_order:
                  type: integer
                  default: 0
      responses:
        '201':
          description: Folder created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/folders/{id}:
    put:
      tags:
      - Channels
      summary: Update folder
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Channels
      summary: Delete folder (chats become unfiled)
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/presence/heartbeat:
    post:
      tags:
      - Channels
      summary: Send presence heartbeat
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Heartbeat recorded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/presence:
    get:
      tags:
      - Channels
      summary: Query user presence status
      security:
      - bearerAuth: []
      parameters:
      - name: users
        in: query
        required: true
        schema:
          type: string
        description: Comma-separated user UUIDs (max 100)
      responses:
        '200':
          description: Presence map
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Channel'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/users/search:
    get:
      tags:
      - Channels
      summary: Search users (for DM creation and participant picker)
      security:
      - bearerAuth: []
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Matching users (max 20)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Channel'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/personas:
    get:
      tags:
      - Personas
      summary: List user's personal personas
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Personal personas
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Persona'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Personas
      summary: Create personal persona
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PersonaInput'
      responses:
        '201':
          description: Persona created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/personas/{id}:
    put:
      tags:
      - Personas
      summary: Update personal persona
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Personas
      summary: Delete personal persona
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/personas/{id}/avatar:
    post:
      tags:
      - Personas
      summary: Upload persona avatar
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                image:
                  type: string
      responses:
        '200':
          description: Avatar uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
    delete:
      tags:
      - Personas
      summary: Delete persona avatar
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Avatar removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/personas/{id}/knowledge-bases:
    get:
      tags:
      - Personas
      - Knowledge Bases
      summary: Get persona KB bindings
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Persona KB bindings
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Persona'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Personas
      - Knowledge Bases
      summary: Set persona KB bindings (replace all)
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                kb_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
                auto_search:
                  type: object
                  additionalProperties:
                    type: boolean
      responses:
        '200':
          description: Bindings updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/personas/{id}/tool-grants:
    get:
      tags:
      - Personas
      summary: Get persona tool grants
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Tool grant list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Persona'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Personas
      summary: Set persona tool grants
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                tool_names:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Grants updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/persona-groups:
    get:
      tags:
      - Personas
      summary: List persona groups
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Persona group list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Persona'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Personas
      summary: Create persona group
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                description:
                  type: string
      responses:
        '201':
          description: Group created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/persona-groups/{id}:
    get:
      tags:
      - Personas
      summary: Get persona group with members
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Group with members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Personas
      summary: Update persona group
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Personas
      summary: Delete persona group
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/persona-groups/{id}/members:
    post:
      tags:
      - Personas
      summary: Add persona to group
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - persona_id
              properties:
                persona_id:
                  type: string
                  format: uuid
                is_leader:
                  type: boolean
                  default: false
      responses:
        '201':
          description: Member added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/persona-groups/{id}/members/{memberId}:
    delete:
      tags:
      - Personas
      summary: Remove persona from group
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: memberId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/models/enabled:
    get:
      tags:
      - Models
      summary: List models available to current user
      description: Primary endpoint for model selectors. Returns models, personas, and default.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Available models with default
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                  default_model:
                    type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/models/preferences:
    get:
      tags:
      - Models
      summary: Get user model preferences
      security:
      - bearerAuth: []
      responses:
        '200':
          description: User model preferences
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Models
      summary: Set model preference (upsert)
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - model_id
              - provider_config_id
              properties:
                model_id:
                  type: string
                provider_config_id:
                  type: string
                  format: uuid
                hidden:
                  type: boolean
                sort_order:
                  type: integer
      responses:
        '200':
          description: Preference updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/models/preferences/bulk:
    post:
      tags:
      - Models
      summary: Bulk set model visibility
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - entries
              - hidden
              properties:
                entries:
                  type: array
                  items:
                    type: object
                    properties:
                      model_id:
                        type: string
                      provider_config_id:
                        type: string
                        format: uuid
                hidden:
                  type: boolean
      responses:
        '200':
          description: Preferences updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/api-configs:
    get:
      tags:
      - Providers
      summary: List user's BYOK provider configs
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Provider configs (keys redacted)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProviderConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Providers
      summary: Create BYOK provider config
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderConfigInput'
      responses:
        '201':
          description: Config created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/api-configs/{id}:
    get:
      tags:
      - Providers
      summary: Get provider config (key redacted)
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Provider config
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Providers
      summary: Update provider config
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Providers
      summary: Delete provider config
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/api-configs/{id}/models:
    get:
      tags:
      - Providers
      summary: List models for a provider config
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Model catalog entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProviderConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/api-configs/{id}/models/fetch:
    post:
      tags:
      - Providers
      summary: Sync models from provider API
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Models synced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/notes:
    get:
      tags:
      - Notes
      summary: List notes (paginated)
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - name: folder
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Note list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Note'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Notes
      summary: Create note
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - title
              properties:
                title:
                  type: string
                content:
                  type: string
                folder:
                  type: string
      responses:
        '201':
          description: Note created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/notes/{id}:
    get:
      tags:
      - Notes
      summary: Get note
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Full note object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Notes
      summary: Update note
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Notes
      summary: Delete note
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/notes/{id}/backlinks:
    get:
      tags:
      - Notes
      summary: Get notes that link to this note
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Backlink list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Note'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/notes/search:
    get:
      tags:
      - Notes
      summary: Full-text search notes
      security:
      - bearerAuth: []
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Search results with highlights
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Note'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/notes/search-titles:
    get:
      tags:
      - Notes
      summary: Title search (for wikilink autocomplete)
      security:
      - bearerAuth: []
      parameters:
      - name: q
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Matching titles
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Note'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/notes/graph:
    get:
      tags:
      - Notes
      summary: Get note graph topology
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Graph with nodes, edges, and unresolved links
          content:
            application/json:
              schema:
                type: object
                properties:
                  nodes:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        title:
                          type: string
                  edges:
                    type: array
                    items:
                      type: object
                      properties:
                        source:
                          type: string
                          format: uuid
                        target:
                          type: string
                          format: uuid
                  unresolved:
                    type: array
                    items:
                      type: object
                      properties:
                        source:
                          type: string
                          format: uuid
                        target_title:
                          type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/notes/folders:
    get:
      tags:
      - Notes
      summary: List distinct note folder names
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Folder list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Note'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/notes/bulk-delete:
    post:
      tags:
      - Notes
      summary: Bulk delete notes
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - ids
              properties:
                ids:
                  type: array
                  items:
                    type: string
                    format: uuid
      responses:
        '200':
          description: Notes deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/knowledge-bases:
    get:
      tags:
      - Knowledge Bases
      summary: List knowledge bases
      security:
      - bearerAuth: []
      responses:
        '200':
          description: KB list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/KnowledgeBase'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Knowledge Bases
      summary: Create knowledge base
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                description:
                  type: string
                scope:
                  type: string
                  enum:
                  - personal
                  - team
                  - global
                  default: personal
                team_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: KB created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/knowledge-bases/{id}:
    get:
      tags:
      - Knowledge Bases
      summary: Get knowledge base
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: KB object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Knowledge Bases
      summary: Update knowledge base
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Knowledge Bases
      summary: Delete knowledge base
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/knowledge-bases/{id}/documents:
    get:
      tags:
      - Knowledge Bases
      summary: List KB documents
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Document list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/KnowledgeBase'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Knowledge Bases
      summary: Upload document to KB
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '202':
          description: Document accepted for processing
          content:
            application/json:
              schema:
                type: object
        '412':
          description: No embedding model configured
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/knowledge-bases/{id}/documents/{docId}/status:
    get:
      tags:
      - Knowledge Bases
      summary: Get document processing status
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: docId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Document status
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/KnowledgeBase'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/knowledge-bases/{id}/documents/{docId}:
    delete:
      tags:
      - Knowledge Bases
      summary: Delete KB document
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: docId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/knowledge-bases/{id}/search:
    post:
      tags:
      - Knowledge Bases
      summary: Semantic search within KB
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                limit:
                  type: integer
                  default: 5
                  maximum: 20
                threshold:
                  type: number
                  default: 0.3
      responses:
        '200':
          description: Search results with similarity scores
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/knowledge-bases/{id}/rebuild:
    post:
      tags:
      - Knowledge Bases
      summary: Re-chunk and re-embed all documents
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '202':
          description: Rebuild started
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                  total_docs:
                    type: integer
                  rebuilding:
                    type: integer
                  skipped:
                    type: integer
        '503':
          description: Ingestion pipeline not configured
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/knowledge-bases-discoverable:
    get:
      tags:
      - Knowledge Bases
      summary: List discoverable KBs (for picker UI)
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Discoverable KB list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/KnowledgeBase'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/knowledge-bases/{id}/discoverable:
    put:
      tags:
      - Knowledge Bases
      summary: Toggle KB discoverability
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                discoverable:
                  type: boolean
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
        '403':
          description: Only owner or admin can change
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/memories:
    get:
      tags:
      - Memory
      summary: List user's memories
      security:
      - bearerAuth: []
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - active
          - pending_review
          - archived
          default: active
      - name: query
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Memory list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Memory'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/memories/{id}:
    put:
      tags:
      - Memory
      summary: Update memory
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                key:
                  type: string
                value:
                  type: string
                confidence:
                  type: number
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Memory'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Memory
      summary: Delete memory
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/memories/{id}/approve:
    post:
      tags:
      - Memory
      summary: Approve a pending memory
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Approved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Memory'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/memories/{id}/reject:
    post:
      tags:
      - Memory
      summary: Reject a pending memory
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Memory'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/memories/count:
    get:
      tags:
      - Memory
      summary: Get memory counts by status
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Memory counts
          content:
            application/json:
              schema:
                type: object
                properties:
                  active:
                    type: integer
                  pending:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/memories/compact:
    post:
      tags:
      - Memory
      summary: Compact memories
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Compaction triggered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Memory'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/projects:
    get:
      tags:
      - Projects
      summary: List projects
      security:
      - bearerAuth: []
      parameters:
      - name: include_archived
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Project list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Projects
      summary: Create project
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  maxLength: 200
                description:
                  type: string
                color:
                  type: string
                icon:
                  type: string
      responses:
        '201':
          description: Project created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/projects/{id}:
    get:
      tags:
      - Projects
      summary: Get project
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Project object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Projects
      summary: Update project
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Projects
      summary: Delete project
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/projects/{id}/channels:
    get:
      tags:
      - Projects
      summary: List project channels
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Project channels
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Channel'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Projects
      summary: Add channel to project
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - channel_id
              properties:
                channel_id:
                  type: string
                  format: uuid
                position:
                  type: integer
      responses:
        '200':
          description: Channel added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /api/v1/projects/{id}/channels/{channelId}:
    delete:
      tags:
      - Projects
      summary: Remove channel from project
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: channelId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/projects/{id}/channels/reorder:
    put:
      tags:
      - Projects
      summary: Reorder project channels
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                channel_ids:
                  type: array
                  items:
                    type: string
                    format: uuid
      responses:
        '200':
          description: Reordered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/projects/{id}/knowledge-bases:
    get:
      tags:
      - Projects
      - Knowledge Bases
      summary: List project KB associations
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Project KBs
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Projects
      - Knowledge Bases
      summary: Add KB to project
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - kb_id
              properties:
                kb_id:
                  type: string
                  format: uuid
                auto_search:
                  type: boolean
                  default: false
      responses:
        '201':
          description: KB added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/projects/{id}/knowledge-bases/{kbId}:
    delete:
      tags:
      - Projects
      - Knowledge Bases
      summary: Remove KB from project
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: kbId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/projects/{id}/notes:
    get:
      tags:
      - Projects
      - Notes
      summary: List project note associations
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Project notes
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Projects
      - Notes
      summary: Add note to project
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - note_id
              properties:
                note_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Note added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/projects/{id}/notes/{noteId}:
    delete:
      tags:
      - Projects
      - Notes
      summary: Remove note from project
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: noteId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/projects/{id}/files:
    get:
      tags:
      - Projects
      - Files
      summary: List project files (workspace-backed)
      description: Returns workspace files for the project. Auto-creates workspace on first upload.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: path
        in: query
        schema:
          type: string
        description: Directory path to list (empty = root)
      - name: recursive
        in: query
        schema:
          type: string
          default: 'true'
        description: Include subdirectories
      responses:
        '200':
          description: Project files
          content:
            application/json:
              schema:
                type: object
                properties:
                  files:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        path:
                          type: string
                        is_directory:
                          type: boolean
                        content_type:
                          type: string
                        size_bytes:
                          type: integer
                  count:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Projects
      - Files
      summary: Upload file to project workspace
      description: Uploads a file to the project's workspace. Auto-creates workspace on first upload.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: path
        in: query
        schema:
          type: string
        description: Subdirectory path to upload into
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '201':
          description: File uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  path:
                    type: string
                  filename:
                    type: string
                  content_type:
                    type: string
                  size_bytes:
                    type: integer
        '413':
          description: File too large or workspace quota exceeded
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      tags:
      - Projects
      - Files
      summary: Delete project file
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: path
        in: query
        required: true
        schema:
          type: string
      - name: recursive
        in: query
        schema:
          type: string
      responses:
        '200':
          description: File deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/projects/{id}/files/download:
    get:
      tags:
      - Projects
      - Files
      summary: Download project file
      description: Streams raw file content with Content-Disposition attachment header.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: path
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/projects/{id}/files/mkdir:
    post:
      tags:
      - Projects
      - Files
      summary: Create directory in project workspace
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                path:
                  type: string
              required:
              - path
      responses:
        '201':
          description: Directory created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/projects/{id}/archive/upload:
    post:
      tags:
      - Projects
      - Files
      summary: Upload and extract archive into project workspace
      description: Accepts .zip or .tar.gz, extracts contents into workspace root.
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Archive extracted
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  files_extracted:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/projects/{id}/archive/download:
    get:
      tags:
      - Projects
      - Files
      summary: Download all project files as archive
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: format
        in: query
        schema:
          type: string
          enum: [zip, tar.gz, tgz]
          default: zip
      responses:
        '200':
          description: Archive download
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workspaces:
    get:
      tags:
      - Workspaces
      summary: List workspaces
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Workspace list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Workspaces
      summary: Create workspace
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                owner_type:
                  type: string
                  enum:
                  - user
                  - project
                  - channel
                  - team
                owner_id:
                  type: string
                  format: uuid
      responses:
        '201':
          description: Workspace created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workspaces/default:
    get:
      tags:
      - Workspaces
      summary: Get or create user's default workspace
      description: Returns the current user's personal "My Files" workspace, auto-creating it on first access. Idempotent.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/workspaces/{id}:
    get:
      tags:
      - Workspaces
      summary: Get workspace
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Workspace object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Workspaces
      summary: Update workspace
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Workspaces
      summary: Delete workspace
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workspaces/{id}/files:
    get:
      tags:
      - Workspaces
      summary: List workspace files
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: File tree
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workspaces/{id}/files/read:
    get:
      tags:
      - Workspaces
      summary: Read file content
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: path
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: File content
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workspaces/{id}/files/write:
    put:
      tags:
      - Workspaces
      summary: Write file content
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: File written
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workspaces/{id}/files/delete:
    delete:
      tags:
      - Workspaces
      summary: Delete workspace file
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workspaces/{id}/files/mkdir:
    post:
      tags:
      - Workspaces
      summary: Create directory
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '201':
          description: Directory created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workspaces/{id}/archive/upload:
    post:
      tags:
      - Workspaces
      summary: Upload archive (zip/tar.gz) to workspace
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Archive extracted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workspaces/{id}/archive/download:
    get:
      tags:
      - Workspaces
      summary: Download workspace as archive
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Archive download
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workspaces/{id}/reconcile:
    post:
      tags:
      - Workspaces
      summary: Reconcile workspace state
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Reconciled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workspaces/{id}/stats:
    get:
      tags:
      - Workspaces
      summary: Get workspace statistics
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Workspace stats
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workspaces/{id}/index-status:
    get:
      tags:
      - Workspaces
      summary: Get full-text index status
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Index status
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workspaces/{id}/git/clone:
    post:
      tags:
      - Workspaces
      summary: Clone git remote into workspace
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Clone started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workspaces/{id}/git/pull:
    post:
      tags:
      - Workspaces
      summary: Pull from remote
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Pull complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workspaces/{id}/git/push:
    post:
      tags:
      - Workspaces
      summary: Push to remote
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Push complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workspaces/{id}/git/status:
    get:
      tags:
      - Workspaces
      summary: Git status
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Working tree status
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workspaces/{id}/git/diff:
    get:
      tags:
      - Workspaces
      summary: Git diff
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Diff output
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workspaces/{id}/git/commit:
    post:
      tags:
      - Workspaces
      summary: Commit changes
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Committed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workspaces/{id}/git/log:
    get:
      tags:
      - Workspaces
      summary: Git log
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Commit history
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workspaces/{id}/git/branches:
    get:
      tags:
      - Workspaces
      summary: List git branches
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Branch list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workspaces/{id}/git/checkout:
    post:
      tags:
      - Workspaces
      summary: Checkout branch
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Checked out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/git-credentials:
    get:
      tags:
      - Workspaces
      summary: List git credentials
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Credential list (keys redacted)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Workspaces
      summary: Create git credential
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Credential created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/git-credentials/generate:
    post:
      tags:
      - Workspaces
      summary: Generate SSH key pair
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Key pair generated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workspace'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/git-credentials/{id}/public-key:
    get:
      tags:
      - Workspaces
      summary: Get SSH public key
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Public key
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workspace'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/git-credentials/{id}:
    delete:
      tags:
      - Workspaces
      summary: Delete git credential
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/tasks:
    get:
      tags:
      - Tasks
      summary: List user's tasks
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Task list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Tasks
      summary: Create task
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/tasks/{id}:
    get:
      tags:
      - Tasks
      summary: Get task
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Task object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Tasks
      summary: Update task
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Tasks
      summary: Delete task
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/tasks/{id}/runs:
    get:
      tags:
      - Tasks
      summary: List task runs
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Run history
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/tasks/{id}/run:
    post:
      tags:
      - Tasks
      summary: Execute task immediately
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Run started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/tasks/{id}/kill:
    post:
      tags:
      - Tasks
      summary: Kill running task
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Task killed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workflows:
    get:
      tags:
      - Workflows
      summary: List workflows
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Workflow list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Workflows
      summary: Create workflow
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Workflow created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workflows/{id}:
    get:
      tags:
      - Workflows
      summary: Get workflow
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Workflow object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Workflows
      summary: Update workflow
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Workflows
      summary: Delete workflow
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workflows/{id}/stages:
    get:
      tags:
      - Workflows
      summary: List workflow stages
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Stage list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Workflows
      summary: Create workflow stage
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '201':
          description: Stage created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workflows/{id}/stages/{sid}:
    put:
      tags:
      - Workflows
      summary: Update workflow stage
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: sid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Workflows
      summary: Delete workflow stage
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: sid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workflows/{id}/stages/reorder:
    patch:
      tags:
      - Workflows
      summary: Reorder workflow stages
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Reordered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workflows/{id}/publish:
    post:
      tags:
      - Workflows
      summary: Publish workflow version
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Published
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workflows/{id}/versions/{version}:
    get:
      tags:
      - Workflows
      summary: Get specific workflow version
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: version
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Version snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workflows/{id}/start:
    post:
      tags:
      - Workflows
      summary: Start workflow instance
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '201':
          description: Instance started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/channels/{id}/workflow/status:
    get:
      tags:
      - Workflows
      summary: Get workflow status for channel
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Workflow instance status
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/channels/{id}/workflow/advance:
    post:
      tags:
      - Workflows
      summary: Advance workflow to next stage
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Advanced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/channels/{id}/workflow/reject:
    post:
      tags:
      - Workflows
      summary: Reject and return to previous stage
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Rejected
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workflow-assignments/mine:
    get:
      tags:
      - Workflows
      summary: List assignments for current user
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Assignment list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/workflow-assignments/{id}:
    get:
      tags:
      - Workflows
      summary: Get assignment details
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Assignment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/workflow-assignments/{id}/claim:
    post:
      tags:
      - Workflows
      summary: Claim an assignment
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Claimed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workflow-assignments/{id}/complete:
    post:
      tags:
      - Workflows
      summary: Complete an assignment
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workflow-assignments/{id}/comment:
    post:
      tags:
      - Workflows
      summary: Add comment to assignment
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '201':
          description: Comment added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/w/{id}/form:
    get:
      tags:
      - Workflows
      summary: Get form template for workflow stage
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Form template JSON
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
  /api/v1/w/{id}/form-submit:
    post:
      tags:
      - Workflows
      summary: Submit form data for workflow stage
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Form submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/workflow-entry/{scope}/{slug}:
    post:
      tags:
      - Workflows
      summary: Start workflow as visitor
      parameters:
      - name: scope
        in: path
        required: true
        schema:
          type: string
      - name: slug
        in: path
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Workflow instance started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/notifications:
    get:
      tags:
      - Notifications
      summary: List notifications
      security:
      - bearerAuth: []
      parameters:
      - name: limit
        in: query
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: offset
        in: query
        schema:
          type: integer
          default: 0
      - name: unread_only
        in: query
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Notification list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Notification'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/notifications/unread-count:
    get:
      tags:
      - Notifications
      summary: Get unread notification count
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Unread count
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/notifications/{id}/read:
    patch:
      tags:
      - Notifications
      summary: Mark notification as read
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Marked read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notification'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/notifications/mark-all-read:
    post:
      tags:
      - Notifications
      summary: Mark all notifications as read
      security:
      - bearerAuth: []
      responses:
        '200':
          description: All marked read
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notification'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/notifications/{id}:
    delete:
      tags:
      - Notifications
      summary: Delete notification
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/notifications/preferences:
    get:
      tags:
      - Notifications
      summary: List notification preferences
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Preference list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Notification'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/notifications/preferences/{type}:
    put:
      tags:
      - Notifications
      summary: Set notification preference for type
      security:
      - bearerAuth: []
      parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                in_app:
                  type: boolean
                email:
                  type: boolean
      responses:
        '200':
          description: Preference set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notification'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      tags:
      - Notifications
      summary: Reset notification preference to default
      security:
      - bearerAuth: []
      parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Reset to default
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/extensions:
    get:
      tags:
      - Extensions
      summary: List user-visible extensions
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Extension list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/extensions/{id}/settings:
    post:
      tags:
      - Extensions
      summary: Update user extension settings
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Settings updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/extensions/{id}/manifest:
    get:
      tags:
      - Extensions
      summary: Get extension manifest
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Manifest JSON
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/extensions/tools:
    get:
      tags:
      - Extensions
      summary: List browser tool schemas from extensions
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Tool schema list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/surfaces:
    get:
      tags:
      - Surfaces
      summary: List enabled surface packages
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Surface list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Surface'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/packages:
    get:
      tags:
      - Extensions
      summary: List packages visible to user
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Package list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/packages/install:
    post:
      tags:
      - Extensions
      summary: Install personal package
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Package installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/packages/{id}:
    delete:
      tags:
      - Extensions
      summary: Delete personal package
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/users:
    get:
      tags:
      - Admin
      summary: List all users
      security:
      - bearerAuth: []
      responses:
        '200':
          description: User list
          content:
            application/json:
              schema: &id005
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AuthUser'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Admin
      summary: Create user
      security:
      - bearerAuth: []
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/users/{id}/role:
    put:
      tags:
      - Admin
      summary: Update user role
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Role updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/users/{id}/active:
    put:
      tags:
      - Admin
      summary: Toggle user active status
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Status toggled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/users/{id}/reset-password:
    post:
      tags:
      - Admin
      summary: Reset user password
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Password reset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/users/{id}/vault/reset:
    post:
      tags:
      - Admin
      summary: Reset user vault (BYOK keys lost)
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Vault reset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/users/{id}:
    delete:
      tags:
      - Admin
      summary: Delete user
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: User deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/users/{id}/permissions:
    get:
      tags:
      - Admin
      summary: Get effective permissions for user
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Permission list
          content:
            application/json:
              schema: &id003
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/settings:
    get:
      tags:
      - Admin
      summary: List all global settings
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Settings list
          content:
            application/json:
              schema: &id001
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/settings/{key}:
    get:
      tags:
      - Admin
      summary: Get global setting by key
      security:
      - bearerAuth: []
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Setting value
          content:
            application/json:
              schema: *id001
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Admin
      summary: Update global setting
      security:
      - bearerAuth: []
      parameters:
      - name: key
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Setting updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/configs:
    get:
      tags:
      - Admin
      - Providers
      summary: List global provider configs
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Provider config list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProviderConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Admin
      - Providers
      summary: Create global provider config
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Config created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/configs/{id}:
    put:
      tags:
      - Admin
      - Providers
      summary: Update global provider config
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Admin
      - Providers
      summary: Delete global provider config
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/models:
    get:
      tags:
      - Admin
      - Models
      summary: List model catalog
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Model catalog
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/models/fetch:
    post:
      tags:
      - Admin
      - Models
      summary: Sync models from provider APIs
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Models synced
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/models/bulk:
    put:
      tags:
      - Admin
      - Models
      summary: Bulk update model visibility
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Bulk updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/models/{id}:
    put:
      tags:
      - Admin
      - Models
      summary: Update model config
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Admin
      - Models
      summary: Delete model from catalog
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/models/{id}/capabilities:
    get:
      tags:
      - Admin
      - Models
      summary: Get model capability overrides
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Capabilities
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Admin
      - Models
      summary: Set model capability override
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Override set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/models/{id}/capabilities/{overrideId}:
    delete:
      tags:
      - Admin
      - Models
      summary: Delete capability override
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: overrideId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/capability-overrides:
    get:
      tags:
      - Admin
      - Models
      summary: List all capability overrides
      security:
      - bearerAuth: []
      responses:
        '200':
          description: All overrides
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/provider-types:
    get:
      tags:
      - Admin
      - Providers
      summary: List supported provider types
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Provider type registry
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProviderConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/personas:
    get:
      tags:
      - Admin
      - Personas
      summary: List global personas
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Global persona list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Persona'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Admin
      - Personas
      summary: Create global persona
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Persona created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/personas/{id}:
    put:
      tags:
      - Admin
      - Personas
      summary: Update global persona
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Admin
      - Personas
      summary: Delete global persona
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/personas/{id}/avatar:
    post:
      tags:
      - Admin
      - Personas
      summary: Upload global persona avatar
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Avatar uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
    delete:
      tags:
      - Admin
      - Personas
      summary: Delete global persona avatar
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Avatar removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/personas/{id}/knowledge-bases:
    get:
      tags:
      - Admin
      - Personas
      summary: Get global persona KB bindings
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: KB bindings
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Persona'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Admin
      - Personas
      summary: Set global persona KB bindings
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Bindings updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/personas/{id}/tool-grants:
    get:
      tags:
      - Admin
      - Personas
      summary: Get global persona tool grants
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Tool grants
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Persona'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Admin
      - Personas
      summary: Set global persona tool grants
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Grants updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Persona'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/memories/pending:
    get:
      tags:
      - Admin
      - Memory
      summary: List pending memories for review
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Pending memories
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Memory'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/memories/bulk-approve:
    post:
      tags:
      - Admin
      - Memory
      summary: Bulk approve pending memories
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Memories approved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Memory'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/teams:
    get:
      tags:
      - Admin
      - Teams
      summary: List all teams
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Team list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Admin
      - Teams
      summary: Create team
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Team created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/teams/{id}:
    get:
      tags:
      - Admin
      - Teams
      summary: Get team
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Team object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Admin
      - Teams
      summary: Update team
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Admin
      - Teams
      summary: Delete team
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/teams/{id}/members:
    get:
      tags:
      - Admin
      - Teams
      summary: List team members
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Member list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Admin
      - Teams
      summary: Add team member
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '201':
          description: Member added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/teams/{id}/members/{memberId}:
    put:
      tags:
      - Admin
      - Teams
      summary: Update team member
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: memberId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Admin
      - Teams
      summary: Remove team member
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: memberId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/teams/{id}/export:
    get:
      tags:
      - Admin
      - Teams
      - Data Portability
      summary: Export team data
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Team data archive
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/teams/{id}/import:
    post:
      tags:
      - Admin
      - Teams
      - Data Portability
      summary: Import team data
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Team data imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/notifications/broadcast:
    post:
      tags:
      - Admin
      - Notifications
      summary: Broadcast notification to all users
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - title
              - message
              properties:
                title:
                  type: string
                message:
                  type: string
                level:
                  type: string
                  enum:
                  - info
                  - warning
                  - critical
                  default: info
      responses:
        '200':
          description: Broadcast sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notification'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/notifications/test-email:
    post:
      tags:
      - Admin
      - Notifications
      summary: Send test email to admin
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Test email sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Notification'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/audit:
    get:
      tags:
      - Admin
      summary: List platform audit log
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Audit entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/audit/actions:
    get:
      tags:
      - Admin
      summary: List distinct audit actions
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Action list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: string
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/groups:
    get:
      tags:
      - Admin
      summary: List permission groups
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Group list
          content:
            application/json:
              schema: &id002
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Admin
      summary: Create permission group
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Group created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/groups/{id}:
    get:
      tags:
      - Admin
      summary: Get permission group
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Group object
          content:
            application/json:
              schema: *id002
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Admin
      summary: Update permission group
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Admin
      summary: Delete permission group
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/groups/{id}/members:
    get:
      tags:
      - Admin
      summary: List group members
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Member list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Admin
      summary: Add user to group
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '201':
          description: Member added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/groups/{id}/members/{userId}:
    delete:
      tags:
      - Admin
      summary: Remove user from group
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: userId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/permissions:
    get:
      tags:
      - Admin
      summary: List all available permissions
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Permission list
          content:
            application/json:
              schema: *id003
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/grants/{type}/{id}:
    get:
      tags:
      - Admin
      summary: Get resource grant
      security:
      - bearerAuth: []
      parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Grant object
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Admin
      summary: Set resource grant
      security:
      - bearerAuth: []
      parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Grant set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Admin
      summary: Delete resource grant
      security:
      - bearerAuth: []
      parameters:
      - name: type
        in: path
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/roles:
    get:
      tags:
      - Admin
      summary: List roles
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Role list
          content:
            application/json:
              schema: &id004
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/roles/{role}:
    get:
      tags:
      - Admin
      summary: Get role definition
      security:
      - bearerAuth: []
      parameters:
      - name: role
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Role object
          content:
            application/json:
              schema: *id004
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Admin
      summary: Update role permissions
      security:
      - bearerAuth: []
      parameters:
      - name: role
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/roles/{role}/test:
    post:
      tags:
      - Admin
      summary: Test role permission check
      security:
      - bearerAuth: []
      parameters:
      - name: role
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Test result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/usage/users/{id}:
    get:
      tags:
      - Admin
      - Usage
      summary: Usage for specific user
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: User usage
          content:
            application/json:
              schema: *id005
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/usage/teams/{id}:
    get:
      tags:
      - Admin
      - Usage
      summary: Usage for specific team
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Team usage
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/pricing:
    get:
      tags:
      - Admin
      - Usage
      summary: List pricing overrides
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Pricing list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      tags:
      - Admin
      - Usage
      summary: Upsert pricing override
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Pricing set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/pricing/{provider}/{model}:
    delete:
      tags:
      - Admin
      - Usage
      summary: Delete pricing override
      security:
      - bearerAuth: []
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
      - name: model
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/storage/status:
    get:
      tags:
      - Admin
      summary: Storage backend status
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Storage status
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/storage/orphans:
    get:
      tags:
      - Admin
      summary: Count orphaned storage objects
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Orphan count
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/storage/cleanup:
    post:
      tags:
      - Admin
      summary: Clean up orphaned storage objects
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Cleanup results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/storage/extraction:
    get:
      tags:
      - Admin
      summary: Text extraction pipeline status
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Extraction status
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/vault/status:
    get:
      tags:
      - Admin
      summary: Vault encryption status
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Vault status
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/channels/archived:
    get:
      tags:
      - Admin
      summary: List archived channels
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Archived channel list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Channel'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/channels/{id}/purge:
    delete:
      tags:
      - Admin
      summary: Permanently purge archived channel
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Purged
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/extensions:
    get:
      tags:
      - Admin
      - Extensions
      summary: List all extensions
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Extension list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Admin
      - Extensions
      summary: Install extension
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/extensions/{id}:
    put:
      tags:
      - Admin
      - Extensions
      summary: Update extension
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Admin
      - Extensions
      summary: Uninstall extension
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Uninstalled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/extensions/{id}/permissions:
    get:
      tags:
      - Admin
      - Extensions
      summary: List extension permissions
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Permission list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/extensions/{id}/review:
    get:
      tags:
      - Admin
      - Extensions
      summary: Review package permissions
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Review summary
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/extensions/{id}/permissions/{perm}/grant:
    post:
      tags:
      - Admin
      - Extensions
      summary: Grant extension permission
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: perm
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Granted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/extensions/{id}/permissions/{perm}/revoke:
    post:
      tags:
      - Admin
      - Extensions
      summary: Revoke extension permission
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      - name: perm
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Revoked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/extensions/{id}/permissions/grant-all:
    post:
      tags:
      - Admin
      - Extensions
      summary: Grant all requested permissions
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: All granted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/extensions/{id}/secrets:
    get:
      tags:
      - Admin
      - Extensions
      summary: Get extension secrets (redacted)
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Secret keys (values redacted)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Admin
      - Extensions
      summary: Set extension secrets
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Secrets set
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Admin
      - Extensions
      summary: Delete extension secrets
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Secrets deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/routing/policies:
    get:
      tags:
      - Admin
      - Providers
      summary: List routing policies
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Policy list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProviderConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Admin
      - Providers
      summary: Create routing policy
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Policy created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/routing/policies/{id}:
    get:
      tags:
      - Admin
      - Providers
      summary: Get routing policy
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Policy object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConfig'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Admin
      - Providers
      summary: Update routing policy
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Admin
      - Providers
      summary: Delete routing policy
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/routing/test:
    post:
      tags:
      - Admin
      - Providers
      summary: Dry-run routing evaluation
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Routing candidates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConfig'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/packages/registry:
    get:
      tags:
      - Admin
      - Extensions
      summary: Browse package registry
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Registry entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/packages/registry/install:
    post:
      tags:
      - Admin
      - Extensions
      summary: Install from registry
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/packages:
    get:
      tags:
      - Admin
      - Extensions
      summary: List installed packages
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Package list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/packages/{id}:
    get:
      tags:
      - Admin
      - Extensions
      summary: Get package details
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Package object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Admin
      - Extensions
      summary: Delete package
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/packages/install:
    post:
      tags:
      - Admin
      - Extensions
      summary: Install package from upload
      description: |
        Upload a .pkg/.surface/.zip archive containing manifest.json and
        optional assets. For starlark-tier packages, the archive must
        include `script.star` (or the manifest's `entry_point` value).
        Starlark submodules in `star/` are extracted alongside static
        assets (js/, css/, assets/). The manifest `entry_point` field
        overrides the default entry script name (v0.38.0).
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/packages/{id}/enable:
    put:
      tags:
      - Admin
      - Extensions
      summary: Enable package
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/packages/{id}/disable:
    put:
      tags:
      - Admin
      - Extensions
      summary: Disable package
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/packages/{id}/settings:
    get:
      tags:
      - Admin
      - Extensions
      summary: Get package settings
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Package settings
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Admin
      - Extensions
      summary: Update package settings
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Settings updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Extension'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/packages/{id}/export:
    get:
      tags:
      - Admin
      - Extensions
      summary: Export package as archive
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Package archive
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Extension'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  # ── Extension Dependencies (v0.38.2) ─────────────────────────────────
  /api/v1/admin/packages/{id}/dependencies:
    get:
      tags: [Admin, Extensions]
      summary: List libraries this package depends on
      description: "v0.38.2: Returns dependency records where this package is the consumer."
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Dependencies list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExtDependency'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/packages/{id}/consumers:
    get:
      tags: [Admin, Extensions]
      summary: List packages that depend on this library
      description: "v0.38.2: Returns dependency records where this package is the library."
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Consumers list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExtDependency'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/dependencies:
    get:
      tags: [Admin, Extensions]
      summary: List all package dependencies
      description: "v0.38.2: Returns the full dependency graph."
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Full dependency graph
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExtDependency'
        '401':
          $ref: '#/components/responses/Unauthorized'
  # ── Connection Type Discovery (v0.38.4) ─────────────────────────────
  /api/v1/connection-types:
    get:
      tags: [Extensions]
      summary: List available connection types
      description: |
        Returns merged connection types from all active packages.
        Library declarations take precedence over non-library declarations.
        Any authenticated user can call this endpoint.
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Connection type list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ConnectionType'
        '401':
          $ref: '#/components/responses/Unauthorized'
  # ── Extension Connections (v0.38.1) ─────────────────────────────────
  /api/v1/connections:
    get:
      tags: [Extensions]
      summary: List personal connections
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Personal connections (secrets masked)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ExtConnection'
    post:
      tags: [Extensions]
      summary: Create personal connection
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [type, package_id, name]
              properties:
                type: { type: string }
                package_id: { type: string }
                name: { type: string }
                config: { type: object }
      responses:
        '201':
          description: Created
  /api/v1/connections/{id}:
    get:
      tags: [Extensions]
      summary: Get personal connection
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Connection (secrets masked)
    put:
      tags: [Extensions]
      summary: Update personal connection
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                config: { type: object }
      responses:
        '200':
          description: Updated
    delete:
      tags: [Extensions]
      summary: Delete personal connection
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
  /api/v1/connections/resolve:
    get:
      tags: [Extensions]
      summary: Resolve connection via scope chain (personal > team > global)
      description: |
        Returns a single connection with decrypted config, resolved via
        the scope chain. Requires `type` query parameter. Optional `name`
        for named resolution.
      security:
      - bearerAuth: []
      parameters:
      - name: type
        in: query
        required: true
        schema: { type: string }
      - name: name
        in: query
        schema: { type: string }
      responses:
        '200':
          description: Resolved connection with decrypted config
        '404':
          description: No matching connection found
  /api/v1/teams/{teamId}/connections:
    get:
      tags: [Teams, Extensions]
      summary: List team connections
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/TeamID'
      responses:
        '200':
          description: Team connections
    post:
      tags: [Teams, Extensions]
      summary: Create team connection
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/TeamID'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [type, package_id, name]
              properties:
                type: { type: string }
                package_id: { type: string }
                name: { type: string }
                config: { type: object }
      responses:
        '201':
          description: Created
  /api/v1/teams/{teamId}/connections/{id}:
    put:
      tags: [Teams, Extensions]
      summary: Update team connection
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/TeamID'
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
    delete:
      tags: [Teams, Extensions]
      summary: Delete team connection
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/TeamID'
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
  /api/v1/admin/connections:
    get:
      tags: [Admin, Extensions]
      summary: List global connections
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Global connections
    post:
      tags: [Admin, Extensions]
      summary: Create global connection
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [type, package_id, name]
              properties:
                type: { type: string }
                package_id: { type: string }
                name: { type: string }
                config: { type: object }
      responses:
        '201':
          description: Created
  /api/v1/admin/connections/{id}:
    put:
      tags: [Admin, Extensions]
      summary: Update global connection
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
    delete:
      tags: [Admin, Extensions]
      summary: Delete global connection
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
  /api/v1/admin/workflows/{id}/export:
    get:
      tags:
      - Admin
      - Workflows
      summary: Export workflow as package
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Workflow package archive
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/workflows/monitor/instances:
    get:
      tags:
      - Admin
      - Workflows
      summary: List active workflow instances
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Active instance list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/workflows/monitor/funnel/{id}:
    get:
      tags:
      - Admin
      - Workflows
      summary: Get workflow stage funnel
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Funnel data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/workflows/monitor/stale:
    get:
      tags:
      - Admin
      - Workflows
      summary: List stale workflow instances
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Stale instances
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Workflow'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/surfaces:
    get:
      tags:
      - Admin
      - Surfaces
      summary: List installed surfaces
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Surface list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Surface'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/surfaces/{id}:
    delete:
      tags:
      - Admin
      - Surfaces
      summary: Delete surface
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/surfaces/install:
    post:
      tags:
      - Admin
      - Surfaces
      summary: Install surface package
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Surface'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/surfaces/{id}/enable:
    put:
      tags:
      - Admin
      - Surfaces
      summary: Enable surface
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Surface'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/surfaces/{id}/disable:
    put:
      tags:
      - Admin
      - Surfaces
      summary: Disable surface
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Surface'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/tasks:
    get:
      tags:
      - Admin
      - Tasks
      summary: List all tasks
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Task list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/tasks/{id}/run:
    post:
      tags:
      - Admin
      - Tasks
      summary: Force-run task
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Run started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/tasks/{id}/kill:
    post:
      tags:
      - Admin
      - Tasks
      summary: Kill task run
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Killed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/tasks/{id}:
    delete:
      tags:
      - Admin
      - Tasks
      summary: Delete task
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/admin/system-functions:
    get:
      tags:
      - Admin
      - Tasks
      summary: List registered system functions
      security:
      - bearerAuth: []
      responses:
        '200':
          description: System function registry
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/projects:
    get:
      tags:
      - Admin
      - Projects
      summary: List all projects (cross-user)
      security:
      - bearerAuth: []
      responses:
        '200':
          description: All projects
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/projects/{id}:
    delete:
      tags:
      - Admin
      - Projects
      summary: Delete project
      security:
      - bearerAuth: []
      parameters:
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/mine:
    get:
      tags:
      - Teams
      summary: List teams the current user belongs to
      security:
      - bearerAuth: []
      responses:
        '200':
          description: User's teams
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/teams/{teamId}/members:
    get:
      tags:
      - Teams
      summary: List team members
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Member list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Teams
      summary: Add team member
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: Member added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/teams/{teamId}/members/{memberId}:
    put:
      tags:
      - Teams
      summary: Update team member role
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: memberId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Teams
      summary: Remove team member
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: memberId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/models:
    get:
      tags:
      - Teams
      - Models
      summary: List models available to team
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Team model list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/providers:
    get:
      tags:
      - Teams
      - Providers
      summary: List team provider configs
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Team provider list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Teams
      - Providers
      summary: Create team provider config
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: Config created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/teams/{teamId}/providers/{id}:
    put:
      tags:
      - Teams
      - Providers
      summary: Update team provider config
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Teams
      - Providers
      summary: Delete team provider config
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/providers/{id}/models:
    get:
      tags:
      - Teams
      - Providers
      summary: List models for team provider
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Model list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/personas:
    get:
      tags:
      - Teams
      - Personas
      summary: List team personas
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Team persona list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Teams
      - Personas
      summary: Create team persona
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: Persona created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/teams/{teamId}/personas/{id}:
    put:
      tags:
      - Teams
      - Personas
      summary: Update team persona
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Teams
      - Personas
      summary: Delete team persona
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/personas/{id}/avatar:
    post:
      tags:
      - Teams
      - Personas
      summary: Upload team persona avatar
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Avatar uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
    delete:
      tags:
      - Teams
      - Personas
      summary: Delete team persona avatar
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Avatar removed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/personas/{id}/knowledge-bases:
    get:
      tags:
      - Teams
      - Personas
      summary: Get team persona KB bindings
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: KB bindings
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Teams
      - Personas
      summary: Set team persona KB bindings
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Bindings updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/personas/{id}/tool-grants:
    get:
      tags:
      - Teams
      - Personas
      summary: Get team persona tool grants
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Tool grants
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      tags:
      - Teams
      - Personas
      summary: Set team persona tool grants
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Grants updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/roles:
    get:
      tags:
      - Teams
      summary: List team roles
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Team role list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/roles/{role}:
    put:
      tags:
      - Teams
      summary: Update team role
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: role
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Teams
      summary: Delete team role
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: role
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/audit:
    get:
      tags:
      - Teams
      summary: Team audit log
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Audit entries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/audit/actions:
    get:
      tags:
      - Teams
      summary: List distinct team audit actions
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Action list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/usage:
    get:
      tags:
      - Teams
      - Usage
      summary: Team usage stats
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Team usage
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/groups:
    get:
      tags:
      - Teams
      summary: List groups for team
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Team groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/packages/install:
    post:
      tags:
      - Teams
      - Extensions
      summary: Install package for team
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: Package installed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/teams/{teamId}/packages/{id}:
    delete:
      tags:
      - Teams
      - Extensions
      summary: Delete team package
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/assignments:
    get:
      tags:
      - Teams
      - Workflows
      summary: List workflow assignments for team
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Team assignments
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/workflows:
    get:
      tags:
      - Teams
      - Workflows
      summary: List team workflows
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Team workflow list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Teams
      - Workflows
      summary: Create team workflow
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: Workflow created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/teams/{teamId}/workflows/{id}:
    get:
      tags:
      - Teams
      - Workflows
      summary: Get team workflow
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Workflow object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Teams
      - Workflows
      summary: Update team workflow
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Teams
      - Workflows
      summary: Delete team workflow
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/workflows/{id}/stages:
    get:
      tags:
      - Teams
      - Workflows
      summary: List team workflow stages
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Stage list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Teams
      - Workflows
      summary: Create team workflow stage
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '201':
          description: Stage created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/teams/{teamId}/workflows/{id}/stages/{sid}:
    put:
      tags:
      - Teams
      - Workflows
      summary: Update team workflow stage
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      - name: sid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Teams
      - Workflows
      summary: Delete team workflow stage
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      - name: sid
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/workflows/{id}/stages/reorder:
    patch:
      tags:
      - Teams
      - Workflows
      summary: Reorder team workflow stages
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Reordered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/workflows/{id}/publish:
    post:
      tags:
      - Teams
      - Workflows
      summary: Publish team workflow version
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Published
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/teams/{teamId}/workflows/{id}/versions/{version}:
    get:
      tags:
      - Teams
      - Workflows
      summary: Get team workflow version
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      - name: version
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Version snapshot
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/workflows/monitor/instances:
    get:
      tags:
      - Teams
      - Workflows
      summary: List team active workflow instances
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Active instances
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/tasks:
    get:
      tags:
      - Teams
      - Tasks
      summary: List team tasks (member view)
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Team task list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      tags:
      - Teams
      - Tasks
      summary: Create team task
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '201':
          description: Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/teams/{teamId}/tasks/{id}:
    put:
      tags:
      - Teams
      - Tasks
      summary: Update team task
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Teams
      - Tasks
      summary: Delete team task
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/teams/{teamId}/tasks/{id}/run:
    post:
      tags:
      - Teams
      - Tasks
      summary: Run team task
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Run started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/teams/{teamId}/tasks/{id}/kill:
    post:
      tags:
      - Teams
      - Tasks
      summary: Kill team task run
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Killed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/teams/{teamId}/tasks/{id}/runs:
    get:
      tags:
      - Teams
      - Tasks
      summary: List team task runs
      security:
      - bearerAuth: []
      parameters:
      - name: teamId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - $ref: '#/components/parameters/ResourceID'
      responses:
        '200':
          description: Run history
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /api/v1/groups/mine:
    get:
      tags:
      - Teams
      summary: List permission groups the user belongs to
      security:
      - bearerAuth: []
      responses:
        '200':
          description: User's groups
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Team'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/usage:
    get:
      tags:
      - Usage
      summary: Personal usage stats
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Personal usage
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/export/me:
    get:
      tags:
      - Data Portability
      summary: Export all user data (GDPR)
      security:
      - bearerAuth: []
      responses:
        '200':
          description: User data archive
          content:
            application/json:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/import/me:
    post:
      tags:
      - Data Portability
      summary: Import user data
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Data imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/import/chatgpt:
    post:
      tags:
      - Data Portability
      summary: Import ChatGPT conversation export
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Conversations imported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/me:
    delete:
      tags:
      - Data Portability
      summary: Delete account and all data (GDPR)
      security:
      - bearerAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - password
              properties:
                password:
                  type: string
                  description: Confirmation password
      responses:
        '200':
          description: Account deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/hooks/t/{token}:
    post:
      tags:
      - Workflows
      summary: Webhook trigger endpoint
      parameters:
      - name: token
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Trigger processed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Workflow'
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageResponse'
  /api/v1/admin/stats:
    get:
      tags:
      - Admin
      summary: Platform statistics
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Aggregate counts
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: integer
                  channels:
                    type: integer
                  messages:
                    type: integer
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/providers/health:
    get:
      tags:
      - Admin
      summary: Current health status for all providers
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Provider health summaries
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProviderHealth'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/usage:
    get:
      tags:
      - Admin
      - Usage
      summary: Aggregated token usage
      security:
      - bearerAuth: []
      parameters:
      - name: since
        in: query
        schema:
          type: string
          format: date-time
      - name: until
        in: query
        schema:
          type: string
          format: date-time
      - name: period
        in: query
        schema:
          type: string
          enum:
          - 7d
          - 30d
          - 90d
      - name: group_by
        in: query
        schema:
          type: string
          enum:
          - model
          - user
          - provider
          - day
      responses:
        '200':
          description: Usage data
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/v1/admin/dashboard:
    get:
      tags:
      - Admin
      summary: Real-time observability dashboard data
      description: 'Aggregates provider health, 24h usage, DB pool stats, WebSocket count,

        recent errors, and uptime into a single response.

        '
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Dashboard snapshot
          content:
            application/json:
              schema:
                type: object
                properties:
                  provider_health:
                    type: array
                    items:
                      $ref: '#/components/schemas/ProviderHealth'
                  usage_24h:
                    type: object
                  db_pool:
                    type: object
                    properties:
                      open_connections:
                        type: integer
                      in_use:
                        type: integer
                      idle:
                        type: integer
                  ws_connections:
                    type: integer
                  recent_errors:
                    type: array
                    items:
                      type: object
                  runtime:
                    type: object
                    properties:
                      goroutines:
                        type: integer
                      heap_mb:
                        type: integer
                      sys_mb:
                        type: integer
                      num_gc:
                        type: integer
                      go_version:
                        type: string
                  uptime:
                    type: string
                    description: Go duration string (e.g. "4h32m10s")
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT access token obtained via `POST /api/v1/auth/login` (builtin),

        OIDC callback, or mTLS auto-provisioning. 15-minute TTL, refreshable

        via `POST /api/v1/auth/refresh`.

        '
    mtlsAuth:
      type: mutualTLS
      description: 'Mutual TLS via reverse proxy headers. The proxy terminates TLS and

        forwards certificate DN fields. Configured via `AUTH_MODE=mtls`.

        No explicit login — user identity extracted from certificate on

        every request. Auto-provisions on first connection.

        '
  parameters:
    ResourceID:
      name: id
      in: path
      required: true
      description: Resource UUID
      schema:
        type: string
        format: uuid
    Page:
      name: page
      in: query
      description: Page number (1-indexed)
      schema:
        type: integer
        default: 1
        minimum: 1
    PerPage:
      name: per_page
      in: query
      description: Items per page
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 200
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing or invalid authentication
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: Resource conflict (duplicate, version mismatch)
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limited
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Human-readable error message
      example:
        error: resource not found
    MessageResponse:
      type: object
      properties:
        message:
          type: string
      example:
        message: operation completed
    AuthResponse:
      type: object
      properties:
        access_token:
          type: string
          description: JWT access token (15m TTL)
        refresh_token:
          type: string
          description: Opaque refresh token (7d TTL, rotation on use)
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          description: Access token TTL in seconds
          example: 900
        user:
          $ref: '#/components/schemas/AuthUser'
    AuthUser:
      type: object
      properties:
        id:
          type: string
          format: uuid
        username:
          type: string
        email:
          type: string
          format: email
        display_name:
          type: string
          nullable: true
        role:
          type: string
          enum:
          - admin
          - user
        handle:
          type: string
          description: Unique @mention handle
        auth_source:
          type: string
          enum:
          - builtin
          - oidc
          - mtls
    UserProfile:
      type: object
      properties:
        id:
          type: string
          format: uuid
        username:
          type: string
        email:
          type: string
          format: email
        display_name:
          type: string
          nullable: true
        role:
          type: string
          enum:
          - admin
          - user
        avatar:
          type: string
          nullable: true
          description: Data URI (PNG, 128x128). Null if unset.
        settings:
          type: object
          additionalProperties: true
          description: User preferences (theme, keybindings, etc.)
        created_at:
          type: string
          format: date-time
        last_login_at:
          type: string
          format: date-time
          nullable: true
    Channel:
      type: object
      properties:
        id:
          type: string
          format: uuid
        title:
          type: string
        type:
          type: string
          enum:
          - direct
          - group
          - dm
          - workflow
        user_id:
          type: string
          format: uuid
        team_id:
          type: string
          format: uuid
          nullable: true
        ai_mode:
          type: string
          enum:
          - auto
          - false
          - mention_only
        system_prompt:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        persona_id:
          type: string
          format: uuid
          nullable: true
        project_id:
          type: string
          format: uuid
          nullable: true
        settings:
          type: object
          additionalProperties: true
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    CompletionRequest:
      type: object
      required:
      - content
      - channel_id
      properties:
        channel_id:
          type: string
          format: uuid
        content:
          type: string
        model:
          type: string
          description: Override the default model
        persona_id:
          type: string
          format: uuid
        provider_config_id:
          type: string
          format: uuid
        max_tokens:
          type: integer
        temperature:
          type: number
          minimum: 0
          maximum: 2
        top_p:
          type: number
          minimum: 0
          maximum: 1
        stream:
          type: boolean
          default: true
        file_ids:
          type: array
          items:
            type: string
            format: uuid
        disabled_tools:
          type: array
          items:
            type: string
    CompletionResponse:
      type: object
      description: OpenAI-compatible non-streaming response
      properties:
        model:
          type: string
        choices:
          type: array
          items:
            type: object
            properties:
              message:
                type: object
                properties:
                  role:
                    type: string
                  content:
                    type: string
              finish_reason:
                type: string
        usage:
          $ref: '#/components/schemas/TokenUsage'
    TokenUsage:
      type: object
      properties:
        prompt_tokens:
          type: integer
        completion_tokens:
          type: integer
        total_tokens:
          type: integer
    ProviderHealth:
      type: object
      properties:
        provider_config_id:
          type: string
          format: uuid
        name:
          type: string
        provider_type:
          type: string
        status:
          type: string
          enum:
          - healthy
          - degraded
          - down
          - unknown
        request_count:
          type: integer
        error_count:
          type: integer
        error_rate:
          type: number
        avg_latency_ms:
          type: number
        max_latency_ms:
          type: integer
    Message:
      type: object
      properties:
        id:
          type: string
          format: uuid
        channel_id:
          type: string
          format: uuid
        parent_id:
          type: string
          format: uuid
          nullable: true
        role:
          type: string
          enum:
          - user
          - assistant
          - system
          - tool
        content:
          type: string
        model:
          type: string
          nullable: true
        provider_config_id:
          type: string
          format: uuid
          nullable: true
        participant_id:
          type: string
          format: uuid
          nullable: true
        participant_type:
          type: string
          enum:
          - user
          - persona
          - session
          nullable: true
        thinking:
          type: string
          nullable: true
        tool_calls:
          type: array
          items:
            type: object
          nullable: true
        tool_results:
          type: array
          items:
            type: object
          nullable: true
        attachments:
          type: array
          items:
            type: object
          nullable: true
        has_siblings:
          type: boolean
        sibling_index:
          type: integer
        sibling_count:
          type: integer
        created_at:
          type: string
          format: date-time
    Participant:
      type: object
      properties:
        id:
          type: string
          format: uuid
        channel_id:
          type: string
          format: uuid
        participant_type:
          type: string
          enum:
          - user
          - persona
          - session
        participant_id:
          type: string
          format: uuid
        role:
          type: string
          enum:
          - owner
          - member
          - observer
        display_name:
          type: string
        avatar_url:
          type: string
          nullable: true
        joined_at:
          type: string
          format: date-time
    FileObject:
      type: object
      properties:
        id:
          type: string
          format: uuid
        channel_id:
          type: string
          format: uuid
          nullable: true
        message_id:
          type: string
          format: uuid
          nullable: true
        user_id:
          type: string
          format: uuid
        origin:
          type: string
          enum:
          - user_upload
          - tool_output
          - system
        filename:
          type: string
        content_type:
          type: string
        size_bytes:
          type: integer
        display_hint:
          type: string
          enum:
          - inline
          - download
          - thumbnail
        extracted_text:
          type: string
          nullable: true
        metadata:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ToolDef:
      type: object
      properties:
        name:
          type: string
        display_name:
          type: string
        description:
          type: string
        category:
          type: string
        parameters:
          type: object
          description: JSON Schema for tool parameters
    PersonaInput:
      type: object
      required:
      - name
      - base_model_id
      properties:
        name:
          type: string
        handle:
          type: string
          description: Auto-generated from name if omitted
        description:
          type: string
        icon:
          type: string
        base_model_id:
          type: string
        provider_config_id:
          type: string
          format: uuid
        system_prompt:
          type: string
        temperature:
          type: number
        max_tokens:
          type: integer
        thinking_budget:
          type: integer
          nullable: true
        is_active:
          type: boolean
          default: true
        memory_enabled:
          type: boolean
          default: false
    ProviderConfigInput:
      type: object
      required:
      - name
      - provider
      - api_key
      properties:
        name:
          type: string
        provider:
          type: string
          description: Provider type slug (anthropic, openai, etc.)
        endpoint:
          type: string
          format: uri
        api_key:
          type: string
        model_default:
          type: string
        config:
          type: object
        headers:
          type: object
        settings:
          type: object
    Persona:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        handle:
          type: string
        description:
          type: string
        icon:
          type: string
        avatar:
          type: string
          nullable: true
        base_model_id:
          type: string
        provider_config_id:
          type: string
          format: uuid
          nullable: true
        system_prompt:
          type: string
        temperature:
          type: number
          nullable: true
        max_tokens:
          type: integer
          nullable: true
        thinking_budget:
          type: integer
          nullable: true
        scope:
          type: string
          enum:
          - personal
          - team
          - global
        owner_id:
          type: string
          format: uuid
          nullable: true
        is_active:
          type: boolean
        memory_enabled:
          type: boolean
        kb_ids:
          type: array
          items:
            type: string
            format: uuid
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Note:
      type: object
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        title:
          type: string
        content:
          type: string
        folder:
          type: string
          nullable: true
        source_message_id:
          type: string
          format: uuid
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    KnowledgeBase:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        scope:
          type: string
          enum:
          - personal
          - team
          - global
        owner_id:
          type: string
          format: uuid
          nullable: true
        team_id:
          type: string
          format: uuid
          nullable: true
        document_count:
          type: integer
        chunk_count:
          type: integer
        total_bytes:
          type: integer
        status:
          type: string
          enum:
          - active
          - processing
          - error
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Memory:
      type: object
      properties:
        id:
          type: string
          format: uuid
        scope:
          type: string
          enum:
          - user
          - persona
          - persona_user
        owner_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
          nullable: true
        key:
          type: string
        value:
          type: string
        source_channel_id:
          type: string
          format: uuid
          nullable: true
        confidence:
          type: number
        status:
          type: string
          enum:
          - active
          - pending_review
          - archived
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Project:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        color:
          type: string
          nullable: true
        icon:
          type: string
          nullable: true
        scope:
          type: string
          enum:
          - personal
          - team
          - global
        owner_id:
          type: string
          format: uuid
        team_id:
          type: string
          format: uuid
          nullable: true
        workspace_id:
          type: string
          format: uuid
          nullable: true
        is_archived:
          type: boolean
        settings:
          type: object
        channel_count:
          type: integer
        kb_count:
          type: integer
        note_count:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Workspace:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        owner_type:
          type: string
          enum:
          - user
          - project
          - channel
          - team
        owner_id:
          type: string
          format: uuid
        status:
          type: string
          enum:
          - active
          - archived
          - deleting
        max_bytes:
          type: integer
          nullable: true
        indexing_enabled:
          type: boolean
        git_remote_url:
          type: string
          nullable: true
        git_branch:
          type: string
          nullable: true
        git_credential_id:
          type: string
          format: uuid
          nullable: true
        git_last_sync:
          type: string
          format: date-time
          nullable: true
        file_count:
          type: integer
        total_bytes:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Task:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        task_type:
          type: string
          enum:
          - system
          - starlark
        schedule:
          type: string
          description: Cron expression
        trigger_type:
          type: string
          enum:
          - cron
          - manual
          - event
        owner_id:
          type: string
          format: uuid
        team_id:
          type: string
          format: uuid
          nullable: true
        is_active:
          type: boolean
        config:
          type: object
        last_run_at:
          type: string
          format: date-time
          nullable: true
        next_run_at:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Workflow:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        scope:
          type: string
          enum:
          - personal
          - team
          - global
        owner_id:
          type: string
          format: uuid
        team_id:
          type: string
          format: uuid
          nullable: true
        persona_id:
          type: string
          format: uuid
          nullable: true
        published_version:
          type: integer
          nullable: true
        is_active:
          type: boolean
        branding:
          type: object
          nullable: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Notification:
      type: object
      properties:
        id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        type:
          type: string
          description: domain.action convention
        title:
          type: string
        body:
          type: string
        resource_type:
          type: string
          nullable: true
        resource_id:
          type: string
          format: uuid
          nullable: true
        is_read:
          type: boolean
        created_at:
          type: string
          format: date-time
    ProviderConfig:
      type: object
      description: Provider config with API key redacted
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        provider:
          type: string
          description: Provider type slug
        endpoint:
          type: string
          format: uri
        model_default:
          type: string
          nullable: true
        scope:
          type: string
          enum:
          - personal
          - team
          - global
        owner_id:
          type: string
          format: uuid
          nullable: true
        is_active:
          type: boolean
        has_key:
          type: boolean
        config:
          type: object
        headers:
          type: object
        settings:
          type: object
        created_at:
          type: string
          format: date-time
    Team:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        settings:
          type: object
        member_count:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ConnectionType:
      type: object
      description: "v0.38.4: Available connection type from an installed package"
      properties:
        type:
          type: string
          description: Connection type identifier (e.g. gitea, slack)
        label:
          type: string
          description: Human-readable label
        package_id:
          type: string
          description: Package that declares this connection type
        package_title:
          type: string
          description: Title of the declaring package
        fields:
          type: object
          description: Field definitions (name → {type, required, label})
          additionalProperties:
            type: object
            properties:
              type:
                type: string
              required:
                type: string
              label:
                type: string
        scopes:
          type: array
          items:
            type: string
          description: Allowed scopes (global, team, personal)
    ExtDependency:
      type: object
      description: "v0.38.2: Package dependency record (consumer → library)"
      properties:
        consumer_id:
          type: string
          description: Package ID of the consumer
        library_id:
          type: string
          description: Package ID of the library
        version_spec:
          type: string
          description: Semver version spec declared by consumer
        resolved_ver:
          type: string
          description: Actual library version at dependency creation time
    ConfigSection:
      type: object
      description: "v0.38.3: Manifest-declared config section for Settings/Admin/Team Admin surfaces"
      properties:
        label:
          type: string
          description: Nav link text
        icon:
          type: string
          description: Optional SVG path data (compact format)
        component:
          type: string
          description: Relative asset path within package archive (default js/config.js)
        surfaces:
          type: array
          items:
            type: string
            enum: [admin, settings, team-admin]
          description: Which surfaces show this section
        category:
          type: string
          description: Admin-only category tab (default system)
    ExtConnection:
      type: object
      description: "v0.38.1: Extension connection credential (secrets masked in list responses)"
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          description: Connection type identifier (e.g. "gitea", "github")
        package_id:
          type: string
          description: Declaring package ID (UI attribution)
        scope:
          type: string
          enum: [global, team, personal]
        name:
          type: string
          description: User label (e.g. "Work Gitea")
        is_active:
          type: boolean
        has_config:
          type: boolean
          description: Whether config fields are set (secrets never exposed in list)
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Extension:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        slug:
          type: string
        version:
          type: string
        description:
          type: string
        type:
          type: string
          enum:
          - package
          - surface
        is_enabled:
          type: boolean
        permissions:
          type: array
          items:
            type: string
        created_at:
          type: string
          format: date-time
    Surface:
      $ref: '#/components/schemas/Extension'