Conventions Used in This Manual
Read this once, then read anything. Five minutes to learn the visual vocabulary the rest of the manual leans on.
How the manual is organized
The manual ships as a Quickstart + 5 Parts + 26 Appendices. The chapter numbering scheme tells you which kind of page you're on at a glance.
| Number | Means | Example |
|---|---|---|
Q1 Q2 Q3 | Quickstart steps. The 30-minute zero-to-shipped path. | Q2 · Your First Plan |
1 2 … 24 | Numbered chapters across 5 Parts (Smelt → Forge → Guard → Learn). | Chapter 5 · Crucible |
| (unnumbered) | Sub-chapters and deep dives that hang off a numbered chapter. | Dashboard, LiveGuard |
A B … N | Lettered appendices, reference material, runbooks, enterprise track. | Appendix K · Enterprise Reference Architecture |
O | The Book Index, A–Z search across the whole manual. | Appendix O · Book Index |
Versioning & freshness
This manual describes current behavior. We deliberately avoid NEW vX.Y badges and “introduced in vX.Y” stamps inside reference chapters — they age into anti-signals within a release or two and force every reader to know the version history of every feature.
For version-stamped history, see:
CHANGELOG.md— the canonical, machine-parseable list of what shipped when.- Project History — the narrative version of the same thing: which inflection point solved which problem.
- Foreword — the one-year arc from “impossible” to “seven minutes”.
- The Editions list further down this page — manual-level revisions, when the book itself was reshaped.
Maturity signals (BETA, deprecation warnings, security advisories) are kept inline because they describe a feature's current trust level, not its history.
Hero images and supporting figures
Each numbered chapter opens with a hero image and may carry inline figures (SVG diagrams or photographs) inside the body. The conventions are deliberately uneven by chapter type:
| Page type | Hero image | Inline figures |
|---|---|---|
| Numbered chapter (1, 2, … 29) | Yes, assets/chapter-heroes/chN-hero.webp, 1024×768, generated. | Yes, numbered Figure N‑K via maintain.mjs. |
| Quickstart step (Q1, Q2, Q3) | Yes, same convention. | Optional. |
| Unnumbered sub-chapter (Dashboard, Settings, MCP Reference, deep dives) | No. Sub-chapters inherit visual weight from their parent. | Yes, un-numbered figures, still wrapped in <figure class="manual-figure">. |
| Reference appendix (Glossary, Quick Reference, Book Index, List of Figures, API Surface Index) | No. Reference pages favor density over decoration. | Rare, only when a diagram clarifies the reference. |
| Narrative appendix (Sample Project, Enterprise, Lessons Learned, History, About the Author) | Yes, same convention as numbered chapters. | Yes. |
maintain.mjs.
Callouts
Three flavors of inline aside, each colored for instant recognition. They never carry information that isn't also in the surrounding prose, safe to skip on a first pass, useful on a second.
Code blocks
Code, terminal, and config samples come in a labelled block. The header tells you what the snippet is, a terminal command, a config file path, a JSON payload, and there's a Copy button on the right when the snippet is meant to be run as-is.
node docs/manual/maintain.mjs --audit{
"presets": ["dotnet"],
"execution": { "quorum": "auto" }
}Inside body prose, monospace means a literal name, a file path, an env var, a tool ID, an argv flag. Italics mean a placeholder you fill in.
Diagrams and figures
Inline SVGs and rasters live under docs/manual/assets/diagrams/. Each one carries an alt attribute that describes the diagram in prose, readers using a screen reader (or readers who'd rather skim) get the full meaning without seeing the picture.
Diagrams come in three sizes (diagram-img-sm, 700 px, -md, 750 px, -lg, 800 px), all centered in the body column. Every diagram is wrapped in a <figure> with a one-line italic caption underneath, derived automatically from the alt text title clause. To override an auto-caption with hand-authored prose, edit the <figcaption> directly and remove the <!--cap:auto--> marker, subsequent maintain.mjs runs will leave it alone.
Live numbers
Some sentences refer to a count that changes between releases, "Plan Forge ships 102 MCP tools", "18 instruction files", "12 agents". Those numbers are tokenized in the page source and rewritten at build time from a single source of truth in docs/manual/assets/manual.js. You'll see the up-to-date number rendered, but if you View Source you'll see the token markers wrapping it.
<!--c:KEY-->NUMBER<!--/c--> instead of typing a literal number in chapter prose. Run node docs/manual/maintain.mjs after editing, it sweeps every chapter, fixes drift, and warns on unknown keys.
Navigating the manual
| Where | What it gives you |
|---|---|
| Left sidebar | Always-visible chapter list grouped by Part. Collapses on narrow screens to a hamburger. |
| Sidebar search | Type to filter chapters and indexed sections. Matches both titles and the curated section index. |
| Prev / Next links | At the bottom of every chapter, in reading order. Skips deep-dive sub-chapters unless you're inside one. |
| Back-to-top button | Appears on long pages once you scroll past the first screen. |
| Appendix O — Book Index | A–Z list of every concept, tool, and named section. Letter jump-bar at the top. |
| Appendix P — List of Figures | Every numbered figure in the manual, in chapter order. Click to jump to the diagram in context. |
| Appendix A — Glossary | Definitions of every Plan Forge term. Read first if a chapter uses words you don't recognize. |
Reader paths
The cover offers four "where to next?" tiles, new to Plan Forge, on the GitHub stack, extending it, on a different stack. Pick the path that matches what you're doing today and the manual stays roughly half its apparent size.
Edition & errata
Every page footer (and the meta-bar at the top of the cover) shows the manual edition, pinned to the Plan Forge version it was published with. The full release history lives in CHANGELOG.md on GitHub.
Edition history
- Fifth Edition (in progress) (v3.12.0+), Ebook-completion phase. Cluster A: Front Matter shipped so far: the new Foreword — From Impossible to Seven Minutes framing the one-year journey from "impossible" to a 99/100 application in seven minutes; the Stakeholder Briefing as the 10–15 minute white-paper version with a tailoring flow for prospect-specific remixing; the Reader-Journey Ladders with five persona ladders (solo developer, team lead, reviewer or architect, enterprise architect, extension author); and Appendix R — A Day in the Forge collecting three worked case studies absorbed from contemporary blog posts (the closed loop, the .NET 99-vs-44 A/B test, the three-model quorum run). Further story, reference, and domain-chapter slices land through this edition as the phase ships.
- Fourth Edition (v3.6), OpenBrain promoted to the documented L3 memory layer; new
pforge brain {status, hint, test, replay}subcommands; Team Dashboard tab added to the Forge group (now 19 tabs). Project History extended through v3.6 with v2.95 Lattice, v3.0 Copilot trilogy, v3.2–3.4 Team Mode. Refreshed counts (102 MCP tools, 97 CLI commands). - Third Edition (v3.5.1), Added Part V “Integrate”: Copilot Integration Trilogy, Team Coordination, The Knowledge Graph, Integrating from Outside. Refreshed counts (88 MCP tools, 5 parts, 28 chapters).
- Second Edition (v2.95.0), Added “How the Shop Remembers” (memory architecture: Hallmark, Anvil, Lattice, sync_memories), now Chapter 22 after the Part IV memory-first reorder.
- First Edition (v2.78.0), Initial public release: 24 chapters across Parts I–IV plus 14 appendices.
Spotted something that's wrong, stale, or missing? File an issue on github.com/srnichols/plan-forge with the chapter title and section heading. Manual fixes are tagged docs: in the changelog.