@jcode.labs/ragmir 2.3.0 → 2.5.0

package/skills/ragmir/SKILL.md

@@ -19,7 +19,6 @@ Default project layout:
 
 ```plain text
 .ragmir/config.json   # local Ragmir config
-.ragmir/sources.txt   # optional extra source paths
 .ragmir/raw/          # raw documents to ingest
 .ragmir/storage/      # generated local index
 .ragmir/access.log    # metadata-only access log
@@ -29,9 +28,8 @@ Default project layout:
 ## Data Safety
 
 - Do not commit raw documents, secrets, tax IDs, scans, bank documents, tokens, or generated vector stores.
-- Keep `.ragmir/` ignored by Git. Legacy projects using `private/`, `private/**`, or `.kb/` must keep those paths
-  ignored too.
-- Treat `ragmir search`, `ragmir ask`, `ragmir research`, and MCP results as sensitive because they can
+- Keep `.ragmir/` ignored by Git.
+- Treat `rgr search`, `rgr ask`, `rgr research`, and MCP results as sensitive because they can
   contain private source passages even when redaction is enabled.
 - Prefer summaries and citations over dumping long private passages into the chat.
 - If the user asks for a high-stakes answer, identify which facts came from Ragmir and which still require professional or official verification.
@@ -41,38 +39,38 @@ Default project layout:
 From the repository root:
 
 ```bash
-pnpm exec ragmir doctor
+pnpm exec rgr doctor
 ```
 
 If Ragmir is installed but setup is incomplete or the index is stale:
 
 ```bash
-pnpm exec ragmir doctor --fix
+pnpm exec rgr doctor --fix
 ```
 
 If Ragmir is not installed:
 
 ```bash
 pnpm add -D @jcode.labs/ragmir
-pnpm exec ragmir setup
+pnpm exec rgr setup
 # Optional: one-time model download for higher-quality semantic retrieval.
-pnpm exec ragmir setup --semantic
+pnpm exec rgr setup --semantic
 ```
 
 When the repository should expose only specific agent helpers or must launch MCP through a local
 wrapper, generate the agent kit explicitly:
 
 ```bash
-pnpm exec ragmir setup --agents claude,codex --mcp-command ./scripts/serve-mcp.sh
+pnpm exec rgr setup --agents claude,codex --mcp-command ./scripts/serve-mcp.sh
 ```
 
 If the package manager is npm:
 
 ```bash
 npm install --save-dev @jcode.labs/ragmir
-npx ragmir setup
+npx rgr setup
 # Optional: one-time model download for higher-quality semantic retrieval.
-npx ragmir setup --semantic
+npx rgr setup --semantic
 ```
 
 Use `status`, `audit`, and `security-audit` for deeper checks after `doctor` explains the current
@@ -84,14 +82,15 @@ Prefer the smallest command that answers the user's task:
 
 | Task | Preferred command or tool |
 | --- | --- |
-| Check whether Ragmir is usable | `ragmir doctor` or MCP `ragmir_status` |
-| Repair missing setup or stale index | `ragmir doctor --fix` |
-| Inspect skipped, duplicate, archive-like, or mirror-like sources | `ragmir audit --unsupported` |
-| Find exact source passages | `ragmir search "<query>" --compact` or MCP `ragmir_search` with `compact: true` |
-| Prepare a broad implementation, review, or planning answer | `ragmir research "<topic>" --compact` or MCP `ragmir_research` |
-| Return deterministic cited context for a trusted model | `ragmir ask "<question>"` or MCP `ragmir_ask` |
-| Check local privacy posture | `ragmir security-audit` or MCP `ragmir_security_audit` |
-| Validate recall against known expected files | `ragmir evaluate --golden <file>` or MCP `ragmir_evaluate` |
+| Check whether Ragmir is usable | `rgr doctor` or MCP `ragmir_status` |
+| Decide whether a prompt needs Ragmir | `rgr route-prompt "..." --json` or MCP `ragmir_route_prompt` |
+| Repair missing setup or stale index | `rgr doctor --fix` |
+| Inspect skipped, duplicate, archive-like, or mirror-like sources | `rgr audit --unsupported` |
+| Find exact source passages | `rgr search "<query>" --compact` or MCP `ragmir_search` with `compact: true` |
+| Prepare a broad implementation, review, or planning answer | `rgr research "<topic>" --compact` or MCP `ragmir_research` |
+| Return deterministic cited context for a trusted model | `rgr ask "<question>"` or MCP `ragmir_ask` |
+| Check local privacy posture | `rgr security-audit` or MCP `ragmir_security_audit` |
+| Validate recall against known expected files | `rgr evaluate --golden <file>` or MCP `ragmir_evaluate` |
 
 ## Provider Modes
 
@@ -103,7 +102,7 @@ Default retrieval mode:
 }
 ```
 
-This supports ingestion, search, MCP retrieval, and `ragmir ask` with cited passages without a model
+This supports ingestion, search, MCP retrieval, and `rgr ask` with cited passages without a model
 server. It is lexical/hash retrieval, not model-semantic search. Do not present it as equivalent to
 semantic embeddings.
 
@@ -123,15 +122,15 @@ air-gapped or confidential work and preload model files under `embeddingModelPat
 first-run shortcut when a one-time download is acceptable:
 
 ```bash
-pnpm exec ragmir setup --semantic
-pnpm exec ragmir ingest --rebuild
+pnpm exec rgr setup --semantic
+pnpm exec rgr ingest --rebuild
 ```
 
 Or enable it later:
 
 ```bash
-pnpm exec ragmir models pull --enable
-pnpm exec ragmir ingest --rebuild
+pnpm exec rgr models pull --enable
+pnpm exec rgr ingest --rebuild
 ```
 
 ## Ingestion Workflow
@@ -139,25 +138,26 @@ pnpm exec ragmir ingest --rebuild
 After documents are added or changed:
 
 ```bash
-pnpm exec ragmir doctor --fix
-pnpm exec ragmir audit
-pnpm exec ragmir audit --unsupported
-pnpm exec ragmir security-audit
-pnpm exec ragmir status
+pnpm exec rgr doctor --fix
+pnpm exec rgr audit
+pnpm exec rgr audit --unsupported
+pnpm exec rgr security-audit
+pnpm exec rgr status
 ```
 
-`ragmir doctor --fix` updates the index only when supported files are present and the privacy posture
-has no warnings. Normal `ragmir ingest` reuses unchanged rows; use `ragmir ingest --rebuild` after changing
-embedding provider/model or chunking settings. `ragmir ingest --json` reports `emptyTextFiles` when
-supported files, typically scanned PDFs, produce no indexable text. `ragmir doctor` should show
+`rgr doctor --fix` updates the index only when supported files are present and the privacy posture
+has no warnings. Normal `rgr ingest` reuses unchanged rows; use `rgr ingest --rebuild` after changing
+embedding provider/model or chunking settings. `rgr ingest --json` reports `emptyTextFiles` when
+supported files, typically scanned PDFs, produce no indexable text. `rgr doctor` should show
 `ready=true` before relying on the index. The audit must show no missing or stale supported files, and
 the security audit should not show warnings before relying on Ragmir for sensitive work.
 
 Default retrieval is tuned for broader recall (`topK: 8`, `chunkOverlap: 200`). Keep MCP retrieval
 bounded by `mcpMaxTopK`, and raise `--top-k` only when the first results are too narrow.
 
-For monorepos, keep raw confidential files local and list useful repo docs through `.ragmir/sources.txt`.
-Entries can be paths or glob patterns relative to the Ragmir project root, with `!` exclusions:
+For monorepos, keep raw confidential files local and list useful repo docs through the `sources`
+array in `.ragmir/config.json`. Entries can be paths or glob patterns relative to the Ragmir project
+root, with `!` exclusions:
 
 ```plain text
 ../apps/*/README.md
@@ -168,9 +168,9 @@ Entries can be paths or glob patterns relative to the Ragmir project root, with
 Use the CLI when you want agents or setup scripts to update the file without manual editing:
 
 ```bash
-pnpm exec ragmir sources add "../apps/*/README.md" "../apps/*/docs/**/*.md"
-pnpm exec ragmir sources add "!../apps/**/node_modules/**"
-pnpm exec ragmir sources list
+pnpm exec rgr sources add "../apps/*/README.md" "../apps/*/docs/**/*.md"
+pnpm exec rgr sources add "!../apps/**/node_modules/**"
+pnpm exec rgr sources list
 ```
 
 ## Query Workflow
@@ -178,38 +178,55 @@ pnpm exec ragmir sources list
 Use search when you need exact source passages:
 
 ```bash
-pnpm exec ragmir search "your query"
+pnpm exec rgr search "your query"
 ```
 
 Use research when the user asks for broad context, implementation planning, review preparation, or a
 cross-document audit:
 
 ```bash
-pnpm exec ragmir research "your topic" --compact
+pnpm exec rgr research "your topic" --compact
 ```
 
-`ragmir research` runs audit and security checks, generates several related retrieval queries, merges
+`rgr research` runs audit and security checks, generates several related retrieval queries, merges
 cited evidence, reports source diagnostics, and performs a lightweight repository code scan unless
 `--no-code` is used.
 
 Use ask when you need cited context for the current agent or an external LLM:
 
 ```bash
-pnpm exec ragmir ask "your question"
+pnpm exec rgr ask "your question"
 ```
 
 Ground answers in returned sources. If search results are weak, say that the current index does not
-prove the point and ask for the missing document. `ragmir ask` returns cited passages rather than LLM
+prove the point and ask for the missing document. `rgr ask` returns cited passages rather than LLM
 synthesis. Use those passages as context for the current agent, or tell the user that generative
 synthesis needs a trusted external LLM or model runtime.
 
+## Prompt Routing
+
+When the user did not explicitly mention Ragmir, use local judgment first. If the prompt asks about
+the current repository, local documents, private specs, architecture, previous decisions, citations,
+release readiness, audits, or implementation planning, prefer Ragmir before answering from memory.
+
+When the runtime supports MCP and you are unsure, call `ragmir_route_prompt` with the prompt text. If
+MCP is unavailable, use:
+
+```bash
+pnpm exec rgr route-prompt "the user prompt" --json
+```
+
+If the decision returns `shouldUseRagmir: true`, call the suggested `tool` with the returned `query`.
+If it returns `false`, answer normally. The router is deterministic and local: it does not store
+prompt text, call an LLM, read the vector index, or retrieve passages.
+
 ## Deep Research Workflow
 
 For broad summaries, audits, planning, or institutional dossiers, do not rely on one query. Build a
 small retrieval plan first:
 
-- use `ragmir research` as the first pass when available;
-- check `ragmir audit` and `ragmir security-audit`;
+- use `rgr research` as the first pass when available;
+- check `rgr audit` and `rgr security-audit`;
 - query the main topic;
 - query names, dates, amounts, obligations, risks, decisions, and missing evidence separately;
 - compare the strongest passages across files;
@@ -229,18 +246,18 @@ If the agent supports MCP, configure a server for the repository:
   "mcpServers": {
     "ragmir": {
       "command": "pnpm",
-      "args": ["exec", "ragmir", "serve-mcp"],
+      "args": ["exec", "rgr", "serve-mcp"],
       "cwd": "/absolute/path/to/the/repository"
     }
   }
 }
 ```
 
-Generated MCP helpers use the `ragmir` server name by default. Use `ragmir setup --mcp-name <name>`
-or `ragmir install-skill --mcp-name <name>` only when the repository needs a different stable MCP
+Generated MCP helpers use the `ragmir` server name by default. Use `rgr setup --mcp-name <name>`
+or `rgr install-skill --mcp-name <name>` only when the repository needs a different stable MCP
 key.
 
-For Claude Code, run this from the target repository root after `pnpm exec ragmir setup`:
+For Claude Code, run this from the target repository root after `pnpm exec rgr setup`:
 
 ```bash
 claude mcp add-json --scope local ragmir "$(cat .ragmir/claude-mcp-server.json)"
@@ -260,12 +277,13 @@ For OpenCode, merge `.ragmir/opencode.jsonc` into the OpenCode config layer used
 For Cline, add `.ragmir/cline-mcp.json` under `mcpServers` in Cline's MCP configuration.
 
 For other MCP clients that cannot set `cwd`, set `RAGMIR_PROJECT_ROOT=/absolute/path/to/repository`
-when launching `ragmir serve-mcp`. `RAGMIR_PROJECT_ROOT` is the strongest signal; otherwise a
+when launching `rgr serve-mcp`. `RAGMIR_PROJECT_ROOT` is the strongest signal; otherwise a
 configured current working directory wins before agent-provided project environment variables.
 
 Available MCP tools:
 
 - `ragmir_status`: show config and chunk count.
+- `ragmir_route_prompt`: classify a prompt and suggest whether local Ragmir context is needed.
 - `ragmir_search`: retrieve source passages; set `compact: true` when the agent context is tight.
 - `ragmir_ask`: return cited retrieval context.
 - `ragmir_research`: run audit-backed multi-query retrieval with source diagnostics and optional code matches.
@@ -276,13 +294,13 @@ Available MCP tools:
 
 Prefer MCP tools over shell commands when the agent runtime provides them. Use shell commands when MCP is unavailable.
 
-MCP is read-focused and intentionally does not expose index deletion. Use `pnpm exec ragmir
+MCP is read-focused and intentionally does not expose index deletion. Use `pnpm exec rgr
 destroy-index --yes` from the shell when the user explicitly wants to remove the generated index.
 
 ## Optional Audio Summaries
 
 If the user asks for a listenable or TTS summary, load the optional
-`.ragmir/skills/ragmir-audio-summary/` skill installed by `pnpm exec ragmir setup`.
+`.ragmir/skills/ragmir-audio-summary/` skill installed by `pnpm exec rgr setup`.
 
 The audio skill should:
 
@@ -294,7 +312,7 @@ The audio skill should:
 ## Optional Markdown Reports
 
 If the user asks for a Markdown report, dossier, audit memo, planning note, or decision brief, load
-the optional `.ragmir/skills/ragmir-markdown-report/` skill installed by `pnpm exec ragmir setup`.
+the optional `.ragmir/skills/ragmir-markdown-report/` skill installed by `pnpm exec rgr setup`.
 
 The report skill should:
 
@@ -309,15 +327,15 @@ The report skill should:
 Most repositories should run the full setup command:
 
 ```bash
-pnpm exec ragmir setup
+pnpm exec rgr setup
 ```
 
 Use the lower-level skill installer only when Ragmir is already initialized and you want to refresh
 the local agent kit:
 
 ```bash
-pnpm exec ragmir install-skill
-pnpm exec ragmir install-skill --agents claude,codex --mcp-command ./scripts/serve-mcp.sh
+pnpm exec rgr install-skill
+pnpm exec rgr install-skill --agents claude,codex --mcp-command ./scripts/serve-mcp.sh
 ```
 
 This creates:
@@ -343,9 +361,9 @@ unselected helpers in `.ragmir/` are removed.
 For native discovery, install only the agent the user uses:
 
 ```bash
-pnpm exec ragmir install-agent --agents claude
-pnpm exec ragmir install-agent --agents kimi
-pnpm exec ragmir install-agent --agents claude,codex,kimi,opencode,cline
+pnpm exec rgr install-agent --agents claude
+pnpm exec rgr install-agent --agents kimi
+pnpm exec rgr install-agent --agents claude,codex,kimi,opencode,cline
 ```
 
 By default this writes project-scope skill folders such as `.claude/skills/`, `.kimi/skills/`,

package/skills/ragmir-audio-summary/SKILL.md

@@ -35,7 +35,7 @@ Two reference files sit next to this skill and are read while drafting:
 
 - Treat the source documents, retrieved passages, generated narration, and final audio as sensitive.
 - Do not use online TTS for confidential content unless the user explicitly allows it.
-- Prefer `pnpm exec ragmir audio` or `pnpm exec ragmir-tts render` for plug-and-play output.
+- Prefer `pnpm exec rgr audio` or `pnpm exec rgr-tts render` for plug-and-play output.
 - Use `--engine transformers --offline` when model files are already present and remote model
   loading is not allowed.
 - Use `--engine edge` only when online TTS is acceptable and global Voice Forge quality is required.
@@ -63,21 +63,21 @@ gets dropped at the drafting step, not added because it was "also in the documen
 From the repository root, run:
 
 ```bash
-pnpm exec ragmir doctor
-pnpm exec ragmir status
-pnpm exec ragmir audit
-pnpm exec ragmir audit --unsupported
-pnpm exec ragmir security-audit
+pnpm exec rgr doctor
+pnpm exec rgr status
+pnpm exec rgr audit
+pnpm exec rgr audit --unsupported
+pnpm exec rgr security-audit
 ```
 
 If the audit reports missing or stale files, run:
 
 ```bash
-pnpm exec ragmir doctor --fix
-pnpm exec ragmir audit --unsupported
+pnpm exec rgr doctor --fix
+pnpm exec rgr audit --unsupported
 ```
 
-`ragmir doctor --fix` rebuilds the index only when supported files are present and the privacy posture
+`rgr doctor --fix` rebuilds the index only when supported files are present and the privacy posture
 has no warnings. Do not create an audio summary from stale or incomplete evidence unless the user
 explicitly accepts that limitation.
 
@@ -89,9 +89,9 @@ in step 1 — not from the subject alone.
 For a broad summary, run multiple searches:
 
 ```bash
-pnpm exec ragmir search "<main topic>" --top-k 8
-pnpm exec ragmir search "<people, dates, money, obligations, risks, or decisions>" --top-k 8
-pnpm exec ragmir ask "<specific synthesis question>" --top-k 8
+pnpm exec rgr search "<main topic>" --top-k 8
+pnpm exec rgr search "<people, dates, money, obligations, risks, or decisions>" --top-k 8
+pnpm exec rgr ask "<specific synthesis question>" --top-k 8
 ```
 
 When MCP is available, prefer `ragmir_search`, `ragmir_ask`, `ragmir_audit`, and
@@ -177,7 +177,7 @@ neural voice for the Edge path. Write the narration in the same language you pas
 For global Voice Forge quality on non-confidential text, render with Edge MP3:
 
 ```bash
-pnpm exec ragmir audio /tmp/RAGMIR-SUMMARY-<subject-kebab>.txt \
+pnpm exec rgr audio /tmp/RAGMIR-SUMMARY-<subject-kebab>.txt \
   --engine edge \
   --lang <en|es|fr> \
   --out .ragmir/audio/RAGMIR-SUMMARY-<subject-kebab>.mp3
@@ -189,7 +189,7 @@ the narration text to that service is acceptable.
 For confidential or air-gapped operation, preload the model files under `.ragmir/models/tts` and run:
 
 ```bash
-pnpm exec ragmir audio /tmp/RAGMIR-SUMMARY-<subject-kebab>.txt \
+pnpm exec rgr audio /tmp/RAGMIR-SUMMARY-<subject-kebab>.txt \
   --engine transformers \
   --offline \
   --lang <en|es|fr> \

package/skills/ragmir-legal-dossier/SKILL.md

@@ -59,8 +59,8 @@ dossier and test them on non-sensitive samples first.
 After changing redaction rules, rebuild the index:
 
 ```bash
-pnpm exec ragmir ingest --rebuild
-pnpm exec ragmir security-audit --strict
+pnpm exec rgr ingest --rebuild
+pnpm exec rgr security-audit --strict
 ```
 
 ## Retrieval Workflow
@@ -68,19 +68,19 @@ pnpm exec ragmir security-audit --strict
 Start from readiness checks:
 
 ```bash
-pnpm exec ragmir doctor
-pnpm exec ragmir audit
-pnpm exec ragmir audit --unsupported
-pnpm exec ragmir security-audit --strict
+pnpm exec rgr doctor
+pnpm exec rgr audit
+pnpm exec rgr audit --unsupported
+pnpm exec rgr security-audit --strict
 ```
 
 Then run targeted retrieval passes:
 
 ```bash
-pnpm exec ragmir search "parties obligations dates amounts" --top-k 8
-pnpm exec ragmir search "termination clause liability indemnity notice" --top-k 8
-pnpm exec ragmir search "timeline meeting decision approval refusal" --top-k 8
-pnpm exec ragmir ask "Which documents support the chronology of events?" --top-k 8
+pnpm exec rgr search "parties obligations dates amounts" --top-k 8
+pnpm exec rgr search "termination clause liability indemnity notice" --top-k 8
+pnpm exec rgr search "timeline meeting decision approval refusal" --top-k 8
+pnpm exec rgr ask "Which documents support the chronology of events?" --top-k 8
 ```
 
 When MCP is available, prefer `ragmir_status`, `ragmir_search`, `ragmir_ask`, `ragmir_audit`, and

package/skills/ragmir-markdown-report/SKILL.md

@@ -28,16 +28,16 @@ sanitized report is safe to commit or share.
 From the repository root:
 
 ```bash
-pnpm exec ragmir doctor
-pnpm exec ragmir audit
-pnpm exec ragmir security-audit
+pnpm exec rgr doctor
+pnpm exec rgr audit
+pnpm exec rgr security-audit
 ```
 
 If files are missing, stale, or setup is incomplete:
 
 ```bash
-pnpm exec ragmir doctor --fix
-pnpm exec ragmir audit --unsupported
+pnpm exec rgr doctor --fix
+pnpm exec rgr audit --unsupported
 ```
 
 Do not write a final report from stale evidence unless the user explicitly accepts that limitation.
@@ -47,9 +47,9 @@ Do not write a final report from stale evidence unless the user explicitly accep
 For a broad report, use multiple targeted retrieval passes instead of one generic query:
 
 ```bash
-pnpm exec ragmir search "<main report topic>" --top-k 8
-pnpm exec ragmir search "<people, dates, amounts, obligations, risks, decisions>" --top-k 8
-pnpm exec ragmir ask "<specific synthesis question>" --top-k 8
+pnpm exec rgr search "<main report topic>" --top-k 8
+pnpm exec rgr search "<people, dates, amounts, obligations, risks, decisions>" --top-k 8
+pnpm exec rgr ask "<specific synthesis question>" --top-k 8
 ```
 
 When MCP is available, prefer `ragmir_search`, `ragmir_ask`, `ragmir_audit`, and