# Capabilities Manifest — cageandmirror.com
# Spec: https://perardua.dev/specs/capabilities

manifest:
  spec: "0.1"
  updated: "2026-03-26T00:00:00Z"
  canonical: "https://perardua.dev/specs/capabilities"

domain:
  name: "Cage and Mirror Publishing"
  url: "https://cageandmirror.com"
  description: >
    Publishing house for books on organizational theory, software craft,
    leadership, and privacy. Catalog of 7 titles. Limited edition pre-orders
    with Stripe checkout. Contact and support forms.
  contact: "contact@cageandmirror.com"
  tos: "/tos"
  privacy: "/privacy"

auth:
  - id: public
    type: none

read:
  # ── Book catalog ────────────────────────────────────────
  - id: books
    path: /books/
    description: "Complete book catalog with descriptions and cover images"
    auth: public
    response:
      format: text/html
    cache:
      ttl: 86400
      signal: stable

  - id: book
    path: /{slug}/
    description: "Individual book page with synopsis, author info, and purchase options"
    auth: public
    params:
      - name: slug
        type: string
        required: true
        description: "Book URL slug (e.g., beyond-code, cage-and-mirror)"
    response:
      format: text/html
    cache:
      ttl: 86400
      signal: stable

  # ── Essays and Research ─────────────────────────────────
  - id: essays
    path: /essays/
    description: "Essays on organizational theory, AI, and epistemology"
    auth: public
    response:
      format: text/html
    cache:
      ttl: 86400
      signal: stable

  - id: essay
    path: /essays/{slug}/
    description: "Individual essay"
    auth: public
    params:
      - name: slug
        type: string
        required: true
    response:
      format: text/html
    cache:
      ttl: 86400
      signal: stable

  - id: research
    path: /research/
    description: "Research papers index"
    auth: public
    response:
      format: text/html
    cache:
      ttl: 86400
      signal: stable

  # ── Author / Press ──────────────────────────────────────
  - id: author
    path: /author/
    description: "Author biography"
    auth: public
    response:
      format: text/html
    cache:
      ttl: 604800
      signal: stable

  - id: canon
    path: /canon/
    description: "Publishing canon and editorial philosophy"
    auth: public
    response:
      format: text/html
    cache:
      ttl: 604800
      signal: stable

  - id: press
    path: /press/
    description: "Press coverage and media mentions"
    auth: public
    response:
      format: text/html
    cache:
      ttl: 86400
      signal: stable

write:
  # ── Contact ─────────────────────────────────────────────
  - id: contact
    path: /api/contact
    method: POST
    description: "Submit a general inquiry"
    auth: public
    request:
      format: application/json
      fields:
        - name: name
          type: string
          required: true
          min_length: 2
        - name: email
          type: string
          required: true
          format: email
        - name: subject
          type: string
          required: true
          min_length: 3
        - name: message
          type: string
          required: true
          min_length: 10
    response:
      format: application/json
    idempotent: false
    side_effects:
      - "Stores inquiry"
      - "Sends email to contact@cageandmirror.com"

  # ── Support ─────────────────────────────────────────────
  - id: support
    path: /api/support
    method: POST
    description: "Submit a support or order issue"
    auth: public
    request:
      format: application/json
      fields:
        - name: name
          type: string
          required: true
          min_length: 2
        - name: email
          type: string
          required: true
          format: email
        - name: subject
          type: string
          required: true
          min_length: 3
        - name: message
          type: string
          required: true
          min_length: 10
    response:
      format: application/json
    idempotent: false
    side_effects:
      - "Stores support request"
      - "Sends email to support@cageandmirror.com"

  # ── Newsletter subscription ─────────────────────────────
  - id: subscribe
    path: /api/subscribe
    method: POST
    description: "Subscribe to email newsletter"
    auth: public
    request:
      format: application/json
      fields:
        - name: email
          type: string
          required: true
          format: email
        - name: context
          type: string
          required: false
          default: "homepage"
    response:
      format: application/json
    idempotent: false
    side_effects:
      - "Adds email to subscriber list"
      - "Sends notification to site owner"

  # ── Book pre-order (Stripe checkout) ────────────────────
  - id: checkout
    path: /api/create-checkout-session
    method: POST
    description: "Initiate Stripe checkout for limited edition book pre-order"
    auth: public
    request:
      format: application/json
      fields:
        - name: region
          type: string
          required: true
          enum: [us, canada, europe, international]
          description: "Shipping region determines available countries and rates"
    response:
      format: application/json
      description: "Returns {url: string} — Stripe hosted checkout page"
    payment:
      provider: stripe
      flow: redirect
      currency: usd
    idempotent: false
    side_effects:
      - "Creates Stripe checkout session"
      - "Redirects to Stripe payment page"
      - "On completion: creates order, charges payment, sends confirmation"

errors:
  format: application/json
