llm-wiki-kit 0.1.14 → 0.2.1

package/README.md

@@ -73,18 +73,18 @@ 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
-- record redacted turn summaries
+- 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
-- update `llm-wiki/outputs/questions/YYYY-MM-DD-live-qa.md`
-- capture reusable-answer candidates into `llm-wiki/wiki/queries/`
-- promote decision-like turns into `llm-wiki/wiki/decisions/`
-- queue durable cleanup candidates in `llm-wiki/outputs/maintenance/queue.md` at stop/session-end time
+- update `llm-wiki/outputs/questions/YYYY-MM-DD-live-qa.md` only for meaningful work turns
+- 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
 - recover stale per-turn state into that queue on the next session start or prompt submit when the previous stop hook did not complete
-- nudge the active LLM to fold reusable facts into existing wiki pages instead of leaving everything as one-off Q&A
+- nudge the active LLM to fold approved reusable facts into existing wiki pages instead of leaving everything as one-off Q&A
 - automatically refresh managed rules/templates for older projects when the current runtime starts a session
 
 If you need to think about saving every answer manually, the setup has failed.
+If wiki maintenance delays the actual answer, the setup is being used wrong. The default capture mode is `LLM_WIKI_KIT_CAPTURE_MODE=answer-first`; the old eager query/decision capture path remains only as deprecated compatibility mode via `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager`.
 
 ## Operational Commands
 
@@ -92,9 +92,12 @@ Most users should not need these during daily Claude Code/Codex work. They exist
 
 - Install/update: `llm-wiki install`, `llm-wiki update`, `llm-wiki post-update`, `llm-wiki projects`
 - Diagnostics: `llm-wiki doctor`, `llm-wiki status`, `llm-wiki version`
+- Manual: `llm-wiki manual`
 - Agent maintenance helpers: `llm-wiki context`, `llm-wiki lint`, `llm-wiki consolidate`, `llm-wiki maintenance`
 - Cleanup: `llm-wiki uninstall`
 
+`llm-wiki manual` prints the full package manual from `docs/manual.md`. Keep that document current when adding public commands, options, hook behavior, directory conventions, security policy, or update flows.
+
 `llm-wiki status` is an offline consistency check. It reports the installed runtime version, hook targets, whether the `llm-wiki` command on `PATH` resolves to the current runtime, whether the current workspace has the current managed templates applied, how many rules are auto-updateable, how many managed-looking rules need agent cleanup, and how many wiki maintenance items are pending.
 
 `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.
@@ -103,13 +106,13 @@ Most users should not need these during daily Claude Code/Codex work. They exist
 
 `llm-wiki post-update --workspace <project>` reapplies the current runtime's hook entries and safe managed template updates without running `npm install -g`. Use `post-update --all --workspace <search-root>` to reapply templates across discovered project roots.
 
-`llm-wiki context "<query>"` prints the same layered context used by hooks. It is mainly for debugging what Codex/Claude Code will see; daily use should rely on hook injection.
+`llm-wiki context "<query>"` prints the same layered context used by hooks. It is mainly for debugging what Codex/Claude Code will see; daily use should rely on hook injection. By default, episodic `wiki/queries/` pages are excluded from search unless they were promoted with `memory_type: semantic` or `procedural` and `importance >= 4`; use `--include-episodic` only when debugging old automatic query records.
 
 `llm-wiki lint` checks wiki health and detects outdated managed rules from older kit versions. Agents may use it before/after meaningful wiki maintenance.
 
 `llm-wiki consolidate` refreshes only generated marker blocks in `wiki/memory.md` and `wiki/index.md`. It is an agent maintenance helper, not a command users should run after every turn.
 
-`llm-wiki maintenance` prints the pending queue from `llm-wiki/outputs/maintenance/queue.md`. Hooks create candidates; the active agent should merge reusable items into existing durable wiki pages and mark queue items `done` or `skipped`.
+`llm-wiki maintenance` prints the pending queue from `llm-wiki/outputs/maintenance/queue.md`. Hooks create only selective candidates; the active agent should merge reusable items into existing durable wiki pages and mark queue items `done` or `skipped` without delaying unrelated user answers.
 
 `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`.
 

package/docs/concepts.md

@@ -15,13 +15,14 @@ raw sources -> wiki -> schema/rules
 The important behavior is a loop:
 
 1. A Claude Code or Codex session starts.
-2. `memory.md`, `index.md`, and relevant wiki context are injected automatically.
+2. `memory.md`, `index.md`, and relevant wiki context are injected automatically with an answer-first instruction.
 3. The user works normally; no extra command loop is required.
 4. Hooks gather redacted prompt/tool/result summaries.
-5. At stop/session end, hooks append redacted live Q&A and create query or decision candidates when the turn has enough captured context.
-6. At stop/session-end or the next start/prompt after an abrupt shutdown, hooks queue durable cleanup candidates in `outputs/maintenance/queue.md`.
-7. When reusable knowledge appears, the active Claude Code/Codex agent folds it into existing durable wiki pages instead of leaving everything as one-off Q&A.
-8. Future sessions start from the improved wiki instead of relying on long chat history.
+5. At stop/session end, hooks append redacted live Q&A only for meaningful work turns.
+6. Durable wiki promotion is selective: explicit record/document requests should be handled by the active agent in existing wiki pages; the hook queues review only when such a request was not reflected in durable files.
+7. At the next start/prompt after an abrupt shutdown, hooks can recover stale turn state into `outputs/maintenance/queue.md`.
+8. When reusable knowledge appears, the active Claude Code/Codex agent folds approved facts into existing durable wiki pages instead of leaving everything as one-off Q&A.
+9. Future sessions start from the improved wiki instead of relying on long chat history.
 
 The kit is a template/runtime repository. It must not centralize project wiki contents.
 
@@ -38,7 +39,7 @@ The maintenance loop is intentionally layered:
 
 - `memory.md`: short hot index for current durable facts.
 - `index.md`: broad navigation map.
-- MiniSearch + wikilinks: retrieval over the rest of `wiki/**/*.md`, with substring fallback when MiniSearch is not installed in a source checkout.
-- `outputs/maintenance/queue.md`: pending reminders for turns that need durable wiki review.
+- MiniSearch + wikilinks: retrieval over durable `wiki/**/*.md`, with episodic `wiki/queries/` hidden by default unless `--include-episodic` is requested.
+- `outputs/maintenance/queue.md`: selective reminders for explicit durable requests that need review, plus stale turn recovery.
 - `lint`: finds broken links, stale pages, duplicates, metadata gaps, secret-like content, and outdated managed rules.
 - `consolidate`: agent helper that refreshes generated blocks in `memory.md` and `index.md` while preserving handwritten notes and keeping default query/context/session pages out of the durable generated maps.

package/docs/integrations/claude-code.md

@@ -40,11 +40,12 @@ 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`, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, pending queue items, 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, and injects the smallest useful context set plus pending queue reminders.
+At `SessionStart`/`InstructionsLoaded`, the hook first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, a one-item maintenance summary when needed, 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, and injects the smallest useful context set. 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. `SubagentStop`, `Stop`, and `SessionEnd` append live Q&A and create `wiki/queries/` candidates when a captured question exists. A `wiki/decisions/` page is created only when the captured turn looks decision-like. `Stop` and `SessionEnd` also queue pending maintenance items for durable wiki review, then clear the per-session turn buffer after recording; `SubagentStop` does not.
+`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.
 
 Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
+Set `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` only as deprecated compatibility mode for the old eager query/decision capture behavior.
 
 After installation or update, run:
 

package/docs/integrations/codex.md

@@ -29,17 +29,19 @@ Handled events:
 
 Expected behavior:
 
-- `SessionStart` first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, pending queue items, 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, and injects the smallest useful context set plus pending queue reminders.
+- `SessionStart` first attempts a safe managed-template refresh, recovers stale turn state into `outputs/maintenance/queue.md`, then injects `llm-wiki/wiki/memory.md`, `llm-wiki/wiki/index.md`, recent log context, operating rules, a one-item maintenance summary when needed, 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, and injects the smallest useful context set. 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.
-- `SubagentStop` and `Stop` append live Q&A and create `wiki/queries/` candidates when a captured question exists. A `wiki/decisions/` page is created only when the captured turn looks decision-like. `Stop` also queues a pending maintenance item for durable wiki review.
+- In the default `answer-first` mode, `SubagentStop` does not create live Q&A, query, decision, or maintenance files. `Stop` appends live Q&A only for meaningful work turns and does 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` queues a pending maintenance item for agent review.
 - `Stop` clears the per-session turn buffer after recording. `SubagentStop` leaves the parent turn buffer available for the final stop event.
 
 Hook payloads are stored as small redacted event envelopes rather than full transcripts. Context output is also redacted field by field before it is returned to Codex.
 
 Set `LLM_WIKI_KIT_AUTO_PROJECT_UPDATE=0` only while diagnosing automatic managed-template refresh behavior.
+Set `LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` only as deprecated compatibility mode for the old eager query/decision capture behavior.
 
 Run these after install:
 

package/docs/manual.md

@@ -0,0 +1,461 @@
+# llm-wiki-kit Manual
+
+`llm-wiki-kit`은 Codex와 Claude Code를 평소처럼 사용하는 동안 프로젝트 안에 living Markdown wiki를 유지하는 hook-first runtime이다.
+
+핵심 원칙은 단순하다. 사용자는 별도 기록 명령을 외워서 매번 실행하지 않는다. 평소처럼 질문하고, 구현하고, 검증한다. 내부적으로는 hook이 필요한 context를 주입하고, 안전하게 요약을 남기고, 오래 쓸 지식을 agent가 `llm-wiki/` Markdown에 정리할 수 있도록 돕는다.
+
+## Mental Model
+
+LLM Wiki는 세 층으로 움직인다.
+
+```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를 다루는 규칙과 절차다.
+
+채팅 history는 임시 context다. 오래 남길 지식은 repository Markdown으로 이동해야 다음 세션, 다른 agent, compact 이후에도 검색 가능하다.
+
+## What Gets Created
+
+프로젝트를 bootstrap하거나 install하면 보통 다음 구조가 생긴다.
+
+```text
+llm-wiki/
+├── .kit-state.json
+├── raw/
+│   ├── inbox/
+│   ├── sessions/
+│   ├── sources/
+│   └── assets/
+├── wiki/
+│   ├── index.md
+│   ├── memory.md
+│   ├── log.md
+│   ├── sources/
+│   ├── concepts/
+│   ├── entities/
+│   ├── decisions/
+│   ├── architecture/
+│   ├── debugging/
+│   ├── context/
+│   └── queries/
+├── outputs/
+│   ├── questions/
+│   ├── reports/
+│   └── maintenance/
+└── procedures/
+```
+
+`wiki/memory.md`는 hook context에 들어가는 짧은 hot index다. 긴 설명을 복사하지 말고 중요한 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 내용을 덮어쓰지 않는다.
+
+## Normal Use
+
+평소처럼 Codex 또는 Claude Code를 사용한다.
+
+설치된 hook은 다음 일을 자동으로 수행한다.
+
+- session start, prompt submit, post compact 시점에 `wiki/memory.md`, `wiki/index.md`, 관련 wiki 검색 결과를 context로 주입한다.
+- prompt/tool/result summary를 redaction한 뒤 turn buffer에 기록한다.
+- 의미 있는 작업 turn만 `outputs/questions/YYYY-MM-DD-live-qa.md`에 live Q&A로 남긴다.
+- 기본 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한다.
+
+매번 저장 여부를 사용자가 고민해야 한다면 잘못 쓰고 있는 것이다. 답변보다 wiki maintenance가 먼저 오면 안 된다. 현재 사용자 요청을 먼저 처리하고, 오래 쓸 지식만 필요한 만큼 정리한다.
+
+## Capture Modes
+
+기본값은 다음과 같다.
+
+```bash
+LLM_WIKI_KIT_CAPTURE_MODE=answer-first
+```
+
+`answer-first` mode는 현재 답변을 우선한다.
+
+- 단순 Q&A나 상태 확인은 durable wiki로 승격하지 않는다.
+- 의미 있는 작업 turn은 live Q&A archive에 남길 수 있다.
+- explicit durable request가 빠졌을 때만 selective maintenance queue를 만든다.
+- reusable fact는 active agent가 기존 wiki 문서에 병합한다.
+
+과거 호환용 eager mode도 남아 있다.
+
+```bash
+LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager
+```
+
+`legacy-eager`는 old query/decision auto-promotion 흐름을 유지하기 위한 deprecated compatibility mode다. 새 project는 answer-first mode를 사용한다.
+
+## Command Reference
+
+대부분의 사용자는 일상 작업 중 이 명령들을 직접 실행할 필요가 없다. 설치, 업데이트, 진단, 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한다.
+
+```bash
+llm-wiki install --workspace /apps --profile standard
+llm-wiki install --workspace /path/to/project --profile standard
+llm-wiki install --workspace /path/to/project --profile standard --no-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로 실행한다.
+
+### `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
+```
+
+`--check`는 network를 사용하지만 파일을 변경하지 않는다. installed version보다 registry target이 최신일 때만 update available을 보고한다.
+
+기본 `update --workspace <search-root>`는 runtime update를 한 번 수행한 뒤, known/discovered project roots의 managed templates를 재적용한다. 기존 wiki contents는 덮어쓰지 않는다.
+
+`update`는 source checkout에서 self-update하지 않는다. source checkout 개발 중에는 npm package나 local tarball로 global install한 뒤 update behavior를 테스트한다.
+
+### `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
+
+network를 사용하지 않는다.
+
+### `llm-wiki version`
+
+installed runtime version만 출력한다.
+
+```bash
+llm-wiki version
+llm-wiki --version
+llm-wiki -v
+```
+
+script나 smoke test에서 가장 가볍게 runtime version을 확인할 때 쓴다.
+
+### `llm-wiki doctor`
+
+설치와 hook roundtrip을 진단한다.
+
+```bash
+llm-wiki doctor --workspace /path/to/project
+```
+
+확인 항목:
+
+- Node version
+- docs presence
+- Codex/Claude command availability
+- state directory writability
+- hook target 상태
+- sample hook roundtrip
+- status summary
+
+문제가 있으면 remediation hint를 출력한다.
+
+### `llm-wiki bootstrap`
+
+project-local `llm-wiki/` 구조와 root policy block을 생성한다.
+
+```bash
+llm-wiki bootstrap --workspace /path/to/project
+```
+
+직접 bootstrap할 수 있지만 보통 `install`이 함께 처리한다. 기존 wiki content는 덮어쓰지 않는다.
+
+### `llm-wiki migrate`
+
+legacy wiki material을 current `llm-wiki/` 구조로 copy-only migration한다.
+
+```bash
+llm-wiki migrate --workspace /path/to/project
+```
+
+older OMX/OMC/`omx_wiki/` material은 migration input일 뿐이다. 현재 project knowledge는 `llm-wiki-kit`과 `llm-wiki/` 아래에서 유지한다.
+
+### `llm-wiki context`
+
+hook이 주입하는 layered context를 수동으로 확인한다.
+
+```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 --include-episodic
+```
+
+읽는 자료:
+
+- `wiki/memory.md`
+- `wiki/index.md`
+- recent `wiki/log.md` excerpt
+- MiniSearch 또는 substring fallback 결과
+- strong match의 one-hop wikilink neighbors
+
+기본 검색은 episodic `wiki/queries/`를 제외한다. 오래된 automatic query record까지 보고 싶을 때만 `--include-episodic`을 쓴다.
+
+### `llm-wiki lint`
+
+wiki health check를 수행한다. 파일을 수정하지 않는다.
+
+```bash
+llm-wiki lint --workspace /path/to/project
+```
+
+점검 항목:
+
+- 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
+- outdated managed rules/templates
+- stale or oversized maintenance queue
+
+broken links, invalid source IDs, secret-like content는 error이며 exit code 1을 반환한다. metadata/discoverability gap은 warning이다.
+
+### `llm-wiki consolidate`
+
+generated marker block만 보수적으로 갱신한다.
+
+```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은 덮어쓰지 않고 건너뛴다. 기본 `query`, `context`, `session-log` page는 explicit durable metadata가 없으면 generated map에서 제외한다.
+
+### `llm-wiki maintenance`
+
+maintenance queue summary를 출력한다.
+
+```bash
+llm-wiki maintenance --workspace /path/to/project
+llm-wiki maintenance --workspace /path/to/project --json
+```
+
+이 명령은 page merge를 자동 수행하지 않는다. active agent가 pending item을 읽고, 가장 가까운 durable wiki 문서에 병합한 뒤 queue item을 `done` 또는 `skipped`로 표시한다.
+
+### `llm-wiki uninstall`
+
+kit이 설치한 hook entries를 제거한다.
+
+```bash
+llm-wiki uninstall
+```
+
+project-local `llm-wiki/` contents는 남긴다. 지식 저장소를 삭제하는 명령이 아니다.
+
+### `llm-wiki hook`
+
+Codex/Claude Code hook target으로 쓰는 내부 runtime command다.
+
+```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
+```
+
+일반 사용자가 직접 호출할 필요는 거의 없다. 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을 거친다.
+
+## 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는 기본 기능이 아니다.
+- `llm-wiki lint`는 wiki 안의 secret-like content를 error로 보고한다.
+
+민감한 raw command output, log, screenshot, transcript를 저장해야 할 때는 먼저 redaction한다. 인증값은 wiki, report, live Q&A, command history에 남기지 않는다.
+
+## Updating Existing Installs
+
+일반 흐름:
+
+```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 전 검증:
+
+```bash
+node --test
+npm pack --dry-run
+```
+
+publish 후 검증:
+
+```bash
+npm view llm-wiki-kit version --registry=https://registry.npmjs.org/
+llm-wiki version
+llm-wiki manual
+llm-wiki status --workspace /apps
+llm-wiki doctor --workspace /apps
+```
+
+## Troubleshooting Shortcuts
+
+hook이 안 돈다면:
+
+```bash
+llm-wiki status --workspace /path/to/project
+llm-wiki doctor --workspace /path/to/project
+```
+
+`npm install -g` 후에도 old command가 실행된다면:
+
+```bash
+which -a llm-wiki
+readlink -f "$(command -v llm-wiki)"
+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
+```
+
+wiki page가 중복되거나 오래된 것 같다면:
+
+```bash
+llm-wiki lint --workspace /path/to/project
+llm-wiki maintenance --workspace /path/to/project
+llm-wiki consolidate --workspace /path/to/project
+```
+
+## Manual Maintenance Rule
+
+이 문서는 `llm-wiki manual`의 출력 원본이다.
+
+새 public command, option, hook behavior, directory convention, security policy, update flow가 생기면 구현과 같은 change set에서 `docs/manual.md`를 갱신한다. README는 빠른 시작과 요약을 담고, 자세한 기능 설명은 이 manual에 둔다.

package/docs/operations.md

@@ -120,24 +120,29 @@ After a plain `npm install -g llm-wiki-kit@latest`, existing hooks keep working
 
 ## Context And Wiki Maintenance
 
-Daily use should be Claude Code/Codex first. The user should not need to run a chain of `llm-wiki` commands while working. Hooks inject the context automatically, and the active agent is expected to update durable wiki pages when reusable project knowledge appears.
+Daily use should be Claude Code/Codex first. The user should not need to run a chain of `llm-wiki` commands while working. Hooks inject context automatically, but the current user answer takes priority over wiki cleanup. The active agent updates durable wiki pages when reusable project knowledge appears and the turn's importance or user consent justifies persistence.
 
-`Stop` and `SessionEnd` write pending cleanup candidates to `llm-wiki/outputs/maintenance/queue.md` after live Q&A/query/decision capture. `SessionStart` and `UserPromptSubmit` also recover stale per-turn state into the same queue when the previous stop hook did not complete, then inject up to five pending items into context. This is a recovery and reminder layer, not a full transcript capture path.
+In the default `LLM_WIKI_KIT_CAPTURE_MODE=answer-first` mode, `Stop` and `SessionEnd` append live Q&A only for meaningful work turns. They do not auto-create `wiki/queries/` or `wiki/decisions/`. If the user explicitly asked for recording/documentation and no durable wiki update is detected, a pending cleanup candidate is written to `llm-wiki/outputs/maintenance/queue.md`. `SessionStart` and `UserPromptSubmit` also recover stale per-turn state into the same queue when the previous stop hook did not complete. `SessionStart` injects a one-item queue summary; `UserPromptSubmit` injects a soft reminder only when the prompt is wiki/maintenance related or matches a queue topic. This is a recovery and reminder layer, not a full transcript capture path.
+
+`LLM_WIKI_KIT_CAPTURE_MODE=legacy-eager` keeps the old eager live Q&A/query/decision/maintenance behavior for compatibility only. New projects should rely on the answer-first default.
 
 `llm-wiki context "<query>"` is the manual debug form of hook context injection. It reads:
 
 - `llm-wiki/wiki/memory.md` as the short hot index
 - `llm-wiki/wiki/index.md` as the navigation map
-- MiniSearch results from `llm-wiki/wiki/**/*.md`, with substring fallback when MiniSearch is unavailable
+- MiniSearch results from durable `llm-wiki/wiki/**/*.md`, with substring fallback when MiniSearch is unavailable
 - one-hop wikilink neighbors for the strongest matches
 - redacted output fields for query text, memory/index/log excerpts, hit paths, titles, snippets, matched terms, and link expansion metadata
 
+Default context search excludes episodic `wiki/queries/` pages unless they were explicitly promoted with `memory_type: semantic` or `procedural` and `importance >= 4`. Use `--include-episodic` only when debugging historical automatic query pages:
+
 Use it only when you want to inspect what the next agent turn should see:
 
 ```bash
 llm-wiki context "auth architecture" --workspace /path/to/project
 llm-wiki context "auth architecture" --workspace /path/to/project --json
 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 lint` checks Markdown wiki health without modifying files:

package/docs/troubleshooting.md

@@ -179,7 +179,7 @@ Check:
 
 ## Maintenance Queue Is Empty Or Stale
 
-`llm-wiki/outputs/maintenance/queue.md` is created only after a captured `Stop`/`SessionEnd` turn, or when `SessionStart`/`UserPromptSubmit` recovers stale per-turn state from a session that did not stop cleanly.
+In the default answer-first mode, `llm-wiki/outputs/maintenance/queue.md` is created only when a user explicitly asked for durable recording/documentation but no durable wiki update was detected, or when `SessionStart`/`UserPromptSubmit` recovers stale per-turn state from a session that did not stop cleanly. It is not expected to grow after every normal `Stop`.
 
 Check the queue and health warnings:
 
@@ -188,7 +188,7 @@ llm-wiki maintenance --workspace /path/to/project
 llm-wiki lint --workspace /path/to/project
 ```
 
-If the queue is always empty, confirm hooks run and that the turn had a captured `UserPromptSubmit`. If pending items stay around, the active agent should merge reusable content into existing durable wiki pages and mark each queue item `done` or `skipped`.
+If the queue is always empty during ordinary Q&A, that is normal. If you expected an explicit documentation request to queue, confirm hooks run and that the turn had a captured `UserPromptSubmit`. If pending items stay around, the active agent should merge reusable content into existing durable wiki pages and mark each item `done` or `skipped` without delaying unrelated answers.
 
 ## Authentication Values Were Redacted
 

package/package.json

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

package/src/capture-policy.js

@@ -0,0 +1,163 @@
+const NOT_CAPTURED = '(not captured)';
+
+const EXPLICIT_DURABLE_RE = /(?:기록해|기록해줘|문서화|문서화해|wiki에\s*남겨|위키에\s*남겨|wiki[^.\n]{0,40}(?:남겨|저장|기록)|위키[^.\n]{0,40}(?:남겨|저장|기록)|remember\s+this|save\s+this|document\s+this|record\s+this|persist\s+this)/i;
+
+const DURABLE_KEYWORD_RE = /(?:debug|bug|fix|failure|failed|error|root cause|architecture|runtime|hook|install|update|deploy|release|publish|migration|security|policy|procedure|decision|decided|verification|test|lint|build|doctor|디버깅|버그|오류|에러|실패|수정|원인|아키텍처|구조|런타임|훅|설치|업데이트|배포|릴리스|마이그레이션|보안|정책|절차|결정|선택|채택|확정|검증|테스트|문서|위키|wiki)/i;
+
+const MAINTENANCE_QUERY_RE = /(?:llm-wiki|wiki|위키|maintenance|maintain|문서|문서화|기록|정리|consolidate|lint|queue|AGENTS\.md)/i;
+
+export function captureMode(env = process.env) {
+  return env.LLM_WIKI_KIT_CAPTURE_MODE === 'legacy-eager' ? 'legacy-eager' : 'answer-first';
+}
+
+export function isLegacyEagerCaptureMode(env = process.env) {
+  return captureMode(env) === 'legacy-eager';
+}
+
+export function capturedText(value) {
+  const text = String(value || '').trim();
+  if (!text || text === NOT_CAPTURED) return '';
+  return text;
+}
+
+export function hasCapturedQuestion(entry) {
+  return capturedText(entry?.question).length >= 8;
+}
+
+export function entrySearchText(entry) {
+  return [
+    entry?.question,
+    entry?.result,
+    entry?.work,
+    entry?.changedFiles,
+    entry?.verification,
+  ].map(capturedText).filter(Boolean).join('\n');
+}
+
+export function explicitDurableRequested(value) {
+  const text = typeof value === 'string' ? value : entrySearchText(value);
+  return EXPLICIT_DURABLE_RE.test(text);
+}
+
+export function hasDurableKeyword(value) {
+  const text = typeof value === 'string' ? value : entrySearchText(value);
+  return DURABLE_KEYWORD_RE.test(text);
+}
+
+export function isMaintenanceRelatedQuery(query, pendingItems = []) {
+  const text = capturedText(query);
+  if (!text) return false;
+  if (MAINTENANCE_QUERY_RE.test(text)) return true;
+  const terms = text
+    .normalize('NFC')
+    .toLowerCase()
+    .replace(/[^\p{Letter}\p{Number}]+/gu, ' ')
+    .split(/\s+/)
+    .filter((term) => term.length >= 3);
+  if (terms.length === 0) return false;
+  return pendingItems.some((item) => {
+    const topic = `${item.topic || ''} ${item.source || ''}`.normalize('NFC').toLowerCase();
+    return terms.some((term) => topic.includes(term));
+  });
+}
+
+export function hasDetectedDurableWikiChange(entry) {
+  const text = [
+    entry?.changedFiles,
+    entry?.work,
+  ].map(capturedText).filter(Boolean).join('\n');
+  return /(?:^|[\s"'`])(?:llm-wiki\/)?(?:wiki\/(?!queries\/)(?:architecture|debugging|decisions|concepts|entities|sources|context)\/|procedures\/|llm-wiki\/wiki\/(?!queries\/)(?:architecture|debugging|decisions|concepts|entities|sources|context)\/|llm-wiki\/procedures\/)[^\s"'`]+\.md\b/i.test(text);
+}
+
+export function classifyTurn(entry, eventName = '') {
+  if (eventName === 'SubagentStop') {
+    return {
+      kind: 'subagent',
+      archive: false,
+      suggestDurable: false,
+      queueIfMissingDurable: false,
+    };
+  }
+
+  const question = capturedText(entry?.question);
+  const result = capturedText(entry?.result);
+  const work = capturedText(entry?.work);
+  const changedFiles = capturedText(entry?.changedFiles);
+  const verification = capturedText(entry?.verification);
+  const text = entrySearchText(entry);
+
+  if (!question && !result) {
+    return {
+      kind: 'empty',
+      archive: false,
+      suggestDurable: false,
+      queueIfMissingDurable: false,
+    };
+  }
+
+  if (explicitDurableRequested(text)) {
+    return {
+      kind: 'explicit-durable',
+      archive: true,
+      suggestDurable: false,
+      queueIfMissingDurable: true,
+    };
+  }
+
+  const hasWork = Boolean(work);
+  const hasFiles = Boolean(changedFiles);
+  const hasVerification = Boolean(verification);
+  const longWork = work.length > 800;
+  const durableKeyword = hasDurableKeyword(text);
+  const simple =
+    !hasWork &&
+    !hasFiles &&
+    !hasVerification &&
+    question.length <= 120 &&
+    result.length <= 800 &&
+    !durableKeyword;
+
+  if (simple) {
+    return {
+      kind: 'simple',
+      archive: false,
+      suggestDurable: false,
+      queueIfMissingDurable: false,
+    };
+  }
+
+  if (durableKeyword) {
+    return {
+      kind: 'suggest-durable',
+      archive: true,
+      suggestDurable: true,
+      queueIfMissingDurable: false,
+    };
+  }
+
+  return {
+    kind: hasWork || hasFiles || hasVerification || longWork || result.length > 800 ? 'archive-only' : 'simple',
+    archive: hasWork || hasFiles || hasVerification || longWork || result.length > 800,
+    suggestDurable: false,
+    queueIfMissingDurable: false,
+  };
+}
+
+export function formatDurableCaptureGuidance(query) {
+  const text = capturedText(query);
+  if (!text) return '';
+  if (explicitDurableRequested(text)) {
+    return [
+      'LLM Wiki durable documentation request detected:',
+      '- 현재 사용자 요청을 먼저 처리하되, 사용자가 기록/문서화를 요청했으므로 기존 durable wiki 문서를 찾아 갱신한다.',
+      '- 새 문서는 관련 기존 문서가 없을 때만 만들고, credentials/private data는 저장하지 않는다.',
+    ].join('\n');
+  }
+  if (hasDurableKeyword(text)) {
+    return [
+      'LLM Wiki durable knowledge note:',
+      '- 현재 답변을 먼저 한다. 다음 세션에도 쓸 결론이면 답변 끝에서 짧게 wiki 문서화 여부를 물어본다.',
+    ].join('\n');
+  }
+  return '';
+}

package/src/cli.js

@@ -1,3 +1,4 @@
+import { readFile } from 'fs/promises';
 import { resolve } from 'path';
 import { formatConsolidateResult, runConsolidate } from './consolidate.js';
 import { handleHook } from './hook.js';
@@ -51,6 +52,8 @@ function parseOptions(args) {
       i += 1;
     } else if (arg === '--no-expand') {
       options.expand = false;
+    } else if (arg === '--include-episodic') {
+      options.includeEpisodic = true;
     } else if (arg === '--replace-hooks') {
       options.replaceHooks = true;
     } else if (arg === '--all') {
@@ -91,12 +94,13 @@ Usage:
   llm-wiki projects --workspace /apps
   llm-wiki status
   llm-wiki version
+  llm-wiki manual
   llm-wiki uninstall
   llm-wiki hook codex <EventName>
   llm-wiki hook claude <EventName>
   llm-wiki bootstrap --workspace <project>
   llm-wiki migrate --workspace <project>
-  llm-wiki context "<query>" --workspace <project> [--limit 5] [--no-expand]
+  llm-wiki context "<query>" --workspace <project> [--limit 5] [--no-expand] [--include-episodic]
   llm-wiki lint --workspace <project>
   llm-wiki consolidate --workspace <project> [--dry-run]
   llm-wiki maintenance --workspace <project> [--json]
@@ -139,6 +143,12 @@ Usage:
     return;
   }
 
+  if (command === 'manual') {
+    const manual = await readFile(new URL('../docs/manual.md', import.meta.url), 'utf8');
+    process.stdout.write(manual.endsWith('\n') ? manual : `${manual}\n`);
+    return;
+  }
+
   if (command === 'projects') {
     const result = await listProjects(options);
     printJsonOrText(result, options, formatProjects);

package/src/hook.js

@@ -1,4 +1,5 @@
 import { findProjectRoot } from './fs-utils.js';
+import { classifyTurn, formatDurableCaptureGuidance, hasDetectedDurableWikiChange, isLegacyEagerCaptureMode } from './capture-policy.js';
 import { bootstrapProject, appendContextNote, appendLiveQa, appendSessionEnvelope, appendWikiLog, buildContextBrief, writeDecisionPage, writeQueryPage } from './project.js';
 import { recoverStaleTurnStates, recordMaintenanceForEntry } from './maintenance.js';
 import { applyProjectTemplateUpdate, inspectProjectState } from './project-state.js';
@@ -41,6 +42,49 @@ function contextOutput(eventName, context) {
   };
 }
 
+async function handleLegacyEagerStop(projectRoot, eventName, payload, entry) {
+  if (entry.question !== '(not captured)' || entry.result !== '(not captured)') {
+    const liveQaPath = await appendLiveQa(projectRoot, entry);
+    const queryPath = await writeQueryPage(projectRoot, entry);
+    const decisionPath = await writeDecisionPage(projectRoot, entry);
+    if (eventName === 'Stop' || eventName === 'SessionEnd') {
+      await recordMaintenanceForEntry(projectRoot, entry, {
+        source: decisionPath || queryPath || liveQaPath,
+        eventName,
+        reason: 'Captured turn needs durable wiki review.',
+      }).catch(() => {});
+    }
+    await appendWikiLog(projectRoot, `captured ${eventName}${queryPath ? `; query=${relative(projectRoot, queryPath)}` : ''}${decisionPath ? `; decision=${relative(projectRoot, decisionPath)}` : ''}`);
+  }
+  if (eventName === 'Stop' || eventName === 'SessionEnd') {
+    await clearTurnState(projectRoot, payload).catch(() => {});
+  }
+}
+
+async function handleAnswerFirstStop(projectRoot, eventName, payload, entry) {
+  const classification = classifyTurn(entry, eventName);
+  if (classification.archive) {
+    const archiveEntry = {
+      ...entry,
+      followUp: classification.suggestDurable
+        ? '이 결론은 다음 세션에도 쓸 수 있어 보입니다. 사용자가 승인하면 기존 durable wiki 문서에 합친다.'
+        : entry.followUp,
+    };
+    const liveQaPath = await appendLiveQa(projectRoot, archiveEntry);
+    if (classification.queueIfMissingDurable && !hasDetectedDurableWikiChange(entry)) {
+      await recordMaintenanceForEntry(projectRoot, entry, {
+        source: liveQaPath,
+        eventName,
+        reason: 'Explicit durable documentation request did not have a detected durable wiki update.',
+      }).catch(() => {});
+    }
+    await appendWikiLog(projectRoot, `captured ${eventName}; archive=${relative(projectRoot, liveQaPath)}; classification=${classification.kind}`);
+  }
+  if (eventName === 'Stop' || eventName === 'SessionEnd') {
+    await clearTurnState(projectRoot, payload).catch(() => {});
+  }
+}
+
 async function autoUpdateManagedProject(projectRoot, eventName) {
   if (process.env.LLM_WIKI_KIT_AUTO_PROJECT_UPDATE === '0') return;
   if (eventName !== 'SessionStart' && eventName !== 'InstructionsLoaded') return;
@@ -74,7 +118,8 @@ export async function handleHook(provider, explicitEvent) {
   if (eventName === 'UserPromptSubmit') {
     const prompt = promptText(payload);
     await rememberQuestion(projectRoot, payload, prompt);
-    const context = await buildContextBrief(projectRoot, eventName, prompt);
+    const guidance = formatDurableCaptureGuidance(prompt);
+    const context = [await buildContextBrief(projectRoot, eventName, prompt), guidance].filter(Boolean).join('\n\n');
     return contextOutput(eventName, context);
   }
 
@@ -99,21 +144,10 @@ export async function handleHook(provider, explicitEvent) {
   if (eventName === 'Stop' || eventName === 'SubagentStop' || eventName === 'SessionEnd') {
     const assistantText = payload.last_assistant_message || payload.response || payload.assistant_response || '';
     const entry = await buildEntryFromState(projectRoot, payload, assistantText);
-    if (entry.question !== '(not captured)' || entry.result !== '(not captured)') {
-      const liveQaPath = await appendLiveQa(projectRoot, entry);
-      const queryPath = await writeQueryPage(projectRoot, entry);
-      const decisionPath = await writeDecisionPage(projectRoot, entry);
-      if (eventName === 'Stop' || eventName === 'SessionEnd') {
-        await recordMaintenanceForEntry(projectRoot, entry, {
-          source: decisionPath || queryPath || liveQaPath,
-          eventName,
-          reason: 'Captured turn needs durable wiki review.',
-        }).catch(() => {});
-      }
-      await appendWikiLog(projectRoot, `captured ${eventName}${queryPath ? `; query=${relative(projectRoot, queryPath)}` : ''}${decisionPath ? `; decision=${relative(projectRoot, decisionPath)}` : ''}`);
-    }
-    if (eventName === 'Stop' || eventName === 'SessionEnd') {
-      await clearTurnState(projectRoot, payload).catch(() => {});
+    if (isLegacyEagerCaptureMode()) {
+      await handleLegacyEagerStop(projectRoot, eventName, payload, entry);
+    } else {
+      await handleAnswerFirstStop(projectRoot, eventName, payload, entry);
     }
     return {};
   }

package/src/maintenance.js

@@ -1,6 +1,7 @@
 import { readdir, unlink } from 'fs/promises';
 import { join, relative } from 'path';
 import { appendText, exists, kitDataDir, readJson, readText, sha256, writeTextIfMissing } from './fs-utils.js';
+import { classifyTurn, isMaintenanceRelatedQuery } from './capture-policy.js';
 import { redactText, summarizeForStorage } from './redaction.js';
 import { buildEntryFromTurnState, hasRecoverableTurnState } from './state.js';
 
@@ -206,6 +207,11 @@ export async function recoverStaleTurnStates(projectRoot, options = {}) {
     if (Number.isFinite(updated) && now - updated < cutoffMs) continue;
     if (!hasRecoverableTurnState(state)) continue;
     const entry = buildEntryFromTurnState(state, '');
+    if (!classifyTurn(entry, 'recovered stale turn state').archive) {
+      await unlink(path).catch(() => {});
+      output.push({ created: false, reason: 'simple-stale-turn', statePath: path, session: state.session });
+      continue;
+    }
     const result = await recordMaintenanceForEntry(projectRoot, entry, {
       source: `state:${state.session || path.split('/').pop()?.replace(/\.json$/, '')}`,
       eventName: 'recovered stale turn state',
@@ -219,12 +225,24 @@ export async function recoverStaleTurnStates(projectRoot, options = {}) {
 }
 
 export function formatMaintenanceContext(summary, options = {}) {
-  const limit = options.limit || 5;
-  const pending = summary.pending.slice(0, limit);
+  const eventName = options.eventName || '';
+  const defaultLimit = eventName === 'SessionStart' || eventName === 'InstructionsLoaded' ? 1 : 5;
+  const limit = options.limit || defaultLimit;
+  let pending = summary.pending.slice(0, limit);
   if (pending.length === 0) return '';
+
+  if (eventName === 'UserPromptSubmit') {
+    if (!isMaintenanceRelatedQuery(options.query || '', summary.pending)) return '';
+    pending = summary.pending.slice(0, 1);
+  } else if (eventName !== 'SessionStart' && eventName !== 'InstructionsLoaded') {
+    return '';
+  }
+
   const lines = [
-    'LLM Wiki maintenance queue:',
-    '- Pending items should be merged into existing durable wiki pages when relevant; update queue status to done or skipped after review.',
+    eventName === 'UserPromptSubmit'
+      ? 'LLM Wiki maintenance queue soft reminder:'
+      : 'LLM Wiki maintenance queue summary:',
+    `- pending: ${summary.pendingCount}. 현재 사용자 요청을 지연시키지 말고, 관련 있을 때만 기존 durable wiki 문서에 병합한다.`,
   ];
   for (const item of pending) {
     lines.push(`- ${item.topic || item.id}: source=${item.source}; target=${item.suggested_target}; reason=${item.reason}${item.result_missing ? '; result_missing=true' : ''}`);

package/src/project.js

@@ -169,7 +169,7 @@ export async function buildContextBrief(projectRoot, eventName, query = '') {
     .then(formatProjectMaintenanceContext)
     .catch(() => '');
   const wikiMaintenance = await maintenanceSummary(projectRoot)
-    .then(formatMaintenanceContext)
+    .then((summary) => formatMaintenanceContext(summary, { eventName, query }))
     .catch(() => '');
   return [formatContextPack(pack), maintenance, wikiMaintenance].filter(Boolean).join('\n\n');
 }

package/src/templates.js

@@ -13,11 +13,11 @@ This repository uses llm-wiki-kit as a hook-first living Markdown wiki for Codex
 - \`llm-wiki/raw/\`는 원본 또는 redacted 근거 저장소다. hook envelope append 외에는 원본 capture를 수정하지 않는다.
 - \`llm-wiki/wiki/\`는 agent가 관리하는 지식층이다. 결정, 구조, 디버깅, 개념, 절차, 맥락을 여기에 정리한다.
 - \`llm-wiki/wiki/memory.md\`는 짧은 핵심 기억이다. 긴 설명 대신 현재 상태와 중요한 문서 링크만 유지한다.
-- hook이 주입한 context를 우선 사용한다. 수동 확인이나 정리에는 \`llm-wiki context\`, \`llm-wiki lint\`, \`llm-wiki consolidate\`를 agent 보조 도구로 사용한다.
-- hook은 redacted live Q&A와 query/decision 후보를 기록한다. 재사용 가능한 지식은 agent가 기존 정식 wiki 문서에 합친다.
-- hook은 종료/시작 경계에서 정리 후보를 \`llm-wiki/outputs/maintenance/queue.md\`에 남길 수 있다. pending 항목은 agent가 기존 정식 wiki 문서에 병합한 뒤 done 또는 skipped로 표시한다.
+- hook이 주입한 context를 참고하되, 현재 사용자 답변을 먼저 처리한다. 수동 확인이나 정리에는 \`llm-wiki context\`, \`llm-wiki lint\`, \`llm-wiki consolidate\`를 agent 보조 도구로 사용한다.
+- 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만 남긴다.
 
@@ -32,7 +32,7 @@ Generated by llm-wiki-kit ${runtimeVersion()}.
 
 ## Purpose
 Codex와 Claude Code를 평소처럼 사용하는 동안 living Markdown LLM Wiki를 자연스럽게 유지한다.
-사용자가 많은 \`llm-wiki\` 명령을 직접 실행하는 방식이 아니라, agent가 작업 중 필요한 wiki 조회와 정리를 수행하는 것이 기본이다.
+사용자가 많은 \`llm-wiki\` 명령을 직접 실행하는 방식이 아니라, agent가 작업 중 필요한 wiki 조회와 정리를 수행하되 현재 사용자 답변을 지연시키지 않는 것이 기본이다.
 이 규칙은 오래된 OMX/OMC/\`omx_wiki/\` 규칙을 대체한다.
 
 ## Directories
@@ -42,13 +42,14 @@ Codex와 Claude Code를 평소처럼 사용하는 동안 living Markdown LLM Wik
 - \`procedures/\`: ingest, query, lint, security 같은 운영 규칙.
 
 ## Core Rules
-- 사용자는 Claude Code/Codex를 평소처럼 사용한다. agent가 필요한 wiki 조회와 정리를 자연스럽게 수행한다.
+- 사용자는 Claude Code/Codex를 평소처럼 사용한다. agent가 필요한 wiki 조회와 정리를 자연스럽게 수행하되, 현재 사용자 요청에 대한 답변을 먼저 끝낸다.
 - \`raw/\` 원본은 수정하지 않는다. 안전한 hook envelope append만 예외다.
 - 근거 없는 내용을 사실처럼 쓰지 않는다. 추론은 명시한다.
 - 중요한 주장에는 \`source_ids\`, 파일 경로, 검증 명령 중 하나 이상을 남긴다.
 - 오래 남길 내용이 생기면 새 문서부터 만들지 말고 기존 \`wiki/\` 문서를 먼저 찾아 갱신한다.
-- 반복해서 쓸 지식은 \`outputs/questions/\`에만 두지 말고 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
-- hook이 만든 \`outputs/maintenance/queue.md\` pending 항목은 다음 작업 시작 시 확인하고, 기존 정식 wiki 문서에 병합한 뒤 done 또는 skipped로 표시한다.
+- 단순 답변, 상태 확인, 일회성 대화는 과도하게 \`wiki/queries\`나 maintenance로 승격하지 않는다.
+- 반복해서 쓸 지식은 중요도와 동의 흐름에 따라 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
+- hook이 만든 \`outputs/maintenance/queue.md\` pending 항목은 현재 요청과 관련 있을 때 확인하고, 기존 정식 wiki 문서에 병합한 뒤 done 또는 skipped로 표시한다.
 - \`wiki/memory.md\`는 짧게 유지한다. 긴 설명 대신 현재 상태와 중요한 문서 링크를 둔다.
 - 모순은 덮어쓰지 말고 \`Contradictions\` 또는 \`Open Questions\`에 보존한다.
 - 인증값, token, password, private key, \`.env\` 원문은 wiki에 저장하지 않는다.
@@ -74,10 +75,10 @@ superseded_by: []
 
 ## Operations
 - ingest: \`wiki/memory.md\`와 \`wiki/index.md\`를 먼저 읽고, 새 근거를 확인한 뒤 기존 wiki 문서를 우선 갱신한다.
-- query: hook이 주입한 context를 우선 사용한다. 수동 명령은 점검용이며 일반 사용 흐름의 필수 단계가 아니다.
-- lint: agent가 필요할 때 wiki 건강 상태를 점검하는 보조 도구다. 사용자가 매번 직접 실행해야 하는 명령이 아니다.
+- query: hook이 주입한 context를 참고하되 현재 답변을 먼저 한다. 수동 명령은 점검용이며 일반 사용 흐름의 필수 단계가 아니다.
+- lint: 사용자가 요청했거나 wiki 유지보수 작업일 때 agent가 쓰는 보조 도구다. 매 turn 실행하지 않는다.
 - consolidate: agent가 \`memory.md\`/\`index.md\` generated block을 안전하게 갱신할 때 쓰는 보조 도구다. 손글씨 영역과 정식 문서 본문은 덮어쓰지 않는다.
-- maintenance: \`outputs/maintenance/queue.md\`는 종료/시작 경계에서 생긴 정리 후보 목록이다. agent가 기존 문서 병합 여부를 판단하고 상태를 갱신한다.
+- maintenance: \`outputs/maintenance/queue.md\`는 종료/시작 경계에서 생긴 정리 후보 목록이다. 현재 요청을 지연시키지 않는 범위에서 agent가 기존 문서 병합 여부를 판단하고 상태를 갱신한다.
 `;
 }
 
@@ -169,19 +170,21 @@ export function procedure(name) {
 3. source별 요약이 필요하면 \`wiki/sources/<slug>.md\`를 만들거나 갱신한다.
 4. 새 문서부터 만들지 말고 관련 concept/entity/decision/architecture/debugging/context 문서를 먼저 찾아 갱신한다.
 5. 중복 문서를 만들지 않는다. 같은 사실이 이미 있으면 기존 문서에 합친다.
-6. 중요한 주장에는 source reference, confidence, memory type, importance, verification status를 남긴다.
-7. durable entry point가 바뀌면 \`wiki/memory.md\`를 짧게 갱신하거나 agent가 \`llm-wiki consolidate\`를 사용한다.
-8. 의미 있는 변화는 \`wiki/log.md\`에 짧게 남긴다.
+6. 단순 답변과 일회성 대화는 durable wiki로 승격하지 않는다.
+7. 중요한 주장에는 source reference, confidence, memory type, importance, verification status를 남긴다.
+8. durable entry point가 바뀌면 \`wiki/memory.md\`를 짧게 갱신하거나 agent가 \`llm-wiki consolidate\`를 사용한다.
+9. 의미 있는 변화는 \`wiki/log.md\`에 짧게 남긴다.
 `,
     'query.md': `# Query Procedure
 
-1. hook이 주입한 context를 먼저 사용한다. 수동으로 확인할 때만 \`llm-wiki context "<query>"\`를 쓴다.
+1. 현재 사용자 질문에 먼저 답한다. hook이 주입한 context는 필요한 만큼만 참고한다.
 2. \`wiki/memory.md\`와 \`wiki/index.md\`에서 시작한다.
 3. 관련 \`wiki/\` 문서를 최소한으로 읽는다.
 4. 정확한 근거가 필요할 때만 raw source를 확인한다.
 5. 검증된 사실과 추론을 분리한다.
-6. 일회성 답변은 \`outputs/questions/\`에 남기고, 재사용 가능한 답변은 기존 \`wiki/queries/\` 또는 관련 정식 문서에 연결한다.
-7. 반복해서 쓸 결론은 \`wiki/architecture/\`, \`wiki/debugging/\`, \`wiki/decisions/\`, \`wiki/concepts/\`, \`procedures/\`에 합친다.
+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/\`에 합친다.
 `,
     'lint.md': `# Lint Procedure
 

package/src/wiki-search.js

@@ -79,6 +79,20 @@ function sortHits(a, b) {
   return a.path.localeCompare(b.path);
 }
 
+function importance(page) {
+  const value = Number(page?.frontmatter?.importance || 0);
+  return Number.isFinite(value) ? value : 0;
+}
+
+function isDefaultSearchCandidate(page, options = {}) {
+  if (options.includeEpisodic) return true;
+  const type = String(page.type || '').toLowerCase();
+  if (type === 'query' || page.rel.startsWith('wiki/queries/')) {
+    return ['semantic', 'procedural'].includes(page.memoryType) && importance(page) >= 4;
+  }
+  return true;
+}
+
 export async function searchWiki(projectRoot, query, options = {}) {
   return (await performSearch(projectRoot, query, options)).hits;
 }
@@ -94,7 +108,7 @@ async function performSearch(projectRoot, query, options = {}) {
 
   let pages = [];
   try {
-    pages = await collectWikiPages(projectRoot, opts);
+    pages = (await collectWikiPages(projectRoot, opts)).filter((page) => isDefaultSearchCandidate(page, opts));
   } catch {
     return { hits: [], search: 'missing-wiki' };
   }
@@ -212,12 +226,12 @@ export async function buildContextPack(projectRoot, query, options = {}) {
 
 export function formatContextPack(pack) {
   const lines = [
-    'LLM Wiki context from llm-wiki-kit:',
+    'LLM Wiki context from llm-wiki-kit: answer the current user request first; use wiki context only when it helps.',
     '- Treat chat memory as temporary; update project Markdown when knowledge should persist.',
     '- Preserve raw/wiki separation. Do not store secrets, tokens, .env contents, private keys, or personal/customer identifiers.',
     '- Prefer updating existing wiki pages over creating duplicate pages.',
-    '- Claude Code/Codex를 평소처럼 사용한다. 사용자가 별도 명령을 실행하지 않아도 agent가 필요한 wiki 조회와 정리를 수행한다.',
-    '- 오래 쓸 지식은 outputs/questions에만 두지 말고 기존 wiki/architecture, wiki/debugging, wiki/decisions, wiki/concepts, procedures 문서에 합친다.',
+    '- Claude Code/Codex를 평소처럼 사용한다. 사용자가 별도 명령을 실행하지 않아도 agent가 필요한 wiki 조회와 정리를 수행하되, 현재 사용자 답변을 지연시키지 않는다.',
+    '- durable 기록은 중요도와 동의 흐름에 따라 선택적으로 승격한다. 오래 쓸 지식은 승인된 경우 기존 wiki/architecture, wiki/debugging, wiki/decisions, wiki/concepts, procedures 문서에 합친다.',
     '- wiki/memory.md는 짧은 핵심 기억으로 유지하고, 긴 설명 대신 관련 정식 문서 링크를 둔다.',
   ];
   if (pack.query) {