llm-wiki-kit 0.2.3 → 0.2.5

package/README.md

@@ -16,6 +16,20 @@ llm-wiki doctor --workspace /apps
 
 Restart Claude Code and Codex sessions after installation.
 
+### Native Windows
+
+Native Windows is supported through the npm-generated `llm-wiki.cmd` shim. Use PowerShell or Windows Terminal with Node.js 20+:
+
+```powershell
+npm install -g llm-wiki-kit@latest
+llm-wiki install --workspace C:\path\to\project --profile standard
+llm-wiki doctor --workspace C:\path\to\project
+```
+
+On Windows, `llm-wiki install` does not create a Unix-style `~/.local/bin` symlink. It verifies the npm shim on `PATH`, installs Codex hooks with `commandWindows`, and writes Claude Code hooks with a Windows-safe `node.exe <bin>` command. Restart Codex and Claude Code after installation.
+
+Use WSL2 instead when your repository and tooling already live in Linux. Native Windows support is for Windows-hosted projects and the native Codex/Claude Code surfaces.
+
 The default install mode is npm global install. On servers where the global npm prefix is root-owned, use sudo:
 
 ```bash
@@ -73,6 +87,7 @@ Use Claude Code or Codex normally.
 The installed hooks:
 
 - inject `wiki/memory.md`, `wiki/index.md`, and relevant wiki context at session start, instructions loaded, prompt submit, and post-compact time
+- remove Codex-facing legacy `oh-my-codex:wiki`/`omx_wiki` surfaces at session start so `llm-wiki/` remains the active wiki implementation
 - record small redacted raw event envelopes and per-turn state
 - capture decision points, debugging findings, changed files, and verification notes
 - allow tool calls to proceed without secret/PII-based hook blocking
@@ -102,7 +117,7 @@ Most users should not need these during daily Claude Code/Codex work. They exist
 
 `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 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 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. The command prints step progress to stderr, including registry lookup, npm install, post-update, and project discovery. Use `--timeout-ms <ms>` to bound external commands and `--max-dirs <n>` to bound project discovery under large or slow roots such as WSL `/mnt/*` trees.
 
 Installed npm runtimes also perform a cached update notice check from hooks while the user works. This does not install anything automatically. When a newer npm release is detected, the injected hook context gives the active agent a Korean update reminder and tells it to offer `llm-wiki update --workspace <project-or-search-root>`. The cache is scoped to the npm command used for lookup so test/fake npm checks do not leak into normal hook sessions. Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` only when diagnosing or suppressing that reminder.
 
@@ -118,9 +133,13 @@ Installed npm runtimes also perform a cached update notice check from hooks whil
 
 `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`.
 
+For `llm-wiki-kit` code releases, source tests are not enough. After code changes, publish the package, install the newly published version, and verify the installed CLI and hooks with `version`, `status`, `doctor`, `update`, `lint`, and hook smoke checks before calling the release complete.
+
+Native Windows changes require a real Windows smoke before release. The release gate is: install the packed candidate on a Windows host, run `llm-wiki install`, `llm-wiki status`, and `llm-wiki doctor` against a temporary Windows project, inspect `%USERPROFILE%\.codex\hooks.json` and `%USERPROFILE%\.claude\settings.json`, then repeat the minimal smoke after `npm install -g llm-wiki-kit@latest` once published. Simulated unit tests are not enough for the Windows support claim.
+
 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 Linux/macOS, `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 Windows, the npm-generated `llm-wiki.cmd` shim is the supported command entrypoint and no local symlink is created.
 
 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:
 

package/docs/integrations/claude-code.md

@@ -16,7 +16,7 @@ The installed hook stores the Node executable and the absolute package binary pa
 
 User-local fallback installs may instead point under `$HOME/.local/lib/node_modules`.
 
-Handled events:
+Handled events on compatible Claude Code versions:
 
 - `SessionStart`
 - `InstructionsLoaded`
@@ -30,6 +30,8 @@ Handled events:
 - `Stop`
 - `SessionEnd`
 
+`llm-wiki install` detects `claude --version` and installs a conservative event set when the local Claude Code binary is older or cannot be detected. `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `PostCompact`, `SubagentStop`, and `Stop` are treated as the stable set. `InstructionsLoaded`, `PostToolBatch`, and `SessionEnd` are installed only for newer compatible versions, or when `LLM_WIKI_KIT_CLAUDE_MODERN_HOOKS=1` is set. Existing kit-managed hooks for unsupported event keys are removed during install so Claude Code does not skip the entire settings file with an “Invalid key in record” error.
+
 Claude Code reads `CLAUDE.md`. For project compatibility, the kit creates a `CLAUDE.md` stub containing:
 
 ```text

package/docs/integrations/codex.md

@@ -29,7 +29,7 @@ Handled events:
 
 Expected behavior:
 
-- `SessionStart` first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, performs a cached npm update notice check for npm installs, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, a one-item maintenance summary when needed, any Korean update notice, and any maintenance note for outdated or customized managed rules.
+- `SessionStart` first attempts a safe managed-template refresh, removes Codex-facing legacy `oh-my-codex:wiki`/`omx_wiki` surfaces when they reappear, recovers stale turn state into `outputs/maintenance/queue.md`, performs a cached npm update notice check for npm installs, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, a one-item maintenance summary when needed, any Korean update notice, and any maintenance note for outdated or customized managed rules.
 - `UserPromptSubmit` recovers stale turn state, searches project wiki pages with MiniSearch or substring fallback, expands one-hop wikilinks, redacts context fields, performs the same cached update notice check, and injects the smallest useful context set. Update notice cache is scoped by npm command, and maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
 - `PreToolUse` records redacted tool summaries without blocking tool calls.
 - `PostToolUse` records redacted tool summaries in a turn buffer.

package/docs/manual.md

@@ -69,6 +69,7 @@ llm-wiki/
 - 사용자가 명시적으로 문서화/기록을 요청했는데 durable wiki 반영이 없으면 `outputs/maintenance/queue.md`에 정리 후보를 남긴다.
 - 이전 session이 깨끗하게 종료되지 않았을 때 stale turn state를 maintenance queue로 복구할 수 있다.
 - 새 runtime이 오래된 project rules/templates를 발견하면 안전하게 갱신 가능한 managed file만 refresh한다.
+- `SessionStart`/`InstructionsLoaded`에서 Codex-facing legacy `oh-my-codex:wiki`/`omx_wiki` 설정과 스킬 표면이 되살아났는지 확인하고 제거한다. wiki 기능은 `llm-wiki/`가 단일 활성 구현이다.
 
 매번 저장 여부를 사용자가 고민해야 한다면 잘못 쓰고 있는 것이다. 답변보다 wiki maintenance가 먼저 오면 안 된다. 현재 사용자 요청을 먼저 처리하고, 오래 쓸 지식만 필요한 만큼 정리한다.
 
@@ -119,6 +120,14 @@ llm-wiki install --workspace /path/to/project --profile standard
 llm-wiki install --workspace /path/to/project --profile standard --no-project
 ```
 
+Native Windows에서는 PowerShell/Windows Terminal에서 npm shim을 사용한다.
+
+```powershell
+npm install -g llm-wiki-kit@latest
+llm-wiki install --workspace C:\path\to\project --profile standard
+llm-wiki doctor --workspace C:\path\to\project
+```
+
 `standard` profile은 기본 profile이다.
 
 - context injection
@@ -129,7 +138,7 @@ llm-wiki install --workspace /path/to/project --profile standard --no-project
 
 `--no-project`는 hook/bin 설치만 하고 현재 workspace bootstrap은 하지 않을 때 사용한다.
 
-global npm package 설치 자체는 환경에 따라 `npm install -g` 또는 `sudo npm install -g`로 수행한다. hook 설정 갱신은 보통 일반 사용자 home 아래 파일을 수정하므로 `llm-wiki install`은 해당 user로 실행한다.
+global npm package 설치 자체는 환경에 따라 `npm install -g` 또는 `sudo npm install -g`로 수행한다. hook 설정 갱신은 보통 일반 사용자 home 아래 파일을 수정하므로 `llm-wiki install`은 해당 user로 실행한다. Windows에서는 npm이 만든 `llm-wiki.cmd`를 표준 command shim으로 사용하며 Unix-style `~/.local/bin` symlink를 만들지 않는다. Codex hook에는 Windows 실행용 `commandWindows`가 함께 기록된다.
 
 ### `llm-wiki update`
 
@@ -141,11 +150,14 @@ llm-wiki update --workspace /path/to/search-root
 llm-wiki update --workspace /path/to/search-root --to 0.2.1
 llm-wiki update --workspace /path/to/project --current-only
 llm-wiki update --workspace /path/to/project --dry-run
+llm-wiki update --workspace /path/to/search-root --timeout-ms 120000 --max-dirs 5000
 ```
 
 `--check`는 network를 사용하지만 파일을 변경하지 않는다. installed version보다 registry target이 최신일 때만 update available을 보고한다.
 
-기본 `update --workspace <search-root>`는 runtime update를 한 번 수행한 뒤, known/discovered project roots의 managed templates를 재적용한다. 기존 wiki contents는 덮어쓰지 않는다.
+기본 `update --workspace <search-root>`는 runtime update를 한 번 수행한 뒤, known/discovered project roots의 managed templates를 재적용한다. 기존 wiki contents는 덮어쓰지 않는다. `update`는 registry lookup, npm install, post-update, project discovery 진행 상태를 stderr에 출력한다. JSON 모드에서도 stdout은 JSON만 유지하고 progress는 stderr로 분리한다.
+
+`--timeout-ms`는 `npm view`, `npm install -g`, internal `post-update` 같은 외부 command timeout을 지정한다. timeout 후 SIGTERM과 짧은 grace period 뒤 SIGKILL을 사용해 child process가 terminal을 계속 붙잡는 hard hang을 방지한다. `--max-dirs`는 search root 아래 project discovery가 검사할 최대 directory 수를 제한한다.
 
 `update`는 source checkout에서 self-update하지 않는다. source checkout 개발 중에는 npm package나 local tarball로 global install한 뒤 update behavior를 테스트한다.
 
@@ -412,16 +424,35 @@ node --test
 npm pack --dry-run
 ```
 
+Native Windows 관련 변경은 publish 전 실제 Windows 설치 검증이 필수다. 후보 tarball을 Windows host에 설치하고 임시 project에서 다음을 확인한다.
+
+```powershell
+npm install -g .\llm-wiki-kit-<version>.tgz
+llm-wiki version
+llm-wiki install --workspace C:\Temp\llm-wiki-kit-smoke --profile standard
+llm-wiki status --workspace C:\Temp\llm-wiki-kit-smoke
+llm-wiki doctor --workspace C:\Temp\llm-wiki-kit-smoke
+```
+
+검증에는 `%USERPROFILE%\.codex\hooks.json`의 `commandWindows`, `%USERPROFILE%\.claude\settings.json`의 Windows-safe `node.exe` command, project-local `llm-wiki/` 생성, sample hook roundtrip이 포함된다. 원격 자동화는 WinRM을 사용하되 credential은 환경변수나 secret store로만 전달하고 wiki/log에 저장하지 않는다.
+
 publish 후 검증:
 
 ```bash
 npm view llm-wiki-kit version --registry=https://registry.npmjs.org/
+npm install -g llm-wiki-kit@<published-version> --registry=https://registry.npmjs.org/ --prefer-online
 llm-wiki version
 llm-wiki manual
 llm-wiki status --workspace /apps
 llm-wiki doctor --workspace /apps
+llm-wiki update --workspace /apps --dry-run
+llm-wiki update --workspace /apps --current-only
 ```
 
+`llm-wiki-kit` 코드 변경 릴리스는 publish와 새 published version 설치 후 검증까지 끝나야 완료로 본다. root-owned global npm prefix에서는 package install에 `sudo npm install -g`가 필요할 수 있고, user home hook 갱신은 일반 user로 `llm-wiki install` 또는 `post-update`를 실행한다.
+
+Windows 지원 변경이 포함된 릴리스는 publish 후에도 같은 Windows host에서 `npm install -g llm-wiki-kit@latest` 후 최소 `version/status/doctor` smoke를 반복한다.
+
 ## Troubleshooting Shortcuts
 
 hook이 안 돈다면:
@@ -440,6 +471,14 @@ npm root -g
 node "$(npm root -g)/llm-wiki-kit/bin/llm-wiki.js" version
 ```
 
+Windows에서는 `where llm-wiki`와 npm prefix를 먼저 확인한다.
+
+```powershell
+where llm-wiki
+npm root -g
+node "$(npm root -g)\llm-wiki-kit\bin\llm-wiki.js" version
+```
+
 local shim이 npm global command를 shadowing하면:
 
 ```bash

package/docs/operations.md

@@ -24,6 +24,14 @@ npm install -g llm-wiki-kit
 llm-wiki install --workspace /apps --profile standard
 ```
 
+Native Windows:
+
+```powershell
+npm install -g llm-wiki-kit@latest
+llm-wiki install --workspace C:\path\to\project --profile standard
+llm-wiki doctor --workspace C:\path\to\project
+```
+
 The default install mode is npm global install. On servers where the global npm prefix is root-owned, use sudo:
 
 ```bash
@@ -42,8 +50,9 @@ Avoid mixing root-owned and user-local installs unless you intentionally choose
 The installer:
 
 - 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
+- on Linux/macOS, removes an older kit-managed `~/.local/bin/llm-wiki` shim when it shadows that npm/nvm command
+- on Linux/macOS, 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
+- on Windows, relies on the npm-generated `llm-wiki.cmd` shim and does not create a Unix-style local symlink
 - backs up existing Codex/Claude settings before editing
 - merges hook entries without removing existing hooks
 - bootstraps the workspace `llm-wiki/`
@@ -58,6 +67,13 @@ npm install
 ./install.sh --workspace /apps --profile standard
 ```
 
+On Windows source checkouts, run the CLI through Node instead of `install.sh`:
+
+```powershell
+npm install
+node bin\llm-wiki.js install --workspace C:\path\to\project --profile standard
+```
+
 Pre-publish server smoke tests can use a local tarball:
 
 ```bash
@@ -81,6 +97,7 @@ 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/search-root --timeout-ms 120000 --max-dirs 5000
 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
@@ -113,8 +130,10 @@ Installed npm runtimes also run a cached hook-side update notice check while the
 - reinstalls hook entries without duplicating them
 - patches only managed project files across known or discovered project roots
 - backs up changed files under `~/.local/share/llm-wiki-kit/backups/`
+- prints update progress to stderr and keeps JSON output parseable on stdout
+- force-kills unresponsive child commands after timeout so slow npm/WSL environments do not wait forever
 
-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.
+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. Use `--max-dirs` when a search root is a very large or slow tree.
 
 `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.
 
@@ -208,6 +227,25 @@ llm-wiki version
 
 Do not delete the whole `~/.local/bin` directory. It may contain unrelated user tools.
 
+## Updating Native Windows Installs
+
+Windows uses npm's command shim. If `llm-wiki` is missing or old after install, inspect the Windows command resolution:
+
+```powershell
+where llm-wiki
+npm root -g
+node "$(npm root -g)\llm-wiki-kit\bin\llm-wiki.js" version
+llm-wiki status --workspace C:\path\to\project
+```
+
+If `where llm-wiki` does not show the npm shim, reinstall the package in the active Node installation:
+
+```powershell
+npm uninstall -g llm-wiki-kit
+npm install -g llm-wiki-kit@latest --registry=https://registry.npmjs.org/ --prefer-online
+llm-wiki install --workspace C:\path\to\project --profile standard
+```
+
 Use package-name-only uninstall syntax:
 
 ```bash
@@ -239,6 +277,18 @@ npm pack --dry-run
 
 Check that the tarball includes `bin/`, `src/`, `docs/`, `examples/`, `README.md`, `LICENSE`, `install.sh`, and `package.json`, but does not include project-local `llm-wiki/` contents.
 
+For Native Windows changes, a real Windows smoke is mandatory before publishing. Install the candidate tarball on a Windows host and verify:
+
+```powershell
+npm install -g .\llm-wiki-kit-<version>.tgz
+llm-wiki version
+llm-wiki install --workspace C:\Temp\llm-wiki-kit-smoke --profile standard
+llm-wiki status --workspace C:\Temp\llm-wiki-kit-smoke
+llm-wiki doctor --workspace C:\Temp\llm-wiki-kit-smoke
+```
+
+Inspect `%USERPROFILE%\.codex\hooks.json` for `commandWindows`, `%USERPROFILE%\.claude\settings.json` for a Windows-safe `node.exe` hook command, and the temporary project for the generated `llm-wiki/` tree. If this is automated from Linux, use WinRM and keep credentials only in environment variables or a secret store.
+
 After publishing:
 
 ```bash
@@ -250,6 +300,8 @@ llm-wiki doctor --workspace /apps
 llm-wiki update --check --workspace /apps
 ```
 
+For Native Windows changes, repeat a minimal post-publish smoke on the same Windows host after `npm install -g llm-wiki-kit@latest`.
+
 ## Uninstall
 
 ```bash

package/docs/troubleshooting.md

@@ -36,6 +36,35 @@ llm-wiki update --check --workspace /path/to/project
 
 `status` does not contact the network. `update --check` contacts npm but does not change files.
 
+## llm-wiki update Appears To Hang
+
+`update` runs `npm view`, optional `npm install -g`, project discovery, and `post-update`. It prints progress to stderr while keeping JSON output on stdout parseable. In slow WSL or Windows-mounted trees, start with a bounded dry run:
+
+```bash
+llm-wiki update --dry-run --workspace /path/to/project --current-only --timeout-ms 30000
+llm-wiki update --dry-run --workspace /path/to/search-root --max-dirs 1000 --timeout-ms 30000
+```
+
+If the current project succeeds but the search root is slow, use `--current-only` for that project or raise `--max-dirs` intentionally. If npm itself is slow, compare with:
+
+```bash
+npm view llm-wiki-kit version --registry=https://registry.npmjs.org/
+```
+
+When a child command exceeds `--timeout-ms`, `update` terminates it and then force-kills it after a short grace period.
+
+## Claude Code Settings Error: Invalid Hook Key
+
+Some Claude Code versions reject newer hook event keys such as `PostToolBatch`. Run:
+
+```bash
+claude --version
+llm-wiki install --workspace /path/to/project --profile standard
+llm-wiki doctor --workspace /path/to/project
+```
+
+The installer detects the local Claude version, installs only compatible hook events, and removes kit-managed hooks for unsupported event keys. User-defined hooks are preserved when possible.
+
 ## npm Says The Package Is Not Found
 
 If `llm-wiki update --check` returns npm 404, the package is not published to the registry being used. Until publish, test npm installation with a local tarball:
@@ -94,6 +123,15 @@ npm root -g
 node "$(npm root -g)/llm-wiki-kit/bin/llm-wiki.js" version
 ```
 
+On Native Windows, use PowerShell:
+
+```powershell
+where llm-wiki
+npm ls -g llm-wiki-kit --depth=0
+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, reconnect through the installer:
 
 ```bash
@@ -106,7 +144,7 @@ After a manual `sudo npm install -g llm-wiki-kit@latest`, a normal-user `llm-wik
 
 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.
 
-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.
+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. On Linux/macOS, `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. On Windows, `install` relies on npm's `llm-wiki.cmd` shim and does not create a Unix-style symlink.
 
 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:
 
@@ -130,6 +168,16 @@ llm-wiki version
 
 Use `npm uninstall -g llm-wiki-kit` with the package name only. `npm uninstall -g llm-wiki-kit@latest` is not the correct uninstall syntax and does not remove source checkouts or manually-created command shims.
 
+If `where llm-wiki` is empty on Windows after npm install, the active Node npm prefix is not on `PATH` or npm did not create the shim. Reinstall with the active Node installation, then restart the terminal:
+
+```powershell
+npm uninstall -g llm-wiki-kit
+npm install -g llm-wiki-kit@latest --registry=https://registry.npmjs.org/ --prefer-online
+where llm-wiki
+llm-wiki install --workspace C:\path\to\project --profile standard
+llm-wiki doctor --workspace C:\path\to\project
+```
+
 ## npm install -g Fails With EACCES
 
 If npm tries to write under `/usr` and fails with `EACCES`, use sudo when the server policy allows system-wide global packages:

package/package.json

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

package/src/claude-compat.js

@@ -0,0 +1,83 @@
+import { spawnSync } from 'child_process';
+
+export const CLAUDE_STABLE_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PostToolUse',
+  'PreCompact',
+  'PostCompact',
+  'SubagentStop',
+  'Stop',
+];
+
+export const CLAUDE_MODERN_EVENTS = [
+  'InstructionsLoaded',
+  'PostToolBatch',
+  'SessionEnd',
+];
+
+export const CLAUDE_MODERN_MIN_VERSION = '2.1.138';
+
+function parseVersion(value) {
+  return String(value || '')
+    .replace(/^v/, '')
+    .split('.', 3)
+    .map((part) => {
+      const parsed = Number.parseInt(part, 10);
+      return Number.isFinite(parsed) ? parsed : 0;
+    });
+}
+
+export function compareClaudeVersions(a, b) {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  for (let i = 0; i < 3; i += 1) {
+    const diff = (left[i] || 0) - (right[i] || 0);
+    if (diff !== 0) return diff > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+export function parseClaudeVersionOutput(output) {
+  return String(output || '').match(/\b(\d+\.\d+\.\d+)\b/)?.[1] || '';
+}
+
+export function detectClaudeVersion(options = {}) {
+  if (process.env.LLM_WIKI_KIT_CLAUDE_VERSION) {
+    const version = process.env.LLM_WIKI_KIT_CLAUDE_VERSION;
+    return {
+      available: true,
+      version,
+      raw: version,
+      modern: compareClaudeVersions(version, CLAUDE_MODERN_MIN_VERSION) >= 0,
+    };
+  }
+
+  const command = options.command || process.env.LLM_WIKI_KIT_CLAUDE || 'claude';
+  const result = spawnSync(command, ['--version'], {
+    encoding: 'utf8',
+    timeout: options.timeout || 5000,
+  });
+  const raw = `${result.stdout || ''}${result.stderr || ''}`.trim();
+  const version = parseClaudeVersionOutput(raw);
+  return {
+    available: result.status === 0 && !result.error,
+    version,
+    raw,
+    modern: Boolean(version) && compareClaudeVersions(version, CLAUDE_MODERN_MIN_VERSION) >= 0,
+    error: result.error?.message || null,
+  };
+}
+
+export function supportedClaudeEvents(detection = detectClaudeVersion()) {
+  if (process.env.LLM_WIKI_KIT_CLAUDE_MODERN_HOOKS === '1') {
+    return [...CLAUDE_STABLE_EVENTS, ...CLAUDE_MODERN_EVENTS];
+  }
+  if (process.env.LLM_WIKI_KIT_CLAUDE_MODERN_HOOKS === '0') {
+    return [...CLAUDE_STABLE_EVENTS];
+  }
+  return detection.modern
+    ? [...CLAUDE_STABLE_EVENTS, ...CLAUDE_MODERN_EVENTS]
+    : [...CLAUDE_STABLE_EVENTS];
+}

package/src/cli.js

@@ -32,6 +32,22 @@ function parseOptions(args) {
     } else if (arg === '--to') {
       options.to = optionValue(arg, i);
       i += 1;
+    } else if (arg === '--timeout-ms') {
+      const value = optionValue(arg, i);
+      const timeout = Number(value);
+      if (!Number.isInteger(timeout) || timeout < 1000) {
+        throw new Error('--timeout-ms must be an integer >= 1000');
+      }
+      options.timeout = timeout;
+      i += 1;
+    } else if (arg === '--max-dirs') {
+      const value = optionValue(arg, i);
+      const maxDirs = Number(value);
+      if (!Number.isInteger(maxDirs) || maxDirs < 1) {
+        throw new Error('--max-dirs must be a positive integer');
+      }
+      options.maxDirs = maxDirs;
+      i += 1;
     } else if (arg === '--no-codex') {
       options.codex = false;
     } else if (arg === '--no-claude') {
@@ -88,7 +104,7 @@ export async function runCli(args) {
 
 Usage:
   llm-wiki install --workspace /apps [--profile standard]
-  llm-wiki update --workspace <project-or-search-root> [--check|--dry-run|--current-only|--to <version-or-tag>]
+  llm-wiki update --workspace <project-or-search-root> [--check|--dry-run|--current-only|--to <version-or-tag>] [--timeout-ms 120000] [--max-dirs 5000]
   llm-wiki post-update --workspace <project> [--all]
   llm-wiki doctor --workspace <project>
   llm-wiki projects --workspace /apps
@@ -115,7 +131,7 @@ Usage:
       `- workspace: ${value.workspace}`,
       `- runtime bin: ${value.binPath}`,
       `- command: ${value.commandPath || 'not found on PATH'}`,
-      `- local shim: ${value.localBin} (${value.localBinAction})`,
+      `- command shim: ${value.localBin || value.commandPath || 'not found'} (${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'));
@@ -156,12 +172,21 @@ Usage:
   }
 
   if (command === 'update') {
-    printJsonOrText(await update(options), options, formatUpdate);
+    printJsonOrText(await update({
+      ...options,
+      onProgress: (message) => console.error(`[llm-wiki update] ${message}`),
+    }), options, formatUpdate);
     return;
   }
 
   if (command === 'post-update') {
-    printJsonOrText(await postUpdate(options), options, formatPostUpdate);
+    const postOptions = process.env.LLM_WIKI_KIT_PROGRESS === '1'
+      ? {
+        ...options,
+        onProgress: (message) => console.error(`[llm-wiki post-update] ${message}`),
+      }
+      : options;
+    printJsonOrText(await postUpdate(postOptions), options, formatPostUpdate);
     return;
   }
 
@@ -226,7 +251,7 @@ Usage:
 
 async function listProjects(options) {
   const workspace = resolve(options.workspace || process.cwd());
-  const roots = await knownProjectRoots({ workspace });
+  const roots = await knownProjectRoots({ workspace, maxDirs: options.maxDirs });
   const projects = [];
   for (const root of roots) {
     let state = null;
@@ -256,14 +281,17 @@ function formatStatus(value) {
   return [
     'llm-wiki-kit status',
     `- version: ${value.runtimeVersion}`,
+    `- platform: ${value.platform || process.platform}`,
     `- runtime: ${value.runtimeVersion} (${value.installSource})`,
     `- 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' : ''})`,
+    `- command 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'}`,
+    `- claude version: ${value.claudeVersion || 'unknown'} (${value.claudeModernHooks ? 'modern hooks' : 'compatible hooks'})`,
+    `- claude unsupported kit hooks: ${(value.claudeUnsupportedKitEvents || []).join(', ') || 'none'}`,
     `- project applied runtime: ${project.lastRuntimeVersionApplied || 'unknown'}`,
     `- project templates current: ${project.managedFilesCurrent ? 'yes' : 'no'}`,
     `- project auto-updateable rules: ${autoUpdateCount}`,

package/src/doctor.js

@@ -1,9 +1,11 @@
 import { spawnSync } from 'child_process';
-import { join } from 'path';
+import { dirname, join } from 'path';
 import { mkdtemp } from 'fs/promises';
 import { tmpdir } from 'os';
+import { fileURLToPath } from 'url';
 import { exists, kitDataDir } from './fs-utils.js';
 import { status } from './install.js';
+import { isWindows } from './platform.js';
 
 function nodeMajor() {
   return Number.parseInt(process.versions.node.split('.')[0], 10);
@@ -21,9 +23,15 @@ export async function runDoctor(options = {}) {
   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(
+    'claude-settings-compatible',
+    'Claude hook settings compatible',
+    (stat.claudeUnsupportedKitEvents || []).length === 0,
+    `version=${stat.claudeVersion || 'unknown'}; unsupported=${(stat.claudeUnsupportedKitEvents || []).join(', ') || 'none'}`
+  );
   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('codex-command', 'codex command available', commandVersionAvailable('codex'), 'codex --version');
+  add('claude-command', 'claude command available', commandVersionAvailable('claude'), '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');
@@ -32,8 +40,17 @@ export async function runDoctor(options = {}) {
   return { ok: allOk, checks, workspace: stat.workspace, status: stat };
 }
 
+function commandVersionAvailable(command) {
+  const result = spawnSync(command, ['--version'], {
+    encoding: 'utf8',
+    shell: isWindows(),
+    timeout: 10000,
+  });
+  return result.status === 0;
+}
+
 async function docsPresent() {
-  const root = new URL('..', import.meta.url).pathname;
+  const root = dirname(dirname(fileURLToPath(import.meta.url)));
   return (await exists(join(root, 'README.md'))) &&
     (await exists(join(root, 'docs', 'concepts.md'))) &&
     (await exists(join(root, 'docs', 'security.md')));
@@ -99,19 +116,24 @@ function failed(result, id) {
 
 function doctorRemediation(result) {
   const workspace = result.workspace || process.cwd();
+  const windows = isWindows({ platform: result.status?.platform });
   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`);
+    suggestions.push(windows
+      ? `source checkout development: node bin\\llm-wiki.js install --workspace ${workspace} --profile standard`
+      : `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) {
+    if (!windows && 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`);
+    suggestions.push(windows
+      ? `reinstall npm shim and hooks: npm install -g llm-wiki-kit@latest && llm-wiki install --workspace ${workspace} --profile standard`
+      : `reconnect command and hooks: llm-wiki install --workspace ${workspace} --profile standard`);
   }
-  if (failed(result, 'codex-hook') || failed(result, 'claude-hook')) {
+  if (failed(result, 'codex-hook') || failed(result, 'claude-hook') || failed(result, 'claude-settings-compatible')) {
     suggestions.push(`install hooks: llm-wiki install --workspace ${workspace} --profile standard, then restart Codex/Claude Code sessions`);
   }
   if (failed(result, 'project-templates')) {