llm-wiki-kit 0.1.7 → 0.1.9

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,7 +69,7 @@ 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
@@ -85,16 +85,18 @@ If you need to think about saving every answer manually, the setup has failed.
 
 Most users should not need these during daily Claude Code/Codex work. They exist for install, update, diagnostics, and agent-side maintenance.
 
-- Install/update: `llm-wiki install`, `llm-wiki update`, `llm-wiki projects`
+- 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 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.
+`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 --check` is the online update check. It compares the installed package version with the npm registry without changing files.
+`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 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` upgrades the global npm package when npm has a newer target, reinstalls the hook entries, and reapplies safe managed template updates across known project roots. If the installed runtime already satisfies the registry target, it skips `npm install -g` and still runs post-update maintenance. Use `--current-only` when you intentionally want to update only the supplied workspace. Existing wiki content is not overwritten.
+
+`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 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.
 
@@ -102,10 +104,12 @@ Most users should not need these during daily Claude Code/Codex work. They exist
 
 `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 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 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:
 
 ```bash
@@ -116,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

@@ -18,9 +18,9 @@ The important behavior is a loop:
 2. `memory.md`, `index.md`, and relevant wiki context are injected automatically.
 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.
-7. 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.
+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.
 

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/`
@@ -73,11 +75,14 @@ Daily work should happen through Claude Code/Codex. These commands are for maint
 ```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
@@ -86,25 +91,30 @@ 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>`
+- runs `npm install -g llm-wiki-kit@<target>` only when the registry target is newer than the installed runtime
+- skips npm installation when the installed runtime already satisfies the target, then still runs post-update maintenance
 - 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.
 
-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.
+`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 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
 
@@ -153,7 +163,7 @@ Broken links, invalid source IDs, and secret-like content are errors and return
 
 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.
+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
 
@@ -174,10 +184,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
 ```
@@ -195,8 +205,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
 
@@ -220,7 +232,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/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,32 @@ 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
 ```
 
+After a manual `sudo npm install -g llm-wiki-kit@latest`, a normal-user `llm-wiki update --workspace <search-root>` can be used to reapply hooks and managed templates. When the installed runtime already matches the registry target, `update` skips the npm install step and runs only post-update maintenance.
+
 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 +181,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.7",
+  "version": "0.1.9",
   "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;
   }
 
@@ -232,6 +239,7 @@ 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'}`,
@@ -253,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 [
@@ -267,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');
 }
@@ -304,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');
 }

package/src/doctor.js

@@ -9,27 +9,27 @@ function nodeMajor() {
   return Number.parseInt(process.versions.node.split('.')[0], 10);
 }
 
-export async function runDoctor() {
+export async function runDoctor(options = {}) {
   const checks = [];
-  const add = (name, ok, detail = '') => checks.push({ name, ok, detail });
-  const stat = await status();
+  const add = (id, name, ok, detail = '') => checks.push({ id, name, ok, detail });
+  const stat = await status(options);
 
-  add('node >= 20', nodeMajor() >= 20, process.version);
-  add('runtime version detected', Boolean(stat.runtimeVersion), stat.runtimeVersion || 'unknown');
-  add('llm-wiki bin exists', await exists(stat.binPath), stat.binPath);
-  add('runtime installed from npm', stat.installSource === 'npm', `${stat.installSource}; npm install -g does not update source checkouts`);
-  add('llm-wiki command resolves to current runtime', stat.commandMatchesRuntime, stat.commandPath ? `command=${stat.commandPath}; runtime=${stat.binPath}` : 'command not found on PATH');
-  add('Codex hook installed', stat.codexInstalled, stat.codexHooksPath);
-  add('Claude hook installed', stat.claudeInstalled, stat.claudeSettingsPath);
-  add('project templates current', stat.project.managedFilesCurrent, stat.project.statePath);
-  add('codex command available', spawnSync('codex', ['--version'], { encoding: 'utf8' }).status === 0, 'codex --version');
-  add('claude command available', spawnSync('claude', ['--version'], { encoding: 'utf8' }).status === 0, 'claude --version');
-  add('state directory writable', await canWrite(join(kitDataDir(), '.doctor')), kitDataDir());
-  add('docs present', await docsPresent(), 'README.md and docs/');
-  add('sample hook roundtrip', await sampleHookRoundtrip(stat.binPath), 'UserPromptSubmit fixture');
+  add('node', 'node >= 20', nodeMajor() >= 20, process.version);
+  add('runtime-version', 'runtime version detected', Boolean(stat.runtimeVersion), stat.runtimeVersion || 'unknown');
+  add('runtime-bin', 'llm-wiki bin exists', await exists(stat.binPath), stat.binPath);
+  add('install-source', 'runtime installed from npm', stat.installSource === 'npm', `${stat.installSource}; npm install -g does not update source checkouts`);
+  add('command-path', 'llm-wiki command resolves to current runtime', stat.commandMatchesRuntime, stat.commandPath ? `command=${stat.commandPath}; runtime=${stat.binPath}` : 'command not found on PATH');
+  add('codex-hook', 'Codex hook installed', stat.codexInstalled, stat.codexHooksPath);
+  add('claude-hook', 'Claude hook installed', stat.claudeInstalled, stat.claudeSettingsPath);
+  add('project-templates', 'project templates current', stat.project.managedFilesCurrent, stat.project.statePath);
+  add('codex-command', 'codex command available', spawnSync('codex', ['--version'], { encoding: 'utf8' }).status === 0, 'codex --version');
+  add('claude-command', 'claude command available', spawnSync('claude', ['--version'], { encoding: 'utf8' }).status === 0, 'claude --version');
+  add('state-writable', 'state directory writable', await canWrite(join(kitDataDir(), '.doctor')), kitDataDir());
+  add('docs', 'docs present', await docsPresent(), 'README.md and docs/');
+  add('sample-hook', 'sample hook roundtrip', await sampleHookRoundtrip(stat.binPath), 'UserPromptSubmit fixture');
 
   const allOk = checks.every((check) => check.ok);
-  return { ok: allOk, checks };
+  return { ok: allOk, checks, workspace: stat.workspace, status: stat };
 }
 
 async function docsPresent() {
@@ -84,8 +84,38 @@ export function formatDoctor(result) {
     lines.push(`- ${check.ok ? 'PASS' : 'WARN'} ${check.name}${check.detail ? ` (${check.detail})` : ''}`);
   }
   if (!result.ok) {
-    lines.push('');
-    lines.push('Run ./install.sh --workspace /apps --profile standard to install hooks, then restart Codex/Claude Code sessions.');
+    const remediation = doctorRemediation(result);
+    if (remediation.length > 0) {
+      lines.push('', 'Suggested fix:');
+      for (const item of remediation) lines.push(`- ${item}`);
+    }
   }
   return lines.join('\n');
 }
+
+function failed(result, id) {
+  return (result.checks || []).some((check) => check.id === id && !check.ok);
+}
+
+function doctorRemediation(result) {
+  const workspace = result.workspace || process.cwd();
+  const suggestions = [];
+  if (failed(result, 'install-source')) {
+    suggestions.push(`normal install: npm install -g llm-wiki-kit@latest && llm-wiki install --workspace ${workspace} --profile standard`);
+    suggestions.push(`source checkout development: ./install.sh --workspace ${workspace} --profile standard`);
+  }
+  if (failed(result, 'command-path')) {
+    const local = result.status?.localBin;
+    if (result.status?.installSource === 'npm' && local?.exists && local.managed) {
+      suggestions.push(`remove stale managed local shim if it still shadows npm: rm -f ${local.path} && hash -r`);
+    }
+    suggestions.push(`reconnect command and hooks: llm-wiki install --workspace ${workspace} --profile standard`);
+  }
+  if (failed(result, 'codex-hook') || failed(result, 'claude-hook')) {
+    suggestions.push(`install hooks: llm-wiki install --workspace ${workspace} --profile standard, then restart Codex/Claude Code sessions`);
+  }
+  if (failed(result, 'project-templates')) {
+    suggestions.push(`refresh managed project templates: llm-wiki post-update --workspace ${workspace}`);
+  }
+  return [...new Set(suggestions)];
+}

package/src/install.js

@@ -1,9 +1,9 @@
 import { realpathSync } from 'fs';
-import { chmod } from 'fs/promises';
+import { chmod, lstat, readlink, unlink } from 'fs/promises';
 import { spawnSync } from 'child_process';
 import { join, resolve } from 'path';
 import { CLAUDE_EVENTS, CODEX_EVENTS, KIT_NAME } from './constants.js';
-import { backupFile, ensureDir, exists, homeDir, readJson, safeSymlink, writeJson } from './fs-utils.js';
+import { backupFile, exists, homeDir, readJson, safeSymlink, writeJson } from './fs-utils.js';
 import { inspectProjectState } from './project-state.js';
 import { bootstrapProject } from './project.js';
 import { recordProject } from './projects.js';
@@ -34,6 +34,91 @@ function realpathOrOriginal(path) {
   }
 }
 
+function sameResolvedPath(left, right) {
+  const resolvedLeft = realpathOrOriginal(left);
+  const resolvedRight = realpathOrOriginal(right);
+  return Boolean(resolvedLeft && resolvedRight && resolvedLeft === resolvedRight);
+}
+
+function samePath(left, right) {
+  if (!left || !right) return false;
+  return resolve(left) === resolve(right);
+}
+
+function isKitPath(path) {
+  return String(path || '').replace(/\\/g, '/').includes('/llm-wiki-kit/');
+}
+
+async function inspectLocalBin(localBinPath) {
+  try {
+    const stat = await lstat(localBinPath);
+    const symlink = stat.isSymbolicLink();
+    const target = symlink ? await readlink(localBinPath).catch(() => null) : null;
+    const resolved = realpathOrOriginal(localBinPath);
+    return {
+      path: localBinPath,
+      exists: true,
+      symlink,
+      target,
+      resolved,
+      managed: symlink && (isKitPath(target) || isKitPath(resolved)),
+      matchesRuntime: sameResolvedPath(localBinPath, binPath),
+    };
+  } catch {
+    return {
+      path: localBinPath,
+      exists: false,
+      symlink: false,
+      target: null,
+      resolved: null,
+      managed: false,
+      matchesRuntime: false,
+    };
+  }
+}
+
+async function reconcileLocalBin(localBinPath) {
+  const commandPathsBefore = llmWikiCommandPaths();
+  const localBefore = await inspectLocalBin(localBinPath);
+  const alternateRuntimeCommand = commandPathsBefore.some((path) => (
+    !samePath(path, localBinPath) && sameResolvedPath(path, binPath)
+  ));
+  let action = 'kept';
+
+  if (alternateRuntimeCommand) {
+    if (localBefore.exists && localBefore.managed) {
+      await backupFile(localBinPath, 'local-bin-llm-wiki');
+      await unlink(localBinPath).catch(() => {});
+      action = 'removed-shadowing-shim';
+    } else if (localBefore.exists) {
+      action = 'left-unmanaged-local-bin';
+    } else {
+      action = 'skipped-npm-command-available';
+    }
+  } else if (localBefore.matchesRuntime) {
+    action = 'kept-current-shim';
+  } else {
+    if (localBefore.exists) {
+      await backupFile(localBinPath, 'local-bin-llm-wiki');
+      action = 'replaced-local-shim';
+    } else {
+      action = 'created-local-shim';
+    }
+    await safeSymlink(binPath, localBinPath);
+  }
+
+  const commandPathsAfter = llmWikiCommandPaths();
+  const localAfter = await inspectLocalBin(localBinPath);
+  return {
+    ...localAfter,
+    action,
+    alternateRuntimeCommand,
+    commandPathsBefore,
+    commandPathsAfter,
+    commandPath: commandPathsAfter[0] || null,
+  };
+}
+
 function addHook(hooks, eventName, command, options = {}) {
   hooks[eventName] = Array.isArray(hooks[eventName]) ? hooks[eventName] : [];
   const already = JSON.stringify(hooks[eventName]).includes(command);
@@ -72,12 +157,8 @@ export async function install(options = {}) {
   const workspace = resolve(options.workspace || process.cwd());
   await chmod(binPath, 0o755).catch(() => {});
   const localBin = join(homeDir(), '.local', 'bin');
-  await ensureDir(localBin);
   const localBinPath = join(localBin, 'llm-wiki');
-  if (await exists(localBinPath)) {
-    await backupFile(localBinPath, 'local-bin-llm-wiki');
-  }
-  await safeSymlink(binPath, localBinPath);
+  const localBinResult = await reconcileLocalBin(localBinPath);
   if (!options.noProject) {
     await bootstrapProject(workspace, { profile: options.profile || 'standard', recordState: true });
     await recordProject(workspace, 'install');
@@ -133,7 +214,12 @@ export async function install(options = {}) {
     workspace,
     runtimeVersion: runtimeVersion(),
     binPath,
-    localBin: join(localBin, 'llm-wiki'),
+    localBin: localBinPath,
+    localBinAction: localBinResult.action,
+    localBinManaged: localBinResult.managed,
+    localBinMatchesRuntime: localBinResult.matchesRuntime,
+    commandPath: localBinResult.commandPath,
+    commandPaths: localBinResult.commandPathsAfter,
     changed,
   };
 }
@@ -176,7 +262,10 @@ export async function status(options = {}) {
   const commandPath = commandPaths[0] || null;
   const resolvedCommandPath = realpathOrOriginal(commandPath);
   const resolvedBinPath = realpathOrOriginal(binPath);
+  const localBinPath = join(homeDir(), '.local', 'bin', 'llm-wiki');
+  const localBin = await inspectLocalBin(localBinPath);
   return {
+    workspace,
     runtimeVersion: runtimeVersion(),
     packageRoot,
     installSource: detectInstallSource(),
@@ -184,6 +273,7 @@ export async function status(options = {}) {
     commandPath,
     commandPaths,
     commandMatchesRuntime: Boolean(resolvedCommandPath && resolvedBinPath && resolvedCommandPath === resolvedBinPath),
+    localBin,
     codexInstalled,
     claudeInstalled,
     hooksCurrent: codexInstalled && claudeInstalled,

package/src/projects.js

@@ -50,6 +50,11 @@ export async function recordProject(projectRoot, source = 'unknown') {
   return registry.projects[workspace];
 }
 
+async function looksLikeProjectRoot(root) {
+  return (await exists(join(root, 'llm-wiki', '.kit-state.json'))) ||
+    (await exists(join(root, 'llm-wiki', 'wiki', 'index.md')));
+}
+
 export async function discoverProjectRoots(searchRoot, options = {}) {
   const root = resolve(searchRoot || process.cwd());
   const maxDirs = options.maxDirs || 5000;
@@ -60,7 +65,7 @@ export async function discoverProjectRoots(searchRoot, options = {}) {
     if (seen >= maxDirs) return;
     seen += 1;
 
-    if (await exists(join(dir, 'llm-wiki', '.kit-state.json'))) {
+    if (await looksLikeProjectRoot(dir)) {
       roots.add(dir);
     }
 
@@ -73,8 +78,15 @@ export async function discoverProjectRoots(searchRoot, options = {}) {
 
     for (const entry of entries) {
       if (seen >= maxDirs) return;
-      if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
-      await walk(join(dir, entry.name));
+      if (!entry.isDirectory()) continue;
+      const child = join(dir, entry.name);
+      if (SKIP_DIRS.has(entry.name)) {
+        if (entry.name === 'llm-wiki' && await looksLikeProjectRoot(child)) {
+          await walk(child);
+        }
+        continue;
+      }
+      await walk(child);
     }
   }
 
@@ -92,7 +104,7 @@ export async function knownProjectRoots(options = {}) {
 
   const existing = [];
   for (const root of [...roots].sort()) {
-    if (await isDirectory(root) && await exists(join(root, 'llm-wiki', '.kit-state.json'))) {
+    if (await isDirectory(root) && await looksLikeProjectRoot(root)) {
       existing.push(root);
     }
   }

package/src/templates.js

@@ -13,6 +13,8 @@ This repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex
 - \`llm-wiki/raw/\`는 원본 또는 redacted 근거 저장소다. hook envelope append 외에는 원본 capture를 수정하지 않는다.
 - \`llm-wiki/wiki/\`는 agent가 관리하는 지식층이다. 결정, 구조, 디버깅, 개념, 절차, 맥락을 여기에 정리한다.
 - \`llm-wiki/wiki/memory.md\`는 짧은 핵심 기억이다. 긴 설명 대신 현재 상태와 중요한 문서 링크만 유지한다.
+- hook이 주입한 context를 우선 사용한다. 수동 확인이나 정리에는 \`llm-wiki context\`, \`llm-wiki lint\`, \`llm-wiki consolidate\`를 agent 보조 도구로 사용한다.
+- hook은 redacted live Q&A와 query/decision 후보를 기록한다. 재사용 가능한 지식은 agent가 기존 정식 wiki 문서에 합친다.
 - 새 문서를 만들기 전에 기존 wiki 문서를 먼저 찾아 갱신한다. 반복해서 쓸 사실은 \`outputs/questions/\`에만 두지 말고 적절한 wiki 문서에 합친다.
 - 일회성 작업 기록은 \`llm-wiki/outputs/questions/\`에 보존하고, 재사용 가능한 결론은 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 반영한다.
 - 검증 명령, 근거 파일, 불확실한 점을 함께 남긴다. 추론은 추론이라고 표시하고, 모순은 지우지 말고 Open Questions 또는 Contradictions에 남긴다.

package/src/update.js

@@ -4,7 +4,7 @@ import { exists } from './fs-utils.js';
 import { appendWikiLog } from './project.js';
 import { install } from './install.js';
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
-import { knownProjectRoots } from './projects.js';
+import { knownProjectRoots, recordProject } from './projects.js';
 import { binPath, detectInstallSource, packageName, runtimeVersion } from './version.js';
 
 function runCommand(command, args, options = {}) {
@@ -39,6 +39,34 @@ async function hasProjectWiki(projectRoot) {
   return exists(join(projectRoot, 'llm-wiki', 'wiki'));
 }
 
+function shouldUpdateAllProjects(options = {}) {
+  return options.all || !options.currentOnly;
+}
+
+async function projectRootsForUpdate(workspace, options = {}) {
+  if (!shouldUpdateAllProjects(options)) return [workspace];
+  const roots = await knownProjectRoots({ workspace });
+  return roots.length > 0 ? roots : [workspace];
+}
+
+async function applyTemplatesToProject(projectRoot, options = {}) {
+  const projectResult = options.noProject
+    ? null
+    : await applyProjectTemplateUpdate(projectRoot, { dryRun: options.dryRun });
+  if (!options.noProject && !options.dryRun && await hasProjectWiki(projectRoot)) {
+    await recordProject(projectRoot, options.source || 'post-update').catch(() => {});
+  }
+  return projectResult;
+}
+
+function parseJsonOutput(output) {
+  try {
+    return JSON.parse(output);
+  } catch {
+    return null;
+  }
+}
+
 export function parseRegistryVersion(output) {
   return String(output || '').trim().split(/\s+/).at(-1) || '';
 }
@@ -95,9 +123,7 @@ export async function postUpdate(options = {}) {
     const workspaces = await knownProjectRoots({ workspace });
     const projects = [];
     for (const projectRoot of workspaces) {
-      const projectResult = options.noProject
-        ? null
-        : await applyProjectTemplateUpdate(projectRoot);
+      const projectResult = await applyTemplatesToProject(projectRoot, options);
       if (!options.noProject && await hasProjectWiki(projectRoot)) {
         await appendWikiLog(projectRoot, `llm-wiki-kit post-update applied runtime ${runtimeVersion()}; changed templates: ${projectResult.changed.length}`);
       }
@@ -114,9 +140,7 @@ export async function postUpdate(options = {}) {
     };
   }
 
-  const projectResult = options.noProject
-    ? null
-    : await applyProjectTemplateUpdate(workspace);
+  const projectResult = await applyTemplatesToProject(workspace, options);
 
   if (!options.noProject && await hasProjectWiki(workspace)) {
     await appendWikiLog(workspace, `llm-wiki-kit post-update applied runtime ${runtimeVersion()}; changed templates: ${projectResult.changed.length}`);
@@ -148,23 +172,40 @@ export async function update(options = {}) {
   }
 
   if (options.dryRun) {
+    const workspaces = await projectRootsForUpdate(workspace, options);
+    const projects = [];
+    for (const projectRoot of workspaces) {
+      projects.push({
+        workspace: projectRoot,
+        project: options.noProject ? null : await applyProjectTemplateUpdate(projectRoot, { dryRun: true }),
+      });
+    }
     return {
       mode: 'dry-run',
       workspace,
       ...check,
       installSource: detectInstallSource(),
-      project: options.noProject ? null : await applyProjectTemplateUpdate(workspace, { dryRun: true }),
+      scope: shouldUpdateAllProjects(options) ? 'all' : 'current',
+      project: projects.find((item) => item.workspace === workspace)?.project || projects[0]?.project || null,
+      projects: shouldUpdateAllProjects(options) ? projects : undefined,
     };
   }
 
   const target = options.to || 'latest';
-  const installResult = runCommand(npmCommand(), ['install', '-g', `${packageName()}@${target}`], {
-    timeout: options.timeout || 120000,
-  });
+  const shouldRunNpmInstall = check.updateAvailable;
+  const installResult = shouldRunNpmInstall
+    ? runCommand(npmCommand(), ['install', '-g', `${packageName()}@${target}`], {
+      timeout: options.timeout || 120000,
+    })
+    : {
+      status: 0,
+      stdout: `skipped; installed ${check.installedVersion} is already >= target ${check.latestVersion}`,
+      stderr: '',
+    };
   assertCommandOk(installResult, 'npm install -g');
 
-  const postArgs = [binCommand(), 'post-update', '--workspace', workspace];
-  if (options.all) postArgs.push('--all');
+  const postArgs = [binCommand(), 'post-update', '--workspace', workspace, '--json'];
+  if (shouldUpdateAllProjects(options)) postArgs.push('--all');
   if (options.profile) postArgs.push('--profile', options.profile);
   if (options.noProject) postArgs.push('--no-project');
   if (options.codex === false) postArgs.push('--no-codex');
@@ -173,16 +214,21 @@ export async function update(options = {}) {
     timeout: options.timeout || 120000,
   });
   assertCommandOk(postResult, 'post-update');
+  const parsedPostUpdate = parseJsonOutput(postResult.stdout);
 
   return {
     mode: 'update',
     workspace,
     before: check.installedVersion,
     target,
+    scope: shouldUpdateAllProjects(options) ? 'all' : 'current',
     npmInstall: {
+      skipped: !shouldRunNpmInstall,
       stdout: installResult.stdout.trim(),
       stderr: installResult.stderr.trim(),
     },
-    postUpdate: postResult.stdout.trim(),
+    postUpdate: parsedPostUpdate || postResult.stdout.trim(),
+    project: parsedPostUpdate?.project,
+    projects: parsedPostUpdate?.projects,
   };
 }