diff --git a/.claude/agents/pkgbuild-reviewer.md b/.claude/agents/pkgbuild-reviewer.md
index 6a7981ec..253fb67b 100644
--- a/.claude/agents/pkgbuild-reviewer.md
+++ b/.claude/agents/pkgbuild-reviewer.md
@@ -20,7 +20,7 @@ You review changes to:
 - `sysforge/primitives/vcs_pkgver.py` — `[epoch:]pkgver-pkgrel` resolution for VCS sources
 - `sysforge/primitives/source_meta.py` — `source_meta.toml` schema
 - `sysforge/primitives/build_state.py` — `build_state.toml` schema
-- `sysforge/update.py`, `sysforge/fetch.py`, `sysforge/converge.py` — call sites
+- `sysforge/update.py`, `sysforge/fetch.py` — call sites
 
 Reject the review request if the diff falls outside this scope; the user wants a generalist reviewer instead.
 
diff --git a/.claude/skills/pkgbuild-spec-check/SKILL.md b/.claude/skills/pkgbuild-spec-check/SKILL.md
index 7722912d..3384df54 100644
--- a/.claude/skills/pkgbuild-spec-check/SKILL.md
+++ b/.claude/skills/pkgbuild-spec-check/SKILL.md
@@ -70,7 +70,7 @@ Trigger this whenever a change touches:
 
 - [ ] **Source sync goes through the scheduler** (CLAUDE.md gotcha #3). Any new code path that needs a fresh PKGBUILD calls `sysforge.primitives.source_sync.get_scheduler().request(SyncRequest(...))` — never `git pull` directly.
 - [ ] **`build_state.toml` invariants.** If you touch what's parsed from PKGBUILD, check whether the cached `build_state.toml` schema needs to evolve too.
-- [ ] **Tests.** `tests/test_parser.py`, `tests/test_patcher.py`, `tests/test_pkgbuild_meta.py` (if present), and `tests/test_aur.py` are the regression nets — add or update cases that exercise the spec detail you just changed.
+- [ ] **Tests.** `tests/test_parser.py`, `tests/test_patcher.py` and `tests/test_aur.py` are the regression nets — add or update cases that exercise the spec detail you just changed.
 
 ## Reporting
 
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 00000000..769767e6
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,11 @@
+<!-- What changes, and why. Link the ROADMAP ID or issue. -->
+
+## Checklist
+
+CI checks most of this; the boxes are for what it cannot see.
+
+- [ ] Release-note entry in `docs/release-notes/unreleased.md`, led by its roadmap ID
+- [ ] If a user-facing surface changed: `make surface` committed, and its diff matches what I meant to change
+- [ ] If a name was removed or renamed: the old one is in `tools/retired_names.toml` (config keys: `RETIRED_KEYS`)
+- [ ] The guide for this feature (`docs/guides/`) still describes it correctly
+- [ ] `make pre-release` (or `make ci-local`) passes locally
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index a4f995fc..ac083824 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,12 +1,22 @@
 # Suite, lint and check-* gates on a clean Arch container (3.4.0-DEV1).
-# Contributor-only, never shipped. Advisory: no branch protection until it has
-# stayed green for one release cycle. The job body is tools/ci.sh; reproduce a
-# red run locally with `make ci-local`.
+# Contributor-only, never shipped. Required: a ruleset on main makes this
+# `gates` job a required status check and changes arrive by pull request, so a
+# red run blocks the merge. The job body is tools/ci.sh; reproduce a red run
+# locally with `make ci-local`.
 name: ci
 
 on:
+  # A branch is checked through its pull request; push runs only for main, so a
+  # PR's commit is not tested twice.
   push:
+    branches: [main]
   pull_request:
+  workflow_dispatch:
+
+# A newer push to the same PR cancels the run it supersedes.
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 permissions:
   contents: read
diff --git a/CLAUDE.md b/CLAUDE.md
index b0477c6c..e1709318 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -24,6 +24,8 @@ make check-design    # guard: DESIGN.md in sync with sources
 make roadmap-view SORT=effort  # print Planned table sorted by a column (read-only)
 make check-shipped   # guard: etc/sysforge, PKGBUILD*, hooks, completions, manpage parity
 make check-standards
+make surface         # regenerate tests/data/surface.json after any user-facing change
+make check-surface   # guard: snapshot current; surface changes vs main named in release notes
 make sync-config     # adopt new shipped defaults into untracked live config (add-only)
 make container-smoke[-cachyos]  # packaging + portability checks in a container (needs make vm-pkg-stable first)
 make ci-local        # replay the CI job (.github/workflows/ci.yml) in a clean Arch container
@@ -75,7 +77,8 @@ Shipped-file edits must pass `make check-shipped`; doc/design edits `make check-
   profiles`, profile store paths) updates its guide in the same change. Order: after README.
   Concept pages (`docs/concepts/*.md`) explain the technique, not sysforge: no sysforge
   vocabulary outside the closing "In sysforge" section, upstream sources cited, no numbers
-  measured on one machine; guides link them (and the glossary) rather than re-explaining.
+  measured on one machine (`tests/test_concept_pages.py` checks the closing sections, the upstream
+  links and the vocabulary); guides link them (and the glossary) rather than re-explaining.
 - **`DOC` IDs are for user-facing docs only** (`docs/guides/`, `docs/concepts/`, README, man page) and file under
   `## Changed` (patch; lint-enforced). Internal docs (design, CLAUDE.md, ROADMAP) get no ID;
   wrong `--help`/man output is a `B`, since it is CLI behaviour.
@@ -83,11 +86,14 @@ Shipped-file edits must pass `make check-shipped`; doc/design edits `make check-
   dev docs) and file their release-note entry under `## Changed` only, like `DOC` (lint-enforced,
   `3.4.0-STD1`). Touching `sysforge/` or a shipped file makes it `B`/`F`.
 - **Completions stay in lockstep with the CLI** (`completions/_sysforge` + bash) in the same change.
+- **A user-facing change regenerates `tests/data/surface.json`** (`make surface`) and names what
+  changed in the release notes; `make check-surface` (a required CI gate) enforces both.
 - **Removing or renaming a flag, token or public name adds it to `tools/retired_names.toml`** in the
   same change (unless the old spelling is still valid elsewhere); `make check-standards` then finds
   every leftover, comments included. Written-down `sysforge …` commands and `§` references are
   checked too (§Documentation consistency guards). Tests build `BuildOptions(...)`,
-  `RunOptions(...)` or `build_parser().parse_args([...])`, never a `SimpleNamespace` stand-in.
+  `RunOptions(...)` or `cli_args("state", "list", ...)` (`tests/cli_args.py`), never a
+  `SimpleNamespace` stand-in.
 - **CLI verbs go through the Verb framework**: `Verb` subclass dispatched by `verbs.runner.run_verb`
   (`pre_check`/`execute`/`post_validate`; `requires_sentinel=True` if it mutates). Its flags live
   on the class (`add_parser` classmethod, ending `set_defaults(verb_cls=cls)`); register it in
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 14868087..5553af14 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -14,18 +14,41 @@ just as valuable — many features here started as workflow pain points.
 
 ## Ground rules for PRs
 
-- `make test` and `make lint` must pass. Use the Makefile targets, not direct
-  `pytest`/`ruff` invocations.
-- **`DESIGN.md` is generated** — edit the sources under `docs/design/*.md`, then run
+Changes reach `main` by pull request, and the CI `gates` job is a required check: it runs
+every gate in a clean Arch container, and a red run blocks the merge. Run the same set
+locally with `make pre-release`, or reproduce CI exactly with `make ci-local` (podman).
+`make install-hooks` adds a pre-commit hook running the fast gates, so most failures show
+up before you push.
+
+- Use the Makefile targets, not direct `pytest`/`ruff` invocations.
+- **`DESIGN.md` is generated**: edit the sources under `docs/design/*.md`, then run
   `make design`. Never edit `DESIGN.md` directly. Doc update order: `docs/design/*.md`
   → README.md → CLAUDE.md.
-- CLI surface changes (new verb, flag, help text) must update
-  `completions/_sysforge` + `completions/sysforge.bash` and regenerate the man page
-  (`make man`) **in the same change**. `make check-shipped` verifies this.
 - New logic that branches on the resolved compiler (gcc vs llvm/clang) ships with
   tests for **both** paths.
 - Keep behavior changes and refactors in separate commits where practical.
 
+### Changing anything a user can see
+
+A flag, command, config key, environment variable, `--json` field or log name is a
+*surface*. Change one and, in the same PR:
+
+| Also update | Enforced by |
+|---|---|
+| Both completion scripts (`completions/_sysforge`, `completions/sysforge.bash`) | `make check-shipped` (`completion_commands`) |
+| The man page: `make man` (generated from the parser and the env/journal tables) | `make check-shipped` (`manpage`) |
+| `tests/data/surface.json`: `make surface`; its diff is what a reviewer reads | `make check-surface` |
+| A release-note entry in `docs/release-notes/unreleased.md` naming what changed | `make check-surface`, `make check-standards` |
+| **Removing or renaming** a name: add the old one to `tools/retired_names.toml` (a config key: `RETIRED_KEYS` in `sysforge/primitives/config_schema.py`) | `make check-surface`, `make check-standards` (`retired_names`) |
+| A **new config key**: document it in the shipped `etc/sysforge/*.toml` (and its twin under `tests/data/etc/sysforge/`) | `tests/test_config_keys_documented.py`, `make check-shipped` |
+| A **new environment variable**: a row in `sysforge/primitives/env_vars.py` | `tests/test_env_vars.py` |
+| A **new `--json` field**: its schema under `tests/data/json-schema/` | `tests/test_json_output.py` |
+| The user guide for the feature (`docs/guides/`) | review only |
+
+In tests, build the real objects: `BuildOptions(...)`, `RunOptions(...)`, or
+`cli_args("state", "list", ...)` from `tests/cli_args.py` for a parsed command line.
+`SimpleNamespace` stand-ins drift from the real thing (`tests/test_stand_ins.py`).
+
 ## Getting started
 
 ```bash
diff --git a/DESIGN.md b/DESIGN.md
index 54c12fb1..afaf2b31 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -496,6 +496,17 @@ The non-`profiles.toml` configs (`packages.toml`, `toolchain.toml`, `kernel.toml
 
 **Adopting the `.sfnew` residue — `sysforge config merge`.** Hand-merging the `.sfnew` companions is the only remaining manual step, so `sysforge config merge` (verb `config-merge`, `config_cmd.py`) is a pacdiff-style interactive driver over them. It scans the resolved config dir (`--config-dir` override, else `paths.CONFIG_DIR`) for `*.sfnew` — plus pacman's own `*.pacnew`/`*.pacsave` for sysforge config files on a packaged install — and for each presents: `[v]iew` (a `difflib` unified diff through `$PAGER` via `maybe_pager`, prefixed by a **relocated-section banner** naming any header the diff shows as both removed and added — a header on both a `-` and a `+` line is present in both files, so the pair is a move, not a deletion; `difflib` has no move detection of its own), `[m]erge` (launch the resolved diff/merge tool with `live new`, then re-loop), `[s]kip`, `[r]emove` (drop the companion once the live file is satisfactory), `[o]verwrite` (copy the companion over the live file verbatim — guarded by a confirm and a "discards your local values" warning, never the default, intended for the `.pacnew` accept-maintainer case), and a[b]ort. Because a `.sfnew` is the *verbatim shipped file*, there is **no blind "accept theirs"** as a primary action — the safe path is merge-then-remove. The verb edits config files in place but never builds/installs, so it carries **no sentinel**. The diff/merge tool resolves through one home shared with the reconfigure editor chain — `primitives/editor.resolve_merge_tool` (`SYSFORGE_MERGE` > `sysforge.toml [ui].merge` > `$DIFFPROG` > `vimdiff`) launched via `run_tty_argv` (the `/dev/tty` passthrough, also used by `resolve_editor`'s callers, which additionally runs the child inside a `"child"` `yield_terminal` so an active progress bar's reserved bottom row is released before a full-screen editor takes the terminal). `--dry-run` reports the companion→target pairs without prompting (scripting/CI).
 
+### Checking and repairing a live config
+
+Neither an upgrade nor `sync-config` ever removes anything from a live file, so a key sysforge stopped reading stays there, silently ignored, and a misspelt key is never reported. `primitives/config_schema.py` (`3.5.0-F18`) is the one home for what a live file may contain and for the edits that bring one back in line:
+
+- **The schema.** `KNOWN_SECTIONS`/`KNOWN_TOP_KEYS` (moved here from `tools/check_shipped.py`, which now imports them, so the runtime and the release gate read one definition) name each file's sections and top-level keys. `OPEN_SECTIONS` are the ones whose keys the user names (a profile's flag variables, `[[rules]]`, `[[package]]`, `[group.*]`, `[[kconfig]]`, ...); nothing under them is judged. In every other section a key is known when the **shipped default documents it**, active or as a commented `# key = ...` example, so documenting a key is what makes it valid; a commented example table covers only its own comment block, so a blank line returns to the last real header. `tests/test_config_keys_documented.py` keeps that sound: every key the code reads from a fixed section (chained `.get`/`[]` off a config-like object, or a local assigned from one) and every schema top-level key must be documented in the shipped default, or `config clean --unknown` would delete a working setting. It found `profiles.toml`'s `extends_system` (read from a user file) undocumented. The first run found `toolchain.toml`'s `reuse_unchanged` and `profile_store` (read by the stage and by `resolve_profile_store_root`) missing from the old list; `profile_store` is now also documented in the shipped file.
+- **What was retired.** `RETIRED_KEYS` (renamed or dropped keys: `[git] pull_timeout`, the per-package `pkgbuild_patch`) and `RETIRED_VALUES` (`repo_mode = "profiled"`, `build_mode = "patched_pkgbuild"`), each with the ID that retired it.
+- **The shipped defaults.** `shipped_text(name)` reads the checkout's `etc/sysforge`, or on an installed system the copy the wheel carries (`pyproject.toml` force-includes `etc/sysforge` as `sysforge/_data/config-defaults`): `/etc/sysforge` holds the user's own copies, kept across upgrades by `backup=()`.
+- **Edits.** Line-based, so comments and layout survive, over a small scanner that knows tables, array-of-tables entries and multi-line values. Every edited text is re-parsed with `tomllib` and refused if it would not parse; files are written through `atomic_write.replace_file`.
+
+Three `config` verbs and a doctor axis sit on it (`config_cmd.py`): **`config check`** reports retired and unknown settings with their line, exiting 1 when there are any (`--json` prints one `config-check` document instead, `tests/data/json-schema/config-check.schema.json`: each issue's file, line, kind, setting, message and fix); **`config clean`** renames a retired key (or drops it when its replacement is already set in the same table, saying so) and rewrites a retired value, and with `--unknown` also removes unknown keys and sections; **`config reset FILE [KEY...]`** puts each `SECTION.KEY` back to the shipped line (removing it when the default leaves it unset, adding it when the file lacks it), refuses keys inside array-of-tables entries, and with no KEY replaces the whole file, keeping the old one as `FILE.bak-<time>`. Both writers show a unified diff, honour `--dry-run`, ask at a terminal and otherwise need `--yes`. **`doctor system --config`** runs the same inspection in the default sweep: a parse error is an error, anything else a warning naming the fix.
+
 ### Dev fixtures vs. personal config
 
 `tests/data/etc/sysforge/` is the **git-tracked test fixture set** wired in `tests/conftest.py` (which *forces* `SYSFORGE_CONFIG_DIR` to that dir directly, so a developer shell exporting its own value cannot leak into the suite). It is kept in shipped↔fixture parity by `make check-shipped`. A developer's **personal live config** is a separate, untracked dir (e.g. `~/sf-config`, holding the TOML files directly) that the shell's `SYSFORGE_CONFIG_DIR` points at and that `make sync-config` services — keeping personal config out of the tracked tree while leaving the fixtures deterministic.
@@ -690,7 +701,7 @@ Resolution is `primitives/editor.py`'s single home (`resolve_editor` → `SYSFOR
 
 - **Per-step gate.** `_EDITOR_NEEDING_STEPS` (`config`, `makepkg`) — the steps that open files *inside* the stage. `_run_selected_steps` calls `_require_usable_editor` before each, which runs the picker (with pacman-backed install of the chosen binary) and raises `RuntimeError` to abort the stage if the user cancels, rather than letting every subsequent edit prompt silently no-op.
 - **Pipeline-handoff gate.** `_gate_editor_for_pipeline`, immediately before the "Ready to proceed to toolchain → packages → kernel?" confirm. The per-step gate covers only two steps, so a step subset skipping both (or a skipped `editor` step) would otherwise hand the build stages no editor at all. Skipped under `--standalone` (nothing runs after reconfigure); with no TTY or under `--dry-run` it warns instead of blocking on a prompt nobody can answer.
-- **Adoption.** `_adopt_editor` exports the accepted editor as `SYSFORGE_EDITOR`. Downstream consumers call `resolve_editor()` fresh rather than receiving the stage's threaded local, so without this the pick would evaporate at the stage boundary. Adoption is unconditional; the `Save as sysforge default? [y/N]` prompt (`_offer_save_editor`) is a *separate* choice about persisting to `sysforge.toml` for future invocations, and declining it no longer costs the current run its editor.
+- **Adoption.** `_adopt_editor` exports the accepted editor as `SYSFORGE_EDITOR`. Downstream consumers call `resolve_editor()` fresh rather than receiving the stage's threaded local, so without this the pick would evaporate at the stage boundary. Adoption is unconditional; persisting is a *separate* choice (`_offer_persist_editor`): write `[ui] editor` to `sysforge.toml`, and/or export the pick as `EDITOR`/`VISUAL` from a system-wide or a user shell file, each target confirmed on its own (a target's two variables move together, never half-written). Declining keeps the pick for this run only.
 
 ### Bootstrap workflow (stages 1–3)
 
@@ -800,7 +811,7 @@ separate size block is needed.
 *Kconfig vs previous build* diffs the resolved `.config` against the one the last build produced.
 `primitives/kconfig_history.py` owns that history — nothing else in sysforge keeps a resolved
 `.config` after the build tree is cleaned — archiving each successful build's config (located by
-the existing `_resolve_built_config`, tagged with `_built_kernel_release`) gzipped to
+the existing `resolve_built_config`, tagged with `_built_kernel_release`) gzipped to
 `<state_dir>/kconfig-history/<pkgname>-<release>.config.gz`, newest `KEEP` (5) per pkgname, pruned
 on write and bounded at a few hundred KiB. The comparison runs through the new
 `kernel_safety.diff_kconfig(old, new)`, a symmetric sibling to `diff_requested_kconfig` (which is
@@ -808,11 +819,11 @@ hardcoded to the requested-vs-resolved axis and iterates only sysforge's own int
 the shared `parse_kconfig()`. `diff_kconfig` deliberately does *not* normalise an absent option to
 `n` the way `diff_requested_kconfig` does — on the build-to-build axis, "the symbol did not exist in
 that kernel" and "the symbol existed and was off" are different facts, and collapsing them would
-fabricate churn on every major bump. Output caps at `_KCONFIG_DIFF_CAP` (40) symbols with a
+fabricate churn on every major bump. Output caps at `KCONFIG_DIFF_CAP` (40) symbols with a
 `… and N more` pointer; the full list goes to the unified log, so a major bump cannot bury the
 version rows.
 
-*Kconfig merge drift* relocates `_gate2_kconfig_drift`'s existing result into the summary by having
+*Kconfig merge drift* relocates `gate2_kconfig_drift`'s existing result into the summary by having
 it *return* its drift list; the mid-run warnings are unchanged. `None` (as distinct from `[]`)
 means the check never ran, which the block states explicitly, reusing the "did NOT run" wording
 established by 2.6.1-B6 — the AlreadyBuilt path is exactly where a stale build makes the check most
@@ -936,14 +947,14 @@ option = "CONFIG_HZ_1000"        # must match CONFIG_[A-Z0-9_]+
 value  = "y"                     # y | m | n | non-empty string
 ```
 
-`srcdir` is needed when the PKGBUILD directory name differs from the tracked name (e.g. `pkgname = "linux-sysforge"` but the repo is cloned as `~/builds/linux`). Resolution: `srcdir` → `upstream_pkgname` → `pkgname`, first set wins (`_srcdir_path`).
+`srcdir` is needed when the PKGBUILD directory name differs from the tracked name (e.g. `pkgname = "linux-sysforge"` but the repo is cloned as `~/builds/linux`). Resolution: `srcdir` → `upstream_pkgname` → `pkgname`, first set wins (`srcdir_path`).
 
 **Source tracking & local-rename (F40).** `upstream_pkgname` decouples *what to pull* from *what to build/install as*. Two modes fall out of the schema:
 
 - **Pure-local** (default): `upstream_pkgname` unset, `source = "local"`, `pkgname` names the hand-maintained tree — no sync, no rename; byte-identical to the pre-F40 behavior.
 - **Track-upstream:** `upstream_pkgname = "linux-zen"` (+ optional distinct `pkgname = "linux-mine"`) — the stage clones/fetches `linux-zen` into `<pkgbuild_src_dir>/linux-zen`, and when `pkgname` differs it threads `BuildOptions.rename_pkgbase_to = pkgname` into the build; `makepkg_wrapper._run_build` applies `pkgbuild_patcher.patch_pkgbase_rename(mode="coexist")` to the patched PKGBUILD so the build installs *alongside* the official package. For an FDO build the stage passes the final role name instead (`linux-zen` → `linux-mine-sysforge-fdo`; see *Per-role kernel names* below), and the generic `-sysforge` suffix layer stands down for it; the rename dict that rides to `build_state` keeps `origin_pkgbase = <upstream_pkgname>` so `sysforge update` still source-syncs the upstream tree. With `pkgname` omitted (defaults to `upstream_pkgname`) there is no rename and the repo-collision check is the safety net against shadowing the official package.
 
-**Name resolution** is `_resolve_names` (one home): `upstream_pkgname` or `None`, `pkgname` defaulting to `upstream_pkgname`; neither set is an error. **Source resolution** is `_resolve_source(kernel_cfg, srcdir_path)`: an explicit `source` is honored (`git` errors — it was a phantom value with no URL to clone from); when omitted it auto-resolves `local → repo → aur` — an existing non-git tree is `local` (never clobbered by a re-clone), an existing git clone is `repo` (the scheduler's generic fetch rebases via the tree's own origin, skipping the AUR RPC), and a missing tree picks its clone remote via `aur.is_repo_package` on the tracked name (sync DB hit → `repo`/pkgctl, else `aur`). The build entry runs the source sync **before** requiring the PKGBUILD path, so a missing tree is bootstrapped by the scheduler's clone-if-missing path instead of aborting with "clone it first".
+**Name resolution** is `resolve_names` (one home): `upstream_pkgname` or `None`, `pkgname` defaulting to `upstream_pkgname`; neither set is an error. **Source resolution** is `_resolve_source(kernel_cfg, srcdir_path)`: an explicit `source` is honored (`git` errors — it was a phantom value with no URL to clone from); when omitted it auto-resolves `local → repo → aur` — an existing non-git tree is `local` (never clobbered by a re-clone), an existing git clone is `repo` (the scheduler's generic fetch rebases via the tree's own origin, skipping the AUR RPC), and a missing tree picks its clone remote via `aur.is_repo_package` on the tracked name (sync DB hit → `repo`/pkgctl, else `aur`). The build entry runs the source sync **before** requiring the PKGBUILD path, so a missing tree is bootstrapped by the scheduler's clone-if-missing path instead of aborting with "clone it first".
 
 **Per-role kernel names (`3.3.0-F6`).** An FDO kernel never replaces the plain one; each role installs beside it under its own name. `kernel_fdo.record_pkgname` and `kernel_fdo.optimized_pkgname` are the only producers: `pkgname`, then `-sysforge` appended if absent, then exactly one role suffix (`kernel_fdo.strip_role` inverts it).
 
@@ -958,9 +969,9 @@ The name always reflects what was *applied*: a Propeller → AutoFDO fallback in
 
 **Kernel-stage compiler override:** `compiler = "gcc" | "llvm"` is independent of the toolchain stage. A system that keeps gcc system-wide can still build the kernel with LLVM (or vice versa). Resolution order: `--toolchain` CLI flag > `kernel.toml compiler` > toolchain-stage pipeline state (cc/cxx set by stage 5) > profile defaults. When set to LLVM, the standard `LLVM=1 LLVM_IAS=1` env vars are injected by `makepkg_wrapper` automatically — no extra PKGBUILD changes needed. Note: `compiler = "llvm"` builds the kernel *with* clang but does **not** apply the toolchain's PGO profdata — that profdata trains the clang binary, not the linux target. The kernel's own profile-guided path is sample-based AutoFDO/Propeller (`--autofdo`, LLVM-only), described under *Sample-based kernel FDO* below — a distinct mechanism from the toolchain PGO.
 
-**Headers/docs subpackages (`build_headers` / `build_docs`):** the kernel image is always built; the optional `-headers` and `-docs` subpackages are toggled independently. `build_headers` defaults **on** (DKMS and any out-of-tree module build need the matching kernel headers to compile); `build_docs` defaults **off** (the docs subpackage is slow to package and rarely needed) — note this drops the `-docs` subpackage that a stock kernel PKGBUILD would otherwise build. Resolution per toggle: CLI flag (`--headers`/`--no-headers`, `--docs`/`--no-docs`, `argparse.BooleanOptionalAction`, default unset → `None`) > `kernel.toml` (`build_headers`/`build_docs`) > hard default. The single home for the resolve is `_resolve_subpackages`. Disabling a subpackage works by **dropping its entry from the PKGBUILD's `pkgname` array** — `pkgbuild_patcher.patch_kernel_subpackages` (called from `makepkg_wrapper` for every kernel build, after `patch_kernel_btf_guard`) removes any array token whose dequoted value ends with `-headers`/`-docs`. It rewrites **both** the initial `pkgname=(...)` literal **and** every `pkgname+=(...)` append — modern Arch kernel PKGBUILDs add the optional subpackages via `pkgname+=("$pkgbase-docs")`, which a single-array walk would miss (leaving `-docs` to build and install; B7); an append that existed solely to add now-dropped subpackage(s) has its whole statement line removed rather than leaving an empty `pkgname+=()`. Standard Arch kernels synthesize each `package_$_p()` via `for _p in "${pkgname[@]}"; do eval …`, so an entry absent from the array is never packaged; the `_package-headers()`/`_package-docs()` helper bodies are left untouched. **Disabling docs additionally neutralizes the doc *build*:** stock Arch `linux` builds the documentation in `build()` (`make htmldocs SPHINXOPTS=-QT`), not only in `_package-docs()`, so dropping the `-docs` pkgname token stops packaging but not the (often multi-minute Sphinx) compile — which would make the summary's `docs=off` a lie. When `build_docs` is off the same patcher neutralizes any doc-target make line (`_neutralize_kernel_doc_build`, two passes over the goals — htmldocs/pdfdocs/infodocs/mandocs/…): a **mixed** line such as `make all htmldocs` loses *only* its `*docs` goals (→ `make all`) so the real build survives, while a line whose goals are **exclusively** `*docs` (with optional `VAR=val`/flag tokens) is commented out whole with a `# sysforge(docs off):` prefix. Both passes treat shell control operators and redirections (`&`, `;`, `|`, `&&`, `>…`) as punctuation the shell owns, never as make goals — stock Arch `linux` *backgrounds* its doc build (`make htmldocs SPHINXOPTS=-QT &`), and counting the trailing `&` as a surviving real goal made an exclusive-doc line look mixed: only `htmldocs` was stripped, leaving a goalless `make &` that resolves to make's **default** goal (`all`) and runs a second kernel build concurrently with the real one, killing `build()` with `E_USER_FUNCTION_FAILED` (B15). A backgrounded exclusive-doc line is additionally rewritten to `true &` rather than merely commented: the following line is invariably `local pid_docs=$!` and the function later `wait`s on that pid, so removing the only background job would leave the capture reading an unset or stale `$!` — and a `wait` on a non-child exits non-zero, fatal under makepkg's errexit. A trivial background job keeps `$!` valid and `wait` at 0, with the original command preserved in the trailing `# sysforge(docs off):` comment. The patcher needs no sentinel (every edit is self-idempotent — a commented line no longer starts with `make`, a stripped/removed token no longer matches), is a no-op when both subpackages are kept or the targeted subpackage is absent, and preserves both the single-line and one-token-per-line array layouts. When `build_headers` is disabled, Gate 1 escalates the standing DKMS reminder into a hard warning: no `<pkg>-headers` will be installed, so out-of-tree and DKMS modules (nvidia-open-dkms → black screen) cannot rebuild and won't load on reboot; any present DKMS modules are named.
+**Headers/docs subpackages (`build_headers` / `build_docs`):** the kernel image is always built; the optional `-headers` and `-docs` subpackages are toggled independently. `build_headers` defaults **on** (DKMS and any out-of-tree module build need the matching kernel headers to compile); `build_docs` defaults **off** (the docs subpackage is slow to package and rarely needed) — note this drops the `-docs` subpackage that a stock kernel PKGBUILD would otherwise build. Resolution per toggle: CLI flag (`--headers`/`--no-headers`, `--docs`/`--no-docs`, `argparse.BooleanOptionalAction`, default unset → `None`) > `kernel.toml` (`build_headers`/`build_docs`) > hard default. The single home for the resolve is `resolve_subpackages`. Disabling a subpackage works by **dropping its entry from the PKGBUILD's `pkgname` array** — `pkgbuild_patcher.patch_kernel_subpackages` (called from `makepkg_wrapper` for every kernel build, after `patch_kernel_btf_guard`) removes any array token whose dequoted value ends with `-headers`/`-docs`. It rewrites **both** the initial `pkgname=(...)` literal **and** every `pkgname+=(...)` append — modern Arch kernel PKGBUILDs add the optional subpackages via `pkgname+=("$pkgbase-docs")`, which a single-array walk would miss (leaving `-docs` to build and install; B7); an append that existed solely to add now-dropped subpackage(s) has its whole statement line removed rather than leaving an empty `pkgname+=()`. Standard Arch kernels synthesize each `package_$_p()` via `for _p in "${pkgname[@]}"; do eval …`, so an entry absent from the array is never packaged; the `_package-headers()`/`_package-docs()` helper bodies are left untouched. **Disabling docs additionally neutralizes the doc *build*:** stock Arch `linux` builds the documentation in `build()` (`make htmldocs SPHINXOPTS=-QT`), not only in `_package-docs()`, so dropping the `-docs` pkgname token stops packaging but not the (often multi-minute Sphinx) compile — which would make the summary's `docs=off` a lie. When `build_docs` is off the same patcher neutralizes any doc-target make line (`_neutralize_kernel_doc_build`, two passes over the goals — htmldocs/pdfdocs/infodocs/mandocs/…): a **mixed** line such as `make all htmldocs` loses *only* its `*docs` goals (→ `make all`) so the real build survives, while a line whose goals are **exclusively** `*docs` (with optional `VAR=val`/flag tokens) is commented out whole with a `# sysforge(docs off):` prefix. Both passes treat shell control operators and redirections (`&`, `;`, `|`, `&&`, `>…`) as punctuation the shell owns, never as make goals — stock Arch `linux` *backgrounds* its doc build (`make htmldocs SPHINXOPTS=-QT &`), and counting the trailing `&` as a surviving real goal made an exclusive-doc line look mixed: only `htmldocs` was stripped, leaving a goalless `make &` that resolves to make's **default** goal (`all`) and runs a second kernel build concurrently with the real one, killing `build()` with `E_USER_FUNCTION_FAILED` (B15). A backgrounded exclusive-doc line is additionally rewritten to `true &` rather than merely commented: the following line is invariably `local pid_docs=$!` and the function later `wait`s on that pid, so removing the only background job would leave the capture reading an unset or stale `$!` — and a `wait` on a non-child exits non-zero, fatal under makepkg's errexit. A trivial background job keeps `$!` valid and `wait` at 0, with the original command preserved in the trailing `# sysforge(docs off):` comment. The patcher needs no sentinel (every edit is self-idempotent — a commented line no longer starts with `make`, a stripped/removed token no longer matches), is a no-op when both subpackages are kept or the targeted subpackage is absent, and preserves both the single-line and one-token-per-line array layouts. When `build_headers` is disabled, Gate 1 escalates the standing DKMS reminder into a hard warning: no `<pkg>-headers` will be installed, so out-of-tree and DKMS modules (nvidia-open-dkms → black screen) cannot rebuild and won't load on reboot; any present DKMS modules are named.
 
-**Resolution summary.** After resolving compiler (+ its origin), variant, bootloader (+ whether the chosen one is detected installed), source, interactive mode, kconfig counts, the headers/docs subpackage toggles (`subpkgs:` line), and the boot-safety gate settings, the stage emits a single labelled "Kernel build plan:" block (`_log_resolution_summary`). It prints on every run (useful before a multi-hour build) and is the readable core of `--dry-run`, replacing decisions previously scattered across the log. The standalone interactive default also emits a one-line nudge pointing at `--no-interactive` for unattended runs.
+**Resolution summary.** After resolving compiler (+ its origin), variant, bootloader (+ whether the chosen one is detected installed), source, interactive mode, kconfig counts, the headers/docs subpackage toggles (`subpkgs:` line), and the boot-safety gate settings, the stage emits a single labelled "Kernel build plan:" block (`log_resolution_summary`). It prints on every run (useful before a multi-hour build) and is the readable core of `--dry-run`, replacing decisions previously scattered across the log. The standalone interactive default also emits a one-line nudge pointing at `--no-interactive` for unattended runs.
 
 **Variant-inheritance nudge.** When `compiler` is unset (neither CLI nor `kernel.toml`) and the toolchain-stage variant is `pgo_llvm`, the stage emits a WARN naming the inherited variant and recommending that the operator persist `compiler = "llvm"` in `kernel.toml` so the choice survives a future toolchain-stage disable (which clears `[stages.toolchain.result]`). `stock_llvm` gets the same nudge at INFO level. `gcc` and `system` variants are silent — gcc is the safe default and `system` means there's no opinion to project.
 
@@ -996,9 +1007,9 @@ The fragment is an *overlay* — it does not define the build's starting `.confi
 
 Before the build, `lsmod` output is captured to `<state_dir>/lsmod.snapshot` (unless `capture_lsmod_snapshot = false`), then `kconfig.stage_lsmod_snapshot` copies it next to the PKGBUILD as `kconfig_plan.LSMOD_FILE` (`sysforge.lsmod`) — `prepare()` can reach `$startdir` but not the state dir. A configured `localmodconfig`/`localyesconfig` (`kconfig_targets`, below) renders as a guard block that passes it as `LSMOD="$startdir/sysforge.lsmod"` when the file exists and falls back to the bare invocation (live `lsmod`) when it does not; the guard is required because `streamline_config.pl` dies on an `LSMOD` path that does not exist, and treats `LSMOD=""` as one. Without `LSMOD` the minimizer reads live `lsmod` and the accumulated set below is never used (`3.2.0-B35`). Both branches of the guard also take their stdin from `< <(yes '')` (`kconfig_plan._DEFAULT_ANSWERS`): the minimizer ends in `conf --oldconfig`, which prompts for every symbol that minimization newly exposes (a `(NEW)` symbol absent from every prior config), and inheriting the interactive stage's terminal stranded the build on an unannounced prompt ahead of the REVIEW slot. Default answers resolve exactly as the `olddefconfig` that follows would, leaving REVIEW the single human touchpoint. It is a process substitution rather than a `yes '' |` pipeline because makepkg toggles `pipefail`, under which `yes` dying of SIGPIPE would fail `prepare()` (`3.2.0-B36`). With capture off or no snapshot, a stale staged copy is removed so the fallback is live `lsmod`, not a previous run's data. A packager-owned `make localmodconfig` line (no `kconfig_targets`) is left as written and reads live `lsmod`. `localmodconfig` strips drivers for hardware *not loaded at snapshot time* — Gate 1 warns about this only when `kconfig_targets` actually names a minimizer (otherwise it logs at `info` that the config is not minimized, since a snapshot alone trims nothing), and Gate 2 (below) is the backstop that catches a dropped root-path driver before install.
 
-**Keeping hotplug drivers through minimization (`keep_hotplug_drivers`):** `localmodconfig`/`localyesconfig` minimize to hardware present *at build time*, so a device attached later (a USB drive, an SD card, a hot-plugged PCI/CardBus card) can end up with no built driver. `kernel.toml keep_hotplug_drivers` (default off; also `--keep-hotplug-drivers`/`--no-keep-hotplug-drivers`, CLI wins over the config key) re-enables a curated set of hotplug driver classes — USB host/gadget, USB4/Thunderbolt, MMC/SD, hot-plug PCI/CardBus, hot-plug HID, and removable-media filesystems (FAT/VFAT, exFAT, ISO 9660, UDF, NTFS3, plus the `NLS_UTF8`/`NLS_ISO8859_1` codepages their default mount options need) — regardless of what was attached at build time. The set is additive (it only ever enables; no `is not set` lines), and each symbol carries the value its kconfig type permits — `=m` for tristate symbols, `=y` for the `bool` ones (`CONFIG_HOTPLUG_PCI`, `CONFIG_HOTPLUG_PCI_PCIE`, `CONFIG_CARDBUS`). Writing `=m` for a bool makes kconfig discard the assignment entirely with `symbol value 'm' invalid for X`, so the symbol silently falls back to its tree default and the re-enable is lost; `tests/test_stage_kernel.py::test_hotplug_kconfig_values_are_legal` pins the per-symbol values, and adding a symbol to the curated set means checking its type in the kernel tree first. Resolution is `_resolve_keep_hotplug_drivers`; when it's on, the stage writes the curated set to a dedicated `sysforge.hotplug.config` fragment (distinct from the main `sysforge.config` fragment above) next to the PKGBUILD. The merge is contributed as the `kconfig_plan.HOTPLUG_MERGE` slot, ordered by `SLOT_ORDER` *after* `GENERATE` (so any `localmodconfig`/`localyesconfig` minimization has already run and can't strip the re-enabled modules) and *before* `REVIEW` (the configured tail or the injected `make nconfig`), so the operator still reviews the final, hotplug-safe config. File-existence guarded and idempotent, like the other fragment merges. When the key resolves off, any stale `sysforge.hotplug.config` from a prior run is removed. Boot safety remains authoritative — this mechanism only *adds* modules; it doesn't touch Gate 1/Gate 2.
+**Keeping hotplug drivers through minimization (`keep_hotplug_drivers`):** `localmodconfig`/`localyesconfig` minimize to hardware present *at build time*, so a device attached later (a USB drive, an SD card, a hot-plugged PCI/CardBus card) can end up with no built driver. `kernel.toml keep_hotplug_drivers` (default off; also `--keep-hotplug-drivers`/`--no-keep-hotplug-drivers`, CLI wins over the config key) re-enables a curated set of hotplug driver classes — USB host/gadget, USB4/Thunderbolt, MMC/SD, hot-plug PCI/CardBus, hot-plug HID, and removable-media filesystems (FAT/VFAT, exFAT, ISO 9660, UDF, NTFS3, plus the `NLS_UTF8`/`NLS_ISO8859_1` codepages their default mount options need) — regardless of what was attached at build time. The set is additive (it only ever enables; no `is not set` lines), and each symbol carries the value its kconfig type permits — `=m` for tristate symbols, `=y` for the `bool` ones (`CONFIG_HOTPLUG_PCI`, `CONFIG_HOTPLUG_PCI_PCIE`, `CONFIG_CARDBUS`). Writing `=m` for a bool makes kconfig discard the assignment entirely with `symbol value 'm' invalid for X`, so the symbol silently falls back to its tree default and the re-enable is lost; `tests/test_stage_kernel.py::test_hotplug_kconfig_values_are_legal` pins the per-symbol values, and adding a symbol to the curated set means checking its type in the kernel tree first. Resolution is `resolve_keep_hotplug_drivers`; when it's on, the stage writes the curated set to a dedicated `sysforge.hotplug.config` fragment (distinct from the main `sysforge.config` fragment above) next to the PKGBUILD. The merge is contributed as the `kconfig_plan.HOTPLUG_MERGE` slot, ordered by `SLOT_ORDER` *after* `GENERATE` (so any `localmodconfig`/`localyesconfig` minimization has already run and can't strip the re-enabled modules) and *before* `REVIEW` (the configured tail or the injected `make nconfig`), so the operator still reviews the final, hotplug-safe config. File-existence guarded and idempotent, like the other fragment merges. When the key resolves off, any stale `sysforge.hotplug.config` from a prior run is removed. Boot safety remains authoritative — this mechanism only *adds* modules; it doesn't touch Gate 1/Gate 2.
 
-The snapshot **accumulates**: `_capture_lsmod_snapshot` union-merges each new `lsmod` capture with the prior snapshot by module name (`_merge_lsmod`), with the current capture's row winning on overlap (fresher `Size`/`Used` data) and prior-only rows retained. This means a module that was loaded once (USB device, VPN, container netfilter) but isn't loaded during a later capture is never dropped just because that particular run didn't have it active — the module set grows monotonically across builds instead of resetting each time. There is no reset flag: to start over, delete `<state_dir>/lsmod.snapshot` manually.
+The snapshot **accumulates**: `capture_lsmod_snapshot` union-merges each new `lsmod` capture with the prior snapshot by module name (`merge_lsmod`), with the current capture's row winning on overlap (fresher `Size`/`Used` data) and prior-only rows retained. This means a module that was loaded once (USB device, VPN, container netfilter) but isn't loaded during a later capture is never dropped just because that particular run didn't have it active — the module set grows monotonically across builds instead of resetting each time. There is no reset flag: to start over, delete `<state_dir>/lsmod.snapshot` manually.
 
 **Configurable kconfig target sequence (`kconfig_targets`):**
 
@@ -1020,15 +1031,15 @@ The resolved sequence is threaded as `BuildOptions.kconfig_targets` (kernel.py 
 
 Note: when other verbs (`sysforge build`, `sysforge update`) build a kernel PKGBUILD with `build_mode = "kernel"` on the resolved profile, those paths still default to *non-interactive* — interactive-by-default is a kernel-stage-only contract because the stage is the user-driven kernel build entry point.
 
-**Post-build kconfig drift (advisory):** after the build, beside Gate 2 (pre-install, outside the sentinel), `_gate2_kconfig_drift` compares the options sysforge merged into `sysforge.config` against the resolved `.config` and warns on any that didn't survive — disabled (`y/m`→`n`/absent), changed (built-in↔module, or a string/int value change), or re-enabled (`n`→`y/m`). On the interactive path a drop usually means the operator toggled it off in `make nconfig`; otherwise it's typically `make olddefconfig` dropping a request whose dependencies are unmet. sysforge can't distinguish the two without a full dependency solve, so this **never blocks** the build — unlike the boot-critical Gate 2 audit it sits next to. The diff itself is a pure fact in `kernel_safety.diff_requested_kconfig` (returning `KconfigDrift` records over the same `parse_kconfig_text` representation both files share — a missing resolved option normalises to `n`, so a requested `n` that ends up absent is correctly not flagged); the stage owns only the logging. The check keys off the fragment's existence, so it is on exactly when `kconfig_merge` produced a fragment (both on or both off).
+**Post-build kconfig drift (advisory):** after the build, beside Gate 2 (pre-install, outside the sentinel), `gate2_kconfig_drift` compares the options sysforge merged into `sysforge.config` against the resolved `.config` and warns on any that didn't survive — disabled (`y/m`→`n`/absent), changed (built-in↔module, or a string/int value change), or re-enabled (`n`→`y/m`). On the interactive path a drop usually means the operator toggled it off in `make nconfig`; otherwise it's typically `make olddefconfig` dropping a request whose dependencies are unmet. sysforge can't distinguish the two without a full dependency solve, so this **never blocks** the build — unlike the boot-critical Gate 2 audit it sits next to. The diff itself is a pure fact in `kernel_safety.diff_requested_kconfig` (returning `KconfigDrift` records over the same `parse_kconfig_text` representation both files share — a missing resolved option normalises to `n`, so a requested `n` that ends up absent is correctly not flagged); the stage owns only the logging. The check keys off the fragment's existence, so it is on exactly when `kconfig_merge` produced a fragment (both on or both off).
 
 **Source sync via the scheduler:**
 
-The kernel stage routes its source refresh through `source_sync.get_scheduler().request(SyncRequest(..., source=<resolved source>))` ahead of the build, the same path as the toolchain stage — and (F40) *before* `_pkgbuild_path` requires the PKGBUILD, so a missing tree is bootstrapped by the scheduler's clone-if-missing path. With `source = "local"` (explicit or auto-resolved), the scheduler short-circuits (no RPC, no clone, no fetch) — only `--cleansrc` / `--cleansrc-force` would attempt a purge, but a hand-maintained tree has no remote to re-clone from, so users on the `local` path leave cleansrc unset. For `source = "repo"` / `"aur"`, the normal sync runs: `--cleansrc` purges and re-clones (refusing on dirty/ahead/no-upstream clones); `--cleansrc-force` overrides that guard; cleansrc forces a sync even when `--no-update` is also set. `STATUS_FAILED` / `STATUS_RATE_LIMITED` / `STATUS_PURGE_REFUSED` raise.
+The kernel stage routes its source refresh through `source_sync.get_scheduler().request(SyncRequest(..., source=<resolved source>))` ahead of the build, the same path as the toolchain stage — and (F40) *before* `pkgbuild_path` requires the PKGBUILD, so a missing tree is bootstrapped by the scheduler's clone-if-missing path. With `source = "local"` (explicit or auto-resolved), the scheduler short-circuits (no RPC, no clone, no fetch) — only `--cleansrc` / `--cleansrc-force` would attempt a purge, but a hand-maintained tree has no remote to re-clone from, so users on the `local` path leave cleansrc unset. For `source = "repo"` / `"aur"`, the normal sync runs: `--cleansrc` purges and re-clones (refusing on dirty/ahead/no-upstream clones); `--cleansrc-force` overrides that guard; cleansrc forces a sync even when `--no-update` is also set. `STATUS_FAILED` / `STATUS_RATE_LIMITED` / `STATUS_PURGE_REFUSED` raise.
 
-`STATUS_DIVERGED` (upstream advanced but the local tree can't fast-forward — local commits or a dirty tree) gets stronger handling in the *kernel* stage than the plain warning the other verbs use, because building a kernel off stale or hand-edited source is exactly the easy-to-miss footgun. `_warn_and_confirm_diverged` enriches the WARN with ahead/behind counts (`classify_head_vs_upstream`) so the "upstream has new commits but the local repo is dirty" case is spelled out, then **gates the build**: an interactive run must confirm (`prompt_choice`, default no), and an unattended run (`--no-interactive` or no TTY) aborts. Either decline raises, leaving nothing built (the sync runs before the sentinel). `--cleansrc` to discard local edits is the suggested escape hatch.
+`STATUS_DIVERGED` (upstream advanced but the local tree can't fast-forward — local commits or a dirty tree) gets stronger handling in the *kernel* stage than the plain warning the other verbs use, because building a kernel off stale or hand-edited source is exactly the easy-to-miss footgun. `warn_and_confirm_diverged` enriches the WARN with ahead/behind counts (`classify_head_vs_upstream`) so the "upstream has new commits but the local repo is dirty" case is spelled out, then **gates the build**: an interactive run must confirm (`prompt_choice`, default no), and an unattended run (`--no-interactive` or no TTY) aborts. Either decline raises, leaving nothing built (the sync runs before the sentinel). `--cleansrc` to discard local edits is the suggested escape hatch.
 
-The source sync (including the `--cleansrc` purge, which `purge_src` does as a non-atomic `shutil.rmtree`) runs **outside** the boot sentinel by design: it mutates only the src tree, nothing boot-critical, so wrapping it in the sentinel — whose `recovery_cmd` is `sudo mkinitcpio -P` — would be semantically wrong. The atomicity contract is "purge, then clone"; an interrupted purge leaves a missing/partial PKGBUILD that fails **loudly** at `_pkgbuild_path` on the next run (with a hint to re-run `--cleansrc` to re-clone), not a silent brick. No sentinel is needed because the running kernel was never touched.
+The source sync (including the `--cleansrc` purge, which `purge_src` does as a non-atomic `shutil.rmtree`) runs **outside** the boot sentinel by design: it mutates only the src tree, nothing boot-critical, so wrapping it in the sentinel — whose `recovery_cmd` is `sudo mkinitcpio -P` — would be semantically wrong. The atomicity contract is "purge, then clone"; an interrupted purge leaves a missing/partial PKGBUILD that fails **loudly** at `pkgbuild_path` on the next run (with a hint to re-run `--cleansrc` to re-clone), not a silent brick. No sentinel is needed because the running kernel was never touched.
 
 **Stage-ownership stamp:**
 
@@ -1106,7 +1117,7 @@ The AUR-dep build and per-package install loop are wrapped in `sentinel_scope(st
 
 ### Toolchain stage (stage 5)
 
-**Module layout.** The stage is a package (`pipeline/stages/toolchain/`), not a module. It was one 4263-line file with four classes and a 701-line `_build_llvm_pgo_inner`; `3.2.0-F2` split it along the seams its own comment banners already named:
+**Module layout.** The stage is a package (`pipeline/stages/toolchain/`), not a module. It was one 4263-line file with four classes and a 701-line `build_llvm_pgo_inner`; `3.2.0-F2` split it along the seams its own comment banners already named:
 
 | module | holds |
 | --- | --- |
@@ -1174,17 +1185,17 @@ When `compiler` is unset (or set to `"gcc"`), the toolchain stage is **register-
 
 **Build-safety gates + build/install split (kernel-parity).** The LLVM path mirrors the kernel stage's three-gate / build-install-split structure so a broken or doomed build can never leave the live `/usr` toolchain inconsistent. The pure, unit-testable facts live in `primitives/toolchain_safety.py` (`ToolchainFinding(severity, check_id, message, remediation, is_brick)`); the toolchain stage owns the abort/warn *policy*. `toolchain_safety` imports `LLVM_LOCKSTEP_SUITE` from `toolchain_preflight` (both primitives — no layering issue) and is **not** a third health-check entry point: `_verify_llvm_install` (pipeline, post-install) and `toolchain_preflight._probe_cc` (primitives, update path) remain the only two, and `_verify_llvm_install`'s skew arm now draws from `toolchain_safety.detect_suite_skew`.
 
-- **Gate 1 — pre-build preflight** (`_gate1_preflight`, outside the sentinel, runs for both PGO and non-PGO). Brick-class aborts *before any build time is spent*: PKGBUILD pkgver skew across the lockstep suite (`check_pkgver_lockstep`; `spirv-llvm-translator` + `lib32-*` are excluded so their legitimately-different versions don't false-positive — the bug the old whole-set `_check_pkgver_consistency` had); a non-functional clang (`smoke_test_compilers`, now run on the non-PGO path too); insufficient build-filesystem headroom (`check_build_space`, deduped by `st_dev`); `[multilib]` disabled while a `lib32-*` is in scope (`check_multilib_enabled`). Each brick is overridable (`--allow-version-skew`, `--allow-low-build-space`, `require_multilib = false`) and **downgraded to a warning in `--dry-run`**. Advisory (warn-only): residual `-fprofile-generate` instrumentation; an incomplete rollback snapshot.
-- **Bootstrap-compiler self-heal (inside Gate 1, `_install_bootstrap_compilers`).** The LLVM path is a 4-pass bootstrap: Pass 1 must be compiled by an *already-installed* `/usr/bin/clang`, and `lld` links every pass. Both are needed **earlier than any other build prerequisite** — before `build_core.batch_install_makedeps` runs — and neither appears in the llvm PKGBUILD's `makedepends` (upstream builds with gcc), so nothing else in the pipeline would ever install them. On a clean machine (`base-devel` ships gcc, not clang) the stage therefore bricked on `smoke:clang_missing` with a manual `pacman -S clang` hint, making the LLVM toolchain unreachable without an out-of-band step. Gate 1 now maps the *missing*-class smoke findings to their providing package (`_BOOTSTRAP_PKG_FOR`: `smoke:clang_missing`→`clang`, `smoke:lld_missing`→`lld`), installs them via `install_repo_pkgs` inside a `sentinel_scope` (a mutation window, sequential with — never nested in — the build sentinel; entered only after `sudo_session.authenticate()` succeeds, `3.5.0-B75`), then **re-runs `smoke_test_compilers` and acts on the result**, so a freshly-installed-but-broken clang still aborts. `smoke:clang_broken` is deliberately *not* auto-installable: it signals a mismatched lockstep suite from an aborted run, whose remediation is reinstalling the whole suite under the operator's eye, not a blind `-S clang`. In `--dry-run` the install is previewed and the original brick is preserved (downgraded to a warning by the enclosing gate).
+- **Gate 1 — pre-build preflight** (`gate1_preflight`, outside the sentinel, runs for both PGO and non-PGO). Brick-class aborts *before any build time is spent*: PKGBUILD pkgver skew across the lockstep suite (`check_pkgver_lockstep`; `spirv-llvm-translator` + `lib32-*` are excluded so their legitimately-different versions don't false-positive — the bug the old whole-set `_check_pkgver_consistency` had); a non-functional clang (`smoke_test_compilers`, now run on the non-PGO path too); insufficient build-filesystem headroom (`check_build_space`, deduped by `st_dev`); `[multilib]` disabled while a `lib32-*` is in scope (`check_multilib_enabled`). Each brick is overridable (`--allow-version-skew`, `--allow-low-build-space`, `require_multilib = false`) and **downgraded to a warning in `--dry-run`**. Advisory (warn-only): residual `-fprofile-generate` instrumentation; an incomplete rollback snapshot.
+- **Bootstrap-compiler self-heal (inside Gate 1, `install_bootstrap_compilers`).** The LLVM path is a 4-pass bootstrap: Pass 1 must be compiled by an *already-installed* `/usr/bin/clang`, and `lld` links every pass. Both are needed **earlier than any other build prerequisite** — before `build_core.batch_install_makedeps` runs — and neither appears in the llvm PKGBUILD's `makedepends` (upstream builds with gcc), so nothing else in the pipeline would ever install them. On a clean machine (`base-devel` ships gcc, not clang) the stage therefore bricked on `smoke:clang_missing` with a manual `pacman -S clang` hint, making the LLVM toolchain unreachable without an out-of-band step. Gate 1 now maps the *missing*-class smoke findings to their providing package (`_BOOTSTRAP_PKG_FOR`: `smoke:clang_missing`→`clang`, `smoke:lld_missing`→`lld`), installs them via `install_repo_pkgs` inside a `sentinel_scope` (a mutation window, sequential with — never nested in — the build sentinel; entered only after `sudo_session.authenticate()` succeeds, `3.5.0-B75`), then **re-runs `smoke_test_compilers` and acts on the result**, so a freshly-installed-but-broken clang still aborts. `smoke:clang_broken` is deliberately *not* auto-installable: it signals a mismatched lockstep suite from an aborted run, whose remediation is reinstalling the whole suite under the operator's eye, not a blind `-S clang`. In `--dry-run` the install is previewed and the original brick is preserved (downgraded to a warning by the enclosing gate).
 - **Soname gate — pre-build, between Gate 1 and the build** (`_gate_soname_consumers`, calls `toolchain_safety.assess_libllvm_soname_impact`). PGO/optimization never changes `libLLVM`'s `SOVERSION` or exported symbols, so a same-version rebuild is ABI-identical and silent; but a libLLVM **version bump** changes the soname (`libLLVM.so.22.1` → `libLLVM.so.23.0`), and every installed package that links the old soname (mesa's radeonsi/radv/llvmpipe, and others) is left with a dangling `NEEDED` until rebuilt. The gate derives the target soname from the resolved llvm PKGBUILD pkgver, reads the installed soname authoritatively from `llvm-libs`'s on-disk file list, and — when they differ — enumerates the installed consumers (every package whose recorded `%DEPENDS%` carries a `libLLVM.so=<old major.minor>` soname dep, via `dep_analysis._SONAME_RE`), collapsed to pkgbase and **excluding** the LLVM lockstep suite + the packages being built this run (they're rebuilt here already). The `rebuild_soname_consumers` mode (CLI `--rebuild-soname-consumers` > `toolchain.toml` > `"prompt"`) decides: `prompt` (default) warns + lists + asks, approving captures the consumers for rebuild after Gate 3 and declining is a clean abort (non-TTY aborts — never silently break the system, pointing at `=auto`/`=off`); `auto` approves without prompting; `off` builds the toolchain but rebuilds nothing, printing the manual `sysforge build <consumers>` command. `--dry-run` previews the impact without prompting or rebuilding. The consumer rebuild runs through the same PKGBUILD review policy as `update` and `build` (`pkgbuild_review.resolve_review_policy` over packages.toml `[build]`, 3.0.0-F3): with no terminal an untrusted changed consumer source is refused, and a refusal fails the stage with the manual rebuild command like any other unfinished consumer. Like `build`, it stamps `source = "repo"` on a consumer whose checkout's `origin` is the official packaging repo for that pkgbase (`aur.repo_checkout_pkgbase`: host `gitlab.archlinux.org`, project `archlinux/packaging/packages/<pkgbase>`), so the default trusted list (`["repo"]`) accepts official-repo consumers such as doxygen without a prompt; before `3.5.0-B16` every consumer was unclassified, read as `aur`, and reviewed. Provenance is the origin, never the PKGBUILD's declared names: an AUR PKGBUILD may list any `pkgname`, so a name-based test would let it skip review. The facts function is pure (guarded reads degrade to "no impact"); the stage owns the prompt/abort policy.
 - **Build (outside the sentinel).** All passes build with `install=False`; the build functions return the built package map. A build-pass failure therefore mutates nothing and leaves **no sentinel** (matches kernel).
-- **Gate 2 — pre-install ABI audit** (`_gate2_audit`, outside the sentinel, both paths). Scans the built `.pkg.tar*` for the `_ZNSt*@LLVM_*` hazard via `toolchain_safety.scan_abi_hazards`, **and** for a **graphics-consumer symbol shortfall** via `toolchain_safety.check_system_consumer_symbols`: it extracts the about-to-be-installed `libLLVM.so.*` from the built packages (lib32 excluded) and, for each installed external consumer that links that exact soname (mesa's `libgallium`/DRI/Vulkan drivers, curated in `_SYSTEM_LIBLLVM_CONSUMER_GLOBS`), checks every `LLVM_x.y`-versioned symbol the consumer imports is exported by the new libLLVM. An import one of the consumer's *other* `NEEDED` libraries exports (resolved through `ldconfig`) is not owed by libLLVM and is left out: libclang, libclang-cpp and liblldb version their own exports `LLVM_*` too, so doxygen's `clang_*@LLVM_13` and lldb's `lldb::SB*@LLVM_<ver>` would otherwise read as drift and queue a needless consumer rebuild (`3.5.0-B18`). Neither is any package the batch itself ships: besides the lockstep suite, the merged `llvm` pkgbase builds lldb, libclc and llvm-lit, whose installed copies the same `pacman -U` replaces, so the scan drops every pkgname read from the built archives' `.PKGINFO` (`toolchain_safety.shipped_pkgnames`, `3.5.0-B20`). `_diff_consumers_against_libllvm` splits a miss into two classes (see §`graphics-stack` → *Two stranding classes*): an **unhealable** target-init drop (`LLVMInitialize*` — a reduced `LLVM_TARGETS_TO_BUILD` dropped a backend the consumer needs, e.g. AMDGPU; the symbol exists nowhere) **aborts before any `pacman -U`** — nothing installed, no sentinel; a **healable** `std::` re-export drop (only non-target-init `LLVM_*` symbols — the `-fprofile-use` libLLVM inlined away the weak libstdc++ copies the stock build re-exported at the *same* soname) does **not** abort. For the healable case Gate 2 enumerates the installed libLLVM consumers via `toolchain_safety.libllvm_abi_consumers` (the reverse-dep `%DEPENDS%` walk shared with the soname gate, here un-gated on a soname change), applies the `rebuild_soname_consumers` mode (prompt/auto/off, mirroring the soname gate), and **returns** them for rebuild after Gate 3. This is the gate that `scan_abi_hazards` (intra-build only) never covered: it checks *already-installed* external consumers, the gap that let a target-reduced libLLVM ship. **`std::` export parity (`3.5.0-F4`).** The healable class cannot heal mesa built in the sandbox, which links the repo libLLVM again, so the llvm PKGBUILD's `prepare()` gains a block (`pkgbuild_patcher.patch_llvm_std_exports`, wired as `makepkg_wrapper._maybe_patch_llvm_std_exports` beside the target patch) that adds `primitives/llvm_std_exports.py`'s thunks to libLLVM: each libstdc++ member stock re-exported and the `-fprofile-use` build dropped is exported again as `sym@LLVM_<mm>` at a **non-default** version, forwarding to libstdc++'s own `@GLIBCXX_*` export. An already-linked consumer resolves it; no new link binds to it, so the suite built alongside keeps importing `@GLIBCXX_*` and `scan_abi_hazards` stays clean (default-version re-exports, the obvious fix, would trip it). The CMake hook configures itself out unless the build links with lld on x86-64 with a known `LLVM_SHLIB_SYMBOL_VERSION`. Gate 2 then reports, as `-v` narration, any pure-`std` export stock has that the build still lacks and the system `libstdc++.so.6` itself exports (only that extern-template set is imported rather than emitted by a consumer; stock exports other std instantiations only because GCC built it) (`toolchain_safety.check_std_export_parity`, against the signed stock `llvm-libs` of the same version in the pacman cache via `pacman.cached_repo_pkg_file`; skipped when none is cached). The TU goes in `llvm-shlib/sysforge/`, because LLVM's configure (`llvm_check_source_file_list`) rejects any unlisted `*.cpp` in a target's own directory. `build_fingerprint._SCHEMA` 4 keeps `--reuse-built` from reusing a libLLVM built without the thunks, and the rendered block's hash is a Pass-4 fingerprint input, so a later `STD_EXPORTS` edit invalidates reuse on its own.
+- **Gate 2 — pre-install ABI audit** (`gate2_audit`, outside the sentinel, both paths). Scans the built `.pkg.tar*` for the `_ZNSt*@LLVM_*` hazard via `toolchain_safety.scan_abi_hazards`, **and** for a **graphics-consumer symbol shortfall** via `toolchain_safety.check_system_consumer_symbols`: it extracts the about-to-be-installed `libLLVM.so.*` from the built packages (lib32 excluded) and, for each installed external consumer that links that exact soname (mesa's `libgallium`/DRI/Vulkan drivers, curated in `_SYSTEM_LIBLLVM_CONSUMER_GLOBS`), checks every `LLVM_x.y`-versioned symbol the consumer imports is exported by the new libLLVM. An import one of the consumer's *other* `NEEDED` libraries exports (resolved through `ldconfig`) is not owed by libLLVM and is left out: libclang, libclang-cpp and liblldb version their own exports `LLVM_*` too, so doxygen's `clang_*@LLVM_13` and lldb's `lldb::SB*@LLVM_<ver>` would otherwise read as drift and queue a needless consumer rebuild (`3.5.0-B18`). Neither is any package the batch itself ships: besides the lockstep suite, the merged `llvm` pkgbase builds lldb, libclc and llvm-lit, whose installed copies the same `pacman -U` replaces, so the scan drops every pkgname read from the built archives' `.PKGINFO` (`toolchain_safety.shipped_pkgnames`, `3.5.0-B20`). `_diff_consumers_against_libllvm` splits a miss into two classes (see §`graphics-stack` → *Two stranding classes*): an **unhealable** target-init drop (`LLVMInitialize*` — a reduced `LLVM_TARGETS_TO_BUILD` dropped a backend the consumer needs, e.g. AMDGPU; the symbol exists nowhere) **aborts before any `pacman -U`** — nothing installed, no sentinel; a **healable** `std::` re-export drop (only non-target-init `LLVM_*` symbols — the `-fprofile-use` libLLVM inlined away the weak libstdc++ copies the stock build re-exported at the *same* soname) does **not** abort. For the healable case Gate 2 enumerates the installed libLLVM consumers via `toolchain_safety.libllvm_abi_consumers` (the reverse-dep `%DEPENDS%` walk shared with the soname gate, here un-gated on a soname change), applies the `rebuild_soname_consumers` mode (prompt/auto/off, mirroring the soname gate), and **returns** them for rebuild after Gate 3. This is the gate that `scan_abi_hazards` (intra-build only) never covered: it checks *already-installed* external consumers, the gap that let a target-reduced libLLVM ship. **`std::` export parity (`3.5.0-F4`).** The healable class cannot heal mesa built in the sandbox, which links the repo libLLVM again, so the llvm PKGBUILD's `prepare()` gains a block (`pkgbuild_patcher.patch_llvm_std_exports`, wired as `makepkg_wrapper._maybe_patch_llvm_std_exports` beside the target patch) that adds `primitives/llvm_std_exports.py`'s thunks to libLLVM: each libstdc++ member stock re-exported and the `-fprofile-use` build dropped is exported again as `sym@LLVM_<mm>` at a **non-default** version, forwarding to libstdc++'s own `@GLIBCXX_*` export. An already-linked consumer resolves it; no new link binds to it, so the suite built alongside keeps importing `@GLIBCXX_*` and `scan_abi_hazards` stays clean (default-version re-exports, the obvious fix, would trip it). The CMake hook configures itself out unless the build links with lld on x86-64 with a known `LLVM_SHLIB_SYMBOL_VERSION`. Gate 2 then reports, as `-v` narration, any pure-`std` export stock has that the build still lacks and the system `libstdc++.so.6` itself exports (only that extern-template set is imported rather than emitted by a consumer; stock exports other std instantiations only because GCC built it) (`toolchain_safety.check_std_export_parity`, against the signed stock `llvm-libs` of the same version in the pacman cache via `pacman.cached_repo_pkg_file`; skipped when none is cached). The TU goes in `llvm-shlib/sysforge/`, because LLVM's configure (`llvm_check_source_file_list`) rejects any unlisted `*.cpp` in a target's own directory. `build_fingerprint._SCHEMA` 4 keeps `--reuse-built` from reusing a libLLVM built without the thunks, and the rendered block's hash is a Pass-4 fingerprint input, so a later `STD_EXPORTS` edit invalidates reuse on its own.
 - **Snapshot.** Right before the install, `cached_pkg_files_for(lockstep suite ∪ built names)` (in `primitives/pacman.py`) locates each currently-installed member's `.pkg.tar*` in the pacman cache. `gates.snapshot_suite` keeps only names installed before the run: a new subpackage or lib32 member has nothing to restore, and its `None` would otherwise read as a missing archive and refuse the whole rollback (`3.5.0-B76`). This is the offline-undo source. Gate 1 warns up front when any member's archive is missing (auto-undo will fall back to `pacman -S`).
-- **Gate 3 — post-install verify, inside the sentinel** (`_verify_llvm_install`). Its `expected_targets` (for the `built ⊇ expected` `llvm-config --targets-built` check) is the **actually resolved** target set — `resolve_or_detect_llvm_targets(TOOLCHAIN_PATH, <state_dir>/hardware_profile.toml)`, the same value the build patched in — **not** just `toolchain.toml [llvm] targets`. On an autodetect host that key is unset, so the old form resolved to `None` and skipped the check entirely; sourcing the resolved set makes it actually assert (after the Part-1 baseline, that includes AMDGPU). A **post-install graphics arm** then runs `toolchain_safety.check_installed_consumer_symbols(exclude=…)` (the same symbol diff as Gate 2, but vs the *now-installed* `/usr/lib/libLLVM.so.*`, the numerically newest soname via `toolchain_safety.so_version` so a compat package's older library never stands in for it (`3.5.0-B58`), excluding the same shipped pkgnames, which the install just replaced; the other callers, `doctor` and `build_core`'s post-install backstop, exclude nothing). Only **unhealable** (target-init) findings fold into the verify issues; **healable** `std::` re-export misses are *expected* here — mesa is not rebuilt until *after* Gate 3, so folding them in would auto-rollback the very libLLVM the queued consumer rebuild is about to make coherent — and are logged, not failed. On any (unhealable) failure, the stage **auto-restores** the prior-good toolchain from the snapshot in one `pacman -U` transaction (`_rollback_to_snapshot` → `batch_install_pkgs`): if restore succeeds the live `/usr` is whole again, so the sentinel is **cleared** and a `RuntimeError` is raised telling the user to investigate; if restore fails or the snapshot was incomplete, the sentinel is **kept** with `recovery_cmd` set to the snapshot restore (offline `pacman -U <cached>`, falling back to `pacman -S <suite>`). So a target-reduced libLLVM that somehow reached install is reverted automatically while rollback is still armed, rather than surfacing as a black screen at next login.
+- **Gate 3 — post-install verify, inside the sentinel** (`_verify_llvm_install`). Its `expected_targets` (for the `built ⊇ expected` `llvm-config --targets-built` check) is the **actually resolved** target set — `resolve_or_detect_llvm_targets(TOOLCHAIN_PATH, <state_dir>/hardware_profile.toml)`, the same value the build patched in — **not** just `toolchain.toml [llvm] targets`. On an autodetect host that key is unset, so the old form resolved to `None` and skipped the check entirely; sourcing the resolved set makes it actually assert (after the Part-1 baseline, that includes AMDGPU). A **post-install graphics arm** then runs `toolchain_safety.check_installed_consumer_symbols(exclude=…)` (the same symbol diff as Gate 2, but vs the *now-installed* `/usr/lib/libLLVM.so.*`, the numerically newest soname via `toolchain_safety.so_version` so a compat package's older library never stands in for it (`3.5.0-B58`), excluding the same shipped pkgnames, which the install just replaced; the other callers, `doctor` and `build_core`'s post-install backstop, exclude nothing). Only **unhealable** (target-init) findings fold into the verify issues; **healable** `std::` re-export misses are *expected* here — mesa is not rebuilt until *after* Gate 3, so folding them in would auto-rollback the very libLLVM the queued consumer rebuild is about to make coherent — and are logged, not failed. On any (unhealable) failure, the stage **auto-restores** the prior-good toolchain from the snapshot in one `pacman -U` transaction (`rollback_to_snapshot` → `batch_install_pkgs`): if restore succeeds the live `/usr` is whole again, so the sentinel is **cleared** and a `RuntimeError` is raised telling the user to investigate; if restore fails or the snapshot was incomplete, the sentinel is **kept** with `recovery_cmd` set to the snapshot restore (offline `pacman -U <cached>`, falling back to `pacman -S <suite>`). So a target-reduced libLLVM that somehow reached install is reverted automatically while rollback is still armed, rather than surfacing as a black screen at next login.
 
-- **Consumer rebuild — after Gate 3, outside the sentinel** (`_rebuild_soname_consumers`). The rebuild set is the **union** of the pre-build soname gate's consumers (a soname *bump*, mode `prompt`-approved or `auto`) and Gate 2's healable `std::` re-export drift consumers (a same-soname ABI regression) — deduped. The now-installed-and-verified toolchain is followed by a rebuild of those consumers through the shared `build_core.build_and_install` engine (resolved via `find_pkgbuild` — auto-cloning repo packages like mesa — and the user's normal profile, so they re-link the new libLLVM: a soname-bump consumer picks up the new `NEEDED`, a std::-drift consumer re-links the dropped symbols to libstdc++ `@GLIBCXX_*`). It runs **outside** the toolchain sentinel deliberately: a consumer rebuild failure must **not** roll back the intended toolchain bump — it surfaces as an actionable `RuntimeError` naming the failed packages and the manual `sysforge build` command, with the new toolchain left healthy. The system self-stabilises — once a std::-drift consumer is rebuilt it no longer imports the `…@LLVM_<ver>` `std::` symbols, so a later `run toolchain` sees no stranding and queues no rebuild.
+- **Consumer rebuild — after Gate 3, outside the sentinel** (`rebuild_soname_consumers`). The rebuild set is the **union** of the pre-build soname gate's consumers (a soname *bump*, mode `prompt`-approved or `auto`) and Gate 2's healable `std::` re-export drift consumers (a same-soname ABI regression) — deduped. The now-installed-and-verified toolchain is followed by a rebuild of those consumers through the shared `build_core.build_and_install` engine (resolved via `find_pkgbuild` — auto-cloning repo packages like mesa — and the user's normal profile, so they re-link the new libLLVM: a soname-bump consumer picks up the new `NEEDED`, a std::-drift consumer re-links the dropped symbols to libstdc++ `@GLIBCXX_*`). It runs **outside** the toolchain sentinel deliberately: a consumer rebuild failure must **not** roll back the intended toolchain bump — it surfaces as an actionable `RuntimeError` naming the failed packages and the manual `sysforge build` command, with the new toolchain left healthy. The system self-stabilises — once a std::-drift consumer is rebuilt it no longer imports the `…@LLVM_<ver>` `std::` symbols, so a later `run toolchain` sees no stranding and queues no rebuild.
 
-The mutation window is therefore exactly install → Gate 3 → (rollback), followed by the out-of-band consumer rebuild. The concurrent-run lock (`_pgo_lock`) wraps the whole build → audit → snapshot → install window, like the kernel stage's `kernel-build.lock`. Under `--dry-run` neither the lock nor the install sentinel is taken (`contextlib.nullcontext()`), so a preview writes no `stage_in_progress.toml` and never contends with a real run (`3.5.0-B74`). Gate 3's line for a healable `std::` re-export drift promises the consumer rebuild only when one is queued; with nothing queued (`rebuild_soname_consumers = off`, or the rebuild declined) it points at `sysforge build <pkg>` (`stage.healable_drift_line`, `3.5.0-B98`). A consolidated resolution summary (`_log_toolchain_resolution_summary`) prints the compiler/pgo/variant, package counts, staging paths, gate settings, and snapshot availability — the readable core of `--dry-run`.
+The mutation window is therefore exactly install → Gate 3 → (rollback), followed by the out-of-band consumer rebuild. The concurrent-run lock (`_pgo_lock`) wraps the whole build → audit → snapshot → install window, like the kernel stage's `kernel-build.lock`. Under `--dry-run` neither the lock nor the install sentinel is taken (`contextlib.nullcontext()`), so a preview writes no `stage_in_progress.toml` and never contends with a real run (`3.5.0-B74`). Gate 3's line for a healable `std::` re-export drift promises the consumer rebuild only when one is queued; with nothing queued (`rebuild_soname_consumers = off`, or the rebuild declined) it points at `sysforge build <pkg>` (`stage.healable_drift_line`, `3.5.0-B98`). A consolidated resolution summary (`log_toolchain_resolution_summary`) prints the compiler/pgo/variant, package counts, staging paths, gate settings, and snapshot availability — the readable core of `--dry-run`.
 
 **PKGBUILD resolution:** each name is first mapped to the pkgbase the sync DB says builds it (`pacman.get_sync_pkgbase`, the sync DB's `%BASE%` via `pacman -Sddp --print-format '%n %e'`), and that pkgbase, not the package name, is what `find_pkgbuild`'s lookup order (local `pkgbuild_src_dir` → `pkgctl repo clone`) searches for (`3.5.0-B13`). A repo can move a package under another pkgbase, as upstream did when it folded clang, lld, polly, compiler-rt and openmp into `llvm`; the old per-package checkouts stay on disk with a frozen tree and would otherwise win the local lookup, then fail to pin to a release their repo never tagged. A stale checkout is reported with `warn()` and left alone. A name no repo carries (AUR, local) keeps its own name, and the split-package scan still covers members of an already-resolved PKGBUILD. After path resolution, the stage routes each unique resolved `pkgbuild_dir` through `SourceSyncScheduler.sync_many()` so missing trees are cloned and pre-existing trees are refreshed against AUR/repo upstream — same RPC short-circuit, rate-limit, and dirty-tree handling as `sysforge update`. Pass `--no-update` to skip the sync step (use whatever is on disk verbatim). Blocker statuses (`STATUS_FAILED`, `STATUS_RATE_LIMITED`, `STATUS_PURGE_REFUSED`) abort the stage; `STATUS_DIVERGED` is a warning. Resolved paths are then displayed in a table and the user is prompted to confirm or abort. On abort, the resume command is printed (`sysforge pipeline --resume --state-dir <dir>`) so they can make manual modifications and return.
 
@@ -1200,20 +1211,20 @@ The sequence is **four builds** (Pass 1, Pass 2, Pass 3, Pass 4) across three on
 
 3. **Pass 3** — training run. CC is `<staging1>/usr/bin/clang` (built in Pass 2), and the Pass-3 environment redirects dyld / cmake at stage1 via `LD_LIBRARY_PATH=<staging1>/usr/lib:…`, `CMAKE_PREFIX_PATH=<staging1>/usr:…`, `PATH=<staging1>/usr/bin:…`. The running clang and the libLLVM it loads are guaranteed coherent because they were built together — no possibility of version drift against `/usr`. Pass 3 builds pgo + non_pgo packages; the act of running stage1's clang against stage1's instrumented libLLVM generates profraw as a side effect. `LLVM_PROFILE_FILE` uses `%m_%p` (per-module-hash + per-PID) so parallel `make -j` clang processes each write their own `.profraw` file rather than contending on one; `CCACHE_DISABLE` and `SCCACHE_DISABLE` are set so neither cache tool bypasses the instrumented compiler. `linker_flags_extra` carries the same force-loaded profile-runtime LDFLAGS, and Pass 3 likewise sets `toolchain_variant="pgo_llvm"` (lld), so its non_pgo `find_package(LLVM)` builds against stage1's instrumented `.a` archives still link cleanly. A background daemon merges profraw into `clang.profdata` every 15 seconds using adaptive batch sizing (starts at 128 files; halves on OOM; minimum batch 8). No install. After the build, Pass 3 binaries are extracted to `pgo_staging` (stage2). The stage2 outputs are **non-instrumented** since Pass 3 doesn't apply `-fprofile-generate`.
 
-   **Training-corpus enrichment (`[packages] training_corpus`, opt-in).** Pass 3's profile only reflects the code clang was made to compile, and LLVM's own C++ self-build under-exercises graphics/C-heavy codegen. `training_corpus` (default `["llvm"]`; `"llvm"` is the implicit base) lists *extra* packages — currently `"mesa"` — that Pass 3 additionally compiles **with the same instrumented stage1 clang and the same `LLVM_PROFILE_FILE`**, so their profraw lands in the same `pgo_store` and merges into the one `clang.profdata`. The resolution/build seam has one home: `_resolve_training_corpus(tcfg)` returns the non-llvm extras (unknown members warned + dropped, "llvm" stripped, deduped); the call site resolves them through the same scheduler-synced `_resolve_all_pkgbuilds` path as the toolchain packages (best-effort — a resolution miss degrades to an LLVM-only corpus with a warning, never blocks the build) and threads a `corpus_map` into `_build_llvm_pgo_inner`, which runs a second `_build_pass` right after the main training build (daemon still merging). Three invariants make this safe and correct: corpus members are **never installed** and **never `-fprofile-use` targets** (the profile stays clang-keyed — applying clang's profile *to* mesa would be a category error; that is Phase-3 mesa-PGO, a separate cycle); the corpus build uses `staged_deps=True` (`--nodeps`, no `--syncdeps`) so it keeps the **no-pacman-mutation** invariant and the extras' makedepends must already be installed; and the build is **best-effort** — a failure (missing makedep, mesa configure quirk) is logged and the run proceeds with whatever LLVM-only profraw was collected, so enrichment can never brick the toolchain build. An explicit user abort at the corpus build's failure menu is *not* a best-effort failure: it raises `makepkg_invoke.BuildAborted` (a `RuntimeError` subclass), which the corpus handler re-raises to stop the run. The corpus build gets **no** `profile_runtime_ldflag()` force-load (it links stage1's *shared* instrumented libLLVM, which carries its own runtime, and meson's doubled `LDFLAGS` would whole-load the archive twice into duplicate symbols), and runs with `pgo_reuse=False` so a member's own prior `--pgo=use` profile is not re-applied. LLVM/PGO path only (a non-PGO single-pass build generates no profraw).
+   **Training-corpus enrichment (`[packages] training_corpus`, opt-in).** Pass 3's profile only reflects the code clang was made to compile, and LLVM's own C++ self-build under-exercises graphics/C-heavy codegen. `training_corpus` (default `["llvm"]`; `"llvm"` is the implicit base) lists *extra* packages — currently `"mesa"` — that Pass 3 additionally compiles **with the same instrumented stage1 clang and the same `LLVM_PROFILE_FILE`**, so their profraw lands in the same `pgo_store` and merges into the one `clang.profdata`. The resolution/build seam has one home: `resolve_training_corpus(tcfg)` returns the non-llvm extras (unknown members warned + dropped, "llvm" stripped, deduped); the call site resolves them through the same scheduler-synced `resolve_all_pkgbuilds` path as the toolchain packages (best-effort — a resolution miss degrades to an LLVM-only corpus with a warning, never blocks the build) and threads a `corpus_map` into `build_llvm_pgo_inner`, which runs a second `build_pass` right after the main training build (daemon still merging). Three invariants make this safe and correct: corpus members are **never installed** and **never `-fprofile-use` targets** (the profile stays clang-keyed — applying clang's profile *to* mesa would be a category error; that is Phase-3 mesa-PGO, a separate cycle); the corpus build uses `staged_deps=True` (`--nodeps`, no `--syncdeps`) so it keeps the **no-pacman-mutation** invariant and the extras' makedepends must already be installed; and the build is **best-effort** — a failure (missing makedep, mesa configure quirk) is logged and the run proceeds with whatever LLVM-only profraw was collected, so enrichment can never brick the toolchain build. An explicit user abort at the corpus build's failure menu is *not* a best-effort failure: it raises `makepkg_invoke.BuildAborted` (a `RuntimeError` subclass), which the corpus handler re-raises to stop the run. The corpus build gets **no** `profile_runtime_ldflag()` force-load (it links stage1's *shared* instrumented libLLVM, which carries its own runtime, and meson's doubled `LDFLAGS` would whole-load the archive twice into duplicate symbols), and runs with `pgo_reuse=False` so a member's own prior `--pgo=use` profile is not re-applied. LLVM/PGO path only (a non-PGO single-pass build generates no profraw).
 
 4. **Pass 4** — final optimized build of pgo + non_pgo (+ lib32 only if explicitly opted in; empty by default — see *lib32 is not toolchain-managed*) with `-fprofile-use=<clang.profdata>`. It is split into coherent sub-passes so the non-pgo suite links against **the exact libLLVM that ships**, not the live `/usr` one:
 
    - **4a — pgo** (`llvm`, `llvm-libs`): the optimized PGO build. CC selection is conditional on whether `<pgo_staging>/usr/bin/clang` exists: when the PGO set includes `clang` (so Pass 3 produced a staged clang), 4a uses `CC=<pgo_staging>/usr/bin/clang` and redirects dyld / cmake at stage2 (`LD_LIBRARY_PATH`/`CMAKE_PREFIX_PATH`/`PATH`) — the staged clang's NEEDED libLLVM is stage2's, so the redirect is ABI-coherent. The shipped default only PGO-builds `llvm`/`llvm-libs` (clang is `non_pgo`, lives in stage1, never stage2), so the **system-clang fallback** applies: `CC=/usr/bin/clang` with the stage2 redirect **suppressed** (pointing stock clang at stage2's `LLVM_TARGETS_TO_BUILD`-restricted libLLVM would recreate the Pass 2 version-skew failure — missing target-init symbols like `LLVMInitializeBPFTarget`).
-   - **stage3 extract** — the just-built optimized `llvm`/`llvm-libs` `.pkg.tar*` are extracted into `pgo_staging3` (via `_extract_pass2_to_staging`), so `<pgo_staging3>/usr` holds the libLLVM + headers + cmake configs that the install will ship. **Both split members must be staged**: `llvm-libs` carries `libLLVM.so*` while the `llvm` (dev) package carries `usr/lib/cmake/llvm/LLVMConfig.cmake` and the headers — without the latter, 4b's `find_package(LLVM)` finds nothing under `CMAKE_PREFIX_PATH` and silently falls back to the system `/usr` libLLVM (defeating the whole split → Gate-3 brick). Because the artifact lookup matches per-pkgname, the glob is **version-anchored** (`{name}-[0-9]*-*.pkg.tar*`, same idiom as `pacman.cached_pkg_files_for`) so the shorter `llvm` pkgname does not swallow the `llvm-libs-…` sibling artifact. As a belt-and-suspenders guard, `_assert_staging_has_llvm_cmake(pgo_staging3)` runs immediately after extraction and **aborts before install** if `LLVMConfig.cmake` is absent — converting a multi-hour build + bricked install into an immediate, actionable error.
-   - **4b — non_pgo** (`clang`, `lld`, …): steered at the just-built optimized libLLVM via **both** `CMAKE_PREFIX_PATH=<pgo_staging3>/usr` (build env) **and** a `-DLLVM_DIR="<pgo_staging3>/usr/lib/cmake/llvm"` injected into the PKGBUILD `cmake` line (`pkgbuild_patcher.patch_llvm_dir`, threaded as `cmake_llvm_dir` through `_build_pass` → `make_build_options` → `_run_build`). The env var alone proved **insufficient**: `find_package(LLVM CONFIG)` silently resolved the live `/usr` libLLVM despite `CMAKE_PREFIX_PATH` (env-var search precedence lost to the system prefix), so clang/lld linked the wrong libLLVM and bricked at Gate 3. `LLVM_DIR` is the highest-precedence config-mode override — a cmake **cache** variable, checked before any prefix search and persisted in `CMakeCache.txt` across the PKGBUILD's repeated `cmake ..` calls (so injecting after the first invocation is sufficient, mirroring `patch_llvm_targets`). Both cmake-arg injectors append the new `-D` arg at the **true end of the (possibly `\`-continued) cmake statement** (`_cmake_statement_end`), not the first newline — so `-DLLVM_TARGETS_TO_BUILD` (injected first, for `clang`/`lld`/`compiler-rt`) and `-DLLVM_DIR` compose on one command. Inserting at the first newline instead splices the second arg into the first's continuation chain and orphans an arg, which bash then runs as a command (`-DLLVM_TARGETS_TO_BUILD…: command not found`, `build()` exit 4). Both injectors also anchor on the cmake **configure** invocation via `_find_cmake_configure_anchor`, **not** a bare `^cmake\b` line match: the anchor requires a same-line argument (so a lone `cmake` element in a multi-line `makedepends=(...)` array — e.g. `spirv-llvm-translator` — is never chosen; the loose match spliced `-DLLVM_DIR` into the dependency array and makepkg rejected it, exit 12) and skips action-mode invocations (`cmake --build`/`--install`/`-E`/…) which ignore `-D` cache args. **Post-patch validation gate:** after all injectors run and before makepkg, `pkgbuild_patcher.validate_patched_pkgbuild` (called from `makepkg_wrapper._run_build`, gated to the injection path) re-parses the patched PKGBUILD and fails fast on the two corruption classes that previously surfaced only hours into a build — **G1** requires the parsed dependency/identity globals (`depends`/`makedepends`/`checkdepends`/`provides`/… via `pkgbuild_meta.parse_pkgbuild`) to be unchanged from upstream (catches a `-D` arg landing in a dep array), and **G2** requires each managed injected token (`-DLLVM_TARGETS_TO_BUILD=`/`-DLLVM_DIR=`) to ride a `cmake` command's continuation-joined logical line (catches an orphaned arg, while ignoring legitimate `-D …` *array elements* like `cmake_options=(-D FOO=ON)` since only the two managed tokens are checked). A violation raises `PkgbuildPatchError` and aborts before anything is built. **Why this matters:** the std::-symbol re-export profile flips between build modes — stock/instrumented libLLVM emits an out-of-line weak copy of e.g. `std::string::_M_assign`, which the `LLVM_X.Y { global: *; }` version script globs into the LLVM namespace (so libLLVM *exports* `_M_assign@@LLVM_X.Y`), while the `-fprofile-use` build inlines it away and imports it from libstdc++ (`@GLIBCXX_*`). If clang were built against an *exporting* libLLVM (stock `/usr`, stage1, or stage2) but the run ships the *non-exporting* PGO libLLVM, `libclang-cpp` would dangle `_ZNSt*@LLVM_X.Y` and the live clang would brick at the first symbol lookup. Building 4b against stage3 makes clang record its true ABI (`@GLIBCXX_*`), coherent with the shipped libLLVM. As in Pass 2, **only `CMAKE_PREFIX_PATH` is set in the env, never `LD_LIBRARY_PATH`** (the host clang compiles the source; it must not be forced to *load* the staged libLLVM — `-DLLVM_DIR` steers only the cmake config lookup, not the runtime loader; build-tree tools get stage3 via the same narrowed build RPATH as Pass 2). **Post-build link assertion:** immediately after 4b (still pre-install), `_assert_pass_links_shipped_libllvm` reruns `toolchain_safety.scan_abi_hazards` on the just-built `clang`/`lld` `.pkg.tar*`; a correctly-steered build yields **zero** `_ZNSt*@LLVM_*` undefined refs, so a non-empty result means the steering was *still* defeated and the stage aborts **before install** (no sentinel, no rollback), naming the offending pass — the earliest, most specific catch.
+   - **stage3 extract** — the just-built optimized `llvm`/`llvm-libs` `.pkg.tar*` are extracted into `pgo_staging3` (via `_extract_pass2_to_staging`), so `<pgo_staging3>/usr` holds the libLLVM + headers + cmake configs that the install will ship. **Both split members must be staged**: `llvm-libs` carries `libLLVM.so*` while the `llvm` (dev) package carries `usr/lib/cmake/llvm/LLVMConfig.cmake` and the headers — without the latter, 4b's `find_package(LLVM)` finds nothing under `CMAKE_PREFIX_PATH` and silently falls back to the system `/usr` libLLVM (defeating the whole split → Gate-3 brick). Because the artifact lookup matches per-pkgname, the glob is **version-anchored** (`{name}-[0-9]*-*.pkg.tar*`, same idiom as `pacman.cached_pkg_files_for`) so the shorter `llvm` pkgname does not swallow the `llvm-libs-…` sibling artifact. As a belt-and-suspenders guard, `assert_staging_has_llvm_cmake(pgo_staging3)` runs immediately after extraction and **aborts before install** if `LLVMConfig.cmake` is absent — converting a multi-hour build + bricked install into an immediate, actionable error.
+   - **4b — non_pgo** (`clang`, `lld`, …): steered at the just-built optimized libLLVM via **both** `CMAKE_PREFIX_PATH=<pgo_staging3>/usr` (build env) **and** a `-DLLVM_DIR="<pgo_staging3>/usr/lib/cmake/llvm"` injected into the PKGBUILD `cmake` line (`pkgbuild_patcher.patch_llvm_dir`, threaded as `cmake_llvm_dir` through `build_pass` → `make_build_options` → `_run_build`). The env var alone proved **insufficient**: `find_package(LLVM CONFIG)` silently resolved the live `/usr` libLLVM despite `CMAKE_PREFIX_PATH` (env-var search precedence lost to the system prefix), so clang/lld linked the wrong libLLVM and bricked at Gate 3. `LLVM_DIR` is the highest-precedence config-mode override — a cmake **cache** variable, checked before any prefix search and persisted in `CMakeCache.txt` across the PKGBUILD's repeated `cmake ..` calls (so injecting after the first invocation is sufficient, mirroring `patch_llvm_targets`). Both cmake-arg injectors append the new `-D` arg at the **true end of the (possibly `\`-continued) cmake statement** (`_cmake_statement_end`), not the first newline — so `-DLLVM_TARGETS_TO_BUILD` (injected first, for `clang`/`lld`/`compiler-rt`) and `-DLLVM_DIR` compose on one command. Inserting at the first newline instead splices the second arg into the first's continuation chain and orphans an arg, which bash then runs as a command (`-DLLVM_TARGETS_TO_BUILD…: command not found`, `build()` exit 4). Both injectors also anchor on the cmake **configure** invocation via `_find_cmake_configure_anchor`, **not** a bare `^cmake\b` line match: the anchor requires a same-line argument (so a lone `cmake` element in a multi-line `makedepends=(...)` array — e.g. `spirv-llvm-translator` — is never chosen; the loose match spliced `-DLLVM_DIR` into the dependency array and makepkg rejected it, exit 12) and skips action-mode invocations (`cmake --build`/`--install`/`-E`/…) which ignore `-D` cache args. **Post-patch validation gate:** after all injectors run and before makepkg, `pkgbuild_patcher.validate_patched_pkgbuild` (called from `makepkg_wrapper._run_build`, gated to the injection path) re-parses the patched PKGBUILD and fails fast on the two corruption classes that previously surfaced only hours into a build — **G1** requires the parsed dependency/identity globals (`depends`/`makedepends`/`checkdepends`/`provides`/… via `pkgbuild_meta.parse_pkgbuild`) to be unchanged from upstream (catches a `-D` arg landing in a dep array), and **G2** requires each managed injected token (`-DLLVM_TARGETS_TO_BUILD=`/`-DLLVM_DIR=`) to ride a `cmake` command's continuation-joined logical line (catches an orphaned arg, while ignoring legitimate `-D …` *array elements* like `cmake_options=(-D FOO=ON)` since only the two managed tokens are checked). A violation raises `PkgbuildPatchError` and aborts before anything is built. **Why this matters:** the std::-symbol re-export profile flips between build modes — stock/instrumented libLLVM emits an out-of-line weak copy of e.g. `std::string::_M_assign`, which the `LLVM_X.Y { global: *; }` version script globs into the LLVM namespace (so libLLVM *exports* `_M_assign@@LLVM_X.Y`), while the `-fprofile-use` build inlines it away and imports it from libstdc++ (`@GLIBCXX_*`). If clang were built against an *exporting* libLLVM (stock `/usr`, stage1, or stage2) but the run ships the *non-exporting* PGO libLLVM, `libclang-cpp` would dangle `_ZNSt*@LLVM_X.Y` and the live clang would brick at the first symbol lookup. Building 4b against stage3 makes clang record its true ABI (`@GLIBCXX_*`), coherent with the shipped libLLVM. As in Pass 2, **only `CMAKE_PREFIX_PATH` is set in the env, never `LD_LIBRARY_PATH`** (the host clang compiles the source; it must not be forced to *load* the staged libLLVM — `-DLLVM_DIR` steers only the cmake config lookup, not the runtime loader; build-tree tools get stage3 via the same narrowed build RPATH as Pass 2). **Post-build link assertion:** immediately after 4b (still pre-install), `assert_pass_links_shipped_libllvm` reruns `toolchain_safety.scan_abi_hazards` on the just-built `clang`/`lld` `.pkg.tar*`; a correctly-steered build yields **zero** `_ZNSt*@LLVM_*` undefined refs, so a non-empty result means the steering was *still* defeated and the stage aborts **before install** (no sentinel, no rollback), naming the offending pass — the earliest, most specific catch.
    - **4c — lib32** (only when explicitly opted in): same `CMAKE_PREFIX_PATH=<pgo_staging3>/usr` + `-DLLVM_DIR` steering and the same post-build link assertion.
 
    Across all sub-passes `LLVM_PROFILE_FILE` is cleared so any inherited Pass-3 training env can't leak, and `linker_flags_extra` is left unset (stage3's LLVM is non-instrumented — no `__llvm_profile_*` references, and no Pass 2/3 residual flag leaks into the final binaries). The install — the **only** `sudo pacman -U` against `/usr` — runs after the Gate-2 audit on the built packages. Staging prefixes (stage2 *and* stage3) are removed only **after** the post-install verify passes (see below), so a failed verify keeps the stage prefixes on disk for diagnostic inspection. Profdata is **preserved** at `<pgo_store>/clang.profdata`; a version sidecar `clang.profdata.version` (LLVM major integer, e.g. `22`) is written alongside it so `sysforge update` can check compatibility before reusing the profdata.
 
 **Merged `llvm` pkgbase (`3.5.0-F2`).** Upstream builds clang, lld, lldb, polly, compiler-rt, openmp, offload, libc++, libclc, the WASI runtimes and `llvm-bolt` from the one `llvm` PKGBUILD since 23.1.3-2 (one CMake tree with `LLVM_ENABLE_PROJECTS` + `LLVM_ENABLE_RUNTIMES`). After resolution (which maps each name to its sync-DB pkgbase, `3.5.0-B13`) those names point at the same PKGBUILD as `llvm`, and `pkgbuilds.partition_by_pkgbuild` moves every name a pgo PKGBUILD builds into the pgo map before the passes are planned. The four passes then need no layout switch: Pass 1 instruments the whole tree, clang included, so stage1 has its own clang and `libclang-cpp` is profiled for the first time; Pass 2 and 4b keep only the separate pkgbases (`spirv-llvm-translator`, now also an llvm makedepend); Pass 3 trains with stage1's clang; Pass 4a optimizes the whole tree once. Left in `non_pgo`, the merged names would send the full llvm tree through Pass 2 and 4b again. With the old per-package PKGBUILDs nothing shares a file and nothing moves. **What gets installed.** `makepkg --packagelist` now yields 18 packages; the install step takes `pkgbuilds.install_names` (the configured names plus every *installed* member of the built PKGBUILDs, e.g. lldb and libclc) and `profdata.select_install_members` closes that set over `depend` edges between the built members (clang → `clang-libs=<ver>`), so no member is left on the old version against the new libLLVM and none is newly pulled in. The rollback snapshot (`gates.snapshot_suite(extra_names=…)`) covers the same set. Not yet done: trimming lldb, libc++, the offload device runtimes, libclc and WASI out of the instrumented and training passes, which would shorten them.
 
-**Pre-install ABI hazard check (Gate 2).** Between the Pass-4 build and the final `sudo pacman -U`, `_gate2_audit` extracts each built `.pkg.tar*`'s shared libraries and scans their `nm -D` output via `toolchain_safety.scan_abi_hazards` (which uses `abi_check._undefined_versioned`). Any UND versioned symbol whose mangled name is in the C++ stdlib namespace (`_ZNSt*`) and whose version starts with `LLVM_` is a hard block: it means a built binary (typically `libclang-cpp.so`) recorded a `std::string` (or similar) requirement against the `LLVM_X.Y` version namespace — i.e. clang was linked against a libLLVM that *re-exports* the C++ stdlib while the run ships one that does not. Installing those binaries would leave the live toolchain unable to resolve `std::string` methods at runtime (`symbol lookup error: libclang-cpp.so: undefined symbol _ZNSt..., version LLVM_22.1`). The Pass-4 coherent sub-pass split (4b builds the non-pgo suite against the shipped libLLVM in stage3) is the **primary** prevention; the 4b/4c post-build link assertion (above) is the earliest catch; Gate 2 is the final **backstop** that refuses to install if a hazard slips through anyway. Gate 2 runs *outside* the sentinel, so a hazard aborts with the live `/usr` intact and **no sentinel**; the user is told to restart with `--rebuild-profdata`. (This scan moved out of `_pgo_install` — which now only installs — and is shared with the non-PGO path.) Gate 2 (and the 4b/4c assertion) depend on `abi_check._extract_sos` actually extracting: it now `mkdir`s its destination before `bsdtar -x -C` (`scan_abi_hazards` extracts each package into a per-package subdir to avoid same-named `.so` collisions, and that subdir does not pre-exist — without the `mkdir`, `bsdtar` failed with *"could not chdir to …"*, the audit saw zero shared objects, and the gate passed **vacuously**, which is exactly how the brick reached install).
+**Pre-install ABI hazard check (Gate 2).** Between the Pass-4 build and the final `sudo pacman -U`, `gate2_audit` extracts each built `.pkg.tar*`'s shared libraries and scans their `nm -D` output via `toolchain_safety.scan_abi_hazards` (which uses `abi_check._undefined_versioned`). Any UND versioned symbol whose mangled name is in the C++ stdlib namespace (`_ZNSt*`) and whose version starts with `LLVM_` is a hard block: it means a built binary (typically `libclang-cpp.so`) recorded a `std::string` (or similar) requirement against the `LLVM_X.Y` version namespace — i.e. clang was linked against a libLLVM that *re-exports* the C++ stdlib while the run ships one that does not. Installing those binaries would leave the live toolchain unable to resolve `std::string` methods at runtime (`symbol lookup error: libclang-cpp.so: undefined symbol _ZNSt..., version LLVM_22.1`). The Pass-4 coherent sub-pass split (4b builds the non-pgo suite against the shipped libLLVM in stage3) is the **primary** prevention; the 4b/4c post-build link assertion (above) is the earliest catch; Gate 2 is the final **backstop** that refuses to install if a hazard slips through anyway. Gate 2 runs *outside* the sentinel, so a hazard aborts with the live `/usr` intact and **no sentinel**; the user is told to restart with `--rebuild-profdata`. (This scan moved out of `pgo_install` — which now only installs — and is shared with the non-PGO path.) Gate 2 (and the 4b/4c assertion) depend on `abi_check._extract_sos` actually extracting: it now `mkdir`s its destination before `bsdtar -x -C` (`scan_abi_hazards` extracts each package into a per-package subdir to avoid same-named `.so` collisions, and that subdir does not pre-exist — without the `mkdir`, `bsdtar` failed with *"could not chdir to …"*, the audit saw zero shared objects, and the gate passed **vacuously**, which is exactly how the brick reached install).
 
 **ABI-safety invariant (Path B).** The live `/usr` is observably coherent before and after every step except the single final `pacman -U`, and even that is now reversible: Gate 3 verifies the result and auto-rolls-back to the snapshot on failure. A run that aborts before install (build failure, Gate 1, or Gate 2) leaves the system exactly as `sysforge run toolchain` found it — nothing installed, no sentinel. A run whose install verifies-bad restores the prior-good suite from the pacman cache. No half-installed instrumented `libLLVM.so`, no orphaned `/usr/bin/clang` that can't resolve `LLVMInitializeBPFTarget@LLVM_22.1`. The only role `/usr/bin/clang` plays in the run is **as a bootstrap host compiler in Pass 2** (compiling source into objects, never loading a different-version libLLVM); version drift between the in-tree LLVM source and the installed system packages is therefore no longer a failure mode.
 
@@ -1225,23 +1236,23 @@ The sequence is **four builds** (Pass 1, Pass 2, Pass 3, Pass 4) across three on
 
 **BOLT inside the llvm build (opt-in, EXPERIMENTAL, `3.5.0-F3`).** With `toolchain.toml [bolt] enabled = true`, BOLT (Binary Optimization and Layout Tool) is layered on the PGO toolchain, the canonical **PGO→BOLT "fast clang"** stack. It is the fourth method on the shared profile-store rails and the only **post-link** one, so it has no compiler flag: the facts and subprocess seams live in `primitives/bolt.py`, the orchestration in `toolchain/bolt.py::optimize_in_build`. Where it runs follows from four facts a spike against `extra/llvm-bolt` 23.1.3-3 established. (1) **The targets are the shared libraries.** With `LLVM_LINK_LLVM_DYLIB=ON` the `clang` executable is a ~100 KB driver; the code is in `libclang-cpp.so` (always rewritten) and `libLLVM.so` (only with `[bolt] libllvm`, since every libLLVM consumer on the system loads it). (2) **It runs inside the build.** BOLT refuses stripped input and instrumentation needs relocations, but makepkg strips while packaging, and only the copies in `$pkgdir`: right after Pass 4a the **build tree** (`bolt.build_tree_for`: `<BUILDDIR>/<pkgbase>/src/llvm-project-*/build`, under the root Pass 4a reported building in, which `build_pass(build_roots=…)` collects from `makepkg_wrapper.run` so a profile's `BUILDDIR` wins over the system `makepkg.conf`'s; `--cleanbuild` clears `src` *before* a build, so the tree is 4a's) still holds unstripped libraries linked with `-Wl,--emit-relocs` (threaded as `linker_flags_extra` into 4a and 4b). sysforge rewrites them there and then reruns only `package()` (`makepkg --repackage --force`, with 4a's settings and source sync off, since a re-pinned tree would not be the one just rewritten). Each replacement keeps the original mtime (`bolt.replace_keep_mtime`): ninja records output mtimes in `.ninja_log`, so a changed one makes `package()`'s `ninja install-…` relink the library and silently restore the un-BOLTed file. This needs upstream's merged `llvm` pkgbase (`3.5.0-F2`), which builds clang and `bolt` in the same tree as llvm. (3) **It profiles by instrumentation.** `perf record -j any` needs branch-stack sampling, which the tested Zen 3 hardware lacks; `llvm-bolt -instrument` is hardware-independent. The instrumented libraries are trained by replaying up to `TRAINING_UNITS` of the tree's own compile commands (`bolt.training_commands`: `ninja -t commands <libclang-cpp target>`, clang's front-end sources first, compiler swapped for the tree's new `clang++`, outputs and dependency files kept out of the tree) under `LD_LIBRARY_PATH`, or by compiling `[bolt] training_workload` when set; fewer than half succeeding means the instrumented libraries are broken and the profile is not used. (4) **It uses the in-tree tools, checking the runtime first.** `llvm-bolt`, `merge-fdata` and `libbolt_rt_instr.a` come from the same build tree. A runtime built by GCC with `-fno-plt` (Arch's packaged one) calls `memset` through the GOT, which BOLT's JITLink rejects for every input ("unsupported edge kind RequestGOTAndTransformToPCRel32GOTLoadRelaxable"); `bolt.runtime_linkable` checks for `GOTPCRELX` relocations up front. The flags are LLVM 23's spellings (`-reorder-functions=cdsort`, `-icf=all`; `hfsort+` and numeric `-icf` are deprecated). **Kept originals and `--bolt-only`.** Before replacing a library, `optimize_in_build` keeps the un-BOLTed copy in `lib/.sysforge-prebolt/` (mtime intact) and restores it before every cycle, so a rerun on the same tree starts from it; a library carrying BOLT's `.note.bolt_info` with no kept original is refused (`bolt.is_bolted`), since rewriting BOLT output is unsupported. A Pass-4a rebuild clears `src`, so a kept original never outlives its tree. `run toolchain --bolt-only` (`pgo.bolt_only`, branched in `stage.py` in place of `build_llvm_pgo_inner`) builds nothing: `toolchain/bolt.check_bolt_only_tree` refuses unless llvm's `build_state` record says `pgo_llvm` at the PKGBUILD's version, `libclang-cpp` carries relocations (only Pass 4 links `--emit-relocs`, so an earlier pass's tree has none), and llvm's PKGDEST artifacts are no older than it; the tree is found under the `BUILDDIR` that record's `flags_string` holds (`build_state.recorded_builddir`). It then BOLTs with `[bolt] enabled` forced on and `strict=True` (every skip raises, since reinstalling unchanged packages achieves nothing), repackages llvm through the same `_repackage_llvm` as 4a, and returns the whole suite so Gate 2, the install and Gate 3 run unchanged on the packages the last run built. The pre-install confirmation asks about BOLT and install rather than a build, the resolution summary names the mode and drops the build-only staging rows, and Gate 1 skips the `min_build_free_gb` headroom check (a repackage needs a fraction of it; the lockstep, compiler and multilib checks still run). The flag implies `--no-update` (a sync could re-pin the PKGBUILD off the tree's version) and the verb's `pre_check` refuses it with `--rebuild-profdata`, `--reuse-built` or `--cleansrc[-force]`. Its record check (llvm's `build_state` says `pgo_llvm` at the PKGBUILD's version) is `pkgbuilds.check_last_pgo_build`, shared with `--install-only`. Passes 1 to 3 build as `pgo_llvm` too (its lld guard and overlays), so they pass `record_variant=constants.INTERMEDIATE_VARIANT` through `build_pass`/`build_pkg` to `BuildOptions.record_toolchain_variant`, which replaces only the variant `_record_build_state` writes: a run that stops before Pass 4 leaves `pgo_llvm_intermediate`, which the check refuses as instrumented or a bootstrap, and Pass 4 overwrites it with `pgo_llvm` (`3.5.0-B39`). The training-corpus extras keep recording `pgo_llvm`, so the user's mesa record is not made to read as drifted. **`run toolchain --install-only` (`pgo.install_only`).** The recovery for a run that built (and BOLTed) the suite but did not install it, such as an install sudo prompt nobody answered: after that same record check, every PKGBUILD of the suite must have a built package at its version in PKGDEST (`profdata.collect_pgo_packages`, the `makepkg --packagelist` lookup the install itself uses), and the whole suite is returned so Gate 2, the snapshot, the install and Gate 3 run as after a build. It shares `--bolt-only`'s handling: `gates.no_build_mode` names the mode for the plan header, the confirmation and Gate 1's skipped headroom check; the stage refuses it outside the PGO LLVM configuration; it implies `--no-update`; and `pre_check` refuses it with the build flags or `--bolt-only`. A failed PGO install (`pacman -U` non-zero, sentinel kept) and the pre-sentinel sudo refusal both name it as the retry, as does the sentinel's `retry_cmd`. **Failure handling.** Any failure up to and including the smoke test (a compile with the rewritten libraries) warns and leaves the build tree and the 4a packages exactly as built, so the PGO toolchain installs un-BOLTed. A failed repackage restores the tree and stops the stage *before* install, since the 4a packages may be half-rewritten by then. Merged profiles are kept in the `bolt` store. The rewritten libraries ship under their stock names in the normal install, covered by Gate 2/3 and the snapshot rollback like the rest of the suite; `pacman -Qkk` sees nothing modified, since the rewrite happens before packaging. **Not yet verified on a full build:** the sequence is covered by unit tests and by spikes of each step on small libraries (instrumentation of a PIC C++ shared library with exceptions, TLS and a forked child; ninja's mtime behaviour), not by an end-to-end `run toolchain`; it stays `enabled = false` by default. LLVM/PGO path only.
 
-**Dep resolution for staged passes.** Pass 1 (and the non-PGO single pass) build against the live `/usr`. Their missing repo build tools (cmake, ninja, python, z3, libffi, …) are installed by sysforge before the pass, through `build_core.install_missing_repo_deps` (the same repo arm `prepare_deps` uses, excluding the pass's own packages so the stock copy of what is being built is never installed). makepkg itself runs with `--syncdeps` always stripped, so it never escalates inside the build's forwarded output (`3.4.0-F1`); a password prompt is sysforge's own, with the progress bar yielded. Pass 2, Pass 3, and Pass 4 build against a stage prefix; `CMAKE_PREFIX_PATH=<staging>/usr` makes `find_package(LLVM)` see the staged headers and cmake configs, but pacman has no knowledge of those staged packages. `_build_pass(staged_deps=True)` therefore strips `--syncdeps`/`-s` (via the shared `SYNC_FLAGS` constant from `makepkg_wrapper.py`, the same set `pacman.BATCH_STRIP_FLAGS` removes for batch builds) from the resolved profile's makepkg flags and appends `--nodeps` for those three passes. Without that, makepkg's pre-build dep check would invoke `sudo pacman -S llvm=<pkgver>` and fail with "target not found" (the just-built version is not in any repo). The non-llvm build deps stay required, so `build_llvm_pgo_inner` installs them once before any pass, for every PKGBUILD of the run (pgo, non-pgo and lib32) with the whole suite excluded (`3.5.0-B15`). Pass 1's own pre-install covers only the pgo PKGBUILD, and a profdata-reuse run skips Pass 1 entirely: before this, the merged `llvm` PKGBUILD's new makedepends (`wasi-libc`) were never installed on that path, and 4a died in the wasm32 libc++ build with an unresolved `::mbstate_t`. `build_pass(install=True)` (no current caller: every pass builds without installing, and the toolchain installs as one batch inside the sentinel) likewise never passes `--install` to makepkg; it installs through `makepkg_wrapper.install_built_packages` after the build.
+**Dep resolution for staged passes.** Pass 1 (and the non-PGO single pass) build against the live `/usr`. Their missing repo build tools (cmake, ninja, python, z3, libffi, …) are installed by sysforge before the pass, through `build_core.install_missing_repo_deps` (the same repo arm `prepare_deps` uses, excluding the pass's own packages so the stock copy of what is being built is never installed). makepkg itself runs with `--syncdeps` always stripped, so it never escalates inside the build's forwarded output (`3.4.0-F1`); a password prompt is sysforge's own, with the progress bar yielded. Pass 2, Pass 3, and Pass 4 build against a stage prefix; `CMAKE_PREFIX_PATH=<staging>/usr` makes `find_package(LLVM)` see the staged headers and cmake configs, but pacman has no knowledge of those staged packages. `build_pass(staged_deps=True)` therefore strips `--syncdeps`/`-s` (via the shared `SYNC_FLAGS` constant from `makepkg_wrapper.py`, the same set `pacman.BATCH_STRIP_FLAGS` removes for batch builds) from the resolved profile's makepkg flags and appends `--nodeps` for those three passes. Without that, makepkg's pre-build dep check would invoke `sudo pacman -S llvm=<pkgver>` and fail with "target not found" (the just-built version is not in any repo). The non-llvm build deps stay required, so `build_llvm_pgo_inner` installs them once before any pass, for every PKGBUILD of the run (pgo, non-pgo and lib32) with the whole suite excluded (`3.5.0-B15`). Pass 1's own pre-install covers only the pgo PKGBUILD, and a profdata-reuse run skips Pass 1 entirely: before this, the merged `llvm` PKGBUILD's new makedepends (`wasi-libc`) were never installed on that path, and 4a died in the wasm32 libc++ build with an unresolved `::mbstate_t`. `build_pass(install=True)` (no current caller: every pass builds without installing, and the toolchain installs as one batch inside the sentinel) likewise never passes `--install` to makepkg; it installs through `makepkg_wrapper.install_built_packages` after the build.
 
 **Staging-prefix ownership (`3.5.0-B54`).** The three prefixes are fixed names in world-writable `/var/tmp`, and their contents run later in the build (`stage_env` puts them first on `PATH`/`LD_LIBRARY_PATH`/`CMAKE_PREFIX_PATH`, and Pass 4a uses stage2's clang as `CC`). Another local user who created a name first, or planted a symlink, would have their files run. So extraction creates a prefix 0700 through `fs_provision.ensure_private_dir`, and `fs_provision.check_private_dir` refuses a symlink, a non-directory, a directory another uid owns, or one others can write to, at extraction, in `stage_env` and before the staged clang becomes `CC`. The fresh-build purge checks owner and symlink only (`check_mode=False`): it deletes the contents, so their mode cannot matter. `/var/tmp`'s sticky bit keeps anyone else from replacing a directory this user owns, so ownership plus mode is sufficient.
 
-**Concurrent-run lock.** `ToolchainStage.run` acquires an advisory `flock(2)` (`_pgo_lock`, the shared `build_lock` primitive) on `_pgo_lock_path(staging1)` = `<pgo_staging1>.parent/sysforge-pgo.lock` (typically `/var/tmp/sysforge-pgo.lock`) around the whole build → audit → snapshot → install window — not just the PGO passes, so the non-PGO path is guarded too (mirroring the kernel stage's `kernel-build.lock`). The sentinel scope guards re-entry on the state-dir but not the `/var/tmp` staging dirs or `~/pgo`, both of which two concurrent runs would corrupt. The lock file holds the owner's PID, so the loser surfaces "another sysforge PGO build is running (pid N)" rather than a confusing mid-flow failure. The path is in `staging1.parent` rather than inside `pgo_store` so the Pass-1 purge cannot delete it. Skipped in `--dry-run` (the lock file would be a side effect) — so a dry run, unlocked, must never mutate the shared prefixes either: `profdata.remove_staging(staging, dry_run)` takes `dry_run` as a required argument and only logs on a dry run. The Pass-4 stage3 clear was the one unguarded deletion; a concurrent dry run (the stage test suite included) removed stage3 under a real run's Pass 4b clang, which then compiled against `/usr/include`'s older LLVM headers (`3.3.0-B9`). The path's one home is `primitives/makepkg_pgo.py` (`pgo_lock_path`, `resolve_pgo_lock_path`, and `DEFAULT_PGO_STAGING_1`, which `constants.DEFAULT_STAGING_1` re-exports) because `makepkg_wrapper.run` probes the same lock to leave a running PGO build's `pgo_store` alone (`3.3.0-B8`, §Stale-profraw post-build check), and `primitives/` cannot import from `pipeline/`.
+**Concurrent-run lock.** `ToolchainStage.run` acquires an advisory `flock(2)` (`_pgo_lock`, the shared `build_lock` primitive) on `pgo_lock_path(staging1)` = `<pgo_staging1>.parent/sysforge-pgo.lock` (typically `/var/tmp/sysforge-pgo.lock`) around the whole build → audit → snapshot → install window — not just the PGO passes, so the non-PGO path is guarded too (mirroring the kernel stage's `kernel-build.lock`). The sentinel scope guards re-entry on the state-dir but not the `/var/tmp` staging dirs or `~/pgo`, both of which two concurrent runs would corrupt. The lock file holds the owner's PID, so the loser surfaces "another sysforge PGO build is running (pid N)" rather than a confusing mid-flow failure. The path is in `staging1.parent` rather than inside `pgo_store` so the Pass-1 purge cannot delete it. Skipped in `--dry-run` (the lock file would be a side effect) — so a dry run, unlocked, must never mutate the shared prefixes either: `profdata.remove_staging(staging, dry_run)` takes `dry_run` as a required argument and only logs on a dry run. The Pass-4 stage3 clear was the one unguarded deletion; a concurrent dry run (the stage test suite included) removed stage3 under a real run's Pass 4b clang, which then compiled against `/usr/include`'s older LLVM headers (`3.3.0-B9`). The path's one home is `primitives/makepkg_pgo.py` (`pgo_lock_path`, `resolve_pgo_lock_path`, and `DEFAULT_PGO_STAGING_1`, which `constants.DEFAULT_STAGING_1` re-exports) because `makepkg_wrapper.run` probes the same lock to leave a running PGO build's `pgo_store` alone (`3.3.0-B8`, §Stale-profraw post-build check), and `primitives/` cannot import from `pipeline/`.
 
 **Post-install libLLVM resolution check.** `_verify_llvm_install` runs `ldd /usr/bin/clang` and `ldd /usr/bin/lld` and asserts that any `libLLVM*.so` lines resolve under `/usr/lib`. A `/var/tmp/sysforge-llvm-stage*` path appearing in `ldd` of an installed binary means Pass 4 packaged a bad RPATH or the install is incomplete — `/usr` looks consistent until `/var/tmp` gets cleaned, at which point the live toolchain silently breaks. The verify-stage check catches that before the sentinel clears.
 
-**Verify-failure diagnostic dump.** On a `_verify_llvm_install` failure, `ToolchainStage.run` calls `_dump_stage_dynsym_evidence(staging3, state_dir)` before the recovery prompt. The brick is a C++ stdlib symbol bound to libLLVM's `LLVM_<ver>` version node, so the actionable evidence is the **set difference** between what the *installed* consumers (`libclang-cpp` / `liblldCommon`) demand under `@LLVM_*` and what the *installed* `libLLVM` provides — read straight from the live `/usr` files that bricked. The dump lists those missing symbols (the brick cause) and, when the kept `stage3` libLLVM *does* export them, notes that the shipped libLLVM diverged from what Pass 4b linked against — pointing directly at an incomplete/incoherent stage3. It is written to `<state_dir>/llvm_abi_hazard.log`. (This replaced an earlier dump of `stage2`'s `libLLVM` defined exports, which on the profdata-reuse fast path captured a stale/empty prefix that never contained the brick symbols.) The installed libLLVM is selected to **match the soname the consumers actually link** (`_newest_so` keyed on the consumer's `lib*.so.<major>.<minor>` version), not a lexical-first glob — otherwise a compat package's older runtime (e.g. `llvm21-libs`'s `libLLVM.so.21.1` sitting beside `llvm-libs`'s `libLLVM.so.22.1`) is picked, its `@LLVM_21.1` exports satisfy nothing the `@LLVM_22.1` consumers demand, and the diff reports a false *"0 NOT provided"* all-clear that hides the brick. Staging removal is deferred until verify passes, so the `stage3` prefix survives the failure path for this contrast. The log path is surfaced in the WARN block alongside the suggested recovery command.
+**Verify-failure diagnostic dump.** On a `_verify_llvm_install` failure, `ToolchainStage.run` calls `dump_stage_dynsym_evidence(staging3, state_dir)` before the recovery prompt. The brick is a C++ stdlib symbol bound to libLLVM's `LLVM_<ver>` version node, so the actionable evidence is the **set difference** between what the *installed* consumers (`libclang-cpp` / `liblldCommon`) demand under `@LLVM_*` and what the *installed* `libLLVM` provides — read straight from the live `/usr` files that bricked. The dump lists those missing symbols (the brick cause) and, when the kept `stage3` libLLVM *does* export them, notes that the shipped libLLVM diverged from what Pass 4b linked against — pointing directly at an incomplete/incoherent stage3. It is written to `<state_dir>/llvm_abi_hazard.log`. (This replaced an earlier dump of `stage2`'s `libLLVM` defined exports, which on the profdata-reuse fast path captured a stale/empty prefix that never contained the brick symbols.) The installed libLLVM is selected to **match the soname the consumers actually link** (`_newest_so` keyed on the consumer's `lib*.so.<major>.<minor>` version), not a lexical-first glob — otherwise a compat package's older runtime (e.g. `llvm21-libs`'s `libLLVM.so.21.1` sitting beside `llvm-libs`'s `libLLVM.so.22.1`) is picked, its `@LLVM_21.1` exports satisfy nothing the `@LLVM_22.1` consumers demand, and the diff reports a false *"0 NOT provided"* all-clear that hides the brick. Staging removal is deferred until verify passes, so the `stage3` prefix survives the failure path for this contrast. The log path is surfaced in the WARN block alongside the suggested recovery command.
 
 **Profdata reuse:** before purging `pgo_store`, the stage checks for an existing `clang.profdata` + version sidecar. The sidecar's LLVM major version is compared against the `pkgver` in the pgo PKGBUILDs (not the installed version — the toolchain stage builds a *new* version). If compatible (same major), passes 1–3 are skipped entirely and only the optimized build (Pass 4) runs, using system clang as CC (which, after a prior successful run, is already PGO-optimized). Stage1/stage2 are not needed in this path, but **stage3 still is**: Pass 4 stages the freshly-built optimized libLLVM there and builds the non-pgo suite (4b) against it for ABI coherence — exactly as on the full path. `--rebuild-profdata` forces a full 4-pass build regardless, e.g. after upstream codegen changes within the same major version.
 
-**Pass-4 input-fingerprint reuse (opt-in).** Profdata reuse skips the *training* (passes 1–3) but still rebuilds every Pass-4 package. When a *late* Pass-4 package fails (e.g. `spirv-llvm-translator` in 4b), a rerun would needlessly re-optimise the identical `llvm`/`llvm-libs` (4a, the heaviest target) and other unchanged packages. The opt-in input-fingerprint cache (`primitives/build_fingerprint.py`, CLI `--reuse-built` > `toolchain.toml reuse_unchanged` > off) skips a Pass-4 package whose **inputs are unchanged and whose built artifact is still on disk**. The fingerprint folds everything that determines the output: the upstream PKGBUILD content hash, the source-tree git HEAD, the compiler `--version` line (`compiler_version_line` — **not** the full `clang_identity` path+size+mtime: Pass 4 runs with the staged stage-2 clang on a profgen run but `/usr/bin/clang` on a resume, so keying on the binary's path/bytes would guarantee a miss on the exact rerun-after-failure case reuse exists for; the actual trained codegen is already pinned by the profdata hash below, and a genuine version bump still invalidates — 2.1.0-B14), the injected/profile flags (`compiler_flags_extra`/`linker_flags_extra`/`cmake_llvm_dir`/`extra_flags`), a `config_digest` (`hash_obj` of the flag-relevant config — `profiles`/`rules` + `toolchain.toml`, the latter because `[llvm] targets` drives the `LLVM_TARGETS_TO_BUILD` patch the upstream-PKGBUILD hash can't see), the `clang.profdata` content hash (hashed once per run), and the installed versions of the **external** build-deps only. The toolchain build-set members (`llvm`, `llvm-libs`, `clang`, …) are **excluded** from that dep-version fold: Pass 4 satisfies them from the staging prefix (`--nodeps`), so their live-`/usr` version is not a build input, and the staged libLLVM they actually link is already pinned via `staged_dep_fps`. Folding it in would spuriously invalidate every Pass-4 fingerprint the instant the suite is self-installed — defeating cache reuse on a post-install sanity re-run, since e.g. `clang`'s `depends=('llvm-libs')` would flip the moment the freshly-built `llvm-libs` is installed (`_dep_versions_from_globals(exclude=…)`, 2.5.1-B2). Sub-passes are **Merkle-chained**: 4b/4c fold in 4a's current fingerprints (`staged_dep_fps`), so if a rebuilt libLLVM's fingerprint shifts, every consumer's does too and they rebuild — no stale libLLVM can ride through a cache hit. The cache is keyed by `(pass_id, pkgbase)` and stored at `<pgo_store>.parent/build-cache/build_cache.json` (`_reuse_cache_path`) — a **sibling** of `pgo_store`, deliberately outside it so a fresh 4-pass start's `empty_dir_contents(pgo_store)` purge cannot wipe a prior run's records before the resume consults them (each entry binds its own `profdata_sha`, so a surviving-but-stale entry from a different profdata fail-safe-misses rather than mis-hitting — 2.1.0-B14). It is **always written** (so a first, non-opted-in run populates it) but only **consulted** when opted in. The whole mechanism is fail-safe — a missing/changed artifact (size or nanosecond mtime), a fingerprint mismatch, a config edit, a schema bump, dry-run, or the GCC register-only path all force a normal rebuild; it never reuses a stale build. `--rebuild-profdata` (full 4-pass + `pgo_store` purge) also bypasses it. The logic lives in `_build_pass` (per-package skip/record, returning `{pkgbase: fingerprint}` for the chain) with the cache primitives in `build_fingerprint`; do not add a second cache or skip path.
+**Pass-4 input-fingerprint reuse (opt-in).** Profdata reuse skips the *training* (passes 1–3) but still rebuilds every Pass-4 package. When a *late* Pass-4 package fails (e.g. `spirv-llvm-translator` in 4b), a rerun would needlessly re-optimise the identical `llvm`/`llvm-libs` (4a, the heaviest target) and other unchanged packages. The opt-in input-fingerprint cache (`primitives/build_fingerprint.py`, CLI `--reuse-built` > `toolchain.toml reuse_unchanged` > off) skips a Pass-4 package whose **inputs are unchanged and whose built artifact is still on disk**. The fingerprint folds everything that determines the output: the upstream PKGBUILD content hash, the source-tree git HEAD, the compiler `--version` line (`compiler_version_line` — **not** the full `clang_identity` path+size+mtime: Pass 4 runs with the staged stage-2 clang on a profgen run but `/usr/bin/clang` on a resume, so keying on the binary's path/bytes would guarantee a miss on the exact rerun-after-failure case reuse exists for; the actual trained codegen is already pinned by the profdata hash below, and a genuine version bump still invalidates — 2.1.0-B14), the injected/profile flags (`compiler_flags_extra`/`linker_flags_extra`/`cmake_llvm_dir`/`extra_flags`), a `config_digest` (`hash_obj` of the flag-relevant config — `profiles`/`rules` + `toolchain.toml`, the latter because `[llvm] targets` drives the `LLVM_TARGETS_TO_BUILD` patch the upstream-PKGBUILD hash can't see), the `clang.profdata` content hash (hashed once per run), and the installed versions of the **external** build-deps only. The toolchain build-set members (`llvm`, `llvm-libs`, `clang`, …) are **excluded** from that dep-version fold: Pass 4 satisfies them from the staging prefix (`--nodeps`), so their live-`/usr` version is not a build input, and the staged libLLVM they actually link is already pinned via `staged_dep_fps`. Folding it in would spuriously invalidate every Pass-4 fingerprint the instant the suite is self-installed — defeating cache reuse on a post-install sanity re-run, since e.g. `clang`'s `depends=('llvm-libs')` would flip the moment the freshly-built `llvm-libs` is installed (`_dep_versions_from_globals(exclude=…)`, 2.5.1-B2). Sub-passes are **Merkle-chained**: 4b/4c fold in 4a's current fingerprints (`staged_dep_fps`), so if a rebuilt libLLVM's fingerprint shifts, every consumer's does too and they rebuild — no stale libLLVM can ride through a cache hit. The cache is keyed by `(pass_id, pkgbase)` and stored at `<pgo_store>.parent/build-cache/build_cache.json` (`reuse_cache_path`) — a **sibling** of `pgo_store`, deliberately outside it so a fresh 4-pass start's `empty_dir_contents(pgo_store)` purge cannot wipe a prior run's records before the resume consults them (each entry binds its own `profdata_sha`, so a surviving-but-stale entry from a different profdata fail-safe-misses rather than mis-hitting — 2.1.0-B14). It is **always written** (so a first, non-opted-in run populates it) but only **consulted** when opted in. The whole mechanism is fail-safe — a missing/changed artifact (size or nanosecond mtime), a fingerprint mismatch, a config edit, a schema bump, dry-run, or the GCC register-only path all force a normal rebuild; it never reuses a stale build. `--rebuild-profdata` (full 4-pass + `pgo_store` purge) also bypasses it. The logic lives in `build_pass` (per-package skip/record, returning `{pkgbase: fingerprint}` for the chain) with the cache primitives in `build_fingerprint`; do not add a second cache or skip path.
 
-**Sidecar write timing.** The version sidecar is written **right after Pass 3 completes** (after the final profraw merge produces `clang.profdata`, before Pass 4 starts) — not after a successful Pass 4 install. The sidecar's only invariant is "this profdata is for LLVM major N", which is determined entirely by what Pass 3 instrumented; Pass 4 success has no bearing on it. Writing it post-Pass-3 means a Pass-4 failure (e.g. a transient toolchain bug, an aborted run) still leaves recoverable profdata that the next invocation can reuse via `_check_existing_profdata` rather than being forced into a full 4-pass rebuild. The major itself is derived from the in-tree PGO PKGBUILD `pkgver` (`_pgo_target_major`), matching the value `_check_existing_profdata` will later compare against — symmetric with the reuse check, and correct across major bumps where `pacman -Q llvm` would report a stale value.
+**Sidecar write timing.** The version sidecar is written **right after Pass 3 completes** (after the final profraw merge produces `clang.profdata`, before Pass 4 starts) — not after a successful Pass 4 install. The sidecar's only invariant is "this profdata is for LLVM major N", which is determined entirely by what Pass 3 instrumented; Pass 4 success has no bearing on it. Writing it post-Pass-3 means a Pass-4 failure (e.g. a transient toolchain bug, an aborted run) still leaves recoverable profdata that the next invocation can reuse via `check_existing_profdata` rather than being forced into a full 4-pass rebuild. The major itself is derived from the in-tree PGO PKGBUILD `pkgver` (`pgo_target_major`), matching the value `check_existing_profdata` will later compare against — symmetric with the reuse check, and correct across major bumps where `pacman -Q llvm` would report a stale value.
 
-**Confirmation gating (PGO).** Unlike the rest of sysforge (which is automation-focused), the LLVM PGO sub-flow is fragile enough that wrong profdata silently mis-optimises the resulting compiler. Four decision points in `_build_llvm_pgo` therefore prompt the user before destructive or long-running work, all sharing a single `_pgo_confirm` helper:
+**Confirmation gating (PGO).** Unlike the rest of sysforge (which is automation-focused), the LLVM PGO sub-flow is fragile enough that wrong profdata silently mis-optimises the resulting compiler. Four decision points in `build_llvm_pgo_inner` therefore prompt the user before destructive or long-running work, all sharing a single `pgo_confirm` helper:
 
 1. **Reuse vs rebuild** — when compatible profdata is found, prompt `[Y/n]` to reuse; declining triggers a full 4-pass rebuild (and continues into prompts 2–3).
 2. **Purge `staging/` and `pgo_store/`** — prompt `[y/N]` before clearing; declining aborts PGO. The `staging1/2/3` dirs (under world-writable `/var/tmp`) are `rmtree`'d, but `pgo_store` is cleared with `fs_provision.empty_dir_contents` — it lives under the root-owned FHS parent `/var/cache/sysforge`, so `rmtree`'s final `rmdir` would need write on that parent and fail with `EACCES`; emptying the contents (all unprivileged-written) keeps the node and needs no parent write. After the purge, `pgo_store` is (re)provisioned via `fs_provision.ensure_writable_dir` (`root:sysforge 2775` — see *Directory provisioning* above). A user-writable / env-override `pgo_store` takes the direct path and never touches sudo.
@@ -1280,7 +1291,7 @@ The packages and kernel stages read these values and inject them into the build
 
     **Liveness guard.** Presence of the sentinel cannot distinguish "a previous run died mid-mutation" from "a run is alive right now" — and the recovery prompts above are unanswerable, and destructive, against a live run: clearing a live owner's sentinel lets the second run's `mark_started` overwrite the record wholesale, after which whichever run finishes first `clear()`s the other's (silently — `clear()` suppresses `FileNotFoundError`), leaving two concurrent install-bearing runs with no interruption record for either. So `sentinel_scope` also holds an exclusive `flock` on `<state_dir>/stage_in_progress.lock` for the stage's lifetime, via the shared `primitives/build_lock.py` primitive (its `noun` parameter carries the "install stage" wording; the build stages pass `noun="build"` and keep their existing messages). Liveness becomes "is the lock takeable?", which the kernel answers correctly even after `SIGKILL` or power loss — a PID recorded in the sentinel could not, since PID recycling would report a dead owner as alive forever, unrecoverable given the no-override decision below. Two layers use it: `check_and_recover_stale_sentinel` probes the lock at CLI entry and returns False **without prompting** when an owner is alive (naming the holder PID and the recorded stage), making the clear prompt unreachable; and `sentinel_scope` acquires it for real — before `mark_started`, so a live owner's record is never overwritten — catching the probe/acquire race plus any mutating verb reached outside `cli._gate_sentinel_check`'s allowlist. **A stale record is never overwritten** (`3.5.0-B46`): `uninstall`, `revert-to-stock`, the `state` verbs and the artifact verbs set `requires_sentinel = True` but are outside that allowlist, so their scope's `mark_started` replaced an interrupted toolchain install's record and the success path cleared it, and the next `update` ran with no recovery prompt. `sentinel_scope` now calls `check_and_recover_stale_sentinel` itself, before taking the lock, whenever a record exists, and raises `RuntimeError` with the record kept when recovery is declined or fails. Contention there raises `RuntimeError`, which `verbs/runner.py` already converts to exit 1. **No override:** a live owner is unambiguous, so a prompt would only invite the mistake the guard prevents; escaping requires killing the owning process. The posture splits by error type — contention is strict (hard refusal), while `OSError`/`PermissionError` stay lenient (warn + proceed, matching the sentinel write itself) so a read-only state dir cannot lock the user out of every mutating verb. Per-state-dir scoping is automatic since the lock lives in the state dir, so an isolated `SYSFORGE_STATE_DIR` (test fixtures, VM) never contends with a live run. Scopes are sequential, never nested — the `run` verbs set `requires_sentinel = False` precisely so a verb-level scope cannot wrap a stage's own.
 
-2. **Post-install verification (Gate 3)** — after the `pacman -U` of the LLVM run, `_verify_llvm_install()` checks: (a) `pacman -Q` versions across `_LLVM_VERSION_MATCH_SET` (which *is* `LLVM_LOCKSTEP_SUITE` from `toolchain_preflight` — `llvm`/`llvm-libs`/`clang`/`lld`/`compiler-rt`/`polly`/`openmp`) agree, via `toolchain_safety.detect_suite_skew` (the canonical interrupted-install symptom — a mismatched `llvm-libs` is the exact failure mode that produces a broken GUI). The suite spans several independent pkgbases, so lockstep is on **pkgver** (the upstream release keying the `LLVM_<ver>` ABI namespace); a pkgrel-only divergence across pkgbases (e.g. an `llvm` -2 rebuild beside `clang` -1) is a legitimate state and is *not* a skew — only the shared-pkgbase pair `llvm`/`llvm-libs` is held to full `pkgver-pkgrel` lockstep. (b) `clang --version` and `ld.lld --version` invoke cleanly without missing-symbol errors (probing `ld.lld`, the GNU-compatible flavor `-fuse-ld=lld` resolves to — bare `lld` is the generic multiplexer driver and always exits 1 without a flavor), and clang compiles and links a trivial program with `-fuse-ld=lld`, since `--version` returns before libclang-cpp's symbols are bound (`3.5.0-B58`, as Gate 1's smoke test), (c) `ldd` of installed clang/lld resolves libLLVM under `/usr/lib` (`_check_llvm_link_resolution`), (d) when `[llvm] targets` is configured, `llvm-config --targets-built` is a superset. On failure the stage **auto-rolls-back** to the pre-install snapshot rather than prompting (the kernel-parity overhaul replaced the old interactive `_prompt_llvm_recovery`): a successful restore clears the sentinel and raises "prior toolchain was restored"; a failed/incomplete restore keeps the sentinel with the snapshot recovery command. This verification is comprehensive and fatal, but only runs inside `run toolchain`; if a toolchain run is interrupted before it (or a later partial pacman transaction reintroduces a skew), the broken state can still reach an everyday `sysforge update`. That gap is closed by the `cc:<name>` compiler-health probe in `toolchain_preflight` (see §`toolchain_preflight.py`), which re-detects the suite-wide pkgver skew / non-runnable clang before any package builds — deliberately a lightweight independent check sharing the `LLVM_LOCKSTEP_SUITE` constant rather than importing this pipeline-layer verifier into the primitives layer.
+2. **Post-install verification (Gate 3)** — after the `pacman -U` of the LLVM run, `_verify_llvm_install()` checks: (a) `pacman -Q` versions across `_LLVM_VERSION_MATCH_SET` (which *is* `LLVM_LOCKSTEP_SUITE` from `toolchain_preflight` — `llvm`/`llvm-libs`/`clang`/`lld`/`compiler-rt`/`polly`/`openmp`) agree, via `toolchain_safety.detect_suite_skew` (the canonical interrupted-install symptom — a mismatched `llvm-libs` is the exact failure mode that produces a broken GUI). The suite spans several independent pkgbases, so lockstep is on **pkgver** (the upstream release keying the `LLVM_<ver>` ABI namespace); a pkgrel-only divergence across pkgbases (e.g. an `llvm` -2 rebuild beside `clang` -1) is a legitimate state and is *not* a skew — only the shared-pkgbase pair `llvm`/`llvm-libs` is held to full `pkgver-pkgrel` lockstep. (b) `clang --version` and `ld.lld --version` invoke cleanly without missing-symbol errors (probing `ld.lld`, the GNU-compatible flavor `-fuse-ld=lld` resolves to — bare `lld` is the generic multiplexer driver and always exits 1 without a flavor), and clang compiles and links a trivial program with `-fuse-ld=lld`, since `--version` returns before libclang-cpp's symbols are bound (`3.5.0-B58`, as Gate 1's smoke test), (c) `ldd` of installed clang/lld resolves libLLVM under `/usr/lib` (`check_llvm_link_resolution`), (d) when `[llvm] targets` is configured, `llvm-config --targets-built` is a superset. On failure the stage **auto-rolls-back** to the pre-install snapshot rather than prompting (the kernel-parity overhaul replaced the old interactive `_prompt_llvm_recovery`): a successful restore clears the sentinel and raises "prior toolchain was restored"; a failed/incomplete restore keeps the sentinel with the snapshot recovery command. This verification is comprehensive and fatal, but only runs inside `run toolchain`; if a toolchain run is interrupted before it (or a later partial pacman transaction reintroduces a skew), the broken state can still reach an everyday `sysforge update`. That gap is closed by the `cc:<name>` compiler-health probe in `toolchain_preflight` (see §`toolchain_preflight.py`), which re-detects the suite-wide pkgver skew / non-runnable clang before any package builds — deliberately a lightweight independent check sharing the `LLVM_LOCKSTEP_SUITE` constant rather than importing this pipeline-layer verifier into the primitives layer.
 
 3. **Clean-exit SIGINT scope** (`primitives/interrupt.py`) — every `sentinel_scope` body runs inside an `InterruptScope`. The first Ctrl-C flips a flag without raising and prints a one-line notice (a raw `os.write` to stderr, since a signal handler must not take the logging locks); children in the terminal's foreground process group, such as makepkg and pacman, still get it themselves. Code inside the scope stops at a safe boundary by calling the module-level `interrupt.checkpoint()`, which raises `CleanExitRequested` (translated by `sentinel_scope` into a `RuntimeError` with the retry and recovery hints, sentinel intact). The checkpoints sit only where stopping leaves the system consistent: before each package in `build_core.build_and_install`'s loop (the `build`/`update` verb scopes) and in the packages stage loop. The toolchain and kernel install windows (install, then Gate 3 or `mkinitcpio` and the bootloader) have no safe midpoint, so they have no checkpoint: the body finishes, the sentinel is cleared, and `InterruptScope.redeliver` sends the SIGINT again under the previous handler, so the run stops as a Ctrl-C outside any scope would. Before `3.5.0-B44` nothing called `check()`, so the first Ctrl-C was swallowed and never acted on. A second Ctrl-C falls through to default `SIGINT` handling (immediate termination) — the operator explicitly chose the unsafe path. `CleanExitRequested` subclasses `BaseException` so it propagates through `except Exception:` blocks without being silently swallowed.
 
@@ -1379,7 +1390,7 @@ spelling per meaning, across every verb:
 
 **Sentinel handling.** Verbs whose `execute` mutates the live system set `requires_sentinel = True`. The runner wraps `execute + post_validate` in `sentinel_scope(state_dir, verb.name, recovery=…, retry_cmd=…, **metadata)` (`recovery` is a `stage_sentinel.Recovery` from `verb.sentinel_recovery`, stored as a kind plus arguments, `3.5.0-B43`) from `primitives/stage_sentinel.py`. On entry, the sentinel writes `stage_in_progress.toml`; on normal completion (both phases pass), it clears. On `RuntimeError` or `CleanExitRequested`, the sentinel is left in place so the next sysforge invocation blocks at the CLI-entry recovery prompt. `sentinel_scope` also installs an `InterruptScope`, so verbs participate in the same first-Ctrl-C-defers-to-safe-boundary behaviour as the toolchain stage: `build` and `update` stop before their next package (`interrupt.checkpoint()` in `build_core`), and a verb with no checkpoint stops when its `execute` + `post_validate` complete (`3.5.0-B44`). It additionally holds the `stage_in_progress.lock` liveness lock for the scope: if another run already holds it, entering the scope raises `RuntimeError` **before** `mark_started`, which the runner's existing handler converts to exit 1 without clobbering the live run's sentinel (§Pipeline layer, *Liveness guard*). The toolchain pipeline stage uses the same primitive — there is one implementation, shared.
 
-**Read-only verbs** (`env`, `help`, `resolve`, `log`, `state list`, `state orphans` without `--delete`, `state failed` without `--clear`/`--clear-all`, `state profiles` without `--delete`, `state boot-entries`, `bench toolchain`, `packages list`, `doctor` without `--apply`) implement `execute` (the work is printing) and return `ExecResult()`; `post_validate` defaults to no-op and `requires_sentinel = False`. They use the same dispatch path as mutating verbs — no second code path.
+**Read-only verbs** (`env`, `help`, `resolve`, `log`, `config check`, `state list`, `state orphans` without `--delete`, `state failed` without `--clear`/`--clear-all`, `state profiles` without `--delete`, `state boot-entries`, `bench toolchain`, `packages list`, `doctor` without `--apply`) implement `execute` (the work is printing) and return `ExecResult()`; `post_validate` defaults to no-op and `requires_sentinel = False`. They use the same dispatch path as mutating verbs — no second code path.
 
 **`state boot-entries`** (`3.3.0-F5`, `StateBootEntriesVerb`, read-only, `requires_sentinel = False`) lists every `vmlinuz-*` in `/boot` with the loader entry that boots it. The table goes through the pager like `state profiles` (`--no-pager` disables it): columns KERNEL / ENTRY / OWNER (`you`, `sysforge` or `none`) / TEMPLATE, plus `(missing)` rows for managed entries whose kernel is gone. Under `bootloader = grub`/`none` it prints a one-line note instead; with `boot_entries = "off"` it notes that and still lists. Rows come from `boot_entries.rows_for`.
 
@@ -1403,6 +1414,9 @@ spelling per meaning, across every verb:
 | `log` | null | resolve the pipeline, per-pkg or `--verb` log path; page through `$PAGER` | null | no |
 | `packages {list,add,remove}` | load packages.toml + validate override fields | rewrite TOML | null | no |
 | `state {list,repair,orphans}` | load state dir | inspect / repair / prune | null | `repair` only |
+| `config check` | null | inspect the live config files (`config_schema.inspect`) | null | no |
+| `config clean` | null | rewrite retired settings (`--unknown`: drop unknown ones); diff, then consent | null | no |
+| `config reset` | null | restore keys or a whole file to the shipped default; diff, then consent | null | no |
 | `config merge` | null | scan config dir for `.sfnew`/`.pacnew`; pacdiff-style view/merge/remove loop | null | no |
 | `revert-to-stock` | resolve state dir + `plan_revert` over `BuildState` (pure, no mutation) | prompt/`--yes`/`--dry-run` gate, then per-target reinstall / atomic replace / derename-then-reinstall via `pacman` | (state written inline) | yes |
 | `bench toolchain` | null | resolve preconditions → workload → unprivileged stock fetch + extract → interleaved timing → report → `bench.toml` | null | no |
@@ -1632,7 +1646,7 @@ The whole feature is LLVM-only — it instruments with clang and merges with `ll
 - **`prepare_deps(pkgbuild_paths, config, *, building_names, …)`** — pre-installs missing repo *build deps* in one `pacman -S` transaction (`batch_install_makedeps`) and builds AUR/local deps in topo order (`resolve_aur_deps_batch` + `build_resolved_deps`), excluding the packages about to be built themselves. The repo arm collects `depends` + `makedepends` + `checkdepends` (`pacman.collect_builddeps`), **not just makedepends**: the per-package makepkg call runs with `-s` stripped, and makepkg checks runtime `depends` before building too, so a missing repo runtime dep would abort the build with exit 8 ("Could not resolve all dependencies"). It **filters the missing set to sync-repo packages first** (`aur.repo_packages`, the same classifier the AUR resolver uses) — an AUR-only dep mixed into the `pacman -S` transaction makes pacman abort with "target not found" and install *none* of the repo deps either, so AUR deps are excluded here and left to the AUR arm (which resolves `depends + makedepends`). Both arms are best-effort — a failure warns and lets the build proceed, surfacing a genuinely-missing dep as a per-package build failure with a diagnosis rather than aborting the whole batch up front.
 - **`install_built(built_pkg_files, *, always_install=frozenset(), interactive=False, allow_break_deps=frozenset(), state_dir=None) -> (installed_files, not_installed)`** — dedupe, re-fetch the installed set (makedep/AUR pre-install may have expanded it), `filter_pkgs_to_installed` for split-pkgbase safety, then one `pacman -U`. `not_installed` maps each artifact pacman did not install to a one-line reason (empty on success). The transaction stays single so pacman resolves the batch's inter-dependencies together, which makes it all-or-nothing; when pacman refuses on **file conflicts**, `batch_install_pkgs(conflicts_out=…)` reports the culprit pkgnames (`pacman.file_conflict_culprits`) and those artifacts are set aside with pacman's per-file detail as their reason, then the remainder is retried as one transaction (3.2.0-B33). A refusal naming no culprit (deps, signatures, DB lock) or naming only packages outside the batch fails everything still pending with `INSTALL_REFUSED_REASON` — a retry is never the identical set. `build_and_install` folds the per-file reasons into `BuildOutcome.not_installed` (`not_installed_by_pkgbase`, also used by `update`'s `--install-only` scan) and snapshots `build_state` for its targets before the loop, so a refused artifact's entry — written by `makepkg_wrapper` at build time — is put back via `BuildState.revert_record` (3.2.0-B34): the pre-build entry returns, keeping only the new `build_seconds` ring and any pre-3.5.0-B8 `reviewed_commit` (the build and review did happen; the current review baseline lives in `[reviewed]`, which a revert never touches), or the entry is dropped when there was none. Without the revert `build_state` claimed a version and flags that never reached the system. The revert passes the refused artifact's filename, so `BuildState` keeps the undone entry in its `[reverted]` table; when a later install of that same file succeeds, `install_built` (given `state_dir`) calls `_restore_reverted_state`, which puts it back (3.3.0-B2). Without that, a rerun that reuses the artifact ("already built" skips `makepkg_wrapper`, so nothing records it) installs the new build while `build_state` keeps describing the old one. With `state_dir` (both `build_and_install` call sites and `update`'s `--install-only` scan pass it), each dropped sub-package that is not installed also loses the `build_state` record `makepkg_wrapper` wrote for it at build time (3.2.0-B31): the wrapper records every PKGBUILD `pkgname` because it runs before the install decision, and this filter is the one place that knows which members reach the system — without the cleanup a replaced split member reappears as a `source_built` phantom after every rebuild of its pkgbase until the next superset sync prunes it. Best-effort; a state IO error never fails the install. The keep-set is the currently-installed pkgnames **union `always_install`** — the pkgnames the caller explicitly asked to build. `build_and_install` passes the build targets' pkgnames, so a fresh `sysforge build <new-pkg>` installs the package the user asked for instead of dropping it for not being installed yet; for `update` the union is a no-op (its targets are already installed). A conflict-mode `-sysforge` rebuild (e.g. `mesa --pgo=use`) emits artifacts renamed off every stock pkgname (`mesa-sysforge`), so `filter_pkgs_to_installed` keeps them via their `replaces` rather than their absent pkgname — otherwise the optimized build would complete and then be silently dropped at install. Reused by `update`'s `--install-only` artifact-scan branch (which keeps the default empty set). `interactive` threads down to `pacman.batch_install_pkgs(..., interactive=…)`: when set it drops `--noconfirm` and inherits pacman's TTY streams so a package-conflict question (`X and Y are in conflict. Remove Y? [y/N]`) is put to the operator instead of auto-answered `N` and aborting the transaction. `build_and_install` passes its own `interactive` from both the just-in-time and final-install call sites; `update`'s non-interactive call keeps the default (`--noconfirm`). The non-interactive path still has to install the conflict-mode rename without an operator at the prompt: pacman only auto-processes `replaces` on a sync upgrade, so on a local `-U` the renamed drop-in (`mesa-sysforge` declaring `replaces = mesa`) still raises the conflict prompt, which `--noconfirm` declines (default `N`) and aborts. `batch_install_pkgs` therefore adds `--ask=4` (`ALPM_QUESTION_CONFLICT_PKG`) **only when** a built package's `replaces` names a currently-installed package — auto-confirming exactly the intended drop-in removal; absent a real replaces-installed relationship the prompt keeps its safe default so an unexpected conflict still aborts.
 - **`sync_source`** is the single deliberate caller difference: `update` passes `False` (Phase 2 already synced sources through the scheduler), `build` passes `not --no-update` to keep its inline per-package source sync (which itself routes through `source_sync.get_scheduler()` inside `makepkg_wrapper.run`). `_find_existing_artifacts` and `_record_build_failure` live here too (moved from `update.py`) since both the engine and `update`'s install-only scan use them — though `_find_existing_artifacts` is now a thin delegate to `makepkg_artifacts.find_artifacts`, which `3.1.0-F9` lifted into `primitives/` so the build sandbox could share the matcher (§Primitives Layer).
-- **`make_build_options(stage, options, **overrides) -> BuildOptions`** — the shared factory the three install-bearing pipeline stages (`kernel`/`toolchain`/`packages`) use instead of hand-assembling a `BuildOptions`. It maps the fields common to every stage's `RunOptions` (`no_pkg_log` → `pkg_log`, plus `persist_log`/`state_dir`/`abi_check`, the last via `getattr` so a run-options object without it degrades to `False`), layers in the stage's constant defaults from `_STAGE_BUILD_DEFAULTS` (`kernel` → `owner_stage="kernel"` + `no_install=True`; `toolchain` → `pgo_managed=True`; `packages` → none), then applies the caller's per-call `overrides` (which win over both). Fields that differ per stage or per package — `profile_conf`, `log_dir`, `update`, `cc`/`cxx`/`ld_override`, `source`, `toolchain_variant`, `extra_flags`, … — are passed explicitly as overrides; anything a stage omits keeps its `BuildOptions` default (so `toolchain` not passing `log_dir` keeps it `None`). This is where a stage-wide default like the kernel build/install split lives, rather than being repeated at each call site.
+- **`make_build_options(stage, options, **overrides) -> BuildOptions`** — the shared factory the three install-bearing pipeline stages (`kernel`/`toolchain`/`packages`) use instead of hand-assembling a `BuildOptions`. It maps the fields common to every stage's `RunOptions` (`no_pkg_log` → `pkg_log`, plus `persist_log`/`state_dir`/`abi_check`, all read directly off the stage's `RunOptions`), layers in the stage's constant defaults from `_STAGE_BUILD_DEFAULTS` (`kernel` → `owner_stage="kernel"` + `no_install=True`; `toolchain` → `pgo_managed=True`; `packages` → none), then applies the caller's per-call `overrides` (which win over both). Fields that differ per stage or per package — `profile_conf`, `log_dir`, `update`, `cc`/`cxx`/`ld_override`, `source`, `toolchain_variant`, `extra_flags`, … — are passed explicitly as overrides; anything a stage omits keeps its `BuildOptions` default (so `toolchain` not passing `log_dir` keeps it `None`). This is where a stage-wide default like the kernel build/install split lives, rather than being repeated at each call site.
 
 ---
 
@@ -1732,7 +1746,7 @@ Implements `sysforge doctor` — the unified diagnostic front-end for sysforge-m
 
 **Two scopes (`system` / `pkg`).** The surface is split into `sysforge doctor system [AXIS…]` and `sysforge doctor pkg [TARGETS] [AXIS…]`. Bare `sysforge doctor` is `doctor system` — unchanged as the everyday full sweep. The split exists because a single `PKG` positional previously meant three different things (a walk target, a scope qualifier for `rust`/`integrity`, and — via `--graphics` — a target *injector*), none of which `--help` distinguished. Two rules apply identically at both scopes:
 
-1. **No axis flag → that scope's defaults.** `doctor system` runs the 13 non-opt-in axes; `doctor pkg mesa` runs `abi + rust + integrity` scoped to mesa. The opt-in axes are included at package scope because their cost is a whole-system scan, not a per-package one.
+1. **No axis flag → that scope's defaults.** `doctor system` runs the 14 non-opt-in axes; `doctor pkg mesa` runs `abi + rust + integrity` scoped to mesa. The opt-in axes are included at package scope because their cost is a whole-system scan, not a per-package one.
 2. **A broad target selector suppresses the opt-ins.** `doctor pkg --all` / `--repo` runs `--abi` only; name an opt-in axis explicitly to override. This reuses the existing `_OPT_IN_AXES` frozenset rather than introducing a second policy. `--graphics` is *not* a broad selector for this purpose — it expands to ~15 curated packages, not the whole system.
 
 So `doctor pkg cosmic-comp-git --rust` means exactly one thing: the rust axis, that package, no linkage walk.
@@ -1776,6 +1790,8 @@ Per-package group headers and the final summary both tag each package with its i
 
 `--pacman` runs a pacman / system-integrity axis (`primitives/system_probe.py::collect_system_findings`) — all read-only against the *local* database (never `-Sy`): `pacman -Dk` local-db dependency consistency (missing deps → `error`), a lingering `/var/lib/pacman/db.lck` from an interrupted transaction (`warn`), unmerged `*.pacnew`/`*.pacsave` config files under `/etc` (`warn`), and `pacman -Qtdq` true orphans (`info`). Two size/freshness checks join the same axis: **package-cache size** (`_check_pkg_cache`, F15) sums the `.pkg.tar*` archives in the pacman cache dirs resolved via `pacman.get_pacman_cache_dirs()` (never hardcoding `/var/cache/pacman/pkg`) and `warn`s over `[doctor] pkg_cache_warn_gb` (default 5 GB) with `paccache` remediation — distinct from `cache_probe`, which reports *build* caches (ccache/sccache); and **mirrorlist freshness** (`_check_mirror_freshness`, F16) `warn`s when `/etc/pacman.d/mirrorlist`'s mtime age exceeds `[doctor] mirrorlist_stale_days` (default 14) — file-age only, never a live latency probe. It also folds in **sysforge libalpm-hook drift** (`doctor._collect_hook_findings` over `primitives/pacman_hooks.diff_status`): each shipped hook/helper that is missing from or stale against the canonical source emits a `warn` with remediation `run \`sysforge setup\``. Read-only — `diff_status` only reads. Standalone (`sysforge doctor --pacman`).
 
+`--config` (`3.5.0-F18`) inspects the live config files through `config_schema.inspect` (the report `sysforge config check` prints): a file that does not parse is an error, a retired or unknown setting a warning whose remediation is `sysforge config clean` (with `--unknown` for an unknown one). Read-only, and in the default sweep.
+
 `--state` runs a sysforge state-integrity axis (`primitives/state_probe.py::collect_state_findings`) — read-only inspection of sysforge's *own* persisted state: recorded build failures from `build_state.toml`'s `[failures]` table (each `warn`, surfacing the `build_diag` signature + `fix_cmd` when present; a package removed since the last reconcile is dropped in memory via `install_reconcile.clear_removed_failures`, never saved, `3.5.0-B120`), an interrupted stage sentinel via `StageSentinel.get_active()` (`error`, carrying the recorded `recovery_cmd` — it does **not** call the recovering `check_and_recover_stale_sentinel`), and build-state drift vs the live pacman db (`info`, zombie entries for uninstalled packages). It also flags **live record-stage PGO builds** (`_check_instrumented_builds`, F14): for each tracked package it resolves the PGO store (`mesa_pgo.resolve_store`) and `warn`s when a bare `.profraw` is present with **no** merged `.profdata` — an instrumented, unoptimized build left live — pointing at `sysforge build <pkg> --pgo=use` or a repo rollback. Detection is provenance-only (never inspects a binary); a package that never used `--pgo` has no store and is silently skipped. The last source-sync `STATUS_*` is intentionally *not* surfaced: the source-sync scheduler cache is per-process, so a standalone `doctor` run has no sync results. Standalone (`sysforge doctor --state`).
 
 `--boot` runs a boot/kernel-runtime axis (`doctor._collect_boot_findings`, reusing `primitives/kernel_safety`) — the running-system analog of the kernel stage's gates 1/3: per-bootable-kernel boot-artifact verification (`verify_boot_artifacts`: vmlinuz + initramfs + a boot entry; gaps are brick-class `is_brick` → exit code), a recovery-fallback check (`find_fallback_kernels`; only one bootable kernel → `info`), `/boot` free space (`check_boot_mount_space`), and DKMS modules for the running kernel (`check_dkms_for_kernel(running_kernel_release())`; these `dkms:*` findings carry the running-kernel reboot caveat, while the filesystem-live boot-artifact / `/boot`-space findings do not). The running-kernel `.config` device audit stays in `--hardware` (it is device-driver coverage, distinct from boot-artifact readiness), so there is no double-report. Standalone (`sysforge doctor --boot`).
@@ -1931,7 +1947,7 @@ Bottom-anchored status line for batch operations (`[3/10] building · htop`). Du
 
 **How primitives reach it.** They don't import it. `ui/progress.py` registers itself with `primitives/progress_hooks.py` at import, and the leaf layer calls `progress_hooks.hooks().<name>()` — see that module below.
 
-Integration sites: `sysforge/verbs/runner.py::run_verb` (universal `<verb>: starting…` startup phase + clear), `sysforge/pipeline/runner.py` (`phase(stage.name)` per stage in `run_stage_standalone` / `run_pipeline`), `sysforge/pipeline/stages/packages.py` (build loop), `sysforge/primitives/aur_resolve.py::build_resolved_deps` (AUR deps), `sysforge/update.py` (phase statuses for init/assembly/drift/preflight + trackers for source sync and the threaded version check), `sysforge/build_core.py` (phase statuses for source pre-sync, dep prep, and install + the build-loop tracker), `sysforge/fetch.py` (fetch loop). Prompts need nothing from their call sites: every `prompt.py` helper yields the terminal itself.
+Integration sites: `sysforge/verbs/runner.py::run_verb` (universal `<verb>: starting…` startup phase + clear), `sysforge/pipeline/runner.py` (`phase(stage.name)` per stage in `run_stage_standalone` / `run_pipeline`), `sysforge/pipeline/stages/packages.py` (build loop), `sysforge/build/aur_deps.py::build_resolved_deps` (AUR deps), `sysforge/update.py` (phase statuses for init/assembly/drift/preflight + trackers for source sync and the threaded version check), `sysforge/build_core.py` (phase statuses for source pre-sync, dep prep, and install + the build-loop tracker), `sysforge/fetch.py` (fetch loop). Prompts need nothing from their call sites: every `prompt.py` helper yields the terminal itself.
 
 ### `prompt.py`
 
@@ -1940,13 +1956,13 @@ Single shared interactive-prompt helper. Every stage that needs user input goes
 Key contract:
 
 - Every helper reads its input inside `progress_hooks.hooks().yield_terminal("prompt")`, so the bottom-anchored bar is blanked in place for the prompt and repainted as soon as the answer is in. This is the single home for that guarantee — call sites no longer manage the bar by hand before prompting (the forgotten clear at the toolchain confirm/preflight/PGO prompts was exactly this footgun). Since every interactive input comes through here, it is also what pauses an open tracker's clock while the user decides (`3.3.0-F2`). (A prompt yield keeps the scroll region — a full region reset's cursor-restore is unreliable on some terminals and rendered prompts off-view.)
-- `prompt_choice` re-prompts with a visible warning on unrecognized input (so typos / jibberish never silently fall through to the default), unless the call site passes `retry_on_invalid=False` — used for destructive / mutate-confirm prompts where any non-confirming input must abort (partition.py's literal-`yes` confirmation; the `[y/N]` confirms in `state orphans --delete`, `doctor --apply` rebuild, and `auto_repair`'s checksum-mismatch `updpkgsums` retry). These three previously used a bare `input()` with a hand-rolled `EOFError` guard; routing them through `prompt_choice` also picks up the captured-stdin `OSError`-as-EOF handling for free.
-- `eof_default` is a separate kwarg from `default`. Most sites pass neither (EOF returns `default`). `toolchain.py`'s GCC-build override and `_confirm_or_abort` deliberately set `eof_default="y"` to preserve their long-standing "EOF means proceed unattended" semantic.
+- `prompt_choice` re-prompts with a visible warning on unrecognized input (so typos / jibberish never silently fall through to the default), unless the call site passes `retry_on_invalid=False` — used for destructive / mutate-confirm prompts where any non-confirming input must abort (`pipeline/stages/_partition_plan.py`'s literal-`yes` confirmation; the `[y/N]` confirms in `state orphans --delete`, `doctor --apply` rebuild, and `auto_repair`'s checksum-mismatch `updpkgsums` retry). These three previously used a bare `input()` with a hand-rolled `EOFError` guard; routing them through `prompt_choice` also picks up the captured-stdin `OSError`-as-EOF handling for free.
+- `eof_default` is a separate kwarg from `default`. Most sites pass neither (EOF returns `default`). The toolchain stage's build confirmation (`toolchain/pkgbuilds.py`) is the one site that sets `eof_default="y"`, preserving its long-standing "EOF means proceed unattended" semantic; the soname-consumer prompts in `toolchain/gates.py` set `eof_default="n"`, since they approve extra rebuilds.
 - Both helpers catch `EOFError` *and* `OSError`, since pytest's captured stdin and other unreadable-stdin scenarios raise the latter.
 - `prompt_key` reads one character in cbreak mode (`termios`/`tty`, restored in a `finally`) and echoes it plus a newline so the transcript still shows the answer — no Enter required. It degrades to line-based `input()` (first character of the stripped line) when stdin is not a TTY, `termios` is unavailable, or raw-mode setup fails, so tests and pipes keep working. Ctrl-C raises `KeyboardInterrupt` (cbreak delivers it as `\x03`); Ctrl-D/EOF/unreadable stdin raise `EOFError`; a bare Enter returns `""` ("no answer", distinct from EOF) so callers can re-prompt. Validation and re-prompt loops stay in the caller, matching `prompt_choice`'s contract. Used by the PKGBUILD review gate.
 - Optional `tag`/`level` kwargs reuse `log.prompt_prefix(level, tag)` so prompts keep the standard `[SYSFORGE][LEVEL][TAG] ` format.
 
-Call sites: `pipeline/stages/reconfigure.py` (11), `pipeline/stages/packages.py` (`_prompt_failed_packages`), `pipeline/stages/toolchain/` (3), `pipeline/stages/partition.py` (1), `setup_cmd.py` (1), `build/makepkg_wrapper.py` (4). No stage may call `input()` directly.
+Call sites span the stages (`reconfigure` most of all), the verbs and the build primitives (the review gate, the recovery menu, `auto_repair`). No stage may call `input()` directly.
 
 ### `progress_hooks.py`
 
@@ -1960,6 +1976,10 @@ Host detection and the derivations built on it: `detect_host_arch()` (uname), `p
 
 Pure constants module — the canonical directory of every config file sysforge reads. `CONFIG_BASE` is derived from `$SYSFORGE_CONFIG_DIR` (default `/`, so system config resolves under `<base>/etc/sysforge/`, including `BOOTSTRAP_PATH`). User-side roots follow the XDG Base Directory Specification via the `_xdg_base(env, default)` helper: `USER_CONFIG_DIR` (`$XDG_CONFIG_HOME/sysforge`), `USER_CACHE_DIR` (`$XDG_CACHE_HOME/sysforge`), `USER_STATE_DIR` (`$XDG_STATE_HOME/sysforge`). The resolved path lists (`CONFIG_PATHS`, `CONFLICT_GROUP_PATHS`, `CONSUMES_INFERENCE_PATHS`) layer the user file (`$XDG_CONFIG_HOME/sysforge/…`) over the system file in `extends_system` order. Helpers: `resolve_packages_path(config)` returns the `packages.toml` path the rest of the codebase should use (honouring `--packages` overrides), and **`resolve_state_dir(cli_override)`** is the single home for state-dir resolution — `--state-dir` > `SYSFORGE_STATE_DIR` > `/var/lib/sysforge` > the XDG state dir when the default is neither writable nor provisionable — returning `(Path, source)` where `source` is one of `--state-dir`, `SYSFORGE_STATE_DIR`, `default`, `xdg-fallback`. Read-only callers pass `provision=False` (`state profiles`, `3.4.0-B20`): an unwritable default is then never provisioned, since that path can prompt for sudo, and the XDG dir is read instead when it exists, because that is where this user's earlier runs wrote when provisioning was refused. It lived in `pipeline/state.py` until `3.2.0-F1`, which meant five primitives (`makepkg_wrapper`, `state_probe`, `source_sync`, `llvm_state`, `init_notice`) reached *upward* into the pipeline layer at function level for a path computation; `pipeline.state` re-exports the name so existing imports and test patch points are unaffected. Apart from that resolver's writability probe and its `fs_provision` fallback, the module does no I/O — just path strings.
 
+### `env_vars.py`
+
+The registry of every environment variable sysforge reads (`3.5.0-B128`): `ENV_VARS`, one `EnvVar(name, audience, text)` each, `audience` `user` (a setting) or `diagnostic` (a switch for bug reports). Pure data; the readers keep their own `os.environ.get` calls. `tools/gen_options.py` renders the man page's ENVIRONMENT section from it, and `tests/test_env_vars.py` fails on a `SYSFORGE_*` name in the code that it does not list (journal fields live in `journal.JOURNAL_FIELDS`), and on an entry nothing reads.
+
 ### `config.py`
 
 TOML config loading and path resolution. Public API:
@@ -2011,7 +2031,7 @@ Init-file parsing is regex-based (`export KEY=value`, `KEY=value; export KEY`, p
 ### `pacman.py`
 
 All pacman and batch-install shared operations. Public API:
-- `get_pkgdest()` / `get_builddir()` / `get_srcdest()` / `get_logdest()` — resolve the corresponding makepkg path variable via the shared `_resolve_makepkg_path(key)` helper, which mirrors makepkg's own precedence: **environment first** (`os.environ`), then the layered `parse_system_makepkg_conf()` (`/etc/makepkg.conf` → user conf), quotes stripped and `~`/`$VARS` expanded, else `None`. These are the single home for "where did makepkg put / read this?" — any new code that needs to *locate* a built artifact, build tree, downloaded source, or build log must call them rather than assuming `~/builds` / the PKGBUILD dir / a hardcoded default (a recurring bug class). `BUILDDIR` resolution in particular feeds `makepkg_env._effective_build_dir` (side-car log diagnosis) and `kernel._resolve_built_config` (resolved `.config` discovery), both of which must honour a `BUILDDIR` set only in `/etc/makepkg.conf`. `PKGDEST` resolution feeds `makepkg_wrapper._find_artifacts` (the union-of-`PKGDEST`-and-PKGBUILD-dir locator behind `install_built_packages` + the post-build ABI report) and `build_core`'s artifact snapshot — so a non-default `PKGDEST` doesn't strand the install/ABI scan looking in the PKGBUILD dir. `install_built_packages` wraps that locator in `_artifacts_for_pkgbuild`, which scopes the union in two tiers. **Preferred:** a build-time manifest (`_BUILT_MANIFEST_NAME`, `.sysforge-built.list`) — the exact package basenames `makepkg --packagelist` emitted, recorded by `_capture_built_manifest` on build success *while the patched `PKGBUILD.sysforge` is still present* — is matched exactly. Recorded for any **name-affecting** build: one that applies an extracted profile **or** a rename (kernel local-rename / `-sysforge` suffix); a rename is exactly the case pkgname scoping can't recover (2.5.1-B3 — a rename-only kernel previously recorded no manifest because capture was gated on the extracted profile alone). This is the only reliable scope for a **renamed** build (e.g. a `-sysforge` kernel): by install time the patched PKGBUILD is cleaned up, leaving only the upstream PKGBUILD whose pkgname (`linux`) prefix-matches unrelated (`linux-custom`, `linux-steam-integration`) and stale-version (`linux-sysforge-<oldver>`) artifacts — the pre-B9 bug that swept those into `pacman -U` and could downgrade the running kernel. **Fallback** (no manifest, or none of its entries are present): scope by the PKGBUILD's own pkgnames (filename-matched via `_parse_built_pkg_filename`, which anchors on the exact `<pkgname>-` prefix **and** requires a valid `[epoch:]pkgver-pkgrel-arch` tail — three hyphen-delimited fields, since `PKGBUILD(5)` forbids hyphens in pkgver/pkgrel/arch — so pkgname `linux` no longer matches `linux-custom` et al., 2.5.1-B3). Within that set it keeps only the artifacts at the PKGBUILD's own `epoch:pkgver-pkgrel` (`_pkgbuild_version`), so an older build of the same pkgnames still in PKGDEST is not reported or installed as this build's output (`3.5.0-B21`: every build without a rename or extracted profile records no manifest, sandboxed mesa 26.2.5 included, and its post-build ABI report covered the 26.2.4 artifacts too); when that version matches none of them, as for a VCS PKGBUILD whose `pkgver()` rewrote a copy rather than this file, every scoped version is kept. This scoped set is returned **even when empty** — it never degrades to the full PKGDEST union: when the PKGBUILD parses cleanly and names its pkgnames but none match (the renamed-away case, absent a manifest), the caller fails loudly (`nothing to install`) rather than hand a shared PKGDEST of hundreds of unrelated packages to `pacman -U`. Only a PKGBUILD that yields *no* parseable pkgnames still degrades to the union (best-effort locate-everything), a case that fires solely with a local, unset `PKGDEST`. The manifest is deleted after a successful install so a later build in the same dir can't read a stale list.
+- `get_pkgdest()` / `get_builddir()` / `get_srcdest()` / `get_logdest()` — resolve the corresponding makepkg path variable via the shared `_resolve_makepkg_path(key)` helper, which mirrors makepkg's own precedence: **environment first** (`os.environ`), then the layered `parse_system_makepkg_conf()` (`/etc/makepkg.conf` → user conf), quotes stripped and `~`/`$VARS` expanded, else `None`. These are the single home for "where did makepkg put / read this?" — any new code that needs to *locate* a built artifact, build tree, downloaded source, or build log must call them rather than assuming `~/builds` / the PKGBUILD dir / a hardcoded default (a recurring bug class). `BUILDDIR` resolution in particular feeds `makepkg_env._effective_build_dir` (side-car log diagnosis) and `kernel.resolve_built_config` (resolved `.config` discovery), both of which must honour a `BUILDDIR` set only in `/etc/makepkg.conf`. `PKGDEST` resolution feeds `makepkg_wrapper._find_artifacts` (the union-of-`PKGDEST`-and-PKGBUILD-dir locator behind `install_built_packages` + the post-build ABI report) and `build_core`'s artifact snapshot — so a non-default `PKGDEST` doesn't strand the install/ABI scan looking in the PKGBUILD dir. `install_built_packages` wraps that locator in `_artifacts_for_pkgbuild`, which scopes the union in two tiers. **Preferred:** a build-time manifest (`_BUILT_MANIFEST_NAME`, `.sysforge-built.list`) — the exact package basenames `makepkg --packagelist` emitted, recorded by `_capture_built_manifest` on build success *while the patched `PKGBUILD.sysforge` is still present* — is matched exactly. Recorded for any **name-affecting** build: one that applies an extracted profile **or** a rename (kernel local-rename / `-sysforge` suffix); a rename is exactly the case pkgname scoping can't recover (2.5.1-B3 — a rename-only kernel previously recorded no manifest because capture was gated on the extracted profile alone). This is the only reliable scope for a **renamed** build (e.g. a `-sysforge` kernel): by install time the patched PKGBUILD is cleaned up, leaving only the upstream PKGBUILD whose pkgname (`linux`) prefix-matches unrelated (`linux-custom`, `linux-steam-integration`) and stale-version (`linux-sysforge-<oldver>`) artifacts — the pre-B9 bug that swept those into `pacman -U` and could downgrade the running kernel. **Fallback** (no manifest, or none of its entries are present): scope by the PKGBUILD's own pkgnames (filename-matched via `_parse_built_pkg_filename`, which anchors on the exact `<pkgname>-` prefix **and** requires a valid `[epoch:]pkgver-pkgrel-arch` tail — three hyphen-delimited fields, since `PKGBUILD(5)` forbids hyphens in pkgver/pkgrel/arch — so pkgname `linux` no longer matches `linux-custom` et al., 2.5.1-B3). Within that set it keeps only the artifacts at the PKGBUILD's own `epoch:pkgver-pkgrel` (`_pkgbuild_version`), so an older build of the same pkgnames still in PKGDEST is not reported or installed as this build's output (`3.5.0-B21`: every build without a rename or extracted profile records no manifest, sandboxed mesa 26.2.5 included, and its post-build ABI report covered the 26.2.4 artifacts too); when that version matches none of them, as for a VCS PKGBUILD whose `pkgver()` rewrote a copy rather than this file, every scoped version is kept. This scoped set is returned **even when empty** — it never degrades to the full PKGDEST union: when the PKGBUILD parses cleanly and names its pkgnames but none match (the renamed-away case, absent a manifest), the caller fails loudly (`nothing to install`) rather than hand a shared PKGDEST of hundreds of unrelated packages to `pacman -U`. Only a PKGBUILD that yields *no* parseable pkgnames still degrades to the union (best-effort locate-everything), a case that fires solely with a local, unset `PKGDEST`. The manifest is deleted after a successful install so a later build in the same dir can't read a stale list.
 - `snapshot_pkg_dir(pkgdest)` — records the set of `.pkg.tar.*` files currently in pkgdest before a build
 - `batch_install_pkgs(pkg_paths, *, interactive=False, allow_break_deps=frozenset(), conflicts_out=None) -> bool` — installs the given artifacts in a single `sudo pacman -U`. An interactive run goes through `run_logged_transaction` (pty, stdin inherited so the conflict prompt works, every line teed into the run log, failed-hook lines raised to `warn()`; a failure logs the captured tail, superseding the old "output went to the terminal" note, `3.3.0-B21`); a non-interactive run keeps capturing stderr, which the file-conflict isolation needs. It never retries itself (the toolchain rollback wants all-or-nothing); with `conflicts_out`, a refused non-interactive transaction's file-conflict culprits (`file_conflict_culprits(stderr)` → `{pkgname: ["<path> exists in filesystem…"]}`) are handed back so the caller can retry without them (3.2.0-B33, consumed by `build_core.install_built`)
 - `read_pkgname_from_file(path)` — extracts `pkgname` from a built `.pkg.tar.*` via `bsdtar -xOqf <path> .PKGINFO`; returns `None` on failure
@@ -2242,7 +2262,7 @@ Sole entry point for inspecting LLVM-toolchain source trees before a command tou
 
 Public API: `is_llvm_in_scope(pkgnames)`, `collect_llvm_state(pkgnames, config, *, probe_fetch=False, offline=False)`, `is_actionable_state(state)`, `render_preflight(report, *, verbose=False)`, `evaluate_strict(report, *, allow_dirty=False)`. Read-only — never clones, never mutates. PKGBUILD resolution mirrors steps 1-3 of `config.find_pkgbuild` without the auto-clone branch.
 
-Wiring: `fetch` / `update` / `build` render the report informationally, unless `preflight_suppressed(args)` says otherwise: `--no-llvm-preflight` wins, else `[safety] llvm_preflight = false`, resolved through `config.resolve_flag_default` with the key negated (`3.5.0-B110`; the key used to be documented but unread). `render_preflight` shows only **actionable** rows (`is_actionable_state`): a row is worth printing when it has an active concern (dirty / diverged / PGO profdata-mismatch), was built locally (`install_origin == "foreign"`), or sysforge intends to build it from source (any non-`pacman` build_mode). A repo-origin package installed from the binary repo with no source build_mode has every source-state column empty/`unknown`, so its row is dropped (it would otherwise read as noise); when every row is non-actionable the whole block collapses to nothing. `--verbose` overrides the filter and renders every row. The filter is display-only — `evaluate_strict` still sees the full state set, so the `run toolchain` blocker path is unchanged. `run toolchain` calls `evaluate_strict` after `_resolve_all_pkgbuilds` and refuses-by-default on dirty or diverged trees; bypass per-run with `--allow-dirty-llvm`, or actually overwrite the local trees with `--cleansrc-force` (which uses the new dirty classifier so trees in the `diverged_upstream` state — upstream force-pushed, no local commits authored by the local git user — are reported as clean and don't even need the bypass). The dirty-reason string distinguishes `"N commits ahead of upstream"` (`ahead`, real unpushed work) from `"diverged from upstream (N local / M upstream)"` (`diverged_user`, the histories have a common ancestor but the local user authored at least one commit on the local side). PGO profdata version mismatches are never bypassable — building against stale profdata silently corrupts the output.
+Wiring: `fetch` / `update` / `build` render the report informationally, unless `preflight_suppressed(args)` says otherwise: `--no-llvm-preflight` wins, else `[safety] llvm_preflight = false`, resolved through `config.resolve_flag_default` with the key negated (`3.5.0-B110`; the key used to be documented but unread). `render_preflight` shows only **actionable** rows (`is_actionable_state`): a row is worth printing when it has an active concern (dirty / diverged / PGO profdata-mismatch), was built locally (`install_origin == "foreign"`), or sysforge intends to build it from source (any non-`pacman` build_mode). A repo-origin package installed from the binary repo with no source build_mode has every source-state column empty/`unknown`, so its row is dropped (it would otherwise read as noise); when every row is non-actionable the whole block collapses to nothing. `--verbose` overrides the filter and renders every row. The filter is display-only — `evaluate_strict` still sees the full state set, so the `run toolchain` blocker path is unchanged. `run toolchain` calls `evaluate_strict` after `resolve_all_pkgbuilds` and refuses-by-default on dirty or diverged trees; bypass per-run with `--allow-dirty-llvm`, or actually overwrite the local trees with `--cleansrc-force` (which uses the new dirty classifier so trees in the `diverged_upstream` state — upstream force-pushed, no local commits authored by the local git user — are reported as clean and don't even need the bypass). The dirty-reason string distinguishes `"N commits ahead of upstream"` (`ahead`, real unpushed work) from `"diverged from upstream (N local / M upstream)"` (`diverged_user`, the histories have a common ancestor but the local user authored at least one commit on the local side). PGO profdata version mismatches are never bypassable — building against stale profdata silently corrupts the output.
 
 Reuses (do not duplicate from caller code): `pkgbuild_patcher.is_llvm_pkgbase`, `aur.git_is_dirty`, `aur.git_fetch_and_compare`, `source_meta.SourceMetaCache.get`, `pkgbuild_meta.parse_pkgbuild`, `version.format_version`, `pacman.get_foreign_packages` / `get_installed_version`, `profile.match_rules` / `get_build_mode`, `makepkg_wrapper._resolve_pgo_state`. Log tag: `[LLVM]`.
 
@@ -2440,13 +2460,13 @@ AUR RPC queries, package source detection, git/pkgctl clone helpers, and GPG key
 - `aur_clone(name, dest, *, ref=None, depth=None)` — `git clone https://aur.archlinux.org/<name>.git <dest>`; optional `ref` / `depth` support shallow / branch-pinned clones. Raises `RuntimeError` on failure.
 - `git_fetch_and_compare(pkgbuild_dir, *, timeout=30, limiter=None, is_vcs=False)` — **full-history** fetch of the tracked upstream (`git fetch <remote> <branch>`, adding `--unshallow` when the repo is shallow) followed by a HEAD compare, then an `--ff-only` merge when HEAD is an ancestor of `FETCH_HEAD`. A `--depth=1` fetch is deliberately *not* used: it grafts the fetched tip as a parent-less root (and marks the repo shallow), which makes the `merge-base --is-ancestor` check — and the `rev-list` counts in `classify_head_vs_upstream` — see no shared history, so every routine upstream advance would falsely report `diverged`. Packaging repos carry only PKGBUILD/metadata, so a full fetch is cheap. **Non-destructive**: never runs a reset/rebase; returns a `GitFetchOutcome(status, head_before, head_after, error)` where `status ∈ {"up_to_date", "fetched", "diverged", "failed", "skipped_no_tracking"}`. Divergence (a genuine non-fast-forward — local commits or a force-push upstream) is reported, not auto-recovered here — the scheduler decides whether to reset (see `source_sync.py`). Honours the limiter's `wait_before_fetch()` / `Retry-After` budget when supplied. `is_vcs` (threaded from `source_sync.is_vcs_pkgbase(pkgbase)`, and from `llvm_state` for the same reason) governs **only the operator-facing message** on the dirty-tree branch: a `-git` checkout whose sole working-tree change is makepkg's `pkgver()` auto-bump plus the regenerated `.SRCINFO` is a build artifact, not operator work, so the `WARN … working tree has local modifications` is downgraded to an `INFO` noting the caller will reset. The fast-forward gate itself stays VCS-blind on purpose: `git merge --ff-only` aborts against a dirty tree whenever the upstream commit also touched `PKGBUILD` (the common AUR case), which would return `failed` — a scheduler blocker — where `diverged` is the outcome `source_sync`'s clean-tree hard-reset already heals correctly.
 - `is_transient_git_error(stderr)` / `is_rate_limit_error(stderr)` — shared stderr classifiers used by both the scheduler and legacy retry paths.
-- `_classify_head_vs_upstream(pkgbuild_dir)` — single classifier consumed by both `git_is_dirty` and `llvm_state._dirty_reason`. Returns `(state, n_local, n_upstream)` where `state ∈ {"not_a_repo", "no_head", "no_tracking", "clean", "behind", "ahead", "diverged_user", "diverged_upstream"}`. The two `diverged_*` states distinguish "upstream rewrote history (force-push), no local commits authored by the local git user" (`diverged_upstream` → not dirty) from "HEAD and upstream have a common ancestor but at least one of HEAD's divergent commits is authored **or committed** by the local user" (the committer check keeps a `git am`-applied or cherry-picked patch with a foreign author, `3.5.0-B69`) (`diverged_user` → dirty). The local user identity is read from `git -C <dir> config user.email` (with global fallback). `ahead` = HEAD is a strict descendant of upstream; `behind` = HEAD is an ancestor of upstream (the only "out of date but clean" case).
+- `classify_head_vs_upstream(pkgbuild_dir)` — single classifier consumed by both `git_is_dirty` and `llvm_state._dirty_reason`. Returns `(state, n_local, n_upstream)` where `state ∈ {"not_a_repo", "no_head", "no_tracking", "clean", "behind", "ahead", "diverged_user", "diverged_upstream"}`. The two `diverged_*` states distinguish "upstream rewrote history (force-push), no local commits authored by the local git user" (`diverged_upstream` → not dirty) from "HEAD and upstream have a common ancestor but at least one of HEAD's divergent commits is authored **or committed** by the local user" (the committer check keeps a `git am`-applied or cherry-picked patch with a foreign author, `3.5.0-B69`) (`diverged_user` → dirty). The local user identity is read from `git -C <dir> config user.email` (with global fallback). `ahead` = HEAD is a strict descendant of upstream; `behind` = HEAD is an ancestor of upstream (the only "out of date but clean" case).
 - `git_is_dirty(pkgbuild_dir, *, is_vcs=False)` — wrapper over the classifier: returns `True` for `no_tracking`, `ahead`, `diverged_user` (plus uncommitted tracked changes detected separately via `git status`); returns `False` for `clean`, `behind`, `no_head`, `not_a_repo`, `diverged_upstream`. Untracked files (build artifacts) are intentionally ignored. The `diverged_upstream` exemption fixes the false-positive on workstations whose Arch packaging clones get force-pushed every release. **`is_vcs=True`** (passed for `-git`/`-svn`/`-hg`/`-bzr` packaging repos) additionally filters out makepkg's `pkgver()` churn from the uncommitted-tracked check: a PKGBUILD whose diff against `HEAD` (not the index, so a staged edit still shows — `3.5.0-B38`) is restricted to `pkgver=`/`pkgrel=` lines (the auto-bump), and **any** change to the generated `.SRCINFO` (treated as a build artifact — `pkgver()` rewrites its version-pinned `depends`/`provides` lines too, so a line-level filter can't distinguish a mechanical bump from a real edit; deliberate edits live in PKGBUILD, which is still checked). Deliberate edits to other PKGBUILD lines / other tracked files still count as dirty.
-- `purge_src(pkgbuild_dir, *, force=False, is_vcs=False)` — `rm -rf` the directory after a `git_is_dirty` safety check. Raises `RuntimeError` if the clone holds local work that would be destroyed; non-git directories are purged unconditionally; non-existent paths are a silent no-op. `force=True` skips the dirty check and purges unconditionally — used by the `--cleansrc-force` CLI path. Used by `sysforge build --cleansrc[/-force]`, `sysforge update --cleansrc[/-force]`, `sysforge fetch --cleansrc[/-force]`, `sysforge run toolchain --cleansrc[/-force]`, and the source-sync recovery paths. **Detached-HEAD fix:** a `source = "repo"` checkout pinned to a release tag (see `source_sync.py` below) sits on a detached HEAD with no `@{u}` tracking branch — the pre-pin refusal logic treated that shape identically to a genuine local-only repo and refused to purge it. The refusal check (`_purge_refusal_message`) now calls `_head_reachable_from_remote` (`git branch -r --contains HEAD`) before citing "no upstream tracking branch": a detached HEAD that is still reachable from some remote branch is upstream's own history, not local-only work, and does not block the purge; a genuinely local-only commit (unreachable from any remote ref) still refuses.
+- `purge_src(pkgbuild_dir, *, force=False, is_vcs=False)` — `rm -rf` the directory after a `git_is_dirty` safety check. Raises `RuntimeError` if the clone holds local work that would be destroyed; non-git directories are purged unconditionally; non-existent paths are a silent no-op. `force=True` skips the dirty check and purges unconditionally — used by the `--cleansrc-force` CLI path. Used by `sysforge build --cleansrc[/-force]`, `sysforge update --cleansrc[/-force]`, `sysforge fetch --cleansrc[/-force]`, `sysforge run toolchain --cleansrc[/-force]`, and the source-sync recovery paths. **Detached-HEAD fix:** a `source = "repo"` checkout pinned to a release tag (see `source_sync.py` below) sits on a detached HEAD with no `@{u}` tracking branch — the pre-pin refusal logic treated that shape identically to a genuine local-only repo and refused to purge it. The refusal check (`_purge_refusal_message`) now calls `head_reachable_from_remote` (`git branch -r --contains HEAD`) before citing "no upstream tracking branch": a detached HEAD that is still reachable from some remote branch is upstream's own history, not local-only work, and does not block the purge; a genuinely local-only commit (unreachable from any remote ref) still refuses.
 - `purge_srcdest(pkgbase, srcdest_dir, *, pkgbuild_dir=None)` — companion to `purge_src` for `--cleansrc`: the checkout rmtree never touched makepkg's `SRCDEST` tarball cache, so a purged-and-re-cloned package could still rebuild against a stale cached source tarball instead of the freshly re-pinned/re-cloned tree. Deletes `<pkgbase>-<digit…>*` entries (matching makepkg's `name-version.ext` tarball naming, so a dash-prefixed sibling pkgbase like `foo-tools` is never clobbered by a `foo` purge) from `srcdest_dir`. No-ops when `srcdest_dir` is unset/missing, or resolves inside `pkgbuild_dir` (the makepkg-default layout, already covered by the checkout rmtree). Best-effort hygiene, not a safety gate: no dirty-tree guard, no force flag, failures warn and never raise. Returns the count removed. Called from both `SourceSyncScheduler` cleansrc branches (the explicit `--cleansrc` purge and the missing-PKGBUILD recovery purge) alongside `purge_src`.
 - `pkgctl_checkout(name, dest, *, timeout=60)` — `pkgctl repo clone --protocol=https <name>` run in `dest.parent`; fetches official Arch packaging repo. Output is streamed line-by-line to `_build_log.debug` so progress is visible at `-vvv` (cloning from gitlab.archlinux.org can take minutes on a fresh checkout). Raises `RuntimeError` on failure or timeout. `find_pkgbuild` passes `[git] clone_timeout` from `sysforge.toml`; `0` disables.
 - `pkgctl_switch_version(dest, version, *, timeout=60)` — `pkgctl repo switch <version>` run inside an existing `pkgctl_checkout` clone; `pkgctl` owns the pacman-version → git-tag translation (epoch and pkgrel included), so callers pass `pacman.get_repo_candidate_version()` output verbatim. Leaves the checkout on a detached HEAD at the tag. Raises `RuntimeError` on failure or timeout (including a missing `pkgctl` binary — hints at `devtools`). Sole caller: `source_sync.SourceSyncScheduler._pin_repo_checkout` (see below).
-- `import_pgp_keys(pkgmeta, pkgbuild_path)` — ensures all `validpgpkeys` listed in the PKGBUILD are in the GPG keyring before `makepkg` runs. Strategy: (1) import any bundled `.asc` files from `keys/pgp/` alongside the PKGBUILD, (2) check which keys are still missing via `gpg --list-keys`, (3) fetch remaining via `fetch_pgp_keys` — the **one home for keyserver fetches** (`3.1.0-F8`; `auto_repair`'s PGP repair routes through it too). `validpgpkeys` exists so a person decides who the upstream signer is, so the fetch: is its own egress kind (`net_policy.KIND_KEY_FETCH`), so `freeze_sources` covers it and a frozen run raises `NetworkFrozen` (the package fails with the `--thaw` hint; the batch continues); lands in a throwaway `GNUPGHOME` first, then prints each key's fingerprint, primary uid and the requesting pkgbase (`ui()`) before anything touches the real keyring; and imports (`--export` from the throwaway home → `--import`) only after a TTY confirmation (`primitives/prompt.py`, default No). A non-interactive run fails closed — nothing imported, an error naming the fingerprints and the manual `gpg --recv-keys` — unless `[security] auto_fetch_pgp_keys = true` (installed once by `cli.main` via `set_key_fetch_policy`) restores unattended imports, still echoed. Bundled-key import and the keyring check are unaffected. Other import failures are logged as warnings — makepkg surfaces a clearer error if a key is still absent at verification time.
+- `import_pgp_keys(pkgmeta, pkgbuild_path)` — ensures all `validpgpkeys` listed in the PKGBUILD are in the GPG keyring before `makepkg` runs. Strategy: (1) import any bundled `.asc` files from `<pkgbuild dir>/keys/pgp/`, (2) check which keys are still missing via `gpg --list-keys`, (3) fetch remaining via `fetch_pgp_keys` — the **one home for keyserver fetches** (`3.1.0-F8`; `auto_repair`'s PGP repair routes through it too). `validpgpkeys` exists so a person decides who the upstream signer is, so the fetch: is its own egress kind (`net_policy.KIND_KEY_FETCH`), so `freeze_sources` covers it and a frozen run raises `NetworkFrozen` (the package fails with the `--thaw` hint; the batch continues); lands in a throwaway `GNUPGHOME` first, then prints each key's fingerprint, primary uid and the requesting pkgbase (`ui()`) before anything touches the real keyring; and imports (`--export` from the throwaway home → `--import`) only after a TTY confirmation (`primitives/prompt.py`, default No). A non-interactive run fails closed — nothing imported, an error naming the fingerprints and the manual `gpg --recv-keys` — unless `[security] auto_fetch_pgp_keys = true` (installed once by `cli.main` via `set_key_fetch_policy`) restores unattended imports, still echoed. Bundled-key import and the keyring check are unaffected. Other import failures are logged as warnings — makepkg surfaces a clearer error if a key is still absent at verification time.
 - `fetch_aur_name_cache(force=False)` — downloads `https://aur.archlinux.org/packages.gz` and extracts it to `$XDG_CACHE_HOME/sysforge/aur-packages.txt` (default `~/.cache/sysforge/aur-packages.txt`). Skips the download if the cache is less than 24 hours old unless `force=True`. Called as a side effect of `sysforge update`; read by `sysforge completions packages` to provide AUR package name completion.
 
 `sysforge completions packages` — outputs local pkgbuild_src_dir packages + pacman sync DB names + AUR cache. Used by both completion scripts for `build`, `packages add`. The merged list (~140k names) is cached in `$XDG_CACHE_HOME/sysforge/completion-packages.txt` (`completions_data.PACKAGES_CACHE`); its first line is a key of every input's mtime (each `/var/lib/pacman/sync/*.db`, the AUR name list, `pkgbuild_src_dir`), so the list is rebuilt, and `pacman -Ssq` run, only after one of them changes, and a fresh cache costs one file read. The scripts pass `--prefix=<typed text> --limit=<cap + 1>`, so sysforge filters and caps the list itself rather than piping every name through `grep`; zsh shows a `zle -M` message when the cap is exceeded. `--prefix`/`--limit` apply to every resource.
@@ -3825,7 +3845,7 @@ tools/gen_options.py --template man/sysforge.1.scd.in --out man/sysforge.1.scd
 scdoc < man/sysforge.1.scd > man/sysforge.1
 ```
 
-- **`man/sysforge.1.scd.in`** (committed) — hand-written NAME / SYNOPSIS / DESCRIPTION / GLOBAL OPTIONS / FILES / ENVIRONMENT / EXIT STATUS / EXAMPLES / SEE ALSO / AUTHORS prose, with an `@OPTIONS@` marker where the generated COMMANDS sections splice in and an `@SHARED_OPTIONS@` marker under a hand-written SHARED OPTIONS heading. The template stays short: a config key's reference text lives in the shipped config file's own comments (FILES says so), and DESCRIPTION gives an overview without repeating any command's options. scdoc syntax gotcha: indented continuation lines must not start with a table-control character (`[`, `|`, `]`) — scdoc errors with "Tables cannot be indented".
+- **`man/sysforge.1.scd.in`** (committed) — hand-written NAME / SYNOPSIS / DESCRIPTION / GLOBAL OPTIONS / FILES / EXIT STATUS / EXAMPLES / SEE ALSO / AUTHORS prose, with an `@OPTIONS@` marker where the generated COMMANDS sections splice in and an `@SHARED_OPTIONS@` marker under a hand-written SHARED OPTIONS heading. The ENVIRONMENT and JOURNAL bodies are generated too, from `@ENVIRONMENT@` (`primitives/env_vars.ENV_VARS`, user settings then diagnostic switches, `3.5.0-B128`) and `@JOURNAL@` (`primitives/journal.JOURNAL_FIELDS`, `3.5.0-DOC13`); `tests/test_env_vars.py` fails on a `SYSFORGE_*` name the code uses that neither table lists, and on a listed variable nothing reads. `gen_options._wrap` keeps a word starting with `[`, `|` or `-` off the start of a line, since scdoc reads one there as a table or list. The template stays short: a config key's reference text lives in the shipped config file's own comments (FILES says so), and DESCRIPTION gives an overview without repeating any command's options. scdoc syntax gotcha: indented continuation lines must not start with a table-control character (`[`, `|`, `]`) — scdoc errors with "Tables cannot be indented".
 - **`tools/gen_options.py`** — walks `verbs.registry.build_parser()`'s subparser tree depth-first (so `packages add`, `run kernel`, etc. each get a `## <name>` section) — top-level commands ordered by `verbs.registry.tiered_command_order()` so the COMMANDS sections stay in lockstep with the `sysforge --help` usage tiers (§CLI Verb Framework), sub-commands in registration order — emits a synopsis line plus one definition block per positional/option (a value placeholder is the metavar, else the choices as `_a_|_b_`, matching `--help`), escapes scdoc formatting characters in help text, and performs the splice itself (no sed). Subparsers registered without `help=` (the internal `completions` data sink) are excluded. **Shared options** (`_shared_options`): an option two or more commands carry with the same head *and* the same help text is written once under SHARED OPTIONS, with a `Used by:` line, and each of those commands lists it in a `*Shared options:*` line instead of repeating the block. A flag whose help differs between commands shares only its most common text (first-seen on a tie) and the others stay inline, so SHARED OPTIONS never lists a flag twice. Sharing is keyed on identical text, so wording drift between verbs shows up as an inline duplicate: give a flag that means the same everywhere one help constant (`verbs.helpers.PACKAGES_FILE_HELP`, `CLEANSRC_FORCE_HELP`). Each command section also gets a `*Configuration:*` / `*Environment:*` trailer from the hand-maintained `_VERB_CONFIG` dict at the top of the script (qualified command name → config files / env vars consumed; commands without an entry get no trailer). The FILES and ENVIRONMENT sections of the template carry the inverse index ("Read by: …") — when a verb gains or loses a config source, update both `_VERB_CONFIG` and the template. The trailer is man-page-only by design: it is not wired into argparse epilogs, so it never appears in `--help` output (which has its own tiered `COMMAND` grouping — §CLI Verb Framework).
 - **`man/sysforge.1.scd`** — intermediate, gitignored. **`man/sysforge.1`** — committed, so AUR-built tarballs ship the page without build-time tooling; the PKGBUILD `package()` installs the committed file directly and needs no man-page makedepend.
 - Makefile target: `make man` (pins `COLUMNS=80` so any argparse-derived wrapping is deterministic). `scdoc` is a dev-machine dependency only (the `DEV_DEPS_CORE` set, installed by `make dev-deps` / `make dev`); `python-argparse-manpage` is no longer used anywhere.
@@ -3912,7 +3932,7 @@ In addition to the positive `=y` enables above, the hardware stage emits an `=n`
 
 `_arch_disable_kconfig(host_arch)` resolves the host domain, then iterates every *other* domain in the registry and emits `{CONFIG_X: "n"}`. Keys appearing in the host's own domain set are filtered out as a defensive guard (no clobber if a future kconfig key gains a presence in multiple domains). Unknown `host_arch` returns an empty dict and logs a WARN.
 
-The `=n` entries land in the same `[kconfig]` table as the existing `=y` enables, so the kernel stage's existing merge path — `merged = {**device_kconfig, **hw_kconfig, **manual_kconfig}` — applies unchanged. A user cross-compiling or otherwise wanting an arch-disabled key re-enabled puts an explicit `[[kconfig]] option = "CONFIG_ARM64" value = "y"` in `kernel.toml`; the existing manual-override-wins-with-WARN behaviour in `_write_kconfig_fragment` extends to arch-disable entries.
+The `=n` entries land in the same `[kconfig]` table as the existing `=y` enables, so the kernel stage's existing merge path — `merged = {**device_kconfig, **hw_kconfig, **manual_kconfig}` — applies unchanged. A user cross-compiling or otherwise wanting an arch-disabled key re-enabled puts an explicit `[[kconfig]] option = "CONFIG_ARM64" value = "y"` in `kernel.toml`; the existing manual-override-wins-with-WARN behaviour in `write_kconfig_fragment` extends to arch-disable entries.
 
 ### Device-driven kconfig (`[kconfig_devices]`)
 
@@ -3931,7 +3951,7 @@ Design ambition is broad (every kconfig domain in the registry, every CPU/GPU br
 - Storage: NVMe
 - Distro: Arch Linux, kernel: custom `linux-custom` PKGBUILD
 
-**Tested in VM** (`make vm-iso` → `make vm-install`):
+**Tested in VM** (`make vm-iso` → `make vm-install-stable`):
 - Host arch: `x86_64` (qemu/KVM guest)
 - CPU: emulated/passthrough (typically host-passthrough)
 - GPU: virtio (`gpu_vendors` likely empty or `["other"]`)
@@ -3987,7 +4007,7 @@ Cache probe uses `ccache --print-stats --format=tab` (ccache ≥ 4.0, standard o
 
 ### Toolchain fingerprint tracking
 
-SysForge tracks a toolchain fingerprint (hash of compiler path + version) in its state dir. On mismatch (e.g. after LLVM version bump), `invalidate_on_toolchain_change` fires: `warn` (default) / `purge` / `ignore`.
+There is no cache-invalidation setting. Each source build records the toolchain that built it in `build_state.toml` (`toolchain_variant`, `toolchain_fingerprint`), and `sysforge update` reports a package built by a different or rebuilt toolchain as toolchain drift (§Drift detection), rebuilding it with `--rebuild-on-toolchain-drift`. The compile caches need nothing from sysforge here: ccache and sccache key their entries on the compiler itself, so a toolchain change misses rather than reusing objects from the old compiler.
 
 ---
 
@@ -4016,7 +4036,7 @@ Build in this order to satisfy dependencies correctly:
 - **Target-init drop (unhealable).** A dropped LLVM backend (e.g. a reduced `LLVM_TARGETS_TO_BUILD` without `AMDGPU`). The symbol would not exist anywhere — rebuilding the consumer cannot recover it. Gate 2 hard-aborts before install; the AMDGPU baseline is the real fix. **Unchanged behaviour.**
 - **`std::` re-export drop (healable).** A drop of *only* non-target-init `LLVM_*`-versioned symbols. These are libstdc++ `std::__cxx11::basic_string` methods that LLVM's `global: *` version script globs into the `LLVM_<ver>` node as out-of-line weak copies. The official `llvm-libs` exports them; mesa links them as `…@LLVM_<ver>`. A PGO (`-fprofile-use`) `libLLVM` **inlines those weak copies away**, so the optimized lib — *at the same soname* — no longer exports them and mesa is stranded. This is healable: rebuilding mesa against the new `libLLVM` re-links the symbols to libstdc++ (`@GLIBCXX_*`), exactly as a distro does on an llvm rebump.
 
-For the healable class Gate 2 does **not** abort. It captures the installed libLLVM consumers via `toolchain_safety.libllvm_abi_consumers` (the reverse-dep `%DEPENDS%` walk factored out of `assess_libllvm_soname_impact` into `libllvm_soname_consumers`, here **not** gated on a soname change) and rebuilds them after Gate 3 through the same `_rebuild_soname_consumers` path used for a soname bump — gated by the existing `rebuild_soname_consumers` mode (`prompt` default | `auto` | `off`). Gate 3 tolerates the healable miss (mesa is not rebuilt until *after* Gate 3, so a rollback there would revert the very libLLVM the rebuild is about to make coherent); only target-init misses still trip the auto-rollback. The system self-stabilises: once mesa links the optimized libLLVM it stops importing the `…@LLVM_<ver>` `std::` symbols, so a subsequent `run toolchain` sees no stranding and queues no rebuild. Note `assess_libllvm_soname_impact` still short-circuits on a same-version (`old_mm == target_mm`) refresh — the std:: drift is owned by this Gate-2/3 + `libllvm_abi_consumers` path, not the soname-bump gate. Since `3.5.0-F4` the toolchain's libLLVM re-exports the members stock libLLVM did, as non-default-versioned thunks (§Pipeline layer → Gate 2), so a stock-linked mesa no longer strands on them; the healable path remains for any export outside that table, which Gate 2 names.
+For the healable class Gate 2 does **not** abort. It captures the installed libLLVM consumers via `toolchain_safety.libllvm_abi_consumers` (the reverse-dep `%DEPENDS%` walk factored out of `assess_libllvm_soname_impact` into `libllvm_soname_consumers`, here **not** gated on a soname change) and rebuilds them after Gate 3 through the same `rebuild_soname_consumers` path used for a soname bump — gated by the existing `rebuild_soname_consumers` mode (`prompt` default | `auto` | `off`). Gate 3 tolerates the healable miss (mesa is not rebuilt until *after* Gate 3, so a rollback there would revert the very libLLVM the rebuild is about to make coherent); only target-init misses still trip the auto-rollback. The system self-stabilises: once mesa links the optimized libLLVM it stops importing the `…@LLVM_<ver>` `std::` symbols, so a subsequent `run toolchain` sees no stranding and queues no rebuild. Note `assess_libllvm_soname_impact` still short-circuits on a same-version (`old_mm == target_mm`) refresh — the std:: drift is owned by this Gate-2/3 + `libllvm_abi_consumers` path, not the soname-bump gate. Since `3.5.0-F4` the toolchain's libLLVM re-exports the members stock libLLVM did, as non-default-versioned thunks (§Pipeline layer → Gate 2), so a stock-linked mesa no longer strands on them; the healable path remains for any export outside that table, which Gate 2 names.
 
 ---
 
@@ -4078,8 +4098,8 @@ the gates — they need a booted VM or a working podman and network, neither of
 prerequisite of a lint run — but a minor or major release that skips them is untested against a
 real install. See `tools/vm/README.md` and `tools/container/README.md`.
 
-**CI** (`.github/workflows/ci.yml`, `3.4.0-DEV1`) runs every `pre-release` gate on every push and
-pull request in a fresh `archlinux:base-devel` container, as an unprivileged user, with only the
+**CI** (`.github/workflows/ci.yml`, `3.4.0-DEV1`) runs every `pre-release` gate on each pull request (a newer push to
+it cancels the superseded run) and on each push to `main`, in a fresh `archlinux:base-devel` container, as an unprivileged user, with only the
 core dev tier (`make dev-deps-core`) installed. Its job is
 to catch a test or gate that passes only because of the workstation (clang-forced shell, live
 config, installed extras, one hardware profile); it is not a release gate and holds no signing key.
@@ -4093,8 +4113,9 @@ report (`tools/junit_annotate.py`, `3.5.0-DEV6`). It opens with the container's
 (package count, LLVM and `tomlkit` presence, Python, pytest and uv versions) so a CI-only failure
 compares against the local machine (`3.5.0-DEV7`).
 The job body is `tools/ci.sh`, and `make ci-local` replays it under podman against the working tree
-(read-only mount, `CI=true` set as on the runner), so a red run reproduces without a push. It stays
-advisory (no branch protection) until it has held green for one release cycle. Because it runs the
+(read-only mount, `CI=true` set as on the runner), so a red run reproduces without a push. Its `gates`
+job is a **required status check**: a ruleset on `main` requires pull requests and a green `gates`
+run before merge, so every check below binds every contributor, not only those who run it locally. Because it runs the
 `pre-release` set in a strictly cleaner environment, the checklist's static-gate stage uses `make
 ci-local`, with `pre-release` as the fallback where podman is unavailable.
 
@@ -4129,6 +4150,7 @@ The version markers in `README.md` and `DESIGN.md` wrap the single live version
 - **`pkgbuild_parity`** — `PKGBUILD` and `PKGBUILD-git` parse to the same dict (via `pkgbuild_meta.parse_pkgbuild`) except for a tightly-scoped allowlist of keys that are *supposed* to differ (`pkgname`, `pkgver`, `pkgrel`, `pkgdesc`, `source`, `sha256sums`, `conflicts`, `provides`, `validpgpkeys` — stable-only, since the VCS package has no release `.asc`). `depends` / `makedepends` / `optdepends` / `backup` arrays must be byte-identical, and both `package()` bodies must install the same set of targets (`_parse_pkgbuild_install_targets`), which is how a `pkgbuild`-group rule checked on the stable file, such as the license install, reaches `PKGBUILD-git`.
 - **`hooks`** — every `etc/pacman.d/hooks/sysforge-*.hook` `Exec` line must invoke `tools/pacman-hook-helper.sh` and pass a subcommand the helper documents (`kernel`, `toolchain`, `buildstate`).
 - **`completions`** — every verb and every long-flag in the argparse parser tree (reached via `sysforge.verbs.registry.build_parser`) must appear in both `completions/_sysforge` and `completions/sysforge.bash`; stale top-level verb entries in the zsh case statement (function-suffix matches case-word but parser doesn't know the verb) are an error. Mirrors the `completions-cli-parity` subagent's audit; this is the mechanical layer that runs every release.
+- **`completion_commands`** (`3.5.0-DEV14`) — `completions` only walked top-level commands, so after `3.5.0-F15` left group parents with no flags, no subcommand flag was checked at all, and a flag counted as present if it appeared anywhere in the file. This group checks each command where it is completed: its zsh function (`_sysforge_state_orphans`, description text excluded) and its bash `case` arm. Every long flag must be offered there, nothing the command lacks may be, every argparse `choices` value must be offered (bash keeps values in `_sysforge_flag_arg` keyed by flag, or in the command's own body), and lists copied from code constants (`_MIRRORED_LISTS`: the desktop catalog, `PROFILE_METHODS`) must equal them. Its first run found bash offering no values for `run toolchain --rebuild-soname-consumers` (`3.5.0-B127`).
 - **`completion_widths`** — every description in `completions/_sysforge` must fit an 80-column listing (`COMPLETION_TARGET_COLUMNS`). zsh renders a match as `<match><pad>  -- <description>`, padding the match column to the longest match in that generator call; once a row exceeds the terminal width zsh abandons the inline two-column table and emits every description as its own list entry, so the whole block renders with names and descriptions detached (the 3.0.0-B2 symptom). The budget is therefore per-call and shared: `COLUMNS - (longest match in the block) - 4`, computed separately for each `_arguments` spec list and each `_describe` array (`_completion_blocks`). One over-wide row degrades every row beside it, and adding a long *option name* to a verb tightens the budget for every *description* in it — `update` is the tightest block in the file at 48 characters, bounded by `--rebuild-on-toolchain-drift`. `completions/sysforge.bash` is not checked: it emits bare `compgen -W` word lists with no descriptions and cannot exhibit this failure.
 - **`versions`** — `pyproject.toml` `[project] version` must equal `PKGBUILD` `pkgver=`, the leading `X.Y.Z` of `PKGBUILD-git` `pkgver=`, and every `<!--version-->vX.Y.Z<!--/version-->` marker in `README.md` and `DESIGN.md` (literal `vX.Y.Z` placeholder strings in prose are filtered out by the `\d+\.\d+\.\d+` constraint).
 - **`manpage`** — regenerates `man/sysforge.1` via the scdoc-hybrid pipeline `make man` uses (`tools/gen_options.py` splices the argparse-derived COMMANDS sections into `man/sysforge.1.scd.in`, then `scdoc` renders) into temp files and diffs against the committed page; any difference is an error, with the fix `make man && git add man/sysforge.1`. Both sides are passed through `_normalize_roff` before diffing, so scdoc-version-specific artifacts aren't findings: the `.TH … "DATE"` header (daily date change), the `.\" Generated by scdoc <version>` banner, and hyphen escaping (`\-` vs `-`, functionally inert in roff). This keeps the gate coupled to the CLI surface rather than to the local scdoc build. Skipped with a `warn` if `scdoc` isn't on PATH. See the Man Pages section.
@@ -4137,10 +4159,14 @@ Findings default to hard fail (non-zero exit); pass `--warn` for a report-only m
 
 **Documentation consistency guards.** Large sweeps (renames, removals, moved sections) leave stale references behind in places no parser reads: prose, comments, completions. A guard per kind of reference:
 
+- **The surface snapshot** (`tools/surface.py`, `make surface` / `make check-surface`, `3.5.0-DEV18`) — `tests/data/surface.json` lists every user-facing surface: each command's flags and their allowed values, the environment variables and journal fields, each config file's sections and keys (open sections as `null`), each `--json` document's fields, and the run-log names. It is generated like `DESIGN.md`, so a surface change is one reviewable diff. The gate, which `pre-release`, CI and the release preflight all run, fails when the snapshot is stale, and compares it with the base (the merge-base with `main`, or on `main` the previous commit, since a squash merge lands as one): every added or removed entry must be named in text the change adds to `unreleased.md`, and a flag, command, environment variable or config key that leaves the product entirely must be registered as retired (`tools/retired_names.toml`, or `RETIRED_KEYS`). These are the two things the checks above could not see: a removal nobody registered, and a change with no release note. `CONTRIBUTING.md`'s surface table and `.github/pull_request_template.md` carry the same rules for human contributors, and `make install-hooks` adds a pre-commit hook (`tools/pre-commit.sh`) running the fast gates.
 - **`design_refs`** (`check_standards`, `3.5.0-DEV10`) — every `§Section` in `docs/design/`, both CLAUDE.md files and `sysforge/` code must name something that exists: a DESIGN.md heading or bold run-in lead, matched by word-prefix so `§CLI Verb` and `§Drift detection → *Toolchain drift*` resolve; a design file number or slug (`§07`, `§primitives-layer`); a design `.md` file; or a standards row. External citations (`RFC 7231 §7.1.3`, `§§6–8`) are skipped. Its first run found nine dangling references, among them six `§Reconvergence` (design 18's heading is *Drift detection*) and a `§1242–1264` that cited DESIGN.md line numbers.
 - **Written-down commands** (`tests/test_verb_registry.py`, `3.5.0-DEV11`, generalising `3.5.0-B3`'s doctor-only check) — every `sysforge …` in string literals, docstrings and comments under `sysforge/`, the README, both CLAUDE.md files, the man source, guides, concept pages and shipped config comments is walked through the real parser: each long flag must exist on its subcommand or be global (a flag's value is skipped), and an unknown word close to a real subcommand is a typo or a rename. Short flags are not judged (`build`/`update` pass makepkg's through), and a word that matches no subcommand is prose or a positional. Design docs, ROADMAP and release notes name old spellings on purpose and are not scanned.
 - **`retired_names`** (`check_standards`, `3.5.0-DEV12`) — `tools/retired_names.toml` lists names sysforge no longer has (each with the ID that retired it and what to use instead), and none may appear in a tracked file outside release notes, ROADMAP, tests (which check the old names are refused), the generated DESIGN.md and the entry's own `allow` list (the migration code that still reads an old value). Whole-word match, comments and completions included. Only names that cannot mean anything else are listed: a spelling still valid on another command (`--force`) or common in other tools (`--prune`) is left to the per-command check above. Its first run found design 08 citing a function `3.5.0-F17` removed, and standards row 24 still describing the deprecation record `3.5.0-F16` removed as live.
-- **Stand-ins** (`tests/test_stand_ins.py`, `3.5.0-DEV13`) — a `SimpleNamespace` in place of `BuildOptions`, `RunOptions` or a parsed command line breaks every test at once when the code reads a new field, and keeps passing on a renamed one. Tests build the real thing: both dataclasses default every field and reject unknown names, and `build_parser().parse_args([...])` has every flag. Options stand-ins (recognised by a field on the dataclass that is no CLI destination) are not allowed at all; argument stand-ins that predate the check sit in a shrinking per-file allowlist, so a new one fails and a converted file must lower its count.
+- **`citations`** (`check_standards`, `3.5.0-DEV15`) — the `claude_md` resolver, run over `docs/design/` and the tracked `.claude/` agents, skills and rules, which steer contributors and agents as much as CLAUDE.md does. It learned `path/module.symbol` citations, placeholders (`vX.Y.Z`), a symbol in any same-named module, and `make` targets (missing counts only as a near miss of one of ours, since the kernel's `make nconfig` is quoted on purpose); paths are checked only when their first segment is in the repo, and bare `.sh` names are skipped. A bare code name (private, snake case or camel case) with no module to resolve against must at least appear in a tracked non-doc file; names from other software and deliberate history are listed (`_CITATION_EXTERNAL`, `_CITATION_HISTORY`). That rule found 48 private names design 07 still used after the `3.2.0` split made them public, a removed editor prompt, and a cache setting design 15 described that never existed. Inline code is now paired per line with fenced blocks dropped (both groups): a ```` ``` ```` fence had paired with the next lone backtick and hidden a stale path. Its first run found, besides false positives, a design passage on the prompt module with a removed stage file, a removed function, inverted `eof_default` facts and per-file call counts that were all wrong, a symbol under the wrong module, `make vm-install`, and two `.claude` files citing a removed verb module and a test file that never existed.
+- **Concept pages** (`tests/test_concept_pages.py`, `3.5.0-DEV16`) — each page but the glossary closes with *Further reading* (at least one upstream link) then *In sysforge*, and nothing before *In sysforge* uses sysforge's own vocabulary (its name, its config files, `build_state`). Upstream tools' flags stay allowed, since they are the technique. The rest of the rule (no numbers measured on one machine) stays a review item.
+- **Flags reach the code** (`tests/test_flags_reach_code.py`, `3.5.0-DEV17`) — a field read on an options object (`options`, `opts`, ...; by attribute or `getattr` with a literal, method calls excluded) must be a `RunOptions` or `BuildOptions` field, since a missing one silently returns its default: the shape of `3.5.0-B129`, which this reports on the pre-fix code. And every command's parsed flag must be read through its argument object (`args.x`, `run.args.x`, `getattr(args, "x")`, `resolve_flag_default(args, "x")`) somewhere in the package, except the namespace dispatch fields and two indirect readers named in the test (doctor's `_AXIS_FLAGS`, pinned to the axis flags exactly, and `PKG_KEY_BUILD_FROM_SOURCE`). With `test_every_run_stage_flag_reaches_the_stage` this covers the hop from parsed arguments to the options a stage reads.
+- **Stand-ins** (`tests/test_stand_ins.py`, `3.5.0-DEV13`) — a `SimpleNamespace` in place of `BuildOptions`, `RunOptions` or a parsed command line breaks every test at once when the code reads a new field, and keeps passing on a renamed one. Tests build the real thing: both dataclasses default every field and reject unknown names, and `tests/cli_args.cli_args(*argv, **fields)` parses a real command line, then sets fields the command has (a name it lacks fails). Options stand-ins (a field on the dataclass that is no CLI destination) are refused; argument stand-ins (fields all one command's flags) may appear only in `_ARGS_STAND_INS`, which is empty and pinned so (`test_stand_in_allowlist_is_empty`); its last entry tested a `getattr` fallback in `make_build_options` no caller needed, and both went. Converting the 31 others found `run kernel --keep-hotplug-drivers` parsed and dropped (`3.5.0-B129`, now guarded by `test_every_run_stage_flag_reaches_the_stage`) and sentinel-gate tests exercising `build --dry-run` and `setup --dry-run`, which do not exist.
 
 **Clean chroot validation.** The release gate catches underspecified `depends`/`makedepends` that a host build would silently accept because the dep is already installed. It uses `makechrootpkg` from `devtools` and is a hard prerequisite for the release flow — not the everyday `sysforge build` path, which remains a direct host-side `makepkg` invocation for speed.
 
@@ -4337,7 +4363,7 @@ subsection is only presentation.
 | 27 | Release-gate completeness | Static-analysis gates of `make pre-release` vs the `tools/release.sh` preflight | enforced | Every `pre-release` prerequisite except the full `test` suite (the heavier tier, by design) is also run by the release preflight, which fails the release on it. `pre-release` is advisory and the script is the gate a release cannot skip, so a check only the former runs is one a tag can ship without: `v3.2.0` shipped four pyright errors — one a live crash (`3.2.0-B30`) the type-checker had named weeks earlier — and the 3.3.0 cycle reached eighteen (`3.2.0-STD1`). `check_standards` `release_gates` group diffs the `pre-release:` prerequisite list against the targets `release.sh` invokes, so `docs/RELEASE-CHECKLIST.md`'s gate table cannot silently diverge. A new `pre-release` gate is added to the script in the same change, or to `_RELEASE_GATE_EXEMPT` with its reason. Because the script *blocks*, each gate must also be deterministic: a `uv run --with` overlay in a gate's recipe is pinned (`PYRIGHT_VERSION`, `REUSE_VERSION` in the Makefile header), since an unpinned overlay resolves the newest release on every run and a tool update alone could turn a release red; the same group flags an unpinned `--with` in any gate recipe. Pins are bumped deliberately in their own commit, and the header keeps the no-`[dependency-groups] dev` rule (the overlays stay the one record). Known residue: `lint` runs the pacman-provided `ruff`, which is kept on `PATH` for editor/hook integration and so follows system upgrades. |
 | 30 | No em-dashes in user-facing prose | `README.md`, `docs/guides/`, `docs/concepts/` (`3.5.0-DOC3`), the man page (`man/sysforge.1.scd.in` and the generated `man/sysforge.1`), `completions/`, and every non-docstring string literal under `sysforge/`: `--help` text, log and prompt messages, exception text, and the headers of files sysforge generates | enforced | Rewrite with a comma, colon, semicolon, period or parentheses as the sentence needs, never a blind substitution (`3.4.0-DOC2`). `check_standards` `em_dash` group: a line scan of the files and an AST scan of every string constant under `sysforge/`, so implicit concatenation and f-string pieces are covered without importing `sysforge`. Exempt: docstrings (developer prose), a literal that is only the glyph (an empty-cell placeholder, or a key in `log`'s ASCII glyph-fallback table), ROADMAP and release-note entries, whose ``- **`<ID>` — <title>.**`` lead is a lint-enforced format (changing it is its own `STD`), internal docs, shipped-config and hook comments, and code comments. `tests/test_standards_compliance.py` (`test_em_dash_*`). |
 | 31 | Subprocess goes through `primitives/run` | Every external command `sysforge/` runs | enforced | Numbered 28 until `3.4.0-STD2`, when it was found sharing that number with the `pam.d(5)` row, which took 28 first and keeps it. ruff `banned-api` (TID251, `pyproject.toml`) bans `subprocess.run`/`Popen`/`call`/`check_call`/`check_output` outside the seam modules `primitives/run.py`, `pty_runner.py`, `privilege.py` and `sudo_session.py` (`3.2.0-F13`). Probes use `run.capture` (missing binary → `None`) or `run.probe` (missing binary → status 127), raise-on-failure calls use `run_or_raise`, and escalation uses the §22 privilege seam. A call that legitimately stays raw (inherits the TTY, streams, needs its own `preexec_fn`, or is a privileged command whose status or `CalledProcessError` its caller inspects) carries `# noqa: TID251 — <why>`, and the reason is mandatory. Enforced by the ruff rule plus `tests/test_standards_compliance.py` (`test_subprocess_fence_*`), which pins the banned set, the exemption list and the per-call reasons. Complements row 17, which governs argv form; this row governs *where* the call is made. |
-| 32 | Machine-readable output contract (`--json`) | `state list --json`, `doctor` (`system`, `pkg`, bare) `--json`, `update --dry-run --json` | enforced | `primitives/json_out.py` is the one home (`3.4.0-F7`). Stdout carries exactly one JSON document ([RFC 8259](https://www.rfc-editor.org/rfc/rfc8259)) and nothing else: `cli.main` enters `json_out.reserved_stdout()` right after parsing and `verbs.runner.run_verb` enters it again (re-entrant), so every `ui()`/`print()`, startup logs and progress phases included, goes to stderr; the document goes out through `json_out.emit`. Every document has a top-level `"schema"` integer (`SCHEMA_VERSION`, now 1) and a `"kind"` (`state-list`, `doctor`, `update-dry-run`). **Adding a field is a minor change; renaming or removing one, or changing its type, is a major change and bumps `SCHEMA_VERSION`.** Each document is built from the result objects the human renderer reads (`AxisResult` via `diagnostics.axis_document`, `run.results` and the drift lists via `update._dry_run_document`, build_state rows through an explicit field list in `state_cmd._JSON_ENTRY_FIELDS`), so the two outputs cannot disagree. Exit codes are unchanged by `--json`. Mutating runs are out of scope: `update --json` without `--dry-run` and `doctor pkg --apply --json` are refused (exit 2). The schemas are committed as JSON Schema draft 2020-12 under `tests/data/json-schema/`; `tests/test_json_output.py` validates each verb's document against its schema (a subset validator, so the suite needs no new dependency), checks that stdout parses as one document with `log` in dry-run mode at `-vv`, and that a doctor skip appears under `roster.skipped`, never as a finding. A new field updates its schema in the same change. |
+| 32 | Machine-readable output contract (`--json`) | `state list --json`, `doctor` (`system`, `pkg`, bare) `--json`, `update --dry-run --json`, `config check --json` (`3.5.0-F18`) | enforced | `primitives/json_out.py` is the one home (`3.4.0-F7`). Stdout carries exactly one JSON document ([RFC 8259](https://www.rfc-editor.org/rfc/rfc8259)) and nothing else: `cli.main` enters `json_out.reserved_stdout()` right after parsing and `verbs.runner.run_verb` enters it again (re-entrant), so every `ui()`/`print()`, startup logs and progress phases included, goes to stderr; the document goes out through `json_out.emit`. Every document has a top-level `"schema"` integer (`SCHEMA_VERSION`, now 1) and a `"kind"` (`state-list`, `doctor`, `update-dry-run`). **Adding a field is a minor change; renaming or removing one, or changing its type, is a major change and bumps `SCHEMA_VERSION`.** Each document is built from the result objects the human renderer reads (`AxisResult` via `diagnostics.axis_document`, `run.results` and the drift lists via `update._dry_run_document`, build_state rows through an explicit field list in `state_cmd._JSON_ENTRY_FIELDS`), so the two outputs cannot disagree. Exit codes are unchanged by `--json`. Mutating runs are out of scope: `update --json` without `--dry-run` and `doctor pkg --apply --json` are refused (exit 2). The schemas are committed as JSON Schema draft 2020-12 under `tests/data/json-schema/`; `tests/test_json_output.py` validates each verb's document against its schema (a subset validator, so the suite needs no new dependency), checks that stdout parses as one document with `log` in dry-run mode at `-vv`, and that a doctor skip appears under `roster.skipped`, never as a finding. A new field updates its schema in the same change. |
 
 ### Notes on selected standards
 
diff --git a/Makefile b/Makefile
index 917cb8b9..ddb272e2 100644
--- a/Makefile
+++ b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: all help dev venv build install dev-install dev-uninstall clean distclean test test-x lint typecheck coverage coverage-ratchet coverage-ratchet-update man \
+.PHONY: all help surface check-surface install-hooks dev venv build install dev-install dev-uninstall clean distclean test test-x lint typecheck coverage coverage-ratchet coverage-ratchet-update man \
         dev-deps dev-deps-core dev-deps-pkg dev-deps-container dev-deps-release dev-deps-list \
         lint-py lint-sh \
         bench-completions check-shipped check-personal check-standards check-bump check-standards-at next-id next-bump design check-design pre-release print-gates audit \
@@ -275,6 +275,16 @@ design: ## Regenerate DESIGN.md from docs/design/
 
 # DESIGN.md drift gate (mirrors the manpage check). Fails if the committed
 # DESIGN.md is out of date with its docs/design/ sources. Run by tools/release.sh.
+install-hooks: ## Install the pre-commit hook running the fast gates (tools/pre-commit.sh)
+	ln -sf ../../tools/pre-commit.sh .git/hooks/pre-commit
+	@echo "pre-commit hook installed; skip once with git commit --no-verify"
+
+surface: ## Regenerate tests/data/surface.json, the snapshot of every user-facing surface
+	uv run --no-sync python tools/surface.py --write
+
+check-surface: ## Gate: surface snapshot current; changes vs main recorded in release notes
+	uv run --no-sync python tools/surface.py --check
+
 check-design: ## Gate: DESIGN.md in sync with docs/design/
 	uv run --no-sync python tools/build_design.py --check
 
@@ -358,7 +368,7 @@ sync-config: ## Merge new shipped defaults into the live config dir
 # The gate list, in run order, written once (3.5.0-DEV8): `pre-release`
 # depends on it and tools/ci.sh reads it through `print-gates`, so the release
 # gate and CI cannot drift apart.
-GATES := lint typecheck test check-shipped check-personal check-design check-roadmap-table check-standards
+GATES := lint typecheck test check-shipped check-personal check-design check-roadmap-table check-standards check-surface
 
 pre-release: $(GATES) ## Composite gate: lint, types, tests, all checks
 
diff --git a/README.md b/README.md
index b74ace0f..13757776 100644
--- a/README.md
+++ b/README.md
@@ -153,6 +153,9 @@ Fields may be added in a minor release; a renamed or removed field bumps `"schem
 **Config and your own artifacts**
 
 ```bash
+sysforge config check           # settings sysforge retired or does not know
+sysforge config clean           # rewrite the retired ones (--unknown: drop unknown ones)
+sysforge config reset FILE [KEY]  # back to the shipped default (whole file: keeps a backup)
 sysforge config merge           # adopt shipped config-default drift (.sfnew)
 sysforge setup                  # pacman integration (IgnoreGroup + hooks), a preset, update preferences
 sysforge artifact list          # inventory your scripts, systemd units, pacman hooks
diff --git a/completions/_sysforge b/completions/_sysforge
index 9411aa3c..ff9193ef 100644
--- a/completions/_sysforge
+++ b/completions/_sysforge
@@ -284,6 +284,7 @@ _sysforge_doctor_system() {
     '--rust[Rust toolchain owner + rustup default; opt-in]' \
     '--cache[compile-cache readiness: ccache/sccache]' \
     '--pacman[pacman-db consistency, .pacnew drift, orphans]' \
+    '--config[retired or unknown settings in the live config]' \
     '--state[state integrity: failures, sentinel, drift]' \
     '--boot[boot readiness: kernel artifacts, space, DKMS]' \
     '--restart[processes running superseded code after upgrade]' \
@@ -758,7 +759,7 @@ _sysforge_base_config_source() {
 
 _sysforge_log() {
   _arguments \
-    '(1)--verb[page a verb'"'"'s consolidated log]:verb:(build config-merge doctor fetch revert-to-stock run-hardware run-kernel run-packages run-reconfigure run-toolchain setup state-forget state-repair uninstall update)' \
+    '(1)--verb[page a verb'"'"'s consolidated log]:verb:(build config-clean config-merge config-reset doctor fetch revert-to-stock run-hardware run-kernel run-packages run-reconfigure run-toolchain setup state-forget state-repair uninstall update)' \
     '--log-dir[directory the log was written to]:directory:_files -/' \
     '--state-dir[override state directory]:directory:_files -/' \
     '--no-pager[do not pipe output through $PAGER]' \
@@ -776,6 +777,9 @@ _sysforge_config() {
   case $state in
     args)
       case $words[1] in
+        check) _sysforge_config_check ;;
+        clean) _sysforge_config_clean ;;
+        reset) _sysforge_config_reset ;;
         merge) _sysforge_config_merge ;;
       esac
       ;;
@@ -784,11 +788,37 @@ _sysforge_config() {
 
 _sysforge_config_subcommands() {
   local subcommands=(
+    'check:report retired or unknown settings in the live config'
+    'clean:rewrite retired settings (--unknown: drop unknown ones)'
+    'reset:put keys, or a whole file, back to the shipped default'
     'merge:interactively adopt or clear .sfnew/.pacnew config companions'
   )
   _describe 'subcommand' subcommands
 }
 
+_sysforge_config_check() {
+  _arguments \
+    '--config-dir[live config dir to check]:directory:_files -/' \
+    '--json[print one JSON document instead of the report]'
+}
+
+_sysforge_config_clean() {
+  _arguments \
+    '--config-dir[live config dir to clean]:directory:_files -/' \
+    '--unknown[also remove settings sysforge does not know]' \
+    '--dry-run[show the diff without writing]' \
+    '--yes[write without asking]'
+}
+
+_sysforge_config_reset() {
+  _arguments \
+    '--config-dir[live config dir]:directory:_files -/' \
+    '--dry-run[show the diff without writing]' \
+    '--yes[write without asking]' \
+    '1:file:(sysforge.toml profiles.toml packages.toml kernel.toml toolchain.toml)' \
+    '*:key (SECTION.KEY):'
+}
+
 _sysforge_config_merge() {
   _arguments \
     '--config-dir[live config dir to scan]:directory:_files -/' \
diff --git a/completions/sysforge.bash b/completions/sysforge.bash
index 47120133..5fbc562f 100644
--- a/completions/sysforge.bash
+++ b/completions/sysforge.bash
@@ -131,13 +131,17 @@ _sysforge_flag_arg() {
             ;;
         --verb)
             # sysforge log: every verb_log_names() entry (test_log_cmd checks).
-            COMPREPLY=( $(compgen -W "build config-merge doctor fetch revert-to-stock run-hardware run-kernel run-packages run-reconfigure run-toolchain setup state-forget state-repair uninstall update" -- "$cur") )
+            COMPREPLY=( $(compgen -W "build config-clean config-merge config-reset doctor fetch revert-to-stock run-hardware run-kernel run-packages run-reconfigure run-toolchain setup state-forget state-repair uninstall update" -- "$cur") )
             return 0
             ;;
         --bootloader)
             COMPREPLY=( $(compgen -W "systemd-boot grub none" -- "$cur") )
             return 0
             ;;
+        --rebuild-soname-consumers)
+            COMPREPLY=( $(compgen -W "prompt auto off" -- "$cur") )
+            return 0
+            ;;
         --base-config)
             # A keyword or a path to a .config file.
             _filedir
@@ -268,7 +272,7 @@ _sysforge_doctor() {
     case "$subverb" in
         system)
             local sys_flags="--distro --graphics --gfxperf --hardware --toolchain \
-                --rust --cache --pacman --state --boot --restart --storage \
+                --rust --cache --pacman --state --config --boot --restart --storage \
                 --services --audio --network --integrity --findings-only --json"
             [[ $cur == -* ]] && COMPREPLY=( $(compgen -W "$sys_flags" -- "$cur") )
             ;;
@@ -503,10 +507,23 @@ _sysforge_help() {
 _sysforge_config() {
     _sysforge_flag_arg && return
     if [[ -z $subverb ]]; then
-        COMPREPLY=( $(compgen -W "merge" -- "$cur") )
+        COMPREPLY=( $(compgen -W "check clean reset merge" -- "$cur") )
         return
     fi
     case "$subverb" in
+        check)
+            [[ $cur == -* ]] && COMPREPLY=( $(compgen -W "--config-dir --json" -- "$cur") )
+            ;;
+        clean)
+            [[ $cur == -* ]] && COMPREPLY=( $(compgen -W "--config-dir --unknown --dry-run --yes" -- "$cur") )
+            ;;
+        reset)
+            if [[ $cur == -* ]]; then
+                COMPREPLY=( $(compgen -W "--config-dir --dry-run --yes" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W "sysforge.toml profiles.toml packages.toml kernel.toml toolchain.toml" -- "$cur") )
+            fi
+            ;;
         merge)
             [[ $cur == -* ]] && COMPREPLY=( $(compgen -W "--config-dir --dry-run --no-pager" -- "$cur") )
             ;;
diff --git a/docs/design/06-config-layer.md b/docs/design/06-config-layer.md
index 42e0f3c8..878648a8 100644
--- a/docs/design/06-config-layer.md
+++ b/docs/design/06-config-layer.md
@@ -21,6 +21,17 @@ The non-`profiles.toml` configs (`packages.toml`, `toolchain.toml`, `kernel.toml
 
 **Adopting the `.sfnew` residue — `sysforge config merge`.** Hand-merging the `.sfnew` companions is the only remaining manual step, so `sysforge config merge` (verb `config-merge`, `config_cmd.py`) is a pacdiff-style interactive driver over them. It scans the resolved config dir (`--config-dir` override, else `paths.CONFIG_DIR`) for `*.sfnew` — plus pacman's own `*.pacnew`/`*.pacsave` for sysforge config files on a packaged install — and for each presents: `[v]iew` (a `difflib` unified diff through `$PAGER` via `maybe_pager`, prefixed by a **relocated-section banner** naming any header the diff shows as both removed and added — a header on both a `-` and a `+` line is present in both files, so the pair is a move, not a deletion; `difflib` has no move detection of its own), `[m]erge` (launch the resolved diff/merge tool with `live new`, then re-loop), `[s]kip`, `[r]emove` (drop the companion once the live file is satisfactory), `[o]verwrite` (copy the companion over the live file verbatim — guarded by a confirm and a "discards your local values" warning, never the default, intended for the `.pacnew` accept-maintainer case), and a[b]ort. Because a `.sfnew` is the *verbatim shipped file*, there is **no blind "accept theirs"** as a primary action — the safe path is merge-then-remove. The verb edits config files in place but never builds/installs, so it carries **no sentinel**. The diff/merge tool resolves through one home shared with the reconfigure editor chain — `primitives/editor.resolve_merge_tool` (`SYSFORGE_MERGE` > `sysforge.toml [ui].merge` > `$DIFFPROG` > `vimdiff`) launched via `run_tty_argv` (the `/dev/tty` passthrough, also used by `resolve_editor`'s callers, which additionally runs the child inside a `"child"` `yield_terminal` so an active progress bar's reserved bottom row is released before a full-screen editor takes the terminal). `--dry-run` reports the companion→target pairs without prompting (scripting/CI).
 
+### Checking and repairing a live config
+
+Neither an upgrade nor `sync-config` ever removes anything from a live file, so a key sysforge stopped reading stays there, silently ignored, and a misspelt key is never reported. `primitives/config_schema.py` (`3.5.0-F18`) is the one home for what a live file may contain and for the edits that bring one back in line:
+
+- **The schema.** `KNOWN_SECTIONS`/`KNOWN_TOP_KEYS` (moved here from `tools/check_shipped.py`, which now imports them, so the runtime and the release gate read one definition) name each file's sections and top-level keys. `OPEN_SECTIONS` are the ones whose keys the user names (a profile's flag variables, `[[rules]]`, `[[package]]`, `[group.*]`, `[[kconfig]]`, ...); nothing under them is judged. In every other section a key is known when the **shipped default documents it**, active or as a commented `# key = ...` example, so documenting a key is what makes it valid; a commented example table covers only its own comment block, so a blank line returns to the last real header. `tests/test_config_keys_documented.py` keeps that sound: every key the code reads from a fixed section (chained `.get`/`[]` off a config-like object, or a local assigned from one) and every schema top-level key must be documented in the shipped default, or `config clean --unknown` would delete a working setting. It found `profiles.toml`'s `extends_system` (read from a user file) undocumented. The first run found `toolchain.toml`'s `reuse_unchanged` and `profile_store` (read by the stage and by `resolve_profile_store_root`) missing from the old list; `profile_store` is now also documented in the shipped file.
+- **What was retired.** `RETIRED_KEYS` (renamed or dropped keys: `[git] pull_timeout`, the per-package `pkgbuild_patch`) and `RETIRED_VALUES` (`repo_mode = "profiled"`, `build_mode = "patched_pkgbuild"`), each with the ID that retired it.
+- **The shipped defaults.** `shipped_text(name)` reads the checkout's `etc/sysforge`, or on an installed system the copy the wheel carries (`pyproject.toml` force-includes `etc/sysforge` as `sysforge/_data/config-defaults`): `/etc/sysforge` holds the user's own copies, kept across upgrades by `backup=()`.
+- **Edits.** Line-based, so comments and layout survive, over a small scanner that knows tables, array-of-tables entries and multi-line values. Every edited text is re-parsed with `tomllib` and refused if it would not parse; files are written through `atomic_write.replace_file`.
+
+Three `config` verbs and a doctor axis sit on it (`config_cmd.py`): **`config check`** reports retired and unknown settings with their line, exiting 1 when there are any (`--json` prints one `config-check` document instead, `tests/data/json-schema/config-check.schema.json`: each issue's file, line, kind, setting, message and fix); **`config clean`** renames a retired key (or drops it when its replacement is already set in the same table, saying so) and rewrites a retired value, and with `--unknown` also removes unknown keys and sections; **`config reset FILE [KEY...]`** puts each `SECTION.KEY` back to the shipped line (removing it when the default leaves it unset, adding it when the file lacks it), refuses keys inside array-of-tables entries, and with no KEY replaces the whole file, keeping the old one as `FILE.bak-<time>`. Both writers show a unified diff, honour `--dry-run`, ask at a terminal and otherwise need `--yes`. **`doctor system --config`** runs the same inspection in the default sweep: a parse error is an error, anything else a warning naming the fix.
+
 ### Dev fixtures vs. personal config
 
 `tests/data/etc/sysforge/` is the **git-tracked test fixture set** wired in `tests/conftest.py` (which *forces* `SYSFORGE_CONFIG_DIR` to that dir directly, so a developer shell exporting its own value cannot leak into the suite). It is kept in shipped↔fixture parity by `make check-shipped`. A developer's **personal live config** is a separate, untracked dir (e.g. `~/sf-config`, holding the TOML files directly) that the shell's `SYSFORGE_CONFIG_DIR` points at and that `make sync-config` services — keeping personal config out of the tracked tree while leaving the fixtures deterministic.
diff --git a/docs/design/07-pipeline-layer.md b/docs/design/07-pipeline-layer.md
index daf8f8e3..bca44fe8 100644
--- a/docs/design/07-pipeline-layer.md
+++ b/docs/design/07-pipeline-layer.md
@@ -77,7 +77,7 @@ Resolution is `primitives/editor.py`'s single home (`resolve_editor` → `SYSFOR
 
 - **Per-step gate.** `_EDITOR_NEEDING_STEPS` (`config`, `makepkg`) — the steps that open files *inside* the stage. `_run_selected_steps` calls `_require_usable_editor` before each, which runs the picker (with pacman-backed install of the chosen binary) and raises `RuntimeError` to abort the stage if the user cancels, rather than letting every subsequent edit prompt silently no-op.
 - **Pipeline-handoff gate.** `_gate_editor_for_pipeline`, immediately before the "Ready to proceed to toolchain → packages → kernel?" confirm. The per-step gate covers only two steps, so a step subset skipping both (or a skipped `editor` step) would otherwise hand the build stages no editor at all. Skipped under `--standalone` (nothing runs after reconfigure); with no TTY or under `--dry-run` it warns instead of blocking on a prompt nobody can answer.
-- **Adoption.** `_adopt_editor` exports the accepted editor as `SYSFORGE_EDITOR`. Downstream consumers call `resolve_editor()` fresh rather than receiving the stage's threaded local, so without this the pick would evaporate at the stage boundary. Adoption is unconditional; the `Save as sysforge default? [y/N]` prompt (`_offer_save_editor`) is a *separate* choice about persisting to `sysforge.toml` for future invocations, and declining it no longer costs the current run its editor.
+- **Adoption.** `_adopt_editor` exports the accepted editor as `SYSFORGE_EDITOR`. Downstream consumers call `resolve_editor()` fresh rather than receiving the stage's threaded local, so without this the pick would evaporate at the stage boundary. Adoption is unconditional; persisting is a *separate* choice (`_offer_persist_editor`): write `[ui] editor` to `sysforge.toml`, and/or export the pick as `EDITOR`/`VISUAL` from a system-wide or a user shell file, each target confirmed on its own (a target's two variables move together, never half-written). Declining keeps the pick for this run only.
 
 ### Bootstrap workflow (stages 1–3)
 
@@ -187,7 +187,7 @@ separate size block is needed.
 *Kconfig vs previous build* diffs the resolved `.config` against the one the last build produced.
 `primitives/kconfig_history.py` owns that history — nothing else in sysforge keeps a resolved
 `.config` after the build tree is cleaned — archiving each successful build's config (located by
-the existing `_resolve_built_config`, tagged with `_built_kernel_release`) gzipped to
+the existing `resolve_built_config`, tagged with `_built_kernel_release`) gzipped to
 `<state_dir>/kconfig-history/<pkgname>-<release>.config.gz`, newest `KEEP` (5) per pkgname, pruned
 on write and bounded at a few hundred KiB. The comparison runs through the new
 `kernel_safety.diff_kconfig(old, new)`, a symmetric sibling to `diff_requested_kconfig` (which is
@@ -195,11 +195,11 @@ hardcoded to the requested-vs-resolved axis and iterates only sysforge's own int
 the shared `parse_kconfig()`. `diff_kconfig` deliberately does *not* normalise an absent option to
 `n` the way `diff_requested_kconfig` does — on the build-to-build axis, "the symbol did not exist in
 that kernel" and "the symbol existed and was off" are different facts, and collapsing them would
-fabricate churn on every major bump. Output caps at `_KCONFIG_DIFF_CAP` (40) symbols with a
+fabricate churn on every major bump. Output caps at `KCONFIG_DIFF_CAP` (40) symbols with a
 `… and N more` pointer; the full list goes to the unified log, so a major bump cannot bury the
 version rows.
 
-*Kconfig merge drift* relocates `_gate2_kconfig_drift`'s existing result into the summary by having
+*Kconfig merge drift* relocates `gate2_kconfig_drift`'s existing result into the summary by having
 it *return* its drift list; the mid-run warnings are unchanged. `None` (as distinct from `[]`)
 means the check never ran, which the block states explicitly, reusing the "did NOT run" wording
 established by 2.6.1-B6 — the AlreadyBuilt path is exactly where a stale build makes the check most
@@ -323,14 +323,14 @@ option = "CONFIG_HZ_1000"        # must match CONFIG_[A-Z0-9_]+
 value  = "y"                     # y | m | n | non-empty string
 ```
 
-`srcdir` is needed when the PKGBUILD directory name differs from the tracked name (e.g. `pkgname = "linux-sysforge"` but the repo is cloned as `~/builds/linux`). Resolution: `srcdir` → `upstream_pkgname` → `pkgname`, first set wins (`_srcdir_path`).
+`srcdir` is needed when the PKGBUILD directory name differs from the tracked name (e.g. `pkgname = "linux-sysforge"` but the repo is cloned as `~/builds/linux`). Resolution: `srcdir` → `upstream_pkgname` → `pkgname`, first set wins (`srcdir_path`).
 
 **Source tracking & local-rename (F40).** `upstream_pkgname` decouples *what to pull* from *what to build/install as*. Two modes fall out of the schema:
 
 - **Pure-local** (default): `upstream_pkgname` unset, `source = "local"`, `pkgname` names the hand-maintained tree — no sync, no rename; byte-identical to the pre-F40 behavior.
 - **Track-upstream:** `upstream_pkgname = "linux-zen"` (+ optional distinct `pkgname = "linux-mine"`) — the stage clones/fetches `linux-zen` into `<pkgbuild_src_dir>/linux-zen`, and when `pkgname` differs it threads `BuildOptions.rename_pkgbase_to = pkgname` into the build; `makepkg_wrapper._run_build` applies `pkgbuild_patcher.patch_pkgbase_rename(mode="coexist")` to the patched PKGBUILD so the build installs *alongside* the official package. For an FDO build the stage passes the final role name instead (`linux-zen` → `linux-mine-sysforge-fdo`; see *Per-role kernel names* below), and the generic `-sysforge` suffix layer stands down for it; the rename dict that rides to `build_state` keeps `origin_pkgbase = <upstream_pkgname>` so `sysforge update` still source-syncs the upstream tree. With `pkgname` omitted (defaults to `upstream_pkgname`) there is no rename and the repo-collision check is the safety net against shadowing the official package.
 
-**Name resolution** is `_resolve_names` (one home): `upstream_pkgname` or `None`, `pkgname` defaulting to `upstream_pkgname`; neither set is an error. **Source resolution** is `_resolve_source(kernel_cfg, srcdir_path)`: an explicit `source` is honored (`git` errors — it was a phantom value with no URL to clone from); when omitted it auto-resolves `local → repo → aur` — an existing non-git tree is `local` (never clobbered by a re-clone), an existing git clone is `repo` (the scheduler's generic fetch rebases via the tree's own origin, skipping the AUR RPC), and a missing tree picks its clone remote via `aur.is_repo_package` on the tracked name (sync DB hit → `repo`/pkgctl, else `aur`). The build entry runs the source sync **before** requiring the PKGBUILD path, so a missing tree is bootstrapped by the scheduler's clone-if-missing path instead of aborting with "clone it first".
+**Name resolution** is `resolve_names` (one home): `upstream_pkgname` or `None`, `pkgname` defaulting to `upstream_pkgname`; neither set is an error. **Source resolution** is `_resolve_source(kernel_cfg, srcdir_path)`: an explicit `source` is honored (`git` errors — it was a phantom value with no URL to clone from); when omitted it auto-resolves `local → repo → aur` — an existing non-git tree is `local` (never clobbered by a re-clone), an existing git clone is `repo` (the scheduler's generic fetch rebases via the tree's own origin, skipping the AUR RPC), and a missing tree picks its clone remote via `aur.is_repo_package` on the tracked name (sync DB hit → `repo`/pkgctl, else `aur`). The build entry runs the source sync **before** requiring the PKGBUILD path, so a missing tree is bootstrapped by the scheduler's clone-if-missing path instead of aborting with "clone it first".
 
 **Per-role kernel names (`3.3.0-F6`).** An FDO kernel never replaces the plain one; each role installs beside it under its own name. `kernel_fdo.record_pkgname` and `kernel_fdo.optimized_pkgname` are the only producers: `pkgname`, then `-sysforge` appended if absent, then exactly one role suffix (`kernel_fdo.strip_role` inverts it).
 
@@ -345,9 +345,9 @@ The name always reflects what was *applied*: a Propeller → AutoFDO fallback in
 
 **Kernel-stage compiler override:** `compiler = "gcc" | "llvm"` is independent of the toolchain stage. A system that keeps gcc system-wide can still build the kernel with LLVM (or vice versa). Resolution order: `--toolchain` CLI flag > `kernel.toml compiler` > toolchain-stage pipeline state (cc/cxx set by stage 5) > profile defaults. When set to LLVM, the standard `LLVM=1 LLVM_IAS=1` env vars are injected by `makepkg_wrapper` automatically — no extra PKGBUILD changes needed. Note: `compiler = "llvm"` builds the kernel *with* clang but does **not** apply the toolchain's PGO profdata — that profdata trains the clang binary, not the linux target. The kernel's own profile-guided path is sample-based AutoFDO/Propeller (`--autofdo`, LLVM-only), described under *Sample-based kernel FDO* below — a distinct mechanism from the toolchain PGO.
 
-**Headers/docs subpackages (`build_headers` / `build_docs`):** the kernel image is always built; the optional `-headers` and `-docs` subpackages are toggled independently. `build_headers` defaults **on** (DKMS and any out-of-tree module build need the matching kernel headers to compile); `build_docs` defaults **off** (the docs subpackage is slow to package and rarely needed) — note this drops the `-docs` subpackage that a stock kernel PKGBUILD would otherwise build. Resolution per toggle: CLI flag (`--headers`/`--no-headers`, `--docs`/`--no-docs`, `argparse.BooleanOptionalAction`, default unset → `None`) > `kernel.toml` (`build_headers`/`build_docs`) > hard default. The single home for the resolve is `_resolve_subpackages`. Disabling a subpackage works by **dropping its entry from the PKGBUILD's `pkgname` array** — `pkgbuild_patcher.patch_kernel_subpackages` (called from `makepkg_wrapper` for every kernel build, after `patch_kernel_btf_guard`) removes any array token whose dequoted value ends with `-headers`/`-docs`. It rewrites **both** the initial `pkgname=(...)` literal **and** every `pkgname+=(...)` append — modern Arch kernel PKGBUILDs add the optional subpackages via `pkgname+=("$pkgbase-docs")`, which a single-array walk would miss (leaving `-docs` to build and install; B7); an append that existed solely to add now-dropped subpackage(s) has its whole statement line removed rather than leaving an empty `pkgname+=()`. Standard Arch kernels synthesize each `package_$_p()` via `for _p in "${pkgname[@]}"; do eval …`, so an entry absent from the array is never packaged; the `_package-headers()`/`_package-docs()` helper bodies are left untouched. **Disabling docs additionally neutralizes the doc *build*:** stock Arch `linux` builds the documentation in `build()` (`make htmldocs SPHINXOPTS=-QT`), not only in `_package-docs()`, so dropping the `-docs` pkgname token stops packaging but not the (often multi-minute Sphinx) compile — which would make the summary's `docs=off` a lie. When `build_docs` is off the same patcher neutralizes any doc-target make line (`_neutralize_kernel_doc_build`, two passes over the goals — htmldocs/pdfdocs/infodocs/mandocs/…): a **mixed** line such as `make all htmldocs` loses *only* its `*docs` goals (→ `make all`) so the real build survives, while a line whose goals are **exclusively** `*docs` (with optional `VAR=val`/flag tokens) is commented out whole with a `# sysforge(docs off):` prefix. Both passes treat shell control operators and redirections (`&`, `;`, `|`, `&&`, `>…`) as punctuation the shell owns, never as make goals — stock Arch `linux` *backgrounds* its doc build (`make htmldocs SPHINXOPTS=-QT &`), and counting the trailing `&` as a surviving real goal made an exclusive-doc line look mixed: only `htmldocs` was stripped, leaving a goalless `make &` that resolves to make's **default** goal (`all`) and runs a second kernel build concurrently with the real one, killing `build()` with `E_USER_FUNCTION_FAILED` (B15). A backgrounded exclusive-doc line is additionally rewritten to `true &` rather than merely commented: the following line is invariably `local pid_docs=$!` and the function later `wait`s on that pid, so removing the only background job would leave the capture reading an unset or stale `$!` — and a `wait` on a non-child exits non-zero, fatal under makepkg's errexit. A trivial background job keeps `$!` valid and `wait` at 0, with the original command preserved in the trailing `# sysforge(docs off):` comment. The patcher needs no sentinel (every edit is self-idempotent — a commented line no longer starts with `make`, a stripped/removed token no longer matches), is a no-op when both subpackages are kept or the targeted subpackage is absent, and preserves both the single-line and one-token-per-line array layouts. When `build_headers` is disabled, Gate 1 escalates the standing DKMS reminder into a hard warning: no `<pkg>-headers` will be installed, so out-of-tree and DKMS modules (nvidia-open-dkms → black screen) cannot rebuild and won't load on reboot; any present DKMS modules are named.
+**Headers/docs subpackages (`build_headers` / `build_docs`):** the kernel image is always built; the optional `-headers` and `-docs` subpackages are toggled independently. `build_headers` defaults **on** (DKMS and any out-of-tree module build need the matching kernel headers to compile); `build_docs` defaults **off** (the docs subpackage is slow to package and rarely needed) — note this drops the `-docs` subpackage that a stock kernel PKGBUILD would otherwise build. Resolution per toggle: CLI flag (`--headers`/`--no-headers`, `--docs`/`--no-docs`, `argparse.BooleanOptionalAction`, default unset → `None`) > `kernel.toml` (`build_headers`/`build_docs`) > hard default. The single home for the resolve is `resolve_subpackages`. Disabling a subpackage works by **dropping its entry from the PKGBUILD's `pkgname` array** — `pkgbuild_patcher.patch_kernel_subpackages` (called from `makepkg_wrapper` for every kernel build, after `patch_kernel_btf_guard`) removes any array token whose dequoted value ends with `-headers`/`-docs`. It rewrites **both** the initial `pkgname=(...)` literal **and** every `pkgname+=(...)` append — modern Arch kernel PKGBUILDs add the optional subpackages via `pkgname+=("$pkgbase-docs")`, which a single-array walk would miss (leaving `-docs` to build and install; B7); an append that existed solely to add now-dropped subpackage(s) has its whole statement line removed rather than leaving an empty `pkgname+=()`. Standard Arch kernels synthesize each `package_$_p()` via `for _p in "${pkgname[@]}"; do eval …`, so an entry absent from the array is never packaged; the `_package-headers()`/`_package-docs()` helper bodies are left untouched. **Disabling docs additionally neutralizes the doc *build*:** stock Arch `linux` builds the documentation in `build()` (`make htmldocs SPHINXOPTS=-QT`), not only in `_package-docs()`, so dropping the `-docs` pkgname token stops packaging but not the (often multi-minute Sphinx) compile — which would make the summary's `docs=off` a lie. When `build_docs` is off the same patcher neutralizes any doc-target make line (`_neutralize_kernel_doc_build`, two passes over the goals — htmldocs/pdfdocs/infodocs/mandocs/…): a **mixed** line such as `make all htmldocs` loses *only* its `*docs` goals (→ `make all`) so the real build survives, while a line whose goals are **exclusively** `*docs` (with optional `VAR=val`/flag tokens) is commented out whole with a `# sysforge(docs off):` prefix. Both passes treat shell control operators and redirections (`&`, `;`, `|`, `&&`, `>…`) as punctuation the shell owns, never as make goals — stock Arch `linux` *backgrounds* its doc build (`make htmldocs SPHINXOPTS=-QT &`), and counting the trailing `&` as a surviving real goal made an exclusive-doc line look mixed: only `htmldocs` was stripped, leaving a goalless `make &` that resolves to make's **default** goal (`all`) and runs a second kernel build concurrently with the real one, killing `build()` with `E_USER_FUNCTION_FAILED` (B15). A backgrounded exclusive-doc line is additionally rewritten to `true &` rather than merely commented: the following line is invariably `local pid_docs=$!` and the function later `wait`s on that pid, so removing the only background job would leave the capture reading an unset or stale `$!` — and a `wait` on a non-child exits non-zero, fatal under makepkg's errexit. A trivial background job keeps `$!` valid and `wait` at 0, with the original command preserved in the trailing `# sysforge(docs off):` comment. The patcher needs no sentinel (every edit is self-idempotent — a commented line no longer starts with `make`, a stripped/removed token no longer matches), is a no-op when both subpackages are kept or the targeted subpackage is absent, and preserves both the single-line and one-token-per-line array layouts. When `build_headers` is disabled, Gate 1 escalates the standing DKMS reminder into a hard warning: no `<pkg>-headers` will be installed, so out-of-tree and DKMS modules (nvidia-open-dkms → black screen) cannot rebuild and won't load on reboot; any present DKMS modules are named.
 
-**Resolution summary.** After resolving compiler (+ its origin), variant, bootloader (+ whether the chosen one is detected installed), source, interactive mode, kconfig counts, the headers/docs subpackage toggles (`subpkgs:` line), and the boot-safety gate settings, the stage emits a single labelled "Kernel build plan:" block (`_log_resolution_summary`). It prints on every run (useful before a multi-hour build) and is the readable core of `--dry-run`, replacing decisions previously scattered across the log. The standalone interactive default also emits a one-line nudge pointing at `--no-interactive` for unattended runs.
+**Resolution summary.** After resolving compiler (+ its origin), variant, bootloader (+ whether the chosen one is detected installed), source, interactive mode, kconfig counts, the headers/docs subpackage toggles (`subpkgs:` line), and the boot-safety gate settings, the stage emits a single labelled "Kernel build plan:" block (`log_resolution_summary`). It prints on every run (useful before a multi-hour build) and is the readable core of `--dry-run`, replacing decisions previously scattered across the log. The standalone interactive default also emits a one-line nudge pointing at `--no-interactive` for unattended runs.
 
 **Variant-inheritance nudge.** When `compiler` is unset (neither CLI nor `kernel.toml`) and the toolchain-stage variant is `pgo_llvm`, the stage emits a WARN naming the inherited variant and recommending that the operator persist `compiler = "llvm"` in `kernel.toml` so the choice survives a future toolchain-stage disable (which clears `[stages.toolchain.result]`). `stock_llvm` gets the same nudge at INFO level. `gcc` and `system` variants are silent — gcc is the safe default and `system` means there's no opinion to project.
 
@@ -383,9 +383,9 @@ The fragment is an *overlay* — it does not define the build's starting `.confi
 
 Before the build, `lsmod` output is captured to `<state_dir>/lsmod.snapshot` (unless `capture_lsmod_snapshot = false`), then `kconfig.stage_lsmod_snapshot` copies it next to the PKGBUILD as `kconfig_plan.LSMOD_FILE` (`sysforge.lsmod`) — `prepare()` can reach `$startdir` but not the state dir. A configured `localmodconfig`/`localyesconfig` (`kconfig_targets`, below) renders as a guard block that passes it as `LSMOD="$startdir/sysforge.lsmod"` when the file exists and falls back to the bare invocation (live `lsmod`) when it does not; the guard is required because `streamline_config.pl` dies on an `LSMOD` path that does not exist, and treats `LSMOD=""` as one. Without `LSMOD` the minimizer reads live `lsmod` and the accumulated set below is never used (`3.2.0-B35`). Both branches of the guard also take their stdin from `< <(yes '')` (`kconfig_plan._DEFAULT_ANSWERS`): the minimizer ends in `conf --oldconfig`, which prompts for every symbol that minimization newly exposes (a `(NEW)` symbol absent from every prior config), and inheriting the interactive stage's terminal stranded the build on an unannounced prompt ahead of the REVIEW slot. Default answers resolve exactly as the `olddefconfig` that follows would, leaving REVIEW the single human touchpoint. It is a process substitution rather than a `yes '' |` pipeline because makepkg toggles `pipefail`, under which `yes` dying of SIGPIPE would fail `prepare()` (`3.2.0-B36`). With capture off or no snapshot, a stale staged copy is removed so the fallback is live `lsmod`, not a previous run's data. A packager-owned `make localmodconfig` line (no `kconfig_targets`) is left as written and reads live `lsmod`. `localmodconfig` strips drivers for hardware *not loaded at snapshot time* — Gate 1 warns about this only when `kconfig_targets` actually names a minimizer (otherwise it logs at `info` that the config is not minimized, since a snapshot alone trims nothing), and Gate 2 (below) is the backstop that catches a dropped root-path driver before install.
 
-**Keeping hotplug drivers through minimization (`keep_hotplug_drivers`):** `localmodconfig`/`localyesconfig` minimize to hardware present *at build time*, so a device attached later (a USB drive, an SD card, a hot-plugged PCI/CardBus card) can end up with no built driver. `kernel.toml keep_hotplug_drivers` (default off; also `--keep-hotplug-drivers`/`--no-keep-hotplug-drivers`, CLI wins over the config key) re-enables a curated set of hotplug driver classes — USB host/gadget, USB4/Thunderbolt, MMC/SD, hot-plug PCI/CardBus, hot-plug HID, and removable-media filesystems (FAT/VFAT, exFAT, ISO 9660, UDF, NTFS3, plus the `NLS_UTF8`/`NLS_ISO8859_1` codepages their default mount options need) — regardless of what was attached at build time. The set is additive (it only ever enables; no `is not set` lines), and each symbol carries the value its kconfig type permits — `=m` for tristate symbols, `=y` for the `bool` ones (`CONFIG_HOTPLUG_PCI`, `CONFIG_HOTPLUG_PCI_PCIE`, `CONFIG_CARDBUS`). Writing `=m` for a bool makes kconfig discard the assignment entirely with `symbol value 'm' invalid for X`, so the symbol silently falls back to its tree default and the re-enable is lost; `tests/test_stage_kernel.py::test_hotplug_kconfig_values_are_legal` pins the per-symbol values, and adding a symbol to the curated set means checking its type in the kernel tree first. Resolution is `_resolve_keep_hotplug_drivers`; when it's on, the stage writes the curated set to a dedicated `sysforge.hotplug.config` fragment (distinct from the main `sysforge.config` fragment above) next to the PKGBUILD. The merge is contributed as the `kconfig_plan.HOTPLUG_MERGE` slot, ordered by `SLOT_ORDER` *after* `GENERATE` (so any `localmodconfig`/`localyesconfig` minimization has already run and can't strip the re-enabled modules) and *before* `REVIEW` (the configured tail or the injected `make nconfig`), so the operator still reviews the final, hotplug-safe config. File-existence guarded and idempotent, like the other fragment merges. When the key resolves off, any stale `sysforge.hotplug.config` from a prior run is removed. Boot safety remains authoritative — this mechanism only *adds* modules; it doesn't touch Gate 1/Gate 2.
+**Keeping hotplug drivers through minimization (`keep_hotplug_drivers`):** `localmodconfig`/`localyesconfig` minimize to hardware present *at build time*, so a device attached later (a USB drive, an SD card, a hot-plugged PCI/CardBus card) can end up with no built driver. `kernel.toml keep_hotplug_drivers` (default off; also `--keep-hotplug-drivers`/`--no-keep-hotplug-drivers`, CLI wins over the config key) re-enables a curated set of hotplug driver classes — USB host/gadget, USB4/Thunderbolt, MMC/SD, hot-plug PCI/CardBus, hot-plug HID, and removable-media filesystems (FAT/VFAT, exFAT, ISO 9660, UDF, NTFS3, plus the `NLS_UTF8`/`NLS_ISO8859_1` codepages their default mount options need) — regardless of what was attached at build time. The set is additive (it only ever enables; no `is not set` lines), and each symbol carries the value its kconfig type permits — `=m` for tristate symbols, `=y` for the `bool` ones (`CONFIG_HOTPLUG_PCI`, `CONFIG_HOTPLUG_PCI_PCIE`, `CONFIG_CARDBUS`). Writing `=m` for a bool makes kconfig discard the assignment entirely with `symbol value 'm' invalid for X`, so the symbol silently falls back to its tree default and the re-enable is lost; `tests/test_stage_kernel.py::test_hotplug_kconfig_values_are_legal` pins the per-symbol values, and adding a symbol to the curated set means checking its type in the kernel tree first. Resolution is `resolve_keep_hotplug_drivers`; when it's on, the stage writes the curated set to a dedicated `sysforge.hotplug.config` fragment (distinct from the main `sysforge.config` fragment above) next to the PKGBUILD. The merge is contributed as the `kconfig_plan.HOTPLUG_MERGE` slot, ordered by `SLOT_ORDER` *after* `GENERATE` (so any `localmodconfig`/`localyesconfig` minimization has already run and can't strip the re-enabled modules) and *before* `REVIEW` (the configured tail or the injected `make nconfig`), so the operator still reviews the final, hotplug-safe config. File-existence guarded and idempotent, like the other fragment merges. When the key resolves off, any stale `sysforge.hotplug.config` from a prior run is removed. Boot safety remains authoritative — this mechanism only *adds* modules; it doesn't touch Gate 1/Gate 2.
 
-The snapshot **accumulates**: `_capture_lsmod_snapshot` union-merges each new `lsmod` capture with the prior snapshot by module name (`_merge_lsmod`), with the current capture's row winning on overlap (fresher `Size`/`Used` data) and prior-only rows retained. This means a module that was loaded once (USB device, VPN, container netfilter) but isn't loaded during a later capture is never dropped just because that particular run didn't have it active — the module set grows monotonically across builds instead of resetting each time. There is no reset flag: to start over, delete `<state_dir>/lsmod.snapshot` manually.
+The snapshot **accumulates**: `capture_lsmod_snapshot` union-merges each new `lsmod` capture with the prior snapshot by module name (`merge_lsmod`), with the current capture's row winning on overlap (fresher `Size`/`Used` data) and prior-only rows retained. This means a module that was loaded once (USB device, VPN, container netfilter) but isn't loaded during a later capture is never dropped just because that particular run didn't have it active — the module set grows monotonically across builds instead of resetting each time. There is no reset flag: to start over, delete `<state_dir>/lsmod.snapshot` manually.
 
 **Configurable kconfig target sequence (`kconfig_targets`):**
 
@@ -407,15 +407,15 @@ The resolved sequence is threaded as `BuildOptions.kconfig_targets` (kernel.py 
 
 Note: when other verbs (`sysforge build`, `sysforge update`) build a kernel PKGBUILD with `build_mode = "kernel"` on the resolved profile, those paths still default to *non-interactive* — interactive-by-default is a kernel-stage-only contract because the stage is the user-driven kernel build entry point.
 
-**Post-build kconfig drift (advisory):** after the build, beside Gate 2 (pre-install, outside the sentinel), `_gate2_kconfig_drift` compares the options sysforge merged into `sysforge.config` against the resolved `.config` and warns on any that didn't survive — disabled (`y/m`→`n`/absent), changed (built-in↔module, or a string/int value change), or re-enabled (`n`→`y/m`). On the interactive path a drop usually means the operator toggled it off in `make nconfig`; otherwise it's typically `make olddefconfig` dropping a request whose dependencies are unmet. sysforge can't distinguish the two without a full dependency solve, so this **never blocks** the build — unlike the boot-critical Gate 2 audit it sits next to. The diff itself is a pure fact in `kernel_safety.diff_requested_kconfig` (returning `KconfigDrift` records over the same `parse_kconfig_text` representation both files share — a missing resolved option normalises to `n`, so a requested `n` that ends up absent is correctly not flagged); the stage owns only the logging. The check keys off the fragment's existence, so it is on exactly when `kconfig_merge` produced a fragment (both on or both off).
+**Post-build kconfig drift (advisory):** after the build, beside Gate 2 (pre-install, outside the sentinel), `gate2_kconfig_drift` compares the options sysforge merged into `sysforge.config` against the resolved `.config` and warns on any that didn't survive — disabled (`y/m`→`n`/absent), changed (built-in↔module, or a string/int value change), or re-enabled (`n`→`y/m`). On the interactive path a drop usually means the operator toggled it off in `make nconfig`; otherwise it's typically `make olddefconfig` dropping a request whose dependencies are unmet. sysforge can't distinguish the two without a full dependency solve, so this **never blocks** the build — unlike the boot-critical Gate 2 audit it sits next to. The diff itself is a pure fact in `kernel_safety.diff_requested_kconfig` (returning `KconfigDrift` records over the same `parse_kconfig_text` representation both files share — a missing resolved option normalises to `n`, so a requested `n` that ends up absent is correctly not flagged); the stage owns only the logging. The check keys off the fragment's existence, so it is on exactly when `kconfig_merge` produced a fragment (both on or both off).
 
 **Source sync via the scheduler:**
 
-The kernel stage routes its source refresh through `source_sync.get_scheduler().request(SyncRequest(..., source=<resolved source>))` ahead of the build, the same path as the toolchain stage — and (F40) *before* `_pkgbuild_path` requires the PKGBUILD, so a missing tree is bootstrapped by the scheduler's clone-if-missing path. With `source = "local"` (explicit or auto-resolved), the scheduler short-circuits (no RPC, no clone, no fetch) — only `--cleansrc` / `--cleansrc-force` would attempt a purge, but a hand-maintained tree has no remote to re-clone from, so users on the `local` path leave cleansrc unset. For `source = "repo"` / `"aur"`, the normal sync runs: `--cleansrc` purges and re-clones (refusing on dirty/ahead/no-upstream clones); `--cleansrc-force` overrides that guard; cleansrc forces a sync even when `--no-update` is also set. `STATUS_FAILED` / `STATUS_RATE_LIMITED` / `STATUS_PURGE_REFUSED` raise.
+The kernel stage routes its source refresh through `source_sync.get_scheduler().request(SyncRequest(..., source=<resolved source>))` ahead of the build, the same path as the toolchain stage — and (F40) *before* `pkgbuild_path` requires the PKGBUILD, so a missing tree is bootstrapped by the scheduler's clone-if-missing path. With `source = "local"` (explicit or auto-resolved), the scheduler short-circuits (no RPC, no clone, no fetch) — only `--cleansrc` / `--cleansrc-force` would attempt a purge, but a hand-maintained tree has no remote to re-clone from, so users on the `local` path leave cleansrc unset. For `source = "repo"` / `"aur"`, the normal sync runs: `--cleansrc` purges and re-clones (refusing on dirty/ahead/no-upstream clones); `--cleansrc-force` overrides that guard; cleansrc forces a sync even when `--no-update` is also set. `STATUS_FAILED` / `STATUS_RATE_LIMITED` / `STATUS_PURGE_REFUSED` raise.
 
-`STATUS_DIVERGED` (upstream advanced but the local tree can't fast-forward — local commits or a dirty tree) gets stronger handling in the *kernel* stage than the plain warning the other verbs use, because building a kernel off stale or hand-edited source is exactly the easy-to-miss footgun. `_warn_and_confirm_diverged` enriches the WARN with ahead/behind counts (`classify_head_vs_upstream`) so the "upstream has new commits but the local repo is dirty" case is spelled out, then **gates the build**: an interactive run must confirm (`prompt_choice`, default no), and an unattended run (`--no-interactive` or no TTY) aborts. Either decline raises, leaving nothing built (the sync runs before the sentinel). `--cleansrc` to discard local edits is the suggested escape hatch.
+`STATUS_DIVERGED` (upstream advanced but the local tree can't fast-forward — local commits or a dirty tree) gets stronger handling in the *kernel* stage than the plain warning the other verbs use, because building a kernel off stale or hand-edited source is exactly the easy-to-miss footgun. `warn_and_confirm_diverged` enriches the WARN with ahead/behind counts (`classify_head_vs_upstream`) so the "upstream has new commits but the local repo is dirty" case is spelled out, then **gates the build**: an interactive run must confirm (`prompt_choice`, default no), and an unattended run (`--no-interactive` or no TTY) aborts. Either decline raises, leaving nothing built (the sync runs before the sentinel). `--cleansrc` to discard local edits is the suggested escape hatch.
 
-The source sync (including the `--cleansrc` purge, which `purge_src` does as a non-atomic `shutil.rmtree`) runs **outside** the boot sentinel by design: it mutates only the src tree, nothing boot-critical, so wrapping it in the sentinel — whose `recovery_cmd` is `sudo mkinitcpio -P` — would be semantically wrong. The atomicity contract is "purge, then clone"; an interrupted purge leaves a missing/partial PKGBUILD that fails **loudly** at `_pkgbuild_path` on the next run (with a hint to re-run `--cleansrc` to re-clone), not a silent brick. No sentinel is needed because the running kernel was never touched.
+The source sync (including the `--cleansrc` purge, which `purge_src` does as a non-atomic `shutil.rmtree`) runs **outside** the boot sentinel by design: it mutates only the src tree, nothing boot-critical, so wrapping it in the sentinel — whose `recovery_cmd` is `sudo mkinitcpio -P` — would be semantically wrong. The atomicity contract is "purge, then clone"; an interrupted purge leaves a missing/partial PKGBUILD that fails **loudly** at `pkgbuild_path` on the next run (with a hint to re-run `--cleansrc` to re-clone), not a silent brick. No sentinel is needed because the running kernel was never touched.
 
 **Stage-ownership stamp:**
 
@@ -493,7 +493,7 @@ The AUR-dep build and per-package install loop are wrapped in `sentinel_scope(st
 
 ### Toolchain stage (stage 5)
 
-**Module layout.** The stage is a package (`pipeline/stages/toolchain/`), not a module. It was one 4263-line file with four classes and a 701-line `_build_llvm_pgo_inner`; `3.2.0-F2` split it along the seams its own comment banners already named:
+**Module layout.** The stage is a package (`pipeline/stages/toolchain/`), not a module. It was one 4263-line file with four classes and a 701-line `build_llvm_pgo_inner`; `3.2.0-F2` split it along the seams its own comment banners already named:
 
 | module | holds |
 | --- | --- |
@@ -561,17 +561,17 @@ When `compiler` is unset (or set to `"gcc"`), the toolchain stage is **register-
 
 **Build-safety gates + build/install split (kernel-parity).** The LLVM path mirrors the kernel stage's three-gate / build-install-split structure so a broken or doomed build can never leave the live `/usr` toolchain inconsistent. The pure, unit-testable facts live in `primitives/toolchain_safety.py` (`ToolchainFinding(severity, check_id, message, remediation, is_brick)`); the toolchain stage owns the abort/warn *policy*. `toolchain_safety` imports `LLVM_LOCKSTEP_SUITE` from `toolchain_preflight` (both primitives — no layering issue) and is **not** a third health-check entry point: `_verify_llvm_install` (pipeline, post-install) and `toolchain_preflight._probe_cc` (primitives, update path) remain the only two, and `_verify_llvm_install`'s skew arm now draws from `toolchain_safety.detect_suite_skew`.
 
-- **Gate 1 — pre-build preflight** (`_gate1_preflight`, outside the sentinel, runs for both PGO and non-PGO). Brick-class aborts *before any build time is spent*: PKGBUILD pkgver skew across the lockstep suite (`check_pkgver_lockstep`; `spirv-llvm-translator` + `lib32-*` are excluded so their legitimately-different versions don't false-positive — the bug the old whole-set `_check_pkgver_consistency` had); a non-functional clang (`smoke_test_compilers`, now run on the non-PGO path too); insufficient build-filesystem headroom (`check_build_space`, deduped by `st_dev`); `[multilib]` disabled while a `lib32-*` is in scope (`check_multilib_enabled`). Each brick is overridable (`--allow-version-skew`, `--allow-low-build-space`, `require_multilib = false`) and **downgraded to a warning in `--dry-run`**. Advisory (warn-only): residual `-fprofile-generate` instrumentation; an incomplete rollback snapshot.
-- **Bootstrap-compiler self-heal (inside Gate 1, `_install_bootstrap_compilers`).** The LLVM path is a 4-pass bootstrap: Pass 1 must be compiled by an *already-installed* `/usr/bin/clang`, and `lld` links every pass. Both are needed **earlier than any other build prerequisite** — before `build_core.batch_install_makedeps` runs — and neither appears in the llvm PKGBUILD's `makedepends` (upstream builds with gcc), so nothing else in the pipeline would ever install them. On a clean machine (`base-devel` ships gcc, not clang) the stage therefore bricked on `smoke:clang_missing` with a manual `pacman -S clang` hint, making the LLVM toolchain unreachable without an out-of-band step. Gate 1 now maps the *missing*-class smoke findings to their providing package (`_BOOTSTRAP_PKG_FOR`: `smoke:clang_missing`→`clang`, `smoke:lld_missing`→`lld`), installs them via `install_repo_pkgs` inside a `sentinel_scope` (a mutation window, sequential with — never nested in — the build sentinel; entered only after `sudo_session.authenticate()` succeeds, `3.5.0-B75`), then **re-runs `smoke_test_compilers` and acts on the result**, so a freshly-installed-but-broken clang still aborts. `smoke:clang_broken` is deliberately *not* auto-installable: it signals a mismatched lockstep suite from an aborted run, whose remediation is reinstalling the whole suite under the operator's eye, not a blind `-S clang`. In `--dry-run` the install is previewed and the original brick is preserved (downgraded to a warning by the enclosing gate).
+- **Gate 1 — pre-build preflight** (`gate1_preflight`, outside the sentinel, runs for both PGO and non-PGO). Brick-class aborts *before any build time is spent*: PKGBUILD pkgver skew across the lockstep suite (`check_pkgver_lockstep`; `spirv-llvm-translator` + `lib32-*` are excluded so their legitimately-different versions don't false-positive — the bug the old whole-set `_check_pkgver_consistency` had); a non-functional clang (`smoke_test_compilers`, now run on the non-PGO path too); insufficient build-filesystem headroom (`check_build_space`, deduped by `st_dev`); `[multilib]` disabled while a `lib32-*` is in scope (`check_multilib_enabled`). Each brick is overridable (`--allow-version-skew`, `--allow-low-build-space`, `require_multilib = false`) and **downgraded to a warning in `--dry-run`**. Advisory (warn-only): residual `-fprofile-generate` instrumentation; an incomplete rollback snapshot.
+- **Bootstrap-compiler self-heal (inside Gate 1, `install_bootstrap_compilers`).** The LLVM path is a 4-pass bootstrap: Pass 1 must be compiled by an *already-installed* `/usr/bin/clang`, and `lld` links every pass. Both are needed **earlier than any other build prerequisite** — before `build_core.batch_install_makedeps` runs — and neither appears in the llvm PKGBUILD's `makedepends` (upstream builds with gcc), so nothing else in the pipeline would ever install them. On a clean machine (`base-devel` ships gcc, not clang) the stage therefore bricked on `smoke:clang_missing` with a manual `pacman -S clang` hint, making the LLVM toolchain unreachable without an out-of-band step. Gate 1 now maps the *missing*-class smoke findings to their providing package (`_BOOTSTRAP_PKG_FOR`: `smoke:clang_missing`→`clang`, `smoke:lld_missing`→`lld`), installs them via `install_repo_pkgs` inside a `sentinel_scope` (a mutation window, sequential with — never nested in — the build sentinel; entered only after `sudo_session.authenticate()` succeeds, `3.5.0-B75`), then **re-runs `smoke_test_compilers` and acts on the result**, so a freshly-installed-but-broken clang still aborts. `smoke:clang_broken` is deliberately *not* auto-installable: it signals a mismatched lockstep suite from an aborted run, whose remediation is reinstalling the whole suite under the operator's eye, not a blind `-S clang`. In `--dry-run` the install is previewed and the original brick is preserved (downgraded to a warning by the enclosing gate).
 - **Soname gate — pre-build, between Gate 1 and the build** (`_gate_soname_consumers`, calls `toolchain_safety.assess_libllvm_soname_impact`). PGO/optimization never changes `libLLVM`'s `SOVERSION` or exported symbols, so a same-version rebuild is ABI-identical and silent; but a libLLVM **version bump** changes the soname (`libLLVM.so.22.1` → `libLLVM.so.23.0`), and every installed package that links the old soname (mesa's radeonsi/radv/llvmpipe, and others) is left with a dangling `NEEDED` until rebuilt. The gate derives the target soname from the resolved llvm PKGBUILD pkgver, reads the installed soname authoritatively from `llvm-libs`'s on-disk file list, and — when they differ — enumerates the installed consumers (every package whose recorded `%DEPENDS%` carries a `libLLVM.so=<old major.minor>` soname dep, via `dep_analysis._SONAME_RE`), collapsed to pkgbase and **excluding** the LLVM lockstep suite + the packages being built this run (they're rebuilt here already). The `rebuild_soname_consumers` mode (CLI `--rebuild-soname-consumers` > `toolchain.toml` > `"prompt"`) decides: `prompt` (default) warns + lists + asks, approving captures the consumers for rebuild after Gate 3 and declining is a clean abort (non-TTY aborts — never silently break the system, pointing at `=auto`/`=off`); `auto` approves without prompting; `off` builds the toolchain but rebuilds nothing, printing the manual `sysforge build <consumers>` command. `--dry-run` previews the impact without prompting or rebuilding. The consumer rebuild runs through the same PKGBUILD review policy as `update` and `build` (`pkgbuild_review.resolve_review_policy` over packages.toml `[build]`, 3.0.0-F3): with no terminal an untrusted changed consumer source is refused, and a refusal fails the stage with the manual rebuild command like any other unfinished consumer. Like `build`, it stamps `source = "repo"` on a consumer whose checkout's `origin` is the official packaging repo for that pkgbase (`aur.repo_checkout_pkgbase`: host `gitlab.archlinux.org`, project `archlinux/packaging/packages/<pkgbase>`), so the default trusted list (`["repo"]`) accepts official-repo consumers such as doxygen without a prompt; before `3.5.0-B16` every consumer was unclassified, read as `aur`, and reviewed. Provenance is the origin, never the PKGBUILD's declared names: an AUR PKGBUILD may list any `pkgname`, so a name-based test would let it skip review. The facts function is pure (guarded reads degrade to "no impact"); the stage owns the prompt/abort policy.
 - **Build (outside the sentinel).** All passes build with `install=False`; the build functions return the built package map. A build-pass failure therefore mutates nothing and leaves **no sentinel** (matches kernel).
-- **Gate 2 — pre-install ABI audit** (`_gate2_audit`, outside the sentinel, both paths). Scans the built `.pkg.tar*` for the `_ZNSt*@LLVM_*` hazard via `toolchain_safety.scan_abi_hazards`, **and** for a **graphics-consumer symbol shortfall** via `toolchain_safety.check_system_consumer_symbols`: it extracts the about-to-be-installed `libLLVM.so.*` from the built packages (lib32 excluded) and, for each installed external consumer that links that exact soname (mesa's `libgallium`/DRI/Vulkan drivers, curated in `_SYSTEM_LIBLLVM_CONSUMER_GLOBS`), checks every `LLVM_x.y`-versioned symbol the consumer imports is exported by the new libLLVM. An import one of the consumer's *other* `NEEDED` libraries exports (resolved through `ldconfig`) is not owed by libLLVM and is left out: libclang, libclang-cpp and liblldb version their own exports `LLVM_*` too, so doxygen's `clang_*@LLVM_13` and lldb's `lldb::SB*@LLVM_<ver>` would otherwise read as drift and queue a needless consumer rebuild (`3.5.0-B18`). Neither is any package the batch itself ships: besides the lockstep suite, the merged `llvm` pkgbase builds lldb, libclc and llvm-lit, whose installed copies the same `pacman -U` replaces, so the scan drops every pkgname read from the built archives' `.PKGINFO` (`toolchain_safety.shipped_pkgnames`, `3.5.0-B20`). `_diff_consumers_against_libllvm` splits a miss into two classes (see §`graphics-stack` → *Two stranding classes*): an **unhealable** target-init drop (`LLVMInitialize*` — a reduced `LLVM_TARGETS_TO_BUILD` dropped a backend the consumer needs, e.g. AMDGPU; the symbol exists nowhere) **aborts before any `pacman -U`** — nothing installed, no sentinel; a **healable** `std::` re-export drop (only non-target-init `LLVM_*` symbols — the `-fprofile-use` libLLVM inlined away the weak libstdc++ copies the stock build re-exported at the *same* soname) does **not** abort. For the healable case Gate 2 enumerates the installed libLLVM consumers via `toolchain_safety.libllvm_abi_consumers` (the reverse-dep `%DEPENDS%` walk shared with the soname gate, here un-gated on a soname change), applies the `rebuild_soname_consumers` mode (prompt/auto/off, mirroring the soname gate), and **returns** them for rebuild after Gate 3. This is the gate that `scan_abi_hazards` (intra-build only) never covered: it checks *already-installed* external consumers, the gap that let a target-reduced libLLVM ship. **`std::` export parity (`3.5.0-F4`).** The healable class cannot heal mesa built in the sandbox, which links the repo libLLVM again, so the llvm PKGBUILD's `prepare()` gains a block (`pkgbuild_patcher.patch_llvm_std_exports`, wired as `makepkg_wrapper._maybe_patch_llvm_std_exports` beside the target patch) that adds `primitives/llvm_std_exports.py`'s thunks to libLLVM: each libstdc++ member stock re-exported and the `-fprofile-use` build dropped is exported again as `sym@LLVM_<mm>` at a **non-default** version, forwarding to libstdc++'s own `@GLIBCXX_*` export. An already-linked consumer resolves it; no new link binds to it, so the suite built alongside keeps importing `@GLIBCXX_*` and `scan_abi_hazards` stays clean (default-version re-exports, the obvious fix, would trip it). The CMake hook configures itself out unless the build links with lld on x86-64 with a known `LLVM_SHLIB_SYMBOL_VERSION`. Gate 2 then reports, as `-v` narration, any pure-`std` export stock has that the build still lacks and the system `libstdc++.so.6` itself exports (only that extern-template set is imported rather than emitted by a consumer; stock exports other std instantiations only because GCC built it) (`toolchain_safety.check_std_export_parity`, against the signed stock `llvm-libs` of the same version in the pacman cache via `pacman.cached_repo_pkg_file`; skipped when none is cached). The TU goes in `llvm-shlib/sysforge/`, because LLVM's configure (`llvm_check_source_file_list`) rejects any unlisted `*.cpp` in a target's own directory. `build_fingerprint._SCHEMA` 4 keeps `--reuse-built` from reusing a libLLVM built without the thunks, and the rendered block's hash is a Pass-4 fingerprint input, so a later `STD_EXPORTS` edit invalidates reuse on its own.
+- **Gate 2 — pre-install ABI audit** (`gate2_audit`, outside the sentinel, both paths). Scans the built `.pkg.tar*` for the `_ZNSt*@LLVM_*` hazard via `toolchain_safety.scan_abi_hazards`, **and** for a **graphics-consumer symbol shortfall** via `toolchain_safety.check_system_consumer_symbols`: it extracts the about-to-be-installed `libLLVM.so.*` from the built packages (lib32 excluded) and, for each installed external consumer that links that exact soname (mesa's `libgallium`/DRI/Vulkan drivers, curated in `_SYSTEM_LIBLLVM_CONSUMER_GLOBS`), checks every `LLVM_x.y`-versioned symbol the consumer imports is exported by the new libLLVM. An import one of the consumer's *other* `NEEDED` libraries exports (resolved through `ldconfig`) is not owed by libLLVM and is left out: libclang, libclang-cpp and liblldb version their own exports `LLVM_*` too, so doxygen's `clang_*@LLVM_13` and lldb's `lldb::SB*@LLVM_<ver>` would otherwise read as drift and queue a needless consumer rebuild (`3.5.0-B18`). Neither is any package the batch itself ships: besides the lockstep suite, the merged `llvm` pkgbase builds lldb, libclc and llvm-lit, whose installed copies the same `pacman -U` replaces, so the scan drops every pkgname read from the built archives' `.PKGINFO` (`toolchain_safety.shipped_pkgnames`, `3.5.0-B20`). `_diff_consumers_against_libllvm` splits a miss into two classes (see §`graphics-stack` → *Two stranding classes*): an **unhealable** target-init drop (`LLVMInitialize*` — a reduced `LLVM_TARGETS_TO_BUILD` dropped a backend the consumer needs, e.g. AMDGPU; the symbol exists nowhere) **aborts before any `pacman -U`** — nothing installed, no sentinel; a **healable** `std::` re-export drop (only non-target-init `LLVM_*` symbols — the `-fprofile-use` libLLVM inlined away the weak libstdc++ copies the stock build re-exported at the *same* soname) does **not** abort. For the healable case Gate 2 enumerates the installed libLLVM consumers via `toolchain_safety.libllvm_abi_consumers` (the reverse-dep `%DEPENDS%` walk shared with the soname gate, here un-gated on a soname change), applies the `rebuild_soname_consumers` mode (prompt/auto/off, mirroring the soname gate), and **returns** them for rebuild after Gate 3. This is the gate that `scan_abi_hazards` (intra-build only) never covered: it checks *already-installed* external consumers, the gap that let a target-reduced libLLVM ship. **`std::` export parity (`3.5.0-F4`).** The healable class cannot heal mesa built in the sandbox, which links the repo libLLVM again, so the llvm PKGBUILD's `prepare()` gains a block (`pkgbuild_patcher.patch_llvm_std_exports`, wired as `makepkg_wrapper._maybe_patch_llvm_std_exports` beside the target patch) that adds `primitives/llvm_std_exports.py`'s thunks to libLLVM: each libstdc++ member stock re-exported and the `-fprofile-use` build dropped is exported again as `sym@LLVM_<mm>` at a **non-default** version, forwarding to libstdc++'s own `@GLIBCXX_*` export. An already-linked consumer resolves it; no new link binds to it, so the suite built alongside keeps importing `@GLIBCXX_*` and `scan_abi_hazards` stays clean (default-version re-exports, the obvious fix, would trip it). The CMake hook configures itself out unless the build links with lld on x86-64 with a known `LLVM_SHLIB_SYMBOL_VERSION`. Gate 2 then reports, as `-v` narration, any pure-`std` export stock has that the build still lacks and the system `libstdc++.so.6` itself exports (only that extern-template set is imported rather than emitted by a consumer; stock exports other std instantiations only because GCC built it) (`toolchain_safety.check_std_export_parity`, against the signed stock `llvm-libs` of the same version in the pacman cache via `pacman.cached_repo_pkg_file`; skipped when none is cached). The TU goes in `llvm-shlib/sysforge/`, because LLVM's configure (`llvm_check_source_file_list`) rejects any unlisted `*.cpp` in a target's own directory. `build_fingerprint._SCHEMA` 4 keeps `--reuse-built` from reusing a libLLVM built without the thunks, and the rendered block's hash is a Pass-4 fingerprint input, so a later `STD_EXPORTS` edit invalidates reuse on its own.
 - **Snapshot.** Right before the install, `cached_pkg_files_for(lockstep suite ∪ built names)` (in `primitives/pacman.py`) locates each currently-installed member's `.pkg.tar*` in the pacman cache. `gates.snapshot_suite` keeps only names installed before the run: a new subpackage or lib32 member has nothing to restore, and its `None` would otherwise read as a missing archive and refuse the whole rollback (`3.5.0-B76`). This is the offline-undo source. Gate 1 warns up front when any member's archive is missing (auto-undo will fall back to `pacman -S`).
-- **Gate 3 — post-install verify, inside the sentinel** (`_verify_llvm_install`). Its `expected_targets` (for the `built ⊇ expected` `llvm-config --targets-built` check) is the **actually resolved** target set — `resolve_or_detect_llvm_targets(TOOLCHAIN_PATH, <state_dir>/hardware_profile.toml)`, the same value the build patched in — **not** just `toolchain.toml [llvm] targets`. On an autodetect host that key is unset, so the old form resolved to `None` and skipped the check entirely; sourcing the resolved set makes it actually assert (after the Part-1 baseline, that includes AMDGPU). A **post-install graphics arm** then runs `toolchain_safety.check_installed_consumer_symbols(exclude=…)` (the same symbol diff as Gate 2, but vs the *now-installed* `/usr/lib/libLLVM.so.*`, the numerically newest soname via `toolchain_safety.so_version` so a compat package's older library never stands in for it (`3.5.0-B58`), excluding the same shipped pkgnames, which the install just replaced; the other callers, `doctor` and `build_core`'s post-install backstop, exclude nothing). Only **unhealable** (target-init) findings fold into the verify issues; **healable** `std::` re-export misses are *expected* here — mesa is not rebuilt until *after* Gate 3, so folding them in would auto-rollback the very libLLVM the queued consumer rebuild is about to make coherent — and are logged, not failed. On any (unhealable) failure, the stage **auto-restores** the prior-good toolchain from the snapshot in one `pacman -U` transaction (`_rollback_to_snapshot` → `batch_install_pkgs`): if restore succeeds the live `/usr` is whole again, so the sentinel is **cleared** and a `RuntimeError` is raised telling the user to investigate; if restore fails or the snapshot was incomplete, the sentinel is **kept** with `recovery_cmd` set to the snapshot restore (offline `pacman -U <cached>`, falling back to `pacman -S <suite>`). So a target-reduced libLLVM that somehow reached install is reverted automatically while rollback is still armed, rather than surfacing as a black screen at next login.
+- **Gate 3 — post-install verify, inside the sentinel** (`_verify_llvm_install`). Its `expected_targets` (for the `built ⊇ expected` `llvm-config --targets-built` check) is the **actually resolved** target set — `resolve_or_detect_llvm_targets(TOOLCHAIN_PATH, <state_dir>/hardware_profile.toml)`, the same value the build patched in — **not** just `toolchain.toml [llvm] targets`. On an autodetect host that key is unset, so the old form resolved to `None` and skipped the check entirely; sourcing the resolved set makes it actually assert (after the Part-1 baseline, that includes AMDGPU). A **post-install graphics arm** then runs `toolchain_safety.check_installed_consumer_symbols(exclude=…)` (the same symbol diff as Gate 2, but vs the *now-installed* `/usr/lib/libLLVM.so.*`, the numerically newest soname via `toolchain_safety.so_version` so a compat package's older library never stands in for it (`3.5.0-B58`), excluding the same shipped pkgnames, which the install just replaced; the other callers, `doctor` and `build_core`'s post-install backstop, exclude nothing). Only **unhealable** (target-init) findings fold into the verify issues; **healable** `std::` re-export misses are *expected* here — mesa is not rebuilt until *after* Gate 3, so folding them in would auto-rollback the very libLLVM the queued consumer rebuild is about to make coherent — and are logged, not failed. On any (unhealable) failure, the stage **auto-restores** the prior-good toolchain from the snapshot in one `pacman -U` transaction (`rollback_to_snapshot` → `batch_install_pkgs`): if restore succeeds the live `/usr` is whole again, so the sentinel is **cleared** and a `RuntimeError` is raised telling the user to investigate; if restore fails or the snapshot was incomplete, the sentinel is **kept** with `recovery_cmd` set to the snapshot restore (offline `pacman -U <cached>`, falling back to `pacman -S <suite>`). So a target-reduced libLLVM that somehow reached install is reverted automatically while rollback is still armed, rather than surfacing as a black screen at next login.
 
-- **Consumer rebuild — after Gate 3, outside the sentinel** (`_rebuild_soname_consumers`). The rebuild set is the **union** of the pre-build soname gate's consumers (a soname *bump*, mode `prompt`-approved or `auto`) and Gate 2's healable `std::` re-export drift consumers (a same-soname ABI regression) — deduped. The now-installed-and-verified toolchain is followed by a rebuild of those consumers through the shared `build_core.build_and_install` engine (resolved via `find_pkgbuild` — auto-cloning repo packages like mesa — and the user's normal profile, so they re-link the new libLLVM: a soname-bump consumer picks up the new `NEEDED`, a std::-drift consumer re-links the dropped symbols to libstdc++ `@GLIBCXX_*`). It runs **outside** the toolchain sentinel deliberately: a consumer rebuild failure must **not** roll back the intended toolchain bump — it surfaces as an actionable `RuntimeError` naming the failed packages and the manual `sysforge build` command, with the new toolchain left healthy. The system self-stabilises — once a std::-drift consumer is rebuilt it no longer imports the `…@LLVM_<ver>` `std::` symbols, so a later `run toolchain` sees no stranding and queues no rebuild.
+- **Consumer rebuild — after Gate 3, outside the sentinel** (`rebuild_soname_consumers`). The rebuild set is the **union** of the pre-build soname gate's consumers (a soname *bump*, mode `prompt`-approved or `auto`) and Gate 2's healable `std::` re-export drift consumers (a same-soname ABI regression) — deduped. The now-installed-and-verified toolchain is followed by a rebuild of those consumers through the shared `build_core.build_and_install` engine (resolved via `find_pkgbuild` — auto-cloning repo packages like mesa — and the user's normal profile, so they re-link the new libLLVM: a soname-bump consumer picks up the new `NEEDED`, a std::-drift consumer re-links the dropped symbols to libstdc++ `@GLIBCXX_*`). It runs **outside** the toolchain sentinel deliberately: a consumer rebuild failure must **not** roll back the intended toolchain bump — it surfaces as an actionable `RuntimeError` naming the failed packages and the manual `sysforge build` command, with the new toolchain left healthy. The system self-stabilises — once a std::-drift consumer is rebuilt it no longer imports the `…@LLVM_<ver>` `std::` symbols, so a later `run toolchain` sees no stranding and queues no rebuild.
 
-The mutation window is therefore exactly install → Gate 3 → (rollback), followed by the out-of-band consumer rebuild. The concurrent-run lock (`_pgo_lock`) wraps the whole build → audit → snapshot → install window, like the kernel stage's `kernel-build.lock`. Under `--dry-run` neither the lock nor the install sentinel is taken (`contextlib.nullcontext()`), so a preview writes no `stage_in_progress.toml` and never contends with a real run (`3.5.0-B74`). Gate 3's line for a healable `std::` re-export drift promises the consumer rebuild only when one is queued; with nothing queued (`rebuild_soname_consumers = off`, or the rebuild declined) it points at `sysforge build <pkg>` (`stage.healable_drift_line`, `3.5.0-B98`). A consolidated resolution summary (`_log_toolchain_resolution_summary`) prints the compiler/pgo/variant, package counts, staging paths, gate settings, and snapshot availability — the readable core of `--dry-run`.
+The mutation window is therefore exactly install → Gate 3 → (rollback), followed by the out-of-band consumer rebuild. The concurrent-run lock (`_pgo_lock`) wraps the whole build → audit → snapshot → install window, like the kernel stage's `kernel-build.lock`. Under `--dry-run` neither the lock nor the install sentinel is taken (`contextlib.nullcontext()`), so a preview writes no `stage_in_progress.toml` and never contends with a real run (`3.5.0-B74`). Gate 3's line for a healable `std::` re-export drift promises the consumer rebuild only when one is queued; with nothing queued (`rebuild_soname_consumers = off`, or the rebuild declined) it points at `sysforge build <pkg>` (`stage.healable_drift_line`, `3.5.0-B98`). A consolidated resolution summary (`log_toolchain_resolution_summary`) prints the compiler/pgo/variant, package counts, staging paths, gate settings, and snapshot availability — the readable core of `--dry-run`.
 
 **PKGBUILD resolution:** each name is first mapped to the pkgbase the sync DB says builds it (`pacman.get_sync_pkgbase`, the sync DB's `%BASE%` via `pacman -Sddp --print-format '%n %e'`), and that pkgbase, not the package name, is what `find_pkgbuild`'s lookup order (local `pkgbuild_src_dir` → `pkgctl repo clone`) searches for (`3.5.0-B13`). A repo can move a package under another pkgbase, as upstream did when it folded clang, lld, polly, compiler-rt and openmp into `llvm`; the old per-package checkouts stay on disk with a frozen tree and would otherwise win the local lookup, then fail to pin to a release their repo never tagged. A stale checkout is reported with `warn()` and left alone. A name no repo carries (AUR, local) keeps its own name, and the split-package scan still covers members of an already-resolved PKGBUILD. After path resolution, the stage routes each unique resolved `pkgbuild_dir` through `SourceSyncScheduler.sync_many()` so missing trees are cloned and pre-existing trees are refreshed against AUR/repo upstream — same RPC short-circuit, rate-limit, and dirty-tree handling as `sysforge update`. Pass `--no-update` to skip the sync step (use whatever is on disk verbatim). Blocker statuses (`STATUS_FAILED`, `STATUS_RATE_LIMITED`, `STATUS_PURGE_REFUSED`) abort the stage; `STATUS_DIVERGED` is a warning. Resolved paths are then displayed in a table and the user is prompted to confirm or abort. On abort, the resume command is printed (`sysforge pipeline --resume --state-dir <dir>`) so they can make manual modifications and return.
 
@@ -587,20 +587,20 @@ The sequence is **four builds** (Pass 1, Pass 2, Pass 3, Pass 4) across three on
 
 3. **Pass 3** — training run. CC is `<staging1>/usr/bin/clang` (built in Pass 2), and the Pass-3 environment redirects dyld / cmake at stage1 via `LD_LIBRARY_PATH=<staging1>/usr/lib:…`, `CMAKE_PREFIX_PATH=<staging1>/usr:…`, `PATH=<staging1>/usr/bin:…`. The running clang and the libLLVM it loads are guaranteed coherent because they were built together — no possibility of version drift against `/usr`. Pass 3 builds pgo + non_pgo packages; the act of running stage1's clang against stage1's instrumented libLLVM generates profraw as a side effect. `LLVM_PROFILE_FILE` uses `%m_%p` (per-module-hash + per-PID) so parallel `make -j` clang processes each write their own `.profraw` file rather than contending on one; `CCACHE_DISABLE` and `SCCACHE_DISABLE` are set so neither cache tool bypasses the instrumented compiler. `linker_flags_extra` carries the same force-loaded profile-runtime LDFLAGS, and Pass 3 likewise sets `toolchain_variant="pgo_llvm"` (lld), so its non_pgo `find_package(LLVM)` builds against stage1's instrumented `.a` archives still link cleanly. A background daemon merges profraw into `clang.profdata` every 15 seconds using adaptive batch sizing (starts at 128 files; halves on OOM; minimum batch 8). No install. After the build, Pass 3 binaries are extracted to `pgo_staging` (stage2). The stage2 outputs are **non-instrumented** since Pass 3 doesn't apply `-fprofile-generate`.
 
-   **Training-corpus enrichment (`[packages] training_corpus`, opt-in).** Pass 3's profile only reflects the code clang was made to compile, and LLVM's own C++ self-build under-exercises graphics/C-heavy codegen. `training_corpus` (default `["llvm"]`; `"llvm"` is the implicit base) lists *extra* packages — currently `"mesa"` — that Pass 3 additionally compiles **with the same instrumented stage1 clang and the same `LLVM_PROFILE_FILE`**, so their profraw lands in the same `pgo_store` and merges into the one `clang.profdata`. The resolution/build seam has one home: `_resolve_training_corpus(tcfg)` returns the non-llvm extras (unknown members warned + dropped, "llvm" stripped, deduped); the call site resolves them through the same scheduler-synced `_resolve_all_pkgbuilds` path as the toolchain packages (best-effort — a resolution miss degrades to an LLVM-only corpus with a warning, never blocks the build) and threads a `corpus_map` into `_build_llvm_pgo_inner`, which runs a second `_build_pass` right after the main training build (daemon still merging). Three invariants make this safe and correct: corpus members are **never installed** and **never `-fprofile-use` targets** (the profile stays clang-keyed — applying clang's profile *to* mesa would be a category error; that is Phase-3 mesa-PGO, a separate cycle); the corpus build uses `staged_deps=True` (`--nodeps`, no `--syncdeps`) so it keeps the **no-pacman-mutation** invariant and the extras' makedepends must already be installed; and the build is **best-effort** — a failure (missing makedep, mesa configure quirk) is logged and the run proceeds with whatever LLVM-only profraw was collected, so enrichment can never brick the toolchain build. An explicit user abort at the corpus build's failure menu is *not* a best-effort failure: it raises `makepkg_invoke.BuildAborted` (a `RuntimeError` subclass), which the corpus handler re-raises to stop the run. The corpus build gets **no** `profile_runtime_ldflag()` force-load (it links stage1's *shared* instrumented libLLVM, which carries its own runtime, and meson's doubled `LDFLAGS` would whole-load the archive twice into duplicate symbols), and runs with `pgo_reuse=False` so a member's own prior `--pgo=use` profile is not re-applied. LLVM/PGO path only (a non-PGO single-pass build generates no profraw).
+   **Training-corpus enrichment (`[packages] training_corpus`, opt-in).** Pass 3's profile only reflects the code clang was made to compile, and LLVM's own C++ self-build under-exercises graphics/C-heavy codegen. `training_corpus` (default `["llvm"]`; `"llvm"` is the implicit base) lists *extra* packages — currently `"mesa"` — that Pass 3 additionally compiles **with the same instrumented stage1 clang and the same `LLVM_PROFILE_FILE`**, so their profraw lands in the same `pgo_store` and merges into the one `clang.profdata`. The resolution/build seam has one home: `resolve_training_corpus(tcfg)` returns the non-llvm extras (unknown members warned + dropped, "llvm" stripped, deduped); the call site resolves them through the same scheduler-synced `resolve_all_pkgbuilds` path as the toolchain packages (best-effort — a resolution miss degrades to an LLVM-only corpus with a warning, never blocks the build) and threads a `corpus_map` into `build_llvm_pgo_inner`, which runs a second `build_pass` right after the main training build (daemon still merging). Three invariants make this safe and correct: corpus members are **never installed** and **never `-fprofile-use` targets** (the profile stays clang-keyed — applying clang's profile *to* mesa would be a category error; that is Phase-3 mesa-PGO, a separate cycle); the corpus build uses `staged_deps=True` (`--nodeps`, no `--syncdeps`) so it keeps the **no-pacman-mutation** invariant and the extras' makedepends must already be installed; and the build is **best-effort** — a failure (missing makedep, mesa configure quirk) is logged and the run proceeds with whatever LLVM-only profraw was collected, so enrichment can never brick the toolchain build. An explicit user abort at the corpus build's failure menu is *not* a best-effort failure: it raises `makepkg_invoke.BuildAborted` (a `RuntimeError` subclass), which the corpus handler re-raises to stop the run. The corpus build gets **no** `profile_runtime_ldflag()` force-load (it links stage1's *shared* instrumented libLLVM, which carries its own runtime, and meson's doubled `LDFLAGS` would whole-load the archive twice into duplicate symbols), and runs with `pgo_reuse=False` so a member's own prior `--pgo=use` profile is not re-applied. LLVM/PGO path only (a non-PGO single-pass build generates no profraw).
 
 4. **Pass 4** — final optimized build of pgo + non_pgo (+ lib32 only if explicitly opted in; empty by default — see *lib32 is not toolchain-managed*) with `-fprofile-use=<clang.profdata>`. It is split into coherent sub-passes so the non-pgo suite links against **the exact libLLVM that ships**, not the live `/usr` one:
 
    - **4a — pgo** (`llvm`, `llvm-libs`): the optimized PGO build. CC selection is conditional on whether `<pgo_staging>/usr/bin/clang` exists: when the PGO set includes `clang` (so Pass 3 produced a staged clang), 4a uses `CC=<pgo_staging>/usr/bin/clang` and redirects dyld / cmake at stage2 (`LD_LIBRARY_PATH`/`CMAKE_PREFIX_PATH`/`PATH`) — the staged clang's NEEDED libLLVM is stage2's, so the redirect is ABI-coherent. The shipped default only PGO-builds `llvm`/`llvm-libs` (clang is `non_pgo`, lives in stage1, never stage2), so the **system-clang fallback** applies: `CC=/usr/bin/clang` with the stage2 redirect **suppressed** (pointing stock clang at stage2's `LLVM_TARGETS_TO_BUILD`-restricted libLLVM would recreate the Pass 2 version-skew failure — missing target-init symbols like `LLVMInitializeBPFTarget`).
-   - **stage3 extract** — the just-built optimized `llvm`/`llvm-libs` `.pkg.tar*` are extracted into `pgo_staging3` (via `_extract_pass2_to_staging`), so `<pgo_staging3>/usr` holds the libLLVM + headers + cmake configs that the install will ship. **Both split members must be staged**: `llvm-libs` carries `libLLVM.so*` while the `llvm` (dev) package carries `usr/lib/cmake/llvm/LLVMConfig.cmake` and the headers — without the latter, 4b's `find_package(LLVM)` finds nothing under `CMAKE_PREFIX_PATH` and silently falls back to the system `/usr` libLLVM (defeating the whole split → Gate-3 brick). Because the artifact lookup matches per-pkgname, the glob is **version-anchored** (`{name}-[0-9]*-*.pkg.tar*`, same idiom as `pacman.cached_pkg_files_for`) so the shorter `llvm` pkgname does not swallow the `llvm-libs-…` sibling artifact. As a belt-and-suspenders guard, `_assert_staging_has_llvm_cmake(pgo_staging3)` runs immediately after extraction and **aborts before install** if `LLVMConfig.cmake` is absent — converting a multi-hour build + bricked install into an immediate, actionable error.
-   - **4b — non_pgo** (`clang`, `lld`, …): steered at the just-built optimized libLLVM via **both** `CMAKE_PREFIX_PATH=<pgo_staging3>/usr` (build env) **and** a `-DLLVM_DIR="<pgo_staging3>/usr/lib/cmake/llvm"` injected into the PKGBUILD `cmake` line (`pkgbuild_patcher.patch_llvm_dir`, threaded as `cmake_llvm_dir` through `_build_pass` → `make_build_options` → `_run_build`). The env var alone proved **insufficient**: `find_package(LLVM CONFIG)` silently resolved the live `/usr` libLLVM despite `CMAKE_PREFIX_PATH` (env-var search precedence lost to the system prefix), so clang/lld linked the wrong libLLVM and bricked at Gate 3. `LLVM_DIR` is the highest-precedence config-mode override — a cmake **cache** variable, checked before any prefix search and persisted in `CMakeCache.txt` across the PKGBUILD's repeated `cmake ..` calls (so injecting after the first invocation is sufficient, mirroring `patch_llvm_targets`). Both cmake-arg injectors append the new `-D` arg at the **true end of the (possibly `\`-continued) cmake statement** (`_cmake_statement_end`), not the first newline — so `-DLLVM_TARGETS_TO_BUILD` (injected first, for `clang`/`lld`/`compiler-rt`) and `-DLLVM_DIR` compose on one command. Inserting at the first newline instead splices the second arg into the first's continuation chain and orphans an arg, which bash then runs as a command (`-DLLVM_TARGETS_TO_BUILD…: command not found`, `build()` exit 4). Both injectors also anchor on the cmake **configure** invocation via `_find_cmake_configure_anchor`, **not** a bare `^cmake\b` line match: the anchor requires a same-line argument (so a lone `cmake` element in a multi-line `makedepends=(...)` array — e.g. `spirv-llvm-translator` — is never chosen; the loose match spliced `-DLLVM_DIR` into the dependency array and makepkg rejected it, exit 12) and skips action-mode invocations (`cmake --build`/`--install`/`-E`/…) which ignore `-D` cache args. **Post-patch validation gate:** after all injectors run and before makepkg, `pkgbuild_patcher.validate_patched_pkgbuild` (called from `makepkg_wrapper._run_build`, gated to the injection path) re-parses the patched PKGBUILD and fails fast on the two corruption classes that previously surfaced only hours into a build — **G1** requires the parsed dependency/identity globals (`depends`/`makedepends`/`checkdepends`/`provides`/… via `pkgbuild_meta.parse_pkgbuild`) to be unchanged from upstream (catches a `-D` arg landing in a dep array), and **G2** requires each managed injected token (`-DLLVM_TARGETS_TO_BUILD=`/`-DLLVM_DIR=`) to ride a `cmake` command's continuation-joined logical line (catches an orphaned arg, while ignoring legitimate `-D …` *array elements* like `cmake_options=(-D FOO=ON)` since only the two managed tokens are checked). A violation raises `PkgbuildPatchError` and aborts before anything is built. **Why this matters:** the std::-symbol re-export profile flips between build modes — stock/instrumented libLLVM emits an out-of-line weak copy of e.g. `std::string::_M_assign`, which the `LLVM_X.Y { global: *; }` version script globs into the LLVM namespace (so libLLVM *exports* `_M_assign@@LLVM_X.Y`), while the `-fprofile-use` build inlines it away and imports it from libstdc++ (`@GLIBCXX_*`). If clang were built against an *exporting* libLLVM (stock `/usr`, stage1, or stage2) but the run ships the *non-exporting* PGO libLLVM, `libclang-cpp` would dangle `_ZNSt*@LLVM_X.Y` and the live clang would brick at the first symbol lookup. Building 4b against stage3 makes clang record its true ABI (`@GLIBCXX_*`), coherent with the shipped libLLVM. As in Pass 2, **only `CMAKE_PREFIX_PATH` is set in the env, never `LD_LIBRARY_PATH`** (the host clang compiles the source; it must not be forced to *load* the staged libLLVM — `-DLLVM_DIR` steers only the cmake config lookup, not the runtime loader; build-tree tools get stage3 via the same narrowed build RPATH as Pass 2). **Post-build link assertion:** immediately after 4b (still pre-install), `_assert_pass_links_shipped_libllvm` reruns `toolchain_safety.scan_abi_hazards` on the just-built `clang`/`lld` `.pkg.tar*`; a correctly-steered build yields **zero** `_ZNSt*@LLVM_*` undefined refs, so a non-empty result means the steering was *still* defeated and the stage aborts **before install** (no sentinel, no rollback), naming the offending pass — the earliest, most specific catch.
+   - **stage3 extract** — the just-built optimized `llvm`/`llvm-libs` `.pkg.tar*` are extracted into `pgo_staging3` (via `_extract_pass2_to_staging`), so `<pgo_staging3>/usr` holds the libLLVM + headers + cmake configs that the install will ship. **Both split members must be staged**: `llvm-libs` carries `libLLVM.so*` while the `llvm` (dev) package carries `usr/lib/cmake/llvm/LLVMConfig.cmake` and the headers — without the latter, 4b's `find_package(LLVM)` finds nothing under `CMAKE_PREFIX_PATH` and silently falls back to the system `/usr` libLLVM (defeating the whole split → Gate-3 brick). Because the artifact lookup matches per-pkgname, the glob is **version-anchored** (`{name}-[0-9]*-*.pkg.tar*`, same idiom as `pacman.cached_pkg_files_for`) so the shorter `llvm` pkgname does not swallow the `llvm-libs-…` sibling artifact. As a belt-and-suspenders guard, `assert_staging_has_llvm_cmake(pgo_staging3)` runs immediately after extraction and **aborts before install** if `LLVMConfig.cmake` is absent — converting a multi-hour build + bricked install into an immediate, actionable error.
+   - **4b — non_pgo** (`clang`, `lld`, …): steered at the just-built optimized libLLVM via **both** `CMAKE_PREFIX_PATH=<pgo_staging3>/usr` (build env) **and** a `-DLLVM_DIR="<pgo_staging3>/usr/lib/cmake/llvm"` injected into the PKGBUILD `cmake` line (`pkgbuild_patcher.patch_llvm_dir`, threaded as `cmake_llvm_dir` through `build_pass` → `make_build_options` → `_run_build`). The env var alone proved **insufficient**: `find_package(LLVM CONFIG)` silently resolved the live `/usr` libLLVM despite `CMAKE_PREFIX_PATH` (env-var search precedence lost to the system prefix), so clang/lld linked the wrong libLLVM and bricked at Gate 3. `LLVM_DIR` is the highest-precedence config-mode override — a cmake **cache** variable, checked before any prefix search and persisted in `CMakeCache.txt` across the PKGBUILD's repeated `cmake ..` calls (so injecting after the first invocation is sufficient, mirroring `patch_llvm_targets`). Both cmake-arg injectors append the new `-D` arg at the **true end of the (possibly `\`-continued) cmake statement** (`_cmake_statement_end`), not the first newline — so `-DLLVM_TARGETS_TO_BUILD` (injected first, for `clang`/`lld`/`compiler-rt`) and `-DLLVM_DIR` compose on one command. Inserting at the first newline instead splices the second arg into the first's continuation chain and orphans an arg, which bash then runs as a command (`-DLLVM_TARGETS_TO_BUILD…: command not found`, `build()` exit 4). Both injectors also anchor on the cmake **configure** invocation via `_find_cmake_configure_anchor`, **not** a bare `^cmake\b` line match: the anchor requires a same-line argument (so a lone `cmake` element in a multi-line `makedepends=(...)` array — e.g. `spirv-llvm-translator` — is never chosen; the loose match spliced `-DLLVM_DIR` into the dependency array and makepkg rejected it, exit 12) and skips action-mode invocations (`cmake --build`/`--install`/`-E`/…) which ignore `-D` cache args. **Post-patch validation gate:** after all injectors run and before makepkg, `pkgbuild_patcher.validate_patched_pkgbuild` (called from `makepkg_wrapper._run_build`, gated to the injection path) re-parses the patched PKGBUILD and fails fast on the two corruption classes that previously surfaced only hours into a build — **G1** requires the parsed dependency/identity globals (`depends`/`makedepends`/`checkdepends`/`provides`/… via `pkgbuild_meta.parse_pkgbuild`) to be unchanged from upstream (catches a `-D` arg landing in a dep array), and **G2** requires each managed injected token (`-DLLVM_TARGETS_TO_BUILD=`/`-DLLVM_DIR=`) to ride a `cmake` command's continuation-joined logical line (catches an orphaned arg, while ignoring legitimate `-D …` *array elements* like `cmake_options=(-D FOO=ON)` since only the two managed tokens are checked). A violation raises `PkgbuildPatchError` and aborts before anything is built. **Why this matters:** the std::-symbol re-export profile flips between build modes — stock/instrumented libLLVM emits an out-of-line weak copy of e.g. `std::string::_M_assign`, which the `LLVM_X.Y { global: *; }` version script globs into the LLVM namespace (so libLLVM *exports* `_M_assign@@LLVM_X.Y`), while the `-fprofile-use` build inlines it away and imports it from libstdc++ (`@GLIBCXX_*`). If clang were built against an *exporting* libLLVM (stock `/usr`, stage1, or stage2) but the run ships the *non-exporting* PGO libLLVM, `libclang-cpp` would dangle `_ZNSt*@LLVM_X.Y` and the live clang would brick at the first symbol lookup. Building 4b against stage3 makes clang record its true ABI (`@GLIBCXX_*`), coherent with the shipped libLLVM. As in Pass 2, **only `CMAKE_PREFIX_PATH` is set in the env, never `LD_LIBRARY_PATH`** (the host clang compiles the source; it must not be forced to *load* the staged libLLVM — `-DLLVM_DIR` steers only the cmake config lookup, not the runtime loader; build-tree tools get stage3 via the same narrowed build RPATH as Pass 2). **Post-build link assertion:** immediately after 4b (still pre-install), `assert_pass_links_shipped_libllvm` reruns `toolchain_safety.scan_abi_hazards` on the just-built `clang`/`lld` `.pkg.tar*`; a correctly-steered build yields **zero** `_ZNSt*@LLVM_*` undefined refs, so a non-empty result means the steering was *still* defeated and the stage aborts **before install** (no sentinel, no rollback), naming the offending pass — the earliest, most specific catch.
    - **4c — lib32** (only when explicitly opted in): same `CMAKE_PREFIX_PATH=<pgo_staging3>/usr` + `-DLLVM_DIR` steering and the same post-build link assertion.
 
    Across all sub-passes `LLVM_PROFILE_FILE` is cleared so any inherited Pass-3 training env can't leak, and `linker_flags_extra` is left unset (stage3's LLVM is non-instrumented — no `__llvm_profile_*` references, and no Pass 2/3 residual flag leaks into the final binaries). The install — the **only** `sudo pacman -U` against `/usr` — runs after the Gate-2 audit on the built packages. Staging prefixes (stage2 *and* stage3) are removed only **after** the post-install verify passes (see below), so a failed verify keeps the stage prefixes on disk for diagnostic inspection. Profdata is **preserved** at `<pgo_store>/clang.profdata`; a version sidecar `clang.profdata.version` (LLVM major integer, e.g. `22`) is written alongside it so `sysforge update` can check compatibility before reusing the profdata.
 
 **Merged `llvm` pkgbase (`3.5.0-F2`).** Upstream builds clang, lld, lldb, polly, compiler-rt, openmp, offload, libc++, libclc, the WASI runtimes and `llvm-bolt` from the one `llvm` PKGBUILD since 23.1.3-2 (one CMake tree with `LLVM_ENABLE_PROJECTS` + `LLVM_ENABLE_RUNTIMES`). After resolution (which maps each name to its sync-DB pkgbase, `3.5.0-B13`) those names point at the same PKGBUILD as `llvm`, and `pkgbuilds.partition_by_pkgbuild` moves every name a pgo PKGBUILD builds into the pgo map before the passes are planned. The four passes then need no layout switch: Pass 1 instruments the whole tree, clang included, so stage1 has its own clang and `libclang-cpp` is profiled for the first time; Pass 2 and 4b keep only the separate pkgbases (`spirv-llvm-translator`, now also an llvm makedepend); Pass 3 trains with stage1's clang; Pass 4a optimizes the whole tree once. Left in `non_pgo`, the merged names would send the full llvm tree through Pass 2 and 4b again. With the old per-package PKGBUILDs nothing shares a file and nothing moves. **What gets installed.** `makepkg --packagelist` now yields 18 packages; the install step takes `pkgbuilds.install_names` (the configured names plus every *installed* member of the built PKGBUILDs, e.g. lldb and libclc) and `profdata.select_install_members` closes that set over `depend` edges between the built members (clang → `clang-libs=<ver>`), so no member is left on the old version against the new libLLVM and none is newly pulled in. The rollback snapshot (`gates.snapshot_suite(extra_names=…)`) covers the same set. Not yet done: trimming lldb, libc++, the offload device runtimes, libclc and WASI out of the instrumented and training passes, which would shorten them.
 
-**Pre-install ABI hazard check (Gate 2).** Between the Pass-4 build and the final `sudo pacman -U`, `_gate2_audit` extracts each built `.pkg.tar*`'s shared libraries and scans their `nm -D` output via `toolchain_safety.scan_abi_hazards` (which uses `abi_check._undefined_versioned`). Any UND versioned symbol whose mangled name is in the C++ stdlib namespace (`_ZNSt*`) and whose version starts with `LLVM_` is a hard block: it means a built binary (typically `libclang-cpp.so`) recorded a `std::string` (or similar) requirement against the `LLVM_X.Y` version namespace — i.e. clang was linked against a libLLVM that *re-exports* the C++ stdlib while the run ships one that does not. Installing those binaries would leave the live toolchain unable to resolve `std::string` methods at runtime (`symbol lookup error: libclang-cpp.so: undefined symbol _ZNSt..., version LLVM_22.1`). The Pass-4 coherent sub-pass split (4b builds the non-pgo suite against the shipped libLLVM in stage3) is the **primary** prevention; the 4b/4c post-build link assertion (above) is the earliest catch; Gate 2 is the final **backstop** that refuses to install if a hazard slips through anyway. Gate 2 runs *outside* the sentinel, so a hazard aborts with the live `/usr` intact and **no sentinel**; the user is told to restart with `--rebuild-profdata`. (This scan moved out of `_pgo_install` — which now only installs — and is shared with the non-PGO path.) Gate 2 (and the 4b/4c assertion) depend on `abi_check._extract_sos` actually extracting: it now `mkdir`s its destination before `bsdtar -x -C` (`scan_abi_hazards` extracts each package into a per-package subdir to avoid same-named `.so` collisions, and that subdir does not pre-exist — without the `mkdir`, `bsdtar` failed with *"could not chdir to …"*, the audit saw zero shared objects, and the gate passed **vacuously**, which is exactly how the brick reached install).
+**Pre-install ABI hazard check (Gate 2).** Between the Pass-4 build and the final `sudo pacman -U`, `gate2_audit` extracts each built `.pkg.tar*`'s shared libraries and scans their `nm -D` output via `toolchain_safety.scan_abi_hazards` (which uses `abi_check._undefined_versioned`). Any UND versioned symbol whose mangled name is in the C++ stdlib namespace (`_ZNSt*`) and whose version starts with `LLVM_` is a hard block: it means a built binary (typically `libclang-cpp.so`) recorded a `std::string` (or similar) requirement against the `LLVM_X.Y` version namespace — i.e. clang was linked against a libLLVM that *re-exports* the C++ stdlib while the run ships one that does not. Installing those binaries would leave the live toolchain unable to resolve `std::string` methods at runtime (`symbol lookup error: libclang-cpp.so: undefined symbol _ZNSt..., version LLVM_22.1`). The Pass-4 coherent sub-pass split (4b builds the non-pgo suite against the shipped libLLVM in stage3) is the **primary** prevention; the 4b/4c post-build link assertion (above) is the earliest catch; Gate 2 is the final **backstop** that refuses to install if a hazard slips through anyway. Gate 2 runs *outside* the sentinel, so a hazard aborts with the live `/usr` intact and **no sentinel**; the user is told to restart with `--rebuild-profdata`. (This scan moved out of `pgo_install` — which now only installs — and is shared with the non-PGO path.) Gate 2 (and the 4b/4c assertion) depend on `abi_check._extract_sos` actually extracting: it now `mkdir`s its destination before `bsdtar -x -C` (`scan_abi_hazards` extracts each package into a per-package subdir to avoid same-named `.so` collisions, and that subdir does not pre-exist — without the `mkdir`, `bsdtar` failed with *"could not chdir to …"*, the audit saw zero shared objects, and the gate passed **vacuously**, which is exactly how the brick reached install).
 
 **ABI-safety invariant (Path B).** The live `/usr` is observably coherent before and after every step except the single final `pacman -U`, and even that is now reversible: Gate 3 verifies the result and auto-rolls-back to the snapshot on failure. A run that aborts before install (build failure, Gate 1, or Gate 2) leaves the system exactly as `sysforge run toolchain` found it — nothing installed, no sentinel. A run whose install verifies-bad restores the prior-good suite from the pacman cache. No half-installed instrumented `libLLVM.so`, no orphaned `/usr/bin/clang` that can't resolve `LLVMInitializeBPFTarget@LLVM_22.1`. The only role `/usr/bin/clang` plays in the run is **as a bootstrap host compiler in Pass 2** (compiling source into objects, never loading a different-version libLLVM); version drift between the in-tree LLVM source and the installed system packages is therefore no longer a failure mode.
 
@@ -612,23 +612,23 @@ The sequence is **four builds** (Pass 1, Pass 2, Pass 3, Pass 4) across three on
 
 **BOLT inside the llvm build (opt-in, EXPERIMENTAL, `3.5.0-F3`).** With `toolchain.toml [bolt] enabled = true`, BOLT (Binary Optimization and Layout Tool) is layered on the PGO toolchain, the canonical **PGO→BOLT "fast clang"** stack. It is the fourth method on the shared profile-store rails and the only **post-link** one, so it has no compiler flag: the facts and subprocess seams live in `primitives/bolt.py`, the orchestration in `toolchain/bolt.py::optimize_in_build`. Where it runs follows from four facts a spike against `extra/llvm-bolt` 23.1.3-3 established. (1) **The targets are the shared libraries.** With `LLVM_LINK_LLVM_DYLIB=ON` the `clang` executable is a ~100 KB driver; the code is in `libclang-cpp.so` (always rewritten) and `libLLVM.so` (only with `[bolt] libllvm`, since every libLLVM consumer on the system loads it). (2) **It runs inside the build.** BOLT refuses stripped input and instrumentation needs relocations, but makepkg strips while packaging, and only the copies in `$pkgdir`: right after Pass 4a the **build tree** (`bolt.build_tree_for`: `<BUILDDIR>/<pkgbase>/src/llvm-project-*/build`, under the root Pass 4a reported building in, which `build_pass(build_roots=…)` collects from `makepkg_wrapper.run` so a profile's `BUILDDIR` wins over the system `makepkg.conf`'s; `--cleanbuild` clears `src` *before* a build, so the tree is 4a's) still holds unstripped libraries linked with `-Wl,--emit-relocs` (threaded as `linker_flags_extra` into 4a and 4b). sysforge rewrites them there and then reruns only `package()` (`makepkg --repackage --force`, with 4a's settings and source sync off, since a re-pinned tree would not be the one just rewritten). Each replacement keeps the original mtime (`bolt.replace_keep_mtime`): ninja records output mtimes in `.ninja_log`, so a changed one makes `package()`'s `ninja install-…` relink the library and silently restore the un-BOLTed file. This needs upstream's merged `llvm` pkgbase (`3.5.0-F2`), which builds clang and `bolt` in the same tree as llvm. (3) **It profiles by instrumentation.** `perf record -j any` needs branch-stack sampling, which the tested Zen 3 hardware lacks; `llvm-bolt -instrument` is hardware-independent. The instrumented libraries are trained by replaying up to `TRAINING_UNITS` of the tree's own compile commands (`bolt.training_commands`: `ninja -t commands <libclang-cpp target>`, clang's front-end sources first, compiler swapped for the tree's new `clang++`, outputs and dependency files kept out of the tree) under `LD_LIBRARY_PATH`, or by compiling `[bolt] training_workload` when set; fewer than half succeeding means the instrumented libraries are broken and the profile is not used. (4) **It uses the in-tree tools, checking the runtime first.** `llvm-bolt`, `merge-fdata` and `libbolt_rt_instr.a` come from the same build tree. A runtime built by GCC with `-fno-plt` (Arch's packaged one) calls `memset` through the GOT, which BOLT's JITLink rejects for every input ("unsupported edge kind RequestGOTAndTransformToPCRel32GOTLoadRelaxable"); `bolt.runtime_linkable` checks for `GOTPCRELX` relocations up front. The flags are LLVM 23's spellings (`-reorder-functions=cdsort`, `-icf=all`; `hfsort+` and numeric `-icf` are deprecated). **Kept originals and `--bolt-only`.** Before replacing a library, `optimize_in_build` keeps the un-BOLTed copy in `lib/.sysforge-prebolt/` (mtime intact) and restores it before every cycle, so a rerun on the same tree starts from it; a library carrying BOLT's `.note.bolt_info` with no kept original is refused (`bolt.is_bolted`), since rewriting BOLT output is unsupported. A Pass-4a rebuild clears `src`, so a kept original never outlives its tree. `run toolchain --bolt-only` (`pgo.bolt_only`, branched in `stage.py` in place of `build_llvm_pgo_inner`) builds nothing: `toolchain/bolt.check_bolt_only_tree` refuses unless llvm's `build_state` record says `pgo_llvm` at the PKGBUILD's version, `libclang-cpp` carries relocations (only Pass 4 links `--emit-relocs`, so an earlier pass's tree has none), and llvm's PKGDEST artifacts are no older than it; the tree is found under the `BUILDDIR` that record's `flags_string` holds (`build_state.recorded_builddir`). It then BOLTs with `[bolt] enabled` forced on and `strict=True` (every skip raises, since reinstalling unchanged packages achieves nothing), repackages llvm through the same `_repackage_llvm` as 4a, and returns the whole suite so Gate 2, the install and Gate 3 run unchanged on the packages the last run built. The pre-install confirmation asks about BOLT and install rather than a build, the resolution summary names the mode and drops the build-only staging rows, and Gate 1 skips the `min_build_free_gb` headroom check (a repackage needs a fraction of it; the lockstep, compiler and multilib checks still run). The flag implies `--no-update` (a sync could re-pin the PKGBUILD off the tree's version) and the verb's `pre_check` refuses it with `--rebuild-profdata`, `--reuse-built` or `--cleansrc[-force]`. Its record check (llvm's `build_state` says `pgo_llvm` at the PKGBUILD's version) is `pkgbuilds.check_last_pgo_build`, shared with `--install-only`. Passes 1 to 3 build as `pgo_llvm` too (its lld guard and overlays), so they pass `record_variant=constants.INTERMEDIATE_VARIANT` through `build_pass`/`build_pkg` to `BuildOptions.record_toolchain_variant`, which replaces only the variant `_record_build_state` writes: a run that stops before Pass 4 leaves `pgo_llvm_intermediate`, which the check refuses as instrumented or a bootstrap, and Pass 4 overwrites it with `pgo_llvm` (`3.5.0-B39`). The training-corpus extras keep recording `pgo_llvm`, so the user's mesa record is not made to read as drifted. **`run toolchain --install-only` (`pgo.install_only`).** The recovery for a run that built (and BOLTed) the suite but did not install it, such as an install sudo prompt nobody answered: after that same record check, every PKGBUILD of the suite must have a built package at its version in PKGDEST (`profdata.collect_pgo_packages`, the `makepkg --packagelist` lookup the install itself uses), and the whole suite is returned so Gate 2, the snapshot, the install and Gate 3 run as after a build. It shares `--bolt-only`'s handling: `gates.no_build_mode` names the mode for the plan header, the confirmation and Gate 1's skipped headroom check; the stage refuses it outside the PGO LLVM configuration; it implies `--no-update`; and `pre_check` refuses it with the build flags or `--bolt-only`. A failed PGO install (`pacman -U` non-zero, sentinel kept) and the pre-sentinel sudo refusal both name it as the retry, as does the sentinel's `retry_cmd`. **Failure handling.** Any failure up to and including the smoke test (a compile with the rewritten libraries) warns and leaves the build tree and the 4a packages exactly as built, so the PGO toolchain installs un-BOLTed. A failed repackage restores the tree and stops the stage *before* install, since the 4a packages may be half-rewritten by then. Merged profiles are kept in the `bolt` store. The rewritten libraries ship under their stock names in the normal install, covered by Gate 2/3 and the snapshot rollback like the rest of the suite; `pacman -Qkk` sees nothing modified, since the rewrite happens before packaging. **Not yet verified on a full build:** the sequence is covered by unit tests and by spikes of each step on small libraries (instrumentation of a PIC C++ shared library with exceptions, TLS and a forked child; ninja's mtime behaviour), not by an end-to-end `run toolchain`; it stays `enabled = false` by default. LLVM/PGO path only.
 
-**Dep resolution for staged passes.** Pass 1 (and the non-PGO single pass) build against the live `/usr`. Their missing repo build tools (cmake, ninja, python, z3, libffi, …) are installed by sysforge before the pass, through `build_core.install_missing_repo_deps` (the same repo arm `prepare_deps` uses, excluding the pass's own packages so the stock copy of what is being built is never installed). makepkg itself runs with `--syncdeps` always stripped, so it never escalates inside the build's forwarded output (`3.4.0-F1`); a password prompt is sysforge's own, with the progress bar yielded. Pass 2, Pass 3, and Pass 4 build against a stage prefix; `CMAKE_PREFIX_PATH=<staging>/usr` makes `find_package(LLVM)` see the staged headers and cmake configs, but pacman has no knowledge of those staged packages. `_build_pass(staged_deps=True)` therefore strips `--syncdeps`/`-s` (via the shared `SYNC_FLAGS` constant from `makepkg_wrapper.py`, the same set `pacman.BATCH_STRIP_FLAGS` removes for batch builds) from the resolved profile's makepkg flags and appends `--nodeps` for those three passes. Without that, makepkg's pre-build dep check would invoke `sudo pacman -S llvm=<pkgver>` and fail with "target not found" (the just-built version is not in any repo). The non-llvm build deps stay required, so `build_llvm_pgo_inner` installs them once before any pass, for every PKGBUILD of the run (pgo, non-pgo and lib32) with the whole suite excluded (`3.5.0-B15`). Pass 1's own pre-install covers only the pgo PKGBUILD, and a profdata-reuse run skips Pass 1 entirely: before this, the merged `llvm` PKGBUILD's new makedepends (`wasi-libc`) were never installed on that path, and 4a died in the wasm32 libc++ build with an unresolved `::mbstate_t`. `build_pass(install=True)` (no current caller: every pass builds without installing, and the toolchain installs as one batch inside the sentinel) likewise never passes `--install` to makepkg; it installs through `makepkg_wrapper.install_built_packages` after the build.
+**Dep resolution for staged passes.** Pass 1 (and the non-PGO single pass) build against the live `/usr`. Their missing repo build tools (cmake, ninja, python, z3, libffi, …) are installed by sysforge before the pass, through `build_core.install_missing_repo_deps` (the same repo arm `prepare_deps` uses, excluding the pass's own packages so the stock copy of what is being built is never installed). makepkg itself runs with `--syncdeps` always stripped, so it never escalates inside the build's forwarded output (`3.4.0-F1`); a password prompt is sysforge's own, with the progress bar yielded. Pass 2, Pass 3, and Pass 4 build against a stage prefix; `CMAKE_PREFIX_PATH=<staging>/usr` makes `find_package(LLVM)` see the staged headers and cmake configs, but pacman has no knowledge of those staged packages. `build_pass(staged_deps=True)` therefore strips `--syncdeps`/`-s` (via the shared `SYNC_FLAGS` constant from `makepkg_wrapper.py`, the same set `pacman.BATCH_STRIP_FLAGS` removes for batch builds) from the resolved profile's makepkg flags and appends `--nodeps` for those three passes. Without that, makepkg's pre-build dep check would invoke `sudo pacman -S llvm=<pkgver>` and fail with "target not found" (the just-built version is not in any repo). The non-llvm build deps stay required, so `build_llvm_pgo_inner` installs them once before any pass, for every PKGBUILD of the run (pgo, non-pgo and lib32) with the whole suite excluded (`3.5.0-B15`). Pass 1's own pre-install covers only the pgo PKGBUILD, and a profdata-reuse run skips Pass 1 entirely: before this, the merged `llvm` PKGBUILD's new makedepends (`wasi-libc`) were never installed on that path, and 4a died in the wasm32 libc++ build with an unresolved `::mbstate_t`. `build_pass(install=True)` (no current caller: every pass builds without installing, and the toolchain installs as one batch inside the sentinel) likewise never passes `--install` to makepkg; it installs through `makepkg_wrapper.install_built_packages` after the build.
 
 **Staging-prefix ownership (`3.5.0-B54`).** The three prefixes are fixed names in world-writable `/var/tmp`, and their contents run later in the build (`stage_env` puts them first on `PATH`/`LD_LIBRARY_PATH`/`CMAKE_PREFIX_PATH`, and Pass 4a uses stage2's clang as `CC`). Another local user who created a name first, or planted a symlink, would have their files run. So extraction creates a prefix 0700 through `fs_provision.ensure_private_dir`, and `fs_provision.check_private_dir` refuses a symlink, a non-directory, a directory another uid owns, or one others can write to, at extraction, in `stage_env` and before the staged clang becomes `CC`. The fresh-build purge checks owner and symlink only (`check_mode=False`): it deletes the contents, so their mode cannot matter. `/var/tmp`'s sticky bit keeps anyone else from replacing a directory this user owns, so ownership plus mode is sufficient.
 
-**Concurrent-run lock.** `ToolchainStage.run` acquires an advisory `flock(2)` (`_pgo_lock`, the shared `build_lock` primitive) on `_pgo_lock_path(staging1)` = `<pgo_staging1>.parent/sysforge-pgo.lock` (typically `/var/tmp/sysforge-pgo.lock`) around the whole build → audit → snapshot → install window — not just the PGO passes, so the non-PGO path is guarded too (mirroring the kernel stage's `kernel-build.lock`). The sentinel scope guards re-entry on the state-dir but not the `/var/tmp` staging dirs or `~/pgo`, both of which two concurrent runs would corrupt. The lock file holds the owner's PID, so the loser surfaces "another sysforge PGO build is running (pid N)" rather than a confusing mid-flow failure. The path is in `staging1.parent` rather than inside `pgo_store` so the Pass-1 purge cannot delete it. Skipped in `--dry-run` (the lock file would be a side effect) — so a dry run, unlocked, must never mutate the shared prefixes either: `profdata.remove_staging(staging, dry_run)` takes `dry_run` as a required argument and only logs on a dry run. The Pass-4 stage3 clear was the one unguarded deletion; a concurrent dry run (the stage test suite included) removed stage3 under a real run's Pass 4b clang, which then compiled against `/usr/include`'s older LLVM headers (`3.3.0-B9`). The path's one home is `primitives/makepkg_pgo.py` (`pgo_lock_path`, `resolve_pgo_lock_path`, and `DEFAULT_PGO_STAGING_1`, which `constants.DEFAULT_STAGING_1` re-exports) because `makepkg_wrapper.run` probes the same lock to leave a running PGO build's `pgo_store` alone (`3.3.0-B8`, §Stale-profraw post-build check), and `primitives/` cannot import from `pipeline/`.
+**Concurrent-run lock.** `ToolchainStage.run` acquires an advisory `flock(2)` (`_pgo_lock`, the shared `build_lock` primitive) on `pgo_lock_path(staging1)` = `<pgo_staging1>.parent/sysforge-pgo.lock` (typically `/var/tmp/sysforge-pgo.lock`) around the whole build → audit → snapshot → install window — not just the PGO passes, so the non-PGO path is guarded too (mirroring the kernel stage's `kernel-build.lock`). The sentinel scope guards re-entry on the state-dir but not the `/var/tmp` staging dirs or `~/pgo`, both of which two concurrent runs would corrupt. The lock file holds the owner's PID, so the loser surfaces "another sysforge PGO build is running (pid N)" rather than a confusing mid-flow failure. The path is in `staging1.parent` rather than inside `pgo_store` so the Pass-1 purge cannot delete it. Skipped in `--dry-run` (the lock file would be a side effect) — so a dry run, unlocked, must never mutate the shared prefixes either: `profdata.remove_staging(staging, dry_run)` takes `dry_run` as a required argument and only logs on a dry run. The Pass-4 stage3 clear was the one unguarded deletion; a concurrent dry run (the stage test suite included) removed stage3 under a real run's Pass 4b clang, which then compiled against `/usr/include`'s older LLVM headers (`3.3.0-B9`). The path's one home is `primitives/makepkg_pgo.py` (`pgo_lock_path`, `resolve_pgo_lock_path`, and `DEFAULT_PGO_STAGING_1`, which `constants.DEFAULT_STAGING_1` re-exports) because `makepkg_wrapper.run` probes the same lock to leave a running PGO build's `pgo_store` alone (`3.3.0-B8`, §Stale-profraw post-build check), and `primitives/` cannot import from `pipeline/`.
 
 **Post-install libLLVM resolution check.** `_verify_llvm_install` runs `ldd /usr/bin/clang` and `ldd /usr/bin/lld` and asserts that any `libLLVM*.so` lines resolve under `/usr/lib`. A `/var/tmp/sysforge-llvm-stage*` path appearing in `ldd` of an installed binary means Pass 4 packaged a bad RPATH or the install is incomplete — `/usr` looks consistent until `/var/tmp` gets cleaned, at which point the live toolchain silently breaks. The verify-stage check catches that before the sentinel clears.
 
-**Verify-failure diagnostic dump.** On a `_verify_llvm_install` failure, `ToolchainStage.run` calls `_dump_stage_dynsym_evidence(staging3, state_dir)` before the recovery prompt. The brick is a C++ stdlib symbol bound to libLLVM's `LLVM_<ver>` version node, so the actionable evidence is the **set difference** between what the *installed* consumers (`libclang-cpp` / `liblldCommon`) demand under `@LLVM_*` and what the *installed* `libLLVM` provides — read straight from the live `/usr` files that bricked. The dump lists those missing symbols (the brick cause) and, when the kept `stage3` libLLVM *does* export them, notes that the shipped libLLVM diverged from what Pass 4b linked against — pointing directly at an incomplete/incoherent stage3. It is written to `<state_dir>/llvm_abi_hazard.log`. (This replaced an earlier dump of `stage2`'s `libLLVM` defined exports, which on the profdata-reuse fast path captured a stale/empty prefix that never contained the brick symbols.) The installed libLLVM is selected to **match the soname the consumers actually link** (`_newest_so` keyed on the consumer's `lib*.so.<major>.<minor>` version), not a lexical-first glob — otherwise a compat package's older runtime (e.g. `llvm21-libs`'s `libLLVM.so.21.1` sitting beside `llvm-libs`'s `libLLVM.so.22.1`) is picked, its `@LLVM_21.1` exports satisfy nothing the `@LLVM_22.1` consumers demand, and the diff reports a false *"0 NOT provided"* all-clear that hides the brick. Staging removal is deferred until verify passes, so the `stage3` prefix survives the failure path for this contrast. The log path is surfaced in the WARN block alongside the suggested recovery command.
+**Verify-failure diagnostic dump.** On a `_verify_llvm_install` failure, `ToolchainStage.run` calls `dump_stage_dynsym_evidence(staging3, state_dir)` before the recovery prompt. The brick is a C++ stdlib symbol bound to libLLVM's `LLVM_<ver>` version node, so the actionable evidence is the **set difference** between what the *installed* consumers (`libclang-cpp` / `liblldCommon`) demand under `@LLVM_*` and what the *installed* `libLLVM` provides — read straight from the live `/usr` files that bricked. The dump lists those missing symbols (the brick cause) and, when the kept `stage3` libLLVM *does* export them, notes that the shipped libLLVM diverged from what Pass 4b linked against — pointing directly at an incomplete/incoherent stage3. It is written to `<state_dir>/llvm_abi_hazard.log`. (This replaced an earlier dump of `stage2`'s `libLLVM` defined exports, which on the profdata-reuse fast path captured a stale/empty prefix that never contained the brick symbols.) The installed libLLVM is selected to **match the soname the consumers actually link** (`_newest_so` keyed on the consumer's `lib*.so.<major>.<minor>` version), not a lexical-first glob — otherwise a compat package's older runtime (e.g. `llvm21-libs`'s `libLLVM.so.21.1` sitting beside `llvm-libs`'s `libLLVM.so.22.1`) is picked, its `@LLVM_21.1` exports satisfy nothing the `@LLVM_22.1` consumers demand, and the diff reports a false *"0 NOT provided"* all-clear that hides the brick. Staging removal is deferred until verify passes, so the `stage3` prefix survives the failure path for this contrast. The log path is surfaced in the WARN block alongside the suggested recovery command.
 
 **Profdata reuse:** before purging `pgo_store`, the stage checks for an existing `clang.profdata` + version sidecar. The sidecar's LLVM major version is compared against the `pkgver` in the pgo PKGBUILDs (not the installed version — the toolchain stage builds a *new* version). If compatible (same major), passes 1–3 are skipped entirely and only the optimized build (Pass 4) runs, using system clang as CC (which, after a prior successful run, is already PGO-optimized). Stage1/stage2 are not needed in this path, but **stage3 still is**: Pass 4 stages the freshly-built optimized libLLVM there and builds the non-pgo suite (4b) against it for ABI coherence — exactly as on the full path. `--rebuild-profdata` forces a full 4-pass build regardless, e.g. after upstream codegen changes within the same major version.
 
-**Pass-4 input-fingerprint reuse (opt-in).** Profdata reuse skips the *training* (passes 1–3) but still rebuilds every Pass-4 package. When a *late* Pass-4 package fails (e.g. `spirv-llvm-translator` in 4b), a rerun would needlessly re-optimise the identical `llvm`/`llvm-libs` (4a, the heaviest target) and other unchanged packages. The opt-in input-fingerprint cache (`primitives/build_fingerprint.py`, CLI `--reuse-built` > `toolchain.toml reuse_unchanged` > off) skips a Pass-4 package whose **inputs are unchanged and whose built artifact is still on disk**. The fingerprint folds everything that determines the output: the upstream PKGBUILD content hash, the source-tree git HEAD, the compiler `--version` line (`compiler_version_line` — **not** the full `clang_identity` path+size+mtime: Pass 4 runs with the staged stage-2 clang on a profgen run but `/usr/bin/clang` on a resume, so keying on the binary's path/bytes would guarantee a miss on the exact rerun-after-failure case reuse exists for; the actual trained codegen is already pinned by the profdata hash below, and a genuine version bump still invalidates — 2.1.0-B14), the injected/profile flags (`compiler_flags_extra`/`linker_flags_extra`/`cmake_llvm_dir`/`extra_flags`), a `config_digest` (`hash_obj` of the flag-relevant config — `profiles`/`rules` + `toolchain.toml`, the latter because `[llvm] targets` drives the `LLVM_TARGETS_TO_BUILD` patch the upstream-PKGBUILD hash can't see), the `clang.profdata` content hash (hashed once per run), and the installed versions of the **external** build-deps only. The toolchain build-set members (`llvm`, `llvm-libs`, `clang`, …) are **excluded** from that dep-version fold: Pass 4 satisfies them from the staging prefix (`--nodeps`), so their live-`/usr` version is not a build input, and the staged libLLVM they actually link is already pinned via `staged_dep_fps`. Folding it in would spuriously invalidate every Pass-4 fingerprint the instant the suite is self-installed — defeating cache reuse on a post-install sanity re-run, since e.g. `clang`'s `depends=('llvm-libs')` would flip the moment the freshly-built `llvm-libs` is installed (`_dep_versions_from_globals(exclude=…)`, 2.5.1-B2). Sub-passes are **Merkle-chained**: 4b/4c fold in 4a's current fingerprints (`staged_dep_fps`), so if a rebuilt libLLVM's fingerprint shifts, every consumer's does too and they rebuild — no stale libLLVM can ride through a cache hit. The cache is keyed by `(pass_id, pkgbase)` and stored at `<pgo_store>.parent/build-cache/build_cache.json` (`_reuse_cache_path`) — a **sibling** of `pgo_store`, deliberately outside it so a fresh 4-pass start's `empty_dir_contents(pgo_store)` purge cannot wipe a prior run's records before the resume consults them (each entry binds its own `profdata_sha`, so a surviving-but-stale entry from a different profdata fail-safe-misses rather than mis-hitting — 2.1.0-B14). It is **always written** (so a first, non-opted-in run populates it) but only **consulted** when opted in. The whole mechanism is fail-safe — a missing/changed artifact (size or nanosecond mtime), a fingerprint mismatch, a config edit, a schema bump, dry-run, or the GCC register-only path all force a normal rebuild; it never reuses a stale build. `--rebuild-profdata` (full 4-pass + `pgo_store` purge) also bypasses it. The logic lives in `_build_pass` (per-package skip/record, returning `{pkgbase: fingerprint}` for the chain) with the cache primitives in `build_fingerprint`; do not add a second cache or skip path.
+**Pass-4 input-fingerprint reuse (opt-in).** Profdata reuse skips the *training* (passes 1–3) but still rebuilds every Pass-4 package. When a *late* Pass-4 package fails (e.g. `spirv-llvm-translator` in 4b), a rerun would needlessly re-optimise the identical `llvm`/`llvm-libs` (4a, the heaviest target) and other unchanged packages. The opt-in input-fingerprint cache (`primitives/build_fingerprint.py`, CLI `--reuse-built` > `toolchain.toml reuse_unchanged` > off) skips a Pass-4 package whose **inputs are unchanged and whose built artifact is still on disk**. The fingerprint folds everything that determines the output: the upstream PKGBUILD content hash, the source-tree git HEAD, the compiler `--version` line (`compiler_version_line` — **not** the full `clang_identity` path+size+mtime: Pass 4 runs with the staged stage-2 clang on a profgen run but `/usr/bin/clang` on a resume, so keying on the binary's path/bytes would guarantee a miss on the exact rerun-after-failure case reuse exists for; the actual trained codegen is already pinned by the profdata hash below, and a genuine version bump still invalidates — 2.1.0-B14), the injected/profile flags (`compiler_flags_extra`/`linker_flags_extra`/`cmake_llvm_dir`/`extra_flags`), a `config_digest` (`hash_obj` of the flag-relevant config — `profiles`/`rules` + `toolchain.toml`, the latter because `[llvm] targets` drives the `LLVM_TARGETS_TO_BUILD` patch the upstream-PKGBUILD hash can't see), the `clang.profdata` content hash (hashed once per run), and the installed versions of the **external** build-deps only. The toolchain build-set members (`llvm`, `llvm-libs`, `clang`, …) are **excluded** from that dep-version fold: Pass 4 satisfies them from the staging prefix (`--nodeps`), so their live-`/usr` version is not a build input, and the staged libLLVM they actually link is already pinned via `staged_dep_fps`. Folding it in would spuriously invalidate every Pass-4 fingerprint the instant the suite is self-installed — defeating cache reuse on a post-install sanity re-run, since e.g. `clang`'s `depends=('llvm-libs')` would flip the moment the freshly-built `llvm-libs` is installed (`_dep_versions_from_globals(exclude=…)`, 2.5.1-B2). Sub-passes are **Merkle-chained**: 4b/4c fold in 4a's current fingerprints (`staged_dep_fps`), so if a rebuilt libLLVM's fingerprint shifts, every consumer's does too and they rebuild — no stale libLLVM can ride through a cache hit. The cache is keyed by `(pass_id, pkgbase)` and stored at `<pgo_store>.parent/build-cache/build_cache.json` (`reuse_cache_path`) — a **sibling** of `pgo_store`, deliberately outside it so a fresh 4-pass start's `empty_dir_contents(pgo_store)` purge cannot wipe a prior run's records before the resume consults them (each entry binds its own `profdata_sha`, so a surviving-but-stale entry from a different profdata fail-safe-misses rather than mis-hitting — 2.1.0-B14). It is **always written** (so a first, non-opted-in run populates it) but only **consulted** when opted in. The whole mechanism is fail-safe — a missing/changed artifact (size or nanosecond mtime), a fingerprint mismatch, a config edit, a schema bump, dry-run, or the GCC register-only path all force a normal rebuild; it never reuses a stale build. `--rebuild-profdata` (full 4-pass + `pgo_store` purge) also bypasses it. The logic lives in `build_pass` (per-package skip/record, returning `{pkgbase: fingerprint}` for the chain) with the cache primitives in `build_fingerprint`; do not add a second cache or skip path.
 
-**Sidecar write timing.** The version sidecar is written **right after Pass 3 completes** (after the final profraw merge produces `clang.profdata`, before Pass 4 starts) — not after a successful Pass 4 install. The sidecar's only invariant is "this profdata is for LLVM major N", which is determined entirely by what Pass 3 instrumented; Pass 4 success has no bearing on it. Writing it post-Pass-3 means a Pass-4 failure (e.g. a transient toolchain bug, an aborted run) still leaves recoverable profdata that the next invocation can reuse via `_check_existing_profdata` rather than being forced into a full 4-pass rebuild. The major itself is derived from the in-tree PGO PKGBUILD `pkgver` (`_pgo_target_major`), matching the value `_check_existing_profdata` will later compare against — symmetric with the reuse check, and correct across major bumps where `pacman -Q llvm` would report a stale value.
+**Sidecar write timing.** The version sidecar is written **right after Pass 3 completes** (after the final profraw merge produces `clang.profdata`, before Pass 4 starts) — not after a successful Pass 4 install. The sidecar's only invariant is "this profdata is for LLVM major N", which is determined entirely by what Pass 3 instrumented; Pass 4 success has no bearing on it. Writing it post-Pass-3 means a Pass-4 failure (e.g. a transient toolchain bug, an aborted run) still leaves recoverable profdata that the next invocation can reuse via `check_existing_profdata` rather than being forced into a full 4-pass rebuild. The major itself is derived from the in-tree PGO PKGBUILD `pkgver` (`pgo_target_major`), matching the value `check_existing_profdata` will later compare against — symmetric with the reuse check, and correct across major bumps where `pacman -Q llvm` would report a stale value.
 
-**Confirmation gating (PGO).** Unlike the rest of sysforge (which is automation-focused), the LLVM PGO sub-flow is fragile enough that wrong profdata silently mis-optimises the resulting compiler. Four decision points in `_build_llvm_pgo` therefore prompt the user before destructive or long-running work, all sharing a single `_pgo_confirm` helper:
+**Confirmation gating (PGO).** Unlike the rest of sysforge (which is automation-focused), the LLVM PGO sub-flow is fragile enough that wrong profdata silently mis-optimises the resulting compiler. Four decision points in `build_llvm_pgo_inner` therefore prompt the user before destructive or long-running work, all sharing a single `pgo_confirm` helper:
 
 1. **Reuse vs rebuild** — when compatible profdata is found, prompt `[Y/n]` to reuse; declining triggers a full 4-pass rebuild (and continues into prompts 2–3).
 2. **Purge `staging/` and `pgo_store/`** — prompt `[y/N]` before clearing; declining aborts PGO. The `staging1/2/3` dirs (under world-writable `/var/tmp`) are `rmtree`'d, but `pgo_store` is cleared with `fs_provision.empty_dir_contents` — it lives under the root-owned FHS parent `/var/cache/sysforge`, so `rmtree`'s final `rmdir` would need write on that parent and fail with `EACCES`; emptying the contents (all unprivileged-written) keeps the node and needs no parent write. After the purge, `pgo_store` is (re)provisioned via `fs_provision.ensure_writable_dir` (`root:sysforge 2775` — see *Directory provisioning* above). A user-writable / env-override `pgo_store` takes the direct path and never touches sudo.
@@ -667,7 +667,7 @@ The packages and kernel stages read these values and inject them into the build
 
     **Liveness guard.** Presence of the sentinel cannot distinguish "a previous run died mid-mutation" from "a run is alive right now" — and the recovery prompts above are unanswerable, and destructive, against a live run: clearing a live owner's sentinel lets the second run's `mark_started` overwrite the record wholesale, after which whichever run finishes first `clear()`s the other's (silently — `clear()` suppresses `FileNotFoundError`), leaving two concurrent install-bearing runs with no interruption record for either. So `sentinel_scope` also holds an exclusive `flock` on `<state_dir>/stage_in_progress.lock` for the stage's lifetime, via the shared `primitives/build_lock.py` primitive (its `noun` parameter carries the "install stage" wording; the build stages pass `noun="build"` and keep their existing messages). Liveness becomes "is the lock takeable?", which the kernel answers correctly even after `SIGKILL` or power loss — a PID recorded in the sentinel could not, since PID recycling would report a dead owner as alive forever, unrecoverable given the no-override decision below. Two layers use it: `check_and_recover_stale_sentinel` probes the lock at CLI entry and returns False **without prompting** when an owner is alive (naming the holder PID and the recorded stage), making the clear prompt unreachable; and `sentinel_scope` acquires it for real — before `mark_started`, so a live owner's record is never overwritten — catching the probe/acquire race plus any mutating verb reached outside `cli._gate_sentinel_check`'s allowlist. **A stale record is never overwritten** (`3.5.0-B46`): `uninstall`, `revert-to-stock`, the `state` verbs and the artifact verbs set `requires_sentinel = True` but are outside that allowlist, so their scope's `mark_started` replaced an interrupted toolchain install's record and the success path cleared it, and the next `update` ran with no recovery prompt. `sentinel_scope` now calls `check_and_recover_stale_sentinel` itself, before taking the lock, whenever a record exists, and raises `RuntimeError` with the record kept when recovery is declined or fails. Contention there raises `RuntimeError`, which `verbs/runner.py` already converts to exit 1. **No override:** a live owner is unambiguous, so a prompt would only invite the mistake the guard prevents; escaping requires killing the owning process. The posture splits by error type — contention is strict (hard refusal), while `OSError`/`PermissionError` stay lenient (warn + proceed, matching the sentinel write itself) so a read-only state dir cannot lock the user out of every mutating verb. Per-state-dir scoping is automatic since the lock lives in the state dir, so an isolated `SYSFORGE_STATE_DIR` (test fixtures, VM) never contends with a live run. Scopes are sequential, never nested — the `run` verbs set `requires_sentinel = False` precisely so a verb-level scope cannot wrap a stage's own.
 
-2. **Post-install verification (Gate 3)** — after the `pacman -U` of the LLVM run, `_verify_llvm_install()` checks: (a) `pacman -Q` versions across `_LLVM_VERSION_MATCH_SET` (which *is* `LLVM_LOCKSTEP_SUITE` from `toolchain_preflight` — `llvm`/`llvm-libs`/`clang`/`lld`/`compiler-rt`/`polly`/`openmp`) agree, via `toolchain_safety.detect_suite_skew` (the canonical interrupted-install symptom — a mismatched `llvm-libs` is the exact failure mode that produces a broken GUI). The suite spans several independent pkgbases, so lockstep is on **pkgver** (the upstream release keying the `LLVM_<ver>` ABI namespace); a pkgrel-only divergence across pkgbases (e.g. an `llvm` -2 rebuild beside `clang` -1) is a legitimate state and is *not* a skew — only the shared-pkgbase pair `llvm`/`llvm-libs` is held to full `pkgver-pkgrel` lockstep. (b) `clang --version` and `ld.lld --version` invoke cleanly without missing-symbol errors (probing `ld.lld`, the GNU-compatible flavor `-fuse-ld=lld` resolves to — bare `lld` is the generic multiplexer driver and always exits 1 without a flavor), and clang compiles and links a trivial program with `-fuse-ld=lld`, since `--version` returns before libclang-cpp's symbols are bound (`3.5.0-B58`, as Gate 1's smoke test), (c) `ldd` of installed clang/lld resolves libLLVM under `/usr/lib` (`_check_llvm_link_resolution`), (d) when `[llvm] targets` is configured, `llvm-config --targets-built` is a superset. On failure the stage **auto-rolls-back** to the pre-install snapshot rather than prompting (the kernel-parity overhaul replaced the old interactive `_prompt_llvm_recovery`): a successful restore clears the sentinel and raises "prior toolchain was restored"; a failed/incomplete restore keeps the sentinel with the snapshot recovery command. This verification is comprehensive and fatal, but only runs inside `run toolchain`; if a toolchain run is interrupted before it (or a later partial pacman transaction reintroduces a skew), the broken state can still reach an everyday `sysforge update`. That gap is closed by the `cc:<name>` compiler-health probe in `toolchain_preflight` (see §`toolchain_preflight.py`), which re-detects the suite-wide pkgver skew / non-runnable clang before any package builds — deliberately a lightweight independent check sharing the `LLVM_LOCKSTEP_SUITE` constant rather than importing this pipeline-layer verifier into the primitives layer.
+2. **Post-install verification (Gate 3)** — after the `pacman -U` of the LLVM run, `_verify_llvm_install()` checks: (a) `pacman -Q` versions across `_LLVM_VERSION_MATCH_SET` (which *is* `LLVM_LOCKSTEP_SUITE` from `toolchain_preflight` — `llvm`/`llvm-libs`/`clang`/`lld`/`compiler-rt`/`polly`/`openmp`) agree, via `toolchain_safety.detect_suite_skew` (the canonical interrupted-install symptom — a mismatched `llvm-libs` is the exact failure mode that produces a broken GUI). The suite spans several independent pkgbases, so lockstep is on **pkgver** (the upstream release keying the `LLVM_<ver>` ABI namespace); a pkgrel-only divergence across pkgbases (e.g. an `llvm` -2 rebuild beside `clang` -1) is a legitimate state and is *not* a skew — only the shared-pkgbase pair `llvm`/`llvm-libs` is held to full `pkgver-pkgrel` lockstep. (b) `clang --version` and `ld.lld --version` invoke cleanly without missing-symbol errors (probing `ld.lld`, the GNU-compatible flavor `-fuse-ld=lld` resolves to — bare `lld` is the generic multiplexer driver and always exits 1 without a flavor), and clang compiles and links a trivial program with `-fuse-ld=lld`, since `--version` returns before libclang-cpp's symbols are bound (`3.5.0-B58`, as Gate 1's smoke test), (c) `ldd` of installed clang/lld resolves libLLVM under `/usr/lib` (`check_llvm_link_resolution`), (d) when `[llvm] targets` is configured, `llvm-config --targets-built` is a superset. On failure the stage **auto-rolls-back** to the pre-install snapshot rather than prompting (the kernel-parity overhaul replaced the old interactive `_prompt_llvm_recovery`): a successful restore clears the sentinel and raises "prior toolchain was restored"; a failed/incomplete restore keeps the sentinel with the snapshot recovery command. This verification is comprehensive and fatal, but only runs inside `run toolchain`; if a toolchain run is interrupted before it (or a later partial pacman transaction reintroduces a skew), the broken state can still reach an everyday `sysforge update`. That gap is closed by the `cc:<name>` compiler-health probe in `toolchain_preflight` (see §`toolchain_preflight.py`), which re-detects the suite-wide pkgver skew / non-runnable clang before any package builds — deliberately a lightweight independent check sharing the `LLVM_LOCKSTEP_SUITE` constant rather than importing this pipeline-layer verifier into the primitives layer.
 
 3. **Clean-exit SIGINT scope** (`primitives/interrupt.py`) — every `sentinel_scope` body runs inside an `InterruptScope`. The first Ctrl-C flips a flag without raising and prints a one-line notice (a raw `os.write` to stderr, since a signal handler must not take the logging locks); children in the terminal's foreground process group, such as makepkg and pacman, still get it themselves. Code inside the scope stops at a safe boundary by calling the module-level `interrupt.checkpoint()`, which raises `CleanExitRequested` (translated by `sentinel_scope` into a `RuntimeError` with the retry and recovery hints, sentinel intact). The checkpoints sit only where stopping leaves the system consistent: before each package in `build_core.build_and_install`'s loop (the `build`/`update` verb scopes) and in the packages stage loop. The toolchain and kernel install windows (install, then Gate 3 or `mkinitcpio` and the bootloader) have no safe midpoint, so they have no checkpoint: the body finishes, the sentinel is cleared, and `InterruptScope.redeliver` sends the SIGINT again under the previous handler, so the run stops as a Ctrl-C outside any scope would. Before `3.5.0-B44` nothing called `check()`, so the first Ctrl-C was swallowed and never acted on. A second Ctrl-C falls through to default `SIGINT` handling (immediate termination) — the operator explicitly chose the unsafe path. `CleanExitRequested` subclasses `BaseException` so it propagates through `except Exception:` blocks without being silently swallowed.
 
diff --git a/docs/design/08-cli-verb-framework.md b/docs/design/08-cli-verb-framework.md
index 32004ab9..f8cae6a3 100644
--- a/docs/design/08-cli-verb-framework.md
+++ b/docs/design/08-cli-verb-framework.md
@@ -77,7 +77,7 @@ spelling per meaning, across every verb:
 
 **Sentinel handling.** Verbs whose `execute` mutates the live system set `requires_sentinel = True`. The runner wraps `execute + post_validate` in `sentinel_scope(state_dir, verb.name, recovery=…, retry_cmd=…, **metadata)` (`recovery` is a `stage_sentinel.Recovery` from `verb.sentinel_recovery`, stored as a kind plus arguments, `3.5.0-B43`) from `primitives/stage_sentinel.py`. On entry, the sentinel writes `stage_in_progress.toml`; on normal completion (both phases pass), it clears. On `RuntimeError` or `CleanExitRequested`, the sentinel is left in place so the next sysforge invocation blocks at the CLI-entry recovery prompt. `sentinel_scope` also installs an `InterruptScope`, so verbs participate in the same first-Ctrl-C-defers-to-safe-boundary behaviour as the toolchain stage: `build` and `update` stop before their next package (`interrupt.checkpoint()` in `build_core`), and a verb with no checkpoint stops when its `execute` + `post_validate` complete (`3.5.0-B44`). It additionally holds the `stage_in_progress.lock` liveness lock for the scope: if another run already holds it, entering the scope raises `RuntimeError` **before** `mark_started`, which the runner's existing handler converts to exit 1 without clobbering the live run's sentinel (§Pipeline layer, *Liveness guard*). The toolchain pipeline stage uses the same primitive — there is one implementation, shared.
 
-**Read-only verbs** (`env`, `help`, `resolve`, `log`, `state list`, `state orphans` without `--delete`, `state failed` without `--clear`/`--clear-all`, `state profiles` without `--delete`, `state boot-entries`, `bench toolchain`, `packages list`, `doctor` without `--apply`) implement `execute` (the work is printing) and return `ExecResult()`; `post_validate` defaults to no-op and `requires_sentinel = False`. They use the same dispatch path as mutating verbs — no second code path.
+**Read-only verbs** (`env`, `help`, `resolve`, `log`, `config check`, `state list`, `state orphans` without `--delete`, `state failed` without `--clear`/`--clear-all`, `state profiles` without `--delete`, `state boot-entries`, `bench toolchain`, `packages list`, `doctor` without `--apply`) implement `execute` (the work is printing) and return `ExecResult()`; `post_validate` defaults to no-op and `requires_sentinel = False`. They use the same dispatch path as mutating verbs — no second code path.
 
 **`state boot-entries`** (`3.3.0-F5`, `StateBootEntriesVerb`, read-only, `requires_sentinel = False`) lists every `vmlinuz-*` in `/boot` with the loader entry that boots it. The table goes through the pager like `state profiles` (`--no-pager` disables it): columns KERNEL / ENTRY / OWNER (`you`, `sysforge` or `none`) / TEMPLATE, plus `(missing)` rows for managed entries whose kernel is gone. Under `bootloader = grub`/`none` it prints a one-line note instead; with `boot_entries = "off"` it notes that and still lists. Rows come from `boot_entries.rows_for`.
 
@@ -101,6 +101,9 @@ spelling per meaning, across every verb:
 | `log` | null | resolve the pipeline, per-pkg or `--verb` log path; page through `$PAGER` | null | no |
 | `packages {list,add,remove}` | load packages.toml + validate override fields | rewrite TOML | null | no |
 | `state {list,repair,orphans}` | load state dir | inspect / repair / prune | null | `repair` only |
+| `config check` | null | inspect the live config files (`config_schema.inspect`) | null | no |
+| `config clean` | null | rewrite retired settings (`--unknown`: drop unknown ones); diff, then consent | null | no |
+| `config reset` | null | restore keys or a whole file to the shipped default; diff, then consent | null | no |
 | `config merge` | null | scan config dir for `.sfnew`/`.pacnew`; pacdiff-style view/merge/remove loop | null | no |
 | `revert-to-stock` | resolve state dir + `plan_revert` over `BuildState` (pure, no mutation) | prompt/`--yes`/`--dry-run` gate, then per-target reinstall / atomic replace / derename-then-reinstall via `pacman` | (state written inline) | yes |
 | `bench toolchain` | null | resolve preconditions → workload → unprivileged stock fetch + extract → interleaved timing → report → `bench.toml` | null | no |
@@ -330,7 +333,7 @@ The whole feature is LLVM-only — it instruments with clang and merges with `ll
 - **`prepare_deps(pkgbuild_paths, config, *, building_names, …)`** — pre-installs missing repo *build deps* in one `pacman -S` transaction (`batch_install_makedeps`) and builds AUR/local deps in topo order (`resolve_aur_deps_batch` + `build_resolved_deps`), excluding the packages about to be built themselves. The repo arm collects `depends` + `makedepends` + `checkdepends` (`pacman.collect_builddeps`), **not just makedepends**: the per-package makepkg call runs with `-s` stripped, and makepkg checks runtime `depends` before building too, so a missing repo runtime dep would abort the build with exit 8 ("Could not resolve all dependencies"). It **filters the missing set to sync-repo packages first** (`aur.repo_packages`, the same classifier the AUR resolver uses) — an AUR-only dep mixed into the `pacman -S` transaction makes pacman abort with "target not found" and install *none* of the repo deps either, so AUR deps are excluded here and left to the AUR arm (which resolves `depends + makedepends`). Both arms are best-effort — a failure warns and lets the build proceed, surfacing a genuinely-missing dep as a per-package build failure with a diagnosis rather than aborting the whole batch up front.
 - **`install_built(built_pkg_files, *, always_install=frozenset(), interactive=False, allow_break_deps=frozenset(), state_dir=None) -> (installed_files, not_installed)`** — dedupe, re-fetch the installed set (makedep/AUR pre-install may have expanded it), `filter_pkgs_to_installed` for split-pkgbase safety, then one `pacman -U`. `not_installed` maps each artifact pacman did not install to a one-line reason (empty on success). The transaction stays single so pacman resolves the batch's inter-dependencies together, which makes it all-or-nothing; when pacman refuses on **file conflicts**, `batch_install_pkgs(conflicts_out=…)` reports the culprit pkgnames (`pacman.file_conflict_culprits`) and those artifacts are set aside with pacman's per-file detail as their reason, then the remainder is retried as one transaction (3.2.0-B33). A refusal naming no culprit (deps, signatures, DB lock) or naming only packages outside the batch fails everything still pending with `INSTALL_REFUSED_REASON` — a retry is never the identical set. `build_and_install` folds the per-file reasons into `BuildOutcome.not_installed` (`not_installed_by_pkgbase`, also used by `update`'s `--install-only` scan) and snapshots `build_state` for its targets before the loop, so a refused artifact's entry — written by `makepkg_wrapper` at build time — is put back via `BuildState.revert_record` (3.2.0-B34): the pre-build entry returns, keeping only the new `build_seconds` ring and any pre-3.5.0-B8 `reviewed_commit` (the build and review did happen; the current review baseline lives in `[reviewed]`, which a revert never touches), or the entry is dropped when there was none. Without the revert `build_state` claimed a version and flags that never reached the system. The revert passes the refused artifact's filename, so `BuildState` keeps the undone entry in its `[reverted]` table; when a later install of that same file succeeds, `install_built` (given `state_dir`) calls `_restore_reverted_state`, which puts it back (3.3.0-B2). Without that, a rerun that reuses the artifact ("already built" skips `makepkg_wrapper`, so nothing records it) installs the new build while `build_state` keeps describing the old one. With `state_dir` (both `build_and_install` call sites and `update`'s `--install-only` scan pass it), each dropped sub-package that is not installed also loses the `build_state` record `makepkg_wrapper` wrote for it at build time (3.2.0-B31): the wrapper records every PKGBUILD `pkgname` because it runs before the install decision, and this filter is the one place that knows which members reach the system — without the cleanup a replaced split member reappears as a `source_built` phantom after every rebuild of its pkgbase until the next superset sync prunes it. Best-effort; a state IO error never fails the install. The keep-set is the currently-installed pkgnames **union `always_install`** — the pkgnames the caller explicitly asked to build. `build_and_install` passes the build targets' pkgnames, so a fresh `sysforge build <new-pkg>` installs the package the user asked for instead of dropping it for not being installed yet; for `update` the union is a no-op (its targets are already installed). A conflict-mode `-sysforge` rebuild (e.g. `mesa --pgo=use`) emits artifacts renamed off every stock pkgname (`mesa-sysforge`), so `filter_pkgs_to_installed` keeps them via their `replaces` rather than their absent pkgname — otherwise the optimized build would complete and then be silently dropped at install. Reused by `update`'s `--install-only` artifact-scan branch (which keeps the default empty set). `interactive` threads down to `pacman.batch_install_pkgs(..., interactive=…)`: when set it drops `--noconfirm` and inherits pacman's TTY streams so a package-conflict question (`X and Y are in conflict. Remove Y? [y/N]`) is put to the operator instead of auto-answered `N` and aborting the transaction. `build_and_install` passes its own `interactive` from both the just-in-time and final-install call sites; `update`'s non-interactive call keeps the default (`--noconfirm`). The non-interactive path still has to install the conflict-mode rename without an operator at the prompt: pacman only auto-processes `replaces` on a sync upgrade, so on a local `-U` the renamed drop-in (`mesa-sysforge` declaring `replaces = mesa`) still raises the conflict prompt, which `--noconfirm` declines (default `N`) and aborts. `batch_install_pkgs` therefore adds `--ask=4` (`ALPM_QUESTION_CONFLICT_PKG`) **only when** a built package's `replaces` names a currently-installed package — auto-confirming exactly the intended drop-in removal; absent a real replaces-installed relationship the prompt keeps its safe default so an unexpected conflict still aborts.
 - **`sync_source`** is the single deliberate caller difference: `update` passes `False` (Phase 2 already synced sources through the scheduler), `build` passes `not --no-update` to keep its inline per-package source sync (which itself routes through `source_sync.get_scheduler()` inside `makepkg_wrapper.run`). `_find_existing_artifacts` and `_record_build_failure` live here too (moved from `update.py`) since both the engine and `update`'s install-only scan use them — though `_find_existing_artifacts` is now a thin delegate to `makepkg_artifacts.find_artifacts`, which `3.1.0-F9` lifted into `primitives/` so the build sandbox could share the matcher (§Primitives Layer).
-- **`make_build_options(stage, options, **overrides) -> BuildOptions`** — the shared factory the three install-bearing pipeline stages (`kernel`/`toolchain`/`packages`) use instead of hand-assembling a `BuildOptions`. It maps the fields common to every stage's `RunOptions` (`no_pkg_log` → `pkg_log`, plus `persist_log`/`state_dir`/`abi_check`, the last via `getattr` so a run-options object without it degrades to `False`), layers in the stage's constant defaults from `_STAGE_BUILD_DEFAULTS` (`kernel` → `owner_stage="kernel"` + `no_install=True`; `toolchain` → `pgo_managed=True`; `packages` → none), then applies the caller's per-call `overrides` (which win over both). Fields that differ per stage or per package — `profile_conf`, `log_dir`, `update`, `cc`/`cxx`/`ld_override`, `source`, `toolchain_variant`, `extra_flags`, … — are passed explicitly as overrides; anything a stage omits keeps its `BuildOptions` default (so `toolchain` not passing `log_dir` keeps it `None`). This is where a stage-wide default like the kernel build/install split lives, rather than being repeated at each call site.
+- **`make_build_options(stage, options, **overrides) -> BuildOptions`** — the shared factory the three install-bearing pipeline stages (`kernel`/`toolchain`/`packages`) use instead of hand-assembling a `BuildOptions`. It maps the fields common to every stage's `RunOptions` (`no_pkg_log` → `pkg_log`, plus `persist_log`/`state_dir`/`abi_check`, all read directly off the stage's `RunOptions`), layers in the stage's constant defaults from `_STAGE_BUILD_DEFAULTS` (`kernel` → `owner_stage="kernel"` + `no_install=True`; `toolchain` → `pgo_managed=True`; `packages` → none), then applies the caller's per-call `overrides` (which win over both). Fields that differ per stage or per package — `profile_conf`, `log_dir`, `update`, `cc`/`cxx`/`ld_override`, `source`, `toolchain_variant`, `extra_flags`, … — are passed explicitly as overrides; anything a stage omits keeps its `BuildOptions` default (so `toolchain` not passing `log_dir` keeps it `None`). This is where a stage-wide default like the kernel build/install split lives, rather than being repeated at each call site.
 
 ---
 
diff --git a/docs/design/09-primitives-layer.md b/docs/design/09-primitives-layer.md
index 7d7d72f8..a9c783a0 100644
--- a/docs/design/09-primitives-layer.md
+++ b/docs/design/09-primitives-layer.md
@@ -59,7 +59,7 @@ Bottom-anchored status line for batch operations (`[3/10] building · htop`). Du
 
 **How primitives reach it.** They don't import it. `ui/progress.py` registers itself with `primitives/progress_hooks.py` at import, and the leaf layer calls `progress_hooks.hooks().<name>()` — see that module below.
 
-Integration sites: `sysforge/verbs/runner.py::run_verb` (universal `<verb>: starting…` startup phase + clear), `sysforge/pipeline/runner.py` (`phase(stage.name)` per stage in `run_stage_standalone` / `run_pipeline`), `sysforge/pipeline/stages/packages.py` (build loop), `sysforge/primitives/aur_resolve.py::build_resolved_deps` (AUR deps), `sysforge/update.py` (phase statuses for init/assembly/drift/preflight + trackers for source sync and the threaded version check), `sysforge/build_core.py` (phase statuses for source pre-sync, dep prep, and install + the build-loop tracker), `sysforge/fetch.py` (fetch loop). Prompts need nothing from their call sites: every `prompt.py` helper yields the terminal itself.
+Integration sites: `sysforge/verbs/runner.py::run_verb` (universal `<verb>: starting…` startup phase + clear), `sysforge/pipeline/runner.py` (`phase(stage.name)` per stage in `run_stage_standalone` / `run_pipeline`), `sysforge/pipeline/stages/packages.py` (build loop), `sysforge/build/aur_deps.py::build_resolved_deps` (AUR deps), `sysforge/update.py` (phase statuses for init/assembly/drift/preflight + trackers for source sync and the threaded version check), `sysforge/build_core.py` (phase statuses for source pre-sync, dep prep, and install + the build-loop tracker), `sysforge/fetch.py` (fetch loop). Prompts need nothing from their call sites: every `prompt.py` helper yields the terminal itself.
 
 ### `prompt.py`
 
@@ -68,13 +68,13 @@ Single shared interactive-prompt helper. Every stage that needs user input goes
 Key contract:
 
 - Every helper reads its input inside `progress_hooks.hooks().yield_terminal("prompt")`, so the bottom-anchored bar is blanked in place for the prompt and repainted as soon as the answer is in. This is the single home for that guarantee — call sites no longer manage the bar by hand before prompting (the forgotten clear at the toolchain confirm/preflight/PGO prompts was exactly this footgun). Since every interactive input comes through here, it is also what pauses an open tracker's clock while the user decides (`3.3.0-F2`). (A prompt yield keeps the scroll region — a full region reset's cursor-restore is unreliable on some terminals and rendered prompts off-view.)
-- `prompt_choice` re-prompts with a visible warning on unrecognized input (so typos / jibberish never silently fall through to the default), unless the call site passes `retry_on_invalid=False` — used for destructive / mutate-confirm prompts where any non-confirming input must abort (partition.py's literal-`yes` confirmation; the `[y/N]` confirms in `state orphans --delete`, `doctor --apply` rebuild, and `auto_repair`'s checksum-mismatch `updpkgsums` retry). These three previously used a bare `input()` with a hand-rolled `EOFError` guard; routing them through `prompt_choice` also picks up the captured-stdin `OSError`-as-EOF handling for free.
-- `eof_default` is a separate kwarg from `default`. Most sites pass neither (EOF returns `default`). `toolchain.py`'s GCC-build override and `_confirm_or_abort` deliberately set `eof_default="y"` to preserve their long-standing "EOF means proceed unattended" semantic.
+- `prompt_choice` re-prompts with a visible warning on unrecognized input (so typos / jibberish never silently fall through to the default), unless the call site passes `retry_on_invalid=False` — used for destructive / mutate-confirm prompts where any non-confirming input must abort (`pipeline/stages/_partition_plan.py`'s literal-`yes` confirmation; the `[y/N]` confirms in `state orphans --delete`, `doctor --apply` rebuild, and `auto_repair`'s checksum-mismatch `updpkgsums` retry). These three previously used a bare `input()` with a hand-rolled `EOFError` guard; routing them through `prompt_choice` also picks up the captured-stdin `OSError`-as-EOF handling for free.
+- `eof_default` is a separate kwarg from `default`. Most sites pass neither (EOF returns `default`). The toolchain stage's build confirmation (`toolchain/pkgbuilds.py`) is the one site that sets `eof_default="y"`, preserving its long-standing "EOF means proceed unattended" semantic; the soname-consumer prompts in `toolchain/gates.py` set `eof_default="n"`, since they approve extra rebuilds.
 - Both helpers catch `EOFError` *and* `OSError`, since pytest's captured stdin and other unreadable-stdin scenarios raise the latter.
 - `prompt_key` reads one character in cbreak mode (`termios`/`tty`, restored in a `finally`) and echoes it plus a newline so the transcript still shows the answer — no Enter required. It degrades to line-based `input()` (first character of the stripped line) when stdin is not a TTY, `termios` is unavailable, or raw-mode setup fails, so tests and pipes keep working. Ctrl-C raises `KeyboardInterrupt` (cbreak delivers it as `\x03`); Ctrl-D/EOF/unreadable stdin raise `EOFError`; a bare Enter returns `""` ("no answer", distinct from EOF) so callers can re-prompt. Validation and re-prompt loops stay in the caller, matching `prompt_choice`'s contract. Used by the PKGBUILD review gate.
 - Optional `tag`/`level` kwargs reuse `log.prompt_prefix(level, tag)` so prompts keep the standard `[SYSFORGE][LEVEL][TAG] ` format.
 
-Call sites: `pipeline/stages/reconfigure.py` (11), `pipeline/stages/packages.py` (`_prompt_failed_packages`), `pipeline/stages/toolchain/` (3), `pipeline/stages/partition.py` (1), `setup_cmd.py` (1), `build/makepkg_wrapper.py` (4). No stage may call `input()` directly.
+Call sites span the stages (`reconfigure` most of all), the verbs and the build primitives (the review gate, the recovery menu, `auto_repair`). No stage may call `input()` directly.
 
 ### `progress_hooks.py`
 
@@ -88,6 +88,10 @@ Host detection and the derivations built on it: `detect_host_arch()` (uname), `p
 
 Pure constants module — the canonical directory of every config file sysforge reads. `CONFIG_BASE` is derived from `$SYSFORGE_CONFIG_DIR` (default `/`, so system config resolves under `<base>/etc/sysforge/`, including `BOOTSTRAP_PATH`). User-side roots follow the XDG Base Directory Specification via the `_xdg_base(env, default)` helper: `USER_CONFIG_DIR` (`$XDG_CONFIG_HOME/sysforge`), `USER_CACHE_DIR` (`$XDG_CACHE_HOME/sysforge`), `USER_STATE_DIR` (`$XDG_STATE_HOME/sysforge`). The resolved path lists (`CONFIG_PATHS`, `CONFLICT_GROUP_PATHS`, `CONSUMES_INFERENCE_PATHS`) layer the user file (`$XDG_CONFIG_HOME/sysforge/…`) over the system file in `extends_system` order. Helpers: `resolve_packages_path(config)` returns the `packages.toml` path the rest of the codebase should use (honouring `--packages` overrides), and **`resolve_state_dir(cli_override)`** is the single home for state-dir resolution — `--state-dir` > `SYSFORGE_STATE_DIR` > `/var/lib/sysforge` > the XDG state dir when the default is neither writable nor provisionable — returning `(Path, source)` where `source` is one of `--state-dir`, `SYSFORGE_STATE_DIR`, `default`, `xdg-fallback`. Read-only callers pass `provision=False` (`state profiles`, `3.4.0-B20`): an unwritable default is then never provisioned, since that path can prompt for sudo, and the XDG dir is read instead when it exists, because that is where this user's earlier runs wrote when provisioning was refused. It lived in `pipeline/state.py` until `3.2.0-F1`, which meant five primitives (`makepkg_wrapper`, `state_probe`, `source_sync`, `llvm_state`, `init_notice`) reached *upward* into the pipeline layer at function level for a path computation; `pipeline.state` re-exports the name so existing imports and test patch points are unaffected. Apart from that resolver's writability probe and its `fs_provision` fallback, the module does no I/O — just path strings.
 
+### `env_vars.py`
+
+The registry of every environment variable sysforge reads (`3.5.0-B128`): `ENV_VARS`, one `EnvVar(name, audience, text)` each, `audience` `user` (a setting) or `diagnostic` (a switch for bug reports). Pure data; the readers keep their own `os.environ.get` calls. `tools/gen_options.py` renders the man page's ENVIRONMENT section from it, and `tests/test_env_vars.py` fails on a `SYSFORGE_*` name in the code that it does not list (journal fields live in `journal.JOURNAL_FIELDS`), and on an entry nothing reads.
+
 ### `config.py`
 
 TOML config loading and path resolution. Public API:
@@ -139,7 +143,7 @@ Init-file parsing is regex-based (`export KEY=value`, `KEY=value; export KEY`, p
 ### `pacman.py`
 
 All pacman and batch-install shared operations. Public API:
-- `get_pkgdest()` / `get_builddir()` / `get_srcdest()` / `get_logdest()` — resolve the corresponding makepkg path variable via the shared `_resolve_makepkg_path(key)` helper, which mirrors makepkg's own precedence: **environment first** (`os.environ`), then the layered `parse_system_makepkg_conf()` (`/etc/makepkg.conf` → user conf), quotes stripped and `~`/`$VARS` expanded, else `None`. These are the single home for "where did makepkg put / read this?" — any new code that needs to *locate* a built artifact, build tree, downloaded source, or build log must call them rather than assuming `~/builds` / the PKGBUILD dir / a hardcoded default (a recurring bug class). `BUILDDIR` resolution in particular feeds `makepkg_env._effective_build_dir` (side-car log diagnosis) and `kernel._resolve_built_config` (resolved `.config` discovery), both of which must honour a `BUILDDIR` set only in `/etc/makepkg.conf`. `PKGDEST` resolution feeds `makepkg_wrapper._find_artifacts` (the union-of-`PKGDEST`-and-PKGBUILD-dir locator behind `install_built_packages` + the post-build ABI report) and `build_core`'s artifact snapshot — so a non-default `PKGDEST` doesn't strand the install/ABI scan looking in the PKGBUILD dir. `install_built_packages` wraps that locator in `_artifacts_for_pkgbuild`, which scopes the union in two tiers. **Preferred:** a build-time manifest (`_BUILT_MANIFEST_NAME`, `.sysforge-built.list`) — the exact package basenames `makepkg --packagelist` emitted, recorded by `_capture_built_manifest` on build success *while the patched `PKGBUILD.sysforge` is still present* — is matched exactly. Recorded for any **name-affecting** build: one that applies an extracted profile **or** a rename (kernel local-rename / `-sysforge` suffix); a rename is exactly the case pkgname scoping can't recover (2.5.1-B3 — a rename-only kernel previously recorded no manifest because capture was gated on the extracted profile alone). This is the only reliable scope for a **renamed** build (e.g. a `-sysforge` kernel): by install time the patched PKGBUILD is cleaned up, leaving only the upstream PKGBUILD whose pkgname (`linux`) prefix-matches unrelated (`linux-custom`, `linux-steam-integration`) and stale-version (`linux-sysforge-<oldver>`) artifacts — the pre-B9 bug that swept those into `pacman -U` and could downgrade the running kernel. **Fallback** (no manifest, or none of its entries are present): scope by the PKGBUILD's own pkgnames (filename-matched via `_parse_built_pkg_filename`, which anchors on the exact `<pkgname>-` prefix **and** requires a valid `[epoch:]pkgver-pkgrel-arch` tail — three hyphen-delimited fields, since `PKGBUILD(5)` forbids hyphens in pkgver/pkgrel/arch — so pkgname `linux` no longer matches `linux-custom` et al., 2.5.1-B3). Within that set it keeps only the artifacts at the PKGBUILD's own `epoch:pkgver-pkgrel` (`_pkgbuild_version`), so an older build of the same pkgnames still in PKGDEST is not reported or installed as this build's output (`3.5.0-B21`: every build without a rename or extracted profile records no manifest, sandboxed mesa 26.2.5 included, and its post-build ABI report covered the 26.2.4 artifacts too); when that version matches none of them, as for a VCS PKGBUILD whose `pkgver()` rewrote a copy rather than this file, every scoped version is kept. This scoped set is returned **even when empty** — it never degrades to the full PKGDEST union: when the PKGBUILD parses cleanly and names its pkgnames but none match (the renamed-away case, absent a manifest), the caller fails loudly (`nothing to install`) rather than hand a shared PKGDEST of hundreds of unrelated packages to `pacman -U`. Only a PKGBUILD that yields *no* parseable pkgnames still degrades to the union (best-effort locate-everything), a case that fires solely with a local, unset `PKGDEST`. The manifest is deleted after a successful install so a later build in the same dir can't read a stale list.
+- `get_pkgdest()` / `get_builddir()` / `get_srcdest()` / `get_logdest()` — resolve the corresponding makepkg path variable via the shared `_resolve_makepkg_path(key)` helper, which mirrors makepkg's own precedence: **environment first** (`os.environ`), then the layered `parse_system_makepkg_conf()` (`/etc/makepkg.conf` → user conf), quotes stripped and `~`/`$VARS` expanded, else `None`. These are the single home for "where did makepkg put / read this?" — any new code that needs to *locate* a built artifact, build tree, downloaded source, or build log must call them rather than assuming `~/builds` / the PKGBUILD dir / a hardcoded default (a recurring bug class). `BUILDDIR` resolution in particular feeds `makepkg_env._effective_build_dir` (side-car log diagnosis) and `kernel.resolve_built_config` (resolved `.config` discovery), both of which must honour a `BUILDDIR` set only in `/etc/makepkg.conf`. `PKGDEST` resolution feeds `makepkg_wrapper._find_artifacts` (the union-of-`PKGDEST`-and-PKGBUILD-dir locator behind `install_built_packages` + the post-build ABI report) and `build_core`'s artifact snapshot — so a non-default `PKGDEST` doesn't strand the install/ABI scan looking in the PKGBUILD dir. `install_built_packages` wraps that locator in `_artifacts_for_pkgbuild`, which scopes the union in two tiers. **Preferred:** a build-time manifest (`_BUILT_MANIFEST_NAME`, `.sysforge-built.list`) — the exact package basenames `makepkg --packagelist` emitted, recorded by `_capture_built_manifest` on build success *while the patched `PKGBUILD.sysforge` is still present* — is matched exactly. Recorded for any **name-affecting** build: one that applies an extracted profile **or** a rename (kernel local-rename / `-sysforge` suffix); a rename is exactly the case pkgname scoping can't recover (2.5.1-B3 — a rename-only kernel previously recorded no manifest because capture was gated on the extracted profile alone). This is the only reliable scope for a **renamed** build (e.g. a `-sysforge` kernel): by install time the patched PKGBUILD is cleaned up, leaving only the upstream PKGBUILD whose pkgname (`linux`) prefix-matches unrelated (`linux-custom`, `linux-steam-integration`) and stale-version (`linux-sysforge-<oldver>`) artifacts — the pre-B9 bug that swept those into `pacman -U` and could downgrade the running kernel. **Fallback** (no manifest, or none of its entries are present): scope by the PKGBUILD's own pkgnames (filename-matched via `_parse_built_pkg_filename`, which anchors on the exact `<pkgname>-` prefix **and** requires a valid `[epoch:]pkgver-pkgrel-arch` tail — three hyphen-delimited fields, since `PKGBUILD(5)` forbids hyphens in pkgver/pkgrel/arch — so pkgname `linux` no longer matches `linux-custom` et al., 2.5.1-B3). Within that set it keeps only the artifacts at the PKGBUILD's own `epoch:pkgver-pkgrel` (`_pkgbuild_version`), so an older build of the same pkgnames still in PKGDEST is not reported or installed as this build's output (`3.5.0-B21`: every build without a rename or extracted profile records no manifest, sandboxed mesa 26.2.5 included, and its post-build ABI report covered the 26.2.4 artifacts too); when that version matches none of them, as for a VCS PKGBUILD whose `pkgver()` rewrote a copy rather than this file, every scoped version is kept. This scoped set is returned **even when empty** — it never degrades to the full PKGDEST union: when the PKGBUILD parses cleanly and names its pkgnames but none match (the renamed-away case, absent a manifest), the caller fails loudly (`nothing to install`) rather than hand a shared PKGDEST of hundreds of unrelated packages to `pacman -U`. Only a PKGBUILD that yields *no* parseable pkgnames still degrades to the union (best-effort locate-everything), a case that fires solely with a local, unset `PKGDEST`. The manifest is deleted after a successful install so a later build in the same dir can't read a stale list.
 - `snapshot_pkg_dir(pkgdest)` — records the set of `.pkg.tar.*` files currently in pkgdest before a build
 - `batch_install_pkgs(pkg_paths, *, interactive=False, allow_break_deps=frozenset(), conflicts_out=None) -> bool` — installs the given artifacts in a single `sudo pacman -U`. An interactive run goes through `run_logged_transaction` (pty, stdin inherited so the conflict prompt works, every line teed into the run log, failed-hook lines raised to `warn()`; a failure logs the captured tail, superseding the old "output went to the terminal" note, `3.3.0-B21`); a non-interactive run keeps capturing stderr, which the file-conflict isolation needs. It never retries itself (the toolchain rollback wants all-or-nothing); with `conflicts_out`, a refused non-interactive transaction's file-conflict culprits (`file_conflict_culprits(stderr)` → `{pkgname: ["<path> exists in filesystem…"]}`) are handed back so the caller can retry without them (3.2.0-B33, consumed by `build_core.install_built`)
 - `read_pkgname_from_file(path)` — extracts `pkgname` from a built `.pkg.tar.*` via `bsdtar -xOqf <path> .PKGINFO`; returns `None` on failure
@@ -370,7 +374,7 @@ Sole entry point for inspecting LLVM-toolchain source trees before a command tou
 
 Public API: `is_llvm_in_scope(pkgnames)`, `collect_llvm_state(pkgnames, config, *, probe_fetch=False, offline=False)`, `is_actionable_state(state)`, `render_preflight(report, *, verbose=False)`, `evaluate_strict(report, *, allow_dirty=False)`. Read-only — never clones, never mutates. PKGBUILD resolution mirrors steps 1-3 of `config.find_pkgbuild` without the auto-clone branch.
 
-Wiring: `fetch` / `update` / `build` render the report informationally, unless `preflight_suppressed(args)` says otherwise: `--no-llvm-preflight` wins, else `[safety] llvm_preflight = false`, resolved through `config.resolve_flag_default` with the key negated (`3.5.0-B110`; the key used to be documented but unread). `render_preflight` shows only **actionable** rows (`is_actionable_state`): a row is worth printing when it has an active concern (dirty / diverged / PGO profdata-mismatch), was built locally (`install_origin == "foreign"`), or sysforge intends to build it from source (any non-`pacman` build_mode). A repo-origin package installed from the binary repo with no source build_mode has every source-state column empty/`unknown`, so its row is dropped (it would otherwise read as noise); when every row is non-actionable the whole block collapses to nothing. `--verbose` overrides the filter and renders every row. The filter is display-only — `evaluate_strict` still sees the full state set, so the `run toolchain` blocker path is unchanged. `run toolchain` calls `evaluate_strict` after `_resolve_all_pkgbuilds` and refuses-by-default on dirty or diverged trees; bypass per-run with `--allow-dirty-llvm`, or actually overwrite the local trees with `--cleansrc-force` (which uses the new dirty classifier so trees in the `diverged_upstream` state — upstream force-pushed, no local commits authored by the local git user — are reported as clean and don't even need the bypass). The dirty-reason string distinguishes `"N commits ahead of upstream"` (`ahead`, real unpushed work) from `"diverged from upstream (N local / M upstream)"` (`diverged_user`, the histories have a common ancestor but the local user authored at least one commit on the local side). PGO profdata version mismatches are never bypassable — building against stale profdata silently corrupts the output.
+Wiring: `fetch` / `update` / `build` render the report informationally, unless `preflight_suppressed(args)` says otherwise: `--no-llvm-preflight` wins, else `[safety] llvm_preflight = false`, resolved through `config.resolve_flag_default` with the key negated (`3.5.0-B110`; the key used to be documented but unread). `render_preflight` shows only **actionable** rows (`is_actionable_state`): a row is worth printing when it has an active concern (dirty / diverged / PGO profdata-mismatch), was built locally (`install_origin == "foreign"`), or sysforge intends to build it from source (any non-`pacman` build_mode). A repo-origin package installed from the binary repo with no source build_mode has every source-state column empty/`unknown`, so its row is dropped (it would otherwise read as noise); when every row is non-actionable the whole block collapses to nothing. `--verbose` overrides the filter and renders every row. The filter is display-only — `evaluate_strict` still sees the full state set, so the `run toolchain` blocker path is unchanged. `run toolchain` calls `evaluate_strict` after `resolve_all_pkgbuilds` and refuses-by-default on dirty or diverged trees; bypass per-run with `--allow-dirty-llvm`, or actually overwrite the local trees with `--cleansrc-force` (which uses the new dirty classifier so trees in the `diverged_upstream` state — upstream force-pushed, no local commits authored by the local git user — are reported as clean and don't even need the bypass). The dirty-reason string distinguishes `"N commits ahead of upstream"` (`ahead`, real unpushed work) from `"diverged from upstream (N local / M upstream)"` (`diverged_user`, the histories have a common ancestor but the local user authored at least one commit on the local side). PGO profdata version mismatches are never bypassable — building against stale profdata silently corrupts the output.
 
 Reuses (do not duplicate from caller code): `pkgbuild_patcher.is_llvm_pkgbase`, `aur.git_is_dirty`, `aur.git_fetch_and_compare`, `source_meta.SourceMetaCache.get`, `pkgbuild_meta.parse_pkgbuild`, `version.format_version`, `pacman.get_foreign_packages` / `get_installed_version`, `profile.match_rules` / `get_build_mode`, `makepkg_wrapper._resolve_pgo_state`. Log tag: `[LLVM]`.
 
@@ -568,13 +572,13 @@ AUR RPC queries, package source detection, git/pkgctl clone helpers, and GPG key
 - `aur_clone(name, dest, *, ref=None, depth=None)` — `git clone https://aur.archlinux.org/<name>.git <dest>`; optional `ref` / `depth` support shallow / branch-pinned clones. Raises `RuntimeError` on failure.
 - `git_fetch_and_compare(pkgbuild_dir, *, timeout=30, limiter=None, is_vcs=False)` — **full-history** fetch of the tracked upstream (`git fetch <remote> <branch>`, adding `--unshallow` when the repo is shallow) followed by a HEAD compare, then an `--ff-only` merge when HEAD is an ancestor of `FETCH_HEAD`. A `--depth=1` fetch is deliberately *not* used: it grafts the fetched tip as a parent-less root (and marks the repo shallow), which makes the `merge-base --is-ancestor` check — and the `rev-list` counts in `classify_head_vs_upstream` — see no shared history, so every routine upstream advance would falsely report `diverged`. Packaging repos carry only PKGBUILD/metadata, so a full fetch is cheap. **Non-destructive**: never runs a reset/rebase; returns a `GitFetchOutcome(status, head_before, head_after, error)` where `status ∈ {"up_to_date", "fetched", "diverged", "failed", "skipped_no_tracking"}`. Divergence (a genuine non-fast-forward — local commits or a force-push upstream) is reported, not auto-recovered here — the scheduler decides whether to reset (see `source_sync.py`). Honours the limiter's `wait_before_fetch()` / `Retry-After` budget when supplied. `is_vcs` (threaded from `source_sync.is_vcs_pkgbase(pkgbase)`, and from `llvm_state` for the same reason) governs **only the operator-facing message** on the dirty-tree branch: a `-git` checkout whose sole working-tree change is makepkg's `pkgver()` auto-bump plus the regenerated `.SRCINFO` is a build artifact, not operator work, so the `WARN … working tree has local modifications` is downgraded to an `INFO` noting the caller will reset. The fast-forward gate itself stays VCS-blind on purpose: `git merge --ff-only` aborts against a dirty tree whenever the upstream commit also touched `PKGBUILD` (the common AUR case), which would return `failed` — a scheduler blocker — where `diverged` is the outcome `source_sync`'s clean-tree hard-reset already heals correctly.
 - `is_transient_git_error(stderr)` / `is_rate_limit_error(stderr)` — shared stderr classifiers used by both the scheduler and legacy retry paths.
-- `_classify_head_vs_upstream(pkgbuild_dir)` — single classifier consumed by both `git_is_dirty` and `llvm_state._dirty_reason`. Returns `(state, n_local, n_upstream)` where `state ∈ {"not_a_repo", "no_head", "no_tracking", "clean", "behind", "ahead", "diverged_user", "diverged_upstream"}`. The two `diverged_*` states distinguish "upstream rewrote history (force-push), no local commits authored by the local git user" (`diverged_upstream` → not dirty) from "HEAD and upstream have a common ancestor but at least one of HEAD's divergent commits is authored **or committed** by the local user" (the committer check keeps a `git am`-applied or cherry-picked patch with a foreign author, `3.5.0-B69`) (`diverged_user` → dirty). The local user identity is read from `git -C <dir> config user.email` (with global fallback). `ahead` = HEAD is a strict descendant of upstream; `behind` = HEAD is an ancestor of upstream (the only "out of date but clean" case).
+- `classify_head_vs_upstream(pkgbuild_dir)` — single classifier consumed by both `git_is_dirty` and `llvm_state._dirty_reason`. Returns `(state, n_local, n_upstream)` where `state ∈ {"not_a_repo", "no_head", "no_tracking", "clean", "behind", "ahead", "diverged_user", "diverged_upstream"}`. The two `diverged_*` states distinguish "upstream rewrote history (force-push), no local commits authored by the local git user" (`diverged_upstream` → not dirty) from "HEAD and upstream have a common ancestor but at least one of HEAD's divergent commits is authored **or committed** by the local user" (the committer check keeps a `git am`-applied or cherry-picked patch with a foreign author, `3.5.0-B69`) (`diverged_user` → dirty). The local user identity is read from `git -C <dir> config user.email` (with global fallback). `ahead` = HEAD is a strict descendant of upstream; `behind` = HEAD is an ancestor of upstream (the only "out of date but clean" case).
 - `git_is_dirty(pkgbuild_dir, *, is_vcs=False)` — wrapper over the classifier: returns `True` for `no_tracking`, `ahead`, `diverged_user` (plus uncommitted tracked changes detected separately via `git status`); returns `False` for `clean`, `behind`, `no_head`, `not_a_repo`, `diverged_upstream`. Untracked files (build artifacts) are intentionally ignored. The `diverged_upstream` exemption fixes the false-positive on workstations whose Arch packaging clones get force-pushed every release. **`is_vcs=True`** (passed for `-git`/`-svn`/`-hg`/`-bzr` packaging repos) additionally filters out makepkg's `pkgver()` churn from the uncommitted-tracked check: a PKGBUILD whose diff against `HEAD` (not the index, so a staged edit still shows — `3.5.0-B38`) is restricted to `pkgver=`/`pkgrel=` lines (the auto-bump), and **any** change to the generated `.SRCINFO` (treated as a build artifact — `pkgver()` rewrites its version-pinned `depends`/`provides` lines too, so a line-level filter can't distinguish a mechanical bump from a real edit; deliberate edits live in PKGBUILD, which is still checked). Deliberate edits to other PKGBUILD lines / other tracked files still count as dirty.
-- `purge_src(pkgbuild_dir, *, force=False, is_vcs=False)` — `rm -rf` the directory after a `git_is_dirty` safety check. Raises `RuntimeError` if the clone holds local work that would be destroyed; non-git directories are purged unconditionally; non-existent paths are a silent no-op. `force=True` skips the dirty check and purges unconditionally — used by the `--cleansrc-force` CLI path. Used by `sysforge build --cleansrc[/-force]`, `sysforge update --cleansrc[/-force]`, `sysforge fetch --cleansrc[/-force]`, `sysforge run toolchain --cleansrc[/-force]`, and the source-sync recovery paths. **Detached-HEAD fix:** a `source = "repo"` checkout pinned to a release tag (see `source_sync.py` below) sits on a detached HEAD with no `@{u}` tracking branch — the pre-pin refusal logic treated that shape identically to a genuine local-only repo and refused to purge it. The refusal check (`_purge_refusal_message`) now calls `_head_reachable_from_remote` (`git branch -r --contains HEAD`) before citing "no upstream tracking branch": a detached HEAD that is still reachable from some remote branch is upstream's own history, not local-only work, and does not block the purge; a genuinely local-only commit (unreachable from any remote ref) still refuses.
+- `purge_src(pkgbuild_dir, *, force=False, is_vcs=False)` — `rm -rf` the directory after a `git_is_dirty` safety check. Raises `RuntimeError` if the clone holds local work that would be destroyed; non-git directories are purged unconditionally; non-existent paths are a silent no-op. `force=True` skips the dirty check and purges unconditionally — used by the `--cleansrc-force` CLI path. Used by `sysforge build --cleansrc[/-force]`, `sysforge update --cleansrc[/-force]`, `sysforge fetch --cleansrc[/-force]`, `sysforge run toolchain --cleansrc[/-force]`, and the source-sync recovery paths. **Detached-HEAD fix:** a `source = "repo"` checkout pinned to a release tag (see `source_sync.py` below) sits on a detached HEAD with no `@{u}` tracking branch — the pre-pin refusal logic treated that shape identically to a genuine local-only repo and refused to purge it. The refusal check (`_purge_refusal_message`) now calls `head_reachable_from_remote` (`git branch -r --contains HEAD`) before citing "no upstream tracking branch": a detached HEAD that is still reachable from some remote branch is upstream's own history, not local-only work, and does not block the purge; a genuinely local-only commit (unreachable from any remote ref) still refuses.
 - `purge_srcdest(pkgbase, srcdest_dir, *, pkgbuild_dir=None)` — companion to `purge_src` for `--cleansrc`: the checkout rmtree never touched makepkg's `SRCDEST` tarball cache, so a purged-and-re-cloned package could still rebuild against a stale cached source tarball instead of the freshly re-pinned/re-cloned tree. Deletes `<pkgbase>-<digit…>*` entries (matching makepkg's `name-version.ext` tarball naming, so a dash-prefixed sibling pkgbase like `foo-tools` is never clobbered by a `foo` purge) from `srcdest_dir`. No-ops when `srcdest_dir` is unset/missing, or resolves inside `pkgbuild_dir` (the makepkg-default layout, already covered by the checkout rmtree). Best-effort hygiene, not a safety gate: no dirty-tree guard, no force flag, failures warn and never raise. Returns the count removed. Called from both `SourceSyncScheduler` cleansrc branches (the explicit `--cleansrc` purge and the missing-PKGBUILD recovery purge) alongside `purge_src`.
 - `pkgctl_checkout(name, dest, *, timeout=60)` — `pkgctl repo clone --protocol=https <name>` run in `dest.parent`; fetches official Arch packaging repo. Output is streamed line-by-line to `_build_log.debug` so progress is visible at `-vvv` (cloning from gitlab.archlinux.org can take minutes on a fresh checkout). Raises `RuntimeError` on failure or timeout. `find_pkgbuild` passes `[git] clone_timeout` from `sysforge.toml`; `0` disables.
 - `pkgctl_switch_version(dest, version, *, timeout=60)` — `pkgctl repo switch <version>` run inside an existing `pkgctl_checkout` clone; `pkgctl` owns the pacman-version → git-tag translation (epoch and pkgrel included), so callers pass `pacman.get_repo_candidate_version()` output verbatim. Leaves the checkout on a detached HEAD at the tag. Raises `RuntimeError` on failure or timeout (including a missing `pkgctl` binary — hints at `devtools`). Sole caller: `source_sync.SourceSyncScheduler._pin_repo_checkout` (see below).
-- `import_pgp_keys(pkgmeta, pkgbuild_path)` — ensures all `validpgpkeys` listed in the PKGBUILD are in the GPG keyring before `makepkg` runs. Strategy: (1) import any bundled `.asc` files from `keys/pgp/` alongside the PKGBUILD, (2) check which keys are still missing via `gpg --list-keys`, (3) fetch remaining via `fetch_pgp_keys` — the **one home for keyserver fetches** (`3.1.0-F8`; `auto_repair`'s PGP repair routes through it too). `validpgpkeys` exists so a person decides who the upstream signer is, so the fetch: is its own egress kind (`net_policy.KIND_KEY_FETCH`), so `freeze_sources` covers it and a frozen run raises `NetworkFrozen` (the package fails with the `--thaw` hint; the batch continues); lands in a throwaway `GNUPGHOME` first, then prints each key's fingerprint, primary uid and the requesting pkgbase (`ui()`) before anything touches the real keyring; and imports (`--export` from the throwaway home → `--import`) only after a TTY confirmation (`primitives/prompt.py`, default No). A non-interactive run fails closed — nothing imported, an error naming the fingerprints and the manual `gpg --recv-keys` — unless `[security] auto_fetch_pgp_keys = true` (installed once by `cli.main` via `set_key_fetch_policy`) restores unattended imports, still echoed. Bundled-key import and the keyring check are unaffected. Other import failures are logged as warnings — makepkg surfaces a clearer error if a key is still absent at verification time.
+- `import_pgp_keys(pkgmeta, pkgbuild_path)` — ensures all `validpgpkeys` listed in the PKGBUILD are in the GPG keyring before `makepkg` runs. Strategy: (1) import any bundled `.asc` files from `<pkgbuild dir>/keys/pgp/`, (2) check which keys are still missing via `gpg --list-keys`, (3) fetch remaining via `fetch_pgp_keys` — the **one home for keyserver fetches** (`3.1.0-F8`; `auto_repair`'s PGP repair routes through it too). `validpgpkeys` exists so a person decides who the upstream signer is, so the fetch: is its own egress kind (`net_policy.KIND_KEY_FETCH`), so `freeze_sources` covers it and a frozen run raises `NetworkFrozen` (the package fails with the `--thaw` hint; the batch continues); lands in a throwaway `GNUPGHOME` first, then prints each key's fingerprint, primary uid and the requesting pkgbase (`ui()`) before anything touches the real keyring; and imports (`--export` from the throwaway home → `--import`) only after a TTY confirmation (`primitives/prompt.py`, default No). A non-interactive run fails closed — nothing imported, an error naming the fingerprints and the manual `gpg --recv-keys` — unless `[security] auto_fetch_pgp_keys = true` (installed once by `cli.main` via `set_key_fetch_policy`) restores unattended imports, still echoed. Bundled-key import and the keyring check are unaffected. Other import failures are logged as warnings — makepkg surfaces a clearer error if a key is still absent at verification time.
 - `fetch_aur_name_cache(force=False)` — downloads `https://aur.archlinux.org/packages.gz` and extracts it to `$XDG_CACHE_HOME/sysforge/aur-packages.txt` (default `~/.cache/sysforge/aur-packages.txt`). Skips the download if the cache is less than 24 hours old unless `force=True`. Called as a side effect of `sysforge update`; read by `sysforge completions packages` to provide AUR package name completion.
 
 `sysforge completions packages` — outputs local pkgbuild_src_dir packages + pacman sync DB names + AUR cache. Used by both completion scripts for `build`, `packages add`. The merged list (~140k names) is cached in `$XDG_CACHE_HOME/sysforge/completion-packages.txt` (`completions_data.PACKAGES_CACHE`); its first line is a key of every input's mtime (each `/var/lib/pacman/sync/*.db`, the AUR name list, `pkgbuild_src_dir`), so the list is rebuilt, and `pacman -Ssq` run, only after one of them changes, and a fresh cache costs one file read. The scripts pass `--prefix=<typed text> --limit=<cap + 1>`, so sysforge filters and caps the list itself rather than piping every name through `grep`; zsh shows a `zle -M` message when the cap is exceeded. `--prefix`/`--limit` apply to every resource.
diff --git a/docs/design/13-man-pages.md b/docs/design/13-man-pages.md
index 64164f31..ec121d55 100644
--- a/docs/design/13-man-pages.md
+++ b/docs/design/13-man-pages.md
@@ -7,7 +7,7 @@ tools/gen_options.py --template man/sysforge.1.scd.in --out man/sysforge.1.scd
 scdoc < man/sysforge.1.scd > man/sysforge.1
 ```
 
-- **`man/sysforge.1.scd.in`** (committed) — hand-written NAME / SYNOPSIS / DESCRIPTION / GLOBAL OPTIONS / FILES / ENVIRONMENT / EXIT STATUS / EXAMPLES / SEE ALSO / AUTHORS prose, with an `@OPTIONS@` marker where the generated COMMANDS sections splice in and an `@SHARED_OPTIONS@` marker under a hand-written SHARED OPTIONS heading. The template stays short: a config key's reference text lives in the shipped config file's own comments (FILES says so), and DESCRIPTION gives an overview without repeating any command's options. scdoc syntax gotcha: indented continuation lines must not start with a table-control character (`[`, `|`, `]`) — scdoc errors with "Tables cannot be indented".
+- **`man/sysforge.1.scd.in`** (committed) — hand-written NAME / SYNOPSIS / DESCRIPTION / GLOBAL OPTIONS / FILES / EXIT STATUS / EXAMPLES / SEE ALSO / AUTHORS prose, with an `@OPTIONS@` marker where the generated COMMANDS sections splice in and an `@SHARED_OPTIONS@` marker under a hand-written SHARED OPTIONS heading. The ENVIRONMENT and JOURNAL bodies are generated too, from `@ENVIRONMENT@` (`primitives/env_vars.ENV_VARS`, user settings then diagnostic switches, `3.5.0-B128`) and `@JOURNAL@` (`primitives/journal.JOURNAL_FIELDS`, `3.5.0-DOC13`); `tests/test_env_vars.py` fails on a `SYSFORGE_*` name the code uses that neither table lists, and on a listed variable nothing reads. `gen_options._wrap` keeps a word starting with `[`, `|` or `-` off the start of a line, since scdoc reads one there as a table or list. The template stays short: a config key's reference text lives in the shipped config file's own comments (FILES says so), and DESCRIPTION gives an overview without repeating any command's options. scdoc syntax gotcha: indented continuation lines must not start with a table-control character (`[`, `|`, `]`) — scdoc errors with "Tables cannot be indented".
 - **`tools/gen_options.py`** — walks `verbs.registry.build_parser()`'s subparser tree depth-first (so `packages add`, `run kernel`, etc. each get a `## <name>` section) — top-level commands ordered by `verbs.registry.tiered_command_order()` so the COMMANDS sections stay in lockstep with the `sysforge --help` usage tiers (§CLI Verb Framework), sub-commands in registration order — emits a synopsis line plus one definition block per positional/option (a value placeholder is the metavar, else the choices as `_a_|_b_`, matching `--help`), escapes scdoc formatting characters in help text, and performs the splice itself (no sed). Subparsers registered without `help=` (the internal `completions` data sink) are excluded. **Shared options** (`_shared_options`): an option two or more commands carry with the same head *and* the same help text is written once under SHARED OPTIONS, with a `Used by:` line, and each of those commands lists it in a `*Shared options:*` line instead of repeating the block. A flag whose help differs between commands shares only its most common text (first-seen on a tie) and the others stay inline, so SHARED OPTIONS never lists a flag twice. Sharing is keyed on identical text, so wording drift between verbs shows up as an inline duplicate: give a flag that means the same everywhere one help constant (`verbs.helpers.PACKAGES_FILE_HELP`, `CLEANSRC_FORCE_HELP`). Each command section also gets a `*Configuration:*` / `*Environment:*` trailer from the hand-maintained `_VERB_CONFIG` dict at the top of the script (qualified command name → config files / env vars consumed; commands without an entry get no trailer). The FILES and ENVIRONMENT sections of the template carry the inverse index ("Read by: …") — when a verb gains or loses a config source, update both `_VERB_CONFIG` and the template. The trailer is man-page-only by design: it is not wired into argparse epilogs, so it never appears in `--help` output (which has its own tiered `COMMAND` grouping — §CLI Verb Framework).
 - **`man/sysforge.1.scd`** — intermediate, gitignored. **`man/sysforge.1`** — committed, so AUR-built tarballs ship the page without build-time tooling; the PKGBUILD `package()` installs the committed file directly and needs no man-page makedepend.
 - Makefile target: `make man` (pins `COLUMNS=80` so any argparse-derived wrapping is deterministic). `scdoc` is a dev-machine dependency only (the `DEV_DEPS_CORE` set, installed by `make dev-deps` / `make dev`); `python-argparse-manpage` is no longer used anywhere.
diff --git a/docs/design/14-hardware-detection.md b/docs/design/14-hardware-detection.md
index faa8c0cd..c912909b 100644
--- a/docs/design/14-hardware-detection.md
+++ b/docs/design/14-hardware-detection.md
@@ -76,7 +76,7 @@ In addition to the positive `=y` enables above, the hardware stage emits an `=n`
 
 `_arch_disable_kconfig(host_arch)` resolves the host domain, then iterates every *other* domain in the registry and emits `{CONFIG_X: "n"}`. Keys appearing in the host's own domain set are filtered out as a defensive guard (no clobber if a future kconfig key gains a presence in multiple domains). Unknown `host_arch` returns an empty dict and logs a WARN.
 
-The `=n` entries land in the same `[kconfig]` table as the existing `=y` enables, so the kernel stage's existing merge path — `merged = {**device_kconfig, **hw_kconfig, **manual_kconfig}` — applies unchanged. A user cross-compiling or otherwise wanting an arch-disabled key re-enabled puts an explicit `[[kconfig]] option = "CONFIG_ARM64" value = "y"` in `kernel.toml`; the existing manual-override-wins-with-WARN behaviour in `_write_kconfig_fragment` extends to arch-disable entries.
+The `=n` entries land in the same `[kconfig]` table as the existing `=y` enables, so the kernel stage's existing merge path — `merged = {**device_kconfig, **hw_kconfig, **manual_kconfig}` — applies unchanged. A user cross-compiling or otherwise wanting an arch-disabled key re-enabled puts an explicit `[[kconfig]] option = "CONFIG_ARM64" value = "y"` in `kernel.toml`; the existing manual-override-wins-with-WARN behaviour in `write_kconfig_fragment` extends to arch-disable entries.
 
 ### Device-driven kconfig (`[kconfig_devices]`)
 
@@ -95,7 +95,7 @@ Design ambition is broad (every kconfig domain in the registry, every CPU/GPU br
 - Storage: NVMe
 - Distro: Arch Linux, kernel: custom `linux-custom` PKGBUILD
 
-**Tested in VM** (`make vm-iso` → `make vm-install`):
+**Tested in VM** (`make vm-iso` → `make vm-install-stable`):
 - Host arch: `x86_64` (qemu/KVM guest)
 - CPU: emulated/passthrough (typically host-passthrough)
 - GPU: virtio (`gpu_vendors` likely empty or `["other"]`)
diff --git a/docs/design/15-cache-management.md b/docs/design/15-cache-management.md
index 9045a557..c34ab1a9 100644
--- a/docs/design/15-cache-management.md
+++ b/docs/design/15-cache-management.md
@@ -36,7 +36,7 @@ Cache probe uses `ccache --print-stats --format=tab` (ccache ≥ 4.0, standard o
 
 ### Toolchain fingerprint tracking
 
-SysForge tracks a toolchain fingerprint (hash of compiler path + version) in its state dir. On mismatch (e.g. after LLVM version bump), `invalidate_on_toolchain_change` fires: `warn` (default) / `purge` / `ignore`.
+There is no cache-invalidation setting. Each source build records the toolchain that built it in `build_state.toml` (`toolchain_variant`, `toolchain_fingerprint`), and `sysforge update` reports a package built by a different or rebuilt toolchain as toolchain drift (§Drift detection), rebuilding it with `--rebuild-on-toolchain-drift`. The compile caches need nothing from sysforge here: ccache and sccache key their entries on the compiler itself, so a toolchain change misses rather than reusing objects from the old compiler.
 
 ---
 
diff --git a/docs/design/16-graphics-stack.md b/docs/design/16-graphics-stack.md
index c9619621..be55f299 100644
--- a/docs/design/16-graphics-stack.md
+++ b/docs/design/16-graphics-stack.md
@@ -23,7 +23,7 @@ Build in this order to satisfy dependencies correctly:
 - **Target-init drop (unhealable).** A dropped LLVM backend (e.g. a reduced `LLVM_TARGETS_TO_BUILD` without `AMDGPU`). The symbol would not exist anywhere — rebuilding the consumer cannot recover it. Gate 2 hard-aborts before install; the AMDGPU baseline is the real fix. **Unchanged behaviour.**
 - **`std::` re-export drop (healable).** A drop of *only* non-target-init `LLVM_*`-versioned symbols. These are libstdc++ `std::__cxx11::basic_string` methods that LLVM's `global: *` version script globs into the `LLVM_<ver>` node as out-of-line weak copies. The official `llvm-libs` exports them; mesa links them as `…@LLVM_<ver>`. A PGO (`-fprofile-use`) `libLLVM` **inlines those weak copies away**, so the optimized lib — *at the same soname* — no longer exports them and mesa is stranded. This is healable: rebuilding mesa against the new `libLLVM` re-links the symbols to libstdc++ (`@GLIBCXX_*`), exactly as a distro does on an llvm rebump.
 
-For the healable class Gate 2 does **not** abort. It captures the installed libLLVM consumers via `toolchain_safety.libllvm_abi_consumers` (the reverse-dep `%DEPENDS%` walk factored out of `assess_libllvm_soname_impact` into `libllvm_soname_consumers`, here **not** gated on a soname change) and rebuilds them after Gate 3 through the same `_rebuild_soname_consumers` path used for a soname bump — gated by the existing `rebuild_soname_consumers` mode (`prompt` default | `auto` | `off`). Gate 3 tolerates the healable miss (mesa is not rebuilt until *after* Gate 3, so a rollback there would revert the very libLLVM the rebuild is about to make coherent); only target-init misses still trip the auto-rollback. The system self-stabilises: once mesa links the optimized libLLVM it stops importing the `…@LLVM_<ver>` `std::` symbols, so a subsequent `run toolchain` sees no stranding and queues no rebuild. Note `assess_libllvm_soname_impact` still short-circuits on a same-version (`old_mm == target_mm`) refresh — the std:: drift is owned by this Gate-2/3 + `libllvm_abi_consumers` path, not the soname-bump gate. Since `3.5.0-F4` the toolchain's libLLVM re-exports the members stock libLLVM did, as non-default-versioned thunks (§Pipeline layer → Gate 2), so a stock-linked mesa no longer strands on them; the healable path remains for any export outside that table, which Gate 2 names.
+For the healable class Gate 2 does **not** abort. It captures the installed libLLVM consumers via `toolchain_safety.libllvm_abi_consumers` (the reverse-dep `%DEPENDS%` walk factored out of `assess_libllvm_soname_impact` into `libllvm_soname_consumers`, here **not** gated on a soname change) and rebuilds them after Gate 3 through the same `rebuild_soname_consumers` path used for a soname bump — gated by the existing `rebuild_soname_consumers` mode (`prompt` default | `auto` | `off`). Gate 3 tolerates the healable miss (mesa is not rebuilt until *after* Gate 3, so a rollback there would revert the very libLLVM the rebuild is about to make coherent); only target-init misses still trip the auto-rollback. The system self-stabilises: once mesa links the optimized libLLVM it stops importing the `…@LLVM_<ver>` `std::` symbols, so a subsequent `run toolchain` sees no stranding and queues no rebuild. Note `assess_libllvm_soname_impact` still short-circuits on a same-version (`old_mm == target_mm`) refresh — the std:: drift is owned by this Gate-2/3 + `libllvm_abi_consumers` path, not the soname-bump gate. Since `3.5.0-F4` the toolchain's libLLVM re-exports the members stock libLLVM did, as non-default-versioned thunks (§Pipeline layer → Gate 2), so a stock-linked mesa no longer strands on them; the healable path remains for any export outside that table, which Gate 2 names.
 
 ---
 
diff --git a/docs/design/17-release-plan.md b/docs/design/17-release-plan.md
index 3c40d5d5..ca7ba04f 100644
--- a/docs/design/17-release-plan.md
+++ b/docs/design/17-release-plan.md
@@ -35,8 +35,8 @@ the gates — they need a booted VM or a working podman and network, neither of
 prerequisite of a lint run — but a minor or major release that skips them is untested against a
 real install. See `tools/vm/README.md` and `tools/container/README.md`.
 
-**CI** (`.github/workflows/ci.yml`, `3.4.0-DEV1`) runs every `pre-release` gate on every push and
-pull request in a fresh `archlinux:base-devel` container, as an unprivileged user, with only the
+**CI** (`.github/workflows/ci.yml`, `3.4.0-DEV1`) runs every `pre-release` gate on each pull request (a newer push to
+it cancels the superseded run) and on each push to `main`, in a fresh `archlinux:base-devel` container, as an unprivileged user, with only the
 core dev tier (`make dev-deps-core`) installed. Its job is
 to catch a test or gate that passes only because of the workstation (clang-forced shell, live
 config, installed extras, one hardware profile); it is not a release gate and holds no signing key.
@@ -50,8 +50,9 @@ report (`tools/junit_annotate.py`, `3.5.0-DEV6`). It opens with the container's
 (package count, LLVM and `tomlkit` presence, Python, pytest and uv versions) so a CI-only failure
 compares against the local machine (`3.5.0-DEV7`).
 The job body is `tools/ci.sh`, and `make ci-local` replays it under podman against the working tree
-(read-only mount, `CI=true` set as on the runner), so a red run reproduces without a push. It stays
-advisory (no branch protection) until it has held green for one release cycle. Because it runs the
+(read-only mount, `CI=true` set as on the runner), so a red run reproduces without a push. Its `gates`
+job is a **required status check**: a ruleset on `main` requires pull requests and a green `gates`
+run before merge, so every check below binds every contributor, not only those who run it locally. Because it runs the
 `pre-release` set in a strictly cleaner environment, the checklist's static-gate stage uses `make
 ci-local`, with `pre-release` as the fallback where podman is unavailable.
 
@@ -86,6 +87,7 @@ The version markers in `README.md` and `DESIGN.md` wrap the single live version
 - **`pkgbuild_parity`** — `PKGBUILD` and `PKGBUILD-git` parse to the same dict (via `pkgbuild_meta.parse_pkgbuild`) except for a tightly-scoped allowlist of keys that are *supposed* to differ (`pkgname`, `pkgver`, `pkgrel`, `pkgdesc`, `source`, `sha256sums`, `conflicts`, `provides`, `validpgpkeys` — stable-only, since the VCS package has no release `.asc`). `depends` / `makedepends` / `optdepends` / `backup` arrays must be byte-identical, and both `package()` bodies must install the same set of targets (`_parse_pkgbuild_install_targets`), which is how a `pkgbuild`-group rule checked on the stable file, such as the license install, reaches `PKGBUILD-git`.
 - **`hooks`** — every `etc/pacman.d/hooks/sysforge-*.hook` `Exec` line must invoke `tools/pacman-hook-helper.sh` and pass a subcommand the helper documents (`kernel`, `toolchain`, `buildstate`).
 - **`completions`** — every verb and every long-flag in the argparse parser tree (reached via `sysforge.verbs.registry.build_parser`) must appear in both `completions/_sysforge` and `completions/sysforge.bash`; stale top-level verb entries in the zsh case statement (function-suffix matches case-word but parser doesn't know the verb) are an error. Mirrors the `completions-cli-parity` subagent's audit; this is the mechanical layer that runs every release.
+- **`completion_commands`** (`3.5.0-DEV14`) — `completions` only walked top-level commands, so after `3.5.0-F15` left group parents with no flags, no subcommand flag was checked at all, and a flag counted as present if it appeared anywhere in the file. This group checks each command where it is completed: its zsh function (`_sysforge_state_orphans`, description text excluded) and its bash `case` arm. Every long flag must be offered there, nothing the command lacks may be, every argparse `choices` value must be offered (bash keeps values in `_sysforge_flag_arg` keyed by flag, or in the command's own body), and lists copied from code constants (`_MIRRORED_LISTS`: the desktop catalog, `PROFILE_METHODS`) must equal them. Its first run found bash offering no values for `run toolchain --rebuild-soname-consumers` (`3.5.0-B127`).
 - **`completion_widths`** — every description in `completions/_sysforge` must fit an 80-column listing (`COMPLETION_TARGET_COLUMNS`). zsh renders a match as `<match><pad>  -- <description>`, padding the match column to the longest match in that generator call; once a row exceeds the terminal width zsh abandons the inline two-column table and emits every description as its own list entry, so the whole block renders with names and descriptions detached (the 3.0.0-B2 symptom). The budget is therefore per-call and shared: `COLUMNS - (longest match in the block) - 4`, computed separately for each `_arguments` spec list and each `_describe` array (`_completion_blocks`). One over-wide row degrades every row beside it, and adding a long *option name* to a verb tightens the budget for every *description* in it — `update` is the tightest block in the file at 48 characters, bounded by `--rebuild-on-toolchain-drift`. `completions/sysforge.bash` is not checked: it emits bare `compgen -W` word lists with no descriptions and cannot exhibit this failure.
 - **`versions`** — `pyproject.toml` `[project] version` must equal `PKGBUILD` `pkgver=`, the leading `X.Y.Z` of `PKGBUILD-git` `pkgver=`, and every `<!--version-->vX.Y.Z<!--/version-->` marker in `README.md` and `DESIGN.md` (literal `vX.Y.Z` placeholder strings in prose are filtered out by the `\d+\.\d+\.\d+` constraint).
 - **`manpage`** — regenerates `man/sysforge.1` via the scdoc-hybrid pipeline `make man` uses (`tools/gen_options.py` splices the argparse-derived COMMANDS sections into `man/sysforge.1.scd.in`, then `scdoc` renders) into temp files and diffs against the committed page; any difference is an error, with the fix `make man && git add man/sysforge.1`. Both sides are passed through `_normalize_roff` before diffing, so scdoc-version-specific artifacts aren't findings: the `.TH … "DATE"` header (daily date change), the `.\" Generated by scdoc <version>` banner, and hyphen escaping (`\-` vs `-`, functionally inert in roff). This keeps the gate coupled to the CLI surface rather than to the local scdoc build. Skipped with a `warn` if `scdoc` isn't on PATH. See the Man Pages section.
@@ -94,10 +96,14 @@ Findings default to hard fail (non-zero exit); pass `--warn` for a report-only m
 
 **Documentation consistency guards.** Large sweeps (renames, removals, moved sections) leave stale references behind in places no parser reads: prose, comments, completions. A guard per kind of reference:
 
+- **The surface snapshot** (`tools/surface.py`, `make surface` / `make check-surface`, `3.5.0-DEV18`) — `tests/data/surface.json` lists every user-facing surface: each command's flags and their allowed values, the environment variables and journal fields, each config file's sections and keys (open sections as `null`), each `--json` document's fields, and the run-log names. It is generated like `DESIGN.md`, so a surface change is one reviewable diff. The gate, which `pre-release`, CI and the release preflight all run, fails when the snapshot is stale, and compares it with the base (the merge-base with `main`, or on `main` the previous commit, since a squash merge lands as one): every added or removed entry must be named in text the change adds to `unreleased.md`, and a flag, command, environment variable or config key that leaves the product entirely must be registered as retired (`tools/retired_names.toml`, or `RETIRED_KEYS`). These are the two things the checks above could not see: a removal nobody registered, and a change with no release note. `CONTRIBUTING.md`'s surface table and `.github/pull_request_template.md` carry the same rules for human contributors, and `make install-hooks` adds a pre-commit hook (`tools/pre-commit.sh`) running the fast gates.
 - **`design_refs`** (`check_standards`, `3.5.0-DEV10`) — every `§Section` in `docs/design/`, both CLAUDE.md files and `sysforge/` code must name something that exists: a DESIGN.md heading or bold run-in lead, matched by word-prefix so `§CLI Verb` and `§Drift detection → *Toolchain drift*` resolve; a design file number or slug (`§07`, `§primitives-layer`); a design `.md` file; or a standards row. External citations (`RFC 7231 §7.1.3`, `§§6–8`) are skipped. Its first run found nine dangling references, among them six `§Reconvergence` (design 18's heading is *Drift detection*) and a `§1242–1264` that cited DESIGN.md line numbers.
 - **Written-down commands** (`tests/test_verb_registry.py`, `3.5.0-DEV11`, generalising `3.5.0-B3`'s doctor-only check) — every `sysforge …` in string literals, docstrings and comments under `sysforge/`, the README, both CLAUDE.md files, the man source, guides, concept pages and shipped config comments is walked through the real parser: each long flag must exist on its subcommand or be global (a flag's value is skipped), and an unknown word close to a real subcommand is a typo or a rename. Short flags are not judged (`build`/`update` pass makepkg's through), and a word that matches no subcommand is prose or a positional. Design docs, ROADMAP and release notes name old spellings on purpose and are not scanned.
 - **`retired_names`** (`check_standards`, `3.5.0-DEV12`) — `tools/retired_names.toml` lists names sysforge no longer has (each with the ID that retired it and what to use instead), and none may appear in a tracked file outside release notes, ROADMAP, tests (which check the old names are refused), the generated DESIGN.md and the entry's own `allow` list (the migration code that still reads an old value). Whole-word match, comments and completions included. Only names that cannot mean anything else are listed: a spelling still valid on another command (`--force`) or common in other tools (`--prune`) is left to the per-command check above. Its first run found design 08 citing a function `3.5.0-F17` removed, and standards row 24 still describing the deprecation record `3.5.0-F16` removed as live.
-- **Stand-ins** (`tests/test_stand_ins.py`, `3.5.0-DEV13`) — a `SimpleNamespace` in place of `BuildOptions`, `RunOptions` or a parsed command line breaks every test at once when the code reads a new field, and keeps passing on a renamed one. Tests build the real thing: both dataclasses default every field and reject unknown names, and `build_parser().parse_args([...])` has every flag. Options stand-ins (recognised by a field on the dataclass that is no CLI destination) are not allowed at all; argument stand-ins that predate the check sit in a shrinking per-file allowlist, so a new one fails and a converted file must lower its count.
+- **`citations`** (`check_standards`, `3.5.0-DEV15`) — the `claude_md` resolver, run over `docs/design/` and the tracked `.claude/` agents, skills and rules, which steer contributors and agents as much as CLAUDE.md does. It learned `path/module.symbol` citations, placeholders (`vX.Y.Z`), a symbol in any same-named module, and `make` targets (missing counts only as a near miss of one of ours, since the kernel's `make nconfig` is quoted on purpose); paths are checked only when their first segment is in the repo, and bare `.sh` names are skipped. A bare code name (private, snake case or camel case) with no module to resolve against must at least appear in a tracked non-doc file; names from other software and deliberate history are listed (`_CITATION_EXTERNAL`, `_CITATION_HISTORY`). That rule found 48 private names design 07 still used after the `3.2.0` split made them public, a removed editor prompt, and a cache setting design 15 described that never existed. Inline code is now paired per line with fenced blocks dropped (both groups): a ```` ``` ```` fence had paired with the next lone backtick and hidden a stale path. Its first run found, besides false positives, a design passage on the prompt module with a removed stage file, a removed function, inverted `eof_default` facts and per-file call counts that were all wrong, a symbol under the wrong module, `make vm-install`, and two `.claude` files citing a removed verb module and a test file that never existed.
+- **Concept pages** (`tests/test_concept_pages.py`, `3.5.0-DEV16`) — each page but the glossary closes with *Further reading* (at least one upstream link) then *In sysforge*, and nothing before *In sysforge* uses sysforge's own vocabulary (its name, its config files, `build_state`). Upstream tools' flags stay allowed, since they are the technique. The rest of the rule (no numbers measured on one machine) stays a review item.
+- **Flags reach the code** (`tests/test_flags_reach_code.py`, `3.5.0-DEV17`) — a field read on an options object (`options`, `opts`, ...; by attribute or `getattr` with a literal, method calls excluded) must be a `RunOptions` or `BuildOptions` field, since a missing one silently returns its default: the shape of `3.5.0-B129`, which this reports on the pre-fix code. And every command's parsed flag must be read through its argument object (`args.x`, `run.args.x`, `getattr(args, "x")`, `resolve_flag_default(args, "x")`) somewhere in the package, except the namespace dispatch fields and two indirect readers named in the test (doctor's `_AXIS_FLAGS`, pinned to the axis flags exactly, and `PKG_KEY_BUILD_FROM_SOURCE`). With `test_every_run_stage_flag_reaches_the_stage` this covers the hop from parsed arguments to the options a stage reads.
+- **Stand-ins** (`tests/test_stand_ins.py`, `3.5.0-DEV13`) — a `SimpleNamespace` in place of `BuildOptions`, `RunOptions` or a parsed command line breaks every test at once when the code reads a new field, and keeps passing on a renamed one. Tests build the real thing: both dataclasses default every field and reject unknown names, and `tests/cli_args.cli_args(*argv, **fields)` parses a real command line, then sets fields the command has (a name it lacks fails). Options stand-ins (a field on the dataclass that is no CLI destination) are refused; argument stand-ins (fields all one command's flags) may appear only in `_ARGS_STAND_INS`, which is empty and pinned so (`test_stand_in_allowlist_is_empty`); its last entry tested a `getattr` fallback in `make_build_options` no caller needed, and both went. Converting the 31 others found `run kernel --keep-hotplug-drivers` parsed and dropped (`3.5.0-B129`, now guarded by `test_every_run_stage_flag_reaches_the_stage`) and sentinel-gate tests exercising `build --dry-run` and `setup --dry-run`, which do not exist.
 
 **Clean chroot validation.** The release gate catches underspecified `depends`/`makedepends` that a host build would silently accept because the dep is already installed. It uses `makechrootpkg` from `devtools` and is a hard prerequisite for the release flow — not the everyday `sysforge build` path, which remains a direct host-side `makepkg` invocation for speed.
 
diff --git a/docs/design/21-standards.md b/docs/design/21-standards.md
index 5400d2c3..f444d298 100644
--- a/docs/design/21-standards.md
+++ b/docs/design/21-standards.md
@@ -63,7 +63,7 @@ subsection is only presentation.
 | 27 | Release-gate completeness | Static-analysis gates of `make pre-release` vs the `tools/release.sh` preflight | enforced | Every `pre-release` prerequisite except the full `test` suite (the heavier tier, by design) is also run by the release preflight, which fails the release on it. `pre-release` is advisory and the script is the gate a release cannot skip, so a check only the former runs is one a tag can ship without: `v3.2.0` shipped four pyright errors — one a live crash (`3.2.0-B30`) the type-checker had named weeks earlier — and the 3.3.0 cycle reached eighteen (`3.2.0-STD1`). `check_standards` `release_gates` group diffs the `pre-release:` prerequisite list against the targets `release.sh` invokes, so `docs/RELEASE-CHECKLIST.md`'s gate table cannot silently diverge. A new `pre-release` gate is added to the script in the same change, or to `_RELEASE_GATE_EXEMPT` with its reason. Because the script *blocks*, each gate must also be deterministic: a `uv run --with` overlay in a gate's recipe is pinned (`PYRIGHT_VERSION`, `REUSE_VERSION` in the Makefile header), since an unpinned overlay resolves the newest release on every run and a tool update alone could turn a release red; the same group flags an unpinned `--with` in any gate recipe. Pins are bumped deliberately in their own commit, and the header keeps the no-`[dependency-groups] dev` rule (the overlays stay the one record). Known residue: `lint` runs the pacman-provided `ruff`, which is kept on `PATH` for editor/hook integration and so follows system upgrades. |
 | 30 | No em-dashes in user-facing prose | `README.md`, `docs/guides/`, `docs/concepts/` (`3.5.0-DOC3`), the man page (`man/sysforge.1.scd.in` and the generated `man/sysforge.1`), `completions/`, and every non-docstring string literal under `sysforge/`: `--help` text, log and prompt messages, exception text, and the headers of files sysforge generates | enforced | Rewrite with a comma, colon, semicolon, period or parentheses as the sentence needs, never a blind substitution (`3.4.0-DOC2`). `check_standards` `em_dash` group: a line scan of the files and an AST scan of every string constant under `sysforge/`, so implicit concatenation and f-string pieces are covered without importing `sysforge`. Exempt: docstrings (developer prose), a literal that is only the glyph (an empty-cell placeholder, or a key in `log`'s ASCII glyph-fallback table), ROADMAP and release-note entries, whose ``- **`<ID>` — <title>.**`` lead is a lint-enforced format (changing it is its own `STD`), internal docs, shipped-config and hook comments, and code comments. `tests/test_standards_compliance.py` (`test_em_dash_*`). |
 | 31 | Subprocess goes through `primitives/run` | Every external command `sysforge/` runs | enforced | Numbered 28 until `3.4.0-STD2`, when it was found sharing that number with the `pam.d(5)` row, which took 28 first and keeps it. ruff `banned-api` (TID251, `pyproject.toml`) bans `subprocess.run`/`Popen`/`call`/`check_call`/`check_output` outside the seam modules `primitives/run.py`, `pty_runner.py`, `privilege.py` and `sudo_session.py` (`3.2.0-F13`). Probes use `run.capture` (missing binary → `None`) or `run.probe` (missing binary → status 127), raise-on-failure calls use `run_or_raise`, and escalation uses the §22 privilege seam. A call that legitimately stays raw (inherits the TTY, streams, needs its own `preexec_fn`, or is a privileged command whose status or `CalledProcessError` its caller inspects) carries `# noqa: TID251 — <why>`, and the reason is mandatory. Enforced by the ruff rule plus `tests/test_standards_compliance.py` (`test_subprocess_fence_*`), which pins the banned set, the exemption list and the per-call reasons. Complements row 17, which governs argv form; this row governs *where* the call is made. |
-| 32 | Machine-readable output contract (`--json`) | `state list --json`, `doctor` (`system`, `pkg`, bare) `--json`, `update --dry-run --json` | enforced | `primitives/json_out.py` is the one home (`3.4.0-F7`). Stdout carries exactly one JSON document ([RFC 8259](https://www.rfc-editor.org/rfc/rfc8259)) and nothing else: `cli.main` enters `json_out.reserved_stdout()` right after parsing and `verbs.runner.run_verb` enters it again (re-entrant), so every `ui()`/`print()`, startup logs and progress phases included, goes to stderr; the document goes out through `json_out.emit`. Every document has a top-level `"schema"` integer (`SCHEMA_VERSION`, now 1) and a `"kind"` (`state-list`, `doctor`, `update-dry-run`). **Adding a field is a minor change; renaming or removing one, or changing its type, is a major change and bumps `SCHEMA_VERSION`.** Each document is built from the result objects the human renderer reads (`AxisResult` via `diagnostics.axis_document`, `run.results` and the drift lists via `update._dry_run_document`, build_state rows through an explicit field list in `state_cmd._JSON_ENTRY_FIELDS`), so the two outputs cannot disagree. Exit codes are unchanged by `--json`. Mutating runs are out of scope: `update --json` without `--dry-run` and `doctor pkg --apply --json` are refused (exit 2). The schemas are committed as JSON Schema draft 2020-12 under `tests/data/json-schema/`; `tests/test_json_output.py` validates each verb's document against its schema (a subset validator, so the suite needs no new dependency), checks that stdout parses as one document with `log` in dry-run mode at `-vv`, and that a doctor skip appears under `roster.skipped`, never as a finding. A new field updates its schema in the same change. |
+| 32 | Machine-readable output contract (`--json`) | `state list --json`, `doctor` (`system`, `pkg`, bare) `--json`, `update --dry-run --json`, `config check --json` (`3.5.0-F18`) | enforced | `primitives/json_out.py` is the one home (`3.4.0-F7`). Stdout carries exactly one JSON document ([RFC 8259](https://www.rfc-editor.org/rfc/rfc8259)) and nothing else: `cli.main` enters `json_out.reserved_stdout()` right after parsing and `verbs.runner.run_verb` enters it again (re-entrant), so every `ui()`/`print()`, startup logs and progress phases included, goes to stderr; the document goes out through `json_out.emit`. Every document has a top-level `"schema"` integer (`SCHEMA_VERSION`, now 1) and a `"kind"` (`state-list`, `doctor`, `update-dry-run`). **Adding a field is a minor change; renaming or removing one, or changing its type, is a major change and bumps `SCHEMA_VERSION`.** Each document is built from the result objects the human renderer reads (`AxisResult` via `diagnostics.axis_document`, `run.results` and the drift lists via `update._dry_run_document`, build_state rows through an explicit field list in `state_cmd._JSON_ENTRY_FIELDS`), so the two outputs cannot disagree. Exit codes are unchanged by `--json`. Mutating runs are out of scope: `update --json` without `--dry-run` and `doctor pkg --apply --json` are refused (exit 2). The schemas are committed as JSON Schema draft 2020-12 under `tests/data/json-schema/`; `tests/test_json_output.py` validates each verb's document against its schema (a subset validator, so the suite needs no new dependency), checks that stdout parses as one document with `log` in dry-run mode at `-vv`, and that a doctor skip appears under `roster.skipped`, never as a finding. A new field updates its schema in the same change. |
 
 ### Notes on selected standards
 
diff --git a/docs/design/verbs/doctor.md b/docs/design/verbs/doctor.md
index 1e4cc0c5..a6ede1b7 100644
--- a/docs/design/verbs/doctor.md
+++ b/docs/design/verbs/doctor.md
@@ -4,7 +4,7 @@ Implements `sysforge doctor` — the unified diagnostic front-end for sysforge-m
 
 **Two scopes (`system` / `pkg`).** The surface is split into `sysforge doctor system [AXIS…]` and `sysforge doctor pkg [TARGETS] [AXIS…]`. Bare `sysforge doctor` is `doctor system` — unchanged as the everyday full sweep. The split exists because a single `PKG` positional previously meant three different things (a walk target, a scope qualifier for `rust`/`integrity`, and — via `--graphics` — a target *injector*), none of which `--help` distinguished. Two rules apply identically at both scopes:
 
-1. **No axis flag → that scope's defaults.** `doctor system` runs the 13 non-opt-in axes; `doctor pkg mesa` runs `abi + rust + integrity` scoped to mesa. The opt-in axes are included at package scope because their cost is a whole-system scan, not a per-package one.
+1. **No axis flag → that scope's defaults.** `doctor system` runs the 14 non-opt-in axes; `doctor pkg mesa` runs `abi + rust + integrity` scoped to mesa. The opt-in axes are included at package scope because their cost is a whole-system scan, not a per-package one.
 2. **A broad target selector suppresses the opt-ins.** `doctor pkg --all` / `--repo` runs `--abi` only; name an opt-in axis explicitly to override. This reuses the existing `_OPT_IN_AXES` frozenset rather than introducing a second policy. `--graphics` is *not* a broad selector for this purpose — it expands to ~15 curated packages, not the whole system.
 
 So `doctor pkg cosmic-comp-git --rust` means exactly one thing: the rust axis, that package, no linkage walk.
@@ -48,6 +48,8 @@ Per-package group headers and the final summary both tag each package with its i
 
 `--pacman` runs a pacman / system-integrity axis (`primitives/system_probe.py::collect_system_findings`) — all read-only against the *local* database (never `-Sy`): `pacman -Dk` local-db dependency consistency (missing deps → `error`), a lingering `/var/lib/pacman/db.lck` from an interrupted transaction (`warn`), unmerged `*.pacnew`/`*.pacsave` config files under `/etc` (`warn`), and `pacman -Qtdq` true orphans (`info`). Two size/freshness checks join the same axis: **package-cache size** (`_check_pkg_cache`, F15) sums the `.pkg.tar*` archives in the pacman cache dirs resolved via `pacman.get_pacman_cache_dirs()` (never hardcoding `/var/cache/pacman/pkg`) and `warn`s over `[doctor] pkg_cache_warn_gb` (default 5 GB) with `paccache` remediation — distinct from `cache_probe`, which reports *build* caches (ccache/sccache); and **mirrorlist freshness** (`_check_mirror_freshness`, F16) `warn`s when `/etc/pacman.d/mirrorlist`'s mtime age exceeds `[doctor] mirrorlist_stale_days` (default 14) — file-age only, never a live latency probe. It also folds in **sysforge libalpm-hook drift** (`doctor._collect_hook_findings` over `primitives/pacman_hooks.diff_status`): each shipped hook/helper that is missing from or stale against the canonical source emits a `warn` with remediation `run \`sysforge setup\``. Read-only — `diff_status` only reads. Standalone (`sysforge doctor --pacman`).
 
+`--config` (`3.5.0-F18`) inspects the live config files through `config_schema.inspect` (the report `sysforge config check` prints): a file that does not parse is an error, a retired or unknown setting a warning whose remediation is `sysforge config clean` (with `--unknown` for an unknown one). Read-only, and in the default sweep.
+
 `--state` runs a sysforge state-integrity axis (`primitives/state_probe.py::collect_state_findings`) — read-only inspection of sysforge's *own* persisted state: recorded build failures from `build_state.toml`'s `[failures]` table (each `warn`, surfacing the `build_diag` signature + `fix_cmd` when present; a package removed since the last reconcile is dropped in memory via `install_reconcile.clear_removed_failures`, never saved, `3.5.0-B120`), an interrupted stage sentinel via `StageSentinel.get_active()` (`error`, carrying the recorded `recovery_cmd` — it does **not** call the recovering `check_and_recover_stale_sentinel`), and build-state drift vs the live pacman db (`info`, zombie entries for uninstalled packages). It also flags **live record-stage PGO builds** (`_check_instrumented_builds`, F14): for each tracked package it resolves the PGO store (`mesa_pgo.resolve_store`) and `warn`s when a bare `.profraw` is present with **no** merged `.profdata` — an instrumented, unoptimized build left live — pointing at `sysforge build <pkg> --pgo=use` or a repo rollback. Detection is provenance-only (never inspects a binary); a package that never used `--pgo` has no store and is silently skipped. The last source-sync `STATUS_*` is intentionally *not* surfaced: the source-sync scheduler cache is per-process, so a standalone `doctor` run has no sync results. Standalone (`sysforge doctor --state`).
 
 `--boot` runs a boot/kernel-runtime axis (`doctor._collect_boot_findings`, reusing `primitives/kernel_safety`) — the running-system analog of the kernel stage's gates 1/3: per-bootable-kernel boot-artifact verification (`verify_boot_artifacts`: vmlinuz + initramfs + a boot entry; gaps are brick-class `is_brick` → exit code), a recovery-fallback check (`find_fallback_kernels`; only one bootable kernel → `info`), `/boot` free space (`check_boot_mount_space`), and DKMS modules for the running kernel (`check_dkms_for_kernel(running_kernel_release())`; these `dkms:*` findings carry the running-kernel reboot caveat, while the filesystem-live boot-artifact / `/boot`-space findings do not). The running-kernel `.config` device audit stays in `--hardware` (it is device-driver coverage, distinct from boot-artifact readiness), so there is no double-report. Standalone (`sysforge doctor --boot`).
diff --git a/docs/release-notes/unreleased.md b/docs/release-notes/unreleased.md
index 2ad9b887..d80695bb 100644
--- a/docs/release-notes/unreleased.md
+++ b/docs/release-notes/unreleased.md
@@ -98,6 +98,11 @@ https://keepachangelog.com/en/1.1.0/
 ---
 
 - **`3.5.0-F14` — choose a package's toolchain when you build it, and keep it.** `sysforge build PKG --toolchain gcc` (or `llvm`) builds the packages you name with that toolchain as a whole: compilers, `ar`/`nm`/`ranlib`/`strip` and linker together, the same swap the build-failure menu makes. Before, the only CLI choice was `--cc`/`--cxx`, which changed just the two compilers and left an LLVM profile's `llvm-ar` and `lld` in place. A `--cc gcc --cxx g++` or `--cc clang --cxx clang++` pair now does the same as `--toolchain`; any other pair still sets only the compilers, for a compiler sysforge does not bundle. Add `--save-toolchain` to keep the choice for those packages in `profiles.toml`, so later builds and `update` use it, without waiting for a build to fail first; `--reset-toolchain` removes it again. Dependencies built along the way keep their own profile. `run kernel` takes the same option under the same name (it was `--compiler`; see `3.5.0-F15`).
+
+---
+
+- **`3.5.0-F18` — find and fix retired or misspelt settings in your config files.** An upgrade never rewrites your config files, so a setting sysforge stopped reading stayed there, silently ignored, and a misspelt key was never reported. `sysforge config check` lists both, with the line (`--json` prints them as one JSON document for scripts): settings sysforge renamed or retired (such as `[git] pull_timeout`, the per-package `pkgbuild_patch`, `repo_mode = "profiled"` and `build_mode = "patched_pkgbuild"`) and keys it does not know. `sysforge config clean` gives retired settings their current name or value, keeping your comments, and with `--unknown` removes the unknown ones. `sysforge config reset FILE [KEY ...]` puts keys back to the shipped default, or the whole file, keeping the old one as `FILE.bak-<time>`. Both show the change first and ask (or take `--yes`; `--dry-run` only shows it). `sysforge doctor system --config`, part of the default sweep, reports the same findings. The shipped defaults are now installed with the package for this, and `toolchain.toml` documents `profile_store` and `profiles.toml` documents `extends_system`, both read but listed nowhere. A test keeps every setting sysforge reads documented in the shipped files, so `config check` never calls a working setting unknown.
+
 ## Changed
 
 - **`3.0.0-F3` — `update` no longer builds a changed source nobody looked at.** The PKGBUILD review gate, which diffs a package's whole source tree since the last build you accepted, used to accept every change during `update` with a logged line, and accepted silently whenever there was no terminal, so a timer-driven `update` built and installed whatever had arrived. Now a changed source is shown to you at a terminal (view, accept, skip or abort, as `--review` did), and with no terminal (a timer, cron, a pipe) that package is refused: the rest of the run still builds, the summary lists it under "Refused at review" and the run exits 1. Changes from Arch's own packaging repos are accepted with a logged line, since the same people publish the binary packages you already install; `[build] review_trusted_sources` in `packages.toml` changes that list, and `--review` reviews everything. `build` and the toolchain stage's rebuild of libLLVM consumers follow the same rules, and `build` gains `--review`. To keep the old unattended behaviour, set `[build] review = "accept"` (every accepted change is still listed in the summary) or pass `--no-review`. The config comment explains the risk: a build sandbox limits what a build can read, but it does not inspect what gets installed.
@@ -172,7 +177,27 @@ https://keepachangelog.com/en/1.1.0/
 
 ---
 
-- **`3.5.0-DEV13` — tests build real options and arguments, not stand-ins.** A `SimpleNamespace` standing in for `BuildOptions`, `RunOptions` or a parsed command line broke whole test files each time the code read a new field, and would keep passing on a renamed one. A new test refuses options stand-ins outright (the last three are converted) and keeps the 31 older argument stand-ins from growing: each file's count may only go down. The root CLAUDE.md now says to build `BuildOptions(...)`, `RunOptions(...)` or `build_parser().parse_args([...])`, and to add every removed name to `tools/retired_names.toml`.
+- **`3.5.0-DEV13` — tests build real options and arguments, not stand-ins.** A `SimpleNamespace` standing in for `BuildOptions`, `RunOptions` or a parsed command line broke whole test files each time the code read a new field, and would keep passing on a renamed one. A new test refuses them, and every test now builds a real `BuildOptions`, `RunOptions` or parsed command line (the last through a small `cli_args` helper), with no exceptions left: the last stand-in tested a fallback no caller needed, and both are gone. Converting them found a real bug (`3.5.0-B129`) and tests of `--dry-run` on two commands that have no such flag. The root CLAUDE.md now says to build `BuildOptions(...)`, `RunOptions(...)` or `build_parser().parse_args([...])`, and to add every removed name to `tools/retired_names.toml`.
+
+---
+
+- **`3.5.0-DEV14` — completions are checked command by command.** `make check-shipped` gains a `completion_commands` group. The old check looked only at top-level commands, so once group commands such as `state` and `run` stopped taking flags of their own, none of their subcommands' flags were checked, and a flag counted as present if it appeared anywhere in the file. Now each command's flags must be offered where that command is completed, in both zsh and bash; no flag the command lacks may be offered; every value a flag accepts must be offered; and lists copied from the code (desktops, profile-store methods) must match it.
+
+---
+
+- **`3.5.0-DEV15` — citations in the design docs and the Claude Code agents are checked.** The check that every file, module symbol and script CLAUDE.md cites still exists now covers the design docs and the agents, skills and rules under `.claude/`, and checks `make` targets too. It found and fixed a design passage on the prompt helpers that named a removed stage file and a removed function and gave call counts that were all wrong, a symbol cited under the wrong module, `make vm-install` (now `vm-install-stable`), and an agent and a skill citing files that no longer exist. A code name cited without its module must also exist somewhere in the code: that found 48 functions the design docs still called by names they lost in an earlier reorganization, a reconfigure prompt that changed, and a cache-invalidation setting the docs described but sysforge never had.
+
+---
+
+- **`3.5.0-DEV16` — the concept pages' rules are tested.** Each concept page must close with *Further reading*, citing at least one upstream source, then *In sysforge*, and must not use sysforge's own terms before that last section. The rule was in CLAUDE.md only; every page already followed it.
+
+---
+
+- **`3.5.0-DEV17` — a test that every flag reaches the code that uses it.** `run kernel --keep-hotplug-drivers` (`3.5.0-B129`) was read by the stage from an options object that never had the field, so the read always returned its default. Any such read now fails a test, as does a command flag that nothing reads. Both pass on today's code; the first would have caught B129.
+
+---
+
+- **`3.5.0-DEV18` — every user-facing change is recorded where reviewers look.** `tests/data/surface.json` is a generated list of everything a user can type, set or parse: commands and their flags and values, environment variables, journal fields, config keys, `--json` fields and log names. `make check-surface` fails when it is out of date, when something was added or removed without a release note naming it, or when a name disappears without being registered as retired. CI now blocks a merge on any failing check, `CONTRIBUTING.md` lists what to update for each kind of change, pull requests get a checklist, and `make install-hooks` adds an optional pre-commit hook running the fast checks.
 
 ---
 
@@ -224,6 +249,10 @@ https://keepachangelog.com/en/1.1.0/
 
 ---
 
+- **`3.5.0-DOC13` — the man page documents the journal records.** Commands that change installed packages or build state write a record to the systemd journal, queryable by field, but no user document said so. A new JOURNAL section names the fields (`SYSFORGE_VERB`, `SYSFORGE_TARGET`, `SYSFORGE_EXIT`), which commands write them, and two `journalctl` queries; it is generated from the field list the records are built from.
+
+---
+
 - **`3.5.0-F2` — `run toolchain` builds the LLVM toolchain from upstream's single `llvm` package.** The repos now build clang, lld, polly, compiler-rt and openmp, along with lldb, libclc and others, as part of the `llvm` package. With PGO on, the whole set now goes through the profiling build together, which also means clang's own code (`libclang-cpp`) is optimized with the profile for the first time; before, only libLLVM was. Building them separately would have meant building the entire llvm source tree two extra times. When it installs, the toolchain stage now also replaces the other packages that come from the same build and that you already have installed (for example lldb and libclc), so they match the new libLLVM, and the rollback covers them too. Packages from that build you never installed, such as the WebAssembly runtimes, are built but not installed. Your `[packages]` lists in `toolchain.toml` keep working unchanged.
 
 ---
@@ -759,6 +788,18 @@ https://keepachangelog.com/en/1.1.0/
 
 - **`3.5.0-B126` — A kernel built with the other compiler is recorded as such, and stops warning about it.** `run kernel` recorded the system toolchain's variant whatever compiler built the kernel, so a kernel kept on gcc (`compiler = "gcc"` in `kernel.toml`, or `--toolchain gcc`) on an LLVM system was recorded as `pgo_llvm`. The record now names the compiler that built it, as `3.5.0-B125` does for other packages. The kernel stage's "Rebuilding will switch toolchains" warning now compares the record with the compiler this run will use rather than the system one, so it appears only when the kernel's compiler actually changes, and it names that compiler.
 
+---
+
+- **`3.5.0-B127` — bash completes the values of `run toolchain --rebuild-soname-consumers`.** zsh offered `prompt`, `auto` and `off` after the flag; bash offered nothing. It now offers the same three.
+
+---
+
+- **`3.5.0-B128` — the man page lists every environment variable sysforge reads.** Its ENVIRONMENT section named three of eleven. Now it also covers `SYSFORGE_MERGE` (the merge tool for `config merge`), `SYSFORGE_ASCII` (ASCII in place of decorative glyphs), `SYSFORGE_PGO_STORE` and `SYSFORGE_PROFILE_STORE` (where profiles are kept, the second documented nowhere before), and three diagnostic switches for bug reports. The `SYSFORGE_EDITOR` entry now gives the whole lookup order, which includes `sysforge.toml [ui] editor`, and the pager entry the right fallback flags. The section is generated from one list in the code, and a test fails on a variable missing from it.
+
+---
+
+- **`3.5.0-B129` — `run kernel --keep-hotplug-drivers` takes effect.** The flag and its `--no-` form were accepted and then dropped before the kernel stage read them, so the stage always used `kernel.toml`'s `keep_hotplug_drivers`. They now override it, as their help says. A new test checks that every flag of every `run` stage reaches the stage.
+
 ## Security
 
 - **`3.5.0-B37` — the root pacman hook no longer follows links in the state directory.** The hook helper runs as root in every pacman transaction and wrote into `/var/lib/sysforge/sentinels`, whose parent any `sysforge` group member can write to. A member could swap `sentinels` for a symlink to another directory, which the next transaction made group-writable, or symlink one of its files so the hook appended to any file as root. The helper now enters the directory and acts only if it is the real `sentinels`, owned by root. It appends only to a regular file, opened so that a symlink is refused and a planted FIFO cannot stall the transaction. As before, it never fails a transaction.
diff --git a/etc/sysforge/profiles.toml b/etc/sysforge/profiles.toml
index e1af9505..ef112156 100644
--- a/etc/sysforge/profiles.toml
+++ b/etc/sysforge/profiles.toml
@@ -224,6 +224,11 @@
 #
 # ============================== END OF HEADER ================================
 
+# extends_system — only in a user file (~/.config/sysforge/profiles.toml):
+#   true merges it onto this system file (its rules ranked above the system's)
+#   instead of replacing the system file outright.
+# extends_system = true
+
 [paths]
 pkgbuild_src_dir = "~/src"
 
diff --git a/etc/sysforge/toolchain.toml b/etc/sysforge/toolchain.toml
index 54d776a2..f896a7f2 100644
--- a/etc/sysforge/toolchain.toml
+++ b/etc/sysforge/toolchain.toml
@@ -82,6 +82,11 @@ drift_detect = "fingerprint"
 #   major) skips passes 1-3. Use --rebuild-profdata to force a full 4-pass
 #   build. Needs ~500 MB free during pass 3.
 #pgo_store = "/var/cache/sysforge/llvm-pgo"
+#
+# profile_store — root directory of the other profile stores: build --pgo's
+#   pgo/<pkgbase>, the kernel's autofdo/ and propeller/, and bolt/. Overridden
+#   by SYSFORGE_PROFILE_STORE when unset here.
+#profile_store = "/var/cache/sysforge"
 
 # ---------------------------------------------------------------------------
 # Build-safety gates (LLVM path only — the GCC path is register-only and skips
diff --git a/man/sysforge.1 b/man/sysforge.1
index 131b3807..ea9b1eeb 100644
--- a/man/sysforge.1
+++ b/man/sysforge.1
@@ -5,7 +5,7 @@
 .nh
 .ad l
 .\" Begin generated content:
-.TH "sysforge" "1" "2026\-10\-21"
+.TH "sysforge" "1" "2026\-10\-22"
 .PP
 .PP
 .SH NAME
@@ -157,6 +157,12 @@ Like \-\-cleansrc but bypasses the dirty/diverged guard and overwrites the local
 Used by: \fBbuild\fR, \fBupdate\fR, \fBfetch\fR, \fBrun toolchain\fR, \fBrun kernel\fR.\&
 .PP
 .RE
+\fB\-\-config\-dir\fR \fIDIR\fR
+.RS 4
+Live config dir (default: $SYSFORGE_CONFIG_DIR, else /etc/sysforge).\&
+Used by: \fBconfig check\fR, \fBconfig clean\fR, \fBconfig reset\fR.\&
+.PP
+.RE
 \fB\-\-dry\-run\fR
 .RS 4
 Show what would run without executing anything.\&
@@ -223,6 +229,12 @@ Override state directory.\&
 Used by: \fBbuild\fR, \fBupdate\fR, \fBstate list\fR, \fBstate repair\fR, \fBstate failed\fR, \fBstate forget\fR, \fBrun pipeline\fR, \fBrun hardware\fR, \fBrun reconfigure\fR, \fBrun toolchain\fR, \fBrun packages\fR, \fBrun kernel\fR, \fBrevert\-to\-stock\fR, \fBuninstall\fR.\&
 .PP
 .RE
+\fB\-\-yes\fR
+.RS 4
+Write without asking (needed without a terminal).\&
+Used by: \fBconfig clean\fR, \fBconfig reset\fR.\&
+.PP
+.RE
 .SH COMMANDS
 .PP
 .SS build
@@ -537,7 +549,7 @@ Diagnose system health (`doctor system`) or package health (`doctor pkg`).\& Bar
 .PP
 \fBsysforge doctor system\fR [\fIOPTIONS\fR]
 .PP
-System\-state axes: toolchain, cache, hardware, graphics, pacman, state, boot, restart, storage, services, audio, network, distro.\& With no axis flag, runs all 13 non\-opt\-in axes.\&
+System\-state axes: toolchain, cache, hardware, graphics, pacman, state, config, boot, restart, storage, services, audio, network, distro.\& With no axis flag, runs all 14 non\-opt\-in axes.\&
 .PP
 \fB\-\-graphics\fR
 .RS 4
@@ -584,6 +596,11 @@ Check local package\-database integrity (read\-only, never syncs): `pacman \-Dk`
 Check sysforge'\&s own state integrity: recorded build failures, an interrupted stage sentinel from a prior run, and build_state drift vs the live pacman database.\& Read\-only (does not recover).\&
 .PP
 .RE
+\fB\-\-config\fR
+.RS 4
+Check the live config files for settings sysforge retired or does not know (the same report as `sysforge config check`).\&
+.PP
+.RE
 \fB\-\-boot\fR
 .RS 4
 Check running\-system boot readiness (reusing the kernel stage'\&s safety primitives): per\-kernel boot artifacts (vmlinuz + initramfs + boot entry), a recovery fallback kernel, /boot space, and DKMS modules for the running kernel.\&
@@ -1047,7 +1064,61 @@ Apply a config preset without asking: defaults, performance (faster binaries), l
 .PP
 \fBsysforge config\fR \fISUBCOMMAND\fR
 .PP
-Manage live sysforge config files (adopt shipped\-default drift).\&
+Check, clean or reset the live sysforge config files, or merge shipped\-default changes into them.\&
+.PP
+.SS config check
+.PP
+\fBsysforge config check\fR [\fIOPTIONS\fR]
+.PP
+Report settings in the live config files that sysforge retired (renamed keys, refused values) or does not know (misspelt or no longer used).\& Exits 1 when it finds any.\&
+.PP
+\fB\-\-json\fR
+.RS 4
+Print one JSON document (schema 1) on stdout instead of the report; the exit code is unchanged.\&
+.PP
+.RE
+\fBShared options:\fR \fB\-\-config\-dir\fR (see SHARED OPTIONS)
+.PP
+.SS config clean
+.PP
+\fBsysforge config clean\fR [\fIOPTIONS\fR]
+.PP
+Rewrite retired settings in the live config files: a renamed key takes its new name (or is dropped when the new one is already set), a retired value its replacement.\& Comments are kept.\& Shows the diff and asks first.\&
+.PP
+\fB\-\-unknown\fR
+.RS 4
+Also remove settings sysforge does not know (see `config check`).\&
+.PP
+.RE
+\fB\-\-dry\-run\fR
+.RS 4
+Show the diff without writing anything.\&
+.PP
+.RE
+\fBShared options:\fR \fB\-\-config\-dir\fR, \fB\-\-yes\fR (see SHARED OPTIONS)
+.PP
+.SS config reset
+.PP
+\fBsysforge config reset\fR [\fIOPTIONS\fR] \fIFILE\fR \fI[KEY.\&.\&.\&]\fR
+.PP
+Put settings back to the shipped default: each KEY given as SECTION.\&KEY (or KEY for a top\-level one), or with no KEY the whole FILE, keeping the current one as FILE.\&bak\-<time>.\& Shows the diff and asks first.\&
+.PP
+\fBFILE\fR
+.RS 4
+Config file to reset (sysforge.\&toml, profiles.\&toml, packages.\&toml, kernel.\&toml or toolchain.\&toml).\&
+.PP
+.RE
+\fBKEY\fR
+.RS 4
+Keys to reset, such as build.\&jobs; omit to reset the whole file.\&
+.PP
+.RE
+\fB\-\-dry\-run\fR
+.RS 4
+Show the diff without writing anything.\&
+.PP
+.RE
+\fBShared options:\fR \fB\-\-config\-dir\fR, \fB\-\-yes\fR (see SHARED OPTIONS)
 .PP
 .SS config merge
 .PP
@@ -1515,16 +1586,91 @@ FILES).\&
 .RE
 SYSFORGE_EDITOR
 .RS 4
-Editor for the interactive config review in \fBrun reconfigure\fR.\&
-Falls back to $EDITOR, then $VISUAL.\&
+Editor sysforge opens: \fBrun reconfigure\fR'\&s config review,
+\fBartifact edit\fR and \fBconfig merge\fR.\& Checked first, then
+sysforge.\&toml [ui] editor, $EDITOR and $VISUAL.\&
+.PP
+.RE
+SYSFORGE_MERGE
+.RS 4
+Merge tool for \fBconfig merge\fR.\& Checked first, then sysforge.\&toml [ui] merge, $DIFFPROG, then vimdiff.\&
+.PP
+.RE
+SYSFORGE_ASCII
+.RS 4
+Any non\-empty value prints ASCII in place of decorative glyphs
+(arrows, bullets, progress fills), for terminals and fonts without
+them.\&
+.PP
+.RE
+SYSFORGE_PGO_STORE
+.RS 4
+Directory for the toolchain'\&s PGO profiles, used when
+toolchain.\&toml sets no pgo_store.\&
+.PP
+.RE
+SYSFORGE_PROFILE_STORE
+.RS 4
+Root directory of every other profile store (pgo/<pkgbase>,
+autofdo, propeller, bolt), used when toolchain.\&toml sets no
+profile_store.\&
 .PP
 .RE
 PAGER
 .RS 4
 Pager for \fBsysforge log\fR, \fBstate\fR listings, and PKGBUILD review
-diffs in \fBbuild\fR/\fBupdate\fR (falls back to less \-RFX, then more).\&
+diffs in \fBbuild\fR/\fBupdate\fR (falls back to less \-RF, then more).\&
+.PP
+.RE
+SYSFORGE_PTY_RAW_DUMP (diagnostic)
+.RS 4
+A file path: every byte a build writes to its terminal is appended
+there, after a line giving the terminal size sysforge handed it.\&
+For reports about garbled build output.\&
+.PP
+.RE
+SYSFORGE_PROGRESS_TRACE (diagnostic)
+.RS 4
+A file path: the progress bar logs each repaint, resize and
+handover there.\& For reports about the progress bar.\&
+.PP
+.RE
+SYSFORGE_PACMAN_NO_PYALPM (diagnostic)
+.RS 4
+Any non\-empty value makes sysforge query pacman through the pacman
+command rather than pyalpm, to tell a pyalpm problem from a
+sysforge one.\&
 .PP
 .RE
+.SH JOURNAL
+.PP
+Commands that change installed packages or build state (\fBbuild\fR, \fBupdate\fR,
+\fBrevert\-to\-stock\fR, \fBuninstall\fR, \fBartifact deploy\fR/\fBremove\fR, \fBstate
+repair\fR/\fBforget\fR) write one record to the systemd journal when they finish, with SYSLOG_IDENTIFIER=sysforge and these
+fields, so runs can be queried rather than grepped:
+.PP
+SYSFORGE_VERB
+.RS 4
+The command, with spaces as dashes for subcommands (build, update,
+state\-forget, artifact\-deploy).\&
+.PP
+.RE
+SYSFORGE_TARGET
+.RS 4
+What it acted on, when it has a subject: pkg:<names> for packages
+(space\-separated), mode:<name> for a state operation.\& Absent
+otherwise.\&
+.PP
+.RE
+SYSFORGE_EXIT
+.RS 4
+The exit status.\& Records of a failed run are also logged at
+PRIORITY=3 (err), the others at 6 (info).\&
+.PP
+.RE
+For example, \fBjournalctl SYSFORGE_VERB=update\fR lists every update, and
+\fBjournalctl SYSLOG_IDENTIFIER=sysforge PRIORITY=3\fR the failed runs.\&
+.PP
 .SH DISTRIBUTIONS
 .PP
 SysForge assumes \fBpacman\fR(8) and \fBmakepkg\fR(8), and nothing narrower.\& It has no
diff --git a/man/sysforge.1.scd.in b/man/sysforge.1.scd.in
index 2fbd5b91..31321b3c 100644
--- a/man/sysforge.1.scd.in
+++ b/man/sysforge.1.scd.in
@@ -163,23 +163,19 @@ bench.toml (under the state directory)
 
 # ENVIRONMENT
 
-SYSFORGE_STATE_DIR
-	Override the state directory (stage progress, build_state.toml,
-	logs, sentinels). Read by every command that touches build state:
-	*build*, *update*, *state*, *log*, *doctor*, and the *run* stages.
-
-SYSFORGE_CONFIG_DIR
-	Override the configuration directory searched before
-	/etc/sysforge. Read by every command that loads a config file (see
-	FILES).
-
-SYSFORGE_EDITOR
-	Editor for the interactive config review in *run reconfigure*.
-	Falls back to $EDITOR, then $VISUAL.
-
-PAGER
-	Pager for *sysforge log*, *state* listings, and PKGBUILD review
-	diffs in *build*/*update* (falls back to less -RFX, then more).
+@ENVIRONMENT@
+
+# JOURNAL
+
+Commands that change installed packages or build state (*build*, *update*,
+*revert-to-stock*, *uninstall*, *artifact deploy*/*remove*, *state
+repair*/*forget*) write one record to the systemd journal when they finish, with SYSLOG_IDENTIFIER=sysforge and these
+fields, so runs can be queried rather than grepped:
+
+@JOURNAL@
+
+For example, *journalctl SYSFORGE_VERB=update* lists every update, and
+*journalctl SYSLOG_IDENTIFIER=sysforge PRIORITY=3* the failed runs.
 
 # DISTRIBUTIONS
 
diff --git a/pyproject.toml b/pyproject.toml
index 7d60b9a8..1dc1f339 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -35,6 +35,9 @@ packages = ["sysforge"]
 [tool.hatch.build.targets.wheel.force-include]
 "etc/pacman.d/hooks" = "sysforge/_data/pacman-hooks"
 "tools/pacman-hook-helper.sh" = "sysforge/_data/pacman-hook-helper.sh"
+# Pristine shipped configs, for `sysforge config check/reset` (3.5.0-F18): the
+# copies under /etc/sysforge are the user's, kept across upgrades by backup=().
+"etc/sysforge" = "sysforge/_data/config-defaults"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
diff --git a/sysforge/CLAUDE.md b/sysforge/CLAUDE.md
index d01e3ff4..9c602fc7 100644
--- a/sysforge/CLAUDE.md
+++ b/sysforge/CLAUDE.md
@@ -179,6 +179,10 @@ Mechanism lives in the cited §DESIGN section.
   A pair's jump-size tint is `version_pair(..., classify=True)` (`3.4.0-F8`, order via the pure
   `version.vercmp_local`); only on a `ui()`/`print()` line, never in text that can reach `error()`.
 - **LLVM source-state**: `llvm_state.collect_llvm_state` — don't call `git_is_dirty`+URL-parse.
+- **Live-config schema and repair**: `primitives/config_schema.py` (`KNOWN_SECTIONS`/`KNOWN_TOP_KEYS`,
+  `OPEN_SECTIONS`, `RETIRED_KEYS`/`RETIRED_VALUES`, `shipped_text`, `inspect`, `clean_text`,
+  `reset_keys_text`); `tools/check_shipped.py` imports its schema. A retired config key or value
+  gets a row there in the same change; a new key is valid once the shipped default documents it.
 - **Editor/merge-tool launch**: `primitives/editor.py` (`resolve_editor`, `resolve_merge_tool`,
   `run_tty_argv`); `.sfnew` adoption in `config_cmd.ConfigMergeVerb`. §Config Layer.
 - **Dir/group provisioning**: `primitives/fs_provision.py` (`root:sysforge` setgid 2775); `/etc/
@@ -254,7 +258,7 @@ Mechanism lives in the cited §DESIGN section.
 - **Pass-3 builds non-pgo against the libLLVM it ships** (`CMAKE_PREFIX_PATH` **and** forced
   `-DLLVM_DIR` via `patch_llvm_dir`; staging3 needs both `llvm-libs`+`llvm`). Build reuse opt-in via
   `build_fingerprint.py` (`--reuse-built`, fail-safe to rebuild; bump `_SCHEMA` on new inputs).
-- **Pass-2 training corpus**: `_resolve_training_corpus`; extras (mesa) compile with the instrumented
+- **Pass-2 training corpus**: `resolve_training_corpus`; extras (mesa) compile with the instrumented
   stage1 clang so profraw merges into the one `clang.profdata` — never installed, never
   `-fprofile-use` (`pgo_reuse=False`), no profile-runtime force-load. Best-effort, but
   `BuildAborted` (user abort) re-raises. PGO path only.
diff --git a/sysforge/build_core.py b/sysforge/build_core.py
index 4fb6edd3..65ec46b1 100644
--- a/sysforge/build_core.py
+++ b/sysforge/build_core.py
@@ -700,8 +700,9 @@ def make_build_options(stage: str, options, **overrides):
 
     This centralizes the three install-bearing stages' (``kernel`` /
     ``toolchain`` / ``packages``) hand-assembly so a stage-wide default lives in
-    exactly one place. ``abi_check`` is read via ``getattr`` so a run-options
-    object without the attribute degrades to ``False`` rather than raising.
+    exactly one place. Every caller passes its stage's ``RunOptions``, so each
+    field is read directly: a ``getattr`` default here would hide a renamed
+    field behind a silent ``False`` (the shape of 3.5.0-B129).
     """
     from sysforge.build.makepkg_wrapper import BuildOptions
 
@@ -711,7 +712,7 @@ def make_build_options(stage: str, options, **overrides):
         "pkg_log": not options.no_pkg_log,
         "persist_log": options.persist_log,
         "state_dir": options.state_dir,
-        "abi_check": getattr(options, "abi_check", False),
+        "abi_check": options.abi_check,
     }
     fields.update(_STAGE_BUILD_DEFAULTS[stage])
     fields.update(overrides)
diff --git a/sysforge/config_cmd.py b/sysforge/config_cmd.py
index 6cd1c1d3..0ef485ba 100644
--- a/sysforge/config_cmd.py
+++ b/sysforge/config_cmd.py
@@ -3,7 +3,14 @@
 # SPDX-License-Identifier: MIT
 
 """
-config_cmd.py — `sysforge config merge` verb: interactive .sfnew adoption.
+config_cmd.py — `sysforge config` verbs: check, clean, reset (3.5.0-F18) and
+merge (interactive .sfnew adoption).
+
+`check` reports settings sysforge retired or does not know, `clean` rewrites
+the retired ones (and with ``--unknown`` removes the unknown), and `reset` puts
+keys, or a whole file, back to the shipped default. The schema and the edits
+are primitives/config_schema.py; this module adds the reporting, the diff and
+the consent. The rest of this docstring is about `merge`.
 
 `make sync-config` adopts new shipped config defaults into the live config dir
 via an add-only, key-anchored merge (tools/sync_config.py), but it cannot carry
@@ -22,18 +29,20 @@
 default action.
 
 Public API:
+    cmd_config_check(args), cmd_config_clean(args), cmd_config_reset(args)
     cmd_config_merge(args)
-    ConfigMergeVerb
+    ConfigCheckVerb, ConfigCleanVerb, ConfigResetVerb, ConfigMergeVerb
 """
 from __future__ import annotations
 
 import difflib
 import re
 import shutil
+import time
 from pathlib import Path
 
 from sysforge import log
-from sysforge.primitives import paths
+from sysforge.primitives import atomic_write, config_schema, json_out, paths, prompt
 from sysforge.primitives.editor import resolve_merge_tool, run_tty_argv
 from sysforge.primitives.pager import maybe_pager
 from sysforge.primitives.prompt import prompt_choice, prompt_key
@@ -213,6 +222,257 @@ def cmd_config_merge(args) -> int:
     return 0
 
 
+# ---------------------------------------------------------------------------
+# check / clean / reset (3.5.0-F18)
+# ---------------------------------------------------------------------------
+
+_HINTS = {
+    "retired_key": "sysforge config clean",
+    "retired_value": "sysforge config clean",
+    "unknown_key": "check the spelling, or sysforge config clean --unknown",
+    "unknown_section": "check the spelling, or sysforge config clean --unknown",
+    "parse_error": "fix it by hand",
+}
+
+
+def cmd_config_check(args) -> int:
+    """Report retired and unknown settings. 0 when there are none, else 1."""
+    config_dir = _resolve_config_dir(args)
+    issues = config_schema.inspect(config_dir)
+    if json_out.requested(args):
+        json_out.emit("config-check", {
+            "config_dir": str(config_dir),
+            "issues": [{"file": i.file, "line": i.line, "kind": i.kind,
+                        "setting": i.where or None, "message": i.message,
+                        "fix": _HINTS[i.kind]} for i in issues],
+        })
+        return 1 if issues else 0
+    if not issues:
+        _log.ui(f"config check: nothing retired or unknown in {config_dir}")
+        return 0
+    for name in config_schema.CONFIG_FILES:
+        mine = [i for i in issues if i.file == name]
+        if not mine:
+            continue
+        _log.ui(f"{config_dir / name}")
+        for i in mine:
+            where = f"{i.where}: " if i.where else ""
+            _log.ui(f"  line {i.line}  {where}{i.message}  ({_HINTS[i.kind]})")
+    kinds = {i.kind for i in issues}
+    _log.ui(f"config check: {len(issues)} setting(s) to review"
+            + ("; `sysforge config clean` fixes the retired ones"
+               if kinds & {"retired_key", "retired_value"} else ""))
+    return 1
+
+
+def _show_diff(path: Path, old: str, new: str) -> None:
+    for line in difflib.unified_diff(old.splitlines(), new.splitlines(),
+                                     f"{path} (now)", f"{path} (after)", lineterm=""):
+        _log.ui(line)
+
+
+def _consent(args, question: str) -> bool | None:
+    """True to write, False when declined, None when it cannot ask."""
+    if getattr(args, "yes", False):
+        return True
+    if not prompt.is_interactive():
+        return None
+    return prompt.prompt_choice(f"{question} [y/N] ", ["y", "n"], default="n",
+                                retry_on_invalid=False) == "y"
+
+
+def _write_all(args, writes: list[tuple[Path, str, str]], question: str) -> int:
+    """Show each (path, old, new) diff, then write them all with consent."""
+    for path, old, new in writes:
+        _show_diff(path, old, new)
+    if getattr(args, "dry_run", False):
+        _log.ui("Dry run: nothing written.")
+        return 0
+    answer = _consent(args, question)
+    if answer is None:
+        _log.error("refusing to edit config files without a terminal to confirm on; "
+                   "pass --yes (or --dry-run to only look)")
+        return 2
+    if not answer:
+        _log.ui("Aborted: nothing written.")
+        return 2
+    for path, _old, new in writes:
+        written = atomic_write.replace_file(path, new, tag="CONFIG")
+        _log.ui(f"Wrote {written}")
+    return 0
+
+
+def cmd_config_clean(args) -> int:
+    config_dir = _resolve_config_dir(args)
+    unknown = getattr(args, "unknown", False)
+    writes, fixed, left = [], [], []
+    for name in config_schema.CONFIG_FILES:
+        path = config_dir / name
+        if not path.is_file():
+            continue
+        old = path.read_text(encoding="utf-8")
+        try:
+            new, done = config_schema.clean_text(name, old, unknown=unknown)
+        except config_schema.ConfigEditError as e:
+            _log.error(f"{path}: {e}")
+            return 1
+        fixed += done
+        left += config_schema.inspect_text(name, new)
+        if new != old:
+            writes.append((path, old, new))
+    for i, action in fixed:
+        _log.ui(f"{i.file} line {i.line}  {i.where}: {action} ({i.message})")
+    if left:
+        _log.ui(f"{len(left)} unknown setting(s) left in place; `sysforge config check` "
+                "lists them, and --unknown removes them")
+    if not writes:
+        _log.ui("config clean: nothing to change")
+        return 0
+    return _write_all(args, writes, f"Apply these changes to {len(writes)} file(s)?")
+
+
+def cmd_config_reset(args) -> int:
+    config_dir = _resolve_config_dir(args)
+    name = args.file
+    path = config_dir / name
+    keys = list(getattr(args, "keys", None) or [])
+    shipped = config_schema.shipped_text(name)
+    if shipped is None:
+        _log.error(f"no shipped default for {name} is installed")
+        return 1
+    old = path.read_text(encoding="utf-8") if path.is_file() else ""
+    if keys:
+        try:
+            new, changes = config_schema.reset_keys_text(name, old, keys)
+        except config_schema.ConfigEditError as e:
+            _log.error(str(e))
+            return 2
+        for line in changes:
+            _log.ui(line)
+        if new == old:
+            return 0
+        return _write_all(args, [(path, old, new)], f"Reset {len(keys)} key(s) in {path}?")
+    if old == shipped:
+        _log.ui(f"{path} is already the shipped default")
+        return 0
+    backup = path.with_name(f"{name}.bak-{time.strftime('%Y%m%d-%H%M%S')}")
+    _log.ui(f"{path} will be replaced by the shipped default; the current file is "
+            f"kept as {backup}")
+    if getattr(args, "dry_run", False):
+        _show_diff(path, old, shipped)
+        _log.ui("Dry run: nothing written.")
+        return 0
+    answer = _consent(args, f"Replace {path} with the shipped default?")
+    if answer is None:
+        _log.error("refusing to replace a config file without a terminal to confirm on; "
+                   "pass --yes (or --dry-run to only look)")
+        return 2
+    if not answer:
+        _log.ui("Aborted: nothing written.")
+        return 2
+    if old:
+        atomic_write.replace_file(backup, old, tag="CONFIG")
+    written = atomic_write.replace_file(path, shipped, tag="CONFIG")
+    _log.ui(f"Wrote {written}" + (f" (previous copy: {backup})" if old else ""))
+    return 0
+
+
+def _add_config_dir(p) -> None:
+    p.add_argument("--config-dir", metavar="DIR", dest="config_dir",
+        help="Live config dir (default: $SYSFORGE_CONFIG_DIR, else /etc/sysforge).")
+
+
+class ConfigCheckVerb(Verb):
+    """Read-only: report retired and unknown settings in the live config."""
+
+    name = "config-check"
+    requires_sentinel = False
+
+    @classmethod
+    def add_parser(cls, sub):
+        p = sub.add_parser("check",
+            help="Report settings in the live config files that sysforge retired "
+                 "(renamed keys, refused values) or does not know (misspelt or "
+                 "no longer used). Exits 1 when it finds any.")
+        _add_config_dir(p)
+        p.add_argument("--json", action="store_true", dest="json",
+            help="Print one JSON document (schema 1) on stdout instead of the "
+                 "report; the exit code is unchanged.")
+        p.set_defaults(verb_cls=cls)
+        return p
+
+    def pre_check(self, args) -> PreCheckResult:
+        return PreCheckResult()
+
+    def execute(self, args, pre: PreCheckResult) -> ExecResult:
+        return ExecResult(exit_code=cmd_config_check(args))
+
+
+class ConfigCleanVerb(Verb):
+    """Rewrite retired settings in place; reversible and never builds."""
+
+    name = "config-clean"
+    wants_run_log = True
+    requires_sentinel = False
+
+    @classmethod
+    def add_parser(cls, sub):
+        p = sub.add_parser("clean",
+            help="Rewrite retired settings in the live config files: a renamed key "
+                 "takes its new name (or is dropped when the new one is already "
+                 "set), a retired value its replacement. Comments are kept. Shows "
+                 "the diff and asks first.")
+        _add_config_dir(p)
+        p.add_argument("--unknown", action="store_true", dest="unknown",
+            help="Also remove settings sysforge does not know (see `config check`).")
+        p.add_argument("--dry-run", action="store_true", dest="dry_run",
+            help="Show the diff without writing anything.")
+        p.add_argument("--yes", action="store_true", dest="yes",
+            help="Write without asking (needed without a terminal).")
+        p.set_defaults(verb_cls=cls)
+        return p
+
+    def pre_check(self, args) -> PreCheckResult:
+        return PreCheckResult()
+
+    def execute(self, args, pre: PreCheckResult) -> ExecResult:
+        return ExecResult(exit_code=cmd_config_clean(args))
+
+
+class ConfigResetVerb(Verb):
+    """Put keys, or a whole file, back to the shipped default."""
+
+    name = "config-reset"
+    wants_run_log = True
+    requires_sentinel = False
+
+    @classmethod
+    def add_parser(cls, sub):
+        p = sub.add_parser("reset",
+            help="Put settings back to the shipped default: each KEY given as "
+                 "SECTION.KEY (or KEY for a top-level one), or with no KEY the whole "
+                 "FILE, keeping the current one as FILE.bak-<time>. Shows the diff "
+                 "and asks first.")
+        p.add_argument("file", metavar="FILE", choices=config_schema.CONFIG_FILES,
+            help="Config file to reset (sysforge.toml, profiles.toml, packages.toml, "
+                 "kernel.toml or toolchain.toml).")
+        p.add_argument("keys", nargs="*", metavar="KEY",
+            help="Keys to reset, such as build.jobs; omit to reset the whole file.")
+        _add_config_dir(p)
+        p.add_argument("--dry-run", action="store_true", dest="dry_run",
+            help="Show the diff without writing anything.")
+        p.add_argument("--yes", action="store_true", dest="yes",
+            help="Write without asking (needed without a terminal).")
+        p.set_defaults(verb_cls=cls)
+        return p
+
+    def pre_check(self, args) -> PreCheckResult:
+        return PreCheckResult()
+
+    def execute(self, args, pre: PreCheckResult) -> ExecResult:
+        return ExecResult(exit_code=cmd_config_reset(args))
+
+
 class ConfigMergeVerb(Verb):
     """Interactive .sfnew/.pacnew adoption. Edits config files in place but is
     fully reversible and never builds/installs, so it carries no sentinel."""
@@ -248,10 +508,11 @@ def execute(self, args, pre: PreCheckResult) -> ExecResult:
         return ExecResult(exit_code=cmd_config_merge(args))
 
 
-#: `sysforge config`: merge (subcommand required).
+#: `sysforge config`: check, clean, reset, merge (subcommand required).
 CONFIG_GROUP = VerbGroup(
     name="config",
-    help="Manage live sysforge config files (adopt shipped-default drift).",
+    help="Check, clean or reset the live sysforge config files, or merge "
+         "shipped-default changes into them.",
     dest="config_cmd",
-    members=(ConfigMergeVerb,),
+    members=(ConfigCheckVerb, ConfigCleanVerb, ConfigResetVerb, ConfigMergeVerb),
 )
diff --git a/sysforge/doctor.py b/sysforge/doctor.py
index 13dd488e..bb5b841d 100644
--- a/sysforge/doctor.py
+++ b/sysforge/doctor.py
@@ -943,6 +943,27 @@ def _collect_hook_findings() -> list[diag.Finding]:
     return out
 
 
+def _collect_config_findings() -> diag.AxisResult:
+    """Retired and unknown settings in the live config files (3.5.0-F18).
+
+    Read-only; the same inspection as `sysforge config check`. A file that does
+    not parse is an error (every command reading it fails); a retired or
+    unknown setting is a warning, since sysforge runs on, ignoring it."""
+    from sysforge.primitives import config_schema
+    from sysforge.primitives.paths import CONFIG_DIR
+    out = []
+    for i in config_schema.inspect(CONFIG_DIR):
+        retired = i.kind in ("retired_key", "retired_value")
+        out.append(diag.Finding(
+            "config", diag.SEV_ERROR if i.kind == "parse_error" else diag.SEV_WARN,
+            f"config:{i.file}:{i.line}",
+            f"{i.file} line {i.line}" + (f" {i.where}" if i.where else "") + f": {i.message}",
+            remediation=("fix the file by hand" if i.kind == "parse_error" else
+                         "sysforge config clean" if retired else
+                         "check the spelling, or sysforge config clean --unknown")))
+    return _ran(out, "retired_and_unknown_settings")
+
+
 def _collect_state_findings(args) -> diag.AxisResult:
     """sysforge's own state integrity: recorded build failures, an interrupted
     stage sentinel, build_state drift. Read-only — does not recover or save.
@@ -1138,7 +1159,7 @@ def _collect_integrity_findings(args) -> diag.AxisResult:
 # Canonical order every KNOWN axis renders in (explicit flags select from here).
 _SYSTEM_AXIS_ORDER: tuple[str, ...] = (
     "distro", "toolchain", "rust", "cache", "hardware", "graphics", "gfxperf",
-    "pacman", "state", "boot", "restart", "storage", "services", "audio",
+    "pacman", "state", "config", "boot", "restart", "storage", "services", "audio",
     "network", "integrity",
     # `abi` is registered here so axis lookup/selection is uniform, but it is
     # package-scoped: it never runs in a system sweep (_resolve_axis_names
@@ -1163,6 +1184,7 @@ def _collect_integrity_findings(args) -> diag.AxisResult:
     "gfxperf": "gfxperf",
     "pacman": "pacman",
     "state": "state",
+    "config": "config",
     "boot": "boot",
     "restart": "restart",
     "storage": "storage",
@@ -1234,6 +1256,10 @@ def _system_axes(config, args=None) -> dict[str, diag.Axis]:
             "state", "sysforge state integrity",
             lambda: _collect_state_findings(args),
             clean_msg="no build failures, stale sentinel, or state drift"),
+        "config": diag.Axis(
+            "config", "live config settings",
+            lambda: _collect_config_findings(),
+            clean_msg="no retired or unknown settings in the live config files"),
         "boot": diag.Axis(
             "boot", "boot / kernel runtime",
             lambda: _collect_boot_findings(),
@@ -1273,7 +1299,7 @@ def _system_axes(config, args=None) -> dict[str, diag.Axis]:
 
 def _resolve_axis_names(args) -> list[str]:
     """Which system axes to run, in canonical order. Explicit axis flags select
-    exactly those; otherwise the 13 non-opt-in axes (the full sweep).
+    exactly those; otherwise the 14 non-opt-in axes (the full sweep).
 
     ``abi`` is never part of a system sweep — a package walk is `doctor pkg`'s
     job and package targets no longer reach this function (2.6.1-F1).
@@ -1682,6 +1708,9 @@ def _add_system_axis_flags(p):
         help="Check sysforge's own state integrity: recorded build failures, an "
              "interrupted stage sentinel from a prior run, and build_state drift "
              "vs the live pacman database. Read-only (does not recover).")
+    p.add_argument("--config", action="store_true",
+        help="Check the live config files for settings sysforge retired or does "
+             "not know (the same report as `sysforge config check`).")
     p.add_argument("--boot", action="store_true",
         help="Check running-system boot readiness (reusing the kernel stage's "
              "safety primitives): per-kernel boot artifacts (vmlinuz + initramfs "
@@ -1754,8 +1783,8 @@ def run_log_name(cls) -> str | None:
     def add_parser(cls, sub):
         p = sub.add_parser("system",
             help="System-state axes: toolchain, cache, hardware, graphics, pacman, "
-                 "state, boot, restart, storage, services, audio, network, distro. "
-                 "With no axis flag, runs all 13 non-opt-in axes.")
+                 "state, config, boot, restart, storage, services, audio, network, distro. "
+                 "With no axis flag, runs all 14 non-opt-in axes.")
         _add_system_axis_flags(p)
         p.set_defaults(verb_cls=cls, packages=[])
         return p
diff --git a/sysforge/pipeline/stages/base.py b/sysforge/pipeline/stages/base.py
index 5cd9bb22..4b48e855 100644
--- a/sysforge/pipeline/stages/base.py
+++ b/sysforge/pipeline/stages/base.py
@@ -60,6 +60,8 @@ class RunOptions:
     build_headers: bool | None = None
     # kernel: build -docs subpackage; None → kernel.toml (default off)
     build_docs: bool | None = None
+    # kernel: --[no-]keep-hotplug-drivers; None → kernel.toml (3.5.0-B129)
+    keep_hotplug_drivers: bool | None = None
     # kernel: sample-based FDO step ("record"|"capture"|"use"); LLVM-only
     kernel_fdo: str | None = None
     kernel_propeller: bool = False     # kernel: layer Propeller on the --autofdo cycle
diff --git a/sysforge/primitives/config_schema.py b/sysforge/primitives/config_schema.py
new file mode 100644
index 00000000..b09ed643
--- /dev/null
+++ b/sysforge/primitives/config_schema.py
@@ -0,0 +1,520 @@
+# SPDX-FileCopyrightText: 2026 Keith Raghubar
+#
+# SPDX-License-Identifier: MIT
+
+"""
+config_schema.py — what a live config file may contain, and the edits that bring
+one back in line (3.5.0-F18).
+
+A live config dir is never rewritten by an upgrade (pacman's backup=() or
+`make sync-config`, which only adds), so a key sysforge stopped reading stays
+there, silently ignored, and a misspelt one is never reported. This module is
+the one home for:
+
+* the schema: the top-level sections and keys each file accepts
+  (``KNOWN_SECTIONS``/``KNOWN_TOP_KEYS``, also used by tools/check_shipped.py),
+  the sections whose keys the user names (``OPEN_SECTIONS``: profiles, rules,
+  packages, ...), and, for every other section, the keys the shipped default
+  documents, active or as a commented example;
+* what was retired: ``RETIRED_KEYS`` (renamed or dropped keys) and
+  ``RETIRED_VALUES`` (values that are now refused or ignored);
+* the shipped defaults themselves (``shipped_text``), read from the checkout or
+  from the copy packaged in the wheel;
+* ``inspect`` (what `config check` and `doctor system --config` report) and the
+  edits `config clean` and `config reset` make.
+
+Edits are line-based so comments and layout survive, and every edited file is
+re-parsed with tomllib before it is written: an edit that would leave the file
+unparsable is refused.
+
+Public API:
+    CONFIG_FILES, KNOWN_SECTIONS, KNOWN_TOP_KEYS, OPEN_SECTIONS
+    RETIRED_KEYS, RETIRED_VALUES
+    Issue
+    shipped_text(name) -> str | None
+    inspect(config_dir) -> list[Issue]
+    clean_text(name, text, *, unknown) -> tuple[str, list[tuple[Issue, str]]]
+    reset_keys_text(name, text, keys) -> tuple[str, list[str]]
+    ConfigEditError
+"""
+from __future__ import annotations
+
+import fnmatch
+import re
+import tomllib
+from dataclasses import dataclass
+from importlib import resources as importlib_resources
+from pathlib import Path
+
+# Files a live config dir holds. bootstrap.toml is a per-host install answer
+# file shipped as an example, not a live config.
+CONFIG_FILES: tuple[str, ...] = (
+    "sysforge.toml", "profiles.toml", "packages.toml", "kernel.toml", "toolchain.toml",
+)
+
+# Top-level sections accepted in each file. Adding one here is the deliberate
+# signal that the schema changed; the schema and the shipped file are edited
+# together (tools/check_shipped.py `configs` checks the shipped side).
+KNOWN_SECTIONS: dict[str, set[str]] = {
+    "sysforge.toml":  {"ui", "log", "git", "aur", "build", "failure_handling",
+                       "safety", "mesa", "pgo", "update", "doctor", "artifacts",
+                       "security"},
+    "profiles.toml":  {"paths", "defaults", "profiles", "rules",
+                       "append_conflict_groups", "preserved_system_tokens",
+                       "consumes_inference",
+                       "package_compiler_overrides"},
+    "packages.toml":  {"build", "package", "group"},
+    "kernel.toml":    {"kconfig", "fdo"},
+    "toolchain.toml": {"packages", "llvm", "bolt", "bench"},
+    "bootstrap.toml": {"partition", "system", "mirror", "desktop", "makepkg"},
+}
+
+# Top-level scalar keys (in addition to sections).
+KNOWN_TOP_KEYS: dict[str, set[str]] = {
+    "sysforge.toml":  set(),
+    "profiles.toml":  {"extends_system"},
+    "packages.toml":  set(),
+    # Kept in lockstep with what KernelStage actually reads via
+    # kernel_cfg.get(...) — enforced by tests/test_check_shipped.py's
+    # test_kernel_allowlist_matches_stage_reads. The kernel stage does NO
+    # PGO, so the toolchain's pgo/skip_build/pgo_staging/pgo_store keys are
+    # deliberately absent here.
+    "kernel.toml":    {"enabled", "compiler", "pkgname", "upstream_pkgname",
+                       "srcdir", "boot_entries", "boot_entries_prefix",
+                       "bootloader", "interactive", "pkgbuild_src_dir",
+                       "source", "base_config", "base_config_merge",
+                       "require_fallback_kernel", "boot_audit", "min_boot_free_mb",
+                       "capture_lsmod_snapshot", "device_kconfig",
+                       "kconfig_merge", "build_headers", "build_docs",
+                       "kconfig_targets", "keep_hotplug_drivers", "hardening"},
+    "toolchain.toml": {"enabled", "compiler", "pgo", "skip_build",
+                       "drift_detect",
+                       "pgo_staging", "pgo_staging1", "pgo_staging3",
+                       "pgo_store", "min_build_free_gb", "require_multilib",
+                       "rebuild_soname_consumers", "reuse_unchanged",
+                       # read by makepkg_pgo.resolve_profile_store_root; the
+                       # list predates it (3.5.0-F18 found it missing)
+                       "profile_store"},
+    "bootstrap.toml": {"target"},
+}
+
+# Sections whose keys (or sub-table names) the user chooses: a profile's flag
+# variables, a rule, a package entry, a group, a kconfig option. Nothing under
+# them is reported as unknown.
+OPEN_SECTIONS: dict[str, set[str]] = {
+    "profiles.toml": {"profiles", "rules", "append_conflict_groups",
+                      "preserved_system_tokens", "consumes_inference",
+                      "package_compiler_overrides"},
+    "packages.toml": {"package", "group"},
+    "kernel.toml":   {"kconfig"},
+}
+
+
+@dataclass(frozen=True)
+class RetiredKey:
+    file: str
+    section: str          # fnmatch pattern on the table name ("" = top level)
+    key: str
+    replacement: str | None
+    retired_in: str
+
+
+@dataclass(frozen=True)
+class RetiredValue:
+    file: str
+    section: str
+    key: str
+    old: str
+    new: str
+    retired_in: str
+
+
+RETIRED_KEYS: tuple[RetiredKey, ...] = (
+    RetiredKey("sysforge.toml", "git", "pull_timeout", "fetch_timeout", "2.6.1-F5"),
+    RetiredKey("packages.toml", "package", "pkgbuild_patch",
+               "enable_build_from_source", "2.6.1-F5"),
+)
+
+RETIRED_VALUES: tuple[RetiredValue, ...] = (
+    RetiredValue("packages.toml", "build", "repo_mode", "profiled",
+                 "build_from_source", "2.6.1-F5"),
+    RetiredValue("profiles.toml", "profiles.*", "build_mode", "patched_pkgbuild",
+                 "source_built", "3.5.0-F16"),
+)
+
+
+@dataclass(frozen=True)
+class Issue:
+    file: str
+    line: int             # 1-based
+    # parse_error | retired_key | retired_value | unknown_key | unknown_section
+    kind: str
+    where: str            # "[git] pull_timeout", "[nosuch]", "extends_systm"
+    message: str
+
+
+class ConfigEditError(Exception):
+    """An edit was refused (its result would not parse, or it cannot apply)."""
+
+
+# ---------------------------------------------------------------------------
+# Shipped defaults
+# ---------------------------------------------------------------------------
+
+def _repo_defaults_dir() -> Path:
+    return Path(__file__).resolve().parents[2] / "etc/sysforge"
+
+
+def shipped_text(name: str) -> str | None:
+    """The shipped default for ``name``: the checkout's etc/sysforge when
+    running from one, else the copy packaged in the wheel."""
+    repo = _repo_defaults_dir() / name
+    if repo.is_file():
+        return repo.read_text(encoding="utf-8")
+    try:
+        data = importlib_resources.files("sysforge").joinpath("_data", "config-defaults", name)
+        return data.read_text(encoding="utf-8") if data.is_file() else None
+    except (FileNotFoundError, ModuleNotFoundError):
+        return None
+
+
+# ---------------------------------------------------------------------------
+# A line-level view of a TOML file
+# ---------------------------------------------------------------------------
+
+_HEADER_RE = re.compile(r"^\s*(\[\[?)\s*([^\[\]#]+?)\s*(\]\]?)\s*(#.*)?$")
+_KEY_RE = re.compile(r"""^\s*((?:[A-Za-z0-9_-]+|"[^"]*"|'[^']*')"""
+                     r"""(?:\s*\.\s*(?:[A-Za-z0-9_-]+|"[^"]*"|'[^']*'))*)\s*=""")
+
+
+def _unquote_parts(dotted: str) -> list[str]:
+    return [p.strip().strip("\"'") for p in re.findall(
+        r"""(?:"[^"]*"|'[^']*'|[^.]+)""", dotted)]
+
+
+@dataclass
+class _Entry:
+    start: int            # 0-based first line
+    end: int              # 0-based last line, inclusive
+    table: str            # dotted table name ("" = top level)
+    table_id: int         # which occurrence of a header (array-of-tables entries differ)
+    is_array_table: bool
+    key: str              # first key part
+    raw_value: str        # value text, comments included
+
+
+@dataclass
+class _Header:
+    line: int
+    table: str
+    table_id: int
+    is_array_table: bool
+
+
+def _value_extent(lines: list[str], i: int, after_eq: str) -> int:
+    """Last line of a value starting on line ``i`` (multi-line arrays, inline
+    tables and triple-quoted strings span lines)."""
+    text = after_eq.lstrip()
+    for quote in ('"""', "'''"):
+        if text.startswith(quote):
+            if text.count(quote) >= 2:
+                return i
+            j = i + 1
+            while j < len(lines) and quote not in lines[j]:
+                j += 1
+            return min(j, len(lines) - 1)
+    depth, j, chunk = 0, i, after_eq
+    while True:
+        in_str = None
+        for ch in chunk:
+            if in_str:
+                if ch == in_str:
+                    in_str = None
+            elif ch in "\"'":
+                in_str = ch
+            elif ch == "#":
+                break
+            elif ch in "[{":
+                depth += 1
+            elif ch in "]}":
+                depth -= 1
+        if depth <= 0 or j + 1 >= len(lines):
+            return j
+        j += 1
+        chunk = lines[j]
+
+
+def _scan(lines: list[str]) -> tuple[list[_Header], list[_Entry]]:
+    headers: list[_Header] = []
+    entries: list[_Entry] = []
+    table, table_id, is_aot = "", 0, False
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            i += 1
+            continue
+        h = _HEADER_RE.match(line)
+        if h and h.group(1) == ("[[" if h.group(3) == "]]" else "["):
+            table = ".".join(_unquote_parts(h.group(2)))
+            table_id += 1
+            is_aot = h.group(1) == "[["
+            headers.append(_Header(i, table, table_id, is_aot))
+            i += 1
+            continue
+        k = _KEY_RE.match(line)
+        if k:
+            after = line[k.end():]
+            end = _value_extent(lines, i, after)
+            raw = "\n".join([after] + lines[i + 1:end + 1])
+            entries.append(_Entry(i, end, table, table_id, is_aot,
+                                  _unquote_parts(k.group(1))[0], raw))
+            i = end + 1
+            continue
+        i += 1
+    return headers, entries
+
+
+def _documented(text: str) -> dict[str, set[str]]:
+    """Table -> keys the shipped default documents, active or commented out."""
+    out: dict[str, set[str]] = {"": set()}
+    table = active = ""
+    for line in text.splitlines():
+        if not line.strip():
+            # A commented example table covers its own comment block only: a
+            # blank line returns to the last real header, so a top-level key
+            # documented after the header's examples stays top-level.
+            table = active
+            continue
+        commented = line.lstrip().startswith("#")
+        body = re.sub(r"^\s*#\s?", "", line) if commented else line
+        h = _HEADER_RE.match(body)
+        if h and body.strip().startswith("["):
+            table = ".".join(_unquote_parts(h.group(2)))
+            if not commented:
+                active = table
+            out.setdefault(table, set())
+            continue
+        k = _KEY_RE.match(body)
+        if k:
+            out.setdefault(table, set()).add(_unquote_parts(k.group(1))[0])
+    return out
+
+
+def _value(raw: str):
+    try:
+        return tomllib.loads("v = " + raw.strip())["v"]
+    except tomllib.TOMLDecodeError:
+        return None
+
+
+# ---------------------------------------------------------------------------
+# Inspection
+# ---------------------------------------------------------------------------
+
+def _retired_key(name: str, table: str, key: str) -> RetiredKey | None:
+    return next((r for r in RETIRED_KEYS if r.file == name and r.key == key
+                 and fnmatch.fnmatchcase(table, r.section)), None)
+
+
+def _retired_value(name: str, table: str, key: str, value) -> RetiredValue | None:
+    return next((r for r in RETIRED_VALUES if r.file == name and r.key == key
+                 and value == r.old and fnmatch.fnmatchcase(table, r.section)), None)
+
+
+def _where(table: str, key: str | None = None) -> str:
+    head = f"[{table}]" if table else ""
+    return f"{head} {key}".strip() if key else head
+
+
+def inspect_text(name: str, text: str) -> list[Issue]:
+    """Issues in one config file's text (``name`` is its file name)."""
+    try:
+        tomllib.loads(text)
+    except tomllib.TOMLDecodeError as e:
+        line = getattr(e, "lineno", 0) or 0
+        return [Issue(name, line, "parse_error", "", f"does not parse: {e}")]
+    lines = text.splitlines()
+    headers, entries = _scan(lines)
+    known_sections = KNOWN_SECTIONS.get(name, set())
+    open_sections = OPEN_SECTIONS.get(name, set())
+    shipped = shipped_text(name)
+    documented = _documented(shipped) if shipped else {}
+    issues: list[Issue] = []
+    for h in headers:
+        top = h.table.split(".")[0]
+        if top not in known_sections:
+            issues.append(Issue(name, h.line + 1, "unknown_section", _where(h.table),
+                                f"{name} has no [{top}] section"))
+    for e in entries:
+        where = _where(e.table, e.key)
+        top = e.table.split(".")[0] if e.table else ""
+        rk = _retired_key(name, e.table, e.key)
+        if rk:
+            use = f"; use {rk.replacement}" if rk.replacement else ""
+            issues.append(Issue(name, e.start + 1, "retired_key", where,
+                                f"retired in {rk.retired_in}, no longer read{use}"))
+            continue
+        rv = _retired_value(name, e.table, e.key, _value(e.raw_value))
+        if rv:
+            issues.append(Issue(name, e.start + 1, "retired_value", where,
+                                f"{rv.old!r} was retired in {rv.retired_in}; use {rv.new!r}"))
+            continue
+        if top and (top not in known_sections or top in open_sections):
+            continue  # reported with its header, or the user names these keys
+        if not top:
+            if e.key not in KNOWN_TOP_KEYS.get(name, set()):
+                issues.append(Issue(name, e.start + 1, "unknown_key", where,
+                                    f"{name} has no top-level {e.key!r}"))
+            continue
+        if documented and e.key not in documented.get(e.table, set()):
+            issues.append(Issue(name, e.start + 1, "unknown_key", where,
+                                f"[{e.table}] has no {e.key!r} (misspelt, or no longer used)"))
+    return sorted(issues, key=lambda i: i.line)
+
+
+def inspect(config_dir: Path) -> list[Issue]:
+    """Issues across every config file present in ``config_dir``."""
+    issues: list[Issue] = []
+    for name in CONFIG_FILES:
+        path = Path(config_dir) / name
+        if path.is_file():
+            issues += inspect_text(name, path.read_text(encoding="utf-8"))
+    return issues
+
+
+# ---------------------------------------------------------------------------
+# Edits
+# ---------------------------------------------------------------------------
+
+def _apply(lines: list[str], edits: list[tuple[int, int, list[str]]]) -> list[str]:
+    """Replace each inclusive line range with new lines, last edit first."""
+    out = list(lines)
+    for start, end, new in sorted(edits, key=lambda e: e[0], reverse=True):
+        out[start:end + 1] = new
+    return out
+
+
+def _checked(text: str) -> str:
+    try:
+        tomllib.loads(text)
+    except tomllib.TOMLDecodeError as e:
+        raise ConfigEditError(f"the edited file would not parse ({e}); nothing written") from e
+    return text
+
+
+def _rejoin(lines: list[str], original: str) -> str:
+    return "\n".join(lines) + ("\n" if original.endswith("\n") else "")
+
+
+def clean_text(name: str, text: str, *, unknown: bool) -> tuple[str, list[tuple[Issue, str]]]:
+    """``text`` with retired keys renamed (or dropped when the replacement is
+    already set) and retired values rewritten; with ``unknown``, unknown keys
+    and sections removed too. Returns (new text, [(issue, what was done)])."""
+    issues = inspect_text(name, text)
+    if any(i.kind == "parse_error" for i in issues):
+        raise ConfigEditError(f"{name} does not parse; fix it by hand first")
+    lines = text.splitlines()
+    headers, entries = _scan(lines)
+    by_line = {e.start + 1: e for e in entries}
+    present = {(e.table_id, e.key) for e in entries}
+    edits: list[tuple[int, int, list[str]]] = []
+    fixed: list[tuple[Issue, str]] = []
+    for issue in issues:
+        e = by_line.get(issue.line)
+        if issue.kind == "retired_key" and e:
+            rk = _retired_key(name, e.table, e.key)
+            assert rk is not None  # noqa: S101 — inspect_text found it
+            if rk.replacement and (e.table_id, rk.replacement) not in present:
+                first = re.sub(rf"^(\s*){re.escape(e.key)}(\s*=)", rf"\g<1>{rk.replacement}\2",
+                               lines[e.start], count=1)
+                edits.append((e.start, e.start, [first]))
+                fixed.append((issue, f"renamed to {rk.replacement}"))
+            else:
+                edits.append((e.start, e.end, []))
+                fixed.append((issue, f"removed; {rk.replacement} is already set in this "
+                                     "table and keeps its value" if rk.replacement
+                              else "removed"))
+        elif issue.kind == "retired_value" and e:
+            rv = _retired_value(name, e.table, e.key, _value(e.raw_value))
+            assert rv is not None  # noqa: S101
+            new = re.sub(rf"(['\"]){re.escape(rv.old)}\1", rf"\g<1>{rv.new}\1",
+                         lines[e.start], count=1)
+            edits.append((e.start, e.start, [new]))
+            fixed.append((issue, f"set to {rv.new!r}"))
+        elif unknown and issue.kind == "unknown_key" and e:
+            edits.append((e.start, e.end, []))
+            fixed.append((issue, "removed"))
+        elif unknown and issue.kind == "unknown_section":
+            h = next(h for h in headers if h.line + 1 == issue.line)
+            nxt = next((x.line for x in headers if x.line > h.line), len(lines))
+            edits.append((h.line, nxt - 1, []))
+            fixed.append((issue, "removed with everything in it"))
+    if not edits:
+        return text, []
+    return _checked(_rejoin(_apply(lines, edits), text)), fixed
+
+
+def _split_key(spec: str) -> tuple[str, str]:
+    table, _, key = spec.rpartition(".")
+    return table, key
+
+
+def reset_keys_text(name: str, text: str, keys: list[str]) -> tuple[str, list[str]]:
+    """``text`` with each ``section.key`` (or top-level ``key``) set back to the
+    shipped default: the shipped line when the default sets it, else removed
+    (the default only documents it). Returns (new text, what changed)."""
+    shipped = shipped_text(name)
+    if shipped is None:
+        raise ConfigEditError(f"no shipped default for {name} is installed")
+    s_lines = shipped.splitlines()
+    _, s_entries = _scan(s_lines)
+    lines = text.splitlines()
+    headers, entries = _scan(lines)
+    edits: list[tuple[int, int, list[str]]] = []
+    appends: list[str] = []
+    changes: list[str] = []
+    for spec in keys:
+        table, key = _split_key(spec)
+        if any(h.table == table and h.is_array_table for h in headers) or any(
+                e.table == table and e.is_array_table for e in s_entries):
+            raise ConfigEditError(
+                f"{spec}: [[{table}]] entries are yours to edit; reset the whole file instead")
+        mine = [e for e in entries if e.table == table and e.key == key]
+        theirs = next((e for e in s_entries if e.table == table and e.key == key), None)
+        new_lines = s_lines[theirs.start:theirs.end + 1] if theirs else []
+        if mine:
+            current = lines[mine[0].start:mine[0].end + 1]
+            if current == new_lines:
+                changes.append(f"{spec}: already the shipped default")
+                continue
+            edits.append((mine[0].start, mine[0].end, new_lines))
+            changes.append(f"{spec}: " + ("set to the shipped value" if theirs
+                                          else "removed (the default leaves it unset)"))
+        elif theirs:
+            section_end = None
+            for h in headers:
+                if h.table == table:
+                    nxt = next((x.line for x in headers if x.line > h.line), len(lines))
+                    section_end = nxt - 1
+            if not table:
+                edits.append((-1, -1, new_lines))  # sentinel: before the first header
+            elif section_end is not None:
+                edits.append((section_end + 1, section_end, new_lines))
+            else:
+                appends += ["", f"[{table}]", *new_lines]
+            changes.append(f"{spec}: added with the shipped value")
+        else:
+            changes.append(f"{spec}: unset here and in the shipped default; nothing to do")
+    out = list(lines)
+    for start, end, new in sorted(edits, key=lambda e: e[0], reverse=True):
+        if start == -1:
+            first = next((h.line for h in headers), len(out))
+            out[first:first] = new
+        else:
+            out[start:end + 1] = new
+    out += appends
+    if out == lines:
+        return text, changes
+    return _checked(_rejoin(out, text)), changes
diff --git a/sysforge/primitives/env_vars.py b/sysforge/primitives/env_vars.py
new file mode 100644
index 00000000..c49fe769
--- /dev/null
+++ b/sysforge/primitives/env_vars.py
@@ -0,0 +1,71 @@
+# SPDX-FileCopyrightText: 2026 Keith Raghubar
+#
+# SPDX-License-Identifier: MIT
+
+"""
+env_vars.py — every environment variable sysforge reads, in one table (3.5.0-B128).
+
+The man page's ENVIRONMENT section is generated from ``ENV_VARS``
+(``tools/gen_options.py``, the ``@ENVIRONMENT@`` marker), and
+``tests/test_env_vars.py`` fails on a ``SYSFORGE_*`` name the code reads that
+is not here. Before this table the man page listed three of the eleven, and
+``SYSFORGE_PROFILE_STORE`` was documented nowhere.
+
+``audience`` is ``"user"`` for a setting a user is expected to change and
+``"diagnostic"`` for a switch meant for bug reports; the man page shows both,
+diagnostics last. Descriptions are scdoc text, one paragraph each.
+
+Public API:
+    EnvVar
+    ENV_VARS
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class EnvVar:
+    name: str
+    audience: str  # "user" | "diagnostic"
+    text: str
+
+
+ENV_VARS: tuple[EnvVar, ...] = (
+    EnvVar("SYSFORGE_STATE_DIR", "user",
+           "Override the state directory (stage progress, build_state.toml, logs, "
+           "sentinels). Read by every command that touches build state: *build*, "
+           "*update*, *state*, *log*, *doctor*, and the *run* stages."),
+    EnvVar("SYSFORGE_CONFIG_DIR", "user",
+           "Override the configuration directory searched before /etc/sysforge. "
+           "Read by every command that loads a config file (see FILES)."),
+    EnvVar("SYSFORGE_EDITOR", "user",
+           "Editor sysforge opens: *run reconfigure*'s config review, *artifact "
+           "edit* and *config merge*. Checked first, then sysforge.toml [ui] editor, "
+           "$EDITOR and $VISUAL."),
+    EnvVar("SYSFORGE_MERGE", "user",
+           "Merge tool for *config merge*. Checked first, then sysforge.toml [ui] "
+           "merge, $DIFFPROG, then vimdiff."),
+    EnvVar("SYSFORGE_ASCII", "user",
+           "Any non-empty value prints ASCII in place of decorative glyphs "
+           "(arrows, bullets, progress fills), for terminals and fonts without them."),
+    EnvVar("SYSFORGE_PGO_STORE", "user",
+           "Directory for the toolchain's PGO profiles, used when toolchain.toml "
+           "sets no pgo_store."),
+    EnvVar("SYSFORGE_PROFILE_STORE", "user",
+           "Root directory of every other profile store (pgo/<pkgbase>, autofdo, "
+           "propeller, bolt), used when toolchain.toml sets no profile_store."),
+    EnvVar("PAGER", "user",
+           "Pager for *sysforge log*, *state* listings, and PKGBUILD review diffs "
+           "in *build*/*update* (falls back to less -RF, then more)."),
+    EnvVar("SYSFORGE_PTY_RAW_DUMP", "diagnostic",
+           "A file path: every byte a build writes to its terminal is appended there, "
+           "after a line giving the terminal size sysforge handed it. For reports "
+           "about garbled build output."),
+    EnvVar("SYSFORGE_PROGRESS_TRACE", "diagnostic",
+           "A file path: the progress bar logs each repaint, resize and handover "
+           "there. For reports about the progress bar."),
+    EnvVar("SYSFORGE_PACMAN_NO_PYALPM", "diagnostic",
+           "Any non-empty value makes sysforge query pacman through the pacman "
+           "command rather than pyalpm, to tell a pyalpm problem from a sysforge one."),
+)
diff --git a/sysforge/primitives/journal.py b/sysforge/primitives/journal.py
index 34e8e3cf..a2cb82c7 100644
--- a/sysforge/primitives/journal.py
+++ b/sysforge/primitives/journal.py
@@ -57,6 +57,23 @@ def journal_send(**fields: str | int) -> None:
 TARGET_PKG_PREFIX = "pkg:"
 TARGET_MODE_PREFIX = "mode:"
 
+FIELD_VERB = "SYSFORGE_VERB"
+FIELD_TARGET = "SYSFORGE_TARGET"
+FIELD_EXIT = "SYSFORGE_EXIT"
+
+#: The fields a record carries besides journald's own, as (name, scdoc text).
+#: Only commands that change the system write a record.
+#: The man page's JOURNAL section is generated from this (3.5.0-DOC13).
+JOURNAL_FIELDS: tuple[tuple[str, str], ...] = (
+    (FIELD_VERB, "The command, with spaces as dashes for subcommands "
+                 "(build, update, state-forget, artifact-deploy)."),
+    (FIELD_TARGET, "What it acted on, when it has a subject: pkg:<names> for "
+                   "packages (space-separated), mode:<name> for a state "
+                   "operation. Absent otherwise."),
+    (FIELD_EXIT, "The exit status. Records of a failed run are also logged at "
+                 "PRIORITY=3 (err), the others at 6 (info)."),
+)
+
 
 def pkg_target(names) -> str | None:
     """`pkg:`-namespaced ``SYSFORGE_TARGET`` for a package-subject verb.
@@ -79,9 +96,9 @@ def record_verb(verb: str, target: str | None, exit_code: int) -> None:
         "MESSAGE": message,
         "PRIORITY": 6 if exit_code == 0 else 3,
         "SYSLOG_IDENTIFIER": "sysforge",
-        "SYSFORGE_VERB": verb,
-        "SYSFORGE_EXIT": exit_code,
+        FIELD_VERB: verb,
+        FIELD_EXIT: exit_code,
     }
     if target:
-        fields["SYSFORGE_TARGET"] = target
+        fields[FIELD_TARGET] = target
     journal_send(**fields)
diff --git a/sysforge/run_cmd.py b/sysforge/run_cmd.py
index 22728039..88f5b839 100644
--- a/sysforge/run_cmd.py
+++ b/sysforge/run_cmd.py
@@ -535,6 +535,7 @@ def execute(self, args, pre: PreCheckResult) -> ExecResult:
             allow_boot_audit_failure=getattr(args, "allow_boot_audit_failure", False),
             build_headers=getattr(args, "build_headers", None),
             build_docs=getattr(args, "build_docs", None),
+            keep_hotplug_drivers=getattr(args, "keep_hotplug_drivers", None),
             kernel_fdo=getattr(args, "kernel_fdo", None),
             kernel_propeller=getattr(args, "kernel_propeller", False),
         )
diff --git a/tests/cli_args.py b/tests/cli_args.py
new file mode 100644
index 00000000..8a861727
--- /dev/null
+++ b/tests/cli_args.py
@@ -0,0 +1,26 @@
+# SPDX-FileCopyrightText: 2026 Keith Raghubar
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Parsed command lines for tests (3.5.0-DEV13).
+
+``cli_args("state", "list", state_dir=d)`` parses ``sysforge state list`` with
+the real parser, then sets each keyword on the result. Every field the command
+has is therefore present with its real default, and a keyword the command does
+not have fails at once, so a renamed flag cannot leave a test passing on a
+name production never sets. This replaces ``SimpleNamespace`` stand-ins
+(tests/test_stand_ins.py).
+"""
+from __future__ import annotations
+
+from sysforge.verbs.registry import build_parser
+
+
+def cli_args(*argv: str, **fields):
+    args = build_parser().parse_args(list(argv))
+    for name, value in fields.items():
+        if not hasattr(args, name):
+            raise AttributeError(f"`sysforge {' '.join(argv)}` has no {name!r}")
+        setattr(args, name, value)
+    return args
diff --git a/tests/data/etc/sysforge/profiles.toml b/tests/data/etc/sysforge/profiles.toml
index e38e02f8..a3724fc3 100644
--- a/tests/data/etc/sysforge/profiles.toml
+++ b/tests/data/etc/sysforge/profiles.toml
@@ -133,6 +133,11 @@
 # Defaults
 # =============================================================================
 
+# extends_system — only in a user file (~/.config/sysforge/profiles.toml):
+#   true merges it onto this system file (its rules ranked above the system's)
+#   instead of replacing the system file outright.
+# extends_system = true
+
 [paths]
 pkgbuild_src_dir = "~/src"
 
diff --git a/tests/data/etc/sysforge/toolchain.toml b/tests/data/etc/sysforge/toolchain.toml
index ad9be0b0..cd3ad009 100644
--- a/tests/data/etc/sysforge/toolchain.toml
+++ b/tests/data/etc/sysforge/toolchain.toml
@@ -37,6 +37,11 @@ drift_detect = "fingerprint"
 #   major) skips passes 1-3. Use --rebuild-profdata to force a full 4-pass
 #   build. Needs ~500 MB free during pass 3.
 # pgo_store = "/var/cache/sysforge/llvm-pgo"
+#
+# profile_store — root directory of the other profile stores: build --pgo's
+#   pgo/<pkgbase>, the kernel's autofdo/ and propeller/, and bolt/. Overridden
+#   by SYSFORGE_PROFILE_STORE when unset here.
+# profile_store = "/var/cache/sysforge"
 
 # Build-safety Gate 1 (LLVM path only — the GCC path is register-only and skips
 # all gates). The keys below are *settable config keys shown at their
diff --git a/tests/data/json-schema/config-check.schema.json b/tests/data/json-schema/config-check.schema.json
new file mode 100644
index 00000000..8d84552d
--- /dev/null
+++ b/tests/data/json-schema/config-check.schema.json
@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "sysforge/config-check.schema.json",
+  "title": "sysforge config check --json (schema 1)",
+  "type": "object",
+  "required": ["schema", "kind", "config_dir", "issues"],
+  "additionalProperties": false,
+  "properties": {
+    "schema": {"const": 1},
+    "kind": {"const": "config-check"},
+    "config_dir": {"type": "string"},
+    "issues": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["file", "line", "kind", "setting", "message", "fix"],
+        "additionalProperties": false,
+        "properties": {
+          "file": {"enum": ["sysforge.toml", "profiles.toml", "packages.toml",
+                            "kernel.toml", "toolchain.toml"]},
+          "line": {"type": "integer"},
+          "kind": {"enum": ["parse_error", "retired_key", "retired_value",
+                            "unknown_key", "unknown_section"]},
+          "setting": {"type": ["string", "null"]},
+          "message": {"type": "string"},
+          "fix": {"type": "string"}
+        }
+      }
+    }
+  }
+}
diff --git a/tests/data/surface.json b/tests/data/surface.json
new file mode 100644
index 00000000..582ed372
--- /dev/null
+++ b/tests/data/surface.json
@@ -0,0 +1,879 @@
+{
+ "commands": {
+  "": {
+   "flags": {
+    "--color": [
+     "always",
+     "auto",
+     "never"
+    ],
+    "--frozen": null,
+    "--no-frozen": null,
+    "--no-throttle": null,
+    "--py-profile": null,
+    "--py-profile-out": null,
+    "--quiet": null,
+    "--thaw": null,
+    "--timings": null,
+    "--turbo": null,
+    "--verbose": null,
+    "--version": null
+   },
+   "positionals": {}
+  },
+  "artifact adopt": {
+   "flags": {
+    "--class": [
+     "pacman-hook",
+     "script",
+     "systemd-unit"
+    ]
+   },
+   "positionals": {
+    "PATH": null
+   }
+  },
+  "artifact deploy": {
+   "flags": {
+    "--adopt-live": null,
+    "--all": null,
+    "--force": null
+   },
+   "positionals": {
+    "NAME": null
+   }
+  },
+  "artifact edit": {
+   "flags": {},
+   "positionals": {
+    "NAME": null
+   }
+  },
+  "artifact list": {
+   "flags": {
+    "--unmanaged": null
+   },
+   "positionals": {}
+  },
+  "artifact remove": {
+   "flags": {
+    "--force": null,
+    "--purge": null
+   },
+   "positionals": {
+    "NAME": null
+   }
+  },
+  "artifact review": {
+   "flags": {
+    "--all": null,
+    "--include-unknown": null
+   },
+   "positionals": {}
+  },
+  "bench toolchain": {
+   "flags": {
+    "--offline": null,
+    "--runs": null,
+    "--state-dir": null
+   },
+   "positionals": {}
+  },
+  "build": {
+   "flags": {
+    "--abi-check": null,
+    "--cache-report": null,
+    "--cc": null,
+    "--cleansrc": null,
+    "--cleansrc-force": null,
+    "--cxx": null,
+    "--force": null,
+    "--interactive": null,
+    "--ld": null,
+    "--log-dir": null,
+    "--makepkg": null,
+    "--no-llvm-preflight": null,
+    "--no-pkg-log": null,
+    "--no-review": null,
+    "--no-update": null,
+    "--persist-log": null,
+    "--pgo": [
+     "record",
+     "use"
+    ],
+    "--profile-conf": null,
+    "--rebuild": null,
+    "--reset-toolchain": null,
+    "--review": null,
+    "--save-toolchain": null,
+    "--state-dir": null,
+    "--toolchain": [
+     "gcc",
+     "llvm"
+    ]
+   },
+   "positionals": {
+    "PKGBUILD": null
+   }
+  },
+  "config check": {
+   "flags": {
+    "--config-dir": null,
+    "--json": null
+   },
+   "positionals": {}
+  },
+  "config clean": {
+   "flags": {
+    "--config-dir": null,
+    "--dry-run": null,
+    "--unknown": null,
+    "--yes": null
+   },
+   "positionals": {}
+  },
+  "config merge": {
+   "flags": {
+    "--config-dir": null,
+    "--dry-run": null,
+    "--no-pager": null
+   },
+   "positionals": {}
+  },
+  "config reset": {
+   "flags": {
+    "--config-dir": null,
+    "--dry-run": null,
+    "--yes": null
+   },
+   "positionals": {
+    "FILE": [
+     "kernel.toml",
+     "packages.toml",
+     "profiles.toml",
+     "sysforge.toml",
+     "toolchain.toml"
+    ],
+    "KEY": null
+   }
+  },
+  "doctor pkg": {
+   "flags": {
+    "--abi": null,
+    "--all": null,
+    "--apply": null,
+    "--dry-run": null,
+    "--findings-only": null,
+    "--graphics": null,
+    "--integrity": null,
+    "--json": null,
+    "--repo": null,
+    "--rust": null,
+    "--shallow": null,
+    "--suggest": null,
+    "--yes": null
+   },
+   "positionals": {
+    "PKG": null
+   }
+  },
+  "doctor system": {
+   "flags": {
+    "--audio": null,
+    "--boot": null,
+    "--cache": null,
+    "--config": null,
+    "--distro": null,
+    "--findings-only": null,
+    "--gfxperf": null,
+    "--graphics": null,
+    "--hardware": null,
+    "--integrity": null,
+    "--json": null,
+    "--network": null,
+    "--pacman": null,
+    "--restart": null,
+    "--rust": null,
+    "--services": null,
+    "--state": null,
+    "--storage": null,
+    "--toolchain": null
+   },
+   "positionals": {}
+  },
+  "env": {
+   "flags": {},
+   "positionals": {}
+  },
+  "fetch": {
+   "flags": {
+    "--cleansrc": null,
+    "--cleansrc-force": null,
+    "--no-llvm-preflight": null,
+    "--no-update": null,
+    "--profile-conf": null
+   },
+   "positionals": {
+    "PKG": null
+   }
+  },
+  "help": {
+   "flags": {},
+   "positionals": {
+    "COMMAND": null
+   }
+  },
+  "log": {
+   "flags": {
+    "--log-dir": null,
+    "--no-pager": null,
+    "--state-dir": null,
+    "--verb": [
+     "build",
+     "config-clean",
+     "config-merge",
+     "config-reset",
+     "doctor",
+     "fetch",
+     "revert-to-stock",
+     "run-hardware",
+     "run-kernel",
+     "run-packages",
+     "run-reconfigure",
+     "run-toolchain",
+     "setup",
+     "state-forget",
+     "state-repair",
+     "uninstall",
+     "update"
+    ]
+   },
+   "positionals": {
+    "PKG": null
+   }
+  },
+  "packages add": {
+   "flags": {
+    "--enable-build-from-source": null,
+    "--no-cache": null,
+    "--packages": null,
+    "--reason": null,
+    "--source": [
+     "aur",
+     "local",
+     "repo"
+    ]
+   },
+   "positionals": {
+    "PKG": null
+   }
+  },
+  "packages add-group": {
+   "flags": {
+    "--packages": null
+   },
+   "positionals": {
+    "DESKTOP": [
+     "budgie",
+     "cinnamon",
+     "cosmic",
+     "gnome",
+     "kde",
+     "lxqt",
+     "mate",
+     "xfce"
+    ]
+   }
+  },
+  "packages list": {
+   "flags": {
+    "--orphans": null,
+    "--packages": null
+   },
+   "positionals": {}
+  },
+  "packages remove": {
+   "flags": {
+    "--packages": null
+   },
+   "positionals": {
+    "PKG": null
+   }
+  },
+  "resolve": {
+   "flags": {
+    "--deps": null,
+    "--profile-conf": null,
+    "--show-flags": null
+   },
+   "positionals": {
+    "PKG": null
+   }
+  },
+  "revert-to-stock": {
+   "flags": {
+    "--dry-run": null,
+    "--state-dir": null,
+    "--yes": null
+   },
+   "positionals": {
+    "PKG": null
+   }
+  },
+  "run hardware": {
+   "flags": {
+    "--dry-run": null,
+    "--state-dir": null
+   },
+   "positionals": {}
+  },
+  "run kernel": {
+   "flags": {
+    "--abi-check": null,
+    "--allow-boot-audit-failure": null,
+    "--allow-no-fallback": null,
+    "--autofdo": [
+     "capture",
+     "record",
+     "use"
+    ],
+    "--base-config": null,
+    "--base-config-merge": [
+     "overlay",
+     "replace"
+    ],
+    "--bootloader": [
+     "grub",
+     "none",
+     "systemd-boot"
+    ],
+    "--cache-report": null,
+    "--cleansrc": null,
+    "--cleansrc-force": null,
+    "--dry-run": null,
+    "--log-dir": null,
+    "--no-docs": null,
+    "--no-headers": null,
+    "--no-interactive": null,
+    "--no-keep-hotplug-drivers": null,
+    "--no-pkg-log": null,
+    "--no-update": null,
+    "--persist-log": null,
+    "--profile-conf": null,
+    "--propeller": null,
+    "--state-dir": null,
+    "--toolchain": [
+     "gcc",
+     "llvm"
+    ]
+   },
+   "positionals": {}
+  },
+  "run packages": {
+   "flags": {
+    "--abi-check": null,
+    "--cache-report": null,
+    "--dry-run": null,
+    "--log-dir": null,
+    "--no-pkg-log": null,
+    "--no-update": null,
+    "--packages": null,
+    "--persist-log": null,
+    "--profile-conf": null,
+    "--retry-failed": null,
+    "--state-dir": null
+   },
+   "positionals": {}
+  },
+  "run pipeline": {
+   "flags": {
+    "--abi-check": null,
+    "--cache-report": null,
+    "--dry-run": null,
+    "--log-dir": null,
+    "--no-pkg-log": null,
+    "--no-unified-log": null,
+    "--no-update": null,
+    "--packages": null,
+    "--persist-log": null,
+    "--profile-conf": null,
+    "--resume": null,
+    "--retry-failed": null,
+    "--start-from": null,
+    "--state-dir": null,
+    "--truncate-log": null
+   },
+   "positionals": {}
+  },
+  "run reconfigure": {
+   "flags": {
+    "--dry-run": null,
+    "--packages": null,
+    "--state-dir": null
+   },
+   "positionals": {}
+  },
+  "run toolchain": {
+   "flags": {
+    "--abi-check": null,
+    "--allow-dirty-llvm": null,
+    "--allow-low-build-space": null,
+    "--allow-version-skew": null,
+    "--bolt-only": null,
+    "--cache-report": null,
+    "--cleansrc": null,
+    "--cleansrc-force": null,
+    "--dry-run": null,
+    "--install-only": null,
+    "--makepkg": null,
+    "--no-update": null,
+    "--persist-log": null,
+    "--rebuild-profdata": null,
+    "--rebuild-soname-consumers": [
+     "auto",
+     "off",
+     "prompt"
+    ],
+    "--reuse-built": null,
+    "--state-dir": null,
+    "--yes": null
+   },
+   "positionals": {}
+  },
+  "search": {
+   "flags": {},
+   "positionals": {
+    "TERM": null
+   }
+  },
+  "setup": {
+   "flags": {
+    "--pacman-conf": null,
+    "--preset": [
+     "defaults",
+     "low-friction",
+     "performance",
+     "secure"
+    ]
+   },
+   "positionals": {}
+  },
+  "state boot-entries": {
+   "flags": {
+    "--no-pager": null
+   },
+   "positionals": {}
+  },
+  "state failed": {
+   "flags": {
+    "--clear": null,
+    "--clear-all": null,
+    "--names": null,
+    "--no-pager": null,
+    "--state-dir": null
+   },
+   "positionals": {}
+  },
+  "state forget": {
+   "flags": {
+    "--state-dir": null
+   },
+   "positionals": {
+    "PKG": null
+   }
+  },
+  "state list": {
+   "flags": {
+    "--json": null,
+    "--no-pager": null,
+    "--state-dir": null
+   },
+   "positionals": {}
+  },
+  "state orphans": {
+   "flags": {
+    "--delete": null,
+    "--no-pager": null,
+    "--yes": null
+   },
+   "positionals": {}
+  },
+  "state profiles": {
+   "flags": {
+    "--delete": null,
+    "--no-pager": null,
+    "--state-dir": null,
+    "--yes": null
+   },
+   "positionals": {}
+  },
+  "state repair": {
+   "flags": {
+    "--dry-run": null,
+    "--state-dir": null
+   },
+   "positionals": {}
+  },
+  "uninstall": {
+   "flags": {
+    "--state-dir": null
+   },
+   "positionals": {
+    "PKG": null
+   }
+  },
+  "update": {
+   "flags": {
+    "--cache-report": null,
+    "--cleansrc": null,
+    "--cleansrc-force": null,
+    "--devel": null,
+    "--dry-run": null,
+    "--explain-drift": null,
+    "--include-stage-owned": null,
+    "--install-only": null,
+    "--interactive": null,
+    "--json": null,
+    "--log-dir": null,
+    "--makepkg": null,
+    "--no-cleanbuild": null,
+    "--no-llvm-preflight": null,
+    "--no-pkg-log": null,
+    "--no-review": null,
+    "--no-sysupgrade": null,
+    "--no-sysupgrade-report": null,
+    "--no-toolchain-preflight": null,
+    "--offline": null,
+    "--packages": null,
+    "--persist-log": null,
+    "--profile-conf": null,
+    "--rebuild-on-drift": null,
+    "--rebuild-on-flag-drift": null,
+    "--rebuild-on-toolchain-drift": null,
+    "--review": null,
+    "--state-dir": null,
+    "--sysupgrade": null,
+    "--versions": null,
+    "--yes": null
+   },
+   "positionals": {
+    "PKG": null
+   }
+  }
+ },
+ "environment": [
+  "PAGER",
+  "SYSFORGE_ASCII",
+  "SYSFORGE_CONFIG_DIR",
+  "SYSFORGE_EDITOR",
+  "SYSFORGE_MERGE",
+  "SYSFORGE_PACMAN_NO_PYALPM",
+  "SYSFORGE_PGO_STORE",
+  "SYSFORGE_PROFILE_STORE",
+  "SYSFORGE_PROGRESS_TRACE",
+  "SYSFORGE_PTY_RAW_DUMP",
+  "SYSFORGE_STATE_DIR"
+ ],
+ "journal_fields": [
+  "SYSFORGE_EXIT",
+  "SYSFORGE_TARGET",
+  "SYSFORGE_VERB"
+ ],
+ "config": {
+  "sysforge.toml": {
+   "top_level": [],
+   "sections": {
+    "artifacts": [
+     "roots"
+    ],
+    "aur": [
+     "enabled",
+     "min_fetch_interval_ms",
+     "rate_limit_abort_s"
+    ],
+    "build": [
+     "cpu_quota",
+     "ionice",
+     "jobs",
+     "mem_limit",
+     "nice",
+     "pre_build_snapshot",
+     "python",
+     "repo_track"
+    ],
+    "doctor": [
+     "disk_low_gb",
+     "mirrorlist_stale_days",
+     "pkg_cache_warn_gb"
+    ],
+    "failure_handling": [
+     "checksum_mismatch",
+     "pgp_key_missing",
+     "srcinfo_drift",
+     "vendored_deps_missing"
+    ],
+    "git": [
+     "clone_timeout",
+     "fetch_timeout"
+    ],
+    "log": [
+     "verbosity"
+    ],
+    "mesa": [
+     "filter_drivers",
+     "gallium",
+     "vulkan"
+    ],
+    "pgo": [
+     "allow",
+     "skew_warn_ratio"
+    ],
+    "safety": [
+     "llvm_preflight",
+     "llvm_strict_toolchain"
+    ],
+    "security": [
+     "auto_fetch_pgp_keys",
+     "freeze_sources",
+     "sandbox_builds",
+     "sandbox_chroot_dir",
+     "sandbox_clean",
+     "sandbox_local_repo",
+     "sandbox_update"
+    ],
+    "ui": [
+     "color",
+     "editor",
+     "merge"
+    ],
+    "update": [
+     "rebuild_on_drift",
+     "rebuild_on_flag_drift",
+     "rebuild_on_toolchain_drift"
+    ]
+   }
+  },
+  "profiles.toml": {
+   "top_level": [
+    "extends_system"
+   ],
+   "sections": {
+    "append_conflict_groups": null,
+    "consumes_inference": null,
+    "defaults": [
+     "append_groups",
+     "profile",
+     "toolchain"
+    ],
+    "package_compiler_overrides": null,
+    "paths": [
+     "pkgbuild_src_dir"
+    ],
+    "preserved_system_tokens": null,
+    "profiles": null,
+    "rules": null
+   }
+  },
+  "packages.toml": {
+   "top_level": [],
+   "sections": {
+    "build": [
+     "abi_check",
+     "cache_report",
+     "confirm_plan",
+     "persist_log",
+     "pkgbuild_src_dir",
+     "repo_mode",
+     "review",
+     "review_trusted_sources",
+     "system_upgrade"
+    ],
+    "group": null,
+    "package": null
+   }
+  },
+  "kernel.toml": {
+   "top_level": [
+    "base_config",
+    "base_config_merge",
+    "boot_audit",
+    "boot_entries",
+    "boot_entries_prefix",
+    "bootloader",
+    "build_docs",
+    "build_headers",
+    "capture_lsmod_snapshot",
+    "compiler",
+    "device_kconfig",
+    "enabled",
+    "hardening",
+    "interactive",
+    "kconfig_merge",
+    "kconfig_targets",
+    "keep_hotplug_drivers",
+    "min_boot_free_mb",
+    "pkgbuild_src_dir",
+    "pkgname",
+    "require_fallback_kernel",
+    "source",
+    "srcdir",
+    "upstream_pkgname"
+   ],
+   "sections": {
+    "fdo": [
+     "mode"
+    ],
+    "kconfig": null
+   }
+  },
+  "toolchain.toml": {
+   "top_level": [
+    "compiler",
+    "drift_detect",
+    "enabled",
+    "min_build_free_gb",
+    "pgo",
+    "pgo_staging",
+    "pgo_staging1",
+    "pgo_staging3",
+    "pgo_store",
+    "profile_store",
+    "rebuild_soname_consumers",
+    "require_multilib",
+    "reuse_unchanged",
+    "skip_build"
+   ],
+   "sections": {
+    "bench": [
+     "after_build",
+     "corpus"
+    ],
+    "bolt": [
+     "enabled",
+     "libllvm",
+     "training_workload"
+    ],
+    "llvm": [
+     "targets"
+    ],
+    "packages": [
+     "lib32",
+     "non_pgo",
+     "pgo",
+     "training_corpus"
+    ]
+   }
+  }
+ },
+ "json": {
+  "config-check": [
+   "config_dir",
+   "issues",
+   "issues[].file",
+   "issues[].fix",
+   "issues[].kind",
+   "issues[].line",
+   "issues[].message",
+   "issues[].setting",
+   "kind",
+   "schema"
+  ],
+  "doctor": [
+   "affected",
+   "affected[].issues",
+   "affected[].name",
+   "affected[].tag",
+   "axes",
+   "axes[].errors",
+   "axes[].findings",
+   "axes[].findings[].check_id",
+   "axes[].findings[].fix_cmd",
+   "axes[].findings[].is_brick",
+   "axes[].findings[].message",
+   "axes[].findings[].remediation",
+   "axes[].findings[].severity",
+   "axes[].findings[].subject",
+   "axes[].label",
+   "axes[].name",
+   "axes[].roster",
+   "axes[].roster.ran",
+   "axes[].roster.skipped",
+   "axes[].roster.skipped[].check",
+   "axes[].roster.skipped[].reason",
+   "kind",
+   "schema",
+   "scope"
+  ],
+  "state-list": [
+   "kind",
+   "opted_out",
+   "opted_out[].at",
+   "opted_out[].pkgbase",
+   "opted_out[].pkgnames",
+   "opted_out[].via",
+   "packages",
+   "packages[].build_mode",
+   "packages[].built_at",
+   "packages[].name",
+   "packages[].owner_stage",
+   "packages[].pkgbase",
+   "packages[].pkgbuild_dir",
+   "packages[].source",
+   "packages[].toolchain_variant",
+   "packages[].version",
+   "schema",
+   "untracked_foreign",
+   "untracked_foreign[].name",
+   "untracked_foreign[].version"
+  ],
+  "update-dry-run": [
+   "drift",
+   "drift.flags",
+   "drift.flags.packages",
+   "drift.flags.packages[].diff",
+   "drift.flags.packages[].pkgbase",
+   "drift.flags.rebuild",
+   "drift.toolchain",
+   "drift.toolchain.active",
+   "drift.toolchain.packages",
+   "drift.toolchain.packages[].pkgbase",
+   "drift.toolchain.packages[].reason",
+   "drift.toolchain.packages[].recorded",
+   "drift.toolchain.rebuild",
+   "kind",
+   "offline",
+   "packages",
+   "packages[].action",
+   "packages[].available",
+   "packages[].has_build_record",
+   "packages[].installed",
+   "packages[].pkgbase",
+   "packages[].pkgnames",
+   "packages[].source",
+   "schema",
+   "sync_failures",
+   "sync_failures[].error",
+   "sync_failures[].pkgbase",
+   "sync_failures[].status"
+  ]
+ },
+ "run_logs": [
+  "build",
+  "config-clean",
+  "config-merge",
+  "config-reset",
+  "doctor",
+  "fetch",
+  "revert-to-stock",
+  "run-hardware",
+  "run-kernel",
+  "run-packages",
+  "run-reconfigure",
+  "run-toolchain",
+  "setup",
+  "state-forget",
+  "state-repair",
+  "uninstall",
+  "update"
+ ]
+}
diff --git a/tests/test_build_cmd.py b/tests/test_build_cmd.py
index 3be7918a..e590127a 100644
--- a/tests/test_build_cmd.py
+++ b/tests/test_build_cmd.py
@@ -15,6 +15,8 @@
 
 import pytest
 
+from cli_args import cli_args
+
 import sysforge.build_cmd as build_cmd
 import sysforge.build_core as build_core
 import sysforge.pipeline.state as pipeline_state
@@ -50,13 +52,8 @@ def _fake_build_and_install(targets, **kwargs):
     monkeypatch.setattr(pipeline_state, "get_toolchain_fingerprint", lambda st: None)
     monkeypatch.setattr(pipeline_state, "PipelineState", lambda d: None)
 
-    args = types.SimpleNamespace(
-        makepkg=None, pkgbuilds=[pkgname], cleansrc=False, cleansrc_force=False,
-        no_update=True, interactive=False, profile_conf=None, cc=None, cxx=None,
-        ld=None, state_dir=None, no_pkg_log=True, persist_log=False, log_dir=None,
-        cache_report=False, abi_check=False, no_review=True, timings=False,
-        force=force, rebuild=rebuild,
-    )
+    args = cli_args("build", pkgname, no_update=True, no_pkg_log=True, no_review=True,
+                    force=force, rebuild=rebuild)
     result = BuildVerb().execute(args, PreCheckResult(ctx={"config": config or {}}))
     return captured["targets"], result
 
@@ -94,14 +91,8 @@ def _fake_build_and_install(targets, **kwargs):
     monkeypatch.setattr(pipeline_state, "get_toolchain_fingerprint", lambda st: None)
     monkeypatch.setattr(pipeline_state, "PipelineState", lambda d: None)
 
-    args = types.SimpleNamespace(
-        makepkg=None, pkgbuilds=["wayland-git", "wayland-docs-git"],
-        cleansrc=False, cleansrc_force=False,
-        no_update=True, interactive=False, profile_conf=None, cc=None, cxx=None,
-        ld=None, state_dir=None, no_pkg_log=True, persist_log=False, log_dir=None,
-        cache_report=False, abi_check=False, no_review=True, timings=False,
-        force=True,
-    )
+    args = cli_args("build", "wayland-git", "wayland-docs-git", no_update=True,
+                    no_pkg_log=True, no_review=True, force=True)
     BuildVerb().execute(args, PreCheckResult(ctx={"config": {}}))
 
     assert [t.pkgbase for t in captured["targets"]] == ["wayland-git"]
@@ -262,13 +253,8 @@ def _fake_build_and_install(targets, **kwargs):
     pkg_path.write_text(packages_toml_text)
     cfg = {"packages_file": str(pkg_path)}
 
-    args = types.SimpleNamespace(
-        makepkg=None, pkgbuilds=[pkgname], cleansrc=False, cleansrc_force=False,
-        no_update=True, interactive=False, profile_conf=None, cc=None, cxx=None,
-        ld=None, state_dir=None, no_pkg_log=True, persist_log=False, log_dir=None,
-        cache_report=False, abi_check=False, no_review=True, timings=False,
-        force=force,
-    )
+    args = cli_args("build", pkgname, no_update=True, no_pkg_log=True, no_review=True,
+                    force=force)
     BuildVerb().execute(args, PreCheckResult(ctx={"config": cfg}))
     return captured
 
diff --git a/tests/test_build_core.py b/tests/test_build_core.py
index 12a1c151..998eaa12 100644
--- a/tests/test_build_core.py
+++ b/tests/test_build_core.py
@@ -1434,13 +1434,6 @@ def test_make_build_options_override_wins_over_stage_default():
     assert bo.owner_stage == "other"
 
 
-def test_make_build_options_abi_check_defaults_false_when_absent():
-    """A run-options object lacking abi_check degrades to False, not error."""
-    opts = SimpleNamespace(no_pkg_log=False, persist_log=False, state_dir=None)
-    bo = make_build_options("packages", opts)
-    assert bo.abi_check is False
-    assert bo.pkg_log is True
-
 
 def test_make_build_options_unknown_stage_raises():
     opts = _run_options()
diff --git a/tests/test_check_shipped.py b/tests/test_check_shipped.py
index c2c171bd..41eb8aeb 100644
--- a/tests/test_check_shipped.py
+++ b/tests/test_check_shipped.py
@@ -519,7 +519,7 @@ def _config_dataclass_reads() -> set[str]:
     keys |= {"packages", "bolt", "llvm"}
     # Keys the dataclass carries but resolves through a helper that takes the
     # whole table (asserted separately in the test that calls this).
-    keys |= {"pgo_store", "drift_detect"}
+    keys |= {"pgo_store", "drift_detect", "profile_store"}
     # [bolt]/[packages] member keys belong to their section, not the top level.
     return keys - {"enabled", "libllvm", "training_workload", "pgo", "non_pgo",
                    "lib32", "training_corpus"} | {"enabled", "pgo"}
@@ -563,7 +563,7 @@ def test_toolchain_allowlist_matches_stage_reads(self):
         compared as sets instead of one-way containment plus a hand-maintained
         set of helper exemptions.
 
-        Two keys are still resolved elsewhere, by helpers that take the whole
+        Three keys are still resolved elsewhere, by helpers that take the whole
         table by design, and the indirection is asserted rather than assumed.
         """
         cs = _load_check_shipped()
@@ -576,6 +576,9 @@ def test_toolchain_allowlist_matches_stage_reads(self):
         # wrapper's orphan-profraw guard.
         helper = (REPO / "sysforge/primitives/makepkg_pgo.py").read_text()
         assert 'get("pgo_store")' in helper
+        # profile_store likewise, in resolve_profile_store_root(raw), the root of
+        # the pgo/autofdo/propeller/bolt stores (allowlisted by 3.5.0-F18).
+        assert 'get("profile_store")' in helper
         # drift_detect configures *update*'s same-variant drift fingerprint, not
         # anything the toolchain stage does; ToolchainConfig carries it so the
         # key is not orphaned, and config.resolve_drift_detect is the reader.
@@ -1149,3 +1152,54 @@ def test_no_shipped_profile_lists_a_flag_every_build_strips(cfg_dir):
     offenders = {name: sorted(set(prof.get("makepkg_flags", [])) & BATCH_STRIP_FLAGS)
                  for name, prof in data.get("profiles", {}).items()}
     assert {n: f for n, f in offenders.items() if f} == {}
+
+
+# ---------------------------------------------------------------------------
+# completion_commands (3.5.0-DEV14)
+# ---------------------------------------------------------------------------
+
+_REAL = Path(__file__).resolve().parent.parent
+
+
+def _completion_repo(tmp_path, edit=None):
+    """A repo whose completion scripts are the real ones, optionally edited."""
+    shutil.copytree(_REAL / "completions", tmp_path / "completions")
+    shutil.copytree(_REAL / "etc/sysforge", tmp_path / "etc/sysforge")
+    if edit:
+        script, old, new = edit
+        path = tmp_path / "completions" / script
+        text = path.read_text()
+        assert old in text, old
+        path.write_text(text.replace(old, new, 1))
+    return tmp_path
+
+
+def _completion_findings(repo):
+    return [f.message for f in _load_check_shipped().check_completion_commands(repo)]
+
+
+def test_completion_commands_clean_against_real_repo(tmp_path):
+    assert _completion_findings(_completion_repo(tmp_path)) == []
+
+
+@pytest.mark.parametrize("edit, expect", [
+    # a subcommand's flag dropped from its own zsh function
+    (("_sysforge", "'--delete[delete one profile store", "'--nope[delete one profile store"),
+     "state profiles: --delete not offered in _sysforge_state_profiles"),
+    # the same in bash's case arm
+    (("sysforge.bash", '"--delete --yes --no-pager --state-dir"', '"--yes --no-pager --state-dir"'),
+     "state profiles: --delete not offered"),
+    # a flag the command no longer has, still offered
+    (("sysforge.bash", '"--state-dir --dry-run" -- "$cur"',
+      '"--state-dir --dry-run --prune" -- "$cur"'),
+     "state repair: offers --prune"),
+    # a choice value missing from bash's value case (3.5.0-B127's shape)
+    (("sysforge.bash", 'compgen -W "prompt auto off"', 'compgen -W "auto"'),
+     "run toolchain --rebuild-soname-consumers: value 'prompt' not offered"),
+    # a hand-copied list drifting from its code constant
+    (("_sysforge", ":store:(instr-pgo pgo autofdo propeller bolt)", ":store:(pgo autofdo)"),
+     "list differs from makepkg_pgo.PROFILE_METHODS"),
+])
+def test_completion_commands_flags(tmp_path, edit, expect):
+    found = _completion_findings(_completion_repo(tmp_path, edit))
+    assert any(expect in m for m in found), found
diff --git a/tests/test_check_standards_claude_md.py b/tests/test_check_standards_claude_md.py
index 5e6ceed5..a3a499de 100644
--- a/tests/test_check_standards_claude_md.py
+++ b/tests/test_check_standards_claude_md.py
@@ -63,6 +63,17 @@ def test_missing_path_citation_is_error(tmp_path):
                for f in findings), findings
 
 
+def test_gitignored_generated_path_passes_when_absent(tmp_path):
+    """A clean checkout has no `man/sysforge.1.scd`; a dev tree does. The verdict
+    must not depend on which one runs the check."""
+    import subprocess
+    repo = _repo(tmp_path, "Rendered from `man/sysforge.1.scd` and `man/gone.scd`.\n",
+                 {".gitignore": "man/sysforge.1.scd\n"})
+    subprocess.run(["git", "init", "-q", str(repo)], check=True)
+    findings = check_standards.check_claude_md(repo)
+    assert [f.message for f in findings] == ["cites path `man/gone.scd` which does not exist"]
+
+
 def test_sysforge_relative_path_resolves(tmp_path):
     """`primitives/paths.py` is cited repo-root-relative to sysforge/."""
     repo = _repo(tmp_path, "User paths -> `primitives/paths.py`.\n",
@@ -104,7 +115,11 @@ def test_unresolvable_tokens_are_skipped(tmp_path):
         "`docs/design/*.md`; never `os.environ[\"BUILDDIR\"]`; id `1.2.0-F1`;\n"
         "`vX.Y.Z.md`; `emit_makepkg_conf(is_lib32=)`; `[bolt] enabled = false`.\n"
     )
-    repo = _repo(tmp_path, body)
+    # A bare callee is checked against the code (3.5.0-DEV15), so the fixture
+    # defines it; the call syntax around it is what this case tolerates.
+    repo = _repo(tmp_path, body, {"sysforge/primitives/makepkg_conf.py":
+                                  "def emit_makepkg_conf(is_lib32=False):\n    pass\n"})
+    check_standards._CODE_WORDS.clear()
     assert check_standards.check_claude_md(repo) == []
 
 
diff --git a/tests/test_cli.py b/tests/test_cli.py
index 071525e1..73e21e1b 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -31,6 +31,7 @@
     _resolve_verbosity,
 )
 from sysforge.build.makepkg_wrapper import expand_makepkg_flags
+from cli_args import cli_args
 
 
 # ---------------------------------------------------------------------------
@@ -393,10 +394,17 @@ def test_implicit_preserves_tokens_before_subcommand():
 # CLI-entry sentinel check skip on --dry-run
 # ---------------------------------------------------------------------------
 
+# A minimal real command line per command the gate tests use.
+_GATE_ARGV = {"build": ["build", "x"], "update": ["update"], "run": ["run", "toolchain"],
+              "setup": ["setup"], "env": ["env"], "doctor": ["doctor", "system"],
+              "resolve": ["resolve", "x"], "fetch": ["fetch", "x"],
+              "completions": ["completions", "packages"], "log": ["log"],
+              "packages": ["packages", "list"], "state": ["state", "list"]}
+
+
 def _gate_args(*, command, dry_run):
-    """Minimal args namespace for the sentinel-gate condition."""
-    from types import SimpleNamespace
-    return SimpleNamespace(command=command, dry_run=dry_run, state_dir=None)
+    """The parsed command line for the sentinel-gate condition."""
+    return cli_args(*_GATE_ARGV[command], *(["--dry-run"] if dry_run else []))
 
 
 def test_dry_run_skips_entry_sentinel_check():
@@ -407,7 +415,8 @@ def test_dry_run_skips_entry_sentinel_check():
     outer CLI gate should match so the two stay in sync.
     """
     from sysforge.cli import _gate_sentinel_check
-    for cmd in ("build", "update", "run", "setup"):
+    # build and setup have no --dry-run, so only these two can be read-only here.
+    for cmd in ("update", "run"):
         assert _gate_sentinel_check(_gate_args(command=cmd, dry_run=True)) is False
 
 
diff --git a/tests/test_completions_speed.py b/tests/test_completions_speed.py
index a8cb5088..b91a0660 100644
--- a/tests/test_completions_speed.py
+++ b/tests/test_completions_speed.py
@@ -19,6 +19,8 @@
 
 import pytest
 
+from cli_args import cli_args
+
 import sysforge.completions_data as completions_data
 
 _ROOT = Path(__file__).resolve().parent.parent
@@ -93,8 +95,7 @@ def _probe(argv, **_kw):
 
 
 def _emit(capsys, resource="packages", prefix="", limit=0) -> list[str]:
-    completions_data.emit(types.SimpleNamespace(resource=resource, prefix=prefix,
-                                                limit=limit))
+    completions_data.emit(cli_args("completions", resource, prefix=prefix, limit=limit))
     return capsys.readouterr().out.splitlines()
 
 
diff --git a/tests/test_concept_pages.py b/tests/test_concept_pages.py
new file mode 100644
index 00000000..1779e859
--- /dev/null
+++ b/tests/test_concept_pages.py
@@ -0,0 +1,58 @@
+# SPDX-FileCopyrightText: 2026 Keith Raghubar
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Concept pages explain the technique, not sysforge (3.5.0-DEV16).
+
+The rule in CLAUDE.md: no sysforge vocabulary outside the closing "In sysforge"
+section, and upstream sources cited. It was review-only; this pins the parts a
+test can see. Upstream tools' own flags (makepkg's --nocheck, the linker's
+--emit-relocs) are the technique and stay allowed. The glossary defines both
+kinds of term on purpose and is exempt.
+"""
+import re
+from pathlib import Path
+
+import pytest
+
+CONCEPTS = Path(__file__).resolve().parent.parent / "docs/concepts"
+PAGES = sorted(p for p in CONCEPTS.glob("*.md") if p.name != "glossary.md")
+
+# sysforge's own vocabulary: its name, its config files, its state file.
+_SYSFORGE_TERMS = re.compile(
+    r"\bsysforge\b|\b(?:profiles|toolchain|kernel|packages|bootstrap)\.toml\b|\bbuild_state\b",
+    re.IGNORECASE)
+
+
+def _sections(text):
+    return re.findall(r"^## (.+)$", text, re.MULTILINE)
+
+
+@pytest.mark.parametrize("page", PAGES, ids=lambda p: p.name)
+def test_page_closes_with_further_reading_then_in_sysforge(page):
+    assert _sections(page.read_text(encoding="utf-8"))[-2:] == ["Further reading", "In sysforge"]
+
+
+@pytest.mark.parametrize("page", PAGES, ids=lambda p: p.name)
+def test_further_reading_cites_upstream_sources(page):
+    text = page.read_text(encoding="utf-8")
+    further = text.split("\n## Further reading", 1)[1].split("\n## In sysforge", 1)[0]
+    assert re.search(r"\]\(https?://", further), "cite at least one upstream source"
+
+
+@pytest.mark.parametrize("page", PAGES, ids=lambda p: p.name)
+def test_no_sysforge_vocabulary_before_in_sysforge(page):
+    text = page.read_text(encoding="utf-8")
+    body = text.split("\n## In sysforge", 1)[0]
+    # The page title may name the guide it belongs beside; judge the body.
+    body = body.split("\n", 1)[1] if body.startswith("# ") else body
+    bad = [f"{page.name}:{n}: {line.strip()[:80]}"
+           for n, line in enumerate(body.splitlines(), 2) if _SYSFORGE_TERMS.search(line)]
+    assert not bad, "sysforge terms belong in the 'In sysforge' section:\n  " + "\n  ".join(bad)
+
+
+def test_the_check_sees_a_leak():
+    assert _SYSFORGE_TERMS.search("set it in profiles.toml")
+    assert _SYSFORGE_TERMS.search("sysforge rebuilds it")
+    assert not _SYSFORGE_TERMS.search("makepkg --nocheck skips check()")
diff --git a/tests/test_config_keys_documented.py b/tests/test_config_keys_documented.py
new file mode 100644
index 00000000..5cd4d42e
--- /dev/null
+++ b/tests/test_config_keys_documented.py
@@ -0,0 +1,116 @@
+# SPDX-FileCopyrightText: 2026 Keith Raghubar
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Every config key the code reads is documented in the shipped default (3.5.0-F18).
+
+`sysforge config check` counts a key in a fixed section as valid when the
+shipped default documents it, so a key the code reads but the default never
+mentions would be reported as unknown, and `config clean --unknown` would
+delete a working setting. `toolchain.toml`'s `profile_store` and
+`profiles.toml`'s `extends_system` were both read and undocumented.
+
+The scan finds section reads off a config-like object (a name containing cfg,
+config, conf, toml, data or raw, or a load_*() call): `cfg.get("ui", {})
+.get("editor")`, `cfg["build"]["jobs"]`, and `.get`/`[]` on a local assigned
+from such a section in the same function. The typed stage configs' top-level
+keys have their own tests (tests/test_check_shipped.py); this adds the
+fixed-section keys and the schema's top-level keys.
+"""
+import ast
+import collections
+import re
+from pathlib import Path
+
+from sysforge.primitives import config_schema as cs
+
+PKG = Path(__file__).resolve().parent.parent / "sysforge"
+_CONFIGISH = re.compile(r"cfg|config|conf|toml|data|raw", re.IGNORECASE)
+
+
+def _fixed_sections() -> dict[str, set[str]]:
+    """Section -> the live config files where it is a fixed (not user-named) one."""
+    out: dict[str, set[str]] = collections.defaultdict(set)
+    for name in cs.CONFIG_FILES:
+        for section in cs.KNOWN_SECTIONS[name] - cs.OPEN_SECTIONS.get(name, set()):
+            out[section].add(name)
+    return out
+
+
+def _configish(base) -> bool:
+    if isinstance(base, ast.Call):
+        name = getattr(base.func, "id", None) or getattr(base.func, "attr", "")
+        return name.startswith("load") or bool(_CONFIGISH.search(name))
+    return bool(_CONFIGISH.search(getattr(base, "id", None) or getattr(base, "attr", None) or ""))
+
+
+def _section_of(expr, sections) -> str | None:
+    if isinstance(expr, ast.BoolOp):                  # cfg.get("ui") or {}
+        expr = expr.values[0]
+    if isinstance(expr, ast.Call) and getattr(expr.func, "attr", None) == "get":
+        base, key = expr.func.value, expr.args[0] if expr.args else None
+    elif isinstance(expr, ast.Subscript):
+        base, key = expr.value, expr.slice
+    else:
+        return None
+    if (isinstance(key, ast.Constant) and key.value in sections and _configish(base)):
+        return key.value
+    return None
+
+
+def section_reads(text: str, sections) -> set[tuple[str, str, int]]:
+    """(section, key, line) for each fixed-section key read in ``text``."""
+    out = set()
+    for fn in (n for n in ast.walk(ast.parse(text)) if isinstance(n, ast.FunctionDef)):
+        local = {}
+        for n in ast.walk(fn):
+            if isinstance(n, ast.Assign) and len(n.targets) == 1 \
+                    and isinstance(n.targets[0], ast.Name):
+                section = _section_of(n.value, sections)
+                if section:
+                    local[n.targets[0].id] = section
+        for n in ast.walk(fn):
+            if isinstance(n, ast.Call) and getattr(n.func, "attr", None) == "get" and n.args \
+                    and isinstance(n.args[0], ast.Constant) and isinstance(n.args[0].value, str):
+                holder, key = n.func.value, n.args[0].value
+            elif isinstance(n, ast.Subscript) and isinstance(n.slice, ast.Constant) \
+                    and isinstance(n.slice.value, str):
+                holder, key = n.value, n.slice.value
+            else:
+                continue
+            section = _section_of(holder, sections) or (
+                local.get(holder.id) if isinstance(holder, ast.Name) else None)
+            if section:
+                out.add((section, key, n.lineno))
+    return out
+
+
+def test_every_fixed_section_key_the_code_reads_is_documented():
+    sections = _fixed_sections()
+    documented = {name: cs._documented(cs.shipped_text(name)) for name in cs.CONFIG_FILES}
+    reads, undocumented = 0, []
+    for py in sorted(PKG.rglob("*.py")):
+        for section, key, line in section_reads(py.read_text(encoding="utf-8"), sections):
+            reads += 1
+            if not any(key in documented[f].get(section, set()) for f in sections[section]):
+                undocumented.append(f"{py.relative_to(PKG.parent)}:{line}: [{section}] {key}")
+    assert reads >= 20, f"the scan found only {reads} reads; it has stopped seeing the code"
+    assert not undocumented, ("document these in the shipped default (active or as a "
+                              "commented example):\n  " + "\n  ".join(sorted(undocumented)))
+
+
+def test_every_known_top_level_key_is_documented():
+    for name in ("kernel.toml", "toolchain.toml", "profiles.toml"):
+        documented = cs._documented(cs.shipped_text(name)).get("", set())
+        assert cs.KNOWN_TOP_KEYS[name] <= documented, (name, cs.KNOWN_TOP_KEYS[name] - documented)
+
+
+def test_the_scan_sees_chained_and_local_reads():
+    src = ('def f(cfg, entry):\n'
+           '    a = cfg.get("ui", {}).get("editor")\n'
+           '    build = cfg.get("build") or {}\n'
+           '    b = build.get("jobs")\n'
+           '    c = entry.get("ui", {}).get("not_config")\n')   # entry is no config
+    assert {(s, k) for s, k, _ in section_reads(src, {"ui", "build"})} == {
+        ("ui", "editor"), ("build", "jobs")}
diff --git a/tests/test_config_schema.py b/tests/test_config_schema.py
new file mode 100644
index 00000000..5a77711e
--- /dev/null
+++ b/tests/test_config_schema.py
@@ -0,0 +1,210 @@
+# SPDX-FileCopyrightText: 2026 Keith Raghubar
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Live-config checking and repair (3.5.0-F18): `config check`, `config clean`,
+`config reset` and the `doctor system --config` axis, over
+primitives/config_schema.py.
+"""
+import shutil
+import tomllib
+from pathlib import Path
+
+import pytest
+
+from sysforge import config_cmd
+from sysforge.primitives import config_schema as cs
+from sysforge.verbs.registry import build_parser
+
+REPO = Path(__file__).resolve().parent.parent
+SHIPPED = REPO / "etc/sysforge"
+
+
+def _kinds(name, text):
+    return [(i.kind, i.where) for i in cs.inspect_text(name, text)]
+
+
+# --- the schema against the shipped files -----------------------------------
+
+@pytest.mark.parametrize("d", [SHIPPED, REPO / "tests/data/etc/sysforge"])
+def test_shipped_and_fixture_configs_are_clean(d):
+    assert cs.inspect(d) == []
+
+
+@pytest.mark.parametrize("name", ["kernel.toml", "toolchain.toml"])
+def test_every_documented_top_level_key_is_known(name):
+    """A key the shipped file documents (even commented out) is a real setting;
+    toolchain.toml's reuse_unchanged was missing from the list until F18."""
+    documented = cs._documented(cs.shipped_text(name))[""]
+    assert documented <= cs.KNOWN_TOP_KEYS[name]
+
+
+def test_retired_replacements_are_current_names():
+    for r in cs.RETIRED_KEYS:
+        assert r.replacement and r.replacement in (SHIPPED / r.file).read_text()
+    for v in cs.RETIRED_VALUES:
+        assert v.new in (SHIPPED / v.file).read_text()
+
+
+def test_defaults_ship_in_the_wheel():
+    pyproject = tomllib.loads((REPO / "pyproject.toml").read_text())
+    include = pyproject["tool"]["hatch"]["build"]["targets"]["wheel"]["force-include"]
+    assert include["etc/sysforge"] == "sysforge/_data/config-defaults"
+
+
+# --- inspection ---------------------------------------------------------------
+
+def test_retired_key_and_value_are_reported():
+    assert ("retired_key", "[git] pull_timeout") in _kinds(
+        "sysforge.toml", "[git]\npull_timeout = 45\n")
+    assert ("retired_value", "[build] repo_mode") in _kinds(
+        "packages.toml", '[build]\nrepo_mode = "profiled"\n')
+    assert ("retired_value", "[profiles.mine] build_mode") in _kinds(
+        "profiles.toml", '[profiles.mine]\nbuild_mode = "patched_pkgbuild"\n')
+    assert ("retired_key", "[package] pkgbuild_patch") in _kinds(
+        "packages.toml", '[[package]]\nname = "x"\npkgbuild_patch = true\n')
+
+
+def test_unknown_keys_in_fixed_sections_but_not_in_open_ones():
+    assert _kinds("sysforge.toml", '[ui]\ncolr = "never"\n') == [("unknown_key", "[ui] colr")]
+    assert _kinds("sysforge.toml", "[nosuch]\nx = 1\n") == [("unknown_section", "[nosuch]")]
+    assert _kinds("toolchain.toml", "enabld = true\n") == [("unknown_key", "enabld")]
+    # User-named: a profile's flag variables, a rule, a package entry.
+    assert _kinds("profiles.toml", '[profiles.mine]\nMY_VAR = "1"\n') == []
+    assert _kinds("packages.toml", '[[package]]\nname = "x"\nanything = 1\n') == []
+
+
+def test_a_commented_example_counts_as_known():
+    assert _kinds("toolchain.toml", "reuse_unchanged = true\n") == []
+
+
+def test_unparsable_file_is_one_parse_error():
+    [(kind, _)] = _kinds("sysforge.toml", "[ui\n")
+    assert kind == "parse_error"
+
+
+# --- clean --------------------------------------------------------------------
+
+def test_clean_renames_a_retired_key_and_keeps_comments():
+    text = "[git]\n# my note\npull_timeout = 45  # trailing\n"
+    new, fixed = cs.clean_text("sysforge.toml", text, unknown=False)
+    assert new == "[git]\n# my note\nfetch_timeout = 45  # trailing\n"
+    assert fixed[0][1] == "renamed to fetch_timeout"
+
+
+def test_clean_drops_a_retired_key_whose_replacement_is_set():
+    text = "[git]\nfetch_timeout = 30\npull_timeout = 45\n"
+    new, fixed = cs.clean_text("sysforge.toml", text, unknown=False)
+    assert new == "[git]\nfetch_timeout = 30\n"
+    assert "already set" in fixed[0][1]
+
+
+def test_clean_renames_within_each_array_table_entry():
+    text = ('[[package]]\nname = "a"\npkgbuild_patch = true\n'
+            '[[package]]\nname = "b"\nenable_build_from_source = false\npkgbuild_patch = true\n')
+    new, _ = cs.clean_text("packages.toml", text, unknown=False)
+    assert tomllib.loads(new)["package"] == [
+        {"name": "a", "enable_build_from_source": True},
+        {"name": "b", "enable_build_from_source": False}]
+
+
+def test_clean_rewrites_a_retired_value():
+    new, _ = cs.clean_text("profiles.toml",
+                           '[profiles.mine]\nbuild_mode = "patched_pkgbuild"  # x\n',
+                           unknown=False)
+    assert new == '[profiles.mine]\nbuild_mode = "source_built"  # x\n'
+
+
+def test_clean_leaves_unknown_keys_unless_asked():
+    text = '[ui]\ncolr = [\n  "a",\n  "b",\n]\ncolor = "auto"\n[nosuch]\nx = 1\n'
+    assert cs.clean_text("sysforge.toml", text, unknown=False) == (text, [])
+    new, fixed = cs.clean_text("sysforge.toml", text, unknown=True)
+    assert new == '[ui]\ncolor = "auto"\n'   # the whole multi-line array, and [nosuch]
+    assert len(fixed) == 2
+
+
+def test_clean_refuses_an_unparsable_file():
+    with pytest.raises(cs.ConfigEditError):
+        cs.clean_text("sysforge.toml", "[ui\n", unknown=True)
+
+
+# --- reset --------------------------------------------------------------------
+
+def test_reset_key_to_an_active_shipped_value():
+    shipped = tomllib.loads(cs.shipped_text("sysforge.toml"))["git"]["fetch_timeout"]
+    new, changes = cs.reset_keys_text("sysforge.toml", "[git]\nfetch_timeout = 999\n",
+                                      ["git.fetch_timeout"])
+    assert tomllib.loads(new)["git"]["fetch_timeout"] == shipped
+    assert changes == ["git.fetch_timeout: set to the shipped value"]
+
+
+def test_reset_key_the_default_leaves_unset_removes_it():
+    new, changes = cs.reset_keys_text("sysforge.toml", "[build]\njobs = 3\n", ["build.jobs"])
+    assert "jobs" not in tomllib.loads(new)["build"]
+    assert "removed" in changes[0]
+
+
+def test_reset_adds_a_missing_shipped_key_to_its_section():
+    new, _ = cs.reset_keys_text("sysforge.toml", "[git]\n", ["git.fetch_timeout"])
+    assert "fetch_timeout" in tomllib.loads(new)["git"]
+
+
+def test_reset_refuses_array_table_keys():
+    with pytest.raises(cs.ConfigEditError):
+        cs.reset_keys_text("packages.toml", '[[package]]\nname = "x"\n', ["package.name"])
+
+
+# --- the verbs ----------------------------------------------------------------
+
+def _live(tmp_path):
+    for name in cs.CONFIG_FILES:
+        shutil.copy(SHIPPED / name, tmp_path / name)
+    return tmp_path
+
+
+def _args(*argv):
+    return build_parser().parse_args(["config", *argv])
+
+
+def test_check_exits_1_on_findings_and_0_when_clean(tmp_path):
+    d = _live(tmp_path)
+    assert config_cmd.cmd_config_check(_args("check", "--config-dir", str(d))) == 0
+    (d / "sysforge.toml").write_text((d / "sysforge.toml").read_text()
+                                     .replace("[git]", "[git]\npull_timeout = 1", 1))
+    assert config_cmd.cmd_config_check(_args("check", "--config-dir", str(d))) == 1
+
+
+def test_clean_without_a_terminal_needs_yes(tmp_path, monkeypatch):
+    d = _live(tmp_path)
+    path = d / "sysforge.toml"
+    path.write_text(path.read_text().replace("[ui]", "[ui]\ncolr = 1", 1))
+    before = path.read_text()
+    monkeypatch.setattr(config_cmd.prompt, "is_interactive", lambda: False)
+    argv = ["clean", "--unknown", "--config-dir", str(d)]
+    assert config_cmd.cmd_config_clean(_args(*argv)) == 2
+    assert config_cmd.cmd_config_clean(_args(*argv, "--dry-run")) == 0
+    assert path.read_text() == before
+    assert config_cmd.cmd_config_clean(_args(*argv, "--yes")) == 0
+    assert "colr" not in path.read_text()
+
+
+def test_reset_whole_file_keeps_a_backup(tmp_path):
+    d = _live(tmp_path)
+    path = d / "kernel.toml"
+    path.write_text(path.read_text() + "\n# mine\n")
+    assert config_cmd.cmd_config_reset(_args("reset", "kernel.toml", "--config-dir", str(d),
+                                              "--yes")) == 0
+    assert path.read_text() == (SHIPPED / "kernel.toml").read_text()
+    [backup] = d.glob("kernel.toml.bak-*")
+    assert backup.read_text().endswith("# mine\n")
+
+
+def test_doctor_config_axis_reports_retired_settings(tmp_path, monkeypatch):
+    from sysforge import doctor
+    d = _live(tmp_path)
+    (d / "packages.toml").write_text('[build]\nrepo_mode = "profiled"\n')
+    monkeypatch.setattr("sysforge.primitives.paths.CONFIG_DIR", d)
+    result = doctor._collect_config_findings()
+    [finding] = result.findings
+    assert finding.severity == "warn" and finding.remediation == "sysforge config clean"
diff --git a/tests/test_doctor.py b/tests/test_doctor.py
index 89cf9481..3a7fd8ff 100644
--- a/tests/test_doctor.py
+++ b/tests/test_doctor.py
@@ -1908,11 +1908,9 @@ def test_rust_axis_is_opt_in(monkeypatch):
 
 def test_rust_flag_selects_only_rust_axis():
     from sysforge import doctor
-    from types import SimpleNamespace
-    args = SimpleNamespace(packages=[], repo=False, rust=True,
-                           **{a: False for a in doctor._AXIS_FLAGS
-                              if a != "rust"})
-    # every other axis flag defaults False; only --rust set
+    from cli_args import cli_args
+    args = cli_args("doctor", "pkg", "--rust")
+    # every other axis flag keeps its real default; only --rust set
     names = doctor._resolve_axis_names(args)
     assert names == ["rust"]
 
diff --git a/tests/test_doctor_roster.py b/tests/test_doctor_roster.py
index a1ed280f..cbf66a4e 100644
--- a/tests/test_doctor_roster.py
+++ b/tests/test_doctor_roster.py
@@ -34,6 +34,7 @@ def _args(**kw):
     "gfxperf": doctor._collect_gfxperf_findings,
     "pacman": doctor._collect_pacman_findings,
     "state": doctor._collect_state_findings,
+    "config": doctor._collect_config_findings,
     "boot": doctor._collect_boot_findings,
     "restart": doctor._collect_restart_findings,
     "storage": doctor._collect_storage_findings,
@@ -140,3 +141,22 @@ def test_render_no_longer_says_not_reported(monkeypatch, capsys):
     out = "".join(capsys.readouterr())
     assert "not reported by this axis" not in out
     assert "default_route" in out
+
+
+def test_system_help_names_every_default_axis_and_their_count():
+    """`doctor system --help` lists the sweep's axes and says how many run;
+    adding the config axis (3.5.0-F18) showed both were hand-kept."""
+    import argparse
+    import re
+
+    from sysforge import doctor
+    from sysforge.verbs.registry import build_parser
+    sub = next(a for a in build_parser()._actions if isinstance(a, argparse._SubParsersAction))
+    doctor_p = sub.choices["doctor"]
+    group = next(a for a in doctor_p._actions if isinstance(a, argparse._SubParsersAction))
+    help_text = next(c.help for c in group._choices_actions if c.dest == "system")
+    defaults = [a for a in doctor._SYSTEM_AXIS_ORDER
+                if a not in doctor._OPT_IN_AXES and a != "abi"]
+    listed = re.search(r"axes: ([^.]+)\.", help_text).group(1).replace(" ", "").split(",")
+    assert sorted(listed) == sorted(defaults)
+    assert f"all {len(defaults)} non-opt-in axes" in help_text
diff --git a/tests/test_env_vars.py b/tests/test_env_vars.py
new file mode 100644
index 00000000..51140c14
--- /dev/null
+++ b/tests/test_env_vars.py
@@ -0,0 +1,69 @@
+# SPDX-FileCopyrightText: 2026 Keith Raghubar
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Every environment variable and journal field sysforge uses is registered
+(3.5.0-B128, 3.5.0-DOC13), and the man page is generated from the registry.
+
+Before primitives/env_vars.py the man page listed three of the eleven
+variables, with a stale editor order and pager flags; SYSFORGE_PROFILE_STORE
+was documented nowhere, and the journal fields not at all.
+"""
+import ast
+from pathlib import Path
+
+from sysforge.primitives.env_vars import ENV_VARS
+from sysforge.primitives.journal import JOURNAL_FIELDS
+
+REPO = Path(__file__).resolve().parent.parent
+
+# SYSFORGE_* strings that are not names sysforge reads: heredoc delimiters in
+# the PKGBUILD text llvm_std_exports generates.
+_NOT_NAMES = {"SYSFORGE_CMAKE", "SYSFORGE_TU"}
+
+
+def _sysforge_strings():
+    """(where, value) for each SYSFORGE_* string literal under sysforge/."""
+    for py in sorted((REPO / "sysforge").rglob("*.py")):
+        tree = ast.parse(py.read_text(encoding="utf-8"))
+        for node in ast.walk(tree):
+            if (isinstance(node, ast.Constant) and isinstance(node.value, str)
+                    and node.value.startswith("SYSFORGE_")
+                    and node.value.replace("_", "").isalnum()
+                    and node.value.isupper()):
+                yield f"{py.relative_to(REPO)}:{node.lineno}", node.value
+
+
+def test_every_sysforge_name_in_the_code_is_registered():
+    known = {v.name for v in ENV_VARS} | {f for f, _ in JOURNAL_FIELDS} | _NOT_NAMES
+    bad = [f"{where}: {name}" for where, name in _sysforge_strings() if name not in known]
+    assert not bad, ("register these in primitives/env_vars.ENV_VARS "
+                     "(or journal.JOURNAL_FIELDS):\n  " + "\n  ".join(bad))
+
+
+def test_every_registered_variable_is_read_somewhere():
+    """A stale entry documents a variable that no longer does anything."""
+    used = {name for _, name in _sysforge_strings()}
+    source = "".join(p.read_text(encoding="utf-8")
+                     for p in (REPO / "sysforge").rglob("*.py")
+                     if p.name != "env_vars.py")
+    stale = [v.name for v in ENV_VARS
+             if v.name not in used and f'"{v.name}"' not in source]
+    assert not stale, f"registered but never read: {stale}"
+
+
+def test_registry_shape():
+    names = [v.name for v in ENV_VARS]
+    assert len(names) == len(set(names))
+    assert {v.audience for v in ENV_VARS} <= {"user", "diagnostic"}
+    assert all(v.text.endswith(".") for v in ENV_VARS)
+
+
+def test_man_page_lists_every_variable_and_journal_field():
+    man = (REPO / "man/sysforge.1.scd.in").read_text(encoding="utf-8")
+    assert "@ENVIRONMENT@" in man and "@JOURNAL@" in man
+    rendered = (REPO / "man/sysforge.1").read_text(encoding="utf-8")
+    missing = [n for n in [v.name for v in ENV_VARS] + [f for f, _ in JOURNAL_FIELDS]
+               if n.replace("_", "\\_") not in rendered and n not in rendered]
+    assert not missing, f"not in man/sysforge.1 (run `make man`): {missing}"
diff --git a/tests/test_flags_reach_code.py b/tests/test_flags_reach_code.py
new file mode 100644
index 00000000..3f2e6854
--- /dev/null
+++ b/tests/test_flags_reach_code.py
@@ -0,0 +1,124 @@
+# SPDX-FileCopyrightText: 2026 Keith Raghubar
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Every parsed flag reaches the code that acts on it (3.5.0-DEV17).
+
+`run kernel --keep-hotplug-drivers` (3.5.0-B129) was parsed, then read by the
+stage as ``getattr(options, "keep_hotplug_drivers", None)`` off a RunOptions
+that had no such field, so the read always returned the default. Two checks
+cover that shape for every command:
+
+* a field read on an options object, by attribute or by ``getattr`` with a
+  literal name, is a real RunOptions or BuildOptions field;
+* every command's parsed flag is read through its argument object somewhere in
+  the package (``args.x``, ``run.args.x``, ``getattr(args, "x")``, ...), or by
+  one of the few indirect readers named below.
+"""
+import argparse
+import ast
+import dataclasses
+import re
+from pathlib import Path
+
+from sysforge.build.makepkg_wrapper import BuildOptions
+from sysforge.pipeline.stages.base import RunOptions
+from sysforge.verbs.registry import build_parser
+
+PKG = Path(__file__).resolve().parent.parent / "sysforge"
+_OPTION_NAMES = {"options", "opts", "run_options", "build_options"}
+
+
+def _sources():
+    return {p: p.read_text(encoding="utf-8") for p in sorted(PKG.rglob("*.py"))}
+
+
+def _bad_option_reads(text: str, where: str) -> list[str]:
+    """Reads of a name that is no RunOptions/BuildOptions field, off an object
+    named like an options object."""
+    fields = {f.name for cls in (BuildOptions, RunOptions) for f in dataclasses.fields(cls)}
+    tree = ast.parse(text)
+    called = {id(n.func) for n in ast.walk(tree) if isinstance(n, ast.Call)}
+    bad = []
+    for node in ast.walk(tree):
+        target: ast.AST | None = None
+        name = ""
+        if (isinstance(node, ast.Call) and getattr(node.func, "id", None) == "getattr"
+                and len(node.args) >= 2 and isinstance(node.args[1], ast.Constant)
+                and isinstance(node.args[1].value, str)):
+            target, name = node.args[0], node.args[1].value
+        elif (isinstance(node, ast.Attribute) and isinstance(node.ctx, ast.Load)
+                and id(node) not in called):      # `options.append(...)` is a list
+            target, name = node.value, node.attr
+        holder = getattr(target, "id", None) or getattr(target, "attr", None)
+        if holder in _OPTION_NAMES and name not in fields and not name.startswith("_"):
+            bad.append(f"{where}:{getattr(node, 'lineno', 0)}: {holder}.{name}")
+    return bad
+
+
+def test_options_reads_name_real_fields():
+    bad = [b for path, text in _sources().items()
+           for b in _bad_option_reads(text, str(path.relative_to(PKG.parent)))]
+    assert not bad, ("options objects read fields RunOptions/BuildOptions do not have, "
+                     "so the read always returns its default:\n  " + "\n  ".join(bad))
+
+
+def test_the_options_check_sees_the_b129_shape():
+    src = ('def f(options):\n'
+           '    cli = getattr(options, "keep_hotplug_drivrs", None)\n'
+           '    options.append(1)\n'
+           '    return options.dry_run, options.no_such\n')
+    assert _bad_option_reads(src, "x") == ["x:2: options.keep_hotplug_drivrs",
+                                           "x:4: options.no_such"]
+
+
+# Flags read without their own name in the source: the namespace dispatch
+# fields, doctor's axis flags (looked up through _AXIS_FLAGS), and the
+# packages.toml key the `packages add` flag is named after.
+def _indirect_reads():
+    from sysforge import doctor
+    from sysforge.primitives.config import PKG_KEY_BUILD_FROM_SOURCE
+    return set(doctor._AXIS_FLAGS) | {PKG_KEY_BUILD_FROM_SOURCE}
+
+
+def _commands(parser, path=()):
+    for a in parser._actions:
+        if isinstance(a, argparse._SubParsersAction):
+            for name, sub in a.choices.items():
+                yield path + (name,), sub, a.dest
+                yield from _commands(sub, path + (name,))
+
+
+def test_every_parsed_flag_is_read():
+    source = "\n".join(_sources().values())
+    root = build_parser()
+    global_dests = {a.dest for a in root._actions}
+    dispatch = {dest for *_, dest in _commands(root)}
+    indirect = _indirect_reads()
+    unread = []
+    for path, sub, _ in _commands(root):
+        for a in sub._actions:
+            d = a.dest
+            if (isinstance(a, argparse._SubParsersAction) or d in ("help", "verb_cls")
+                    or d in global_dests or d in dispatch or d in indirect):
+                continue
+            if not re.search(rf'\.args\.{d}\b|\bargs\.{d}\b|getattr\(\s*[\w.]*args\s*,\s*"{d}"'
+                             rf'|resolve_flag_default\(\s*[\w.]*args\s*,\s*"{d}"', source):
+                unread.append(f"sysforge {' '.join(path)}: {d}")
+    assert not unread, "parsed but never read:\n  " + "\n  ".join(sorted(set(unread)))
+
+
+def test_doctor_axis_flags_are_the_indirect_ones():
+    """The doctor exemption above is only sound while _AXIS_FLAGS names the
+    axis flags exactly."""
+    from sysforge import doctor
+    root = build_parser()
+    doctor_sub = next(a for a in root._actions
+                      if isinstance(a, argparse._SubParsersAction)).choices["doctor"]
+    axis_dests = set()
+    for a in doctor_sub._actions:
+        if isinstance(a, argparse._SubParsersAction):
+            for sub in a.choices.values():
+                axis_dests |= {x.dest for x in sub._actions if x.dest in doctor._AXIS_FLAGS}
+    assert axis_dests == set(doctor._AXIS_FLAGS)
diff --git a/tests/test_journal.py b/tests/test_journal.py
index d92cf6ed..47428826 100644
--- a/tests/test_journal.py
+++ b/tests/test_journal.py
@@ -8,6 +8,7 @@
 import struct
 from types import SimpleNamespace
 
+from cli_args import cli_args
 from sysforge.primitives import journal
 
 
@@ -122,19 +123,19 @@ def test_state_failed_verb_journal_target():
     from sysforge.state_cmd import StateFailedVerb
 
     verb = StateFailedVerb()
-    assert verb.journal_target(SimpleNamespace(clear="mesa", clear_all=False)) == "pkg:mesa"
+    assert verb.journal_target(cli_args("state", "failed", "--clear", "mesa")) == "pkg:mesa"
     # neither flag: not sentinel-gated, no subject
-    assert verb.journal_target(SimpleNamespace(clear=None, clear_all=False)) is None
+    assert verb.journal_target(cli_args("state", "failed")) is None
     # 2.5.1-F3: --clear-all is equally sentinel-gated (it rewrites
     # build_state.toml) but subjectless, so it emits a `mode:` target rather
     # than journalling the bare verb name.
     assert (
-        verb.journal_target(SimpleNamespace(clear=None, clear_all=True))
+        verb.journal_target(cli_args("state", "failed", "--clear-all"))
         == "mode:failed-clear-all"
     )
     # --clear wins when both are somehow set: the named subject is more useful.
     assert (
-        verb.journal_target(SimpleNamespace(clear="mesa", clear_all=True)) == "pkg:mesa"
+        verb.journal_target(cli_args("state", "failed", clear="mesa", clear_all=True)) == "pkg:mesa"
     )
 
 
diff --git a/tests/test_json_output.py b/tests/test_json_output.py
index 092ca2bc..4c14d230 100644
--- a/tests/test_json_output.py
+++ b/tests/test_json_output.py
@@ -13,6 +13,7 @@
 
 import pytest
 
+from cli_args import cli_args
 from sysforge import log
 from sysforge.primitives import json_out
 
@@ -103,7 +104,7 @@ def test_state_list_json_validates(tmp_path, capsys, monkeypatch, verbose):
     bs.save()
     OptOutList(tmp_path).add("mesa", ["mesa"], via=VIA_FORGET)
     monkeypatch.setattr(pacman, "get_foreign_packages", lambda: {"foo-git": "1-1"})
-    args = SimpleNamespace(state_dir=str(tmp_path), no_pager=False, json=True)
+    args = cli_args("state", "list", "--json", state_dir=str(tmp_path))
     assert run_verb(StateListVerb(), args) == 0
     doc = _only_document(capsys.readouterr().out)
     _validate(doc, _schema("state-list"))
@@ -156,7 +157,7 @@ def test_doctor_json_exit_code_matches_the_report(monkeypatch, capsys):
 
 def test_doctor_pkg_refuses_json_with_apply():
     from sysforge.doctor import DoctorPkgVerb
-    pre = DoctorPkgVerb().pre_check(SimpleNamespace(json=True, apply=True))
+    pre = DoctorPkgVerb().pre_check(cli_args("doctor", "pkg", "--json", "--apply"))
     assert pre.blocker and pre.exit_code == 2
 
 
@@ -228,3 +229,55 @@ def test_update_dry_run_json_lists_flag_drift_promotion(
     doc = _only_document(capsys.readouterr().out)
     (pkg,) = doc["packages"]
     assert (pkg["pkgbase"], pkg["action"]) == ("htop", "NEEDS_REBUILD")
+
+
+def test_config_check_json_validates(tmp_path, capsys, verbose):
+    """3.5.0-F18: one document on stdout, every finding in it, same exit code."""
+    import shutil
+
+    from sysforge.config_cmd import ConfigCheckVerb
+    from sysforge.primitives import config_schema
+    from sysforge.verbs.runner import run_verb
+    shipped = Path(__file__).resolve().parent.parent / "etc/sysforge"
+    for name in config_schema.CONFIG_FILES:
+        shutil.copy(shipped / name, tmp_path / name)
+    (tmp_path / "sysforge.toml").write_text("[git]\npull_timeout = 5\n[ui]\ncolr = 1\n[nosuch]\n")
+    args = cli_args("config", "check", "--json", "--config-dir", str(tmp_path))
+    assert run_verb(ConfigCheckVerb(), args) == 1
+    doc = _only_document(capsys.readouterr().out)
+    _validate(doc, _schema("config-check"))
+    assert [(i["kind"], i["setting"]) for i in doc["issues"]] == [
+        ("retired_key", "[git] pull_timeout"), ("unknown_key", "[ui] colr"),
+        ("unknown_section", "[nosuch]")]
+
+
+def test_config_check_json_when_clean(tmp_path, capsys):
+    import shutil
+
+    from sysforge.config_cmd import ConfigCheckVerb
+    from sysforge.primitives import config_schema
+    from sysforge.verbs.runner import run_verb
+    shipped = Path(__file__).resolve().parent.parent / "etc/sysforge"
+    for name in config_schema.CONFIG_FILES:
+        shutil.copy(shipped / name, tmp_path / name)
+    args = cli_args("config", "check", "--json", "--config-dir", str(tmp_path))
+    assert run_verb(ConfigCheckVerb(), args) == 0
+    doc = _only_document(capsys.readouterr().out)
+    _validate(doc, _schema("config-check"))
+    assert doc["issues"] == []
+
+
+def test_every_emitted_kind_has_a_schema_and_back():
+    """Each `json_out.emit("<kind>", ...)` has tests/data/json-schema/<kind>.schema.json,
+    and each schema is for a kind something emits (standards row 32)."""
+    import ast
+    pkg = Path(__file__).resolve().parent.parent / "sysforge"
+    kinds = set()
+    for py in pkg.rglob("*.py"):
+        for node in ast.walk(ast.parse(py.read_text(encoding="utf-8"))):
+            if (isinstance(node, ast.Call) and getattr(node.func, "attr", None) == "emit"
+                    and getattr(node.func.value, "id", None) == "json_out"
+                    and node.args and isinstance(node.args[0], ast.Constant)):
+                kinds.add(node.args[0].value)
+    schemas = {p.name.removesuffix(".schema.json") for p in _SCHEMAS.glob("*.schema.json")}
+    assert kinds == schemas
diff --git a/tests/test_log_cmd.py b/tests/test_log_cmd.py
index 6630d0b3..42708e5e 100644
--- a/tests/test_log_cmd.py
+++ b/tests/test_log_cmd.py
@@ -125,13 +125,11 @@ def test_log_missing_verb_log_does_not_fall_back(tmp_path, capsys):
 def test_every_run_log_writer_is_pageable():
     """Each verb's declared name is what the runner opens and what --verb
     accepts, so a verb that starts logging is pageable with no second edit."""
-    from types import SimpleNamespace
-
     from sysforge import log
     from sysforge.verbs.base import VerbGroup
     from sysforge.verbs.registry import COMMANDS, verb_log_names
     names = verb_log_names()
-    args = SimpleNamespace(apply=False, dry_run=False)
+    args = _args(None, None)  # read only by doctor pkg (apply/dry_run), absent elsewhere
     verbs = [v for e in COMMANDS for v in (e.members if isinstance(e, VerbGroup) else (e,))]
     for v in verbs:
         if v.wants_run_log:
diff --git a/tests/test_net_policy_cli.py b/tests/test_net_policy_cli.py
index 2444be76..5d71f339 100644
--- a/tests/test_net_policy_cli.py
+++ b/tests/test_net_policy_cli.py
@@ -6,6 +6,7 @@
 
 import pytest
 
+from cli_args import cli_args
 from sysforge import cli
 from sysforge.primitives.net_policy import reset_policy
 
@@ -144,7 +145,6 @@ def test_frozen_run_exits_non_zero_with_the_package_named(update_scenario, capsy
     ``--frozen`` run produces once the CLI in this task installs the policy
     at entry.
     """
-    from types import SimpleNamespace
 
     from sysforge.primitives.source_sync import STATUS_FROZEN
 
@@ -152,11 +152,7 @@ def test_frozen_run_exits_non_zero_with_the_package_named(update_scenario, capsy
     update_scenario.fake_sync(
         {"htop": (STATUS_FROZEN, "source freeze active — refused: htop")}
     )
-    args = SimpleNamespace(
-        state_dir=None, dry_run=False, devel=False, offline=False,
-        no_pkg_log=True, persist_log=False, log_dir=None, profile_conf=None,
-        cache_report=False, packages=None,
-    )
+    args = cli_args("update", "--no-pkg-log")
     with pytest.raises(RuntimeError, match="htop"):
         update_scenario.run(args, installed={"htop": "0.9.0-1"}, foreign={"htop": "0.9.0-1"})
     combined = "".join(capsys.readouterr())
diff --git a/tests/test_opt_out.py b/tests/test_opt_out.py
index 285435e4..b98f1f82 100644
--- a/tests/test_opt_out.py
+++ b/tests/test_opt_out.py
@@ -12,6 +12,7 @@
 
 import pytest
 
+from cli_args import cli_args
 from sysforge.primitives.build_state import BuildState
 from sysforge.primitives.opt_out import (
     VIA_FORGET,
@@ -103,7 +104,7 @@ def test_forget_without_opt_out_records_nothing(tmp_path):
 def test_state_forget_writes_the_record(tmp_path, capsys):
     from sysforge.state_cmd import cmd_state_forget
     _seed(tmp_path, "htop", "htop")
-    cmd_state_forget(SimpleNamespace(state_dir=str(tmp_path), pkgnames=["htop"]))
+    cmd_state_forget(cli_args("state", "forget", "htop", state_dir=str(tmp_path)))
     assert OptOutList(tmp_path).load()["htop"]["via"] == "forget"
     assert "will not re-adopt" in capsys.readouterr().out
 
@@ -113,7 +114,7 @@ def test_revert_records_a_revert_opt_out(tmp_path, monkeypatch):
     monkeypatch.setattr(revert_cmd, "resolve_state_dir", lambda *a, **k: (tmp_path, "test"))
     _seed(tmp_path, "htop", "htop")
     verb = revert_cmd.RevertToStockVerb()
-    args = SimpleNamespace(packages=["htop"], dry_run=False, yes=True, state_dir=None)
+    args = cli_args("revert-to-stock", "htop", "--yes")
     with patch.object(revert_cmd.pacman, "reinstall_repo_pkgs"):
         pre = verb.pre_check(args)
         assert verb.execute(args, pre).exit_code == 0
diff --git a/tests/test_packages_add.py b/tests/test_packages_add.py
index 44e9b1fd..f2ed35a4 100644
--- a/tests/test_packages_add.py
+++ b/tests/test_packages_add.py
@@ -22,6 +22,7 @@
     cmd_packages_remove,
 )
 from sysforge.verbs.shared import entry_is_inert, rewrite_packages_toml
+from cli_args import cli_args
 
 
 def _args(pkg, packages, **overrides):
@@ -212,7 +213,7 @@ def test_remove_missing_entry_is_fatal(tmp_path, capsys):
 # ---------------------------------------------------------------------------
 
 def _group_args(desktop, packages):
-    return SimpleNamespace(desktop=desktop, packages=str(packages))
+    return cli_args("packages", "add-group", "cosmic", desktop=desktop, packages=str(packages))
 
 
 def test_add_group_writes_group(tmp_path, capsys):
diff --git a/tests/test_packages_list.py b/tests/test_packages_list.py
index 48049b8e..112c4f7a 100644
--- a/tests/test_packages_list.py
+++ b/tests/test_packages_list.py
@@ -3,12 +3,14 @@
 
 import pytest
 
+from cli_args import cli_args
 from sysforge import packages_cmd
 from sysforge.packages_cmd import PackagesAddVerb, cmd_packages_list
 
 
 def _list(path, **kw):
-    cmd_packages_list(SimpleNamespace(packages=str(path), orphans=kw.get("orphans", False)))
+    cmd_packages_list(cli_args("packages", "list", packages=str(path),
+                               orphans=kw.get("orphans", False)))
 
 
 def test_list_without_a_file_is_fatal(tmp_path):
@@ -77,8 +79,7 @@ def test_packages_file_defaults_to_the_configured_path(tmp_path, monkeypatch):
 
 
 def test_add_verb_pre_check_blocks_source_only():
-    args = SimpleNamespace(pkg="mesa", enable_build_from_source=False,
-                           no_cache=False, reason=None, source="repo")
+    args = cli_args("packages", "add", "mesa", "--source", "repo")
     pre = PackagesAddVerb().pre_check(args)
     assert pre.blocker and "--source alone is metadata" in pre.blocker
     assert pre.exit_code == 1
@@ -113,4 +114,4 @@ def test_add_reports_a_lifted_opt_out(tmp_path, monkeypatch, capsys):
 def test_remove_without_a_file_is_fatal(tmp_path):
     with pytest.raises(SystemExit):
         packages_cmd.cmd_packages_remove(
-            SimpleNamespace(pkg="mesa", packages=str(tmp_path / "packages.toml")))
+            cli_args("packages", "remove", "mesa", packages=str(tmp_path / "packages.toml")))
diff --git a/tests/test_release_resume.py b/tests/test_release_resume.py
index 4c0dbf76..e3570dd0 100644
--- a/tests/test_release_resume.py
+++ b/tests/test_release_resume.py
@@ -49,9 +49,9 @@ def scaffold(tmp_path):
     )
     (repo / "Makefile").write_text(
         ".PHONY: lint typecheck check-shipped check-personal check-design "
-        "check-roadmap-table check-standards check-bump check-standards-at man\n"
+        "check-roadmap-table check-standards check-surface check-bump check-standards-at man\n"
         "lint typecheck check-shipped check-personal check-design check-roadmap-table "
-        "check-standards check-bump check-standards-at man:\n"
+        "check-standards check-surface check-bump check-standards-at man:\n"
         "\t@true\n"
     )
     _git(repo, "init", "-q", "-b", "main")
diff --git a/tests/test_removed_failures.py b/tests/test_removed_failures.py
index 6e0075fe..e8f102c5 100644
--- a/tests/test_removed_failures.py
+++ b/tests/test_removed_failures.py
@@ -11,6 +11,7 @@
 
 import pytest
 
+from cli_args import cli_args
 from sysforge import state_cmd, uninstall_cmd
 from sysforge.primitives import install_reconcile as ir
 from sysforge.primitives import pacman, state_probe
@@ -223,8 +224,8 @@ def test_state_failed_omits_a_removal_without_saving(tmp_path, local_db, capsys)
     _state(tmp_path, {"foo": _src("foo")}, failures=["foo", "bar"])
     _window("foo")
 
-    state_cmd.cmd_state_failed(SimpleNamespace(
-        state_dir=str(tmp_path), no_pager=True, clear=None, clear_all=False, names=True))
+    state_cmd.cmd_state_failed(cli_args("state", "failed", "--names", "--no-pager",
+                                        state_dir=str(tmp_path)))
 
     assert capsys.readouterr().out.split() == ["bar"]
     assert set(BuildState(tmp_path).all_failures()) == {"foo", "bar"}
diff --git a/tests/test_resolve.py b/tests/test_resolve.py
index 63af8053..2053881e 100644
--- a/tests/test_resolve.py
+++ b/tests/test_resolve.py
@@ -13,7 +13,6 @@
 import os
 import sys
 from pathlib import Path
-from types import SimpleNamespace
 from unittest.mock import patch
 
 import pytest
@@ -30,6 +29,7 @@
     _print_resolve,
     cmd_resolve,
 )
+from cli_args import cli_args
 
 TESTS_DIR = Path(__file__).parent
 DATA_DIR = TESTS_DIR / "data"
@@ -427,7 +427,8 @@ def test_print_resolve_internal_keys_separated(capsys, tmp_path):
 # ---------------------------------------------------------------------------
 
 def _make_args(pkg, show_flags=False, deps=False, profile_conf=None):
-    return SimpleNamespace(pkg=pkg, show_flags=show_flags, deps=deps, profile_conf=profile_conf)
+    return cli_args("resolve", "_", pkg=pkg, show_flags=show_flags, deps=deps,
+                    profile_conf=profile_conf)
 
 
 def test_cmd_resolve_htop_matches_rule(capsys):
diff --git a/tests/test_run_cmd.py b/tests/test_run_cmd.py
index e23b11fe..7a421291 100644
--- a/tests/test_run_cmd.py
+++ b/tests/test_run_cmd.py
@@ -174,3 +174,52 @@ def test_top_level_description_is_the_package_description():
     project = tomllib.loads(
         (Path(__file__).parent.parent / "pyproject.toml").read_text())["project"]
     assert _build_parser().description == project["description"]
+
+
+# 3.5.0-B129: `run kernel --keep-hotplug-drivers` was parsed and then dropped,
+# because the verb never copied it into RunOptions (which had no such field).
+
+def test_every_run_stage_flag_reaches_the_stage():
+    """Each `run <stage>` flag is read by that verb (into RunOptions, or by
+    load_config_with_overrides), so none is parsed and silently ignored."""
+    import ast
+    import re
+    from pathlib import Path
+
+    from sysforge.verbs.registry import build_parser
+    src = (Path(__file__).resolve().parent.parent / "sysforge/run_cmd.py").read_text()
+    classes = {n.name: ast.get_source_segment(src, n) for n in ast.parse(src).body
+               if isinstance(n, ast.ClassDef)}
+    root = build_parser()
+    global_dests = {a.dest for a in root._actions} | {"command", "run_stage", "verb_cls"}
+    stages = {"pipeline": "RunPipelineVerb", "hardware": "RunHardwareVerb",
+              "reconfigure": "RunReconfigureVerb", "toolchain": "RunToolchainVerb",
+              "packages": "RunPackagesVerb", "kernel": "RunKernelVerb"}
+    dropped = {}
+    for stage, cls in stages.items():
+        body = classes[cls]
+        execute = body[body.index("def execute"):]
+        read = set(re.findall(r"args\.(\w+)", execute)) | \
+            set(re.findall(r'getattr\(args, "(\w+)"', execute))
+        if "load_config_with_overrides(args)" in execute:
+            read |= {"packages", "profile_conf"}
+        lost = set(vars(root.parse_args(["run", stage]))) - global_dests - read
+        if lost:
+            dropped[stage] = sorted(lost)
+    assert not dropped, f"flags parsed but never passed on: {dropped}"
+
+
+def test_keep_hotplug_drivers_reaches_the_kernel_stage(monkeypatch):
+    from sysforge import run_cmd
+    from sysforge.pipeline import runner
+    from sysforge.verbs.registry import build_parser
+    seen = {}
+    monkeypatch.setattr(run_cmd, "load_config", lambda: {})
+    monkeypatch.setattr(runner, "run_stage_standalone",
+                        lambda stage, config, options: seen.setdefault("o", options))
+    for argv, want in ((["--keep-hotplug-drivers"], True),
+                       (["--no-keep-hotplug-drivers"], False), ([], None)):
+        seen.clear()
+        args = build_parser().parse_args(["run", "kernel", *argv])
+        run_cmd.RunKernelVerb().execute(args, None)
+        assert seen["o"].keep_hotplug_drivers is want
diff --git a/tests/test_stage_kernel.py b/tests/test_stage_kernel.py
index 23354f1a..dca42d5d 100644
--- a/tests/test_stage_kernel.py
+++ b/tests/test_stage_kernel.py
@@ -5,7 +5,6 @@
 bootctl, makepkg) are mocked — nothing real runs.
 """
 import contextlib
-import types
 from contextlib import contextmanager
 from types import SimpleNamespace
 from unittest.mock import MagicMock, patch
@@ -3469,10 +3468,8 @@ def test_kernel_stage_run_stages_lsmod_snapshot(tmp_path):
 
 
 def _hotplug_opts(**kw):
-    ns = types.SimpleNamespace(keep_hotplug_drivers=None, dry_run=False)
-    for k, v in kw.items():
-        setattr(ns, k, v)
-    return ns
+    from sysforge.pipeline.stages.base import RunOptions
+    return RunOptions(**kw)
 
 
 def test_resolve_keep_hotplug_cli_overrides_toml():
@@ -4093,8 +4090,8 @@ def test_base_config_merge_cli_overrides_kernel_toml(tmp_path, monkeypatch):
 
     cfg, d = _running_base(tmp_path, monkeypatch)
     label = write_base_config(
-        cfg, dry_run=False, options=SimpleNamespace(base_config=None,
-                                                    base_config_merge="overlay"))
+        cfg, dry_run=False, options=RunOptions(base_config=None,
+                                               base_config_merge="overlay"))
     assert label == "running (overlay)"
 
 
diff --git a/tests/test_stand_ins.py b/tests/test_stand_ins.py
index c9e53555..ef2d90de 100644
--- a/tests/test_stand_ins.py
+++ b/tests/test_stand_ins.py
@@ -12,15 +12,16 @@
 name and the test goes on passing against an object production never builds.
 
 ``BuildOptions(...)`` and ``RunOptions(...)`` default every field and reject a
-name they do not have, and ``build_parser().parse_args([...])`` gives a parsed
-command line with every flag present. Use those.
+name they do not have, and ``cli_args("state", "list", state_dir=d)``
+(tests/cli_args.py) parses a real command line, then sets fields the command
+has. Use those.
 
 Options stand-ins are recognised by a field that is on the dataclass but is no
 CLI flag's destination, so only an options object has it. Argument stand-ins
-are recognised by fields that are all one command's flags; the ones that
-predate this check are in ``_ARGS_STAND_INS``, a **shrinking** allowlist (the
-same discipline as tests/test_module_layering.py): a new one fails, and a file
-that converts some must lower its count.
+are recognised by fields that are all one command's flags. ``_ARGS_STAND_INS``
+lists the deliberate exceptions with their reason, as a **shrinking**
+allowlist (the discipline of tests/test_module_layering.py): a new stand-in
+fails, and a converted exception must be removed from it.
 """
 import argparse
 import ast
@@ -34,30 +35,11 @@
 
 TESTS = Path(__file__).resolve().parent
 
-# file name -> SimpleNamespace stand-ins for parsed arguments it still has.
-_ARGS_STAND_INS: dict[str, int] = {
-    "test_build_cmd.py": 3,
-    "test_build_core.py": 1,
-    "test_cli.py": 1,
-    "test_completions_speed.py": 1,
-    "test_doctor.py": 1,
-    "test_journal.py": 4,
-    "test_json_output.py": 2,
-    "test_log_cmd.py": 1,
-    "test_net_policy_cli.py": 1,
-    "test_opt_out.py": 2,
-    "test_packages_add.py": 1,
-    "test_packages_list.py": 3,
-    "test_removed_failures.py": 1,
-    "test_resolve.py": 1,
-    "test_stage_kernel.py": 2,
-    "test_standards_compliance.py": 1,
-    "test_state_forget.py": 1,
-    "test_state_list.py": 1,
-    "test_state_orphans.py": 1,
-    "test_state_repair.py": 1,
-    "test_toolchain_measure.py": 1,
-}
+# Deliberate exceptions, as file name -> (stand-ins it keeps, why). Empty, and
+# that is the steady state: the last one tested a getattr fallback no caller
+# needed, and went with it. Every parsed command line is built with
+# tests/cli_args.cli_args; converting them found 3.5.0-B129.
+_ARGS_STAND_INS: dict[str, tuple[int, str]] = {}
 
 
 def _stand_ins():
@@ -114,10 +96,18 @@ def test_parsed_argument_stand_ins_only_shrink():
         keys -= global_dests
         if len(keys) >= 2 and any(keys <= d for d in commands):
             found[py.name] += 1
-    grown = {f: n for f, n in found.items() if n > _ARGS_STAND_INS.get(f, 0)}
+    allowed = {f: n for f, (n, _why) in _ARGS_STAND_INS.items()}
+    grown = {f: n for f, n in found.items() if n > allowed.get(f, 0)}
     assert not grown, (
         "new SimpleNamespace stand-ins for parsed arguments; build them with "
-        f"build_parser().parse_args([...]) instead: {grown}")
-    shrunk = {f: (n, found.get(f, 0)) for f, n in _ARGS_STAND_INS.items()
+        f"tests/cli_args.cli_args(...) instead: {grown}")
+    shrunk = {f: (n, found.get(f, 0)) for f, n in allowed.items()
               if found.get(f, 0) < n}
     assert not shrunk, f"lower these _ARGS_STAND_INS counts (listed, now): {shrunk}"
+
+
+def test_stand_in_allowlist_is_empty():
+    """The shrinking-allowlist check passes vacuously on an empty list, so this
+    pins it shut, as tests/test_module_layering.py does. Re-adding an entry
+    needs a reason a real object cannot serve."""
+    assert _ARGS_STAND_INS == {}
diff --git a/tests/test_standards_compliance.py b/tests/test_standards_compliance.py
index 99ef32a0..c4b4248b 100644
--- a/tests/test_standards_compliance.py
+++ b/tests/test_standards_compliance.py
@@ -422,7 +422,6 @@ def test_journald_mirror_emits_only_for_sentinel_verbs(tmp_path, monkeypatch):
     hard-coded verb list — so it cannot rot as verbs are added.
     """
     from contextlib import nullcontext
-    from types import SimpleNamespace
 
     from sysforge.verbs import runner
     from sysforge.verbs.base import ExecResult, PreCheckResult, Verb
@@ -458,7 +457,8 @@ def pre_check(self, args):
         def execute(self, args, pre):
             return ExecResult(exit_code=0)
 
-    args = SimpleNamespace(state_dir=str(tmp_path), dry_run=True)
+    from cli_args import cli_args
+    args = cli_args("state", "repair", "--dry-run", state_dir=str(tmp_path))
 
     assert runner.run_verb(_Mut(), args) == 0
     assert runner.run_verb(_Ro(), args) == 0
@@ -1192,3 +1192,68 @@ def test_retired_names_matches_whole_words_and_honours_allows(tmp_path):
         "tests/test_x.py": "assert '--skip-boot-audit' not in flags\n",       # always allowed
     })
     assert _load_check_standards().check_retired_names(repo) == []
+
+
+# ---------------------------------------------------------------------------
+# citations (3.5.0-DEV15)
+# ---------------------------------------------------------------------------
+
+def test_citations_group_is_clean_on_the_real_repo():
+    findings = _load_check_standards().check_citations(_REPO)
+    assert findings == [], "\n".join(f"{f.location}: {f.message}" for f in findings)
+
+
+def _cite_repo(tmp_path, body):
+    (tmp_path / "docs/design").mkdir(parents=True)
+    (tmp_path / "docs/design/01-x.md").write_text(body)
+    (tmp_path / "sysforge/primitives").mkdir(parents=True)
+    (tmp_path / "sysforge/primitives/artifacts.py").write_text("def rehash(): pass\n")
+    (tmp_path / "etc/sysforge").mkdir(parents=True)
+    (tmp_path / "Makefile").write_text("vm-install-git: ## x\n\ttrue\ntest: ## y\n\ttrue\n")
+    return tmp_path
+
+
+@pytest.mark.parametrize("cite", [
+    "`primitives/artifacts.rehash`",      # path + symbol ("rehash" ends in "sh")
+    "`make test ARGS=-x`", "`make nconfig`", "`make htmldocs`",  # ours, kernel's
+    "`etc/pam.d`", "`root/usr/bin`", "`and/or`",                 # not repo paths
+    "`merge_config.sh`",                                          # a kernel script
+    "`run.plan`", "`docs/release-notes/vX.Y.Z.md`",               # local, placeholder
+    "`sysforge/_data/config-defaults`",                           # wheel-only
+])
+def test_citations_accepts(tmp_path, cite):
+    assert _load_check_standards().check_citations(_cite_repo(tmp_path, f"see {cite}\n")) == []
+
+
+@pytest.mark.parametrize("cite, expect", [
+    ("`primitives/artifacts.gone`", "has no `gone`"),
+    ("`make vm-install`", "did it become `vm-install-git`"),
+    ("`primitives/removed.py`", "does not exist"),
+    ("`converge.py`", "no such file"),
+])
+def test_citations_flags(tmp_path, cite, expect):
+    [f] = _load_check_standards().check_citations(_cite_repo(tmp_path, f"see {cite}\n"))
+    assert expect in f.message
+
+
+def test_citations_are_paired_per_line_past_a_fence(tmp_path):
+    """A ``` fence used to pair with the next lone backtick, shifting every
+    span after it; that hid a stale path in a skill file."""
+    body = "```bash\nmake test\n```\nsee `primitives/removed.py` here\n"
+    [f] = _load_check_standards().check_citations(_cite_repo(tmp_path, body))
+    assert "primitives/removed.py" in f.message
+
+
+def test_citations_flag_a_bare_name_nothing_defines(tmp_path):
+    """3.5.0-DEV15: `_confirm_or_abort` had no module to resolve against, so
+    it outlived its function by years."""
+    repo = _cite_repo(tmp_path, "see `_confirm_or_abort` and `rehash` and `IgnorePkg`\n")
+    [f] = _load_check_standards().check_citations(repo)
+    assert "_confirm_or_abort" in f.message
+
+
+def test_citations_accept_a_bare_name_the_code_uses(tmp_path):
+    repo = _cite_repo(tmp_path, "see `_make_frame` here\n")
+    (repo / "sysforge/primitives/frames.py").write_text("def _make_frame(): pass\n")
+    _load_check_standards()._CODE_WORDS.clear()
+    assert _load_check_standards().check_citations(repo) == []
diff --git a/tests/test_state_forget.py b/tests/test_state_forget.py
index 04acddeb..f7590eac 100644
--- a/tests/test_state_forget.py
+++ b/tests/test_state_forget.py
@@ -5,14 +5,14 @@
 package (the escape hatch for durable-by-default tracking).
 """
 from pathlib import Path
-from types import SimpleNamespace
 
 from sysforge.primitives.build_state import BuildState
 from sysforge.state_cmd import cmd_state_forget
+from cli_args import cli_args
 
 
 def _args(state_dir: Path, *pkgnames):
-    return SimpleNamespace(state_dir=str(state_dir), pkgnames=list(pkgnames))
+    return cli_args("state", "forget", "_", state_dir=str(state_dir), pkgnames=list(pkgnames))
 
 
 def _seed(state_dir: Path, pkgname: str, pkgbase: str, build_mode="source_built"):
diff --git a/tests/test_state_list.py b/tests/test_state_list.py
index 1f48a6a1..0c7d7ffe 100644
--- a/tests/test_state_list.py
+++ b/tests/test_state_list.py
@@ -3,14 +3,14 @@
 section (C3) and the basic tabular output.
 """
 from pathlib import Path
-from types import SimpleNamespace
 from unittest.mock import patch
 
 from sysforge.state_cmd import cmd_state_list
+from cli_args import cli_args
 
 
 def _args(state_dir: Path, no_pager: bool = True):
-    return SimpleNamespace(state_dir=str(state_dir), no_pager=no_pager)
+    return cli_args("state", "list", state_dir=str(state_dir), no_pager=no_pager)
 
 
 def _seed_state(state_dir: Path, entries: dict[str, dict]) -> None:
diff --git a/tests/test_state_orphans.py b/tests/test_state_orphans.py
index ed00f7f2..5247226e 100644
--- a/tests/test_state_orphans.py
+++ b/tests/test_state_orphans.py
@@ -6,14 +6,14 @@
 (with confirmation by default).
 """
 from pathlib import Path
-from types import SimpleNamespace
 from unittest.mock import patch
 
 from sysforge.state_cmd import cmd_state_orphans
+from cli_args import cli_args
 
 
 def _args(delete: bool = False, yes: bool = False, no_pager: bool = True):
-    return SimpleNamespace(delete=delete, yes=yes, no_pager=no_pager)
+    return cli_args("state", "orphans", delete=delete, yes=yes, no_pager=no_pager)
 
 
 def _mk_pkg(pkgdest: Path, name: str, ver: str, rel: str = "1") -> Path:
diff --git a/tests/test_state_repair.py b/tests/test_state_repair.py
index 85a8e3a0..7749427c 100644
--- a/tests/test_state_repair.py
+++ b/tests/test_state_repair.py
@@ -7,10 +7,10 @@
 corrupting good state.
 """
 from pathlib import Path
-from types import SimpleNamespace
 
 from sysforge.state_cmd import cmd_state_repair
 from sysforge.primitives.build_state import BuildState
+from cli_args import cli_args
 
 
 def _write_broken_state(state_dir: Path, entries: dict[str, dict]) -> None:
@@ -26,7 +26,7 @@ def _write_broken_state(state_dir: Path, entries: dict[str, dict]) -> None:
 
 
 def _args(state_dir: Path, dry_run: bool = False):
-    return SimpleNamespace(state_dir=str(state_dir), dry_run=dry_run)
+    return cli_args("state", "repair", state_dir=str(state_dir), dry_run=dry_run)
 
 
 def test_repair_simple_scalar_reference(tmp_path, capsys, monkeypatch):
diff --git a/tests/test_surface.py b/tests/test_surface.py
new file mode 100644
index 00000000..7cdc33ab
--- /dev/null
+++ b/tests/test_surface.py
@@ -0,0 +1,86 @@
+# SPDX-FileCopyrightText: 2026 Keith Raghubar
+#
+# SPDX-License-Identifier: MIT
+
+"""
+The surface snapshot and its review rules (3.5.0-DEV18, tools/surface.py).
+"""
+import importlib.util
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO = Path(__file__).resolve().parent.parent
+
+
+def _surface():
+    spec = importlib.util.spec_from_file_location("surface", REPO / "tools/surface.py")
+    assert spec and spec.loader
+    mod = importlib.util.module_from_spec(spec)
+    sys.modules.setdefault("surface", mod)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _snap(flags=None, env=(), config_keys=()):
+    return {
+        "commands": {"state list": {"flags": flags or {"--json": None}, "positionals": {}}},
+        "environment": list(env),
+        "journal_fields": [],
+        "config": {"sysforge.toml": {"top_level": [],
+                                     "sections": {"git": list(config_keys)}}},
+        "json": {},
+        "run_logs": [],
+    }
+
+
+def test_committed_snapshot_is_current():
+    s = _surface()
+    assert (REPO / s.SNAPSHOT).read_text(encoding="utf-8") == s.render(s.collect()), \
+        "run `make surface` and commit tests/data/surface.json"
+
+
+def test_unchanged_surface_needs_nothing():
+    s = _surface()
+    assert s.judge(_snap(), _snap(), "", set()) == []
+
+
+def test_an_added_flag_needs_a_release_note():
+    s = _surface()
+    head = _snap(flags={"--json": None, "--wide": None})
+    [problem] = s.judge(_snap(), head, "", set())
+    assert "added flag: state list --wide" in problem
+    assert s.judge(_snap(), head, "- **`3.5.0-F99` — `state list --wide`.** ...", set()) == []
+
+
+def test_an_added_value_and_env_var_need_naming():
+    s = _surface()
+    head = _snap(flags={"--json": None, "--sort": ["age", "name"]}, env=["SYSFORGE_X"])
+    problems = s.judge(_snap(), head, "", set())
+    assert {p.split(":")[0] for p in problems} == {"added flag", "added value", "added environment"}
+
+
+@pytest.mark.parametrize("base, head, name", [
+    (_snap(flags={"--json": None, "--old": None}), _snap(), "--old"),
+    (_snap(env=["SYSFORGE_OLD"]), _snap(), "SYSFORGE_OLD"),
+    (_snap(config_keys=["pull_timeout"]), _snap(), "pull_timeout"),
+])
+def test_a_name_gone_entirely_must_be_retired(base, head, name):
+    s = _surface()
+    notes = f"- **`3.5.0-F99` — `{name}` is gone.**"
+    [problem] = s.judge(base, head, notes, set())
+    assert "tools/retired_names.toml" in problem
+    assert s.judge(base, head, notes, {name}) == []
+
+
+def test_a_flag_still_on_another_command_is_not_retired():
+    """Dropping --json from one command is a release-note matter only."""
+    s = _surface()
+    base = _snap()
+    base["commands"]["state failed"] = {"flags": {"--json": None}, "positionals": {}}
+    head = _snap()
+    head["commands"]["state failed"] = {"flags": {}, "positionals": {}}
+    notes = "`state failed` no longer takes `--json`"
+    assert s.judge(base, head, notes, set()) == []
+
diff --git a/tests/test_toolchain_measure.py b/tests/test_toolchain_measure.py
index 822c856b..4c86bcc0 100644
--- a/tests/test_toolchain_measure.py
+++ b/tests/test_toolchain_measure.py
@@ -3,7 +3,8 @@
 # SPDX-License-Identifier: MIT
 
 """Toolchain stage → bench hand-off after a verified install (3.4.0-F11)."""
-from types import SimpleNamespace
+
+from pathlib import Path
 
 import pytest
 
@@ -13,7 +14,8 @@
 
 
 def _opts(tmp_path, dry_run=False):
-    return SimpleNamespace(dry_run=dry_run, state_dir=str(tmp_path))
+    from sysforge.pipeline.stages.base import RunOptions
+    return RunOptions(dry_run=dry_run, state_dir=Path(tmp_path))
 
 
 def _tcfg(after_build):
diff --git a/tools/check_shipped.py b/tools/check_shipped.py
index 52c5d4fd..719e4772 100644
--- a/tools/check_shipped.py
+++ b/tools/check_shipped.py
@@ -36,6 +36,13 @@
     completions      every verb and long-flag in the argparse parser appears
                      in both completions/_sysforge and completions/sysforge.bash;
                      no stale verb entries in the zsh case statement.
+    completion_commands  per command, in both scripts (3.5.0-DEV14): each
+                     long flag is offered where that command is completed
+                     (its zsh function, its bash case arm), no flag it lacks
+                     is offered there, every argparse choice value is offered
+                     (bash: in _sysforge_flag_arg or the command's own body),
+                     and lists copied from code constants (desktop catalog,
+                     profile-store methods) equal them.
     versions         pyproject.toml == PKGBUILD pkgver == PKGBUILD-git leading
                      pkgver == README.md / DESIGN.md <!--version--> markers.
     manpage          `make man` regen output (tools/gen_options.py splice +
@@ -73,6 +80,9 @@
 from pathlib import Path
 
 REPO = Path(__file__).resolve().parent.parent
+if str(REPO) not in sys.path:
+    sys.path.insert(0, str(REPO))
+from sysforge.primitives import config_schema  # noqa: E402
 
 
 @dataclass
@@ -87,48 +97,10 @@ class Finding:
 # Group: configs
 # ===========================================================================
 
-# Top-level sections accepted in each shipped TOML. Adding a section here is
-# the deliberate signal that the schema changed; the schema and the file are
-# always edited together.
-_KNOWN_SECTIONS: dict[str, set[str]] = {
-    "sysforge.toml":  {"ui", "log", "git", "aur", "build", "failure_handling",
-                       "safety", "mesa", "pgo", "update", "doctor", "artifacts",
-                       "security"},
-    "profiles.toml":  {"paths", "defaults", "profiles", "rules",
-                       "append_conflict_groups", "preserved_system_tokens",
-                       "consumes_inference",
-                       "package_compiler_overrides"},
-    "packages.toml":  {"build", "package", "group"},
-    "kernel.toml":    {"kconfig", "fdo"},
-    "toolchain.toml": {"packages", "llvm", "bolt", "bench"},
-    "bootstrap.toml": {"partition", "system", "mirror", "desktop", "makepkg"},
-}
-
-# Top-level scalar keys (in addition to sections).
-_KNOWN_TOP_KEYS: dict[str, set[str]] = {
-    "sysforge.toml":  set(),
-    "profiles.toml":  {"extends_system"},
-    "packages.toml":  set(),
-    # Kept in lockstep with what KernelStage actually reads via
-    # kernel_cfg.get(...) — enforced by tests/test_check_shipped.py's
-    # test_kernel_allowlist_matches_stage_reads. The kernel stage does NO
-    # PGO, so the toolchain's pgo/skip_build/pgo_staging/pgo_store keys are
-    # deliberately absent here.
-    "kernel.toml":    {"enabled", "compiler", "pkgname", "upstream_pkgname",
-                       "srcdir", "boot_entries", "boot_entries_prefix",
-                       "bootloader", "interactive", "pkgbuild_src_dir",
-                       "source", "base_config", "base_config_merge",
-                       "require_fallback_kernel", "boot_audit", "min_boot_free_mb",
-                       "capture_lsmod_snapshot", "device_kconfig",
-                       "kconfig_merge", "build_headers", "build_docs",
-                       "kconfig_targets", "keep_hotplug_drivers", "hardening"},
-    "toolchain.toml": {"enabled", "compiler", "pgo", "skip_build",
-                       "drift_detect",
-                       "pgo_staging", "pgo_staging1", "pgo_staging3",
-                       "pgo_store", "min_build_free_gb", "require_multilib",
-                       "rebuild_soname_consumers", "reuse_unchanged"},
-    "bootstrap.toml": {"target"},
-}
+# The config schema lives in the package (3.5.0-F18), so `sysforge config
+# check` at runtime and this release gate read one definition.
+_KNOWN_SECTIONS = config_schema.KNOWN_SECTIONS
+_KNOWN_TOP_KEYS = config_schema.KNOWN_TOP_KEYS
 
 
 def check_configs(repo: Path) -> list[Finding]:
@@ -1056,6 +1028,170 @@ def check_completions(repo: Path) -> list[Finding]:
     return findings
 
 
+# ===========================================================================
+# Group: completion_commands (3.5.0-DEV14)
+# ===========================================================================
+
+# Both scripts are laid out per command, which is what makes this check
+# possible: zsh has one function per command path (`_sysforge_state_orphans`),
+# bash one function per top-level command with a `case` arm per subcommand,
+# and every bash option value is offered from one `_sysforge_flag_arg` case
+# keyed by flag. A flag is therefore checked where it is offered, not anywhere
+# in the file.
+_FN_ALIASES = {"revert-to-stock": "revert"}
+_LONG_FLAG_RE = re.compile(r"(?<![\w-])--[a-z][\w-]*")
+
+
+def _fn_bodies(text: str) -> dict[str, str]:
+    """Shell function name -> body (up to the closing `}` in column 0)."""
+    bodies = {}
+    for m in re.finditer(r"^(\w+)\s*\(\)\s*\{\n(.*?)^\}", text, re.MULTILINE | re.DOTALL):
+        bodies[m.group(1)] = m.group(2)
+    return bodies
+
+
+def _with_helpers(body: str, bodies: dict[str, str]) -> str:
+    """A body plus the bodies of the `_sysforge_*` helpers it calls (one level)."""
+    called = set(re.findall(r"\b(_sysforge_\w+)\b", body))
+    return body + "".join(bodies.get(fn, "") for fn in sorted(called))
+
+
+def _bash_arm(body: str, word: str) -> str | None:
+    """The text of a `case` arm labelled `word)` inside a bash function body."""
+    m = re.search(rf"^\s+(?:[\w|-]+\|)?{re.escape(word)}(?:\|[\w|-]+)?\)\s*\n(.*?);;",
+                  body, re.MULTILINE | re.DOTALL)
+    return m.group(1) if m else None
+
+
+def _command_parsers(parser, path=()):
+    for a in parser._actions:
+        if isinstance(a, argparse._SubParsersAction):
+            for name, sub in a.choices.items():
+                if (path + (name,))[0] == "completions":
+                    continue
+                yield path + (name,), sub
+                yield from _command_parsers(sub, path + (name,))
+
+
+# Value lists the scripts copy from code rather than from argparse choices:
+# (what, loader, [(script, function)]). Each list in those functions that
+# shares a word with the constant must equal it exactly.
+def _desktops():
+    from sysforge.primitives.pkg_catalog import DESKTOP_CATALOG
+    return set(DESKTOP_CATALOG)
+
+
+def _profile_methods():
+    from sysforge.primitives.makepkg_pgo import PROFILE_METHODS
+    return set(PROFILE_METHODS)
+
+
+_MIRRORED_LISTS = (
+    ("pkg_catalog.DESKTOP_CATALOG", _desktops,
+     (("completions/_sysforge", "_sysforge_packages_add_group"),
+      ("completions/sysforge.bash", "_sysforge_packages"))),
+    ("makepkg_pgo.PROFILE_METHODS", _profile_methods,
+     (("completions/_sysforge", "_sysforge_state_profiles"),)),
+)
+# A zsh `(a b c)` value list or a bash `compgen -W "a b c"` word list.
+_WORD_LIST_RE = re.compile(r':\(([\w ._-]+)\)\'|compgen -W "([^"$]+)"')
+
+
+def _check_mirrored_lists(repo: Path) -> list[Finding]:
+    findings = []
+    for what, load, places in _MIRRORED_LISTS:
+        want = load()
+        for script, fn in places:
+            body = _fn_bodies((repo / script).read_text()).get(fn)
+            lists = [set((m.group(1) or m.group(2)).split())
+                     for m in _WORD_LIST_RE.finditer(body or "")]
+            lists = [w for w in lists if w & want]
+            if not lists:
+                findings.append(Finding("completion_commands", "error", script,
+                                        f"{fn}: no list mirroring {what}"))
+            for words in lists:
+                if words != want:
+                    findings.append(Finding(
+                        "completion_commands", "error", script,
+                        f"{fn}: list differs from {what} "
+                        f"(missing {sorted(want - words)}, extra {sorted(words - want)})"))
+    return findings
+
+
+def check_completion_commands(repo: Path) -> list[Finding]:
+    zsh_path, bash_path = repo / "completions/_sysforge", repo / "completions/sysforge.bash"
+    if not (zsh_path.exists() and bash_path.exists()):
+        return []
+    zsh = _fn_bodies(zsh_path.read_text())
+    bash = _fn_bodies(bash_path.read_text())
+    flag_arg = bash.get("_sysforge_flag_arg", "")
+    root = _import_build_parser(repo)
+    global_flags = {o for a in root._actions for o in a.option_strings}
+    findings: list[Finding] = []
+
+    def err(where, msg):
+        findings.append(Finding("completion_commands", "error", where, msg))
+
+    for path, sub in _command_parsers(root):
+        actions = [a for a in sub._actions if a.option_strings and a.dest != "help"]
+        has_subs = any(isinstance(a, argparse._SubParsersAction) for a in sub._actions)
+        if has_subs and not actions:
+            continue  # a group parent: its subcommands carry the flags
+        cmd = " ".join(path)
+        words = [_FN_ALIASES.get(path[0], path[0]), *path[1:]]
+        zfn = "_sysforge_" + "_".join(w.replace("-", "_") for w in words)
+        zbody = zsh.get(zfn)
+        if zbody is None:
+            err("completions/_sysforge", f"{cmd}: no {zfn} function")
+        else:
+            zfull = _with_helpers(zbody, zsh)
+            # Flags named inside a `[description]` are prose, not offers.
+            zspecs = re.sub(r"\[[^]\n]*\]", "", zbody)
+            flags = {o for a in actions for o in a.option_strings}
+            for flag in sorted(o for o in flags if o.startswith("--")):
+                if not re.search(rf"(?<![\w-]){re.escape(flag)}(?![\w-])", zspecs):
+                    err("completions/_sysforge", f"{cmd}: {flag} not offered in {zfn}")
+            offered = _LONG_FLAG_RE.findall(zspecs)
+            for flag in sorted(set(offered) - flags - global_flags):
+                err("completions/_sysforge", f"{cmd}: {zfn} offers {flag}, which it does not have")
+            for a in actions:
+                for value in map(str, a.choices or ()):
+                    if not re.search(rf"(?<![\w-]){re.escape(value)}(?![\w-])", zfull):
+                        err("completions/_sysforge",
+                            f"{cmd} {a.option_strings[-1]}: value {value!r} not offered")
+        bfn = "_sysforge_" + words[0].replace("-", "_")
+        bbody = bash.get(bfn)
+        if bbody is None:
+            err("completions/sysforge.bash", f"{cmd}: no {bfn} function")
+            continue
+        scope = bbody if len(path) == 1 else _bash_arm(bbody, path[-1])
+        if scope is None:
+            err("completions/sysforge.bash", f"{cmd}: no `{path[-1]})` arm in {bfn}")
+            continue
+        flags = {o for a in actions for o in a.option_strings}
+        for flag in sorted(o for o in flags if o.startswith("--")):
+            if not re.search(rf"(?<![\w-]){re.escape(flag)}(?![\w-])", scope):
+                err("completions/sysforge.bash", f"{cmd}: {flag} not offered")
+        if len(path) > 1:  # a top-level body also holds its subcommands' arms
+            for flag in sorted(set(_LONG_FLAG_RE.findall(scope)) - flags - global_flags):
+                err("completions/sysforge.bash", f"{cmd}: offers {flag}, which it does not have")
+        for a in actions:
+            if not a.choices:
+                continue
+            arm = next((_bash_arm(flag_arg, o) for o in a.option_strings
+                        if _bash_arm(flag_arg, o) is not None), None)
+            if arm is None and any(f"$prev == {o}" in scope for o in a.option_strings):
+                arm = scope  # values offered by the command itself (setup --preset)
+            if arm is None:
+                err("completions/sysforge.bash",
+                    f"{cmd} {a.option_strings[-1]}: no value case in _sysforge_flag_arg")
+                continue
+            for value in map(str, a.choices):
+                if not re.search(rf"(?<![\w-]){re.escape(value)}(?![\w-])", arm):
+                    err("completions/sysforge.bash",
+                        f"{cmd} {a.option_strings[-1]}: value {value!r} not offered")
+    return findings + _check_mirrored_lists(repo)
+
 # ===========================================================================
 # Group: completion_widths
 # ===========================================================================
@@ -1482,6 +1618,7 @@ def check_dev_install_parity(repo: Path) -> list[Finding]:
     "hooks":           check_hooks,
     "completions":     check_completions,
     "completion_widths": check_completion_widths,
+    "completion_commands": check_completion_commands,
     "versions":        check_versions,
     "manpage":         check_manpage,
     "dev_install":     check_dev_install_parity,
diff --git a/tools/check_standards.py b/tools/check_standards.py
index 79f52169..b2b653c0 100644
--- a/tools/check_standards.py
+++ b/tools/check_standards.py
@@ -88,6 +88,11 @@
                     tokens, functions) appears in a tracked file outside release
                     notes, ROADMAP, tests, the generated DESIGN.md and each
                     entry's own allow list (3.5.0-DEV12). Whole-word match.
+    citations       The claude_md citation check over docs/design/ and the
+                    tracked .claude/ agents, skills and rules (3.5.0-DEV15):
+                    cited paths, `path/module.symbol`s, .py files and `make`
+                    targets exist (a missing target only when it is a near
+                    miss of one of ours; the kernel's are quoted on purpose).
 
 Drift detection cases (verify these still fire after editing this script):
     - Add `Path.home() / ".cache/sysforge"` to a module other than paths.py.
@@ -110,6 +115,7 @@
     - Rename the symbol a shim record's anchor cites.
     - Cite `§Toolchain-variant drift detection` (no such heading) in docs/design/.
     - Write a name from tools/retired_names.toml in a comment under sysforge/.
+    - Cite `make vm-install` (the targets are vm-install-stable/-git) in docs/design/.
     - Replace the _REGISTRY literal with a comprehension (parse finds 0 records).
     - Run with --target-version=3.0.0 while a 3.0.0 removal is still present.
     - Break deprecations.py syntactically and run --check=semver_bump alone
@@ -491,8 +497,90 @@ def _resolve_module_file(repo: Path, name: str) -> Path | None:
     return hits[0] if len(hits) == 1 else None
 
 
+# Things cited on purpose after their removal, in a passage about that history.
+_CITATION_HISTORY = {"doctor.flat_flags", "_DOCTOR_MIGRATION", "_prompt_llvm_recovery",
+                     "from_fix_suggestion", "from_toolchain_check"}
+# Names from other software the docs quote: pacman, LLVM, systemd-boot, sysctl,
+# makechrootpkg, and PKGBUILD example variables.
+_CITATION_EXTERNAL = {"IgnorePkg", "InitializeAllTargets", "LoaderEntryDefault",
+                      "kptr_restrict", "unprivileged_bpf_disabled", "install_packages",
+                      "depends_x86_64", "sha256sums_x86_64", "package_bar", "_pkgver"}
+# A bare code name: `_private`, `snake_case_name`, `CamelCase` (3.5.0-DEV15).
+_CODE_NAME_RE = re.compile(
+    r"^(?:_[A-Za-z0-9_]+|[a-z][a-z0-9]*(?:_[a-z0-9]+)+|[A-Z][a-z0-9]+(?:[A-Z][a-z0-9]+)+)$")
+_CODE_WORDS: dict[str, set[str]] = {}
+
+
+def _code_words(repo: Path) -> set[str]:
+    """Every identifier-shaped word in the repo's tracked non-doc files."""
+    key = str(repo)
+    if key not in _CODE_WORDS:
+        words: set[str] = set()
+        for path in _tracked_text_files(repo):
+            rel = path.relative_to(repo).as_posix()
+            if rel.startswith(("docs/", ".claude/")) or rel.endswith(".md"):
+                continue
+            try:
+                words |= set(re.findall(r"[A-Za-z_][A-Za-z0-9_]*",
+                                        path.read_text(encoding="utf-8")))
+            except (OSError, UnicodeDecodeError):
+                continue
+        _CODE_WORDS[key] = words
+    return _CODE_WORDS[key]
+# The repo's own top-level and package directories: a path into one of these is
+# a citation even if that whole directory is gone.
+_REPO_TOP_DIRS = {"tools", "tests", "docs", "sysforge", "etc", "completions", "man",
+                  "primitives", "pipeline", "verbs", "build", "ui"}
+# Local variables the design prose names attributes of: `run.plan` is update's
+# UpdateRun record, not primitives/run.py.
+_CITATION_LOCALS = {"run", "self", "args", "options", "opts", "state", "registry"}
+# A version or name placeholder (`docs/release-notes/vX.Y.Z.md`).
+_PLACEHOLDER_RE = re.compile(r"X\.Y|\bvX\b|\bNN\b|\bNAME\b")
+
+
+def _make_targets(repo: Path) -> set[str]:
+    mk = repo / "Makefile"
+    if not mk.is_file():
+        return set()
+    return set(re.findall(r"^([A-Za-z0-9_.-]+)\s*:(?!=)", mk.read_text(encoding="utf-8"),
+                          re.MULTILINE))
+
+
+def _git_ignored(repo: Path, rel: str) -> bool:
+    """A gitignored path is generated: it exists after a build, never in a clean
+    checkout, so whether it exists here depends on the machine."""
+    r = subprocess.run(["git", "-C", str(repo), "check-ignore", "-q", "--no-index", rel],
+                       capture_output=True)
+    return r.returncode == 0
+
+
 def _check_citation(repo: Path, token: str) -> str | None:
     """Return an error message for a stale citation, or None (ok/skipped)."""
+    # `make <target> ...` (3.5.0-DEV15): the target must exist.
+    if token.startswith("make ") and len(token.split()) >= 2:
+        target = token.split()[1]
+        if re.fullmatch(r"[a-z][\w-]*", target) and "=" not in target:
+            import difflib
+            targets = _make_targets(repo)
+            # Only a near miss of one of ours is stale; `make nconfig` and
+            # `make htmldocs` are the kernel's targets, quoted on purpose.
+            near = ([t for t in sorted(targets) if t.startswith(target + "-")]
+                    or difflib.get_close_matches(target, sorted(targets), n=1, cutoff=0.85))
+            if targets and target not in targets and near:
+                return (f"cites `{token}` but the Makefile has no `{target}` target "
+                        f"(did it become `{near[0]}`?)")
+        return None
+    if token in _CITATION_HISTORY or _PLACEHOLDER_RE.search(token):
+        return None
+    if token.split(".")[0] in _CITATION_LOCALS and "/" not in token:
+        return None
+    # A bare code name with no module to resolve it against: it must at least
+    # exist somewhere in the code (`_confirm_or_abort` had been gone for years).
+    bare = token.split("(", 1)[0]
+    if _CODE_NAME_RE.match(bare) and bare not in _CITATION_EXTERNAL:
+        if bare not in _code_words(repo):
+            return f"cites `{bare}`, which nothing in the code defines or uses"
+        return None
     # `file.py::symbol` — resolve the file, then grep for the symbol.
     if "::" in token:
         file_part, _, sym = token.partition("::")
@@ -517,11 +605,42 @@ def _check_citation(repo: Path, token: str) -> str | None:
         rel = token.rstrip("/")
         if (repo / rel).exists() or (repo / "sysforge" / rel).exists():
             return None
+        # Only a path into this repo can be stale; `root/usr/bin`, `and/or` and
+        # runtime paths start with a segment the repo does not have.
+        first = rel.split("/")[0]
+        if first not in _REPO_TOP_DIRS and not (
+                (repo / first).exists() or (repo / "sysforge" / first).exists()):
+            return None
+        # `etc/pam.d`, `etc/sudoers.d`: system paths; the repo's etc/ holds
+        # only what it ships.
+        parts = rel.split("/")
+        if first == "etc" and len(parts) > 1 and not (repo / "etc" / parts[1]).exists():
+            return None
+        if rel.startswith("sysforge/_data"):
+            return None  # exists only in the built wheel (force-include)
+        if _git_ignored(repo, rel):
+            return None  # a generated intermediate (`man/sysforge.1.scd`)
+        # `primitives/artifacts.unified_rows`: a module path, then a symbol.
+        head, _, tail = rel.rpartition("/")
+        modname, dot, sym = tail.partition(".")
+        if not dot and any((b / head / f"{tail}.py").is_file() for b in (repo, repo / "sysforge")):
+            return None  # `primitives/install_reconcile`: a module named without .py
+        if dot and sym and Path(tail).suffix not in (".py", ".md", ".sh", ".toml", ".json"):
+            for base in (repo, repo / "sysforge"):
+                mod = base / head / f"{modname}.py"
+                if mod.is_file():
+                    if sym.split(".")[0] not in mod.read_text(encoding="utf-8"):
+                        return (f"cites `{token}` but {mod.relative_to(repo)} has no "
+                                f"`{sym.split('.')[0]}`")
+                    return None
         return f"cites path `{token}` which does not exist"
 
     # Bare script/module filename: resolvable anywhere in the tree.
-    if token.endswith((".py", ".sh")):
-        if (repo / token).exists() or _resolve_module_file(repo, token.rsplit(".", 1)[0]):
+    if token.endswith(".sh"):
+        return None  # a bare script name is as often the kernel's or the user's
+    if token.endswith(".py"):
+        if (repo / token).exists() or any(
+                not _CLAUDE_MD_SKIP_DIRS & set(p.parts) for p in repo.rglob(token)):
             return None
         return f"cites `{token}` — no such file in the tree"
 
@@ -553,6 +672,12 @@ def _check_citation(repo: Path, token: str) -> str | None:
         if mod is None:
             return None  # can't map — skip, fail-safe
         if sym_segs and sym_segs[0] not in mod.read_text(encoding="utf-8"):
+            # Several modules share a name (the kernel stage's config.py beside
+            # primitives/config.py): any of them defining it will do.
+            same = [p for p in repo.rglob(f"{segs[0]}.py")
+                    if not _CLAUDE_MD_SKIP_DIRS & set(p.parts)]
+            if any(sym_segs[0] in p.read_text(encoding="utf-8") for p in same):
+                return None
             return (f"cites `{token}` but {mod.relative_to(repo)} "
                     f"has no `{sym_segs[0]}`")
     return None
@@ -565,7 +690,7 @@ def check_claude_md(repo: Path) -> list[Finding]:
             continue
         rel = md.relative_to(repo).as_posix()
         seen: set[str] = set()
-        for token in _BACKTICK_RE.findall(md.read_text(encoding="utf-8")):
+        for token in _inline_code(md.read_text(encoding="utf-8")):
             token = token.strip()
             if token in seen:
                 continue
@@ -576,6 +701,47 @@ def check_claude_md(repo: Path) -> list[Finding]:
     return findings
 
 
+
+def _inline_code(text: str) -> list[str]:
+    """Inline code spans, paired within each line, fenced blocks dropped: a
+    ``` fence pairs with the next lone backtick otherwise and shifts every
+    span after it, which hid a stale path in a skill file."""
+    text = re.sub(r"^\s*```.*?^\s*```", "", text, flags=re.MULTILINE | re.DOTALL)
+    return [t for line in text.splitlines() for t in _BACKTICK_RE.findall(line)]
+
+
+def _citation_findings(repo: Path, files: list[Path], group: str) -> list[Finding]:
+    findings: list[Finding] = []
+    for md in files:
+        rel = md.relative_to(repo).as_posix()
+        seen: set[str] = set()
+        for token in _inline_code(md.read_text(encoding="utf-8")):
+            token = token.strip()
+            if token in seen:
+                continue
+            seen.add(token)
+            msg = _check_citation(repo, token)
+            if msg:
+                findings.append(Finding(group, "error", rel, msg))
+    return findings
+
+
+def check_citations(repo: Path) -> list[Finding]:
+    """The CLAUDE.md citation check, over the design docs and the tracked
+    `.claude/` agents, skills and rules (3.5.0-DEV15): every cited path, module
+    symbol, script and `make` target exists. Those files steer contributors and
+    agents as much as CLAUDE.md does, and went stale the same way."""
+    files = sorted((repo / "docs/design").rglob("*.md"))
+    claude = repo / ".claude"
+    if claude.is_dir():
+        try:
+            out = subprocess.run(["git", "-C", str(repo), "ls-files", "-z", ".claude"],
+                                 capture_output=True, check=True).stdout.decode()
+            files += sorted(repo / n for n in out.split("\0") if n.endswith(".md"))
+        except (OSError, subprocess.CalledProcessError):
+            files += sorted(claude.rglob("*.md"))
+    return _citation_findings(repo, [f for f in files if f.is_file()], "citations")
+
 # ===========================================================================
 # Group: roadmap_ids  (ROADMAP.md <-> release-notes ID collision detection)
 # ===========================================================================
@@ -1973,6 +2139,7 @@ def check_retired_names(repo: Path) -> list[Finding]:
     "standards_rows": check_standards_rows,
     "design_refs":    check_design_refs,
     "retired_names":  check_retired_names,
+    "citations":      check_citations,
 }
 
 
diff --git a/tools/gen_options.py b/tools/gen_options.py
index e9bf0f33..72e25182 100644
--- a/tools/gen_options.py
+++ b/tools/gen_options.py
@@ -34,6 +34,8 @@
 
 MARKER = "@OPTIONS@"
 SHARED_MARKER = "@SHARED_OPTIONS@"
+ENV_MARKER = "@ENVIRONMENT@"
+JOURNAL_MARKER = "@JOURNAL@"
 
 # Per-command configuration/environment summary, rendered as a trailer after
 # each command's option blocks. Values are raw scdoc (not escaped). Keyed by
@@ -277,6 +279,43 @@ def _fill(template: str, marker: str, lines: list[str]) -> str | None:
     return rendered
 
 
+def _wrap(text: str) -> list[str]:
+    """Tab-indented scdoc paragraph lines. scdoc reads a line starting with
+    `[`, `|` or `-` as a table or list, so such a word is kept on the line
+    before it."""
+    import textwrap
+    lines: list[str] = []
+    for line in textwrap.wrap(text, width=66):
+        if lines and line[:1] in "[|-":
+            lines[-1] += " " + line
+        else:
+            lines.append(line)
+    return ["\t" + line for line in lines]
+
+
+def render_environment() -> list[str]:
+    """The ENVIRONMENT section body, from primitives/env_vars.ENV_VARS
+    (3.5.0-B128): user settings first, then the diagnostic switches."""
+    from sysforge.primitives.env_vars import ENV_VARS
+    lines: list[str] = []
+    ordered = [v for v in ENV_VARS if v.audience == "user"] + \
+              [v for v in ENV_VARS if v.audience == "diagnostic"]
+    for var in ordered:
+        label = var.name + (" (diagnostic)" if var.audience == "diagnostic" else "")
+        lines += [label, *_wrap(var.text), ""]
+    return lines[:-1]
+
+
+def render_journal() -> list[str]:
+    """The JOURNAL section's field list, from primitives/journal.JOURNAL_FIELDS
+    (3.5.0-DOC13)."""
+    from sysforge.primitives.journal import JOURNAL_FIELDS
+    lines: list[str] = []
+    for name, text in JOURNAL_FIELDS:
+        lines += [name, *_wrap(text), ""]
+    return lines[:-1]
+
+
 def main() -> int:
     ap_ = argparse.ArgumentParser(description=__doc__)
     ap_.add_argument("--template", required=True)
@@ -286,7 +325,9 @@ def main() -> int:
     shared_lines, command_lines = render(build_parser(), tiered_command_order())
 
     rendered = Path(ns.template).read_text(encoding="utf-8")
-    for marker, lines in ((SHARED_MARKER, shared_lines), (MARKER, command_lines)):
+    for marker, lines in ((SHARED_MARKER, shared_lines), (MARKER, command_lines),
+                          (ENV_MARKER, render_environment()),
+                          (JOURNAL_MARKER, render_journal())):
         filled = _fill(rendered, marker, lines)
         if filled is None:
             print(f"error: marker {marker} not found in {ns.template}",
diff --git a/tools/pre-commit.sh b/tools/pre-commit.sh
new file mode 100755
index 00000000..c4a2f4e3
--- /dev/null
+++ b/tools/pre-commit.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+# SPDX-FileCopyrightText: 2026 Keith Raghubar
+#
+# SPDX-License-Identifier: MIT
+
+# Pre-commit hook (`make install-hooks`, 3.5.0-DEV18): the fast gates, so most
+# CI failures show up before a push. The test suite stays in CI and
+# `make pre-release`. Skip once with `git commit --no-verify`.
+set -euo pipefail
+cd "$(git rev-parse --show-toplevel)"
+exec make -s --no-print-directory lint check-shipped check-design check-standards check-surface
diff --git a/tools/release.sh b/tools/release.sh
index ff569331..52de0688 100755
--- a/tools/release.sh
+++ b/tools/release.sh
@@ -361,6 +361,12 @@ preflight_fresh() {
         echo "ERROR: standards checks failed — fix the findings above and re-run." >&2
         exit 1
     fi
+    # Surface snapshot gate (3.5.0-DEV18): tests/data/surface.json current, and
+    # every surface change since the last commit recorded in the release notes.
+    if ! make --no-print-directory check-surface >&2; then
+        echo "ERROR: surface snapshot stale or a change unrecorded — see above; 'make surface' regenerates it." >&2
+        exit 1
+    fi
     # Version-relative rules need the version being released, which `make
     # check-standards` cannot know (it runs before the bump). Re-run the two
     # version-aware groups against $NEW: R3 (a declared removal still present)
diff --git a/tools/retired_names.toml b/tools/retired_names.toml
index c02ab3de..8d91ea3c 100644
--- a/tools/retired_names.toml
+++ b/tools/retired_names.toml
@@ -85,6 +85,9 @@ allow = [
     "docs/design/10-flag-profile-system.md",
     "docs/design/21-standards.md",
     "etc/sysforge/profiles.toml",
+    # the live-config repair that rewrites it (3.5.0-F18)
+    "sysforge/primitives/config_schema.py",
+    "docs/design/06-config-layer.md",
 ]
 
 # --- 3.5.0-F17: mesa PGO is generic -----------------------------------------
diff --git a/tools/surface.py b/tools/surface.py
new file mode 100644
index 00000000..d85fd15c
--- /dev/null
+++ b/tools/surface.py
@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+
+# SPDX-FileCopyrightText: 2026 Keith Raghubar
+#
+# SPDX-License-Identifier: MIT
+
+"""
+tools/surface.py — the committed snapshot of every user-facing surface (3.5.0-DEV18).
+
+tests/data/surface.json lists what a user can type, set or parse: every command
+with its flags and their allowed values, the environment variables and journal
+fields, each config file's sections and keys, the fields of each `--json`
+document, and the run-log names. It is generated, like DESIGN.md and the man
+page, so a change to any surface shows up as a diff of that one file, which is
+where a reviewer looks.
+
+    --write          regenerate the snapshot (`make surface`)
+    --check          the gate (`make check-surface`):
+                       1. the committed snapshot matches the code;
+                       2. against the base (the merge-base with main, or the
+                          previous commit on main itself), every added or
+                          removed entry is named in text this change adds to
+                          docs/release-notes/unreleased.md;
+                       3. a flag, command, environment variable or config key
+                          that leaves the product entirely is registered as
+                          retired (tools/retired_names.toml, or for a config
+                          key config_schema.RETIRED_KEYS), so it cannot creep
+                          back unnoticed.
+                     With no snapshot at the base (its first introduction) or
+                     no base at all, step 1 runs alone.
+    --base REF       compare against REF instead.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+if str(REPO) not in sys.path:
+    sys.path.insert(0, str(REPO))
+
+SNAPSHOT = "tests/data/surface.json"
+NOTES = "docs/release-notes/unreleased.md"
+
+
+# ---------------------------------------------------------------------------
+# Collecting
+# ---------------------------------------------------------------------------
+
+def _commands() -> dict:
+    import argparse as ap
+
+    from sysforge.verbs.registry import build_parser
+
+    out: dict = {}
+
+    def walk(parser, path):
+        flags, positionals = {}, {}
+        subs = None
+        for a in parser._actions:
+            if isinstance(a, ap._SubParsersAction):
+                subs = a
+                continue
+            if a.dest == "help":
+                continue
+            values = sorted(map(str, a.choices)) if a.choices else None
+            if a.option_strings:
+                flags[max(a.option_strings, key=len)] = values
+            else:
+                positionals[a.metavar or a.dest] = values
+        # A group parent takes nothing itself; its subcommands carry it all.
+        if not (path and subs is not None and not flags and not positionals):
+            out[" ".join(path)] = {"flags": dict(sorted(flags.items())),
+                                   "positionals": positionals}
+        if subs is not None:
+            for name, sub in subs.choices.items():
+                if (path + [name])[0] == "completions":
+                    continue  # the completion scripts' own plumbing
+                walk(sub, path + [name])
+
+    walk(build_parser(), [])
+    return dict(sorted(out.items()))
+
+
+def _json_fields(schema: dict, prefix: str = "") -> list[str]:
+    fields = []
+    for name, sub in sorted(schema.get("properties", {}).items()):
+        path = f"{prefix}.{name}" if prefix else name
+        fields.append(path)
+        if sub.get("type") == "array" and isinstance(sub.get("items"), dict):
+            fields += _json_fields(sub["items"], path + "[]")
+        elif "properties" in sub:
+            fields += _json_fields(sub, path)
+    return fields
+
+
+def collect() -> dict:
+    from sysforge.primitives import config_schema as cs
+    from sysforge.primitives.env_vars import ENV_VARS
+    from sysforge.primitives.journal import JOURNAL_FIELDS
+    from sysforge.verbs.registry import verb_log_names
+
+    config = {}
+    for name in cs.CONFIG_FILES:
+        documented = cs._documented(cs.shipped_text(name) or "")
+        sections = {}
+        for section in sorted(cs.KNOWN_SECTIONS[name]):
+            sections[section] = (None if section in cs.OPEN_SECTIONS.get(name, set())
+                                 else sorted(documented.get(section, set())))
+        config[name] = {"top_level": sorted(cs.KNOWN_TOP_KEYS[name]), "sections": sections}
+    schemas = {}
+    for path in sorted((REPO / "tests/data/json-schema").glob("*.schema.json")):
+        schemas[path.name.removesuffix(".schema.json")] = _json_fields(
+            json.loads(path.read_text(encoding="utf-8")))
+    return {
+        "commands": _commands(),
+        "environment": sorted(v.name for v in ENV_VARS),
+        "journal_fields": sorted(f for f, _ in JOURNAL_FIELDS),
+        "config": config,
+        "json": schemas,
+        "run_logs": verb_log_names(),
+    }
+
+
+def render(surface: dict) -> str:
+    return json.dumps(surface, indent=1, sort_keys=False) + "\n"
+
+
+# ---------------------------------------------------------------------------
+# Comparing
+# ---------------------------------------------------------------------------
+
+def entries(surface: dict) -> dict[str, str]:
+    """Flatten a snapshot to {entry id: the name a release note would use}."""
+    out: dict[str, str] = {}
+    for cmd, spec in surface.get("commands", {}).items():
+        if cmd:
+            out[f"command: {cmd}"] = cmd
+        for flag, values in spec.get("flags", {}).items():
+            out[f"flag: {cmd} {flag}".replace("  ", " ")] = flag
+            for v in values or []:
+                out[f"value: {cmd} {flag}={v}".replace("  ", " ")] = v
+        for pos, values in spec.get("positionals", {}).items():
+            for v in values or []:
+                out[f"value: {cmd} {pos}={v}"] = v
+    for name in surface.get("environment", []):
+        out[f"environment: {name}"] = name
+    for name in surface.get("journal_fields", []):
+        out[f"journal field: {name}"] = name
+    for file, spec in surface.get("config", {}).items():
+        for key in spec.get("top_level", []):
+            out[f"config: {file} {key}"] = key
+        for section, keys in spec.get("sections", {}).items():
+            out[f"config: {file} [{section}]"] = section
+            for key in keys or []:
+                out[f"config: {file} [{section}] {key}"] = key
+    for kind, fields in surface.get("json", {}).items():
+        out[f"json: {kind}"] = kind
+        for field in fields:
+            out[f"json: {kind}.{field}"] = field.rsplit(".", 1)[-1].removesuffix("[]")
+    for name in surface.get("run_logs", []):
+        out[f"run log: {name}"] = name
+    return out
+
+
+def _all_names(surface: dict, kinds: tuple[str, ...]) -> set[str]:
+    return {name for eid, name in entries(surface).items() if eid.split(":")[0] in kinds}
+
+
+def _retired(repo: Path) -> set[str]:
+    names = set()
+    reg = repo / "tools/retired_names.toml"
+    if reg.is_file():
+        names |= {e["name"] for e in tomllib.loads(reg.read_text(encoding="utf-8"))
+                  .get("retired", [])}
+    from sysforge.primitives import config_schema as cs
+    names |= {r.key for r in cs.RETIRED_KEYS}
+    return names
+
+
+def judge(base: dict, head: dict, added_notes: str, retired: set[str]) -> list[str]:
+    """Problems with going from ``base`` to ``head``; [] when it is fine."""
+    old, new = entries(base), entries(head)
+    problems = []
+    for eid in sorted(set(new) - set(old)):
+        if not re.search(rf"(?<![\w-]){re.escape(new[eid])}(?![\w-])", added_notes):
+            problems.append(f"added {eid}: name `{new[eid]}` in a release-note entry")
+    gone_everywhere = {
+        "flag": _all_names(base, ("flag",)) - _all_names(head, ("flag",)),
+        "command": _all_names(base, ("command",)) - _all_names(head, ("command",)),
+        "environment": _all_names(base, ("environment",)) - _all_names(head, ("environment",)),
+        "config": _all_names(base, ("config",)) - _all_names(head, ("config",)),
+    }
+    for eid in sorted(set(old) - set(new)):
+        name = old[eid]
+        if not re.search(rf"(?<![\w-]){re.escape(name)}(?![\w-])", added_notes):
+            problems.append(f"removed {eid}: name `{name}` in a release-note entry")
+        kind = eid.split(":")[0]
+        if kind in gone_everywhere and name in gone_everywhere[kind] and name not in retired:
+            problems.append(f"removed {eid}: `{name}` is gone entirely; add it to "
+                            "tools/retired_names.toml (a config key: "
+                            "config_schema.RETIRED_KEYS)")
+    return problems
+
+
+# ---------------------------------------------------------------------------
+# Git
+# ---------------------------------------------------------------------------
+
+def _git(*args: str) -> str | None:
+    r = subprocess.run(["git", "-C", str(REPO), *args], capture_output=True, text=True)
+    return r.stdout if r.returncode == 0 else None
+
+
+def default_base() -> str | None:
+    """The merge-base with main (origin/main first, as in CI); on main itself,
+    the previous commit, since a squash merge lands as one."""
+    head = (_git("rev-parse", "HEAD") or "").strip()
+    for ref in ("origin/main", "main"):
+        base = (_git("merge-base", "HEAD", ref) or "").strip()
+        if base and base != head:
+            return base
+        if base == head:
+            prev = (_git("rev-parse", "HEAD^") or "").strip()
+            return prev or None
+    return None
+
+
+def _added_text(base: str) -> str:
+    """Lines this change adds to the release notes (the whole file when the base
+    has none)."""
+    old = _git("show", f"{base}:{NOTES}") or ""
+    new = (REPO / NOTES).read_text(encoding="utf-8") if (REPO / NOTES).is_file() else ""
+    old_lines = set(old.splitlines())
+    return "\n".join(line for line in new.splitlines() if line not in old_lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    mode = p.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--write", action="store_true")
+    mode.add_argument("--check", action="store_true")
+    p.add_argument("--base", metavar="REF")
+    args = p.parse_args(argv)
+    current = collect()
+    path = REPO / SNAPSHOT
+    if args.write:
+        path.write_text(render(current), encoding="utf-8")
+        print(f"wrote {SNAPSHOT}")
+        return 0
+    if not path.is_file() or path.read_text(encoding="utf-8") != render(current):
+        print(f"[FAIL] {SNAPSHOT} is out of date with the code: run `make surface` and "
+              "commit it (its diff is the surface change to review)")
+        return 1
+    base = args.base or default_base()
+    base_snapshot = _git("show", f"{base}:{SNAPSHOT}") if base else None
+    if base is None or base_snapshot is None:
+        print(f"[OK]   {SNAPSHOT} is current (no snapshot at the base to compare with)")
+        return 0
+    problems = judge(json.loads(base_snapshot), current, _added_text(base), _retired(REPO))
+    if problems:
+        print(f"[FAIL] surface changes since {base[:12]} need a release note or a "
+              "retirement record:")
+        for problem in problems:
+            print(f"  {problem}")
+        return 1
+    print(f"[OK]   {SNAPSHOT} is current, and every change since {base[:12]} is recorded")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())