project-librarian 0.4.2 → 0.5.0

package/README.ko.md

@@ -16,7 +16,7 @@
 재사용 가능한 스킬 파일을 한 번 설치하거나, 셸을 사용할 수 있는 에이전트에게 설치를 요청합니다.
 
 ```bash
-npx project-librarian install-skill --scope user --agents all
+npx project-librarian@latest install --scope user --agents all
 ```
 
 그다음 대상 저장소에서 Codex, Claude Code, Cursor, Gemini CLI에 자연어로 요청합니다.
@@ -28,10 +28,33 @@ npx project-librarian install-skill --scope user --agents all
 설치된 스킬은 에이전트가 로컬 실행 경로를 찾고 프로젝트 루트에서 맞는 명령을 실행하도록 안내합니다. 실행 경로를 대상 저장소의 에이전트 설정 안에 두고 싶을 때만 프로젝트 범위 설치를 선택합니다.
 
 ```bash
-npx project-librarian install-skill --scope project --agents all
+npx project-librarian@latest install --scope project --agents all
 ```
 
-`install-skill`은 재사용 가능한 실행 파일과 스킬 파일만 복사합니다. `AGENTS.md`, 에이전트 훅, `wiki/`, git 훅 파일, 진단, 선택적 코드 근거 지원을 만들거나 갱신하는 것은 에이전트가 실행하는 생명주기 명령입니다.
+`install`은 재사용 가능한 실행 파일과 스킬 파일만 복사합니다. `AGENTS.md`, 에이전트 훅, `wiki/`, git 훅 파일, 진단, 선택적 코드 근거 지원을 만들거나 갱신하는 것은 에이전트가 실행하는 생명주기 명령입니다. `install-skill`은 호환성 별칭으로 계속 지원됩니다.
+
+## 업데이트
+
+기존 Project Librarian 설정을 위키 마이그레이션 없이 갱신하려면 대상 저장소 루트에서 최신 패키지를 실행합니다.
+
+```bash
+npx project-librarian@latest update
+```
+
+이 명령은 관리 설정 파일, 에이전트 훅, 위키 운영/메타 파일, 그리고 선택된 에이전트 표면에 이미 있는 프로젝트 범위 Project Librarian 스킬 복사본을 갱신합니다. 현재 `wiki/`는 보존하고 migration flag는 거부하므로 위키를 `wiki_legacy*`로 바꾸지 않습니다.
+
+특정 프로젝트 표면을 의도적으로 추가하거나 갱신할 때는 `--agents`를 명시합니다.
+
+```bash
+npx project-librarian@latest update --agents cursor
+npx project-librarian@latest update --agents all
+```
+
+사용자 범위 스킬 설치는 전역 에이전트 도구이므로 프로젝트 업데이트가 바꾸지 않습니다. 전역 스킬은 명시적으로 갱신합니다.
+
+```bash
+npx project-librarian@latest install --scope user --agents all
+```
 
 ## 핵심 강점
 
@@ -52,7 +75,7 @@ Project Librarian은 에이전트에게 두 가지 로컬 정본을 제공합니
 | 표면 | 에이전트가 얻는 것 |
 | --- | --- |
 | `wiki/startup.md` + `wiki/index.md` | 짧은 세션 시작 요약과 라우터. 관련 계획 페이지만 읽습니다. |
-| `wiki/canonical/` 및 `wiki/decisions/` | 현재 프로젝트 사실, 제약, 리스크, 패키지 계약, CLI 동작, 지속되는 결정. |
+| `wiki/canonical/`, `wiki/roadmaps/`, `wiki/plans/`, `wiki/decisions/` | 현재 정본은 canonical, 큰 미래 작업은 roadmaps, 상세 실행은 plans, 지속되는 근거는 decisions에 둡니다. |
 | `wiki/meta/document-taxonomy.md` | PRD, 정책, UX, 데이터, 개발, QA, 릴리즈, 운영 정본을 어디에 둘지 안내하는 서비스 생애주기 분류 지도. |
 | `.codex/`, `.claude/`, `.cursor/`, `.gemini/` 훅 | 전체 위키를 불러오지 않는 Codex/Claude Code/Cursor/Gemini CLI 시작 컨텍스트. |
 | `GEMINI.md` 및 `.cursor/rules/` | Gemini CLI와 Cursor를 같은 간결한 위키 우선 계약으로 안내하는 지침 파일. |
@@ -119,34 +142,36 @@ SHA로 고정한 오픈소스 저장소 2곳에서, 손으로 작성한 정답
 
 ## 설치 상세
 
-설치 범위나 대상 에이전트를 고를 때 이 섹션을 참고합니다. 초기 스킬 설치에만 `npx`를 사용합니다.
+설치 범위나 대상 에이전트를 고를 때 이 섹션을 참고합니다. 초기 스킬 설치나 레지스트리 버전을 명시한 프로젝트 갱신에는 `npx`를 사용합니다.
 
 ```bash
-npx project-librarian install-skill --scope user --agents all
+npx project-librarian@latest install --scope user --agents all
 ```
 
 현재 저장소에 설치:
 
 ```bash
-npx project-librarian install-skill --scope project --agents all
+npx project-librarian@latest install --scope project --agents all
 ```
 
-`install-skill`은 재사용 가능한 스킬 파일만 복사합니다. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `wiki/`, `.cursor/rules/`, `.cursor/hooks.json`, `.gemini/settings.json`, `.codex/hooks.json`, `.claude/settings.json`은 만들거나 갱신하지 않습니다.
+`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 install-skill --scope user --agents all` |
-| 현재 저장소에 설치 | `npx project-librarian install-skill --scope project --agents all` |
-| Codex만 설치 | `npx project-librarian install-skill --agents codex` |
-| Claude Code만 설치 | `npx project-librarian install-skill --agents claude` |
-| Cursor만 설치 | `npx project-librarian install-skill --agents cursor` |
-| Gemini CLI만 설치 | `npx project-librarian install-skill --agents gemini` |
-| 설치 결과 미리 보기 | `npx project-librarian install-skill --scope project --agents all --dry-run` |
+| 지원하는 모든 에이전트에 전역 설치 | `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 스킬 설치가 있으면, 현재 실행 중인 패키지의 재사용 가능한 스킬 파일을 그 프로젝트 스킬 디렉터리로 동기화합니다. 따라서 `npx project-librarian@latest update`는 마이그레이션 없이 저장소의 관리 설정, 훅, 위키 메타 파일, 기존 프로젝트 범위 스킬 복사본을 함께 갱신할 수 있습니다. 기본적으로 새 프로젝트 범위 스킬 설치를 만들지는 않고, 사용자 범위 스킬 설치도 갱신하지 않습니다. 사용자 범위 스킬은 `install --scope user`로 명시적으로 갱신합니다.
+
 ## 실행 경로
 
 이 경로들은 주로 에이전트와 자동화를 위한 참조입니다. 설치 후 에이전트는 `npx`가 아니라 설치된 로컬 복사본을 `node`로 실행해야 합니다. 이렇게 하면 제한된 에이전트 환경에서 네트워크 접근과 버전이 고정되지 않은 패키지 실행을 피할 수 있습니다.
@@ -172,6 +197,7 @@ npx project-librarian install-skill --scope project --agents all
 | --- | --- | --- |
 | 위키 생성 또는 갱신 | "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` |
@@ -236,6 +262,8 @@ Git 훅 파일:
 위키 디렉터리:
 
 - `wiki/canonical/`
+- `wiki/roadmaps/`
+- `wiki/plans/`
 - `wiki/decisions/`
 - `wiki/inbox/`
 - `wiki/meta/`
@@ -328,10 +356,12 @@ codex mcp add project-librarian -- node .codex/skills/project-librarian/dist/ini
 
 ```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-skill [--scope user|project] [--agents codex|claude|cursor|gemini|all]
+node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope user|project] [--agents codex|claude|cursor|gemini|all]
 ```
 
-`update`는 기존 프로젝트 설정을 명시적으로 갱신하는 명령입니다. `--migrate`와 `--adopt-existing`는 함께 쓸 수 없습니다. 기존 문서나 위키를 `wiki_legacy*`로 보존하고 검토해야 할 때는 최상위 `--migrate`를 사용합니다.
+`install-skill`은 `install`의 호환성 별칭으로 계속 지원됩니다.
+
+`update`는 기존 프로젝트 설정을 명시적으로 갱신하는 명령입니다. `--migrate`와 `--adopt-existing`는 함께 쓸 수 없습니다. 기존 문서나 위키를 `wiki_legacy*`로 보존하고 검토해야 할 때는 최상위 `--migrate`를 사용합니다. 선택된 에이전트 표면에 프로젝트 범위 Project Librarian 스킬 설치가 이미 있으면, `update`는 관리 설정을 갱신하기 전에 현재 패키지의 재사용 가능한 스킬 파일을 해당 프로젝트 스킬 디렉터리로 복사합니다.
 
 중요 옵션:
 

package/README.md

@@ -16,7 +16,7 @@ Most users should ask their coding agent to run Project Librarian rather than ru
 Install the reusable skill files once, or ask an agent with shell access to do it:
 
 ```bash
-npx project-librarian install-skill --scope user --agents all
+npx project-librarian@latest install --scope user --agents all
 ```
 
 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:
 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:
 
 ```bash
-npx project-librarian install-skill --scope project --agents all
+npx project-librarian@latest install --scope project --agents all
 ```
 
-`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.
+`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.
+
+## Update
+
+To refresh an existing Project Librarian setup without migrating the wiki, run the latest package from the repository root:
+
+```bash
+npx project-librarian@latest update
+```
+
+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*`.
+
+Use `--agents` when you intentionally want to add or refresh a specific project surface:
+
+```bash
+npx project-librarian@latest update --agents cursor
+npx project-librarian@latest update --agents all
+```
+
+User-scoped skill installs are global agent tooling and are not changed by a project update. Refresh them explicitly:
+
+```bash
+npx project-librarian@latest install --scope user --agents all
+```
 
 ## Highlights
 
@@ -52,7 +75,7 @@ Project Librarian gives agents two local sources of truth:
 | Surface | What It Gives The Agent |
 | --- | --- |
 | `wiki/startup.md` + `wiki/index.md` | A compact session-start summary and router, so only the relevant planning pages are read. |
-| `wiki/canonical/` and `wiki/decisions/` | Current project facts, constraints, risks, package contracts, CLI behavior, and durable decisions. |
+| `wiki/canonical/`, `wiki/roadmaps/`, `wiki/plans/`, and `wiki/decisions/` | Current truth stays in canonical pages, broad future work stays in roadmaps, detailed execution stays in plans, and durable rationale stays in decisions. |
 | `wiki/meta/document-taxonomy.md` | A service-lifecycle classification map that tells agents where PRD, policy, UX, data, engineering, QA, release, and operations truth should live. |
 | `.codex/`, `.claude/`, `.cursor/`, and `.gemini/` hooks | Automatic startup context for Codex, Claude Code, Cursor, and Gemini CLI without loading the full wiki. |
 | `GEMINI.md` and `.cursor/rules/` | Gemini CLI and Cursor instruction files that route agents to the same compact wiki-first contract. |
@@ -119,34 +142,36 @@ Question types (task families):
 
 ## Install Details
 
-Use this section when you need to choose an install scope or target agent. Use `npx` only for initial skill installation:
+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:
 
 ```bash
-npx project-librarian install-skill --scope user --agents all
+npx project-librarian@latest install --scope user --agents all
 ```
 
 Install into the current repository instead:
 
 ```bash
-npx project-librarian install-skill --scope project --agents all
+npx project-librarian@latest install --scope project --agents all
 ```
 
-`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`.
+`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.
 
 | Situation | Command |
 | --- | --- |
-| Install globally for all supported agents | `npx project-librarian install-skill --scope user --agents all` |
-| Install in the current repository | `npx project-librarian install-skill --scope project --agents all` |
-| Install only Codex | `npx project-librarian install-skill --agents codex` |
-| Install only Claude Code | `npx project-librarian install-skill --agents claude` |
-| Install only Cursor | `npx project-librarian install-skill --agents cursor` |
-| Install only Gemini CLI | `npx project-librarian install-skill --agents gemini` |
-| Preview install output | `npx project-librarian install-skill --scope project --agents all --dry-run` |
+| 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` also 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. 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.
@@ -172,6 +197,7 @@ Wiki setup and maintenance:
 | --- | --- | --- |
 | 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` |
@@ -236,6 +262,8 @@ Git hook files:
 Wiki directories:
 
 - `wiki/canonical/`
+- `wiki/roadmaps/`
+- `wiki/plans/`
 - `wiki/decisions/`
 - `wiki/inbox/`
 - `wiki/meta/`
@@ -328,10 +356,12 @@ Use the resolved local runner for automation or direct CLI execution:
 
 ```bash
 node .codex/skills/project-librarian/dist/init-project-wiki.js [init|update] [options]
-node .codex/skills/project-librarian/dist/init-project-wiki.js install-skill [--scope user|project] [--agents codex|claude|cursor|gemini|all]
+node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope user|project] [--agents codex|claude|cursor|gemini|all]
 ```
 
-`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.
+`install-skill` remains a compatibility alias for `install`.
+
+`update` is the explicit existing-project update command. It rejects `--migrate` and `--adopt-existing`; use top-level `--migrate` when legacy docs or wiki content should be preserved into `wiki_legacy*` and reviewed. When project-scoped Project Librarian skill installs already exist for the selected agent surfaces, `update` copies the current package's reusable skill files into those project skill directories before refreshing the managed setup.
 
 Important options:
 

package/SKILL.md

@@ -60,6 +60,7 @@ Use the command variants as follows:
 - Explicit existing-project update without migration: `$PROJECT_LIBRARIAN update` (rejects `--migrate` and `--adopt-existing`).
 - Existing wiki/docs need migration: `$PROJECT_LIBRARIAN --migrate`.
 - Install hook files without changing git config: `$PROJECT_LIBRARIAN --no-git-config`.
+- 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.
 
 When project terminology becomes important, initialize the optional glossary:
 
@@ -200,6 +201,7 @@ Execution contract:
 3. Separate evidence mapping from canonical truth:
    - Code structure, entrypoints, module relationships, execution flows, read-on-demand routes, and evidence paths belong under `wiki/meta/` with descriptive project-specific filenames chosen by the LLM.
    - Code-backed current project behavior, features, policies, constraints, terminology, domain rules, and operational facts belong under `wiki/canonical/`.
+   - Broad future work belongs under `wiki/roadmaps/`; detailed execution plans belong under `wiki/plans/`. After completion, update canonical truth and remove completed roadmap/plan content after rationale and evidence are preserved.
    - Important design rationale or tradeoffs inferred from code may belong under `wiki/decisions/` when they meet the decision policy.
    - Unclear, conflicting, or low-confidence interpretations belong in `wiki/inbox/` or a focused canonical questions page created for the topic, not directly in canonical truth.
 4. Do not use fixed canonical filenames. Choose or create files from topic boundaries, expected read frequency, and token budget.
@@ -228,6 +230,8 @@ It installs:
 - `wiki/startup.md` compact session-start context.
 - `wiki/index.md` router with read/update/token-budget hints.
 - `wiki/canonical/` directory for project-current-truth documents, created only when real content exists.
+- `wiki/roadmaps/` for broad future scope and priority queues, created only when real content exists.
+- `wiki/plans/` for detailed future execution plans, created only when real content exists.
 - Optional `wiki/canonical/glossary.md` project terminology contract when `--glossary-init` is used.
 - `wiki/decisions/` project-decision directory and lightweight decision ledgers.
 - `wiki/meta/` wiki operating rules, project decision policy, and wiki-operations Decision Pack.
@@ -247,7 +251,7 @@ Project canonical wiki content should not default to Korean or English. Choose t
 
 ## Boundary Rule
 
-`wiki/canonical/` and `wiki/decisions/` are for project planning only. Do not store wiki operating decisions, hook/bootstrap/lint/migration details, LLM collaboration preferences, assistant reminders, or non-project workflow memory there.
+`wiki/canonical/`, `wiki/roadmaps/`, `wiki/plans/`, and `wiki/decisions/` are for project planning only. Do not store wiki operating decisions, hook/bootstrap/lint/migration details, LLM collaboration preferences, assistant reminders, or non-project workflow memory there.
 
 Use:
 
@@ -255,6 +259,8 @@ Use:
 - Root `AGENTS.md`, hooks, or skills for durable project-wide LLM instructions and collaboration memory.
 - `wiki/AGENTS.md` for wiki-internal editing rules that should apply only under `wiki/`.
 - `wiki/canonical/` only for current project truth.
+- `wiki/roadmaps/` only for broad future scope, priority queues, and milestone sequences.
+- `wiki/plans/` only for detailed future execution plans.
 - `wiki/decisions/` only for project decision history.
 
 Every wiki markdown file should include a compact metadata header with `status`, `updated`, `scope`, `read_budget`, `decision_ref`, and `review_trigger`.

package/dist/args.js

@@ -7,7 +7,7 @@ exports.argValue = argValue;
 exports.argValues = argValues;
 const agent_surfaces_1 = require("./agent-surfaces");
 exports.rawArgs = process.argv.slice(2);
-const knownCommands = new Set(["init", "update", "install-skill", "mcp"]);
+const knownCommands = new Set(["init", "update", "install", "install-skill", "mcp"]);
 const flagDefinitions = [
     { name: "--acknowledge-small-repo", value: "none" },
     { name: "--adopt-existing", value: "none" },

package/dist/init-project-wiki.js

@@ -16,7 +16,7 @@ function codeIndex() {
 function printUsage() {
     console.log(`Usage:
   project-librarian [init|update] [options]
-  project-librarian install-skill [--scope user|project] [--agents codex|claude|cursor|gemini|all]
+  project-librarian install [--scope user|project] [--agents codex|claude|cursor|gemini|all]
   project-librarian mcp
 
 Options:
@@ -59,7 +59,9 @@ Options:
   --code-search-symbol <term>      Search indexed symbols.
 
 Commands:
-  update                           Run the idempotent wiki/setup update path; rejects migration flags.
+  install                          Install the reusable Project Librarian skill files for selected agents.
+  install-skill                    Compatibility alias for install.
+  update                           Run the idempotent wiki/setup update path, sync existing project-scoped skill installs, and reject migration flags.
   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.
 
   --help                           Show this help.`);
@@ -154,7 +156,7 @@ if (args_1.codeIndexIncrementalMode && args_1.codeIndexFullMode) {
     console.error("Use one code index update mode at a time: --incremental or --code-index-full.");
     process.exit(1);
 }
-if (args_1.command === "install-skill") {
+if (args_1.command === "install" || args_1.command === "install-skill") {
     (0, install_skill_1.runInstallSkillMode)();
     process.exit(0);
 }
@@ -259,6 +261,9 @@ function runInitCommand() {
         : args_1.migrateMode
             ? Array.from(agent_surfaces_1.allAgentSurfaces)
             : (0, agent_surfaces_1.resolveBootstrapAgentSurfaces)(args_1.agentTargets, workspace_1.exists, workspace_1.read);
+    const projectSkillSyncSurfaces = args_1.command === "update"
+        ? (0, install_skill_1.installedProjectSkillSurfaces)().filter((surface) => (0, agent_surfaces_1.includesAgentSurface)(selectedAgentSurfaces, surface))
+        : [];
     const shouldWriteSurface = (surface) => (0, agent_surfaces_1.includesAgentSurface)(selectedAgentSurfaces, surface);
     const writeCodexSurface = shouldWriteSurface("codex");
     const writeClaudeSurface = shouldWriteSurface("claude");
@@ -284,6 +289,10 @@ function runInitCommand() {
     if (writeGeminiSurface)
         (0, workspace_1.mkdirp)(".gemini/hooks");
     (0, workspace_1.mkdirp)(".githooks");
+    for (const surface of projectSkillSyncSurfaces) {
+        for (const result of (0, install_skill_1.syncProjectSkillInstall)(surface))
+            results.push(result);
+    }
     // B1 fallback: sync the CURRENT startup.md TL;DR into the managed AGENTS.md block
     // so non-interactive `codex exec` (which does not run SessionStart hooks) still
     // gets compact startup context. Routers are starter files written later in this

package/dist/install-skill.js

@@ -33,6 +33,9 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectSkillTarget = projectSkillTarget;
+exports.installedProjectSkillSurfaces = installedProjectSkillSurfaces;
+exports.syncProjectSkillInstall = syncProjectSkillInstall;
 exports.runInstallSkillMode = runInstallSkillMode;
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
@@ -99,6 +102,12 @@ function projectAgentRoot(agent) {
         return ".cursor";
     return ".gemini";
 }
+function projectSkillRelativeRoot(agent) {
+    return path.join(projectAgentRoot(agent), "skills", skillName);
+}
+function projectSkillTarget(agent) {
+    return path.join(process.cwd(), projectSkillRelativeRoot(agent));
+}
 function installTarget(agent, scope) {
     const base = scope === "user" ? userAgentRoot(agent) : path.join(process.cwd(), projectAgentRoot(agent));
     return path.join(base, "skills", skillName);
@@ -129,24 +138,38 @@ function copyPath(source, target, dryRun) {
     fs.chmodSync(target, sourceStat.mode);
     return existed ? "updated" : "created";
 }
+function installedProjectSkillSurfaces() {
+    return agent_surfaces_1.allAgentSurfaces.filter((agent) => fs.existsSync(path.join(projectSkillTarget(agent), "SKILL.md")));
+}
+function copyPackageFiles(targetRoot, dryRun, labelRoot = targetRoot) {
+    const root = packageRoot();
+    return packageFiles.map((relativePath) => {
+        const source = path.join(root, relativePath);
+        const target = path.join(targetRoot, relativePath);
+        return [path.join(labelRoot, relativePath), copyPath(source, target, dryRun)];
+    });
+}
+function syncProjectSkillInstall(agent) {
+    return copyPackageFiles(projectSkillTarget(agent), false, projectSkillRelativeRoot(agent)).map(([label, status]) => {
+        if (status === "dry-run")
+            throw new Error("project skill sync does not support dry-run status");
+        return [label, status];
+    });
+}
 function runInstallSkillMode() {
     const scope = installScope();
     const agents = installAgents();
     const dryRun = args_1.args.has("--dry-run");
-    const root = packageRoot();
     const rows = [];
     for (const agent of agents) {
         const targetRoot = installTarget(agent, scope);
-        for (const relativePath of packageFiles) {
-            const source = path.join(root, relativePath);
-            const target = path.join(targetRoot, relativePath);
-            rows.push([`${agent}:${scope}:${path.join(targetRoot, relativePath)}`, copyPath(source, target, dryRun)]);
-        }
+        rows.push(...copyPackageFiles(targetRoot, dryRun).map(([label, status]) => [`${agent}:${scope}:${label}`, status]));
     }
     console.log(`Project Librarian skill ${dryRun ? "install dry-run" : "install"} complete.`);
     console.log(`scope: ${scope}`);
     console.log(`agents: ${agents.join(", ")}`);
-    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.");
+    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.");
+    console.log("compatibility: install-skill remains supported as an alias for install.");
     console.log("next: ask your agent to use Project Librarian from the target project root; the installed skill resolves the local runner.");
     for (const [label, status] of rows) {
         console.log(`${status.padEnd(7)} ${label}`);

package/dist/templates.js

@@ -70,7 +70,7 @@ At the start of every session:
 
 1. Review \`wiki/startup.md\` for compact current context.
 2. Review \`wiki/index.md\` as the router for which files to read next.
-3. Read detailed \`wiki/canonical/\`, \`wiki/decisions/\`, \`wiki/meta/\`, and \`wiki/sources/\` files on demand only when the current question needs them.
+3. Read detailed \`wiki/canonical/\`, \`wiki/roadmaps/\`, \`wiki/plans/\`, \`wiki/decisions/\`, \`wiki/meta/\`, and \`wiki/sources/\` files on demand only when the current question needs them.
 
 ### ${exports.startupTldrSyncLabel}
 
@@ -133,12 +133,14 @@ Language policy:
 Reading rules:
 
 - Treat \`startup.md\` as compact session context and \`index.md\` as the router.
-- Read detailed \`canonical/\`, \`decisions/\`, \`meta/\`, and \`sources/\` files on demand only when the current question needs them.
+- Read detailed \`canonical/\`, \`roadmaps/\`, \`plans/\`, \`decisions/\`, \`meta/\`, and \`sources/\` files on demand only when the current question needs them.
 - Prefer each file's TL;DR and metadata before reading the full body.
 
 Storage boundaries:
 
 - \`canonical/\` contains current project-planning truth only.
+- \`roadmaps/\` contains broad future scope, priority queues, and milestone sequences only; it is not canonical truth.
+- \`plans/\` contains detailed execution plans for roadmap items only; it is not canonical truth.
 - \`decisions/\` contains project decision history only.
 - \`meta/\` contains wiki operating rules, decision policy, bootstrap, lint, hook, and migration decisions.
 - \`sources/\` contains external reference summaries and source notes.
@@ -150,6 +152,8 @@ Classification rules:
 
 - Before adding or consolidating project content, classify it with \`meta/document-taxonomy.md\`.
 - Write current agreement to the narrowest durable canonical document that fits the taxonomy; do not append unrelated material to \`canonical/project-brief.md\`.
+- Put broad future work in \`roadmaps/\` and detailed execution plans in \`plans/\`, not \`canonical/\`.
+- When roadmap or plan work is completed, update canonical truth first, preserve rationale/evidence where needed, then remove the completed roadmap/plan content.
 - If one input crosses several lifecycle areas, split it into separate canonical updates and link the related pages.
 - If the input explains why a direction changed, update the relevant decision log or Decision Pack in addition to canonical truth.
 - If an external artifact is the better source of truth (for example Figma, OpenAPI, ERD, issue tracker, or code), keep a concise canonical summary and link the external source as the authoritative location.
@@ -187,10 +191,11 @@ exports.startup = `${(0, exports.metadata)("startup-router", "short", "wiki/meta
 ## TL;DR
 
 - This project is in an initial planning state unless the canonical wiki says otherwise.
-- Project truth lives in \`wiki/canonical/\`, project decision history lives in \`wiki/decisions/\`, and source summaries live in \`wiki/sources/\`.
+- Project truth lives in \`wiki/canonical/\`, future work in \`wiki/roadmaps/\` and \`wiki/plans/\`, project decisions in \`wiki/decisions/\`, and sources in \`wiki/sources/\`.
 - Wiki operating rules and wiki operating decisions live in \`wiki/meta/\`.
 - At session start, read only this file and \`wiki/index.md\` first; read detailed files on demand.
 - Project canonical content language is not fixed by this bootstrap. The LLM should choose the language that best matches the user and project context.
+- Completed roadmaps/plans are removed after truth/rationale/evidence capture.
 - Update the wiki in the same turn when project-planning content changes.
 - Classify new project-planning content with \`wiki/meta/document-taxonomy.md\` before writing or consolidating it.
 
@@ -239,7 +244,9 @@ This file is a router, not a file to expand into every answer. Read only the fil
 
 ## Boundary Rule
 
-- \`wiki/canonical/\` and \`wiki/decisions/\` contain project-planning content only.
+- \`wiki/canonical/\`: current accepted project truth only.
+- \`wiki/roadmaps/\`: broad future scope only; \`wiki/plans/\`: detailed execution only.
+- \`wiki/decisions/\`: project decision history only.
 - Wiki operating rules and wiki operating decisions live in \`wiki/meta/\`.
 - Non-project LLM memory, collaboration reminders, and workflow instructions belong in \`AGENTS.md\`, \`wiki/AGENTS.md\`, hooks, or skills, not in project canonical/decision docs.
 
@@ -254,7 +261,7 @@ This file is a router, not a file to expand into every answer. Read only the fil
 
 No empty canonical starter pages are created by default. Create focused pages under \`wiki/canonical/\` only when durable project truth exists, then route them here or with \`--refresh-index\`.
 
-## Project Decisions
+## Decisions
 
 - [[decisions/recent]]
   - Read: recent important project decisions.
@@ -335,6 +342,7 @@ exports.wikiOperatingModel = `${(0, exports.metadata)("wiki-meta", "medium", "wi
 - This wiki keeps project-planning knowledge as durable markdown.
 - Codex, Claude Code, Cursor, and Gemini CLI session-start hooks inject only \`wiki/startup.md\` and \`wiki/index.md\`.
 - Detailed canonical and decision files are read on demand.
+- Roadmaps and plans are separate from canonical truth; canonical pages keep the current accepted state.
 - Root \`AGENTS.md\` keeps the project-wide wiki-first contract; \`wiki/AGENTS.md\` keeps detailed wiki editing rules.
 - Operating documents generated by bootstrap are English by default.
 - Project canonical content language is selected from user/project context, not hardcoded by this bootstrap.
@@ -352,24 +360,28 @@ Karpathy's LLM Wiki pattern favors a continuously maintained markdown wiki over
 ## Layers
 
 1. Sources: external docs, links, user notes, and evidence summaries.
-2. Canonical project truth: current valid planning content under \`wiki/canonical/\`.
-3. Project decisions: rationale, rejected alternatives, and revisit triggers under \`wiki/decisions/\`.
-4. Startup context: compact session summary in \`wiki/startup.md\`.
-5. Router: read/update/token-budget guidance in \`wiki/index.md\`.
-6. Wiki meta: operating rules, decision policy, bootstrap, migration, lint, and language policy under \`wiki/meta/\`.
+2. Canonical project truth: current accepted specs, contracts, policies, and operating state under \`wiki/canonical/\`.
+3. Roadmaps: broad future scope, priority queues, and milestone sequences under \`wiki/roadmaps/\` or an external tracker.
+4. Plans: detailed execution plans for roadmap items under \`wiki/plans/\` or an external tracker.
+5. Project decisions: rationale, rejected alternatives, and revisit triggers under \`wiki/decisions/\`.
+6. Startup context: compact session summary in \`wiki/startup.md\`.
+7. Router: read/update/token-budget guidance in \`wiki/index.md\`.
+8. Wiki meta: operating rules, decision policy, bootstrap, migration, lint, and language policy under \`wiki/meta/\`.
 
 ## Content Classification Procedure
 
 Before writing or reorganizing project-planning content:
 
 1. Identify the content's lifecycle area with [[meta/document-taxonomy]].
-2. Decide whether the content is current truth, decision rationale, source evidence, an unresolved candidate, or a wiki operating rule.
-3. Write current truth to the narrowest relevant \`canonical/\` page, decision rationale to \`decisions/\`, source notes to \`sources/\`, candidates to \`inbox/\`, and wiki operating rules to \`meta/\`.
+2. Decide whether the content is current truth, roadmap, detailed plan, decision rationale, source evidence, an unresolved candidate, or a wiki operating rule.
+3. Write current truth to the narrowest relevant \`canonical/\` page, broad future scope to \`roadmaps/\`, detailed execution plans to \`plans/\`, decision rationale to \`decisions/\`, source notes to \`sources/\`, candidates to \`inbox/\`, and wiki operating rules to \`meta/\`.
 4. Split multi-area inputs instead of making one catch-all document.
 5. Link upstream and downstream pages when the content derives from another artifact or produces another artifact.
 
 Do not treat \`canonical/project-brief.md\` as a default dumping ground. It should summarize direction, audience, scope, and success criteria; detailed product, policy, UX, data, engineering, QA, release, or operations truth should move into focused pages when it grows.
 
+Do not treat \`wiki/canonical/\` as a plan archive. If a whole document is mainly about future scope, implementation sequence, migration wave, branch status, or work result log, keep it outside canonical truth and link it from the relevant current-spec page only when readers need that context. When the work is done, update canonical truth and then remove completed roadmap/plan content after rationale and evidence are preserved in their proper places.
+
 ## Language Policy
 
 - Bootstrap-generated operating documents are English.
@@ -448,14 +460,15 @@ exports.documentTaxonomy = `${(0, exports.metadata)("wiki-meta", "medium", "wiki
 ## TL;DR
 
 - Classify new project-planning content before writing it into the wiki.
-- Use this page to classify content into \`canonical/\`, \`decisions/\`, \`sources/\`, \`inbox/\`, or \`meta/\`.
-- Keep \`canonical/project-brief.md\` compact; move detailed truth into focused canonical pages.
+- Classify into \`canonical/\`, \`roadmaps/\`, \`plans/\`, \`decisions/\`, \`sources/\`, \`inbox/\`, or \`meta/\`.
+- Keep \`canonical/project-brief.md\` compact; move details into focused pages.
+- Keep future work outside canonical; canonical pages may include brief change pointers.
 - Preserve derivation links: evidence -> strategy -> requirements -> design/data/engineering -> QA -> release/operations -> feedback.
 
 ## Top-Level Flow
 
 \`\`\`text
-0. Source-of-truth governance
+0. Governance
   -> 1. Research and evidence
     -> 2. Strategy and business model
       -> 3. Product scope and requirements
@@ -469,27 +482,37 @@ exports.documentTaxonomy = `${(0, exports.metadata)("wiki-meta", "medium", "wiki
             -> 11. Release and operations
               -> 12. Business operations
                 -> 13. Improvement, migration, and end-of-life
-                  -> next product scope, policy, or roadmap change
+                  -> roadmap -> plan -> canonical update
 \`\`\`
 
 ## Storage Decision
 
 | Content Type | Store In | Notes |
 | --- | --- | --- |
-| Current valid project truth | \`wiki/canonical/\` | Split by topic and read frequency. |
+| Current project truth | \`wiki/canonical/\` | Accepted spec, contract, policy, or operating state. |
+| Roadmap, milestone sequence, or priority queue | \`wiki/roadmaps/\` or tracker | Broad future scope, not canonical truth. |
+| Detailed plan, proposal, migration, or task sequence | \`wiki/plans/\` or external tracker | Execution detail, not canonical truth. |
 | Why a choice was made | \`wiki/decisions/\` | Use log, Decision Pack, or ADR by impact. |
 | Source material or summarized evidence | \`wiki/sources/\` | Keep links, checked dates, and applicability. |
 | Unreviewed or ambiguous material | \`wiki/inbox/\` | Do not treat as canonical truth. |
 | Wiki operation, taxonomy, hooks, migration, lint, language rules | \`wiki/meta/\` | Keep outside project canonical truth. |
 | Better external source of truth | External artifact plus a concise wiki route | Examples: Figma, OpenAPI, ERD, Jira, code. |
 
+## Canonical vs Roadmap vs Plan Boundary
+
+\`wiki/canonical/\` is for the state readers should treat as true now. A page mainly about future change, implementation sequence, migration wave, branch status, or work log is not canonical truth.
+
+Use \`wiki/roadmaps/\` for broad ordered future work. Use \`wiki/plans/\` for one roadmap item's details. Put only short planned-change notes in canonical pages.
+
+After acceptance or release, rewrite canonical truth. Move rationale to \`wiki/decisions/\` and evidence to \`wiki/sources/\`, release notes, or reports. Then delete completed roadmap/plan content unless external retention is required.
+
 ## Lifecycle Areas
 
 | Area | Put Here | Usually Derives From | Usually Produces |
 | --- | --- | --- | --- |
 | 0. Governance | source-of-truth map, owners, RACI, approval flow, change rules, glossary, state dictionary, assumptions, risk register | team/process constraints | routing, ownership, conflict resolution |
 | 1. Research | market, competitor, user interviews, VOC, analytics, legal/regulatory, technical feasibility, cost, vendor, accessibility research | raw discovery | strategy, risks, sources |
-| 2. Strategy | service overview, vision, problem, target users, personas, jobs-to-be-done, value offer, positioning, business model, KPI/OKR, success/stop criteria, roadmap, MVP, non-goals | research | PRD, roadmap, scope |
+| 2. Strategy | service overview, vision, problem, target users, personas, jobs-to-be-done, value offer, positioning, business model, KPI/OKR, success/stop criteria, committed roadmap summary, MVP, non-goals | research | PRD, roadmap, scope |
 | 3. Product | PRD, user stories, use cases, priorities, backlog rules, acceptance criteria, feature spec, exceptions, state definitions, notification rules, search/filter/sort rules, admin requirements | strategy and policy | UX, API, data, QA |
 | 4. Policy | operations policy, auth/account, permissions, pricing, payment/refund, coupon/credit, content moderation, notifications, retention/deletion, abuse response, support, EOL | business model, law, risks | feature constraints, API rules, CS/ops |
 | 5. UX and Content | IA, sitemap, user flow, task flow, screen list, wireframes, screen specs, content model, UX writing, empty/error states, help/FAQ, localization, SEO, accessibility criteria | product and policy | design, frontend, QA |
@@ -498,7 +521,7 @@ exports.documentTaxonomy = `${(0, exports.metadata)("wiki-meta", "medium", "wiki
 | 8. Engineering | architecture, technology decisions, API/OpenAPI, integrations, webhooks/idempotency, state machines, jobs/cron, error codes, env vars, secrets, local dev, conventions, branch/release strategy, CI/CD, feature flags, dependencies, migrations, performance, scalability, FinOps | product, UX, data, policy | implementation and verification |
 | 9. Security/Legal | security requirements, threat model, privacy rules, privacy impact, terms, privacy policy, audit logs, permission history, internal access controls, key rotation, vulnerability response, licenses, vendor and DPA documents | data, architecture, law | controls, tests, release gates |
 | 10. QA | test strategy, QA scenarios, test cases, regression checklist, UAT, browser/device matrix, accessibility tests, performance tests, security tests, data quality tests, design QA, quality gates | requirements, design, engineering | release approval |
-| 11. Release/Ops | release plan, deployment procedure, rollback, release notes, operator manual, runbooks, monitoring, observability, SLO/SLA, on-call/escalation, incident response, backup/restore, DR/BCP, recurring checks | QA and infrastructure | stable operation |
+| 11. Release/Ops | current release policy, deployment procedure, rollback, release notes, operator manual, runbooks, monitoring, observability, SLO/SLA, on-call/escalation, incident response, backup/restore, DR/BCP, recurring checks | QA and infrastructure | stable operation |
 | 12. Business Ops | CS macros, support policy, training, sales/adoption guide, CRM rules, onboarding playbook, churn/offboarding, admin operations, communication templates, revenue recognition, tax/invoice, partner operations | policy, release, sales motion | customer-facing operation |
 | 13. Improvement/EOL | VOC summary, retrospectives, experiments, experiment results, cohort/retention analysis, feature deprecation, migration/data transfer, service end-of-life | operations and analytics | next PRD, policy, roadmap |
 
@@ -507,11 +530,14 @@ exports.documentTaxonomy = `${(0, exports.metadata)("wiki-meta", "medium", "wiki
 When a new note arrives:
 
 1. Identify the lifecycle area and storage location.
-2. Update an existing focused page when the topic already has a canonical home.
-3. Create a new focused page only when the topic is durable, likely to be read independently, or too large for its current page.
-4. Add an \`index.md\` route when the page becomes durable.
-5. Add upstream/downstream links in prose or tables when one artifact derives from another.
-6. Record decision rationale separately when the change explains why the project chose one option over another.
+2. Decide whether content is current truth, roadmap, plan, decision rationale, evidence, candidate, or wiki operating rule.
+3. Update an existing focused canonical page only when the content changes current truth.
+4. Create a new focused page only when the topic is durable, likely to be read independently, or too large for its current page.
+5. If the document is future-oriented, store broad scope in \`roadmaps/\` and detailed execution in \`plans/\`.
+6. Add an \`index.md\` route when the page becomes durable.
+7. Add upstream/downstream links in prose or tables when one artifact derives from another.
+8. Record decision rationale separately when the change explains why the project chose one option over another.
+9. When roadmap/plan work is done, update canonical truth, preserve rationale/evidence, then remove completed roadmap/plan content.
 
 ## Page Shape
 
@@ -670,7 +696,7 @@ No project decisions yet.
 ## TL;DR
 
 - This Decision Pack records accepted wiki operating choices for project-librarian.
-- It covers wiki structure, document taxonomy, startup hook scope, metadata, language policy, git hook behavior, migration review, and inbox handling.
+- It covers wiki structure, document taxonomy, startup hook scope, metadata, language policy, git hook behavior, migration review, inbox handling, and canonical/roadmap/plan boundaries.
 - Project product decisions belong in \`wiki/decisions/\`, while these operating decisions stay in \`wiki/meta/\`.
 
 Status: accepted
@@ -685,6 +711,8 @@ Canonical: [[meta/operating-model]], [[meta/decision-policy]], [[meta/document-t
 | ${workspace_1.today} | Inject only \`startup.md\` and \`index.md\` through Codex, Claude Code, Cursor, and Gemini CLI startup hooks; route detailed files Read On Demand. | Full canonical and decision bodies waste startup tokens. | Always read detailed canonical and decision files first. | Important context is repeatedly missed at startup. | [[startup]], [[index]] |
 | ${workspace_1.today} | Use metadata headers on wiki knowledge pages. | Agents and humans can quickly judge status, scope, budget, and review triggers. | Body-only conventions. | Header maintenance costs more than it saves. | [[meta/operating-model]] |
 | ${workspace_1.today} | Keep wiki operating docs in \`wiki/meta/\`. | Project truth stays focused on product/project content. | Store operating docs in \`canonical/\` or \`decisions/\`. | Meta docs become hard to discover. | [[meta/operating-model]] |
+| ${workspace_1.today} | Split future work into \`roadmaps/\` and \`plans/\`, outside canonical truth. | Roadmaps list broad future scope and sequencing; plans describe detailed execution for one roadmap item; canonical pages should show only the current accepted spec, contract, policy, or operating state. | Store roadmap, improvement, migration, and implementation plans directly in \`canonical/\` as if they were current truth, or mix roadmaps and detailed plans in one directory. | Teams need a different planning directory convention, or plan artifacts become the authoritative source for current behavior. | [[meta/document-taxonomy]], [[meta/operating-model]] |
+| ${workspace_1.today} | Remove completed roadmap and plan content after canonical truth, rationale, and evidence are updated. | Completed future-work documents become stale logs once their outcome is reflected in canonical pages, decisions, and evidence artifacts. | Keep completed roadmap/plan documents indefinitely inside the wiki. | Audit, legal, or release process requires retaining completed plan artifacts in a dedicated external system. | [[meta/document-taxonomy]], [[meta/operating-model]] |
 | ${workspace_1.today} | Bootstrap-generated operating documents are English by default. | Repository entry points and operating contracts are easier for public users to inspect. | Generate operating docs in a fixed non-English language. | The project intentionally targets a single-language local audience. | [[meta/operating-model]] |
 | ${workspace_1.today} | Project canonical content language is chosen from user/project context. | User language and source material should drive project truth, not the bootstrap tool. | Hardcode Korean or English as the canonical content language. | A team requires a fixed language policy. | [[startup]], [[index]] |
 | ${workspace_1.today} | Install git hook files but preserve existing \`core.hooksPath\` values and allow \`--no-git-config\`. | Public users may already have a hook chain such as Husky. | Always replace \`core.hooksPath\`. | Users prefer automatic setup and accept the side effect. | [[meta/operating-model]] |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-librarian",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Create and maintain compact project context for humans and LLM coding agents.",
   "license": "MIT",
   "type": "commonjs",