llm-wiki-kit 0.2.0 → 0.2.1

package/README.md

@@ -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.

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/package.json

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

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';
@@ -93,6 +94,7 @@ 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>
@@ -141,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);