project-librarian 0.5.5 → 0.5.7

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,61 @@
+# 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 and required local-runner runtime dependencies 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 and required local-runner runtime dependencies 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-index-migrate` | With `--code-index`, explicitly approve replacing an existing index whose schema version differs from the current package. |
+| `--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,93 @@
+# 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.
+
+## Schema Migration
+
+The code evidence index is disposable, but Project Librarian still treats schema-version changes as an explicit migration boundary. If an existing `.project-wiki/code-evidence.sqlite` has a different schema version, `--code-index` stops before replacing the database and prints a migration-required message with the approval command.
+
+Run `project-librarian --code-index-health` to inspect the current index. To approve replacing an incompatible-schema index, rerun the build with `--code-index --code-index-migrate` plus the same scope/parser options you want for the new index. `--incremental` cannot migrate schema versions.
+
+## 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) | 로컬 개발, 릴리스 준비, 신뢰 배포, 벤치마크 운영. |

package/docs/ko/benchmarks.md

@@ -0,0 +1,64 @@
+# 벤치마크 근거
+
+여기 수치는 모든 상황에 대한 약속이 아니라 관리자 릴리스 근거입니다. 모든 값은 실제 Codex JSONL 사용량과 로컬 실행 시간(ChatGPT/Codex 인증, `gpt-5.5`)이며, 격리된 Codex home, 허용 목록 전용 환경, 깨끗한 작업 트리, 실행 후 fixture 검증 조건에서 측정했습니다. 각 시나리오는 측정 3회와 예열 1회로, Project Librarian이 없는 `organic` 대조군과 비교했습니다.
+
+위키 라우팅 트랙과 코드 그래프 트랙은 분리해 측정하고 보고합니다. 한 트랙의 승리가 다른 트랙의 주장을 뒷받침하지 않습니다.
+
+## 릴리스 후보 재현
+
+```bash
+npm run benchmark:release:preview
+npm run benchmark:release -- --allow-codex-run
+```
+
+실측 릴리스 실행은 stderr에 `[benchmark:progress]` 줄을 스트리밍해 시나리오 수, 예상 Codex 실행 총량, 현재 실행 순번, 단계, 프롬프트 ID, 종료 상태, 경과 시간, 원시 JSONL 경로를 보여줍니다. stdout은 최종 JSON 결과 전용입니다.
+
+`benchmarks/reports/llm/` 아래 생성 보고서는 기본적으로 무시됩니다. 공개 주장 근거로 쓰려는 릴리스 기준선만 의도적으로 커밋해야 합니다.
+
+## 위키 트랙
+
+비용 가중 토큰, Project Librarian 대 대조군:
+
+| 규모 | decision_lookup | aggregation | multi_session (2번째 세션) |
+| --- | --- | --- | --- |
+| 소형 | 14.4% 적음 | 81.0% 많음 | 22.0% 적음 |
+| 중형 | 52.0% 적음 | 19.0% 적음 | 54.1% 적음 |
+| 대형 | 71.1% 적음 | 29.0% 적음 | 71.8% 적음 |
+
+최신 합성 위키 트랙 릴리스 후보는 2026-06-19에 `gpt-5.5`로 측정했으며, 42개 시나리오를 각 3회 측정하고 1회 예열했습니다. 전체 주장 게이트는 **통과**했습니다. 42/42개 시나리오가 정확성 검사를 통과했고, 42개 시나리오가 모두 claimable이었으며, 모든 corpus gate가 3-run 최소 조건을 충족했습니다.
+
+이 릴리스 주장은 합성 위키 라우팅 트랙과 표기된 작업 유형에 한정됩니다. 코드 그래프 동작, 실제 저장소, 모든 에이전트 표면, 모든 질문 형태에 대한 주장이 아닙니다. 숨기지 않는 한계도 남습니다. 소형 `aggregation`은 위키를 켰을 때 81.0% 더 비싸고, 전체 보고서의 소형 `release_policy`도 9.4% 더 비싸며, `aggregation`은 토큰 비용이 줄어드는 규모에서도 실행 시간은 매번 더 느립니다.
+
+## 코드 그래프 트랙
+
+SHA로 고정한 오픈소스 저장소 2곳에서, 손으로 작성한 정답 키와 격리된 Codex home에 주입한 답변 형태 MCP 도구로 측정했습니다. 평가기 거짓 양성 2건을 고치고 원시 JSONL에서 재채점한 뒤 30/30 정확으로 주장 게이트를 통과했으며, 원시 데이터에서 다시 계산하는 것이 상시 감사 정책입니다.
+
+비용 가중 토큰, Project Librarian 대 대조군:
+
+| 질문 | excalidraw (약 1.2k 파일) | backstage (약 11.8k 파일) |
+| --- | --- | --- |
+| impact_trace | 117% 많음 | **27.7% 적음** |
+| workspace_graph | 106% 많음 | 2.6% 적음 |
+| ownership_lookup | - | 99% 많음 |
+
+주장은 규모 교차점이며 손실도 승리 옆에 공개합니다. 11.8k 파일 저장소에서는 비싼 순회 질문(`impact_trace` 비용 가중 토큰 27.7% 감소, 스캔 바이트 24.5% 감소)에서 이기고 workspace graph는 손익분기입니다. 반면 소형 저장소에서는 모두 지고, CODEOWNERS 소유권 같은 저렴한 조회는 모든 측정 규모에서 집니다.
+
+## 벤치마크 이름
+
+테스트 대상 저장소:
+
+- **excalidraw** - 실제 오픈소스 화이트보드/다이어그램 앱(약 1.2k 파일). 소형 저장소 표본.
+- **backstage** - Spotify의 오픈소스 개발자 포털 플랫폼(약 11.8k 파일). 대형 저장소 표본.
+
+질문 유형:
+
+- **decision_lookup** - 위키에서 가장 최근 프로젝트 결정과 그 날짜를 찾습니다.
+- **aggregation** - 여러 페이지에 흩어진 사실을 종합해야 답할 수 있는 질문입니다.
+- **multi_session** - 같은 프로젝트의 두 번째 세션으로, 지속되는 위키가 다음 세션에도 도움이 되는지 측정합니다.
+- **impact_trace** - 바뀌는 모듈의 직접/간접 importer 전체를 추적합니다.
+- **ownership_lookup** - CODEOWNERS 마지막 일치 우선순위로 소유자를 판정합니다.
+- **workspace_graph** - workspace/package 의존성 그래프를 판정합니다.
+
+## 관리자 명령
+
+관리자 벤치마크 명령은 [benchmarks/README.md](../../benchmarks/README.md)에도 있습니다. 이 명령은 릴리스 근거와 공개 주장 검증을 위한 것이며 일반 사용자 설정 절차가 아닙니다.

package/docs/ko/cli-reference.md

@@ -0,0 +1,61 @@
+# CLI 참조
+
+자동화나 직접 CLI 실행에는 확인된 로컬 실행 경로를 사용합니다.
+
+```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`은 `install`의 호환성 별칭으로 계속 지원됩니다.
+
+`update`는 기존 프로젝트 갱신을 명시하는 명령입니다. `--migrate`와 `--adopt-existing`를 거부합니다. 기존 문서나 위키 내용을 `wiki_legacy*`로 보존하고 검토해야 한다면 top-level `--migrate`를 사용합니다. 선택된 에이전트 표면에 프로젝트 범위 Project Librarian 스킬 설치가 이미 있으면 `update`는 현재 패키지의 재사용 가능한 스킬 파일과 로컬 실행기에 필요한 필수 런타임 의존성을 해당 프로젝트 스킬 디렉터리에 복사한 뒤 관리 설정을 갱신합니다.
+
+### 주요 옵션
+
+| 옵션 | 목적 |
+| --- | --- |
+| `install --scope user|project --agents <list> --dry-run` | 재사용 가능한 스킬 파일과 로컬 실행기에 필요한 필수 런타임 의존성을 전역 또는 현재 저장소에 설치합니다. `--dry-run`은 install에서 복사될 파일을 미리 보여줍니다. |
+| `update --agents <list>` | 기존 설정과 기존 프로젝트 범위 스킬 복사본을 갱신합니다. 표면은 `codex`, `claude`, `cursor`, `gemini`, `all` 중 하나입니다. |
+| `--migrate`, `--adopt-existing` | 기존 위키를 `wiki_legacy*`로 보존하고 migration inbox, unit-map, split-plan, coverage 검토 파일을 만듭니다. |
+| `--lint` | 파일을 수정하지 않고 생성된 설정을 검증합니다. |
+| `--link-check` | 깨진 위키 링크, 중복 route, orphan page, 시작 라우터 depth 예산 안에서 닿지 않는 페이지를 보고합니다. |
+| `--quality-check` | 오래되었거나 충돌하거나 품질이 낮은 위키 문서 신호를 보고합니다. |
+| `--doctor` | lint, link-check, quality-check를 함께 실행합니다. |
+| `--doctor --fix` | 진단 전에 생성된 index routing을 안전하게 갱신합니다. `--fix`는 `--doctor`의 modifier입니다. |
+| `--migration-lint` | migration coverage, unit-map, split-plan, review scaffolding을 일반 lint와 분리해 검증합니다. |
+| `--migration-quality-check` | migration 정책/구조 신호를 일반 quality-check와 분리해 보고합니다. |
+| `--migration-doctor` | migration-lint와 migration-quality-check를 함께 실행합니다. |
+| `--query <terms>` | 위키 경로, 메타데이터, 제목, 본문을 검색하고 크기 제한이 있는 answer-first 출력을 제공합니다. |
+| `--wiki-impact <page-or-term>` | 일치하는 페이지의 backlinks, `decision_ref` 인용, outgoing link, router depth를 보여줍니다. |
+| `--wiki-visualize` | `.project-wiki/wiki-graph.html`에 독립 실행형 정적 위키 그래프를 작성합니다. |
+| `--wiki-visualize-out <path>` | `--wiki-visualize`와 함께 사용해 `.project-wiki/` 아래 사용자 지정 저장소 상대 경로에 작성합니다. |
+| `--refresh-index` | 자동 발견된 위키 routing을 갱신합니다. |
+| `--capture-inbox --title <title> --content <content> --category <category>` | 후보 메모를 위키 inbox에 추가합니다. category 기본값은 `project-candidate`입니다. |
+| `--handoff-save --goal <goal> --state <state> --next <action>` | `.project-wiki/session/` 아래에 생성형 로컬 세션 핸드오프를 저장합니다. 필요하면 `--next`, `--decision`, `--blocked`, `--open-question`, `--verification`, `--last-success-command`, `--last-failure-command`를 반복합니다. |
+| `--handoff-show`, `--handoff-status`, `--handoff-clear` | 생성된 세션 핸드오프를 출력, 점검, 제거합니다. 시작 훅은 핸드오프가 있을 때 존재만 알리고 기본적으로 전체 파일을 주입하지 않습니다. |
+| `--handoff-promote-inbox` | 생성된 핸드오프의 선별된 사실을 `wiki/inbox/project-candidates.md`에 pending 후보로 추가합니다. canonical, plan, decision 페이지는 쓰지 않습니다. |
+| `--handoff-injection-enable`, `--handoff-injection-disable`, `--handoff-injection-status` | 제한된 전체 핸드오프 주입 실험을 켜고, 끄고, 상태를 확인합니다. 기본 시작 동작은 pointer-only입니다. |
+| `--issue-draft --issue-title <title>` | 문제나 부작용에 대한 읽기 전용 GitHub issue 본문 초안을 출력합니다. |
+| `--issue-create --issue-title <title> --issue-body-file <path>` | 명시적 사용자 승인 후 `gh`로 GitHub issue를 생성합니다. `--issue-body-file`은 기존 Markdown 본문을 재사용합니다. |
+| `--glossary-init` | 선택적 glossary 페이지를 만들고 route에 추가합니다. |
+| `--prune-check` | stale 또는 unresolved lifecycle 신호가 있는 active page를 보고합니다. |
+| `--prune-check --prune-check-strict` | `updated` 날짜가 오늘보다 오래됐다는 이유만으로 선택된 페이지는 제외합니다. |
+| `--review-migration`, `--semantic-migrate` | migration coverage와 inbox status를 migration review 파일에 동기화합니다. |
+| `--no-git-config` | `git core.hooksPath`를 바꾸지 않고 훅 파일을 설치합니다. |
+| `--code-index` | 폐기 가능한 코드 근거 인덱스를 만듭니다. |
+| `--code-scope <path>` | `--code-index`와 함께 사용해 인덱싱 범위를 하나 이상의 프로젝트 상대 파일/디렉터리로 제한합니다. |
+| `--code-index-out <path>` | `.project-wiki/` 아래 사용자 지정 SQLite 출력 경로를 사용합니다. index와 read mode에 모두 적용됩니다. |
+| `--acknowledge-small-repo` | `--code-index`와 함께 사용해 약 5k 파일 미만 규모 경고 후에도 진행합니다. |
+| `--incremental`, `--code-index-incremental`, `--code-index-full` | `--code-index`와 함께 사용해 증분 갱신을 요구하거나 전체 재생성을 강제합니다. |
+| `--code-index-migrate` | `--code-index`와 함께 사용해 기존 인덱스의 스키마 버전이 현재 패키지와 다를 때 교체를 명시적으로 승인합니다. |
+| `--code-parser <mode>` | `--code-index`와 함께 사용해 `default` 또는 선택적 `tree-sitter` 추출을 선택합니다. |
+| `--code-index-health` | 파일을 쓰지 않고 코드 근거 캐시 호환성과 재빌드 안내를 출력합니다. |
+| `--code-index-engine <engine>` | 기본 `auto` 인덱스 엔진을 `typescript` 또는 `native-rust`로 override합니다. |
+| `--code-status`, `--code-files` | 캐시 최신성을 확인하거나 인덱싱된 파일을 나열합니다. |
+| `--code-report` | 근거 인덱스에서 구조와 소유권 요약을 출력합니다. |
+| `--code-report-section <section>` | `coverage`, `ownership`, `languages`, `parsers`, `workspaces`, `workspace-graph`, `routes`, `hotspots`, `configs`, `edges` 중 한 섹션을 출력합니다. |
+| `--code-impact <term>` | 파일, 심볼, route, import, edge, owner 영향 근거를 보여줍니다. |
+| `--code-context-pack <term>` | 구조 파일, 심볼, route, import, edge, 소유권 근거를 담은 예산 제한 first-pass context pack을 출력합니다. |
+| `--code-search-symbol <term>` | 인덱싱된 심볼을 검색합니다. |
+| `--code-query <sql>` | 근거 인덱스에서 보수적 읽기 전용 SQL을 실행합니다. |

package/docs/ko/code-evidence.md

@@ -0,0 +1,93 @@
+# 코드 근거
+
+Project Librarian은 `.project-wiki/` 아래 폐기 가능한 SQLite 인덱스를 만들고, 읽기 전용 CLI와 MCP 표면으로 제공할 수 있습니다. 이 기능은 선택 사항이며 계획 위키는 코드 근거 없이도 동작합니다.
+
+## 최신성 계약
+
+`--code-report`, `--code-impact`, `--code-context-pack`, MCP 도구 출력을 현재 코드 구조 근거로 인용하기 전에는 다음을 실행합니다.
+
+```bash
+project-librarian --code-status
+```
+
+또는 MCP `code_status`를 실행하고 `stale_files: 0`인지 확인해야 합니다. 오래된 보고서는 재빌드가 필요하다는 신호이지 권위 있는 프로젝트 진실이 아닙니다.
+
+## 규모 게이트
+
+코드 근거 인덱스는 모든 상황에서 이기는 도구가 아니라 규모 교차점이 있는 도구로 측정됐습니다. 인덱싱 가능 파일이 약 5k개 미만이면 `--acknowledge-small-repo`를 주지 않는 한 `--code-index`는 중단됩니다. 기존 `.project-wiki` SQLite 인덱스로 사용자가 이미 선택했음을 알 수 있는 경우가 아니면 부트스트랩은 MCP 자동 등록도 건너뜁니다.
+
+측정된 릴리스 근거:
+
+| 질문 | excalidraw (약 1.2k 파일) | backstage (약 11.8k 파일) |
+| --- | --- | --- |
+| impact_trace | 117% 많음 | **27.7% 적음** |
+| workspace_graph | 106% 많음 | 2.6% 적음 |
+| ownership_lookup | - | 99% 많음 |
+
+인덱스는 큰 저장소의 비싼 순회 질문에서만 효과가 납니다. 저렴한 조회는 큰 규모에서도 손해일 수 있습니다.
+
+## MCP 서버
+
+`project-librarian mcp`는 기존 `.project-wiki` 코드 근거 인덱스를 읽기 전용으로 제공하는 직접 구현 stdio MCP 서버입니다. 줄바꿈 구분 JSON 위의 JSON-RPC 2.0을 사용하며 MCP SDK 의존성은 없습니다. 패키지의 필수 런타임 의존성은 `typescript`이고, 코드 근거 기능은 Node의 `node:sqlite`도 사용합니다. Tree-sitter 문법 패키지는 선택 사항입니다.
+
+서버가 제공하는 답변 형태 도구:
+
+- `code_context_pack`
+- `code_impact`
+- `code_ownership`
+- `code_workspace_graph`
+- `code_search`
+- `code_status`
+
+응답은 한 줄 답변으로 시작하고, 간결한 경로/심볼/시그니처 근거가 뒤따르며, 응답 길이를 제한합니다. `code_status`가 인덱스가 오래되었다고 보고하면 경고를 앞에 붙입니다.
+
+고정 리소스도 제공합니다.
+
+- `project-librarian://wiki/startup`
+- `project-librarian://wiki/index`
+- `project-librarian://code/status`
+
+위키 분류 갱신, 코드 영향 추적, 유지보수 개선 검토, 검색 품질 검토용 프롬프트 템플릿도 포함합니다. 리소스 읽기는 임의 파일 경로가 아니라 고정 URI 레지스트리에서만 처리합니다.
+
+부트스트랩은 Claude Code(`.mcp.json`), Cursor(`.cursor/mcp.json`), Gemini CLI(`.gemini/settings.json`의 `mcpServers`)에 서버를 등록하며 기존 서버와 키를 보존합니다. 저장소에 로컬 실행 경로가 있으면 `node <runner> mcp`를 사용하고, 없으면 설치된 `project-librarian mcp` 바이너리를 사용합니다.
+
+Codex는 MCP 서버를 사용자 수준에서만 등록하므로 부트스트랩은 프로젝트 수준 Codex MCP 설정을 쓰지 않습니다. Codex에서 쓰려면 한 번만 실행합니다.
+
+```bash
+codex mcp add project-librarian -- node .codex/skills/project-librarian/dist/init-project-wiki.js mcp
+```
+
+## 언어 지원 표
+
+이 표는 심볼/import 추출이 구현된 언어를 보여줍니다. 그 밖의 인식된 확장자는 inventory-only입니다. 기본 모드는 JS/TS에 `typescript-ast`, 나머지 언어에 `*-light`, 설정 추출, inventory row를 사용합니다. `--code-parser tree-sitter`는 지원 소스 파일을 `tree-sitter-*` 프로파일로 전환합니다.
+
+| 언어 | 확장자 | 기본 추출 | Tree-sitter 추출 | 인덱싱되는 근거 |
+| --- | --- | --- | --- | --- |
+| TypeScript | `.ts`, `.tsx`, `.cts`, `.mts` | `typescript-ast` | `tree-sitter-typescript`, `tree-sitter-tsx` | 함수, 클래스, 메서드, 변수, 인터페이스, 타입, enum, import/export, 호출, 일반 HTTP route |
+| JavaScript | `.js`, `.jsx`, `.cjs`, `.mjs` | `typescript-ast` | `tree-sitter-javascript` | 함수, 클래스, 메서드, 변수, import/export, `require()` 호출, 호출, 일반 HTTP route |
+| Python | `.py` | `python-light` | `tree-sitter-python` | 함수, 클래스, `import`, `from ... import` |
+| Go | `.go` | `go-light` | `tree-sitter-go` | 함수, 메서드, 타입, const, var, 단일 import, import block |
+| Rust | `.rs` | `rust-light` | `tree-sitter-rust` | 함수, struct, enum, trait, impl, `use` import |
+| Java | `.java` | `java-light` | `tree-sitter-java` | 클래스, 인터페이스, enum, 메서드, import |
+| PHP | `.php` | `php-light` | `tree-sitter-php` | 함수, 클래스, 인터페이스, trait, 메서드, namespace use |
+| Kotlin | `.kt`, `.kts` | `kotlin-light` | `tree-sitter-kotlin` | 함수, 클래스, object, import |
+| Swift | `.swift` | `swift-light` | `tree-sitter-swift` | 함수, 클래스, struct, protocol, enum, import |
+| C | `.c`, `.h` | `c-light` | `tree-sitter-c` | 함수, struct, enum, include |
+| C++ | `.cc`, `.cpp`, `.cxx`, `.hpp`, `.hh`, `.hxx` | `cpp-light` | `tree-sitter-cpp` | 함수, 클래스/struct, namespace, enum, include/using |
+| C# | `.cs` | `csharp-light` | `tree-sitter-csharp` | 클래스, 인터페이스, struct, enum, 메서드, using |
+
+`.rb`, `.vue`, `.css`는 인식하지만 inventory-only입니다. `.json`, `.yaml`, `.yml`, `.toml`, `.env.example`, `package.json`, `tsconfig.json`, `Dockerfile`, `Makefile`은 설정 또는 inventory 근거로 인덱싱됩니다.
+
+## 스키마 마이그레이션
+
+코드 근거 인덱스는 폐기 가능한 캐시지만, Project Librarian은 스키마 버전 변경을 명시적 마이그레이션 경계로 취급합니다. 기존 `.project-wiki/code-evidence.sqlite`의 스키마 버전이 현재 패키지와 다르면 `--code-index`는 데이터베이스를 교체하기 전에 멈추고 마이그레이션 필요 메시지와 승인 명령을 출력합니다.
+
+현재 인덱스 상태는 `project-librarian --code-index-health`로 확인합니다. 호환되지 않는 스키마의 인덱스 교체를 승인하려면 새 인덱스에 적용할 scope/parser 옵션과 함께 `--code-index --code-index-migrate`를 다시 실행합니다. `--incremental`은 스키마 버전을 마이그레이션할 수 없습니다.
+
+## 네이티브 헬퍼 정책
+
+실험적 `--code-index-engine native-rust`는 `typescript-ast`, `config`, 표의 `*-light` 프로파일, inventory-only 소스 파일을 네이티브 헬퍼로 처리합니다. `--code-index-engine`을 생략하면 `auto`입니다. full-index auto는 헬퍼를 사용할 수 있고 구조적으로 추출되는 네이티브 프로파일이 하나 이상 있을 때 네이티브 헬퍼를 사용하며, config-only 또는 inventory-only 저장소는 TypeScript 경로에 남깁니다. 호환되는 incremental auto는 헬퍼를 사용할 수 있고 변경 파일이 native-eligible이면 Rust direct-writer를 사용합니다.
+
+헬퍼 탐색은 `PROJECT_LIBRARIAN_NATIVE_INDEXER`를 먼저 보고, 없으면 `dist/native/<platform>-<arch>/project-librarian-indexer` 또는 `.exe`를 확인합니다. Linux musl 설치는 `dist/native/linux-<arch>-musl/`을 확인합니다.
+
+공개 릴리스는 staged helper 하나만 배포하면 안 됩니다. `release:check`는 packaged native helper가 없거나 지원 플랫폼 전체 matrix(`darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-arm64-musl`, `linux-x64`, `linux-x64-musl`, `win32-arm64`, `win32-x64`)가 있을 때만 통과하며, helper 실행 비트, Mach-O/ELF/PE 플랫폼 헤더, packaged-helper SHA-256 manifest도 확인합니다.

package/docs/ko/maintainer.md

@@ -0,0 +1,76 @@
+# 관리자 가이드
+
+README 첫 화면에 넣기에는 깊은 개발과 릴리스 운영 정보를 모은 문서입니다.
+
+## 개발
+
+소스는 TypeScript입니다. 커밋된 `dist/` 디렉터리는 npm 바이너리와 설치된 스킬 복사본이 사용하는 컴파일된 JavaScript입니다.
+
+```bash
+npm install
+npm run typecheck
+npm run build
+npm run check:dist
+npm test
+npm run test:coverage
+npm run benchmark:llm:raw-audit
+npm run benchmark:llm:delta-analysis
+npm run benchmark:claim-ledger
+npm run release:check
+npm pack --dry-run
+```
+
+`src/` 아래 TypeScript를 수정했다면 커밋 전에 다시 빌드해 `dist/`가 최신 상태를 유지하게 해야 합니다. `npm run check:dist`는 체크인된 생성 파일이 최신 빌드 출력과 일치하는지 확인합니다.
+
+`npm run test:coverage`는 Node 내장 coverage를 사용하며 line, branch, function threshold를 보수적으로 설정합니다. coverage는 단순 보고서가 아니라 regression gate입니다.
+
+지원 런타임 하한은 Node.js 22.13+입니다. 개발 type definition은 Node 22 지원 계약과 맞아야 하며, 지원 사용자에게 없는 API를 TypeScript가 허용하지 않도록 Node 22 호환성 확인으로 뒷받침해야 합니다.
+
+## 릴리스 준비
+
+`npm run release:check`는 로컬 전용 관리자 게이트입니다. 테스트, Node 내장 coverage, 벤치마크 parser smoke, real-corpus offline demo, benchmark release preview, benchmark claim-ledger classification, raw hygiene audit, package dry-run inspection, native helper package-matrix, binary-format, SHA-256 provenance-manifest 검사, dist 실행 가능 여부/parity, README benchmark-claim boundary, 문서 CLI reference coverage, README/README.ko code-evidence freshness/scale-gate 문서화, trusted-publishing workflow 검사를 실행합니다.
+
+이 명령은 publish하지 않고, raw benchmark artifact를 삭제하지 않으며, 실측 Codex benchmark도 실행하지 않습니다.
+
+`release:check` 통과는 런타임 보증이 아니라 재현 가능한 릴리스 준비 근거입니다. 현재 checkout에서 위 로컬 게이트를 통과했음을 증명하며, package dry run이 예상 publish boundary 안에 머물고, source/test/repo-local wiki/workflow state/raw benchmark output/local cache를 제외하며, partial, 잘못 라벨링된, manifest 없는, stale manifest, checksum mismatch 상태의 `dist/native/` helper matrix를 포함하지 않는지도 확인합니다.
+
+## 배포
+
+배포는 GitHub Release가 published된 뒤 `.github/workflows/publish.yml`에서 처리합니다. Non-OIDC job은 source package를 검증하고, 지원 native helper를 빌드하고, `dist/native/`를 조립하고, helper manifest를 생성하고, helper가 포함된 package에서 `release:check`를 실행합니다.
+
+최종 publish job은 보호된 `npm-publish` GitHub Environment를 대상으로 하며, GitHub OIDC를 통한 npm trusted publishing(`id-token: write`)과 `npm publish --access public`을 사용하고 npm provenance를 자동 생성합니다. 정상 release path에는 `NODE_AUTH_TOKEN`이나 npm token secret을 쓰면 안 되며, release-critical first-party GitHub Actions는 full commit SHA에 pin되어야 합니다. `release:check`가 이 workflow contract를 로컬에서 검증합니다.
+
+Trusted publishing과 npm provenance는 패키지가 GitHub OIDC workflow를 통해 배포됐음을 증명합니다. benchmark correctness, end-user repository의 code-evidence freshness, security audit를 증명하지는 않습니다. 이들은 별도 근거 트랙입니다.
+
+## 코드 근거 런타임 점검
+
+코드 근거 런타임/저장소 점검에는 `npm run perf:code-efficiency`를 사용합니다. 이 명령은 3k/10k/50k fixture를 만들고 `benchmarks/reports/code-performance-efficiency/current.json`과 `.md`를 작성합니다. 명령 timing에는 CLI startup과 freshness check가 포함되며, `query_groups` 섹션은 대표 file/symbol/route/import/edge query의 직접 DB timing을 보고합니다.
+
+보고서는 체크인된 `mixed-monorepo`, `web-service`, `python-cli`, `docs-heavy` corpus도 synthetic scale fixture와 분리해 측정합니다. `--actual-repo <path>`를 반복하고 `--compare-native`를 함께 주면 local real repository를 같은 TypeScript/Rust timing 및 row-delta report에 포함할 수 있습니다. source directory는 수정하지 않습니다.
+
+실제 저장소 native policy check:
+
+```bash
+npm run perf:code-full-rebuild -- --source-root <dir> --helper <helper>
+npm run perf:code-incremental -- --source-root <dir> --helper <helper>
+```
+
+첫 명령은 fresh repo copy에서 TypeScript와 Rust forced full rebuild를 비교합니다. 두 번째 명령은 controlled file mutation 뒤 TypeScript incremental update와 Rust incremental writer를 비교합니다.
+
+## 벤치마크 raw 출력
+
+실측 LLM benchmark run은 1일보다 오래된 stale prior raw run directory와 isolated Codex home을 자동 정리하고, claimable-run failure가 발생해도 current run의 home을 정리합니다. Raw JSONL, stderr, report, manifest는 retention window 안에서는 남습니다.
+
+오래된 ignored raw output은 retained isolated Codex home을 삭제하기 전에 dry-run-first helper로 감사할 수 있습니다.
+
+```bash
+npm run benchmark:llm:raw-audit -- --older-than-days 14
+npm run benchmark:llm:prune-raw -- --older-than-days 14
+npm run benchmark:llm:prune-raw -- --older-than-days 14 --execute
+```
+
+`npm run benchmark:llm:delta-analysis`는 체크인된 실측 LLM report를 읽고 Codex를 실행하지 않은 채 cost-weighted regression을 순위화합니다. `-- --include-traces`를 추가하면 대표 raw JSONL command trace를 포함하고 broad-search/router-read driver를 분류합니다. 소형 aggregation처럼 약한 cell에 새 benchmark claim을 추가하기 전에 먼저 보는 진단 지점입니다.
+
+실측 LLM run은 기본적으로 `--scenario-order run-major-balanced`를 사용합니다. 각 measured run index가 선택된 모든 scenario를 실행하고, 반복마다 순서를 뒤집어 with/without pair가 반복 실행에서 condition별로 뭉치지 않게 합니다. 오래된 scenario-grouped 진단을 재현할 때만 `--scenario-order scenario-major`를 사용합니다.
+
+`npm run typecheck:ts7`은 선택적 TypeScript 7 RC 호환성 probe입니다. `npx`를 사용하며, compiler API와 이 프로젝트 TypeScript extractor의 측정된 parity record가 생길 때까지 `test`, `release:check`, CI gate 밖에 둡니다.