docs: rationalize root docs and move guide under docs

.gitignore

@@ -7,3 +7,4 @@ lastchat.txt
 AGENTS.md
 EDITORS-REPORT
 EDITORS-REPORT.*
+CODE-EVAL.md

CHANGELOG.md

@@ -31,6 +31,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Planning lifecycle clarified** — live backlog items now exclude delivered work, archive directories now hold retired backlog history and reserved retired design space, landed cycle docs use explicit landed status, and the design/backlog indexes now reflect current truth instead of stale activity.
 - **Architecture map repaired** — [ARCHITECTURE.md](./ARCHITECTURE.md) now describes the shipped system instead of an older flat-manifest-only model, including Merkle manifests, the extracted `VaultService` and `KeyResolver`, current ports/adapters, and the real storage layout for trees and the vault.
 - **Architecture navigation clarified** — [ARCHITECTURE.md](./ARCHITECTURE.md) now distinguishes the public package boundary from internal domain helpers and links directly to [docs/THREAT_MODEL.md](./docs/THREAT_MODEL.md) as adjacent truth.
+- **Guide moved under docs and repaired** — the long-form guide now lives at [docs/GUIDE.md](./docs/GUIDE.md), links back to the canonical API/security docs, uses current `restore --oid` syntax, and no longer teaches stale EventEmitter-first or internal-import-heavy workflows for common use.
 - **Security doc discoverability improved** — [README.md](./README.md), [CONTRIBUTING.md](./CONTRIBUTING.md), [WORKFLOW.md](./WORKFLOW.md), [ARCHITECTURE.md](./ARCHITECTURE.md), [docs/API.md](./docs/API.md), and [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md) now link more directly to [SECURITY.md](./SECURITY.md) and [docs/THREAT_MODEL.md](./docs/THREAT_MODEL.md) so maintainers and agents can find the canonical security guidance from the docs they read first.
 - **GitHub Actions runtime maintenance** — CI and release workflows now run on `actions/checkout@v6` and `actions/setup-node@v6`, clearing the Node 20 deprecation warnings from GitHub-hosted runners.
 - **Ubuntu-based Docker test stages** — the local/CI Node, Bun, and Deno test images now build on `ubuntu:24.04`, copying runtime binaries from the official upstream images instead of inheriting Debian-based runtime images directly, and the final test commands now run as an unprivileged `gitstunts` user.

CONTRIBUTING.md

@@ -99,8 +99,8 @@ That means:
 - backlog items are cheap, single-file work candidates
 - invariants are explicit project truths that work cannot violate
 
-This project still uses IBM Design Thinking framing, but it is now applied at
-the cycle level with both human and agent passes:
+This project still uses a design-thinking framing, but it is now applied at the
+cycle level with both human and agent passes:
 
 - human users, jobs, and hills
 - agent users, jobs, and hills
@@ -328,8 +328,6 @@ Before making non-trivial changes, read:
 - [docs/THREAT_MODEL.md](./docs/THREAT_MODEL.md)
 - [docs/API.md](./docs/API.md)
 - [docs/RELEASE.md](./docs/RELEASE.md)
-- [COMPLETED_TASKS.md](./COMPLETED_TASKS.md)
-- [CODE-EVAL.md](./CODE-EVAL.md)
 
 ## Decision Rule
 

README.md

@@ -376,7 +376,7 @@ CLI flags always take precedence over `.casrc` values.
 
 ## Documentation
 
-- [Guide](./GUIDE.md) — progressive walkthrough
+- [Guide](./docs/GUIDE.md) — progressive walkthrough
 - [API Reference](./docs/API.md) — full method documentation
 - [Architecture](./ARCHITECTURE.md) — hexagonal design overview
 - [Security](./SECURITY.md) — cryptographic design, limits, and operational guidance

ROADMAP.md

@@ -26,7 +26,9 @@ It now follows the workflow defined in [CONTRIBUTING.md](./CONTRIBUTING.md):
 `main` is the playback truth. If code lands out of order, the roadmap adjusts to
 match reality instead of pretending the original sequence still happened.
 
-Completed milestone detail lives in [COMPLETED_TASKS.md](./COMPLETED_TASKS.md).
+Delivered cycle detail now lives in
+[docs/design/README.md](./docs/design/README.md) and
+[docs/archive/BACKLOG/README.md](./docs/archive/BACKLOG/README.md).
 Superseded work lives in [GRAVEYARD.md](./GRAVEYARD.md).
 
 ## Current Reality
@@ -342,6 +344,7 @@ Additional release discipline:
 - [ROADMAP.md](./ROADMAP.md): current reality plus future sequence
 - [STATUS.md](./STATUS.md): compact project snapshot
 - [WORKFLOW.md](./WORKFLOW.md): planning and delivery source of truth for fresh work
-- [COMPLETED_TASKS.md](./COMPLETED_TASKS.md): shipped milestone details
+- [docs/design/README.md](./docs/design/README.md): landed cycle history
+- [docs/archive/BACKLOG/README.md](./docs/archive/BACKLOG/README.md): archived backlog cards
 - [GRAVEYARD.md](./GRAVEYARD.md): superseded or merged-away work
 - [CHANGELOG.md](./CHANGELOG.md): release-by-release history

STATUS.md

@@ -93,4 +93,4 @@ behavior.
 
 ---
 
-_Future detail: [ROADMAP.md](./ROADMAP.md) | Shipped detail: [COMPLETED_TASKS.md](./COMPLETED_TASKS.md) | Release history: [CHANGELOG.md](./CHANGELOG.md)_
+_Future detail: [ROADMAP.md](./ROADMAP.md) | Cycle history: [docs/design/README.md](./docs/design/README.md) | Release history: [CHANGELOG.md](./CHANGELOG.md)_

WORKFLOW.md

@@ -99,7 +99,7 @@ Every active cycle design doc should include:
 - risks and unknowns
 - retrospective
 
-Design here follows IBM Design Thinking twice:
+Design here follows a two-pass design-thinking approach:
 
 - once for humans
 - once for agents
@@ -201,7 +201,7 @@ The detailed pass lives in [docs/DOCS_CHECKLIST.md](./docs/DOCS_CHECKLIST.md).
 
 ## Cycle Workflow
 
-1. Design docs first, using the human and agent IBM Design Thinking passes.
+1. Design docs first, using the human and agent design-thinking passes.
 2. Tests are the spec. Write failing tests first.
 3. Green the tests.
 4. Run human and agent playbacks.

docs/BACKLOG/README.md

@@ -32,6 +32,8 @@ Current backlog items:
 - [TR-005 — CasService Decomposition Plan](./TR-005-casservice-decomposition-plan.md)
 - [TR-008 — Empty-State Phrasing Consistency](./TR-008-empty-state-phrasing-consistency.md)
 - [TR-011 — Streaming Encrypted Restore](./TR-011-streaming-encrypted-restore.md)
+- [TR-012 — Examples Surface Audit](./TR-012-examples-surface-audit.md)
+- [TR-014 — Markdown Surface Rationalization](./TR-014-markdown-surface-rationalization.md)
 
 Archived delivered backlog items:
 

docs/BACKLOG/TR-012-examples-surface-audit.md

@@ -0,0 +1,44 @@
+# TR-012 — Examples Surface Audit
+
+## Legend
+
+- [TR — Truth](../legends/TR-truth.md)
+
+## Why This Exists
+
+The `examples/` directory is part of the repo's public teaching surface, but it
+has not had a recent accuracy and relevance pass against the current API,
+workflow, and runtime story.
+
+Examples that are stale, redundant, or misleading create the same trust problem
+as stale docs, except they also invite copy-paste mistakes.
+
+## Target Outcome
+
+Audit the `examples/` surface and make a concrete recommendation for each entry:
+
+- keep
+- cut
+- merge
+- move
+- refresh for accuracy
+
+## Human Value
+
+Maintainers and adopters should be able to trust that example files still teach
+current, relevant `git-cas` usage instead of historical or partial patterns.
+
+## Agent Value
+
+Agents should be able to cite, update, or remove examples with a clear view of
+which ones still belong in the repo and why.
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Notes
+
+- audit both the top-level `examples/README.md` and the example programs
+- check API accuracy, not just prose quality
+- distinguish educational value from nostalgia

docs/BACKLOG/TR-014-markdown-surface-rationalization.md

@@ -0,0 +1,49 @@
+# TR-014 — Markdown Surface Rationalization
+
+## Legend
+
+- [TR — Truth](../legends/TR-truth.md)
+
+## Why This Exists
+
+The repo has accumulated a broad Markdown surface at the root and under `docs/`
+across different planning eras.
+
+Some of those files clearly belong where they are. Some probably need to be
+cut, merged, or moved. Without a deliberate audit, the repo keeps paying a
+navigation and review tax on every docs-heavy change.
+
+## Target Outcome
+
+Audit tracked Markdown files across the repo and make a recommendation for each
+one using the categories:
+
+- keep
+- cut
+- merge
+- move
+
+More than one recommendation may apply to a single file when a document should
+be retained only after being split, relocated, or merged.
+
+## Human Value
+
+Maintainers should have a clearer map of which Markdown artifacts are canonical,
+which are migration surfaces, and which should stop occupying high-visibility
+locations.
+
+## Agent Value
+
+Agents should be able to plan doc work against a more intentional Markdown
+surface instead of inheriting a flat pile of legacy and canonical files with
+equal apparent status.
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Notes
+
+- include root-level Markdown in the audit, not just `docs/`
+- explicitly call out which artifacts belong at the repo root
+- separate current canonical docs from migration surfaces and local-only files