project-librarian 0.2.1 → 0.3.0

package/README.ko.md

@@ -5,46 +5,116 @@
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.13-brightgreen.svg)](https://nodejs.org/)
 [![코드 근거 인덱스](https://img.shields.io/badge/code%20evidence-node%3Asqlite-blue.svg)](https://nodejs.org/api/sqlite.html)
 
-Codex, Claude Code, Cursor, Gemini CLI를 위한 간결한 프로젝트 메모리와 코드 근거.
+**모든 AI 코딩 에이전트에게 프로젝트에 대한 같은 지속 기억을 주세요.** Project Librarian은 저장소 안에 두는 간결한 계획 위키와 선택적 코드 근거 인덱스를 유지합니다. Codex, Claude Code, Cursor, Gemini CLI가 세션을 시작할 때 이걸 읽으므로, 매번 코드베이스를 처음부터 다시 파악하지 않아도 됩니다.
 
-Project Librarian은 저장소 로컬 계획 위키, 간결한 시작 훅, 선택적 SQLite 코드 근거 인덱스를 생성합니다. 에이전트는 프로젝트 계획에서 시작하고, 필요한 문서로 라우팅하며, 전체 저장소를 반복 스캔하지 않고 코드로 뒷받침되는 근거를 확인할 수 있습니다.
+언어: [English](README.md) | [한국어](README.ko.md)
 
-언어: [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)
+## 빠른 시작
+
+대부분의 사용자는 생명주기 명령을 직접 실행하기보다 코딩 에이전트에게 Project Librarian 실행을 요청하면 됩니다.
+
+재사용 가능한 스킬 파일을 한 번 설치하거나, 셸을 사용할 수 있는 에이전트에게 설치를 요청합니다.
+
+```bash
+npx project-librarian install-skill --scope user --agents all
+```
+
+그다음 대상 저장소에서 Codex, Claude Code, Cursor, Gemini CLI에 자연어로 요청합니다.
+
+- "Project Librarian으로 이 저장소의 계획 위키를 설정하고 진단까지 실행해줘."
+- "Project Librarian으로 기존 docs/wiki 내용을 마이그레이션해줘."
+- "Project Librarian 위키에서 authentication decisions를 찾아줘."
+
+설치된 스킬은 에이전트가 로컬 실행 경로를 찾고 프로젝트 루트에서 맞는 명령을 실행하도록 안내합니다. 실행 경로를 대상 저장소의 에이전트 설정 안에 두고 싶을 때만 프로젝트 범위 설치를 선택합니다.
+
+```bash
+npx project-librarian install-skill --scope project --agents all
+```
+
+`install-skill`은 재사용 가능한 실행 파일과 스킬 파일만 복사합니다. `AGENTS.md`, 에이전트 훅, `wiki/`, git 훅 파일, 진단, 선택적 코드 근거 지원을 만들거나 갱신하는 것은 에이전트가 실행하는 생명주기 명령입니다.
+
+## 핵심 강점
+
+- **첫 읽기를 작게.** 세션 시작 훅은 `wiki/startup.md`와 `wiki/index.md`만 주입하고, 에이전트는 저장소 전체를 처음부터 훑는 대신 필요할 때 더 깊은 페이지로 이동합니다.
+- **한 번 설정, 네 에이전트.** Codex, Claude Code, Cursor, Gemini CLI가 같은 위키 우선 계약과 훅, 규칙을 공유합니다.
+- **구조적인 위키 작성.** 새 프로젝트 내용은 작성하거나 취합하기 전에 `wiki/meta/document-taxonomy.md`로 분류하므로 PRD, 정책, UX, 데이터, API, QA, 릴리즈, 운영 메모가 하나의 잡다한 페이지로 합쳐지지 않습니다.
+- **막연한 표현이 아니라 측정값.** 모든 성능 주장은 격리된 Codex 벤치마크에서 나오며, 손해를 본 경우도 이긴 경우 바로 옆에 보여 줍니다.
+- **선택적 코드 근거.** 재생성 가능한 SQLite 인덱스와 답변 형태 MCP 도구가 영향·소유권·워크스페이스 그래프 질문에 답하며, 추가 런타임 의존성이 전혀 없습니다.
+- **다시 실행해도 안전.** 부트스트랩은 멱등하고 기존 내용 보존을 우선하며, 진단은 깨진 경로·도달 불가 페이지·오래된 사실을 에이전트가 오해하기 전에 잡아냅니다.
 
 ## 존재 이유
 
-LLM 코딩 에이전트는 매 세션마다 프로젝트를 다시 발견하느라 컨텍스트와 도구 호출을 낭비합니다. 오래된 대화 읽기, Markdown 스캔, 소스 검색, 관련 파일 추측이 반복됩니다.
+LLM 코딩 에이전트는 매 세션마다 프로젝트를 처음부터 다시 파악하느라 컨텍스트와 도구 호출을 낭비합니다. 오래된 대화를 읽고, 문서를 훑고, 소스를 검색하고, 어떤 파일이 중요한지 추측하는 일이 반복됩니다.
 
 Project Librarian은 에이전트에게 두 가지 로컬 정본을 제공합니다.
 
 | 표면 | 에이전트가 얻는 것 |
 | --- | --- |
-| `wiki/startup.md` + `wiki/index.md` | 짧은 세션 시작 요약과 라우터. 필요한 계획 페이지만 읽습니다. |
+| `wiki/startup.md` + `wiki/index.md` | 짧은 세션 시작 요약과 라우터. 관련 계획 페이지만 읽습니다. |
 | `wiki/canonical/` 및 `wiki/decisions/` | 현재 프로젝트 사실, 제약, 리스크, 패키지 계약, CLI 동작, 지속되는 결정. |
-| `.codex/`, `.claude/`, `.cursor/`, `.gemini/` 훅 | 전체 위키를 로드하지 않는 Codex/Claude Code/Cursor/Gemini CLI 시작 컨텍스트. |
-| `GEMINI.md` 및 `.cursor/rules/` | Gemini CLI와 Cursor가 같은 compact wiki-first 계약으로 진입하게 하는 instruction 파일. |
-| `.project-wiki/code-evidence.sqlite` | 파일, 심볼, import, route, 소유권, 작업공간 그래프, 보고서, 영향 확인을 위한 재생성 가능한 코드 근거. |
-| 진단 및 마이그레이션 모드 | 링크 확인, 품질 확인, 마이그레이션 수신함, 오래된 신호 보고서, 작업 흐름 문제 발견 시 이슈 초안. |
+| `wiki/meta/document-taxonomy.md` | PRD, 정책, UX, 데이터, 개발, QA, 릴리즈, 운영 정본을 어디에 둘지 안내하는 서비스 생애주기 분류 지도. |
+| `.codex/`, `.claude/`, `.cursor/`, `.gemini/` 훅 | 전체 위키를 불러오지 않는 Codex/Claude Code/Cursor/Gemini CLI 시작 컨텍스트. |
+| `GEMINI.md` 및 `.cursor/rules/` | Gemini CLI와 Cursor를 같은 간결한 위키 우선 계약으로 안내하는 지침 파일. |
+| `.project-wiki/code-evidence.sqlite` | 파일, 심볼, import, route, 소유권, 워크스페이스 그래프, 보고서, 영향 확인을 위한 재생성 가능한 코드 근거. |
+| 진단 및 마이그레이션 모드 | 링크 확인, 품질 확인, 마이그레이션 수신함, 오래된 신호 보고, 작업 흐름에서 문제가 드러날 때의 이슈 초안. |
 
 핵심은 “문서를 더 많이 쓰자”가 아닙니다. 첫 에이전트 읽기량을 작게 유지하고, 더 깊은 프로젝트 정본과 코드 근거로 가는 신뢰 가능한 경로를 제공하는 것입니다.
 
+이 분류 체계는 가능한 모든 문서를 만들라는 지시가 아니라 라우팅 보조 장치입니다. 서비스/제품 개발 문서 체계에 맞춘 분류라, 라이브러리/인프라/연구성 프로젝트에는 일부 항목이 덜 맞을 수 있습니다. 그런 경우 관련 있는 영역만 쓰고 나머지는 억지로 문서화하지 않는 것이 맞습니다.
+
 ## 벤치마크 결과
 
-벤치마크는 관리자 릴리스 근거이며 공개 사용자 작업 흐름이 아닙니다. README와 릴리스 노트가 모호한 성능 표현 대신 경계가 있는 숫자로 설명할 수 있게 하기 위한 근거입니다.
+여기 수치는 모든 상황에 대한 약속이 아니라 관리자 릴리스 근거입니다. 모든 값은 실제 Codex JSONL 사용량과 로컬 실행 시간(ChatGPT/Codex 인증, `gpt-5.5`)이며, 격리된 환경 — 독립 Codex home, 허용 목록 전용 환경 변수, 정결한 작업 트리, 실행 후 픽스처 검증 — 에서 시나리오당 측정 3회와 예열 1회로, Project Librarian이 없는 `organic` 대조군과 비교했습니다.
+
+아래 표에서 **“적음” / “많음”** 은 대조군 대비 비용 가중 토큰을, **“빠름” / “느림”** 은 실행 시간을 비교한 것입니다. (비용 가중 = uncached input + 0.1 × cached input + output + reasoning output. 캐시된 재전송은 정가가 아니므로 할인하며, 단순 합산 총량은 턴을 추가하는 도구를 부당하게 불리하게 만들기 때문입니다.) 위키 라우팅 트랙과 코드 그래프 트랙은 분리해 측정·보고하며, 한 트랙의 우위가 다른 트랙의 주장을 뒷받침하지 않습니다. `benchmarks/reports/llm/` 아래 생성 보고서는 기본적으로 무시됩니다. 공개 주장 근거로 쓸 릴리스 기준선만 의도적으로 커밋해야 합니다. 릴리스 후보는 다음 명령으로 재현할 수 있습니다.
+
+```bash
+npm run benchmark:release
+```
+
+### 위키 트랙 (계획 문서 라우팅)
+
+비용 가중 토큰, Project Librarian 대 대조군:
+
+| 규모 | decision_lookup | aggregation | multi_session (2번째 세션) |
+| --- | --- | --- | --- |
+| 소형 | 7.9% 적음 | 7.0% 많음 | 30.4% 적음 |
+| 중형 | 69.5% 적음 | 8.8% 많음 | 56.6% 적음 |
+| 대형 (게이트 통과 재시도) | 62.6% 적음 | 45.0% 적음* | 70.7% 적음 |
+
+주장 등급 셀(주장 게이트 통과, 전 실행 정확)은 대형의 두 승리입니다: `decision_lookup`(비용 가중 토큰 62.6% 적음, 41.5% 빠름)과 `multi_session`(토큰 70.7% 적음, 33.9% 빠름). 숨기지 않고 함께 공개하는 한계: `aggregation`은 소형/중형에서 토큰을 7~9% *더* 쓰고, 위키를 켜면 토큰이 줄어드는 규모에서도 매 규모 *더 느리며*, *대형 aggregation 수치(45.0% 적음)는 대조군 측 정확성 불안정으로 게이트가 실패한 Stage 1 실행에서 나온 값이라 주장이 아니라 조사 근거로 남습니다.
+
+### 코드 그래프 트랙 (코드 근거 인덱스, 실제 저장소)
+
+SHA로 고정한 오픈소스 저장소 2곳에서, 손으로 작성한 정답 키와 격리된 Codex home에 주입한 답변 형태 MCP 도구로 측정했습니다. 평가기 거짓 양성 2건을 고치고 원시 JSONL에서 재채점한 뒤 30/30 정확으로 주장 게이트를 통과했으며, 원시 데이터에서 다시 계산하는 것이 상시 감사 정책입니다. 비용 가중 토큰, Project Librarian 대 대조군:
+
+| 질문 | excalidraw (~1.2k 파일) | backstage (~11.8k 파일) |
+| --- | --- | --- |
+| impact_trace | 117% 많음 | **27.7% 적음** |
+| workspace_graph | 106% 많음 | 2.6% 적음 |
+| ownership_lookup | — | 99% 많음 |
+
+주장은 규모 교차점이며, 손실도 승리 옆에 함께 공개합니다. 11.8k 파일 저장소에서는 비싼 순회 질문에서 도구가 이기고(impact_trace 비용 가중 토큰 27.7% 적음, 스캔 바이트 24.5% 적음) 워크스페이스 그래프는 손익분기인 반면, 소형 저장소에서는 전부 지고 저렴한 조회(CODEOWNERS 소유권)는 모든 측정 규모에서 집니다. 한마디로, 코드 근거 인덱스는 비싼 순회 질문이 있는 진짜 대형 저장소에서만 이득이며 — 이것이 곧 CLI의 규모 인지 게이트가 구현한 내용입니다: 인덱싱 대상 파일 약 5k개 미만에서는 `--code-index`가 명시적 동의를 요구하고 부트스트랩은 MCP 자동 등록을 건너뜁니다.
 
-현재 로컬 측정 보고서: `benchmarks/reports/llm/current-local.json`, `benchmarks/reports/llm/current-local.md`, 2026-06-10 생성, ChatGPT/Codex 인증, `gpt-5.5`, `decision_lookup`, 조건별 측정 1회, 예열 없음. 아래 값은 실제 Codex JSONL usage와 로컬 wall-clock 측정값입니다. 양수 delta는 Project Librarian 조건이 미사용 control보다 더 많이 사용했다는 뜻입니다.
+### 벤치마크 용어 설명
 
-| 규모 | Project Librarian 미사용 | Project Librarian 사용 | 실제 delta |
-| --- | ---: | ---: | ---: |
-| 소형 | total 102,655 tokens; input 101,226; 37.15s; command 9회 | total 176,104 tokens; input 173,733; 61.04s; command 15회 | tokens +71.55%; time +64.33%; commands +66.67% |
-| 중형 | total 79,340 tokens; input 78,348; 44.28s; command 5회 | total 165,840 tokens; input 163,856; 48.48s; command 10회 | tokens +109.02%; time +9.5%; commands +100% |
-| 대형 | total 197,097 tokens; input 195,278; 45.87s; command 10회 | total 183,959 tokens; input 181,897; 49.42s; command 13회 | tokens -6.67%; time +7.72%; commands +30% |
+테스트 대상 저장소:
 
-주장 범위: 이 승인된 로컬 실행은 benchmark claim gate를 통과했지만 clean release baseline은 아닙니다. dirty worktree, 조건별 1회 실행이며, 런타임 상태 파일이 생성 fixture 디렉터리를 건드렸기 때문에 post-run fixture fingerprint validator는 clean isolated rerun이 필요합니다. 반복 clean actual-LLM 실행에서 안정적인 delta가 나오기 전까지 Project Librarian의 토큰/시간 개선을 주장하지 않습니다.
+- **excalidraw** — 실제 오픈소스 화이트보드/다이어그램 앱(~1.2k 파일). 소형 저장소 표본.
+- **backstage** — Spotify의 오픈소스 개발자 포털 플랫폼(~11.8k 파일). 대형 저장소 표본.
 
-## 설치
+질문 유형(task family):
 
-초기 skill 설치에만 `npx`를 사용합니다.
+- **decision_lookup** — 위키에서 가장 최근 프로젝트 결정과 그 날짜를 찾기.
+- **aggregation** — 여러 페이지에 흩어진 사실을 종합해야 답할 수 있는 질문.
+- **multi_session** — 같은 프로젝트의 두 번째 세션. 지속되는 위키가 첫 세션뿐 아니라 다음 세션에도 도움이 되는지 측정.
+- **impact_trace** — "이 모듈이 바뀌면 무엇이 영향받나?": 직접·간접으로 import하는 전체 집합을 추적.
+- **ownership_lookup** — "이 파일의 소유자는 누구인가?": CODEOWNERS 마지막 일치 우선순위로 소유자 판정.
+- **workspace_graph** — "이 패키지는 모노레포에서 무엇에 의존하나?": 워크스페이스/패키지 의존성 그래프.
+
+## 설치 상세
+
+설치 범위나 대상 에이전트를 고를 때 이 섹션을 참고합니다. 초기 스킬 설치에만 `npx`를 사용합니다.
 
 ```bash
 npx project-librarian install-skill --scope user --agents all
@@ -56,11 +126,11 @@ npx project-librarian install-skill --scope user --agents all
 npx project-librarian install-skill --scope project --agents all
 ```
 
-`install-skill`은 재사용 가능한 skill 파일만 복사합니다. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `wiki/`, `.cursor/rules/`, `.cursor/hooks.json`, `.gemini/settings.json`, `.codex/hooks.json`, `.claude/settings.json`은 만들거나 갱신하지 않습니다.
+`install-skill`은 재사용 가능한 스킬 파일만 복사합니다. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `wiki/`, `.cursor/rules/`, `.cursor/hooks.json`, `.gemini/settings.json`, `.codex/hooks.json`, `.claude/settings.json`은 만들거나 갱신하지 않습니다.
 
 | 상황 | 명령 |
 | --- | --- |
-| 지원하는 모든 agent에 전역 설치 | `npx project-librarian install-skill --scope user --agents all` |
+| 지원하는 모든 에이전트에 전역 설치 | `npx project-librarian install-skill --scope user --agents all` |
 | 현재 저장소에 설치 | `npx project-librarian install-skill --scope project --agents all` |
 | Codex만 설치 | `npx project-librarian install-skill --agents codex` |
 | Claude Code만 설치 | `npx project-librarian install-skill --agents claude` |
@@ -68,79 +138,73 @@ npx project-librarian install-skill --scope project --agents all
 | Gemini CLI만 설치 | `npx project-librarian install-skill --agents gemini` |
 | 설치 결과 미리 보기 | `npx project-librarian install-skill --scope project --agents all --dry-run` |
 
-`--agents`는 `codex,claude,cursor,gemini` 같은 comma-separated 값도 받습니다. `all`은 지원하는 모든 agent를 대상으로 하며, `both`는 Codex/Claude 호환 alias입니다. `--scope`는 `user` 또는 `project`를 받습니다.
+`--agents`는 `codex,claude,cursor,gemini`처럼 쉼표로 구분한 값도 받습니다. `all`은 지원하는 모든 에이전트를 대상으로 합니다. `--scope`는 `user` 또는 `project`를 받습니다.
 
-## 에이전트 실행 경로
+## 실행 경로
 
-설치 후 에이전트는 `npx`가 아니라 설치된 로컬 복사본을 `node`로 실행해야 합니다. 이렇게 하면 제한된 에이전트 환경에서 네트워크 접근과 고정되지 않은 패키지 실행을 피할 수 있습니다.
+이 경로들은 주로 에이전트와 자동화를 위한 참조입니다. 설치 후 에이전트는 `npx`가 아니라 설치된 로컬 복사본을 `node`로 실행해야 합니다. 이렇게 하면 제한된 에이전트 환경에서 네트워크 접근과 버전이 고정되지 않은 패키지 실행을 피할 수 있습니다.
 
 | 설치 위치 | 실행 경로 |
 | --- | --- |
-| 프로젝트 범위 Codex skill | `node .codex/skills/project-librarian/dist/init-project-wiki.js` |
-| 프로젝트 범위 Claude skill | `node .claude/skills/project-librarian/dist/init-project-wiki.js` |
-| 프로젝트 범위 Cursor skill | `node .cursor/skills/project-librarian/dist/init-project-wiki.js` |
-| 프로젝트 범위 Gemini skill | `node .gemini/skills/project-librarian/dist/init-project-wiki.js` |
-| 사용자 범위 Codex skill | `node ~/.codex/skills/project-librarian/dist/init-project-wiki.js` |
-| 사용자 범위 Claude skill | `node ~/.claude/skills/project-librarian/dist/init-project-wiki.js` |
-| 사용자 범위 Cursor skill | `node ~/.cursor/skills/project-librarian/dist/init-project-wiki.js` |
-| 사용자 범위 Gemini skill | `node ~/.gemini/skills/project-librarian/dist/init-project-wiki.js` |
-
-아래 예시는 다음 runner를 사용합니다.
-
-```bash
-PROJECT_LIBRARIAN="node .codex/skills/project-librarian/dist/init-project-wiki.js"
-```
-
-설치 위치에 맞는 로컬 실행 경로를 사용하세요.
-
-## 일반 에이전트 작업 흐름
-
-프로젝트 루트에서 위키를 만들거나 갱신합니다.
-
-```bash
-$PROJECT_LIBRARIAN
-```
-
-위키 검증과 유지보수:
-
-| 목적 | 에이전트 명령 |
-| --- | --- |
-| wiki 생성 또는 갱신 | `$PROJECT_LIBRARIAN` |
-| 기존 docs/wiki 마이그레이션 | `$PROJECT_LIBRARIAN --migrate` |
-| 생성된 설정 검증 | `$PROJECT_LIBRARIAN --lint` |
-| 링크와 문서 품질 점검 | `$PROJECT_LIBRARIAN --doctor` |
-| 진단 전에 생성된 라우팅 갱신 | `$PROJECT_LIBRARIAN --doctor --fix` |
-| project wiki 검색 | `$PROJECT_LIBRARIAN --query "authentication decisions"` |
-| 후보 메모 저장 | `$PROJECT_LIBRARIAN --capture-inbox --title "Candidate" --content "Details"` |
-| 오래되었거나 미해결인 위키 페이지 보고 | `$PROJECT_LIBRARIAN --prune-check` |
-| git config 변경 없이 훅 파일 설치 | `$PROJECT_LIBRARIAN --no-git-config` |
+| 프로젝트 범위 Codex 스킬 | `node .codex/skills/project-librarian/dist/init-project-wiki.js` |
+| 프로젝트 범위 Claude 스킬 | `node .claude/skills/project-librarian/dist/init-project-wiki.js` |
+| 프로젝트 범위 Cursor 스킬 | `node .cursor/skills/project-librarian/dist/init-project-wiki.js` |
+| 프로젝트 범위 Gemini 스킬 | `node .gemini/skills/project-librarian/dist/init-project-wiki.js` |
+| 사용자 범위 Codex 스킬 | `node ~/.codex/skills/project-librarian/dist/init-project-wiki.js` |
+| 사용자 범위 Claude 스킬 | `node ~/.claude/skills/project-librarian/dist/init-project-wiki.js` |
+| 사용자 범위 Cursor 스킬 | `node ~/.cursor/skills/project-librarian/dist/init-project-wiki.js` |
+| 사용자 범위 Gemini 스킬 | `node ~/.gemini/skills/project-librarian/dist/init-project-wiki.js` |
+
+## 일반 에이전트 요청
+
+원하는 결과를 자연어로 요청하면 됩니다. 스킬은 내부적으로 요청을 로컬 실행 경로에 맞는 명령으로 연결합니다.
+
+위키 설정과 유지보수:
+
+| 목적 | 에이전트에게 요청할 말 | 내부 액션 |
+| --- | --- | --- |
+| 위키 생성 또는 갱신 | "Project Librarian으로 이 저장소의 계획 위키를 설정하거나 갱신해줘." | `[init]` |
+| 기존 문서/위키 마이그레이션 | "Project Librarian으로 기존 docs/wiki 내용을 마이그레이션해줘." | `--migrate` |
+| 생성된 설정 검증 | "Project Librarian 검증을 실행해줘." | `--lint` |
+| 링크와 문서 품질 점검 | "Project Librarian 진단을 실행해줘." | `--doctor` |
+| 진단 전에 생성된 라우팅 갱신 | "Project Librarian 라우팅을 갱신한 뒤 진단을 실행해줘." | `--doctor --fix` |
+| 위키 내용 검색 | "Project Librarian 위키에서 authentication decisions를 찾아줘." | `--query "authentication decisions"` |
+| 페이지의 역링크/결정 인용 확인 | "decisions/release-policy의 Project Librarian 위키 영향도를 보여줘." | `--wiki-impact "decisions/release-policy"` |
+| 후보 메모 저장 | "이 내용을 Project Librarian 후보 메모로 저장해줘: <내용>." | `--capture-inbox --title "Candidate" --content "Details"` |
+| 오래되었거나 미해결인 위키 페이지 보고 | "Project Librarian에서 오래되었거나 미해결인 페이지를 확인해줘." | `--prune-check` |
+| git 설정 변경 없이 훅 파일 설치 | "git 설정은 바꾸지 말고 Project Librarian 훅 파일만 설정해줘." | `--no-git-config` |
 
 코드 근거:
 
-| 목적 | 에이전트 명령 |
-| --- | --- |
-| 기본 근거 캐시 생성 | `$PROJECT_LIBRARIAN --code-index --code-scope src` |
-| 여러 범위 빌드 | `$PROJECT_LIBRARIAN --code-index --code-scope src --code-scope packages/api` |
-| 증분 갱신 요구 | `$PROJECT_LIBRARIAN --code-index --incremental` |
-| 전체 재생성 강제 | `$PROJECT_LIBRARIAN --code-index --code-index-full` |
-| 선택적 Tree-sitter backend 사용 | `$PROJECT_LIBRARIAN --code-index --code-parser tree-sitter` |
-| 캐시 상태 보기 | `$PROJECT_LIBRARIAN --code-status` |
-| 인덱싱된 파일 목록 | `$PROJECT_LIBRARIAN --code-files` |
-| 아키텍처/소유권 보고서 출력 | `$PROJECT_LIBRARIAN --code-report` |
-| 보고서 섹션 하나만 출력 | `$PROJECT_LIBRARIAN --code-report --code-report-section routes` |
-| 영향 근거 확인 | `$PROJECT_LIBRARIAN --code-impact healthHandler` |
-| 인덱싱된 심볼 검색 | `$PROJECT_LIBRARIAN --code-search-symbol Auth` |
-| 보수적인 읽기 전용 SQL 실행 | `$PROJECT_LIBRARIAN --code-query "select path from files order by path"` |
+| 목적 | 에이전트에게 요청할 말 | 내부 액션 |
+| --- | --- | --- |
+| 기본 근거 캐시 생성 | "`src`에 대해 Project Librarian 코드 근거를 만들어줘." | `--code-index --code-scope src` |
+| 여러 범위 빌드 | "`src`와 `packages/api`에 대해 Project Librarian 코드 근거를 만들어줘." | `--code-index --code-scope src --code-scope packages/api` |
+| 증분 갱신 요구 | "Project Librarian 코드 근거 인덱스를 증분 갱신해줘." | `--code-index --incremental` |
+| 전체 재생성 강제 | "Project Librarian 코드 근거 인덱스를 전체 재생성해줘." | `--code-index --code-index-full` |
+| 선택적 Tree-sitter 백엔드 사용 | "Tree-sitter 파서로 Project Librarian 코드 근거를 만들어줘." | `--code-index --code-parser tree-sitter` |
+| 캐시 상태 보기 | "Project Librarian 코드 근거 상태를 보여줘." | `--code-status` |
+| 인덱싱된 파일 목록 | "Project Librarian 코드 근거에 인덱싱된 파일을 보여줘." | `--code-files` |
+| 아키텍처/소유권 보고서 출력 | "Project Librarian 코드 보고서를 보여줘." | `--code-report` |
+| 보고서 섹션 하나만 출력 | "Project Librarian 코드 보고서의 routes 섹션을 보여줘." | `--code-report --code-report-section routes` |
+| 영향 근거 확인 | "`healthHandler`에 대한 Project Librarian 영향 근거를 보여줘." | `--code-impact healthHandler` |
+| 인덱싱된 심볼 검색 | "Project Librarian 코드 근거에서 `Auth` 심볼을 찾아줘." | `--code-search-symbol Auth` |
+| 보수적인 읽기 전용 SQL 실행 | "파일 경로를 확인하는 읽기 전용 Project Librarian 코드 근거 쿼리를 실행해줘." | `--code-query "select path from files order by path"` |
 
 코드 근거 모드는 한 번에 하나만 실행할 수 있습니다. `--incremental`, `--code-index-full`, `--code-parser`는 `--code-index`와 함께 쓸 때만 유효합니다.
 
 ## 설치되는 파일
 
+프로젝트 지침 파일:
+
 - `AGENTS.md`
 - `CLAUDE.md`
 - `GEMINI.md`
 - `wiki/AGENTS.md`
 - `.cursor/rules/project-librarian.mdc`
+
+시작 훅:
+
 - `.codex/hooks.json`
 - `.codex/hooks/wiki-session-start.js`
 - `.claude/settings.json`
@@ -149,31 +213,85 @@ $PROJECT_LIBRARIAN
 - `.cursor/hooks/wiki-session-start.js`
 - `.gemini/settings.json`
 - `.gemini/hooks/wiki-session-start.js`
+
+Git 훅 파일:
+
 - `.githooks/prepare-commit-msg`
 - `.githooks/wiki-commit-trailers.js`
-- `wiki/canonical/`, `wiki/decisions/`, `wiki/inbox/`, `wiki/meta/`, `wiki/sources/`, `wiki/migration/`
-- 폐기 가능한 코드 근거 캐시인 `.project-wiki/code-evidence.sqlite`
+
+위키 디렉터리:
+
+- `wiki/canonical/`
+- `wiki/decisions/`
+- `wiki/inbox/`
+- `wiki/meta/`
+- `wiki/sources/`
+- `wiki/migration/`
+
+초기 위키 페이지와 라우터:
+
+- `wiki/startup.md`
+- `wiki/index.md`
+- `wiki/meta/document-taxonomy.md`
+
+`canonical/project-brief.md`, `canonical/open-questions.md`, `canonical/assumptions.md`, `canonical/risks.md`, ADR 템플릿처럼 실제 내용이 없는 빈 프로젝트 문서는 기본 생성하지 않습니다. 나중에 실제 내용이 생기면 문서를 만들고 `--refresh-index`로 라우팅할 수 있습니다. 마이그레이션 중 발견한 양식 전용 legacy 템플릿은 새 위키 페이지나 검토 row로 만들지 않고 `wiki/migration/inventory.md`에 스킵 사유만 남깁니다.
+
+MCP 서버 등록 (`mcpServers`에 기존 항목 보존하며 병합):
+
+- `.mcp.json` (Claude Code)
+- `.cursor/mcp.json` (Cursor)
+- `.gemini/settings.json`의 `mcpServers` (Gemini CLI)
+
+폐기 가능한 코드 근거 캐시:
+
+- `.project-wiki/code-evidence.sqlite`
+
+## 코드 근거 MCP 서버
+
+`project-librarian mcp`는 직접 구현한 stdio MCP 서버(줄바꿈 구분 JSON 위의 JSON-RPC 2.0, 추가 런타임 의존성 없음)를 실행해 기존 `.project-wiki` 코드 근거 인덱스를 읽기 전용으로 제공합니다. 답변 형태 도구 — `code_impact`, `code_ownership`(CODEOWNERS 마지막 일치 우선순위), `code_workspace_graph`, `code_search`, `code_status` — 를 노출하며, 각 응답은 한 줄 답변으로 시작해 간결한 경로/심볼/시그니처 근거가 뒤따르고, 응답마다 길이를 제한하며, `code_status`가 인덱스가 오래되었다고 보고하면 경고를 앞에 붙입니다.
+
+부트스트랩은 Claude Code(`.mcp.json`), Cursor(`.cursor/mcp.json`), Gemini CLI(`.gemini/settings.json`의 `mcpServers`)에 서버를 등록하며, 기존 서버와 키를 보존하고 다시 실행하면 `exists`를 보고합니다. 저장소에 로컬 실행 경로가 있으면 `node <runner> mcp`로, 없으면 설치된 `project-librarian mcp` 바이너리로 등록합니다.
+
+Codex는 MCP 서버를 사용자 레벨에서만 등록(`codex mcp add`)하므로 부트스트랩은 프로젝트 레벨 Codex MCP 설정을 작성하지 않습니다. Codex에서 서버를 쓰려면 머신당 한 번 실행하세요.
+
+```bash
+codex mcp add project-librarian -- node .codex/skills/project-librarian/dist/init-project-wiki.js mcp
+```
 
 ## 작동 방식
 
-1. Bootstrap은 보존 우선 위키 구조와 marker로 경계가 정해진 에이전트 지시 섹션을 만듭니다.
+1. 부트스트랩은 기존 내용 보존을 우선하는 위키 구조와 마커로 경계를 둔 에이전트 지침 섹션을 만듭니다.
 2. 세션 시작 훅은 문자 예산이 적용된 `wiki/startup.md`와 `wiki/index.md`만 주입합니다.
-3. 상세 계획 정본은 canonical, decision, source, meta page에 있고 에이전트가 필요할 때 읽습니다.
-4. `--refresh-index`는 새 위키 페이지를 라우팅하며, route가 많으면 `wiki/indexes/auto-*.md` 범위별 라우터로 분리합니다.
-5. `--code-index`는 `.project-wiki/` 아래 폐기 가능한 SQLite 근거 캐시를 만듭니다.
-6. `--code-report`, `--code-impact`, `--code-search-symbol`, `--code-query`가 계획 갱신용 코드 근거를 제공합니다.
-7. 진단은 깨진 링크, 중복 route, orphan page, 오래된 페이지, 누락된 TL;DR, 근거 gap, 마이그레이션 정책 위반을 보고합니다.
+3. 부트스트랩은 내용 없는 양식 전용 프로젝트 페이지를 만들지 않으며, 초점이 분명한 정본·결정·출처·운영 문서는 실제 내용이 있을 때 생성됩니다.
+4. 상세 계획 정본은 정본·결정·출처·운영 문서에 있고 에이전트가 필요할 때 읽습니다.
+5. 새 프로젝트 계획 내용은 작성하거나 취합하기 전에 `wiki/meta/document-taxonomy.md`로 분류해 상위/하위 문서 관계가 보이도록 유지합니다.
+6. `--refresh-index`는 새로 발견한 위키 페이지를 라우팅하며, route가 많으면 `wiki/indexes/auto-*.md` 범위별 라우터로 분리합니다.
+7. `--code-index`는 `.project-wiki/` 아래 폐기 가능한 SQLite 근거 캐시를 만듭니다.
+8. `--code-report`, `--code-impact`, `--code-search-symbol`, `--code-query`가 계획 갱신용 코드 근거를 제공합니다.
+9. 진단은 깨진 링크, 중복 route, 고아 페이지, 오래된 페이지, 누락된 TL;DR, 근거 누락, 마이그레이션 정책 위반을 보고합니다.
 
-마이그레이션은 검토 우선입니다. `--migrate`는 기존 `wiki/`를 `wiki_legacy*`로 보존하고 마이그레이션 inbox와 unit-level coverage ledger를 작성하며, legacy 의미를 현재 wiki 규칙에 맞게 재구성합니다. 보존하거나 복사한 legacy 내용은 새 wiki 정책과 구조에 맞으면 허용되며, 새 wiki가 `wiki_legacy*` 참조에 의존하면 안 됩니다.
+마이그레이션은 검토를 우선합니다. `--migrate`는 기존 `wiki/`를 `wiki_legacy*`로 보존하고, 양식 전용 legacy 파일은 제외한 뒤, 여러 성격의 내용이 섞인 기존 페이지를 의미 단위로 나눕니다. 이후 각 단위를 문서 분류 체계에 따라 분류해 `wiki/migration/` 아래 검토 파일을 작성합니다.
+
+- `inventory.md`는 기존 마크다운 파일 목록과 파일 단위 분류를 기록합니다.
+- `unit-map.md`는 각 제목, 문단, 목록 항목, 표 행, 코드 블록의 권장 분류 영역과 대상 페이지를 기록합니다.
+- `split-plan.md`는 권장 새 위키 대상별로 의미 단위를 묶습니다. 그래서 API 명세, 기능, UX, QA, 정책, 운영 내용이 한 기존 페이지에 섞여 있어도 서로 다른 파일로 재작성할 수 있습니다.
+- `coverage.md`는 각 단위의 편집 가능한 상태 장부입니다. 상태는 pending, adopted, merged, superseded, rejected, resolved, needs-human-review입니다.
+- `verification.md`와 `review.md`는 `--review-migration` 후 커버리지와 의미적 완료 상태를 요약합니다.
+
+`--migration-lint`는 `coverage.md`, `unit-map.md`, `split-plan.md`가 현재 마이그레이션 배치의 단위를 계속 빠짐없이 다루는지 검증합니다. 중복/오래된 단위 ID, 잘못된 storage/confidence/status 값, split count 불일치, target drift, 오래된 coverage 표 형식을 잡습니다. 기존 페이지 하나가 여러 대상 파일로 나뉘는 경우 `--review-migration`은 파일 단위 수신함 상태만으로 모든 단위를 완료 처리하지 않으며, 단위별 coverage가 해결되어야 합니다.
+
+보존하거나 복사한 legacy 내용은 새 위키 정책과 구조에 맞으면 허용되며, 새 위키가 `wiki_legacy*` 참조에 의존해서는 안 됩니다.
 
 ## 언어 지원 표
 
+이 표는 심볼/import 추출이 구현된 언어를 나열합니다. 그 외 인식되는 확장자는 목록 전용입니다. 기본 모드는 `typescript-ast`, `python-light`, `go-light`, 설정 추출, 목록 항목을 사용합니다. `--code-parser tree-sitter`는 지원되는 소스 파일을 `tree-sitter-*` 프로파일로 전환합니다.
+
 | 언어 | 확장자 | 기본 추출 | Tree-sitter 추출 | 인덱싱되는 근거 |
 | --- | --- | --- | --- | --- |
 | TypeScript | `.ts`, `.tsx`, `.cts`, `.mts` | `typescript-ast` | `tree-sitter-typescript`, `tree-sitter-tsx` | 함수, 클래스, 메서드, 변수, 인터페이스, 타입, enum, import, export, 호출, 일반 HTTP route |
 | JavaScript | `.js`, `.jsx`, `.cjs`, `.mjs` | `typescript-ast` | `tree-sitter-javascript` | 함수, 클래스, 메서드, 변수, import, export, `require()` 호출, 일반 HTTP route |
 | Python | `.py` | `python-light` | `tree-sitter-python` | 함수, 클래스, `import`, `from ... import` |
-| Go | `.go` | `go-light` | `tree-sitter-go` | 함수, 메서드, 타입, const, var, 단일 import, import block |
+| Go | `.go` | `go-light` | `tree-sitter-go` | 함수, 메서드, 타입, const, var, 단일 import, import 블록 |
 | Rust | `.rs` | 목록 전용 | `tree-sitter-rust` | 함수, struct, enum, trait, impl, `use` import |
 | Java | `.java` | 목록 전용 | `tree-sitter-java` | 클래스, interface, enum, 메서드, import |
 | PHP | `.php` | 목록 전용 | `tree-sitter-php` | 함수, 클래스, interface, trait, 메서드, namespace use |
@@ -183,21 +301,51 @@ $PROJECT_LIBRARIAN
 | C++ | `.cc`, `.cpp`, `.cxx`, `.hpp`, `.hh`, `.hxx` | 목록 전용 | `tree-sitter-cpp` | 함수, class/struct, namespace, enum, include/using |
 | C# | `.cs` | 목록 전용 | `tree-sitter-csharp` | class, interface, struct, enum, 메서드, using |
 
-`.rb`, `.vue`, `.css`는 인식되지만 목록 전용입니다. 설정 파일은 설정 근거 또는 목록 근거로 인덱싱됩니다.
+인식되지만 목록 전용인 확장자에는 `.rb`, `.vue`, `.css`가 있습니다. 설정 파일(`.json`, `.yaml`, `.yml`, `.toml`, `.env.example`, `package.json`, `tsconfig.json`, `Dockerfile`, `Makefile`)은 설정 근거 또는 목록 근거로 인덱싱됩니다.
 
 ## CLI 참조
 
-에이전트 실행에는 로컬 실행 경로를 사용합니다.
+자동화나 직접 CLI 실행에는 확인된 로컬 실행 경로를 사용합니다.
 
 ```bash
-$PROJECT_LIBRARIAN [init] [options]
-$PROJECT_LIBRARIAN install-skill [--scope user|project] [--agents codex|claude|cursor|gemini|all|both]
+node .codex/skills/project-librarian/dist/init-project-wiki.js [init] [options]
+node .codex/skills/project-librarian/dist/init-project-wiki.js install-skill [--scope user|project] [--agents codex|claude|cursor|gemini|all]
 ```
 
-중요 옵션: `--migrate`, `--lint`, `--link-check`, `--quality-check`, `--doctor`, `--doctor --fix`, `--migration-lint`, `--migration-quality-check`, `--migration-doctor`, `--query`, `--refresh-index`, `--capture-inbox`, `--issue-draft`, `--issue-create`, `--glossary-init`, `--prune-check`, `--review-migration`, `--no-git-config`, `--code-index`, `--code-report`, `--code-impact`, `--code-search-symbol`, `--code-query`.
+중요 옵션:
+
+| 옵션 | 용도 |
+| --- | --- |
+| `--migrate`, `--adopt-existing` | 기존 위키를 `wiki_legacy*`로 보존하고 마이그레이션 수신함, unit-map, split-plan, coverage 검토 파일을 만듭니다. |
+| `--lint` | 파일을 수정하지 않고 생성된 설정을 검증합니다. |
+| `--link-check` | 깨진 위키 링크, 중복 route, 고아 페이지, 그리고 시작 라우터가 깊이 예산 안에서 닿지 못하는 페이지를 보고합니다. |
+| `--quality-check` | 오래되거나 충돌하거나 품질이 낮은 위키 문서 신호를 보고합니다. |
+| `--doctor` | lint, link-check, quality-check를 함께 실행합니다. |
+| `--doctor --fix` | 진단 전에 생성된 index 라우팅을 안전하게 갱신합니다. |
+| `--migration-lint` | 마이그레이션 coverage, unit-map, split-plan, 검토 골격을 일반 lint와 분리해 검증합니다. |
+| `--migration-quality-check` | 마이그레이션 정책/구조 신호를 일반 quality-check와 분리해 보고합니다. |
+| `--migration-doctor` | migration-lint와 migration-quality-check를 함께 실행합니다. |
+| `--query <terms>` | 위키 경로, 메타데이터, 제목, 본문을 검색합니다. 답변 우선 출력에 페이지별 TL;DR 줄을 붙이고 고정 크기 상한을 적용합니다. |
+| `--wiki-impact <page-or-term>` | 일치하는 페이지의 위키 역링크, `decision_ref` 인용, 나가는 링크, 라우터 깊이를 보여줍니다. |
+| `--refresh-index` | 생성된 자동 발견 위키 라우팅을 갱신합니다. |
+| `--capture-inbox --title <title> --content <content>` | 위키 수신함에 후보 메모를 추가합니다. |
+| `--issue-draft --issue-title <title>` | 문제 또는 부작용에 대한 읽기 전용 GitHub 이슈 본문 초안을 출력합니다. |
+| `--issue-create --issue-title <title>` | 명시적 사용자 승인 후 `gh`로 GitHub 이슈를 생성합니다. |
+| `--glossary-init` | 선택적 용어집 페이지를 만들고 라우팅합니다. |
+| `--prune-check` | 오래되거나 미해결인 수명 주기 신호가 있는 active 페이지를 보고합니다. |
+| `--review-migration`, `--semantic-migrate` | 마이그레이션 coverage와 수신함 상태를 마이그레이션 검토 파일에 동기화합니다. |
+| `--no-git-config` | `git core.hooksPath`를 바꾸지 않고 훅 파일을 설치합니다. |
+| `--code-index` | 폐기 가능한 코드 근거 인덱스를 빌드합니다. |
+| `--code-report` | 근거 인덱스에서 아키텍처/소유권 요약을 출력합니다. |
+| `--code-report-section <section>` | 한 섹션만 출력: `coverage`, `ownership`, `languages`, `parsers`, `workspaces`, `workspace-graph`, `routes`, `hotspots`, `configs`, `edges`. |
+| `--code-impact <term>` | 파일, 심볼, route, import, edge, 소유자 영향 근거를 보여줍니다. |
+| `--code-search-symbol <term>` | 인덱싱된 심볼을 검색합니다. |
+| `--code-query <sql>` | 근거 인덱스에 대해 보수적인 읽기 전용 SQL을 실행합니다. |
 
 ## 개발
 
+소스는 TypeScript입니다. 커밋된 `dist/` 디렉터리는 npm 바이너리와 설치된 스킬 복사본이 사용하는 컴파일된 JavaScript입니다.
+
 ```bash
 npm install
 npm run typecheck
@@ -206,11 +354,15 @@ npm test
 npm pack --dry-run
 ```
 
-관리자 벤치마크 명령은 [benchmarks/README.md](benchmarks/README.md)에 있습니다. 이 명령은 릴리스 근거와 공개 주장 검증을 위한 것이며, 일반 최종 사용자 설정 절차가 아닙니다.
+`src/` 아래 TypeScript를 수정할 때는 커밋 전에 빌드해 `dist/`를 최신 상태로 유지하세요.
+
+관리자 벤치마크 명령은 [benchmarks/README.md](benchmarks/README.md)에 있습니다. 이 명령은 릴리스 근거와 공개 주장 검증을 위한 것이며, 일반 사용자 설정 절차가 아닙니다.
 
 ## 영감
 
-이 프로젝트는 Andrej Karpathy의 [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) 패턴에서 영감을 받았습니다.
+이 프로젝트는 Andrej Karpathy의 [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) 패턴에서 영감을 받았습니다. 긴 대화 기록에서 프로젝트 상태를 재구성하는 대신, 지속되는 markdown 컨텍스트를 작업 가까이에 둡니다.
+
+Project Librarian은 그 아이디어를 저장소 로컬 지침, 간결한 시작 훅, 마이그레이션 도구, 진단, 선택적 코드 근거를 갖춘 Codex, Claude Code, Cursor, Gemini CLI용 설치형 CLI 및 스킬로 구현합니다.
 
 ## 라이선스