@jcode.labs/ragmir 6.1.6 → 6.2.1

package/README.md

@@ -1,7 +1,7 @@
 # @jcode.labs/ragmir
 
 [![npm version](https://img.shields.io/npm/v/@jcode.labs/ragmir?color=cb3837&logo=npm)](https://www.npmjs.com/package/@jcode.labs/ragmir)
-[![npm downloads](https://img.shields.io/npm/dm/@jcode.labs/ragmir?color=0b7285)](https://www.npmjs.com/package/@jcode.labs/ragmir)
+[![CI](https://github.com/jcode-works/jcode-ragmir/actions/workflows/ci.yml/badge.svg)](https://github.com/jcode-works/jcode-ragmir/actions/workflows/ci.yml)
 [![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-2f9e44)](https://github.com/jcode-works/jcode-ragmir/blob/main/LICENSE)
 [![Node.js 22.12+](https://img.shields.io/badge/node-%E2%89%A522.12-339933?logo=node.js&logoColor=white)](https://nodejs.org)
 
@@ -12,17 +12,18 @@ passages with checkable citations through a TypeScript library, the `rgr` CLI, o
 server. Claude Code, Codex, or your own application decides what to search and generates with the
 model you choose. Ragmir does not bundle a chat model or host your documents.
 
-- **Code and documents in one index:** hybrid BM25 and vector search that understands file paths
-  and camelCase identifiers.
-- **Fast on real repositories:** 25 ms median search on a 21,546-chunk monorepo, 14 times faster
-  than the previous release, with up to 35% better nDCG@10 on code and documentation
+- **Code and documents in one index:** hybrid BM25 and vector search that understands paths and
+  camelCase identifiers and boosts the code that defines what you ask about.
+- **Fast on real repositories:** 40 ms median search on a 43,874-chunk monorepo, with the right
+  source in the top 10 for 93% of real developer questions
   ([benchmarks](https://github.com/jcode-works/jcode-ragmir#benchmarks)).
 - **Evidence you can verify:** citations point to source lines or native page, slide, sheet/cell,
-  and EPUB coordinates. Expansion can detect when indexed evidence has changed.
-- **Private by default:** the `local-hash` provider works offline without downloading a model.
-  Semantic embeddings are an explicit option.
-- **Safe to keep running:** incremental, resumable ingestion and validated rebuilds. Search keeps
-  working while an upgrade rebuilds the index.
+  and EPUB coordinates. Results flag changed files (`sourceStatus`) and thin support
+  (`weakEvidence`); unrelated questions return nothing.
+- **Always current:** `rgr doctor` checks the files on disk on every run, and `rgr hooks install`
+  refreshes the index after commits, merges, and checkouts.
+- **Private and portable:** offline by default, with no account or telemetry, and the same paths,
+  exclusions, and citations on Linux, macOS, and Windows.
 
 ## Install and search
 
@@ -37,9 +38,20 @@ npx rgr search "authentication contract" --compact
 ```
 
 `rgr setup` creates ignored local state under `.ragmir/` and installs the selected agent helpers.
-The [quick start](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/quick-start.md) also
+A committed `ragmir.config.json` shares sources and settings with your team. The
+[quick start](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/quick-start.md) also
 covers pnpm and guided setup.
 
+## Connect your agent
+
+`rgr setup --agents claude,codex` prepares a project MCP server and a retrieval skill. The server
+exposes four read-only tools: `ragmir_search` (one question or up to five related ones sharing a
+budget, with named scopes), `ragmir_expand`, `ragmir_status`, and `ragmir_audit`. Passages
+already returned in a session come back as one-line stubs. Its instructions name the base it
+serves, and it warns or refuses agents working in unrelated projects. See
+[agent integration](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/agent-integration.md)
+for connection steps and local or self-hosted model examples.
+
 ## TypeScript API
 
 Use one client per project root in a long-running process and close it during shutdown:
@@ -51,7 +63,7 @@ const ragmir = await createRagmirClient({ cwd: process.cwd() })
 try {
   const passages = await ragmir.search("authentication contract", { topK: 3 })
   for (const passage of passages) {
-    console.log(passage.citation, passage.text)
+    console.log(passage.citation, passage.weakEvidence ? "(verify)" : "", passage.text)
   }
   if (passages[0]) {
     console.log(await ragmir.expandCitation(passages[0].citation, {
@@ -66,43 +78,25 @@ try {
 The library also exports top-level `ingest`, `search`, and `expandCitation` functions for one-shot
 scripts. See the [API reference](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/api-reference.md).
 
-## MCP for developer agents
+## Four workflow examples
 
-`rgr setup --agents claude,codex` prepares a local MCP helper and a retrieval skill for the agents
-you select. The server exposes four bounded tools: `ragmir_status`, `ragmir_search`,
-`ragmir_expand`, and `ragmir_audit`. An agent can search compact results, open an exact cited
-passage, and search again when the evidence is incomplete. The consuming agent owns reasoning,
-generation, and actions. See [agent integration](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/agent-integration.md)
-for connection steps and local or self-hosted model examples.
+1. **Build a feature with Claude Code or Codex.** The agent finds the specification rules and ADR
+   exceptions with Ragmir, opens the cited passages, then changes the code and tests.
+2. **Diagnose an incident with Claude Code or Codex.** It retrieves the runbook, incident report,
+   and retry implementation before it changes code and adds a regression test.
+3. **Plan an API migration with Claude Code or Codex.** It retrieves compatibility, rollback, and
+   versioning rules before it updates callers and migration tests.
+4. **Make a confidential architecture decision.** A local or self-hosted chat retrieves cited
+   evidence and sends it to a model you run, with remote calls disabled.
 
-## Four workflow examples
+## Documents, semantic retrieval, and OCR
+
+Index Markdown, code, JSON, CSV, HTML, PDF, DOCX, XLSX, PPTX, OpenDocument, EPUB, and RTF; scanned
+PDFs, photos, and legacy `.doc` files use local extractors (`rgr ocr setup --images
+--legacy-word`). The default `local-hash` provider needs no model download. For semantic
+embeddings, install `@huggingface/transformers` and run `npx rgr setup --semantic`.
 
-1. **Build a feature with Claude Code or Codex.** Ask the agent to implement account recovery from
-   the project's specification and ADR. It searches with Ragmir, opens cited passages, checks
-   exceptions, then changes the code and tests.
-2. **Diagnose an incident with Claude Code or Codex.** Ask the agent to investigate a checkout
-   timeout from the runbook, incident report, and retry implementation before it changes code and
-   adds a regression test.
-3. **Plan an API migration with Claude Code or Codex.** Ask the agent to retrieve compatibility,
-   rollback, and versioning rules from the migration plan and ADR before it updates callers and
-   migration tests.
-4. **Make a confidential architecture decision.** Ask a local or self-hosted chat whether internal
-   architecture rules call for attachments in PostgreSQL or object storage. The chat retrieves cited
-   evidence with Ragmir and sends it to a downloaded Ollama model with remote calls disabled, or to
-   a model on your own server.
-
-## Retrieval options and documents
-
-The default `local-hash` provider ranks BM25 keyword evidence first and uses deterministic local
-vectors to break ties. For semantic embeddings, install `@huggingface/transformers`, then run `npx rgr setup --semantic` to
-download and enable the selected embedding model. Index Markdown, code, JSON, CSV, HTML, PDF,
-DOCX, XLSX, PPTX, OpenDocument, EPUB, and RTF. Scanned PDF pages require a supported local OCR
-engine: inspect `npx rgr ocr doctor`, then configure it with `npx rgr ocr setup`.
-
-The index stays on the machine running Ragmir, but retrieved text is not masked. With an entirely
-local consumer it can stay there; a self-hosted or cloud consumer receives the selected passages.
-Confidentiality depends on the full setup, including access controls, transport, tools, and logs.
-Ragmir has no telemetry or hosted storage.
+For guided setup, give your agent this prompt:
 
 <!-- ragmir-setup-prompt:start -->
 <details>
@@ -121,7 +115,7 @@ Outcome: Ragmir installed with the repository's package manager; useful sources
 2. Configure:
 - Install @jcode.labs/ragmir with the detected manager. Default to offline local-hash. Semantic retrieval additionally requires @huggingface/transformers and an explicitly approved model download; use rgr setup --semantic only after that approval.
 - Run rgr setup --no-ingest --agents <selected> with the detected manager. Keep project scope. Review an unmanaged same-name skill before using --force-agent-skills.
-- Select narrow relative source globs in .ragmir/config.json: guidance, docs/specs/ADRs, package READMEs, useful config, source, and tests. Scope nested bases separately and keep shared knowledge at the root.
+- Select narrow relative source globs in ragmir.config.json (committed) or .ragmir/config.json: guidance, docs/specs/ADRs, package READMEs, useful config, source, and tests. Set name and description so agents know which project the base serves. Scope nested bases separately and keep shared knowledge at the root.
 - Exclude .env*, credentials, keys, unapproved private data, dependencies, generated/build/cache/coverage/log folders, vendored files, and Ragmir storage/models. Review external folders before including them.
 - Ragmir preserves source text without masking. The consuming application controls where passages go. For confidential work, use a local or self-hosted model and control the client, access, transport, and logs.
 - Keep useful document formats. For scanned PDFs, inspect rgr ocr doctor and configure local OCR with rgr ocr setup only when needed and authorized.
@@ -129,11 +123,11 @@ Outcome: Ragmir installed with the repository's package manager; useful sources
 3. Index and connect:
 - Run rgr preview --json and rgr audit --unsupported. Review source coverage, skipped files, duplicates, chunk structure, and citation coordinates; fix config before ingesting.
 - Run rgr ingest. For an incompatible old installation, run rgr upgrade, which backs up retired config and stages a replacement index. Never delete the active index first.
-- Connect the generated MCP helper or native retrieval skill for the selected agents. Verify the owning base with rgr bases --json or ragmir_status.
+- Connect the generated MCP helper or native retrieval skill for the selected agents, registered per project, never for every project. Verify the owning base with rgr bases --json or ragmir_status. Offer rgr hooks install to refresh the index after Git operations.
 - Use ragmir_search for compact citations, then ragmir_expand for one exact passage. The consuming agent handles reasoning and synthesis with its chosen model.
 
 4. Verify:
-- Run rgr doctor --deep, rgr audit --unsupported, and rgr security-audit.
+- Run rgr doctor --deep, rgr audit --unsupported, and rgr security-audit; fix reported source rules, MCP registration warnings, and index concentration.
 - Run representative searches with citations and --explain. Evaluate a small local golden suite for project questions with rgr evaluate; do not weaken gates to pass.
 - Report packages and downloads, selected sources/exclusions, changed files, readiness, citation examples, evaluation results, and any remaining actions.
 

package/dist/cli.js

@@ -10,15 +10,18 @@ import { doctor } from "./doctor.js";
 import { pullEmbeddingModel } from "./embeddings.js";
 import { evaluateGoldenQueries } from "./evaluate.js";
 import { countSkippedByReason } from "./files.js";
+import { checkIndexFreshness } from "./freshness.js";
 import { collectGenerationGarbage } from "./generation-retention.js";
+import { gitHooksStatus, installGitHooks, uninstallGitHooks, } from "./git-hooks.js";
 import { indexFreshnessWarning, manifestReady } from "./index-diagnostics.js";
 import { audit, ingest } from "./ingest.js";
 import { getIngestionProgress } from "./ingestion-state.js";
 import { initProject } from "./init.js";
-import { discoverKnowledgeBases, knowledgeBaseIdentity } from "./knowledge-bases.js";
+import { discoverKnowledgeBases, knowledgeBaseIdentity, knowledgeBaseProfile, } from "./knowledge-bases.js";
 import { ingestionLimits } from "./limits.js";
 import { serveMcp } from "./mcp.js";
-import { configurePdfOcr, extractPdfPage, extractPdfPages, inspectPdfOcr, parsePdfOcrEngine, parsePdfOcrPages, } from "./ocr.js";
+import { RAGMIR_CLIENT_CWD_ENV } from "./mcp-scope.js";
+import { configureLocalExtractors, configurePdfOcr, extractImageText, extractLegacyWordText, extractPdfPage, extractPdfPages, inspectLocalExtractors, inspectPdfOcr, parseLegacyWordEngine, parsePdfOcrEngine, parsePdfOcrPages, } from "./ocr.js";
 import { rgrCommand } from "./package-manager.js";
 import { previewChunks } from "./preview.js";
 import { search } from "./query.js";
@@ -83,48 +86,104 @@ modelsCommand
 });
 const ocrCommand = program
     .command("ocr")
-    .description("Configure and diagnose local OCR for scanned PDF pages.");
+    .description("Configure and diagnose local OCR for scanned PDFs, images, and legacy .doc files.");
 ocrCommand
     .command("doctor")
     .description("Detect supported local PDF OCR engines and installed languages.")
     .option("--json", "Print machine-readable JSON.")
     .action(async (options, command) => {
-    const status = await inspectPdfOcr(projectRoot(command));
+    const [status, local] = await Promise.all([
+        inspectPdfOcr(projectRoot(command)),
+        inspectLocalExtractors(),
+    ]);
     if (options.json) {
-        console.log(JSON.stringify(status, null, 2));
+        console.log(JSON.stringify({ ...status, local }, null, 2));
         return;
     }
     printPdfOcrStatus(status);
+    console.log(`imageOcr=${local.imageOcr.available ? "tesseract" : "unavailable"}${local.imageOcr.imageConverter ? ` (+${local.imageOcr.imageConverter} for HEIC/AVIF)` : ""}`);
+    console.log(`legacyWord=${local.legacyWord.recommendedEngine ?? "unavailable"}`);
+    if (local.imageOcr.available || local.legacyWord.recommendedEngine) {
+        console.log("Run `rgr ocr setup --images --legacy-word` to index photos and .doc files too.");
+    }
 });
 ocrCommand
     .command("setup")
-    .description("Detect a local PDF OCR engine and write a safe batched-page configuration.")
-    .option("--engine <engine>", "OCR engine: auto, ocrmypdf, or tesseract.", "auto")
+    .description("Detect local OCR and converters, then configure scanned PDFs, images, and legacy .doc files.")
+    .option("--engine <engine>", "PDF OCR engine: auto, ocrmypdf, or tesseract.", "auto")
     .option("--language <codes>", "Tesseract language codes such as eng, fra, or eng+fra.", "eng")
     .option("--timeout-ms <number>", "Per-batch OCR timeout in milliseconds.", parsePositiveInt)
+    .option("--no-pdf", "Leave scanned-PDF OCR unchanged.")
+    .option("--images", "Also OCR photos and scanned images (PNG, JPEG, TIFF, HEIC, ...).")
+    .option("--legacy-word", "Also extract legacy Word .doc files with a local converter.")
     .option("--json", "Print machine-readable JSON.")
     .action(async (options, command) => {
-    const configureOptions = {
-        cwd: projectRoot(command),
-        engine: parsePdfOcrEngine(options.engine, true),
-        language: options.language,
-    };
-    addOption(configureOptions, "timeoutMs", options.timeoutMs);
-    const result = await configurePdfOcr(configureOptions);
+    const cwd = projectRoot(command);
+    let pdf = null;
+    if (options.pdf) {
+        const configureOptions = {
+            cwd,
+            engine: parsePdfOcrEngine(options.engine, true),
+            language: options.language,
+        };
+        addOption(configureOptions, "timeoutMs", options.timeoutMs);
+        pdf = await configurePdfOcr(configureOptions);
+    }
+    const local = options.images || options.legacyWord
+        ? await configureLocalExtractors({
+            cwd,
+            language: options.language,
+            ...(options.images ? { images: true } : {}),
+            ...(options.legacyWord ? { legacyWord: true } : {}),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        })
+        : null;
     if (options.json) {
-        console.log(JSON.stringify(result, null, 2));
+        console.log(JSON.stringify({ pdf, local }, null, 2));
         return;
     }
-    console.log(pc.green("Local PDF OCR configured."));
-    console.log(`engine=${result.engine}`);
-    console.log(`language=${result.language}`);
-    console.log(`timeoutMs=${result.timeoutMs}`);
-    console.log(`configPath=${result.configPath}`);
+    if (pdf) {
+        console.log(pc.green("Local PDF OCR configured."));
+        console.log(`engine=${pdf.engine}`);
+        console.log(`language=${pdf.language}`);
+        console.log(`timeoutMs=${pdf.timeoutMs}`);
+        console.log(`configPath=${pdf.configPath}`);
+    }
+    if (local?.imageOcrCommand) {
+        console.log(pc.green("Local image OCR configured."));
+    }
+    if (local?.legacyWordCommand) {
+        console.log(pc.green(`Legacy Word extraction configured (${local.legacyWordCommand.at(-3)}).`));
+    }
     console.log("");
     console.log("Next steps:");
-    console.log("  1. Run `rgr ingest` to index scanned PDF pages with local OCR.");
+    console.log("  1. Run `rgr ingest` to index the newly readable files with local OCR.");
     console.log("  2. Run `rgr doctor` to confirm complete coverage.");
 });
+ocrCommand
+    .command("extract-image", { hidden: true })
+    .requiredOption("--input <path>", "Image file to read.")
+    .option("--language <codes>", "Tesseract language codes.", "eng")
+    .option("--timeout-ms <number>", "OCR timeout in milliseconds.", parsePositiveInt)
+    .action(async (options, command) => {
+    process.stdout.write(await extractImageText({
+        input: path.resolve(projectRoot(command), options.input),
+        language: options.language,
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    }));
+});
+ocrCommand
+    .command("extract-doc", { hidden: true })
+    .requiredOption("--input <path>", "Legacy Word file to read.")
+    .requiredOption("--engine <engine>", "Converter: textutil, antiword, catdoc, or soffice.")
+    .option("--timeout-ms <number>", "Conversion timeout in milliseconds.", parsePositiveInt)
+    .action(async (options, command) => {
+    process.stdout.write(await extractLegacyWordText({
+        input: path.resolve(projectRoot(command), options.input),
+        engine: parseLegacyWordEngine(options.engine),
+        ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+    }));
+});
 ocrCommand
     .command("extract-page", { hidden: true })
     .requiredOption("--engine <engine>", "OCR engine: ocrmypdf or tesseract.")
@@ -449,6 +508,7 @@ program
     .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("--scope <name>", "Search a named scope from the config's `scopes`.")
     .option("--explain", "Include hybrid score contributions, ranks, and matched terms.")
     .option("--exact-vector-search", "Bypass ANN and use exhaustive vector search for diagnostics.")
     .option("--compact", "Return short snippets instead of full passages.")
@@ -481,7 +541,13 @@ program
     }
     for (const [index, result] of outputResults.entries()) {
         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}`);
+        const flags = [
+            result.sourceStatus === undefined
+                ? null
+                : pc.yellow(`source ${result.sourceStatus} since indexing`),
+            result.weakEvidence ? pc.yellow("weak evidence") : null,
+        ].filter((flag) => flag !== null);
+        console.log(`\n${pc.cyan(`[${index + 1}] ${result.citation}`)} chunk=${result.chunkIndex} distance=${distance}${flags.length > 0 ? ` ${flags.join(" ")}` : ""}`);
         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";
@@ -675,8 +741,12 @@ program
     const freshnessWarning = indexFreshnessWarning(config, manifest);
     const ready = manifestReady(manifest, freshnessWarning);
     const ingestion = await getIngestionProgress(config);
+    const profile = knowledgeBaseProfile(config);
+    const sourceFreshness = manifest ? await checkIndexFreshness(config) : null;
     const status = {
         knowledgeBaseId: identity?.id ?? null,
+        knowledgeBase: { name: profile.name, description: profile.description },
+        scopes: profile.scopes,
         projectRoot: config.projectRoot,
         rawDir: config.rawDir,
         storageDir: config.storageDir,
@@ -708,6 +778,7 @@ program
         indexedFiles: manifest?.fileCount ?? 0,
         chunksIndexed: manifest?.chunkCount ?? 0,
         health: health ?? null,
+        sourceFreshness,
         maintenance: manifest?.maintenance ?? null,
         ingestion,
     };
@@ -715,8 +786,15 @@ program
         console.log(JSON.stringify(status, null, 2));
         return;
     }
+    console.log(`knowledgeBase=${profile.name}`);
+    if (profile.description) {
+        console.log(`description=${profile.description}`);
+    }
     console.log(`knowledgeBaseId=${identity?.id ?? "none"}`);
     console.log(`projectRoot=${config.projectRoot}`);
+    if (profile.scopes.length > 0) {
+        console.log(`scopes=${profile.scopes.map((scope) => scope.name).join(",")}`);
+    }
     console.log(`rawDir=${config.rawDir}`);
     console.log(`storageDir=${config.storageDir}`);
     console.log(`sourcesFile=${config.sourcesFile}`);
@@ -745,6 +823,12 @@ program
     console.log(`corpusFingerprint=${manifest?.corpusFingerprint ?? "unavailable"}`);
     console.log(`indexedFiles=${manifest?.fileCount ?? 0}`);
     console.log(`chunksIndexed=${manifest?.chunkCount ?? 0}`);
+    if (sourceFreshness?.verified) {
+        console.log(`sourceFreshness=verified missingFromIndex=${sourceFreshness.missingFromIndex} staleInIndex=${sourceFreshness.staleInIndex}`);
+    }
+    else if (sourceFreshness) {
+        console.log(`sourceFreshness=unverified (${sourceFreshness.error ?? "unknown"})`);
+    }
     if (freshnessWarning) {
         console.log(`indexFreshnessWarning=${freshnessWarning}`);
     }
@@ -811,13 +895,15 @@ storageCommand
 });
 storageCommand
     .command("gc")
-    .description("Inspect or reclaim expired local index generations.")
+    .description("Reclaim expired index generations and report disk usage and orphaned models or copies.")
     .option("--dry-run", "Report generation roles and reclaimable bytes without deleting tables.")
+    .option("--orphans", "Also delete the listed orphans: unused models (including retired chat models), storage copies, and retired outputs.")
     .option("--json", "Print machine-readable JSON.")
     .action(async (options, command) => {
     const report = await collectGenerationGarbage({
         cwd: projectRoot(command),
         ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+        ...(options.orphans === undefined ? {} : { orphans: options.orphans }),
     });
     if (options.json) {
         console.log(JSON.stringify(report, null, 2));
@@ -848,6 +934,36 @@ storageCommand
         process.exitCode = 1;
     }
 });
+const hooksCommand = program
+    .command("hooks")
+    .description("Refresh the index automatically after commits, merges, checkouts, and rebases.");
+hooksCommand
+    .command("install")
+    .description("Add a background `rgr ingest` to the Git hooks of this repository.")
+    .option("--force", "Also edit hooks in a directory tracked by the working tree, such as .husky.")
+    .option("--json", "Print machine-readable JSON.")
+    .action(async (options, command) => {
+    const report = await installGitHooks({
+        cwd: projectRoot(command),
+        ...(options.force === undefined ? {} : { force: options.force }),
+    });
+    printGitHooks(report, options.json === true, "installed");
+});
+hooksCommand
+    .command("uninstall")
+    .description("Remove the Ragmir block from the Git hooks and keep any other hook content.")
+    .option("--json", "Print machine-readable JSON.")
+    .action(async (options, command) => {
+    const report = await uninstallGitHooks({ cwd: projectRoot(command) });
+    printGitHooks(report, options.json === true, "removed");
+});
+hooksCommand
+    .command("status")
+    .description("Show which Git hooks refresh the index.")
+    .option("--json", "Print machine-readable JSON.")
+    .action(async (options, command) => {
+    printGitHooks(await gitHooksStatus({ cwd: projectRoot(command) }), options.json === true);
+});
 program
     .command("destroy-index")
     .description("Remove the generated local vector index from Ragmir storage.")
@@ -869,6 +985,7 @@ program
     .description("Start the MCP server over stdio for Claude, Codex, and other MCP-compatible agents.")
     .action(async (_options, command) => {
     const explicitRoot = explicitProjectRoot(command);
+    process.env[RAGMIR_CLIENT_CWD_ENV] ||= process.cwd();
     await serveMcp(explicitRoot);
 });
 program
@@ -956,6 +1073,27 @@ program
     console.log("  3. Wire the matching MCP helper if the agent should call Ragmir tools directly.");
     console.log(`  4. Run \`${(await rgrCommand(cwd, ["doctor"])).display}\`.`);
 });
+// Commands removed by the focused-retrieval release. Agents following old skills still call them,
+// so each one explains its replacement instead of failing as an unknown command.
+const RETIRED_COMMANDS = [
+    [
+        "ask",
+        "Search with `rgr search` and let your agent or chat write the answer from the citations.",
+    ],
+    ["research", "Let your agent loop over `rgr search` and citation expansion."],
+    ["chat", "Use your coding agent or a local or self-hosted chat with Ragmir citations."],
+    ["audio", "Send retrieved text to a separate text-to-speech tool."],
+];
+for (const [name, replacement] of RETIRED_COMMANDS) {
+    program
+        .command(name, { hidden: true })
+        .allowUnknownOption()
+        .allowExcessArguments()
+        .action(() => {
+        console.error(`\`rgr ${name}\` was removed: Ragmir now returns cited evidence and your agent writes the result. ${replacement} See https://github.com/jcode-works/jcode-ragmir/blob/main/docs/migration.md`);
+        process.exitCode = 1;
+    });
+}
 try {
     await program.parseAsync(process.argv);
 }
@@ -975,6 +1113,7 @@ function explicitProjectRoot(command) {
 }
 function withSearchOptions(cwd, options) {
     const result = { cwd };
+    addOption(result, "scope", options.scope);
     addOption(result, "topK", options.topK);
     addOption(result, "maxChunksPerDocument", options.maxChunksPerDocument);
     addOption(result, "contextRadius", options.contextRadius);
@@ -1022,6 +1161,9 @@ function printDoctor(report) {
     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 server of report.agentIntegration.mcpServers) {
+        console.log(`agentIntegration.mcpServer=${server.client}:${server.scope}:${server.name} servedRoot=${server.servedRoot ?? "unknown"}${server.approval ? ` approval=${server.approval}` : ""}`);
+    }
     for (const warning of report.agentIntegration.warnings) {
         console.log(pc.yellow(`agentIntegration.warning: ${warning}`));
     }
@@ -1040,6 +1182,10 @@ function printDoctor(report) {
     console.log(`chunksIndexed=${report.chunksIndexed}`);
     console.log(`missingFromIndex=${report.missingFromIndex}`);
     console.log(`staleInIndex=${report.staleInIndex}`);
+    console.log(`coverageVerified=${report.readiness.coverageComplete || report.sourceFreshness?.verified === true || report.inventoryVerified}`);
+    if (report.sourceFreshness?.verified === false) {
+        console.log(pc.yellow(`sourceFreshness: ${report.sourceFreshness.error ?? "unverified"}`));
+    }
     console.log(`corpusFingerprint=${report.corpusFingerprint ?? "unavailable"}`);
     console.log(`securityWarnings=${report.securityWarnings.length}`);
     if (report.securityWarnings.length > 0) {
@@ -1092,16 +1238,40 @@ function printStorageMaintenance(report) {
         console.log(pc.yellow(`warning: ${report.warning}`));
     }
 }
+function printGitHooks(report, json, action) {
+    if (json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    if (action) {
+        console.log(report.changed.length > 0
+            ? pc.green(`Ragmir auto-ingest ${action} in ${report.changed.join(", ")}.`)
+            : `Git hooks already ${action === "installed" ? "refresh" : "skip"} the index.`);
+    }
+    console.log(`hooksDir=${report.hooksDir}`);
+    console.log(`installed=${report.installed.join(",") || "none"}`);
+    if (report.missing.length > 0) {
+        console.log(`missing=${report.missing.join(",")}`);
+    }
+}
 function printGenerationGarbageCollection(report) {
     console.log(`activeTableName=${report.activeTableName}`);
     console.log(`resumableTableName=${report.resumableTableName ?? "none"}`);
     console.log(`rollbackTableName=${report.rollbackTableName ?? "none"}`);
     console.log(`generations=${report.generations.length}`);
+    console.log(`storageDiskBytes=${report.storageDiskBytes}`);
     console.log(`reclaimableBytes=${report.reclaimableBytes}`);
     console.log(`reclaimedBytes=${report.reclaimedBytes}`);
     console.log(`deletedTables=${report.deletedTables.join(",")}`);
     for (const generation of report.generations) {
-        console.log(`generation=${generation.tableName} role=${generation.role} bytes=${generation.bytes} ageMs=${generation.ageMs} leased=${generation.leased} reclaimable=${generation.reclaimable} deleted=${generation.deleted}`);
+        console.log(`generation=${generation.tableName} role=${generation.role} bytes=${generation.bytes} diskBytes=${generation.diskBytes} ageMs=${generation.ageMs} leased=${generation.leased} reclaimable=${generation.reclaimable} deleted=${generation.deleted}`);
+    }
+    for (const orphan of report.orphans) {
+        const removed = report.removedOrphans.includes(orphan.path);
+        console.log(`orphan=${orphan.path} kind=${orphan.kind} diskBytes=${orphan.diskBytes} removed=${removed} reason=${JSON.stringify(orphan.reason)}`);
+    }
+    if (report.orphans.length > 0 && report.removedOrphans.length === 0) {
+        console.log("Run `rgr storage gc --orphans` to delete the orphans listed above.");
     }
     if (report.warning) {
         console.log(pc.yellow(`warning: ${report.warning}`));