openapi.yml

openapi: 3.1.0
info:
  title: "@webhouse/cms API"
  version: "0.2.9"
  description: |
    Headless CMS REST API.

    **Public endpoints** (content, schema, manifest) are unauthenticated.
    **Admin endpoints** require a `cms-session` cookie (JWT) or `X-CMS-Service-Token` header.

    ### Authentication
    - **Session cookie:** Login via `POST /api/auth/login` → sets `cms-session` httpOnly cookie
    - **Service token:** Set `X-CMS-Service-Token: {CMS_JWT_SECRET}` header for machine-to-machine calls (heartbeat, cron)

    ### Field-level AI lock
    `_fieldMeta` is not included in standard document responses.
    Use the dedicated `/_fieldMeta` endpoints to read and manipulate lock state.

servers:
  - url: http://localhost:3000
    description: Local dev
  - url: "{baseUrl}"
    description: Custom
    variables:
      baseUrl:
        default: http://localhost:3000

tags:
  - name: Content
    description: CRUD operations on documents
  - name: FieldMeta
    description: Field-level lock and AI-provenance metadata
  - name: Schema
    description: Collection JSON Schemas (read-only)
  - name: Manifest
    description: CMS configuration and manifest
  - name: Auth
    description: Authentication (login, logout, session)
  - name: Admin
    description: Admin operations (profile, team, config, deploy)
  - name: Scheduler
    description: Heartbeat, scheduled tasks, calendar feed
  - name: Media
    description: File upload, media library, serving
  - name: AI
    description: AI generation, rewriting, agents, curation
  - name: MCP
    description: Model Context Protocol servers (public + admin)

# ---------------------------------------------------------------------------
# Reusable components
# ---------------------------------------------------------------------------
components:
  parameters:
    collection:
      name: collection
      in: path
      required: true
      schema:
        type: string
        example: posts
      description: Navn på collection som defineret i cms.config.ts

    slug:
      name: slug
      in: path
      required: true
      schema:
        type: string
        example: hello-world
      description: Dokumentets URL-slug

    fieldPath:
      name: fieldPath
      in: path
      required: true
      schema:
        type: string
        example: title
      description: Feltnavnet der skal låses/åbnes

    status:
      name: status
      in: query
      schema:
        $ref: "#/components/schemas/DocumentStatus"
      description: Filtrer på status

    limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        example: 20
      description: Maks antal dokumenter i svaret

    offset:
      name: offset
      in: query
      schema:
        type: integer
        minimum: 0
        example: 0
      description: Antal dokumenter at springe over (pagination)

    orderBy:
      name: orderBy
      in: query
      schema:
        type: string
        example: createdAt
      description: Felt at sortere på (createdAt, updatedAt, eller et data-felt)

    order:
      name: order
      in: query
      schema:
        type: string
        enum: [asc, desc]
        default: desc
      description: Sorteringsretning

    tags:
      name: tags
      in: query
      schema:
        type: string
        example: "typescript,cms"
      description: Komma-separeret liste af tags at filtrere på (AND logik)

  schemas:
    DocumentStatus:
      type: string
      enum: [draft, published, archived]

    FieldMeta:
      type: object
      description: |
        Per-felt metadata. Beskriver om feltet er låst og/eller AI-genereret.
        `lockedBy` angiver hvem der låste feltet — er den sat, vil AI-writes blive afvist.
      properties:
        lockedBy:
          type: string
          enum: [user, ai, import]
          description: Hvem der har låst feltet
        lockedAt:
          type: string
          format: date-time
          description: ISO-timestamp for hvornår feltet blev låst
        userId:
          type: string
          description: ID på brugeren der låste feltet (audit trail)
        reason:
          type: string
          description: Human-readable årsag til låsning (f.eks. "user-edit", "import", "manual-lock")
        aiGenerated:
          type: boolean
          description: Om feltets nuværende indhold er AI-genereret
        aiGeneratedAt:
          type: string
          format: date-time
          description: ISO-timestamp for hvornår AI genererede indholdet
        aiModel:
          type: string
          description: AI-modellen der genererede indholdet (f.eks. "claude-sonnet-4-6")

    DocumentFieldMeta:
      type: object
      description: Map fra feltnavn til FieldMeta
      additionalProperties:
        $ref: "#/components/schemas/FieldMeta"
      example:
        title:
          lockedBy: user
          lockedAt: "2024-06-01T10:00:00Z"
          userId: user-abc
          reason: user-edit
          aiGenerated: true
          aiGeneratedAt: "2024-05-31T09:00:00Z"
          aiModel: claude-sonnet-4-6
        content:
          aiGenerated: true
          aiGeneratedAt: "2024-05-31T09:00:00Z"
          aiModel: claude-sonnet-4-6

    Document:
      type: object
      required: [id, slug, collection, status, data, createdAt, updatedAt]
      properties:
        id:
          type: string
          description: Unik dokument-ID (nanoid)
          example: V1StGXR8_Z5jdHi6B-myT
        slug:
          type: string
          description: URL-venligt slug (unikt inden for collection)
          example: hello-world
        collection:
          type: string
          example: posts
        status:
          $ref: "#/components/schemas/DocumentStatus"
        data:
          type: object
          description: Dokumentets felt-data (fri form, defineret af collection-schema)
          additionalProperties: true
          example:
            title: Hello World
            content: "# Min første post"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        locale:
          type: string
          description: BCP 47 locale tag (e.g. "en", "da")
          example: en
        translationOf:
          type: string
          description: Slug of the source document (for translations)
          example: hello-world
        publishAt:
          type: string
          format: date-time
          description: Scheduled publish timestamp (ISO)
      description: |
        `_fieldMeta` returneres **ikke** i dette objekt.
        Brug `GET /{collection}/{slug}/_fieldMeta` for at hente det.

    DocumentList:
      type: object
      required: [documents, total]
      properties:
        documents:
          type: array
          items:
            $ref: "#/components/schemas/Document"
        total:
          type: integer
          description: Samlet antal dokumenter (uanset limit/offset)

    CreateDocumentBody:
      type: object
      required: [data]
      properties:
        slug:
          type: string
          description: Valgfrit. Autogenereres fra title-felt hvis udeladt.
        status:
          $ref: "#/components/schemas/DocumentStatus"
        data:
          type: object
          additionalProperties: true

    UpdateDocumentBody:
      type: object
      properties:
        slug:
          type: string
        status:
          $ref: "#/components/schemas/DocumentStatus"
        data:
          type: object
          additionalProperties: true
          description: Felter merges med eksisterende data (partial update)
        locale:
          type: string
          description: BCP 47 locale tag
        translationOf:
          type: string
          description: Slug of source document
        publishAt:
          type: string
          format: date-time
          description: Schedule publish at this time (null to clear)

    LockFieldBody:
      type: object
      properties:
        userId:
          type: string
          description: ID på den bruger der udfører låsningen (audit trail)
        reason:
          type: string
          description: Årsag til manuel låsning
          example: sensitive-copy

    LockAllBody:
      type: object
      properties:
        userId:
          type: string
          description: ID på den bruger der udfører bulk-låsningen

    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string

  responses:
    NotFound:
      description: Dokument eller collection ikke fundet
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
    BadRequest:
      description: Ugyldig input
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

# ---------------------------------------------------------------------------
# Root
# ---------------------------------------------------------------------------
paths:
  /:
    get:
      summary: API info
      operationId: getInfo
      tags: [Content]
      responses:
        "200":
          description: Navn, version og API-prefix
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    example: "@webhouse/cms"
                  version:
                    type: string
                    example: "0.1.0"
                  api:
                    type: string
                    example: /api

# ---------------------------------------------------------------------------
# Content
# ---------------------------------------------------------------------------
  /api/content/{collection}:
    get:
      summary: List dokumenter
      operationId: listDocuments
      tags: [Content]
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/status"
        - $ref: "#/components/parameters/limit"
        - $ref: "#/components/parameters/offset"
        - $ref: "#/components/parameters/orderBy"
        - $ref: "#/components/parameters/order"
        - $ref: "#/components/parameters/tags"
      responses:
        "200":
          description: Pagineret liste af dokumenter (uden _fieldMeta)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentList"
        "404":
          $ref: "#/components/responses/NotFound"

    post:
      summary: Opret dokument
      operationId: createDocument
      tags: [Content]
      parameters:
        - $ref: "#/components/parameters/collection"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateDocumentBody"
      responses:
        "201":
          description: Oprettet dokument (uden _fieldMeta)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Document"
        "400":
          $ref: "#/components/responses/BadRequest"

  /api/content/{collection}/{slug}:
    get:
      summary: Hent dokument
      operationId: getDocument
      tags: [Content]
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/slug"
      responses:
        "200":
          description: Dokument (uden _fieldMeta)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Document"
        "404":
          $ref: "#/components/responses/NotFound"

    put:
      summary: Opdater dokument
      operationId: updateDocument
      tags: [Content]
      description: |
        Felter i `data` merges med eksisterende data (shallow merge).
        Felter der er låst af en bruger vil **ikke** blive overskrevet —
        kaldet sker med `actor: user`, så eksisterende user-locks respekteres ikke her.
        Brug `/_fieldMeta`-endpoints til at styre locks manuelt.
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/slug"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateDocumentBody"
      responses:
        "200":
          description: Opdateret dokument (uden _fieldMeta)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Document"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

    delete:
      summary: Slet dokument
      operationId: deleteDocument
      tags: [Content]
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/slug"
      responses:
        "200":
          description: Slettet
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

# ---------------------------------------------------------------------------
# FieldMeta
# ---------------------------------------------------------------------------
  /api/content/{collection}/{slug}/_fieldMeta:
    get:
      summary: Hent field metadata
      operationId: getFieldMeta
      tags: [FieldMeta]
      description: |
        Returnerer `_fieldMeta` for dokumentet: lock-state og AI-provenance pr. felt.
        Denne information er stripet fra alle standard GET-responses.
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/slug"
      responses:
        "200":
          description: Field metadata map
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentFieldMeta"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/content/{collection}/{slug}/_fieldMeta/lock-all:
    put:
      summary: Lås alle AI-genererede felter
      operationId: lockAllFields
      tags: [FieldMeta]
      description: Sætter `lockedBy: user` på alle felter der har `aiGenerated: true`.
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/slug"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LockAllBody"
      responses:
        "200":
          description: Opdateret field metadata map
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentFieldMeta"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/content/{collection}/{slug}/_fieldMeta/unlock-all:
    put:
      summary: Fjern alle locks
      operationId: unlockAllFields
      tags: [FieldMeta]
      description: Fjerner `lockedBy`, `lockedAt`, `userId` og `reason` fra alle felter. AI-genererings-metadata bevares.
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/slug"
      responses:
        "200":
          description: Opdateret field metadata map
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DocumentFieldMeta"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/content/{collection}/{slug}/_fieldMeta/{fieldPath}/lock:
    put:
      summary: Lås enkelt felt manuelt
      operationId: lockField
      tags: [FieldMeta]
      description: |
        Sætter `lockedBy: user` på det angivne felt.
        Fremtidige AI-writes til dette felt vil blive afvist.
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/slug"
        - $ref: "#/components/parameters/fieldPath"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LockFieldBody"
      responses:
        "200":
          description: Opdateret FieldMeta for det låste felt
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldMeta"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

  /api/content/{collection}/{slug}/_fieldMeta/{fieldPath}/unlock:
    put:
      summary: Fjern lock fra enkelt felt
      operationId: unlockField
      tags: [FieldMeta]
      description: |
        Fjerner `lockedBy`, `lockedAt`, `userId` og `reason` fra feltet.
        AI-genererings-metadata (`aiGenerated`, `aiModel` osv.) bevares intakt.
      parameters:
        - $ref: "#/components/parameters/collection"
        - $ref: "#/components/parameters/slug"
        - $ref: "#/components/parameters/fieldPath"
      responses:
        "200":
          description: Opdateret FieldMeta for det åbnede felt
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FieldMeta"
        "400":
          $ref: "#/components/responses/BadRequest"
        "404":
          $ref: "#/components/responses/NotFound"

# ---------------------------------------------------------------------------
# Schema
# ---------------------------------------------------------------------------
  /api/schema:
    get:
      summary: Hent alle collection-schemas
      operationId: listSchemas
      tags: [Schema]
      responses:
        "200":
          description: Alle collections med JSON Schema
          content:
            application/json:
              schema:
                type: object
                properties:
                  collections:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        label:
                          type: string
                        slug:
                          type: string
                        jsonSchema:
                          type: object
                          description: JSON Schema for collectionens data-felter
                  blocks:
                    type: array
                    items:
                      type: object

  /api/schema/{collection}:
    get:
      summary: Hent schema for én collection
      operationId: getSchema
      tags: [Schema]
      parameters:
        - $ref: "#/components/parameters/collection"
      responses:
        "200":
          description: Collection med JSON Schema
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                  label:
                    type: string
                  jsonSchema:
                    type: object
        "404":
          $ref: "#/components/responses/NotFound"

# ---------------------------------------------------------------------------
# Manifest
# ---------------------------------------------------------------------------
  /api/manifest:
    get:
      summary: Get CMS manifest
      operationId: getManifest
      tags: [Manifest]
      description: Returns full CMS configuration (collections, build config, storage type, etc.)
      responses:
        "200":
          description: CMS manifest
          content:
            application/json:
              schema:
                type: object
                description: Serialized CmsConfig

# ---------------------------------------------------------------------------
# Auth
# ---------------------------------------------------------------------------
  /api/auth/login:
    post:
      summary: Log in
      operationId: login
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email: { type: string, example: "admin@example.com" }
                password: { type: string, example: "my-password" }
      responses:
        "200":
          description: Login successful — sets cms-session cookie
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  email: { type: string }
                  name: { type: string }
        "401":
          description: Invalid credentials

  /api/auth/logout:
    post:
      summary: Log out
      operationId: logout
      tags: [Auth]
      responses:
        "200":
          description: Session cookie cleared

  /api/auth/me:
    get:
      summary: Get current user
      operationId: getMe
      tags: [Auth]
      responses:
        "200":
          description: Authenticated user profile (or user: null)
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    nullable: true
                    properties:
                      id: { type: string }
                      email: { type: string }
                      name: { type: string }
                      role: { type: string, enum: [admin, editor, viewer] }
                      siteRole: { type: string, nullable: true }
                      zoom: { type: integer }

  /api/auth/setup:
    get:
      summary: Check if initial setup is needed
      operationId: checkSetup
      tags: [Auth]
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  hasUsers: { type: boolean }

    post:
      summary: Create first admin account
      operationId: setupAdmin
      tags: [Auth]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password, name]
              properties:
                email: { type: string }
                password: { type: string, minLength: 8 }
                name: { type: string }
      responses:
        "200":
          description: Account created — sets cms-session cookie
        "403":
          description: Setup already complete

# ---------------------------------------------------------------------------
# Scheduler & Heartbeat
# ---------------------------------------------------------------------------
  /api/cms/heartbeat:
    get:
      summary: Run all pending scheduled tasks
      operationId: heartbeat
      tags: [Scheduler]
      description: |
        Executes all pending scheduled tasks immediately:
        1. Publish/unpublish documents past their scheduled date
        2. Run due AI agents
        3. Run tools scheduler (backup, link check)
        4. Update calendar snapshot

        Designed to be called by an external cron (macOS crontab, GitHub Actions,
        or any uptime monitor) to keep scheduled tasks running even when the
        CMS admin has no interactive traffic.

        **Auth:** Requires `X-CMS-Service-Token` header matching `CMS_JWT_SECRET`.
      responses:
        "200":
          description: Tasks executed
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  durationMs: { type: integer, example: 1234 }
                  ran:
                    type: array
                    items: { type: string }
                    example: ["published: 2 doc(s)", "backup: completed", "snapshot: updated"]
                  errors:
                    type: array
                    items: { type: string }
                  timestamp: { type: string, format: date-time }
        "401":
          description: Missing or invalid service token

  /api/cms/scheduled/calendar.ics:
    get:
      summary: iCalendar feed of scheduled events
      operationId: calendarFeed
      tags: [Scheduler]
      description: |
        Returns an iCalendar (.ics) feed with all scheduled publish/unpublish events,
        upcoming backups, and link checks. Subscribe from Apple Calendar, Google Calendar, etc.

        **Auth:** Token-based via `?token=` query parameter (HMAC of user ID).
      parameters:
        - name: token
          in: query
          required: true
          schema: { type: string }
          description: HMAC token for calendar access
        - name: org
          in: query
          schema: { type: string }
          description: Organization ID
        - name: site
          in: query
          schema: { type: string }
          description: Site ID
      responses:
        "200":
          description: iCalendar feed
          content:
            text/calendar:
              schema:
                type: string
        "401":
          description: Invalid token

# ---------------------------------------------------------------------------
# Media
# ---------------------------------------------------------------------------
  /api/upload:
    post:
      summary: Upload file
      operationId: uploadFile
      tags: [Media]
      description: Upload a file to the media library. Supports images, audio, documents, SVG.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                folder:
                  type: string
                  description: Target folder (e.g. "images", "audio")
      responses:
        "200":
          description: Upload successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  url: { type: string, example: "/uploads/images/photo.jpg" }
                  filename: { type: string }
                  size: { type: integer }

  /api/media:
    get:
      summary: List media files
      operationId: listMedia
      tags: [Media]
      responses:
        "200":
          description: All media files with metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  files:
                    type: array
                    items:
                      type: object
                      properties:
                        name: { type: string }
                        url: { type: string }
                        folder: { type: string }
                        size: { type: integer }
                        type: { type: string, enum: [image, audio, document, svg] }

# ---------------------------------------------------------------------------
# AI Agents
# ---------------------------------------------------------------------------
  /api/cms/agents:
    get:
      summary: List AI agents
      operationId: listAgents
      tags: [AI]
      responses:
        "200":
          description: All agent configurations
    post:
      summary: Create AI agent
      operationId: createAgent
      tags: [AI]
      responses:
        "201":
          description: Agent created

  /api/cms/agents/{id}/run:
    post:
      summary: Run AI agent
      operationId: runAgent
      tags: [AI]
      description: Execute an agent with a prompt. Results go to curation queue or publish directly based on autonomy setting.
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt: { type: string }
                collection: { type: string }
      responses:
        "200":
          description: Agent execution result

# ---------------------------------------------------------------------------
# Curation
# ---------------------------------------------------------------------------
  /api/cms/curation:
    get:
      summary: List curation queue
      operationId: listCuration
      tags: [AI]
      description: AI-generated content waiting for human review.
      parameters:
        - name: stats
          in: query
          schema: { type: boolean }
          description: Include queue statistics
      responses:
        "200":
          description: Queue items

  /api/cms/curation/{id}/approve:
    post:
      summary: Approve curation item
      operationId: approveCuration
      tags: [AI]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Item approved and published/drafted

  /api/cms/curation/{id}/reject:
    post:
      summary: Reject curation item
      operationId: rejectCuration
      tags: [AI]
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        "200":
          description: Item rejected

# ---------------------------------------------------------------------------
# Admin
# ---------------------------------------------------------------------------
  /api/admin/profile:
    post:
      summary: Update user profile
      operationId: updateProfile
      tags: [Admin]
      description: Update name, email, password, zoom, or last active site.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                email: { type: string }
                currentPassword: { type: string }
                newPassword: { type: string, minLength: 8 }
                zoom: { type: integer }
                lastActiveOrg: { type: string }
                lastActiveSite: { type: string }
      responses:
        "200":
          description: Profile updated — new JWT cookie set
        "400":
          description: Validation error (wrong password, etc.)

  /api/admin/site-config:
    get:
      summary: Get site configuration
      operationId: getSiteConfig
      tags: [Admin]
      description: Returns site-specific settings (backup schedule, link check, revalidation, etc.) plus resolvedContentDir.
      responses:
        "200":
          description: Site configuration

    post:
      summary: Update site configuration
      operationId: updateSiteConfig
      tags: [Admin]
      responses:
        "200":
          description: Updated configuration
        "403":
          description: Admin role required

  /api/admin/backups:
    get:
      summary: List backups
      operationId: listBackups
      tags: [Admin]
      responses:
        "200":
          description: Backup manifest with snapshots

    post:
      summary: Create backup
      operationId: createBackup
      tags: [Admin]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                trigger: { type: string, enum: [manual, scheduled] }
      responses:
        "200":
          description: Backup created

  /api/admin/deploy:
    post:
      summary: Trigger deploy
      operationId: triggerDeploy
      tags: [Admin]
      description: Trigger a site deployment via configured deploy hook (Vercel, Netlify, Fly.io, etc.)
      responses:
        "200":
          description: Deploy triggered
        "400":
          description: No deploy hook configured

# ---------------------------------------------------------------------------
# MCP (Model Context Protocol)
# ---------------------------------------------------------------------------
  /api/mcp/info:
    get:
      summary: MCP server info
      operationId: mcpInfo
      tags: [MCP]
      description: Returns available MCP tools, collections, auth status, and rate limit info.
      responses:
        "200":
          description: MCP server metadata