feat(core)!: add portable knowledge bases and compact MCP defaults

Release highlights:
- export verified, relocatable knowledge-base folders for agents and automations
- return compact MCP evidence by default to reduce agent context use

Release details:
- **Portable bundles:** add export, verify, native, MCP, OpenClaw, and generic adapters
- **Agent UX:** guide three compact citations followed by targeted citation expansion
- **Reliability:** defer automatic LanceDB compaction while preserving manual optimization
- **Documentation:** synchronize Core API, setup, team workflow, and the bilingual landing

Verification:
- pass pnpm validate with tests, builds, package checks, smoke tests, and release gates
- verify English desktop and French mobile pages without browser or network errors

BREAKING CHANGE: MCP search, ask, and research now return compact snippets by default.
Set compact: false when a client needs the previous full-text payload.

Author: jb-thery

README.md

@@ -27,7 +27,7 @@ The fastest path is to let your coding agent inspect the repository and tailor t
 <summary><strong>Option 1: paste this into your coding agent</strong></summary>
 
 ~~~text
-Set up Ragmir in this repository. Work interactively: inspect first, ask one concise numbered batch of questions, wait for my answers, then execute. Never assume consent for dependency changes, model downloads, replacing skills, or sharing data.
+Set up Ragmir in this repository. Work interactively: inspect first, infer safe defaults, present a proposal, wait for approval, then execute. Never assume consent for dependency changes, model downloads, replacing skills, or sharing data.
 
 Outcome: Core installed with the repository's package manager; useful sources selected; secrets and generated noise excluded; tools connected; cited retrieval verified. Semantic retrieval, team features, Chat, and TTS are optional.
 
@@ -36,14 +36,12 @@ Outcome: Core installed with the repository's package manager; useful sources se
 - Detect Node 22+ and pnpm, npm, Yarn, or Bun. Prefer packageManager, then the lockfile. Respect workspace-root flags and mise/asdf/Volta. Never create a second lockfile. If signals conflict, ask.
 - If Ragmir exists, inspect its version, config, status, sources, and rgr upgrade --check before changing it.
 
-2. Ask only what the repository did not answer, then wait:
-1) Which repository/monorepo base should own the knowledge base, and are nested app bases wanted?
-2) Which clients: Claude Code, Codex, Kimi, OpenCode, Cline, another MCP client, or none?
-3) Keep default offline local-hash, or allow one semantic-model download for better natural-language retrieval?
-4) Solo or team? If team, is Git upstream authoritative, and should safe pulls be automatic or disabled with --no-pull?
-5) Core only, or optional Chat? For Chat choose lite (~0.49 GB), fast (~3.35 GB), or quality (~5.15 GB).
-6) Optional TTS? Ask language (en/fr/es offline; ja/th/zh require explicit Edge unless a local model is supplied) and whether text may reach Edge.
-7) Which private/external folders are allowed, which must never be indexed, and may I install packages, edit local config, and run approved downloads now?
+2. Propose one setup summary, then ask once:
+- Infer the owning base and useful clients from the repository. State any nested bases you propose.
+- Default to offline local-hash and Core only, or optional Chat only when requested. Optional TTS stays off unless requested. Semantic, Chat, and TTS downloads require explicit approval; Edge text transfer requires separate approval.
+- Default to solo unless the repository or request shows a team workflow. For a Git-backed team, propose the current upstream as authority and safe automatic pulls; offer --no-pull when Git updates must stay manual.
+- List selected source globs, exclusions, any external/private folder, and the exact package, config, skill, and download actions you would perform.
+- Ask only about unresolved choices that materially change source authority, data exposure, downloads, or external execution. Wait for one approval covering the proposal.
 
 3. Implement after approval:
 - Install @jcode.labs/ragmir as a dev dependency with the detected manager. Install Chat/TTS only if selected, at a compatible version.
@@ -132,7 +130,7 @@ authentication, authorization, and rate limits.
 | --- | --- | --- |
 | `rgr` CLI | Setup, ingest, search, audit, and maintenance | Human-readable or JSON output |
 | TypeScript API | Scripts and long-running Node.js workers | Typed results and explicit lifecycle |
-| Local MCP server | Coding agents and compatible clients | Bounded, read-focused retrieval tools |
+| Local MCP server | Coding agents and compatible clients | Up to three compact citations by default, with targeted expansion |
 | Ragmir Chat | Fully local answer generation | Answers grounded in verified cited passages |
 | Ragmir TTS | Reviewed text briefs | Local WAV or explicit online MP3 |
 
@@ -145,6 +143,9 @@ are optional packages loaded only when their commands are used.
 
 Generated MCP helpers pin the project root so an agent queries the intended index. In a monorepo,
 Ragmir selects the nearest `.ragmir/config.json`; root and package bases stay isolated.
+MCP search, ask, and research are compact by default. Agents expand one selected citation instead of
+loading every full passage; research may add up to three code matches, and `compact: false` remains
+available for an explicit full response.
 
 ```bash
 pnpm exec rgr bases
@@ -154,6 +155,36 @@ pnpm exec rgr --project-root apps/web search "checkout contract"
 Read the [agent integration guide](./docs/agent-integration.md) for native helpers, MCP tools,
 resource budgets, and monorepo routing.
 
+### Portable knowledge-base folders
+
+Export one frozen, relocatable folder when another machine, agent, or automation needs the same
+cited evidence without the original source tree:
+
+```bash
+pnpm exec rgr portable export
+pnpm exec rgr portable export --output ../operations-knowledge --name "Operations knowledge"
+pnpm exec rgr portable export --output ../operations-knowledge --replace
+```
+
+The folder contains the active index, any required local embedding model, an embedded read-only
+runtime, two retrieval and decision-evidence skills, MCP templates, and a SHA-256 inventory. It
+excludes raw source files and access logs, but the indexed passages remain sensitive. Move the
+folder to a Node.js 22 host with the platform recorded in `manifest.json`, run
+`node bin/rgr.cjs portable verify . --json`, then generate a destination-specific configuration
+with `node bin/configure.cjs generic` or a native Claude, Codex, Kimi, OpenCode, or Cline target.
+No package-manager install or registry access is needed after transfer. The inventory detects
+changes but does not authenticate who published the folder.
+
+For a stable destination, `--replace` builds and verifies the new export before switching the path.
+The previous bundle is renamed to a timestamped sibling and returned as `previousOutputDir`; restart
+long-running consumers, verify the new bundle, then retire that backup under the operator's
+retention policy. An unrelated existing directory is never replaced.
+
+OpenClaw, Hermes, n8n, and custom hosts use the same MCP stdio or argument-array CLI contract when
+their runtime supports it. Ragmir supplies cited evidence, not permission to perform an external
+action. The host keeps authentication, tool permissions, approval rules, and network security. See
+the [portable knowledge-base guide](./docs/portable-knowledge-bases.md).
+
 ### Teams
 
 ```mermaid
@@ -307,6 +338,7 @@ and model files keep their own licenses.
 | [CLI reference](./docs/cli-reference.md) | Commands, options, and JSON output |
 | [Configuration](./docs/configuration.md) | Sources, privacy, workloads, embeddings, and extractors |
 | [Agent integration](./docs/agent-integration.md) | Native helpers, MCP, monorepos, and teams |
+| [Portable knowledge bases](./docs/portable-knowledge-bases.md) | Frozen folders for agents, automations, and servers |
 | [Troubleshooting](./docs/troubleshooting.md) | Readiness, weak search, OCR, and add-on diagnostics |
 | [Release history](https://github.com/jcode-works/jcode-ragmir/releases) | Curated highlights, verification, artifacts, and upgrade links |
 

context7.json

@@ -23,6 +23,7 @@
     "Use the canonical English setup prompt in docs/quick-start.md for a repository-aware installation; it detects the package manager and existing state, asks before changes or downloads, and verifies retrieval.",
     "Ragmir Core returns cited retrieval context only; it does not synthesize answers itself.",
     "Any compatible coding agent, script, CLI, TypeScript application, or MCP client can consume Core results; use a local consumer when no passage may leave the machine.",
+    "Use `rgr portable export` to create a frozen relocatable folder containing the active index, any required local embedding model, a restricted launcher, portable skills, MCP adapters, and a SHA-256 inventory. Raw source files and access logs are excluded, but indexed passages remain sensitive. Verify the folder after moving it and keep action authority in the host agent or automation.",
     "Use one `createRagmirClient()` per project root for repeated work in a stateful Node.js process; it caches one immutable read snapshot until atomic generation replacement and flushes metadata-only access logs during close. Use top-level functions for one-shot scripts.",
     "Ragmir does not open an HTTP port; a network-facing host owns its transport, authentication, authorization, and rate limits.",
     "`rgr chat` is optional add-on generation via @jcode.labs/ragmir-chat; the core remains retrieval-only.",
@@ -45,7 +46,7 @@
     "Generated PDF OCR setup batches up to 16 blank pages and stores private content-addressed page cache entries keyed by source, engine version, language, DPI, parser policy, and command identity. Ingest and preview report only OCR counts and timing.",
     "Vector search is exact below 100,000 rows and uses the compatible IVF-PQ policy stored in the manifest at larger sizes; set `vectorSearchMode: \"exact\"` or use `--exact-vector-search` for diagnostic comparison.",
     "Run `rgr storage optimize --dry-run --json` to inspect full-text, vector, and relative-path index coverage before applying maintenance.",
-    "MCP resources `ragmir://context` and `ragmir://sources` are bounded agent-orientation surfaces; retrieval still happens through the read-focused tools.",
+    "MCP resources `ragmir://context` and `ragmir://sources` are bounded agent-orientation surfaces; retrieval still happens through the read-focused tools. Search, ask, and research start with at most three compact document citations by default; research may add three code matches. Expand one selected citation or request `compact: false` explicitly.",
     "All ten MCP tools advertise non-destructive behavior and every tool or resource JSON response is byte-bounded. Budget pressure selects typed summaries with exact scalar values, omission counters, and the best search citation instead of shortening identifiers or paths. Search, ask, research, and evaluation conservatively advertise open-world behavior because explicitly enabled semantic models may download public weights. Tools that can initialize local state or append metadata-only logs use conservative read-only and idempotency hints. Each server refreshes its lazy client after effective configuration changes and closes it during shutdown.",
     "MCP `ragmir_evaluate` accepts only an existing project-relative golden file and rejects absolute paths, traversal, and symlinks outside the project. Strict mode returns that relative path, replaces evaluation errors with a generic message, and masks configured model, storage, source, and access-log paths in diagnostic responses."
   ]

docs/agent-integration.md

@@ -6,7 +6,8 @@ retrieval offline. Core is model-agnostic, never uploads the corpus, and never c
 
 For an interactive repository-aware installation, paste the canonical prompt from the
 [quick-start guide](./quick-start.md) into the coding agent. It detects the package manager and
-existing Ragmir state, asks one approval batch, then configures and verifies the selected clients.
+existing Ragmir state, proposes safe inferred defaults, asks for one approval, then configures and
+verifies the selected clients.
 
 Choose the handoff that matches the corpus:
 
@@ -48,6 +49,55 @@ default. Codex skills use `.agents/skills/` for both project and user discovery.
 fallback for filesystems that cannot follow symlinks. Ragmir refuses to overwrite an unmanaged
 same-name skill unless you explicitly pass `--force` after reviewing it.
 
+## Move a frozen knowledge base to another host
+
+Use a portable folder when an agent, automation, or server needs cited evidence but should not
+receive the original project tree:
+
+```bash
+rgr portable export --output ../operations-knowledge
+```
+
+Move the complete directory to a Node.js 22 host with the platform recorded in `manifest.json`, then
+verify it at the destination. The runtime and its native retrieval dependencies are embedded, so no
+package-manager install or registry access is needed after transfer:
+
+```bash
+cd /srv/operations-knowledge
+node bin/rgr.cjs portable verify . --json
+node bin/configure.cjs --list
+node bin/configure.cjs openclaw
+```
+
+For a destination path already used by agents, publish the next source revision with
+`rgr portable export --output /absolute/stable/path --replace`. Ragmir verifies the new folder first
+and preserves the old one as a timestamped sibling. Restart long-running agent processes after the
+switch, then retire the previous folder only after a representative query succeeds.
+
+Dedicated configuration output is available for OpenClaw, Claude, Codex, Kimi, OpenCode, and Cline.
+For OpenClaw, register the generated read-only server object then probe it:
+
+```bash
+openclaw mcp set ragmir "$(node bin/configure.cjs openclaw)"
+openclaw mcp doctor ragmir --probe
+```
+
+Hermes can use the generic MCP stdio configuration. n8n, CI, or a custom service can use the same MCP
+contract or invoke `node bin/rgr.cjs search ... --json` with an argument array. Do not concatenate an
+untrusted query into a shell command.
+
+Load `skills/ragmir-portable` for retrieval behavior and `skills/ragmir-decision-evidence` when an
+agent must compare options. The decision skill requires cited evidence, explicit inference and
+unknowns, and keeps action authority in the host. A knowledge-base result never authorizes a
+deployment, message, purchase, deletion, or other external side effect.
+
+The bundle is frozen. Its launcher rejects ingest, setup, repair, upgrade, storage, source, and
+deletion commands. Its MCP surface omits `ragmir_evaluate` because that operation can persist a
+quality report. Replace the bundle with a new export when source knowledge changes. Raw documents
+and access logs are excluded, but indexed passages are present and sensitive. See
+[Portable knowledge bases](./portable-knowledge-bases.md) for the complete contents, integrity
+model, runtime prerequisite, and network boundary.
+
 ## Monorepo bases
 
 A monorepo can run one root knowledge base plus isolated bases in individual apps. From the app or
@@ -196,8 +246,12 @@ files.
 
 ### Retrieve bounded evidence
 
-Use compact retrieval first, then pass a returned citation to `ragmir_expand` when the agent needs
-the exact chunk or a bounded neighbor window. Search, ask, research, expansion, audit, and evaluation
+MCP search, ask, and research start with at most three compact document citations when `topK` and
+`compact` are omitted; research may add up to three code matches. Pass one returned citation to
+`ragmir_expand` when the agent needs the exact chunk or a
+bounded neighbor window. Use `compact: false` with an explicit `topK` only when the complete
+retrieval payload is required. CLI output is unchanged and needs an explicit `--compact` flag.
+Search, ask, research, expansion, audit, and evaluation
 accept `maxBytes`. Variable-size tool and resource JSON is bounded by `mcpMaxOutputBytes` and an
 absolute 1 MiB server ceiling; every response has an explicit full or summary schema. Responses
 stay parseable, while `_meta["ragmir/output"]` reports the active budget, returned bytes, and
@@ -220,6 +274,9 @@ ignored local state or append metadata-only access logs. `ragmir_evaluate` accep
 project-relative golden file; absolute paths, traversal, and symlinks that escape the project are
 rejected. Strict mode returns that relative path, replaces evaluation failures with a generic
 message, and masks configured model, storage, source, and access-log paths in diagnostic responses.
+The server also publishes concise protocol instructions for the context, compact retrieval,
+single-citation expansion, and read-only evidence flow, so compatible clients do not need to infer
+the sequence from tool names.
 
 The generated helpers cover Claude Code, Codex, Kimi, OpenCode, and Cline. Other tools can consume
 the same evidence through the CLI, TypeScript API, or any compatible MCP client. Hermes, n8n