project-librarian 0.5.4 → 0.5.6

package/dist/migration.js

@@ -57,6 +57,7 @@ exports.migrationCoverageStatusMap = migrationCoverageStatusMap;
 exports.semanticStatusForInboxStatus = semanticStatusForInboxStatus;
 exports.runReviewMigrationMode = runReviewMigrationMode;
 const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
 const taxonomy_1 = require("./taxonomy");
 const workspace_1 = require("./workspace");
 const templates_1 = require("./templates");
@@ -317,9 +318,31 @@ function activeMigrationLegacyRoots() {
     const verifiedRoot = migrationVerificationLegacyRoot();
     return verifiedRoot ? [verifiedRoot] : legacyWikiRoots();
 }
+function migrationDirectoryPath(relativePath) {
+    const resolved = path.resolve(workspace_1.root, relativePath);
+    const rootResolved = path.resolve(workspace_1.root);
+    if (resolved !== rootResolved && !resolved.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new Error(`migration directory must stay inside the project root: ${relativePath}`);
+    }
+    const stat = fs.lstatSync(resolved);
+    if (stat.isSymbolicLink()) {
+        throw new Error(`migration refuses to follow symlinked wiki directory: ${relativePath}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new Error(`migration path is not a directory: ${relativePath}`);
+    }
+    const realPath = fs.realpathSync(resolved);
+    if (realPath !== rootResolved && !realPath.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new Error(`migration directory must resolve inside the project root: ${relativePath}`);
+    }
+    return resolved;
+}
 function expectedMigrationUnits() {
     return activeMigrationLegacyRoots()
-        .flatMap((legacyRoot) => (0, wiki_files_1.walkMarkdownFiles)((0, workspace_1.abs)(legacyRoot), [], (0, workspace_1.abs)(legacyRoot)))
+        .flatMap((legacyRoot) => {
+        const legacyPath = migrationDirectoryPath(legacyRoot);
+        return (0, wiki_files_1.walkMarkdownFiles)(legacyPath, [], legacyPath);
+    })
         .flatMap((file) => extractMigrationUnits(file.basePath, (0, workspace_1.read)(file.path)));
 }
 function loadMigrationUnitContext() {
@@ -962,6 +985,7 @@ function nextLegacyPath() {
 }
 function prepareMigrationMode() {
     if ((0, workspace_1.exists)("wiki")) {
+        migrationDirectoryPath("wiki");
         const legacyPath = nextLegacyPath();
         fs.renameSync((0, workspace_1.abs)("wiki"), (0, workspace_1.abs)(legacyPath));
         return { legacyPath, note: `moved wiki to ${legacyPath}` };
@@ -981,7 +1005,8 @@ function migrationTargetForKind(kind) {
 }
 function runMigrationMode(migrationState) {
     const legacyPath = migrationState.legacyPath;
-    const markdownFiles = legacyPath && (0, workspace_1.exists)(legacyPath) ? (0, wiki_files_1.walkMarkdownFiles)((0, workspace_1.abs)(legacyPath), [], (0, workspace_1.abs)(legacyPath)) : [];
+    const legacyRootPath = legacyPath && (0, workspace_1.exists)(legacyPath) ? migrationDirectoryPath(legacyPath) : "";
+    const markdownFiles = legacyRootPath ? (0, wiki_files_1.walkMarkdownFiles)(legacyRootPath, [], legacyRootPath) : [];
     const fileRecords = markdownFiles.map((file) => {
         const text = (0, workspace_1.read)(file.path);
         return { file, text, formOnlyReason: formOnlyMigrationDocumentReason(file.basePath, text) };

package/dist/native/project-librarian-indexer-manifest.json

@@ -0,0 +1,70 @@
+{
+  "artifact": "project-librarian-indexer",
+  "helpers": [
+    {
+      "architecture": "arm64",
+      "format": "mach-o",
+      "path": "dist/native/darwin-arm64/project-librarian-indexer",
+      "sha256": "f5c69130f6c0441044141c761f1ccdc7e6ee4d06e327ce0f50d43a7aed76cc95",
+      "size": 2697520,
+      "triple": "darwin-arm64"
+    },
+    {
+      "architecture": "x64",
+      "format": "mach-o",
+      "path": "dist/native/darwin-x64/project-librarian-indexer",
+      "sha256": "25041398ba2de3ed749c14103d358ed4a7934a05459eb63c6cf5f6ae58c7fb03",
+      "size": 2770592,
+      "triple": "darwin-x64"
+    },
+    {
+      "architecture": "arm64",
+      "format": "elf",
+      "path": "dist/native/linux-arm64/project-librarian-indexer",
+      "sha256": "01bf4437fd62446958438ac58e9ca8bef811bdc6d70a63fc1a0ca1b627521e67",
+      "size": 3065520,
+      "triple": "linux-arm64"
+    },
+    {
+      "architecture": "arm64",
+      "format": "elf",
+      "path": "dist/native/linux-arm64-musl/project-librarian-indexer",
+      "sha256": "b7287995bea678a6f55bd03761e5b0985d483e875d7594395b81bdb1e90a8dd9",
+      "size": 3100840,
+      "triple": "linux-arm64-musl"
+    },
+    {
+      "architecture": "x64",
+      "format": "elf",
+      "path": "dist/native/linux-x64/project-librarian-indexer",
+      "sha256": "5d93bb7576afbdde0acbde7983a874f2666f0d59227524c1eb42cc75b457c5ed",
+      "size": 3110696,
+      "triple": "linux-x64"
+    },
+    {
+      "architecture": "x64",
+      "format": "elf",
+      "path": "dist/native/linux-x64-musl/project-librarian-indexer",
+      "sha256": "518aea0fc53ed7731751db4bb436a0be98f8583659d51aeff769bedb7a7cb8ab",
+      "size": 3247384,
+      "triple": "linux-x64-musl"
+    },
+    {
+      "architecture": "arm64",
+      "format": "pe",
+      "path": "dist/native/win32-arm64/project-librarian-indexer.exe",
+      "sha256": "392157f4d3591c48a66ee674b99a8a34cda3d38cc76df6343276becb23a7055c",
+      "size": 2098688,
+      "triple": "win32-arm64"
+    },
+    {
+      "architecture": "x64",
+      "format": "pe",
+      "path": "dist/native/win32-x64/project-librarian-indexer.exe",
+      "sha256": "fabe69234daa9a6a738d0b7160c84573853d7a9e3be14c19ec6a27ca171e3f8a",
+      "size": 2375680,
+      "triple": "win32-x64"
+    }
+  ],
+  "schema_version": 1
+}

package/dist/templates.js

@@ -87,7 +87,7 @@ During conversation:
 - Do not store non-project LLM memory, assistant preferences, collaboration reminders, or workflow instructions in project wiki canonical or decision docs.
 - Follow \`wiki/AGENTS.md\` for detailed rules when editing files under \`wiki/\`.
 - Treat broad maintenance/improvement automation requests that do not name a concrete command (for example "improve this project", "start improvement automation", or "개선 자동화 시작해") as analyze-first project work, not as a plain bootstrap/update. Inspect repo, wiki, CI, test, release, dependency, and code-structure evidence; produce a ranked backlog with evidence and verification paths; persist the plan in \`wiki/plans/\` when project-planning content changes; then execute safe high-priority items with tests.
-- Let \`.githooks/prepare-commit-msg\` append wiki trailers automatically for staged wiki, hook, AGENTS, or project-librarian files.
+- Do not execute worktree-controlled commit hooks for wiki trailers; add trailers explicitly when needed.
 - ${exports.wikiTrustContract}
 - ${exports.codeEvidenceTrustContract}
 - ${exports.guidanceClaimEvidenceContract}
@@ -177,9 +177,9 @@ Update rules:
 Commit rules:
 
 - Follow the repository's commit-message policy when one exists.
-- Let \`.githooks/prepare-commit-msg\` append wiki trailers automatically when git hooks are enabled.
+- Do not execute worktree-controlled commit hooks for wiki trailers; add trailers explicitly when needed.
 - If bootstrap was run with \`--no-git-config\`, hook files are installed but \`core.hooksPath\` is not changed.
-- Do not hand-write wiki trailers unless the hook is unavailable or a trailer needs correction.
+- Hand-write wiki trailers when project policy requires them; keep them accurate and evidence-backed.
 <!-- PROJECT-WIKI-INTERNAL:END -->`;
 const metadata = (scope, budget, decisionRef, trigger, status = "active") => `---
 status: ${status}
@@ -415,6 +415,7 @@ node dist/init-project-wiki.js --query "search terms"
 ## Git Hook Setup
 
 - The script installs \`.githooks/prepare-commit-msg\` and \`.githooks/wiki-commit-trailers.js\`.
+- \`.githooks/prepare-commit-msg\` is intentionally passive and must not execute worktree-controlled scripts.
 - By default, git repositories with an unset \`core.hooksPath\` are configured with \`git config core.hooksPath .githooks\`.
 - Existing \`core.hooksPath\` values are preserved so an existing hook chain is not replaced.
 - Run bootstrap with \`--no-git-config\` to install hook files without changing git config.

package/dist/workspace.js

@@ -51,31 +51,105 @@ exports.normalizePath = normalizePath;
 exports.commandOk = commandOk;
 exports.isGitRepository = isGitRepository;
 exports.makeExecutable = makeExecutable;
+exports.containedProjectFileStat = containedProjectFileStat;
+exports.containedProjectDirectoryStat = containedProjectDirectoryStat;
+exports.requireContainedProjectFile = requireContainedProjectFile;
 exports.walkFilesUnder = walkFilesUnder;
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const childProcess = __importStar(require("node:child_process"));
 exports.root = process.cwd();
 exports.today = new Date().toISOString().slice(0, 10);
+const projectRoot = path.resolve(exports.root);
 function abs(relativePath) {
     return path.join(exports.root, relativePath);
 }
+function isInsideProject(absolutePath) {
+    const resolved = path.resolve(absolutePath);
+    return resolved === projectRoot || resolved.startsWith(`${projectRoot}${path.sep}`);
+}
+function resolveProjectPath(relativePath, label = "path") {
+    const resolved = path.isAbsolute(relativePath) ? path.resolve(relativePath) : path.resolve(exports.root, relativePath);
+    if (!isInsideProject(resolved)) {
+        throw new Error(`${label} must stay inside the project root: ${relativePath}`);
+    }
+    return resolved;
+}
+function assertNoSymlinkInProjectPath(relativePath, includeLeaf, label = "path") {
+    const target = resolveProjectPath(relativePath, label);
+    const relative = path.relative(projectRoot, target);
+    if (!relative)
+        return target;
+    const parts = relative.split(path.sep).filter(Boolean);
+    const checkedParts = includeLeaf ? parts : parts.slice(0, -1);
+    let current = projectRoot;
+    for (const part of checkedParts) {
+        current = path.join(current, part);
+        if (!fs.existsSync(current))
+            continue;
+        const stat = fs.lstatSync(current);
+        if (stat.isSymbolicLink()) {
+            throw new Error(`${label} refuses to follow symlink: ${normalizePath(path.relative(projectRoot, current))}`);
+        }
+        if (current !== target && !stat.isDirectory()) {
+            throw new Error(`${label} has a non-directory path component: ${normalizePath(path.relative(projectRoot, current))}`);
+        }
+    }
+    return target;
+}
+function mkdirpAbsolute(target, label = "path") {
+    if (!isInsideProject(target)) {
+        throw new Error(`${label} must stay inside the project root: ${target}`);
+    }
+    const relative = path.relative(projectRoot, target);
+    if (!relative)
+        return;
+    let current = projectRoot;
+    for (const part of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, part);
+        if (fs.existsSync(current)) {
+            const stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink()) {
+                throw new Error(`${label} refuses to follow symlink: ${normalizePath(path.relative(projectRoot, current))}`);
+            }
+            if (!stat.isDirectory()) {
+                throw new Error(`${label} has a non-directory path component: ${normalizePath(path.relative(projectRoot, current))}`);
+            }
+            continue;
+        }
+        fs.mkdirSync(current);
+    }
+}
+function writeFileNoFollow(filePath, content) {
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+    const fd = fs.openSync(filePath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_TRUNC | noFollow, 0o666);
+    try {
+        fs.writeFileSync(fd, content);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
 function exists(relativePath) {
     return fs.existsSync(abs(relativePath));
 }
 function read(relativePath) {
-    return fs.readFileSync(abs(relativePath), "utf8");
+    const filePath = assertNoSymlinkInProjectPath(relativePath, true, "managed read");
+    return fs.readFileSync(filePath, "utf8");
 }
 function write(relativePath, content) {
-    const filePath = abs(relativePath);
-    fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, content);
+    const filePath = assertNoSymlinkInProjectPath(relativePath, true, "managed write");
+    mkdirpAbsolute(path.dirname(filePath), "managed write");
+    writeFileNoFollow(filePath, content);
 }
 function mkdirp(relativePath) {
-    fs.mkdirSync(abs(relativePath), { recursive: true });
+    const dirPath = assertNoSymlinkInProjectPath(relativePath, true, "managed directory");
+    mkdirpAbsolute(dirPath, "managed directory");
 }
 function writeManaged(relativePath, content) {
-    const previous = exists(relativePath) ? read(relativePath) : "";
+    const previous = exists(relativePath)
+        ? (assertNoSymlinkInProjectPath(relativePath, true, "managed read"), read(relativePath))
+        : "";
     if (previous === content)
         return "exists";
     write(relativePath, content);
@@ -86,6 +160,7 @@ function writeStarter(relativePath, content) {
         write(relativePath, content);
         return "created";
     }
+    assertNoSymlinkInProjectPath(relativePath, true, "managed read");
     const current = read(relativePath);
     if (current === content)
         return "exists";
@@ -111,6 +186,7 @@ function upsertMarkedSection(relativePath, startMarker, endMarker, section) {
         write(relativePath, `${section.trim()}\n`);
         return "created";
     }
+    assertNoSymlinkInProjectPath(relativePath, true, "managed read");
     const current = read(relativePath);
     const start = current.indexOf(startMarker);
     const end = current.indexOf(endMarker);
@@ -133,15 +209,17 @@ function upsertMarkedSection(relativePath, startMarker, endMarker, section) {
 function deleteIfGenerated(relativePath, sentinels) {
     if (!exists(relativePath))
         return "absent";
+    const filePath = assertNoSymlinkInProjectPath(relativePath, true, "managed delete");
     const current = read(relativePath);
     if (!sentinels.some((sentinel) => current.includes(sentinel)))
         return "manual-review";
-    fs.unlinkSync(abs(relativePath));
+    fs.unlinkSync(filePath);
     return "removed";
 }
 function parseJson(relativePath, fallback) {
     if (!exists(relativePath))
         return fallback;
+    assertNoSymlinkInProjectPath(relativePath, true, "managed read");
     try {
         return JSON.parse(read(relativePath));
     }
@@ -191,11 +269,60 @@ function isGitRepository() {
 function makeExecutable(relativePath) {
     if (!exists(relativePath))
         return;
-    const currentMode = fs.statSync(abs(relativePath)).mode;
-    fs.chmodSync(abs(relativePath), currentMode | 0o755);
+    const filePath = assertNoSymlinkInProjectPath(relativePath, true, "managed chmod");
+    const currentMode = fs.statSync(filePath).mode;
+    fs.chmodSync(filePath, currentMode | 0o755);
+}
+function containedProjectFileStat(relativePath) {
+    const filePath = resolveProjectPath(relativePath, "project file");
+    let stat;
+    try {
+        stat = fs.lstatSync(filePath);
+    }
+    catch {
+        return null;
+    }
+    if (stat.isSymbolicLink() || !stat.isFile())
+        return null;
+    let realPath = "";
+    try {
+        realPath = fs.realpathSync(filePath);
+    }
+    catch {
+        return null;
+    }
+    return isInsideProject(realPath) ? stat : null;
+}
+function containedProjectDirectoryStat(relativePath) {
+    const dirPath = resolveProjectPath(relativePath, "project directory");
+    let stat;
+    try {
+        stat = fs.lstatSync(dirPath);
+    }
+    catch {
+        return null;
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory())
+        return null;
+    let realPath = "";
+    try {
+        realPath = fs.realpathSync(dirPath);
+    }
+    catch {
+        return null;
+    }
+    return isInsideProject(realPath) ? stat : null;
+}
+function requireContainedProjectFile(relativePath, label = "project file") {
+    const filePath = resolveProjectPath(relativePath, label);
+    const stat = containedProjectFileStat(relativePath);
+    if (!stat) {
+        throw new Error(`${label} must be a regular file inside the project root and must not be a symlink: ${relativePath}`);
+    }
+    return { absolutePath: filePath, stat };
 }
 function walkFilesUnder(relativePath, predicate, acc = []) {
-    const dirPath = abs(relativePath);
+    const dirPath = assertNoSymlinkInProjectPath(relativePath, true, "managed walk");
     if (!fs.existsSync(dirPath))
         return acc;
     for (const entry of fs.readdirSync(dirPath, { withFileTypes: true })) {

package/docs/README.md

@@ -0,0 +1,11 @@
+# Project Librarian Docs
+
+Start from the main [README](../README.md) when evaluating the project. These pages hold the details that are useful after the first-screen overview.
+
+| Document | Contents |
+| --- | --- |
+| [Usage](usage.md) | Install scopes, runner paths, generated files, migration behavior, and common agent requests. |
+| [Code Evidence](code-evidence.md) | Code-evidence index, MCP server, freshness contract, scale gate, language support, and native helper policy. |
+| [CLI Reference](cli-reference.md) | Complete command and option reference. |
+| [Benchmark Evidence](benchmarks.md) | Published benchmark claims, limits, task-family definitions, and reproduction commands. |
+| [Maintainer Guide](maintainer.md) | Local development, release readiness, trusted publishing, and benchmark operations. |

package/docs/benchmarks.md

@@ -0,0 +1,64 @@
+# Benchmark Evidence
+
+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.
+
+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.
+
+## Reproduce A Release Candidate
+
+```bash
+npm run benchmark:release:preview
+npm run benchmark:release -- --allow-codex-run
+```
+
+Measured release runs stream `[benchmark:progress]` lines to stderr for the scenario count, expected Codex exec total, current exec ordinal, phase, prompt id, exit status, elapsed time, and raw JSONL path. stdout stays reserved for the final JSON result.
+
+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.
+
+## Wiki Track
+
+Cost-weighted tokens, Project Librarian vs control:
+
+| Scale | decision_lookup | aggregation | multi_session (2nd session) |
+| --- | --- | --- | --- |
+| Small | 14.4% less | 81.0% more | 22.0% less |
+| Medium | 52.0% less | 19.0% less | 54.1% less |
+| Large | 71.1% less | 29.0% less | 71.8% less |
+
+Latest synthetic wiki-track release candidate: 2026-06-19, `gpt-5.5`, 42 scenarios, 3 measured runs plus 1 warmup each. The overall claim gate **passed**: 42/42 scenarios passed correctness, all 42 scenarios were claimable, and every corpus gate met the 3-run minimum.
+
+The release claim is bounded to the synthetic wiki-routing track and the listed task families. It is not a claim about code-graph behavior, real repositories, every agent surface, or every question shape. Published boundaries remain visible: small `aggregation` still costs 81.0% more with the wiki, small `release_policy` costs 9.4% more in the full report, and `aggregation` stays slower at every scale even when token cost drops.
+
+## Code-Graph Track
+
+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.
+
+## Benchmark Names
+
+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:
+
+- **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** - trace the full set of direct and indirect importers for a changing module.
+- **ownership_lookup** - resolve the owner by CODEOWNERS last-match precedence.
+- **workspace_graph** - resolve the workspace/package dependency graph.
+
+## Maintainer Commands
+
+Maintainer benchmark commands also live in [benchmarks/README.md](../benchmarks/README.md). They are for release evidence and public claim validation, not normal end-user setup.

package/docs/cli-reference.md

@@ -0,0 +1,60 @@
+# CLI Reference
+
+Use the resolved local runner for automation or direct CLI execution:
+
+```bash
+node .codex/skills/project-librarian/dist/init-project-wiki.js [init|update] [options]
+node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope user|project] [--agents codex|claude|cursor|gemini|all]
+```
+
+`install-skill` remains a compatibility alias for `install`.
+
+`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. When project-scoped Project Librarian skill installs already exist for the selected agent surfaces, `update` copies the current package's reusable skill files into those project skill directories before refreshing the managed setup.
+
+### Important Options
+
+| Option | Purpose |
+| --- | --- |
+| `install --scope user|project --agents <list> --dry-run` | Install reusable skill files globally or into the current repository; `--dry-run` previews copied files for install only. |
+| `update --agents <list>` | Refresh an existing setup and existing project-scoped skill copies; selected surfaces can be `codex`, `claude`, `cursor`, `gemini`, or `all`. |
+| `--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, 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. `--fix` is only a modifier for `--doctor`. |
+| `--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. |
+| `--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> --category <category>` | Append a candidate note to the wiki inbox; category defaults to `project-candidate`. |
+| `--handoff-save --goal <goal> --state <state> --next <action>` | Save generated local session handoff state under `.project-wiki/session/`. Repeat `--next`, `--decision`, `--blocked`, `--open-question`, `--verification`, `--last-success-command`, and `--last-failure-command` as needed. |
+| `--handoff-show`, `--handoff-status`, `--handoff-clear` | Print, inspect, or remove generated session handoff state. Startup hooks mention the handoff when it exists but do not inject the full file by default. |
+| `--handoff-promote-inbox` | Append selected generated handoff facts to `wiki/inbox/project-candidates.md` as a pending candidate. It does not write canonical, plan, or decision pages. |
+| `--handoff-injection-enable`, `--handoff-injection-disable`, `--handoff-injection-status` | Opt in, opt out, or inspect the capped full handoff injection experiment. Default startup behavior remains pointer-only. |
+| `--issue-draft --issue-title <title>` | Print a read-only GitHub issue body draft for problems or side effects. |
+| `--issue-create --issue-title <title> --issue-body-file <path>` | Create a GitHub issue through `gh` after explicit user approval; `--issue-body-file` reuses an existing Markdown body. |
+| `--glossary-init` | Create and route the optional glossary page. |
+| `--prune-check` | Report active pages with stale or unresolved lifecycle signals. |
+| `--prune-check --prune-check-strict` | Omit pages selected only because their `updated` date is older than today. |
+| `--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-scope <path>` | With `--code-index`, restrict indexing to one or more project-relative files or directories. |
+| `--code-index-out <path>` | Use a custom SQLite output path under `.project-wiki/`; applies to index and read modes. |
+| `--acknowledge-small-repo` | With `--code-index`, proceed below the ~5k-file scale gate after the cost warning. |
+| `--incremental`, `--code-index-incremental`, `--code-index-full` | With `--code-index`, require an incremental update or force a full rebuild. |
+| `--code-parser <mode>` | With `--code-index`, select `default` or optional `tree-sitter` extraction. |
+| `--code-index-health` | Inspect code evidence cache compatibility and print rebuild guidance without writing. |
+| `--code-index-engine <engine>` | Override the default `auto` index engine with `typescript` or `native-rust`. |
+| `--code-status`, `--code-files` | Inspect cache freshness or list indexed files. |
+| `--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/docs/code-evidence.md

@@ -0,0 +1,87 @@
+# Code Evidence
+
+Project Librarian can build a disposable SQLite index under `.project-wiki/` and serve it through read-only CLI and MCP surfaces. This is optional; the planning wiki works without it.
+
+## Freshness Contract
+
+Before citing `--code-report`, `--code-impact`, `--code-context-pack`, or MCP tool output as current code-structure evidence, run:
+
+```bash
+project-librarian --code-status
+```
+
+or MCP `code_status`, and require `stale_files: 0`. Stale reports are pointers for rebuild, not authoritative project truth.
+
+## Scale Gate
+
+The code-evidence index is measured as a scale crossover, not a universal win. Below ~5k indexable files, `--code-index` halts unless `--acknowledge-small-repo` is passed. Bootstrap skips MCP auto-registration unless an existing `.project-wiki` SQLite index shows the user already opted in.
+
+Measured release evidence:
+
+| 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 index pays off only on genuinely large repositories for expensive traversal questions. Cheap lookups can lose even at larger scale.
+
+## MCP Server
+
+`project-librarian mcp` runs a hand-rolled stdio MCP server (JSON-RPC 2.0 over newline-delimited JSON, no MCP SDK dependency) that serves the existing `.project-wiki` code-evidence index read-only. The package's hard runtime dependency is `typescript`; code evidence also uses Node's `node:sqlite`, with Tree-sitter grammars remaining optional.
+
+The server exposes answer-shaped tools:
+
+- `code_context_pack`
+- `code_impact`
+- `code_ownership`
+- `code_workspace_graph`
+- `code_search`
+- `code_status`
+
+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`
+- `project-librarian://code/status`
+
+It includes prompt templates for wiki taxonomy updates, code impact traces, maintenance improvement reviews, 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
+```
+
+## Language Support Matrix
+
+The matrix lists languages with implemented symbol/import extraction. Other recognized extensions are inventory-only. Default mode uses `typescript-ast`, `*-light` extraction for the listed non-JS languages, config extraction, and inventory rows. `--code-parser tree-sitter` switches supported source files to `tree-sitter-*` profiles.
+
+| Language | Extensions | Default extraction | Tree-sitter extraction | Indexed evidence |
+| --- | --- | --- | --- | --- |
+| TypeScript | `.ts`, `.tsx`, `.cts`, `.mts` | `typescript-ast` | `tree-sitter-typescript`, `tree-sitter-tsx` | functions, classes, methods, variables, interfaces, types, enums, imports, exports, calls, common HTTP routes |
+| JavaScript | `.js`, `.jsx`, `.cjs`, `.mjs` | `typescript-ast` | `tree-sitter-javascript` | functions, classes, methods, variables, imports, exports, `require()` calls, calls, common HTTP routes |
+| Python | `.py` | `python-light` | `tree-sitter-python` | functions, classes, `import`, `from ... import` |
+| Go | `.go` | `go-light` | `tree-sitter-go` | functions, methods, types, consts, vars, single imports, import blocks |
+| Rust | `.rs` | `rust-light` | `tree-sitter-rust` | functions, structs, enums, traits, impls, `use` imports |
+| Java | `.java` | `java-light` | `tree-sitter-java` | classes, interfaces, enums, methods, imports |
+| PHP | `.php` | `php-light` | `tree-sitter-php` | functions, classes, interfaces, traits, methods, namespace uses |
+| Kotlin | `.kt`, `.kts` | `kotlin-light` | `tree-sitter-kotlin` | functions, classes, objects, imports |
+| Swift | `.swift` | `swift-light` | `tree-sitter-swift` | functions, classes, structs, protocols, enums, imports |
+| C | `.c`, `.h` | `c-light` | `tree-sitter-c` | functions, structs, enums, includes |
+| C++ | `.cc`, `.cpp`, `.cxx`, `.hpp`, `.hh`, `.hxx` | `cpp-light` | `tree-sitter-cpp` | functions, classes/structs, namespaces, enums, includes/usings |
+| C# | `.cs` | `csharp-light` | `tree-sitter-csharp` | classes, interfaces, structs, enums, methods, usings |
+
+Recognized but inventory-only extensions include `.rb`, `.vue`, and `.css`. Config files (`.json`, `.yaml`, `.yml`, `.toml`, `.env.example`, `package.json`, `tsconfig.json`, `Dockerfile`, and `Makefile`) are indexed as configuration or inventory evidence.
+
+## Native Helper Policy
+
+Experimental `--code-index-engine native-rust` runs the native helper for `typescript-ast`, `config`, the listed `*-light` profiles, and inventory-only source files. Omitted `--code-index-engine` means `auto`; full-index auto uses the native helper when a helper is available and at least one structurally extracted native profile is present, while config-only or inventory-only repositories stay on TypeScript. Compatible incremental auto uses the Rust direct-writer when a helper is available and the changed files are native-eligible.
+
+Helper resolution checks `PROJECT_LIBRARIAN_NATIVE_INDEXER` first, then `dist/native/<platform>-<arch>/project-librarian-indexer` or `.exe`; Linux musl installs resolve to `dist/native/linux-<arch>-musl/`.
+
+Public releases must not ship only one staged helper. `release:check` accepts either no packaged native helper or a complete supported matrix (`darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-arm64-musl`, `linux-x64`, `linux-x64-musl`, `win32-arm64`, `win32-x64`), checks helper executable bits, Mach-O/ELF/PE platform headers, and the packaged-helper SHA-256 manifest. The GitHub publish workflow builds the supported helper matrix, runs `npm run native:package-manifest`, verifies `npm run native:package-audit:matrix`, and publishes only after the final helper-including package passes `npm run release:check`.

package/docs/ko/README.md

@@ -0,0 +1,13 @@
+# Project Librarian 문서
+
+프로젝트를 처음 평가할 때는 먼저 [한국어 README](../../README.ko.md)를 읽으세요. 이 디렉터리는 첫 화면에 모두 담기에는 긴 세부 정보를 한국어로 정리합니다.
+
+이 한국어 문서는 GitHub 저장소용입니다. npm 패키지에는 영어 상세 문서만 포함되며, `docs/ko/`는 포함하지 않습니다.
+
+| 문서 | 내용 |
+| --- | --- |
+| [사용 가이드](usage.md) | 설치 범위, 실행 경로, 생성 파일, 마이그레이션 동작, 일반 에이전트 요청. |
+| [코드 근거](code-evidence.md) | 코드 근거 인덱스, MCP 서버, 최신성 계약, 규모 게이트, 언어 지원, 네이티브 헬퍼 정책. |
+| [CLI 참조](cli-reference.md) | 전체 명령과 옵션 참조. |
+| [벤치마크 근거](benchmarks.md) | 공개 벤치마크 주장, 한계, 작업 유형, 재현 명령. |
+| [관리자 가이드](maintainer.md) | 로컬 개발, 릴리스 준비, 신뢰 배포, 벤치마크 운영. |