project-librarian 0.2.0 → 0.3.0

package/dist/args.js

@@ -1,12 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-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.queryTerm = exports.codeSearchSymbolMode = exports.codeQueryMode = exports.codeImpactMode = exports.codeParserMode = exports.codeFilesMode = exports.codeStatusMode = exports.codeReportMode = exports.codeIndexFullMode = exports.codeIndexIncrementalMode = exports.codeIndexMode = exports.noGitConfigMode = exports.reviewMigrationMode = exports.pruneCheckMode = exports.captureInboxMode = exports.refreshIndexMode = exports.issueDraftMode = exports.issueCreateMode = exports.glossaryMode = exports.fixMode = exports.doctorMode = exports.qualityCheckMode = exports.linkCheckMode = exports.lintMode = exports.migrateMode = exports.missingValueOptions = exports.unexpectedValueOptions = exports.unknownOptions = exports.args = exports.commandArgs = exports.command = exports.unknownCommand = exports.helpMode = exports.parsedArgs = exports.rawArgs = void 0;
+exports.captureContent = exports.captureTitle = exports.codeIndexScopes = exports.codeParser = exports.codeIndexOutput = exports.codeSearchSymbol = exports.codeReportSection = exports.codeQuerySql = exports.codeImpactTarget = exports.wikiImpactTarget = exports.wikiImpactMode = exports.queryTerm = exports.codeSearchSymbolMode = exports.codeQueryMode = exports.codeImpactMode = exports.codeParserMode = exports.codeFilesMode = exports.codeStatusMode = exports.codeReportMode = exports.codeIndexFullMode = exports.codeIndexIncrementalMode = exports.codeIndexMode = exports.acknowledgeSmallRepoMode = exports.noGitConfigMode = exports.reviewMigrationMode = exports.pruneCheckMode = exports.captureInboxMode = exports.refreshIndexMode = exports.issueDraftMode = exports.issueCreateMode = exports.glossaryMode = exports.fixMode = exports.doctorMode = exports.qualityCheckMode = exports.linkCheckMode = exports.migrationQualityCheckMode = exports.migrationLintMode = exports.migrationDoctorMode = exports.lintMode = exports.migrateMode = exports.missingValueOptions = exports.unexpectedValueOptions = exports.unknownOptions = exports.args = exports.commandArgs = exports.command = exports.unknownCommand = exports.helpMode = exports.parsedArgs = exports.rawArgs = void 0;
+exports.issueDraftTitle = exports.issueBodyFile = exports.captureCategory = void 0;
 exports.parseArgs = parseArgs;
 exports.argValue = argValue;
 exports.argValues = argValues;
 exports.rawArgs = process.argv.slice(2);
-const knownCommands = new Set(["init", "install-skill"]);
+const knownCommands = new Set(["init", "install-skill", "mcp"]);
 const flagsWithoutValues = new Set([
+    "--acknowledge-small-repo",
     "--adopt-existing",
     "--capture-inbox",
     "--code-evidence-files",
@@ -32,6 +34,9 @@ const flagsWithoutValues = new Set([
     "--link-check",
     "--lint",
     "--migrate",
+    "--migration-doctor",
+    "--migration-lint",
+    "--migration-quality-check",
     "--no-git-config",
     "--prune-check",
     "--quality-check",
@@ -62,6 +67,7 @@ const flagsWithValues = new Set([
     "--query",
     "--scope",
     "--title",
+    "--wiki-impact",
 ]);
 const knownFlags = new Set([...flagsWithoutValues, ...flagsWithValues, "--help", "-h"]);
 function flagName(arg) {
@@ -127,6 +133,7 @@ function parseArgs(argv) {
     const codeQuerySql = argValue("--code-query") || argValue("--code-evidence-query");
     const codeSearchSymbol = argValue("--code-search-symbol") || argValue("--code-evidence-symbol");
     return {
+        acknowledgeSmallRepoMode: args.has("--acknowledge-small-repo"),
         args,
         captureCategory: argValue("--category") || "project-candidate",
         captureContent: argValue("--content"),
@@ -161,6 +168,9 @@ function parseArgs(argv) {
         issueDraftTitle: argValue("--issue-title"),
         linkCheckMode: args.has("--link-check"),
         lintMode: args.has("--lint"),
+        migrationDoctorMode: args.has("--migration-doctor"),
+        migrationLintMode: args.has("--migration-lint"),
+        migrationQualityCheckMode: args.has("--migration-quality-check"),
         migrateMode: args.has("--migrate") || args.has("--adopt-existing"),
         missingValueOptions: Array.from(flagsWithValues).filter((flag) => hasFlag(flag) && !flagHasValue(commandArgs, flag)),
         noGitConfigMode: args.has("--no-git-config"),
@@ -179,6 +189,8 @@ function parseArgs(argv) {
             .filter((arg) => arg.startsWith("-"))
             .map(flagName)
             .filter((arg) => !knownFlags.has(arg)))),
+        wikiImpactMode: hasFlag("--wiki-impact"),
+        wikiImpactTarget: argValue("--wiki-impact"),
     };
 }
 exports.parsedArgs = parseArgs(exports.rawArgs);
@@ -192,6 +204,9 @@ exports.unexpectedValueOptions = exports.parsedArgs.unexpectedValueOptions;
 exports.missingValueOptions = exports.parsedArgs.missingValueOptions;
 exports.migrateMode = exports.parsedArgs.migrateMode;
 exports.lintMode = exports.parsedArgs.lintMode;
+exports.migrationDoctorMode = exports.parsedArgs.migrationDoctorMode;
+exports.migrationLintMode = exports.parsedArgs.migrationLintMode;
+exports.migrationQualityCheckMode = exports.parsedArgs.migrationQualityCheckMode;
 exports.linkCheckMode = exports.parsedArgs.linkCheckMode;
 exports.qualityCheckMode = exports.parsedArgs.qualityCheckMode;
 exports.doctorMode = exports.parsedArgs.doctorMode;
@@ -204,6 +219,7 @@ exports.captureInboxMode = exports.parsedArgs.captureInboxMode;
 exports.pruneCheckMode = exports.parsedArgs.pruneCheckMode;
 exports.reviewMigrationMode = exports.parsedArgs.reviewMigrationMode;
 exports.noGitConfigMode = exports.parsedArgs.noGitConfigMode;
+exports.acknowledgeSmallRepoMode = exports.parsedArgs.acknowledgeSmallRepoMode;
 exports.codeIndexMode = exports.parsedArgs.codeIndexMode;
 exports.codeIndexIncrementalMode = exports.parsedArgs.codeIndexIncrementalMode;
 exports.codeIndexFullMode = exports.parsedArgs.codeIndexFullMode;
@@ -221,6 +237,8 @@ function argValues(name) {
     return argValuesFrom(exports.commandArgs, name);
 }
 exports.queryTerm = exports.parsedArgs.queryTerm;
+exports.wikiImpactMode = exports.parsedArgs.wikiImpactMode;
+exports.wikiImpactTarget = exports.parsedArgs.wikiImpactTarget;
 exports.codeImpactTarget = exports.parsedArgs.codeImpactTarget;
 exports.codeQuerySql = exports.parsedArgs.codeQuerySql;
 exports.codeReportSection = exports.parsedArgs.codeReportSection;

package/dist/code-index-file-policy.js

@@ -33,18 +33,28 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.maxIndexedBytes = exports.ignoredDirectories = void 0;
+exports.SMALL_REPO_FILE_THRESHOLD = exports.maxIndexedBytes = exports.ignoredDirectories = exports.codeEvidenceDirectory = void 0;
 exports.fileLanguage = fileLanguage;
 exports.isJavaScriptLike = isJavaScriptLike;
 exports.shouldIndexFile = shouldIndexFile;
 exports.isIgnoredCodePath = isIgnoredCodePath;
+exports.discoverCodeFiles = discoverCodeFiles;
+exports.smallRepoCodeIndexGate = smallRepoCodeIndexGate;
+const childProcess = __importStar(require("node:child_process"));
+const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const workspace_1 = require("./workspace");
+// Single source of truth for the disposable code-evidence directory name. Both
+// the heavy code-index module and the light bootstrap path (hooks.ts) key off
+// this; keeping it here avoids loading typescript/node:sqlite during bootstrap.
+exports.codeEvidenceDirectory = ".project-wiki";
 exports.ignoredDirectories = new Set([
     ".git",
     ".codex",
     ".claude",
-    ".project-wiki",
+    ".cursor",
+    ".gemini",
+    exports.codeEvidenceDirectory,
     "node_modules",
     ".next",
     "dist",
@@ -118,3 +128,98 @@ function isIgnoredCodePath(relativePath) {
         .filter(Boolean)
         .some((part) => exports.ignoredDirectories.has(part));
 }
+// Mirrors normalizeProjectRelative in code-index.ts for git ls-files output, but
+// throws instead of exiting so the light bootstrap path can use discovery too.
+// Git emits repo-relative paths, so the escape branch is unreachable for real
+// output; it stays as a loud guard, not a recovery path.
+function normalizeGitIndexedFile(input) {
+    const raw = input.trim() || ".";
+    const resolved = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(workspace_1.root, raw);
+    const rootResolved = path.resolve(workspace_1.root);
+    if (resolved !== rootResolved && !resolved.startsWith(`${rootResolved}${path.sep}`)) {
+        throw new Error(`git-indexed file must stay inside the project root: ${input}`);
+    }
+    return (0, workspace_1.normalizePath)(path.relative(rootResolved, resolved)) || ".";
+}
+function walkCodeFiles(relativePath, files = []) {
+    if (isIgnoredCodePath(relativePath))
+        return files.sort();
+    const target = (0, workspace_1.abs)(relativePath);
+    if (!fs.existsSync(target))
+        return files;
+    const stat = fs.statSync(target);
+    if (stat.isFile()) {
+        if (stat.size <= exports.maxIndexedBytes && shouldIndexFile(relativePath))
+            files.push(relativePath);
+        return files.sort();
+    }
+    for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+        const child = (0, workspace_1.normalizePath)(path.join(relativePath, entry.name));
+        if (entry.isDirectory()) {
+            if (!exports.ignoredDirectories.has(entry.name))
+                walkCodeFiles(child, files);
+        }
+        else if (entry.isFile() && shouldIndexFile(child)) {
+            const childStat = fs.statSync((0, workspace_1.abs)(child));
+            if (childStat.size <= exports.maxIndexedBytes)
+                files.push(child);
+        }
+    }
+    return files.sort();
+}
+function gitTrackedAndUnignoredFiles(scopes) {
+    try {
+        const output = childProcess.execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", ...scopes], {
+            cwd: workspace_1.root,
+            encoding: "buffer",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        return output.toString("utf8").split("\0").filter(Boolean).map((file) => normalizeGitIndexedFile(file));
+    }
+    catch {
+        return null;
+    }
+}
+function discoverCodeFiles(scopes) {
+    const gitFiles = gitTrackedAndUnignoredFiles(scopes);
+    const candidates = gitFiles ?? scopes.flatMap((scope) => walkCodeFiles(scope));
+    return Array.from(new Set(candidates))
+        .filter((file) => !isIgnoredCodePath(file))
+        .filter((file) => fs.existsSync((0, workspace_1.abs)(file)))
+        .filter((file) => fs.statSync((0, workspace_1.abs)(file)).isFile())
+        .filter((file) => shouldIndexFile(file))
+        .filter((file) => fs.statSync((0, workspace_1.abs)(file)).size <= exports.maxIndexedBytes)
+        .sort();
+}
+// --- Scale-aware code-evidence gate ------------------------------------------
+//
+// Threshold in indexable files (the discoverCodeFiles count) below which the
+// code-evidence surfaces warn (--code-index) or skip by default (bootstrap MCP
+// auto-registration). Evidence: stageR1 real-corpus run, 2026-06-12
+// (benchmarks/reports/llm/stageR1-real.md) — the ~1.2k-file repo LOST every
+// measured question (impact_trace +116.9%, workspace_graph +106.5% cost-weighted
+// tokens vs direct reads) while the ~11.8k-file repo still lost the cheap
+// ownership lookup (+99.0%) and won only the expensive traversal questions
+// (impact_trace -27.7%, workspace_graph -2.6%); stage2d synthetic scales
+// (benchmarks/reports/llm/stage2d-codegraph.md) lost across the board. 5000 sits
+// between the two real measured points: an n=2 extrapolation (1.2k all-loss /
+// 11.8k partial win), explicitly subject to revision as more scales are measured.
+exports.SMALL_REPO_FILE_THRESHOLD = 5000;
+// Decision for the --code-index scale gate: below the threshold the build halts
+// with an evidence-citing warning unless the caller explicitly acknowledged the
+// measured cost. Consent is honored, never refused (2026-06-12 decision: defaults
+// follow the evidence, explicit requests get warning + consent).
+function smallRepoCodeIndexGate(indexableFileCount, acknowledged) {
+    if (acknowledged || indexableFileCount >= exports.SMALL_REPO_FILE_THRESHOLD)
+        return { proceed: true, warning: "" };
+    return {
+        proceed: false,
+        warning: [
+            `--code-index halted: ${indexableFileCount} indexable files is below the ${exports.SMALL_REPO_FILE_THRESHOLD}-file scale threshold.`,
+            "Measured evidence (real-corpus stageR1): on a ~1.2k-file repo the code-evidence track cost MORE on every measured question (impact_trace +116.9%, workspace_graph +106.5% cost-weighted tokens vs direct reads), and even on a ~11.8k-file repo ownership-style cheap lookups lost (+99.0%); only expensive traversal questions won there (impact_trace -27.7%).",
+            "Reports: benchmarks/reports/llm/stageR1-real.md and benchmarks/reports/llm/stage2d-codegraph.md in the project-librarian repo (threshold is an n=2 extrapolation, subject to revision).",
+            "Not measured, so not disproven: human-facing report value (--code-report) and answer accuracy/grounding value. This gate reflects measured LLM token cost only.",
+            "To build the index anyway, re-run with --acknowledge-small-repo.",
+        ].join("\n"),
+    };
+}

package/dist/code-index.js

@@ -33,6 +33,19 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodeEvidenceIndexUnavailableError = void 0;
+exports.codeIndexStaleness = codeIndexStaleness;
+exports.codeownerRules = codeownerRules;
+exports.matchedCodeownerRules = matchedCodeownerRules;
+exports.ownershipContext = ownershipContext;
+exports.ownershipInfo = ownershipInfo;
+exports.evidenceCoverage = evidenceCoverage;
+exports.workspaceSummary = workspaceSummary;
+exports.workspaceDependencyGraph = workspaceDependencyGraph;
+exports.codeReportMetadata = codeReportMetadata;
+exports.codeImpact = codeImpact;
+exports.searchSymbols = searchSymbols;
+exports.openCodeEvidenceDatabaseForServing = openCodeEvidenceDatabaseForServing;
 exports.runCodeIndexMode = runCodeIndexMode;
 exports.runCodeQueryMode = runCodeQueryMode;
 exports.runCodeReportMode = runCodeReportMode;
@@ -43,7 +56,6 @@ exports.runCodeSearchSymbolMode = runCodeSearchSymbolMode;
 exports.isCodeEvidenceMode = isCodeEvidenceMode;
 exports.isCodeEvidenceModeFor = isCodeEvidenceModeFor;
 const crypto = __importStar(require("node:crypto"));
-const childProcess = __importStar(require("node:child_process"));
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
 const ts = __importStar(require("typescript"));
@@ -52,7 +64,6 @@ const code_index_db_1 = require("./code-index-db");
 const code_index_file_policy_1 = require("./code-index-file-policy");
 const code_index_sql_1 = require("./code-index-sql");
 const workspace_1 = require("./workspace");
-const codeEvidenceDirectory = ".project-wiki";
 const codeIndexSchemaVersion = "3";
 const httpMethods = new Set(["all", "delete", "get", "patch", "post", "put"]);
 const treeSitterGrammarPackages = {
@@ -117,11 +128,11 @@ function normalizeProjectRelative(input, label) {
     return (0, workspace_1.normalizePath)(path.relative(rootResolved, resolved)) || ".";
 }
 function codeEvidenceDatabasePath() {
-    const raw = args_1.codeIndexOutput.trim() || `${codeEvidenceDirectory}/code-evidence.sqlite`;
+    const raw = args_1.codeIndexOutput.trim() || `${code_index_file_policy_1.codeEvidenceDirectory}/code-evidence.sqlite`;
     const absolutePath = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(workspace_1.root, raw);
-    const evidenceRoot = path.resolve(workspace_1.root, codeEvidenceDirectory);
+    const evidenceRoot = path.resolve(workspace_1.root, code_index_file_policy_1.codeEvidenceDirectory);
     if (absolutePath === evidenceRoot || !absolutePath.startsWith(`${evidenceRoot}${path.sep}`)) {
-        fail(`--code-index-out must stay inside ${codeEvidenceDirectory}/`);
+        fail(`--code-index-out must stay inside ${code_index_file_policy_1.codeEvidenceDirectory}/`);
     }
     return {
         absolutePath,
@@ -182,56 +193,6 @@ function extractionProfile(relativePath, parserMode) {
         return "config";
     return "inventory-only";
 }
-function walkCodeFiles(relativePath, files = []) {
-    if ((0, code_index_file_policy_1.isIgnoredCodePath)(relativePath))
-        return files.sort();
-    const target = (0, workspace_1.abs)(relativePath);
-    if (!fs.existsSync(target))
-        return files;
-    const stat = fs.statSync(target);
-    if (stat.isFile()) {
-        if (stat.size <= code_index_file_policy_1.maxIndexedBytes && (0, code_index_file_policy_1.shouldIndexFile)(relativePath))
-            files.push(relativePath);
-        return files.sort();
-    }
-    for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
-        const child = (0, workspace_1.normalizePath)(path.join(relativePath, entry.name));
-        if (entry.isDirectory()) {
-            if (!code_index_file_policy_1.ignoredDirectories.has(entry.name))
-                walkCodeFiles(child, files);
-        }
-        else if (entry.isFile() && (0, code_index_file_policy_1.shouldIndexFile)(child)) {
-            const childStat = fs.statSync((0, workspace_1.abs)(child));
-            if (childStat.size <= code_index_file_policy_1.maxIndexedBytes)
-                files.push(child);
-        }
-    }
-    return files.sort();
-}
-function gitTrackedAndUnignoredFiles(scopes) {
-    try {
-        const output = childProcess.execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", ...scopes], {
-            cwd: workspace_1.root,
-            encoding: "buffer",
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        return output.toString("utf8").split("\0").filter(Boolean).map((file) => normalizeProjectRelative(file, "git-indexed file"));
-    }
-    catch {
-        return null;
-    }
-}
-function discoverCodeFiles(scopes) {
-    const gitFiles = gitTrackedAndUnignoredFiles(scopes);
-    const candidates = gitFiles ?? scopes.flatMap((scope) => walkCodeFiles(scope));
-    return Array.from(new Set(candidates))
-        .filter((file) => !(0, code_index_file_policy_1.isIgnoredCodePath)(file))
-        .filter((file) => fs.existsSync((0, workspace_1.abs)(file)))
-        .filter((file) => fs.statSync((0, workspace_1.abs)(file)).isFile())
-        .filter((file) => (0, code_index_file_policy_1.shouldIndexFile)(file))
-        .filter((file) => fs.statSync((0, workspace_1.abs)(file)).size <= code_index_file_policy_1.maxIndexedBytes)
-        .sort();
-}
 function readCodeFile(relativePath, parserMode = "default") {
     const text = fs.readFileSync((0, workspace_1.abs)(relativePath), "utf8");
     return {
@@ -1163,7 +1124,7 @@ function removeDatabaseFiles(databasePath) {
 function codeIndexStaleness(database) {
     const scopes = indexedScopes(database);
     const parserMode = indexedParserMode(database);
-    const current = new Map(discoverCodeFiles(scopes.length > 0 ? scopes : ["."]).map((file) => {
+    const current = new Map((0, code_index_file_policy_1.discoverCodeFiles)(scopes.length > 0 ? scopes : ["."]).map((file) => {
         const codeFile = readCodeFile(file, parserMode);
         return [codeFile.path, codeFile.hash];
     }));
@@ -1311,6 +1272,13 @@ function matchingCodeowners(filePath, rules) {
     const matches = rules.filter((rule) => codeownerPatternMatches(rule.pattern, filePath));
     return matches[matches.length - 1]?.owners ?? [];
 }
+// Return every CODEOWNERS rule that matches a path, in file order. The last entry
+// is the effective owner under last-match-wins; earlier entries are overridden.
+// Reuses the same matcher as matchingCodeowners so precedence answers stay
+// consistent with --code-report / --code-impact.
+function matchedCodeownerRules(filePath, rules) {
+    return rules.filter((rule) => codeownerPatternMatches(rule.pattern, filePath));
+}
 function ownershipContext() {
     return {
         codeownerRules: codeownerRules(),
@@ -1670,16 +1638,66 @@ function codeImpact(database, target) {
         })).sort((left, right) => right.files - left.files || left.owner.localeCompare(right.owner)),
     };
 }
+// Symbol search reusing the exact SELECT behind --code-search-symbol so the MCP
+// code_search tool returns identical rows without duplicating the query string.
+function searchSymbols(database, term) {
+    const like = `%${term}%`;
+    return database.prepare("SELECT name, kind, file_path, line, signature FROM symbols WHERE name LIKE ? OR signature LIKE ? ORDER BY file_path, line LIMIT 50").all(like, like);
+}
+// Error thrown when the code-evidence index is missing or schema-incompatible.
+// The MCP server catches this to return an isError tool result (tools/list still
+// works); CLI modes keep their own process.exit path via requireExistingIndex.
+class CodeEvidenceIndexUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CodeEvidenceIndexUnavailableError";
+    }
+}
+exports.CodeEvidenceIndexUnavailableError = CodeEvidenceIndexUnavailableError;
+// Open the existing .project-wiki code-evidence index READ-ONLY for serving:
+// validates existence and schema version, then pins PRAGMA query_only = ON. Uses
+// the same path resolution and schema constant as the indexer so the server and
+// the writer share one contract. Throws CodeEvidenceIndexUnavailableError (never
+// exits) so the MCP server can answer with guidance to run --code-index.
+function openCodeEvidenceDatabaseForServing() {
+    const databasePath = codeEvidenceDatabasePath();
+    if (!fs.existsSync(databasePath.absolutePath)) {
+        throw new CodeEvidenceIndexUnavailableError(`missing code evidence index: ${databasePath.relativePath}; run \`project-librarian --code-index\` first`);
+    }
+    const database = openDatabase(databasePath.absolutePath);
+    let schemaVersion = "";
+    try {
+        schemaVersion = readMetaValue(database, "schema_version");
+    }
+    catch (error) {
+        database.close();
+        const message = error instanceof Error ? error.message : String(error);
+        throw new CodeEvidenceIndexUnavailableError(`code evidence index at ${databasePath.relativePath} is not readable; rebuild with \`project-librarian --code-index\`. Error: ${message}`);
+    }
+    if (schemaVersion !== codeIndexSchemaVersion) {
+        database.close();
+        throw new CodeEvidenceIndexUnavailableError(`code evidence index schema version ${schemaVersion || "(missing)"} is incompatible with ${codeIndexSchemaVersion}; rebuild with \`project-librarian --code-index\``);
+    }
+    database.exec("PRAGMA query_only = ON");
+    return { database, relativePath: databasePath.relativePath };
+}
 function prepareOutputPath() {
     const databasePath = codeEvidenceDatabasePath();
     (0, workspace_1.mkdirp)(path.dirname(databasePath.relativePath));
-    (0, workspace_1.mkdirp)(codeEvidenceDirectory);
-    fs.writeFileSync((0, workspace_1.abs)(`${codeEvidenceDirectory}/.gitignore`), "*\n!.gitignore\n");
+    (0, workspace_1.mkdirp)(code_index_file_policy_1.codeEvidenceDirectory);
+    fs.writeFileSync((0, workspace_1.abs)(`${code_index_file_policy_1.codeEvidenceDirectory}/.gitignore`), "*\n!.gitignore\n");
 }
 function runCodeIndexMode() {
     const databasePath = codeEvidenceDatabasePath();
     const scopes = codeScopes();
     const parserMode = selectedCodeParserMode();
+    // Scale gate before ANY write or database work: below the measured threshold
+    // the build halts with the evidence-citing warning unless --acknowledge-small-repo
+    // was passed (2026-06-12 scale-aware guidance decision).
+    const discoveredFiles = (0, code_index_file_policy_1.discoverCodeFiles)(scopes);
+    const scaleGate = (0, code_index_file_policy_1.smallRepoCodeIndexGate)(discoveredFiles.length, args_1.acknowledgeSmallRepoMode);
+    if (!scaleGate.proceed)
+        fail(scaleGate.warning);
     const existingIndex = fs.existsSync(databasePath.absolutePath);
     if (args_1.codeIndexIncrementalMode && !existingIndex) {
         fail(`--incremental requires an existing compatible code evidence index: ${databasePath.relativePath}`);
@@ -1706,7 +1724,7 @@ function runCodeIndexMode() {
         if (!incremental)
             setupDatabase(database);
         const statements = createIndexStatements(database);
-        const currentFiles = discoverCodeFiles(scopes).map((filePath) => readCodeFile(filePath, parserMode));
+        const currentFiles = discoveredFiles.map((filePath) => readCodeFile(filePath, parserMode));
         const currentByPath = new Map(currentFiles.map((file) => [file.path, file]));
         const indexed = incremental ? new Map(database.prepare("SELECT path, hash FROM files").all().map((row) => [String(row.path), String(row.hash)])) : new Map();
         const deletedPaths = incremental ? Array.from(indexed.keys()).filter((filePath) => !currentByPath.has(filePath)) : [];

package/dist/hooks.js

@@ -33,12 +33,21 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.gitWikiCommitTrailersScript = exports.gitPrepareCommitMsgHook = exports.hookScript = void 0;
+exports.gitWikiCommitTrailersScript = exports.gitPrepareCommitMsgHook = exports.cursorHookScript = exports.hookScript = void 0;
 exports.upsertGitHooksPath = upsertGitHooksPath;
 exports.upsertHookConfig = upsertHookConfig;
 exports.upsertClaudeHookConfig = upsertClaudeHookConfig;
+exports.upsertGeminiHookConfig = upsertGeminiHookConfig;
+exports.upsertCursorHookConfig = upsertCursorHookConfig;
+exports.codeEvidenceIndexExists = codeEvidenceIndexExists;
+exports.mcpRegistrationGate = mcpRegistrationGate;
+exports.upsertClaudeMcpConfig = upsertClaudeMcpConfig;
+exports.upsertCursorMcpConfig = upsertCursorMcpConfig;
+exports.upsertGeminiMcpConfig = upsertGeminiMcpConfig;
 const childProcess = __importStar(require("node:child_process"));
+const fs = __importStar(require("node:fs"));
 const args_1 = require("./args");
+const code_index_file_policy_1 = require("./code-index-file-policy");
 const workspace_1 = require("./workspace");
 function upsertGitHooksPath() {
     if (args_1.noGitConfigMode)
@@ -109,7 +118,102 @@ function upsertHookConfig() {
 function upsertClaudeHookConfig() {
     return upsertSessionStartHookConfig(".claude/settings.json", "node .claude/hooks/wiki-session-start.js", ["startup", "resume", "clear", "compact"]);
 }
-exports.hookScript = `#!/usr/bin/env node
+function upsertGeminiHookConfig() {
+    return upsertSessionStartHookConfig(".gemini/settings.json", 'node "$GEMINI_PROJECT_DIR/.gemini/hooks/wiki-session-start.js"', ["startup", "resume", "clear"]);
+}
+function isCursorHookCommand(value) {
+    return Boolean(value) && typeof value === "object" && typeof value.command === "string";
+}
+function upsertCursorHookConfig() {
+    const relativePath = ".cursor/hooks.json";
+    const command = "node .cursor/hooks/wiki-session-start.js";
+    const config = (0, workspace_1.parseJson)(relativePath, { version: 1, hooks: {} });
+    if (typeof config.version !== "number")
+        config.version = 1;
+    if (!config.hooks || typeof config.hooks !== "object" || Array.isArray(config.hooks)) {
+        config.hooks = {};
+    }
+    const existing = Array.isArray(config.hooks.sessionStart) ? config.hooks.sessionStart.filter(isCursorHookCommand) : [];
+    config.hooks.sessionStart = [
+        ...existing.filter((hook) => hook.command !== command),
+        { command },
+    ];
+    const next = `${JSON.stringify(config, null, 2)}\n`;
+    const previous = (0, workspace_1.exists)(relativePath) ? (0, workspace_1.read)(relativePath) : "";
+    (0, workspace_1.write)(relativePath, next);
+    return previous === next ? "exists" : previous ? "updated" : "created";
+}
+const mcpServerName = "project-librarian";
+// Candidate local-runner paths, project root relative, in the recorded
+// local-runner-first order (mirrors validationTrailers()). The first existing
+// runner wins; absent any local install we register the published binary.
+const localRunnerCandidates = [
+    "tools/project-librarian/dist/init-project-wiki.js",
+    ".codex/skills/project-librarian/dist/init-project-wiki.js",
+    ".claude/skills/project-librarian/dist/init-project-wiki.js",
+    ".cursor/skills/project-librarian/dist/init-project-wiki.js",
+    ".gemini/skills/project-librarian/dist/init-project-wiki.js",
+];
+// Deterministic command policy for the registered MCP server: if the repo
+// contains a local runner, register `node <runner> mcp`; otherwise register the
+// installed binary `project-librarian mcp`. This mirrors the local-runner-first
+// skill policy (run the installed local copy with node, not npx) so registration
+// does not depend on network/registry access. The runner path is stored project
+// relative so the registration stays portable across clones.
+function mcpServerEntry() {
+    const runner = localRunnerCandidates.find((candidate) => fs.existsSync((0, workspace_1.abs)(candidate)));
+    if (runner)
+        return { command: "node", args: [runner, "mcp"] };
+    return { command: mcpServerName, args: ["mcp"] };
+}
+// Preservation-first, idempotent merge of the project-librarian MCP server into a
+// JSON config file's `mcpServers` map. Unknown keys and other servers are never
+// clobbered; only `mcpServers["project-librarian"]` is set. A second run with an
+// unchanged entry returns "exists". Used for Claude `.mcp.json`, Cursor
+// `.cursor/mcp.json`, and (via the same map) Gemini `.gemini/settings.json`.
+//
+// Codex boundary: `codex mcp` only manages USER-level config (~/.codex/config.toml
+// via `codex mcp add`); there is no documented project-level MCP config file under
+// `.codex/`. Per the no-user-level-writes rule we do not register Codex here; the
+// README documents running `codex mcp add project-librarian -- node <runner> mcp`.
+function upsertMcpServersFile(relativePath) {
+    const config = (0, workspace_1.parseJson)(relativePath, {});
+    if (!config.mcpServers || typeof config.mcpServers !== "object" || Array.isArray(config.mcpServers)) {
+        config.mcpServers = {};
+    }
+    config.mcpServers[mcpServerName] = mcpServerEntry();
+    const next = `${JSON.stringify(config, null, 2)}\n`;
+    const previous = (0, workspace_1.exists)(relativePath) ? (0, workspace_1.read)(relativePath) : "";
+    if (previous === next)
+        return "exists";
+    (0, workspace_1.write)(relativePath, next);
+    return previous ? "updated" : "created";
+}
+function codeEvidenceIndexExists() {
+    return (0, workspace_1.walkFilesUnder)(code_index_file_policy_1.codeEvidenceDirectory, (file) => file.endsWith(".sqlite")).length > 0;
+}
+function mcpRegistrationGate() {
+    if (codeEvidenceIndexExists())
+        return { register: true };
+    const indexableFileCount = (0, code_index_file_policy_1.discoverCodeFiles)(["."]).length;
+    if (indexableFileCount >= code_index_file_policy_1.SMALL_REPO_FILE_THRESHOLD)
+        return { register: true };
+    return {
+        register: false,
+        reason: `skipped-small-repo ${indexableFileCount} indexable files < ${code_index_file_policy_1.SMALL_REPO_FILE_THRESHOLD} (code-evidence tools measured costlier than direct reads at this scale: stageR1; opt in via --code-index --acknowledge-small-repo, then re-run bootstrap)`,
+    };
+}
+function upsertClaudeMcpConfig() {
+    return upsertMcpServersFile(".mcp.json");
+}
+function upsertCursorMcpConfig() {
+    return upsertMcpServersFile(".cursor/mcp.json");
+}
+function upsertGeminiMcpConfig() {
+    return upsertMcpServersFile(".gemini/settings.json");
+}
+function buildStartupHookScript(output) {
+    return `#!/usr/bin/env node
 
 const fs = require("fs");
 const path = require("path");
@@ -127,7 +231,7 @@ function readHookInput() {
 }
 
 const hookInput = readHookInput();
-const cwd = process.env.CODEX_WORKSPACE_DIR || hookInput.cwd || process.cwd();
+const cwd = process.env.GEMINI_PROJECT_DIR || process.env.CODEX_WORKSPACE_DIR || process.env.CLAUDE_PROJECT_DIR || hookInput.cwd || process.cwd();
 
 function readIfExists(relativePath, maxChars) {
   const filePath = path.join(cwd, relativePath);
@@ -155,6 +259,8 @@ const sections = files
 
 const additionalContext = [
   "[Project wiki startup review]",
+  "Injected context: wiki/startup.md and wiki/index.md are ALREADY included below this line.",
+  "Do not re-read these two files this session; route any further reads through the index.",
   "Use ./wiki as the project-planning source of truth only. Start with compact routing context; read detailed project canonical, decision, or meta files on demand.",
   "Project canonical content language is selected from user/project context; do not assume a fixed default language.",
   "When project planning content is added, changed, or removed, update ./wiki in the same turn.",
@@ -164,10 +270,15 @@ const additionalContext = [
 ].join("\\n");
 
 process.stdout.write(JSON.stringify({
-  continue: true,
-  hookSpecificOutput: { hookEventName: "SessionStart", additionalContext },
+${output}
 }));
 `;
+}
+exports.hookScript = buildStartupHookScript(`  continue: true,
+  hookSpecificOutput: { hookEventName: "SessionStart", additionalContext },
+`);
+exports.cursorHookScript = buildStartupHookScript(`  additional_context: additionalContext,
+`);
 exports.gitPrepareCommitMsgHook = `#!/bin/sh
 MSG_FILE="$1"
 SOURCE="$2"
@@ -253,7 +364,10 @@ function wikiScope(files) {
     else if (file === "wiki/index.md") add("index");
     else if (file.startsWith(".codex/hooks/") || file === ".codex/hooks.json") add("codex-hooks");
     else if (file.startsWith(".claude/hooks/") || file === ".claude/settings.json") add("claude-hooks");
-    else if (file === "AGENTS.md" || file === "CLAUDE.md") add("agents");
+    else if (file.startsWith(".cursor/hooks/") || file === ".cursor/hooks.json") add("cursor-hooks");
+    else if (file.startsWith(".cursor/rules/")) add("cursor-rules");
+    else if (file.startsWith(".gemini/hooks/") || file === ".gemini/settings.json") add("gemini-hooks");
+    else if (file === "AGENTS.md" || file === "CLAUDE.md" || file === "GEMINI.md") add("agents");
     else if (file.startsWith(".githooks/")) add("git-hooks");
     else if (file.startsWith("tools/project-librarian/")) add("skill");
   }
@@ -266,15 +380,31 @@ function validationTrailers() {
     "tools/project-librarian/dist/init-project-wiki.js",
     path.join(home, ".codex/skills/project-librarian/dist/init-project-wiki.js"),
     path.join(home, ".claude/skills/project-librarian/dist/init-project-wiki.js"),
+    path.join(home, ".cursor/skills/project-librarian/dist/init-project-wiki.js"),
+    path.join(home, ".gemini/skills/project-librarian/dist/init-project-wiki.js"),
   ].find((candidate) => fs.existsSync(candidate));
   const lintOk = Boolean(lintScript) && commandOk("node", [lintScript, "--lint"]);
   const codexSessionHookOk = fs.existsSync(".codex/hooks/wiki-session-start.js") && commandOk("node", [".codex/hooks/wiki-session-start.js"]);
   const claudeSessionHookOk = fs.existsSync(".claude/hooks/wiki-session-start.js") && commandOk("node", [".claude/hooks/wiki-session-start.js"]);
-  if (lintOk && codexSessionHookOk && claudeSessionHookOk) return { tested: "project wiki lint; Codex and Claude wiki session-start hooks", notTested: "none" };
+  const cursorSessionHookOk = fs.existsSync(".cursor/hooks/wiki-session-start.js") && commandOk("node", [".cursor/hooks/wiki-session-start.js"]);
+  const cursorHookConfigOk = fs.existsSync(".cursor/hooks.json") && existingFile(".cursor/hooks.json").includes("node .cursor/hooks/wiki-session-start.js");
+  const geminiSessionHookOk = fs.existsSync(".gemini/hooks/wiki-session-start.js") && commandOk("node", [".gemini/hooks/wiki-session-start.js"]);
+  const geminiHookConfigOk = fs.existsSync(".gemini/settings.json") && existingFile(".gemini/settings.json").includes('node "$GEMINI_PROJECT_DIR/.gemini/hooks/wiki-session-start.js"');
+  const geminiInstructionsOk = fs.existsSync("GEMINI.md") && existingFile("GEMINI.md").includes("@AGENTS.md");
+  const cursorRuleOk = fs.existsSync(".cursor/rules/project-librarian.mdc") && existingFile(".cursor/rules/project-librarian.mdc").includes("@AGENTS.md");
+  if (lintOk && codexSessionHookOk && claudeSessionHookOk && cursorSessionHookOk && cursorHookConfigOk && geminiSessionHookOk && geminiHookConfigOk && geminiInstructionsOk && cursorRuleOk) {
+    return { tested: "project wiki lint; Codex, Claude, Cursor, and Gemini wiki session-start hooks; Cursor and Gemini instruction files", notTested: "none" };
+  }
   const gaps = [];
   if (!lintOk) gaps.push("project wiki lint");
   if (!codexSessionHookOk) gaps.push("Codex wiki session-start hook");
   if (!claudeSessionHookOk) gaps.push("Claude wiki session-start hook");
+  if (!cursorSessionHookOk) gaps.push("Cursor wiki session-start hook");
+  if (!cursorHookConfigOk) gaps.push("Cursor hook config");
+  if (!geminiSessionHookOk) gaps.push("Gemini wiki SessionStart hook");
+  if (!geminiHookConfigOk) gaps.push("Gemini hook config");
+  if (!cursorRuleOk) gaps.push("Cursor project rule");
+  if (!geminiInstructionsOk) gaps.push("Gemini instructions");
   return { tested: "prepare-commit-msg generated wiki trailers", notTested: gaps.join("; ") || "unknown" };
 }
 
@@ -287,10 +417,16 @@ const wikiFiles = staged.filter((file) => {
   return file.startsWith("wiki/")
     || file === "AGENTS.md"
     || file === "CLAUDE.md"
+    || file === "GEMINI.md"
     || file === ".codex/hooks.json"
     || file.startsWith(".codex/hooks/")
     || file === ".claude/settings.json"
     || file.startsWith(".claude/hooks/")
+    || file.startsWith(".cursor/rules/")
+    || file === ".cursor/hooks.json"
+    || file.startsWith(".cursor/hooks/")
+    || file === ".gemini/settings.json"
+    || file.startsWith(".gemini/hooks/")
     || file.startsWith(".githooks/")
     || file.startsWith("tools/project-librarian/");
 });