fix(core): keep local add-ons optional and polish workflows (#115) (#116)

* fix(core): keep chat and tts truly optional

* fix(landing): polish local rag workflows

Author: jb-thery

AGENTS.md

@@ -13,6 +13,7 @@
 - `packages/ragmir-core` provides `@jcode.labs/ragmir`: the `rgr` CLI, TypeScript library, MCP server, and portable skills.
 - `packages/ragmir-chat` is the optional local GGUF synthesis add-on used by `rgr chat`.
 - `packages/ragmir-tts` is the optional local/offline audio add-on used by `rgr audio`.
+- Core must install and start without Chat or TTS. Keep both as optional peer integrations and load them only when their command is used.
 - `packages/ragmir-landing` is a self-contained, telemetry-free Astro site. Keep it static, open-source focused, and free of vendor deployment configuration.
 - Ragmir Core stays retrieval-first: `local-hash` supports offline retrieval, `transformers` is the explicit semantic option, and local chat remains a separate add-on.
 - Long-running Node.js processes use one `RagmirClient` per project root and close it during shutdown. Keep the top-level API for one-shot scripts.

CLAUDE.md

@@ -17,6 +17,7 @@ Use `pnpm --filter @jcode.labs/ragmir <script>` for Core-only work. The pinned N
 - `packages/ragmir-core`: published CLI, library, MCP server, and skills.
 - `packages/ragmir-chat`: optional local chat add-on.
 - `packages/ragmir-tts`: optional audio add-on.
+- Core must install and start without Chat or TTS. Keep both as optional peer integrations and load them only when their command is used.
 - `packages/ragmir-landing`: self-contained static Astro documentation and product site.
 
 Generated `dist/`, `.astro/`, `release-artifacts/`, and `.ragmir/` directories are ignored. Do not

README.md

@@ -8,10 +8,11 @@
 
 **Local RAG for your coding agents.**
 
-Ragmir indexes the project files you choose, keeps the index on your machine, and gives coding
-agents and local scripts bounded evidence with verifiable citations. Connect through project-scoped
-agent skills, a local MCP server, the CLI, or the TypeScript API. The default path needs no account,
-hosted document store, or model download.
+Ragmir indexes the project files you choose on your machine and retrieves bounded, cited evidence
+offline by default. The corpus and generated index remain local, so confidential source files are
+not uploaded to a hosted RAG service. Connect through project-scoped agent skills, a local MCP
+server, the CLI, or the TypeScript API. The default `local-hash` path needs no account, API key, or
+model download.
 
 Bring the coding agent or automation you already use. Ragmir Core retrieves evidence without
 calling a model. If no retrieved passage may leave the machine, use a local consumer or Ragmir Chat
@@ -235,6 +236,8 @@ Redaction reduces accidental exposure but is not a compliance certification. Rev
 | [`@jcode.labs/ragmir-chat`](./packages/ragmir-chat/README.md) | Optional cited generation with a local GGUF model |
 | [`@jcode.labs/ragmir-tts`](./packages/ragmir-tts/README.md) | Optional local audio or explicit online voice rendering |
 
+Installing Core does not install Chat or TTS. Add only the optional package needed by the workflow.
+
 ## Runnable examples
 
 | Example | What it proves |

SECURITY.md

@@ -17,5 +17,9 @@ or private document disclosure.
 
 ## Data Boundary
 
-Ragmir is designed to index local project documents. Raw project documents, `.ragmir/`,
-environment files, credentials, and customer records must remain outside commits.
+Ragmir indexes selected project documents on the user's machine. The default `local-hash` path keeps
+ingestion and retrieval offline, and Core does not upload the corpus to a hosted RAG service. A cloud
+consumer can still receive returned passages when the user explicitly chooses that handoff.
+
+Raw project documents, `.ragmir/`, environment files, credentials, and customer records must remain
+outside commits.

context7.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://context7.com/schema/context7.json",
   "projectTitle": "Ragmir",
-  "description": "Local RAG for coding agents and scripts, with verifiable citations. The TypeScript CLI, library, read-focused MCP server, and portable skills keep the index under ignored local state. Optional local Chat and TTS remain separate packages.",
+  "description": "Local RAG for coding agents and scripts, with offline cited retrieval. The TypeScript CLI, library, read-focused MCP server, and portable skills keep the corpus and index under ignored local state. Optional local Chat and TTS remain separate packages.",
   "excludeFolders": [
     "node_modules",
     "packages/ragmir-core/dist",

docs/agent-integration.md

@@ -1,7 +1,8 @@
 # Agent integration
 
-Ragmir gives the AI or automation you choose cited local passages through CLI or one stdio MCP
-server. Core is model-agnostic and never calls a model itself.
+Ragmir indexes the selected project files locally and gives the AI or automation you choose cited
+passages through CLI or one stdio MCP server. The default `local-hash` path keeps ingestion and
+retrieval offline. Core is model-agnostic, never uploads the corpus, and never calls a model itself.
 
 Choose the handoff that matches the corpus:
 

docs/api-reference.md

@@ -10,7 +10,9 @@ Ragmir publishes three ESM packages for Node.js 20 or later:
 
 Use the CLI or MCP server when an agent or automation only needs to retrieve evidence. Use these
 APIs when a Node.js process owns the workflow. All paths resolve from `cwd` or the current working
-directory, and generated state stays under the project's ignored `.ragmir/` directory.
+directory, and generated state stays under the project's ignored `.ragmir/` directory. With the
+default `local-hash` provider, Core indexes and retrieves private project files locally and
+offline. Only passages a caller explicitly hands to an external consumer cross that boundary.
 
 ## Core: cited retrieval
 
@@ -279,6 +281,15 @@ import { doctor, renderSpeech } from "@jcode.labs/ragmir-tts"
 const runtime = await doctor()
 console.log(runtime.transformersAvailable)
 
+await renderSpeech({
+  cwd: process.cwd(),
+  text: "Non-sensitive model preload text.",
+  outputPath: "/tmp/ragmir-tts-preload.wav",
+  engine: "transformers",
+  language: "en",
+  allowRemoteModels: true,
+})
+
 const result = await renderSpeech({
   cwd: process.cwd(),
   textFile: ".ragmir/reports/release-brief.md",
@@ -292,8 +303,9 @@ console.log(result.outputPath, result.samplingRate)
 ```
 
 TTS renders text supplied by the caller. It does not retrieve evidence or write a summary. The
-default Transformers.js path produces local WAV output after an explicit model preload. The Edge
-path is explicit and sends narration text to the external service.
+first call explicitly preloads the local model from non-sensitive text. Later calls can keep
+`allowRemoteModels: false` for confidential content. The Edge path is explicit and sends narration
+text to the external service.
 
 ### TTS runtime exports
 

docs/cli-reference.md

@@ -66,6 +66,8 @@ rgr models pull --enable
 rgr ocr doctor
 rgr ocr setup --language eng+fra
 rgr chat setup --profile fast
+printf '%s\n' "Non-sensitive model preload text." > /tmp/ragmir-tts-preload.txt
+rgr audio /tmp/ragmir-tts-preload.txt --allow-remote-models --out .ragmir/audio/preload.wav
 rgr audio ./brief.md --offline --out .ragmir/audio/brief.wav
 ```
 
@@ -77,7 +79,9 @@ rgr audio ./brief.md --offline --out .ragmir/audio/brief.wav
 | `audio <file>` | Render text with the optional TTS add-on. |
 
 OCR runs only for PDF pages without embedded text. The strict privacy profile disables external
-extractors. Normal chat and offline audio rendering do not download models.
+extractors. The first audio command above explicitly downloads the model from non-sensitive text;
+the second uses the prepared cache and does not download anything. See the
+[offline TTS guide](./offline-tts-preload.md) for model paths and verification.
 
 ## Agents, maintenance, and JSON
 

package.json

@@ -2,7 +2,7 @@
   "name": "jcode-ragmir",
   "version": "0.4.12",
   "private": true,
-  "description": "Monorepo for Ragmir, local RAG with verifiable citations for coding agents and scripts, plus optional local Chat and TTS.",
+  "description": "Monorepo for Ragmir, local RAG with offline cited retrieval for coding agents and scripts, plus optional local Chat and TTS.",
   "type": "module",
   "license": "MIT",
   "author": "Jean-Baptiste Thery (https://github.com/jb-thery)",

packages/ragmir-chat/README.md

@@ -7,10 +7,10 @@
 
 **Optional local answers for your coding-agent RAG workflow.**
 
-Ragmir Core retrieves cited project evidence for your coding agent or local script.
-`@jcode.labs/ragmir-chat` adds an optional answer step on the same machine: it runs a verified local
-model, limits generation to the retrieved passages, and validates the source markers in the visible
-answer.
+Ragmir Core indexes selected project files on your machine and retrieves cited evidence offline by
+default, without uploading the source corpus to a hosted RAG service. `@jcode.labs/ragmir-chat` adds
+an optional answer step on the same machine: it runs a verified local model, limits generation to
+the retrieved passages, and validates the source markers in the visible answer.
 
 Core does not require Chat or any generative model. Use this package only when the answer itself,
 not just retrieval, must stay on the workstation.