project-librarian 0.5.5 → 0.5.7

package/docs/ko/usage.md

@@ -0,0 +1,168 @@
+# 사용 가이드
+
+README 빠른 시작 이후에 보는 문서입니다. 설치 범위, 실행 경로, 생성 파일, 마이그레이션 동작, 에이전트 요청 예시를 다룹니다.
+
+## 설치 범위
+
+초기 스킬 설치나 특정 레지스트리 버전으로 프로젝트를 갱신할 때는 `npx`를 사용합니다.
+
+```bash
+npx project-librarian@latest install --scope user --agents all
+```
+
+현재 저장소 안에 설치하려면 다음을 사용합니다.
+
+```bash
+npx project-librarian@latest install --scope project --agents all
+```
+
+`install`은 재사용 가능한 스킬 파일과 로컬 실행기에 필요한 필수 런타임 의존성을 복사합니다. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `wiki/`, `.cursor/rules/`, `.cursor/hooks.json`, `.gemini/settings.json`, `.codex/hooks.json`, `.claude/settings.json`은 만들거나 갱신하지 않습니다. `install-skill`은 호환성 별칭으로 계속 지원됩니다.
+
+| 상황 | 명령 |
+| --- | --- |
+| 지원하는 모든 에이전트에 전역 설치 | `npx project-librarian@latest install --scope user --agents all` |
+| 현재 저장소에 설치 | `npx project-librarian@latest install --scope project --agents all` |
+| Codex만 설치 | `npx project-librarian@latest install --agents codex` |
+| Claude Code만 설치 | `npx project-librarian@latest install --agents claude` |
+| Cursor만 설치 | `npx project-librarian@latest install --agents cursor` |
+| Gemini CLI만 설치 | `npx project-librarian@latest install --agents gemini` |
+| 설치 결과 미리 보기 | `npx project-librarian@latest install --scope project --agents all --dry-run` |
+
+`--agents`는 `codex,claude,cursor,gemini` 같은 쉼표 구분 값도 받습니다. `all`은 지원하는 모든 에이전트를 대상으로 합니다. `--scope`는 `user` 또는 `project`를 받습니다.
+
+프로젝트 설정/갱신 실행기도 `--agents`를 받습니다. 새 설정은 프로젝트 범위 Project Librarian 스킬 설치가 없을 때만 지원하는 모든 에이전트 표면을 기본으로 만듭니다. 저장소에 이미 `.codex/skills/project-librarian/`, `.claude/skills/project-librarian/` 같은 프로젝트 범위 스킬이 있으면 첫 설정도 그 설치된 에이전트 집합을 기본값으로 사용합니다.
+
+마이그레이션 없는 기존 설정 갱신은 저장소에 이미 있는 에이전트 표면만 보존해서 갱신합니다. 따라서 Codex와 Claude 파일만 있던 저장소는 일반 갱신만으로 Cursor나 Gemini 파일이 새로 생기지 않습니다. 새 표면을 의도적으로 추가하려면 `project-librarian update --agents cursor` 또는 `project-librarian update --agents all`처럼 명시합니다. 목록에 없는 표면을 삭제하지는 않습니다.
+
+`project-librarian update`는 선택된 표면에 이미 프로젝트 범위 Project Librarian 스킬 설치가 있으면 현재 실행 중인 패키지의 재사용 가능한 스킬 파일과 프로젝트 로컬 실행기에 필요한 런타임 의존성을 그 프로젝트 스킬 디렉터리로 동기화합니다. 기본적으로 새 프로젝트 범위 스킬 설치를 만들지는 않고, 사용자 범위 스킬 설치도 갱신하지 않습니다. 사용자 범위 스킬은 `install --scope user`로 명시적으로 갱신합니다.
+
+## 실행 경로
+
+이 경로들은 주로 에이전트와 자동화를 위한 참조입니다. 설치 후 에이전트는 `npx`가 아니라 설치된 로컬 복사본을 `node`로 실행해야 합니다. 제한된 에이전트 환경에서 네트워크 접근과 버전이 고정되지 않은 패키지 실행을 피하기 위해서입니다.
+
+| 설치 위치 | 실행 경로 |
+| --- | --- |
+| 프로젝트 범위 Codex 스킬 | `node .codex/skills/project-librarian/dist/init-project-wiki.js` |
+| 프로젝트 범위 Claude 스킬 | `node .claude/skills/project-librarian/dist/init-project-wiki.js` |
+| 프로젝트 범위 Cursor 스킬 | `node .cursor/skills/project-librarian/dist/init-project-wiki.js` |
+| 프로젝트 범위 Gemini 스킬 | `node .gemini/skills/project-librarian/dist/init-project-wiki.js` |
+| 사용자 범위 Codex 스킬 | `node ~/.codex/skills/project-librarian/dist/init-project-wiki.js` |
+| 사용자 범위 Claude 스킬 | `node ~/.claude/skills/project-librarian/dist/init-project-wiki.js` |
+| 사용자 범위 Cursor 스킬 | `node ~/.cursor/skills/project-librarian/dist/init-project-wiki.js` |
+| 사용자 범위 Gemini 스킬 | `node ~/.gemini/skills/project-librarian/dist/init-project-wiki.js` |
+
+## 일반 에이전트 요청
+
+원하는 결과를 에이전트에게 말하면, 스킬이 요청을 로컬 실행 명령으로 연결합니다.
+
+위키 설정과 유지보수:
+
+| 목표 | 에이전트에게 요청 | 내부 동작 |
+| --- | --- | --- |
+| 위키 생성 또는 갱신 | "Project Librarian으로 이 저장소의 계획 위키를 설정하거나 갱신해줘." | `[init]` |
+| 마이그레이션 없는 기존 설정 갱신 | "이 저장소의 Project Librarian 설정을 위키 마이그레이션 없이 갱신해줘." | `update` |
+| npm 최신 패키지로 마이그레이션 없이 갱신 | "이 저장소를 최신 Project Librarian으로 위키 마이그레이션 없이 갱신해줘." | `npx project-librarian@latest update` |
+| 특정 에이전트 표면 추가 | "위키 마이그레이션 없이 Cursor Project Librarian 표면을 추가해줘." | `update --agents cursor` |
+| 기존 문서/위키 마이그레이션 | "Project Librarian으로 기존 docs/wiki 내용을 마이그레이션해줘." | `--migrate` |
+| 생성된 설정 검증 | "Project Librarian 검증을 실행해줘." | `--lint` |
+| 링크와 문서 품질 점검 | "Project Librarian 진단을 실행해줘." | `--doctor` |
+| 진단 전 라우팅 갱신 | "Project Librarian 라우팅을 갱신한 뒤 진단을 실행해줘." | `--doctor --fix` |
+| 위키 내용 검색 | "Project Librarian 위키에서 authentication decisions를 찾아줘." | `--query "authentication decisions"` |
+| 페이지 영향도 확인 | "decisions/release-policy의 Project Librarian 위키 영향도를 보여줘." | `--wiki-impact "decisions/release-policy"` |
+| 위키 그래프 생성 | "Project Librarian 위키 그래프 시각화를 생성해줘." | `--wiki-visualize` |
+| 후보 메모 저장 | "이 내용을 Project Librarian 후보 메모로 저장해줘: <내용>." | `--capture-inbox --title "Candidate" --content "Details"` |
+| 세션 핸드오프 저장 | "현재 작업을 Project Librarian 세션 핸드오프로 저장해줘." | `--handoff-save --goal "..." --state "..." --next "..."` |
+| 핸드오프 보기 | "마지막 Project Librarian 세션 핸드오프를 보여줘." | `--handoff-show` |
+| 핸드오프 후보 승격 | "마지막 Project Librarian 핸드오프를 위키 수신함 후보로 승격해줘." | `--handoff-promote-inbox` |
+| 전체 핸드오프 주입 실험 켜기 | "Project Librarian 전체 핸드오프 주입 실험을 켜줘." | `--handoff-injection-enable` |
+| 오래되었거나 미해결인 페이지 보고 | "Project Librarian에서 오래되었거나 미해결인 페이지를 확인해줘." | `--prune-check` |
+| 엄격한 기준으로 stale/unresolved 보고 | "Project Librarian에서 엄격한 기준으로 오래되었거나 미해결인 페이지를 확인해줘." | `--prune-check --prune-check-strict` |
+| git 설정 변경 없이 훅 파일 설치 | "git 설정은 바꾸지 말고 Project Librarian 훅 파일만 설정해줘." | `--no-git-config` |
+
+코드 근거:
+
+| 목표 | 에이전트에게 요청 | 내부 동작 |
+| --- | --- | --- |
+| 기본 근거 캐시 생성 | "`src`에 대해 Project Librarian 코드 근거를 만들어줘." | `--code-index --code-scope src` |
+| 여러 범위 빌드 | "`src`와 `packages/api`에 대해 Project Librarian 코드 근거를 만들어줘." | `--code-index --code-scope src --code-scope packages/api` |
+| 증분 갱신 요구 | "Project Librarian 코드 근거 인덱스를 증분 갱신해줘." | `--code-index --incremental` |
+| 전체 재생성 강제 | "Project Librarian 코드 근거 인덱스를 전체 재생성해줘." | `--code-index --code-index-full` |
+| 스키마 마이그레이션 승인 | "Project Librarian 코드 근거 인덱스 스키마를 마이그레이션해줘." | `--code-index --code-index-migrate` |
+| 선택적 Tree-sitter 백엔드 사용 | "Tree-sitter 파서로 Project Librarian 코드 근거를 만들어줘." | `--code-index --code-parser tree-sitter` |
+| 캐시 호환성 진단 | "Project Librarian 코드 근거 캐시 상태와 호환성을 진단해줘." | `--code-index-health` |
+| 캐시 상태 확인 | "Project Librarian 코드 근거 상태를 보여줘." | `--code-status` |
+| 인덱싱된 파일 목록 | "Project Librarian 코드 근거 인덱스의 파일 목록을 보여줘." | `--code-files` |
+| 구조/소유권 보고서 | "Project Librarian 코드 보고서를 보여줘." | `--code-report` |
+| 특정 보고서 섹션 | "Project Librarian 코드 보고서의 routes 섹션을 보여줘." | `--code-report --code-report-section routes` |
+| 영향 근거 확인 | "`healthHandler`의 Project Librarian 영향 근거를 보여줘." | `--code-impact healthHandler` |
+| 컨텍스트 팩 생성 | "`healthHandler`의 Project Librarian 컨텍스트 팩을 만들어줘." | `--code-context-pack healthHandler` |
+| 심볼 검색 | "`Auth` 심볼을 Project Librarian 코드 근거에서 찾아줘." | `--code-search-symbol Auth` |
+| 보수적 읽기 전용 SQL | "파일 경로를 위한 읽기 전용 Project Librarian 코드 근거 쿼리를 실행해줘." | `--code-query "select path from files order by path"` |
+
+한 번에 하나의 코드 근거 모드만 실행할 수 있습니다. `--incremental`, `--code-index-full`, `--code-index-migrate`, `--code-parser`는 `--code-index`와 함께 사용할 때만 유효합니다. `--code-index-migrate`는 기존 폐기형 인덱스의 스키마 버전이 현재 패키지와 다를 때 교체를 승인한다는 명시적 표시입니다.
+
+## 설치되는 파일
+
+새 설정은 `--agents`를 지정하지 않았고 저장소에 더 좁은 에이전트 집합의 프로젝트 범위 Project Librarian 스킬이 없으면 지원하는 에이전트 표면을 설치합니다. 기존 마이그레이션 없는 업데이트는 감지된 표면만 보존해서 갱신합니다.
+
+프로젝트 지침 파일:
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `GEMINI.md`
+- `wiki/AGENTS.md`
+- `.cursor/rules/project-librarian.mdc`
+
+시작 훅:
+
+- `.codex/hooks.json`
+- `.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 훅 파일:
+
+- `.githooks/prepare-commit-msg`
+- `.githooks/wiki-commit-trailers.js`
+
+위키 디렉터리:
+
+- `wiki/canonical/`
+- `wiki/roadmaps/`
+- `wiki/plans/`
+- `wiki/decisions/`
+- `wiki/inbox/`
+- `wiki/meta/`
+- `wiki/sources/`
+- `wiki/migration/`
+
+시드 위키 페이지와 라우터:
+
+- `wiki/startup.md`
+- `wiki/index.md`
+- `wiki/meta/document-taxonomy.md`
+
+실제 내용이 없는 빈 프로젝트 문서나 ADR 템플릿은 기본 생성하지 않습니다. 나중에 실제 내용이 생기면 문서를 만들고 `--refresh-index`로 라우팅할 수 있습니다.
+
+MCP 서버 등록은 Claude Code(`.mcp.json`), Cursor(`.cursor/mcp.json`), Gemini CLI(`.gemini/settings.json`)의 `mcpServers`에 기존 값을 보존하며 병합합니다. 폐기 가능한 코드 근거 캐시는 `.project-wiki/code-evidence.sqlite`입니다.
+
+## 작동 방식
+
+1. 부트스트랩은 기존 내용을 보존하는 위키 구조와 marker-bounded 에이전트 지침 섹션을 만듭니다.
+2. 세션 시작 훅은 문자 예산이 적용된 `wiki/startup.md`와 `wiki/index.md`만 주입합니다.
+3. 실제 내용이 없는 양식 전용 페이지는 만들지 않습니다.
+4. 자세한 계획 정본은 에이전트가 필요할 때 읽는 canonical, decision, source, meta 페이지에 둡니다.
+5. 새 프로젝트 계획 내용은 작성하거나 취합하기 전에 분류해 상위/하위 문서 관계가 보이도록 유지합니다.
+6. `--refresh-index`는 새로 발견한 위키 페이지를 라우팅합니다. route가 많으면 `wiki/indexes/auto-*.md` 범위별 라우터로 나눕니다.
+7. `--code-index`는 `.project-wiki/` 아래 폐기 가능한 SQLite 근거 캐시를 만듭니다.
+8. `--code-report`, `--code-impact`, `--code-context-pack`, `--code-search-symbol`, `--code-query`는 계획 업데이트에 쓸 코드 기반 근거를 노출합니다.
+9. 읽기 전용 위키 소비자는 경로와 frontmatter에서 사용자-facing page type을 파생하는 concept read model을 공유합니다.
+10. 위키 생산자는 canonical markdown/YAML 스키마를 계속 쓰고, 진단/MCP/시각화 같은 읽기 전용 소비자는 파생 projection을 사용합니다.
+11. `--wiki-visualize`는 데이터베이스나 서버 없이 `.project-wiki/` 아래 정적 그래프 산출물을 작성합니다.
+12. 진단은 깨진 링크, 중복 route, orphan page, stale page, TL;DR 누락, 근거 공백, 마이그레이션 정책 위반을 보고합니다.
+
+마이그레이션은 검토 우선입니다. `--migrate`는 기존 `wiki/`를 `wiki_legacy*`로 보존하고, 양식 전용 파일은 건너뛰며, 여러 성격이 섞인 기존 페이지를 의미 단위로 나눕니다. 이후 각 단위를 분류해 `wiki/migration/` 아래 검토 파일을 작성합니다.

package/docs/maintainer.md

@@ -0,0 +1,76 @@
+# Maintainer Guide
+
+This page collects development and release-operation details that are too deep for the README first screen.
+
+## Development
+
+The source is TypeScript. The committed `dist/` directory is the compiled JavaScript used by the npm binary and installed skill copies.
+
+```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
+```
+
+When editing TypeScript under `src/`, rebuild before committing so `dist/` stays current. `npm run check:dist` verifies that the checked-in generated files still match the latest build output.
+
+`npm run test:coverage` uses Node's native test coverage with conservative line, branch, and function thresholds so coverage is a regression gate, not only a report.
+
+The supported runtime floor is Node.js 22.13+. Development type definitions should stay aligned with the Node 22 support contract or be backed by a Node 22 compatibility check so TypeScript does not admit APIs unavailable to supported users.
+
+## Release Readiness
+
+`npm run release:check` is a local-only maintainer gate. It runs tests, native Node coverage, benchmark parser smoke, the real-corpus offline demo, benchmark release preview, benchmark claim-ledger classification, raw hygiene audit, package dry-run inspection, native helper package-matrix, binary-format, and SHA-256 provenance-manifest inspection, dist executable/parity checks, README benchmark-claim boundary checks, documentation CLI reference coverage, README/README.ko code-evidence freshness/scale-gate documentation checks, and trusted-publishing workflow checks.
+
+It never publishes, never deletes raw benchmark artifacts, and never launches a measured Codex benchmark.
+
+Treat a green `release:check` as a reproducible release-readiness bundle, not a runtime guarantee. It proves those local gates on the current checkout, including that the package dry run stays inside the expected publish boundary, excludes source files, tests, repo-local wiki/workflow state, raw benchmark output, and local caches, and does not contain a partial, mislabeled, unmanifested, stale-manifest, or checksum-mismatched `dist/native/` helper matrix.
+
+## Publishing
+
+Publishing is handled by `.github/workflows/publish.yml` after a GitHub Release is published. Non-OIDC jobs verify the source package, build each supported native helper, assemble `dist/native/`, generate the helper manifest, and run `release:check` against the helper-including package.
+
+The final publish job targets the protected `npm-publish` GitHub Environment, uses npm trusted publishing through GitHub OIDC (`id-token: write`) and `npm publish --access public`, and generates npm provenance automatically. It must not use `NODE_AUTH_TOKEN` or npm token secrets, and release-critical first-party GitHub Actions are pinned to full commit SHAs. `release:check` verifies this workflow contract locally.
+
+Trusted publishing and npm provenance prove the package was published through that GitHub OIDC workflow. They do not prove benchmark correctness, code-evidence freshness in an end-user repository, or a security audit; those remain separate evidence tracks.
+
+## Code-Evidence Runtime Checks
+
+For code-evidence runtime/storage checks, `npm run perf:code-efficiency` generates 3k/10k/50k fixtures and writes `benchmarks/reports/code-performance-efficiency/current.json` plus `.md`. Command timings include CLI startup and freshness checks; the `query_groups` section reports direct DB timings for representative file/symbol/route/import/edge queries.
+
+The report also measures checked-in `mixed-monorepo`, `web-service`, `python-cli`, and `docs-heavy` corpora separately from synthetic scale fixtures. Add repeated `--actual-repo <path>` options with `--compare-native` to include local real repositories in the same TypeScript/Rust timing and row-delta report without modifying the source directories.
+
+For actual-repository native policy checks:
+
+```bash
+npm run perf:code-full-rebuild -- --source-root <dir> --helper <helper>
+npm run perf:code-incremental -- --source-root <dir> --helper <helper>
+```
+
+The first command compares forced TypeScript and Rust full rebuilds on fresh repo copies. The second compares TypeScript incremental updates against the Rust incremental writer after controlled file mutations.
+
+## Benchmark Raw Output
+
+Measured LLM benchmark runs automatically prune stale prior raw run directories and isolated Codex homes older than 1 day, then prune the current run's homes even on claimable-run failure. Raw JSONL, stderr, reports, and manifests remain for runs inside the retention window.
+
+Old ignored raw output can still be audited with the dry-run-first helper before deleting retained isolated Codex homes:
+
+```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` reads the checked-in measured LLM report and ranks cost-weighted regressions without launching Codex. Add `-- --include-traces` to include representative raw JSONL command traces and classify broad-search/router-read drivers. It is the first diagnostic stop for weak cells such as small-scale aggregation before adding new benchmark claims.
+
+Measured LLM runs default to `--scenario-order run-major-balanced`: each measured run index executes all selected scenarios, reversing the order on alternating repetitions so with/without pairs are not grouped by condition across repeated runs. Use `--scenario-order scenario-major` only when reproducing older scenario-grouped diagnostics.
+
+`npm run typecheck:ts7` is an opt-in TypeScript 7 RC compatibility probe. It uses `npx` and is intentionally outside `test`, `release:check`, and CI gates until the compiler API and this project's TypeScript extractor have a measured parity record.

package/docs/usage.md

@@ -0,0 +1,176 @@
+# Usage
+
+Use this guide after the README quick start. It covers install scope, runner paths, generated files, migration behavior, and agent-facing requests.
+
+## Install Scopes
+
+Use `npx` for initial skill installation or for an explicit registry-version project update:
+
+```bash
+npx project-librarian@latest install --scope user --agents all
+```
+
+Install into the current repository instead:
+
+```bash
+npx project-librarian@latest install --scope project --agents all
+```
+
+`install` copies reusable skill files and required local-runner runtime dependencies. 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`. `install-skill` remains supported as a compatibility alias.
+
+| Situation | Command |
+| --- | --- |
+| Install globally for all supported agents | `npx project-librarian@latest install --scope user --agents all` |
+| Install in the current repository | `npx project-librarian@latest install --scope project --agents all` |
+| Install only Codex | `npx project-librarian@latest install --agents codex` |
+| Install only Claude Code | `npx project-librarian@latest install --agents claude` |
+| Install only Cursor | `npx project-librarian@latest install --agents cursor` |
+| Install only Gemini CLI | `npx project-librarian@latest install --agents gemini` |
+| Preview install output | `npx project-librarian@latest install --scope project --agents all --dry-run` |
+
+`--agents` accepts comma-separated values such as `codex,claude,cursor,gemini`. `all` targets every supported agent. `--scope` accepts `user` or `project`.
+
+The project setup/update runner also accepts `--agents`. Fresh setup defaults to all supported agent surfaces only when no project-scoped Project Librarian skill install is present. If the repository already has project-scoped skills such as `.codex/skills/project-librarian/` and `.claude/skills/project-librarian/`, the first setup uses that installed agent set by default. Existing non-migration updates preserve the agent surfaces already present in the repository, so a repo that has only Codex and Claude files will not gain Cursor or Gemini files on a plain update. Use `project-librarian update --agents cursor` or `project-librarian update --agents all` when you intentionally want to add newly supported surfaces; unlisted surfaces are not deleted.
+
+`project-librarian update` also syncs any project-scoped Project Librarian skill installs that already exist for the selected surfaces from the currently running package, including the runtime dependencies needed by the project-local runner. This means `npx project-librarian@latest update` can refresh the repository's managed setup, hooks, wiki meta files, and existing project-scoped skill copies without migration. It does not create new project-scoped skill installs by default and does not update user-scoped skill installs; use `install --scope user` for that.
+
+## Runner Paths
+
+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` |
+| 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]` |
+| Update existing setup without migration | "Update this repository's Project Librarian setup without migrating the wiki." | `update` |
+| Update from the npm latest package without migration | "Run the latest Project Librarian update for this repository without migrating the wiki." | `npx project-librarian@latest update` |
+| Add a specific agent surface to an existing setup | "Add the Cursor Project Librarian surface without migrating the wiki." | `update --agents cursor` |
+| Migrate existing docs/wiki content | "Use Project Librarian to migrate the existing docs/wiki content." | `--migrate` |
+| Validate generated setup | "Run Project Librarian validation." | `--lint` |
+| Check links and document quality | "Run Project Librarian diagnostics." | `--doctor` |
+| Refresh generated routing before diagnostics | "Refresh Project Librarian routing and then run diagnostics." | `--doctor --fix` |
+| Search project wiki content | "Search the Project Librarian wiki for authentication decisions." | `--query "authentication decisions"` |
+| Show backlinks and decision citations for a page | "Show Project Librarian wiki impact for decisions/release-policy." | `--wiki-impact "decisions/release-policy"` |
+| Generate a wiki graph visualizer | "Generate the Project Librarian wiki graph visualizer." | `--wiki-visualize` |
+| Capture a candidate note | "Capture this as a Project Librarian candidate note: <details>." | `--capture-inbox --title "Candidate" --content "Details"` |
+| Save a session handoff | "Save a Project Librarian session handoff for the current work." | `--handoff-save --goal "..." --state "..." --next "..."` |
+| Resume from a handoff | "Show the last Project Librarian session handoff." | `--handoff-show` |
+| Promote handoff candidates | "Promote the last Project Librarian handoff to the wiki inbox." | `--handoff-promote-inbox` |
+| Opt in to full handoff injection | "Enable the Project Librarian full handoff injection experiment." | `--handoff-injection-enable` |
+| Report stale or unresolved wiki pages | "Check Project Librarian for stale or unresolved pages." | `--prune-check` |
+| Report only higher-signal stale or unresolved wiki pages | "Check Project Librarian for strict stale or unresolved pages." | `--prune-check --prune-check-strict` |
+| 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` |
+| Approve a schema migration | "Migrate the Project Librarian code evidence index schema." | `--code-index --code-index-migrate` |
+| Use optional Tree-sitter backend | "Build Project Librarian code evidence with the Tree-sitter parser." | `--code-index --code-parser tree-sitter` |
+| Inspect cache compatibility | "Inspect Project Librarian code evidence cache health." | `--code-index-health` |
+| Show cache status | "Show Project Librarian code evidence status." | `--code-status` |
+| List indexed files | "List files in the Project Librarian code evidence index." | `--code-files` |
+| Print architecture and ownership report | "Show the Project Librarian code report." | `--code-report` |
+| Print one report section | "Show the routes section of the Project Librarian code report." | `--code-report --code-report-section routes` |
+| Inspect impact evidence | "Show Project Librarian impact evidence for `healthHandler`." | `--code-impact healthHandler` |
+| Build a context pack | "Build a Project Librarian context pack for `healthHandler`." | `--code-context-pack healthHandler` |
+| Search indexed symbols | "Search Project Librarian code evidence for symbol `Auth`." | `--code-search-symbol Auth` |
+| Run conservative read-only SQL | "Run a read-only Project Librarian code evidence query for file paths." | `--code-query "select path from files order by path"` |
+
+Only one code evidence mode can run at a time. `--incremental`, `--code-index-full`, `--code-index-migrate`, and `--code-parser` are valid only with `--code-index`. `--code-index-migrate` is explicit approval to replace an existing disposable index when its schema version differs from the current package.
+
+## What Gets Installed
+
+Fresh setup installs the supported agent surfaces below unless you pass `--agents` or the repository already has project-scoped Project Librarian skills for a narrower agent set. Existing non-migration updates preserve the detected surface set by default and update only those selected surfaces plus the common wiki/git-hook files.
+
+Project instruction files:
+
+- `AGENTS.md`
+- `CLAUDE.md`
+- `GEMINI.md`
+- `wiki/AGENTS.md`
+- `.cursor/rules/project-librarian.mdc`
+
+Startup hooks:
+
+- `.codex/hooks.json`
+- `.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:
+
+- `.githooks/prepare-commit-msg`
+- `.githooks/wiki-commit-trailers.js`
+
+Wiki directories:
+
+- `wiki/canonical/`
+- `wiki/roadmaps/`
+- `wiki/plans/`
+- `wiki/decisions/`
+- `wiki/inbox/`
+- `wiki/meta/`
+- `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 is a preservation-first merge into `mcpServers` for Claude Code (`.mcp.json`), Cursor (`.cursor/mcp.json`), and Gemini CLI (`.gemini/settings.json`). The disposable code-evidence cache is `.project-wiki/code-evidence.sqlite`.
+
+## 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. 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 before it is written or consolidated, keeping upstream/downstream document relationships visible.
+6. `--refresh-index` routes newly discovered wiki pages; large route sets are split into `wiki/indexes/auto-*.md` scoped routers.
+7. `--code-index` creates a disposable SQLite evidence cache under `.project-wiki/`.
+8. `--code-report`, `--code-impact`, `--code-context-pack`, `--code-search-symbol`, and `--code-query` expose code-backed evidence for planning updates.
+9. Read-only wiki consumers share a concept read model that derives user-facing page types from paths and frontmatter without rewriting the canonical wiki schema.
+10. Wiki producers keep writing the canonical markdown/YAML schema, while read-only consumers such as diagnostics, MCP, and the visualizer use derived projections instead of mutating source documents.
+11. `--wiki-visualize` writes a static graph artifact to `.project-wiki/`, reusing the wiki graph and concept read model instead of introducing a database or server.
+12. Diagnostics report broken links, duplicate routes, orphan pages, stale pages, missing TL;DRs, evidence gaps, and migration policy violations.
+
+Migration is intentionally review-first. `--migrate` preserves an existing `wiki/` as `wiki_legacy*`, skips form-only/template legacy files, splits mixed legacy pages into meaning units, classifies each unit through the document taxonomy, and writes review files under `wiki/migration/`:
+
+- `inventory.md` records migratable legacy markdown files, file-level classification, and form-only/template files skipped from semantic migration.
+- `unit-map.md` records each heading, paragraph, list item, table row, and code block with its suggested taxonomy area and target page.
+- `split-plan.md` groups those units by suggested new wiki target, so one legacy page that mixes API specs, features, UX, QA, policy, or operations can be rewritten into separate files.
+- `coverage.md` is the editable status ledger for each unit: pending, adopted, merged, superseded, rejected, resolved, or needs-human-review.
+- `verification.md` and `review.md` summarize coverage and semantic completion after `--review-migration`.
+
+`--migration-lint` validates that `coverage.md`, `unit-map.md`, and `split-plan.md` still account for the current migration batch, including duplicate/stale unit IDs, invalid storage/confidence/status values, split count drift, target drift, and old coverage-table schemas. When a legacy page has units that point to multiple targets, `--review-migration` will not let a file-level inbox status complete every unit; unit-level coverage must be resolved instead.
+
+Retained or copied legacy content is acceptable when it fits the new wiki policy and structure; the new wiki must not depend on citing `wiki_legacy*`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-librarian",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "Create and maintain compact project context for humans and LLM coding agents.",
   "license": "MIT",
   "type": "commonjs",
@@ -24,6 +24,8 @@
   "homepage": "https://github.com/kkjk1176/project-librarian#readme",
   "files": [
     "agents/",
+    "CONTRIBUTING.md",
+    "docs/",
     "dist/",
     "LICENSE",
     "README.md",
@@ -59,7 +61,15 @@
     "build": "tsc && chmod +x dist/init-project-wiki.js",
     "check:dist": "node benchmarks/tools/release-readiness.js --only-dist-parity",
     "audit:supply-chain": "npm audit --omit=dev",
+    "native:build": "cargo build --release --locked --manifest-path native/indexer-rs/Cargo.toml",
+    "native:package-audit": "node benchmarks/tools/native-indexer-package-audit.js",
+    "native:package-audit:matrix": "node benchmarks/tools/native-indexer-package-audit.js --require-packaged-helper-matrix --require-packaged-helper-provenance",
+    "native:package-manifest": "node benchmarks/tools/native-indexer-package-audit.js --write-packaged-helper-manifest --require-packaged-helper-matrix --require-packaged-helper-provenance",
+    "native:stage": "npm run build && npm run native:build && node benchmarks/tools/native-indexer-package-audit.js --stage-packaged-helper --require-packaged-helper",
     "perf:code-efficiency": "node benchmarks/tools/code-performance-efficiency.js --full",
+    "perf:code-efficiency:native": "node benchmarks/tools/code-performance-efficiency.js --full --compare-native",
+    "perf:code-full-rebuild": "node benchmarks/tools/code-full-rebuild-performance.js",
+    "perf:code-incremental": "node benchmarks/tools/code-incremental-performance.js",
     "release:check": "node benchmarks/tools/release-readiness.js",
     "typecheck": "tsc --noEmit",
     "typecheck:ts7": "npx --yes -p typescript@rc tsc --noEmit --project tsconfig.json",