@jcode.labs/ragmir 2.10.0 → 2.12.0

package/README.md

@@ -55,7 +55,10 @@ npx rgr audit --unsupported
 npx rgr security-audit
 
 # Retrieval
+npx rgr preview --path docs --max-chunks 3
 npx rgr search "deployment decision"
+npx rgr search "deployment decision" --explain
+npx rgr search "deployment decision" --context-path "Operations > Deployment"
 npx rgr ask "What evidence supports the deployment decision?"
 npx rgr research "deployment obligations" --compact
 
@@ -88,7 +91,10 @@ Frequently used exports:
 | Export | Purpose |
 | --- | --- |
 | `setupProject`, `addSourceEntries` | Initialize project state and select files |
+| `discoverKnowledgeBases`, `knowledgeBaseIdentity` | Route root and nested monorepo bases |
+| `getKnowledgeBaseContext`, `getKnowledgeBaseSourceCatalog` | Give agents bounded readiness and source context |
 | `ingest`, `audit` | Build the index and compare it with files on disk |
+| `previewChunks` | Inspect redacted chunks and distributions without writing storage |
 | `search`, `ask`, `research`, `expandCitation` | Retrieve or expand cited passages |
 | `doctor`, `securityAudit` | Inspect readiness and local privacy posture |
 | `serveMcp` | Start the read-focused local MCP server |
@@ -104,11 +110,16 @@ npx rgr setup --agents claude,codex,kimi,opencode,cline
 npx rgr doctor
 ```
 
-Ragmir writes helper files for the selected clients and points them at the current project. MCP
+Ragmir links the canonical skills into each selected client's native project folder, writes a local
+runner plus MCP helpers, and points them at the current project. MCP
 exposes status, search, ask, research, exact citation expansion, audit, evaluation, usage, and
 security tools. Retrieval responses have a global byte ceiling and expose metadata-only output
 metrics. The server does not expose index deletion.
 
+For a monorepo with root and app-specific bases, run `rgr bases --json` before retrieval when scope
+is unclear. The nearest configured base is active, nested MCP helpers get unique names, and every
+helper pins `RAGMIR_PROJECT_ROOT` so clients cannot drift to a sibling index.
+
 ## Retrieval modes
 
 | Mode | Network requirement | Best for |

package/dist/chunk-stats.d.ts

@@ -0,0 +1,8 @@
+import type { ChunkStats } from "./types.js";
+interface ChunkShape {
+    contextPath: string;
+    text: string;
+}
+export declare function summarizeChunkStats(chunks: readonly ChunkShape[]): ChunkStats;
+export {};
+//# sourceMappingURL=chunk-stats.d.ts.map

package/dist/chunk-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-stats.d.ts","sourceRoot":"","sources":["../src/chunk-stats.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAE5C,UAAU,UAAU;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,CA2B7E"}

package/dist/chunk-stats.js

@@ -0,0 +1,31 @@
+export function summarizeChunkStats(chunks) {
+    if (chunks.length === 0) {
+        return {
+            count: 0,
+            minChars: 0,
+            averageChars: 0,
+            p50Chars: 0,
+            p95Chars: 0,
+            maxChars: 0,
+            contextualChunks: 0,
+            contextualRatio: 0,
+        };
+    }
+    const lengths = chunks.map((chunk) => chunk.text.length).sort((left, right) => left - right);
+    const contextualChunks = chunks.filter((chunk) => chunk.contextPath.trim().length > 0).length;
+    return {
+        count: chunks.length,
+        minChars: lengths[0] ?? 0,
+        averageChars: lengths.reduce((sum, length) => sum + length, 0) / lengths.length,
+        p50Chars: percentile(lengths, 0.5),
+        p95Chars: percentile(lengths, 0.95),
+        maxChars: lengths.at(-1) ?? 0,
+        contextualChunks,
+        contextualRatio: contextualChunks / chunks.length,
+    };
+}
+function percentile(sortedValues, quantile) {
+    const index = Math.ceil(quantile * sortedValues.length) - 1;
+    return sortedValues[Math.max(0, index)] ?? 0;
+}
+//# sourceMappingURL=chunk-stats.js.map

package/dist/chunk-stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk-stats.js","sourceRoot":"","sources":["../src/chunk-stats.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,mBAAmB,CAAC,MAA6B;IAC/D,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,KAAK,EAAE,CAAC;YACR,QAAQ,EAAE,CAAC;YACX,YAAY,EAAE,CAAC;YACf,QAAQ,EAAE,CAAC;YACX,QAAQ,EAAE,CAAC;YACX,QAAQ,EAAE,CAAC;YACX,gBAAgB,EAAE,CAAC;YACnB,eAAe,EAAE,CAAC;SACnB,CAAA;IACH,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,GAAG,KAAK,CAAC,CAAA;IAC5F,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,CAAA;IAE7F,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,MAAM;QACpB,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;QACzB,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,GAAG,MAAM,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM;QAC/E,QAAQ,EAAE,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC;QAClC,QAAQ,EAAE,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC;QACnC,QAAQ,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC7B,gBAAgB;QAChB,eAAe,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM;KAClD,CAAA;AACH,CAAC;AAED,SAAS,UAAU,CAAC,YAAsB,EAAE,QAAgB;IAC1D,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IAC3D,OAAO,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,CAAA;AAC9C,CAAC"}

package/dist/cli.js

@@ -14,10 +14,12 @@ import { countSkippedByReason } from "./files.js";
 import { getIndexFreshnessWarning, getLexicalScanWarning } from "./index-diagnostics.js";
 import { audit, ingest } from "./ingest.js";
 import { initProject } from "./init.js";
+import { discoverKnowledgeBases, knowledgeBaseIdentity } from "./knowledge-bases.js";
 import { ingestionLimits } from "./limits.js";
 import { serveMcp } from "./mcp.js";
 import { configurePdfOcr, extractPdfPage, inspectPdfOcr, parsePdfOcrEngine } from "./ocr.js";
 import { rgrCommand } from "./package-manager.js";
+import { previewChunks } from "./preview.js";
 import { routePrompt } from "./prompt-routing.js";
 import { ask, search } from "./query.js";
 import { compactResearchReport, compactSearchResults, research } from "./research.js";
@@ -163,14 +165,15 @@ program
 });
 program
     .command("setup")
-    .description("Initialize Ragmir, install the agent kit, run doctor, and ingest when safe.")
+    .description("Initialize Ragmir, expose native agent skills, generate MCP helpers, and ingest when safe.")
     .option("--target-dir <path>", "Directory where the skill folder should be copied.", DEFAULT_SKILL_TARGET_DIR)
-    .option("--agents <list>", `Agent MCP helpers to generate: all, ${SUPPORTED_AGENT_TARGETS.join(", ")}.`, "all")
-    .option("--mcp-name <name>", "MCP server name used in generated config.", "ragmir")
+    .option("--agents <list>", `Native agent skills and MCP helpers to install: all, ${SUPPORTED_AGENT_TARGETS.join(", ")}.`, "all")
+    .option("--mcp-name <name>", "MCP server name. Nested monorepo bases get a unique name by default.")
     .option("--mcp-command <command>", "Custom MCP stdio command for generated helper files.")
     .option("--mcp-arg <arg>", "Argument for --mcp-command. Repeat for multiple arguments.", collectOptionValue, [])
     .option("--semantic", "Download the configured Transformers.js embedding model and enable higher-quality semantic retrieval.")
     .option("--no-ingest", "Skip automatic indexing even when supported files are present.")
+    .option("--force-agent-skills", "Replace same-name native skills after reviewing that they can be overwritten.")
     .option("--json", "Print machine-readable JSON.")
     .action(async (options, command) => {
     const cwd = projectRoot(command);
@@ -178,11 +181,12 @@ program
         cwd,
         targetDir: options.targetDir,
         agents: parseAgentTargets(options.agents),
-        mcpServerName: options.mcpName,
     };
+    addOption(setupOptions, "mcpServerName", options.mcpName);
     addOption(setupOptions, "semantic", options.semantic);
     addOption(setupOptions, "ingest", options.ingest);
     addOption(setupOptions, "mcpCommand", options.mcpCommand);
+    addOption(setupOptions, "forceAgentSkills", options.forceAgentSkills);
     if (options.mcpArg.length > 0) {
         setupOptions.mcpArgs = options.mcpArg;
     }
@@ -300,6 +304,56 @@ program
         process.exitCode = 1;
     }
 });
+program
+    .command("preview")
+    .description("Preview redacted chunks and structure without writing the index.")
+    .option("--path <prefix>", "Preview only source paths under this prefix. Repeat for multiple prefixes.", collectOptionValue, [])
+    .option("--max-files <number>", "Maximum number of matching files to parse.", parsePositiveInt)
+    .option("--max-chunks <number>", "Maximum number of chunks to show per file.", parsePositiveInt)
+    .option("--json", "Print machine-readable JSON.")
+    .action(async (options, command) => {
+    const cwd = projectRoot(command);
+    const previewOptions = { cwd };
+    if (options.path.length > 0) {
+        previewOptions.paths = options.path;
+    }
+    addOption(previewOptions, "maxFiles", options.maxFiles);
+    addOption(previewOptions, "maxChunksPerFile", options.maxChunks);
+    const report = await previewChunks(previewOptions);
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+        if (report.errors.length > 0 ||
+            (report.requestedPaths.length > 0 && report.matchedFiles === 0)) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    console.log(`chunkSize=${report.chunkSize}`);
+    console.log(`chunkOverlap=${report.chunkOverlap}`);
+    console.log(`matchedFiles=${report.matchedFiles}`);
+    console.log(`omittedFiles=${report.omittedFiles}`);
+    for (const unmatchedPath of report.unmatchedPaths) {
+        console.log(pc.yellow(`unmatched: ${unmatchedPath}`));
+    }
+    for (const file of report.files) {
+        console.log(`\n${pc.cyan(file.relativePath)} chunks=${file.chunkStats.count} redactions=${file.redactions} minChars=${file.chunkStats.minChars} p50Chars=${file.chunkStats.p50Chars} p95Chars=${file.chunkStats.p95Chars} maxChars=${file.chunkStats.maxChars} contextualRatio=${file.chunkStats.contextualRatio.toFixed(3)}`);
+        for (const chunk of file.chunks) {
+            const context = chunk.contextPath ? ` context=${chunk.contextPath}` : "";
+            console.log(`\n${pc.dim(chunk.citation)}${context}`);
+            console.log(chunk.text.slice(0, SEARCH_TEXT_PREVIEW_LENGTH));
+        }
+        if (file.omittedChunks > 0) {
+            console.log(pc.dim(`omittedChunks=${file.omittedChunks}`));
+        }
+    }
+    for (const error of report.errors) {
+        console.error(pc.red(`${error.path}: ${error.message}`));
+    }
+    if (report.errors.length > 0 ||
+        (report.requestedPaths.length > 0 && report.matchedFiles === 0)) {
+        process.exitCode = 1;
+    }
+});
 program
     .command("search")
     .description("Retrieve the most relevant passages without calling an LLM.")
@@ -308,6 +362,8 @@ program
     .option("--context-radius <number>", "Include neighboring chunks around each matched passage.", parseNonNegativeInt)
     .option("--include-path <prefix>", "Search only indexed source paths under this prefix. Repeat for multiple prefixes.", collectOptionValue, [])
     .option("--exclude-path <prefix>", "Exclude indexed source paths under this prefix. Repeat for multiple prefixes.", collectOptionValue, [])
+    .option("--context-path <prefix>", "Search only chunks under this structural context. Repeat for multiple prefixes.", collectOptionValue, [])
+    .option("--explain", "Include hybrid score contributions, ranks, and matched terms.")
     .option("--compact", "Return short snippets instead of full passages.")
     .option("--json", "Print machine-readable JSON.")
     .action(async (query, options, command) => {
@@ -332,6 +388,11 @@ program
         const distance = result.distance === null ? "n/a" : result.distance.toFixed(4);
         console.log(`\n${pc.cyan(`[${index + 1}] ${result.citation}`)} chunk=${result.chunkIndex} distance=${distance}`);
         console.log("snippet" in result ? result.snippet : result.text.slice(0, SEARCH_TEXT_PREVIEW_LENGTH));
+        if (result.score) {
+            const vectorRank = result.score.vectorRank ?? "n/a";
+            const lexicalRank = result.score.lexicalRank ?? "n/a";
+            console.log(pc.dim(`score=${result.score.combinedScore.toFixed(6)} fusion=${result.score.fusion} vector=${result.score.vectorContribution.toFixed(6)} lexical=${result.score.lexicalContribution.toFixed(6)} vectorRank=${vectorRank} lexicalRank=${lexicalRank} matchedTerms=${result.score.matchedTerms.join(",") || "n/a"}`));
+        }
     }
 });
 program
@@ -342,6 +403,8 @@ program
     .option("--context-radius <number>", "Include neighboring chunks around each matched passage.", parseNonNegativeInt)
     .option("--include-path <prefix>", "Use only indexed source paths under this prefix. Repeat for multiple prefixes.", collectOptionValue, [])
     .option("--exclude-path <prefix>", "Exclude indexed source paths under this prefix. Repeat for multiple prefixes.", collectOptionValue, [])
+    .option("--context-path <prefix>", "Use only chunks under this structural context. Repeat for multiple prefixes.", collectOptionValue, [])
+    .option("--explain", "Include hybrid score contributions, ranks, and matched terms.")
     .option("--json", "Print machine-readable JSON.")
     .action(async (query, options, command) => {
     const cwd = projectRoot(command);
@@ -360,7 +423,8 @@ program
     if (result.sources.length > 0) {
         console.log(pc.dim("Sources:"));
         for (const [index, source] of result.sources.entries()) {
-            console.log(`  [${index + 1}] ${source.citation} chunk=${source.chunkIndex}`);
+            const score = source.score ? ` score=${source.score.combinedScore.toFixed(6)}` : "";
+            console.log(`  [${index + 1}] ${source.citation} chunk=${source.chunkIndex}${score}`);
         }
     }
 });
@@ -372,6 +436,7 @@ program
     .option("--no-code", "Skip the lightweight repository code search.")
     .option("--include-path <prefix>", "Use only indexed source paths under this prefix. Repeat for multiple prefixes.", collectOptionValue, [])
     .option("--exclude-path <prefix>", "Exclude indexed source paths under this prefix. Repeat for multiple prefixes.", collectOptionValue, [])
+    .option("--context-path <prefix>", "Use only chunks under this structural context. Repeat for multiple prefixes.", collectOptionValue, [])
     .option("--compact", "Return snippets instead of full retrieved passages.")
     .option("--json", "Print machine-readable JSON.")
     .action(async (query, options, command) => {
@@ -493,6 +558,13 @@ program
     console.log(`sensitiveFiles=${countSkippedByReason(report.skippedFiles, "sensitive-name")}`);
     console.log(`indexedFiles=${report.indexedFiles.length}`);
     console.log(`totalChunks=${report.totalChunks}`);
+    console.log(`chunkStats.minChars=${report.chunkStats.minChars}`);
+    console.log(`chunkStats.averageChars=${report.chunkStats.averageChars.toFixed(1)}`);
+    console.log(`chunkStats.p50Chars=${report.chunkStats.p50Chars}`);
+    console.log(`chunkStats.p95Chars=${report.chunkStats.p95Chars}`);
+    console.log(`chunkStats.maxChars=${report.chunkStats.maxChars}`);
+    console.log(`chunkStats.contextualChunks=${report.chunkStats.contextualChunks}`);
+    console.log(`chunkStats.contextualRatio=${report.chunkStats.contextualRatio.toFixed(3)}`);
     console.log(`emptyTextFiles=${report.emptyTextFiles.length}`);
     console.log(`missingFromIndex=${report.missingFromIndex.length}`);
     console.log(`staleInIndex=${report.staleInIndex.length}`);
@@ -578,6 +650,25 @@ program
         console.log(`note: ${note}`);
     }
 });
+program
+    .command("bases")
+    .description("List Ragmir knowledge bases in the active monorepo and mark the selected base.")
+    .option("--json", "Print machine-readable JSON.")
+    .action(async (options, command) => {
+    const inventory = await discoverKnowledgeBases(projectRoot(command));
+    if (options.json) {
+        console.log(JSON.stringify(inventory, null, 2));
+        return;
+    }
+    console.log(`workspaceRoot=${inventory.workspaceRoot}`);
+    console.log(`activeBase=${inventory.activeId ?? "none"}`);
+    console.log(`bases=${inventory.bases.length}`);
+    for (const base of inventory.bases) {
+        const marker = base.active ? "*" : "-";
+        const format = base.legacy ? "legacy" : "ragmir";
+        console.log(`${marker} ${base.id} format=${format} root=${base.projectRoot}`);
+    }
+});
 program
     .command("status")
     .description("Show active configuration and index row count.")
@@ -585,8 +676,10 @@ program
     .action(async (options, command) => {
     const cwd = projectRoot(command);
     const config = await loadConfig(cwd);
+    const identity = knowledgeBaseIdentity(config.projectRoot);
     const rows = await countRows(config);
     const status = {
+        knowledgeBaseId: identity?.id ?? null,
         projectRoot: config.projectRoot,
         rawDir: config.rawDir,
         storageDir: config.storageDir,
@@ -619,6 +712,7 @@ program
         console.log(JSON.stringify(status, null, 2));
         return;
     }
+    console.log(`knowledgeBaseId=${identity?.id ?? "none"}`);
     console.log(`projectRoot=${config.projectRoot}`);
     console.log(`rawDir=${config.rawDir}`);
     console.log(`storageDir=${config.storageDir}`);
@@ -840,7 +934,7 @@ program
     .description("Copy the bundled agent skill and MCP config snippet into the current repository.")
     .option("--target-dir <path>", "Directory where the skill folder should be copied.", DEFAULT_SKILL_TARGET_DIR)
     .option("--agents <list>", `Agent MCP helpers to generate: all, ${SUPPORTED_AGENT_TARGETS.join(", ")}.`, "all")
-    .option("--mcp-name <name>", "MCP server name used in generated config.", "ragmir")
+    .option("--mcp-name <name>", "MCP server name. Nested monorepo bases get a unique name by default.")
     .option("--mcp-command <command>", "Custom MCP stdio command for generated helper files.")
     .option("--mcp-arg <arg>", "Argument for --mcp-command. Repeat for multiple arguments.", collectOptionValue, [])
     .action(async (options, command) => {
@@ -849,8 +943,8 @@ program
         cwd,
         targetDir: options.targetDir,
         agents: parseAgentTargets(options.agents),
-        mcpServerName: options.mcpName,
     };
+    addOption(installOptions, "mcpServerName", options.mcpName);
     addOption(installOptions, "mcpCommand", options.mcpCommand);
     if (options.mcpArg.length > 0) {
         installOptions.mcpArgs = options.mcpArg;
@@ -881,13 +975,20 @@ program
     .option("--agents <list>", `Comma-separated agents: all, ${SUPPORTED_AGENT_TARGETS.join(", ")}.`, "all")
     .option("--scope <scope>", "Install scope: project or user.", "project")
     .option("--mode <mode>", "Expose skills as links or physical copies: link or copy.", "link")
+    .option("--force", "Replace same-name native skills after reviewing that they can be overwritten.")
     .option("--json", "Print machine-readable JSON.")
     .action(async (options, command) => {
     const cwd = projectRoot(command);
     const scope = parseAgentInstallScope(options.scope);
     const mode = parseAgentInstallMode(options.mode);
     const agents = parseAgentTargets(options.agents);
-    const result = await installAgentSkills({ cwd, agents, scope, mode });
+    const result = await installAgentSkills({
+        cwd,
+        agents,
+        scope,
+        mode,
+        force: options.force ?? false,
+    });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
         return;
@@ -954,6 +1055,7 @@ function withSearchOptions(cwd, options) {
     addOption(result, "topK", options.topK);
     addOption(result, "contextRadius", options.contextRadius);
     addPathFilters(result, options);
+    addOption(result, "explain", options.explain);
     return result;
 }
 function addPathFilters(target, options) {
@@ -963,6 +1065,9 @@ function addPathFilters(target, options) {
     if (options.excludePath && options.excludePath.length > 0) {
         target.excludePaths = options.excludePath;
     }
+    if (options.contextPath && options.contextPath.length > 0) {
+        target.contextPaths = options.contextPath;
+    }
 }
 async function loadChat() {
     const module = await import(CHAT_PACKAGE_NAME);
@@ -1043,6 +1148,15 @@ function printDoctor(report) {
     console.log(`packageManager=${report.packageManager}`);
     console.log(`runCommand=${report.runCommand}`);
     console.log(`agentKitInstalled=${report.agentKitInstalled}`);
+    console.log(`agentIntegration.ready=${report.agentIntegration.ready}`);
+    console.log(`agentIntegration.runnerReady=${report.agentIntegration.runnerReady}`);
+    console.log(`agentIntegration.runnerMode=${report.agentIntegration.runnerMode ?? "none"}`);
+    console.log(`agentIntegration.projectAgents=${report.agentIntegration.projectAgents.join(",")}`);
+    console.log(`agentIntegration.userAgents=${report.agentIntegration.userAgents.join(",")}`);
+    console.log(`agentIntegration.nativeAgents=${report.agentIntegration.nativeAgents.join(",")}`);
+    for (const warning of report.agentIntegration.warnings) {
+        console.log(pc.yellow(`agentIntegration.warning: ${warning}`));
+    }
     console.log(`embeddingProvider=${report.embeddingProvider}`);
     console.log(`transformersAllowRemoteModels=${report.transformersAllowRemoteModels}`);
     console.log(`redactionEnabled=${report.redactionEnabled}`);
@@ -1172,6 +1286,9 @@ function printSetup(result, title) {
         console.log(`  - ${helper.label} MCP helper: ${helper.path}`);
     }
     console.log(`  - agent setup guide: ${result.agentKit.agentSetupPath}`);
+    for (const installation of result.agentInstallations) {
+        console.log(`  - ${installation.label} skills: ${installation.targetDir} (${installation.mode})`);
+    }
     console.log("");
     if (result.semantic) {
         console.log(pc.cyan("Semantic retrieval:"));