feat(prompts): unify the CLI contract across every prompt surface

.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`

.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

.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,23 +26,24 @@ 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.
    - Rewrite fragmented docs when a clearer topic boundary exists.
    - 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

.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

.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,16 +37,19 @@ 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.
    - Fold still-valid historical conclusions into active architecture and guide docs.
    - 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

.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"
     }
   ]
 }

.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"
   }

.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/"
 }

.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.