project-librarian 0.5.9 → 0.6.1

package/dist/wiki-graph.js

@@ -6,6 +6,7 @@ exports.buildWikiGraph = buildWikiGraph;
 exports.wikiRouterDepths = wikiRouterDepths;
 exports.wikiQueryGraphEvidence = wikiQueryGraphEvidence;
 exports.wikiImpactAnswer = wikiImpactAnswer;
+exports.wikiNeighborhoodAnswer = wikiNeighborhoodAnswer;
 const wiki_files_1 = require("./wiki-files");
 const workspace_1 = require("./workspace");
 // Router reachability budget. The benchmark fixture A1 assert guarantees
@@ -163,3 +164,125 @@ function wikiImpactAnswer(pages, term, graph = buildWikiGraph(pages)) {
     }
     return finalizeWikiAnswer(lines.join("\n"));
 }
+const neighborhoodReadCap = 5;
+function pageClassPriority(file, scope) {
+    if (file.startsWith("wiki/decisions/") || /decision/.test(scope))
+        return 90;
+    if (file.startsWith("wiki/sources/") || /source/.test(scope))
+        return 80;
+    if (file.startsWith("wiki/canonical/") || /canonical/.test(scope))
+        return 70;
+    if (file.startsWith("wiki/plans/") || /plan/.test(scope))
+        return 50;
+    if (file.startsWith("wiki/roadmaps/") || /roadmap/.test(scope))
+        return 40;
+    if (file.startsWith("wiki/meta/") || /wiki-meta/.test(scope))
+        return 30;
+    return 10;
+}
+function neighborhoodReasonRank(reason) {
+    if (reason === "exact page match")
+        return 1000;
+    if (reason === "title/path match")
+        return 900;
+    if (reason === "decision_ref target")
+        return 800;
+    if (reason === "decision_ref citation")
+        return 760;
+    if (reason === "outgoing link target")
+        return 700;
+    if (reason === "incoming link source")
+        return 650;
+    return 0;
+}
+function isGeneratedScopedRouter(file) {
+    return /^wiki\/indexes\/auto-[a-z0-9-]+(?:-\d+)?\.md$/.test(file);
+}
+function isRouterOnlySurface(file) {
+    return file === exports.wikiRouterRoot || file === "wiki/index.md" || isGeneratedScopedRouter(file);
+}
+function addNeighborhoodCandidate(candidates, file, reason, bestFile, graph) {
+    if (!graph.files.has(file) || (file !== bestFile && isRouterOnlySurface(file)))
+        return;
+    const existing = candidates.get(file);
+    if (!existing || neighborhoodReasonRank(reason) > neighborhoodReasonRank(existing.reason)) {
+        candidates.set(file, { file, reason });
+    }
+}
+function wikiNeighborhoodAnswer(pages, term, graph = buildWikiGraph(pages)) {
+    const depths = wikiRouterDepths(graph);
+    const textByFile = new Map(pages.map((page) => [page.file, page.text]));
+    const lowered = term.toLowerCase();
+    const exactTarget = (0, wiki_files_1.normalizeWikiLinkTarget)("wiki/index.md", term.replace(/^\[\[|\]\]$/g, ""));
+    const matches = pages
+        .map((page) => ({ file: page.file, title: (0, wiki_files_1.wikiTitleForFile)(page.file, page.text), text: page.text }))
+        .filter((page) => page.file === exactTarget || page.file.toLowerCase().includes(lowered) || page.title.toLowerCase().includes(lowered))
+        .sort((a, b) => {
+        const exactDelta = Number(b.file === exactTarget) - Number(a.file === exactTarget);
+        if (exactDelta !== 0)
+            return exactDelta;
+        const titleDelta = Number(b.title.toLowerCase().includes(lowered)) - Number(a.title.toLowerCase().includes(lowered));
+        if (titleDelta !== 0)
+            return titleDelta;
+        const aScope = (0, workspace_1.metadataValue)(a.text, "scope");
+        const bScope = (0, workspace_1.metadataValue)(b.text, "scope");
+        return pageClassPriority(b.file, bScope) - pageClassPriority(a.file, aScope) || a.file.localeCompare(b.file);
+    });
+    if (matches.length === 0)
+        return `Wiki neighborhood "${term}": no matching wiki pages.`;
+    const best = matches[0];
+    const candidates = new Map();
+    addNeighborhoodCandidate(candidates, best.file, best.file === exactTarget ? "exact page match" : "title/path match", best.file, graph);
+    const outgoingRef = graph.outgoingDecisionRef.get(best.file);
+    if (outgoingRef)
+        addNeighborhoodCandidate(candidates, outgoingRef, "decision_ref target", best.file, graph);
+    for (const source of graph.incomingDecisionRefs.get(best.file) ?? [])
+        addNeighborhoodCandidate(candidates, source, "decision_ref citation", best.file, graph);
+    for (const link of graph.outgoingLinks.get(best.file) ?? [])
+        addNeighborhoodCandidate(candidates, link.normalizedTarget, "outgoing link target", best.file, graph);
+    for (const link of graph.incomingLinks.get(best.file) ?? [])
+        addNeighborhoodCandidate(candidates, link.file, "incoming link source", best.file, graph);
+    const sorted = Array.from(candidates.values()).sort((a, b) => {
+        const reasonDelta = neighborhoodReasonRank(b.reason) - neighborhoodReasonRank(a.reason);
+        if (reasonDelta !== 0)
+            return reasonDelta;
+        const aText = textByFile.get(a.file) ?? "";
+        const bText = textByFile.get(b.file) ?? "";
+        const classDelta = pageClassPriority(b.file, (0, workspace_1.metadataValue)(bText, "scope")) - pageClassPriority(a.file, (0, workspace_1.metadataValue)(aText, "scope"));
+        if (classDelta !== 0)
+            return classDelta;
+        const aDepth = depths.get(a.file) ?? Number.POSITIVE_INFINITY;
+        const bDepth = depths.get(b.file) ?? Number.POSITIVE_INFINITY;
+        return aDepth - bDepth || a.file.localeCompare(b.file);
+    }).slice(0, neighborhoodReadCap);
+    const lines = [
+        `Wiki neighborhood "${term}": best match ${best.file} — ${best.title}; read ${sorted.length} nearby page${sorted.length === 1 ? "" : "s"}.`,
+        "",
+        "Read order:",
+    ];
+    sorted.forEach((candidate, index) => {
+        const text = textByFile.get(candidate.file) ?? "";
+        const depth = depths.get(candidate.file);
+        const status = (0, workspace_1.metadataValue)(text, "status") || "unknown";
+        const scope = (0, workspace_1.metadataValue)(text, "scope") || "unknown-scope";
+        lines.push(`${index + 1}. ${candidate.file} — ${candidate.reason}; ${depth === undefined ? "router unreachable" : `router depth ${depth}`}; ${status} ${scope}`);
+    });
+    const incoming = uniqueSorted((graph.incomingLinks.get(best.file) ?? [])
+        .map((link) => link.file)
+        .filter((source) => source !== best.file && graph.files.has(source)));
+    const outgoing = uniqueSorted((graph.outgoingLinks.get(best.file) ?? [])
+        .map((link) => link.normalizedTarget)
+        .filter((target) => target !== best.file && graph.files.has(target)));
+    const incomingRefs = uniqueSorted((graph.incomingDecisionRefs.get(best.file) ?? [])
+        .filter((source) => source !== best.file && graph.files.has(source)));
+    const reviewTrigger = (0, workspace_1.metadataValue)(best.text, "review_trigger");
+    lines.push("");
+    lines.push("Why:");
+    lines.push(`- incoming links: ${sampled(incoming, impactListCap)}`);
+    lines.push(`- outgoing links: ${sampled(outgoing, impactListCap)}`);
+    lines.push(`- decision_ref: ${outgoingRef && graph.files.has(outgoingRef) ? outgoingRef : "none"}`);
+    lines.push(`- decision_ref citations: ${sampled(incomingRefs, impactListCap)}`);
+    if (reviewTrigger)
+        lines.push(`- review_trigger: ${reviewTrigger}`);
+    return finalizeWikiAnswer(lines.join("\n"));
+}

package/docs/cli-reference.md

@@ -9,7 +9,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 
 `install-skill` remains a compatibility alias for `install`.
 
-`update` is the explicit existing-project update command. It rejects `--migrate` and `--adopt-existing`; use top-level `--migrate` when legacy docs or wiki content should be preserved into `wiki_legacy*` and reviewed. When project-scoped Project Librarian skill installs already exist for the selected agent surfaces, `update` copies the current package's reusable skill files and required local-runner runtime dependencies into those project skill directories before refreshing the managed setup.
+`update` is the explicit existing-project update command. It rejects `--migrate` and `--adopt-existing`; use top-level `--migrate` when legacy docs or wiki content should be preserved into `wiki_legacy*` and reviewed. When project-scoped Project Librarian skill installs already exist for the selected agent surfaces, `update` copies the current package's reusable skill files and required local-runner runtime dependencies into those project skill directories before refreshing the managed setup. An existing shared `.agents/skills/project-librarian/` install is synchronized independently without selecting agent-specific setup surfaces.
 
 ### Important Options
 
@@ -19,7 +19,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 | `update --agents <list>` | Refresh an existing setup and existing project-scoped skill copies; selected surfaces can be `codex`, `claude`, `cursor`, `gemini`, or `all`. |
 | `--migrate`, `--adopt-existing` | Preserve an existing wiki as `wiki_legacy*`, create migration inboxes, and generate unit-map/split-plan/coverage review files. |
 | `--lint` | Validate generated setup without editing files. |
-| `--link-check` | Report broken wiki links, duplicate routes, orphan pages, and pages the startup router cannot reach within the depth budget. |
+| `--link-check` | Report broken wiki links, duplicate routes, orphan pages, router reachability, and warning-only topology signals. |
 | `--quality-check` | Report stale, conflicting, and low-quality wiki document signals. |
 | `--doctor` | Run lint, link-check, and quality-check together. |
 | `--doctor --fix` | Safely refresh generated index routing before diagnostics. `--fix` is only a modifier for `--doctor`. |
@@ -28,8 +28,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 | `--migration-doctor` | Run migration-lint and migration-quality-check together. |
 | `--query <terms>` | Search wiki paths, metadata, titles, and bodies; answer-first output with per-page TL;DR lines under a hard size cap. |
 | `--wiki-impact <page-or-term>` | Show wiki backlinks, `decision_ref` citations, outgoing links, and router depth for matching pages. |
-| `--wiki-visualize` | Write a self-contained static wiki graph visualizer to `.project-wiki/wiki-graph.html`. |
-| `--wiki-visualize-out <path>` | With `--wiki-visualize`, write to a custom repository-relative path under `.project-wiki/`. |
+| `--wiki-neighborhood <page-or-term>` | Show a bounded read order for nearby wiki pages using links, `decision_ref`, metadata, page class, and router depth. |
 | `--refresh-index` | Update generated auto-discovered wiki routing. |
 | `--capture-inbox --title <title> --content <content> --category <category>` | Append a candidate note to the wiki inbox; category defaults to `project-candidate`. |
 | `--handoff-save --goal <goal> --state <state> --next <action>` | Save generated local session handoff state under `.project-wiki/session/`. Repeat `--next`, `--decision`, `--blocked`, `--open-question`, `--verification`, `--last-success-command`, and `--last-failure-command` as needed. |
@@ -59,3 +58,14 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 | `--code-context-pack <term>` | Print a budgeted first-pass context pack with structural file, symbol, route, import, edge, and ownership evidence. |
 | `--code-search-symbol <term>` | Search indexed symbols. |
 | `--code-query <sql>` | Run conservative read-only SQL over the evidence index. |
+
+### Topology Warnings
+
+`--link-check` keeps topology findings warning-only so they can guide cleanup without blocking bootstrap, update, or release flows.
+
+| Code | Meaning |
+| --- | --- |
+| `hub-overload` | A hand-maintained router or meta page links to too many wiki pages and should be split or scoped. |
+| `weak-authority-route` | An active canonical page with decision or evidence authority signals is reachable only through generated auto-index routing. |
+| `missing-evidence-link` | An active canonical page makes a source-backed claim without a source link or `decision_ref`. |
+| `stale-fanout` | A heavily linked active page has a broad review trigger that is too weak for topology-sensitive edits. |

package/docs/ko/cli-reference.md

@@ -9,7 +9,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 
 `install-skill`은 `install`의 호환성 별칭으로 계속 지원됩니다.
 
-`update`는 기존 프로젝트 갱신을 명시하는 명령입니다. `--migrate`와 `--adopt-existing`를 거부합니다. 기존 문서나 위키 내용을 `wiki_legacy*`로 보존하고 검토해야 한다면 top-level `--migrate`를 사용합니다. 선택된 에이전트 표면에 프로젝트 범위 Project Librarian 스킬 설치가 이미 있으면 `update`는 현재 패키지의 재사용 가능한 스킬 파일과 로컬 실행기에 필요한 필수 런타임 의존성을 해당 프로젝트 스킬 디렉터리에 복사한 뒤 관리 설정을 갱신합니다.
+`update`는 기존 프로젝트 갱신을 명시하는 명령입니다. `--migrate`와 `--adopt-existing`를 거부합니다. 기존 문서나 위키 내용을 `wiki_legacy*`로 보존하고 검토해야 한다면 top-level `--migrate`를 사용합니다. 선택된 에이전트 표면에 프로젝트 범위 Project Librarian 스킬 설치가 이미 있으면 `update`는 현재 패키지의 재사용 가능한 스킬 파일과 로컬 실행기에 필요한 필수 런타임 의존성을 해당 프로젝트 스킬 디렉터리에 복사한 뒤 관리 설정을 갱신합니다. 기존 공유 `.agents/skills/project-librarian/` 설치는 에이전트별 설정 표면을 선택하지 않고 별도로 동기화합니다.
 
 ### 주요 옵션
 
@@ -19,7 +19,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 | `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 예산 안에서 닿지 않는 페이지를 보고합니다. |
+| `--link-check` | 깨진 위키 링크, 중복 route, orphan page, router reachability, warning-only topology 신호를 보고합니다. |
 | `--quality-check` | 오래되었거나 충돌하거나 품질이 낮은 위키 문서 신호를 보고합니다. |
 | `--doctor` | lint, link-check, quality-check를 함께 실행합니다. |
 | `--doctor --fix` | 진단 전에 생성된 index routing을 안전하게 갱신합니다. `--fix`는 `--doctor`의 modifier입니다. |
@@ -28,8 +28,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 | `--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/` 아래 사용자 지정 저장소 상대 경로에 작성합니다. |
+| `--wiki-neighborhood <page-or-term>` | link, `decision_ref`, metadata, page class, router depth를 사용해 가까운 위키 페이지의 제한된 읽기 순서를 보여줍니다. |
 | `--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`를 반복합니다. |
@@ -59,3 +58,14 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 | `--code-context-pack <term>` | 구조 파일, 심볼, route, import, edge, 소유권 근거를 담은 예산 제한 first-pass context pack을 출력합니다. |
 | `--code-search-symbol <term>` | 인덱싱된 심볼을 검색합니다. |
 | `--code-query <sql>` | 근거 인덱스에서 보수적 읽기 전용 SQL을 실행합니다. |
+
+### Topology Warnings
+
+`--link-check`의 topology finding은 warning-only입니다. 그래서 bootstrap, update, release 흐름을 막지 않으면서 정리 방향을 알려줍니다.
+
+| 코드 | 의미 |
+| --- | --- |
+| `hub-overload` | 사람이 관리하는 router 또는 meta 페이지가 너무 많은 위키 페이지를 링크하므로 분리하거나 범위를 좁혀야 합니다. |
+| `weak-authority-route` | decision 또는 evidence 권위 신호가 있는 active canonical page가 generated auto-index routing으로만 도달 가능합니다. |
+| `missing-evidence-link` | active canonical page가 source-backed claim을 하지만 source link 또는 `decision_ref`가 없습니다. |
+| `stale-fanout` | 많이 링크된 active page가 topology-sensitive edit에 비해 너무 넓은 review trigger를 갖고 있습니다. |

package/docs/ko/usage.md

@@ -34,7 +34,7 @@ npx project-librarian@latest install --scope project --agents all
 
 마이그레이션 없는 기존 설정 갱신은 저장소에 이미 있는 에이전트 표면만 보존해서 갱신합니다. 따라서 Codex와 Claude 파일만 있던 저장소는 일반 갱신만으로 Cursor나 Gemini 파일이 새로 생기지 않습니다. 새 표면을 의도적으로 추가하려면 `project-librarian update --agents cursor` 또는 `project-librarian update --agents all`처럼 명시합니다. 목록에 없는 표면을 삭제하지는 않습니다.
 
-`project-librarian update`는 선택된 표면에 이미 프로젝트 범위 Project Librarian 스킬 설치가 있으면 현재 실행 중인 패키지의 재사용 가능한 스킬 파일과 프로젝트 로컬 실행기에 필요한 런타임 의존성을 그 프로젝트 스킬 디렉터리로 동기화합니다. 기본적으로 새 프로젝트 범위 스킬 설치를 만들지는 않고, 사용자 범위 스킬 설치도 갱신하지 않습니다. 사용자 범위 스킬은 `install --scope user`로 명시적으로 갱신합니다.
+`project-librarian update`는 선택된 표면에 이미 프로젝트 범위 Project Librarian 스킬 설치가 있으면 현재 실행 중인 패키지의 재사용 가능한 스킬 파일과 프로젝트 로컬 실행기에 필요한 런타임 의존성을 그 프로젝트 스킬 디렉터리로 동기화합니다. 기존 공유 `.agents/skills/project-librarian/` 설치는 별도로 동기화하며 Codex, Claude, Cursor, Gemini 설정 표면을 암묵적으로 추가하지 않습니다. 기본적으로 새 프로젝트 범위 스킬 설치를 만들지는 않고, 사용자 범위 스킬 설치도 갱신하지 않습니다. 사용자 범위 스킬은 `install --scope user`로 명시적으로 갱신합니다.
 
 ## 실행 경로
 
@@ -42,6 +42,7 @@ npx project-librarian@latest install --scope project --agents all
 
 | 설치 위치 | 실행 경로 |
 | --- | --- |
+| 공유 프로젝트 범위 스킬 | `node .agents/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` |
@@ -69,7 +70,7 @@ npx project-librarian@latest install --scope project --agents all
 | 진단 전 라우팅 갱신 | "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` |
+| 가까운 위키 맥락 찾기 | "canonical/project-brief의 Project Librarian wiki neighborhood를 보여줘." | `--wiki-neighborhood "canonical/project-brief"` |
 | 후보 메모 저장 | "이 내용을 Project Librarian 후보 메모로 저장해줘: <내용>." | `--capture-inbox --title "Candidate" --content "Details"` |
 | 세션 핸드오프 저장 | "현재 작업을 Project Librarian 세션 핸드오프로 저장해줘." | `--handoff-save --goal "..." --state "..." --next "..."` |
 | 핸드오프 보기 | "마지막 Project Librarian 세션 핸드오프를 보여줘." | `--handoff-show` |
@@ -160,9 +161,7 @@ MCP 서버 등록은 Claude Code(`.mcp.json`), Cursor(`.cursor/mcp.json`), Gemin
 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 누락, 근거 공백, 마이그레이션 정책 위반을 보고합니다.
+9. 위키 생산자는 canonical markdown/YAML 스키마를 계속 쓰고, 진단/MCP 같은 읽기 전용 소비자는 원본 문서를 변경하지 않고 검사합니다.
+10. 진단은 깨진 링크, 중복 route, orphan page, topology warning, stale page, TL;DR 누락, 근거 공백, 마이그레이션 정책 위반을 보고합니다.
 
 마이그레이션은 검토 우선입니다. `--migrate`는 기존 `wiki/`를 `wiki_legacy*`로 보존하고, 양식 전용 파일은 건너뛰며, 여러 성격이 섞인 기존 페이지를 의미 단위로 나눕니다. 이후 각 단위를 분류해 `wiki/migration/` 아래 검토 파일을 작성합니다.

package/docs/usage.md

@@ -32,7 +32,7 @@ npx project-librarian@latest install --scope project --agents all
 
 The project setup/update runner also accepts `--agents`. Fresh setup defaults to all supported agent surfaces only when no project-scoped Project Librarian skill install is present. If the repository already has project-scoped skills such as `.codex/skills/project-librarian/` and `.claude/skills/project-librarian/`, the first setup uses that installed agent set by default. Existing non-migration updates preserve the agent surfaces already present in the repository, so a repo that has only Codex and Claude files will not gain Cursor or Gemini files on a plain update. Use `project-librarian update --agents cursor` or `project-librarian update --agents all` when you intentionally want to add newly supported surfaces; unlisted surfaces are not deleted.
 
-`project-librarian update` also syncs any project-scoped Project Librarian skill installs that already exist for the selected surfaces from the currently running package, including the runtime dependencies needed by the project-local runner. This means `npx project-librarian@latest update` can refresh the repository's managed setup, hooks, wiki meta files, and existing project-scoped skill copies without migration. It does not create new project-scoped skill installs by default and does not update user-scoped skill installs; use `install --scope user` for that.
+`project-librarian update` also syncs any project-scoped Project Librarian skill installs that already exist for the selected surfaces from the currently running package, including the runtime dependencies needed by the project-local runner. An existing shared `.agents/skills/project-librarian/` install is synchronized independently and does not imply Codex, Claude, Cursor, or Gemini setup surfaces. 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
 
@@ -40,6 +40,7 @@ These paths are mainly for agents and automation. After installation, agents sho
 
 | Installation | Runner |
 | --- | --- |
+| Shared project-scoped skill | `node .agents/skills/project-librarian/dist/init-project-wiki.js` |
 | Project-scoped Codex skill | `node .codex/skills/project-librarian/dist/init-project-wiki.js` |
 | Project-scoped Claude skill | `node .claude/skills/project-librarian/dist/init-project-wiki.js` |
 | Project-scoped Cursor skill | `node .cursor/skills/project-librarian/dist/init-project-wiki.js` |
@@ -67,7 +68,7 @@ Wiki setup and maintenance:
 | Refresh generated routing before diagnostics | "Refresh Project Librarian routing and then run diagnostics." | `--doctor --fix` |
 | Search project wiki content | "Search the Project Librarian wiki for authentication decisions." | `--query "authentication decisions"` |
 | Show backlinks and decision citations for a page | "Show Project Librarian wiki impact for decisions/release-policy." | `--wiki-impact "decisions/release-policy"` |
-| Generate a wiki graph visualizer | "Generate the Project Librarian wiki graph visualizer." | `--wiki-visualize` |
+| Find nearby wiki context | "Show Project Librarian wiki neighborhood for canonical/project-brief." | `--wiki-neighborhood "canonical/project-brief"` |
 | Capture a candidate note | "Capture this as a Project Librarian candidate note: <details>." | `--capture-inbox --title "Candidate" --content "Details"` |
 | Save a session handoff | "Save a Project Librarian session handoff for the current work." | `--handoff-save --goal "..." --state "..." --next "..."` |
 | Resume from a handoff | "Show the last Project Librarian session handoff." | `--handoff-show` |
@@ -158,10 +159,8 @@ MCP server registration is a preservation-first merge into `mcpServers` for Clau
 6. `--refresh-index` routes newly discovered wiki pages; large route sets are split into `wiki/indexes/auto-*.md` scoped routers.
 7. `--code-index` creates a disposable SQLite evidence cache under `.project-wiki/`.
 8. `--code-report`, `--code-impact`, `--code-context-pack`, `--code-search-symbol`, and `--code-query` expose code-backed evidence for planning updates.
-9. Read-only wiki consumers share a concept read model that derives user-facing page types from paths and frontmatter without rewriting the canonical wiki schema.
-10. Wiki producers keep writing the canonical markdown/YAML schema, while read-only consumers such as diagnostics, MCP, and the visualizer use derived projections instead of mutating source documents.
-11. `--wiki-visualize` writes a static graph artifact to `.project-wiki/`, reusing the wiki graph and concept read model instead of introducing a database or server.
-12. Diagnostics report broken links, duplicate routes, orphan pages, stale pages, missing TL;DRs, evidence gaps, and migration policy violations.
+9. Wiki producers keep writing the canonical markdown/YAML schema, while read-only consumers such as diagnostics and MCP inspect source documents without mutating them.
+10. Diagnostics report broken links, duplicate routes, orphan pages, topology warnings, stale pages, missing TL;DRs, evidence gaps, and migration policy violations.
 
 Migration is intentionally review-first. `--migrate` preserves an existing `wiki/` as `wiki_legacy*`, skips form-only/template legacy files, splits mixed legacy pages into meaning units, classifies each unit through the document taxonomy, and writes review files under `wiki/migration/`:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "project-librarian",
-  "version": "0.5.9",
+  "version": "0.6.1",
   "description": "Create and maintain compact project context for humans and LLM coding agents.",
   "license": "MIT",
   "type": "commonjs",
@@ -97,6 +97,6 @@
     "@sengac/tree-sitter-typescript": "^0.25.15"
   },
   "devDependencies": {
-    "@types/node": "^22.20.0"
+    "@types/node": "^26.1.0"
   }
 }

package/dist/wiki-concepts.js

@@ -1,49 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.conceptIdForFile = conceptIdForFile;
-exports.wikiConceptType = wikiConceptType;
-exports.conceptFromPage = conceptFromPage;
-exports.readWikiConcepts = readWikiConcepts;
-const wiki_files_1 = require("./wiki-files");
-const workspace_1 = require("./workspace");
-function conceptIdForFile(file) {
-    return file.replace(/^wiki\//, "").replace(/\.(md|mdx)$/i, "");
-}
-function wikiConceptType(file, scope) {
-    if (scope === "startup-router" || file === "wiki/startup.md")
-        return "Startup Router";
-    if (scope === "wiki-router" || file === "wiki/index.md" || /^wiki\/indexes\//.test(file))
-        return "Wiki Router";
-    if (scope === "project-canonical" || /^wiki\/canonical\//.test(file))
-        return "Project Canonical Concept";
-    if (scope === "project-decisions" || /^wiki\/decisions\//.test(file))
-        return "Project Decision";
-    if (scope === "source-summary" || /^wiki\/sources\//.test(file))
-        return "Source Summary";
-    if (scope === "wiki-meta" || /^wiki\/meta\//.test(file))
-        return "Wiki Operations Concept";
-    if (/^migration-/.test(scope) || /^wiki\/migration\//.test(file))
-        return "Migration Ledger";
-    if (scope === "inbox" || /^wiki\/inbox\//.test(file))
-        return "Project Candidate";
-    return "Wiki Concept";
-}
-function conceptFromPage(file, text) {
-    const scope = (0, workspace_1.metadataValue)(text, "scope") || "-";
-    const tldr = (0, wiki_files_1.firstTldrBullet)(text);
-    return {
-        budget: (0, workspace_1.metadataValue)(text, "read_budget") || "-",
-        conceptId: conceptIdForFile(file),
-        description: tldr || (0, wiki_files_1.compactSummary)(text),
-        file,
-        reviewTrigger: (0, workspace_1.metadataValue)(text, "review_trigger"),
-        scope,
-        status: (0, workspace_1.metadataValue)(text, "status") || "-",
-        timestamp: (0, workspace_1.metadataValue)(text, "updated"),
-        title: (0, wiki_files_1.wikiTitleForFile)(file, text),
-        type: wikiConceptType(file, scope),
-    };
-}
-function readWikiConcepts(files = (0, wiki_files_1.wikiMarkdownFiles)()) {
-    return files.map((file) => conceptFromPage(file, (0, workspace_1.read)(file)));
-}