feat: add review lanes and polish blog assets

Author: flyingrobots

QUICK_REFERENCE.md

@@ -113,12 +113,23 @@ All endpoints are served by `git cms serve` (default port 4638). Slugs are NFKC-
 | `POST` | `/api/cms/unpublish` | `{ slug }` | Unpublish an article |
 | `POST` | `/api/cms/revert` | `{ slug }` | Revert to draft state |
 | `GET` | `/api/cms/history` | `?slug=xxx&limit=50` | List version history (max 200) |
+| `GET` | `/api/cms/reviews` | `?slug=xxx` | List review lanes for one article |
+| `GET` | `/api/cms/review` | `?slug=xxx&laneId=yyy` | Read one review lane's visible proposal state |
+| `POST` | `/api/cms/review/create` | `{ slug, owner (optional) }` | Create a speculative review lane pinned to the current article state |
+| `POST` | `/api/cms/review/snapshot` | `{ slug, laneId, title, body, trailers (optional) }` | Save speculative edits into a review lane without touching the live draft |
+| `POST` | `/api/cms/review/apply` | `{ slug, laneId }` | Apply a review lane by writing a new draft commit |
 | `GET` | `/api/cms/show-version` | `?slug=xxx&sha=<oid>` | Read a specific historical version |
 | `POST` | `/api/cms/restore` | `{ slug, sha }` | Restore a historical version as new draft |
 | `POST` | `/api/cms/upload` | `{ slug, filename, data }` | Upload base64-encoded asset (optionally encrypted server-side) |
 
 Historical version endpoints currently assume Git's default SHA-1 object format and therefore validate 40-character hexadecimal commit IDs.
 
+Review-lane note:
+
+- review lanes use `git-warp` working sets for speculative editorial state
+- the live draft stays untouched until `POST /api/cms/review/apply`
+- apply writes a new draft commit; it does not replace history or mutate the working set into truth
+
 ---
 
 ## State Machine

README.md

@@ -6,7 +6,7 @@ A Git-native, database-free CMS: article bodies in commit messages, publish by m
 
 > "I'm using `git push` as my API endpoint."
 
-`git-cms` treats Git as an application substrate, not just a version-control tool. Article bodies live in commit messages on empty-tree commits. Draft and published state live in refs. History falls out of the storage model instead of being layered on afterward.
+`git-cms` treats Git as an application substrate, not just a version-control tool. Article bodies live in commit messages on empty-tree commits. Draft and published state live in refs. History falls out of the storage model instead of being layered on afterward. Review lanes use `git-warp` working sets so speculative edits can stay off the live draft until they are explicitly applied back as a new commit.
 
 Full article: [Git as CMS](https://flyingrobots.dev/git-stunts/git-cms)
 
@@ -69,6 +69,7 @@ The stunt is narrow on purpose:
 - published state lives at `refs/_blog/dev/published/<slug>`
 - publishing is pointer movement
 - restore writes a new commit from old content
+- review lanes live in `git-warp` working sets and apply back as new draft commits
 - history is the storage model
 
 The admin UI exists to prove the model is usable. It is not the point of the project.
@@ -120,6 +121,7 @@ git -C "$GIT_CMS_REPO" log refs/_blog/dev/articles/hello-world --graph --oneline
 - 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.
+- 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.
 
@@ -146,6 +148,7 @@ If you are here because of the article, start with `demo` or `sandbox`, not `dev
 - **Fast-forward publish semantics:** Published refs only move to the current draft tip
 - **Atomic publishes:** Publish is a CAS-protected ref update
 - **Infinite history:** Every draft save is a commit
+- **Speculative review lanes:** Review lanes use `git-warp` working sets and only affect the live article when you explicitly apply them
 - **Optional asset encryption:** Assets can be encrypted server-side via `@git-stunts/git-cas`
 
 ## Contributor Workflow

docs/GIT_CMS_COMPANION.md

@@ -65,6 +65,16 @@ With `npm run sandbox` running:
 
 The important thing is that restore does not rewrite history. It appends a new commit using older content.
 
+## Review Lanes
+
+`git-cms` now has one deliberately narrow editorial feature layered on top of the core draft/publish model: review lanes.
+
+- the live draft stays where it is
+- a review lane stores speculative edits in a `git-warp` working set
+- `Apply Lane` writes those edits back as a new draft commit
+
+That means a review lane is not a second truth. It is a pinned sidecar for proposed edits until you deliberately promote it.
+
 ## Key Code Paths
 
 If you want to read the implementation alongside the article, start here:
@@ -73,6 +83,7 @@ If you want to read the implementation alongside the article, start here:
   - `saveSnapshot()` for draft creation
   - `publishArticle()` for ref movement
   - `getArticleHistory()` and `restoreVersion()` for version browsing and restore
+  - `createReviewLane()`, `saveReviewLaneSnapshot()`, and `applyReviewLane()` for speculative editorial state
 - [src/server/index.js](../src/server/index.js)
   - thin HTTP layer over `CmsService`
 - [scripts/prepare-playground.sh](../scripts/prepare-playground.sh)
@@ -91,11 +102,13 @@ Good fit:
 
 Not the point:
 
-- rich editorial workflows
+- full editorial workflow platforms
 - search and plugin ecosystems
 - collaborative editing
 - mainstream CMS feature parity
 
+The new review lanes are intentionally small. They prove that `git-warp` can hold speculative editorial state cleanly, but they do not turn `git-cms` into a general collaborative CMS.
+
 ## Related Series Entries
 
 - [Welcome to Git Stunts](https://flyingrobots.dev/git-stunts/welcome-to-git-stunts)

docs/media/README.md

@@ -37,38 +37,45 @@ Implementation:
 
 ## `git-cas` terminal capture
 
-This repo also carries a VHS starter for the sibling `git-cas` project so the series can produce consistent terminal-native motion assets.
+This repo also carries VHS starters for the sibling `git-cas` project so the series can produce consistent terminal-native motion assets.
 
 Run it from this repo root:
 
 ```bash
 npm run capture:git-cas:vhs
+npm run capture:git-cas:tui
 ```
 
 Defaults:
 
 - expects the `git-cas` source repo at `$HOME/git/git-stunts/git-cas`
-- creates a temporary throwaway repo at `/tmp/git-cas-vhs-demo`
+- creates a synthetic media root at `/tmp/git-stunts-media`
+- symlinks the real source repo into `/tmp/git-stunts-media/git-cas`
+- creates a throwaway Git repo at `/tmp/git-stunts-media/repo`
 - renders a GIF into `docs/media/generated/git-cas/`
 
 Override the source repo path if needed:
 
 ```bash
 GIT_CAS_REPO=/absolute/path/to/git-cas npm run capture:git-cas:vhs
+GIT_CAS_REPO=/absolute/path/to/git-cas npm run capture:git-cas:tui
 ```
 
 Output file:
 
 - `docs/media/generated/git-cas/git-cas-inspect.gif`
+- `docs/media/generated/git-cas/git-cas-dashboard.gif`
 
 Implementation:
 
 - [vhs/git-cas-inspect.tape](../../vhs/git-cas-inspect.tape)
+- [vhs/git-cas-dashboard.tape](../../vhs/git-cas-dashboard.tape)
 - [scripts/render-git-cas-vhs.sh](../../scripts/render-git-cas-vhs.sh)
 
 ## Notes
 
 - The `git-cms` capture is meant for article-quality browser footage, not test coverage.
 - The filmed restore flow uses a draft-only article because restoring a still-published article is intentionally blocked by the product.
-- The VHS tape focuses on the `git-cas` inspect flow because it is concise, deterministic, and terminal-native.
+- The `git-cas` inspect tape is concise and deterministic. The dashboard tape captures the actual vault TUI.
+- The `git-cas` capture scripts intentionally render from synthetic `/tmp/git-stunts-media/...` paths and set a neutral shell prompt so the media does not leak local checkout paths like `/Users/james/...`.
 - If you want MP4 transcoding or caption burn-ins later, add that as a second pass. The canonical raw outputs here are WebM for browser footage and GIF for VHS.

package-lock.json

@@ -20,7 +20,8 @@
     "quickstart": "./scripts/quickstart.sh",
     "setup": "./scripts/setup.sh",
     "capture:cms": "node ./scripts/capture-cms-footage.mjs",
-    "capture:git-cas:vhs": "./scripts/render-git-cas-vhs.sh",
+    "capture:git-cas:vhs": "./scripts/render-git-cas-vhs.sh inspect",
+    "capture:git-cas:tui": "./scripts/render-git-cas-vhs.sh dashboard",
     "check:deps": "node scripts/check-dependency-integrity.mjs",
     "check:docs": "./scripts/check-doc-drift.sh",
     "test": "./test/run-docker.sh",
@@ -41,7 +42,7 @@
     "@git-stunts/alfred": "^0.10.3",
     "@git-stunts/docker-guard": "^0.1.0",
     "@git-stunts/git-cas": "^5.3.2",
-    "@git-stunts/git-warp": "^14.3.0",
+    "@git-stunts/git-warp": "^14.8.0",
     "@git-stunts/plumbing": "^2.8.0",
     "@git-stunts/trailer-codec": "^2.1.1",
     "@git-stunts/vault": "^1.0.1"