Documentation is significantly expanded. Here is what changed.

Primary update: docs/roadmap.md
Roughly doubled in depth with a table of contents and 20 sections, including:

New section	What it covers
End-to-end lifecycle
State diagram + first-time vs rolling checkpoint flows
ROADMAP.md document contract
All 12 sections, purposes, enumerated values, schema vs bootstrap complete
Example payloads
Truncated JSON for guide, checkpoint, validate
Phases and next-action logic
Phase table + recommend_next_action() priority order
Workspace resolution
Resolution order, quarantine, expected path
Configuration reference
Full dietcode.roadmap YAML + every key and env var
Write guard and native hints
_roadmap_write_hint fields for success vs rejection
Progress, state, telemetry
JSONL paths + .dietcode/roadmap-state.json field reference
Code soup audit
Section 9 signals and how checkpoint uses them
Anti-patterns
Do / don't list for agents and operators
Existing sections were refined with:

Evidence bundle key reference
Fill plan JSON structure
Gate catalog with blocks_kanban_complete defaults
Fingerprint cache behavior
Expanded troubleshooting
Cross-reference updates
docs/agent-ergonomics.md — deep-dive link table to roadmap sections
docs/tools-reference.md — links to schema, payloads, config, gates
docs/architecture.md — pointer to full roadmap doc
docs/README.md + README.md — updated descriptions
optional-skills/.../SKILL.md — doc section index for agents
prompts.py — 12-section schema, workspace guard, anti-pattern pointer
The main entry point for operators and implementers is docs/roadmap.md.

Author: CardSorting

README.md

@@ -187,7 +187,7 @@ Operator guide: [docs/kernel-bridge-operations.md](docs/kernel-bridge-operations
 | [docs/README.md](docs/README.md) | Documentation index |
 | [docs/dietcode-plugin.md](docs/dietcode-plugin.md) | Plugin overview, config, workflow |
 | [docs/architecture.md](docs/architecture.md) | Runtime layers, hook flow, authority split |
-| [docs/roadmap.md](docs/roadmap.md) | Per-project ROADMAP steering, fingerprint, bootstrap autofill |
+| [docs/roadmap.md](docs/roadmap.md) | Per-project ROADMAP steering — schema, config, gates, example JSON |
 | [docs/kernel-bridge-operations.md](docs/kernel-bridge-operations.md) | Kernel bridge operator manual |
 | [docs/tools-reference.md](docs/tools-reference.md) | Slash commands and Hermes tools |
 | [docs/broccolidb.md](docs/broccolidb.md) | BroccoliDB runtime and RPC |

docs/README.md

@@ -39,7 +39,7 @@ intent → patch → receipt → journal → verify → verification journal →
 | [broccolidb.md](broccolidb.md) | Bundled BroccoliDB package, RPC worker, database location, smoke tests. |
 | [broccolidb-native-execution-throughput.md](broccolidb-native-execution-throughput.md) | Native RPC execution model and throughput notes. |
 | [agent-ergonomics.md](agent-ergonomics.md) | Kernel progress telemetry, stuck-operator runbook, roadmap loop summary. |
-| [roadmap.md](roadmap.md) | Per-project ROADMAP.md steering, fingerprint, bootstrap autofill, gates. |
+| [roadmap.md](roadmap.md) | Per-project ROADMAP steering: fingerprint, 12-section schema, bootstrap autofill, gates, config, example JSON. |
 | [releases/v1.9.4.md](releases/v1.9.4.md) | v1.9.4 sonic kernel UX release notes. |
 | [releases/v1.9.3.md](releases/v1.9.3.md) | v1.9.3 cockpit responsiveness release notes. |
 | [releases/v1.9.2.md](releases/v1.9.2.md) | v1.9.2 performance pass release notes. |

docs/agent-ergonomics.md

@@ -243,7 +243,17 @@ Long-horizon steering surface for product and architecture coherence. Every
 response is **scoped to the resolved Hermes project workspace** via
 `project_fingerprint` → `project_steering_digest` → `project_identity_line`.
 
-**Full reference:** [roadmap.md](roadmap.md)
+**Full reference:** [roadmap.md](roadmap.md) — schema contract, config, example JSON,
+gates, workspace resolution, write guard, code soup audit, anti-patterns.
+
+| Topic in roadmap.md | Section |
+| --- | --- |
+| 12-section ROADMAP.md contract | [Document contract](roadmap.md#roadmapmd-document-contract) |
+| Example `guide` / `checkpoint` / `validate` JSON | [Example payloads](roadmap.md#example-payloads) |
+| All `dietcode.roadmap` config keys | [Configuration reference](roadmap.md#configuration-reference) |
+| Gate IDs and kanban blocking | [Steering gates](roadmap.md#steering-gates) |
+| Workspace resolution order | [Workspace resolution](roadmap.md#workspace-resolution) |
+| Native write hints | [Write guard](roadmap.md#write-guard-and-native-hints) |
 
 ### Per-project identity (read this first)
 

docs/architecture.md

@@ -158,6 +158,9 @@ Per-project identity flows: `project_fingerprint` → evidence bundle →
 `project_steering_digest` → top-level `project_identity_line` on every tool
 response, JoyZoning context, kernel cockpit, doctor, and progress telemetry.
 
+See [roadmap.md](roadmap.md) for the 12-section document contract, full config
+reference, example JSON payloads, gate catalog, and write-guard behavior.
+
 `tools_loader.py` reports missing modules via `/dietcode tools`.
 
 ## BroccoliDB boundary