@jcode.labs/ragmir 2.18.0 → 2.19.0

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

@@ -1,52 +1,36 @@
 # Document evidence benchmark
 
-A deterministic, public-safe benchmark for the retrieval and citation quality coding agents receive
-from Ragmir's confidential local RAG pipeline.
+A deterministic, public-safe benchmark for the retrieval and citation quality a coding agent
+receives from Ragmir. Six golden queries require the expected path and an exact file, line, chunk,
+or PDF-page citation. The fictional corpus runs offline with `local-hash`.
 
-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 an exact verifiable file, line, chunk, or PDF-page
-citation.
-Every document is fictional and safe to commit. The benchmark keeps its corpus and generated index
-on the machine and runs the default `local-hash` retrieval offline.
+## What passes
 
-## What it measures
-
-| Signal | What a passing result means |
+| Signal | Requirement |
 | --- | --- |
-| `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#chunkIndex` is returned without invented source lines |
-
-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.
+| Recall@K | An expected source appears in the configured top K |
+| Text citation | Exact `relative/path:Lx-Ly#chunkIndex` |
+| PDF citation | Exact `relative/path:pN#chunkIndex`, with no invented source lines |
 
-## Corpus
+Each source fits in one chunk so citation expectations stay stable while exercising the production
+ingestion and evaluation pipeline.
 
-| Fictional source | Evidence type |
+| Fictional source | Evidence |
 | --- | --- |
 | `raw/contracts/master-services-agreement.md` | Contract and residency obligations |
-| `raw/contracts/pdf-control-evidence.pdf` | Embedded PDF text with a page citation |
+| `raw/contracts/pdf-control-evidence.pdf` | Embedded PDF text and 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.
+[`golden-queries.json`](./golden-queries.json) maps questions to expected paths and citations.
 
-## Run the benchmark
-
-From the repository root, install dependencies and build the packages:
+## Run it
 
 ```bash
 pnpm install --frozen-lockfile
 pnpm build
-```
-
-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 --rebuild
@@ -54,40 +38,17 @@ node ../../dist/cli.js evaluate --golden golden-queries.json --json
 node ../../dist/cli.js evaluate --golden golden-queries.json --fail-under 1
 ```
 
-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.
+The final command fails unless every query meets the threshold. Keep JSON output when CI or a
+retrieval review needs machine-readable evidence.
 
-## Safety
+On failure, run `rgr audit`, inspect returned paths and citations, then decide whether retrieval,
+chunking, the corpus, or the intended expectation changed. Update a golden query only for an
+intentional behavior change; never lower `--fail-under` to hide a regression.
 
-- 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.
+For private evaluation, copy the `.ragmir/config.json`, `golden-queries.json`, and `raw/` structure
+into an ignored workspace. Record the smallest expected source set and exact coordinates only when
+the source is stable. Never commit private documents, queries, or reports.
 
-Return to the [Ragmir Core README](../../README.md) or try the
-[confidential local RAG demo](../sovereign-rag-demo/README.md) for a broader CLI walkthrough.
+A perfect score proves this fixture, not universal retrieval quality. Continue with the
+[confidential local RAG demo](../sovereign-rag-demo/README.md) or
+[Core README](../../README.md).

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

@@ -1,50 +1,24 @@
 # Library API demo
 
-A runnable smoke test for the public `@jcode.labs/ragmir` TypeScript API behind confidential local
-RAG workflows for coding agents and scripts.
-
-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. The default `local-hash` path keeps the corpus
-and generated index on the machine and performs retrieval offline.
-
-## What it proves
-
-The demo opens one persistent client and exercises four public operations in order:
-
-1. `ragmir.ingest({ rebuild: true })` parses, redacts, chunks, embeds, and stores the corpus.
-2. `ragmir.search(query, { topK })` returns ranked source passages.
-3. `ragmir.ask(query, { topK })` returns retrieval-only cited context without LLM synthesis.
-4. `ragmir.status()` reports the active knowledge base and indexed coverage.
-
-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.
+A runnable smoke test for the public `@jcode.labs/ragmir` TypeScript API. It opens one persistent
+client, ingests a fictional local corpus, retrieves cited passages, returns retrieval-only context,
+and reports status through the same package name an external consumer imports.
 
 ## Run it
 
-From the repository root:
-
 ```bash
 pnpm install --frozen-lockfile
 pnpm example
 ```
 
-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 `status` sections so a reviewer can see each
-public step succeed.
-
-To rerun only the script after an existing build:
+The root command builds the packages and runs [`run.mjs`](./run.mjs). Package self-reference points
+to this checkout's `packages/ragmir-core/dist`, never the npm release. To rerun after a build:
 
 ```bash
 node packages/ragmir-core/examples/library-api-demo/run.mjs
 ```
 
-`dist/` is ignored, so a clean clone must be built at least once.
-
-## The public API pattern
-
-The essential integration is intentionally small:
+## Integration pattern
 
 ```js
 import { createRagmirClient } from "@jcode.labs/ragmir"
@@ -52,39 +26,25 @@ import { createRagmirClient } from "@jcode.labs/ragmir"
 const ragmir = await createRagmirClient({ cwd: projectRoot })
 try {
   await ragmir.ingest({ rebuild: true, timeoutMs: 30_000 })
-
   const results = await ragmir.search("offline retrieval approval", { topK: 3 })
-
   const context = await ragmir.ask("What evidence supports offline operation?", { topK: 3 })
-
   const status = await ragmir.status()
 } finally {
   await ragmir.close()
 }
 ```
 
-All project-relative state is resolved once from `cwd`. Reuse one client per project root in a
-long-running Node.js process and close it during shutdown. For one-shot scripts, the top-level
-`ingest`, `search`, `ask`, and `audit` functions remain available.
-
-## Data used by the demo
+The demo proves `ingest`, `search`, `ask`, and `status` in order. `ask` returns cited context without
+LLM synthesis. Reuse one client per project root in a long-running process; one-shot top-level
+functions remain available.
 
-The script reuses the sibling [confidential local RAG demo](../sovereign-rag-demo/README.md):
+The script shares the sibling demo's synthetic Markdown, CSV, JSONL, YAML, and custom-text corpus.
+It uses offline `local-hash`, writes only ignored `.ragmir/storage`, downloads no model, and contains
+no private documents. Keep committed changes deterministic and use a separate ignored corpus for
+private tests.
 
-- 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
-
-| Need | Example |
+| Need | Continue with |
 | --- | --- |
-| Learn the complete CLI workflow | [Confidential local 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 | [Complete TypeScript API reference](../../../../docs/api-reference.md) |
-
-Return to the [Ragmir Core README](../../README.md) for installation, MCP, OCR, and privacy guidance.
+| Complete CLI workflow | [Confidential local RAG demo](../sovereign-rag-demo/README.md) |
+| Exact path and citation gates | [Document evidence benchmark](../document-evidence-benchmark/README.md) |
+| Every exported option | [TypeScript API reference](../../../../docs/api-reference.md) |

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

@@ -1,42 +1,29 @@
 # Confidential local RAG demo
 
-A complete, fictional workspace for learning how agents and scripts retrieve cited local project
-context with Ragmir.
-
-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 keeps the fictional
-corpus and generated index on the machine, runs with offline `local-hash` retrieval, and contains no
-customer or production data.
+A complete fictional workspace for learning how agents and scripts retrieve cited project evidence
+with Ragmir. It covers multiple formats, privacy checks, unsupported files, golden queries, and
+agent access while keeping corpus and index local with offline `local-hash` retrieval.
 
 ## Scenario
 
-The corpus models an operations team reviewing whether an evidence workflow can stay local:
-
-| File | Role in the scenario |
+| File | Role |
 | --- | --- |
 | `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 |
+| `raw/review-notes.evidence` | Project-configured text extension |
+| `raw/facility-scan.heic` | Deliberately unsupported audit fixture |
 
-## Run the full workflow
-
-From the repository root:
+## Run the workflow
 
 ```bash
 pnpm install --frozen-lockfile
 pnpm build
-```
-
-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.
+# POSIX only: Git and npm archives do not preserve this fixture's intended mode.
 chmod 700 raw
 
 node ../../dist/cli.js security-audit
@@ -49,101 +36,54 @@ node ../../dist/cli.js audit --unsupported
 node ../../dist/cli.js status
 ```
 
-`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.
+`init` is idempotent. The security audit intentionally warns that `.ragmir/` is not fully ignored
+because this public fixture commits its configuration and source list. Generated storage, models,
+reports, audio, logs, and salts remain ignored. Private projects should ignore the complete
+`.ragmir/` directory.
 
-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.
+Expected results:
 
-## What to look for
+- search and ask identify source paths and chunks;
+- `ask` returns evidence, not a generated answer;
+- `research` combines bounded queries and source diagnostics;
+- every golden query finds its expected source;
+- the audit explains why HEIC was skipped and suggests local OCR;
+- status confirms the active provider and local index.
 
-- 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 include `dataset residency`, `incident containment evidence`,
+`who owns the usage review`, and `what documents support sovereign deployment`.
 
-## Useful queries
+## Connect an agent
 
-```text
-offline retrieval approval
-dataset residency
-incident containment evidence
-who owns the usage review
-what documents support sovereign deployment
-```
-
-Try a precise query first, then compare it with `research --compact` when the question spans several
-files.
-
-## Give the demo to an agent
-
-In a real project, `rgr setup` generates an MCP helper under `.ragmir/`. After setup, an
-MCP-compatible agent can follow a prompt like:
+In a real project, `rgr setup` writes an ignored MCP helper. A compatible agent can then follow:
 
 ```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.
+Use Ragmir to search for "offline retrieval approval" and write a cited report under
+.ragmir/reports/demo-sovereign-rag.md. Mention unsupported or stale files reported by the audit.
 ```
 
-The report path stays under ignored local state. Do not commit generated reports that may contain
-retrieved project evidence.
+Keep retrieved reports under ignored local state.
 
 ## Compare semantic retrieval
 
-The committed configuration uses:
+The committed configuration uses offline lexical/hash retrieval:
 
 ```json
-{
-  "embeddingProvider": "local-hash"
-}
+{ "embeddingProvider": "local-hash" }
 ```
 
-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:
+For a deliberate semantic comparison, prepare a Transformers.js model locally, set
+`embeddingProvider`, `embeddingModel`, `embeddingModelRevision`, `embeddingModelPath`, and
+`transformersAllowRemoteModels: false`, then rebuild and rerun evaluation. Keep remote loading off.
+A lower semantic score is a tuning signal, never a reason to weaken a quality gate.
 
-```json
-{
-  "embeddingProvider": "transformers",
-  "embeddingModel": "intfloat/multilingual-e5-small",
-  "embeddingModelRevision": "main",
-  "embeddingModelPath": ".ragmir/models",
-  "transformersAllowRemoteModels": false
-}
-```
-
-```bash
-node ../../dist/cli.js ingest --rebuild
-node ../../dist/cli.js evaluate --golden golden-queries.json --json
-```
-
-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
-
-All runtime state stays under the ignored directory:
-
-```text
-.ragmir/
-```
-
-Remove only the generated index when you want a clean rerun:
+All generated state stays under `.ragmir/`. Reset only the index with:
 
 ```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.
+Never replace the fictional fixtures with confidential documents. Continue with the
+[Library API demo](../library-api-demo/README.md),
+[Document evidence benchmark](../document-evidence-benchmark/README.md), or
+[Core README](../../README.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jcode.labs/ragmir",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "Confidential local RAG for coding agents, with offline cited retrieval through CLI, MCP, and TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -78,8 +78,8 @@
     "zod": "^4.1.13"
   },
   "peerDependencies": {
-    "@jcode.labs/ragmir-chat": "2.18.0",
-    "@jcode.labs/ragmir-tts": "2.18.0"
+    "@jcode.labs/ragmir-chat": "2.19.0",
+    "@jcode.labs/ragmir-tts": "2.19.0"
   },
   "peerDependenciesMeta": {
     "@jcode.labs/ragmir-chat": {
@@ -96,8 +96,8 @@
     "publint": "^0.3.21",
     "typescript": "^5.9.3",
     "vitest": "^4.0.15",
-    "@jcode.labs/ragmir-chat": "2.18.0",
-    "@jcode.labs/ragmir-tts": "2.18.0"
+    "@jcode.labs/ragmir-chat": "2.19.0",
+    "@jcode.labs/ragmir-tts": "2.19.0"
   },
   "scripts": {
     "bench:compare": "node benchmarks/compare.mjs",

package/skills/ragmir/SKILL.md

@@ -47,6 +47,8 @@ acceptable. Normal confidential indexing keeps remote model loading disabled.
 | Bounded source coverage and index drift | Read `ragmir://sources` or run `rgr audit` |
 | Readiness | `rgr doctor` or `ragmir_status` |
 | Repair setup or stale data | `rgr doctor --fix` |
+| Check upgrade compatibility | `rgr upgrade --check`; run `rgr upgrade` when action is required |
+| Compare team indexes | `rgr team snapshot` and `rgr team compare` |
 | Check unindexed or unsupported files | `rgr audit --unsupported` |
 | Preview redacted chunks before indexing | `rgr preview --path <prefix> --json` |
 | Check privacy posture | `rgr security-audit` |
@@ -76,6 +78,36 @@ When a monorepo has a root Ragmir base and nested app bases, select the base bef
 5. Never silently combine citations from different bases. Label each base when a task genuinely
    requires evidence from more than one.
 
+## Team synchronization
+
+When the task involves shared project knowledge, check that the local index is ready before relying
+on retrieval. If a teammate provided an authorized snapshot, run:
+
+```sh
+pnpm exec rgr team compare .ragmir/team/peer.json --local-label local --json
+```
+
+If the result is not `synchronized`, warn the user in the language they are using. Summarize
+configuration drift plus local-only, peer-only, and changed files, then present the ordered
+`recommendedActions`. Never decide which source copy is correct, overwrite a source file, or ingest
+an unreviewed peer copy. The declared Git commit, Drive revision, or team folder remains the
+authority.
+
+To create a shareable diagnostic without source text or absolute project paths:
+
+```sh
+pnpm exec rgr team snapshot --label <name> --output .ragmir/team/<name>.json
+```
+
+Treat the snapshot as sensitive metadata because it contains relative paths and checksums. Keep it
+under ignored `.ragmir/` state and share it only with authorized teammates.
+
+After updating the package and before retrieval with the new runtime, run `rgr upgrade --check`. If
+action is required, explain it before running `rgr upgrade`. A safe rebuild keeps the previous
+validated index until atomic activation; never delete `.ragmir/storage/` as the first upgrade step.
+For a long-running host, keep the already loaded runtime serving and cut over only after the upgrade
+reports `status=current` and `ready=true`.
+
 ## Indexing
 
 Use `.ragmir/config.json` for sources, with paths, globs, and `!` exclusions:
@@ -148,6 +180,7 @@ load `ragmir-markdown-report`. Both should write generated output under ignored
 
 ## Answer standard
 
+- Reply in the language used by the user unless they request another language.
 - Cite file paths and source labels when useful.
 - State uncertainty when retrieval does not prove a claim.
 - Keep legal, security, and financial conclusions conservative and recommend appropriate review.