project-librarian 0.2.0 → 0.3.0

package/README.md

@@ -5,11 +5,42 @@
 [![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 and Claude Code.
+**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.
+- **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,134 +52,144 @@ 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. |
-| `.codex/` and `.claude/` hooks | Automatic startup context for Codex and Claude Code without loading the full wiki. |
+| `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. |
 | 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.
-
-Latest clean large report: `benchmarks/reports/current-large.json`, generated 2026-06-09T08:08:07.238Z on Node v22.19.0, darwin arm64, Apple M4 Pro, commit `18e730882c4f`, 5 measured runs with 1 discarded warmup run. Timing status was `stable`; unstable metrics were `none`; the report source-control fingerprint was clean.
-
-| Metric | Result |
-| --- | ---: |
-| Median estimated Markdown context avoidance | 99.61% |
-| Minimum estimated Markdown context avoidance | 99.43% |
-| Median read-time reduction | 99.47% |
-| Minimum read-time reduction | 99.26% |
-| Wiki pages measured | 1,601 |
-| Code-index files | 1,608 |
-| Code-index time | 336.312ms |
-| Code-index throughput | 4,781.27 files/sec |
-| Incremental index time | 186.776ms |
-| Full-to-incremental time reduction | 45.52% |
-| Architecture report time | 251.175ms |
-| Architecture report evidence tables | 6 |
-| Architecture report routes | 24 |
-| Sample repos | 3 |
-| Benchmark runs | 5 |
-| Warmup runs | 1 |
-| Timing status | stable |
-| Unstable metrics | none |
-
-Scenario summary:
-
-| Scenario | Scale | Result |
-| --- | ---: | --- |
-| Docs-heavy wiki | 500 pages | 99.74% estimated Markdown context avoidance, 99.47% read reduction, 43.83ms query |
-| Monorepo wiki | 320 pages | 99.43% estimated Markdown context avoidance, 99.26% read reduction, 81.12ms doctor |
-| Scoped router wiki | 720 pages | 99.61% estimated Markdown context avoidance, 99.55% read reduction, 67.684ms refresh |
-| Code-heavy mixed index | 1,608 files | 336.312ms full index, 186.776ms incremental, 251.175ms report, 626.969ms Tree-sitter index |
-| Sample repo validation | 3 repos, 16 files | 132.363ms median code index, 135.694ms median architecture report |
-
-Claim boundary: token estimates use `ceil(characters / 4)` as a Markdown context-size estimate. They are not model tokenizer output, API billing counters, or measured real LLM token consumption. The benchmark compares the wiki context read by targeted retrieval against a naive full-wiki scan that reads every wiki Markdown file in the fixture. Code-index metrics are local CLI subprocess timings over generated and sample repositories; sample repo values are observational evidence for those explicit fixtures.
-
-## Install
-
-Use `npx` only for initial skill installation:
+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
-npx project-librarian install-skill --scope user --agents both
+npm run benchmark:release
+```
+
+### Wiki track (planning-doc routing)
+
+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 |
+
+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.
+
+### 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:
+
+- **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.
+
+Question types (task families):
+
+- **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 Details
+
+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
 ```
 
 Install into the current repository instead:
 
 ```bash
-npx project-librarian install-skill --scope project --agents both
+npx project-librarian install-skill --scope project --agents all
 ```
 
-`install-skill` copies reusable skill files only. It does not create or update `AGENTS.md`, `CLAUDE.md`, `wiki/`, `.codex/hooks.json`, or `.claude/settings.json`.
+`install-skill` copies reusable skill files only. It does not create or update `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `wiki/`, `.cursor/rules/`, `.cursor/hooks.json`, `.gemini/settings.json`, `.codex/hooks.json`, or `.claude/settings.json`.
 
 | Situation | Command |
 | --- | --- |
-| Install globally for Codex and Claude Code | `npx project-librarian install-skill --scope user --agents both` |
-| Install in the current repository | `npx project-librarian install-skill --scope project --agents both` |
+| Install globally for all supported agents | `npx project-librarian install-skill --scope user --agents all` |
+| Install in the current repository | `npx project-librarian install-skill --scope project --agents all` |
 | Install only Codex | `npx project-librarian install-skill --agents codex` |
 | Install only Claude Code | `npx project-librarian install-skill --agents claude` |
-| Preview install output | `npx project-librarian install-skill --scope project --agents both --dry-run` |
+| Install only Cursor | `npx project-librarian install-skill --agents cursor` |
+| 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`. `--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 |
 | --- | --- |
 | Project-scoped Codex skill | `node .codex/skills/project-librarian/dist/init-project-wiki.js` |
 | Project-scoped Claude skill | `node .claude/skills/project-librarian/dist/init-project-wiki.js` |
+| Project-scoped Cursor skill | `node .cursor/skills/project-librarian/dist/init-project-wiki.js` |
+| Project-scoped Gemini skill | `node .gemini/skills/project-librarian/dist/init-project-wiki.js` |
 | User-scoped Codex skill | `node ~/.codex/skills/project-librarian/dist/init-project-wiki.js` |
 | User-scoped Claude skill | `node ~/.claude/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"` |
+| 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` |
+
+## 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]` |
+| 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"` |
+| 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` |
+| 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`.
 
@@ -158,7 +199,9 @@ Project instruction files:
 
 - `AGENTS.md`
 - `CLAUDE.md`
+- `GEMINI.md`
 - `wiki/AGENTS.md`
+- `.cursor/rules/project-librarian.mdc`
 
 Startup hooks:
 
@@ -166,6 +209,10 @@ Startup hooks:
 - `.codex/hooks/wiki-session-start.js`
 - `.claude/settings.json`
 - `.claude/hooks/wiki-session-start.js`
+- `.cursor/hooks.json`
+- `.cursor/hooks/wiki-session-start.js`
+- `.gemini/settings.json`
+- `.gemini/hooks/wiki-session-start.js`
 
 Git hook files:
 
@@ -181,21 +228,59 @@ 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_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.
+
+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 copy risks.
+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-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.
+
+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/`:
+
+- `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.
 
-Migration is intentionally review-first. `--migrate` preserves an existing `wiki/` as `wiki_legacy*`, writes migration inboxes, and avoids copying legacy markdown directly into new canonical truth.
+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
 
@@ -220,31 +305,35 @@ 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|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]
 ```
 
 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. |
-| `--query <terms>` | Search wiki paths, metadata, titles, and bodies. |
+| `--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; 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. |
 | `--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. |
@@ -273,7 +362,7 @@ Maintainer benchmark commands live in [benchmarks/README.md](benchmarks/README.m
 
 This project is inspired by Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern: keep persistent markdown context close to the work instead of reconstructing project state from long chat history.
 
-Project Librarian adapts that idea into an installable CLI and skill for Codex and Claude Code, with repo-local instructions, compact startup hooks, migration helpers, diagnostics, and optional code evidence.
+Project Librarian adapts that idea into an installable CLI and skill for Codex, Claude Code, Cursor, and Gemini CLI, with repo-local instructions, compact startup hooks, migration helpers, diagnostics, and optional code evidence.
 
 ## License
 

package/SKILL.md

@@ -37,8 +37,12 @@ Prefer an already installed local runner over network package execution:
 - In the project-librarian source repository, use `node dist/init-project-wiki.js` when `dist/init-project-wiki.js` exists.
 - In a target repository with a project-scoped Codex skill install, use `node .codex/skills/project-librarian/dist/init-project-wiki.js`.
 - In a target repository with a project-scoped Claude skill install, use `node .claude/skills/project-librarian/dist/init-project-wiki.js`.
+- In a target repository with a project-scoped Cursor skill install, use `node .cursor/skills/project-librarian/dist/init-project-wiki.js`.
+- In a target repository with a project-scoped Gemini skill install, use `node .gemini/skills/project-librarian/dist/init-project-wiki.js`.
 - In a user-scoped Codex skill install, use `node ~/.codex/skills/project-librarian/dist/init-project-wiki.js`.
 - In a user-scoped Claude skill install, use `node ~/.claude/skills/project-librarian/dist/init-project-wiki.js`.
+- In a user-scoped Cursor skill install, use `node ~/.cursor/skills/project-librarian/dist/init-project-wiki.js`.
+- In a user-scoped Gemini skill install, use `node ~/.gemini/skills/project-librarian/dist/init-project-wiki.js`.
 
 Use `npx` or `npm exec` only when no local runner exists and registry access is explicitly acceptable for the environment. When using npm package execution, pin the package version instead of running an unpinned public package.
 
@@ -68,6 +72,7 @@ Map lifecycle requests to these internal operations:
 - Check wiki links and routing: `$PROJECT_LIBRARIAN --link-check`.
 - Check document quality signals: `$PROJECT_LIBRARIAN --quality-check`.
 - Run all wiki diagnostics: `$PROJECT_LIBRARIAN --doctor`.
+- Check migration-specific review signals: `$PROJECT_LIBRARIAN --migration-doctor`.
 - Safely refresh generated routing before diagnostics: `$PROJECT_LIBRARIAN --doctor --fix`.
 - Search the wiki: `$PROJECT_LIBRARIAN --query "search terms"`.
 - Refresh wiki routing/index: `$PROJECT_LIBRARIAN --refresh-index`.
@@ -89,9 +94,11 @@ Skill problem reporting contract:
 ```bash
 node .codex/hooks/wiki-session-start.js
 node .claude/hooks/wiki-session-start.js
+node .cursor/hooks/wiki-session-start.js
+GEMINI_PROJECT_DIR="$PWD" node .gemini/hooks/wiki-session-start.js
 $PROJECT_LIBRARIAN --lint
 $PROJECT_LIBRARIAN --doctor
-node -e 'JSON.parse(require("fs").readFileSync(".codex/hooks.json","utf8")); JSON.parse(require("fs").readFileSync(".claude/settings.json","utf8")); console.log("project librarian ok")'
+node -e 'const fs=require("fs"); JSON.parse(fs.readFileSync(".codex/hooks.json","utf8")); JSON.parse(fs.readFileSync(".claude/settings.json","utf8")); JSON.parse(fs.readFileSync(".cursor/hooks.json","utf8")); JSON.parse(fs.readFileSync(".gemini/settings.json","utf8")); if (!fs.readFileSync("GEMINI.md","utf8").includes("@AGENTS.md")) process.exit(1); if (!fs.readFileSync(".cursor/rules/project-librarian.mdc","utf8").includes("@AGENTS.md")) process.exit(1); console.log("project librarian ok")'
 ```
 
 4. Report the files created or updated.
@@ -102,7 +109,7 @@ The script is idempotent. It creates missing files, updates the managed startup/
 
 Existing root instruction files are preservation-first:
 
-- Existing `AGENTS.md`, `CLAUDE.md`, and `wiki/AGENTS.md` files are not overwritten wholesale.
+- Existing `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and `wiki/AGENTS.md` files are not overwritten wholesale.
 - If no managed project-wiki section exists, bootstrap appends its marker-bounded section to the existing file.
 - On rerun, bootstrap replaces only content between its own `PROJECT-WIKI-*` markers and preserves surrounding project-specific content.
 
@@ -112,9 +119,9 @@ Use `--lint` for read-only validation:
 $PROJECT_LIBRARIAN --lint
 ```
 
-Use `--query`, `--prune-check`, `--issue-draft`, `--link-check`, `--quality-check`, and `--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 `--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
 
@@ -193,8 +200,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.
@@ -204,22 +211,28 @@ It installs:
 
 - `AGENTS.md` compact project-wide wiki-first planning instructions.
 - `CLAUDE.md` compact Claude Code compatibility file that imports `AGENTS.md`.
+- `GEMINI.md` compact Gemini CLI compatibility file that imports `AGENTS.md`.
 - `wiki/AGENTS.md` detailed wiki-internal editing and boundary rules.
+- `.cursor/rules/project-librarian.mdc` compact always-applied Cursor rule that references `AGENTS.md`.
 - `.githooks/prepare-commit-msg` wiki commit trailer hook.
 - `.githooks/wiki-commit-trailers.js` staged-file based trailer generator.
 - `.codex/hooks.json` `SessionStart` hook.
 - `.codex/hooks/wiki-session-start.js` compact startup context injector.
 - `.claude/settings.json` Claude Code `SessionStart` hook.
 - `.claude/hooks/wiki-session-start.js` compact startup context injector for Claude Code.
+- `.cursor/hooks.json` Cursor `sessionStart` hook.
+- `.cursor/hooks/wiki-session-start.js` compact startup context injector for Cursor.
+- `.gemini/settings.json` Gemini CLI `SessionStart` hook.
+- `.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 and Claude Code 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`. `CLAUDE.md` still imports `AGENTS.md` so Claude Code shares 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.
+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.
 
 When the project is a git repository, the script configures `git config core.hooksPath .githooks` by default only when `core.hooksPath` is unset, so wiki commit trailers are generated automatically without replacing an existing hook chain. Use `--no-git-config` to install hook files without changing git config. If the project is not a git repository yet, the hook files are still installed and will work after `core.hooksPath` is set.
 
@@ -249,7 +262,7 @@ Every wiki markdown file should include a compact metadata header with `status`,
 
 Wiki-specific commit trailers are automated through `.githooks/prepare-commit-msg`.
 
-The hook runs when staged files include `wiki/`, `AGENTS.md`, `CLAUDE.md`, `.codex/hooks.json`, `.codex/hooks/`, `.claude/settings.json`, `.claude/hooks/`, `.githooks/`, or `tools/project-librarian/`.
+The hook runs when staged files include `wiki/`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/`, `.cursor/hooks.json`, `.cursor/hooks/`, `.gemini/settings.json`, `.gemini/hooks/`, `.codex/hooks.json`, `.codex/hooks/`, `.claude/settings.json`, `.claude/hooks/`, `.githooks/`, or `tools/project-librarian/`.
 
 It appends these trailers when they are missing:
 
@@ -264,7 +277,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 and Claude hook files/settings, 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
 
@@ -297,20 +310,27 @@ Captured inbox entries are not canonical. Fold them into `wiki/canonical/`, `wik
 
 `--migrate` and `--adopt-existing` are aliases.
 
-Migration mode is a reset-and-rewrite flow:
+Migration mode is a reset-and-restructure flow:
 
 - If `./wiki` exists, renames it to `./wiki_legacy`.
 - 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/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`
   - `wiki/sources/migration-inbox.md`
 - Adds migration routing to `wiki/startup.md` and `wiki/index.md`.
 
-After migration mode, inspect inboxes and fold legacy content into canonical docs, Decision Packs, ADRs, source summaries, or meta docs. Do not copy legacy markdown files directly into `wiki/canonical/`, `wiki/decisions/`, or `wiki/sources/`; rewrite only the useful project meaning, cite current-project evidence when possible, and keep ambiguous material in the migration inbox or mark it `needs-human-review`.
+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 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:
 
@@ -326,10 +346,10 @@ 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. This is not a semantic-completeness proof. Semantic migration is complete only after inbox rows are marked adopted/rejected/resolved and `needs-human-review` is 0.
+`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`.
 
-Run `$PROJECT_LIBRARIAN --doctor` after migration review. `--quality-check` and `--doctor` report `migration-copy-risk` when a new project wiki document appears to be copied from `wiki_legacy*`, and report `migration-filename-reuse` when a legacy filename is reused and needs rewrite verification.
+Run `$PROJECT_LIBRARIAN --migration-doctor` after migration review. Normal `--quality-check` and `--doctor` intentionally omit migration-only policy/structure signals so accepted migration decisions do not pollute later non-migration document checks. `--migration-quality-check` and `--migration-doctor` report `migration-legacy-reference` as an error when active project truth links to or cites `wiki_legacy*`. They do not warn merely because a new wiki document copies legacy wording, blocks, whole documents, or filenames; those are acceptable when the result follows the current wiki policy and structure. Use `--migration-lint` and `wiki/migration/coverage.md` to prevent information loss.
 
-Do not delete `wiki_legacy` until migration verification passes, semantic review is complete, and migration copy diagnostics are clear.
+Do not delete `wiki_legacy` until migration verification passes, semantic review is complete, and migration policy/structure diagnostics are clear.