Post-merge docs sweep: restore cross-links, route to new pages, fill CHANGELOG

CHANGELOG.md

@@ -7,8 +7,71 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- **`coding-scaffold tour`** — read-only five-screen walkthrough explaining what the
+  tool does, the scaffold artifact families, the doctor/pilot/setup loop, the daily
+  session/eval/team workflow, and where to go next. Never writes files; safe right
+  after install. Closes [#91](https://github.com/JRS1986/CodingScaffold/issues/91).
+- **`--persona` flag on `doctor` and `pilot`** — choose from `beginner` (default),
+  `control`, `security`, `team-lead`. Each persona reorders the artifact survey and
+  swaps the recommended-commands list for a focused recipe matching the persona's job.
+  Persona registry lives at `src/coding_scaffold/personas.py` and is kept in sync
+  with the [Team-Rollout](docs/docs/wiki/Team-Rollout.md#persona-paths) wiki page.
+  Closes [#90](https://github.com/JRS1986/CodingScaffold/issues/90).
+- **Stability markers in `--help`.** Every top-level command now renders a
+  `[stable]` / `[preview]` / `[experimental]` marker so teams know what they can
+  build on. Contract per marker documented in
+  [Stability](docs/docs/wiki/Stability.md). Registry at
+  `src/coding_scaffold/cli_stability.py`. Closes
+  [#95](https://github.com/JRS1986/CodingScaffold/issues/95).
+- **Per-subcommand `--help` descriptions and examples.** Every subcommand
+  (`setup run`, `knowledge lint`, `team push`, ...) now prints a one-paragraph
+  description, when-to-run guidance, and 1-3 worked examples instead of bare
+  argparse output. Registry at `src/coding_scaffold/cli_help.py`. Closes
+  [#89](https://github.com/JRS1986/CodingScaffold/issues/89).
+- **Doctor rationale lines.** Every artifact `doctor` surveys is rendered with a
+  one-line `→ why this matters` rationale, sourced from the shared
+  `src/coding_scaffold/artifacts.py` registry so `doctor`, `pilot`, and any future
+  onboarding command stay in sync. Closes
+  [#87](https://github.com/JRS1986/CodingScaffold/issues/87).
+- **`setup update --force` + `min_supported_scaffold_version` field.**
+  `.coding-scaffold/scaffold-version.json` now records the minimum scaffold
+  version required to safely update the project. `setup update` refuses to run
+  when the installed scaffold is older (use `--force` to override after reading
+  the migration note). Closes
+  [#96](https://github.com/JRS1986/CodingScaffold/issues/96).
+- **`setup update` prints a copy-pasteable `.new` reconciliation recipe.** When
+  staged `.new` sidecars are produced, the command now prints the `diff -u` /
+  merge / delete / `eval` steps inline, plus a link to the upgrade guide.
+
+### Fixed
+
+- **Template renderer no longer leaks `${undefined}` into user files.** Missing
+  keys raise `UnresolvedTemplateError` naming the template + key; any
+  `${...}` token surviving substitution raises before the file is written.
+  `$$` is preserved as the documented escape for a literal `$`. A parametrized
+  test renders every template under `templates/{writers,adapters}/` with a
+  default context. Fixes [#94](https://github.com/JRS1986/CodingScaffold/issues/94).
+
+### Changed
+
+- **Unified error message style.** New `src/coding_scaffold/errors.py` exposes
+  `fail_with(cause, next_step, link=None)` so CLI failure paths share a
+  three-line shape (`error: ... / next: ... / see: ...`). Documented in
+  [Errors and Recovery](docs/docs/wiki/Errors-and-Recovery.md). Closes
+  [#92](https://github.com/JRS1986/CodingScaffold/issues/92).
+
 ### Documentation
 
+- **New wiki pages**: [Glossary](docs/docs/wiki/Glossary.md) (cold-readable
+  vocabulary; linked from `doctor` and `--help` footers — closes
+  [#88](https://github.com/JRS1986/CodingScaffold/issues/88));
+  [Stability](docs/docs/wiki/Stability.md);
+  [Upgrading](docs/docs/wiki/Upgrading.md) (the full upgrade contract:
+  `.new` recipe, rollback, version pinning, reading CHANGELOG Breaking notes);
+  [Errors and Recovery](docs/docs/wiki/Errors-and-Recovery.md). Wiki index +
+  README updated to route to the new pages.
 - **Install docs now default to an isolated global CLI.** README, Getting Started, and generated
   project onboarding recommend `uv tool install` or `pipx install` from the GitHub repo so users can
   run `coding-scaffold` from any project without activating the source checkout's virtual
@@ -18,6 +81,17 @@ aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   workflows before the quick-start commands. Knowledge docs clarify that durable wiki pages should
   be distilled and reviewed, not raw chat transcript dumps.
 
+### Tests
+
+- **Test coverage gap filled** for `file_ops`, `scaffold_version`, `doctor`,
+  `pilot`, `session` (full init → start → checkpoint → diff → rollback
+  round-trip), and `pr_template`. Test count grew from 351 to 590. Closes
+  [#93](https://github.com/JRS1986/CodingScaffold/issues/93).
+- **Acceptance-criteria audit** for the team / knowledge / HTML-backend issues
+  (#97 – #105) — one test per acceptance bullet, with failure messages naming
+  the issue so regressions surface the affected ticket. The deeper mechanics
+  coverage stays in `tests/test_team.py` and `tests/test_knowledge.py`.
+
 ## [0.5.1] — 2026-05-19
 
 ### Fixed

README.md

@@ -66,8 +66,13 @@ Everything else (`policy`, `mcp`, `skills`, `memory`, `team`, routing, and workf
 is useful later, but it should not be day-one cognitive load.
 
 > Looking for a specific entry point? See the [persona paths](docs/docs/wiki/Team-Rollout.md#persona-paths)
-> (beginner / control-and-reproducibility / security review / team lead). For the threat model
+> (beginner / control-and-reproducibility / security review / team lead), surfaced directly via
+> `coding-scaffold doctor --persona <name>` / `pilot --persona <name>`. For the threat model
 > and what the scaffold deliberately does not enforce, read [Security](docs/docs/wiki/Security.md#threat-model).
+> Cold-start? Run `coding-scaffold tour` for a five-screen walkthrough, or skim the
+> [Glossary](docs/docs/wiki/Glossary.md). Hit a CLI error? See
+> [Errors and Recovery](docs/docs/wiki/Errors-and-Recovery.md). Wondering what's safe to depend on?
+> See [Stability](docs/docs/wiki/Stability.md). Upgrading? See [Upgrading](docs/docs/wiki/Upgrading.md).
 > Release notes are in [CHANGELOG.md](CHANGELOG.md).
 
 CodingScaffold prepares an existing project for AI-assisted development without tying the team to

docs/docs/wiki/FAQ.md

@@ -18,6 +18,39 @@ Run `coding-scaffold doctor --target .`. It surveys the repo and recommends the
 If you want the smallest useful demo, run `coding-scaffold pilot --target . --tool opencode` next
 and follow the printed recipe.
 
+If the CLI vocabulary is unfamiliar, run `coding-scaffold tour` first — a read-only five-screen
+walkthrough of what the tool does, the artifact families, and where to go next. Definitions for
+every term live in the [Glossary](./Glossary.md).
+
+## Can I get a focused recipe for my job (security, team lead, …)?
+
+Yes. Pass `--persona {beginner,control,security,team-lead}` to `doctor` or `pilot`. A security
+reviewer running `doctor --persona security` sees policy / MCP / permissions surfaced first
+instead of the full firehose; a team lead gets a manifest / knowledge / skills recipe. The four
+persona paths are documented in [Team Rollout](./Team-Rollout.md#persona-paths).
+
+## A command failed and I don't know what to do — where do I look?
+
+Every CLI failure path prints a three-line block: `error: <cause>` / `next: <one concrete
+recovery step>` / `see: <optional wiki link>`. Read the `next:` line first. If you want to
+understand the recurring failure modes (missing tool, untouched .env, eval on empty repo,
+manifest version mismatch), the [Errors and Recovery](./Errors-and-Recovery.md) page
+enumerates them.
+
+## How do I know what I can build automation on?
+
+Every top-level command in `coding-scaffold --help` carries a `[stable]` / `[preview]` /
+`[experimental]` marker. The [Stability](./Stability.md) page defines the deprecation and
+breaking-change contract for each marker — depend on `[stable]` freely; pin a version
+when depending on `[preview]`; treat `[experimental]` as exploratory only.
+
+## How do I upgrade a project after a new release?
+
+`coding-scaffold setup update --target .` refreshes generated files without losing your edits.
+Unchanged files are rewritten in place; edited files get a `.new` sidecar so you can merge.
+The full upgrade contract — `.new` reconciliation recipe, rollback, version pinning, how to
+read the CHANGELOG's Breaking section — is in [Upgrading](./Upgrading.md).
+
 ## Does setup install tools?
 
 Yes, when it is running interactively and the selected coding environment is missing. It asks before

docs/docs/wiki/Getting-Started.md

@@ -8,17 +8,31 @@ backend immediately; the goal is to make one small, inspected, verified change.
 After installing CodingScaffold in your environment, your first three commands are:
 
 ```bash
+coding-scaffold tour                                    # optional five-screen orientation
 coding-scaffold doctor --target .
 coding-scaffold pilot --target . --tool opencode
 # follow the printed steps
 ```
 
+`tour` is a read-only five-screen walkthrough (artifacts → doctor loop → daily workflow →
+where to go next). It's stateless — never writes files — so it's safe to run on a fresh
+checkout. Skip it if you already know the model.
+
 That's it for day one. Everything else on this page is reference material you can come back
 to when you actually need it. The other commands (`policy`, `mcp`, `skills`, `memory`,
 `team`, `permissions`, `tools route`) are deliberately out of the first-run mental model —
 `doctor` lists them under "Ignore for now (advanced)" so you don't have to track them
 yourself.
 
+### Persona-targeted output
+
+`doctor` and `pilot` accept `--persona {beginner,control,security,team-lead}` to scope the
+recommendations and ignore-for-now list to a specific job. A security reviewer running
+`coding-scaffold doctor --persona security --target .` sees policy / MCP / permissions
+surfaced first instead of the full firehose. The four personas are documented in
+[Team Rollout](./Team-Rollout.md#persona-paths); the registry lives at
+`src/coding_scaffold/personas.py` so the CLI and wiki stay in sync.
+
 ### What `doctor` does
 
 Surveys the scaffold artifacts already present in your project (AGENTS.md, PR template,

docs/docs/wiki/Glossary.md

@@ -114,6 +114,7 @@ See [artifact](#artifact).
 A SHA256 snapshot of every generated file written by setup, stored in
 `.coding-scaffold/scaffold-version.json`. `setup update` uses it to tell unchanged
 files (safe to rewrite) from user-edited files (write a `.new` sidecar instead).
+See [Upgrading](./Upgrading.md).
 
 ## session trace
 

docs/docs/wiki/Upgrading.md

@@ -137,8 +137,7 @@ The CHANGELOG groups changes by release. Look for these sections:
 - **Deprecated** — features that still work but are scheduled for removal.
   Plan to migrate before the next major bump.
 - **Stability** — commands moved between `stable`/`preview`/`experimental`
-  markers. The Stability wiki page (shipped alongside this one) defines what
-  each marker promises.
+  markers. See [Stability](./Stability.md) for what each marker promises.
 
 A worked example: if 0.6.0's CHANGELOG says "Renamed `policy.network.allow`
 to `policy.network.allowlist`", and your update produced

docs/docs/wiki/index.md

@@ -42,11 +42,15 @@ Start with the smallest path that matches your job today:
 
 | Need | Page | What you get |
 | --- | --- | --- |
+| Define a term you saw in `--help` | [Glossary](./Glossary.md) | One paragraph per term (artifact, persona, MCP, manifest, scope, ...). |
 | First useful session | [Getting Started](./Getting-Started.md) | The `doctor` + `pilot` path and the first bounded agentic change. |
-| Small-team pilot | [Team Rollout](./Team-Rollout.md) | A two-person rollout plan for teams under 20 people. |
+| Small-team pilot | [Team Rollout](./Team-Rollout.md) | A two-person rollout plan + the four persona paths surfaced by `--persona`. |
 | Security/compliance review | [Security](./Security.md) | Credential, provider, MCP, policy, and trust-boundary notes. |
 | Tool comparison | [Tool Adapters](./Tool-Adapters.md) | Capability matrix for OpenCode, Claude Code, Codex, OpenClaude, Hermes, and Pi. |
 | Shared memory | [Knowledge Base](./Knowledge-Base.md) | Markdown, HTML, Obsidian, Foam, MemPalace, and shared Git workflows. |
+| Upgrade a project | [Upgrading](./Upgrading.md) | What `setup update` does, the `.new` recipe, rollback, version pinning. |
+| Decide what to depend on | [Stability](./Stability.md) | What `[stable]` / `[preview]` / `[experimental]` markers in `--help` promise. |
+| Recover from a CLI failure | [Errors and Recovery](./Errors-and-Recovery.md) | The three-line error format and the recurring failure modes. |
 
 Then use the reference pages when the need appears: