@m16khb/llm-wiki 0.1.0 → 0.1.1

package/README.md

@@ -2,15 +2,18 @@
 
 `llm-wiki`는 Claude Code와 Codex가 같은 Obsidian-backed LLM Wiki vault를 안전하게 공유하도록 하는 Go 기반 MCP 서버/CLI다.
 
-현재 기본 구조는 **단일 daemon process + streamable HTTP MCP + SQLite WAL queue + in-memory metadata cache**다. 여러 Claude Code/Codex 세션은 각자 파일을 직접 쓰지 않고 같은 daemon의 MCP endpoint에 붙는다.
+현재 기본 구조는 **단일 long-running daemon process + streamable HTTP MCP + SQLite WAL queue + in-memory metadata cache**다. Claude Code/Codex는 기본적으로 `mcp-autostart` stdio shim을 실행하고, shim은 daemon이 없으면 자동으로 띄운 뒤 실제 tool call을 같은 daemon의 HTTP MCP endpoint로 proxy한다. 즉 client마다 짧은 shim process는 생길 수 있지만, vault/DB를 소유하고 write를 직렬화하는 프로세스는 하나의 `llm-wiki serve` daemon이다.
 
 ## 핵심 원칙
 
 - Single writer: `llm-wiki serve` daemon 하나가 write를 직렬화한다.
+- Lazy start: `llm-wiki mcp-autostart`가 MCP client 시작 시 daemon health를 확인하고 없으면 자동 기동한다.
+- Auto init: `llm-wiki init` 또는 `mcp-autostart --init-vault`가 누락된 vault 폴더 구조를 non-destructive하게 만든다.
 - SQLite WAL queue: write job은 durable queue/audit DB에 먼저 기록된다.
 - Local-first: Markdown vault가 canonical source다. SQLite는 queue/index/cache/audit state이며 rebuild 가능해야 한다.
 - Read-safe: `.obsidian/`, hidden/runtime directory, path traversal은 차단한다.
 - Write-minimal: 기본 write는 `wiki_capture`의 additive Markdown 생성뿐이다.
+- Destructive maintenance: `llm-wiki cleanup`은 기본 dry-run이며 `--apply`가 있을 때만 archive/rename/rewrite를 수행한다.
 - Source 보호: `10-sources/` body 수정/삭제 도구는 제공하지 않는다.
 
 ## 빠른 시작
@@ -19,18 +22,23 @@
 # repo root
 ./scripts/install-local.sh
 
-# singleton daemon 시작
-./bin/llm-wiki serve --vault ~/workspace/knowledge-base/llm-wiki
-
-# 별도 shell에서 health check
-curl http://127.0.0.1:39233/healthz
-
 # read-only CLI smoke
+./bin/llm-wiki init --vault ~/workspace/knowledge-base/llm-wiki --json
 ./bin/llm-wiki info --vault ~/workspace/knowledge-base/llm-wiki --json
 ./bin/llm-wiki search --vault ~/workspace/knowledge-base/llm-wiki --limit 5 karpathy
 ./bin/llm-wiki lint --vault ~/workspace/knowledge-base/llm-wiki --json
+```
+
+MCP client에서는 아래 설정 파일을 복사/병합하면 된다. daemon을 미리 켤 필요는 없다.
 
-# queue audit 확인
+- Claude Code: `config/claude-code.mcp.json`을 target project의 `.mcp.json`에 복사
+- Codex: `config/codex.config.toml` 내용을 `~/.codex/config.toml`에 병합
+
+수동 운영이나 launchd/systemd가 daemon을 관리하는 환경에서는 직접 daemon을 띄우고 HTTP config를 써도 된다.
+
+```bash
+./bin/llm-wiki serve --vault ~/workspace/knowledge-base/llm-wiki
+curl http://127.0.0.1:39233/healthz
 ./bin/llm-wiki jobs --limit 20
 ```
 
@@ -42,15 +50,23 @@ curl http://127.0.0.1:39233/healthz
 
 | Command | Purpose |
 |---|---|
+| `llm-wiki init` | 누락된 vault root와 표준 폴더 구조 생성 |
 | `llm-wiki serve` | singleton daemon + streamable HTTP MCP endpoint 시작 |
-| `llm-wiki mcp` | legacy stdio MCP server; daemon HTTP가 기본 권장 경로 |
+| `llm-wiki mcp-autostart` | stdio MCP shim; daemon을 자동 기동/재사용하고 HTTP MCP로 proxy |
+| `llm-wiki mcp` | legacy direct stdio MCP server; daemon 공유가 필요 없는 compatibility path |
 | `llm-wiki info` | vault root/count 요약 |
 | `llm-wiki search QUERY` | Markdown lexical search |
 | `llm-wiki read PAGE_OR_PATH` | slug 또는 vault-relative path로 page 읽기 |
 | `llm-wiki lint` | frontmatter/wikilink/slug 구조 점검 |
 | `llm-wiki capture` | SQLite queue를 통해 allowed folder에 curated note 생성 |
+| `llm-wiki cleanup` | dry-run 기본의 apply-gated vault cleanup; `repository-references`, `duplicate-slugs`, LLM-reviewed `analyze`/`apply-plan` 지원 |
+| `llm-wiki session-context` | hook/수동 사용을 위한 project-aware wiki context 검색 |
+| `llm-wiki session-capture` | 세션 중 선별한 내용을 `30-sessions/`에 capture |
+| `llm-wiki hook` | Claude Code/Codex 공용 lifecycle hook entrypoint |
 | `llm-wiki jobs` | SQLite queue 최근 job audit 출력 |
 
+표준 vault 구조는 `00-meta/`, `00-meta/reports/`, `10-sources/`, `20-wiki/concepts/`, `20-wiki/entities/`, `20-wiki/summaries/`, `30-sessions/`이다. `init`은 `.obsidian/`을 만들거나 수정하지 않고 기존 파일을 rewrite하지 않는다.
+
 ## MCP tools
 
 | Tool | Type | Purpose |
@@ -61,35 +77,101 @@ curl http://127.0.0.1:39233/healthz
 | `wiki_lint` | read-only | structural lint |
 | `wiki_capture` | queued additive write | `20-wiki/`, `30-sessions/`, `00-meta/reports/` 하위에 note 생성 |
 
-## Claude Code 설정
+## Vault cleanup
+
+`llm-wiki cleanup`은 `ai-slop-cleaner`식으로 과도하게 파편화된 wiki 내용을 정리하는 **CLI-only maintenance command**다. MCP tool로 노출하지 않는 이유는 archive/rename/bulk wikilink rewrite가 destructive operation이라서, local shell에서 dry-run 결과를 본 뒤 명시적으로 `--apply`를 붙이는 흐름이 더 안전하기 때문이다.
 
-먼저 daemon을 실행한다.
+현재 지원 scope는 `repository-references`와 `duplicate-slugs`다.
 
 ```bash
-/Users/m16khb/Workspace/llm-wiki/bin/llm-wiki serve \
-  --vault /Users/m16khb/Workspace/knowledge-base/llm-wiki
+# 계획만 출력하고 파일은 변경하지 않음
+llm-wiki cleanup --vault ~/workspace/knowledge-base/llm-wiki --json
+
+# repo별 dated fragment를 bundle page로 합치고 원본은 _archive/로 rename
+llm-wiki cleanup --vault ~/workspace/knowledge-base/llm-wiki --scope repository-references --apply --json
+
+# duplicate slug warning을 없애기 위해 non-canonical page를 unique slug로 rename
+llm-wiki cleanup --vault ~/workspace/knowledge-base/llm-wiki --scope duplicate-slugs --apply --json
 ```
 
-그 다음 `config/claude-code.mcp.json`을 target project의 `.mcp.json`에 복사한다.
+LLM이 “진짜 cleanup 대상인지 / 어떤 전략이 안전한지” 먼저 판단하게 하려면 `analyze → plan JSON → apply-plan` 흐름을 사용한다. CLI 자체는 외부 LLM을 호출하지 않고, candidate packet과 deterministic plan executor만 제공한다. Codex/Claude 같은 agent가 analysis를 읽고 allowlisted JSON plan을 작성한 뒤, CLI가 다시 dry-run 검증과 `--apply` gate를 담당한다.
+
+```bash
+# LLM/agent가 검토할 candidate packet 생성; 파일 변경 없음
+llm-wiki cleanup analyze --vault ~/workspace/knowledge-base/llm-wiki --scope repository-references --json
+llm-wiki cleanup analyze --vault ~/workspace/knowledge-base/llm-wiki --scope duplicate-slugs --json
+
+# agent가 작성한 JSON plan을 먼저 검증만 수행
+llm-wiki cleanup apply-plan --vault ~/workspace/knowledge-base/llm-wiki --plan /tmp/cleanup-plan.json --json
+
+# 검증 결과가 의도와 맞을 때만 적용
+llm-wiki cleanup apply-plan --vault ~/workspace/knowledge-base/llm-wiki --plan /tmp/cleanup-plan.json --apply --json
+```
+
+Plan schema는 versioned JSON이고 현재 allowlisted action은 `run_scope`와 `rename_page`뿐이다. `run_scope`는 기존 guarded cleanup을 통째로 실행하므로 plan 안에서 단독 action이어야 한다.
 
 ```json
 {
-  "mcpServers": {
-    "llm-wiki": {
-      "type": "http",
-      "url": "http://127.0.0.1:39233/mcp"
+  "version": 1,
+  "scope": "repository-references",
+  "summary": "LLM-reviewed reason for why these candidates are true cleanup targets.",
+  "actions": [
+    {
+      "type": "run_scope",
+      "scope": "repository-references",
+      "reason": "Consolidate dated fragments through the guarded deterministic cleanup scope."
     }
-  }
+  ]
 }
 ```
 
-Claude Code는 local stdio뿐 아니라 HTTP MCP server 설정도 지원한다. 공식 문서는 `claude mcp add`와 `.mcp.json` scope를 설명한다: https://code.claude.com/docs/en/mcp
+Repo-local skill 표면도 제공한다. **MCP 설정만으로 skill이 자동 배포되지는 않는다.** MCP는 tool 호출 표면이고, skill은 Claude Code/Codex client가 별도로 로드하는 prompt package다. 이 repo에는 같은 workflow를 Codex와 Claude Code 양쪽 skill 폴더에 둔다.
+
+| Skill | Purpose |
+|---|---|
+| `llm-wiki-query` | `info/search/read/lint/session-context` read-only lookup |
+| `llm-wiki-capture` | `wiki_capture`, `capture`, `session-capture` curated additive write |
+| `llm-wiki-cleanup` | LLM-reviewed `cleanup analyze → apply-plan` workflow |
+| `llm-wiki-mcp-ops` | daemon, `mcp-autostart`, jobs, npx/MCP smoke |
+| `llm-wiki-hooks` | `SessionStart`, `UserPromptSubmit`, `Stop` hook validation |
+
+Locations:
+
+- Codex/OMX: `.codex/skills/<skill>/SKILL.md` (`$llm-wiki-query`, `$llm-wiki-capture`, ...)
+- Claude Code: `.claude/skills/<skill>/SKILL.md` (client skill picker/skill trigger)
+
+`repository-references` 적용 시 동작:
+
+- `20-wiki/concepts/repository-references/<repo>/` 아래 dated fragment들을 `<repo>-reference-bundle-YYYY-MM-DD.md`로 통합한다.
+- 원본 fragment는 `_archive/repository-reference-fragments-YYYY-MM-DD/<repo>/archived-*.md`로 이동해 duplicate slug를 피한다.
+- active wiki page의 wikilink는 bundle slug로 rewrite한다.
+- `00-meta/index.md`, `00-meta/log.md`, `00-meta/reports/repository-reference-cleanup-YYYY-MM-DD*.md`를 갱신한다.
+- `.obsidian/`과 `10-sources/` body는 수정하지 않는다.
 
-### npx / stdio compatibility 설정
+`duplicate-slugs` 적용 시 동작:
 
-HTTP daemon을 공유하는 구성이 기본 권장 경로지만, stdio MCP만 허용되는 환경에서는 npm wrapper로 `llm-wiki mcp`를 실행할 수 있다.
+- 같은 filename slug를 가진 page들 중 canonical page를 하나 고른다. `10-sources/`는 보호 대상, `00-meta/` canonical entry는 root compatibility page보다 우선한다.
+- non-canonical page를 같은 폴더의 unique slug로 rename한다. 예: root `index.md` → `root-compatibility-index.md`.
+- renamed page에는 canonical page wikilink와 이전 path notice를 추가한다.
+- `00-meta/log.md`와 `00-meta/reports/duplicate-slug-cleanup-YYYY-MM-DD*.md`를 갱신한다.
+- `.obsidian/`과 `10-sources/` body는 수정하지 않는다.
 
-로컬 repo를 바로 쓰는 `.mcp.json` 예시:
+## Lazy daemon MCP 설정
+
+권장 설정은 stdio command로 `llm-wiki mcp-autostart`를 실행하는 방식이다.
+
+```text
+MCP client ── stdio ── llm-wiki mcp-autostart shim
+                         │ health/start/proxy
+                         ▼
+                   llm-wiki serve daemon ── /mcp ── shared service/queue/vault
+```
+
+동시에 여러 client가 시작되어도 같은 `--db` path의 daemon lock이 중복 daemon을 막는다. 이미 다른 vault/DB를 가진 daemon이 같은 address를 점유 중이면 shim은 proxy하지 않고 에러를 낸다.
+
+### Claude Code
+
+`config/claude-code.mcp.json`을 target project의 `.mcp.json`에 복사한다.
 
 ```json
 {
@@ -98,44 +180,107 @@ HTTP daemon을 공유하는 구성이 기본 권장 경로지만, stdio MCP만
       "command": "npx",
       "args": [
         "-y",
+        "--prefix",
+        "/tmp",
         "--package",
         "/Users/m16khb/Workspace/llm-wiki",
+        "--",
         "llm-wiki",
-        "mcp",
+        "mcp-autostart",
+        "--init-vault",
         "--vault",
-        "/Users/m16khb/Workspace/knowledge-base/llm-wiki"
+        "/Users/m16khb/Workspace/knowledge-base/llm-wiki",
+        "--addr",
+        "127.0.0.1:39233"
       ]
     }
   }
 }
 ```
 
-npm registry에 publish한 뒤에는 package path 대신 package name을 쓴다.
+npm registry package를 쓸 때는 `--package` 값을 `@m16khb/llm-wiki`로 바꾼다. `config/claude-code.npx.mcp.json`은 registry package 예시, `config/claude-code.npx-local.mcp.json`은 local repo 예시다.
 
-```json
-{
-  "mcpServers": {
-    "llm-wiki": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "--package",
-        "@m16khb/llm-wiki",
-        "llm-wiki",
-        "mcp",
-        "--vault",
-        "/Users/m16khb/Workspace/knowledge-base/llm-wiki"
-      ]
-    }
-  }
-}
+Claude Code는 local stdio뿐 아니라 HTTP MCP server 설정도 지원한다. 공식 문서는 `claude mcp add`와 `.mcp.json` scope를 설명한다: https://code.claude.com/docs/en/mcp
+
+### Codex
+
+`config/codex.config.toml` 내용을 `~/.codex/config.toml`에 병합한다.
+
+```toml
+[mcp_servers.llm-wiki]
+command = "npx"
+args = [
+  "-y",
+  "--prefix", "/tmp",
+  "--package", "/Users/m16khb/Workspace/llm-wiki",
+  "--",
+  "llm-wiki",
+  "mcp-autostart",
+  "--init-vault",
+  "--vault", "/Users/m16khb/Workspace/knowledge-base/llm-wiki",
+  "--addr", "127.0.0.1:39233",
+]
+startup_timeout_sec = 60
+tool_timeout_sec = 60
+```
+
+Codex config는 MCP stdio server에 `mcp_servers.<id>.command` / `args`를 쓰고, streamable HTTP server에는 `mcp_servers.<id>.url`을 쓴다: https://developers.openai.com/codex/config-reference
+
+## Claude Code / Codex 공용 session hooks
+
+두 client의 hook 설정 문법은 다르지만, `llm-wiki`는 같은 command를 실행하게 만든다.
+
+```text
+SessionStart      -> llm-wiki hook -> project/tech terms로 wiki_search 후 additionalContext 주입
+UserPromptSubmit  -> llm-wiki hook -> prompt keyword + project/tech terms로 wiki_search 후 relevant context 주입
+Stop              -> llm-wiki hook -> assistant가 명시한 llm-wiki-capture block만 30-sessions/에 저장
 ```
 
-wrapper는 기존 `bin/llm-wiki`가 있으면 그대로 실행하고, 없으면 Go toolchain으로 CLI를 cache에 빌드한 뒤 실행한다. MCP stdio 안전을 위해 wrapper 자체는 stdout에 진단을 쓰지 않는다.
+`go.mod`가 있으면 Go/Golang을 감지하고, MCP SDK·SQLite·Gin·GORM·Redis 같은 dependency 신호, `package.json`/`bin` 기반 Node/npm/npx wrapper 신호, `swaggo` dependency나 `swagger.yaml`/`openapi.yaml` 같은 API spec 파일을 tech context로 별도 검색한다. 검색 결과는 현재 project와 맞는 문서를 우선하고, 다른 repository 전용 reference는 hook tech context에서 제외한다.
+
+공용 wrapper는 `scripts/hooks/llm-wiki-hook.sh`다. `LLM_WIKI_BIN`이 있으면 그 binary를 쓰고, 없으면 `llm-wiki` PATH, 마지막으로 이 repo를 `npx --package <repo>`로 실행한다.
+
+현재 repo에는 project-local hook 설정도 포함되어 있다: `.claude/settings.json`, `.codex/hooks.json`. 다른 repo에 붙일 때는 아래 예시를 복사하고 command path/vault path를 조정한다.
+
+예시 파일:
+
+- Claude Code project/user settings 예시: `config/claude-code.hooks.settings.json`
+- Codex project/user hooks 예시: `config/codex.hooks.json`
+
+Codex는 `~/.codex/hooks.json` 또는 `<repo>/.codex/hooks.json`, Claude Code는 `.claude/settings.json`/`~/.claude/settings.json`에 같은 wrapper command를 등록하면 된다. Codex hooks는 기본 enabled지만 trust review가 필요할 수 있고, Claude Code는 `UserPromptSubmit`/`SessionStart`에서 `hookSpecificOutput.additionalContext`를 context로 넣는다.
 
-## Codex 설정
+세션 중 수동 capture:
 
-먼저 daemon을 실행한다. 그 다음 `config/codex.config.toml` 내용을 `~/.codex/config.toml`에 병합한다.
+```bash
+llm-wiki session-capture \
+  --vault ~/workspace/knowledge-base/llm-wiki \
+  --project "$PWD" \
+  --phase progress \
+  --title "MCP hook decision" \
+  --body "Claude Code와 Codex는 같은 llm-wiki hook command를 호출한다."
+```
+
+Stop hook에서 자동 저장하려면 assistant 최종 답변에 아래처럼 명시적으로 선별 블록을 포함한다. 블록이 없으면 Stop hook은 아무것도 저장하지 않는다.
+
+````markdown
+```llm-wiki-capture
+title: MCP hook decision
+tags: hooks, codex, claude
+---
+Claude Code와 Codex hook은 같은 `llm-wiki hook` command를 호출한다.
+```
+````
+
+### 직접 HTTP daemon 설정
+
+launchd/systemd/manual command로 daemon을 이미 관리한다면 HTTP URL config를 써도 된다.
+
+```bash
+/Users/m16khb/Workspace/llm-wiki/bin/llm-wiki serve \
+  --vault /Users/m16khb/Workspace/knowledge-base/llm-wiki
+```
+
+Claude Code HTTP 예시는 `config/claude-code.http.mcp.json`, Codex HTTP 예시는 `config/codex.http.config.toml`에 있다.
 
 ```toml
 [mcp_servers.llm-wiki]
@@ -144,7 +289,11 @@ startup_timeout_sec = 10
 tool_timeout_sec = 60
 ```
 
-Codex config는 MCP streamable HTTP server endpoint를 `mcp_servers.<id>.url`로 설정한다: https://developers.openai.com/codex/config-reference
+### Direct stdio compatibility
+
+`llm-wiki mcp`는 daemon을 거치지 않고 stdio MCP server가 직접 vault/service를 연다. stdio-only 환경의 비상/호환 경로이며, Claude Code와 Codex가 같은 daemon을 공유해야 하는 기본 운영에는 `mcp-autostart`를 사용한다.
+
+npx wrapper는 기존 `bin/llm-wiki`가 있으면 그대로 실행하고, 없으면 Go toolchain으로 CLI를 cache에 빌드한 뒤 실행한다. MCP stdio 안전을 위해 wrapper 자체는 stdout에 진단을 쓰지 않는다. `--prefix /tmp`는 이 repo처럼 현재 프로젝트의 `package.json` 이름이 `@m16khb/llm-wiki`와 같을 때 npx가 local package로 오인하는 것을 피하기 위한 안전장치다.
 
 ## 개발 문서