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

[Disdjj]

Summary

The retrieval-gate work (#38) and the external-tooling decision (#39) landed on the operating skill and hooks, but never reached the four workflow skills, the two agent contracts, or the generated Codex surface. This PR closes that gap and fixes three contradictions it exposed.

1. One invocation contract

Three forms coexisted:

Surface	Before
hooks/hooks.json, skills/llmdoc	npx -y @tokenroll/llmdoc
skills/{init,update,prune,upgrade}, agents/*	bare npx @tokenroll/llmdoc
.agents/skills/*, .codex/agents/*	npx --no-install (15 call sites)

The bare form prompts interactively when the package is missing, which hangs a subagent; --no-install fails outright, the opposite of the "external tooling, fetched into the npm cache, never a project dependency" contract. Everything is now npx -y @tokenroll/llmdoc <cmd>, declared once per surface so individual command references stay short.

2. The Retrieval Gate now reaches both agents

investigator opened with a fixed tree → index → context → search → show sequence and recorder with a seven-command list — both contradicting the gate's "choose one entry point by intent, these are alternatives, not a sequence" rule. Both now apply the gate, and investigator states explicitly where native tools take over for exact facts (source text, line numbers, tests, counts, git state).

3. recorder no longer conflicts with commit

recorder taught validate + fingerprint --update as its finalizer. The workflow skills and llmdoc/workflows/init-and-update.mdx already replaced that with the one-shot commit ("never hand-roll this sequence"). recorder now validates, leaves finalization to the calling workflow, and only fingerprints when the workflow explicitly asks for revisions without a commit.

Smaller fixes

• operating skill: intent routing table moved ahead of the invocation constraints; description sharpened toward discovery-shaped tasks
• prune / upgrade: state that the CLI reports and diagnoses rather than rewriting, matching llmdoc/workflows/prune-and-upgrade.mdx
• upgrade: gained the init-state / commit --all finalizer the other three workflows already had
• README recipes (en + zh): commit named as the finalizer alongside fingerprint / new / mv

Validation

• npm test — 36 passed
• npm run check:prompts — all five skills within budget (llmdoc 1171/1600, was 989)
• node scripts/check-codex-surface.mjs — ok
• npm run validate:dogfood — ok
• skill/agent front matter parses across all 12 canonical and generated files
• both .codex/agents/*.toml parse and contain no --no-install
• canonical and generated skill bodies verified byte-identical

Follow-ups, deliberately not in this PR

• Codex regeneration. .agents/ and .codex/ were synced by hand, replacement style, preserving the ACPlugin front-matter style. The npx-resolved acplugin is 1.1.0, below the 1.6.1 that llmdoc/plugin-packaging/claude-and-codex.mdx requires (older versions regress model: inherit and downgrade hooks), so a regeneration pass should confirm this output rather than being run blind now.
• Dogfood knowledge. delta reports 5 impacted docs and mode: deep for this change. Running /llmdoc:update after merge is the intended path; leaving the decision to the maintainer follows this repo's own convention.

[Disdjj]

Second pass (faa61ca), after re-reviewing the unified skills:

• Real ordering bug in upgrade: the finalize step ran validate before init-state, but validate requires meta.json to exist and mirror the tree — a migration that lost the ledger could never pass. Now: seed ledger → validate → commit --all.
• update report contract still asked for "the fingerprint result or why it was skipped" from before commit absorbed fingerprinting; it now asks for the commit result. init/prune/upgrade report contracts aligned the same way.
• Minor: dropped a markdown anchor link from the operating skill (useless in a prompt), straightened the gate sentence.
• Version bump to 3.2.0 across the full set the release workflow gates on: package.json, cli/package.json, both lockfiles, .claude-plugin/plugin.json, .claude-plugin/marketplace.json (acplugin's version source), .codex-plugin/plugin.json, plus the README pin examples.

Codex surfaces re-synced; all checks re-run green (check:prompts — llmdoc 1161/1600, validate:dogfood ok, codex surface ok, TOMLs parse, bodies byte-identical).