From 6d5fe045b5a2df0da02abbe7d2c8cc15de5b7f13 Mon Sep 17 00:00:00 2001
From: Jean-Baptiste THERY <jb.thery@jcode.works>
Date: Tue, 14 Jul 2026 19:58:21 +0700
Subject: [PATCH] fix(core): keep local add-ons optional and polish workflows
 (#115)

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

* fix(landing): polish local rag workflows
---
 AGENTS.md                                     |  1 +
 CLAUDE.md                                     |  1 +
 README.md                                     | 11 ++--
 SECURITY.md                                   |  8 ++-
 context7.json                                 |  2 +-
 docs/agent-integration.md                     |  5 +-
 docs/api-reference.md                         | 18 +++++--
 docs/cli-reference.md                         |  6 ++-
 package.json                                  |  2 +-
 packages/ragmir-chat/README.md                |  8 +--
 packages/ragmir-core/README.md                | 10 ++--
 .../document-evidence-benchmark/README.md     |  3 +-
 .../examples/library-api-demo/README.md       |  3 +-
 .../examples/sovereign-rag-demo/README.md     |  7 +--
 packages/ragmir-core/package.json             | 18 +++++--
 packages/ragmir-core/src/cli-options.ts       | 14 +++--
 packages/ragmir-core/src/cli.test.ts          |  6 +++
 packages/ragmir-core/src/cli.ts               | 37 ++++++++++++--
 packages/ragmir-landing/README.md             |  6 ++-
 packages/ragmir-landing/messages/en.json      | 23 +++++----
 packages/ragmir-landing/messages/fr.json      | 51 ++++++++++---------
 packages/ragmir-landing/package.json          |  2 +-
 packages/ragmir-landing/public/llms.txt       |  7 +--
 .../src/components/hero-demo-script.ts        |  8 +--
 .../src/components/use-case-carousel.tsx      | 45 ++++++++--------
 packages/ragmir-tts/README.md                 |  9 ++--
 pnpm-lock.yaml                                | 12 ++---
 scripts/semantic-release-verify.mjs           | 17 +++++++
 28 files changed, 225 insertions(+), 115 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index b7d0fbc..739df2a 100644
--- a/AGENTS.md
+++ b/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.
diff --git a/CLAUDE.md b/CLAUDE.md
index df101b8..822bb54 100644
--- a/CLAUDE.md
+++ b/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
diff --git a/README.md b/README.md
index 0a39390..2390737 100644
--- a/README.md
+++ b/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 |
diff --git a/SECURITY.md b/SECURITY.md
index 74d2a12..4f9c3d7 100644
--- a/SECURITY.md
+++ b/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.
diff --git a/context7.json b/context7.json
index fbd1746..6dbbdd4 100644
--- a/context7.json
+++ b/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",
diff --git a/docs/agent-integration.md b/docs/agent-integration.md
index 43f924f..cfd0c46 100644
--- a/docs/agent-integration.md
+++ b/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:
 
diff --git a/docs/api-reference.md b/docs/api-reference.md
index e595c48..39c4a68 100644
--- a/docs/api-reference.md
+++ b/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
 
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 2941ca8..1965353 100644
--- a/docs/cli-reference.md
+++ b/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
 
diff --git a/package.json b/package.json
index 88da1c6..6ec4285 100644
--- a/package.json
+++ b/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)",
diff --git a/packages/ragmir-chat/README.md b/packages/ragmir-chat/README.md
index e985f7d..e446cf6 100644
--- a/packages/ragmir-chat/README.md
+++ b/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.
diff --git a/packages/ragmir-core/README.md b/packages/ragmir-core/README.md
index aec0683..7834fb8 100644
--- a/packages/ragmir-core/README.md
+++ b/packages/ragmir-core/README.md
@@ -7,10 +7,10 @@
 
 **Local RAG for your coding agents.**
 
-`@jcode.labs/ragmir` indexes the project files you select, keeps the index on your machine, and
-returns bounded evidence with verifiable citations. Your coding agent or local script gets the
-context it needs without a hosted document store. The default `local-hash` path works offline,
-without an account or model download.
+`@jcode.labs/ragmir` indexes the project files you select 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. Your coding agent or local script gets the
+context it needs without an account, API key, or model download.
 
 Core is model-agnostic. Connect the coding agent or local script you already use through generated
 project skills, local MCP, or the JSON CLI. Use the typed Node.js API when your application owns the
@@ -34,7 +34,7 @@ control flow.
 Core retrieves cited evidence. It does not require a generative model or generate answers. Use
 [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.
+output. Core declares both as optional peer integrations and does not install either add-on.
 
 ## Connect a coding agent in minutes
 
diff --git a/packages/ragmir-core/examples/document-evidence-benchmark/README.md b/packages/ragmir-core/examples/document-evidence-benchmark/README.md
index 8cd14ca..0f9494f 100644
--- a/packages/ragmir-core/examples/document-evidence-benchmark/README.md
+++ b/packages/ragmir-core/examples/document-evidence-benchmark/README.md
@@ -5,7 +5,8 @@ Ragmir.
 
 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.
+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 it measures
 
diff --git a/packages/ragmir-core/examples/library-api-demo/README.md b/packages/ragmir-core/examples/library-api-demo/README.md
index dcf91e1..3cd4a17 100644
--- a/packages/ragmir-core/examples/library-api-demo/README.md
+++ b/packages/ragmir-core/examples/library-api-demo/README.md
@@ -5,7 +5,8 @@ workflows.
 
 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.
+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
 
diff --git a/packages/ragmir-core/examples/sovereign-rag-demo/README.md b/packages/ragmir-core/examples/sovereign-rag-demo/README.md
index f5b331e..5a7f946 100644
--- a/packages/ragmir-core/examples/sovereign-rag-demo/README.md
+++ b/packages/ragmir-core/examples/sovereign-rag-demo/README.md
@@ -3,9 +3,10 @@
 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 runs with offline
-`local-hash` retrieval and contains no customer or production data.
+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.
 
 ## Scenario
 
diff --git a/packages/ragmir-core/package.json b/packages/ragmir-core/package.json
index ccd4d78..098981e 100644
--- a/packages/ragmir-core/package.json
+++ b/packages/ragmir-core/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@jcode.labs/ragmir",
   "version": "0.4.12",
-  "description": "Local RAG for coding agents, with cited project evidence through CLI, MCP, and TypeScript.",
+  "description": "Local RAG for coding agents, with offline cited retrieval through CLI, MCP, and TypeScript.",
   "type": "module",
   "license": "MIT",
   "author": {
@@ -69,8 +69,6 @@
   },
   "dependencies": {
     "@huggingface/transformers": "^4.2.0",
-    "@jcode.labs/ragmir-chat": "workspace:*",
-    "@jcode.labs/ragmir-tts": "workspace:*",
     "@lancedb/lancedb": "^0.30.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "commander": "^14.0.2",
@@ -84,7 +82,21 @@
     "yaml": "^2.9.0",
     "zod": "^4.1.13"
   },
+  "peerDependencies": {
+    "@jcode.labs/ragmir-chat": "workspace:*",
+    "@jcode.labs/ragmir-tts": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "@jcode.labs/ragmir-chat": {
+      "optional": true
+    },
+    "@jcode.labs/ragmir-tts": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@jcode.labs/ragmir-chat": "workspace:*",
+    "@jcode.labs/ragmir-tts": "workspace:*",
     "@types/html-to-text": "^9.0.4",
     "@types/node": "^24.10.1",
     "publint": "^0.3.21",
diff --git a/packages/ragmir-core/src/cli-options.ts b/packages/ragmir-core/src/cli-options.ts
index c6fc923..d25bf96 100644
--- a/packages/ragmir-core/src/cli-options.ts
+++ b/packages/ragmir-core/src/cli-options.ts
@@ -1,4 +1,3 @@
-import { isTtsLanguage, TTS_LANGUAGES, type TtsLanguage } from "@jcode.labs/ragmir-tts"
 import type { AgentInstallMode, AgentInstallScope } from "./skill.js"
 
 /**
@@ -12,6 +11,9 @@ import type { AgentInstallMode, AgentInstallScope } from "./skill.js"
 
 export type AudioEngine = "auto" | "edge" | "transformers"
 
+export const SUPPORTED_AUDIO_LANGUAGES = ["en", "es", "fr", "ja", "th", "zh"] as const
+export type AudioLanguage = (typeof SUPPORTED_AUDIO_LANGUAGES)[number]
+
 export interface AudioOptions {
   out?: string
   engine?: string
@@ -78,14 +80,18 @@ export function audioAllowRemoteModels(options: AudioOptions): boolean | undefin
  * Resolve the spoken language from `--lang`. Throws on an unsupported value so
  * the operator is told which languages are available.
  */
-export function audioLanguage(options: AudioOptions): TtsLanguage | undefined {
+export function audioLanguage(options: AudioOptions): AudioLanguage | undefined {
   if (options.lang === undefined) {
     return undefined
   }
-  if (isTtsLanguage(options.lang)) {
+  if (isSupportedAudioLanguage(options.lang)) {
     return options.lang
   }
-  throw new Error(`Expected --lang to be one of: ${TTS_LANGUAGES.join(", ")}.`)
+  throw new Error(`Expected --lang to be one of: ${SUPPORTED_AUDIO_LANGUAGES.join(", ")}.`)
+}
+
+function isSupportedAudioLanguage(value: string): value is AudioLanguage {
+  return SUPPORTED_AUDIO_LANGUAGES.some((language) => language === value)
 }
 
 /**
diff --git a/packages/ragmir-core/src/cli.test.ts b/packages/ragmir-core/src/cli.test.ts
index 88b8980..30cc1d0 100644
--- a/packages/ragmir-core/src/cli.test.ts
+++ b/packages/ragmir-core/src/cli.test.ts
@@ -1,3 +1,4 @@
+import { TTS_LANGUAGES } from "@jcode.labs/ragmir-tts"
 import { describe, expect, it } from "vitest"
 import {
   audioAllowRemoteModels,
@@ -8,6 +9,7 @@ import {
   parseNumber,
   parsePositiveInt,
   parseRecallThreshold,
+  SUPPORTED_AUDIO_LANGUAGES,
 } from "./cli-options.js"
 
 describe("parsePositiveInt", () => {
@@ -72,6 +74,10 @@ describe("audioAllowRemoteModels", () => {
 })
 
 describe("audioLanguage", () => {
+  it("matches the optional TTS package language contract", () => {
+    expect(SUPPORTED_AUDIO_LANGUAGES).toEqual(TTS_LANGUAGES)
+  })
+
   it("returns undefined when no language is provided", () => {
     expect(audioLanguage({})).toBeUndefined()
   })
diff --git a/packages/ragmir-core/src/cli.ts b/packages/ragmir-core/src/cli.ts
index 461c2e7..c1cc669 100644
--- a/packages/ragmir-core/src/cli.ts
+++ b/packages/ragmir-core/src/cli.ts
@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import path from "node:path"
 import type { ChatSource } from "@jcode.labs/ragmir-chat"
-import type { TtsLanguage } from "@jcode.labs/ragmir-tts"
 import { Command } from "commander"
 import pc from "picocolors"
 import { accessLogUsageReport } from "./access-log.js"
 import {
+  type AudioLanguage,
   audioAllowRemoteModels,
   audioEngine,
   audioLanguage,
@@ -1568,7 +1568,7 @@ interface TtsRenderOptions {
   textFile: string
   outputPath?: string
   engine: "auto" | "edge" | "transformers"
-  language?: TtsLanguage
+  language?: AudioLanguage
   model?: string
   modelPath?: string
   allowRemoteModels?: boolean
@@ -1579,7 +1579,17 @@ interface TtsRenderOptions {
 }
 
 async function loadChat(): Promise<ChatModule> {
-  const module: unknown = await import(CHAT_PACKAGE_NAME)
+  let module: unknown
+  try {
+    module = await import(CHAT_PACKAGE_NAME)
+  } catch (error) {
+    if (isMissingOptionalPackage(error, CHAT_PACKAGE_NAME)) {
+      throw new Error(
+        `Ragmir Chat is optional and is not installed. Add ${CHAT_PACKAGE_NAME} to this project before using \`rgr chat\`.`,
+      )
+    }
+    throw error
+  }
   if (!isChatModule(module)) {
     throw new Error(`${CHAT_PACKAGE_NAME} did not expose the expected chat API.`)
   }
@@ -1630,13 +1640,32 @@ function toChatSource(source: Awaited<ReturnType<typeof search>>[number]): ChatS
 }
 
 async function loadTts(): Promise<TtsModule> {
-  const module: unknown = await import(TTS_PACKAGE_NAME)
+  let module: unknown
+  try {
+    module = await import(TTS_PACKAGE_NAME)
+  } catch (error) {
+    if (isMissingOptionalPackage(error, TTS_PACKAGE_NAME)) {
+      throw new Error(
+        `Ragmir TTS is optional and is not installed. Add ${TTS_PACKAGE_NAME} to this project before using \`rgr audio\`.`,
+      )
+    }
+    throw error
+  }
   if (!isTtsModule(module)) {
     throw new Error(`${TTS_PACKAGE_NAME} did not expose the expected TTS API.`)
   }
   return module
 }
 
+function isMissingOptionalPackage(error: unknown, packageName: string): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    error.code === "ERR_MODULE_NOT_FOUND" &&
+    error.message.includes(packageName)
+  )
+}
+
 function isTtsModule(value: unknown): value is TtsModule {
   return (
     typeof value === "object" &&
diff --git a/packages/ragmir-landing/README.md b/packages/ragmir-landing/README.md
index edb75e3..f16f400 100644
--- a/packages/ragmir-landing/README.md
+++ b/packages/ragmir-landing/README.md
@@ -1,7 +1,9 @@
 # Ragmir Landing
 
-The static, telemetry-free website for [Ragmir](https://ragmir.com), local RAG for your coding agents
-and scripts. Public guides are available in the
+The static, telemetry-free website for [Ragmir](https://ragmir.com), local RAG that indexes selected
+project files on the user's machine, keeps the corpus and generated index there, and retrieves cited
+evidence offline by default. Core does not upload source documents to a hosted RAG service. Public
+guides are available in the
 [project documentation](https://github.com/jcode-works/jcode-ragmir/wiki).
 
 This private workspace package presents the open-source CLI, TypeScript API, MCP integration,
diff --git a/packages/ragmir-landing/messages/en.json b/packages/ragmir-landing/messages/en.json
index 7fdc1f7..54237a7 100644
--- a/packages/ragmir-landing/messages/en.json
+++ b/packages/ragmir-landing/messages/en.json
@@ -11,17 +11,17 @@
   "nav_aria_label": "Main navigation",
   "language_label": "Language",
   "seo_home_title": "Ragmir: local RAG for coding agents and scripts",
-  "seo_home_description": "Give coding agents and local scripts cited context from private specifications, monorepo docs, PDFs, spreadsheets, and synced folders.",
+  "seo_home_description": "Index private project files locally and retrieve cited context offline for coding agents and scripts across specs, PDFs, spreadsheets, and monorepos.",
   "seo_home_keywords": "Ragmir, local RAG, coding agents, AI coding agents, cited retrieval, private specifications, monorepo documentation, PDF search, XLSX search, synced Drive files, local automation scripts, persistent Node.js RAG client, local RAG API, MCP, TypeScript",
   "seo_author": "Jean-Baptiste Thery",
   "seo_robots": "index, follow",
   "seo_image_alt": "Ragmir local RAG with cited retrieval for coding agents",
   "seo_og_site_name": "Ragmir",
   "seo_application_name": "Ragmir",
-  "hero_badge": "Local index | Verifiable citations | CLI, API & MCP | Open source",
+  "hero_badge": "Local index | Offline retrieval | Verifiable citations | CLI, API & MCP | Open source",
   "hero_title_line_1": "Local RAG for your",
   "hero_title_line_2": "coding agents.",
-  "hero_description": "Turn specs, Word files, PDFs, and local exports into cited local context for the coding agent or script you already use. Core retrieves evidence without calling a model.",
+  "hero_description": "Turn specs, Word files, PDFs, and local exports into cited evidence indexed and retrieved locally. Core works offline by default, never uploads your corpus, and calls no model.",
   "hero_primary_cta": "Install Ragmir",
   "hero_secondary_cta": "See use cases",
   "hero_npm_downloads_label": "Ragmir downloads/month on npm",
@@ -53,7 +53,7 @@
   "demo_scenario_drive_title": "Synced Drive",
   "demo_scenario_drive_description": "Read PDF, XLSX, and DOCX files from a locally synced Google Drive folder and turn them into cited feature context.",
   "demo_scenario_youtube_title": "YouTube script",
-  "demo_scenario_youtube_description": "A local script retrieves cited research, your preferred AI drafts the episode, and a person approves it before publication.",
+  "demo_scenario_youtube_description": "A local script retrieves cited passages from research sources, your preferred AI drafts the episode, and a person approves it before publication.",
   "demo_scenario_visa_title": "Visa project",
   "demo_scenario_visa_description": "A local script turns an administrative corpus into a dated checklist that remains subject to human and official-source review.",
   "demo_replay_label": "Replay the story",
@@ -64,9 +64,13 @@
   "demo_badge_visa": "Private dossier",
   "demo_script_prefix": "Local script",
   "demo_word_prompt": "Implement account recovery from these requirements. Cite every rule.",
+  "demo_word_search_command": "ragmir_search({ query: \"account recovery lockout acceptance criteria\", topK: 5 })",
   "demo_monorepo_prompt": "Explain how authentication works across packages. Cite each owner and contract.",
+  "demo_monorepo_search_command": "ragmir_search({ query: \"authentication flow package owners onboarding\", topK: 5 })",
   "demo_drive_prompt": "Implement team invitations from the roadmap, stories, and architecture. Cite every rule.",
+  "demo_drive_search_command": "ragmir_search({ query: \"feature scope dependencies acceptance criteria\", topK: 5 })",
   "demo_youtube_prompt": "Draft the episode from this cited brief and follow the channel voice guide.",
+  "demo_youtube_draft_command": "node scripts/draft-episode.mjs \"Why habits outlast motivation\"",
   "demo_word_out_setup": ".ragmir/ stays Git-ignored; the Codex helper and local runner are ready.",
   "demo_word_out_indexed": "Indexed locally: 2 DOCX | 74 chunks | 0 uploads.",
   "demo_word_out_rules": "Rules: the token expires after 15 minutes, five failed attempts lock the account, and the email must not reveal whether the account exists.",
@@ -147,7 +151,7 @@
   "agents_automation_text": "Local scripts, desktop tools, and CI jobs consume typed or JSON retrieval results with or without a generative model.",
   "use_cases_eyebrow": "Use cases",
   "use_cases_title": "Five local workflows built around realistic project files.",
-  "use_cases_text": "From private specifications and monorepos to synced Drive folders, media research, and administrative dossiers, each flow keeps the index local and returns citations.",
+  "use_cases_text": "From private specifications and monorepos to synced Drive folders, media research, and administrative dossiers, each flow keeps indexing local, retrieves offline, and returns citations.",
   "use_cases_tabs_label": "Developer use case explorer",
   "use_cases_previous": "Previous use case",
   "use_cases_next": "Next use case",
@@ -168,7 +172,7 @@
   "use_case_monorepo_title": "Onboard across a monorepo.",
   "use_case_monorepo_description": "Answer architecture questions across root and package documentation.",
   "use_case_monorepo_question": "A developer asks how authentication works across the monorepo.",
-  "use_case_monorepo_retrieval": "Ragmir searches the root and package docs as one cited knowledge base.",
+  "use_case_monorepo_retrieval": "Ragmir queries the relevant root and package bases without merging their indexes.",
   "use_case_monorepo_result": "The agent returns an onboarding map with owners, dependencies, and sources.",
   "use_case_drive_tab": "Synced Drive",
   "use_case_drive_title": "Build from a synced Drive folder.",
@@ -191,9 +195,6 @@
   "use_case_visa_request": "A local project script gathers forms, receipts, and current official guidance.",
   "use_case_visa_retrieval": "Ragmir finds matching requirements, deadlines, and missing evidence with citations.",
   "use_case_visa_result": "The script updates a dated checklist for human verification before any action.",
-  "use_case_audio_eyebrow": "Audio and micro-learning",
-  "use_case_audio_title": "Listen to a dense document set instead of reading it.",
-  "use_case_audio_text": "Generate a short MP3 or WAV summary from cited passages to review a specification, architecture, or research roundup away from the screen.",
   "seo_team_title": "The team behind Ragmir",
   "seo_team_description": "Meet the team building Ragmir, an open-source local RAG for coding agents and scripts grounded in cited project documents.",
   "team_eyebrow": "The team",
@@ -238,11 +239,11 @@
   "footer_link_releases": "Releases",
   "footer_link_changelog": "Changelog",
   "footer_link_api": "API reference",
-  "footer_text": "Ragmir is JCode Labs' local RAG layer for agents and scripts that need cited project context.",
+  "footer_text": "Ragmir is JCode Labs' local RAG layer for agents and scripts that need offline, cited retrieval from private project documents.",
   "footer_version_label": "Current Ragmir version on npm",
   "strengths_eyebrow": "Useful by design",
   "strengths_title": "Built for the documents your code search does not see.",
-  "strengths_text": "Ragmir turns private, scattered project documents into a local evidence layer that coding agents and local scripts can query through MCP, CLI, or TypeScript.",
+  "strengths_text": "Ragmir turns private, scattered project documents into a local evidence layer that coding agents and scripts can query offline through MCP, CLI, or TypeScript.",
   "strengths_best_title": "Where Ragmir fits best",
   "strengths_best_item_1_title": "Project knowledge beyond code",
   "strengths_best_item_1": "Search PDFs, DOCX, XLSX, specifications, contracts, and runbooks alongside the repository they explain.",
diff --git a/packages/ragmir-landing/messages/fr.json b/packages/ragmir-landing/messages/fr.json
index ce2cd2b..d82c64f 100644
--- a/packages/ragmir-landing/messages/fr.json
+++ b/packages/ragmir-landing/messages/fr.json
@@ -11,24 +11,24 @@
   "nav_aria_label": "Navigation principale",
   "language_label": "Langue",
   "seo_home_title": "Ragmir : RAG local pour agents de code et scripts",
-  "seo_home_description": "Donnez aux agents de code et scripts locaux un contexte cité issu de spécifications privées, docs de monorepo, PDF, tableurs et dossiers synchronisés.",
+  "seo_home_description": "Indexez vos fichiers projet privés en local et retrouvez leur contexte cité hors ligne pour vos agents de code et scripts.",
   "seo_home_keywords": "Ragmir, RAG local, agents de code, agents IA de code, recherche citée, spécifications privées, documentation monorepo, recherche PDF, recherche XLSX, fichiers Drive synchronisés, scripts d'automatisation locaux, client RAG Node.js persistant, API RAG locale, MCP, TypeScript",
   "seo_author": "Jean-Baptiste Thery",
   "seo_robots": "index, follow",
   "seo_image_alt": "Ragmir RAG local avec recherche citée pour agents de code",
   "seo_og_site_name": "Ragmir",
   "seo_application_name": "Ragmir",
-  "hero_badge": "Index local | Citations vérifiables | CLI, API & MCP | Open source",
+  "hero_badge": "Index local | Recherche hors ligne | Citations vérifiables | CLI, API & MCP | Open source",
   "hero_title_line_1": "Le RAG local pour vos",
   "hero_title_line_2": "agents de code.",
-  "hero_description": "Transformez spécifications, fichiers Word, PDF et exports locaux en contexte local cité pour l'agent de code ou le script que vous utilisez déjà. Core récupère les preuves sans appeler de modèle.",
+  "hero_description": "Transformez spécifications, fichiers Word, PDF et exports locaux en preuves citées, indexées et retrouvées en local. Core fonctionne hors ligne par défaut, n'envoie aucun corpus et n'appelle aucun modèle.",
   "hero_primary_cta": "Installer Ragmir",
   "hero_secondary_cta": "Voir les cas d'usage",
   "hero_npm_downloads_label": "téléchargements/mois de Ragmir sur npm",
   "hero_metric_private_value": "Moins de tokens",
   "hero_metric_private_label": "Récupérez les passages utiles au lieu d'envoyer tout le corpus dans un prompt.",
   "hero_metric_precision_value": "Citations vérifiables",
-  "hero_metric_precision_label": "Chaque résultat indique la source, l'extrait et le chunk ou la page PDF lorsqu'elle existe.",
+  "hero_metric_precision_label": "Chaque résultat indique la source, l'extrait et le segment ou la page PDF lorsqu'elle existe.",
   "hero_metric_agents_value": "Votre agent, vos règles",
   "hero_metric_agents_label": "Utilisez un agent hébergé selon sa politique de données, ou gardez le consommateur local si aucun passage ne doit sortir.",
   "hero_metric_mcp_value": "CLI + API + MCP",
@@ -53,9 +53,9 @@
   "demo_scenario_drive_title": "Drive synchronisé",
   "demo_scenario_drive_description": "Lisez les PDF, XLSX et DOCX d'un dossier Google Drive synchronisé localement, puis transformez-les en contexte d'implémentation cité.",
   "demo_scenario_youtube_title": "Script YouTube",
-  "demo_scenario_youtube_description": "Un script local récupère une recherche citée, l'IA de votre choix rédige l'épisode et une personne le valide avant publication.",
+  "demo_scenario_youtube_description": "Un script local récupère des passages cités dans les sources de recherche, l'IA de votre choix rédige l'épisode et une personne le valide avant publication.",
   "demo_scenario_visa_title": "Projet de visa",
-  "demo_scenario_visa_description": "Un script local transforme un corpus administratif en liste de contrôle datée, toujours soumise à une vérification humaine et aux sources officielles.",
+  "demo_scenario_visa_description": "Un script local transforme un corpus administratif en liste de contrôle datée, qui doit toujours être validée par une personne et vérifiée auprès des sources officielles.",
   "demo_replay_label": "Rejouer le scénario",
   "demo_badge_word": "DOCX local",
   "demo_badge_monorepo": "Bases imbriquées",
@@ -64,9 +64,13 @@
   "demo_badge_visa": "Dossier privé",
   "demo_script_prefix": "Script local",
   "demo_word_prompt": "Implémente la récupération de compte à partir de ces exigences. Cite chaque règle.",
+  "demo_word_search_command": "ragmir_search({ query: \"récupération de compte verrouillage critères d'acceptation\", topK: 5 })",
   "demo_monorepo_prompt": "Explique le fonctionnement de l'authentification entre les packages. Cite chaque responsable et chaque contrat.",
+  "demo_monorepo_search_command": "ragmir_search({ query: \"flux d'authentification responsables des packages prise en main\", topK: 5 })",
   "demo_drive_prompt": "Implémente les invitations d'équipe à partir de la feuille de route, des récits et de l'architecture. Cite chaque règle.",
+  "demo_drive_search_command": "ragmir_search({ query: \"périmètre de la fonctionnalité dépendances critères d'acceptation\", topK: 5 })",
   "demo_youtube_prompt": "Rédige l'épisode à partir de ce brief cité et respecte le guide éditorial de la chaîne.",
+  "demo_youtube_draft_command": "node scripts/draft-episode.mjs \"Pourquoi les habitudes durent plus longtemps que la motivation\"",
   "demo_word_out_setup": ".ragmir/ reste ignoré par Git ; l'intégration Codex et le lanceur local sont prêts.",
   "demo_word_out_indexed": "Indexé en local : 2 DOCX | 74 segments | aucun téléversement.",
   "demo_word_out_rules": "Règles : jeton valable 15 minutes, verrouillage après cinq échecs et e-mail qui ne révèle jamais si le compte existe.",
@@ -147,7 +151,7 @@
   "agents_automation_text": "Les scripts locaux, les outils de bureau et les tâches CI consomment des résultats typés ou JSON, avec ou sans modèle génératif.",
   "use_cases_eyebrow": "Cas d'usage",
   "use_cases_title": "Cinq workflows locaux construits autour de fichiers projet réalistes.",
-  "use_cases_text": "Qu'il s'agisse de cahiers des charges privés, de monorepos, de dossiers Drive synchronisés, de recherche média ou de dossiers administratifs, chaque flux garde l'index en local et renvoie des citations.",
+  "use_cases_text": "Qu'il s'agisse de cahiers des charges privés, de monorepos, de dossiers Drive synchronisés, de recherche média ou de dossiers administratifs, chaque flux garde l'indexation en local, effectue la recherche hors ligne et renvoie des citations.",
   "use_cases_tabs_label": "Explorateur des cas d'usage pour développeurs",
   "use_cases_previous": "Cas d'usage précédent",
   "use_cases_next": "Cas d'usage suivant",
@@ -157,8 +161,8 @@
   "use_cases_evidence_label": "Sources locales",
   "use_cases_retrieval_step_label": "Recherche",
   "use_cases_result_label": "Résultat cité",
-  "use_case_spec_tab": "Spec privée",
-  "use_case_spec_title": "Développez depuis un cahier des charges privé.",
+  "use_case_spec_tab": "Spécification privée",
+  "use_case_spec_title": "Développez à partir d'un cahier des charges privé.",
   "use_case_spec_description": "Transformez un cahier des charges privé en preuves prêtes pour l'implémentation.",
   "use_case_spec_request": "Codex reçoit une fonctionnalité de récupération de compte à développer.",
   "use_case_spec_evidence": "Les spécifications Word privées restent sur la machine.",
@@ -168,32 +172,29 @@
   "use_case_monorepo_title": "Accélérez la prise en main d'un monorepo.",
   "use_case_monorepo_description": "Répondez aux questions d'architecture à partir de la documentation racine et de celle des packages.",
   "use_case_monorepo_question": "Un développeur demande comment l'authentification fonctionne dans le monorepo.",
-  "use_case_monorepo_retrieval": "Ragmir cherche dans la racine et les packages comme dans une base citée unique.",
+  "use_case_monorepo_retrieval": "Ragmir interroge les bases pertinentes de la racine et des packages sans fusionner leurs index.",
   "use_case_monorepo_result": "L'agent renvoie une carte avec responsables, dépendances et sources.",
   "use_case_drive_tab": "Drive synchronisé",
-  "use_case_drive_title": "Développez depuis un dossier Drive synchronisé.",
+  "use_case_drive_title": "Développez à partir d'un dossier Drive synchronisé.",
   "use_case_drive_description": "Réconciliez les documents produit avant que l'agent implémente une fonctionnalité.",
   "use_case_drive_evidence": "Feuille de route, tableur et architecture restent dans un dossier local synchronisé.",
   "use_case_drive_request": "Un agent de code reçoit une demande de fonctionnalité au contexte incomplet.",
-  "use_case_drive_retrieval": "Ragmir compare les exigences utiles entre fichiers et cite les contradictions.",
+  "use_case_drive_retrieval": "Ragmir compare les exigences entre les fichiers et cite les contradictions.",
   "use_case_drive_plan": "L'agent ordonne les dépendances et critères d'acceptation à partir des preuves.",
-  "use_case_drive_result": "La fonctionnalité et ses tests restent traçables aux sources produit.",
+  "use_case_drive_result": "La fonctionnalité et ses tests restent rattachés aux sources produit.",
   "use_case_youtube_tab": "Scripts YouTube",
   "use_case_youtube_title": "Rédigez un script YouTube appuyé par des citations.",
-  "use_case_youtube_description": "Appuyez le brouillon sur les sources et la ligne éditoriale avant validation humaine.",
+  "use_case_youtube_description": "Fondez le brouillon sur les recherches et la ligne éditoriale avant validation humaine.",
   "use_case_youtube_evidence": "PDF, notes et règles éditoriales restent dans un corpus local.",
   "use_case_youtube_request": "Un script de rédaction local part du sujet du prochain épisode.",
-  "use_case_youtube_retrieval": "Ragmir retrouve faits, citations et règles de ton avec leurs sources.",
-  "use_case_youtube_result": "Votre IA rédige l'épisode depuis ces preuves, puis un humain le valide.",
+  "use_case_youtube_retrieval": "Ragmir retrouve les faits, les extraits et les règles de ton utiles, avec leurs sources.",
+  "use_case_youtube_result": "Votre IA rédige l'épisode à partir de ces preuves, puis une personne le valide.",
   "use_case_visa_tab": "Projet de visa",
-  "use_case_visa_title": "Appuyez un projet de visa sur vos documents locaux.",
+  "use_case_visa_title": "Pilotez un projet de visa à partir de vos documents locaux.",
   "use_case_visa_description": "Gardez une liste datée fondée sur un corpus local qui évolue.",
   "use_case_visa_request": "Un script local rassemble formulaires, justificatifs et guides officiels à jour.",
-  "use_case_visa_retrieval": "Ragmir retrouve exigences, échéances et preuves manquantes avec leurs sources.",
+  "use_case_visa_retrieval": "Ragmir retrouve les exigences, les échéances et les justificatifs manquants avec leurs sources.",
   "use_case_visa_result": "Le script met à jour une liste datée à vérifier avant toute action.",
-  "use_case_audio_eyebrow": "Audio et mini-formation",
-  "use_case_audio_title": "Écoutez un dossier dense plutôt que de le lire.",
-  "use_case_audio_text": "Générez un court résumé MP3 ou WAV à partir de passages cités pour réviser une spécification, une architecture ou une veille loin de l'écran.",
   "seo_team_title": "L'équipe derrière Ragmir",
   "seo_team_description": "Découvrez l'équipe qui développe Ragmir, un RAG local open source pour agents de code et scripts, fondé sur des documents de projet cités.",
   "team_eyebrow": "L'équipe",
@@ -210,7 +211,7 @@
   "faq_what_question": "Qu'est-ce que Ragmir ?",
   "faq_what_answer": "Ragmir est un RAG local open source pour agents et scripts sur Node.js : une bibliothèque, une CLI et un serveur MCP local qui transforment les fichiers choisis en contexte cité et interrogeable. Il complète la mémoire des agents et la recherche de code native pour les specs, runbooks, contrats, PDF et autres documents projet. Le parcours par défaut fonctionne hors ligne sans téléchargement de modèle.",
   "faq_private_question": "Ragmir envoie-t-il mon code ou mes documents confidentiels ?",
-  "faq_private_answer": "Ragmir indexe uniquement les dossiers locaux que vous choisissez et garde l'état généré dans le dossier .ragmir/ ignoré par Git. La recherche du cœur n'ajoute ni télémétrie ni envoi de documents. La configuration explicite des modèles télécharge des poids publics, jamais vos documents ; un agent cloud peut recevoir les passages cités lorsque vous choisissez de l'utiliser.",
+  "faq_private_answer": "Ragmir indexe uniquement les dossiers locaux que vous choisissez et garde l'état généré dans le dossier .ragmir/ ignoré par Git. La recherche effectuée par Core n'ajoute aucune télémétrie et n'envoie aucun document. La configuration explicite des modèles télécharge des poids publics, jamais vos documents ; un agent cloud peut recevoir les passages cités lorsque vous choisissez de l'utiliser.",
   "faq_agents_question": "Avec quels agents IA et outils Ragmir fonctionne-t-il ?",
   "faq_agents_answer": "Ragmir Core est indépendant du modèle. Les intégrations couvrent Claude Code, Codex, Kimi, OpenCode et Cline. Les autres clients MCP, scripts locaux, outils de bureau et tâches CI utilisent les mêmes résultats cités.",
   "faq_offline_question": "Ragmir nécessite-t-il une clé API, un téléchargement de modèle ou une connexion internet ?",
@@ -238,11 +239,11 @@
   "footer_link_releases": "Versions",
   "footer_link_changelog": "Changelog",
   "footer_link_api": "Référence API",
-  "footer_text": "Ragmir est le RAG local de JCode Labs pour les agents et scripts qui ont besoin d'un contexte projet cité.",
+  "footer_text": "Ragmir est le RAG local de JCode Labs pour les agents et les scripts qui doivent interroger hors ligne des documents de projet privés, avec des citations.",
   "footer_version_label": "Version actuelle de Ragmir sur npm",
   "strengths_eyebrow": "Pensé pour être utile",
   "strengths_title": "Conçu pour les documents que votre recherche de code ne voit pas.",
-  "strengths_text": "Ragmir transforme les documents privés et dispersés du projet en un socle de preuves local que les agents de code et scripts locaux peuvent interroger via MCP, CLI ou TypeScript.",
+  "strengths_text": "Ragmir transforme les documents privés et dispersés du projet en un socle de preuves local que les agents de code et les scripts peuvent interroger hors ligne via MCP, CLI ou TypeScript.",
   "strengths_best_title": "Là où Ragmir est le plus utile",
   "strengths_best_item_1_title": "La connaissance du projet au-delà du code",
   "strengths_best_item_1": "Recherchez dans les PDF, DOCX, XLSX, specs, contrats et runbooks aux côtés du dépôt qu'ils expliquent.",
@@ -251,7 +252,7 @@
   "strengths_best_item_3_title": "Un corpus qui reste à vous",
   "strengths_best_item_3": "Gardez l'index en local et associez Ragmir à un consommateur local lorsqu'aucun passage cité ne doit quitter le poste.",
   "strengths_best_item_4_title": "Des preuves réutilisables par les agents et scripts",
-  "strengths_best_item_4": "Donnez aux agents de code et scripts locaux des passages traçables avec références de fichier, ligne, chunk et page PDF.",
+  "strengths_best_item_4": "Donnez aux agents de code et scripts locaux des passages traçables avec les références du fichier, de la ligne, du segment et de la page PDF.",
   "strengths_limits_eyebrow": "Aucune couche superflue",
   "strengths_limits_title": "Gardez le chemin le plus simple quand il suffit.",
   "strengths_limits_text": "Ragmir complète les outils qui font déjà bien leur travail. Ajoutez-le lorsque le corpus rend la recherche locale et citée réellement utile.",
diff --git a/packages/ragmir-landing/package.json b/packages/ragmir-landing/package.json
index 5a9732c..8486cc0 100644
--- a/packages/ragmir-landing/package.json
+++ b/packages/ragmir-landing/package.json
@@ -2,7 +2,7 @@
   "name": "@jcode.labs/ragmir-landing",
   "version": "0.4.10",
   "private": true,
-  "description": "Static site for Ragmir, local RAG with verifiable citations for coding agents and scripts.",
+  "description": "Static site for Ragmir, local RAG with offline cited retrieval for coding agents and scripts.",
   "type": "module",
   "scripts": {
     "build": "node scripts/astro-no-telemetry.mjs check && node scripts/astro-no-telemetry.mjs build",
diff --git a/packages/ragmir-landing/public/llms.txt b/packages/ragmir-landing/public/llms.txt
index 636c394..237d0bf 100644
--- a/packages/ragmir-landing/public/llms.txt
+++ b/packages/ragmir-landing/public/llms.txt
@@ -1,8 +1,9 @@
 # Ragmir
 
-Ragmir is open-source local RAG for your coding agents and scripts on Node.js. It indexes the files
-selected by the project, stores the index under ignored `.ragmir/` state, and returns source-backed
-passages through a CLI, TypeScript API, or local read-focused MCP server.
+Ragmir is open-source local RAG for your coding agents and scripts on Node.js. It indexes selected
+project files on the user's machine, keeps the corpus and generated index under ignored `.ragmir/`
+state, and retrieves source-backed passages offline by default through a CLI, TypeScript API, or
+local read-focused MCP server. Core does not upload source documents to a hosted RAG service.
 
 ## Product boundary
 
diff --git a/packages/ragmir-landing/src/components/hero-demo-script.ts b/packages/ragmir-landing/src/components/hero-demo-script.ts
index 6d20be1..6fc5da4 100644
--- a/packages/ragmir-landing/src/components/hero-demo-script.ts
+++ b/packages/ragmir-landing/src/components/hero-demo-script.ts
@@ -55,7 +55,7 @@ export const HERO_DEMO_SCENARIOS: readonly HeroDemoScenario[] = [
       { kind: "codex", textKey: "demo_word_prompt" },
       {
         kind: "mcp",
-        text: 'ragmir_search({ query: "account recovery lockout acceptance criteria", topK: 5 })',
+        textKey: "demo_word_search_command",
       },
       { kind: "citation", text: "[1] private/specification.docx:L12-L18#2" },
       { kind: "citation", text: "[2] private/acceptance-criteria.docx:L7-L13#1" },
@@ -84,7 +84,7 @@ export const HERO_DEMO_SCENARIOS: readonly HeroDemoScenario[] = [
       { kind: "codex", textKey: "demo_monorepo_prompt" },
       {
         kind: "mcp",
-        text: 'ragmir_search({ query: "authentication flow package owners onboarding", topK: 5 })',
+        textKey: "demo_monorepo_search_command",
       },
       { kind: "citation", text: "[1] docs/adr/0042-auth-contract.md:L18-L31#3" },
       { kind: "citation", text: "[2] packages/api-client/docs/auth.md:L11-L24#2" },
@@ -118,7 +118,7 @@ export const HERO_DEMO_SCENARIOS: readonly HeroDemoScenario[] = [
       { kind: "codex", textKey: "demo_drive_prompt" },
       {
         kind: "mcp",
-        text: 'ragmir_search({ query: "feature scope dependencies acceptance criteria", topK: 5 })',
+        textKey: "demo_drive_search_command",
       },
       { kind: "citation", text: "[1] roadmap.pdf:p4:L88-L102#5" },
       { kind: "citation", text: "[2] stories.xlsx:L42-L48#8" },
@@ -149,7 +149,7 @@ export const HERO_DEMO_SCENARIOS: readonly HeroDemoScenario[] = [
       { kind: "success", textKey: "demo_youtube_out_indexed", holdMs: 1400 },
       {
         kind: "shell",
-        text: 'node scripts/draft-episode.mjs "Why habits outlast motivation"',
+        textKey: "demo_youtube_draft_command",
       },
       { kind: "script", textKey: "demo_youtube_script_research" },
       { kind: "citation", text: "[1] library/research.pdf:p8:L142-L156#9" },
diff --git a/packages/ragmir-landing/src/components/use-case-carousel.tsx b/packages/ragmir-landing/src/components/use-case-carousel.tsx
index 9e9e1d9..bd267e6 100644
--- a/packages/ragmir-landing/src/components/use-case-carousel.tsx
+++ b/packages/ragmir-landing/src/components/use-case-carousel.tsx
@@ -461,26 +461,31 @@ function MobileWorkflow({
   }
 
   return (
-    <ol
-      className="flex w-full flex-col bg-background/50 p-4 lg:hidden"
+    <div
+      className="h-full overflow-y-auto overscroll-y-contain bg-background/50 [scrollbar-width:thin] lg:hidden [&::-webkit-scrollbar]:w-1.5 [&::-webkit-scrollbar-thumb]:rounded-full [&::-webkit-scrollbar-thumb]:bg-border [&::-webkit-scrollbar-track]:bg-transparent"
       data-workflow-canvas={useCase.id}
+      data-workflow-scroll-region="true"
     >
-      {nodes.map((node, index) => {
-        const ports: readonly WorkflowPort[] =
-          index === 0 ? ["bottom"] : index === nodes.length - 1 ? ["top"] : ["top", "bottom"]
+      <ol className="flex min-h-full w-full flex-col justify-center p-4">
+        {nodes.map((node, index) => {
+          const ports: readonly WorkflowPort[] =
+            index === 0 ? ["bottom"] : index === nodes.length - 1 ? ["top"] : ["top", "bottom"]
 
-        return (
-          <li className="flex flex-col" key={`${useCase.id}-${node.label}`}>
-            <WorkflowNode {...node} ports={ports} />
-            {index < nodes.length - 1 ? (
-              <div className="h-10">
-                <VerticalConnector id={`${node.nodeId}-to-${nodes[index + 1]?.nodeId ?? "next"}`} />
-              </div>
-            ) : null}
-          </li>
-        )
-      })}
-    </ol>
+          return (
+            <li className="flex flex-col" key={`${useCase.id}-${node.label}`}>
+              <WorkflowNode {...node} ports={ports} />
+              {index < nodes.length - 1 ? (
+                <div className="h-10">
+                  <VerticalConnector
+                    id={`${node.nodeId}-to-${nodes[index + 1]?.nodeId ?? "next"}`}
+                  />
+                </div>
+              ) : null}
+            </li>
+          )
+        })}
+      </ol>
+    </div>
   )
 }
 
@@ -543,8 +548,8 @@ export function UseCaseCarousel({ translations }: UseCaseCarouselProps): React.J
               key={useCase.id}
               value={useCase.id}
             >
-              <Card className="w-full min-w-0 overflow-hidden bg-card/90 lg:h-full">
-                <CardHeader className="gap-4 border-b border-border md:grid md:grid-cols-[minmax(0,1fr)_auto] md:items-center lg:h-[5.5rem] lg:py-4">
+              <Card className="flex h-[55rem] w-full min-w-0 flex-col overflow-hidden bg-card/90 md:h-[49rem] lg:h-full">
+                <CardHeader className="h-48 shrink-0 gap-4 border-b border-border md:grid md:h-[7.5rem] md:grid-cols-[minmax(0,1fr)_auto] md:items-center lg:h-[5.5rem] lg:py-4">
                   <div className="flex min-w-0 flex-col gap-2">
                     <CardTitle className="max-w-2xl text-xl leading-tight">
                       {t(useCase.titleKey)}
@@ -584,7 +589,7 @@ export function UseCaseCarousel({ translations }: UseCaseCarouselProps): React.J
                   </div>
                 </CardHeader>
 
-                <CardContent className="flex w-full min-w-0 flex-col pt-5 lg:flex-1 lg:px-0">
+                <CardContent className="flex min-h-0 w-full min-w-0 flex-1 flex-col pt-5 lg:px-0">
                   <DesktopWorkflow translations={translations} useCase={useCase} />
                   <MobileWorkflow translations={translations} useCase={useCase} />
                 </CardContent>
diff --git a/packages/ragmir-tts/README.md b/packages/ragmir-tts/README.md
index 41980b5..9156afb 100644
--- a/packages/ragmir-tts/README.md
+++ b/packages/ragmir-tts/README.md
@@ -7,10 +7,11 @@
 
 **Optional local audio for your coding-agent RAG workflow.**
 
-Ragmir Core retrieves cited project evidence, your coding agent turns it into a reviewable brief,
-and `@jcode.labs/ragmir-tts` renders the approved text as audio. The default Transformers.js path
-produces WAV locally after model preparation. An explicit Edge mode produces online MP3 only when
-sending narration text to that service is acceptable.
+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. Your coding agent turns that
+evidence into a reviewable brief, and `@jcode.labs/ragmir-tts` renders the approved text as audio.
+The default Transformers.js path produces WAV locally after model preparation. An explicit Edge
+mode produces online MP3 only when sending narration text to that service is acceptable.
 
 [Ragmir overview](https://github.com/jcode-works/jcode-ragmir#readme) ·
 [Documentation](https://github.com/jcode-works/jcode-ragmir/wiki) ·
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2166e40..afa27f0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -54,12 +54,6 @@ importers:
       '@huggingface/transformers':
         specifier: ^4.2.0
         version: 4.2.0
-      '@jcode.labs/ragmir-chat':
-        specifier: workspace:*
-        version: link:../ragmir-chat
-      '@jcode.labs/ragmir-tts':
-        specifier: workspace:*
-        version: link:../ragmir-tts
       '@lancedb/lancedb':
         specifier: ^0.30.0
         version: 0.30.0(apache-arrow@18.1.0)
@@ -97,6 +91,12 @@ importers:
         specifier: ^4.1.13
         version: 4.4.3
     devDependencies:
+      '@jcode.labs/ragmir-chat':
+        specifier: workspace:*
+        version: link:../ragmir-chat
+      '@jcode.labs/ragmir-tts':
+        specifier: workspace:*
+        version: link:../ragmir-tts
       '@types/html-to-text':
         specifier: ^9.0.4
         version: 9.0.4
diff --git a/scripts/semantic-release-verify.mjs b/scripts/semantic-release-verify.mjs
index 5913583..87f4610 100644
--- a/scripts/semantic-release-verify.mjs
+++ b/scripts/semantic-release-verify.mjs
@@ -5,7 +5,9 @@ import { fileURLToPath } from "node:url"
 
 const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
 const packageDirs = ["packages/ragmir-tts", "packages/ragmir-chat", "packages/ragmir-core"]
+const optionalCorePackages = ["@jcode.labs/ragmir-chat", "@jcode.labs/ragmir-tts"]
 const checkOnly = process.argv.includes("--check")
+let coreManifest
 
 for (const directory of packageDirs) {
   const manifest = JSON.parse(
@@ -14,6 +16,21 @@ for (const directory of packageDirs) {
   if (manifest.publishConfig?.access !== "public") {
     throw new Error(`${manifest.name} must publish with public access`)
   }
+  if (directory === "packages/ragmir-core") {
+    coreManifest = manifest
+  }
+}
+
+for (const packageName of optionalCorePackages) {
+  if (coreManifest?.dependencies?.[packageName] !== undefined) {
+    throw new Error(`${packageName} must not be installed as a Core dependency`)
+  }
+  if (
+    typeof coreManifest?.peerDependencies?.[packageName] !== "string" ||
+    coreManifest.peerDependenciesMeta?.[packageName]?.optional !== true
+  ) {
+    throw new Error(`${packageName} must remain an optional Core peer dependency`)
+  }
 }
 
 if (checkOnly) {