git-stunts · flyingrobots · Mar 16, 2026 · Feb 14, 2026 · Feb 15, 2026 · Feb 15, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,23 @@
 
 All notable changes to git-cms are documented in this file.
 
+## [1.1.4] — 2026-02-14
+
+### Changed
+
+- Consolidate and update documentation for M1.1, M1.2, M1.3, CE2, and CE3
+- `QUICK_REFERENCE.md` is now the canonical reference for all 9 CLI commands, 10 HTTP API endpoints, and state machine
+- `docs/GETTING_STARTED.md` updated with version history, migration, unpublish/revert workflows
+- `README.md` updated with missing CLI commands and choose-your-path navigation
+- `ROADMAP.md` milestone statuses updated (M1.1, M1.2, M1.3, CE2, CE3 → complete)
+- Root `GETTING_STARTED.md` and `REPO_WALKTHROUGH.md` replaced with redirect stubs
+- `docs/ADR.md` file tree updated (removed `REPO_WALKTHROUGH.md`, added `CONTENT_ID_POLICY.md` and `LAYOUT_SPEC.md`)
+
+### Added
+
+- `scripts/check-doc-drift.sh` — automated doc drift detection (CLI commands, HTTP endpoints, stale references)
+- `npm run check:docs` script
+
 ## [1.1.3] — 2026-02-14
 
 ### Fixed
@@ -102,6 +119,7 @@ All notable changes to git-cms are documented in this file.
 - **(P2) walkLimit divergence:** Extracted `HISTORY_WALK_LIMIT` as a shared exported constant used by both `_validateAncestry` and the server's history limit clamp
 
 [Unreleased]: https://github.com/flyingrobots/git-cms/compare/main...git-stunts
+[1.1.4]: https://github.com/flyingrobots/git-cms/compare/v1.1.3...v1.1.4
 [1.1.3]: https://github.com/flyingrobots/git-cms/compare/v1.1.2...v1.1.3
 [1.1.2]: https://github.com/flyingrobots/git-cms/compare/v1.1.1...v1.1.2
 [1.1.1]: https://github.com/flyingrobots/git-cms/compare/v1.1.0...v1.1.1

diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md
@@ -1,73 +1,3 @@
-# Getting Started with Git CMS
+# Getting Started
 
-This quick guide is the lightweight entry point. For the full Docker-focused walkthrough in the docs folder, see [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md).
-
----
-
-## Prerequisites
-
-- Git
-- Node.js 22+
-- Docker Desktop (recommended for safe testing)
-
----
-
-## Installation
-
-### Option A: Local CLI Install
-
-```bash
-git clone https://github.com/flyingrobots/git-cms.git
-cd git-cms
-npm install
-npm link
-```
-
-### Option B: Docker (Recommended)
-
-```bash
-git clone https://github.com/flyingrobots/git-cms.git
-cd git-cms
-npm run setup
-npm run dev
-```
-
-Open the UI at [http://localhost:4638/](http://localhost:4638/).
-
----
-
-## First Article
-
-1. Click `+ New Article`.
-2. Set a slug like `my-first-post`.
-3. Add title + body content.
-4. Click `Save Draft`.
-5. Click `Publish` when ready.
-
----
-
-## CLI Basics
-
-```bash
-# Draft reads content from stdin
-echo "# Hello" | git cms draft hello-world "Hello World"
-
-# List drafts
-git cms list
-
-# Publish
-git cms publish hello-world
-
-# Show article
-git cms show hello-world
-```
-
----
-
-## Safety Notes
-
-- Prefer Docker workflows while learning.
-- Use a dedicated test repository for local CLI experimentation.
-- Avoid running low-level Git plumbing in repositories you care about.
-
-See [`TESTING_GUIDE.md`](TESTING_GUIDE.md) for safety and cleanup procedures.
+This guide has moved to [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md).
diff --git a/QUICK_REFERENCE.md b/QUICK_REFERENCE.md
@@ -1,6 +1,8 @@
 # Git CMS Quick Reference
 
-One-page cheat sheet for Git CMS commands and concepts.
+> Validated against v1.1.3 on 2026-02-14.
+
+One-page cheat sheet for Git CMS commands, API endpoints, and concepts.
 
 ---
 
@@ -27,10 +29,25 @@ npm run demo   # Watch a guided walkthrough
 | `npm test` | Run integration tests in Docker |
 | `npm run test:setup` | Run setup-script tests (BATS) |
 | `npm run test:local` | Run Vitest directly on host (advanced) |
+| `npm run check:docs` | Check documentation drift against source code |
 
 ---
 
-## CLI Commands (Inside Container)
+## CLI Commands
+
+All 9 commands available via `node bin/git-cms.js <command>` or `git cms <command>` (if linked):
+
+| Command | Usage | Description |
+|---------|-------|-------------|
+| `draft` | `echo "body" \| git cms draft <slug> "Title"` | Create or update a draft (reads body from stdin) |
+| `publish` | `git cms publish <slug>` | Fast-forward published ref to match draft |
+| `unpublish` | `git cms unpublish <slug>` | Remove from published, keep as unpublished draft |
+| `revert` | `git cms revert <slug>` | Revert published/unpublished article back to draft state |
+| `list` | `git cms list` | List all draft articles |
+| `show` | `git cms show <slug>` | Print article title and body |
+| `serve` | `git cms serve` | Start HTTP API + Admin UI on port 4638 |
+| `migrate` | `git cms migrate` | Run pending layout migrations (forward-only, idempotent) |
+| `layout-version` | `git cms layout-version` | Print repo and codebase layout versions |
 
 ```bash
 # Enter container
@@ -45,12 +62,24 @@ node bin/git-cms.js list
 # Publish a draft
 node bin/git-cms.js publish my-slug
 
+# Unpublish
+node bin/git-cms.js unpublish my-slug
+
+# Revert to draft
+node bin/git-cms.js revert my-slug
+
 # Read article content
 node bin/git-cms.js show my-slug
 
 # Start HTTP API + Admin UI
 node bin/git-cms.js serve
 
+# Check layout version
+node bin/git-cms.js layout-version
+
+# Run pending migrations
+node bin/git-cms.js migrate
+
 # Exit container
 exit
 ```
@@ -59,6 +88,64 @@ exit
 
 ---
 
+## HTTP API
+
+All endpoints are served by `git cms serve` (default port 4638). Slugs are NFKC-normalized on the server.
+
+| Method | Path | Params / Body | Description |
+|--------|------|---------------|-------------|
+| `GET` | `/api/cms/list` | `?kind=articles\|published` | List articles by kind |
+| `GET` | `/api/cms/show` | `?slug=xxx&kind=articles` | Read article content |
+| `POST` | `/api/cms/snapshot` | `{ slug, title, body, trailers? }` | Create or update a draft |
+| `POST` | `/api/cms/publish` | `{ slug, sha? }` | Publish a draft |
+| `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/show-version` | `?slug=xxx&sha=<40-hex>` | 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 (encrypted) |
+
+---
+
+## State Machine
+
+Articles move through four states. Transitions are enforced by `ContentStatePolicy.js`.
+
+```text
+States: draft, published, unpublished, reverted
+
+         ┌──────────┐
+         │  draft    │◄──────────────────────┐
+         └────┬──────┘                       │
+              │ publish                      │ revert
+              ▼                              │
+         ┌──────────┐    unpublish    ┌──────┴─────┐
+         │ published │───────────────►│ unpublished │
+         └────┬──────┘                └──────┬──────┘
+              │ publish (update)             │ publish
+              └──────────┐                   │
+                         ▼                   │
+                    ┌──────────┐             │
+                    │ published │◄────────────┘
+                    └──────────┘
+
+         ┌──────────┐
+         │ reverted  │──── revert (from draft) ────►  draft
+         └──────────┘
+```
+
+**Effective state** is derived from which refs exist:
+- Draft ref only → `draft`
+- Both draft + published refs → `published`
+- Draft ref with `Status: unpublished` trailer → `unpublished`
+- Draft ref with `Status: reverted` trailer → `reverted`
+
+**Restoring a version creates a new commit — git-cms never rewrites history.**
+
+See [`docs/LAYOUT_SPEC.md`](docs/LAYOUT_SPEC.md) for the full ref namespace and state derivation rules.
+
+---
+
 ## Core Concept
 
 ### Traditional CMS
@@ -89,6 +176,22 @@ The trick: content lives in commit messages while commits point at the repo's em
 
 ---
 
+## Architecture (Lego Blocks)
+
+```text
+git-cms
+  -> CmsService (orchestrator)
+     -> @git-stunts/plumbing (Git execution)
+     -> @git-stunts/trailer-codec (trailer encode/decode)
+     -> @git-stunts/git-warp (commit graph primitives)
+     -> @git-stunts/git-cas (asset chunk + manifest storage)
+     -> @git-stunts/vault (secret/key resolution)
+```
+
+This replaced older in-repo helpers (`src/lib/git.js`, `src/lib/parse.js`, `src/lib/chunks.js`, `src/lib/secrets.js`).
+
+---
+
 ## Inspecting with Git
 
 ```bash
@@ -107,20 +210,6 @@ git hash-object -t tree /dev/null
 
 ---
 
-## Architecture (Lego Blocks)
-
-```text
-git-cms
-  -> CmsService (orchestrator)
-     -> @git-stunts/plumbing (Git execution)
-     -> @git-stunts/trailer-codec (trailer encode/decode)
-     -> @git-stunts/git-warp (commit graph primitives)
-     -> @git-stunts/git-cas (asset chunk + manifest storage)
-     -> @git-stunts/vault (secret/key resolution)
-```
-
----
-
 ## Commit Message Shape
 
 ```text
@@ -139,6 +228,19 @@ Trailers are parsed by `@git-stunts/trailer-codec`.
 
 ---
 
+## Testing Surface
+
+| Test File | Coverage |
+|-----------|----------|
+| `test/git.test.js` | Integration tests — CRUD, publish, unpublish, revert, state machine, content identity |
+| `test/chunks.test.js` | Asset encryption and chunking |
+| `test/server.test.js` | HTTP API endpoints, validation, error responses |
+| `test/git-e2e.test.js` | Real-git smoke tests (subprocess forks) |
+| `test/setup.bats` | Setup script tests (BATS) |
+| `test/run-docker.sh` | Docker test harness |
+
+---
+
 ## Troubleshooting
 
 ### Cannot find module `@git-stunts/...`
@@ -166,9 +268,21 @@ Start Docker Desktop (macOS/Windows) or start Docker service on Linux.
 
 ## Docs Map
 
-- `README.md`: overview + quick start
-- `TESTING_GUIDE.md`: safe test workflow
-- `docs/GETTING_STARTED.md`: full walkthrough
-- `docs/ADR.md`: architecture decision record
-- `scripts/README.md`: helper script docs
-- `test/README.md`: test suite docs
+| File | Contents |
+|------|----------|
+| [`README.md`](README.md) | Overview + quick start |
+| [`TESTING_GUIDE.md`](TESTING_GUIDE.md) | Safe test workflow |
+| [`QUICK_REFERENCE.md`](QUICK_REFERENCE.md) | This file — canonical CLI/API/state machine reference |
+| [`ROADMAP.md`](ROADMAP.md) | M0–M6 milestone plan |
+| [`docs/GETTING_STARTED.md`](docs/GETTING_STARTED.md) | Full onboarding walkthrough |
+| [`docs/ADR.md`](docs/ADR.md) | Architecture decision record |
+| [`docs/CONTENT_ID_POLICY.md`](docs/CONTENT_ID_POLICY.md) | Slug validation and content identity rules |
+| [`docs/LAYOUT_SPEC.md`](docs/LAYOUT_SPEC.md) | Ref namespace, layout versions, migration policy |
+| [`scripts/README.md`](scripts/README.md) | Helper script docs |
+| [`test/README.md`](test/README.md) | Test suite docs |
+
+**Removed docs** (redirect stubs remain for one release cycle):
+- `GETTING_STARTED.md` (root) — moved to `docs/GETTING_STARTED.md`
+- `REPO_WALKTHROUGH.md` — consolidated into this file
+
+**Repository:** [https://github.com/flyingrobots/git-cms](https://github.com/flyingrobots/git-cms)
diff --git a/README.md b/README.md
@@ -43,7 +43,7 @@ npm run dev
 
 The tests create, destroy, and manipulate Git repositories. Running low-level plumbing commands on your host filesystem is risky - a typo could affect your local Git setup. That's why we built Docker isolation into everything.
 
-**Read more:** [TESTING_GUIDE.md](./TESTING_GUIDE.md) | [docs/GETTING_STARTED.md](./docs/GETTING_STARTED.md) | [docs/CONTENT_ID_POLICY.md](./docs/CONTENT_ID_POLICY.md)
+**Read more:** [TESTING_GUIDE.md](./TESTING_GUIDE.md) | [docs/GETTING_STARTED.md](./docs/GETTING_STARTED.md) | [QUICK_REFERENCE.md](./QUICK_REFERENCE.md) | [docs/CONTENT_ID_POLICY.md](./docs/CONTENT_ID_POLICY.md)
 
 ## Features
 
@@ -129,6 +129,32 @@ Publishing fast-forwards `refs/_blog/published/<slug>` to match the draft.
 git cms publish hello-world
 ```
 
+### 6. Unpublish / Revert
+
+```bash
+# Remove from published, keep as unpublished draft
+git cms unpublish hello-world
+
+# Revert to draft state
+git cms revert hello-world
+```
+
+### 7. Layout Version / Migrate
+
+```bash
+# Check repo vs codebase layout version
+git cms layout-version
+
+# Run pending layout migrations (forward-only, idempotent)
+git cms migrate
+```
+
+## Where to Go Next
+
+- **New user?** Start with [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md)
+- **Operator / API user?** See [`QUICK_REFERENCE.md`](./QUICK_REFERENCE.md) for all CLI commands and HTTP endpoints
+- **Architecture / rationale?** Read [`docs/ADR.md`](./docs/ADR.md) and [`docs/LAYOUT_SPEC.md`](./docs/LAYOUT_SPEC.md)
+
 ## License
 
 Copyright © 2026 James Ross. This software is licensed under the [Apache License](./LICENSE), Version 2.0