Versioning and drafts

Published docs stay on /v1. Proposed changes go on /next until someone reviews and promotes them.

flowchart LR
  PR[PR against next]
  Preview[PR preview URL]
  Review[Review on next]
  Promote[Promote next to v1.x]
  Live["/v1 published"]
  PR --> Preview --> Review --> Promote --> Live

What lives where

Path	Role
docs/v1/	Human playbooks — implement these
docs/next/	Draft playbooks under review
specs/core/v1/openapi.yaml	Published Core Backend contract
specs/core/next/openapi.yaml	Proposed Core Backend contract
specs/middleware/v1/openapi.yaml	Published Middleware Backend contract
specs/middleware/next/openapi.yaml	Proposed Middleware Backend contract

How to propose a change

Example: “Move upload property from Core Backend to Middleware Backend.”

1. Add the Middleware Backend operation to specs/middleware/next/openapi.yaml.
2. Rewrite the Create property card on docs/next/ so the winner is Middleware Backend. Move the Core Backend URL to “Called by Middleware Backend, not by frontend.”
3. Add a row to /next/changelog: who must change (frontend / middleware / core).
4. Open a PR. Reviewers use the preview URL. v1 stays unchanged.
5. After approval: copy next → v1.1 (or v2 if breaking), update the version switcher, reset next.

Do not silently edit published v1 playbooks to point at a route that is not deployed.

Hosting

• Preferred: Vercel or Cloudflare Pages on this repo. Every PR gets a preview URL. Production custom domain: docs.bookdirect.live.
• Fallback: GitHub Actions (.github/workflows/deploy-docs.yml) builds VitePress and deploys GitHub Pages from main.
• Local: npm run docs:dev → http://localhost:5173

Contracts vs live Swagger

Source	Use for
specs/**/openapi.yaml in this repo	What teams should implement (API-first)
Core Backend explorer	What Core Backend actually has today
Middleware Backend explorer	What Middleware Backend actually has today

An iteration always diffs live explorers against the YAML, then updates playbooks. See prompts/iterate-docs.md.