docs: audit examples surface

CHANGELOG.md

@@ -28,10 +28,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **README rewritten** — the front page now focuses on current product truth, clear quick starts, operational caveats, and the canonical doc map instead of mixing release history, marketing copy, and reference detail.
 - **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.
+- **Markdown surface map added** — [docs/MARKDOWN_SURFACE.md](./docs/MARKDOWN_SURFACE.md) now records a per-file `KEEP` / `CUT` / `MERGE` / `MOVE` recommendation across the tracked Markdown surface, including which root docs still belong at the repo front door and which remaining artifacts are migration or local-only candidates.
+- **Examples surface audited** — [examples/README.md](./examples/README.md) now records the recommendation for each maintained example, and the store/restore example now uses the public `readManifest()` helper instead of manual manifest decoding through service internals.
 - **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.

docs/BACKLOG/README.md

@@ -32,8 +32,7 @@ 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)
+- [TR-015 — Platform-Agnostic CLI Plan](./TR-015-platform-agnostic-cli-plan.md)
 
 Archived delivered backlog items:
 

docs/BACKLOG/TR-015-platform-agnostic-cli-plan.md

@@ -0,0 +1,61 @@
+# TR-015 — Platform-Agnostic CLI Plan
+
+## Legend
+
+- [TR — Truth](../legends/TR-truth.md)
+
+## Why This Exists
+
+`git-cas` already maintains a real Node, Bun, and Deno test matrix, but the
+human CLI entrypoint is still a Node-specific launcher.
+
+[bin/git-cas.js](../../bin/git-cas.js) depends directly on:
+
+- the `#!/usr/bin/env node` launcher model
+- `node:` built-ins for file, path, URL, and readline behavior
+- direct `process` access for argv, env, stdin, stdout, and stderr
+- Node-oriented file helpers and prompt flows under `bin/` and `src/`
+
+That means the repo is closer to "runtime-tested core with a Node CLI" than to
+"portable command surface with multiple distribution options."
+
+## Target Outcome
+
+Produce a design-backed plan for making the CLI runtime-neutral at the command
+core while being honest about distribution realities, including:
+
+- what must move out of the Node-specific launcher
+- what runtime adapter boundary should exist for argv, stdio, prompts, file
+  access, and exit behavior
+- whether file-backed store/restore helpers should stay Node-only or move
+  behind a portable interface
+- what `@git-stunts/plumbing` assumptions still block true portability
+- how per-platform packaged binaries should follow after the runtime boundary is
+  clean
+
+## Human Value
+
+Maintainers should be able to reason clearly about what "platform agnostic"
+means here, what work is required to get there, and whether the repo should aim
+for multi-runtime source portability, compiled binaries, or both.
+
+## Agent Value
+
+Agents should be able to propose bounded follow-on work around CLI portability
+without hand-waving past the current Node-specific launcher, TTY helpers, and
+Git runner assumptions.
+
+## Linked Invariants
+
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+
+## Notes
+
+- distinguish runtime-agnostic command logic from platform-specific binary
+  packaging
+- prefer a small runtime adapter boundary over scattering `globalThis.Bun` /
+  `globalThis.Deno` checks throughout command code
+- treat Git runner behavior and subprocess semantics as first-class constraints,
+  not an afterthought
+- do not promise a single universal binary; prefer a portable codebase with
+  explicit per-platform artifacts if packaging is pursued

docs/MARKDOWN_SURFACE.md

@@ -0,0 +1,205 @@
+# Markdown Surface Map
+
+This document audits the tracked Markdown surface in `git-cas` and makes an
+explicit recommendation for each file:
+
+- `KEEP` — the file belongs where it is
+- `CUT` — the file should stop existing in its current tracked form
+- `MERGE` — the file's value should move into one or more other docs
+- `MOVE` — the file should live elsewhere in the repo
+
+More than one recommendation can apply at once.
+
+## Root Policy
+
+The repo root should contain only a small set of high-traffic, front-door, or
+canonical project docs:
+
+- package/front-door docs
+- contributor and workflow docs
+- security and architecture docs
+- release history
+
+Planning history, archive material, long-form tutorials, and tool-specific
+instruction files should prefer `docs/`, `docs/archive/`, or local-only
+surfaces.
+
+## Root Markdown
+
+- [README.md](../README.md): `KEEP` — package front door and adoption surface;
+  belongs at the repo root.
+- [CHANGELOG.md](../CHANGELOG.md): `KEEP` — canonical release history; belongs
+  at the repo root.
+- [CONTRIBUTING.md](../CONTRIBUTING.md): `KEEP` — contributor doctrine and
+  onboarding surface; belongs at the repo root.
+- [SECURITY.md](../SECURITY.md): `KEEP` — canonical security guidance and
+  vulnerability-routing surface; belongs at the repo root.
+- [WORKFLOW.md](../WORKFLOW.md): `KEEP` — planning and delivery model for fresh
+  work; belongs at the repo root.
+- [ARCHITECTURE.md](../ARCHITECTURE.md): `KEEP` — canonical high-level
+  architecture map; still useful as a root-level reference.
+- [ROADMAP.md](../ROADMAP.md): `MOVE`, `CUT` — useful as migration and sequence
+  context today, but too specialized and too drift-prone for permanent
+  root-level residency.
+- [STATUS.md](../STATUS.md): `MERGE`, `CUT` — compact snapshot value is real,
+  but it largely overlaps with the README, roadmap, and changelog.
+- [GRAVEYARD.md](../GRAVEYARD.md): `KEEP`, `MOVE` — still useful historical
+  context, but it belongs under `docs/archive/` instead of the repo root.
+- [CLAUDE.md](../CLAUDE.md): `CUT`, `MOVE` — tool-specific instruction files
+  should not occupy tracked root doctrine alongside canonical project docs.
+
+## Canonical Docs Under `docs/`
+
+- [docs/API.md](./API.md): `KEEP` — canonical API reference; belongs under
+  `docs/`.
+- [docs/THREAT_MODEL.md](./THREAT_MODEL.md): `KEEP` — canonical threat model;
+  belongs under `docs/`.
+- [docs/BENCHMARKS.md](./BENCHMARKS.md): `KEEP` — benchmark guidance and
+  published baselines belong under `docs/`.
+- [docs/RELEASE.md](./RELEASE.md): `KEEP` — release runbook belongs under
+  `docs/`.
+- [docs/DOCS_CHECKLIST.md](./DOCS_CHECKLIST.md): `KEEP` — maintainer-facing docs
+  review checklist belongs under `docs/`.
+- [docs/GUIDE.md](./GUIDE.md): `KEEP` — the long-form tutorial should exist, but
+  under `docs/`, not at the repo root.
+- [docs/ADR-001-vault-in-facade.md](./ADR-001-vault-in-facade.md): `KEEP` —
+  accepted architecture decision record; current placement is fine until there
+  is a broader ADR collection.
+- [docs/MARKDOWN_SURFACE.md](./MARKDOWN_SURFACE.md): `KEEP` — this audit belongs
+  under `docs/` as repo-maintainer guidance, not at the root.
+
+## Live Planning Surface
+
+- [docs/BACKLOG/README.md](./BACKLOG/README.md): `KEEP` — canonical live backlog
+  index.
+- [docs/BACKLOG/TR-005-casservice-decomposition-plan.md](./BACKLOG/TR-005-casservice-decomposition-plan.md):
+  `KEEP` — active backlog work item.
+- [docs/BACKLOG/TR-008-empty-state-phrasing-consistency.md](./BACKLOG/TR-008-empty-state-phrasing-consistency.md):
+  `KEEP` — active backlog work item.
+- [docs/BACKLOG/TR-011-streaming-encrypted-restore.md](./BACKLOG/TR-011-streaming-encrypted-restore.md):
+  `KEEP` — active backlog work item.
+- [docs/BACKLOG/TR-015-platform-agnostic-cli-plan.md](./BACKLOG/TR-015-platform-agnostic-cli-plan.md):
+  `KEEP` — active backlog work item.
+
+## Landed Design Surface
+
+- [docs/design/README.md](./design/README.md): `KEEP` — canonical landed design
+  index.
+- [docs/design/0001-m18-relay-agent-cli.md](./design/0001-m18-relay-agent-cli.md):
+  `KEEP` — legacy-named landed cycle history; retain until touched.
+- [docs/design/0002-m18-relay-write-flows.md](./design/0002-m18-relay-write-flows.md):
+  `KEEP` — legacy-named landed cycle history; retain until touched.
+- [docs/design/0003-m18-relay-tree-creation.md](./design/0003-m18-relay-tree-creation.md):
+  `KEEP` — legacy-named landed cycle history; retain until touched.
+- [docs/design/RL-001-agent-recipient-list.md](./design/RL-001-agent-recipient-list.md):
+  `KEEP` — landed cycle history.
+- [docs/design/RL-002-agent-recipient-mutations.md](./design/RL-002-agent-recipient-mutations.md):
+  `KEEP` — landed cycle history.
+- [docs/design/RL-003-agent-rotate.md](./design/RL-003-agent-rotate.md):
+  `KEEP` — landed cycle history.
+- [docs/design/RL-004-agent-vault-rotate.md](./design/RL-004-agent-vault-rotate.md):
+  `KEEP` — landed cycle history.
+- [docs/design/RL-005-agent-vault-lifecycle.md](./design/RL-005-agent-vault-lifecycle.md):
+  `KEEP` — landed cycle history.
+- [docs/design/TR-001-architecture-reality-gap.md](./design/TR-001-architecture-reality-gap.md):
+  `KEEP` — landed cycle history.
+- [docs/design/TR-002-threat-model.md](./design/TR-002-threat-model.md):
+  `KEEP` — landed cycle history.
+- [docs/design/TR-003-benchmark-baselines.md](./design/TR-003-benchmark-baselines.md):
+  `KEEP` — landed cycle history.
+- [docs/design/TR-004-design-doc-lifecycle.md](./design/TR-004-design-doc-lifecycle.md):
+  `KEEP` — landed cycle history.
+- [docs/design/TR-006-docs-maintainer-checklist.md](./design/TR-006-docs-maintainer-checklist.md):
+  `KEEP` — landed cycle history.
+- [docs/design/TR-007-security-doc-discoverability-audit.md](./design/TR-007-security-doc-discoverability-audit.md):
+  `KEEP` — landed cycle history.
+- [docs/design/TR-009-pre-pr-doc-cross-link-audit.md](./design/TR-009-pre-pr-doc-cross-link-audit.md):
+  `KEEP` — landed cycle history.
+- [docs/design/TR-010-planning-index-consistency-review.md](./design/TR-010-planning-index-consistency-review.md):
+  `KEEP` — landed cycle history.
+- [docs/design/TR-012-examples-surface-audit.md](./design/TR-012-examples-surface-audit.md):
+  `KEEP` — landed cycle history.
+- [docs/design/TR-013-guide-accuracy-audit.md](./design/TR-013-guide-accuracy-audit.md):
+  `KEEP` — landed cycle history.
+- [docs/design/TR-014-markdown-surface-rationalization.md](./design/TR-014-markdown-surface-rationalization.md):
+  `KEEP` — landed cycle history.
+
+## Archive And Historical Intent
+
+- [docs/archive/README.md](./archive/README.md): `KEEP` — archive entrypoint.
+- [docs/archive/design/README.md](./archive/design/README.md): `KEEP` — reserved
+  archive surface for retired design docs.
+- [docs/archive/BACKLOG/README.md](./archive/BACKLOG/README.md): `KEEP` —
+  canonical archive index for retired backlog cards.
+- [docs/archive/BACKLOG/RL-001-agent-recipient-list.md](./archive/BACKLOG/RL-001-agent-recipient-list.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/RL-002-agent-recipient-mutations.md](./archive/BACKLOG/RL-002-agent-recipient-mutations.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/RL-003-agent-rotate.md](./archive/BACKLOG/RL-003-agent-rotate.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/RL-004-agent-vault-rotate.md](./archive/BACKLOG/RL-004-agent-vault-rotate.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/RL-005-agent-vault-lifecycle.md](./archive/BACKLOG/RL-005-agent-vault-lifecycle.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/TR-001-architecture-reality-gap.md](./archive/BACKLOG/TR-001-architecture-reality-gap.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/TR-002-threat-model.md](./archive/BACKLOG/TR-002-threat-model.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/TR-003-benchmark-baselines.md](./archive/BACKLOG/TR-003-benchmark-baselines.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/TR-004-design-doc-lifecycle.md](./archive/BACKLOG/TR-004-design-doc-lifecycle.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/TR-006-docs-maintainer-checklist.md](./archive/BACKLOG/TR-006-docs-maintainer-checklist.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/TR-007-security-doc-discoverability-audit.md](./archive/BACKLOG/TR-007-security-doc-discoverability-audit.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/TR-009-pre-pr-doc-cross-link-audit.md](./archive/BACKLOG/TR-009-pre-pr-doc-cross-link-audit.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/TR-010-planning-index-consistency-review.md](./archive/BACKLOG/TR-010-planning-index-consistency-review.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/TR-012-examples-surface-audit.md](./archive/BACKLOG/TR-012-examples-surface-audit.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/TR-013-guide-accuracy-audit.md](./archive/BACKLOG/TR-013-guide-accuracy-audit.md):
+  `KEEP` — archived historical intent.
+- [docs/archive/BACKLOG/TR-014-markdown-surface-rationalization.md](./archive/BACKLOG/TR-014-markdown-surface-rationalization.md):
+  `KEEP` — archived historical intent.
+
+## Invariants And Legends
+
+- [docs/invariants/README.md](./invariants/README.md): `KEEP` — invariants index.
+- [docs/invariants/I-001-determinism-trust-and-explicit-surfaces.md](./invariants/I-001-determinism-trust-and-explicit-surfaces.md):
+  `KEEP` — active project invariant.
+- [docs/legends/README.md](./legends/README.md): `KEEP` — legend index.
+- [docs/legends/RL-relay.md](./legends/RL-relay.md): `KEEP` — active legend doc.
+- [docs/legends/TR-truth.md](./legends/TR-truth.md): `KEEP` — active legend doc.
+
+## Examples And Test Doctrine
+
+- [examples/README.md](../examples/README.md): `KEEP` — examples index is useful,
+  though the example surface still needs its own audit.
+- [test/CONVENTIONS.md](../test/CONVENTIONS.md): `KEEP` — test doctrine belongs
+  near the test surface.
+- [test/cycles/README.md](../test/cycles/README.md): `KEEP` — cycle-owned test
+  directory contract belongs near the test surface.
+
+## Local-Only And Non-Tracked Markdown
+
+These files are not part of the tracked Markdown audit and should remain out of
+the canonical tracked doctrine surface unless the repo makes an explicit policy
+change:
+
+- `AGENTS.md`
+- `EDITORS-REPORT.md`
+- `.claude/bad_code.md`
+- `.claude/cool_ideas.md`
+
+## Immediate Follow-On Priorities
+
+If the repo wants to act on this audit, the highest-value next changes are:
+
+1. move [GRAVEYARD.md](../GRAVEYARD.md) under `docs/archive/`
+2. decide whether [CLAUDE.md](../CLAUDE.md) should leave tracked root entirely
+3. collapse [STATUS.md](../STATUS.md) into other canonical surfaces and remove
+   the duplicate snapshot doc
+4. shrink and relocate [ROADMAP.md](../ROADMAP.md) once its remaining migration
+   value is absorbed elsewhere

docs/archive/BACKLOG/README.md

@@ -33,5 +33,9 @@ Landed archived backlog items:
   - landed as [TR-009 — Truth: Pre-PR Doc Cross-Link Audit](../../design/TR-009-pre-pr-doc-cross-link-audit.md)
 - [TR-010 — Planning Index Consistency Review](./TR-010-planning-index-consistency-review.md)
   - landed as [TR-010 — Truth: Planning Index Consistency Review](../../design/TR-010-planning-index-consistency-review.md)
+- [TR-012 — Examples Surface Audit](./TR-012-examples-surface-audit.md)
+  - landed as [TR-012 — Truth: Examples Surface Audit](../../design/TR-012-examples-surface-audit.md)
 - [TR-013 — Guide Accuracy Audit](./TR-013-guide-accuracy-audit.md)
   - landed as [TR-013 — Truth: Guide Accuracy Audit](../../design/TR-013-guide-accuracy-audit.md)
+- [TR-014 — Markdown Surface Rationalization](./TR-014-markdown-surface-rationalization.md)
+  - landed as [TR-014 — Truth: Markdown Surface Rationalization](../../design/TR-014-markdown-surface-rationalization.md)

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

@@ -2,7 +2,7 @@
 
 ## Legend
 
-- [TR — Truth](../legends/TR-truth.md)
+- [TR — Truth](../../legends/TR-truth.md)
 
 ## Why This Exists
 
@@ -35,7 +35,7 @@ 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)
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
 
 ## Notes
 

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

@@ -2,7 +2,7 @@
 
 ## Legend
 
-- [TR — Truth](../legends/TR-truth.md)
+- [TR — Truth](../../legends/TR-truth.md)
 
 ## Why This Exists
 
@@ -40,7 +40,7 @@ equal apparent status.
 
 ## Linked Invariants
 
-- [I-001 — Determinism, Trust, And Explicit Surfaces](../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
+- [I-001 — Determinism, Trust, And Explicit Surfaces](../../invariants/I-001-determinism-trust-and-explicit-surfaces.md)
 
 ## Notes
 

docs/design/README.md

@@ -47,7 +47,9 @@ Landed cycle docs:
 - [TR-007 — Truth: Security Doc Discoverability Audit](./TR-007-security-doc-discoverability-audit.md)
 - [TR-009 — Truth: Pre-PR Doc Cross-Link Audit](./TR-009-pre-pr-doc-cross-link-audit.md)
 - [TR-010 — Truth: Planning Index Consistency Review](./TR-010-planning-index-consistency-review.md)
+- [TR-012 — Truth: Examples Surface Audit](./TR-012-examples-surface-audit.md)
 - [TR-013 — Truth: Guide Accuracy Audit](./TR-013-guide-accuracy-audit.md)
+- [TR-014 — Truth: Markdown Surface Rationalization](./TR-014-markdown-surface-rationalization.md)
 
 Archived or retired cycle docs: