project-librarian 0.5.6 → 0.5.7

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`은 호환성 별칭으로 계속 지원됩니다.
 
 ## 업데이트
 

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
 

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;
 }
@@ -125,6 +168,33 @@ 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 {
@@ -140,23 +210,9 @@ function runCodeIndexMode(runtime) {
             }
         }
     }
-    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}`);
     }

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

@@ -53,7 +53,7 @@
       "architecture": "arm64",
       "format": "pe",
       "path": "dist/native/win32-arm64/project-librarian-indexer.exe",
-      "sha256": "392157f4d3591c48a66ee674b99a8a34cda3d38cc76df6343276becb23a7055c",
+      "sha256": "e8e5200660a8852d1b7554daf0d16361e29e5599baa5cd406eb3f2266abd98f6",
       "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": "dc076bd61271f23ab87b428c7cbfa3af45911c00f7bf7986a2ed9d517e1cfb6f",
       "size": 2375680,
       "triple": "win32-x64"
     }

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.7",
   "description": "Create and maintain compact project context for humans and LLM coding agents.",
   "license": "MIT",
   "type": "commonjs",