@jcode.labs/ragmir 2.9.2 → 2.9.3

package/README.md

@@ -1,50 +1,70 @@
 # Ragmir Core
 
-`@jcode.labs/ragmir` is the main Ragmir package. It provides the `rgr` command-line interface, a
-TypeScript retrieval API, a local MCP server, and portable agent helpers.
+[![npm version](https://img.shields.io/npm/v/@jcode.labs/ragmir)](https://www.npmjs.com/package/@jcode.labs/ragmir)
+[![npm downloads](https://img.shields.io/npm/dm/@jcode.labs/ragmir)](https://www.npmjs.com/package/@jcode.labs/ragmir)
+[![Node.js](https://img.shields.io/node/v/@jcode.labs/ragmir)](https://www.npmjs.com/package/@jcode.labs/ragmir)
+[![MIT](https://img.shields.io/npm/l/@jcode.labs/ragmir)](https://github.com/jcode-works/jcode-ragmir/blob/main/LICENSE)
 
-Use it when a repository needs searchable, cited context without uploading its documents to a hosted
-knowledge base. It is retrieval-first: the default `local-hash` mode works offline, without an
-account or model download.
+**The CLI, TypeScript API, and local MCP server for cited project retrieval.**
 
-## Choose this package when you need
+`@jcode.labs/ragmir` indexes the files a project selects and returns source-backed passages without
+a hosted document store. The default `local-hash` retrieval path works offline, without an account
+or model download.
 
-| Need | What Core provides |
+[Project overview](https://github.com/jcode-works/jcode-ragmir#readme) ·
+[CLI reference](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/cli-reference.md) ·
+[API reference](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/api-reference.md)
+
+## Install Core when you need
+
+| Goal | Core interface |
 | --- | --- |
-| Search project documents from a terminal | `rgr search` with source citations. |
-| Give an AI agent bounded access to repository context | A local stdio MCP server and generated helpers. |
-| Build retrieval into a Node.js tool | A typed TypeScript API for ingesting and searching. |
-| Index PDFs, Markdown, source files, Office files, HTML, or CSV | Local extraction, redaction, chunking, and storage. |
-| Work with a confidential repository offline | Ignored local `.ragmir/` state and offline-first retrieval. |
+| Search repository documents with citations | `rgr search` |
+| Audit a local knowledge base | `rgr audit`, `rgr doctor`, and `rgr security-audit` |
+| Add retrieval to a Node.js application | Typed `ingest`, `search`, `ask`, and `research` exports |
+| Give an AI agent bounded project context | Local stdio MCP server and generated helpers |
+| Index scanned PDFs | Embedded text first, with optional page-aware local OCR |
 
-For answer generation, install the optional [Ragmir Chat](https://www.npmjs.com/package/@jcode.labs/ragmir-chat)
-package. For audio summaries, install [Ragmir TTS](https://www.npmjs.com/package/@jcode.labs/ragmir-tts).
+Core retrieves evidence. It does not require a generative model and does not produce an ungrounded
+answer. Add [Ragmir Chat](https://www.npmjs.com/package/@jcode.labs/ragmir-chat) only when local
+GGUF synthesis is useful, or [Ragmir TTS](https://www.npmjs.com/package/@jcode.labs/ragmir-tts)
+when you need audio output.
 
-## Quick start
+## First cited search
 
-Install Core in the repository that owns the documents you want to search:
+Requires Node.js 20 or later.
 
 ```bash
 npm install --save-dev @jcode.labs/ragmir
 npx rgr setup
-npx rgr sources add "docs/**/*.md"
+npx rgr sources add "README.md" "docs/**/*.md"
 npx rgr ingest
-npx rgr search "Which decision changed the deployment?"
+npx rgr search "Which decision changed the rollout?"
 ```
 
-`rgr setup` creates ignored local state. `rgr ingest` incrementally extracts text, applies configured
-redaction, chunks the content, and writes the local index. Every search result identifies its source
-file, excerpt, chunk, and PDF page when available.
+The project now owns an ignored `.ragmir/` directory containing configuration and generated local
+state. Ingestion is incremental, and every result identifies the source path, chunk, line range, and
+PDF page when one is available.
 
-## How it works
+## CLI essentials
 
-1. Select files with `rgr sources add` or `.ragmir/sources.txt`.
-2. Ragmir extracts and redacts text locally, then writes a local index under `.ragmir/`.
-3. `rgr search`, the TypeScript API, and MCP return ranked passages with citations.
-4. Semantic embeddings, OCR, local chat, and audio are explicit opt-ins.
+```bash
+# Readiness and source coverage
+npx rgr doctor
+npx rgr audit --unsupported
+npx rgr security-audit
+
+# Retrieval
+npx rgr search "deployment decision"
+npx rgr ask "What evidence supports the deployment decision?"
+npx rgr research "deployment obligations" --compact
+
+# Machine-readable output
+npx rgr search "deployment decision" --json
+```
 
-For a scanned PDF, OCR runs only on pages that have no embedded text, through a command configured on
-your machine. Ragmir never sends PDF pages to a cloud OCR service.
+`ask` returns cited retrieval context, not LLM synthesis. `research` performs an audit-backed,
+multi-query retrieval pass and reports missing or weak evidence.
 
 ## TypeScript API
 
@@ -53,39 +73,100 @@ import { ingest, search } from "@jcode.labs/ragmir"
 
 await ingest({ cwd: process.cwd() })
 
-const results = await search("Which decision changed the deployment?", { topK: 5 })
+const results = await search("Which decision changed the rollout?", {
+  cwd: process.cwd(),
+  topK: 5,
+})
 
 for (const result of results) {
-  console.log(result.relativePath, result.citation, result.text)
+  console.log(result.citation, result.text)
 }
 ```
 
-Use `ask()` for cited retrieval context without an LLM, `research()` for audit-backed multi-query
-retrieval, and `serveMcp()` to start the local MCP server from your own integration.
+Frequently used exports:
+
+| Export | Purpose |
+| --- | --- |
+| `setupProject`, `addSourceEntries` | Initialize project state and select files |
+| `ingest`, `audit` | Build the index and compare it with files on disk |
+| `search`, `ask`, `research` | Retrieve cited passages at different levels of breadth |
+| `doctor`, `securityAudit` | Inspect readiness and local privacy posture |
+| `serveMcp` | Start the read-focused local MCP server |
+| `configurePdfOcr`, `inspectPdfOcr` | Configure and inspect local PDF OCR |
 
-## Agent setup
+See the [complete API reference](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/api-reference.md)
+for options and result shapes.
 
-Generate local MCP helpers for the agents used by the repository:
+## Connect an AI agent
 
 ```bash
 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
+exposes status, search, ask, research, audit, evaluation, usage, and security tools. It does not
+expose index deletion.
+
+## Retrieval modes
+
+| Mode | Network requirement | Best for |
+| --- | --- | --- |
+| `local-hash` | None | Default offline retrieval, setup-free projects, and deterministic evaluation |
+| `transformers` | Explicit model preload or download | Higher-quality semantic matching with local inference |
+
+Enable semantic retrieval explicitly:
+
+```bash
+npx rgr setup --semantic
+npx rgr ingest --rebuild
+```
+
+`local-hash` is lexical/hash retrieval. It should not be presented as equivalent to semantic
+embeddings.
+
+## Documents and OCR
+
+Core parses common source, text, structured-data, Office, OpenDocument, EPUB, HTML, email, notebook,
+and PDF formats. Projects can add custom text extensions. Run `rgr audit --unsupported` to see every
+skipped file and recommendation.
+
+For scanned PDFs:
+
+```bash
+npx rgr ocr setup --engine auto
+npx rgr ingest --rebuild
 ```
 
-The generated helper points the agent at the current project, never at Ragmir's package installation
-directory. Retrieval stays bounded and read-focused.
+Ragmir prefers embedded PDF text and invokes OCR only for blank pages. OCR runs through a configured
+local executable, never a shell string or cloud OCR service.
+
+## Local data and privacy
 
-## Technology and local data
+- Project paths resolve from `cwd` or explicit configuration, not the npm installation directory.
+- Generated indexes, models, reports, audio, and access logs belong under ignored `.ragmir/` state.
+- Redaction runs before indexing when configured, but it is not a compliance certification.
+- External extractors and model downloads are opt-in system boundaries.
+- MCP retrieval is bounded and access logs contain metadata, not query text or retrieved passages.
 
-Core is TypeScript for Node.js 20 or later. It uses LanceDB for local storage, the Model Context
-Protocol TypeScript SDK for agent integration, and Transformers.js only when semantic retrieval is
-explicitly enabled. Its generated `.ragmir/` state is local and should stay ignored by Git.
+Read [configuration and privacy](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/configuration.md)
+and [security hardening](https://github.com/jcode-works/jcode-ragmir/blob/main/SECURITY-HARDENING.md)
+before indexing sensitive material.
+
+## Runnable examples
+
+| Example | Demonstrates |
+| --- | --- |
+| [Sovereign RAG demo](https://github.com/jcode-works/jcode-ragmir/tree/main/packages/ragmir-core/examples/sovereign-rag-demo) | CLI ingestion, search, audit, redaction, and evaluation |
+| [Library API demo](https://github.com/jcode-works/jcode-ragmir/tree/main/packages/ragmir-core/examples/library-api-demo) | The public library surface against fictional files |
+| [Document evidence benchmark](https://github.com/jcode-works/jcode-ragmir/tree/main/packages/ragmir-core/examples/document-evidence-benchmark) | Recall and exact citation evaluation |
 
-## Further reading
+## Documentation
 
-- [Ragmir overview and package comparison](https://github.com/jcode-works/jcode-ragmir#readme)
 - [CLI reference](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/cli-reference.md)
 - [TypeScript API reference](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/api-reference.md)
-- [Configuration and privacy](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/configuration.md)
+- [Configuration](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/configuration.md)
 - [Agent integration](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/agent-integration.md)
+- [Troubleshooting](https://github.com/jcode-works/jcode-ragmir/blob/main/docs/troubleshooting.md)
 
-Ragmir is open source under the [MIT License](https://github.com/jcode-works/jcode-ragmir/blob/main/LICENSE).
+Ragmir Core is open source under the [MIT License](https://github.com/jcode-works/jcode-ragmir/blob/main/LICENSE).

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "2.9.2";
+export declare const VERSION = "2.9.3";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "2.9.2";
+export const VERSION = "2.9.3";
 //# sourceMappingURL=version.js.map

package/examples/document-evidence-benchmark/README.md

@@ -1,36 +1,90 @@
-# Document Evidence Benchmark
+# Document evidence benchmark
 
-Synthetic document benchmark for Ragmir retrieval. It is intentionally safe to commit: the contract,
-RFP, runbook, spec, and legal/tax notes are fictional and contain no customer data.
+A deterministic, public-safe benchmark for Ragmir retrieval and citation quality.
 
-This benchmark checks three things:
+Use this example when you want to prove more than "a relevant file appeared." Its six golden queries
+check that Ragmir retrieves the expected path and the exact file, line, chunk, or PDF-page citation.
+Every document is fictional and safe to commit.
 
-- `Recall@K`: each query retrieves the expected source file or passage.
-- exact citations: each query retrieves the expected `relative/path:Lx-Ly#chunkIndex` citation.
-- embedded PDF text: the synthetic PDF is extracted and retrieved with an exact
-  `relative/path:p1:Lx-Ly#chunkIndex` page citation.
+## What it measures
 
-The corpus is small on purpose so every source file fits in a single chunk. That keeps the expected
-citations deterministic while exercising the same CLI path used for private dogfooding.
+| Signal | What a passing result means |
+| --- | --- |
+| `Recall@K` | An expected source path appears within the configured top K results |
+| Exact text citation | The expected `relative/path:Lx-Ly#chunkIndex` is returned |
+| Exact PDF citation | The expected `relative/path:pN:Lx-Ly#chunkIndex` is returned |
 
-## Run From This Repository Checkout
+The corpus is intentionally small enough for each source to fit in one chunk. That makes citation
+expectations stable while exercising the same ingestion and evaluation code used for private
+knowledge bases.
 
-Build Ragmir once from the repository root:
+## Corpus
+
+| Fictional source | Evidence type |
+| --- | --- |
+| `raw/contracts/master-services-agreement.md` | Contract and residency obligations |
+| `raw/contracts/pdf-control-evidence.pdf` | Embedded PDF text with a page citation |
+| `raw/rfp/security-questionnaire.md` | Security and hosting requirements |
+| `raw/runbooks/incident-response-runbook.md` | Operational evidence collection |
+| `raw/specs/agent-integration-spec.md` | Agent and retrieval boundaries |
+| `raw/legal-tax/residency-review-note.md` | Professional-review disclaimer |
+
+[`golden-queries.json`](./golden-queries.json) maps each test query to its expected path and exact
+citation.
+
+## Run the benchmark
+
+From the repository root, install dependencies and build the packages:
 
 ```bash
+pnpm install --frozen-lockfile
 pnpm build
 ```
 
-Then run the benchmark from this folder:
+Then run the benchmark from this directory:
 
 ```bash
 cd packages/ragmir-core/examples/document-evidence-benchmark
 node ../../dist/cli.js init
-node ../../dist/cli.js ingest
+node ../../dist/cli.js ingest --rebuild
 node ../../dist/cli.js evaluate --golden golden-queries.json --json
 node ../../dist/cli.js evaluate --golden golden-queries.json --fail-under 1
 ```
 
-Use this example as a public-safe template for private document evaluations. Keep real contracts,
-RFPs, runbooks, tax notes, golden queries, and generated JSON reports outside Git or under ignored
-local Ragmir state.
+The last command exits non-zero unless every golden query succeeds at the configured threshold.
+Keep the JSON output when you need machine-readable evidence for CI or a retrieval-quality review.
+
+## Read a failure
+
+1. Check `rgr audit` for missing, stale, or skipped source files.
+2. Inspect the failed query's returned paths and citations in JSON output.
+3. Decide whether the corpus, expected citation, chunking, or retrieval mode changed.
+4. Update a golden expectation only when the intended product behavior changed.
+
+Do not lower `--fail-under` merely to make a regression pass.
+
+## Adapt it to a private corpus
+
+Copy the structure, not the fictional documents:
+
+```text
+private-evaluation/
+├── .ragmir/config.json
+├── golden-queries.json
+└── raw/
+```
+
+For each important question, record the smallest set of expected source paths. Add exact citations
+when the source is stable enough to make line, page, and chunk boundaries meaningful. Keep private
+contracts, RFPs, runbooks, tax notes, scans, golden queries, and evaluation reports outside Git or
+under ignored local state.
+
+## Safety
+
+- The committed corpus contains no customer or production data.
+- The benchmark uses the offline `local-hash` provider and needs no model download.
+- Generated `.ragmir/storage` and evaluation output stay local and ignored.
+- A perfect synthetic score proves this fixture, not universal retrieval quality.
+
+Return to the [Ragmir Core README](../../README.md) or try the
+[sovereign RAG demo](../sovereign-rag-demo/README.md) for a broader CLI walkthrough.

package/examples/library-api-demo/README.md

@@ -1,43 +1,88 @@
-# Library API Demo
+# Library API demo
 
-Runnable smoke for the `@jcode.labs/ragmir` **library** API, meant for local development of Ragmir
-Core itself. Where [`sovereign-rag-demo`](../sovereign-rag-demo) drives the **CLI**
-(`node ../../dist/cli.js ...`), this demo `import`s the public TypeScript surface the same way an
-external consumer would:
+A runnable smoke test for the public `@jcode.labs/ragmir` TypeScript API.
 
-```js
-import { ask, audit, ingest, search } from "@jcode.labs/ragmir"
-```
+Use this example when you are changing Ragmir Core or evaluating it as a library rather than as a
+CLI. It imports the same package name an external consumer uses, runs the full retrieval loop, and
+prints cited results from a fictional local corpus.
+
+## What it proves
+
+The demo exercises four public operations in order:
+
+1. `ingest({ cwd, rebuild: true })` parses, redacts, chunks, embeds, and stores the corpus.
+2. `search(query, { cwd, topK })` returns ranked source passages.
+3. `ask(query, { cwd, topK })` returns retrieval-only cited context without LLM synthesis.
+4. `audit(cwd)` compares supported files with the current index.
 
-Node self-referencing resolves `@jcode.labs/ragmir` to this repository's local build
-(`packages/ragmir-core/dist`), **never** the npm-published package. So you can validate your local
-changes to the library end to end, without `npx` silently running a released version.
+Node's package self-reference resolves `@jcode.labs/ragmir` to this checkout's local
+`packages/ragmir-core/dist` build. It never falls back to the npm-published version, so the result
+reflects the code you are currently reviewing.
 
-## Run
+## Run it
 
 From the repository root:
 
 ```bash
+pnpm install --frozen-lockfile
 pnpm example
 ```
 
-That builds Ragmir Core, then runs the demo. It reuses the committed synthetic corpus from
-`sovereign-rag-demo`, so it needs no private documents and writes only to that example's gitignored
-`.ragmir/storage`.
+The root command builds the published packages required by Core and runs [`run.mjs`](./run.mjs). The
+output is organized into `ingest`, `search`, `ask`, and `audit` sections so a reviewer can see each
+public step succeed.
 
-To run it directly against the already-built `dist/` without rebuilding (run `pnpm build` first;
-`dist/` is gitignored, so a clean clone has none):
+To rerun only the script after an existing build:
 
 ```bash
 node packages/ragmir-core/examples/library-api-demo/run.mjs
 ```
 
-## What it exercises
+`dist/` is ignored, so a clean clone must be built at least once.
+
+## The public API pattern
+
+The essential integration is intentionally small:
+
+```js
+import { ask, audit, ingest, search } from "@jcode.labs/ragmir"
+
+await ingest({ cwd: projectRoot, rebuild: true })
+
+const results = await search("offline retrieval approval", {
+  cwd: projectRoot,
+  topK: 3,
+})
+
+const context = await ask("What evidence supports offline operation?", {
+  cwd: projectRoot,
+  topK: 3,
+})
+
+const report = await audit(projectRoot)
+```
+
+All project-relative state is resolved from `cwd`. This is the key boundary for applications that
+use Ragmir across more than one repository.
+
+## Data used by the demo
+
+The script reuses the sibling [sovereign RAG demo](../sovereign-rag-demo/README.md):
+
+- committed synthetic Markdown, CSV, JSONL, YAML, and custom text files;
+- an offline `local-hash` configuration;
+- gitignored `.ragmir/storage` output;
+- no private documents and no model download.
+
+Change the queries in `run.mjs` when testing a retrieval behavior, but keep the committed demo
+deterministic and public-safe. Use a separate ignored corpus for private evaluations.
+
+## When to use another example
 
-- `ingest({ cwd, rebuild: true })` — parse, redact, chunk, and embed the synthetic corpus.
-- `search(query, { cwd, topK })` — ranked cited passages.
-- `ask(query, { cwd, topK })` — retrieval-only cited context (no LLM synthesis in core).
-- `audit(cwd)` — indexed, supported, and skipped file counts.
+| Need | Example |
+| --- | --- |
+| Learn the complete CLI workflow | [Sovereign RAG demo](../sovereign-rag-demo/README.md) |
+| Measure exact paths and citations | [Document evidence benchmark](../document-evidence-benchmark/README.md) |
+| Explore every exported function and option | [Core API reference](../../README.md#typescript-api) |
 
-It uses `embeddingProvider: "local-hash"` (from the reused corpus config), so it runs fully offline
-with no model download.
+Return to the [Ragmir Core README](../../README.md) for installation, MCP, OCR, and privacy guidance.

package/examples/sovereign-rag-demo/README.md

@@ -1,76 +1,109 @@
-# Sovereign RAG Demo
+# Sovereign RAG demo
 
-Synthetic test workspace for Ragmir. It is intentionally safe to commit: every document is fictional,
-generic, and designed only to exercise local ingestion, retrieval, redaction, custom extensions, and
-security-audit flows.
+A complete, fictional workspace for learning Ragmir's local CLI workflow.
 
-This folder must never contain real-world sensitive, regulated, or production documents.
+Use this example to ingest several file types, search with citations, inspect privacy posture, find an
+unsupported file, evaluate golden queries, and prepare agent access. It runs with offline
+`local-hash` retrieval and contains no customer or production data.
 
-## What It Covers
+## Scenario
 
-- Markdown operational briefs.
-- CSV dataset inventories.
-- JSONL incident timelines.
-- YAML policy metadata.
-- A custom `.evidence` text extension enabled through `.ragmir/config.json`.
-- Unsupported/skipped-file reporting with recommendations through `audit --unsupported`.
+The corpus models an operations team reviewing whether an evidence workflow can stay local:
 
-## Run From This Repository Checkout
+| File | Role in the scenario |
+| --- | --- |
+| `raw/operations-brief.md` | Approval, ownership, and operating requirements |
+| `raw/dataset-inventory.csv` | Accepted and rejected datasets |
+| `raw/incident-timeline.jsonl` | Time-ordered operational evidence |
+| `raw/security-policy.yaml` | Model-loading and security rules |
+| `raw/review-notes.evidence` | Custom text extension configured for this project |
+| `raw/facility-scan.heic` | Deliberately unsupported file used by the audit example |
 
-Build Ragmir once from the repository root:
+## Run the full workflow
+
+From the repository root:
 
 ```bash
+pnpm install --frozen-lockfile
 pnpm build
 ```
 
-Then run the CLI from this folder:
+Then enter this example and run the local CLI build:
 
 ```bash
 cd packages/ragmir-core/examples/sovereign-rag-demo
 node ../../dist/cli.js init
+
 # POSIX only: this example deliberately uses a custom tracked rawDir.
 chmod 700 raw
+
 node ../../dist/cli.js security-audit
-node ../../dist/cli.js ingest
+node ../../dist/cli.js ingest --rebuild
 node ../../dist/cli.js search "offline retrieval approval"
-node ../../dist/cli.js search "dataset residency"
 node ../../dist/cli.js ask "What evidence supports offline operation?"
-node ../../dist/cli.js evaluate --golden golden-queries.json
+node ../../dist/cli.js research "sovereign deployment evidence" --compact
 node ../../dist/cli.js evaluate --golden golden-queries.json --fail-under 1
-node ../../dist/cli.js audit
 node ../../dist/cli.js audit --unsupported
 node ../../dist/cli.js status
 ```
 
-`init` is idempotent here and applies owner-only permissions to the copied `.ragmir` config. The
-example deliberately keeps documents under the custom tracked `raw/` path, so secure that directory
-explicitly on POSIX before a strict audit. Git and package archives cannot encode its `0700` mode.
+`init` is idempotent. Git and npm archives cannot preserve the example's intended `0700` raw-folder
+mode, so the explicit `chmod` keeps the raw corpus owner-only on POSIX systems.
 
-This example uses `embeddingProvider: "local-hash"`, so it does not require a model runtime.
-Retrieval is lexical/hash-based rather than model-semantic.
+The security audit still reports that `.ragmir/` is not fully ignored. That warning is expected only
+for this public fixture because it deliberately commits `.ragmir/config.json` and
+`.ragmir/sources.txt`. Generated storage, models, reports, audio, logs, and salts remain ignored.
+Normal private projects should ignore the complete `.ragmir/` directory.
 
-## Useful Test Queries
+## What to look for
 
-- `offline retrieval approval`
-- `dataset residency`
-- `incident containment evidence`
-- `who owns the usage review`
-- `what documents support sovereign deployment`
+- Search and ask output identify the source path and chunk.
+- `ask` returns cited passages, not a generated answer from a hosted LLM.
+- `research` combines several retrieval queries and reports source diagnostics.
+- The audit surfaces the fixture-specific tracked-config warning described above.
+- The golden evaluation finds the expected sources for all four questions.
+- `audit --unsupported` explains why the HEIC fixture was skipped and recommends local OCR.
+- `status` confirms the active provider and local index state.
+
+## Useful queries
+
+```text
+offline retrieval approval
+dataset residency
+incident containment evidence
+who owns the usage review
+what documents support sovereign deployment
+```
 
-## Agent Report Prompt
+Try a precise query first, then compare it with `research --compact` when the question spans several
+files.
 
-After running `rgr setup` in a real project, an MCP-compatible agent can use the generated
-`.ragmir/mcp.json`. For this synthetic demo, ask an agent:
+## Give the demo to an agent
 
-```plain text
+In a real project, `rgr setup` generates an MCP helper under `.ragmir/`. After setup, an
+MCP-compatible agent can follow a prompt like:
+
+```text
 Use Ragmir to inspect the local knowledge base, search for "offline retrieval approval", and write a
 cited Markdown report under .ragmir/reports/demo-sovereign-rag.md. Mention any unsupported or stale
 files reported by the audit.
 ```
 
-## Switch To Transformers Semantic Mode
+The report path stays under ignored local state. Do not commit generated reports that may contain
+retrieved project evidence.
+
+## Compare semantic retrieval
+
+The committed configuration uses:
+
+```json
+{
+  "embeddingProvider": "local-hash"
+}
+```
 
-To compare no-model retrieval with semantic local retrieval, change `.ragmir/config.json`:
+This is offline lexical/hash retrieval, not model-semantic search. To run a deliberate semantic
+comparison, configure a Transformers.js model, preload it under `.ragmir/models`, and rebuild:
 
 ```json
 {
@@ -82,22 +115,33 @@ To compare no-model retrieval with semantic local retrieval, change `.ragmir/con
 }
 ```
 
-Preload the model files under `.ragmir/models` for offline work, then rebuild the index:
-
 ```bash
-node ../../dist/cli.js ingest
-node ../../dist/cli.js ask "What documents support sovereign deployment?"
+node ../../dist/cli.js ingest --rebuild
 node ../../dist/cli.js evaluate --golden golden-queries.json --json
-node ../../dist/cli.js evaluate --golden golden-queries.json --fail-under 0.8 --json
 ```
 
-## Generated State
+Keep remote model loading disabled for an offline comparison. A lower semantic score may indicate
+that queries or thresholds need tuning, not that a gate should be weakened.
+
+## Generated state and cleanup
 
-Generated state stays local and ignored:
+All runtime state stays under the ignored directory:
 
-```plain text
+```text
 .ragmir/
 ```
 
-Do not replace these synthetic documents with real confidential files inside the Ragmir package
-repository.
+Remove only the generated index when you want a clean rerun:
+
+```bash
+node ../../dist/cli.js destroy-index --yes
+```
+
+Never replace the fictional fixtures in this package with real confidential documents. Use a
+separate ignored workspace for private dogfooding.
+
+## Continue exploring
+
+- [Library API demo](../library-api-demo/README.md): call the public TypeScript API.
+- [Document evidence benchmark](../document-evidence-benchmark/README.md): require exact paths and citations.
+- [Ragmir Core README](../../README.md): installation, MCP, OCR, and privacy reference.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcode.labs/ragmir",
-  "version": "2.9.2",
+  "version": "2.9.3",
   "description": "Ragmir Core: open-source sovereign local RAG for confidential datasets and AI agents.",
   "type": "module",
   "license": "MIT",
@@ -69,8 +69,8 @@
     "unpdf": "^1.4.0",
     "yaml": "^2.9.0",
     "zod": "^4.1.13",
-    "@jcode.labs/ragmir-chat": "2.9.2",
-    "@jcode.labs/ragmir-tts": "2.9.2"
+    "@jcode.labs/ragmir-chat": "2.9.3",
+    "@jcode.labs/ragmir-tts": "2.9.3"
   },
   "devDependencies": {
     "@types/html-to-text": "^9.0.4",