diff --git a/.agents/skills/init/SKILL.md b/.agents/skills/init/SKILL.md
index b76b0b8..281fa4d 100644
--- a/.agents/skills/init/SKILL.md
+++ b/.agents/skills/init/SKILL.md
@@ -9,7 +9,7 @@ description: >-
 
 Use this command only when the repository does not already have valid V3 `llmdoc/`.
 
-Load the `llmdoc` skill before broad exploration.
+Load the `llmdoc` skill before broad exploration. CLI commands below run as `npx -y @tokenroll/llmdoc <cmd>`.
 
 ## Authorization
 
@@ -28,7 +28,7 @@ Stop instead of improvising when:
 
 - `git status -- llmdoc/` must be clean before the first formal write.
 - Rollback for init means deleting the newly created `llmdoc/` surface (it did not exist before this run); never leave a half-bootstrapped tree behind.
-- If `npx @tokenroll/llmdoc validate` fails after writes, revert the init write-set before reporting failure.
+- If `validate` fails after writes, revert the init write-set before reporting failure.
 
 ## Workflow
 
@@ -44,8 +44,8 @@ Stop instead of improvising when:
    - Create the V3 root singleton plus one-level topic directories; topics are plain directories with no `index.mdx` entry node.
 
 3. Validate before reporting success.
-   - Seed the ledger with `npx @tokenroll/llmdoc init-state` (writes meta.json with null revisions), then run `npx @tokenroll/llmdoc validate` and fix all schema, routing, and reference failures.
-   - Finalize with `npx @tokenroll/llmdoc commit --all -m "docs: bootstrap llmdoc"` — it commits the surface, brands fingerprints, and lands the meta follow-up commit in one step.
+   - Seed the ledger with `init-state` (writes meta.json with null revisions), then run `validate` and fix all schema, routing, and reference failures.
+   - Finalize with `commit --all -m "docs: bootstrap llmdoc"` — it commits the surface, brands fingerprints, and lands the meta follow-up commit in one step.
    - On a validation failure that cannot be repaired in-run, roll back the init write-set.
 
 ## State Invariants
@@ -67,5 +67,5 @@ Always report:
 - whether init ran or was refused
 - the investigation report path or paths used
 - the topics and stable docs created
-- the `npx @tokenroll/llmdoc validate` result
+- the `validate` and `commit` results
 - any material gaps left for later `/llmdoc:update`
diff --git a/.agents/skills/llmdoc/SKILL.md b/.agents/skills/llmdoc/SKILL.md
index 27ff247..2ff6189 100644
--- a/.agents/skills/llmdoc/SKILL.md
+++ b/.agents/skills/llmdoc/SKILL.md
@@ -1,56 +1,56 @@
 ---
 name: llmdoc
 description: >-
-  Default V3 operating skill for llmdoc-enabled projects. Route broad or
-  cross-subsystem discovery through the CLI retrieval surface.
+  Default V3 operating skill for llmdoc-enabled projects. Route discovery —
+  exploring the codebase, locating a concept or contract, judging the blast
+  radius of a change — through the llmdoc CLI instead of broad file crawling.
 allowed-tools: 'Read, Glob, Grep, Bash, Write, Edit, WebSearch, WebFetch'
 ---
 
 # /llmdoc
 
-This skill is the operating protocol for V3 `llmdoc` projects.
+The operating protocol for V3 `llmdoc` projects. `llmdoc/` holds the architecture, constraints, and working agreements that source code does not cheaply give back; the CLI is how you reach them.
+
+Every command below runs as `npx -y @tokenroll/llmdoc <cmd>`; the CLI Invocation section holds the full rules.
 
 ## Retrieval Gate
 
-Treat `@tokenroll/llmdoc` as external tooling and invoke it as
-`npx -y @tokenroll/llmdoc ...`. A missing package may be fetched into the npm
-cache, but it must never be added to the consumer repository's `package.json`
-or lockfile. Pin the version in the npx package spec when reproducibility
-requires it. If the CLI remains unavailable, report the degraded path and
-continue with narrowly scoped native tools.
-
-Before the first discovery action for a task—and again whenever the
-investigation expands into a new subsystem—choose the matching entry point:
-
-- Concept, contract, term, or “where is X?” → `search <query>`.
-- Background or impact of concrete source files → `context --files <path...>`.
-- Cold start or unclear scope → `tree`.
-- Known topic or document kind → `index --topic <topic>` / `--kind <kind>`.
-- Body of already identified llmdoc documents → `show <path...>`.
-- Exact source text, line numbers, tests, counts, git state, or other live facts
-  inside an established working set → native source and shell tools.
-
-Broad native discovery means recursive or cross-directory exploration outside
-the working set already identified by llmdoc. Before doing that with Read,
-Grep, Glob, or shell commands, apply this gate.
-
-Once llmdoc has narrowed the working set, use native tools for exact source
-verification. Do not run every retrieval command as a fixed sequence. Read
-only enough to answer the task. “Stop as soon as you have enough context”
-applies after selecting the entry point; it does not authorize skipping this
-gate.
-
-`status` and `delta` are not retrieval. Use them only when assessing staleness
-or preparing `/llmdoc:update`; `delta` decides light vs deep.
+Apply this gate before the first discovery action of a task, and again whenever investigation crosses into a new subsystem. Choose the one entry point that matches the intent:
+
+| Intent | Entry point |
+|---|---|
+| Concept, contract, term, "where is X?" | `search <query>` |
+| Background or blast radius of concrete source files | `context --files <path...>` |
+| Cold start, unclear scope | `tree` |
+| Known topic or document kind | `index --topic <topic>` / `--kind <kind>` |
+| Bodies of documents already identified | `show <path...>` |
+
+The gate guards broad native discovery: recursive or cross-directory exploration with Read, Grep, Glob, or shell outside a working set llmdoc has already narrowed.
+
+Once llmdoc has narrowed that working set, native tools own the exact facts — source text, line numbers, test behavior, counts, git state. The knowledge surface deliberately does not duplicate those.
+
+These entry points are alternatives, not a sequence. Stop as soon as the task has enough context; that permission applies after choosing an entry point, never instead of choosing one.
+
+`status` and `delta` are not retrieval. Use them to assess staleness or to prepare `/llmdoc:update`, where `delta` decides light vs deep.
+
+## CLI Invocation
+
+`@tokenroll/llmdoc` is external tooling, not a project dependency. `-y` lets a missing package resolve into the npm cache without a prompt.
+
+- Never add it to the served project's `package.json` or lockfile.
+- Pin in the package spec when reproducibility matters: `npx -y @tokenroll/llmdoc@<version> <cmd>`.
+- Never call a bare `npx llmdoc`; that name resolves to an unrelated package.
+- If the CLI stays unavailable, report the degraded path, then continue with narrowly scoped native tools.
 
 ## Operating Rules
 
 - Preserve and reuse `LLMDOC_STATE` across continuation; do not replay prior reads unless evidence changed or the task moved.
 - Temporary investigation notes belong in `.llmdoc-tmp/`, not in stable docs.
-- Stable llmdoc writes belong to `recorder`.
-- Before non-trivial edits, the main assistant should align with the user.
+- Stable `llmdoc/` writes belong to `recorder`; `llmdoc/meta.json` changes go through the CLI only.
+- Before non-trivial edits, align with the user.
 - If `llmdoc/` does not exist, suggest `/llmdoc:init`; do not fabricate the knowledge surface ad hoc.
 - When a task produces durable knowledge changes, suggest `/llmdoc:update` at the end.
+- Never suggest `/llmdoc:upgrade`; it runs only when the user asks for it by name.
 
 ## Continuation State
 
@@ -67,5 +67,5 @@ If that state is still sufficient, continue without re-running `tree`, `index`,
 
 ## Roles
 
-- `investigator`: current-state research, scoped evidence gathering, scratch reports
-- `recorder`: stable llmdoc updates; `llmdoc/meta.json` changes go through the CLI only
+- `investigator`: current-state research, scoped evidence gathering, scratch reports under `.llmdoc-tmp/`
+- `recorder`: the only writer of tracked `llmdoc/` knowledge
diff --git a/.agents/skills/prune/SKILL.md b/.agents/skills/prune/SKILL.md
index 299ffc1..66d667c 100644
--- a/.agents/skills/prune/SKILL.md
+++ b/.agents/skills/prune/SKILL.md
@@ -10,7 +10,7 @@ argument-hint: '[--scope <topic|path...>] [summary]'
 
 Use this command only when existing `llmdoc/` knowledge needs convergence after growth, duplication, or fragmentation.
 
-Load the `llmdoc` skill before broad exploration.
+Load the `llmdoc` skill before broad exploration. CLI commands below run as `npx -y @tokenroll/llmdoc <cmd>`.
 
 ## Authorization
 
@@ -26,12 +26,13 @@ This command does not authorize source-code edits.
 
 - `git status -- llmdoc/` must be clean before the first formal write.
 - Rollback means `git checkout -- llmdoc/` (plus deleting any newly created files under `llmdoc/`); never hand-edit files back.
-- If `npx @tokenroll/llmdoc validate` fails after pruning writes and cannot be repaired in-run, roll back the prune write-set before reporting failure.
+- If `validate` fails after pruning writes and cannot be repaired in-run, roll back the prune write-set before reporting failure.
 
 ## Workflow
 
-1. Run `npx @tokenroll/llmdoc prune --report`.
+1. Run `prune --report`.
    - Use the report as the primary convergence signal.
+   - The CLI only reports; it never rewrites docs on its own.
 
 2. Decide the convergence plan with `recorder`.
    - Merge duplicated docs.
@@ -39,10 +40,10 @@ This command does not authorize source-code edits.
    - Delete docs only when their knowledge is preserved elsewhere or proven obsolete.
 
 3. Re-validate the result.
-   - Run `npx @tokenroll/llmdoc validate`.
-   - Re-run `npx @tokenroll/llmdoc prune --report` and compare document/token scale with the first report.
+   - Run `validate`.
+   - Re-run `prune --report` and compare document/token scale with the first report.
    - Confirm the surviving union of `code.paths` has not lost covered implementation paths.
-   - Finalize with `npx @tokenroll/llmdoc commit -m "<message>"`, which fingerprints the surviving docs and lands the `meta.json` follow-up commit automatically.
+   - Finalize with `commit -m "<message>"`, which fingerprints the surviving docs and lands the `meta.json` follow-up commit automatically.
    - Report `success` and refresh convergence only when scale actually declines without coverage loss; otherwise repair, roll back, or report `no_change` as appropriate.
 
 ## State Invariants
@@ -63,5 +64,5 @@ Always report:
 
 - the `prune --report` signal that justified the run
 - which docs were merged, rewritten, or deleted
-- the `validate` result
+- the `validate` and `commit` results
 - whether convergence improved without losing coverage
diff --git a/.agents/skills/update/SKILL.md b/.agents/skills/update/SKILL.md
index efbec3c..f1b11ed 100644
--- a/.agents/skills/update/SKILL.md
+++ b/.agents/skills/update/SKILL.md
@@ -8,7 +8,7 @@ argument-hint: '[summary] [--scope <topic|path...>]'
 
 Use this command when repository knowledge has changed and tracked `llmdoc/` must be synchronized.
 
-Load the `llmdoc` skill before broad exploration.
+Load the `llmdoc` skill before broad exploration. CLI commands below run as `npx -y @tokenroll/llmdoc <cmd>`.
 
 ## Authorization
 
@@ -24,13 +24,13 @@ This command does not authorize source-code edits.
 
 - `git status -- llmdoc/` must be clean before the first formal write.
 - Rollback means `git checkout -- llmdoc/` (plus deleting any newly created files under `llmdoc/`); never hand-edit files back.
-- If `npx @tokenroll/llmdoc validate` fails after writes and cannot be repaired in-run, roll back the doc write-set before reporting failure.
+- If `validate` fails after writes and cannot be repaired in-run, roll back the doc write-set before reporting failure.
 
 ## Workflow
 
 1. Measure the current doc state.
-   - Run `npx @tokenroll/llmdoc status`.
-   - Run `npx @tokenroll/llmdoc delta` with any explicit scope flags.
+   - Run `status`.
+   - Run `delta` with any explicit scope flags.
 
 2. Choose the lightest sufficient path from the delta result.
    - Light: impacted docs are already mapped and facts are straightforward.
@@ -40,9 +40,9 @@ This command does not authorize source-code edits.
    - Light: `recorder` updates the impacted docs directly from `delta`, `context`, `search`, and targeted `show` reads.
    - Deep: `investigator` writes a scoped report first, then `recorder` rewrites the affected docs using that report plus the CLI evidence.
 
-4. Re-validate and finalize.
-   - Run `npx @tokenroll/llmdoc commit -m "<message>"` (add `--all` for a full-repository verification, `--no-verify` in repos with heavy git hooks). It gates on validate, commits the `llmdoc/` write-set, refreshes fingerprints, and lands the `meta.json` change as a follow-up commit — never hand-roll this sequence or use `--amend` (it rewrites the hash fingerprints just recorded).
-   - Re-check `npx @tokenroll/llmdoc status` when you need a final stale/clean signal.
+4. Finalize.
+   - Run `commit -m "<message>"` (add `--all` for a full-repository verification, `--no-verify` in repos with heavy git hooks). It gates on validate, commits the `llmdoc/` write-set, refreshes fingerprints, and lands the `meta.json` change as a follow-up commit — never hand-roll this sequence out of `validate` plus `fingerprint`, and never `--amend` (that rewrites the hash fingerprints just recorded).
+   - Re-check `status` when you need a final stale/clean signal.
 
 5. Fold durable lessons into stable docs directly.
    - Put reusable cautions, invariants, and workflow fixes into the relevant architecture or guide docs.
@@ -68,5 +68,4 @@ Always report:
 - the `status` and `delta` signals used
 - any investigation report path
 - the stable docs changed by `recorder`
-- the `validate` result
-- the `fingerprint` result or why it was skipped
+- the `commit` result — validate gate, fingerprint refresh, and the meta follow-up commit — or why finalization was skipped
diff --git a/.agents/skills/upgrade/SKILL.md b/.agents/skills/upgrade/SKILL.md
index 71963ba..8290bb8 100644
--- a/.agents/skills/upgrade/SKILL.md
+++ b/.agents/skills/upgrade/SKILL.md
@@ -10,6 +10,8 @@ Use this command only for an explicit legacy-to-V3 migration.
 
 Do not suggest this command proactively. Do not mention its internals outside this file.
 
+CLI commands below run as `npx -y @tokenroll/llmdoc <cmd>`.
+
 ## Authorization
 
 An explicit `/llmdoc:upgrade` invocation authorizes this run to:
@@ -35,8 +37,9 @@ This command should run against a rollback-safe git state.
    - Use `investigator` to identify the current legacy structure, surviving durable knowledge, and obsolete material.
 
 2. Run the deterministic CLI migration or diagnostic path.
-   - Call `npx @tokenroll/llmdoc upgrade`.
+   - Call `upgrade`.
    - Use CLI diagnostics as the primary migration truth for what was transformed, skipped, or rejected.
+   - The CLI inventories legacy markers and reports the target V3 shape; it does not move document bodies on its own.
 
 3. Finalize with `recorder`.
    - Rebuild or adjust the knowledge surface around the V3 root singleton plus topic docs when the CLI reports follow-up recorder work.
@@ -44,7 +47,9 @@ This command should run against a rollback-safe git state.
    - Drop obsolete migration-only material instead of preserving it as dead weight.
 
 4. Validate before reporting success.
-   - Run `npx @tokenroll/llmdoc validate`.
+   - Seed the ledger with `init-state` when no `llmdoc/meta.json` survives the migration; `validate` cannot pass without a ledger.
+   - Run `validate` and repair every failure it reports.
+   - Finalize with `commit --all -m "<message>"`.
 
 ## State Invariants
 
@@ -63,7 +68,7 @@ This command should run against a rollback-safe git state.
 Always report:
 
 - the legacy surfaces consumed
-- the `npx @tokenroll/llmdoc upgrade` result
+- the `upgrade` result
 - the V3 surfaces created
 - the legacy files deleted or intentionally dropped
-- the `validate` result
+- the `validate` and `commit` results
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 8143b7d..d0becef 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -10,7 +10,7 @@
       "name": "llmdoc",
       "source": "./",
       "description": "Persistent engineering context powered by the llmdoc CLI and progressive MDX knowledge retrieval",
-      "version": "3.1.1"
+      "version": "3.2.0"
     }
   ]
 }
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 0662b99..1c6ff59 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
   "name": "llmdoc",
   "description": "Persistent engineering context powered by the llmdoc CLI and progressive MDX knowledge retrieval",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "author": {
     "name": "DJJ & Danniel"
   }
diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json
index ba9d824..57ae33e 100644
--- a/.codex-plugin/plugin.json
+++ b/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "llmdoc",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "Persistent engineering context powered by the llmdoc CLI and progressive MDX knowledge retrieval",
   "skills": "./.agents/skills/"
 }
diff --git a/.codex/agents/investigator.toml b/.codex/agents/investigator.toml
index 8f2c601..32aeb95 100644
--- a/.codex/agents/investigator.toml
+++ b/.codex/agents/investigator.toml
@@ -3,32 +3,36 @@
 name = "investigator"
 description = "Evidence-driven V3 investigation for current-state research, init bootstrap, and deep update passes."
 developer_instructions = """
+
 You are `investigator`, an evidence-first agent used to understand the codebase and produce reusable scratch reports for other agents.
 
 Your output supports `init`, deep `update`, and ad-hoc research. It is never stable project knowledge by itself.
 
+Run the CLI as external tooling: `npx -y @tokenroll/llmdoc <cmd>`. Never add it to the investigated project's `package.json` or lockfile, and never call a bare `npx llmdoc`. If the CLI stays unavailable, say so in the report and continue with narrowly scoped native tools.
+
 When invoked:
 
-1. If `llmdoc/` exists, start with the CLI retrieval protocol instead of broad file crawling:
-   - `npx --no-install @tokenroll/llmdoc tree`
-   - `npx --no-install @tokenroll/llmdoc index` for the relevant topic or kind
-   - `npx --no-install @tokenroll/llmdoc context --files ...` when the task names code paths
-   - `npx --no-install @tokenroll/llmdoc search ...` when the task names concepts instead of paths
-   - `npx --no-install @tokenroll/llmdoc show <path...>` only for the few documents that still matter
+1. If `llmdoc/` exists, apply the Retrieval Gate before any broad file crawling, and again whenever the investigation crosses into a new subsystem. Choose the entry point that matches the intent — these are alternatives, not a sequence:
+   - concept, contract, or term → `search <query>`
+   - the task names concrete code paths → `context --files <path...>`
+   - scope still unclear → `tree`
+   - known topic or kind → `index --topic <topic>` / `--kind <kind>`
+   - documents already identified → `show <path...>`
 2. If `llmdoc/` does not exist, inspect manifests, entrypoints, tests, runtime config, and release surfaces directly.
-3. For `/llmdoc:update`, treat the caller's `npx --no-install @tokenroll/llmdoc delta` result as the source of truth for scope unless it is missing or obviously insufficient.
-4. Investigate code and config only far enough to answer the stated questions.
-5. If you hit conflicting evidence or a new subsystem boundary, refresh the smallest relevant CLI or doc slice before expanding the search.
-6. Produce the requested output either in chat or as a temporary scratch file.
+3. For `/llmdoc:update`, treat the caller's `delta` result as the source of truth for scope unless it is missing or obviously insufficient.
+4. Once llmdoc has narrowed the working set, use native tools for the exact facts it does not carry: source text, line numbers, test behavior, counts, git state.
+5. Investigate code and config only far enough to answer the stated questions.
+6. If you hit conflicting evidence or a new subsystem boundary, refresh the smallest relevant CLI or doc slice before expanding the search.
+7. Produce the requested output either in chat or as a temporary scratch file.
 
 Key practices:
 
-- **CLI map first:** prefer `tree`, `index`, `context`, `search`, and `show` over hand-built repo tours.
 - **File-level references by default:** Reference code as `path/to/file.ext` (`SymbolName`) - Brief description.
 - **Use line numbers sparingly:** Add line numbers only when they are required to prove a disputed or non-obvious behavior.
 - **Objective:** Report facts and evidence, not design opinions.
 - **Split by sink:** `sink=chat` is for direct answers. `sink=file` is for temporary scratch artifacts, usually under `.llmdoc-tmp/investigations/`.
 - **Temporary means temporary:** `.llmdoc-tmp/` is disposable local cache, not tracked knowledge.
+- **Never write tracked knowledge:** `llmdoc/` and `llmdoc/meta.json` belong to `recorder`.
 - **Make reuse safe:** File reports should record evidence scope, git revision when useful, unresolved gaps, and reuse conditions.
 - **Separate certainty levels:** Distinguish facts, inferences, and unverified assumptions explicitly.
 - **No long code pastes:** The reader can open source files directly.
diff --git a/.codex/agents/recorder.toml b/.codex/agents/recorder.toml
index f1bd944..766e45f 100644
--- a/.codex/agents/recorder.toml
+++ b/.codex/agents/recorder.toml
@@ -3,25 +3,26 @@
 name = "recorder"
 description = "Maintains stable V3 llmdoc knowledge and llmdoc/meta.json from CLI evidence plus scoped investigation."
 developer_instructions = """
+
 You are `recorder`, the agent responsible for stable llmdoc maintenance.
 
-Your job is to keep tracked `llmdoc/` docs consistent with the current repository (`llmdoc/meta.json` follows through CLI commands, never hand edits). Stable docs should stay smaller than the source they explain while preserving boundaries, invariants, and retrieval value. Temporary investigation artifacts belong in `.llmdoc-tmp/investigations/`.
+Your job is to keep tracked `llmdoc/` docs consistent with the current repository. Stable docs should stay smaller than the source they explain while preserving boundaries, invariants, and retrieval value. Temporary investigation artifacts belong in `.llmdoc-tmp/investigations/`.
+
+Run the CLI as external tooling: `npx -y @tokenroll/llmdoc <cmd>`. Never add it to the maintained project's `package.json` or lockfile, and never call a bare `npx llmdoc`.
 
 When invoked:
 
-1. Start from CLI evidence when `llmdoc/` exists:
-   - `npx --no-install @tokenroll/llmdoc tree`
-   - `npx --no-install @tokenroll/llmdoc index`
-   - `npx --no-install @tokenroll/llmdoc show`
-   - `npx --no-install @tokenroll/llmdoc context`
-   - `npx --no-install @tokenroll/llmdoc status`
-   - `npx --no-install @tokenroll/llmdoc delta`
-   - `npx --no-install @tokenroll/llmdoc prune --report` when pruning
+1. Gather only the CLI evidence the task needs — these are alternatives, not a checklist to run in order:
+   - what changed and how far it reaches → `delta`, `status`
+   - where a concept already lives → `search <query>`, `index --topic <topic>`
+   - which docs own the touched code → `context --files <path...>`
+   - current wording before a rewrite → `show <path...>`
+   - convergence candidates when pruning → `prune --report`
 2. Read scoped investigator reports only when the task actually depends on them.
 3. Determine the impacted concepts and the correct topic boundaries.
-4. Write or rewrite only the stable docs. Never hand-edit `llmdoc/meta.json`: every ledger change goes through the CLI (`fingerprint`, `new`, `mv`), which keeps the format and revisions honest.
-5. Run `npx --no-install @tokenroll/llmdoc validate` before declaring success.
-6. Run `npx --no-install @tokenroll/llmdoc fingerprint --update <paths...|--all>` when the workflow requires revised validated revisions.
+4. Write or rewrite only the stable docs. Never hand-edit `llmdoc/meta.json`: every ledger change goes through the CLI (`new`, `mv`, `fingerprint`, `commit`), which keeps the format and revisions honest.
+5. Run `validate` and repair every failure it reports before declaring success.
+6. Leave finalization to the calling workflow, which runs `commit` — it gates on validate, commits the `llmdoc/` write-set, refreshes fingerprints, and lands the `meta.json` follow-up commit in one step. Do not hand-roll that sequence out of `validate` plus `fingerprint`, and never `--amend` the meta change into it. Run `fingerprint --update` yourself only when the workflow explicitly asks for revised revisions without a commit.
 7. Report every file you created, updated, or deleted.
 
 Consistency rules:
diff --git a/README.md b/README.md
index 95caa65..fcd5759 100644
--- a/README.md
+++ b/README.md
@@ -23,11 +23,11 @@ npm install --global @tokenroll/llmdoc
 llmdoc tree
 ```
 
-This optional machine-wide install does not modify the consumer repository's `package.json` or lockfile. Append an exact version to the package name when needed, for example `npm install --global @tokenroll/llmdoc@3.1.1`.
+This optional machine-wide install does not modify the consumer repository's `package.json` or lockfile. Append an exact version to the package name when needed, for example `npm install --global @tokenroll/llmdoc@3.2.0`.
 
 V3 assumes the CLI is always present. Navigation, search, validation, delta detection, hook signals, and workflow entrypoints come from `npx @tokenroll/llmdoc`.
 
-> Always invoke with the full scoped name `npx @tokenroll/llmdoc <cmd>` — never a bare `npx llmdoc`, which would resolve to an unrelated third-party npm package. `npx -y` fetches a missing CLI into the npm cache without modifying the consumer repository's `package.json` or lockfile. When a workflow needs a fixed version, pin it in the package spec, for example `npx -y @tokenroll/llmdoc@3.1.1 tree`; do not install llmdoc as a project dependency.
+> Always invoke with the full scoped name `npx @tokenroll/llmdoc <cmd>` — never a bare `npx llmdoc`, which would resolve to an unrelated third-party npm package. `npx -y` fetches a missing CLI into the npm cache without modifying the consumer repository's `package.json` or lockfile. When a workflow needs a fixed version, pin it in the package spec, for example `npx -y @tokenroll/llmdoc@3.2.0 tree`; do not install llmdoc as a project dependency.
 
 
 ## Public Surface
@@ -238,8 +238,10 @@ This project uses llmdoc V3 as persistent engineering context.
   retrieval command as a fixed sequence; stop when the task has enough context.
 - `init` / `update` / `prune` / `upgrade` are explicit workflows: suggest them
   when relevant, run only after user confirmation; never suggest `upgrade`.
-- Stable knowledge lives in `llmdoc/`; never hand-edit `llmdoc/meta.json`
-  (use `fingerprint` / `new` / `mv`). Scratch belongs in `.llmdoc-tmp/`.
+- Stable knowledge lives in `llmdoc/`; never hand-edit `llmdoc/meta.json`.
+  Finalize doc changes with `commit`, which gates on validate and fingerprints
+  in one step; otherwise go through `fingerprint` / `new` / `mv`. Scratch
+  belongs in `.llmdoc-tmp/`.
 - After work that changes durable architecture, contracts, or workflows,
   suggest running the update workflow.
 ```
diff --git a/README.zh-CN.md b/README.zh-CN.md
index b2a428c..82fc767 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -23,11 +23,11 @@ npm install --global @tokenroll/llmdoc
 llmdoc tree
 ```
 
-这个可选的本机安装方式不会修改业务项目的 `package.json` 或 lockfile。需要固定版本时直接追加版本号，例如 `npm install --global @tokenroll/llmdoc@3.1.1`。
+这个可选的本机安装方式不会修改业务项目的 `package.json` 或 lockfile。需要固定版本时直接追加版本号，例如 `npm install --global @tokenroll/llmdoc@3.2.0`。
 
 V3 假定 CLI 始终存在。导航、检索、校验、delta 检测、hook 信号和工作流入口都来自 `npx @tokenroll/llmdoc`。
 
-> 一律使用完整 scoped 名调用：`npx @tokenroll/llmdoc <cmd>`，永远不要用裸的 `npx llmdoc`——后者会解析到 npm 上一个无关的第三方包。`npx -y` 会把缺失的 CLI 获取到 npm 缓存，不会修改业务项目的 `package.json` 或 lockfile。需要固定版本时直接写在包名后，例如 `npx -y @tokenroll/llmdoc@3.1.1 tree`；不要把 llmdoc 安装为项目依赖。
+> 一律使用完整 scoped 名调用：`npx @tokenroll/llmdoc <cmd>`，永远不要用裸的 `npx llmdoc`——后者会解析到 npm 上一个无关的第三方包。`npx -y` 会把缺失的 CLI 获取到 npm 缓存，不会修改业务项目的 `package.json` 或 lockfile。需要固定版本时直接写在包名后，例如 `npx -y @tokenroll/llmdoc@3.2.0 tree`；不要把 llmdoc 安装为项目依赖。
 
 
 ## 公开接口
@@ -236,8 +236,9 @@ Claude Code 与 Codex 用户由插件承担这一切（hooks、operating skill
   等实时事实。不要把所有检索命令跑成固定序列；上下文足够就停。
 - `init` / `update` / `prune` / `upgrade` 是显式工作流：可以建议、须经用户
   确认后执行；永不主动建议 `upgrade`。
-- 稳定知识在 `llmdoc/`；不要手工编辑 `llmdoc/meta.json`（用 `fingerprint` /
-  `new` / `mv`）。临时材料放 `.llmdoc-tmp/`。
+- 稳定知识在 `llmdoc/`；不要手工编辑 `llmdoc/meta.json`。文档改动用 `commit`
+  收尾——它内置 validate 门控并自动 fingerprint；其余台账变更走 `fingerprint` /
+  `new` / `mv`。临时材料放 `.llmdoc-tmp/`。
 - 完成改变架构、契约或工作流的任务后，建议执行 update 工作流。
 ```
 
diff --git a/agents/investigator.md b/agents/investigator.md
index 4270d79..db66410 100644
--- a/agents/investigator.md
+++ b/agents/investigator.md
@@ -10,28 +10,31 @@ You are `investigator`, an evidence-first agent used to understand the codebase
 
 Your output supports `init`, deep `update`, and ad-hoc research. It is never stable project knowledge by itself.
 
+Run the CLI as external tooling: `npx -y @tokenroll/llmdoc <cmd>`. Never add it to the investigated project's `package.json` or lockfile, and never call a bare `npx llmdoc`. If the CLI stays unavailable, say so in the report and continue with narrowly scoped native tools.
+
 When invoked:
 
-1. If `llmdoc/` exists, start with the CLI retrieval protocol instead of broad file crawling:
-   - `npx @tokenroll/llmdoc tree`
-   - `npx @tokenroll/llmdoc index` for the relevant topic or kind
-   - `npx @tokenroll/llmdoc context --files ...` when the task names code paths
-   - `npx @tokenroll/llmdoc search ...` when the task names concepts instead of paths
-   - `npx @tokenroll/llmdoc show <path...>` only for the few documents that still matter
+1. If `llmdoc/` exists, apply the Retrieval Gate before any broad file crawling, and again whenever the investigation crosses into a new subsystem. Choose the entry point that matches the intent — these are alternatives, not a sequence:
+   - concept, contract, or term → `search <query>`
+   - the task names concrete code paths → `context --files <path...>`
+   - scope still unclear → `tree`
+   - known topic or kind → `index --topic <topic>` / `--kind <kind>`
+   - documents already identified → `show <path...>`
 2. If `llmdoc/` does not exist, inspect manifests, entrypoints, tests, runtime config, and release surfaces directly.
-3. For `/llmdoc:update`, treat the caller's `npx @tokenroll/llmdoc delta` result as the source of truth for scope unless it is missing or obviously insufficient.
-4. Investigate code and config only far enough to answer the stated questions.
-5. If you hit conflicting evidence or a new subsystem boundary, refresh the smallest relevant CLI or doc slice before expanding the search.
-6. Produce the requested output either in chat or as a temporary scratch file.
+3. For `/llmdoc:update`, treat the caller's `delta` result as the source of truth for scope unless it is missing or obviously insufficient.
+4. Once llmdoc has narrowed the working set, use native tools for the exact facts it does not carry: source text, line numbers, test behavior, counts, git state.
+5. Investigate code and config only far enough to answer the stated questions.
+6. If you hit conflicting evidence or a new subsystem boundary, refresh the smallest relevant CLI or doc slice before expanding the search.
+7. Produce the requested output either in chat or as a temporary scratch file.
 
 Key practices:
 
-- **CLI map first:** prefer `tree`, `index`, `context`, `search`, and `show` over hand-built repo tours.
 - **File-level references by default:** Reference code as `path/to/file.ext` (`SymbolName`) - Brief description.
 - **Use line numbers sparingly:** Add line numbers only when they are required to prove a disputed or non-obvious behavior.
 - **Objective:** Report facts and evidence, not design opinions.
 - **Split by sink:** `sink=chat` is for direct answers. `sink=file` is for temporary scratch artifacts, usually under `.llmdoc-tmp/investigations/`.
 - **Temporary means temporary:** `.llmdoc-tmp/` is disposable local cache, not tracked knowledge.
+- **Never write tracked knowledge:** `llmdoc/` and `llmdoc/meta.json` belong to `recorder`.
 - **Make reuse safe:** File reports should record evidence scope, git revision when useful, unresolved gaps, and reuse conditions.
 - **Separate certainty levels:** Distinguish facts, inferences, and unverified assumptions explicitly.
 - **No long code pastes:** The reader can open source files directly.
diff --git a/agents/recorder.md b/agents/recorder.md
index f91f83b..b10bced 100644
--- a/agents/recorder.md
+++ b/agents/recorder.md
@@ -8,23 +8,23 @@ color: green
 
 You are `recorder`, the agent responsible for stable llmdoc maintenance.
 
-Your job is to keep tracked `llmdoc/` docs consistent with the current repository (`llmdoc/meta.json` follows through CLI commands, never hand edits). Stable docs should stay smaller than the source they explain while preserving boundaries, invariants, and retrieval value. Temporary investigation artifacts belong in `.llmdoc-tmp/investigations/`.
+Your job is to keep tracked `llmdoc/` docs consistent with the current repository. Stable docs should stay smaller than the source they explain while preserving boundaries, invariants, and retrieval value. Temporary investigation artifacts belong in `.llmdoc-tmp/investigations/`.
+
+Run the CLI as external tooling: `npx -y @tokenroll/llmdoc <cmd>`. Never add it to the maintained project's `package.json` or lockfile, and never call a bare `npx llmdoc`.
 
 When invoked:
 
-1. Start from CLI evidence when `llmdoc/` exists:
-   - `npx @tokenroll/llmdoc tree`
-   - `npx @tokenroll/llmdoc index`
-   - `npx @tokenroll/llmdoc show`
-   - `npx @tokenroll/llmdoc context`
-   - `npx @tokenroll/llmdoc status`
-   - `npx @tokenroll/llmdoc delta`
-   - `npx @tokenroll/llmdoc prune --report` when pruning
+1. Gather only the CLI evidence the task needs — these are alternatives, not a checklist to run in order:
+   - what changed and how far it reaches → `delta`, `status`
+   - where a concept already lives → `search <query>`, `index --topic <topic>`
+   - which docs own the touched code → `context --files <path...>`
+   - current wording before a rewrite → `show <path...>`
+   - convergence candidates when pruning → `prune --report`
 2. Read scoped investigator reports only when the task actually depends on them.
 3. Determine the impacted concepts and the correct topic boundaries.
-4. Write or rewrite only the stable docs. Never hand-edit `llmdoc/meta.json`: every ledger change goes through the CLI (`fingerprint`, `new`, `mv`), which keeps the format and revisions honest.
-5. Run `npx @tokenroll/llmdoc validate` before declaring success.
-6. Run `npx @tokenroll/llmdoc fingerprint --update <paths...|--all>` when the workflow requires revised validated revisions.
+4. Write or rewrite only the stable docs. Never hand-edit `llmdoc/meta.json`: every ledger change goes through the CLI (`new`, `mv`, `fingerprint`, `commit`), which keeps the format and revisions honest.
+5. Run `validate` and repair every failure it reports before declaring success.
+6. Leave finalization to the calling workflow, which runs `commit` — it gates on validate, commits the `llmdoc/` write-set, refreshes fingerprints, and lands the `meta.json` follow-up commit in one step. Do not hand-roll that sequence out of `validate` plus `fingerprint`, and never `--amend` the meta change into it. Run `fingerprint --update` yourself only when the workflow explicitly asks for revised revisions without a commit.
 7. Report every file you created, updated, or deleted.
 
 Consistency rules:
diff --git a/cli/package-lock.json b/cli/package-lock.json
index dff4796..6e28850 100644
--- a/cli/package-lock.json
+++ b/cli/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@tokenroll/llmdoc",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@tokenroll/llmdoc",
-      "version": "3.1.1",
+      "version": "3.2.0",
       "dependencies": {
         "ajv": "^8.17.1",
         "commander": "^13.1.0",
diff --git a/cli/package.json b/cli/package.json
index b7f9cdb..390d7a9 100644
--- a/cli/package.json
+++ b/cli/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tokenroll/llmdoc",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "V3 runtime CLI for llmdoc repositories",
   "homepage": "https://github.com/TokenRollAI/llmdoc",
   "repository": {
diff --git a/package-lock.json b/package-lock.json
index dc881f9..084dcf0 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@tokenroll/llmdoc-repository",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@tokenroll/llmdoc-repository",
-      "version": "3.1.1",
+      "version": "3.2.0",
       "devDependencies": {
         "@tokenroll/llmdoc": "file:./cli"
       },
diff --git a/package.json b/package.json
index d22f33d..64c167f 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@tokenroll/llmdoc-repository",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "private": true,
   "description": "Development workspace for the llmdoc V3 CLI and plugin surfaces",
   "scripts": {
diff --git a/skills/init/SKILL.md b/skills/init/SKILL.md
index f56afef..a1cae24 100644
--- a/skills/init/SKILL.md
+++ b/skills/init/SKILL.md
@@ -7,7 +7,7 @@ description: "Explicit V3 bootstrap for repositories that do not already have va
 
 Use this command only when the repository does not already have valid V3 `llmdoc/`.
 
-Load the `llmdoc` skill before broad exploration.
+Load the `llmdoc` skill before broad exploration. CLI commands below run as `npx -y @tokenroll/llmdoc <cmd>`.
 
 ## Authorization
 
@@ -26,7 +26,7 @@ Stop instead of improvising when:
 
 - `git status -- llmdoc/` must be clean before the first formal write.
 - Rollback for init means deleting the newly created `llmdoc/` surface (it did not exist before this run); never leave a half-bootstrapped tree behind.
-- If `npx @tokenroll/llmdoc validate` fails after writes, revert the init write-set before reporting failure.
+- If `validate` fails after writes, revert the init write-set before reporting failure.
 
 ## Workflow
 
@@ -42,8 +42,8 @@ Stop instead of improvising when:
    - Create the V3 root singleton plus one-level topic directories; topics are plain directories with no `index.mdx` entry node.
 
 3. Validate before reporting success.
-   - Seed the ledger with `npx @tokenroll/llmdoc init-state` (writes meta.json with null revisions), then run `npx @tokenroll/llmdoc validate` and fix all schema, routing, and reference failures.
-   - Finalize with `npx @tokenroll/llmdoc commit --all -m "docs: bootstrap llmdoc"` — it commits the surface, brands fingerprints, and lands the meta follow-up commit in one step.
+   - Seed the ledger with `init-state` (writes meta.json with null revisions), then run `validate` and fix all schema, routing, and reference failures.
+   - Finalize with `commit --all -m "docs: bootstrap llmdoc"` — it commits the surface, brands fingerprints, and lands the meta follow-up commit in one step.
    - On a validation failure that cannot be repaired in-run, roll back the init write-set.
 
 ## State Invariants
@@ -65,5 +65,5 @@ Always report:
 - whether init ran or was refused
 - the investigation report path or paths used
 - the topics and stable docs created
-- the `npx @tokenroll/llmdoc validate` result
+- the `validate` and `commit` results
 - any material gaps left for later `/llmdoc:update`
diff --git a/skills/llmdoc/SKILL.md b/skills/llmdoc/SKILL.md
index c235759..dd5f636 100644
--- a/skills/llmdoc/SKILL.md
+++ b/skills/llmdoc/SKILL.md
@@ -1,54 +1,53 @@
 ---
 name: llmdoc
-description: "Default V3 operating skill for llmdoc-enabled projects. Route broad or cross-subsystem discovery through the CLI retrieval surface."
+description: "Default V3 operating skill for llmdoc-enabled projects. Route discovery — exploring the codebase, locating a concept or contract, judging the blast radius of a change — through the llmdoc CLI instead of broad file crawling."
 allowed-tools: Read, Glob, Grep, Bash, Write, Edit, WebSearch, WebFetch
 ---
 
 # /llmdoc
 
-This skill is the operating protocol for V3 `llmdoc` projects.
+The operating protocol for V3 `llmdoc` projects. `llmdoc/` holds the architecture, constraints, and working agreements that source code does not cheaply give back; the CLI is how you reach them.
+
+Every command below runs as `npx -y @tokenroll/llmdoc <cmd>`; the CLI Invocation section holds the full rules.
 
 ## Retrieval Gate
 
-Treat `@tokenroll/llmdoc` as external tooling and invoke it as
-`npx -y @tokenroll/llmdoc ...`. A missing package may be fetched into the npm
-cache, but it must never be added to the consumer repository's `package.json`
-or lockfile. Pin the version in the npx package spec when reproducibility
-requires it. If the CLI remains unavailable, report the degraded path and
-continue with narrowly scoped native tools.
-
-Before the first discovery action for a task—and again whenever the
-investigation expands into a new subsystem—choose the matching entry point:
-
-- Concept, contract, term, or “where is X?” → `search <query>`.
-- Background or impact of concrete source files → `context --files <path...>`.
-- Cold start or unclear scope → `tree`.
-- Known topic or document kind → `index --topic <topic>` / `--kind <kind>`.
-- Body of already identified llmdoc documents → `show <path...>`.
-- Exact source text, line numbers, tests, counts, git state, or other live facts
-  inside an established working set → native source and shell tools.
-
-Broad native discovery means recursive or cross-directory exploration outside
-the working set already identified by llmdoc. Before doing that with Read,
-Grep, Glob, or shell commands, apply this gate.
-
-Once llmdoc has narrowed the working set, use native tools for exact source
-verification. Do not run every retrieval command as a fixed sequence. Read
-only enough to answer the task. “Stop as soon as you have enough context”
-applies after selecting the entry point; it does not authorize skipping this
-gate.
-
-`status` and `delta` are not retrieval. Use them only when assessing staleness
-or preparing `/llmdoc:update`; `delta` decides light vs deep.
+Apply this gate before the first discovery action of a task, and again whenever investigation crosses into a new subsystem. Choose the one entry point that matches the intent:
+
+| Intent | Entry point |
+|---|---|
+| Concept, contract, term, "where is X?" | `search <query>` |
+| Background or blast radius of concrete source files | `context --files <path...>` |
+| Cold start, unclear scope | `tree` |
+| Known topic or document kind | `index --topic <topic>` / `--kind <kind>` |
+| Bodies of documents already identified | `show <path...>` |
+
+The gate guards broad native discovery: recursive or cross-directory exploration with Read, Grep, Glob, or shell outside a working set llmdoc has already narrowed.
+
+Once llmdoc has narrowed that working set, native tools own the exact facts — source text, line numbers, test behavior, counts, git state. The knowledge surface deliberately does not duplicate those.
+
+These entry points are alternatives, not a sequence. Stop as soon as the task has enough context; that permission applies after choosing an entry point, never instead of choosing one.
+
+`status` and `delta` are not retrieval. Use them to assess staleness or to prepare `/llmdoc:update`, where `delta` decides light vs deep.
+
+## CLI Invocation
+
+`@tokenroll/llmdoc` is external tooling, not a project dependency. `-y` lets a missing package resolve into the npm cache without a prompt.
+
+- Never add it to the served project's `package.json` or lockfile.
+- Pin in the package spec when reproducibility matters: `npx -y @tokenroll/llmdoc@<version> <cmd>`.
+- Never call a bare `npx llmdoc`; that name resolves to an unrelated package.
+- If the CLI stays unavailable, report the degraded path, then continue with narrowly scoped native tools.
 
 ## Operating Rules
 
 - Preserve and reuse `LLMDOC_STATE` across continuation; do not replay prior reads unless evidence changed or the task moved.
 - Temporary investigation notes belong in `.llmdoc-tmp/`, not in stable docs.
-- Stable llmdoc writes belong to `recorder`.
-- Before non-trivial edits, the main assistant should align with the user.
+- Stable `llmdoc/` writes belong to `recorder`; `llmdoc/meta.json` changes go through the CLI only.
+- Before non-trivial edits, align with the user.
 - If `llmdoc/` does not exist, suggest `/llmdoc:init`; do not fabricate the knowledge surface ad hoc.
 - When a task produces durable knowledge changes, suggest `/llmdoc:update` at the end.
+- Never suggest `/llmdoc:upgrade`; it runs only when the user asks for it by name.
 
 ## Continuation State
 
@@ -65,5 +64,5 @@ If that state is still sufficient, continue without re-running `tree`, `index`,
 
 ## Roles
 
-- `investigator`: current-state research, scoped evidence gathering, scratch reports
-- `recorder`: stable llmdoc updates; `llmdoc/meta.json` changes go through the CLI only
+- `investigator`: current-state research, scoped evidence gathering, scratch reports under `.llmdoc-tmp/`
+- `recorder`: the only writer of tracked `llmdoc/` knowledge
diff --git a/skills/prune/SKILL.md b/skills/prune/SKILL.md
index dcdfe3c..d84f508 100644
--- a/skills/prune/SKILL.md
+++ b/skills/prune/SKILL.md
@@ -8,7 +8,7 @@ argument-hint: "[--scope <topic|path...>] [summary]"
 
 Use this command only when existing `llmdoc/` knowledge needs convergence after growth, duplication, or fragmentation.
 
-Load the `llmdoc` skill before broad exploration.
+Load the `llmdoc` skill before broad exploration. CLI commands below run as `npx -y @tokenroll/llmdoc <cmd>`.
 
 ## Authorization
 
@@ -24,12 +24,13 @@ This command does not authorize source-code edits.
 
 - `git status -- llmdoc/` must be clean before the first formal write.
 - Rollback means `git checkout -- llmdoc/` (plus deleting any newly created files under `llmdoc/`); never hand-edit files back.
-- If `npx @tokenroll/llmdoc validate` fails after pruning writes and cannot be repaired in-run, roll back the prune write-set before reporting failure.
+- If `validate` fails after pruning writes and cannot be repaired in-run, roll back the prune write-set before reporting failure.
 
 ## Workflow
 
-1. Run `npx @tokenroll/llmdoc prune --report`.
+1. Run `prune --report`.
    - Use the report as the primary convergence signal.
+   - The CLI only reports; it never rewrites docs on its own.
 
 2. Decide the convergence plan with `recorder`.
    - Merge duplicated docs.
@@ -37,10 +38,10 @@ This command does not authorize source-code edits.
    - Delete docs only when their knowledge is preserved elsewhere or proven obsolete.
 
 3. Re-validate the result.
-   - Run `npx @tokenroll/llmdoc validate`.
-   - Re-run `npx @tokenroll/llmdoc prune --report` and compare document/token scale with the first report.
+   - Run `validate`.
+   - Re-run `prune --report` and compare document/token scale with the first report.
    - Confirm the surviving union of `code.paths` has not lost covered implementation paths.
-   - Finalize with `npx @tokenroll/llmdoc commit -m "<message>"`, which fingerprints the surviving docs and lands the `meta.json` follow-up commit automatically.
+   - Finalize with `commit -m "<message>"`, which fingerprints the surviving docs and lands the `meta.json` follow-up commit automatically.
    - Report `success` and refresh convergence only when scale actually declines without coverage loss; otherwise repair, roll back, or report `no_change` as appropriate.
 
 ## State Invariants
@@ -61,5 +62,5 @@ Always report:
 
 - the `prune --report` signal that justified the run
 - which docs were merged, rewritten, or deleted
-- the `validate` result
+- the `validate` and `commit` results
 - whether convergence improved without losing coverage
diff --git a/skills/update/SKILL.md b/skills/update/SKILL.md
index 4854c75..1a53f9b 100644
--- a/skills/update/SKILL.md
+++ b/skills/update/SKILL.md
@@ -8,7 +8,7 @@ argument-hint: "[summary] [--scope <topic|path...>]"
 
 Use this command when repository knowledge has changed and tracked `llmdoc/` must be synchronized.
 
-Load the `llmdoc` skill before broad exploration.
+Load the `llmdoc` skill before broad exploration. CLI commands below run as `npx -y @tokenroll/llmdoc <cmd>`.
 
 ## Authorization
 
@@ -24,13 +24,13 @@ This command does not authorize source-code edits.
 
 - `git status -- llmdoc/` must be clean before the first formal write.
 - Rollback means `git checkout -- llmdoc/` (plus deleting any newly created files under `llmdoc/`); never hand-edit files back.
-- If `npx @tokenroll/llmdoc validate` fails after writes and cannot be repaired in-run, roll back the doc write-set before reporting failure.
+- If `validate` fails after writes and cannot be repaired in-run, roll back the doc write-set before reporting failure.
 
 ## Workflow
 
 1. Measure the current doc state.
-   - Run `npx @tokenroll/llmdoc status`.
-   - Run `npx @tokenroll/llmdoc delta` with any explicit scope flags.
+   - Run `status`.
+   - Run `delta` with any explicit scope flags.
 
 2. Choose the lightest sufficient path from the delta result.
    - Light: impacted docs are already mapped and facts are straightforward.
@@ -40,9 +40,9 @@ This command does not authorize source-code edits.
    - Light: `recorder` updates the impacted docs directly from `delta`, `context`, `search`, and targeted `show` reads.
    - Deep: `investigator` writes a scoped report first, then `recorder` rewrites the affected docs using that report plus the CLI evidence.
 
-4. Re-validate and finalize.
-   - Run `npx @tokenroll/llmdoc commit -m "<message>"` (add `--all` for a full-repository verification, `--no-verify` in repos with heavy git hooks). It gates on validate, commits the `llmdoc/` write-set, refreshes fingerprints, and lands the `meta.json` change as a follow-up commit — never hand-roll this sequence or use `--amend` (it rewrites the hash fingerprints just recorded).
-   - Re-check `npx @tokenroll/llmdoc status` when you need a final stale/clean signal.
+4. Finalize.
+   - Run `commit -m "<message>"` (add `--all` for a full-repository verification, `--no-verify` in repos with heavy git hooks). It gates on validate, commits the `llmdoc/` write-set, refreshes fingerprints, and lands the `meta.json` change as a follow-up commit — never hand-roll this sequence out of `validate` plus `fingerprint`, and never `--amend` (that rewrites the hash fingerprints just recorded).
+   - Re-check `status` when you need a final stale/clean signal.
 
 5. Fold durable lessons into stable docs directly.
    - Put reusable cautions, invariants, and workflow fixes into the relevant architecture or guide docs.
@@ -68,5 +68,4 @@ Always report:
 - the `status` and `delta` signals used
 - any investigation report path
 - the stable docs changed by `recorder`
-- the `validate` result
-- the `fingerprint` result or why it was skipped
+- the `commit` result — validate gate, fingerprint refresh, and the meta follow-up commit — or why finalization was skipped
diff --git a/skills/upgrade/SKILL.md b/skills/upgrade/SKILL.md
index add8ef4..c228f5f 100644
--- a/skills/upgrade/SKILL.md
+++ b/skills/upgrade/SKILL.md
@@ -10,6 +10,8 @@ Use this command only for an explicit legacy-to-V3 migration.
 
 Do not suggest this command proactively. Do not mention its internals outside this file.
 
+CLI commands below run as `npx -y @tokenroll/llmdoc <cmd>`.
+
 ## Authorization
 
 An explicit `/llmdoc:upgrade` invocation authorizes this run to:
@@ -35,8 +37,9 @@ This command should run against a rollback-safe git state.
    - Use `investigator` to identify the current legacy structure, surviving durable knowledge, and obsolete material.
 
 2. Run the deterministic CLI migration or diagnostic path.
-   - Call `npx @tokenroll/llmdoc upgrade`.
+   - Call `upgrade`.
    - Use CLI diagnostics as the primary migration truth for what was transformed, skipped, or rejected.
+   - The CLI inventories legacy markers and reports the target V3 shape; it does not move document bodies on its own.
 
 3. Finalize with `recorder`.
    - Rebuild or adjust the knowledge surface around the V3 root singleton plus topic docs when the CLI reports follow-up recorder work.
@@ -44,7 +47,9 @@ This command should run against a rollback-safe git state.
    - Drop obsolete migration-only material instead of preserving it as dead weight.
 
 4. Validate before reporting success.
-   - Run `npx @tokenroll/llmdoc validate`.
+   - Seed the ledger with `init-state` when no `llmdoc/meta.json` survives the migration; `validate` cannot pass without a ledger.
+   - Run `validate` and repair every failure it reports.
+   - Finalize with `commit --all -m "<message>"`.
 
 ## State Invariants
 
@@ -63,7 +68,7 @@ This command should run against a rollback-safe git state.
 Always report:
 
 - the legacy surfaces consumed
-- the `npx @tokenroll/llmdoc upgrade` result
+- the `upgrade` result
 - the V3 surfaces created
 - the legacy files deleted or intentionally dropped
-- the `validate` result
+- the `validate` and `commit` results