project-librarian 0.2.1 → 0.4.0

package/README.md

@@ -5,11 +5,43 @@
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22.13-brightgreen.svg)](https://nodejs.org/)
 [![Code evidence index](https://img.shields.io/badge/code%20evidence-node%3Asqlite-blue.svg)](https://nodejs.org/api/sqlite.html)
 
-Compact project memory and code evidence for Codex, Claude Code, Cursor, and Gemini CLI.
+**Give every AI coding agent the same durable memory of your project.** Project Librarian keeps a compact, repo-local planning wiki — plus an optional code-evidence index — that Codex, Claude Code, Cursor, and Gemini CLI read at session start, so they stop rediscovering your codebase from scratch every time.
 
-Project Librarian creates a repo-local planning wiki, compact startup hooks, and an optional SQLite code evidence index so agents can start with the project plan, route to the right document, and inspect code-backed evidence without repeatedly scanning the whole repository.
+Languages: [English](README.md) | [한국어](README.ko.md)
 
-Languages: [English](README.md) | [한국어](README.ko.md) | [日本語](README.ja.md) | [简体中文](README.zh.md)
+## Quick Start
+
+Most users should ask their coding agent to run Project Librarian rather than run lifecycle commands by hand.
+
+Install the reusable skill files once, or ask an agent with shell access to do it:
+
+```bash
+npx project-librarian install-skill --scope user --agents all
+```
+
+Then ask Codex, Claude Code, Cursor, or Gemini CLI from the target repository:
+
+- "Use Project Librarian to set up this repository's planning wiki and run diagnostics."
+- "Use Project Librarian to migrate the existing docs/wiki content."
+- "Search the Project Librarian wiki for authentication decisions."
+
+The installed skill tells the agent to resolve the local runner and execute the right command from the project root. Prefer a project-local install only when you want that runner stored inside the target repository's agent setup:
+
+```bash
+npx project-librarian install-skill --scope project --agents all
+```
+
+`install-skill` only copies the reusable runner and skill files. The agent-run lifecycle command is what creates or updates `AGENTS.md`, agent hooks, `wiki/`, git hook files, diagnostics, and optional code-evidence support.
+
+## Highlights
+
+- **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.
 
 ## Why It Exists
 
@@ -21,30 +53,71 @@ Project Librarian gives agents two local sources of truth:
 | --- | --- |
 | `wiki/startup.md` + `wiki/index.md` | A compact session-start summary and router, so only the relevant planning pages are read. |
 | `wiki/canonical/` and `wiki/decisions/` | Current project facts, constraints, risks, package contracts, CLI behavior, and durable decisions. |
+| `wiki/meta/document-taxonomy.md` | A service-lifecycle classification map that tells agents where PRD, policy, UX, data, engineering, QA, release, and operations truth should live. |
 | `.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."
 
+The taxonomy is a routing aid, not a mandate to create every possible document. It is strongest for service and product development. Library, infrastructure, research, or other non-service projects can use only the relevant slices and leave the rest as intentionally unused categories instead of forcing artificial pages.
+
 ## Benchmark Results
 
-Benchmarks are maintainer release evidence, not a public user workflow. They exist so README and release notes can make bounded claims with numbers instead of vague performance language.
+These numbers are maintainer release evidence, not a blanket promise. Every value is real Codex JSONL usage and local wall-clock time (ChatGPT/Codex auth, `gpt-5.5`), measured hermetically — isolated Codex home, allowlist-only environment, clean tree, post-run fixture validation — with 3 measured runs plus 1 warmup per scenario against an `organic` control that has no Project Librarian.
+
+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:preview
+npm run benchmark:release -- --allow-codex-run
+```
+
+### Wiki track (planning-doc routing)
+
+Cost-weighted tokens, Project Librarian vs control:
+
+| Scale | decision_lookup | aggregation | multi_session (2nd session) |
+| --- | --- | --- | --- |
+| 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 |
+
+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)
+
+Measured on two SHA-pinned open-source repositories with hand-authored answer keys and the answer-shaped MCP tools injected into the hermetic Codex home. The claim gate passed with 30/30 runs correct after two evaluator false positives were fixed and the report was re-scored from raw JSONL; recompute-from-raw is the standing audit policy. Cost-weighted tokens, Project Librarian vs control:
+
+| Question | excalidraw (~1.2k files) | backstage (~11.8k files) |
+| --- | --- | --- |
+| impact_trace | 117% more | **27.7% less** |
+| workspace_graph | 106% more | 2.6% less |
+| ownership_lookup | — | 99% more |
+
+The claim is a scale crossover, and the losses are published next to the win: on the 11.8k-file repository the tool wins the expensive traversal question (impact_trace 27.7% fewer cost-weighted tokens, 24.5% fewer scan bytes) and breaks even on the workspace graph, but everything loses on the small repository and cheap lookups (CODEOWNERS ownership) lose at every measured scale. In short, the code-evidence index pays off only on genuinely large repositories for expensive-traversal questions — exactly what the CLI's scale-aware gates encode: below ~5k indexable files, `--code-index` asks for explicit acknowledgement and bootstrap skips MCP auto-registration, citing these measurements.
+
+### What the benchmark names mean
+
+Repositories under test:
 
-Current local measured report: `benchmarks/reports/llm/current-local.json` and `benchmarks/reports/llm/current-local.md`, generated 2026-06-10 with ChatGPT/Codex auth, `gpt-5.5`, `decision_lookup`, 1 measured run per condition, no warmup. These values are real Codex JSONL usage and local wall-clock measurements. Positive deltas mean the Project Librarian condition used more than the no-Project-Librarian control.
+- **excalidraw** — a real open-source whiteboard/diagramming app (~1.2k files); the small-repo data point.
+- **backstage** — Spotify's open-source developer-portal platform (~11.8k files); the large-repo data point.
 
-| Scale | Without Project Librarian | With Project Librarian | Actual delta |
-| --- | ---: | ---: | ---: |
-| Small | 102,655 total tokens; 101,226 input; 37.15s; 9 command invocations | 176,104 total tokens; 173,733 input; 61.04s; 15 command invocations | +71.55% tokens; +64.33% time; +66.67% commands |
-| Medium | 79,340 total tokens; 78,348 input; 44.28s; 5 command invocations | 165,840 total tokens; 163,856 input; 48.48s; 10 command invocations | +109.02% tokens; +9.5% time; +100% commands |
-| Large | 197,097 total tokens; 195,278 input; 45.87s; 10 command invocations | 183,959 total tokens; 181,897 input; 49.42s; 13 command invocations | -6.67% tokens; +7.72% time; +30% commands |
+Question types (task families):
 
-Claim boundary: this approved local run passed the benchmark claim gate, but it is not a clean release baseline. It used a dirty worktree, one run per condition, and post-run fixture fingerprint validation needs a clean isolated rerun because runtime state files touched the generated fixture directories. Do not claim token or time improvement from Project Librarian until repeated clean actual-LLM runs show stable deltas.
+- **decision_lookup** — find the latest project decision and its date from the wiki.
+- **aggregation** — answer a question whose facts are scattered across several pages and must be synthesized.
+- **multi_session** — a second session on the same project, measuring whether the durable wiki helps the next session, not just the first.
+- **impact_trace** — "if this module changes, what else is affected?": trace the full set of direct and indirect importers.
+- **ownership_lookup** — "who owns this file?": resolve the owner by CODEOWNERS last-match precedence.
+- **workspace_graph** — "what does this package depend on across the monorepo?": the workspace/package dependency graph.
 
-## Install
+## Install Details
 
-Use `npx` only for initial skill installation:
+Use this section when you need to choose an install scope or target agent. Use `npx` only for initial skill installation:
 
 ```bash
 npx project-librarian install-skill --scope user --agents all
@@ -68,11 +141,11 @@ npx project-librarian install-skill --scope project --agents all
 | Install only Gemini CLI | `npx project-librarian install-skill --agents gemini` |
 | Preview install output | `npx project-librarian install-skill --scope project --agents all --dry-run` |
 
-`--agents` also accepts comma-separated values such as `codex,claude,cursor,gemini`. `all` targets every supported agent; `both` remains a Codex/Claude compatibility alias. `--scope` accepts `user` or `project`.
+`--agents` also accepts comma-separated values such as `codex,claude,cursor,gemini`. `all` targets every supported agent. `--scope` accepts `user` or `project`.
 
-## Agent Runner
+## Runner Paths
 
-After installation, agents should run the installed local copy with `node`, not `npx`. This avoids network access and unpinned package execution in restricted agent environments.
+These paths are mainly for agents and automation. After installation, agents should run the installed local copy with `node`, not `npx`. This avoids network access and unpinned package execution in restricted agent environments.
 
 | Installation | Runner |
 | --- | --- |
@@ -85,52 +158,44 @@ After installation, agents should run the installed local copy with `node`, not
 | User-scoped Cursor skill | `node ~/.cursor/skills/project-librarian/dist/init-project-wiki.js` |
 | User-scoped Gemini skill | `node ~/.gemini/skills/project-librarian/dist/init-project-wiki.js` |
 
-The examples below use:
-
-```bash
-PROJECT_LIBRARIAN="node .codex/skills/project-librarian/dist/init-project-wiki.js"
-```
-
-Use the matching local runner for your install location.
-
-## Common Agent Workflows
-
-Bootstrap or update the wiki from the project root:
-
-```bash
-$PROJECT_LIBRARIAN
-```
-
-Validate and maintain the wiki:
-
-| Goal | Agent Command |
-| --- | --- |
-| Create or update the wiki | `$PROJECT_LIBRARIAN` |
-| Migrate existing docs/wiki content | `$PROJECT_LIBRARIAN --migrate` |
-| Validate generated setup | `$PROJECT_LIBRARIAN --lint` |
-| Check links and document quality | `$PROJECT_LIBRARIAN --doctor` |
-| Refresh generated routing before diagnostics | `$PROJECT_LIBRARIAN --doctor --fix` |
-| Search project wiki content | `$PROJECT_LIBRARIAN --query "authentication decisions"` |
-| Capture a candidate note | `$PROJECT_LIBRARIAN --capture-inbox --title "Candidate" --content "Details"` |
-| Report stale or unresolved wiki pages | `$PROJECT_LIBRARIAN --prune-check` |
-| Install hook files without changing git config | `$PROJECT_LIBRARIAN --no-git-config` |
-
-Build and inspect code evidence:
-
-| Goal | Agent Command |
-| --- | --- |
-| Build the default evidence cache | `$PROJECT_LIBRARIAN --code-index --code-scope src` |
-| Build multiple scopes | `$PROJECT_LIBRARIAN --code-index --code-scope src --code-scope packages/api` |
-| Require incremental update | `$PROJECT_LIBRARIAN --code-index --incremental` |
-| Force a full rebuild | `$PROJECT_LIBRARIAN --code-index --code-index-full` |
-| Use optional Tree-sitter backend | `$PROJECT_LIBRARIAN --code-index --code-parser tree-sitter` |
-| Show cache status | `$PROJECT_LIBRARIAN --code-status` |
-| List indexed files | `$PROJECT_LIBRARIAN --code-files` |
-| Print architecture and ownership report | `$PROJECT_LIBRARIAN --code-report` |
-| Print one report section | `$PROJECT_LIBRARIAN --code-report --code-report-section routes` |
-| Inspect impact evidence | `$PROJECT_LIBRARIAN --code-impact healthHandler` |
-| Search indexed symbols | `$PROJECT_LIBRARIAN --code-search-symbol Auth` |
-| Run conservative read-only SQL | `$PROJECT_LIBRARIAN --code-query "select path from files order by path"` |
+## Common Agent Requests
+
+Ask your agent for the outcome you want; the skill maps the request to the local runner internally.
+
+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` |
+
+Code evidence:
+
+| Goal | Ask The Agent | Internal Action |
+| --- | --- | --- |
+| Build the default evidence cache | "Build Project Librarian code evidence for `src`." | `--code-index --code-scope src` |
+| Build multiple scopes | "Build Project Librarian code evidence for `src` and `packages/api`." | `--code-index --code-scope src --code-scope packages/api` |
+| Require incremental update | "Update the Project Librarian code evidence index incrementally." | `--code-index --incremental` |
+| Force a full rebuild | "Fully rebuild the Project Librarian code evidence index." | `--code-index --code-index-full` |
+| Use optional Tree-sitter backend | "Build Project Librarian code evidence with the Tree-sitter parser." | `--code-index --code-parser tree-sitter` |
+| Show cache status | "Show Project Librarian code evidence status." | `--code-status` |
+| List indexed files | "List files in the Project Librarian code evidence index." | `--code-files` |
+| 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"` |
 
 Only one code evidence mode can run at a time. `--incremental`, `--code-index-full`, and `--code-parser` are valid only with `--code-index`.
 
@@ -169,21 +234,64 @@ Wiki directories:
 - `wiki/sources/`
 - `wiki/migration/`
 
+Seed wiki pages and routers:
+
+- `wiki/startup.md`
+- `wiki/index.md`
+- `wiki/meta/document-taxonomy.md`
+
+Empty project pages such as `canonical/project-brief.md`, `canonical/open-questions.md`, `canonical/assumptions.md`, `canonical/risks.md`, and ADR templates are not created until there is real content to store. The router can discover them later with `--refresh-index`. During migration, form-only legacy templates are recorded as skipped in `wiki/migration/inventory.md` instead of becoming review rows or new wiki pages.
+
+MCP server registration (preservation-first merge into `mcpServers`):
+
+- `.mcp.json` (Claude Code)
+- `.cursor/mcp.json` (Cursor)
+- `.gemini/settings.json` `mcpServers` (Gemini CLI)
+
 Disposable code evidence cache:
 
 - `.project-wiki/code-evidence.sqlite`
 
+## 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_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.
+
+Codex registers MCP servers at the user level only (`codex mcp add`), so bootstrap does not write a project-level Codex MCP config. To use the server with Codex, run it once per machine:
+
+```bash
+codex mcp add project-librarian -- node .codex/skills/project-librarian/dist/init-project-wiki.js mcp
+```
+
 ## How It Works
 
 1. Bootstrap creates a preservation-first wiki structure and marker-bounded agent instruction sections.
 2. Session-start hooks inject only `wiki/startup.md` and `wiki/index.md`, with character budgets.
-3. Detailed planning truth stays in canonical, decision, source, and meta pages that agents read on demand.
-4. `--refresh-index` routes newly discovered wiki pages; large route sets are split into `wiki/indexes/auto-*.md` scoped routers.
-5. `--code-index` creates a disposable SQLite evidence cache under `.project-wiki/`.
-6. `--code-report`, `--code-impact`, `--code-search-symbol`, and `--code-query` expose code-backed evidence for planning updates.
-7. Diagnostics report broken links, duplicate routes, orphan pages, stale pages, missing TL;DRs, evidence gaps, and migration policy violations.
+3. Bootstrap avoids empty form-only project pages; focused canonical, decision, source, and meta pages are created when content actually exists.
+4. Detailed planning truth stays in canonical, decision, source, and meta pages that agents read on demand.
+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-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/`:
 
-Migration is intentionally review-first. `--migrate` preserves an existing `wiki/` as `wiki_legacy*`, writes migration inboxes and a unit-level coverage ledger, and restructures legacy meaning into the current wiki rules. Retained or copied legacy content is acceptable when it fits the new wiki policy and structure; the new wiki must not depend on citing `wiki_legacy*`.
+- `inventory.md` records migratable legacy markdown files, file-level classification, and form-only/template files skipped from semantic migration.
+- `unit-map.md` records each heading, paragraph, list item, table row, and code block with its suggested taxonomy area and target page.
+- `split-plan.md` groups those units by suggested new wiki target, so one legacy page that mixes API specs, features, UX, QA, policy, or operations can be rewritten into separate files.
+- `coverage.md` is the editable status ledger for each unit: pending, adopted, merged, superseded, rejected, resolved, or needs-human-review.
+- `verification.md` and `review.md` summarize coverage and semantic completion after `--review-migration`.
+
+`--migration-lint` validates that `coverage.md`, `unit-map.md`, and `split-plan.md` still account for the current migration batch, including duplicate/stale unit IDs, invalid storage/confidence/status values, split count drift, target drift, and old coverage-table schemas. When a legacy page has units that point to multiple targets, `--review-migration` will not let a file-level inbox status complete every unit; unit-level coverage must be resolved instead.
+
+Retained or copied legacy content is acceptable when it fits the new wiki policy and structure; the new wiki must not depend on citing `wiki_legacy*`.
 
 ## Language Support Matrix
 
@@ -208,39 +316,45 @@ Recognized but inventory-only extensions include `.rb`, `.vue`, and `.css`. Conf
 
 ## CLI Reference
 
-Use the local runner for agent execution:
+Use the resolved local runner for automation or direct CLI execution:
 
 ```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|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 |
 | --- | --- |
-| `--migrate`, `--adopt-existing` | Preserve an existing wiki as `wiki_legacy*` and create migration inboxes. |
+| `--migrate`, `--adopt-existing` | Preserve an existing wiki as `wiki_legacy*`, create migration inboxes, and generate unit-map/split-plan/coverage review files. |
 | `--lint` | Validate generated setup without editing files. |
-| `--link-check` | Report broken wiki links, duplicate routes, and orphan pages. |
+| `--link-check` | Report broken wiki links, duplicate routes, orphan pages, and pages the startup router cannot reach within the depth budget. |
 | `--quality-check` | Report stale, conflicting, and low-quality wiki document signals. |
 | `--doctor` | Run lint, link-check, and quality-check together. |
 | `--doctor --fix` | Safely refresh generated index routing before diagnostics. |
-| `--migration-lint` | Validate migration review scaffolding separately from normal lint. |
+| `--migration-lint` | Validate migration coverage, unit-map, split-plan, and review scaffolding separately from normal lint. |
 | `--migration-quality-check` | Report migration policy/structure signals separately from normal quality-check. |
 | `--migration-doctor` | Run migration-lint and migration-quality-check together. |
-| `--query <terms>` | Search wiki paths, metadata, titles, and bodies. |
+| `--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. |
 | `--issue-create --issue-title <title>` | Create a GitHub issue through `gh` after explicit user approval. |
 | `--glossary-init` | Create and route the optional glossary page. |
 | `--prune-check` | Report active pages with stale or unresolved lifecycle signals. |
-| `--review-migration`, `--semantic-migrate` | Sync migration inbox statuses into migration review files. |
+| `--review-migration`, `--semantic-migrate` | Sync migration coverage and inbox statuses into migration review files. |
 | `--no-git-config` | Install hook files without changing `git core.hooksPath`. |
 | `--code-index` | Build the disposable code evidence index. |
 | `--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`.
 
@@ -121,7 +122,7 @@ $PROJECT_LIBRARIAN --lint
 
 Use `--query`, `--prune-check`, `--issue-draft`, `--link-check`, `--quality-check`, `--doctor`, `--migration-lint`, `--migration-quality-check`, and `--migration-doctor` for read-only inspection/output through the resolved runner. Use `--doctor --fix` when safe generated routing refresh is intended. Use `--refresh-index`, `--capture-inbox`, `--glossary-init`, and `--migrate` only when updating wiki files is intended.
 
-Use `--review-migration` or `--semantic-migrate` after migration inbox rows are processed. It syncs inbox statuses into `wiki/migration/review.md` and `wiki/migration/verification.md`.
+Use `--review-migration` or `--semantic-migrate` after migration coverage or compatible inbox rows are processed. It syncs unit coverage and safe file-level inbox statuses into `wiki/migration/review.md` and `wiki/migration/verification.md`.
 
 ## Code-Informed Canonicalization
 
@@ -200,8 +201,8 @@ Execution contract:
    - Code structure, entrypoints, module relationships, execution flows, read-on-demand routes, and evidence paths belong under `wiki/meta/` with descriptive project-specific filenames chosen by the LLM.
    - Code-backed current project behavior, features, policies, constraints, terminology, domain rules, and operational facts belong under `wiki/canonical/`.
    - Important design rationale or tradeoffs inferred from code may belong under `wiki/decisions/` when they meet the decision policy.
-   - Unclear, conflicting, or low-confidence interpretations belong in `wiki/inbox/` or `wiki/canonical/open-questions.md`, not directly in canonical truth.
-4. Do not use fixed canonical filenames beyond existing starter docs. Choose or create files from topic boundaries, expected read frequency, and token budget.
+   - Unclear, conflicting, or low-confidence interpretations belong in `wiki/inbox/` or a focused canonical questions page created for the topic, not directly in canonical truth.
+4. Do not use fixed canonical filenames. Choose or create files from topic boundaries, expected read frequency, and token budget.
 5. Split large subjects into focused documents when a single file would force agents to read unrelated content.
 6. Cite concrete evidence with repository-relative paths and distinguish code-proven facts from inference.
 7. Update `wiki/startup.md` and `wiki/index.md` only with compact routing hints, not large code summaries.
@@ -226,11 +227,11 @@ It installs:
 - `.gemini/hooks/wiki-session-start.js` compact startup context injector for Gemini CLI.
 - `wiki/startup.md` compact session-start context.
 - `wiki/index.md` router with read/update/token-budget hints.
-- `wiki/canonical/` project-current-truth starter documents.
+- `wiki/canonical/` directory for project-current-truth documents, created only when real content exists.
 - Optional `wiki/canonical/glossary.md` project terminology contract when `--glossary-init` is used.
-- `wiki/decisions/` project-decision starter documents and ADR templates.
+- `wiki/decisions/` project-decision directory and lightweight decision ledgers.
 - `wiki/meta/` wiki operating rules, project decision policy, and wiki-operations Decision Pack.
-- `wiki/sources/` source summary starter documents.
+- `wiki/sources/` source summary documents.
 
 The Codex, Claude Code, Cursor, and Gemini CLI startup hooks inject only `wiki/startup.md` and `wiki/index.md`. Codex uses `.codex/hooks.json` plus `.codex/hooks/wiki-session-start.js`; Claude Code uses `.claude/settings.json` plus `.claude/hooks/wiki-session-start.js`; Cursor uses `.cursor/hooks.json` plus `.cursor/hooks/wiki-session-start.js`; Gemini CLI uses `.gemini/settings.json` plus `.gemini/hooks/wiki-session-start.js`. `CLAUDE.md` and `GEMINI.md` import `AGENTS.md`, and `.cursor/rules/project-librarian.mdc` references `AGENTS.md`, so Claude Code, Gemini CLI, and Cursor share the same compact wiki-first instruction contract without duplicating the rules. `AGENTS.md` should stay compact and project-wide; `wiki/AGENTS.md` should carry detailed wiki editing rules. `wiki/startup.md` should route detailed canonical and decision files as Read On Demand, not Always Read First, so detailed files are read only when the current question needs them.
 
@@ -277,7 +278,7 @@ It appends these trailers when they are missing:
 
 Do not hand-write wiki trailers unless the hook is unavailable or the generated value needs correction.
 
-`--lint` verifies the Codex, Claude, Cursor, and Gemini hook files/settings, Cursor and Gemini instruction files, git hook files, executable bits, trailer phrases, and `core.hooksPath` when the project is a git repository. If `--no-git-config` was used, an unset or different `core.hooksPath` is expected until the project owner configures it manually.
+`--lint` verifies common wiki files plus the agent surfaces that are present in the project. If any file for a surface exists, lint requires the rest of that surface's files and settings; uninstalled Cursor or Gemini surfaces are not hard requirements. It also checks git hook files, executable bits, trailer phrases, and `core.hooksPath` when the project is a git repository. If `--no-git-config` was used, an unset or different `core.hooksPath` is expected until the project owner configures it manually.
 
 ## Glossary Mode
 
@@ -316,7 +317,8 @@ Migration mode is a reset-and-restructure flow:
 - If `./wiki_legacy` already exists, preserves both by using a timestamped `wiki_legacy_...` directory for the current wiki.
 - Creates a fresh `./wiki` using the current standard rules.
 - Scans markdown files under the legacy wiki directory.
-- Writes `wiki/migration/inventory.md`, `wiki/migration/coverage.md`, `wiki/migration/plan.md`, and `wiki/migration/verification.md`.
+- Skips form-only/template legacy files as non-semantic input; `inventory.md` records the skipped source and reason instead of creating review rows or new wiki pages.
+- Writes `wiki/migration/inventory.md`, `wiki/migration/unit-map.md`, `wiki/migration/split-plan.md`, `wiki/migration/coverage.md`, `wiki/migration/plan.md`, `wiki/migration/review.md`, and `wiki/migration/verification.md`.
 - Writes rewrite inboxes:
   - `wiki/canonical/migration-inbox.md`
   - `wiki/decisions/migration-inbox.md`
@@ -325,7 +327,11 @@ Migration mode is a reset-and-restructure flow:
 
 After migration mode, inspect inboxes and fold legacy content into canonical docs, Decision Packs, ADRs, source summaries, or meta docs. Minimize information loss while converting useful legacy meaning to the current wiki structure and rules. Legacy files, sections, blocks, and wording may be retained when review confirms each retained unit belongs in the new topic shape and remains current project truth. Do not link to or cite `wiki_legacy*` from the new wiki; cite current-project evidence when possible, and keep ambiguous material in the migration inbox or mark it `needs-human-review`.
 
-`wiki/migration/coverage.md` is the unit-level coverage ledger. It accounts for legacy headings, paragraphs, list items, table rows, and code blocks with stable unit IDs. Every unit should end as `adopted`, `merged`, `superseded`, `rejected`, `resolved`, or `needs-human-review`; `pending` means the unit is still open. `adopted` and `merged` rows require a new-wiki target under `wiki/canonical/`, `wiki/decisions/`, `wiki/sources/`, or `wiki/meta/`. Deleting a unit row is treated as possible information loss and `--migration-lint` reports it as `migration-unaccounted-unit`.
+`wiki/migration/coverage.md` is the unit-level coverage ledger. It accounts for extracted legacy headings, paragraphs, list items, table rows, and code blocks with stable unit IDs. Form-only/template files are excluded before unit extraction and are listed in `inventory.md` instead. Every extracted unit should end as `adopted`, `merged`, `superseded`, `rejected`, `resolved`, or `needs-human-review`; `pending` means the unit is still open. `adopted` and `merged` rows require a new-wiki target under `wiki/canonical/`, `wiki/decisions/`, `wiki/sources/`, or `wiki/meta/`. Deleting an extracted unit row is treated as possible information loss and `--migration-lint` reports it as `migration-unaccounted-unit`.
+
+`wiki/migration/unit-map.md` is the generated per-unit classification ledger. `wiki/migration/split-plan.md` groups units by suggested new target file. `--migration-lint` validates these files alongside `coverage.md`: stale or duplicate units, invalid storage/confidence/status values, split count drift, target drift, and old coverage schemas are reported separately from normal lint.
+
+When one legacy file maps to multiple target pages, file-level migration inbox status is not enough to close every unit. In that case, update `wiki/migration/coverage.md` unit rows directly; `--review-migration` records that the file-level inbox row was ignored for the mixed-target source. File-level inbox fallback remains available only when all units from the legacy source point to the same target, preserving older migration workflows without masking mixed-page splits.
 
 Inbox rows use these statuses:
 
@@ -341,7 +347,7 @@ Run semantic review sync after LLM or human processing:
 $PROJECT_LIBRARIAN --review-migration
 ```
 
-`wiki/migration/verification.md` verifies file coverage: every legacy markdown file should be mapped to a new-wiki migration target. `wiki/migration/coverage.md` verifies unit coverage: every extracted legacy meaning unit should remain accounted for. Semantic migration is complete only after inbox rows are marked adopted/rejected/resolved and `needs-human-review` is 0, and unit coverage has no unaccounted rows.
+`wiki/migration/verification.md` verifies current-batch unit coverage: every extracted legacy meaning unit should be mapped to a new-wiki target and remain accounted for. Semantic migration is complete only after unit coverage or safe inbox rows are marked adopted/rejected/resolved and `needs-human-review` is 0.
 
 Human review is not required for every inbox item. LLM may process ordinary rows and close them as adopted/rejected/resolved. Human review is reserved for `needs-human-review`.
 

package/dist/args.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.issueDraftTitle = exports.issueBodyFile = exports.captureCategory = exports.captureContent = exports.captureTitle = exports.codeIndexScopes = exports.codeParser = exports.codeIndexOutput = exports.codeSearchSymbol = exports.codeReportSection = exports.codeQuerySql = exports.codeImpactTarget = exports.queryTerm = exports.codeSearchSymbolMode = exports.codeQueryMode = exports.codeImpactMode = exports.codeParserMode = exports.codeFilesMode = exports.codeStatusMode = exports.codeReportMode = exports.codeIndexFullMode = exports.codeIndexIncrementalMode = exports.codeIndexMode = 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.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"]);
+const knownCommands = new Set(["init", "update", "install-skill", "mcp"]);
 const flagsWithoutValues = new Set([
+    "--acknowledge-small-repo",
     "--adopt-existing",
     "--capture-inbox",
     "--code-evidence-files",
@@ -41,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",
@@ -65,6 +71,8 @@ const flagsWithValues = new Set([
     "--query",
     "--scope",
     "--title",
+    "--wiki-impact",
+    "--wiki-visualize-out",
 ]);
 const knownFlags = new Set([...flagsWithoutValues, ...flagsWithValues, "--help", "-h"]);
 function flagName(arg) {
@@ -127,14 +135,18 @@ 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 {
+        acknowledgeSmallRepoMode: args.has("--acknowledge-small-repo"),
         args,
         captureCategory: argValue("--category") || "project-candidate",
         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,
@@ -185,6 +197,10 @@ function parseArgs(argv) {
             .filter((arg) => arg.startsWith("-"))
             .map(flagName)
             .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);
@@ -213,12 +229,14 @@ exports.captureInboxMode = exports.parsedArgs.captureInboxMode;
 exports.pruneCheckMode = exports.parsedArgs.pruneCheckMode;
 exports.reviewMigrationMode = exports.parsedArgs.reviewMigrationMode;
 exports.noGitConfigMode = exports.parsedArgs.noGitConfigMode;
+exports.acknowledgeSmallRepoMode = exports.parsedArgs.acknowledgeSmallRepoMode;
 exports.codeIndexMode = exports.parsedArgs.codeIndexMode;
 exports.codeIndexIncrementalMode = exports.parsedArgs.codeIndexIncrementalMode;
 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;
@@ -230,6 +248,11 @@ function argValues(name) {
     return argValuesFrom(exports.commandArgs, 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;