llm-wiki-kit 0.1.6 → 0.1.8

package/README.md

@@ -11,7 +11,7 @@ After the package is published to npm:
 ```bash
 npm install -g llm-wiki-kit
 llm-wiki install --workspace /apps --profile standard
-llm-wiki doctor
+llm-wiki doctor --workspace /apps
 ```
 
 Restart Claude Code and Codex sessions after installation.
@@ -69,49 +69,46 @@ Use Claude Code or Codex normally.
 
 The installed hooks:
 
-- inject `wiki/memory.md`, `wiki/index.md`, and relevant wiki context at session start and prompt submit time
+- inject `wiki/memory.md`, `wiki/index.md`, and relevant wiki context at session start, instructions loaded, prompt submit, and post-compact time
 - record redacted turn summaries
 - capture decision points, debugging findings, changed files, and verification notes
 - allow tool calls to proceed without secret/PII-based hook blocking
 - update `llm-wiki/outputs/questions/YYYY-MM-DD-live-qa.md`
-- promote useful answers into `llm-wiki/wiki/queries/`
+- capture reusable-answer candidates into `llm-wiki/wiki/queries/`
 - promote decision-like turns into `llm-wiki/wiki/decisions/`
+- nudge the active LLM to fold reusable facts into existing wiki pages instead of leaving everything as one-off Q&A
+- automatically refresh managed rules/templates for older projects when the current runtime starts a session
 
 If you need to think about saving every answer manually, the setup has failed.
 
-## User-Facing Commands
+## Operational Commands
 
-```bash
-llm-wiki install --workspace /path/to/project --profile standard
-llm-wiki doctor
-llm-wiki version
-llm-wiki status --workspace /path/to/project
-llm-wiki projects --workspace /path/to/search-root
-llm-wiki update --check --workspace /path/to/project
-llm-wiki update --all --workspace /path/to/search-root
-llm-wiki update --dry-run --workspace /path/to/project
-llm-wiki update --workspace /path/to/project
-llm-wiki context "search phrase" --workspace /path/to/project
-llm-wiki lint --workspace /path/to/project
-llm-wiki consolidate --workspace /path/to/project
-llm-wiki uninstall
-```
+Most users should not need these during daily Claude Code/Codex work. They exist for install, update, diagnostics, and agent-side maintenance.
 
-`llm-wiki status` is an offline consistency check. It reports the installed runtime version, hook targets, and whether the current workspace has the current managed templates applied.
+- Install/update: `llm-wiki install`, `llm-wiki update`, `llm-wiki post-update`, `llm-wiki projects`
+- Diagnostics: `llm-wiki doctor`, `llm-wiki status`, `llm-wiki version`
+- Agent maintenance helpers: `llm-wiki context`, `llm-wiki lint`, `llm-wiki consolidate`
+- Cleanup: `llm-wiki uninstall`
 
-`llm-wiki update --check` is the online update check. It compares the installed package version with the npm registry without changing files.
+`llm-wiki status` is an offline consistency check. It reports the installed runtime version, hook targets, whether the `llm-wiki` command on `PATH` resolves to the current runtime, whether the current workspace has the current managed templates applied, how many rules are auto-updateable, and how many managed-looking rules need agent cleanup.
 
-`llm-wiki update` upgrades the global npm package, reinstalls the hook entries, and patches only managed project files such as the marked `AGENTS.md` policy block and generated `llm-wiki/AGENTS.md`/procedure files. Existing wiki content is not overwritten.
+`llm-wiki update --check [--to <version-or-tag>]` is the online update check. It compares the installed package version with the npm registry target without changing files, and reports an available update only when the target version is newer than the installed version.
 
-`llm-wiki context "<query>"` prints the same layered context used by hooks: the short `memory.md` excerpt, the `index.md` excerpt, and MiniSearch + wikilink-expanded page hits. Use `--limit 1..50` to bound hits and `--no-expand` to disable one-hop link expansion. Context output is redacted before printing; if MiniSearch is unavailable in a source checkout, the command falls back to substring search.
+`llm-wiki update` upgrades the global npm package, reinstalls the hook entries, and reapplies safe managed template updates across known project roots. Use `--current-only` when you intentionally want to update only the supplied workspace. Existing wiki content is not overwritten.
 
-`llm-wiki lint` checks wiki health: missing core files, invalid frontmatter, broken wikilinks, broken relative Markdown links, unsafe `source_ids`, secret-like content, missing source files, duplicate aliases/titles, stale pages, and orphan candidates. Broken links, unsafe source IDs, and secret-like content are errors; metadata and discoverability gaps are warnings.
+`llm-wiki post-update --workspace <project>` reapplies the current runtime's hook entries and safe managed template updates without running `npm install -g`. Use `post-update --all --workspace <search-root>` to reapply templates across discovered project roots.
 
-`llm-wiki consolidate` refreshes only generated marker blocks in `wiki/memory.md` and `wiki/index.md`. Handwritten notes outside those blocks are preserved. Runtime update creates `wiki/memory.md` if missing, but does not overwrite an existing memory page. Default `query`/`context`/`session-log` pages are not promoted into generated maps unless they are explicitly marked `memory_type: semantic` or `procedural` with `importance >= 4`.
+`llm-wiki context "<query>"` prints the same layered context used by hooks. It is mainly for debugging what Codex/Claude Code will see; daily use should rely on hook injection.
 
-`llm-wiki projects --workspace /apps` lists project roots that already have `llm-wiki-kit` state and shows the update commands to run. `llm-wiki update --all --workspace /apps` updates the global runtime once, then reapplies managed templates across every discovered project root under `/apps`.
+`llm-wiki lint` checks wiki health and detects outdated managed rules from older kit versions. Agents may use it before/after meaningful wiki maintenance.
 
-After a plain `npm install -g llm-wiki-kit@latest`, installed hooks point at the same global binary path. The next `SessionStart`/`InstructionsLoaded` hook automatically reapplies safe managed template updates for the active project root. This only patches generated/managed files and does not overwrite wiki content.
+`llm-wiki consolidate` refreshes only generated marker blocks in `wiki/memory.md` and `wiki/index.md`. It is an agent maintenance helper, not a command users should run after every turn.
+
+`llm-wiki projects --workspace /apps` lists project roots that already have `llm-wiki-kit` state or an older `llm-wiki/wiki/index.md`, and shows the update commands to run. `llm-wiki update --workspace /apps` updates the global runtime once, then reapplies managed templates across every known or discovered project root under `/apps`.
+
+After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working when they already point at the global npm package path. The next `SessionStart`/`InstructionsLoaded` hook automatically reapplies safe managed template updates for the active project root. Clearly generated older `llm-wiki/AGENTS.md` and procedure files are refreshed even when old state is missing; user-edited files are not overwritten and are surfaced to the active agent as cleanup work. If hooks point at a source checkout or stale shim, run `llm-wiki post-update --workspace <project>` or `llm-wiki install --workspace <project>` once to reconnect them.
+
+`llm-wiki install` no longer creates a user-local `~/.local/bin/llm-wiki` shim when an npm/nvm global `llm-wiki` command already resolves to the current runtime. If an older kit-managed local shim is shadowing that npm command, install backs it up and removes it.
 
 On PCs that use nvm or user-local npm, prefer the non-sudo global install and make sure the `llm-wiki` command resolves to that npm package:
 
@@ -123,10 +120,10 @@ llm-wiki version
 llm-wiki status
 ```
 
-If `which -a llm-wiki` shows a stale `~/.local/bin/llm-wiki` before the nvm/npm global binary, remove only that file, not the whole `~/.local/bin` directory:
+If `which -a llm-wiki` shows a stale `~/.local/bin/llm-wiki` before the nvm/npm global binary, run install once so the kit can remove a managed shadowing shim or report an unmanaged one:
 
 ```bash
-rm -f "$HOME/.local/bin/llm-wiki"
+llm-wiki install --workspace /path/to/project --profile standard
 hash -r
 llm-wiki version
 ```

package/docs/concepts.md

@@ -16,10 +16,11 @@ The important behavior is a loop:
 
 1. A Claude Code or Codex session starts.
 2. `memory.md`, `index.md`, and relevant wiki context are injected automatically.
-3. The user works normally.
+3. The user works normally; no extra command loop is required.
 4. Hooks gather redacted prompt/tool/result summaries.
-5. At stop/session end, useful knowledge is written back to Markdown.
-6. Future sessions start from the improved wiki instead of relying on long chat history.
+5. At stop/session end, hooks append redacted live Q&A and create query or decision candidates when the turn has enough captured context.
+6. When reusable knowledge appears, the active Claude Code/Codex agent folds it into existing durable wiki pages instead of leaving everything as one-off Q&A.
+7. Future sessions start from the improved wiki instead of relying on long chat history.
 
 The kit is a template/runtime repository. It must not centralize project wiki contents.
 
@@ -27,6 +28,8 @@ Runtime updates and project knowledge are separate:
 
 - npm updates replace the runtime package and hook targets.
 - project patching updates only managed policy blocks and generated procedure files.
+- old generated `llm-wiki/AGENTS.md` and procedure files are refreshed automatically when they are clearly kit-generated, even if old project state is missing.
+- user-edited files are preserved and surfaced to the agent as cleanup work.
 - `memory.md` is created when missing, then treated as project-owned content.
 - curated wiki pages remain project-owned content and are not overwritten by runtime updates.
 
@@ -35,5 +38,5 @@ The maintenance loop is intentionally layered:
 - `memory.md`: short hot index for current durable facts.
 - `index.md`: broad navigation map.
 - MiniSearch + wikilinks: retrieval over the rest of `wiki/**/*.md`, with substring fallback when MiniSearch is not installed in a source checkout.
-- `lint`: finds broken links, stale pages, duplicates, and metadata gaps.
-- `consolidate`: refreshes generated blocks in `memory.md` and `index.md` while preserving handwritten notes and keeping default query/context/session pages out of the durable generated maps.
+- `lint`: finds broken links, stale pages, duplicates, metadata gaps, secret-like content, and outdated managed rules.
+- `consolidate`: agent helper that refreshes generated blocks in `memory.md` and `index.md` while preserving handwritten notes and keeping default query/context/session pages out of the durable generated maps.

package/docs/integrations/claude-code.md

@@ -38,15 +38,19 @@ Claude Code reads `CLAUDE.md`. For project compatibility, the kit creates a `CLA
 
 when no project `CLAUDE.md` exists. Existing `CLAUDE.md` files are not overwritten.
 
-The hook records redacted turn summaries but does not deny tool calls only because an input looks sensitive.
+The hook records redacted turn summaries but does not deny tool calls only because an input looks sensitive. Hook payloads are stored as small redacted event envelopes rather than full transcripts, and context output is redacted field by field before it is returned to Claude Code.
 
-At `SessionStart`/`InstructionsLoaded`, the hook injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, and operating rules. At `UserPromptSubmit`, it searches wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, and injects the smallest useful context set.
+At `SessionStart`/`InstructionsLoaded`, the hook first attempts a safe managed-template refresh, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, and any maintenance note for outdated or customized managed rules. At `UserPromptSubmit`, it searches wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, and injects the smallest useful context set.
+
+`PostToolUse` and `PostToolBatch` record redacted tool summaries in the same turn buffer. `PreCompact` records a compaction note, and `PostCompact` records the note and returns fresh wiki context. `SubagentStop`, `Stop`, and `SessionEnd` append live Q&A and create `wiki/queries/` candidates when a captured question exists. A `wiki/decisions/` page is created only when the captured turn looks decision-like. `Stop` and `SessionEnd` clear the per-session turn buffer after recording; `SubagentStop` does not.
+
+Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
 
 After installation or update, run:
 
 ```bash
 llm-wiki status --workspace /path/to/project
-llm-wiki doctor
+llm-wiki doctor --workspace /path/to/project
 ```
 
 Restart Claude Code so it reloads hook settings.

package/docs/integrations/codex.md

@@ -29,17 +29,23 @@ Handled events:
 
 Expected behavior:
 
-- `SessionStart` injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, and operating rules.
+- `SessionStart` first attempts a safe managed-template refresh, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, and any maintenance note for outdated or customized managed rules.
 - `UserPromptSubmit` searches project wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, and injects the smallest useful context set.
 - `PreToolUse` records redacted tool summaries without blocking tool calls.
 - `PostToolUse` records redacted tool summaries in a turn buffer.
-- `Stop` writes live Q&A and durable wiki pages.
+- `PreCompact` records a compaction note; `PostCompact` records the note and returns fresh wiki context.
+- `SubagentStop` and `Stop` append live Q&A and create `wiki/queries/` candidates when a captured question exists. A `wiki/decisions/` page is created only when the captured turn looks decision-like.
+- `Stop` clears the per-session turn buffer after recording. `SubagentStop` leaves the parent turn buffer available for the final stop event.
+
+Hook payloads are stored as small redacted event envelopes rather than full transcripts. Context output is also redacted field by field before it is returned to Codex.
+
+Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
 
 Run these after install:
 
 ```bash
 llm-wiki status --workspace /path/to/project
-llm-wiki doctor
+llm-wiki doctor --workspace /path/to/project
 ```
 
 If Codex reports untrusted hooks, trust the hook through Codex's own trust flow or run a trusted automation profile that explicitly accepts the hook source. Restart Codex after hook installation or update.

package/docs/operations.md

@@ -41,7 +41,9 @@ Avoid mixing root-owned and user-local installs unless you intentionally choose
 
 The installer:
 
-- creates `~/.local/bin/llm-wiki`
+- uses an npm/nvm global `llm-wiki` command when it already resolves to the current runtime
+- removes an older kit-managed `~/.local/bin/llm-wiki` shim when it shadows that npm/nvm command
+- creates a user-local shim only when no `PATH` command points at the current runtime, such as source checkout development or user-local fallback installs
 - backs up existing Codex/Claude settings before editing
 - merges hook entries without removing existing hooks
 - bootstraps the workspace `llm-wiki/`
@@ -66,16 +68,21 @@ llm-wiki install --workspace /apps --profile standard
 
 Do not delete a project `llm-wiki/` tree to reinstall the runtime. `llm-wiki uninstall` removes hook entries only; project knowledge is intentionally left intact.
 
-## Status And Updates
+## Maintainer And Agent Reference
+
+Daily work should happen through Claude Code/Codex. These commands are for maintainer checks, troubleshooting, and agent-side maintenance.
 
 ```bash
 llm-wiki version
 llm-wiki status --workspace /path/to/project
+llm-wiki doctor --workspace /path/to/project
 llm-wiki projects --workspace /path/to/search-root
-llm-wiki update --check --workspace /path/to/project
-llm-wiki update --all --workspace /path/to/search-root
+llm-wiki update --check --workspace /path/to/project [--to <version-or-tag>]
+llm-wiki update --workspace /path/to/search-root
+llm-wiki update --current-only --workspace /path/to/project
 llm-wiki update --dry-run --workspace /path/to/project
-llm-wiki update --workspace /path/to/project
+llm-wiki post-update --workspace /path/to/project
+llm-wiki post-update --all --workspace /path/to/search-root
 llm-wiki context "search phrase" --workspace /path/to/project
 llm-wiki lint --workspace /path/to/project
 llm-wiki consolidate --workspace /path/to/project
@@ -84,29 +91,35 @@ llm-wiki consolidate --workspace /path/to/project
 `status` is offline and answers whether the local installation is internally consistent:
 
 - runtime version and install source
+- whether the `llm-wiki` command on `PATH` resolves to the current runtime
 - Codex/Claude hook entries pointing at the current runtime
 - project template state from `llm-wiki/.kit-state.json`
 - current managed file hashes
+- auto-updateable managed rules and managed-looking rules that need agent cleanup
 
-`update --check` is online and asks npm whether a newer package version exists.
+`update --check [--to <version-or-tag>]` is online and asks npm for the target version. It reports `update available` only when that registry target is newer than the installed version, so it does not suggest downgrades.
 
-`projects --workspace <search-root>` lists discovered project roots that have `llm-wiki/.kit-state.json`, reports whether their managed templates are current, and prints the update commands for the search root.
+`projects --workspace <search-root>` lists discovered project roots that have `llm-wiki/.kit-state.json` or an older `llm-wiki/wiki/index.md`, reports whether their managed templates are current, and prints the update commands for the search root.
 
 `update` applies changes explicitly only when the user runs it:
 
 - runs `npm install -g llm-wiki-kit@<target>`
 - restarts into the updated binary for `post-update`
 - reinstalls hook entries without duplicating them
-- patches only managed project files
+- patches only managed project files across known or discovered project roots
 - backs up changed files under `~/.local/share/llm-wiki-kit/backups/`
 
-`update --all --workspace <search-root>` performs the npm runtime update once, then reapplies managed templates to every discovered project root under the search root.
+By default, `update --workspace <search-root>` performs the npm runtime update once, then reapplies managed templates to every known or discovered project root under the search root. Use `update --current-only --workspace <project>` to limit template reapplication to one project.
+
+`post-update --workspace <project>` skips npm installation and reapplies the current runtime's hook entries plus safe managed template updates. `post-update --all --workspace <search-root>` does the same template reapplication across discovered project roots.
 
-After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep pointing at the global package path. On the next `SessionStart` or `InstructionsLoaded`, the runtime automatically reapplies safe managed template updates for the active project root.
+After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working when they already point at the global npm package path. On the next `SessionStart` or `InstructionsLoaded`, the runtime automatically reapplies safe managed template updates for the active project root. If hooks point at a source checkout or stale shim, run `llm-wiki post-update --workspace <project>` or `llm-wiki install --workspace <project>` once to reconnect them. `install` will avoid recreating a local shim when an npm/nvm command already points at the current runtime.
 
 ## Context And Wiki Maintenance
 
-`llm-wiki context "<query>"` is the manual form of hook context injection. It reads:
+Daily use should be Claude Code/Codex first. The user should not need to run a chain of `llm-wiki` commands while working. Hooks inject the context automatically, and the active agent is expected to update durable wiki pages when reusable project knowledge appears.
+
+`llm-wiki context "<query>"` is the manual debug form of hook context injection. It reads:
 
 - `llm-wiki/wiki/memory.md` as the short hot index
 - `llm-wiki/wiki/index.md` as the navigation map
@@ -114,7 +127,7 @@ After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep pointing
 - one-hop wikilink neighbors for the strongest matches
 - redacted output fields for query text, memory/index/log excerpts, hit paths, titles, snippets, matched terms, and link expansion metadata
 
-Use it when you want to inspect what the next agent turn should see:
+Use it only when you want to inspect what the next agent turn should see:
 
 ```bash
 llm-wiki context "auth architecture" --workspace /path/to/project
@@ -133,6 +146,7 @@ llm-wiki context "auth architecture" --workspace /path/to/project --limit 8 --no
 - secret-like content patterns such as tokens, password assignments, bearer credentials, and private keys
 - duplicate aliases or titles
 - stale pages and orphan candidates
+- outdated managed rules/templates from earlier `llm-wiki-kit` versions
 
 Broken links, invalid source IDs, and secret-like content are errors and return exit code 1. Metadata and discoverability gaps are warnings.
 
@@ -146,7 +160,9 @@ Broken links, invalid source IDs, and secret-like content are errors and return
 - appends a log entry when files change
 - supports `--dry-run`
 
-Run `consolidate` after meaningful wiki growth, not after every small turn.
+Agents may run `consolidate` after meaningful wiki growth. Users should not need to run it after every turn.
+
+When a new runtime sees an older project, `SessionStart`/`InstructionsLoaded` automatically reapplies safe managed template updates. Files that are clearly generated by older kit versions are refreshed. Files that look user-edited are preserved and surfaced to the active agent as cleanup context instead of being overwritten. Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic template refresh behavior.
 
 ## Updating User-Local Or nvm Installs
 
@@ -167,10 +183,10 @@ npm root -g
 node "$(npm root -g)/llm-wiki-kit/bin/llm-wiki.js" version
 ```
 
-When `which -a llm-wiki` shows `~/.local/bin/llm-wiki` before the nvm global binary, remove only that stale command file:
+When `which -a llm-wiki` shows `~/.local/bin/llm-wiki` before the nvm global binary, run install once. The kit removes an older managed shadowing shim when the npm/nvm command already points at the current runtime, and reports unmanaged local commands through `status`/`doctor`.
 
 ```bash
-rm -f "$HOME/.local/bin/llm-wiki"
+llm-wiki install --workspace /path/to/project --profile standard
 hash -r
 llm-wiki version
 ```
@@ -188,8 +204,10 @@ npm uninstall -g llm-wiki-kit
 Managed project files are conservative:
 
 - root `AGENTS.md` is patched only inside the `llm-wiki-kit` marker block
-- `llm-wiki/AGENTS.md` is replaced only when its recorded hash still matches or the whole file exactly matches the current generated template
-- generated procedures are replaced only when their recorded hash still matches or the whole file exactly matches the current generated template
+- `llm-wiki/AGENTS.md` is replaced only when its recorded hash still matches, the whole file exactly matches the current generated template, or the whole file exactly matches a known legacy generated template
+- generated procedures are replaced only when their recorded hash still matches, the whole file exactly matches the current generated template, or the whole file exactly matches a known legacy generated template
+- missing generated `llm-wiki/AGENTS.md` and procedure files are restored when the project wiki tree exists
+- customized managed-looking files and malformed root policy markers are not overwritten; `status`, `lint`, and injected maintenance context surface them for agent cleanup
 - `llm-wiki/wiki/memory.md` is created if missing but never overwritten by template update once it exists
 - `llm-wiki/wiki/index.md` and existing wiki pages are not overwritten by runtime update; `llm-wiki consolidate` updates only its generated marker block
 
@@ -213,7 +231,7 @@ npm view llm-wiki-kit version
 npm install -g llm-wiki-kit
 llm-wiki install --workspace /apps --profile standard
 llm-wiki status --workspace /apps
-llm-wiki doctor
+llm-wiki doctor --workspace /apps
 llm-wiki update --check --workspace /apps
 ```
 

package/docs/research/baseline.md

@@ -18,3 +18,5 @@ Important conclusions:
 - Obsidian, Graphify, MCP, and RAG can be useful extensions, but v1 must work with plain Markdown and hooks.
 - Retrieval should combine lexical search with explicit Markdown links before adding heavier external infrastructure.
 - Consolidation should be conservative: update generated blocks and navigation surfaces, but preserve human/agent-written page bodies.
+- Separate LLM API integration is not required for the current design. Claude Code and Codex already provide the reasoning/writing layer; the kit should supply context, durable files, guardrails, and safe automatic project-rule updates.
+- Heavy layers such as embeddings, graph databases, MCP tools, and hierarchical summary systems are future considerations only when project wikis become too large for the plain Markdown + hook workflow.

package/docs/research/future-large-scale.md

@@ -0,0 +1,27 @@
+# Future Large-Scale Considerations
+
+These items are not part of the current implementation plan.
+
+The current product direction is plain Markdown plus Codex/Claude Code hooks:
+
+- inject the smallest useful wiki context automatically
+- let the active LLM update durable Markdown during normal work
+- keep generated/template updates safe for older projects
+- preserve raw/wiki separation and redaction rules
+
+Consider heavier infrastructure only when real project wikis become large enough that this model fails in practice.
+
+Deferred options:
+
+- embeddings for semantic retrieval
+- graph database storage
+- MCP tools for direct wiki operations
+- GraphRAG/RAPTOR-style hierarchical summaries
+- external LLM API calls for automatic summarization
+
+Reasons to defer:
+
+- They add setup, cost, data-retention, and failure modes.
+- Codex and Claude Code already provide the LLM reasoning layer.
+- The immediate failure mode is wiki hygiene and old-template drift, not lack of model capacity.
+- Plain Markdown remains inspectable, portable, and easy to repair.

package/docs/troubleshooting.md

@@ -5,12 +5,21 @@
 Run:
 
 ```bash
-llm-wiki doctor
-llm-wiki status
+llm-wiki doctor --workspace /path/to/project
+llm-wiki status --workspace /path/to/project
 ```
 
 Then restart Claude Code or Codex.
 
+`doctor` and `status` report whether hooks point at the current runtime, whether the `llm-wiki` command on `PATH` resolves to that runtime, and whether project managed templates are current. If hooks or shims point at a source checkout or stale path, run one of these once:
+
+```bash
+llm-wiki post-update --workspace /path/to/project
+llm-wiki install --workspace /path/to/project --profile standard
+```
+
+Use `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
+
 ## Is An Update Available?
 
 Use the offline check first:
@@ -85,30 +94,30 @@ npm root -g
 node "$(npm root -g)/llm-wiki-kit/bin/llm-wiki.js" version
 ```
 
-If the direct `node "$(npm root -g)/llm-wiki-kit/bin/llm-wiki.js" version` command prints the latest version but plain `llm-wiki` is old, fix `PATH` or replace the stale shim:
+If the direct `node "$(npm root -g)/llm-wiki-kit/bin/llm-wiki.js" version` command prints the latest version but plain `llm-wiki` is old, reconnect through the installer:
 
 ```bash
-mkdir -p "$HOME/.local/bin"
-ln -sfn "$(npm root -g)/llm-wiki-kit/bin/llm-wiki.js" "$HOME/.local/bin/llm-wiki"
-export PATH="$HOME/.local/bin:$PATH"
+llm-wiki install --workspace /path/to/project --profile standard
 hash -r
-llm-wiki status
+llm-wiki status --workspace /path/to/project
 ```
 
 If `readlink -f "$(command -v llm-wiki)"` points at a repository checkout such as `/mnt/d/dev_proj/llm-wiki-kit/bin/llm-wiki.js`, `npm install -g` is not updating that checkout. Either switch the shim to the npm package as above, or update the checkout itself with `git pull` and run it intentionally as source.
 
-If `which -a llm-wiki` shows both `~/.local/bin/llm-wiki` and an nvm path such as `~/.nvm/versions/node/v20.20.2/bin/llm-wiki`, the `~/.local/bin` entry usually wins because it appears earlier on `PATH`. If the `~/.local/bin/llm-wiki` file is stale, remove only that file and let the nvm npm global command take over:
+Running `llm-wiki post-update --workspace /path/to/project` or `llm-wiki install --workspace /path/to/project --profile standard` also reconnects hook entries to the current runtime. `install` uses an npm/nvm global command when it already resolves to the current runtime, removes an older kit-managed local shim when it shadows that command, and creates a local shim only when no `PATH` command points at the current runtime.
+
+If `which -a llm-wiki` shows both `~/.local/bin/llm-wiki` and an nvm path such as `~/.nvm/versions/node/v20.20.2/bin/llm-wiki`, the `~/.local/bin` entry usually wins because it appears earlier on `PATH`. Let install handle managed shims first:
 
 ```bash
-rm -f "$HOME/.local/bin/llm-wiki"
+llm-wiki install --workspace /path/to/project --profile standard
 hash -r
 which -a llm-wiki
 readlink -f "$(command -v llm-wiki)"
 llm-wiki version
-llm-wiki status
+llm-wiki status --workspace /path/to/project
 ```
 
-Do not remove the entire `~/.local/bin` directory; it may contain unrelated commands. If the nvm command is missing after removing the stale file, reinstall the package in the active nvm Node version:
+Do not remove the entire `~/.local/bin` directory; it may contain unrelated commands. If `status` or `doctor` reports an unmanaged local command that still shadows npm, inspect that one file before removing it. If the nvm command is missing, reinstall the package in the active nvm Node version:
 
 ```bash
 npm uninstall -g llm-wiki-kit
@@ -170,6 +179,8 @@ Check:
 
 The hook does not block tool calls only because inputs look sensitive. Durable summaries redact authentication values before writing, while ordinary work context such as dates, phone numbers, emails, and business identifiers is preserved by default.
 
+Hook payloads are stored as small redacted event envelopes rather than full transcripts. Manual and hook context output is redacted before wiki excerpts or search hits are returned.
+
 ## Duplicate Pages Appear
 
 Run a manual review:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-wiki-kit",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Hook-first living LLM Wiki runtime for Codex and Claude Code.",
   "type": "module",
   "files": [

package/src/cli.js

@@ -4,7 +4,7 @@ import { handleHook } from './hook.js';
 import { install, status, uninstall } from './install.js';
 import { bootstrapProject } from './project.js';
 import { inspectProjectState } from './project-state.js';
-import { commandForProject, knownProjectRoots } from './projects.js';
+import { commandForProject, knownProjectRoots, recordProject } from './projects.js';
 import { formatDoctor, runDoctor } from './doctor.js';
 import { migrate } from './migrate.js';
 import { postUpdate, update } from './update.js';
@@ -54,6 +54,8 @@ function parseOptions(args) {
       options.replaceHooks = true;
     } else if (arg === '--all') {
       options.all = true;
+    } else if (arg === '--current-only') {
+      options.currentOnly = true;
     } else if (arg === '--json') {
       options.json = true;
     } else {
@@ -82,8 +84,9 @@ export async function runCli(args) {
 
 Usage:
   llm-wiki install --workspace /apps [--profile standard]
-  llm-wiki update --workspace <project> [--check|--dry-run|--to <version-or-tag>]
-  llm-wiki doctor
+  llm-wiki update --workspace <project-or-search-root> [--check|--dry-run|--current-only|--to <version-or-tag>]
+  llm-wiki post-update --workspace <project> [--all]
+  llm-wiki doctor --workspace <project>
   llm-wiki projects --workspace /apps
   llm-wiki status
   llm-wiki version
@@ -104,7 +107,9 @@ Usage:
     printJsonOrText(result, options, (value) => [
       'llm-wiki-kit installed',
       `- workspace: ${value.workspace}`,
-      `- bin: ${value.localBin}`,
+      `- runtime bin: ${value.binPath}`,
+      `- command: ${value.commandPath || 'not found on PATH'}`,
+      `- local shim: ${value.localBin} (${value.localBinAction})`,
       `- changed hooks: ${value.changed.length ? value.changed.join(', ') : 'none (already installed)'}`,
       'Restart Codex/Claude Code sessions so new hooks are loaded.',
     ].join('\n'));
@@ -149,7 +154,7 @@ Usage:
   }
 
   if (command === 'doctor') {
-    const result = await runDoctor();
+    const result = await runDoctor(options);
     printJsonOrText(result, options, formatDoctor);
     if (!result.ok) process.exitCode = 1;
     return;
@@ -157,7 +162,9 @@ Usage:
 
   if (command === 'bootstrap') {
     const projectRoot = resolve(options.workspace || process.cwd());
-    printJsonOrText(await bootstrapProject(projectRoot, options), options);
+    const result = await bootstrapProject(projectRoot, options);
+    await recordProject(projectRoot, 'bootstrap').catch(() => {});
+    printJsonOrText(result, options);
     return;
   }
 
@@ -223,6 +230,8 @@ async function listProjects(options) {
 
 function formatStatus(value) {
   const project = value.project || {};
+  const autoUpdateCount = (project.managedFiles || []).filter((file) => !file.current && file.patchable).length;
+  const attentionCount = (project.managedFiles || []).filter((file) => file.needsAttention).length;
   return [
     'llm-wiki-kit status',
     `- version: ${value.runtimeVersion}`,
@@ -230,11 +239,14 @@ function formatStatus(value) {
     `- bin: ${value.binPath}`,
     `- command: ${value.commandPath || 'not found'}`,
     `- command matches runtime: ${value.commandMatchesRuntime ? 'yes' : 'no'}`,
+    `- local shim: ${value.localBin?.path || 'unknown'} (${value.localBin?.exists ? (value.localBin.managed ? 'managed' : 'unmanaged') : 'absent'}${value.localBin?.matchesRuntime ? ', current' : ''})`,
     `- hooks current: ${value.hooksCurrent ? 'yes' : 'no'}`,
     `- codex hook: ${value.codexInstalled ? 'current' : 'missing/outdated'}`,
     `- claude hook: ${value.claudeInstalled ? 'current' : 'missing/outdated'}`,
     `- project applied runtime: ${project.lastRuntimeVersionApplied || 'unknown'}`,
     `- project templates current: ${project.managedFilesCurrent ? 'yes' : 'no'}`,
+    `- project auto-updateable rules: ${autoUpdateCount}`,
+    `- project rules needing agent cleanup: ${attentionCount}`,
   ].join('\n');
 }
 
@@ -249,13 +261,22 @@ function formatUpdate(value) {
     ].join('\n');
   }
   if (value.mode === 'dry-run') {
+    const projects = Array.isArray(value.projects) ? value.projects : [];
+    const changed = projects.length > 0
+      ? projects.reduce((sum, item) => sum + (item.project?.changed?.length || 0), 0)
+      : (value.project?.changed?.length || 0);
+    const skipped = projects.length > 0
+      ? projects.reduce((sum, item) => sum + (item.project?.skipped?.length || 0), 0)
+      : (value.project?.skipped?.length || 0);
     return [
       'llm-wiki-kit update dry-run',
       `- installed: ${value.installedVersion}`,
       `- latest: ${value.latestVersion}`,
       `- update available: ${value.updateAvailable ? 'yes' : 'no'}`,
-      `- project template changes: ${value.project?.changed?.length || 0}`,
-      `- project template skipped: ${value.project?.skipped?.length || 0}`,
+      `- scope: ${value.scope || 'current'}`,
+      ...(projects.length > 0 ? [`- projects checked: ${projects.length}`] : []),
+      `- project template changes: ${changed}`,
+      `- project template skipped: ${skipped}`,
     ].join('\n');
   }
   return [
@@ -263,6 +284,7 @@ function formatUpdate(value) {
     `- workspace: ${value.workspace}`,
     `- before: ${value.before}`,
     `- target: ${value.target}`,
+    `- scope: ${value.scope || 'current'}`,
     ...(value.projects ? [`- projects updated: ${value.projects.length}`] : []),
   ].join('\n');
 }
@@ -300,7 +322,8 @@ function formatProjects(value) {
       lines.push(`- ${project.workspace}: ${status}`);
     }
   }
-  lines.push('', 'To update every listed project root:', commandForProject('update --all', value.workspace));
+  lines.push('', 'To update every listed project root:', commandForProject('update', value.workspace));
+  lines.push('To update only the current project root:', commandForProject('update --current-only', value.workspace));
   lines.push('To reapply templates without npm install:', commandForProject('post-update --all', value.workspace));
   return lines.join('\n');
 }