project-librarian 0.3.0 → 0.4.0

package/README.ko.md

@@ -38,6 +38,7 @@ npx project-librarian install-skill --scope project --agents all
 - **첫 읽기를 작게.** 세션 시작 훅은 `wiki/startup.md`와 `wiki/index.md`만 주입하고, 에이전트는 저장소 전체를 처음부터 훑는 대신 필요할 때 더 깊은 페이지로 이동합니다.
 - **한 번 설정, 네 에이전트.** Codex, Claude Code, Cursor, Gemini CLI가 같은 위키 우선 계약과 훅, 규칙을 공유합니다.
 - **구조적인 위키 작성.** 새 프로젝트 내용은 작성하거나 취합하기 전에 `wiki/meta/document-taxonomy.md`로 분류하므로 PRD, 정책, UX, 데이터, API, QA, 릴리즈, 운영 메모가 하나의 잡다한 페이지로 합쳐지지 않습니다.
+- **검토 가능한 위키 그래프.** `--wiki-visualize`는 `.project-wiki/` 아래에 독립 실행형 HTML 그래프를 작성해, 시작 컨텍스트를 늘리지 않고 페이지 유형·라우터 깊이·역링크·결정 참조를 보여줍니다.
 - **막연한 표현이 아니라 측정값.** 모든 성능 주장은 격리된 Codex 벤치마크에서 나오며, 손해를 본 경우도 이긴 경우 바로 옆에 보여 줍니다.
 - **선택적 코드 근거.** 재생성 가능한 SQLite 인덱스와 답변 형태 MCP 도구가 영향·소유권·워크스페이스 그래프 질문에 답하며, 추가 런타임 의존성이 전혀 없습니다.
 - **다시 실행해도 안전.** 부트스트랩은 멱등하고 기존 내용 보존을 우선하며, 진단은 깨진 경로·도달 불가 페이지·오래된 사실을 에이전트가 오해하기 전에 잡아냅니다.
@@ -56,6 +57,7 @@ Project Librarian은 에이전트에게 두 가지 로컬 정본을 제공합니
 | `.codex/`, `.claude/`, `.cursor/`, `.gemini/` 훅 | 전체 위키를 불러오지 않는 Codex/Claude Code/Cursor/Gemini CLI 시작 컨텍스트. |
 | `GEMINI.md` 및 `.cursor/rules/` | Gemini CLI와 Cursor를 같은 간결한 위키 우선 계약으로 안내하는 지침 파일. |
 | `.project-wiki/code-evidence.sqlite` | 파일, 심볼, import, route, 소유권, 워크스페이스 그래프, 보고서, 영향 확인을 위한 재생성 가능한 코드 근거. |
+| `.project-wiki/wiki-graph.html` | 파생 concept type, 라우터 도달성, 링크, 역링크, 결정 참조를 보여주는 선택적 정적 위키 그래프 시각화. |
 | 진단 및 마이그레이션 모드 | 링크 확인, 품질 확인, 마이그레이션 수신함, 오래된 신호 보고, 작업 흐름에서 문제가 드러날 때의 이슈 초안. |
 
 핵심은 “문서를 더 많이 쓰자”가 아닙니다. 첫 에이전트 읽기량을 작게 유지하고, 더 깊은 프로젝트 정본과 코드 근거로 가는 신뢰 가능한 경로를 제공하는 것입니다.
@@ -69,7 +71,8 @@ Project Librarian은 에이전트에게 두 가지 로컬 정본을 제공합니
 아래 표에서 **“적음” / “많음”** 은 대조군 대비 비용 가중 토큰을, **“빠름” / “느림”** 은 실행 시간을 비교한 것입니다. (비용 가중 = uncached input + 0.1 × cached input + output + reasoning output. 캐시된 재전송은 정가가 아니므로 할인하며, 단순 합산 총량은 턴을 추가하는 도구를 부당하게 불리하게 만들기 때문입니다.) 위키 라우팅 트랙과 코드 그래프 트랙은 분리해 측정·보고하며, 한 트랙의 우위가 다른 트랙의 주장을 뒷받침하지 않습니다. `benchmarks/reports/llm/` 아래 생성 보고서는 기본적으로 무시됩니다. 공개 주장 근거로 쓸 릴리스 기준선만 의도적으로 커밋해야 합니다. 릴리스 후보는 다음 명령으로 재현할 수 있습니다.
 
 ```bash
-npm run benchmark:release
+npm run benchmark:release:preview
+npm run benchmark:release -- --allow-codex-run
 ```
 
 ### 위키 트랙 (계획 문서 라우팅)
@@ -78,11 +81,11 @@ npm run benchmark:release
 
 | 규모 | decision_lookup | aggregation | multi_session (2번째 세션) |
 | --- | --- | --- | --- |
-| 소형 | 7.9% 적음 | 7.0% 많음 | 30.4% 적음 |
-| 중형 | 69.5% 적음 | 8.8% 많음 | 56.6% 적음 |
-| 대형 (게이트 통과 재시도) | 62.6% 적음 | 45.0% 적음* | 70.7% 적음 |
+| 소형 | 43.8% 적음 | 144.5% 많음 | 5.4% 많음 |
+| 중형 | 53.4% 적음 | 4.4% 적음 | 68.5% 적음 |
+| 대형 | 71.6% 적음* | 12.8% 적음 | 66.0% 적음 |
 
-주장 등급 셀(주장 게이트 통과, 전 실행 정확)은 대형의 두 승리입니다: `decision_lookup`(비용 가중 토큰 62.6% 적음, 41.5% 빠름)과 `multi_session`(토큰 70.7% 적음, 33.9% 빠름). 숨기지 않고 함께 공개하는 한계: `aggregation`은 소형/중형에서 토큰을 7~9% *더* 쓰고, 위키를 켜면 토큰이 줄어드는 규모에서도 매 규모 *더 느리며*, *대형 aggregation 수치(45.0% 적음)는 대조군 측 정확성 불안정으로 게이트가 실패한 Stage 1 실행에서 나온 값이라 주장이 아니라 조사 근거로 남습니다.
+최신 합성 위키 트랙 릴리스 후보는 2026-06-16에 `gpt-5.5`로 측정했으며, 42개 시나리오를 각 3회 측정하고 1회 예열했습니다. 전체 주장 게이트는 **실패**했습니다. 42개 중 41개 시나리오는 정확성 검사를 통과했지만, Project Librarian이 없는 대형 `decision_lookup` 대조군이 3회 중 2회만 정답이었습니다. 실패한 대조군 실행은 기대한 최신 benchmark evidence 결정인 `2026-06-10` decision log 항목 대신, dated history 파일의 `2026-05-04` 항목을 골랐습니다. 따라서 이 표는 공개 릴리스 주장이 아니라 진단 근거로만 보아야 하며, 깨끗한 릴리스 실행이 주장 게이트를 통과해야 공개 주장으로 쓸 수 있습니다. 숨기지 않는 한계도 그대로 남습니다. 소형 `aggregation`은 위키를 켰을 때 훨씬 비싸고, 소형 `multi_session`도 약간 더 비싸며, `aggregation`은 토큰 비용이 줄어드는 규모에서도 실행 시간은 매번 더 느립니다.
 
 ### 코드 그래프 트랙 (코드 근거 인덱스, 실제 저장소)
 
@@ -164,12 +167,14 @@ npx project-librarian install-skill --scope project --agents all
 | 목적 | 에이전트에게 요청할 말 | 내부 액션 |
 | --- | --- | --- |
 | 위키 생성 또는 갱신 | "Project Librarian으로 이 저장소의 계획 위키를 설정하거나 갱신해줘." | `[init]` |
+| 마이그레이션 없이 기존 설정 갱신 | "위키를 마이그레이션하지 말고 이 저장소의 Project Librarian 설정을 갱신해줘." | `update` |
 | 기존 문서/위키 마이그레이션 | "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 위키 그래프 시각화를 생성해줘." | `--wiki-visualize` |
 | 후보 메모 저장 | "이 내용을 Project Librarian 후보 메모로 저장해줘: <내용>." | `--capture-inbox --title "Candidate" --content "Details"` |
 | 오래되었거나 미해결인 위키 페이지 보고 | "Project Librarian에서 오래되었거나 미해결인 페이지를 확인해줘." | `--prune-check` |
 | git 설정 변경 없이 훅 파일 설치 | "git 설정은 바꾸지 말고 Project Librarian 훅 파일만 설정해줘." | `--no-git-config` |
@@ -188,6 +193,7 @@ npx project-librarian install-skill --scope project --agents all
 | 아키텍처/소유권 보고서 출력 | "Project Librarian 코드 보고서를 보여줘." | `--code-report` |
 | 보고서 섹션 하나만 출력 | "Project Librarian 코드 보고서의 routes 섹션을 보여줘." | `--code-report --code-report-section routes` |
 | 영향 근거 확인 | "`healthHandler`에 대한 Project Librarian 영향 근거를 보여줘." | `--code-impact healthHandler` |
+| 컨텍스트 팩 생성 | "`healthHandler`에 대한 Project Librarian 컨텍스트 팩을 만들어줘." | `--code-context-pack healthHandler` |
 | 인덱싱된 심볼 검색 | "Project Librarian 코드 근거에서 `Auth` 심볼을 찾아줘." | `--code-search-symbol Auth` |
 | 보수적인 읽기 전용 SQL 실행 | "파일 경로를 확인하는 읽기 전용 Project Librarian 코드 근거 쿼리를 실행해줘." | `--code-query "select path from files order by path"` |
 
@@ -248,7 +254,9 @@ MCP 서버 등록 (`mcpServers`에 기존 항목 보존하며 병합):
 
 ## 코드 근거 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`가 인덱스가 오래되었다고 보고하면 경고를 앞에 붙입니다.
+`project-librarian mcp`는 직접 구현한 stdio MCP 서버(줄바꿈 구분 JSON 위의 JSON-RPC 2.0, 추가 런타임 의존성 없음)를 실행해 기존 `.project-wiki` 코드 근거 인덱스를 읽기 전용으로 제공합니다. 답변 형태 도구 — `code_context_pack`, `code_impact`, `code_ownership`(CODEOWNERS 마지막 일치 우선순위), `code_workspace_graph`, `code_search`, `code_status` — 를 노출하며, 각 응답은 한 줄 답변으로 시작해 간결한 경로/심볼/시그니처 근거가 뒤따르고, 응답마다 길이를 제한하며, `code_status`가 인덱스가 오래되었다고 보고하면 경고를 앞에 붙입니다.
+
+서버는 고정 리소스 — `project-librarian://wiki/startup`, `project-librarian://wiki/index`, `project-librarian://code/status` — 와 위키 분류 갱신, 코드 영향 추적, 검색 품질 검토용 프롬프트 템플릿도 제공합니다. 리소스 읽기는 임의 파일 경로가 아니라 고정 URI 레지스트리에서만 처리합니다.
 
 부트스트랩은 Claude Code(`.mcp.json`), Cursor(`.cursor/mcp.json`), Gemini CLI(`.gemini/settings.json`의 `mcpServers`)에 서버를 등록하며, 기존 서버와 키를 보존하고 다시 실행하면 `exists`를 보고합니다. 저장소에 로컬 실행 경로가 있으면 `node <runner> mcp`로, 없으면 설치된 `project-librarian mcp` 바이너리로 등록합니다.
 
@@ -267,8 +275,11 @@ codex mcp add project-librarian -- node .codex/skills/project-librarian/dist/ini
 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, 근거 누락, 마이그레이션 정책 위반을 보고합니다.
+8. `--code-report`, `--code-impact`, `--code-context-pack`, `--code-search-symbol`, `--code-query`가 계획 갱신용 코드 근거를 제공합니다.
+9. 읽기 전용 위키 소비자는 공통 concept read model을 사용해 canonical 위키 스키마를 다시 쓰지 않고 경로와 frontmatter에서 사용자용 페이지 유형을 파생합니다.
+10. 위키 생산자는 기존 markdown/YAML 정본 스키마를 계속 작성하고, 진단·MCP·시각화 같은 읽기 전용 소비자는 원본 문서를 바꾸지 않는 파생 보기를 사용합니다.
+11. `--wiki-visualize`는 데이터베이스나 서버를 추가하지 않고 기존 위키 그래프와 concept read model을 재사용해 `.project-wiki/` 아래 정적 그래프 산출물을 작성합니다.
+12. 진단은 깨진 링크, 중복 route, 고아 페이지, 오래된 페이지, 누락된 TL;DR, 근거 누락, 마이그레이션 정책 위반을 보고합니다.
 
 마이그레이션은 검토를 우선합니다. `--migrate`는 기존 `wiki/`를 `wiki_legacy*`로 보존하고, 양식 전용 legacy 파일은 제외한 뒤, 여러 성격의 내용이 섞인 기존 페이지를 의미 단위로 나눕니다. 이후 각 단위를 문서 분류 체계에 따라 분류해 `wiki/migration/` 아래 검토 파일을 작성합니다.
 
@@ -308,10 +319,12 @@ codex mcp add project-librarian -- node .codex/skills/project-librarian/dist/ini
 자동화나 직접 CLI 실행에는 확인된 로컬 실행 경로를 사용합니다.
 
 ```bash
-node .codex/skills/project-librarian/dist/init-project-wiki.js [init] [options]
+node .codex/skills/project-librarian/dist/init-project-wiki.js [init|update] [options]
 node .codex/skills/project-librarian/dist/init-project-wiki.js install-skill [--scope user|project] [--agents codex|claude|cursor|gemini|all]
 ```
 
+`update`는 기존 프로젝트 설정을 명시적으로 갱신하는 명령입니다. `--migrate`와 `--adopt-existing`는 함께 쓸 수 없습니다. 기존 문서나 위키를 `wiki_legacy*`로 보존하고 검토해야 할 때는 최상위 `--migrate`를 사용합니다.
+
 중요 옵션:
 
 | 옵션 | 용도 |
@@ -327,6 +340,8 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install-skill [--
 | `--migration-doctor` | migration-lint와 migration-quality-check를 함께 실행합니다. |
 | `--query <terms>` | 위키 경로, 메타데이터, 제목, 본문을 검색합니다. 답변 우선 출력에 페이지별 TL;DR 줄을 붙이고 고정 크기 상한을 적용합니다. |
 | `--wiki-impact <page-or-term>` | 일치하는 페이지의 위키 역링크, `decision_ref` 인용, 나가는 링크, 라우터 깊이를 보여줍니다. |
+| `--wiki-visualize` | `.project-wiki/wiki-graph.html`에 독립 실행형 정적 위키 그래프 시각화를 작성합니다. |
+| `--wiki-visualize-out <path>` | `--wiki-visualize`와 함께 사용해 `.project-wiki/` 아래의 사용자 지정 저장소 상대 경로에 작성합니다. |
 | `--refresh-index` | 생성된 자동 발견 위키 라우팅을 갱신합니다. |
 | `--capture-inbox --title <title> --content <content>` | 위키 수신함에 후보 메모를 추가합니다. |
 | `--issue-draft --issue-title <title>` | 문제 또는 부작용에 대한 읽기 전용 GitHub 이슈 본문 초안을 출력합니다. |
@@ -339,6 +354,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install-skill [--
 | `--code-report` | 근거 인덱스에서 아키텍처/소유권 요약을 출력합니다. |
 | `--code-report-section <section>` | 한 섹션만 출력: `coverage`, `ownership`, `languages`, `parsers`, `workspaces`, `workspace-graph`, `routes`, `hotspots`, `configs`, `edges`. |
 | `--code-impact <term>` | 파일, 심볼, route, import, edge, 소유자 영향 근거를 보여줍니다. |
+| `--code-context-pack <term>` | 구조적 파일, 심볼, route, import, edge, 소유권 근거를 담은 예산 제한 1차 컨텍스트 팩을 출력합니다. |
 | `--code-search-symbol <term>` | 인덱싱된 심볼을 검색합니다. |
 | `--code-query <sql>` | 근거 인덱스에 대해 보수적인 읽기 전용 SQL을 실행합니다. |
 

package/README.md

@@ -38,6 +38,7 @@ npx project-librarian install-skill --scope project --agents all
 - **Small first read.** Session-start hooks inject only `wiki/startup.md` and `wiki/index.md`; agents route to deeper pages on demand instead of grepping the whole repo cold.
 - **One setup, four agents.** Codex, Claude Code, Cursor, and Gemini CLI share the same wiki-first contract, hooks, and rules.
 - **Structured wiki writing.** New project content is classified through `wiki/meta/document-taxonomy.md` before it is written or consolidated, so PRDs, policies, UX, data, APIs, QA, release, and operations notes do not collapse into one catch-all page.
+- **Inspectable wiki graph.** `--wiki-visualize` writes a self-contained HTML graph under `.project-wiki/`, showing page types, router depth, backlinks, and decision references without adding to startup context.
 - **Measured, not hand-wavy.** Every performance claim comes from hermetic Codex benchmarks — and the cases where it costs *more* are shown right next to the wins.
 - **Optional code evidence.** A regenerable SQLite index plus answer-shaped MCP tools answer impact, ownership, and workspace-graph questions, with zero extra runtime dependencies.
 - **Safe to re-run.** Bootstrap is idempotent and preservation-first; diagnostics flag broken routes, unreachable pages, and stale truth before they mislead an agent.
@@ -56,6 +57,7 @@ Project Librarian gives agents two local sources of truth:
 | `.codex/`, `.claude/`, `.cursor/`, and `.gemini/` hooks | Automatic startup context for Codex, Claude Code, Cursor, and Gemini CLI without loading the full wiki. |
 | `GEMINI.md` and `.cursor/rules/` | Gemini CLI and Cursor instruction files that route agents to the same compact wiki-first contract. |
 | `.project-wiki/code-evidence.sqlite` | Regenerable code evidence for files, symbols, imports, routes, ownership, workspace graph, reports, and impact checks. |
+| `.project-wiki/wiki-graph.html` | Optional static wiki graph visualizer with derived concept types, router reachability, links, backlinks, and decision references. |
 | Diagnostics and migration modes | Link checks, quality checks, migration inboxes, stale-signal reports, and issue drafts when the workflow exposes a problem. |
 
 The core idea is not "write more docs." It is "keep the first agent read small, then give it reliable routes to deeper project truth and code evidence."
@@ -69,7 +71,8 @@ These numbers are maintainer release evidence, not a blanket promise. Every valu
 In the tables below, **"less" / "more"** compares cost-weighted tokens against that control, and **"faster" / "slower"** compares wall-clock time. (Cost-weighted = uncached input + 0.1 × cached input + output + reasoning output; cached resends are discounted, and raw merged totals would unfairly penalize any tool that adds a turn.) The wiki-routing track and the code-graph track are measured and reported separately — a win on one never backs a claim about the other. Generated benchmark reports under `benchmarks/reports/llm/` are ignored by default; maintainers should commit deliberate release baselines only when they are meant to support a public claim. Reproduce a release candidate with:
 
 ```bash
-npm run benchmark:release
+npm run benchmark:release:preview
+npm run benchmark:release -- --allow-codex-run
 ```
 
 ### Wiki track (planning-doc routing)
@@ -78,11 +81,11 @@ Cost-weighted tokens, Project Librarian vs control:
 
 | Scale | decision_lookup | aggregation | multi_session (2nd session) |
 | --- | --- | --- | --- |
-| Small | 7.9% less | 7.0% more | 30.4% less |
-| Medium | 69.5% less | 8.8% more | 56.6% less |
-| Large (gate-passed retry) | 62.6% less | 45.0% less* | 70.7% less |
+| Small | 43.8% less | 144.5% more | 5.4% more |
+| Medium | 53.4% less | 4.4% less | 68.5% less |
+| Large | 71.6% less* | 12.8% less | 66.0% less |
 
-The claim-grade cells (claim gate passed, every run correct) are the two large wins: `decision_lookup` (62.6% fewer cost-weighted tokens, 41.5% faster) and `multi_session` (70.7% fewer tokens, 33.9% faster). Published boundaries, not hidden: `aggregation` costs 7–9% *more* tokens at small/medium, aggregation is *slower* with the wiki at every scale even when tokens drop, and *the large aggregation figure (45.0% less) comes from a Stage 1 run whose gate failed on control-side correctness flakes, so it stays investigation evidence rather than a claim.
+Latest synthetic wiki-track release candidate: 2026-06-16, `gpt-5.5`, 42 scenarios, 3 measured runs plus 1 warmup each. The overall claim gate **failed**: 41/42 scenarios passed correctness, but `decision_lookup` at large scale on the no-Project-Librarian control had only 2/3 correct measured runs. The failed control run selected `2026-05-04` from a dated history file instead of the expected latest benchmark-evidence decision `2026-06-10` from the decision log. Treat this table as diagnostic evidence, not a public release claim, until a clean release run passes the claim gate. Published boundaries remain visible: small `aggregation` is much more expensive with the wiki, small `multi_session` is slightly more expensive, and `aggregation` stays slower at every scale even when token cost drops.
 
 ### Code-graph track (code evidence index, real repositories)
 
@@ -164,12 +167,14 @@ Wiki setup and maintenance:
 | Goal | Ask The Agent | Internal Action |
 | --- | --- | --- |
 | Create or update the wiki | "Use Project Librarian to set up or update this repository's planning wiki." | `[init]` |
+| Update existing setup without migration | "Update this repository's Project Librarian setup without migrating the wiki." | `update` |
 | Migrate existing docs/wiki content | "Use Project Librarian to migrate the existing docs/wiki content." | `--migrate` |
 | Validate generated setup | "Run Project Librarian validation." | `--lint` |
 | Check links and document quality | "Run Project Librarian diagnostics." | `--doctor` |
 | Refresh generated routing before diagnostics | "Refresh Project Librarian routing and then run diagnostics." | `--doctor --fix` |
 | Search project wiki content | "Search the Project Librarian wiki for authentication decisions." | `--query "authentication decisions"` |
 | Show backlinks and decision citations for a page | "Show Project Librarian wiki impact for decisions/release-policy." | `--wiki-impact "decisions/release-policy"` |
+| Generate a wiki graph visualizer | "Generate the Project Librarian wiki graph visualizer." | `--wiki-visualize` |
 | Capture a candidate note | "Capture this as a Project Librarian candidate note: <details>." | `--capture-inbox --title "Candidate" --content "Details"` |
 | Report stale or unresolved wiki pages | "Check Project Librarian for stale or unresolved pages." | `--prune-check` |
 | Install hook files without changing git config | "Set up Project Librarian hook files without changing git config." | `--no-git-config` |
@@ -188,6 +193,7 @@ Code evidence:
 | Print architecture and ownership report | "Show the Project Librarian code report." | `--code-report` |
 | Print one report section | "Show the routes section of the Project Librarian code report." | `--code-report --code-report-section routes` |
 | Inspect impact evidence | "Show Project Librarian impact evidence for `healthHandler`." | `--code-impact healthHandler` |
+| Build a context pack | "Build a Project Librarian context pack for `healthHandler`." | `--code-context-pack healthHandler` |
 | Search indexed symbols | "Search Project Librarian code evidence for symbol `Auth`." | `--code-search-symbol Auth` |
 | Run conservative read-only SQL | "Run a read-only Project Librarian code evidence query for file paths." | `--code-query "select path from files order by path"` |
 
@@ -248,7 +254,9 @@ Disposable code evidence cache:
 
 ## Code Evidence MCP Server
 
-`project-librarian mcp` runs a hand-rolled stdio MCP server (JSON-RPC 2.0 over newline-delimited JSON, no extra runtime dependencies) that serves the existing `.project-wiki` code-evidence index read-only. It exposes answer-shaped tools — `code_impact`, `code_ownership` (CODEOWNERS last-match precedence), `code_workspace_graph`, `code_search`, and `code_status` — whose responses lead with a one-line answer, follow with compact path/symbol/signature evidence, cap each reply, and prepend a warning when `code_status` reports the index is stale.
+`project-librarian mcp` runs a hand-rolled stdio MCP server (JSON-RPC 2.0 over newline-delimited JSON, no extra runtime dependencies) that serves the existing `.project-wiki` code-evidence index read-only. It exposes answer-shaped tools — `code_context_pack`, `code_impact`, `code_ownership` (CODEOWNERS last-match precedence), `code_workspace_graph`, `code_search`, and `code_status` — whose responses lead with a one-line answer, follow with compact path/symbol/signature evidence, cap each reply, and prepend a warning when `code_status` reports the index is stale.
+
+The server also exposes fixed resources — `project-librarian://wiki/startup`, `project-librarian://wiki/index`, and `project-librarian://code/status` — plus prompt templates for wiki taxonomy updates, code impact traces, and retrieval quality reviews. Resource reads come from a fixed URI registry rather than arbitrary filesystem paths.
 
 Bootstrap registers the server for Claude Code (`.mcp.json`), Cursor (`.cursor/mcp.json`), and Gemini CLI (`mcpServers` in `.gemini/settings.json`), preserving any existing servers and keys and reporting `exists` on a re-run. When the repository contains a local runner the registration uses `node <runner> mcp`; otherwise it uses the installed `project-librarian mcp` binary.
 
@@ -267,8 +275,11 @@ codex mcp add project-librarian -- node .codex/skills/project-librarian/dist/ini
 5. New project-planning content is classified through `wiki/meta/document-taxonomy.md` before it is written or consolidated, keeping upstream/downstream document relationships visible.
 6. `--refresh-index` routes newly discovered wiki pages; large route sets are split into `wiki/indexes/auto-*.md` scoped routers.
 7. `--code-index` creates a disposable SQLite evidence cache under `.project-wiki/`.
-8. `--code-report`, `--code-impact`, `--code-search-symbol`, and `--code-query` expose code-backed evidence for planning updates.
-9. Diagnostics report broken links, duplicate routes, orphan pages, stale pages, missing TL;DRs, evidence gaps, and migration policy violations.
+8. `--code-report`, `--code-impact`, `--code-context-pack`, `--code-search-symbol`, and `--code-query` expose code-backed evidence for planning updates.
+9. Read-only wiki consumers share a concept read model that derives user-facing page types from paths and frontmatter without rewriting the canonical wiki schema.
+10. Wiki producers keep writing the canonical markdown/YAML schema, while read-only consumers such as diagnostics, MCP, and the visualizer use derived projections instead of mutating source documents.
+11. `--wiki-visualize` writes a static graph artifact to `.project-wiki/`, reusing the wiki graph and concept read model instead of introducing a database or server.
+12. Diagnostics report broken links, duplicate routes, orphan pages, stale pages, missing TL;DRs, evidence gaps, and migration policy violations.
 
 Migration is intentionally review-first. `--migrate` preserves an existing `wiki/` as `wiki_legacy*`, skips form-only/template legacy files, splits mixed legacy pages into meaning units, classifies each unit through the document taxonomy, and writes review files under `wiki/migration/`:
 
@@ -308,10 +319,12 @@ Recognized but inventory-only extensions include `.rb`, `.vue`, and `.css`. Conf
 Use the resolved local runner for automation or direct CLI execution:
 
 ```bash
-node .codex/skills/project-librarian/dist/init-project-wiki.js [init] [options]
+node .codex/skills/project-librarian/dist/init-project-wiki.js [init|update] [options]
 node .codex/skills/project-librarian/dist/init-project-wiki.js install-skill [--scope user|project] [--agents codex|claude|cursor|gemini|all]
 ```
 
+`update` is the explicit existing-project update command. It rejects `--migrate` and `--adopt-existing`; use top-level `--migrate` when legacy docs or wiki content should be preserved into `wiki_legacy*` and reviewed.
+
 Important options:
 
 | Option | Purpose |
@@ -327,6 +340,8 @@ Important options:
 | `--migration-doctor` | Run migration-lint and migration-quality-check together. |
 | `--query <terms>` | Search wiki paths, metadata, titles, and bodies; answer-first output with per-page TL;DR lines under a hard size cap. |
 | `--wiki-impact <page-or-term>` | Show wiki backlinks, `decision_ref` citations, outgoing links, and router depth for matching pages. |
+| `--wiki-visualize` | Write a self-contained static wiki graph visualizer to `.project-wiki/wiki-graph.html`. |
+| `--wiki-visualize-out <path>` | With `--wiki-visualize`, write to a custom repository-relative path under `.project-wiki/`. |
 | `--refresh-index` | Update generated auto-discovered wiki routing. |
 | `--capture-inbox --title <title> --content <content>` | Append a candidate note to the wiki inbox. |
 | `--issue-draft --issue-title <title>` | Print a read-only GitHub issue body draft for problems or side effects. |
@@ -339,6 +354,7 @@ Important options:
 | `--code-report` | Print architecture and ownership summaries from the evidence index. |
 | `--code-report-section <section>` | Print one section: `coverage`, `ownership`, `languages`, `parsers`, `workspaces`, `workspace-graph`, `routes`, `hotspots`, `configs`, or `edges`. |
 | `--code-impact <term>` | Show file, symbol, route, import, edge, and owner impact evidence. |
+| `--code-context-pack <term>` | Print a budgeted first-pass context pack with structural file, symbol, route, import, edge, and ownership evidence. |
 | `--code-search-symbol <term>` | Search indexed symbols. |
 | `--code-query <sql>` | Run conservative read-only SQL over the evidence index. |
 

package/SKILL.md

@@ -57,6 +57,7 @@ $PROJECT_LIBRARIAN
 Use the command variants as follows:
 
 - New project wiki or normal update: `$PROJECT_LIBRARIAN`.
+- Explicit existing-project update without migration: `$PROJECT_LIBRARIAN update` (rejects `--migrate` and `--adopt-existing`).
 - Existing wiki/docs need migration: `$PROJECT_LIBRARIAN --migrate`.
 - Install hook files without changing git config: `$PROJECT_LIBRARIAN --no-git-config`.
 

package/dist/args.js

@@ -1,12 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.captureContent = exports.captureTitle = exports.codeIndexScopes = exports.codeParser = exports.codeIndexOutput = exports.codeSearchSymbol = exports.codeReportSection = exports.codeQuerySql = exports.codeImpactTarget = exports.wikiImpactTarget = exports.wikiImpactMode = exports.queryTerm = exports.codeSearchSymbolMode = exports.codeQueryMode = exports.codeImpactMode = exports.codeParserMode = exports.codeFilesMode = exports.codeStatusMode = exports.codeReportMode = exports.codeIndexFullMode = exports.codeIndexIncrementalMode = exports.codeIndexMode = exports.acknowledgeSmallRepoMode = exports.noGitConfigMode = exports.reviewMigrationMode = exports.pruneCheckMode = exports.captureInboxMode = exports.refreshIndexMode = exports.issueDraftMode = exports.issueCreateMode = exports.glossaryMode = exports.fixMode = exports.doctorMode = exports.qualityCheckMode = exports.linkCheckMode = exports.migrationQualityCheckMode = exports.migrationLintMode = exports.migrationDoctorMode = exports.lintMode = exports.migrateMode = exports.missingValueOptions = exports.unexpectedValueOptions = exports.unknownOptions = exports.args = exports.commandArgs = exports.command = exports.unknownCommand = exports.helpMode = exports.parsedArgs = exports.rawArgs = void 0;
-exports.issueDraftTitle = exports.issueBodyFile = exports.captureCategory = void 0;
+exports.codeIndexOutput = exports.codeSearchSymbol = exports.codeReportSection = exports.codeQuerySql = exports.codeImpactTarget = exports.codeContextPackTarget = exports.wikiVisualizeOutput = exports.wikiVisualizeMode = exports.wikiImpactTarget = exports.wikiImpactMode = exports.queryTerm = exports.codeSearchSymbolMode = exports.codeQueryMode = exports.codeImpactMode = exports.codeParserMode = exports.codeContextPackMode = exports.codeFilesMode = exports.codeStatusMode = exports.codeReportMode = exports.codeIndexFullMode = exports.codeIndexIncrementalMode = exports.codeIndexMode = exports.acknowledgeSmallRepoMode = exports.noGitConfigMode = exports.reviewMigrationMode = exports.pruneCheckMode = exports.captureInboxMode = exports.refreshIndexMode = exports.issueDraftMode = exports.issueCreateMode = exports.glossaryMode = exports.fixMode = exports.doctorMode = exports.qualityCheckMode = exports.linkCheckMode = exports.migrationQualityCheckMode = exports.migrationLintMode = exports.migrationDoctorMode = exports.lintMode = exports.migrateMode = exports.missingValueOptions = exports.unexpectedValueOptions = exports.unknownOptions = exports.args = exports.commandArgs = exports.command = exports.unknownCommand = exports.helpMode = exports.parsedArgs = exports.rawArgs = void 0;
+exports.issueDraftTitle = exports.issueBodyFile = exports.captureCategory = exports.captureContent = exports.captureTitle = exports.codeIndexScopes = exports.codeParser = void 0;
 exports.parseArgs = parseArgs;
 exports.argValue = argValue;
 exports.argValues = argValues;
 exports.rawArgs = process.argv.slice(2);
-const knownCommands = new Set(["init", "install-skill", "mcp"]);
+const knownCommands = new Set(["init", "update", "install-skill", "mcp"]);
 const flagsWithoutValues = new Set([
     "--acknowledge-small-repo",
     "--adopt-existing",
@@ -43,11 +43,15 @@ const flagsWithoutValues = new Set([
     "--refresh-index",
     "--review-migration",
     "--semantic-migrate",
+    "--wiki-graph-html",
+    "--wiki-visualize",
 ]);
 const flagsWithValues = new Set([
     "--agents",
     "--category",
+    "--code-evidence-context-pack",
     "--code-evidence-impact",
+    "--code-context-pack",
     "--code-evidence-out",
     "--code-evidence-parser",
     "--code-evidence-query",
@@ -68,6 +72,7 @@ const flagsWithValues = new Set([
     "--scope",
     "--title",
     "--wiki-impact",
+    "--wiki-visualize-out",
 ]);
 const knownFlags = new Set([...flagsWithoutValues, ...flagsWithValues, "--help", "-h"]);
 function flagName(arg) {
@@ -130,6 +135,7 @@ function parseArgs(argv) {
     const argValue = (name) => argValueFrom(commandArgs, name);
     const argValues = (name) => argValuesFrom(commandArgs, name);
     const codeImpactTarget = argValue("--code-impact") || argValue("--code-evidence-impact");
+    const codeContextPackTarget = argValue("--code-context-pack") || argValue("--code-evidence-context-pack");
     const codeQuerySql = argValue("--code-query") || argValue("--code-evidence-query");
     const codeSearchSymbol = argValue("--code-search-symbol") || argValue("--code-evidence-symbol");
     return {
@@ -139,6 +145,8 @@ function parseArgs(argv) {
         captureContent: argValue("--content"),
         captureInboxMode: args.has("--capture-inbox"),
         captureTitle: argValue("--title"),
+        codeContextPackMode: hasFlag("--code-context-pack") || hasFlag("--code-evidence-context-pack"),
+        codeContextPackTarget,
         codeFilesMode: args.has("--code-files") || args.has("--code-evidence-files"),
         codeImpactMode: hasFlag("--code-impact") || hasFlag("--code-evidence-impact"),
         codeImpactTarget,
@@ -191,6 +199,8 @@ function parseArgs(argv) {
             .filter((arg) => !knownFlags.has(arg)))),
         wikiImpactMode: hasFlag("--wiki-impact"),
         wikiImpactTarget: argValue("--wiki-impact"),
+        wikiVisualizeMode: hasFlag("--wiki-visualize") || hasFlag("--wiki-graph-html"),
+        wikiVisualizeOutput: argValue("--wiki-visualize-out"),
     };
 }
 exports.parsedArgs = parseArgs(exports.rawArgs);
@@ -226,6 +236,7 @@ exports.codeIndexFullMode = exports.parsedArgs.codeIndexFullMode;
 exports.codeReportMode = exports.parsedArgs.codeReportMode;
 exports.codeStatusMode = exports.parsedArgs.codeStatusMode;
 exports.codeFilesMode = exports.parsedArgs.codeFilesMode;
+exports.codeContextPackMode = exports.parsedArgs.codeContextPackMode;
 exports.codeParserMode = exports.parsedArgs.codeParserMode;
 exports.codeImpactMode = exports.parsedArgs.codeImpactMode;
 exports.codeQueryMode = exports.parsedArgs.codeQueryMode;
@@ -239,6 +250,9 @@ function argValues(name) {
 exports.queryTerm = exports.parsedArgs.queryTerm;
 exports.wikiImpactMode = exports.parsedArgs.wikiImpactMode;
 exports.wikiImpactTarget = exports.parsedArgs.wikiImpactTarget;
+exports.wikiVisualizeMode = exports.parsedArgs.wikiVisualizeMode;
+exports.wikiVisualizeOutput = exports.parsedArgs.wikiVisualizeOutput;
+exports.codeContextPackTarget = exports.parsedArgs.codeContextPackTarget;
 exports.codeImpactTarget = exports.parsedArgs.codeImpactTarget;
 exports.codeQuerySql = exports.parsedArgs.codeQuerySql;
 exports.codeReportSection = exports.parsedArgs.codeReportSection;