fix(docs): publish only released documentation

1 files changed, 20 insertions, 7 deletions

diff --git a/website/README.md b/website/README.md
index fd8d8ea2..a511a861 100644
--- a/website/README.md
+++ b/website/README.md
@@ -1,21 +1,34 @@
 # herdr website
 
-The homepage is `index.html`. The documentation source is in `src/content/docs/` and is rendered by Astro Starlight.
+The homepage is `index.html`. Astro Starlight renders the documentation.
 
 ```bash
 bun install
-bun run dev
-bun run build
+bun run dev          # render the unpublished docs/next draft locally
+bun run build        # render only published stable and preview snapshots
+bun run build:draft  # validate the unpublished draft
 ```
 
 The build output is `dist/`. Configure Cloudflare Pages to use `website` as the project root and publish `dist`.
 
-Stable docs live in `src/content/docs/`. Unreleased docs live in `../docs/next/website/src/content/docs/` and are generated at `/docs/preview/`. Immutable release snapshots live in `../docs/versions/` and are generated at `/docs/<version>/`.
+Documentation has three lifecycle states:
 
-Do not promote docs manually before a release. After the GitHub Release succeeds, release CI runs:
+- `../docs/next/website/` is the committed, author-edited draft. Production builds never read it.
+- `../docs/preview/website/` is the latest preview release snapshot, rendered at `/docs/preview/`.
+- `../docs/versions/<version>/website/` contains immutable stable release snapshots, rendered at `/docs/<version>/`.
+
+The current stable site temporarily remains tracked under `src/content/docs/` because it contains post-v0.7.5 documentation corrections. The next stable release switches `docs/versions/manifest.json` to snapshot-backed stable docs and removes that legacy copy. From then on, `src/content/docs/` is entirely generated and ignored.
+
+Preview CI snapshots the selected commit and updates `preview.json` in one commit:
 
 ```bash
-node website/scripts/docs-versions.mjs publish <tag>
+node website/scripts/docs-preview.mjs snapshot <commit>
+node website/scripts/docs-preview.mjs check
 ```
 
-This snapshots the tagged next docs and promotes the same tagged content to stable before the website deploy. Use `node website/scripts/docs-versions.mjs check` to validate committed snapshots against their release tags.
+Stable release CI snapshots the exact tag after the GitHub Release succeeds:
+
+```bash
+node website/scripts/docs-versions.mjs publish <tag>
+node website/scripts/docs-versions.mjs check
+```