llm-wiki-kit 0.2.2 → 0.2.4

package/README.md

@@ -73,6 +73,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,9 +103,9 @@ 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 tells the active agent to mention the available update and offer `llm-wiki update --workspace <project-or-search-root>`. Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` only when diagnosing or suppressing that reminder.
+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.
 
 `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.
 
@@ -118,6 +119,8 @@ 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.
+
 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.

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
@@ -40,7 +42,7 @@ when no project `CLAUDE.md` exists. Existing `CLAUDE.md` files are not overwritt
 
 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 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 update notice, and any maintenance note for outdated or customized managed rules. At `UserPromptSubmit`, it recovers stale turn state, searches 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. Maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
+At `SessionStart`/`InstructionsLoaded`, the hook 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. At `UserPromptSubmit`, it recovers stale turn state, searches 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.
 
 `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. In the default `answer-first` mode, `SubagentStop` does not create live Q&A, query, decision, or maintenance files. `Stop` and `SessionEnd` append live Q&A only for meaningful work turns and do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked to record or document durable knowledge and no durable wiki update is detected, `Stop`/`SessionEnd` queue a pending maintenance item for agent review. `Stop` and `SessionEnd` then clear the per-session turn buffer; `SubagentStop` does not.
 

package/docs/integrations/codex.md

@@ -29,8 +29,8 @@ 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 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. Maintenance reminders are shown only when the prompt is wiki/maintenance related or matches a queue topic.
+- `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.
 - `PreCompact` records a compaction note; `PostCompact` records the note and returns fresh wiki context.

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가 먼저 오면 안 된다. 현재 사용자 요청을 먼저 처리하고, 오래 쓸 지식만 필요한 만큼 정리한다.
 
@@ -141,15 +142,18 @@ 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를 테스트한다.
 
-global npm runtime으로 설치된 경우 hook은 사용 흐름 중 cached update notice check를 수행한다. 자동 설치는 하지 않는다. 새 npm release가 감지되면 hook context가 active agent에게 “업데이트 가능”을 짧게 알리고 `llm-wiki update --workspace <project-or-search-root>` 실행을 제안하게 한다. `LLM_WIKI_KIT_UPDATE_NOTICE=0`으로 이 reminder만 끌 수 있다.
+global npm runtime으로 설치된 경우 hook은 사용 흐름 중 cached update notice check를 수행한다. 자동 설치는 하지 않는다. 새 npm release가 감지되면 hook context가 active agent에게 한국어로 “업데이트 가능”을 짧게 알리고 `llm-wiki update --workspace <project-or-search-root>` 실행을 제안하게 한다. cache는 lookup에 사용한 npm command별로 분리되어 test/fake npm 결과가 일반 hook session에 섞이지 않는다. `LLM_WIKI_KIT_UPDATE_NOTICE=0`으로 이 reminder만 끌 수 있다.
 
 ### `llm-wiki post-update`
 
@@ -416,12 +420,17 @@ 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`를 실행한다.
+
 ## Troubleshooting Shortcuts
 
 hook이 안 돈다면:

package/docs/operations.md

@@ -81,6 +81,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
@@ -101,7 +102,7 @@ llm-wiki maintenance --workspace /path/to/project
 
 `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.
 
-Installed npm runtimes also run a cached hook-side update notice check while the user works. It never installs automatically. If npm has a newer release, `SessionStart`/`InstructionsLoaded`/`UserPromptSubmit` context tells the active agent to mention the available update and offer `llm-wiki update --workspace <project-or-search-root>`. Set `LLM_WIKI_KIT_UPDATE_NOTICE=0` to suppress this reminder while diagnosing.
+Installed npm runtimes also run a cached hook-side update notice check while the user works. It never installs automatically. If npm has a newer release, `SessionStart`/`InstructionsLoaded`/`UserPromptSubmit` 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` to suppress this reminder while diagnosing.
 
 `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.
 
@@ -113,8 +114,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.
 

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:

package/package.json

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

package/src/capture-policy.js

@@ -148,15 +148,16 @@ export function formatDurableCaptureGuidance(query) {
   if (!text) return '';
   if (explicitDurableRequested(text)) {
     return [
-      'LLM Wiki durable documentation request detected:',
+      'LLM Wiki 문서화 요청 감지:',
       '- 현재 사용자 요청을 먼저 처리하되, 사용자가 기록/문서화를 요청했으므로 기존 durable wiki 문서를 찾아 갱신한다.',
       '- 새 문서는 관련 기존 문서가 없을 때만 만들고, credentials/private data는 저장하지 않는다.',
     ].join('\n');
   }
   if (hasDurableKeyword(text)) {
     return [
-      'LLM Wiki durable knowledge note:',
-      '- 현재 답변을 먼저 한다. 다음 세션에도 쓸 결론이면 답변 끝에서 짧게 wiki 문서화 여부를 물어본다.',
+      'LLM Wiki 저장 후보 알림:',
+      '- 현재 답변을 먼저 한다.',
+      '- 다음 세션에도 재사용할 만한 내용(결정, 정책, 디버깅 결과, 운영 절차, 검증된 상태 등)이 있으면 답변 끝에서 짧게 wiki 문서화 여부를 물어본다.',
     ].join('\n');
   }
   return '';

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
@@ -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;
@@ -264,6 +289,8 @@ function formatStatus(value) {
     `- 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}`,
@@ -279,7 +306,7 @@ function formatUpdate(value) {
       `- installed: ${value.installedVersion}`,
       `- latest: ${value.latestVersion}`,
       `- update available: ${value.updateAvailable ? 'yes' : 'no'}`,
-      ...(value.updateAvailable ? [`- recommended action: ${commandForProject('update', value.workspace)}`] : []),
+      ...(value.updateAvailable ? [`- 권장 실행: ${commandForProject('update', value.workspace)}`] : []),
       `- project applied runtime: ${value.project?.lastRuntimeVersionApplied || 'unknown'}`,
     ].join('\n');
   }
@@ -296,7 +323,7 @@ function formatUpdate(value) {
       `- installed: ${value.installedVersion}`,
       `- latest: ${value.latestVersion}`,
       `- update available: ${value.updateAvailable ? 'yes' : 'no'}`,
-      ...(value.updateAvailable ? [`- recommended action: ${commandForProject('update', value.workspace)}`] : []),
+      ...(value.updateAvailable ? [`- 권장 실행: ${commandForProject('update', value.workspace)}`] : []),
       `- scope: ${value.scope || 'current'}`,
       ...(projects.length > 0 ? [`- projects checked: ${projects.length}`] : []),
       `- project template changes: ${changed}`,

package/src/doctor.js

@@ -21,6 +21,12 @@ 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');
@@ -111,7 +117,7 @@ function doctorRemediation(result) {
     }
     suggestions.push(`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')) {

package/src/hook.js

@@ -7,6 +7,7 @@ import { recordProject } from './projects.js';
 import { summarizeForStorage } from './redaction.js';
 import { buildEntryFromState, clearTurnState, rememberQuestion, rememberTool } from './state.js';
 import { updateNoticeContext } from './update-notice.js';
+import { removeLegacyOmxWikiSurfaces } from './legacy-omx-wiki.js';
 import { relative } from 'path';
 
 async function readStdinJson() {
@@ -75,7 +76,7 @@ async function handleAnswerFirstStop(projectRoot, eventName, payload, entry) {
     const archiveEntry = {
       ...entry,
       followUp: classification.suggestDurable
-        ? '이 결론은 다음 세션에도 쓸 수 있어 보입니다. 사용자가 승인하면 기존 durable wiki 문서에 합친다.'
+        ? '이 turn에 저장할 만한 내용이 있어 보입니다. 사용자가 승인하면 기존 durable wiki 문서에 합친다.'
         : entry.followUp,
     };
     const liveQaPath = await appendLiveQa(projectRoot, archiveEntry);
@@ -104,6 +105,13 @@ async function autoUpdateManagedProject(projectRoot, eventName) {
   }
 }
 
+async function removeLegacyWikiSurfaces(projectRoot, eventName) {
+  if (eventName !== 'SessionStart' && eventName !== 'InstructionsLoaded') return;
+  const result = await removeLegacyOmxWikiSurfaces();
+  if (!result.changed) return;
+  await appendWikiLog(projectRoot, `removed legacy oh-my-codex wiki surfaces: ${result.removed.length}`);
+}
+
 export async function handleHook(provider, explicitEvent) {
   const payload = await readStdinJson();
   payload.__provider = provider;
@@ -113,6 +121,7 @@ export async function handleHook(provider, explicitEvent) {
   await bootstrapProject(projectRoot);
   await recordProject(projectRoot, 'hook').catch(() => {});
   await autoUpdateManagedProject(projectRoot, eventName).catch(() => {});
+  await removeLegacyWikiSurfaces(projectRoot, eventName).catch(() => {});
   await appendSessionEnvelope(projectRoot, eventName, payload).catch(() => {});
   if (eventName === 'SessionStart' || eventName === 'InstructionsLoaded' || eventName === 'UserPromptSubmit') {
     await recoverStaleTurnStates(projectRoot).catch(() => []);

package/src/install.js

@@ -2,7 +2,8 @@ import { realpathSync } from 'fs';
 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 { CODEX_EVENTS, KIT_NAME } from './constants.js';
+import { detectClaudeVersion, supportedClaudeEvents } from './claude-compat.js';
 import { backupFile, exists, homeDir, readJson, safeSymlink, writeJson } from './fs-utils.js';
 import { maintenanceSummary } from './maintenance.js';
 import { inspectProjectState } from './project-state.js';
@@ -50,6 +51,11 @@ function isKitPath(path) {
   return String(path || '').replace(/\\/g, '/').includes('/llm-wiki-kit/');
 }
 
+function isKitHookEntry(entry) {
+  const serialized = JSON.stringify(entry || {});
+  return serialized.includes(KIT_NAME) || serialized.includes(binPath) || serialized.includes('/llm-wiki-kit/');
+}
+
 async function inspectLocalBin(localBinPath) {
   try {
     const stat = await lstat(localBinPath);
@@ -145,18 +151,43 @@ function removeKitHooks(hooks) {
   let changed = false;
   for (const [eventName, entries] of Object.entries(hooks || {})) {
     if (!Array.isArray(entries)) continue;
-    const next = entries.filter((entry) => {
-      const serialized = JSON.stringify(entry);
-      return !serialized.includes(KIT_NAME) && !serialized.includes(binPath);
-    });
+    const next = entries.filter((entry) => !isKitHookEntry(entry));
     if (next.length !== entries.length) {
-      hooks[eventName] = next;
+      if (next.length > 0) hooks[eventName] = next;
+      else delete hooks[eventName];
       changed = true;
     }
   }
   return changed;
 }
 
+function removeUnsupportedKitClaudeHooks(hooks, supportedEvents) {
+  const supported = new Set(supportedEvents);
+  const removed = [];
+  for (const [eventName, entries] of Object.entries(hooks || {})) {
+    if (supported.has(eventName) || !Array.isArray(entries)) continue;
+    const next = entries.filter((entry) => !isKitHookEntry(entry));
+    if (next.length !== entries.length) {
+      removed.push(eventName);
+      if (next.length > 0) hooks[eventName] = next;
+      else delete hooks[eventName];
+    }
+  }
+  return [...new Set(removed)];
+}
+
+function unsupportedKitClaudeEvents(hooks, supportedEvents) {
+  const supported = new Set(supportedEvents);
+  return Object.entries(hooks || {})
+    .filter(([eventName, entries]) => (
+      !supported.has(eventName) &&
+      Array.isArray(entries) &&
+      entries.some((entry) => isKitHookEntry(entry))
+    ))
+    .map(([eventName]) => eventName)
+    .sort();
+}
+
 export async function install(options = {}) {
   const workspace = resolve(options.workspace || process.cwd());
   await chmod(binPath, 0o755).catch(() => {});
@@ -196,12 +227,19 @@ export async function install(options = {}) {
   if (options.claude !== false) {
     const claude = (await readJson(claudeSettingsPath, null)) || {};
     claude.hooks = claude.hooks || {};
+    const claudeDetection = detectClaudeVersion();
+    const claudeEvents = supportedClaudeEvents(claudeDetection);
     let claudeChanged = false;
     if (options.replaceHooks && removeKitHooks(claude.hooks)) {
       claudeChanged = true;
       changed.push('claude:replaced');
     }
-    for (const eventName of CLAUDE_EVENTS) {
+    const removedUnsupported = removeUnsupportedKitClaudeHooks(claude.hooks, claudeEvents);
+    if (removedUnsupported.length > 0) {
+      claudeChanged = true;
+      changed.push(...removedUnsupported.map((eventName) => `claude:removed-unsupported:${eventName}`));
+    }
+    for (const eventName of claudeEvents) {
       const matcher = eventName === 'SessionStart' ? 'startup|resume|clear' : undefined;
       if (addHook(claude.hooks, eventName, hookCommand('claude', eventName), { matcher })) {
         claudeChanged = true;
@@ -260,8 +298,12 @@ export async function status(options = {}) {
   const claudeSettingsPath = join(homeDir(), '.claude', 'settings.json');
   const codex = await readJson(codexHooksPath, {});
   const claude = await readJson(claudeSettingsPath, {});
+  const claudeDetection = detectClaudeVersion();
+  const claudeEvents = supportedClaudeEvents(claudeDetection);
+  const claudeMissingEvents = claudeEvents.filter((eventName) => !JSON.stringify(claude.hooks?.[eventName] || []).includes(binPath));
+  const claudeUnsupportedKitEvents = unsupportedKitClaudeEvents(claude.hooks || {}, claudeEvents);
   const codexInstalled = JSON.stringify(codex.hooks || {}).includes(binPath);
-  const claudeInstalled = JSON.stringify(claude.hooks || {}).includes(binPath);
+  const claudeInstalled = claudeMissingEvents.length === 0 && claudeUnsupportedKitEvents.length === 0;
   const commandPaths = llmWikiCommandPaths();
   const commandPath = commandPaths[0] || null;
   const resolvedCommandPath = realpathOrOriginal(commandPath);
@@ -280,6 +322,11 @@ export async function status(options = {}) {
     localBin,
     codexInstalled,
     claudeInstalled,
+    claudeVersion: claudeDetection.version || 'unknown',
+    claudeModernHooks: claudeDetection.modern,
+    claudeSupportedEvents: claudeEvents,
+    claudeMissingEvents,
+    claudeUnsupportedKitEvents,
     hooksCurrent: codexInstalled && claudeInstalled,
     codexHooksPath,
     claudeSettingsPath,

package/src/legacy-omx-wiki.js

@@ -0,0 +1,222 @@
+import { mkdtemp, rm, readdir, writeFile } from 'fs/promises';
+import { spawnSync } from 'child_process';
+import { join, resolve } from 'path';
+import { tmpdir } from 'os';
+import { backupFile, exists, homeDir, readJson, readText, writeJson, writeText } from './fs-utils.js';
+
+const CODEX_CONFIG = '.codex/config.toml';
+const TOML_TABLE = /^\s*\[([^\]]+)\]\s*$/;
+
+function normalizeTomlHeader(header) {
+  return String(header || '').replace(/\s+/g, '').replace(/'/g, '"');
+}
+
+function isLegacyOmxWikiTable(header) {
+  const normalized = normalizeTomlHeader(header);
+  if (normalized === 'mcp_servers.omx_wiki') return true;
+  return normalized.includes('oh-my-codex') &&
+    normalized.includes('.mcp_servers.omx_wiki');
+}
+
+export function removeLegacyOmxWikiTomlTables(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  const output = [];
+  let changed = false;
+  let skipping = false;
+
+  for (const line of lines) {
+    const table = line.match(TOML_TABLE);
+    if (table) {
+      skipping = isLegacyOmxWikiTable(table[1]);
+      if (skipping) {
+        changed = true;
+        continue;
+      }
+    }
+    if (!skipping) output.push(line);
+  }
+
+  if (!changed) return { changed: false, text: String(text || '') };
+  return {
+    changed: true,
+    text: `${output.join('\n').replace(/\n{3,}/g, '\n\n').replace(/\s+$/g, '')}\n`,
+  };
+}
+
+function sourceRootsFromConfig(text) {
+  const roots = new Set();
+  const sourceRe = /^\s*source\s*=\s*["']([^"']*oh-my-codex[^"']*)["']\s*$/gm;
+  let match;
+  while ((match = sourceRe.exec(String(text || '')))) {
+    roots.add(match[1]);
+  }
+  return roots;
+}
+
+function configuredPackageRoots(home, configText) {
+  const roots = new Set([
+    '/usr/lib/node_modules/oh-my-codex',
+    '/usr/local/lib/node_modules/oh-my-codex',
+    join(home, '.local', 'lib', 'node_modules', 'oh-my-codex'),
+  ]);
+  for (const root of sourceRootsFromConfig(configText)) roots.add(root);
+  for (const root of String(process.env.LLM_WIKI_KIT_OMX_WIKI_ROOTS || '').split(':').filter(Boolean)) {
+    roots.add(root);
+  }
+  return roots;
+}
+
+function safeLegacyWikiSkillDir(path) {
+  const normalized = resolve(path).replace(/\\/g, '/');
+  return /(?:^|\/)oh-my-codex(?:\/|$)/.test(normalized) &&
+    /\/skills\/wiki$/.test(normalized);
+}
+
+function safeLegacyWikiMcpPath(path) {
+  const normalized = resolve(path).replace(/\\/g, '/');
+  return /(?:^|\/)oh-my-codex(?:\/|$)/.test(normalized) &&
+    /\/\.mcp\.json$/.test(normalized);
+}
+
+async function collectCachedSkillDirs(root, maxDepth = 8) {
+  const found = [];
+  async function walk(dir, depth) {
+    if (depth < 0) return;
+    let entries = [];
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const full = join(dir, entry.name);
+      const normalized = full.replace(/\\/g, '/');
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      if (entry.name === 'wiki' && normalized.includes('/oh-my-codex/') && normalized.includes('/skills/wiki')) {
+        found.push(full);
+        continue;
+      }
+      await walk(full, depth - 1);
+    }
+  }
+  await walk(root, maxDepth);
+  return found;
+}
+
+async function legacyWikiSkillDirs(home, configText) {
+  const dirs = new Set();
+  for (const root of configuredPackageRoots(home, configText)) {
+    dirs.add(join(root, 'skills', 'wiki'));
+    dirs.add(join(root, 'plugins', 'oh-my-codex', 'skills', 'wiki'));
+  }
+  for (const root of [
+    join(home, '.codex', 'plugins', 'cache'),
+    join(home, '.codex', '.tmp'),
+  ]) {
+    for (const dir of await collectCachedSkillDirs(root)) dirs.add(dir);
+  }
+  return [...dirs].filter(safeLegacyWikiSkillDir);
+}
+
+async function removeSkillDir(dir) {
+  if (!(await exists(dir))) return false;
+  try {
+    await rm(dir, { recursive: true, force: true });
+    return true;
+  } catch (error) {
+    if (!['EACCES', 'EPERM'].includes(error?.code)) throw error;
+  }
+  if (process.env.LLM_WIKI_KIT_OMX_WIKI_SUDO === '0') return false;
+  const result = spawnSync('sudo', ['-n', 'rm', '-rf', dir], {
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+  return result.status === 0 && !(await exists(dir));
+}
+
+async function removePluginMcpEntry(path) {
+  const json = await readJson(path, null);
+  if (!json?.mcpServers?.omx_wiki) return false;
+  delete json.mcpServers.omx_wiki;
+  try {
+    await writeJson(path, json);
+  } catch (error) {
+    if (!['EACCES', 'EPERM'].includes(error?.code) || !safeLegacyWikiMcpPath(path)) throw error;
+    if (process.env.LLM_WIKI_KIT_OMX_WIKI_SUDO === '0') return false;
+    const tempDir = await mkdtemp(join(tmpdir(), 'llm-wiki-kit-mcp-'));
+    const tempPath = join(tempDir, '.mcp.json');
+    await writeFile(tempPath, `${JSON.stringify(json, null, 2)}\n`, 'utf8');
+    const result = spawnSync('sudo', ['-n', 'cp', tempPath, path], {
+      encoding: 'utf8',
+      timeout: 5000,
+    });
+    await rm(tempDir, { recursive: true, force: true }).catch(() => {});
+    if (result.status !== 0) return false;
+  }
+  return true;
+}
+
+async function removeWritablePluginMcpEntries(home, configText) {
+  const changed = [];
+  const candidates = new Set();
+  for (const root of configuredPackageRoots(home, configText)) {
+    candidates.add(join(root, 'plugins', 'oh-my-codex', '.mcp.json'));
+  }
+  for (const root of [
+    join(home, '.codex', 'plugins', 'cache'),
+    join(home, '.codex', '.tmp'),
+  ]) {
+    const dirs = await collectCachedSkillDirs(root);
+    for (const dir of dirs) {
+      candidates.add(resolve(dir, '..', '..', '.mcp.json'));
+    }
+  }
+  for (const candidate of candidates) {
+    try {
+      if (await removePluginMcpEntry(candidate)) changed.push(candidate);
+    } catch {
+      // Root-owned package manifests may be read-only to the hook user. The
+      // active Codex config cleanup is the enforcement point in that case.
+    }
+  }
+  return changed;
+}
+
+export async function removeLegacyOmxWikiSurfaces(options = {}) {
+  if (process.env.LLM_WIKI_KIT_OMX_WIKI_GUARD === '0') {
+    return { changed: false, removed: [], configChanged: false };
+  }
+
+  const home = options.home || homeDir();
+  const configPath = options.configPath || join(home, CODEX_CONFIG);
+  const originalConfig = await readText(configPath, null);
+  const removed = [];
+  let configText = originalConfig || '';
+  let configChanged = false;
+
+  if (originalConfig !== null) {
+    const cleaned = removeLegacyOmxWikiTomlTables(originalConfig);
+    if (cleaned.changed) {
+      await backupFile(configPath, 'codex-config-before-omx-wiki-removal.toml');
+      await writeText(configPath, cleaned.text);
+      configText = cleaned.text;
+      configChanged = true;
+      removed.push('codex-config:omx_wiki');
+    }
+  }
+
+  for (const dir of await legacyWikiSkillDirs(home, configText)) {
+    if (await removeSkillDir(dir)) removed.push(`skill:${dir}`);
+  }
+
+  for (const path of await removeWritablePluginMcpEntries(home, configText)) {
+    removed.push(`mcp:${path}`);
+  }
+
+  return {
+    changed: removed.length > 0,
+    removed,
+    configChanged,
+  };
+}

package/src/projects.js

@@ -58,12 +58,17 @@ async function looksLikeProjectRoot(root) {
 export async function discoverProjectRoots(searchRoot, options = {}) {
   const root = resolve(searchRoot || process.cwd());
   const maxDirs = options.maxDirs || 5000;
+  const progressEvery = options.progressEvery || 1000;
+  const onProgress = typeof options.onProgress === 'function' ? options.onProgress : null;
   const roots = new Set();
   let seen = 0;
 
   async function walk(dir) {
     if (seen >= maxDirs) return;
     seen += 1;
+    if (onProgress && seen % progressEvery === 0) {
+      onProgress(`scanned ${seen}/${maxDirs} directories while discovering projects`);
+    }
 
     if (await looksLikeProjectRoot(dir)) {
       roots.add(dir);
@@ -91,6 +96,9 @@ export async function discoverProjectRoots(searchRoot, options = {}) {
   }
 
   await walk(root);
+  if (onProgress) {
+    onProgress(`project discovery scanned ${seen} director${seen === 1 ? 'y' : 'ies'}; found ${roots.size}`);
+  }
   return [...roots].sort();
 }
 

package/src/templates.js

@@ -17,7 +17,7 @@ This repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex
 - hook은 redacted raw envelope와 필요한 live Q&A를 안전하게 남긴다. \`wiki/queries\`/\`wiki/decisions\` 자동 승격은 기본값이 아니며, durable 지식은 중요도와 동의 흐름에 따라 agent가 기존 정식 wiki 문서에 합친다.
 - hook은 종료/시작 경계에서 정말 필요한 정리 후보를 \`llm-wiki/outputs/maintenance/queue.md\`에 남길 수 있다. pending 항목은 현재 응답을 지연시키지 않는 범위에서 agent가 병합하거나 done/skipped로 표시한다.
 - 새 문서를 만들기 전에 기존 wiki 문서를 먼저 찾아 갱신한다. 반복해서 쓸 사실은 \`outputs/questions/\`에만 두지 말고 적절한 wiki 문서에 합친다.
-- 일회성 작업 기록은 필요할 때 \`llm-wiki/outputs/questions/\`에 보존하고, 재사용 가능한 결론은 승인된 경우 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 반영한다.
+- 일회성 작업 기록은 필요할 때 \`llm-wiki/outputs/questions/\`에 보존하고, 재사용 가능한 사실/지식은 승인된 경우 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 반영한다.
 - 검증 명령, 근거 파일, 불확실한 점을 함께 남긴다. 추론은 추론이라고 표시하고, 모순은 지우지 말고 Open Questions 또는 Contradictions에 남긴다.
 - 인증값, token, password, private key, \`.env\` 원문은 저장하지 않는다. 필요한 경우 redacted summary만 남긴다.
 
@@ -107,7 +107,7 @@ Generated by llm-wiki-kit.
 
 - 넓은 질문은 memory와 이 index에서 시작한다.
 - 새 문서를 만들기 전에 관련 기존 문서 3-7개를 먼저 확인한다.
-- 오래 쓸 결론은 기존 정식 문서에 합치고, 일회성 기록은 outputs/questions에 둔다.
+- 오래 쓸 사실/지식은 기존 정식 문서에 합치고, 일회성 기록은 outputs/questions에 둔다.
 - 관련 페이지가 생기면 \`[[page-or-topic]]\` 링크를 추가한다.
 
 <!-- llm-wiki-kit:index-start -->
@@ -184,7 +184,7 @@ export function procedure(name) {
 5. 검증된 사실과 추론을 분리한다.
 6. 수동 확인이 필요할 때만 \`llm-wiki context "<query>"\`를 쓴다. 과거 episodic query까지 봐야 할 때는 \`--include-episodic\`을 붙인다.
 7. 일회성 답변은 durable wiki로 승격하지 않는다. 필요한 작업 turn만 \`outputs/questions/\`에 남긴다.
-8. 반복해서 쓸 결론은 중요도와 동의 흐름에 따라 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
+8. 반복해서 쓸 사실/지식은 중요도와 동의 흐름에 따라 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
 `,
     'lint.md': `# Lint Procedure
 

package/src/update-notice.js

@@ -48,10 +48,11 @@ function freshEnough(record, now = Date.now()) {
   return Number.isFinite(checkedAt) && now - checkedAt < intervalMs();
 }
 
-function cacheMatches(record, target, installedVersion) {
+function cacheMatches(record, target, installedVersion, npm) {
   return record?.schemaVersion === NOTICE_SCHEMA_VERSION &&
     record.target === target &&
-    record.installedVersion === installedVersion;
+    record.installedVersion === installedVersion &&
+    record.npmCommand === npm;
 }
 
 function trimDetail(value) {
@@ -82,9 +83,10 @@ export async function checkUpdateNotice(options = {}) {
   if (!noticeEnabled()) return null;
   const target = options.to || process.env.LLM_WIKI_KIT_UPDATE_NOTICE_TARGET || 'latest';
   const installedVersion = runtimeVersion();
+  const npm = npmCommand();
   const cachePath = noticeCachePath();
   const cached = await readJson(cachePath, null);
-  if (!options.force && cacheMatches(cached, target, installedVersion) && freshEnough(cached)) {
+  if (!options.force && cacheMatches(cached, target, installedVersion, npm) && freshEnough(cached)) {
     return cached;
   }
 
@@ -95,6 +97,7 @@ export async function checkUpdateNotice(options = {}) {
     checkedAt,
     target,
     installedVersion,
+    npmCommand: npm,
     ...registry,
   };
   await writeJson(cachePath, record).catch(() => {});
@@ -109,12 +112,12 @@ export async function updateNoticeContext(projectRoot, eventName, options = {})
   const workspace = resolve(projectRoot || process.cwd());
   const updateCommand = commandForProject('update', workspace);
   return [
-    'LLM Wiki update notice:',
-    `- Installed llm-wiki-kit: ${notice.installedVersion}`,
-    `- Latest npm release: ${notice.latestVersion}`,
-    `- A newer llm-wiki-kit release was detected automatically while the user was using the hooks.`,
-    `- Briefly tell the user an update is available and offer to run: \`${updateCommand}\``,
-    '- If the user wants every known project root updated, use the broader search root in the same command, for example `--workspace /apps`.',
-    '- Do not install automatically unless the user asks for the update.',
+    'LLM Wiki 업데이트 알림:',
+    `- 설치된 llm-wiki-kit: ${notice.installedVersion}`,
+    `- npm 최신 릴리스: ${notice.latestVersion}`,
+    '- hook 사용 중 더 새로운 llm-wiki-kit 릴리스가 자동 감지되었습니다.',
+    `- 사용자에게 업데이트 가능 사실을 짧게 알리고 다음 명령 실행을 제안하세요: \`${updateCommand}\``,
+    '- 알려진 모든 프로젝트 root를 업데이트하려면 같은 명령에서 더 넓은 search root를 사용합니다. 예: `--workspace /apps`.',
+    '- 사용자가 요청하기 전에는 자동 설치하지 마세요.',
   ].join('\n');
 }

package/src/update.js

@@ -1,4 +1,4 @@
-import { spawnSync } from 'child_process';
+import { spawn } from 'child_process';
 import { join, resolve } from 'path';
 import { exists } from './fs-utils.js';
 import { appendWikiLog } from './project.js';
@@ -7,18 +7,101 @@ import { applyProjectTemplateUpdate, inspectProjectState } from './project-state
 import { knownProjectRoots, recordProject } from './projects.js';
 import { binPath, detectInstallSource, packageName, runtimeVersion } from './version.js';
 
-function runCommand(command, args, options = {}) {
-  const result = spawnSync(command, args, {
-    encoding: 'utf8',
-    env: options.env || process.env,
-    timeout: options.timeout || 120000,
+function commandLine(command, args) {
+  return [command, ...args].join(' ');
+}
+
+function elapsedMs(startedAt) {
+  return Date.now() - startedAt;
+}
+
+function progress(options, message) {
+  if (typeof options.onProgress === 'function') options.onProgress(message);
+}
+
+async function runCommand(command, args, options = {}) {
+  const timeout = options.timeout || 120000;
+  const killGraceMs = options.killGraceMs || 2000;
+  const label = options.label || commandLine(command, args);
+  const startedAt = Date.now();
+  const detached = process.platform !== 'win32';
+  let stdout = '';
+  let stderr = '';
+  let settled = false;
+  let timedOut = false;
+  let timeoutId = null;
+  let killId = null;
+
+  progress(options, `starting ${label}`);
+
+  return new Promise((resolveResult) => {
+    let child;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutId);
+      clearTimeout(killId);
+      progress(options, `${label} finished in ${elapsedMs(startedAt)}ms`);
+      resolveResult({
+        ...result,
+        stdout,
+        stderr,
+        elapsedMs: elapsedMs(startedAt),
+        timedOut,
+      });
+    };
+    const killChild = (signal) => {
+      if (!child?.pid) return;
+      try {
+        if (detached) {
+          process.kill(-child.pid, signal);
+        } else {
+          child.kill(signal);
+        }
+      } catch {
+        // The process may have already exited.
+      }
+    };
+
+    try {
+      child = spawn(command, args, {
+        detached,
+        env: options.env || process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      finish({ status: null, signal: null, error });
+      return;
+    }
+
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', (error) => {
+      finish({ status: null, signal: null, error });
+    });
+    child.on('close', (status, signal) => {
+      const error = timedOut
+        ? Object.assign(new Error(`${label} timed out after ${timeout}ms`), { code: 'ETIMEDOUT' })
+        : null;
+      finish({ status, signal, error });
+    });
+
+    timeoutId = setTimeout(() => {
+      timedOut = true;
+      progress(options, `${label} exceeded ${timeout}ms; terminating`);
+      killChild('SIGTERM');
+      killId = setTimeout(() => {
+        progress(options, `${label} did not exit after SIGTERM; killing`);
+        killChild('SIGKILL');
+      }, killGraceMs);
+    }, timeout);
   });
-  return {
-    status: result.status,
-    stdout: result.stdout || '',
-    stderr: result.stderr || '',
-    error: result.error || null,
-  };
 }
 
 function npmCommand() {
@@ -31,7 +114,11 @@ function binCommand() {
 
 function assertCommandOk(result, label) {
   if (result.status === 0 && !result.error) return;
-  const detail = result.stderr.trim() || result.stdout.trim() || result.error?.message || 'unknown error';
+  const detail = result.stderr.trim() ||
+    result.stdout.trim() ||
+    result.error?.message ||
+    (result.signal ? `signal ${result.signal}` : '') ||
+    'unknown error';
   throw new Error(`${label} failed: ${detail}`);
 }
 
@@ -45,7 +132,13 @@ function shouldUpdateAllProjects(options = {}) {
 
 async function projectRootsForUpdate(workspace, options = {}) {
   if (!shouldUpdateAllProjects(options)) return [workspace];
-  const roots = await knownProjectRoots({ workspace });
+  progress(options, `discovering project roots under ${workspace}`);
+  const roots = await knownProjectRoots({
+    workspace,
+    maxDirs: options.maxDirs,
+    onProgress: options.onProgress,
+  });
+  progress(options, `discovered ${roots.length} project root(s)`);
   return roots.length > 0 ? roots : [workspace];
 }
 
@@ -97,7 +190,9 @@ export function compareVersions(a, b) {
 export async function checkForUpdate(options = {}) {
   const target = options.to || 'latest';
   const installedVersion = runtimeVersion();
-  const result = runCommand(npmCommand(), ['view', `${packageName()}@${target}`, 'version'], {
+  const result = await runCommand(npmCommand(), ['view', `${packageName()}@${target}`, 'version'], {
+    ...options,
+    label: 'npm view',
     timeout: options.timeout || 30000,
   });
   assertCommandOk(result, 'npm view');
@@ -120,9 +215,16 @@ export async function postUpdate(options = {}) {
   });
 
   if (options.all) {
-    const workspaces = await knownProjectRoots({ workspace });
+    progress(options, `discovering project roots under ${workspace}`);
+    const workspaces = await knownProjectRoots({
+      workspace,
+      maxDirs: options.maxDirs,
+      onProgress: options.onProgress,
+    });
+    progress(options, `post-update will inspect ${workspaces.length} project root(s)`);
     const projects = [];
     for (const projectRoot of workspaces) {
+      progress(options, `applying managed templates to ${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}`);
@@ -194,7 +296,9 @@ export async function update(options = {}) {
   const target = options.to || 'latest';
   const shouldRunNpmInstall = check.updateAvailable;
   const installResult = shouldRunNpmInstall
-    ? runCommand(npmCommand(), ['install', '-g', `${packageName()}@${target}`], {
+    ? await runCommand(npmCommand(), ['install', '-g', `${packageName()}@${target}`], {
+      ...options,
+      label: 'npm install -g',
       timeout: options.timeout || 120000,
     })
     : {
@@ -210,7 +314,13 @@ export async function update(options = {}) {
   if (options.noProject) postArgs.push('--no-project');
   if (options.codex === false) postArgs.push('--no-codex');
   if (options.claude === false) postArgs.push('--no-claude');
-  const postResult = runCommand(process.execPath, postArgs, {
+  const postResult = await runCommand(process.execPath, postArgs, {
+    ...options,
+    env: {
+      ...process.env,
+      LLM_WIKI_KIT_PROGRESS: process.env.LLM_WIKI_KIT_PROGRESS || '1',
+    },
+    label: 'post-update',
     timeout: options.timeout || 120000,
   });
   assertCommandOk(postResult, 'post-update');