project-librarian 0.5.8 → 0.6.0

package/README.ko.md

@@ -77,9 +77,9 @@ Project Librarian은 작은 첫 읽기와 더 깊은 정본으로 가는 경로
 - **첫 읽기를 작게.** 시작 훅은 `wiki/startup.md`와 `wiki/index.md`만 주입하고, 에이전트는 필요할 때 더 깊은 페이지로 이동합니다.
 - **한 번 설정, 네 에이전트.** Codex, Claude Code, Cursor, Gemini CLI가 같은 저장소 로컬 기억 계약을 공유합니다.
 - **구조적인 위키 작성.** 새 프로젝트 내용은 작성하거나 취합하기 전에 분류하므로 PRD, 정책, UX, 데이터, API, QA, 릴리즈, 운영 메모가 하나의 잡다한 페이지로 합쳐지지 않습니다.
-- **검토 가능한 위키 그래프.** `--wiki-visualize`는 시작 컨텍스트를 늘리지 않고 `.project-wiki/` 아래에 정적 HTML 그래프를 작성합니다.
 - **측정된 주장.** 벤치마크에서 이긴 경우와 손해를 본 경우를 주장 경계와 함께 공개합니다.
 - **로컬 세션 핸드오프.** `--handoff-save`는 `.project-wiki/session/` 아래에 생성형 재개 메모를 저장하되 실행 기억을 프로젝트 정본으로 바꾸지 않습니다.
+- **답변형 위키 토폴로지.** `--wiki-impact`, `--wiki-neighborhood`, topology diagnostics가 graph visualizer 없이 backlinks, decision 근거, router depth, 가까운 읽기 순서를 노출합니다.
 - **선택적 코드 근거.** SQLite 인덱스와 답변 형태 MCP 도구가 큰 저장소의 비싼 탐색 질문에 답하며, MCP SDK 의존성은 추가하지 않습니다.
 - **다시 실행해도 안전.** 부트스트랩은 멱등하고 기존 내용 보존을 우선합니다.
 
@@ -94,6 +94,7 @@ Project Librarian은 작은 첫 읽기와 더 깊은 정본으로 가는 경로
 | 기존 문서/위키 마이그레이션 | "Project Librarian으로 기존 docs/wiki 내용을 마이그레이션해줘." |
 | 진단 실행 | "Project Librarian 진단을 실행해줘." |
 | 프로젝트 기억 검색 | "Project Librarian 위키에서 authentication decisions를 찾아줘." |
+| 가까운 위키 맥락 찾기 | "canonical/project-brief의 Project Librarian wiki neighborhood를 보여줘." |
 | 코드 근거 구축 | "Project Librarian 코드 근거를 `src`에 대해 구축해줘." |
 | 코드 영향 확인 | "`healthHandler`에 대한 Project Librarian 영향 근거를 보여줘." |
 | 세션 핸드오프 저장 | "현재 작업에 대한 Project Librarian 세션 핸드오프를 저장해줘." |
@@ -115,7 +116,7 @@ Project Librarian은 작은 첫 읽기와 더 깊은 정본으로 가는 경로
 | 중형 | 45.95% 적음 | 37.42% 적음 | 11.88% 적음 | 4.30% 적음 | 69.12% 적음 |
 | 대형 | 66.97% 적음 | 69.87% 적음 | 31.90% 적음 | 35.19% 적음 | 95.58% 적음 |
 
-위키 트랙 작업 유형별 비용 가중 토큰 변화:
+위키 트랙 작업 유형별 비용 가중 토큰 변화, 전체 규모 합산:
 
 | 작업 유형 | 변화 |
 | --- | ---: |
@@ -127,6 +128,8 @@ Project Librarian은 작은 첫 읽기와 더 깊은 정본으로 가는 경로
 | multi_session | 52.58% 적음 |
 | aggregation | 42.53% 적음 |
 
+규모별 값은 서로 다릅니다. 소형/중형/대형 작업 유형별 실제 행렬과 아직 역전이 남은 셀은 [벤치마크 근거](docs/ko/benchmarks.md#위키-트랙)에 있습니다.
+
 실행 시간과 명령 수의 한계도 있습니다. 이번 보고서에서 `code_impact`, `change_location`, `aggregation`은 토큰과 출력 바이트가 모두 개선됐지만, 실행 시간이나 명령 수에서는 일부 역전이 남아 있습니다.
 
 코드 그래프 트랙, 대조군 대비 비용 가중 토큰:

package/README.md

@@ -77,9 +77,9 @@ The core idea is not "write more docs." It is "keep the first agent read small,
 - **Small first read.** Startup hooks inject only `wiki/startup.md` and `wiki/index.md`; agents route to deeper pages on demand.
 - **One setup, four agents.** Codex, Claude Code, Cursor, and Gemini CLI share the same repo-local memory contract.
 - **Structured wiki writing.** New project content is classified before it is written or consolidated, so PRDs, policies, UX, data, APIs, QA, release, and operations notes do not collapse into one catch-all page.
-- **Inspectable wiki graph.** `--wiki-visualize` writes a static HTML graph under `.project-wiki/` without adding to startup context.
 - **Measured claims.** Benchmark wins and losses are published together, with claim boundaries attached.
 - **Local session handoff.** `--handoff-save` stores generated resume notes under `.project-wiki/session/` without turning execution memory into canonical project truth.
+- **Answer-shaped wiki topology.** `--wiki-impact`, `--wiki-neighborhood`, and topology diagnostics expose backlinks, decision evidence, router depth, and nearby read order without a graph visualizer.
 - **Optional code evidence.** A SQLite index plus answer-shaped MCP tools answer expensive traversal questions on large repositories without adding an MCP SDK dependency.
 - **Safe to re-run.** Bootstrap is idempotent and preservation-first.
 
@@ -94,6 +94,7 @@ Ask your agent for the outcome you want; the installed skill maps the request to
 | Migrate existing docs/wiki content | "Use Project Librarian to migrate the existing docs/wiki content." |
 | Run diagnostics | "Run Project Librarian diagnostics." |
 | Search project memory | "Search the Project Librarian wiki for authentication decisions." |
+| Find nearby wiki context | "Show Project Librarian wiki neighborhood for canonical/project-brief." |
 | Build code evidence | "Build Project Librarian code evidence for `src`." |
 | Inspect code impact | "Show Project Librarian impact evidence for `healthHandler`." |
 | Save a handoff | "Save a Project Librarian session handoff for the current work." |
@@ -115,7 +116,7 @@ Wiki track aggregate deltas vs control:
 | Medium | 45.95% less | 37.42% less | 11.88% less | 4.30% less | 69.12% less |
 | Large | 66.97% less | 69.87% less | 31.90% less | 35.19% less | 95.58% less |
 
-Wiki track task-family cost-weighted token deltas vs control:
+Wiki track task-family cost-weighted token deltas vs control, all scales combined:
 
 | Task family | Delta |
 | --- | ---: |
@@ -127,6 +128,8 @@ Wiki track task-family cost-weighted token deltas vs control:
 | multi_session | 52.58% less |
 | aggregation | 42.53% less |
 
+Scale-specific values vary; see [Benchmark Evidence](docs/benchmarks.md#wiki-track) for the small/medium/large task-family matrix and the cells that still regress.
+
 Timing and command-count caveat: `code_impact`, `change_location`, and `aggregation` still had wall-time or command-count regressions in this report, even though token and output-byte metrics improved for every task family.
 
 Code-graph track, cost-weighted tokens vs control:

package/dist/args.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.codeIndexMode = exports.acknowledgeSmallRepoMode = exports.noGitConfigMode = exports.reviewMigrationMode = exports.pruneCheckStrictMode = exports.pruneCheckMode = exports.captureInboxMode = exports.refreshIndexMode = exports.issueDraftMode = exports.issueCreateMode = exports.handoffVerification = exports.handoffStatusMode = exports.handoffState = exports.handoffShowMode = exports.handoffSaveMode = exports.handoffPromoteInboxMode = exports.handoffInjectionStatusMode = exports.handoffInjectionEnableMode = exports.handoffInjectionDisableMode = exports.handoffOpenQuestions = exports.handoffNextActions = exports.handoffLastSuccessCommand = exports.handoffLastFailureCommand = exports.handoffInputMode = exports.handoffGoal = exports.handoffDecisions = exports.handoffClearMode = exports.handoffBlocked = exports.glossaryMode = exports.fixMode = exports.doctorMode = exports.qualityCheckMode = exports.linkCheckMode = exports.migrationQualityCheckMode = exports.migrationLintMode = exports.migrationDoctorMode = exports.lintMode = exports.migrateMode = exports.invalidAgentTargets = exports.missingValueOptions = exports.unexpectedValueOptions = exports.unknownOptions = exports.args = exports.commandArgs = exports.command = exports.unknownCommand = exports.helpMode = exports.agentTargets = exports.parsedArgs = exports.rawArgs = void 0;
-exports.issueDraftTitle = exports.issueBodyFile = exports.captureCategory = exports.captureContent = exports.captureTitle = exports.codeIndexScopes = exports.codeParser = exports.codeIndexOutput = exports.codeSearchSymbol = exports.codeReportSection = exports.codeQuerySql = exports.codeImpactTarget = exports.codeContextPackTarget = exports.wikiVisualizeOutput = exports.wikiVisualizeMode = exports.wikiImpactTarget = exports.wikiImpactMode = exports.queryTerm = exports.codeSearchSymbolMode = exports.codeQueryMode = exports.codeImpactMode = exports.codeParserMode = exports.codeContextPackMode = exports.codeFilesMode = exports.codeStatusMode = exports.codeReportMode = exports.codeIndexHealthMode = exports.codeIndexFullMode = exports.codeIndexMigrateMode = exports.codeIndexIncrementalMode = exports.codeIndexEngineMode = exports.codeIndexEngine = void 0;
+exports.issueDraftTitle = exports.issueBodyFile = exports.captureCategory = exports.captureContent = exports.captureTitle = exports.codeIndexScopes = exports.codeParser = exports.codeIndexOutput = exports.codeSearchSymbol = exports.codeReportSection = exports.codeQuerySql = exports.codeImpactTarget = exports.codeContextPackTarget = exports.wikiNeighborhoodTarget = exports.wikiNeighborhoodMode = exports.wikiImpactTarget = exports.wikiImpactMode = exports.queryTerm = exports.codeSearchSymbolMode = exports.codeQueryMode = exports.codeImpactMode = exports.codeParserMode = exports.codeContextPackMode = exports.codeFilesMode = exports.codeStatusMode = exports.codeReportMode = exports.codeIndexHealthMode = exports.codeIndexFullMode = exports.codeIndexMigrateMode = exports.codeIndexIncrementalMode = exports.codeIndexEngineMode = exports.codeIndexEngine = void 0;
 exports.parseArgs = parseArgs;
 exports.argValue = argValue;
 exports.argValues = argValues;
@@ -72,10 +72,8 @@ const flagDefinitions = [
     { name: "--review-migration", value: "none", aliases: ["--semantic-migrate"] },
     { name: "--scope", value: "value" },
     { name: "--title", value: "value" },
-    { name: "--wiki-graph-html", value: "none" },
     { name: "--wiki-impact", value: "value" },
-    { name: "--wiki-visualize", value: "none" },
-    { name: "--wiki-visualize-out", value: "value" },
+    { name: "--wiki-neighborhood", value: "value" },
 ];
 function definitionNames(definition) {
     return [definition.name, ...(definition.aliases ?? [])];
@@ -156,6 +154,7 @@ function parseArgs(argv) {
     const codeContextPackTarget = argValueFromAny("--code-context-pack");
     const codeQuerySql = argValueFromAny("--code-query");
     const codeSearchSymbol = argValueFromAny("--code-search-symbol");
+    const wikiNeighborhoodTarget = argValue("--wiki-neighborhood");
     const parsedAgentTargets = (0, agent_surfaces_1.parseAgentSurfaceValues)(argValues("--agents"));
     const handoffInputMode = [
         "--blocked",
@@ -254,8 +253,8 @@ function parseArgs(argv) {
             .filter((arg) => !knownFlags.has(arg)))),
         wikiImpactMode: hasFlag("--wiki-impact"),
         wikiImpactTarget: argValue("--wiki-impact"),
-        wikiVisualizeMode: hasFlag("--wiki-visualize") || hasFlag("--wiki-graph-html"),
-        wikiVisualizeOutput: argValue("--wiki-visualize-out"),
+        wikiNeighborhoodMode: hasFlag("--wiki-neighborhood"),
+        wikiNeighborhoodTarget,
     };
 }
 exports.parsedArgs = parseArgs(exports.rawArgs);
@@ -330,8 +329,8 @@ function argValues(name) {
 exports.queryTerm = exports.parsedArgs.queryTerm;
 exports.wikiImpactMode = exports.parsedArgs.wikiImpactMode;
 exports.wikiImpactTarget = exports.parsedArgs.wikiImpactTarget;
-exports.wikiVisualizeMode = exports.parsedArgs.wikiVisualizeMode;
-exports.wikiVisualizeOutput = exports.parsedArgs.wikiVisualizeOutput;
+exports.wikiNeighborhoodMode = exports.parsedArgs.wikiNeighborhoodMode;
+exports.wikiNeighborhoodTarget = exports.parsedArgs.wikiNeighborhoodTarget;
 exports.codeContextPackTarget = exports.parsedArgs.codeContextPackTarget;
 exports.codeImpactTarget = exports.parsedArgs.codeImpactTarget;
 exports.codeQuerySql = exports.parsedArgs.codeQuerySql;

package/dist/init-project-wiki.js

@@ -9,7 +9,6 @@ const modes_1 = require("./modes");
 const migration_1 = require("./migration");
 const session_handoff_1 = require("./session-handoff");
 const templates_1 = require("./templates");
-const wiki_visualizer_1 = require("./wiki-visualizer");
 const workspace_1 = require("./workspace");
 function codeIndex() {
     return require("./code-index");
@@ -37,8 +36,8 @@ Options:
   --dry-run                        With install, preview copied skill files without writing them.
   --query <terms>                  Search wiki paths, metadata, titles, and bodies (answer-shaped, capped output).
   --wiki-impact <page-or-term>     Show wiki backlinks, decision_ref citations, and router depth for matching pages.
-  --wiki-visualize                 Write a static wiki graph visualizer to .project-wiki/wiki-graph.html.
-  --wiki-visualize-out <path>      With --wiki-visualize, write under a custom .project-wiki/ path.
+  --wiki-neighborhood <page-or-term>
+                                    Show a bounded read order for nearby wiki pages.
   --refresh-index                  Update the managed auto-discovered wiki index block.
   --capture-inbox                  Append a candidate note with --title, --content, and optional --category.
   --handoff-save                   Save local generated session handoff state under .project-wiki/session/.
@@ -147,10 +146,6 @@ if (args_1.codeReportSection && !args_1.codeReportMode) {
     console.error("--code-report-section is only supported with --code-report.");
     process.exit(1);
 }
-if (args_1.wikiVisualizeOutput && !args_1.wikiVisualizeMode) {
-    console.error("--wiki-visualize-out is only supported with --wiki-visualize.");
-    process.exit(1);
-}
 if (args_1.pruneCheckStrictMode && !args_1.pruneCheckMode) {
     console.error("--prune-check-strict is only supported with --prune-check.");
     process.exit(1);
@@ -266,16 +261,9 @@ function runInitCommand() {
         exitAfterStdoutDrain(0);
         return;
     }
-    if (args_1.wikiVisualizeMode) {
-        try {
-            const output = (0, wiki_visualizer_1.writeWikiVisualizer)(args_1.wikiVisualizeOutput);
-            console.log(`Project wiki visualizer written: ${output}`);
-            exitAfterStdoutDrain(0);
-        }
-        catch (error) {
-            console.error(error instanceof Error ? error.message : String(error));
-            process.exit(1);
-        }
+    if (args_1.wikiNeighborhoodMode) {
+        (0, modes_1.runWikiNeighborhoodMode)();
+        exitAfterStdoutDrain(0);
         return;
     }
     if (args_1.queryTerm) {

package/dist/modes.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildRefreshIndexBlock = buildRefreshIndexBlock;
 exports.runQueryMode = runQueryMode;
 exports.runWikiImpactMode = runWikiImpactMode;
+exports.runWikiNeighborhoodMode = runWikiNeighborhoodMode;
 exports.projectCandidatesContent = projectCandidatesContent;
 exports.appendProjectCandidate = appendProjectCandidate;
 exports.appendCaptureInbox = appendCaptureInbox;
@@ -325,6 +326,14 @@ function runWikiImpactMode() {
     const corpus = (0, wiki_corpus_1.loadWikiCorpus)();
     console.log((0, wiki_graph_1.wikiImpactAnswer)(corpus.pages, args_1.wikiImpactTarget.trim(), (0, wiki_corpus_1.wikiCorpusGraph)(corpus)));
 }
+function runWikiNeighborhoodMode() {
+    if (!args_1.wikiNeighborhoodTarget.trim()) {
+        console.error("missing wiki neighborhood target: use --wiki-neighborhood \"page-or-term\"");
+        process.exit(1);
+    }
+    const corpus = (0, wiki_corpus_1.loadWikiCorpus)();
+    console.log((0, wiki_graph_1.wikiNeighborhoodAnswer)(corpus.pages, args_1.wikiNeighborhoodTarget.trim(), (0, wiki_corpus_1.wikiCorpusGraph)(corpus)));
+}
 function projectCandidatesContent() {
     return `${(0, templates_1.metadata)("inbox", "on-demand", "wiki/meta/wiki-ops-v1-decisions.md", "candidates are adopted, rejected, or stale")}
 # Project Candidates Inbox
@@ -699,6 +708,7 @@ function collectLinkDiagnostics(corpus = (0, wiki_corpus_1.loadWikiCorpus)()) {
             }
         }
     }
+    diagnostics.push(...(0, wiki_diagnostics_1.collectTopologyDiagnostics)(corpus));
     return diagnostics.sort((a, b) => a.severity.localeCompare(b.severity) || a.file.localeCompare(b.file) || a.code.localeCompare(b.code));
 }
 function legacyWikiRoots() {
@@ -725,9 +735,10 @@ function migrationLegacyReferenceDiagnostics(files, corpus) {
         message: "new project truth must not link to or cite wiki_legacy*; migrate the meaning or keep unresolved material in migration inboxes",
     }));
 }
-function collectQualityDiagnostics(corpus = (0, wiki_corpus_1.loadWikiCorpus)()) {
+function collectQualityDiagnostics(corpus = (0, wiki_corpus_1.loadWikiCorpus)(), options = {}) {
     const diagnostics = [];
     const files = corpus.files;
+    const currentDate = options.today ?? workspace_1.today;
     const titles = new Map();
     for (const file of files) {
         const text = (0, wiki_corpus_1.wikiCorpusText)(corpus, file);
@@ -742,7 +753,7 @@ function collectQualityDiagnostics(corpus = (0, wiki_corpus_1.loadWikiCorpus)())
         if (tldrExpected && !/##\s+TL;DR/.test(body)) {
             diagnostics.push({ code: "missing-tldr", severity: "warn", file, message: "add a compact TL;DR near the top" });
         }
-        const reviewAge = updated ? (0, wiki_diagnostics_1.staleReviewAge)(updated, workspace_1.today) : null;
+        const reviewAge = updated ? (0, wiki_diagnostics_1.staleReviewAge)(updated, currentDate) : null;
         if (status === "active" && reviewAge !== null && /project-canonical|project-decisions|source-summary|wiki-meta/.test(scope)) {
             diagnostics.push({ code: "stale-review", severity: "warn", file, message: `updated ${reviewAge} days ago: ${updated}` });
         }

package/dist/native/project-librarian-indexer-manifest.json

@@ -29,16 +29,16 @@
       "architecture": "arm64",
       "format": "elf",
       "path": "dist/native/linux-arm64-musl/project-librarian-indexer",
-      "sha256": "80f7440c4d115d05805b63b8118a172ddeb5a374b7154593e5b1d0b804a938ae",
-      "size": 3100816,
+      "sha256": "bcb48020ae87fe3e5ebd6a8d986a91f83e67e5d69c4df9357a7c3a6c78c232b0",
+      "size": 3101344,
       "triple": "linux-arm64-musl"
     },
     {
       "architecture": "x64",
       "format": "elf",
       "path": "dist/native/linux-x64/project-librarian-indexer",
-      "sha256": "3d93408db344567d7de6f477b58fdaf6aba19c943336fb7ab9720e3e9fa68c31",
-      "size": 3110832,
+      "sha256": "22d32884276c23c4597bd611facd5880936b29600c8331bb3d585d2ab370a206",
+      "size": 3110688,
       "triple": "linux-x64"
     },
     {
@@ -53,7 +53,7 @@
       "architecture": "arm64",
       "format": "pe",
       "path": "dist/native/win32-arm64/project-librarian-indexer.exe",
-      "sha256": "8c357be6b1e0c3c13337abccdc0edefc628267b272c8aca30be50c679bffb4af",
+      "sha256": "b49ad30a72a9a93ff524cc1643b141c94de4850655ce646d80579edc5b832f71",
       "size": 2098688,
       "triple": "win32-arm64"
     },
@@ -61,7 +61,7 @@
       "architecture": "x64",
       "format": "pe",
       "path": "dist/native/win32-x64/project-librarian-indexer.exe",
-      "sha256": "f4f9f6424fef446ece0684760afd8a404135acc007794c3e0f3effccdc8b4801",
+      "sha256": "36a8416e4975100f89bc57281b311b45158469fb12ea37d33dac2d5855a5e47a",
       "size": 2375680,
       "triple": "win32-x64"
     }

package/dist/wiki-diagnostics.js

@@ -1,8 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.staleReviewAgeDays = void 0;
+exports.topologyFanoutThreshold = exports.topologyHubOverloadThreshold = exports.staleReviewAgeDays = void 0;
 exports.staleReviewAge = staleReviewAge;
+exports.collectTopologyDiagnostics = collectTopologyDiagnostics;
+const wiki_corpus_1 = require("./wiki-corpus");
+const wiki_graph_1 = require("./wiki-graph");
+const workspace_1 = require("./workspace");
 exports.staleReviewAgeDays = 30;
+exports.topologyHubOverloadThreshold = 60;
+exports.topologyFanoutThreshold = 8;
 function dateOnlyMillis(value) {
     if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
         return null;
@@ -17,3 +23,107 @@ function staleReviewAge(updated, currentDate) {
     const ageDays = Math.floor((currentMillis - updatedMillis) / 86_400_000);
     return ageDays > exports.staleReviewAgeDays ? ageDays : null;
 }
+function uniqueExisting(values, fileSet) {
+    return Array.from(new Set(values.filter((value) => fileSet.has(value)))).sort();
+}
+function isGeneratedScopedRouter(file) {
+    return /^wiki\/indexes\/auto-[a-z0-9-]+(?:-\d+)?\.md$/.test(file);
+}
+function isCanonicalTruthPage(file, text) {
+    return file.startsWith("wiki/canonical/") && (0, workspace_1.metadataValue)(text, "status") === "active";
+}
+function hasEvidenceClaimSignal(body) {
+    return /\b(source-backed|source backed|research-backed|external research|paper-backed|evidence-backed)\b/i.test(body);
+}
+function hasDecisionRefSignal(text) {
+    const decisionRef = (0, workspace_1.metadataValue)(text, "decision_ref").trim().toLowerCase();
+    return decisionRef !== "" && decisionRef !== "none";
+}
+function hasFocusedAuthoritySignal(text, body) {
+    return hasDecisionRefSignal(text) || hasEvidenceClaimSignal(body);
+}
+function hasEvidenceLink(file, corpus, graph = (0, wiki_corpus_1.wikiCorpusGraph)(corpus)) {
+    const outgoingLinks = graph.outgoingLinks.get(file) ?? [];
+    const sourceLink = outgoingLinks.some((link) => link.normalizedTarget.startsWith("wiki/sources/") && corpus.fileSet.has(link.normalizedTarget));
+    const decisionRef = graph.outgoingDecisionRef.get(file);
+    return sourceLink || Boolean(decisionRef && corpus.fileSet.has(decisionRef));
+}
+function isBroadReviewTrigger(trigger) {
+    const normalized = trigger.toLowerCase().trim();
+    if (!normalized)
+        return false;
+    return normalized === "changes"
+        || normalized === "project changes"
+        || normalized === "routine review"
+        || /^any\b.*changes$/.test(normalized)
+        || /^general\b.*changes$/.test(normalized);
+}
+function isTopologyHub(file) {
+    return file === "wiki/index.md"
+        || file.startsWith("wiki/meta/")
+        || /^wiki\/indexes\/(?!auto-)[^/]+\.md$/.test(file);
+}
+function collectTopologyDiagnostics(corpus) {
+    const diagnostics = [];
+    const graph = (0, wiki_corpus_1.wikiCorpusGraph)(corpus);
+    for (const file of corpus.files) {
+        if (isGeneratedScopedRouter(file))
+            continue;
+        const outgoing = uniqueExisting((graph.outgoingLinks.get(file) ?? [])
+            .map((link) => link.normalizedTarget)
+            .filter((target) => target !== file), corpus.fileSet);
+        if (isTopologyHub(file) && outgoing.length > exports.topologyHubOverloadThreshold) {
+            diagnostics.push({
+                code: "hub-overload",
+                severity: "warn",
+                file,
+                message: `${outgoing.length} outgoing wiki links exceed the topology hub threshold ${exports.topologyHubOverloadThreshold}; split or scope the route surface`,
+            });
+        }
+    }
+    for (const file of corpus.files) {
+        const text = (0, wiki_corpus_1.wikiCorpusText)(corpus, file);
+        if (isCanonicalTruthPage(file, text)) {
+            const body = (0, workspace_1.stripMetadataHeader)(text);
+            const incoming = uniqueExisting((graph.incomingLinks.get(file) ?? [])
+                .map((link) => link.file)
+                .filter((source) => source !== file), corpus.fileSet);
+            if (incoming.length > 0 && incoming.every(isGeneratedScopedRouter) && hasFocusedAuthoritySignal(text, body)) {
+                diagnostics.push({
+                    code: "weak-authority-route",
+                    severity: "warn",
+                    file,
+                    message: "active canonical page with authority signals is routed only by generated auto-index pages; add a focused route when this truth is durable",
+                });
+            }
+            if (hasEvidenceClaimSignal(body) && !hasEvidenceLink(file, corpus, graph)) {
+                diagnostics.push({
+                    code: "missing-evidence-link",
+                    severity: "warn",
+                    file,
+                    message: "canonical page makes a source-backed claim but has no source link or decision_ref evidence link",
+                });
+            }
+        }
+    }
+    for (const file of corpus.files) {
+        if (file === wiki_graph_1.wikiRouterRoot || isGeneratedScopedRouter(file))
+            continue;
+        const text = (0, wiki_corpus_1.wikiCorpusText)(corpus, file);
+        if ((0, workspace_1.metadataValue)(text, "status") !== "active")
+            continue;
+        const incoming = uniqueExisting((graph.incomingLinks.get(file) ?? [])
+            .map((link) => link.file)
+            .filter((source) => source !== file), corpus.fileSet);
+        const reviewTrigger = (0, workspace_1.metadataValue)(text, "review_trigger");
+        if (incoming.length >= exports.topologyFanoutThreshold && isBroadReviewTrigger(reviewTrigger)) {
+            diagnostics.push({
+                code: "stale-fanout",
+                severity: "warn",
+                file,
+                message: `${incoming.length} incoming links with broad review_trigger "${reviewTrigger}"; tighten review trigger before broad edits`,
+            });
+        }
+    }
+    return diagnostics.sort((a, b) => a.file.localeCompare(b.file) || a.code.localeCompare(b.code));
+}

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/benchmarks.md

@@ -17,17 +17,33 @@ Generated benchmark reports under `benchmarks/reports/llm/` are ignored by defau
 
 ## Wiki Track
 
-Cost-weighted tokens, Project Librarian vs control:
-
-| Scale | decision_lookup | aggregation | multi_session (2nd session) |
-| --- | --- | --- | --- |
-| Small | 14.4% less | 81.0% more | 22.0% less |
-| Medium | 52.0% less | 19.0% less | 54.1% less |
-| Large | 71.1% less | 29.0% less | 71.8% less |
-
-Latest synthetic wiki-track release candidate: 2026-06-19, `gpt-5.5`, 42 scenarios, 3 measured runs plus 1 warmup each. The overall claim gate **passed**: 42/42 scenarios passed correctness, all 42 scenarios were claimable, and every corpus gate met the 3-run minimum.
-
-The release claim is bounded to the synthetic wiki-routing track and the listed task families. It is not a claim about code-graph behavior, real repositories, every agent surface, or every question shape. Published boundaries remain visible: small `aggregation` still costs 81.0% more with the wiki, small `release_policy` costs 9.4% more in the full report, and `aggregation` stays slower at every scale even when token cost drops.
+Latest clean synthetic wiki-track release evidence: 2026-06-29, `gpt-5.5`, branch `perf/small-repo-code-evidence-safeguards` at `ae79390`, 42 scenarios, 21 with/without pairs, 3 measured runs plus 1 warmup each. The overall claim gate **passed**, and the claim ledger classified the report as release-claimable. A repair run reused 125 claimable measured runs from retained raw JSONL and remeasured the remaining failed slot.
+
+Cost-weighted tokens, Project Librarian vs control, all scales combined:
+
+| Task family | Delta |
+| --- | ---: |
+| onboarding | 65.95% less |
+| decision_lookup | 48.46% less |
+| code_impact | 55.61% less |
+| release_policy | 58.22% less |
+| change_location | 29.59% less |
+| multi_session | 52.58% less |
+| aggregation | 42.53% less |
+
+Scale-specific cost-weighted token deltas:
+
+| Task family | Small | Medium | Large |
+| --- | ---: | ---: | ---: |
+| onboarding | 60.88% less | 65.53% less | 69.17% less |
+| decision_lookup | 19.18% less | 51.29% less | 60.12% less |
+| code_impact | 26.61% less | 54.81% less | 68.43% less |
+| release_policy | 30.23% less | 62.16% less | 67.26% less |
+| change_location | 7.79% less | 2.86% more | 57.27% less |
+| multi_session | 54.29% more | 35.32% less | 82.77% less |
+| aggregation | 7.66% less | 51.32% less | 49.17% less |
+
+The release claim is bounded to the synthetic wiki-routing track and the listed task families. It is not a claim about code-graph behavior, real repositories, every agent surface, or every question shape. Published boundaries remain visible: small `multi_session` and medium `change_location` cost more with the wiki in the cost-weighted token metric. `code_impact`, `change_location`, and `aggregation` also still have wall-time or command-count regressions in this report, even though token and output-byte metrics improved at the task-family aggregate level.
 
 ## Code-Graph Track
 
@@ -52,7 +68,11 @@ Repositories under test:
 
 Question types:
 
+- **onboarding** - summarize what the project is, current risks, and where to read next.
 - **decision_lookup** - find the latest project decision and its date from the wiki.
+- **code_impact** - identify likely impacted files or areas for a benchmark report schema change.
+- **release_policy** - find the checks required before publishing or making benchmark claims.
+- **change_location** - find where an agent should edit to implement the Codex LLM benchmark runner.
 - **aggregation** - answer a question whose facts are scattered across several pages and must be synthesized.
 - **multi_session** - a second session on the same project, measuring whether the durable wiki helps the next session, not just the first.
 - **impact_trace** - trace the full set of direct and indirect importers for a changing module.

package/docs/cli-reference.md

@@ -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. |