llm-wiki-kit 0.2.11 → 0.2.13

package/docs/manual.md

@@ -1,36 +1,45 @@
 # llm-wiki-kit Manual
 
-`llm-wiki-kit`은 Codex와 Claude Code를 평소처럼 사용하는 동안 프로젝트 안에 living Markdown wiki를 유지하는 hook-first runtime이다.
+`llm-wiki-kit` is a hook-first runtime that keeps a project-local living Markdown wiki while users work normally in Codex or Claude Code.
 
-핵심 원칙은 단순하다. 사용자는 별도 기록 명령을 외워서 매번 실행하지 않는다. 평소처럼 질문하고, 구현하고, 검증한다. 내부적으로는 hook이 필요한 context를 주입하고, 안전하게 요약을 남기고, 오래 쓸 지식을 agent가 `llm-wiki/` Markdown에 정리할 수 있도록 돕는다.
+The core rule is answer-first operation. Users should not need to remember a separate `record`, `ingest`, or maintenance command loop. Hooks inject useful context, store redacted operational evidence, and help the active agent move durable knowledge into `llm-wiki/` when it matters.
+
+## Language Behavior
+
+The runtime supports seamless Korean/English use:
+
+- If the current user prompt is clearly Korean, hook-visible guidance is Korean.
+- If the current user prompt is clearly English, hook-visible guidance is English.
+- When there is no clear prompt language, Claude Code may use its `settings.json` `language` value when present.
+- If no setting exists, the runtime checks local `CLAUDE.md` and `AGENTS.md` language signals.
+- The fallback is English.
+- Commands, paths, code identifiers, package names, API names, logs, and original error text are kept unchanged.
+
+This is intentionally instruction-driven for both Codex and Claude Code. Claude Code may expose a language setting in some versions, but the kit does not depend on that setting being present.
 
 ## Mental Model
 
-LLM Wiki는 세 층으로 움직인다.
+The wiki has three layers:
 
 ```text
 raw evidence -> curated wiki -> rules and retrieval
 ```
 
-- `raw/`: 원본 또는 redacted 근거 저장소다. 기본 hook은 작은 redacted event envelope만 저장한다.
-- `wiki/`: agent가 관리하는 정식 지식층이다. 결정, 구조, 디버깅, 개념, 절차, 맥락을 Markdown으로 보존한다.
-- `outputs/`: live Q&A, 보고서, maintenance queue 같은 일회성 또는 작업 산출물을 둔다.
-- `AGENTS.md`, `CLAUDE.md`, `procedures/`: agent가 wiki를 다루는 규칙과 절차다.
+- `raw/`: immutable or redacted evidence. Default hooks store small redacted event envelopes, not full transcripts.
+- `wiki/`: curated project knowledge maintained by the agent.
+- `outputs/`: live Q&A chunks, reports, and maintenance candidates.
+- `AGENTS.md`, `CLAUDE.md`, and `procedures/`: instructions and operating rules for agents.
 
-채팅 history는 임시 context다. 오래 남길 지식은 repository Markdown으로 이동해야 다음 세션, 다른 agent, compact 이후에도 검색 가능하다.
+Chat history is temporary. Durable project knowledge belongs in repository Markdown so it survives new sessions, compaction, and different agents.
 
-## What Gets Created
+## Created Structure
 
-프로젝트를 bootstrap하거나 install하면 보통 다음 구조가 생긴다.
+Bootstrap or install creates:
 
 ```text
 llm-wiki/
 ├── .kit-state.json
 ├── raw/
-│   ├── inbox/
-│   ├── sessions/
-│   ├── sources/
-│   └── assets/
 ├── wiki/
 │   ├── index.md
 │   ├── memory.md
@@ -50,80 +59,55 @@ llm-wiki/
 └── procedures/
 ```
 
-`wiki/memory.md`는 hook context에 들어가는 짧은 hot index다. hook은 기능을 유지하되 사용자 화면에 보일 수 있는 부분을 functional compact context로 정제하므로, 긴 설명을 복사하지 말고 중요한 entry point만 둔다.
-
-`wiki/index.md`는 wiki 전체의 navigation map이다. agent는 넓은 질문을 받으면 여기와 `memory.md`에서 시작한다.
-
-`.kit-state.json`은 현재 project rules/templates가 어느 runtime version으로 적용되었는지 기록한다. runtime update와 project knowledge는 별개다. npm package update가 기존 wiki 내용을 덮어쓰지 않는다.
+`wiki/memory.md` is the short hot index used in hook context. `wiki/index.md` is the navigation map. `.kit-state.json` records which runtime last applied managed templates. Runtime updates do not overwrite curated project knowledge.
 
 ## Normal Use
 
-평소처럼 Codex 또는 Claude Code를 사용한다.
-
-설치된 hook은 다음 일을 자동으로 수행한다.
+Use Codex or Claude Code normally. Installed hooks:
 
-- session start, instructions loaded, prompt submit 시점에 functional compact context를 주입한다. `wiki/memory.md`, `wiki/index.md`, 관련 wiki 검색 결과, maintenance signal, update status, compact recovery packet은 계속 사용하되 사용자 화면에 보일 수 있는 hook context는 필요한 정보 중심으로 정제한다.
-- pre compact 시점에는 현재 turn을 분류하고, simple turn은 context note만 남기며, 실제 작업 evidence가 있거나 구조화된 decision 결과가 있는 turn만 redacted live Q&A checkpoint로 남긴다. 명시적 durable 기록 요청이 durable wiki에 반영되지 않았을 때만 maintenance queue 후보를 남긴다. 저장 실패 시에도 compact는 진행시키고, 중요한 내용만 recovery packet으로 준비한다.
-- prompt/tool/result summary를 redaction한 뒤 turn buffer에 기록한다.
-- 의미 있는 작업/결정 turn만 `outputs/questions/YYYY-MM-DD/live-qa-001.md` 같은 chunked live Q&A archive에 남긴다.
-- 기본 answer-first mode에서는 `wiki/queries/`와 `wiki/decisions/`를 매 turn 자동 생성하지 않는다.
-- 사용자가 명시적으로 문서화/기록을 요청했는데 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/`가 단일 활성 구현이다.
+- inject functional compact context at session start, instructions loaded, and prompt submit;
+- select Korean or English hook guidance from the current user prompt and local instruction files;
+- use `wiki/memory.md`, `wiki/index.md`, relevant wiki search, maintenance signals, update notices, and compact recovery packets;
+- record redacted prompt/tool/result summaries in per-turn state;
+- archive only meaningful work turns or structured decision/debugging turns into chunked `outputs/questions/YYYY-MM-DD/live-qa-001.md` files;
+- avoid automatic `wiki/queries/` and `wiki/decisions/` promotion in the default answer-first mode;
+- queue durable cleanup candidates only for explicit documentation requests that were not reflected in durable wiki files, or when stale turn state is recovered;
+- refresh clearly managed rules/templates for older projects at session start;
+- remove legacy Codex-facing `oh-my-codex:wiki`/`omx_wiki` surfaces when they reappear.
 
-hook UX 정책은 기능 보존이 우선이다. Codex와 Claude Code 모두 같은 기능 신호를 받으며, 차이는 raw dump가 아니라 읽기 쉬운 functional compact formatting으로 보여주는 것이다.
-
-매번 저장 여부를 사용자가 고민해야 한다면 잘못 쓰고 있는 것이다. 답변보다 wiki maintenance가 먼저 오면 안 된다. 현재 사용자 요청을 먼저 처리하고, 오래 쓸 지식만 필요한 만큼 정리한다.
+If wiki maintenance delays the actual answer, the workflow is being used wrong. The current user request comes first.
 
 ## Capture Modes
 
-기본값은 다음과 같다.
+Default:
 
 ```bash
 LLM_WIKI_KIT_CAPTURE_MODE=answer-first
 ```
 
-`answer-first` mode는 현재 답변을 우선한다.
-
-- 단순 Q&A, 상태 확인, 키워드만 포함된 답변은 durable wiki나 live Q&A archive로 승격하지 않는다.
-- tool evidence, changed-file evidence, verification, 구조화된 `Decision:`/`Root cause:` 같은 결론이 있는 turn은 live Q&A archive에 남길 수 있다.
-- explicit durable request가 durable wiki에 반영되지 않았을 때만 selective maintenance queue를 만든다.
-- reusable fact는 active agent가 기존 wiki 문서에 병합한다.
+`answer-first` keeps simple Q&A, status checks, and keyword-only replies out of durable wiki and live Q&A by default. It archives work turns with tool evidence, changed-file evidence, verification, or structured `Decision:`/`Root cause:` style conclusions. Explicit durable requests create maintenance queue candidates only when no durable wiki update is detected.
 
-과거 호환용 eager mode도 남아 있다.
+Deprecated compatibility mode:
 
 ```bash
 LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager
 ```
 
-`legacy-eager`는 old query/decision auto-promotion 흐름을 유지하기 위한 deprecated compatibility mode다. 새 project는 answer-first mode를 사용한다.
+Use `legacy-eager` only to preserve older query/decision auto-promotion behavior.
 
-## Command Reference
+## Install
 
-대부분의 사용자는 일상 작업 중 이 명령들을 직접 실행할 필요가 없다. 설치, 업데이트, 진단, agent-side maintenance용 interface다.
-
-### `llm-wiki manual`
-
-이 문서를 출력한다.
-
-```bash
-llm-wiki manual
-```
-
-새 기능이나 명령이 추가되면 `docs/manual.md`를 함께 갱신한다. 이 문서가 CLI manual의 단일 원본이다.
-
-### `llm-wiki install`
-
-Codex/Claude Code hook을 설치하고 workspace를 bootstrap한다.
+Linux/macOS:
 
 ```bash
-llm-wiki install --workspace /apps --profile standard
+npm install -g llm-wiki-kit@latest
 llm-wiki install --workspace /path/to/project --profile standard
-llm-wiki install --workspace /path/to/project --profile standard --no-project
+llm-wiki doctor --workspace /path/to/project
 ```
 
-Native Windows에서는 PowerShell/Windows Terminal에서 npm shim을 사용한다.
+Use `sudo npm install -g llm-wiki-kit@latest` only when the global npm prefix is root-owned. Run `llm-wiki install` as the user who owns the Codex/Claude settings.
+
+Native Windows:
 
 ```powershell
 npm install -g llm-wiki-kit@latest
@@ -131,409 +115,164 @@ llm-wiki install --workspace C:\path\to\project --profile standard
 llm-wiki doctor --workspace C:\path\to\project
 ```
 
-`standard` profile은 기본 profile이다.
-
-- context injection
-- redacted summary recording
-- tool call allow with storage redaction
-- project-local `llm-wiki/` bootstrap
-- hook entry merge
-
-`--no-project`는 hook/bin 설치만 하고 현재 workspace bootstrap은 하지 않을 때 사용한다.
-
-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`
-
-npm registry target과 installed runtime을 비교하고, 필요하면 global package를 업데이트한 뒤 hook과 managed project templates를 갱신한다.
-
-```bash
-llm-wiki update --check --workspace /path/to/project
-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`는 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에는 passive runtime update status가 들어간다. 이 block은 현재 runtime, npm registry target, 업데이트/정비 요청이 있을 때 쓸 수 있는 `llm-wiki update --workspace <project-or-search-root>` 명령을 짧게 보여주는 상태 정보다. 현재 답변을 중단하거나 업데이트 권유를 하라는 지시문이 아니다. cache는 lookup에 사용한 npm command별로 분리되어 test/fake npm 결과가 일반 hook session에 섞이지 않는다. `LLM_WIKI_KIT_UPDATE_NOTICE=0`으로 이 status block만 끌 수 있다.
-
-### `llm-wiki post-update`
-
-npm install 없이 현재 runtime으로 hook entries와 managed project templates를 다시 적용한다.
-
-```bash
-llm-wiki post-update --workspace /path/to/project
-llm-wiki post-update --all --workspace /path/to/search-root
-```
-
-plain `npm install -g llm-wiki-kit@latest` 후 hook/template을 다시 맞출 때 사용한다.
-
-### `llm-wiki projects`
-
-search root 아래의 project roots를 찾고 update 상태를 요약한다.
-
-```bash
-llm-wiki projects --workspace /apps
-```
-
-`llm-wiki/.kit-state.json`이 있거나 older `llm-wiki/wiki/index.md`가 있는 root를 찾는다. 출력 끝에는 전체 update, current-only update, post-update command 예시가 함께 나온다.
-
-### `llm-wiki status`
-
-offline consistency check다.
-
-```bash
-llm-wiki status --workspace /path/to/project
-llm-wiki status
-```
-
-보고 항목:
-
-- runtime version과 install source
-- binary path와 `PATH` command가 current runtime을 가리키는지
-- Codex/Claude hook이 current runtime인지
-- project applied runtime
-- managed templates current 여부
-- auto-updateable rules count
-- agent cleanup이 필요한 managed-looking rules count
-- pending maintenance count
+Windows uses npm's `llm-wiki.cmd` shim. The installer writes Codex `commandWindows` hooks and Claude Code Windows-safe `node.exe <bin>` commands. Restart Codex and Claude Code after installing or updating hooks.
 
-network를 사용하지 않는다.
-
-### `llm-wiki version`
-
-installed runtime version만 출력한다.
+Source checkout development:
 
 ```bash
-llm-wiki version
-llm-wiki --version
-llm-wiki -v
+npm install
+./install.sh --workspace /apps --profile standard
+node --test
 ```
 
-script나 smoke test에서 가장 가볍게 runtime version을 확인할 때 쓴다.
-
-### `llm-wiki doctor`
-
-설치와 hook roundtrip을 진단한다.
+Pre-publish smoke:
 
 ```bash
-llm-wiki doctor --workspace /path/to/project
+npm pack --pack-destination /tmp
+npm install -g /tmp/llm-wiki-kit-<version>.tgz
+llm-wiki install --workspace /path/to/project --profile standard
 ```
 
-확인 항목:
+## Commands
 
-- Node version
-- docs presence
-- Codex/Claude command availability
-- state directory writability
-- hook target 상태
-- sample hook roundtrip
-- status summary
+Most users should not need these during daily coding. They are for install, update, diagnostics, and agent-side maintenance.
 
-문제가 있으면 remediation hint를 출력한다.
-
-### `llm-wiki bootstrap`
-
-project-local `llm-wiki/` 구조와 root policy block을 생성한다.
-
-```bash
-llm-wiki bootstrap --workspace /path/to/project
-```
+- `llm-wiki manual`: print this manual.
+- `llm-wiki install --workspace <project> --profile standard`: install hooks and bootstrap the workspace.
+- `llm-wiki update --check --workspace <project> [--to <version-or-tag>]`: check npm without changing files.
+- `llm-wiki update --workspace <project-or-search-root>`: update the global runtime when npm has a newer target, then reapply hooks and managed templates.
+- `llm-wiki post-update --workspace <project> [--all]`: reapply hooks and managed templates without running npm install.
+- `llm-wiki projects --workspace <search-root>`: list known/discovered project roots and update commands.
+- `llm-wiki status --workspace <project>`: offline consistency report.
+- `llm-wiki version`: print the installed runtime version.
+- `llm-wiki doctor --workspace <project>`: installation and hook roundtrip diagnostics.
+- `llm-wiki bootstrap --workspace <project>`: create project-local wiki structure.
+- `llm-wiki migrate --workspace <project>`: copy legacy wiki material into the current layout.
+- `llm-wiki context "<query>" --workspace <project>`: verbose debug view of hook context sources.
+- `llm-wiki lint --workspace <project>`: wiki health check.
+- `llm-wiki consolidate --workspace <project> [--dry-run]`: refresh generated blocks in `memory.md` and `index.md`.
+- `llm-wiki maintenance --workspace <project> [--json]`: show pending durable cleanup candidates and review health.
+- `llm-wiki archive-questions --workspace <project> [--date YYYY-MM-DD] [--dry-run]`: split old flat live Q&A files into chunks.
+- `llm-wiki uninstall`: remove kit-managed hook entries, leaving project wiki contents intact.
 
-직접 bootstrap할 수 있지만 보통 `install`이 함께 처리한다. 기존 wiki content는 덮어쓰지 않는다.
+## Update Flow
 
-### `llm-wiki migrate`
+`llm-wiki update --check` contacts npm and reports an update only when the registry target is newer than the installed runtime.
 
-legacy wiki material을 current `llm-wiki/` 구조로 copy-only migration한다.
+`llm-wiki update`:
 
-```bash
-llm-wiki migrate --workspace /path/to/project
-```
+- runs `npm install -g llm-wiki-kit@<target>` only when needed;
+- skips npm install when the installed runtime already satisfies the target;
+- checks that `npm root -g` points at the active runtime package root before installing;
+- verifies that the active runtime and `post-update` runtime reached the registry target after installing;
+- exits nonzero instead of printing `updated` when `npm install -g` succeeds but the active runtime is still old;
+- reinstalls hooks without duplicating them;
+- updates only managed project templates and policy blocks;
+- preserves user-edited files and curated wiki contents;
+- prints before/after runtime, registry target, npm global root, active runtime root, and PATH command diagnostics;
+- prints progress to stderr so JSON stdout remains parseable;
+- supports `--timeout-ms` and `--max-dirs` for slow npm, WSL, or large search roots.
 
-older OMX/OMC/`omx_wiki/` material은 migration input일 뿐이다. 현재 project knowledge는 `llm-wiki-kit`과 `llm-wiki/` 아래에서 유지한다.
+Installed npm runtimes also perform a cached hook-side update notice check. It never installs automatically. It only shows passive status in hook context when a newer npm release exists and the user is already working.
 
-### `llm-wiki context`
+## Context And Search
 
-hook이 사용하는 layered context source를 full debug 형태로 수동 확인한다. Codex/Claude hook은 같은 source를 functional compact context로 정제해 주입할 수 있지만, 이 CLI는 retrieval과 formatting 문제를 점검할 수 있도록 verbose debug 출력을 유지한다.
+Hook context is compact and function-focused. The full debug form is:
 
 ```bash
 llm-wiki context "auth architecture" --workspace /path/to/project
 llm-wiki context "auth architecture" --workspace /path/to/project --json
-llm-wiki context "auth architecture" --workspace /path/to/project --limit 8
-llm-wiki context "auth architecture" --workspace /path/to/project --no-expand
+llm-wiki context "auth architecture" --workspace /path/to/project --limit 8 --no-expand
 llm-wiki context "auth architecture" --workspace /path/to/project --include-episodic
 llm-wiki context "auth architecture" --workspace /path/to/project --include-archived
 ```
 
-읽는 자료:
-
-- `wiki/memory.md`
-- `wiki/index.md`
-- recent `wiki/log.md` excerpt
-- MiniSearch 또는 substring fallback 결과
-- strong match의 one-hop wikilink neighbors
-
-기본 검색은 durable semantic/procedural page를 우선하고, episodic `wiki/queries/`, `wiki/context/`, `session-log` 계열은 숨긴다. 해당 page가 `memory_type: semantic|procedural`이고 `importance >= 4`이면 promoted durable page로 취급한다. `status: archived` 또는 `superseded_by`가 있는 page도 기본 검색에서 제외하며, 필요한 조사 때만 `--include-archived`로 복구한다. `status: stale` page는 보존하고 검색할 수 있지만 score를 낮춘다. JSON 출력에는 memory/index/hit/snippet budget metadata가 포함된다.
-
-### `llm-wiki lint`
-
-wiki health check를 수행한다. 파일을 수정하지 않는다.
-
-```bash
-llm-wiki lint --workspace /path/to/project
-```
-
-점검 항목:
+Default search prioritizes durable semantic/procedural wiki pages. Episodic `wiki/queries/`, `wiki/context/`, and `session-log` pages are hidden unless promoted with durable metadata or explicitly requested. Archived and superseded pages are hidden unless `--include-archived` is used. Stale pages remain searchable with lower score.
 
-- missing `index.md`, `memory.md`, `log.md`
-- missing/invalid frontmatter
-- broken or ambiguous `[[wikilinks]]`
-- broken relative Markdown links
-- invalid or unsafe `source_ids`
-- missing source files
-- secret-like content
-- duplicate aliases/titles
-- stale pages and orphan candidates
-- `memory.md` near-budget/oversized 상태
-- wiki page count가 search cap에 근접했는지
-- default-hidden episodic/context/session page 성장
-- stale/archived page의 supersession/link discoverability
-- outdated managed rules/templates
-- stale or oversized maintenance queue
-- oversized legacy live Q&A files or oversized live Q&A chunks
+## Maintenance
 
-broken links, invalid source IDs, secret-like content는 error이며 exit code 1을 반환한다. metadata/discoverability gap은 warning이다.
+`llm-wiki maintenance` reports pending queue state and review health. It does not merge pages automatically. The active agent should merge reusable items into existing durable pages and mark queue items `done` or `skipped`.
 
-### `llm-wiki consolidate`
+Hook reminders are soft:
 
-generated marker block만 보수적으로 갱신한다.
+- session start and instructions loaded may show a one-item summary;
+- prompt submit shows a reminder only when the prompt is wiki/maintenance-related or matches a queue topic.
 
-```bash
-llm-wiki consolidate --workspace /path/to/project
-llm-wiki consolidate --workspace /path/to/project --dry-run
-```
-
-갱신 대상:
-
-- `wiki/memory.md`의 generated memory map
-- `wiki/index.md`의 generated page map
-
-handwritten content는 보존한다. malformed marker block은 덮어쓰지 않고 건너뛴다. generated map에는 durable non-archived page만 넣는다. `stale`, `archived`, `superseded_by` page는 보존하지만 generated map에서는 제외한다. 기본 `query`, `context`, `session-log` page는 explicit durable metadata가 없으면 generated map에서 제외한다. `--dry-run` 결과는 indexed durable pages, hidden episodic pages, archived/stale/superseded skipped counts를 보고한다.
-
-### `llm-wiki maintenance`
-
-maintenance queue summary를 출력한다.
-
-```bash
-llm-wiki maintenance --workspace /path/to/project
-llm-wiki maintenance --workspace /path/to/project --json
-```
-
-이 명령은 page merge를 자동 수행하지 않는다. 정기 maintenance는 agent-side task이며 사용자가 매 turn 실행할 필요가 없다. active agent가 pending item을 읽고, 가장 가까운 durable wiki 문서에 병합한 뒤 queue item을 `done` 또는 `skipped`로 표시한다.
-
-JSON 출력에는 `reviewDue`, `reviewReasons`, `pendingCount`, `stalePendingCount`, `health`, `recommendedCommands`가 포함된다. Review due 조건은 마지막 review 후 14일 경과, pending 5개 이상, stale/result-missing pending item, lint warning/error, `memory.md` near-budget 이상, wiki page count가 search cap의 80% 이상인 경우다. Hook은 due 상태를 `SessionStart`/`InstructionsLoaded`에서만 짧게 보여주고, `UserPromptSubmit`에서는 사용자가 wiki/maintenance/정리 관련 질문을 했을 때만 보여준다. 현재 답변을 중단하거나 정리를 강제하지 않는다.
-
-### `llm-wiki archive-questions`
-
-legacy daily live Q&A 파일을 chunked archive layout으로 분할한다.
-
-```bash
-llm-wiki archive-questions --workspace /path/to/project --dry-run
-llm-wiki archive-questions --workspace /path/to/project --date 2026-06-07
-llm-wiki archive-questions --workspace /path/to/project --date 2026-06-07 --json
-```
-
-대상은 `outputs/questions/YYYY-MM-DD-live-qa.md` 형식의 기존 파일이다. 실행하면 원본은 `outputs/questions/archive/originals/` 아래에 SHA-256 sidecar와 함께 보존하고, 새 기록은 `outputs/questions/YYYY-MM-DD/index.md`와 `live-qa-001.md` style chunk들로 나눈다. 기존 top-level 파일은 새 위치를 가리키는 짧은 stub로 대체한다. `--dry-run`은 어떤 파일도 쓰지 않고 split 계획만 출력한다.
-
-Agent checklist:
-
-```bash
-llm-wiki lint --workspace /path/to/project
-llm-wiki maintenance --workspace /path/to/project
-llm-wiki consolidate --workspace /path/to/project --dry-run
-llm-wiki consolidate --workspace /path/to/project
-```
-
-### `llm-wiki uninstall`
-
-kit이 설치한 hook entries를 제거한다.
-
-```bash
-llm-wiki uninstall
-```
-
-project-local `llm-wiki/` contents는 남긴다. 지식 저장소를 삭제하는 명령이 아니다.
+## PreCompact
 
-### `llm-wiki hook`
-
-Codex/Claude Code hook target으로 쓰는 내부 runtime command다.
+Pre-compact preservation never blocks compaction. Defaults:
 
 ```bash
-llm-wiki hook codex SessionStart
-llm-wiki hook codex UserPromptSubmit
-llm-wiki hook codex Stop
-llm-wiki hook claude InstructionsLoaded
-llm-wiki hook claude Stop
+LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=limited
 ```
 
-일반 사용자가 직접 호출할 필요는 거의 없다. hook integration이나 smoke test를 디버깅할 때만 사용한다.
-
-## Hook Events
-
-Codex handled events:
-
-- `SessionStart`
-- `UserPromptSubmit`
-- `PreToolUse`
-- `PostToolUse`
-- `PreCompact`
-- `PostCompact`
-- `SubagentStop`
-- `Stop`
-
-Claude Code handled events:
-
-- `SessionStart`
-- `InstructionsLoaded`
-- `UserPromptSubmit`
-- `PreToolUse`
-- `PostToolUse`
-- `PostToolBatch`
-- `PreCompact`
-- `PostCompact`
-- `SubagentStop`
-- `Stop`
-- `SessionEnd`
-
-Hook payload는 full transcript가 아니라 작은 redacted event envelope다. context output도 field별 redaction을 거친다. `PreCompact`는 checkpoint 생성을 위해 작은 bounded transcript tail만 읽을 수 있고, 저장 전 인증값과 raw `transcript_path`를 redaction한다.
-
-Context를 반환하는 Codex/Claude hook event는 기능을 제거하지 않는다. memory hot index, navigation index, relevant wiki hits, link expansion, maintenance signal, passive runtime update status, compact recovery packet을 계속 사용할 수 있고, 사용자 화면에 보일 수 있는 `additionalContext`만 functional compact context로 정제한다. `PostCompact`는 compact summary 저장과 recovery packet 준비만 수행하고 model-visible context를 직접 반환하지 않는다. `llm-wiki context` CLI의 full debug 출력은 이 hook formatting 정책과 별도로 유지한다.
-
-Pre-compact 보존은 compact를 block하지 않는다. `LLM_WIKI_KIT_PRECOMPACT_ENFORCEMENT=off`는 실패 warning을 억제하고, `limited`/`soft`는 checkpoint/queue 저장 실패 시 non-blocking warning만 남긴다. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES`로 transcript tail byte 한도를 조정한다.
-
-## Security Defaults
-
-기본 정책은 aggressive blocking보다 useful local work wiki를 우선한다.
-
-- input이 민감해 보인다는 이유만으로 tool call을 막지 않는다.
-- token, password, bearer credential, private key, `.env` 원문 같은 authentication value는 durable summary에 쓰기 전 redaction한다.
-- phone number, email, date, business identifier는 local work context로 유용할 수 있어 기본 보존한다.
-- full raw transcript capture는 기본 기능이 아니다.
-- `PreCompact` checkpoint는 bounded redacted transcript tail만 사용할 수 있으며 full transcript와 raw `transcript_path`는 저장하지 않는다.
-- `llm-wiki lint`는 wiki 안의 secret-like content를 error로 보고한다.
+`limited` and `soft` emit non-blocking warnings on checkpoint failure. `off` suppresses warnings. `LLM_WIKI_KIT_PRECOMPACT_TRANSCRIPT_TAIL_BYTES` controls the small bounded transcript tail used for redacted checkpoints.
 
-민감한 raw command output, log, screenshot, transcript를 저장해야 할 때는 먼저 redaction한다. 인증값은 wiki, report, live Q&A, command history에 남기지 않는다.
+## Security
 
-## Updating Existing Installs
+- Full raw transcript capture is disabled by default.
+- Hook payloads are stored as small redacted event envelopes.
+- Tool calls are not blocked only because input looks sensitive.
+- Tokens, passwords, bearer credentials, private keys, and raw `.env` contents are redacted before durable storage.
+- Phone numbers, emails, dates, and business identifiers are preserved by default because they can be useful local work context.
+- `llm-wiki lint` reports secret-like wiki content as an error.
 
-일반 흐름:
+## Release Verification
 
-```bash
-npm install -g llm-wiki-kit@latest --registry=https://registry.npmjs.org/ --prefer-online
-llm-wiki post-update --all --workspace /apps
-llm-wiki status --workspace /apps
-llm-wiki doctor --workspace /apps
-```
-
-system global npm prefix가 root-owned인 서버에서는 package install에 `sudo npm install -g`가 필요할 수 있다. 단, user home의 Codex/Claude hook 설정을 갱신하는 `llm-wiki install` 또는 `llm-wiki post-update`는 해당 user로 실행하는 것이 일반적으로 맞다.
-
-source checkout 개발 중 pre-publish smoke:
-
-```bash
-npm pack --pack-destination /tmp
-npm install -g /tmp/llm-wiki-kit-<version>.tgz
-llm-wiki install --workspace /apps --profile standard
-```
-
-publish 전 검증:
+For `llm-wiki-kit` releases, source tests are not enough. A complete release includes:
 
 ```bash
 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
+git diff --check
+npm publish
+npm view llm-wiki-kit version dist-tags
+sudo npm install -g llm-wiki-kit@latest
 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 status --workspace /path/to/project
+llm-wiki doctor --workspace /path/to/project
+llm-wiki update --check --workspace /path/to/project
 ```
 
-`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`를 실행한다.
+Native Windows support claims require a real Windows smoke: install the published package, run `install`, `status`, and `doctor` against a Windows project, inspect `%USERPROFILE%\.codex\hooks.json` and `%USERPROFILE%\.claude\settings.json`, and run hook smoke tests through `llm-wiki.cmd`.
 
-Windows 지원 변경이 포함된 릴리스는 publish 후에도 같은 Windows host에서 `npm install -g llm-wiki-kit@latest` 후 최소 `version/status/doctor` smoke를 반복한다.
+## Troubleshooting
 
-## Troubleshooting Shortcuts
-
-hook이 안 돈다면:
+If hooks do not run:
 
 ```bash
-llm-wiki status --workspace /path/to/project
 llm-wiki doctor --workspace /path/to/project
+llm-wiki status --workspace /path/to/project
+llm-wiki install --workspace /path/to/project --profile standard
 ```
 
-`npm install -g` 후에도 old command가 실행된다면:
+If npm install succeeds but `llm-wiki` is old:
 
 ```bash
 which -a llm-wiki
 readlink -f "$(command -v 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
+llm-wiki install --workspace /path/to/project --profile standard
+hash -r
 ```
 
-Windows에서는 `where llm-wiki`와 npm prefix를 먼저 확인한다.
+On Windows:
 
 ```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
-```
-
-local shim이 npm global command를 shadowing하면:
-
-```bash
-llm-wiki install --workspace /path/to/project --profile standard
-hash -r
-llm-wiki version
+llm-wiki install --workspace C:\path\to\project --profile standard
+llm-wiki doctor --workspace C:\path\to\project
 ```
 
-wiki page가 중복되거나 오래된 것 같다면:
+If `update` appears slow, use bounded dry runs:
 
 ```bash
-llm-wiki lint --workspace /path/to/project
-llm-wiki maintenance --workspace /path/to/project
-llm-wiki consolidate --workspace /path/to/project
+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
 ```
 
-## Manual Maintenance Rule
-
-이 문서는 `llm-wiki manual`의 출력 원본이다.
-
-새 public command, option, hook behavior, directory convention, security policy, update flow가 생기면 구현과 같은 change set에서 `docs/manual.md`를 갱신한다. README는 빠른 시작과 요약을 담고, 자세한 기능 설명은 이 manual에 둔다.
+This file is the source for `llm-wiki manual`. Update it in the same change set as public command, option, hook behavior, directory convention, security policy, language behavior, or update-flow changes.