project-librarian 0.4.3 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.ko.md +45 -17
  2. package/README.md +45 -17
  3. package/SKILL.md +1 -0
  4. package/dist/args.js +1 -1
  5. package/dist/code-index/modes.js +3 -2
  6. package/dist/init-project-wiki.js +12 -3
  7. package/dist/install-skill.js +30 -7
  8. package/package.json +1 -1
package/README.ko.md CHANGED
@@ -16,7 +16,7 @@
16
16
  재사용 가능한 스킬 파일을 한 번 설치하거나, 셸을 사용할 수 있는 에이전트에게 설치를 요청합니다.
17
17
 
18
18
  ```bash
19
- npx project-librarian install-skill --scope user --agents all
19
+ npx project-librarian@latest install --scope user --agents all
20
20
  ```
21
21
 
22
22
  그다음 대상 저장소에서 Codex, Claude Code, Cursor, Gemini CLI에 자연어로 요청합니다.
@@ -28,10 +28,33 @@ npx project-librarian install-skill --scope user --agents all
28
28
  설치된 스킬은 에이전트가 로컬 실행 경로를 찾고 프로젝트 루트에서 맞는 명령을 실행하도록 안내합니다. 실행 경로를 대상 저장소의 에이전트 설정 안에 두고 싶을 때만 프로젝트 범위 설치를 선택합니다.
29
29
 
30
30
  ```bash
31
- npx project-librarian install-skill --scope project --agents all
31
+ npx project-librarian@latest install --scope project --agents all
32
32
  ```
33
33
 
34
- `install-skill`은 재사용 가능한 실행 파일과 스킬 파일만 복사합니다. `AGENTS.md`, 에이전트 훅, `wiki/`, git 훅 파일, 진단, 선택적 코드 근거 지원을 만들거나 갱신하는 것은 에이전트가 실행하는 생명주기 명령입니다.
34
+ `install`은 재사용 가능한 실행 파일과 스킬 파일만 복사합니다. `AGENTS.md`, 에이전트 훅, `wiki/`, git 훅 파일, 진단, 선택적 코드 근거 지원을 만들거나 갱신하는 것은 에이전트가 실행하는 생명주기 명령입니다. `install-skill`은 호환성 별칭으로 계속 지원됩니다.
35
+
36
+ ## 업데이트
37
+
38
+ 기존 Project Librarian 설정을 위키 마이그레이션 없이 갱신하려면 대상 저장소 루트에서 최신 패키지를 실행합니다.
39
+
40
+ ```bash
41
+ npx project-librarian@latest update
42
+ ```
43
+
44
+ 이 명령은 관리 설정 파일, 에이전트 훅, 위키 운영/메타 파일, 그리고 선택된 에이전트 표면에 이미 있는 프로젝트 범위 Project Librarian 스킬 복사본을 갱신합니다. 현재 `wiki/`는 보존하고 migration flag는 거부하므로 위키를 `wiki_legacy*`로 바꾸지 않습니다.
45
+
46
+ 특정 프로젝트 표면을 의도적으로 추가하거나 갱신할 때는 `--agents`를 명시합니다.
47
+
48
+ ```bash
49
+ npx project-librarian@latest update --agents cursor
50
+ npx project-librarian@latest update --agents all
51
+ ```
52
+
53
+ 사용자 범위 스킬 설치는 전역 에이전트 도구이므로 프로젝트 업데이트가 바꾸지 않습니다. 전역 스킬은 명시적으로 갱신합니다.
54
+
55
+ ```bash
56
+ npx project-librarian@latest install --scope user --agents all
57
+ ```
35
58
 
36
59
  ## 핵심 강점
37
60
 
@@ -119,34 +142,36 @@ SHA로 고정한 오픈소스 저장소 2곳에서, 손으로 작성한 정답
119
142
 
120
143
  ## 설치 상세
121
144
 
122
- 설치 범위나 대상 에이전트를 고를 때 이 섹션을 참고합니다. 초기 스킬 설치에만 `npx`를 사용합니다.
145
+ 설치 범위나 대상 에이전트를 고를 때 이 섹션을 참고합니다. 초기 스킬 설치나 레지스트리 버전을 명시한 프로젝트 갱신에는 `npx`를 사용합니다.
123
146
 
124
147
  ```bash
125
- npx project-librarian install-skill --scope user --agents all
148
+ npx project-librarian@latest install --scope user --agents all
126
149
  ```
127
150
 
128
151
  현재 저장소에 설치:
129
152
 
130
153
  ```bash
131
- npx project-librarian install-skill --scope project --agents all
154
+ npx project-librarian@latest install --scope project --agents all
132
155
  ```
133
156
 
134
- `install-skill`은 재사용 가능한 스킬 파일만 복사합니다. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `wiki/`, `.cursor/rules/`, `.cursor/hooks.json`, `.gemini/settings.json`, `.codex/hooks.json`, `.claude/settings.json`은 만들거나 갱신하지 않습니다.
157
+ `install`은 재사용 가능한 스킬 파일만 복사합니다. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `wiki/`, `.cursor/rules/`, `.cursor/hooks.json`, `.gemini/settings.json`, `.codex/hooks.json`, `.claude/settings.json`은 만들거나 갱신하지 않습니다. `install-skill`은 호환성 별칭으로 계속 지원됩니다.
135
158
 
136
159
  | 상황 | 명령 |
137
160
  | --- | --- |
138
- | 지원하는 모든 에이전트에 전역 설치 | `npx project-librarian install-skill --scope user --agents all` |
139
- | 현재 저장소에 설치 | `npx project-librarian install-skill --scope project --agents all` |
140
- | Codex만 설치 | `npx project-librarian install-skill --agents codex` |
141
- | Claude Code만 설치 | `npx project-librarian install-skill --agents claude` |
142
- | Cursor만 설치 | `npx project-librarian install-skill --agents cursor` |
143
- | Gemini CLI만 설치 | `npx project-librarian install-skill --agents gemini` |
144
- | 설치 결과 미리 보기 | `npx project-librarian install-skill --scope project --agents all --dry-run` |
161
+ | 지원하는 모든 에이전트에 전역 설치 | `npx project-librarian@latest install --scope user --agents all` |
162
+ | 현재 저장소에 설치 | `npx project-librarian@latest install --scope project --agents all` |
163
+ | Codex만 설치 | `npx project-librarian@latest install --agents codex` |
164
+ | Claude Code만 설치 | `npx project-librarian@latest install --agents claude` |
165
+ | Cursor만 설치 | `npx project-librarian@latest install --agents cursor` |
166
+ | Gemini CLI만 설치 | `npx project-librarian@latest install --agents gemini` |
167
+ | 설치 결과 미리 보기 | `npx project-librarian@latest install --scope project --agents all --dry-run` |
145
168
 
146
169
  `--agents`는 `codex,claude,cursor,gemini`처럼 쉼표로 구분한 값도 받습니다. `all`은 지원하는 모든 에이전트를 대상으로 합니다. `--scope`는 `user` 또는 `project`를 받습니다.
147
170
 
148
171
  프로젝트 설정/갱신 실행기도 `--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`처럼 명시합니다. 목록에 없는 표면을 삭제하지는 않습니다.
149
172
 
173
+ `project-librarian update`는 선택된 표면에 이미 프로젝트 범위 Project Librarian 스킬 설치가 있으면, 현재 실행 중인 패키지의 재사용 가능한 스킬 파일을 그 프로젝트 스킬 디렉터리로 동기화합니다. 따라서 `npx project-librarian@latest update`는 마이그레이션 없이 저장소의 관리 설정, 훅, 위키 메타 파일, 기존 프로젝트 범위 스킬 복사본을 함께 갱신할 수 있습니다. 기본적으로 새 프로젝트 범위 스킬 설치를 만들지는 않고, 사용자 범위 스킬 설치도 갱신하지 않습니다. 사용자 범위 스킬은 `install --scope user`로 명시적으로 갱신합니다.
174
+
150
175
  ## 실행 경로
151
176
 
152
177
  이 경로들은 주로 에이전트와 자동화를 위한 참조입니다. 설치 후 에이전트는 `npx`가 아니라 설치된 로컬 복사본을 `node`로 실행해야 합니다. 이렇게 하면 제한된 에이전트 환경에서 네트워크 접근과 버전이 고정되지 않은 패키지 실행을 피할 수 있습니다.
@@ -172,6 +197,7 @@ npx project-librarian install-skill --scope project --agents all
172
197
  | --- | --- | --- |
173
198
  | 위키 생성 또는 갱신 | "Project Librarian으로 이 저장소의 계획 위키를 설정하거나 갱신해줘." | `[init]` |
174
199
  | 마이그레이션 없이 기존 설정 갱신 | "위키를 마이그레이션하지 말고 이 저장소의 Project Librarian 설정을 갱신해줘." | `update` |
200
+ | npm 최신 패키지로 마이그레이션 없이 갱신 | "이 저장소를 최신 Project Librarian으로 위키 마이그레이션 없이 갱신해줘." | `npx project-librarian@latest update` |
175
201
  | 기존 설정에 특정 에이전트 표면 추가 | "위키 마이그레이션 없이 Cursor Project Librarian 표면을 추가해줘." | `update --agents cursor` |
176
202
  | 기존 문서/위키 마이그레이션 | "Project Librarian으로 기존 docs/wiki 내용을 마이그레이션해줘." | `--migrate` |
177
203
  | 생성된 설정 검증 | "Project Librarian 검증을 실행해줘." | `--lint` |
@@ -330,10 +356,12 @@ codex mcp add project-librarian -- node .codex/skills/project-librarian/dist/ini
330
356
 
331
357
  ```bash
332
358
  node .codex/skills/project-librarian/dist/init-project-wiki.js [init|update] [options]
333
- node .codex/skills/project-librarian/dist/init-project-wiki.js install-skill [--scope user|project] [--agents codex|claude|cursor|gemini|all]
359
+ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope user|project] [--agents codex|claude|cursor|gemini|all]
334
360
  ```
335
361
 
336
- `update`는 기존 프로젝트 설정을 명시적으로 갱신하는 명령입니다. `--migrate`와 `--adopt-existing`는 함께 쓸 수 없습니다. 기존 문서나 위키를 `wiki_legacy*`로 보존하고 검토해야 할 때는 최상위 `--migrate`를 사용합니다.
362
+ `install-skill`은 `install`의 호환성 별칭으로 계속 지원됩니다.
363
+
364
+ `update`는 기존 프로젝트 설정을 명시적으로 갱신하는 명령입니다. `--migrate`와 `--adopt-existing`는 함께 쓸 수 없습니다. 기존 문서나 위키를 `wiki_legacy*`로 보존하고 검토해야 할 때는 최상위 `--migrate`를 사용합니다. 선택된 에이전트 표면에 프로젝트 범위 Project Librarian 스킬 설치가 이미 있으면, `update`는 관리 설정을 갱신하기 전에 현재 패키지의 재사용 가능한 스킬 파일을 해당 프로젝트 스킬 디렉터리로 복사합니다.
337
365
 
338
366
  중요 옵션:
339
367
 
@@ -394,7 +422,7 @@ npm pack --dry-run
394
422
 
395
423
  `release:check` 통과는 런타임 보증이 아니라 재현 가능한 릴리스 준비 근거로 봐야 합니다. 현재 checkout에서 위 로컬 게이트를 통과했음을 증명하며, package dry run이 예상 publish 경계(`agents/`, `dist/`, `LICENSE`, `README.md`, `README.ko.md`, `SKILL.md`) 안에 머물고 소스 파일, 테스트, 저장소 로컬 위키/워크플로 상태, raw 벤치마크 출력, 로컬 캐시를 제외하는지도 확인합니다.
396
424
 
397
- 배포는 GitHub Release가 published 상태가 된 뒤 `.github/workflows/publish.yml`에서 처리합니다. 이 워크플로는 GitHub OIDC 기반 npm trusted publishing(`id-token: write`)과 `npm publish --access public`을 사용하므로 npm provenance가 자동 생성됩니다. `NODE_AUTH_TOKEN`이나 npm token secret을 쓰면 안 되며, 릴리스 핵심 GitHub 공식 Actions는 전체 commit SHA로 고정합니다. `release:check`는 이 워크플로 계약도 로컬에서 검사합니다.
425
+ 배포는 GitHub Release가 published 상태가 된 뒤 `.github/workflows/publish.yml`에서 처리합니다. 이 워크플로는 보호된 `npm-publish` GitHub Environment를 대상으로 하고, GitHub OIDC 기반 npm trusted publishing(`id-token: write`)과 `npm publish --access public`을 사용하므로 npm provenance가 자동 생성됩니다. `NODE_AUTH_TOKEN`이나 npm token secret을 쓰면 안 되며, 릴리스 핵심 GitHub 공식 Actions는 전체 commit SHA로 고정합니다. `release:check`는 이 워크플로 계약도 로컬에서 검사합니다.
398
426
 
399
427
  trusted publishing과 npm provenance는 패키지가 이 GitHub OIDC 워크플로를 통해 게시되었음을 증명합니다. 벤치마크 정확성, 최종 사용자 저장소의 코드 근거 freshness, 보안 감사를 증명하지는 않으며, 그런 항목은 별도의 근거 트랙으로 다룹니다.
400
428
 
package/README.md CHANGED
@@ -16,7 +16,7 @@ Most users should ask their coding agent to run Project Librarian rather than ru
16
16
  Install the reusable skill files once, or ask an agent with shell access to do it:
17
17
 
18
18
  ```bash
19
- npx project-librarian install-skill --scope user --agents all
19
+ npx project-librarian@latest install --scope user --agents all
20
20
  ```
21
21
 
22
22
  Then ask Codex, Claude Code, Cursor, or Gemini CLI from the target repository:
@@ -28,10 +28,33 @@ Then ask Codex, Claude Code, Cursor, or Gemini CLI from the target repository:
28
28
  The installed skill tells the agent to resolve the local runner and execute the right command from the project root. Prefer a project-local install only when you want that runner stored inside the target repository's agent setup:
29
29
 
30
30
  ```bash
31
- npx project-librarian install-skill --scope project --agents all
31
+ npx project-librarian@latest install --scope project --agents all
32
32
  ```
33
33
 
34
- `install-skill` only copies the reusable runner and skill files. The agent-run lifecycle command is what creates or updates `AGENTS.md`, agent hooks, `wiki/`, git hook files, diagnostics, and optional code-evidence support.
34
+ `install` copies the reusable runner and skill files. The agent-run lifecycle command is what creates or updates `AGENTS.md`, agent hooks, `wiki/`, git hook files, diagnostics, and optional code-evidence support. `install-skill` remains supported as a compatibility alias.
35
+
36
+ ## Update
37
+
38
+ To refresh an existing Project Librarian setup without migrating the wiki, run the latest package from the repository root:
39
+
40
+ ```bash
41
+ npx project-librarian@latest update
42
+ ```
43
+
44
+ That updates managed setup files, agent hooks, wiki operating/meta files, and existing project-scoped Project Librarian skill copies for the selected agent surfaces. It preserves the current `wiki/` and rejects migration flags, so it will not rename the wiki to `wiki_legacy*`.
45
+
46
+ Use `--agents` when you intentionally want to add or refresh a specific project surface:
47
+
48
+ ```bash
49
+ npx project-librarian@latest update --agents cursor
50
+ npx project-librarian@latest update --agents all
51
+ ```
52
+
53
+ User-scoped skill installs are global agent tooling and are not changed by a project update. Refresh them explicitly:
54
+
55
+ ```bash
56
+ npx project-librarian@latest install --scope user --agents all
57
+ ```
35
58
 
36
59
  ## Highlights
37
60
 
@@ -119,34 +142,36 @@ Question types (task families):
119
142
 
120
143
  ## Install Details
121
144
 
122
- Use this section when you need to choose an install scope or target agent. Use `npx` only for initial skill installation:
145
+ Use this section when you need to choose an install scope or target agent. Use `npx` for initial skill installation or for an explicit registry-version project update:
123
146
 
124
147
  ```bash
125
- npx project-librarian install-skill --scope user --agents all
148
+ npx project-librarian@latest install --scope user --agents all
126
149
  ```
127
150
 
128
151
  Install into the current repository instead:
129
152
 
130
153
  ```bash
131
- npx project-librarian install-skill --scope project --agents all
154
+ npx project-librarian@latest install --scope project --agents all
132
155
  ```
133
156
 
134
- `install-skill` copies reusable skill files only. It does not create or update `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `wiki/`, `.cursor/rules/`, `.cursor/hooks.json`, `.gemini/settings.json`, `.codex/hooks.json`, or `.claude/settings.json`.
157
+ `install` copies reusable skill files only. It does not create or update `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `wiki/`, `.cursor/rules/`, `.cursor/hooks.json`, `.gemini/settings.json`, `.codex/hooks.json`, or `.claude/settings.json`. `install-skill` remains supported as a compatibility alias.
135
158
 
136
159
  | Situation | Command |
137
160
  | --- | --- |
138
- | Install globally for all supported agents | `npx project-librarian install-skill --scope user --agents all` |
139
- | Install in the current repository | `npx project-librarian install-skill --scope project --agents all` |
140
- | Install only Codex | `npx project-librarian install-skill --agents codex` |
141
- | Install only Claude Code | `npx project-librarian install-skill --agents claude` |
142
- | Install only Cursor | `npx project-librarian install-skill --agents cursor` |
143
- | Install only Gemini CLI | `npx project-librarian install-skill --agents gemini` |
144
- | Preview install output | `npx project-librarian install-skill --scope project --agents all --dry-run` |
161
+ | Install globally for all supported agents | `npx project-librarian@latest install --scope user --agents all` |
162
+ | Install in the current repository | `npx project-librarian@latest install --scope project --agents all` |
163
+ | Install only Codex | `npx project-librarian@latest install --agents codex` |
164
+ | Install only Claude Code | `npx project-librarian@latest install --agents claude` |
165
+ | Install only Cursor | `npx project-librarian@latest install --agents cursor` |
166
+ | Install only Gemini CLI | `npx project-librarian@latest install --agents gemini` |
167
+ | Preview install output | `npx project-librarian@latest install --scope project --agents all --dry-run` |
145
168
 
146
169
  `--agents` also accepts comma-separated values such as `codex,claude,cursor,gemini`. `all` targets every supported agent. `--scope` accepts `user` or `project`.
147
170
 
148
171
  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.
149
172
 
173
+ `project-librarian update` also syncs any project-scoped Project Librarian skill installs that already exist for the selected surfaces from the currently running package. 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.
174
+
150
175
  ## Runner Paths
151
176
 
152
177
  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.
@@ -172,6 +197,7 @@ Wiki setup and maintenance:
172
197
  | --- | --- | --- |
173
198
  | Create or update the wiki | "Use Project Librarian to set up or update this repository's planning wiki." | `[init]` |
174
199
  | Update existing setup without migration | "Update this repository's Project Librarian setup without migrating the wiki." | `update` |
200
+ | 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` |
175
201
  | Add a specific agent surface to an existing setup | "Add the Cursor Project Librarian surface without migrating the wiki." | `update --agents cursor` |
176
202
  | Migrate existing docs/wiki content | "Use Project Librarian to migrate the existing docs/wiki content." | `--migrate` |
177
203
  | Validate generated setup | "Run Project Librarian validation." | `--lint` |
@@ -330,10 +356,12 @@ Use the resolved local runner for automation or direct CLI execution:
330
356
 
331
357
  ```bash
332
358
  node .codex/skills/project-librarian/dist/init-project-wiki.js [init|update] [options]
333
- node .codex/skills/project-librarian/dist/init-project-wiki.js install-skill [--scope user|project] [--agents codex|claude|cursor|gemini|all]
359
+ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope user|project] [--agents codex|claude|cursor|gemini|all]
334
360
  ```
335
361
 
336
- `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.
362
+ `install-skill` remains a compatibility alias for `install`.
363
+
364
+ `update` is the explicit existing-project update command. It rejects `--migrate` and `--adopt-existing`; use top-level `--migrate` when legacy docs or wiki content should be preserved into `wiki_legacy*` and reviewed. When project-scoped Project Librarian skill installs already exist for the selected agent surfaces, `update` copies the current package's reusable skill files into those project skill directories before refreshing the managed setup.
337
365
 
338
366
  Important options:
339
367
 
@@ -394,7 +422,7 @@ When editing TypeScript under `src/`, rebuild before committing so `dist/` stays
394
422
 
395
423
  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 (`agents/`, `dist/`, `LICENSE`, `README.md`, `README.ko.md`, and `SKILL.md`) and excludes source files, tests, repo-local wiki/workflow state, raw benchmark output, and local caches.
396
424
 
397
- Publishing is handled by `.github/workflows/publish.yml` after a GitHub Release is published. The workflow uses npm trusted publishing through GitHub OIDC (`id-token: write`) and `npm publish --access public`, which 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.
425
+ Publishing is handled by `.github/workflows/publish.yml` after a GitHub Release is published. The workflow 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.
398
426
 
399
427
  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.
400
428
 
package/SKILL.md CHANGED
@@ -60,6 +60,7 @@ Use the command variants as follows:
60
60
  - Explicit existing-project update without migration: `$PROJECT_LIBRARIAN update` (rejects `--migrate` and `--adopt-existing`).
61
61
  - Existing wiki/docs need migration: `$PROJECT_LIBRARIAN --migrate`.
62
62
  - Install hook files without changing git config: `$PROJECT_LIBRARIAN --no-git-config`.
63
+ - Install reusable Project Librarian skill files: `$PROJECT_LIBRARIAN install --scope user|project --agents codex|claude|cursor|gemini|all`. `install-skill` remains a compatibility alias, but prefer `install` in new guidance.
63
64
 
64
65
  When project terminology becomes important, initialize the optional glossary:
65
66
 
package/dist/args.js CHANGED
@@ -7,7 +7,7 @@ exports.argValue = argValue;
7
7
  exports.argValues = argValues;
8
8
  const agent_surfaces_1 = require("./agent-surfaces");
9
9
  exports.rawArgs = process.argv.slice(2);
10
- const knownCommands = new Set(["init", "update", "install-skill", "mcp"]);
10
+ const knownCommands = new Set(["init", "update", "install", "install-skill", "mcp"]);
11
11
  const flagDefinitions = [
12
12
  { name: "--acknowledge-small-repo", value: "none" },
13
13
  { name: "--adopt-existing", value: "none" },
package/dist/code-index/modes.js CHANGED
@@ -60,11 +60,12 @@ function printJson(value) {
60
60
  function requireCompatibleDatabase(database, runtime) {
61
61
  const schemaVersion = (0, schema_1.readMetaValue)(database, "schema_version");
62
62
  if (schemaVersion !== schema_1.codeIndexSchemaVersion) {
63
+ const health = runtime.codeIndexHealth();
63
64
  const databasePath = runtime.codeEvidenceDatabasePath();
64
65
  runtime.fail([
65
- `code evidence index schema version ${schemaVersion || "(missing)"} is incompatible with ${schema_1.codeIndexSchemaVersion}`,
66
+ health.message,
66
67
  `inspect: project-librarian --code-index-health`,
67
- `rebuild: project-librarian --code-index --code-index-full`,
68
+ `rebuild: ${health.recommended_rebuild_command}`,
68
69
  `database: ${databasePath.relativePath}`,
69
70
  ].join("\n"));
70
71
  }
package/dist/init-project-wiki.js CHANGED
@@ -16,7 +16,7 @@ function codeIndex() {
16
16
  function printUsage() {
17
17
  console.log(`Usage:
18
18
  project-librarian [init|update] [options]
19
- project-librarian install-skill [--scope user|project] [--agents codex|claude|cursor|gemini|all]
19
+ project-librarian install [--scope user|project] [--agents codex|claude|cursor|gemini|all]
20
20
  project-librarian mcp
21
21
 
22
22
  Options:
@@ -59,7 +59,9 @@ Options:
59
59
  --code-search-symbol <term> Search indexed symbols.
60
60
 
61
61
  Commands:
62
- update Run the idempotent wiki/setup update path; rejects migration flags.
62
+ install Install the reusable Project Librarian skill files for selected agents.
63
+ install-skill Compatibility alias for install.
64
+ update Run the idempotent wiki/setup update path, sync existing project-scoped skill installs, and reject migration flags.
63
65
  mcp Run the stdio MCP server exposing answer-shaped code-evidence tools (code_context_pack, code_impact, code_ownership, code_workspace_graph, code_search, code_status) over the existing .project-wiki index.
64
66
 
65
67
  --help Show this help.`);
@@ -154,7 +156,7 @@ if (args_1.codeIndexIncrementalMode && args_1.codeIndexFullMode) {
154
156
  console.error("Use one code index update mode at a time: --incremental or --code-index-full.");
155
157
  process.exit(1);
156
158
  }
157
- if (args_1.command === "install-skill") {
159
+ if (args_1.command === "install" || args_1.command === "install-skill") {
158
160
  (0, install_skill_1.runInstallSkillMode)();
159
161
  process.exit(0);
160
162
  }
@@ -259,6 +261,9 @@ function runInitCommand() {
259
261
  : args_1.migrateMode
260
262
  ? Array.from(agent_surfaces_1.allAgentSurfaces)
261
263
  : (0, agent_surfaces_1.resolveBootstrapAgentSurfaces)(args_1.agentTargets, workspace_1.exists, workspace_1.read);
264
+ const projectSkillSyncSurfaces = args_1.command === "update"
265
+ ? (0, install_skill_1.installedProjectSkillSurfaces)().filter((surface) => (0, agent_surfaces_1.includesAgentSurface)(selectedAgentSurfaces, surface))
266
+ : [];
262
267
  const shouldWriteSurface = (surface) => (0, agent_surfaces_1.includesAgentSurface)(selectedAgentSurfaces, surface);
263
268
  const writeCodexSurface = shouldWriteSurface("codex");
264
269
  const writeClaudeSurface = shouldWriteSurface("claude");
@@ -284,6 +289,10 @@ function runInitCommand() {
284
289
  if (writeGeminiSurface)
285
290
  (0, workspace_1.mkdirp)(".gemini/hooks");
286
291
  (0, workspace_1.mkdirp)(".githooks");
292
+ for (const surface of projectSkillSyncSurfaces) {
293
+ for (const result of (0, install_skill_1.syncProjectSkillInstall)(surface))
294
+ results.push(result);
295
+ }
287
296
  // B1 fallback: sync the CURRENT startup.md TL;DR into the managed AGENTS.md block
288
297
  // so non-interactive `codex exec` (which does not run SessionStart hooks) still
289
298
  // gets compact startup context. Routers are starter files written later in this
package/dist/install-skill.js CHANGED
@@ -33,6 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.projectSkillTarget = projectSkillTarget;
37
+ exports.installedProjectSkillSurfaces = installedProjectSkillSurfaces;
38
+ exports.syncProjectSkillInstall = syncProjectSkillInstall;
36
39
  exports.runInstallSkillMode = runInstallSkillMode;
37
40
  const fs = __importStar(require("node:fs"));
38
41
  const os = __importStar(require("node:os"));
@@ -99,6 +102,12 @@ function projectAgentRoot(agent) {
99
102
  return ".cursor";
100
103
  return ".gemini";
101
104
  }
105
+ function projectSkillRelativeRoot(agent) {
106
+ return path.join(projectAgentRoot(agent), "skills", skillName);
107
+ }
108
+ function projectSkillTarget(agent) {
109
+ return path.join(process.cwd(), projectSkillRelativeRoot(agent));
110
+ }
102
111
  function installTarget(agent, scope) {
103
112
  const base = scope === "user" ? userAgentRoot(agent) : path.join(process.cwd(), projectAgentRoot(agent));
104
113
  return path.join(base, "skills", skillName);
@@ -129,24 +138,38 @@ function copyPath(source, target, dryRun) {
129
138
  fs.chmodSync(target, sourceStat.mode);
130
139
  return existed ? "updated" : "created";
131
140
  }
141
+ function installedProjectSkillSurfaces() {
142
+ return agent_surfaces_1.allAgentSurfaces.filter((agent) => fs.existsSync(path.join(projectSkillTarget(agent), "SKILL.md")));
143
+ }
144
+ function copyPackageFiles(targetRoot, dryRun, labelRoot = targetRoot) {
145
+ const root = packageRoot();
146
+ return packageFiles.map((relativePath) => {
147
+ const source = path.join(root, relativePath);
148
+ const target = path.join(targetRoot, relativePath);
149
+ return [path.join(labelRoot, relativePath), copyPath(source, target, dryRun)];
150
+ });
151
+ }
152
+ function syncProjectSkillInstall(agent) {
153
+ return copyPackageFiles(projectSkillTarget(agent), false, projectSkillRelativeRoot(agent)).map(([label, status]) => {
154
+ if (status === "dry-run")
155
+ throw new Error("project skill sync does not support dry-run status");
156
+ return [label, status];
157
+ });
158
+ }
132
159
  function runInstallSkillMode() {
133
160
  const scope = installScope();
134
161
  const agents = installAgents();
135
162
  const dryRun = args_1.args.has("--dry-run");
136
- const root = packageRoot();
137
163
  const rows = [];
138
164
  for (const agent of agents) {
139
165
  const targetRoot = installTarget(agent, scope);
140
- for (const relativePath of packageFiles) {
141
- const source = path.join(root, relativePath);
142
- const target = path.join(targetRoot, relativePath);
143
- rows.push([`${agent}:${scope}:${path.join(targetRoot, relativePath)}`, copyPath(source, target, dryRun)]);
144
- }
166
+ rows.push(...copyPackageFiles(targetRoot, dryRun).map(([label, status]) => [`${agent}:${scope}:${label}`, status]));
145
167
  }
146
168
  console.log(`Project Librarian skill ${dryRun ? "install dry-run" : "install"} complete.`);
147
169
  console.log(`scope: ${scope}`);
148
170
  console.log(`agents: ${agents.join(", ")}`);
149
- console.log("note: install-skill only installs the reusable skill files; 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.");
171
+ console.log("note: install only installs the reusable skill files; 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.");
172
+ console.log("compatibility: install-skill remains supported as an alias for install.");
150
173
  console.log("next: ask your agent to use Project Librarian from the target project root; the installed skill resolves the local runner.");
151
174
  for (const [label, status] of rows) {
152
175
  console.log(`${status.padEnd(7)} ${label}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "project-librarian",
3
- "version": "0.4.3",
3
+ "version": "0.5.1",
4
4
  "description": "Create and maintain compact project context for humans and LLM coding agents.",
5
5
  "license": "MIT",
6
6
  "type": "commonjs",