project-librarian 0.5.4 → 0.5.6

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,60 @@
+# 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-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,87 @@
+# 코드 근거
+
+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 근거로 인덱싱됩니다.
+
+## 네이티브 헬퍼 정책
+
+실험적 `--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 밖에 둡니다.

package/docs/ko/usage.md

@@ -0,0 +1,167 @@
+# 사용 가이드
+
+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` |
+| 선택적 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-parser`는 `--code-index`와 함께 사용할 때만 유효합니다.
+
+## 설치되는 파일
+
+새 설정은 `--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.