docs: tighten reader-facing release docs

Author: flyingrobots

GETTING_STARTED.md

@@ -1,3 +1,5 @@
 # Getting Started
 
 This guide has moved to [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md).
+
+If you came here from the article, you may also want the runnable appendix in [`docs/GIT_CMS_COMPANION.md`](docs/GIT_CMS_COMPANION.md).

QUICK_REFERENCE.md

@@ -124,6 +124,12 @@ All endpoints are served by `git cms serve` (default port 4638). Slugs are NFKC-
 
 Historical version endpoints currently assume Git's default SHA-1 object format and therefore validate 40-character hexadecimal commit IDs.
 
+Restore note:
+
+- `POST /api/cms/restore` appends a new draft commit from historical content
+- the article must not currently be in the `published` state
+- history remains append-only
+
 Review-lane note:
 
 - review lanes use `git-warp` working sets for speculative editorial state

README.md

@@ -14,6 +14,8 @@ If you want the runnable appendix rather than the essay, use the companion doc:
 
 - [docs/GIT_CMS_COMPANION.md](./docs/GIT_CMS_COMPANION.md)
 
+If you want the shortest possible first contact, run `npm run demo`. If you want a live system you can keep poking at, run `npm run sandbox`.
+
 ## If You Came Here From The Blog Post
 
 Use the reader-safe path first. It is isolated, seeded, and meant for live poking around:
@@ -68,7 +70,7 @@ The stunt is narrow on purpose:
 - draft state lives at `refs/_blog/dev/articles/<slug>`
 - published state lives at `refs/_blog/dev/published/<slug>`
 - publishing is pointer movement
-- restore writes a new commit from old content
+- restore writes a new commit from old content after the article is unpublished
 - review lanes live in `git-warp` working sets and apply back as new draft commits
 - history is the storage model
 
@@ -102,7 +104,7 @@ This starts the HTTP server on port `4638` against an isolated seeded repo. The
 
 - `hello-world` published at v1
 - two later draft commits ahead of published
-- enough history to make restore interesting immediately
+- enough history to make version browsing and restore interesting immediately
 
 ### 4. Inspect the seeded repo
 
@@ -120,7 +122,7 @@ git -C "$GIT_CMS_REPO" log refs/_blog/dev/articles/hello-world --graph --oneline
 - The article content is stored in the commit message.
 - The commit points at the empty tree.
 - Publishing moves `refs/_blog/dev/published/<slug>` to the current draft tip.
-- Restoring an old version creates a new commit instead of rewriting history.
+- Restoring an old version requires unpublishing first, then creates a new commit instead of rewriting history.
 - Review lanes hold speculative edits off to the side until `Apply Lane` writes them back as a fresh draft commit.
 
 This is the core of the stunt. Before Git can pretend to be a CMS, it has to behave like storage and state first.

REPO_WALKTHROUGH.md

@@ -1,3 +1,5 @@
 # Repository Walkthrough
 
 This content has been consolidated into [`QUICK_REFERENCE.md`](QUICK_REFERENCE.md).
+
+If you want the article-aligned walkthrough instead of the command index, start with [`docs/GIT_CMS_COMPANION.md`](docs/GIT_CMS_COMPANION.md).

TESTING_GUIDE.md

@@ -131,8 +131,8 @@ That also removes the long-lived sandbox repo volume.
 If you intentionally want to use the CLI on your host outside Docker, do it only in a dedicated repo you do not care about yet.
 
 ```bash
-mkdir ~/git-cms-playground
-cd ~/git-cms-playground
+mkdir ~/git-cms-sandbox
+cd ~/git-cms-sandbox
 git init
 git config user.name "Your Name"
 git config user.email "you@example.com"

docs/ADR.md

@@ -2,8 +2,8 @@
 ## Database-Free Content Management via Git Plumbing
 
 **Status:** Active
-**Version:** 1.0.0
-**Last Updated:** 2026-01-11
+**Version:** 1.2.1
+**Last Updated:** 2026-03-21
 **Author:** James Ross
 
 ---
@@ -418,7 +418,7 @@ Output:
 
 ---
 
-#### Module 3: `@git-stunts/git-warp` (v14.0.0)
+#### Module 3: `@git-stunts/git-warp` (v14.8.0)
 **Purpose:** Graph database primitive using commits on empty trees.
 
 **Public API:**
@@ -448,7 +448,7 @@ async commitNode({ message, parents = [], sign = false }) {
 
 ---
 
-#### Module 4: `@git-stunts/git-cas` (v5.3.0)
+#### Module 4: `@git-stunts/git-cas` (v5.3.2)
 **Purpose:** Content-Addressable Store for large files.
 
 **Public API:**
@@ -482,7 +482,7 @@ class ContentAddressableStore {
 
 ---
 
-#### Module 5: `@git-stunts/vault` (v1.0.0)
+#### Module 5: `@git-stunts/vault` (v1.0.1)
 **Purpose:** OS keychain integration for secrets.
 
 **Public API:**
@@ -885,7 +885,7 @@ graph TB
         TestRunner --> TempRepos
     end
 
-    DevMachine -->|docker compose up playground| NodeApp
+    DevMachine -->|npm run sandbox| NodeApp
     Browser -->|HTTP:4638| NodeApp
     DevMachine -->|docker compose run test| TestRunner
 
@@ -955,7 +955,7 @@ CMD ["npm", "run", "test:local"]
 
 **Deployment Steps:**
 ```bash
-docker compose up playground    # Start isolated seeded playground on http://localhost:4638
+docker compose up playground    # Start isolated seeded sandbox on http://localhost:4638
 docker compose up app           # Start contributor dev server against the checkout repo
 docker compose run --rm test  # Run tests in isolated container
 ```

docs/GETTING_STARTED.md

@@ -103,15 +103,15 @@ What you should see:
 - the article body inside the commit message
 - an empty-tree commit
 - a published ref behind the current draft ref
-- multiple restore-worthy historical commits
+- multiple historical commits worth browsing and restoring
 
 ## Seeded Sandbox State
 
 The sandbox deliberately starts with an interesting repo:
 
 - `hello-world` published at v1
 - draft v2 and v3 ahead of published
-- a history chain you can browse and restore immediately
+- a history chain you can browse immediately and restore after unpublishing
 
 That means the UI is alive on first load and the Git inspection commands have something real to show.
 
@@ -124,9 +124,10 @@ While `npm run sandbox` is running:
 3. Compare the current draft with the published state
 4. Open the History panel
 5. Preview an older version
-6. Restore it and watch a new commit appear
+6. Try Restore and note that the UI blocks it while the article is still published
+7. Unpublish, then restore, and watch a new draft commit appear
 
-The important thing to notice is that restore does **not** rewrite history. It appends a new draft commit with old content.
+The important thing to notice is that restore does **not** rewrite history. It appends a new draft commit with old content, but only after the article leaves the `published` state.
 
 ## Contributor Path
 
@@ -166,7 +167,7 @@ To stop services and remove volumes:
 docker compose down -v
 ```
 
-That removes the long-lived playground repo volume too.
+That removes the long-lived sandbox repo volume too.
 
 ## Tests