Make the architecture documents easier to learn and navigate #911

Story

Contributors can follow the README into an architecture explanation that starts with a small document execution, then explains ordinary runs, workflow runs and replay. They can find the rule for a particular boundary without comparing several full restatements or reconstructing an old pull-request stack.

For example, a reader asking what happens after a workflow writes and deletes a file reaches the replay example directly. From that example they can find the lifetime rule, the exact workflow interface and its conformance evidence.

Current gap

Ten previous architect conversations reviewed main at a0320347ff676f76735f42be86ff0bdb07a52980. All ten recommended reordering and consolidation. The sample consists of GPT agent sessions, not independent human readers; no human comprehension or timing experiment was performed.

The architecture opens with a large terminology table and installation details before its concise execution-environment comparison. Glossary and construct-inventory entries repeat detailed contracts from boundary chapters and feature specifications. Current rules are interleaved with delivery chronology. Several summaries conflict with later accepted changes, including workflow definitions, artifact formats, protected component names and Agent directory registration.

Contract

• Keep architecture.md as the primary implementation-invariant contract. Open it with a concrete execution model and linked routes to common reader questions.
• Group chapters and subsections in learning order, including the REPL's journal/entry model before rendering machinery.
• Make terminology and construct inventory concise linked references. Transfer every unique constraint into its owning section before shortening an entry.
• Give repeated material an explicit owner: architecture for implementation invariants; feature specifications for interfaces, observable behavior and conformance; decisions for consequential rationale/history; agent guides for contribution and design procedure.
• Preserve useful examples, surprising rationale, exact diagnostics, serialized spellings, conformance identifiers and ownership, teardown, failure, cancellation, replay and compatibility constraints.
• Reconcile stale statements from accepted history and current implementation. This work changes documentation and navigation, without selecting new runtime behavior or adding migrations.
• Keep current rules distinct from dated delivery history, and connect partially superseded decisions to their surviving scope and current rules.

Scope covers the architecture corpus and its supporting specifications, README and necessary navigation references across the project. It does not require touching every document, splitting the primary contract into new files, imposing a word-count target, changing dependencies or runtime code, or relaxing contributor reading obligations.

Acceptance and evidence

1. README leads to explicit routes for understanding execution, finding a boundary, checking a feature interface and understanding a decision. Record a navigation walkthrough and the governing destinations.
2. The opening explains ordinary versus workflow execution, partial versus completed replay, and historical results versus current filesystem state through a concrete example.
3. A before/after transfer ledger accounts for moved and consolidated constraints, including formerly unique inventory/glossary details and lifecycle exceptions. Detailed rules remain addressable from their summaries.
4. Links, heading anchors, numbered-section references and decision supersession references resolve. Removed duplicate wording points to its canonical destination.
5. A reconciliation record cites accepted commits and implementation/test evidence for factual corrections. Preserved code fences and exact strings are checked, with explicit exceptions only for examples or signatures already made obsolete by accepted changes.
6. Runtime source, dependencies and lockfiles are unchanged. Run the finite documentation and affected checks selected by the Planner; no exhaustive runtime battery is required for prose alone.
7. Human comprehension remains explicitly unmeasured. Prepare explanation and findability tasks for later human evaluation; agent navigation checks are reported as agent observations.

The rewrite starts from reviewed comment follow-up PR #910 (1ef21a6f8fe659f25ea214eaecc5fff4af1c4b87) and preserves its architecture corrections. Its PR targets that branch until the parent lands.