project-librarian 0.5.6 → 0.5.8

package/README.ko.md

@@ -31,7 +31,7 @@ npx project-librarian@latest install --scope user --agents all
 npx project-librarian@latest install --scope project --agents all
 ```
 
-`install`은 재사용 가능한 실행 파일과 스킬 파일만 복사합니다. `AGENTS.md`, 에이전트 훅, `wiki/`, git 훅 파일, 진단, 선택적 코드 근거 지원을 만들거나 갱신하는 것은 에이전트가 실행하는 생명주기 명령입니다. `install-skill`은 호환성 별칭으로 계속 지원됩니다.
+`install`은 재사용 가능한 실행 파일, 스킬 파일, 로컬 실행기에 필요한 필수 런타임 의존성을 복사합니다. `AGENTS.md`, 에이전트 훅, `wiki/`, git 훅 파일, 진단, 선택적 코드 근거 지원을 만들거나 갱신하는 것은 에이전트가 실행하는 생명주기 명령입니다. `install-skill`은 호환성 별칭으로 계속 지원됩니다.
 
 ## 업데이트
 
@@ -104,15 +104,30 @@ Project Librarian은 작은 첫 읽기와 더 깊은 정본으로 가는 경로
 
 여기 수치는 모든 상황에 대한 약속이 아니라 관리자 릴리스 근거입니다. 모든 값은 실제 Codex JSONL 사용량과 로컬 실행 시간이며, Project Librarian이 없는 `organic` 대조군과 격리된 환경에서 비교했습니다. 위키 라우팅 트랙과 코드 그래프 트랙은 분리해 측정하며, 한 트랙의 우위가 다른 트랙의 주장을 뒷받침하지 않습니다.
 
-위키 트랙, 대조군 대비 비용 가중 토큰:
+최신 clean 합성 위키 라우팅 트랙 릴리스 근거는 2026-06-29에 `gpt-5.5`, `perf/small-repo-code-evidence-safeguards` 브랜치의 `ae79390` 커밋에서 측정했습니다. 42개 시나리오, 21개 with/without 쌍을 각 3회 측정하고 1회 예열했으며, 전체 주장 게이트는 통과했고 주장 ledger는 이 보고서를 release-claimable로 분류했습니다. repair 실행은 보존된 raw JSONL에서 claimable 측정 실행 125개를 재사용하고 남은 실패 슬롯 1개를 다시 측정했습니다. 이 주장은 합성 위키 라우팅 트랙과 표기된 작업 유형에 한정되며, 코드 그래프 동작, 실제 저장소, 모든 에이전트 표면, 모든 질문 형태에 대한 주장이 아닙니다.
 
-| 규모 | decision_lookup | aggregation | multi_session |
-| --- | --- | --- | --- |
-| 소형 | 14.4% 적음 | 81.0% 많음 | 22.0% 적음 |
-| 중형 | 52.0% 적음 | 19.0% 적음 | 54.1% 적음 |
-| 대형 | 71.1% 적음 | 29.0% 적음 | 71.8% 적음 |
+위키 트랙 집계, 대조군 대비 변화:
 
-최신 합성 위키 라우팅 트랙 릴리스 후보는 2026-06-19에 `gpt-5.5`로 측정했으며, 42개 시나리오를 각 3회 측정하고 1회 예열했습니다. 전체 주장 게이트는 통과했습니다. 이 주장은 합성 위키 라우팅 트랙과 표기된 작업 유형에 한정되며, 코드 그래프 동작, 실제 저장소, 모든 에이전트 표면, 모든 질문 형태에 대한 주장이 아닙니다.
+| 규모 | 비용 가중 토큰 | 전체 토큰 | 실행 시간 | 명령 수 | 도구 출력 |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| 전체 | 51.39% 적음 | 48.67% 적음 | 19.83% 적음 | 18.40% 적음 | 85.88% 적음 |
+| 소형 | 21.59% 적음 | 9.31% 적음 | 13.91% 적음 | 12.64% 적음 | 43.89% 적음 |
+| 중형 | 45.95% 적음 | 37.42% 적음 | 11.88% 적음 | 4.30% 적음 | 69.12% 적음 |
+| 대형 | 66.97% 적음 | 69.87% 적음 | 31.90% 적음 | 35.19% 적음 | 95.58% 적음 |
+
+위키 트랙 작업 유형별 비용 가중 토큰 변화:
+
+| 작업 유형 | 변화 |
+| --- | ---: |
+| onboarding | 65.95% 적음 |
+| decision_lookup | 48.46% 적음 |
+| code_impact | 55.61% 적음 |
+| release_policy | 58.22% 적음 |
+| change_location | 29.59% 적음 |
+| multi_session | 52.58% 적음 |
+| aggregation | 42.53% 적음 |
+
+실행 시간과 명령 수의 한계도 있습니다. 이번 보고서에서 `code_impact`, `change_location`, `aggregation`은 토큰과 출력 바이트가 모두 개선됐지만, 실행 시간이나 명령 수에서는 일부 역전이 남아 있습니다.
 
 코드 그래프 트랙, 대조군 대비 비용 가중 토큰:
 

package/README.md

@@ -31,7 +31,7 @@ The installed skill resolves the local runner and executes the right command fro
 npx project-librarian@latest install --scope project --agents all
 ```
 
-`install` copies reusable runner and skill files only. The agent-run lifecycle command creates or updates `AGENTS.md`, agent hooks, `wiki/`, git hook files, diagnostics, and optional code-evidence support. `install-skill` remains a compatibility alias.
+`install` copies reusable runner and skill files plus required local-runner runtime dependencies. The agent-run lifecycle command creates or updates `AGENTS.md`, agent hooks, `wiki/`, git hook files, diagnostics, and optional code-evidence support. `install-skill` remains a compatibility alias.
 
 ## Update
 
@@ -104,15 +104,30 @@ See [Usage](docs/usage.md) for install scopes, runner paths, generated files, mi
 
 These numbers are maintainer release evidence, not a blanket promise. Every value is real Codex JSONL usage and local wall-clock time, measured hermetically against an `organic` control with no Project Librarian. The wiki-routing track and the code-graph track are measured separately; a win on one never backs a claim about the other.
 
-Wiki track, cost-weighted tokens vs control:
+Latest clean synthetic wiki-routing 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. This is bounded to the synthetic wiki-routing track and listed task families; it is not a claim about code-graph behavior, real repositories, every agent surface, or every question shape.
 
-| Scale | decision_lookup | aggregation | multi_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 |
+Wiki track aggregate deltas vs control:
 
-Latest synthetic wiki-routing track release candidate: 2026-06-19, `gpt-5.5`, 42 scenarios, 3 measured runs plus 1 warmup each. The overall claim gate **passed**. This is bounded to the synthetic wiki-routing track and listed task families; it is not a claim about code-graph behavior, real repositories, every agent surface, or every question shape.
+| Scale | Cost-weighted tokens | Total tokens | Wall time | Commands | Tool output |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| All | 51.39% less | 48.67% less | 19.83% less | 18.40% less | 85.88% less |
+| Small | 21.59% less | 9.31% less | 13.91% less | 12.64% less | 43.89% less |
+| 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:
+
+| 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 |
+
+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/SKILL.md

@@ -175,6 +175,13 @@ Require a compatible existing cache for changed-file-only updates with `--increm
 $PROJECT_LIBRARIAN --code-index --incremental --code-scope src
 ```
 
+If the cache schema version differs from the current runner, inspect it and require explicit replacement approval before rebuilding:
+
+```bash
+$PROJECT_LIBRARIAN --code-index-health
+$PROJECT_LIBRARIAN --code-index --code-index-migrate --code-scope src
+```
+
 Run read-only SQL over the cache with `--code-query`:
 
 ```bash

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.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.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.parseArgs = parseArgs;
 exports.argValue = argValue;
 exports.argValues = argValues;
@@ -22,6 +22,7 @@ const flagDefinitions = [
     { name: "--code-index-full", value: "none", aliases: ["--code-evidence-index-full"] },
     { name: "--code-index-health", value: "none" },
     { name: "--code-index-incremental", value: "none", aliases: ["--incremental", "--code-incremental", "--code-evidence-index-incremental"] },
+    { name: "--code-index-migrate", value: "none", aliases: ["--code-evidence-index-migrate"] },
     { name: "--code-index-out", value: "value", aliases: ["--code-evidence-out"] },
     { name: "--code-parser", value: "value", aliases: ["--code-evidence-parser"] },
     { name: "--code-query", value: "value", aliases: ["--code-evidence-query"] },
@@ -185,6 +186,7 @@ function parseArgs(argv) {
         codeIndexFullMode: hasAnyFlag("--code-index-full"),
         codeIndexHealthMode: args.has("--code-index-health"),
         codeIndexIncrementalMode: hasAnyFlag("--code-index-incremental"),
+        codeIndexMigrateMode: hasAnyFlag("--code-index-migrate"),
         codeIndexMode: hasAnyFlag("--code-index"),
         codeIndexOutput: argValueFromAny("--code-index-out") || ".project-wiki/code-evidence.sqlite",
         codeIndexScopes: argValuesFromAny("--code-scope"),
@@ -308,6 +310,7 @@ exports.codeIndexMode = exports.parsedArgs.codeIndexMode;
 exports.codeIndexEngine = exports.parsedArgs.codeIndexEngine;
 exports.codeIndexEngineMode = exports.parsedArgs.codeIndexEngineMode;
 exports.codeIndexIncrementalMode = exports.parsedArgs.codeIndexIncrementalMode;
+exports.codeIndexMigrateMode = exports.parsedArgs.codeIndexMigrateMode;
 exports.codeIndexFullMode = exports.parsedArgs.codeIndexFullMode;
 exports.codeIndexHealthMode = exports.parsedArgs.codeIndexHealthMode;
 exports.codeReportMode = exports.parsedArgs.codeReportMode;

package/dist/code-index/index-health.js

@@ -79,8 +79,8 @@ function readScopes(scopesJson, scopesText, fallback) {
     const scopes = scopesText.split(",").map((scope) => scope.trim()).filter(Boolean);
     return scopes.length > 0 ? scopes : fallback;
 }
-function rebuildCommand(indexableFiles, smallRepoThreshold) {
-    const parts = ["project-librarian", "--code-index", "--code-index-full"];
+function rebuildCommand(indexableFiles, smallRepoThreshold, options = {}) {
+    const parts = ["project-librarian", "--code-index", options.schemaMigration ? "--code-index-migrate" : "--code-index-full"];
     if (indexableFiles !== null && indexableFiles < smallRepoThreshold)
         parts.push("--acknowledge-small-repo");
     return parts.join(" ");
@@ -126,6 +126,7 @@ function inspectCodeIndexHealth(options) {
         const indexedFiles = indexedFilesText ? Number(indexedFilesText) : null;
         const indexableFiles = safeDiscoverCodeFiles(options.discoverCodeFiles, scopes.length > 0 ? scopes : options.defaultScopes);
         const compatible = foundSchemaVersion === options.expectedSchemaVersion;
+        const schemaMigration = Boolean(foundSchemaVersion) && !compatible;
         return {
             database_path: options.relativePath,
             expected_schema_version: options.expectedSchemaVersion,
@@ -136,7 +137,7 @@ function inspectCodeIndexHealth(options) {
                 ? `code evidence index is compatible: schema ${foundSchemaVersion}`
                 : `code evidence index schema version ${foundSchemaVersion || "(missing)"} is incompatible with ${options.expectedSchemaVersion}`,
             parser_mode: parserMode,
-            recommended_rebuild_command: rebuildCommand(indexableFiles, options.smallRepoThreshold),
+            recommended_rebuild_command: rebuildCommand(indexableFiles, options.smallRepoThreshold, { schemaMigration }),
             scopes,
             status: compatible ? "compatible" : "incompatible_schema",
             tables,

package/dist/code-index/modes.js

@@ -71,6 +71,49 @@ function requireCompatibleDatabase(database, runtime) {
         ].join("\n"));
     }
 }
+function schemaMigrationRequired(reason) {
+    return reason.startsWith("existing schema version ") && !reason.includes("(missing)");
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:=@+-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function schemaMigrationApprovalCommand(options) {
+    const parts = ["project-librarian", "--code-index", "--code-index-migrate"];
+    for (const scope of options.scopes) {
+        if (scope !== ".")
+            parts.push("--code-scope", scope);
+    }
+    if (args_1.codeIndexOutput !== ".project-wiki/code-evidence.sqlite")
+        parts.push("--code-index-out", args_1.codeIndexOutput);
+    if (args_1.acknowledgeSmallRepoMode)
+        parts.push("--acknowledge-small-repo");
+    if (options.requestedEngine !== "auto")
+        parts.push("--code-index-engine", options.requestedEngine);
+    if (options.parserMode !== "default")
+        parts.push("--code-parser", options.parserMode);
+    return parts.map(shellQuote).join(" ");
+}
+function schemaMigrationRequiredMessage(runtime, reason, options) {
+    const databasePath = runtime.codeEvidenceDatabasePath();
+    return [
+        `code evidence index schema migration required: ${reason}`,
+        "The existing disposable code evidence index must be replaced before this version can write it.",
+        `approve: ${schemaMigrationApprovalCommand(options)}`,
+        "inspect: project-librarian --code-index-health",
+        `database: ${databasePath.relativePath}`,
+    ].join("\n");
+}
+function unreadableIndexMessage(runtime) {
+    const health = runtime.codeIndexHealth();
+    return [
+        health.message,
+        "inspect: project-librarian --code-index-health",
+        `rebuild: ${health.recommended_rebuild_command}`,
+        `database: ${health.database_path}`,
+    ].join("\n");
+}
 function elapsedMs(started) {
     return Number(process.hrtime.bigint() - started) / 1_000_000;
 }
@@ -88,6 +131,36 @@ function emitCodeIndexPhaseTimings(timings) {
         return;
     console.error(`code_index_phase_timings ${JSON.stringify(timings)}`);
 }
+function finishCodeEvidencePhaseTimings(started, timings) {
+    timings.total_ms = Number(elapsedMs(started).toFixed(3));
+    emitCodeIndexPhaseTimings(timings);
+}
+function runWithCodeEvidenceDatabase(runtime, operation, options = {}) {
+    const totalStarted = process.hrtime.bigint();
+    const phaseTimings = {};
+    let database;
+    try {
+        measurePhase(phaseTimings, "require_existing_index_ms", () => runtime.requireExistingIndex());
+        options.beforeOpen?.();
+        database = measurePhase(phaseTimings, "open_database_ms", () => runtime.openDatabase(runtime.codeEvidenceDatabasePath().absolutePath));
+        operation(database, phaseTimings);
+    }
+    finally {
+        if (database) {
+            const openedDatabase = database;
+            measurePhase(phaseTimings, "close_database_ms", () => openedDatabase.close());
+        }
+        finishCodeEvidencePhaseTimings(totalStarted, phaseTimings);
+    }
+}
+function requireCompatibleDatabaseTimed(database, runtime, timings) {
+    measurePhase(timings, "compatibility_ms", () => requireCompatibleDatabase(database, runtime));
+}
+function checkedCodeIndexStaleness(database, runtime, timings) {
+    const staleness = measurePhase(timings, "staleness_ms", () => runtime.codeIndexStaleness(database));
+    runtime.warnIfCodeIndexStale(database, staleness);
+    return staleness;
+}
 function configureBulkWriteConnection(database) {
     database.exec(`
     PRAGMA synchronous = OFF;
@@ -125,38 +198,49 @@ function runCodeIndexMode(runtime) {
         runtime.fail(scaleGate.warning);
     const engineSelectionContext = runtime.codeIndexEngineSelectionContext(discoveredFiles, parserMode);
     const engine = resolveCodeIndexEngine(requestedEngine, engineSelectionContext, runtime.shouldUseNativeCodeIndexAuto);
+    const existingIndex = fs.existsSync(databasePath.absolutePath);
+    if (args_1.codeIndexIncrementalMode && !existingIndex) {
+        runtime.fail(`--incremental requires an existing compatible code evidence index: ${databasePath.relativePath}`);
+    }
+    let compatibility = { compatible: false, reason: "compatibility was not checked" };
+    let checkedCompatibility = false;
+    if (existingIndex) {
+        try {
+            measurePhase(phaseTimings, "compatibility_ms", () => {
+                const existingDatabase = runtime.openDatabase(databasePath.absolutePath);
+                try {
+                    compatibility = (0, schema_1.incrementalCompatibility)(existingDatabase, scopes, parserMode);
+                    checkedCompatibility = true;
+                }
+                finally {
+                    existingDatabase.close();
+                }
+            });
+        }
+        catch {
+            if (!args_1.codeIndexFullMode && !args_1.codeIndexMigrateMode)
+                runtime.fail(unreadableIndexMessage(runtime));
+        }
+        if (!compatibility.compatible && schemaMigrationRequired(compatibility.reason) && !args_1.codeIndexMigrateMode) {
+            runtime.fail(schemaMigrationRequiredMessage(runtime, compatibility.reason, { parserMode, requestedEngine, scopes }));
+        }
+    }
     if (engine === "native-rust") {
         if (!args_1.codeIndexIncrementalMode) {
             try {
                 measurePhase(phaseTimings, "native_helper_ms", () => runtime.runNativeCodeIndexMode({ databasePath, discoveredFiles, parserMode, requestedEngine, scopes }));
-                phaseTimings.total_ms = Number(elapsedMs(totalStarted).toFixed(3));
-                emitCodeIndexPhaseTimings(phaseTimings);
+                finishCodeEvidencePhaseTimings(totalStarted, phaseTimings);
                 return;
             }
             catch (error) {
-                phaseTimings.total_ms = Number(elapsedMs(totalStarted).toFixed(3));
-                emitCodeIndexPhaseTimings(phaseTimings);
+                finishCodeEvidencePhaseTimings(totalStarted, phaseTimings);
                 throw error;
             }
         }
     }
-    const existingIndex = fs.existsSync(databasePath.absolutePath);
-    if (args_1.codeIndexIncrementalMode && !existingIndex) {
-        runtime.fail(`--incremental requires an existing compatible code evidence index: ${databasePath.relativePath}`);
-    }
     let incremental = false;
-    if (existingIndex && !args_1.codeIndexFullMode) {
-        let compatibility = { compatible: false, reason: "compatibility was not checked" };
-        measurePhase(phaseTimings, "compatibility_ms", () => {
-            const existingDatabase = runtime.openDatabase(databasePath.absolutePath);
-            try {
-                compatibility = (0, schema_1.incrementalCompatibility)(existingDatabase, scopes, parserMode);
-            }
-            finally {
-                existingDatabase.close();
-            }
-        });
-        incremental = !args_1.codeIndexFullMode && compatibility.compatible;
+    if (existingIndex && checkedCompatibility && !args_1.codeIndexFullMode && !args_1.codeIndexMigrateMode) {
+        incremental = compatibility.compatible;
         if (args_1.codeIndexIncrementalMode && !compatibility.compatible)
             runtime.fail(`--incremental cannot update ${databasePath.relativePath}: ${compatibility.reason}`);
     }
@@ -222,8 +306,7 @@ function runCodeIndexMode(runtime) {
                     scopes,
                     unchangedFiles,
                 }));
-                phaseTimings.total_ms = Number(elapsedMs(totalStarted).toFixed(3));
-                emitCodeIndexPhaseTimings(phaseTimings);
+                finishCodeEvidencePhaseTimings(totalStarted, phaseTimings);
                 return;
             }
         }
@@ -247,7 +330,6 @@ function runCodeIndexMode(runtime) {
                 (0, schema_1.createSecondaryIndexes)(activeDatabase);
             activeDatabase.exec("COMMIT");
         });
-        phaseTimings.total_ms = Number(elapsedMs(totalStarted).toFixed(3));
         console.log("Project wiki code evidence index complete.");
         console.log(`database: ${databasePath.relativePath}`);
         console.log(`mode: ${incremental ? "incremental" : "full"}`);
@@ -260,7 +342,7 @@ function runCodeIndexMode(runtime) {
         console.log(`reindexed_files: ${reindexedFiles.length}`);
         console.log(`deleted_files: ${deletedPaths.length}`);
         console.log(`unchanged_files: ${unchangedFiles}`);
-        emitCodeIndexPhaseTimings(phaseTimings);
+        finishCodeEvidencePhaseTimings(totalStarted, phaseTimings);
     }
     catch (error) {
         try {
@@ -280,123 +362,93 @@ function runCodeQueryMode(runtime) {
         console.error("missing SQL: use --code-query \"select ...\"");
         process.exit(1);
     }
-    runtime.requireExistingIndex();
-    if (!(0, code_index_sql_1.isReadOnlySql)(args_1.codeQuerySql)) {
-        console.error("code queries must be read-only SQL starting with SELECT or WITH");
-        process.exit(1);
-    }
-    const database = runtime.openDatabase(runtime.codeEvidenceDatabasePath().absolutePath);
-    try {
+    runWithCodeEvidenceDatabase(runtime, (database, phaseTimings) => {
         database.exec("PRAGMA query_only = ON");
-        requireCompatibleDatabase(database, runtime);
-        runtime.warnIfCodeIndexStale(database);
-        printRows(database.prepare(args_1.codeQuerySql).all());
-    }
-    finally {
-        database.close();
-    }
+        requireCompatibleDatabaseTimed(database, runtime, phaseTimings);
+        checkedCodeIndexStaleness(database, runtime, phaseTimings);
+        const rows = measurePhase(phaseTimings, "query_ms", () => database.prepare(args_1.codeQuerySql).all());
+        measurePhase(phaseTimings, "render_ms", () => printRows(rows));
+    }, {
+        beforeOpen() {
+            if (!(0, code_index_sql_1.isReadOnlySql)(args_1.codeQuerySql)) {
+                console.error("code queries must be read-only SQL starting with SELECT or WITH");
+                process.exit(1);
+            }
+        },
+    });
 }
 function runCodeReportMode(runtime) {
-    runtime.requireExistingIndex();
-    const database = runtime.openDatabase(runtime.codeEvidenceDatabasePath().absolutePath);
-    try {
-        requireCompatibleDatabase(database, runtime);
-        const staleness = runtime.codeIndexStaleness(database);
-        runtime.warnIfCodeIndexStale(database, staleness);
-        const report = runtime.codeReportForRequestedSection(database, args_1.codeReportSection, { staleness });
+    runWithCodeEvidenceDatabase(runtime, (database, phaseTimings) => {
+        requireCompatibleDatabaseTimed(database, runtime, phaseTimings);
+        const staleness = checkedCodeIndexStaleness(database, runtime, phaseTimings);
+        const report = measurePhase(phaseTimings, "query_ms", () => runtime.codeReportForRequestedSection(database, args_1.codeReportSection, { staleness }));
         if (!report)
             runtime.fail((0, reports_1.invalidCodeReportSectionMessage)(args_1.codeReportSection));
-        printJson(report);
-    }
-    finally {
-        database.close();
-    }
+        measurePhase(phaseTimings, "render_ms", () => printJson(report));
+    });
 }
 function runCodeStatusMode(runtime) {
-    runtime.requireExistingIndex();
-    const database = runtime.openDatabase(runtime.codeEvidenceDatabasePath().absolutePath);
-    try {
-        requireCompatibleDatabase(database, runtime);
-        const rows = database.prepare(`
+    runWithCodeEvidenceDatabase(runtime, (database, phaseTimings) => {
+        requireCompatibleDatabaseTimed(database, runtime, phaseTimings);
+        const rows = measurePhase(phaseTimings, "query_ms", () => database.prepare(`
       SELECT 'files' AS metric, count(*) AS value FROM files
       UNION ALL SELECT 'symbols', count(*) FROM symbols
       UNION ALL SELECT 'imports', count(*) FROM imports
       UNION ALL SELECT 'routes', count(*) FROM routes
       UNION ALL SELECT 'edges', count(*) FROM edges
       UNION ALL SELECT 'configs', count(*) FROM configs
-    `).all();
-        const staleness = runtime.codeIndexStaleness(database);
+    `).all());
+        const staleness = measurePhase(phaseTimings, "staleness_ms", () => runtime.codeIndexStaleness(database));
         rows.push({ metric: "stale_files", value: staleness.added + staleness.changed + staleness.deleted }, { metric: "stale_changed_files", value: staleness.changed }, { metric: "stale_added_files", value: staleness.added }, { metric: "stale_deleted_files", value: staleness.deleted });
-        printRows(rows);
-    }
-    finally {
-        database.close();
-    }
+        measurePhase(phaseTimings, "render_ms", () => printRows(rows));
+    });
 }
 function runCodeIndexHealthMode(runtime) {
     printJson(runtime.codeIndexHealth());
 }
 function runCodeFilesMode(runtime) {
-    runtime.requireExistingIndex();
-    const database = runtime.openDatabase(runtime.codeEvidenceDatabasePath().absolutePath);
-    try {
-        requireCompatibleDatabase(database, runtime);
-        runtime.warnIfCodeIndexStale(database);
-        printRows(database.prepare("SELECT path, language, profile, kind, lines, bytes FROM files ORDER BY path").all());
-    }
-    finally {
-        database.close();
-    }
+    runWithCodeEvidenceDatabase(runtime, (database, phaseTimings) => {
+        requireCompatibleDatabaseTimed(database, runtime, phaseTimings);
+        checkedCodeIndexStaleness(database, runtime, phaseTimings);
+        const rows = measurePhase(phaseTimings, "query_ms", () => database.prepare("SELECT path, language, profile, kind, lines, bytes FROM files ORDER BY path").all());
+        measurePhase(phaseTimings, "render_ms", () => printRows(rows));
+    });
 }
 function runCodeImpactMode(runtime) {
     if (!args_1.codeImpactTarget.trim()) {
         console.error("missing impact target: use --code-impact \"path-or-symbol-or-module\"");
         process.exit(1);
     }
-    runtime.requireExistingIndex();
-    const database = runtime.openDatabase(runtime.codeEvidenceDatabasePath().absolutePath);
-    try {
-        requireCompatibleDatabase(database, runtime);
-        const staleness = runtime.codeIndexStaleness(database);
-        runtime.warnIfCodeIndexStale(database, staleness);
-        printJson(runtime.codeImpact(database, args_1.codeImpactTarget.trim(), { staleness }));
-    }
-    finally {
-        database.close();
-    }
+    runWithCodeEvidenceDatabase(runtime, (database, phaseTimings) => {
+        requireCompatibleDatabaseTimed(database, runtime, phaseTimings);
+        const staleness = checkedCodeIndexStaleness(database, runtime, phaseTimings);
+        const impact = measurePhase(phaseTimings, "query_ms", () => runtime.codeImpact(database, args_1.codeImpactTarget.trim(), { staleness }));
+        measurePhase(phaseTimings, "render_ms", () => printJson(impact));
+    });
 }
 function runCodeContextPackMode(runtime) {
     if (!args_1.codeContextPackTarget.trim()) {
         console.error("missing context pack query: use --code-context-pack \"path-or-symbol-or-route\"");
         process.exit(1);
     }
-    runtime.requireExistingIndex();
-    const database = runtime.openDatabase(runtime.codeEvidenceDatabasePath().absolutePath);
-    try {
-        requireCompatibleDatabase(database, runtime);
-        const staleness = runtime.codeIndexStaleness(database);
-        runtime.warnIfCodeIndexStale(database, staleness);
-        console.log(runtime.codeContextPack(database, args_1.codeContextPackTarget.trim(), { staleness }));
-    }
-    finally {
-        database.close();
-    }
+    runWithCodeEvidenceDatabase(runtime, (database, phaseTimings) => {
+        requireCompatibleDatabaseTimed(database, runtime, phaseTimings);
+        const staleness = checkedCodeIndexStaleness(database, runtime, phaseTimings);
+        const pack = measurePhase(phaseTimings, "query_ms", () => runtime.codeContextPack(database, args_1.codeContextPackTarget.trim(), { staleness }));
+        measurePhase(phaseTimings, "render_ms", () => console.log(pack));
+    });
 }
 function runCodeSearchSymbolMode(runtime) {
     if (!args_1.codeSearchSymbol.trim()) {
         console.error("missing symbol search term: use --code-search-symbol \"term\"");
         process.exit(1);
     }
-    runtime.requireExistingIndex();
-    const database = runtime.openDatabase(runtime.codeEvidenceDatabasePath().absolutePath);
-    try {
-        requireCompatibleDatabase(database, runtime);
-        runtime.warnIfCodeIndexStale(database);
-        printRows((0, search_1.searchSymbols)(database, args_1.codeSearchSymbol.trim()));
-    }
-    finally {
-        database.close();
-    }
+    runWithCodeEvidenceDatabase(runtime, (database, phaseTimings) => {
+        requireCompatibleDatabaseTimed(database, runtime, phaseTimings);
+        checkedCodeIndexStaleness(database, runtime, phaseTimings);
+        const rows = measurePhase(phaseTimings, "query_ms", () => (0, search_1.searchSymbols)(database, args_1.codeSearchSymbol.trim()));
+        measurePhase(phaseTimings, "render_ms", () => printRows(rows));
+    });
 }
 function isCodeEvidenceModeFor(flags) {
     return Boolean(flags.codeContextPackTarget)

package/dist/code-index/ownership.js

@@ -65,15 +65,126 @@ function readJsonObject(relativePath) {
 function workspacePatternsFromRootPackage() {
     const rootPackage = readJsonObject("package.json");
     const workspaces = rootPackage?.workspaces;
-    if (Array.isArray(workspaces))
-        return workspaces.filter((value) => typeof value === "string");
+    if (Array.isArray(workspaces)) {
+        return workspaces
+            .filter((value) => typeof value === "string")
+            .map((pattern) => ({ pattern, source: "package.json workspaces" }));
+    }
     if (workspaces && typeof workspaces === "object" && !Array.isArray(workspaces)) {
         const packages = workspaces.packages;
-        if (Array.isArray(packages))
-            return packages.filter((value) => typeof value === "string");
+        if (Array.isArray(packages)) {
+            return packages
+                .filter((value) => typeof value === "string")
+                .map((pattern) => ({ pattern, source: "package.json workspaces" }));
+        }
     }
     return [];
 }
+function trimYamlComment(value) {
+    let quote = "";
+    for (let index = 0; index < value.length; index += 1) {
+        const character = value[index] ?? "";
+        if (quote) {
+            if (character === quote)
+                quote = "";
+            continue;
+        }
+        if (character === "\"" || character === "'") {
+            quote = character;
+            continue;
+        }
+        if (character === "#" && (index === 0 || /\s/.test(value[index - 1] ?? "")))
+            return value.slice(0, index).trimEnd();
+    }
+    return value.trimEnd();
+}
+function parseYamlStringScalar(value) {
+    const trimmed = trimYamlComment(value).trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.startsWith("\"")) {
+        const match = trimmed.match(/^"((?:\\.|[^"\\])*)"/);
+        if (!match)
+            return null;
+        return match[1]?.replace(/\\"/g, "\"") ?? "";
+    }
+    if (trimmed.startsWith("'")) {
+        const match = trimmed.match(/^'((?:''|[^'])*)'/);
+        if (!match)
+            return null;
+        return match[1]?.replace(/''/g, "'") ?? "";
+    }
+    return trimmed;
+}
+function splitYamlFlowArray(value) {
+    const trimmed = trimYamlComment(value).trim();
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]"))
+        return null;
+    const entries = [];
+    let quote = "";
+    let current = "";
+    for (const character of trimmed.slice(1, -1)) {
+        if (quote) {
+            current += character;
+            if (character === quote)
+                quote = "";
+            continue;
+        }
+        if (character === "\"" || character === "'") {
+            quote = character;
+            current += character;
+            continue;
+        }
+        if (character === ",") {
+            entries.push(current);
+            current = "";
+            continue;
+        }
+        current += character;
+    }
+    entries.push(current);
+    return entries;
+}
+function workspacePatternsFromPnpmWorkspace() {
+    const filePath = "pnpm-workspace.yaml";
+    if (!(0, workspace_1.containedProjectFileStat)(filePath))
+        return [];
+    const lines = (0, workspace_1.read)(filePath).split(/\r?\n/);
+    const patterns = [];
+    let packagesIndent = null;
+    for (const line of lines) {
+        if (!line.trim() || line.trimStart().startsWith("#"))
+            continue;
+        const indent = line.match(/^\s*/)?.[0].length ?? 0;
+        const packagesMatch = line.match(/^(\s*)packages\s*:\s*(.*)$/);
+        if (packagesMatch) {
+            packagesIndent = packagesMatch[1]?.length ?? 0;
+            const inlineArray = splitYamlFlowArray(packagesMatch[2] ?? "");
+            if (inlineArray) {
+                for (const entry of inlineArray) {
+                    const pattern = parseYamlStringScalar(entry);
+                    if (pattern && !pattern.startsWith("!"))
+                        patterns.push({ pattern, source: "pnpm-workspace.yaml packages" });
+                }
+            }
+            continue;
+        }
+        if (packagesIndent === null)
+            continue;
+        if (indent <= packagesIndent)
+            break;
+        const item = line.slice(indent).match(/^-\s+(.+)$/);
+        if (!item)
+            continue;
+        const pattern = parseYamlStringScalar(item[1] ?? "");
+        if (pattern && !pattern.startsWith("!"))
+            patterns.push({ pattern, source: "pnpm-workspace.yaml packages" });
+    }
+    return patterns;
+}
+function workspacePatterns() {
+    return [...workspacePatternsFromRootPackage(), ...workspacePatternsFromPnpmWorkspace()];
+}
 function workspacePatternCandidates(pattern) {
     const normalized = (0, workspace_1.normalizePath)(pattern).replace(/^\/+/, "").replace(/\/+$/, "");
     if (!normalized || normalized.includes(".."))
@@ -94,8 +205,8 @@ function workspacePatternCandidates(pattern) {
 }
 function workspacePackages() {
     const packages = new Map();
-    for (const pattern of workspacePatternsFromRootPackage()) {
-        for (const candidate of workspacePatternCandidates(pattern)) {
+    for (const workspacePattern of workspacePatterns()) {
+        for (const candidate of workspacePatternCandidates(workspacePattern.pattern)) {
             const packageJsonPath = (0, workspace_1.normalizePath)(path.join(candidate, "package.json"));
             if (!(0, workspace_1.containedProjectFileStat)(packageJsonPath))
                 continue;
@@ -104,8 +215,8 @@ function workspacePackages() {
             packages.set(candidate, {
                 name: packageName,
                 root: candidate,
-                source: "package.json workspaces",
-                workspace_pattern: pattern,
+                source: workspacePattern.source,
+                workspace_pattern: workspacePattern.pattern,
             });
         }
     }

package/dist/code-index/schema.js

@@ -47,7 +47,7 @@ exports.incrementalCompatibility = incrementalCompatibility;
 exports.codeIndexSnapshot = codeIndexSnapshot;
 const crypto = __importStar(require("node:crypto"));
 const workspace_1 = require("../workspace");
-exports.codeIndexSchemaVersion = "5";
+exports.codeIndexSchemaVersion = "6";
 function stableFtsRowid(parts) {
     const hash = crypto.createHash("sha256");
     for (const part of parts) {
@@ -158,7 +158,7 @@ function createIndexStatements(database) {
         insertMeta: database.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)"),
         insertRoute: database.prepare("INSERT INTO routes (method, route, file_path, line, handler) VALUES (?, ?, ?, ?, ?)"),
         insertSymbol: database.prepare("INSERT INTO symbols (name, kind, file_path, line, signature) VALUES (?, ?, ?, ?, ?)"),
-        insertSymbolFts: database.prepare("INSERT INTO symbols_fts (name, kind, file_path, signature) VALUES (?, ?, ?, ?)"),
+        insertSymbolFts: database.prepare("INSERT INTO symbols_fts (rowid, name, kind, file_path, signature) VALUES (last_insert_rowid(), ?, ?, ?, ?)"),
     };
 }
 function removeIndexedFile(filePath, statements) {

package/dist/code-index/search.js

@@ -130,11 +130,7 @@ function searchSymbols(database, term, limit = 50) {
         const ftsRows = database.prepare(`
       SELECT symbols.name, symbols.kind, symbols.file_path, symbols.line, symbols.signature
       FROM symbols_fts
-      JOIN symbols
-        ON symbols.name = symbols_fts.name
-       AND symbols.kind = symbols_fts.kind
-       AND symbols.file_path = symbols_fts.file_path
-       AND symbols.signature = symbols_fts.signature
+      JOIN symbols ON symbols.id = symbols_fts.rowid
       WHERE symbols_fts MATCH ?
       ORDER BY bm25(symbols_fts, 8.0, 1.0, 4.0, 2.0), symbols.file_path, symbols.line
       LIMIT ?

package/dist/code-index.js

@@ -648,16 +648,22 @@ function codeContextScaleLine(fileCount) {
         ? `scale small (${fileCount} indexed files < ${code_index_file_policy_1.SMALL_REPO_FILE_THRESHOLD}); direct reads are usually cheaper for simple lookups`
         : `scale large (${fileCount} indexed files >= ${code_index_file_policy_1.SMALL_REPO_FILE_THRESHOLD}); indexed traversal is useful for impact-style context`;
 }
-function structuralSignature(value) {
-    const signature = (0, shared_1.oneLine)(String(value ?? ""));
-    const bodyStart = signature.indexOf("{");
-    return bodyStart >= 0 ? signature.slice(0, bodyStart).trimEnd() : signature;
-}
-function codeContextPack(database, query, options = {}) {
-    const normalized = query.trim();
-    if (!normalized)
-        return 'Code context pack: missing query; use --code-context-pack "path-or-symbol-or-route".';
-    const evidence = (0, evidence_1.collectCodeEvidence)(database, normalized, {
+function codeContextCollectorOptions(fileCount) {
+    if (fileCount < code_index_file_policy_1.SMALL_REPO_FILE_THRESHOLD) {
+        return {
+            edgeLimit: 8,
+            fileLimit: 8,
+            includeEdgeEvidenceMatches: false,
+            includeOwnerCodeowners: false,
+            includeRouteEdges: false,
+            importLimit: 12,
+            ownerSampleLimit: 3,
+            routeEdgeLimit: 0,
+            routeLimit: 8,
+            symbolLimit: 12,
+        };
+    }
+    return {
         edgeLimit: 30,
         fileLimit: 12,
         includeEdgeEvidenceMatches: true,
@@ -668,14 +674,26 @@ function codeContextPack(database, query, options = {}) {
         routeEdgeLimit: 0,
         routeLimit: 20,
         symbolLimit: 20,
-    });
-    const staleness = options.staleness ?? codeIndexStaleness(database);
+    };
+}
+function structuralSignature(value) {
+    const signature = (0, shared_1.oneLine)(String(value ?? ""));
+    const bodyStart = signature.indexOf("{");
+    return bodyStart >= 0 ? signature.slice(0, bodyStart).trimEnd() : signature;
+}
+function codeContextPack(database, query, options = {}) {
+    const normalized = query.trim();
+    if (!normalized)
+        return 'Code context pack: missing query; use --code-context-pack "path-or-symbol-or-route".';
     const coverage = (0, reports_1.evidenceCoverage)(database);
+    const indexedFileCount = Number(coverage.files ?? 0);
+    const evidence = (0, evidence_1.collectCodeEvidence)(database, normalized, codeContextCollectorOptions(indexedFileCount));
+    const staleness = options.staleness ?? codeIndexStaleness(database);
     const staleLabel = staleness.stale
         ? `STALE ${staleness.changed} changed, ${staleness.added} added, ${staleness.deleted} deleted`
         : "fresh";
     const lines = [
-        `Code context pack "${normalized}": ${evidence.files.length} file matches, ${evidence.symbols.length} symbols, ${evidence.routes.length} routes, ${evidence.imports.length} imports, ${evidence.incomingEdges.length} incoming / ${evidence.outgoingEdges.length} outgoing edges; index ${staleLabel}; ${codeContextScaleLine(Number(coverage.files ?? 0))}.`,
+        `Code context pack "${normalized}": ${evidence.files.length} file matches, ${evidence.symbols.length} symbols, ${evidence.routes.length} routes, ${evidence.imports.length} imports, ${evidence.incomingEdges.length} incoming / ${evidence.outgoingEdges.length} outgoing edges; index ${staleLabel}; ${codeContextScaleLine(indexedFileCount)}.`,
         "Evidence is structural only: paths, lines, signatures, routes, imports, edges, and owners; no source snippets are included.",
     ];
     pushBudgetedSection(lines, "Files:", evidence.files, 8, (row) => `  file-match ${String(row.path)} (${String(row.language)}, ${String(row.profile)}, ${Number(row.lines ?? 0)} lines)`);

package/dist/init-project-wiki.js

@@ -62,6 +62,7 @@ Options:
   --acknowledge-small-repo         With --code-index, proceed below the small-repo scale gate after its cost warning.
   --incremental                    With --code-index, require an existing compatible index and update only changes.
   --code-index-full                With --code-index, force a full rebuild even when incremental update is possible.
+  --code-index-migrate             With --code-index, approve replacing an incompatible schema-version index.
   --code-index-engine <engine>     With --code-index, override default auto engine: typescript or native-rust.
   --code-parser <mode>             With --code-index, use parser mode default or tree-sitter.
   --code-query <sql>               Run conservative read-only SQL over the code evidence index.
@@ -166,6 +167,10 @@ if (args_1.codeIndexFullMode && !args_1.codeIndexMode) {
     console.error("--code-index-full is only supported with --code-index.");
     process.exit(1);
 }
+if (args_1.codeIndexMigrateMode && !args_1.codeIndexMode) {
+    console.error("--code-index-migrate is only supported with --code-index.");
+    process.exit(1);
+}
 if (args_1.codeIndexEngineMode && !args_1.codeIndexMode) {
     console.error("--code-index-engine is only supported with --code-index.");
     process.exit(1);
@@ -178,6 +183,10 @@ 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.codeIndexIncrementalMode && args_1.codeIndexMigrateMode) {
+    console.error("Use one code index update mode at a time: --incremental or --code-index-migrate.");
+    process.exit(1);
+}
 const activeHandoffModes = [
     args_1.handoffSaveMode ? "--handoff-save" : "",
     args_1.handoffShowMode ? "--handoff-show" : "",

package/dist/install-skill.js

@@ -52,6 +52,7 @@ const packageFiles = [
     "package.json",
     "agents",
 ];
+const runtimeDependencyPackages = ["typescript"];
 function fail(message) {
     console.error(message);
     process.exit(1);
@@ -83,6 +84,18 @@ function installAgents() {
 function packageRoot() {
     return path.resolve(__dirname, "..");
 }
+function runtimeDependencySource(packageName) {
+    try {
+        return path.dirname(require.resolve(`${packageName}/package.json`, { paths: [packageRoot()] }));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return fail(`missing runtime dependency ${packageName}: run npm install before installing the Project Librarian skill. Error: ${message}`);
+    }
+}
+function runtimeDependencyTarget(packageName) {
+    return path.join("node_modules", ...packageName.split("/"));
+}
 function userAgentRoot(agent) {
     const home = os.homedir();
     if (agent === "codex")
@@ -236,11 +249,18 @@ function installedProjectSkillSurfaces() {
 }
 function copyPackageFiles(targetRoot, dryRun, labelRoot = targetRoot) {
     const root = packageRoot();
-    return packageFiles.map((relativePath) => {
+    const packageRows = packageFiles.map((relativePath) => {
         const source = path.join(root, relativePath);
         const target = path.join(targetRoot, relativePath);
         return [path.join(labelRoot, relativePath), copyPath(source, target, targetRoot, dryRun)];
     });
+    const dependencyRows = runtimeDependencyPackages.map((packageName) => {
+        const relativePath = runtimeDependencyTarget(packageName);
+        const source = runtimeDependencySource(packageName);
+        const target = path.join(targetRoot, relativePath);
+        return [path.join(labelRoot, relativePath), copyPath(source, target, targetRoot, dryRun)];
+    });
+    return [...packageRows, ...dependencyRows];
 }
 function syncProjectSkillInstall(agent) {
     return copyPackageFiles(projectSkillTarget(agent), false, projectSkillRelativeRoot(agent)).map(([label, status]) => {
@@ -261,7 +281,7 @@ function runInstallSkillMode() {
     console.log(`Project Librarian skill ${dryRun ? "install dry-run" : "install"} complete.`);
     console.log(`scope: ${scope}`);
     console.log(`agents: ${agents.join(", ")}`);
-    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("note: install only installs the reusable skill files and required local-runner runtime dependencies; 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) {

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

@@ -5,7 +5,7 @@
       "architecture": "arm64",
       "format": "mach-o",
       "path": "dist/native/darwin-arm64/project-librarian-indexer",
-      "sha256": "f5c69130f6c0441044141c761f1ccdc7e6ee4d06e327ce0f50d43a7aed76cc95",
+      "sha256": "848c29daf166e55672add5febf22fcd2ba261619a37969d9bc87cff06815787c",
       "size": 2697520,
       "triple": "darwin-arm64"
     },
@@ -13,7 +13,7 @@
       "architecture": "x64",
       "format": "mach-o",
       "path": "dist/native/darwin-x64/project-librarian-indexer",
-      "sha256": "25041398ba2de3ed749c14103d358ed4a7934a05459eb63c6cf5f6ae58c7fb03",
+      "sha256": "b419d82b7560defe1d43fc4d99d96b10222f1ead5bf6d7a6acabbae425ee7545",
       "size": 2770592,
       "triple": "darwin-x64"
     },
@@ -21,7 +21,7 @@
       "architecture": "arm64",
       "format": "elf",
       "path": "dist/native/linux-arm64/project-librarian-indexer",
-      "sha256": "01bf4437fd62446958438ac58e9ca8bef811bdc6d70a63fc1a0ca1b627521e67",
+      "sha256": "f3cc884acca4f5863fb6a6545a4a9f9a37a67872bfe780f4b14f0c4a8a667f16",
       "size": 3065520,
       "triple": "linux-arm64"
     },
@@ -29,31 +29,31 @@
       "architecture": "arm64",
       "format": "elf",
       "path": "dist/native/linux-arm64-musl/project-librarian-indexer",
-      "sha256": "b7287995bea678a6f55bd03761e5b0985d483e875d7594395b81bdb1e90a8dd9",
-      "size": 3100840,
+      "sha256": "80f7440c4d115d05805b63b8118a172ddeb5a374b7154593e5b1d0b804a938ae",
+      "size": 3100816,
       "triple": "linux-arm64-musl"
     },
     {
       "architecture": "x64",
       "format": "elf",
       "path": "dist/native/linux-x64/project-librarian-indexer",
-      "sha256": "5d93bb7576afbdde0acbde7983a874f2666f0d59227524c1eb42cc75b457c5ed",
-      "size": 3110696,
+      "sha256": "3d93408db344567d7de6f477b58fdaf6aba19c943336fb7ab9720e3e9fa68c31",
+      "size": 3110832,
       "triple": "linux-x64"
     },
     {
       "architecture": "x64",
       "format": "elf",
       "path": "dist/native/linux-x64-musl/project-librarian-indexer",
-      "sha256": "518aea0fc53ed7731751db4bb436a0be98f8583659d51aeff769bedb7a7cb8ab",
-      "size": 3247384,
+      "sha256": "0055ec9fefa385d6d637fa1e457308c38f892e0fbdb389db3fcbdf546f0daca8",
+      "size": 3247400,
       "triple": "linux-x64-musl"
     },
     {
       "architecture": "arm64",
       "format": "pe",
       "path": "dist/native/win32-arm64/project-librarian-indexer.exe",
-      "sha256": "392157f4d3591c48a66ee674b99a8a34cda3d38cc76df6343276becb23a7055c",
+      "sha256": "8c357be6b1e0c3c13337abccdc0edefc628267b272c8aca30be50c679bffb4af",
       "size": 2098688,
       "triple": "win32-arm64"
     },
@@ -61,7 +61,7 @@
       "architecture": "x64",
       "format": "pe",
       "path": "dist/native/win32-x64/project-librarian-indexer.exe",
-      "sha256": "fabe69234daa9a6a738d0b7160c84573853d7a9e3be14c19ec6a27ca171e3f8a",
+      "sha256": "f4f9f6424fef446ece0684760afd8a404135acc007794c3e0f3effccdc8b4801",
       "size": 2375680,
       "triple": "win32-x64"
     }

package/dist/templates.js

@@ -199,7 +199,7 @@ exports.startup = `${(0, exports.metadata)("startup-router", "short", "wiki/meta
 - This project is in an initial planning state unless the canonical wiki says otherwise.
 - 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.
+- At session start, read only this file and \`wiki/index.md\` first; use the index as a route table, open matching detail files directly, and avoid broad repo/wiki search unless no route matches.
 - 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.
@@ -232,7 +232,7 @@ exports.startup = `${(0, exports.metadata)("startup-router", "short", "wiki/meta
 ## Token Discipline
 
 - Codex, Claude Code, Cursor, and Gemini CLI session-start hooks inject only this file and \`wiki/index.md\`.
-- Detailed files are selected by the "read when" rules in \`wiki/index.md\`.
+- Detailed files are selected by \`wiki/index.md\`; use broad wiki search only when no route matches or evidence conflicts.
 - Long decision history is not injected wholesale; read only relevant Decision Packs or ADRs.
 `;
 exports.index = `${(0, exports.metadata)("wiki-router", "short", "wiki/meta/wiki-ops-v1-decisions.md", "wiki page added, moved, removed, or routing changes")}
@@ -240,7 +240,7 @@ exports.index = `${(0, exports.metadata)("wiki-router", "short", "wiki/meta/wiki
 
 ## How To Use This Index
 
-This file is a router, not a file to expand into every answer. Read only the files that are relevant to the current question.
+This is a route table, not a page inventory. Open the matching route first; use broad wiki search or file listing only when no route matches or evidence conflicts.
 
 ## Language Policy
 

package/docs/cli-reference.md

@@ -9,13 +9,13 @@ 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 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.
 
 ### Important Options
 
 | Option | Purpose |
 | --- | --- |
-| `install --scope user|project --agents <list> --dry-run` | Install reusable skill files globally or into the current repository; `--dry-run` previews copied files for install only. |
+| `install --scope user|project --agents <list> --dry-run` | Install reusable skill files and required local-runner runtime dependencies globally or into the current repository; `--dry-run` previews copied files for install only. |
 | `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. |
@@ -48,6 +48,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 | `--code-index-out <path>` | Use a custom SQLite output path under `.project-wiki/`; applies to index and read modes. |
 | `--acknowledge-small-repo` | With `--code-index`, proceed below the ~5k-file scale gate after the cost warning. |
 | `--incremental`, `--code-index-incremental`, `--code-index-full` | With `--code-index`, require an incremental update or force a full rebuild. |
+| `--code-index-migrate` | With `--code-index`, explicitly approve replacing an existing index whose schema version differs from the current package. |
 | `--code-parser <mode>` | With `--code-index`, select `default` or optional `tree-sitter` extraction. |
 | `--code-index-health` | Inspect code evidence cache compatibility and print rebuild guidance without writing. |
 | `--code-index-engine <engine>` | Override the default `auto` index engine with `typescript` or `native-rust`. |

package/docs/code-evidence.md

@@ -78,6 +78,12 @@ The matrix lists languages with implemented symbol/import extraction. Other reco
 
 Recognized but inventory-only extensions include `.rb`, `.vue`, and `.css`. Config files (`.json`, `.yaml`, `.yml`, `.toml`, `.env.example`, `package.json`, `tsconfig.json`, `Dockerfile`, and `Makefile`) are indexed as configuration or inventory evidence.
 
+## Schema Migration
+
+The code evidence index is disposable, but Project Librarian still treats schema-version changes as an explicit migration boundary. If an existing `.project-wiki/code-evidence.sqlite` has a different schema version, `--code-index` stops before replacing the database and prints a migration-required message with the approval command.
+
+Run `project-librarian --code-index-health` to inspect the current index. To approve replacing an incompatible-schema index, rerun the build with `--code-index --code-index-migrate` plus the same scope/parser options you want for the new index. `--incremental` cannot migrate schema versions.
+
 ## Native Helper Policy
 
 Experimental `--code-index-engine native-rust` runs the native helper for `typescript-ast`, `config`, the listed `*-light` profiles, and inventory-only source files. Omitted `--code-index-engine` means `auto`; full-index auto uses the native helper when a helper is available and at least one structurally extracted native profile is present, while config-only or inventory-only repositories stay on TypeScript. Compatible incremental auto uses the Rust direct-writer when a helper is available and the changed files are native-eligible.

package/docs/ko/cli-reference.md

@@ -9,13 +9,13 @@ 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`는 현재 패키지의 재사용 가능한 스킬 파일과 로컬 실행기에 필요한 필수 런타임 의존성을 해당 프로젝트 스킬 디렉터리에 복사한 뒤 관리 설정을 갱신합니다.
 
 ### 주요 옵션
 
 | 옵션 | 목적 |
 | --- | --- |
-| `install --scope user|project --agents <list> --dry-run` | 재사용 가능한 스킬 파일을 전역 또는 현재 저장소에 설치합니다. `--dry-run`은 install에서 복사될 파일을 미리 보여줍니다. |
+| `install --scope user|project --agents <list> --dry-run` | 재사용 가능한 스킬 파일과 로컬 실행기에 필요한 필수 런타임 의존성을 전역 또는 현재 저장소에 설치합니다. `--dry-run`은 install에서 복사될 파일을 미리 보여줍니다. |
 | `update --agents <list>` | 기존 설정과 기존 프로젝트 범위 스킬 복사본을 갱신합니다. 표면은 `codex`, `claude`, `cursor`, `gemini`, `all` 중 하나입니다. |
 | `--migrate`, `--adopt-existing` | 기존 위키를 `wiki_legacy*`로 보존하고 migration inbox, unit-map, split-plan, coverage 검토 파일을 만듭니다. |
 | `--lint` | 파일을 수정하지 않고 생성된 설정을 검증합니다. |
@@ -48,6 +48,7 @@ node .codex/skills/project-librarian/dist/init-project-wiki.js install [--scope
 | `--code-index-out <path>` | `.project-wiki/` 아래 사용자 지정 SQLite 출력 경로를 사용합니다. index와 read mode에 모두 적용됩니다. |
 | `--acknowledge-small-repo` | `--code-index`와 함께 사용해 약 5k 파일 미만 규모 경고 후에도 진행합니다. |
 | `--incremental`, `--code-index-incremental`, `--code-index-full` | `--code-index`와 함께 사용해 증분 갱신을 요구하거나 전체 재생성을 강제합니다. |
+| `--code-index-migrate` | `--code-index`와 함께 사용해 기존 인덱스의 스키마 버전이 현재 패키지와 다를 때 교체를 명시적으로 승인합니다. |
 | `--code-parser <mode>` | `--code-index`와 함께 사용해 `default` 또는 선택적 `tree-sitter` 추출을 선택합니다. |
 | `--code-index-health` | 파일을 쓰지 않고 코드 근거 캐시 호환성과 재빌드 안내를 출력합니다. |
 | `--code-index-engine <engine>` | 기본 `auto` 인덱스 엔진을 `typescript` 또는 `native-rust`로 override합니다. |

package/docs/ko/code-evidence.md

@@ -78,6 +78,12 @@ codex mcp add project-librarian -- node .codex/skills/project-librarian/dist/ini
 
 `.rb`, `.vue`, `.css`는 인식하지만 inventory-only입니다. `.json`, `.yaml`, `.yml`, `.toml`, `.env.example`, `package.json`, `tsconfig.json`, `Dockerfile`, `Makefile`은 설정 또는 inventory 근거로 인덱싱됩니다.
 
+## 스키마 마이그레이션
+
+코드 근거 인덱스는 폐기 가능한 캐시지만, Project Librarian은 스키마 버전 변경을 명시적 마이그레이션 경계로 취급합니다. 기존 `.project-wiki/code-evidence.sqlite`의 스키마 버전이 현재 패키지와 다르면 `--code-index`는 데이터베이스를 교체하기 전에 멈추고 마이그레이션 필요 메시지와 승인 명령을 출력합니다.
+
+현재 인덱스 상태는 `project-librarian --code-index-health`로 확인합니다. 호환되지 않는 스키마의 인덱스 교체를 승인하려면 새 인덱스에 적용할 scope/parser 옵션과 함께 `--code-index --code-index-migrate`를 다시 실행합니다. `--incremental`은 스키마 버전을 마이그레이션할 수 없습니다.
+
 ## 네이티브 헬퍼 정책
 
 실험적 `--code-index-engine native-rust`는 `typescript-ast`, `config`, 표의 `*-light` 프로파일, inventory-only 소스 파일을 네이티브 헬퍼로 처리합니다. `--code-index-engine`을 생략하면 `auto`입니다. full-index auto는 헬퍼를 사용할 수 있고 구조적으로 추출되는 네이티브 프로파일이 하나 이상 있을 때 네이티브 헬퍼를 사용하며, config-only 또는 inventory-only 저장소는 TypeScript 경로에 남깁니다. 호환되는 incremental auto는 헬퍼를 사용할 수 있고 변경 파일이 native-eligible이면 Rust direct-writer를 사용합니다.

package/docs/ko/usage.md

@@ -16,7 +16,7 @@ npx project-librarian@latest install --scope user --agents all
 npx project-librarian@latest install --scope project --agents all
 ```
 
-`install`은 재사용 가능한 스킬 파일만 복사합니다. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `wiki/`, `.cursor/rules/`, `.cursor/hooks.json`, `.gemini/settings.json`, `.codex/hooks.json`, `.claude/settings.json`은 만들거나 갱신하지 않습니다. `install-skill`은 호환성 별칭으로 계속 지원됩니다.
+`install`은 재사용 가능한 스킬 파일과 로컬 실행기에 필요한 필수 런타임 의존성을 복사합니다. `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `wiki/`, `.cursor/rules/`, `.cursor/hooks.json`, `.gemini/settings.json`, `.codex/hooks.json`, `.claude/settings.json`은 만들거나 갱신하지 않습니다. `install-skill`은 호환성 별칭으로 계속 지원됩니다.
 
 | 상황 | 명령 |
 | --- | --- |
@@ -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 스킬 설치가 있으면 현재 실행 중인 패키지의 재사용 가능한 스킬 파일과 프로젝트 로컬 실행기에 필요한 런타임 의존성을 그 프로젝트 스킬 디렉터리로 동기화합니다. 기본적으로 새 프로젝트 범위 스킬 설치를 만들지는 않고, 사용자 범위 스킬 설치도 갱신하지 않습니다. 사용자 범위 스킬은 `install --scope user`로 명시적으로 갱신합니다.
 
 ## 실행 경로
 
@@ -87,6 +87,7 @@ npx project-librarian@latest install --scope project --agents all
 | 여러 범위 빌드 | "`src`와 `packages/api`에 대해 Project Librarian 코드 근거를 만들어줘." | `--code-index --code-scope src --code-scope packages/api` |
 | 증분 갱신 요구 | "Project Librarian 코드 근거 인덱스를 증분 갱신해줘." | `--code-index --incremental` |
 | 전체 재생성 강제 | "Project Librarian 코드 근거 인덱스를 전체 재생성해줘." | `--code-index --code-index-full` |
+| 스키마 마이그레이션 승인 | "Project Librarian 코드 근거 인덱스 스키마를 마이그레이션해줘." | `--code-index --code-index-migrate` |
 | 선택적 Tree-sitter 백엔드 사용 | "Tree-sitter 파서로 Project Librarian 코드 근거를 만들어줘." | `--code-index --code-parser tree-sitter` |
 | 캐시 호환성 진단 | "Project Librarian 코드 근거 캐시 상태와 호환성을 진단해줘." | `--code-index-health` |
 | 캐시 상태 확인 | "Project Librarian 코드 근거 상태를 보여줘." | `--code-status` |
@@ -98,7 +99,7 @@ npx project-librarian@latest install --scope project --agents all
 | 심볼 검색 | "`Auth` 심볼을 Project Librarian 코드 근거에서 찾아줘." | `--code-search-symbol Auth` |
 | 보수적 읽기 전용 SQL | "파일 경로를 위한 읽기 전용 Project Librarian 코드 근거 쿼리를 실행해줘." | `--code-query "select path from files order by path"` |
 
-한 번에 하나의 코드 근거 모드만 실행할 수 있습니다. `--incremental`, `--code-index-full`, `--code-parser`는 `--code-index`와 함께 사용할 때만 유효합니다.
+한 번에 하나의 코드 근거 모드만 실행할 수 있습니다. `--incremental`, `--code-index-full`, `--code-index-migrate`, `--code-parser`는 `--code-index`와 함께 사용할 때만 유효합니다. `--code-index-migrate`는 기존 폐기형 인덱스의 스키마 버전이 현재 패키지와 다를 때 교체를 승인한다는 명시적 표시입니다.
 
 ## 설치되는 파일
 

package/docs/usage.md

@@ -16,7 +16,7 @@ Install into the current repository instead:
 npx project-librarian@latest install --scope project --agents all
 ```
 
-`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.
+`install` copies reusable skill files and required local-runner runtime dependencies. 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 |
 | --- | --- |
@@ -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. 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. 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
 
@@ -85,6 +85,7 @@ Code evidence:
 | Build multiple scopes | "Build Project Librarian code evidence for `src` and `packages/api`." | `--code-index --code-scope src --code-scope packages/api` |
 | Require incremental update | "Update the Project Librarian code evidence index incrementally." | `--code-index --incremental` |
 | Force a full rebuild | "Fully rebuild the Project Librarian code evidence index." | `--code-index --code-index-full` |
+| Approve a schema migration | "Migrate the Project Librarian code evidence index schema." | `--code-index --code-index-migrate` |
 | Use optional Tree-sitter backend | "Build Project Librarian code evidence with the Tree-sitter parser." | `--code-index --code-parser tree-sitter` |
 | Inspect cache compatibility | "Inspect Project Librarian code evidence cache health." | `--code-index-health` |
 | Show cache status | "Show Project Librarian code evidence status." | `--code-status` |
@@ -96,7 +97,7 @@ Code evidence:
 | Search indexed symbols | "Search Project Librarian code evidence for symbol `Auth`." | `--code-search-symbol Auth` |
 | Run conservative read-only SQL | "Run a read-only Project Librarian code evidence query for file paths." | `--code-query "select path from files order by path"` |
 
-Only one code evidence mode can run at a time. `--incremental`, `--code-index-full`, and `--code-parser` are valid only with `--code-index`.
+Only one code evidence mode can run at a time. `--incremental`, `--code-index-full`, `--code-index-migrate`, and `--code-parser` are valid only with `--code-index`. `--code-index-migrate` is explicit approval to replace an existing disposable index when its schema version differs from the current package.
 
 ## What Gets Installed
 

package/package.json

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