From 276181026699efa45b5a50eed974eb7663c6e4df Mon Sep 17 00:00:00 2001
From: Jean-Baptiste THERY <jb.thery@jcode.works>
Date: Mon, 13 Jul 2026 03:18:02 +0700
Subject: [PATCH] feat(core): add inspectable retrieval and monorepo routing
 (#91)

---
 AGENTS.md                                     |   1 +
 CLAUDE.md                                     |   3 +
 README.md                                     |  40 +++-
 context7.json                                 |   5 +-
 docs/agent-integration.md                     |  28 +++
 docs/api-reference.md                         |  18 +-
 docs/cli-reference.md                         |  26 ++-
 llms.txt                                      |   9 +-
 packages/ragmir-core/README.md                |  10 +
 packages/ragmir-core/scripts/mcp-smoke.mjs    |  77 ++++++++
 packages/ragmir-core/skills/ragmir/SKILL.md   |  28 +++
 packages/ragmir-core/src/chunk-stats.test.ts  |  36 ++++
 packages/ragmir-core/src/chunk-stats.ts       |  40 ++++
 packages/ragmir-core/src/cli.ts               | 172 +++++++++++++++++-
 packages/ragmir-core/src/config.test.ts       |  20 ++
 .../ragmir-core/src/context-resources.test.ts |  64 +++++++
 packages/ragmir-core/src/context-resources.ts | 103 +++++++++++
 packages/ragmir-core/src/evaluate.test.ts     |  45 ++++-
 packages/ragmir-core/src/evaluate.ts          |   8 +
 packages/ragmir-core/src/index.ts             |  17 ++
 packages/ragmir-core/src/ingest.test.ts       |   4 +
 packages/ragmir-core/src/ingest.ts            |  10 +-
 .../ragmir-core/src/knowledge-bases.test.ts   |  72 ++++++++
 packages/ragmir-core/src/knowledge-bases.ts   | 129 +++++++++++++
 packages/ragmir-core/src/mcp.test.ts          |  27 ++-
 packages/ragmir-core/src/mcp.ts               | 119 +++++++++++-
 packages/ragmir-core/src/preview.test.ts      |  76 ++++++++
 packages/ragmir-core/src/preview.ts           | 161 ++++++++++++++++
 packages/ragmir-core/src/query.test.ts        |  96 ++++++++++
 packages/ragmir-core/src/query.ts             | 106 ++++++++---
 packages/ragmir-core/src/research.ts          |   2 +
 packages/ragmir-core/src/setup.ts             |   2 +-
 packages/ragmir-core/src/skill.test.ts        |  49 ++++-
 packages/ragmir-core/src/skill.ts             |  58 +++++-
 packages/ragmir-core/src/types.ts             | 145 +++++++++++++++
 packages/ragmir-landing/messages/en.json      |  14 +-
 packages/ragmir-landing/messages/fr.json      |  14 +-
 scripts/smoke.mjs                             |  90 ++++++++-
 38 files changed, 1852 insertions(+), 72 deletions(-)
 create mode 100644 packages/ragmir-core/src/chunk-stats.test.ts
 create mode 100644 packages/ragmir-core/src/chunk-stats.ts
 create mode 100644 packages/ragmir-core/src/context-resources.test.ts
 create mode 100644 packages/ragmir-core/src/context-resources.ts
 create mode 100644 packages/ragmir-core/src/knowledge-bases.test.ts
 create mode 100644 packages/ragmir-core/src/knowledge-bases.ts
 create mode 100644 packages/ragmir-core/src/preview.test.ts
 create mode 100644 packages/ragmir-core/src/preview.ts

diff --git a/AGENTS.md b/AGENTS.md
index 5aa8527..85d23b6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -29,6 +29,7 @@
 - Keep `docs/` concise and task-oriented: CLI, API, configuration, agent integration, troubleshooting, local chat, and local TTS. Remove future plans and obsolete surfaces rather than documenting them.
 - Package READMEs are brief npm entrypoints that link to the root README.
 - Keep `llms.txt` and `context7.json` aligned with public documentation and generated-output exclusions.
+- When code changes public behavior, commands, configuration, supported formats, architecture, or product claims, update the relevant docs and landing in the same change. For internal-only changes, verify both surfaces and leave them unchanged when no update is needed.
 
 ## Validation
 
diff --git a/CLAUDE.md b/CLAUDE.md
index ac5a197..3ba7899 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -21,6 +21,9 @@ Use `pnpm --filter @jcode.labs/ragmir <script>` for Core-only work. The pinned N
 
 Generated `dist/`, `.astro/`, `release-artifacts/`, and `.ragmir/` directories are ignored. Do not
 commit them. The root README is the canonical documentation entrypoint; keep package READMEs short.
+When code changes public behavior, commands, configuration, supported formats, architecture, or
+product claims, update the relevant docs and landing in the same change. For internal-only changes,
+verify both surfaces and leave them unchanged when no update is needed.
 
 ## Boundaries
 
diff --git a/README.md b/README.md
index c6b2e42..107e51a 100644
--- a/README.md
+++ b/README.md
@@ -78,18 +78,44 @@ pnpm exec rgr doctor
 
 Setup writes local helper files for the selected agents. The MCP surface is intentionally bounded
 and read-focused. Agents can request compact evidence first, then expand one returned citation
-without opening a second index or reading arbitrary files.
+without opening a second index or reading arbitrary files. MCP clients can read `ragmir://context`
+for a compact base, readiness, freshness, and capability overview before choosing a tool.
+
+### Route knowledge in a monorepo
+
+```bash
+pnpm exec rgr bases
+pnpm exec rgr --project-root apps/web search "checkout contract"
+```
+
+Ragmir selects the nearest `.ragmir/config.json` from the working directory. A monorepo can keep a
+root base for shared knowledge and isolated bases in individual apps. `rgr bases` shows the active
+base, generated MCP helpers pin their project root, and nested bases receive distinct server names
+so agents do not silently query the wrong index.
 
 ### Audit a knowledge base
 
 ```bash
+pnpm exec rgr preview --path docs --max-chunks 3
 pnpm exec rgr audit --unsupported
 pnpm exec rgr security-audit
 pnpm exec rgr research "release obligations" --compact
 ```
 
 Use this path for policies, runbooks, specifications, contracts, and other corpora where the answer
-must remain traceable to evidence.
+must remain traceable to evidence. `preview` shows redacted chunks, structural context, citations,
+and size distributions without writing an index.
+
+### Explain retrieval decisions
+
+```bash
+pnpm exec rgr search "release approval" --explain
+pnpm exec rgr search "release approval" --context-path "Operations > Release"
+```
+
+Explanations expose reciprocal-rank-fusion contributions, vector and lexical ranks, backend scores,
+and matched terms without changing default ranking. Structural filters can target Markdown heading
+paths or JSON paths before candidate retrieval.
 
 ### Enable semantic retrieval
 
@@ -130,15 +156,19 @@ import { ingest, search } from "@jcode.labs/ragmir"
 
 await ingest({ cwd: process.cwd() })
 
-const results = await search("Which decision changed the rollout?", { topK: 5 })
+const results = await search("Which decision changed the rollout?", {
+  topK: 5,
+  explain: true,
+})
 
 for (const result of results) {
   console.log(result.citation, result.text)
 }
 ```
 
-Core also exports `ask`, `research`, `audit`, `doctor`, `securityAudit`, `serveMcp`, and setup
-helpers. See the [API reference](./docs/api-reference.md) for the public surface.
+Core also exports `previewChunks`, `ask`, `research`, `audit`, `doctor`, `securityAudit`,
+`discoverKnowledgeBases`, bounded context helpers, `serveMcp`, and setup helpers. See the
+[API reference](./docs/api-reference.md) for the public surface.
 
 ## Privacy boundaries
 
diff --git a/context7.json b/context7.json
index 2a85ee7..815e6f0 100644
--- a/context7.json
+++ b/context7.json
@@ -23,6 +23,9 @@
     "The `local-hash` embedding provider (default) is a lexical sha256 embedding, not semantic; use `transformers` for semantic retrieval.",
     "Switching `embeddingProvider` requires `rgr ingest --rebuild`, since the two providers produce incompatible vectors.",
     "Run `rgr doctor --fix` after upgrading or misconfiguration to repair scaffolding, `.gitignore` entries, and the agent skill install.",
-    "Config resolves from the caller's working directory (`.ragmir/config.json`), never from the package install path."
+    "Config resolves from the caller's working directory (`.ragmir/config.json`), never from the package install path.",
+    "In a monorepo, the nearest configured ancestor is active; use `rgr bases --json` or explicit `--project-root` to verify routing.",
+    "Use `rgr preview` to inspect redacted chunks without writing an index, and `search(..., { explain: true })` only when rank diagnostics are needed.",
+    "MCP resources `ragmir://context` and `ragmir://sources` are bounded agent-orientation surfaces; retrieval still happens through the read-focused tools."
   ]
 }
diff --git a/docs/agent-integration.md b/docs/agent-integration.md
index 6f81d14..d756d1c 100644
--- a/docs/agent-integration.md
+++ b/docs/agent-integration.md
@@ -26,12 +26,39 @@ rgr install-agent --agents codex,claude
 
 Use `--scope user` only when you intentionally want a user-wide installation. Project scope is the default. `--mode copy` is a fallback for filesystems that cannot follow symlinks.
 
+## Monorepo bases
+
+A monorepo can run one root knowledge base plus isolated bases in individual apps. From the app or
+file currently in scope, run:
+
+```bash
+rgr bases --json
+```
+
+The nearest `.ragmir/config.json` is `activeId`. Use the root base for shared architecture and
+cross-app decisions; use the nearest app base for app-specific questions. Generated MCP helpers set
+`RAGMIR_PROJECT_ROOT` explicitly. Nested bases also receive deterministic names such as
+`ragmir-apps-web`, avoiding collisions with the root `ragmir` server. If an agent can see more than
+one Ragmir server, call `ragmir_status` and verify `knowledgeBaseId` before retrieval. Keep evidence
+from different bases labeled rather than silently merging citations.
+
 ## MCP tools
 
 The server exposes `ragmir_status`, `ragmir_route_prompt`, `ragmir_search`, `ragmir_ask`,
 `ragmir_research`, `ragmir_expand`, `ragmir_audit`, `ragmir_evaluate`, `ragmir_usage_report`, and
 `ragmir_security_audit`.
 
+It also exposes two bounded resources:
+
+| Resource | Use |
+| --- | --- |
+| `ragmir://context` | Active base identity, readiness, freshness, coverage, and available operations. |
+| `ragmir://sources` | Source coverage, skipped-file counts, and index drift, with per-file lists capped at 50. |
+
+Read `ragmir://context` first when the client supports resources. This gives an agent enough context
+to choose the next operation without chaining status, doctor, and audit calls. Totals in
+`ragmir://sources` stay complete even when detail lists are truncated.
+
 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, and expansion accept `maxBytes`;
 the server also enforces the configured `mcpMaxOutputBytes` ceiling. Their single JSON text result
@@ -45,6 +72,7 @@ requirements.
 ```bash
 rgr doctor
 rgr status --json
+rgr bases --json
 rgr search "known phrase" --compact
 ```
 
diff --git a/docs/api-reference.md b/docs/api-reference.md
index 1724b4f..3e45a14 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -17,6 +17,10 @@ All paths resolve from `cwd` or the current working directory. Retrieval results
 | `initProject(cwd?)` | Create local Ragmir state and ignore rules. |
 | `setupProject(options?)` | Initialize sources, helpers, and optional semantic retrieval. |
 | `loadConfig(start?)` | Resolve and validate effective configuration. |
+| `knowledgeBaseIdentity(start?)` | Identify the nearest base relative to the outer configured workspace. |
+| `discoverKnowledgeBases(start?)` | List root and nested bases and mark the active one. |
+| `getKnowledgeBaseContext(cwd?)` | Return bounded identity, readiness, freshness, and capability context. |
+| `getKnowledgeBaseSourceCatalog(cwd?)` | Return bounded source coverage with complete totals. |
 | `listSourceEntries(cwd?)` | Read configured source entries. |
 | `addSourceEntries(options)` | Add source paths or exclusions. |
 
@@ -26,6 +30,7 @@ All paths resolve from `cwd` or the current working directory. Retrieval results
 | --- | --- |
 | `ingest(options?)` | Incrementally parse, redact, chunk, embed, and store files. |
 | `audit(cwd?)` | Compare files on disk with the current index. |
+| `previewChunks(options?)` | Return redacted structured chunks without writing an index. |
 | `search(query, options?)` | Return ranked cited passages. |
 | `ask(query, options?)` | Return cited retrieval context without calling an LLM. |
 | `research(query, options?)` | Run audit-backed multi-query retrieval. |
@@ -34,12 +39,19 @@ All paths resolve from `cwd` or the current working directory. Retrieval results
 | `compactResearchReport(report)` | Remove verbose evidence text from a research report. |
 | `evaluateGoldenQueries(options)` | Score retrieval against a local golden-query file. |
 
-`SearchOptions` accepts `cwd`, `topK`, `contextRadius`, `includePaths`, and `excludePaths`.
+`SearchOptions` accepts `cwd`, `topK`, `contextRadius`, `includePaths`, `excludePaths`,
+`contextPaths`, and `explain`. When explanation is enabled, each result includes RRF contributions,
+one-based vector and lexical ranks, vector distance, lexical backend score, and matched query terms.
 `ExpandCitationOptions` accepts `cwd` and a `contextRadius` clamped to three chunks.
 Search results expose a `contextPath` derived from Markdown headings or JSON structure. This field
 improves retrieval, while `text`, offsets, and citations continue to reference the exact source
 passage.
 
+`PreviewReport` includes per-file redaction counts, citations, offsets, structural context, omitted
+counts, and chunk distributions. `AuditReport.chunkStats` provides corpus-wide character
+distributions and structural-context coverage. Golden-query cases may include `contextPaths` to
+evaluate one heading or structured-data branch.
+
 ## Operations and privacy
 
 | Export | Use |
@@ -76,6 +88,10 @@ passage.
 `kbCommand` and `ragmirCommand` remain compatibility helpers. New integration code should use
 `rgrCommand` and the `rgr` CLI name.
 
+In a monorepo, all public operations still resolve the nearest configured ancestor from `cwd`.
+`KnowledgeBaseInventory` exposes deterministic relative IDs, while each base keeps its own source,
+storage, manifest, and access-log paths.
+
 The MCP retrieval tools accept an optional `maxBytes` below the configured `mcpMaxOutputBytes`
 ceiling. `ragmir_search` and `ragmir_research` also accept `compact`; `ragmir_ask` supports the same
 flag. Oversized full output is compacted and then reduced as valid JSON. Output metrics are available
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 66b7c1e..1646f31 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -16,11 +16,13 @@ rgr search "release decision"
 | `setup [--semantic]` | Initialize `.ragmir/`, agent helpers, and optionally preload embeddings. |
 | `init` | Create basic local configuration only. |
 | `doctor [--fix]` | Check setup, index freshness, and safe repairs. |
+| `preview` | Parse, redact, and chunk selected sources without writing the index. |
 | `ingest [--rebuild]` | Index configured sources; rebuild after provider or chunking changes. |
 | `search <query>` | Return ranked cited passages. |
 | `ask <query>` | Return cited context without model synthesis. |
 | `research <query>` | Run an audit-backed multi-query retrieval pass. |
 | `audit [--unsupported]` | Compare sources with the index and list skipped files. |
+| `bases` | List root and nested monorepo bases and mark the active one. |
 | `status` | Show configuration and indexed chunk count. |
 | `security-audit [--strict]` | Check local privacy and Git-ignore posture. |
 
@@ -29,13 +31,33 @@ rgr search "release decision"
 ```bash
 rgr sources add "docs/**/*.md" "!docs/archive/**"
 rgr sources list
+rgr preview --path docs --max-files 5 --max-chunks 3
 rgr search "migration" --top-k 5 --context-radius 1
 rgr search "migration" --include-path docs --exclude-path docs/archive
+rgr search "migration" --context-path "Guide > Migration" --explain
 ```
 
 `sources add` accepts paths, globs, and `!` exclusions. Search, ask, and research accept `--top-k`,
-`--include-path`, and `--exclude-path`. Use `--compact` on search or research when agent context is
-limited.
+`--include-path`, `--exclude-path`, and repeatable `--context-path`. Search and ask accept
+`--explain`; the optional score object reports RRF contributions, retriever ranks, raw backend
+scores, and matched query terms without changing ranking. Use `--compact` on search or research when
+agent context is limited.
+
+`preview` uses the active redaction and chunking configuration but never writes storage. `audit`
+reports min, mean, p50, p95, and max chunk sizes plus structural-context coverage.
+
+## Monorepos
+
+```bash
+cd apps/web/src
+rgr bases --json
+rgr search "app-specific contract"
+rgr --project-root /absolute/path/to/monorepo search "shared architecture"
+```
+
+Commands resolve the nearest configured ancestor. Use the root base for shared or cross-app
+knowledge and an app base for app-specific evidence. `--project-root` overrides the working
+directory deterministically. Root and nested bases use separate storage and never share index rows.
 
 ## Optional local features
 
diff --git a/llms.txt b/llms.txt
index f4c40d1..040abcf 100644
--- a/llms.txt
+++ b/llms.txt
@@ -9,7 +9,8 @@ store.
 
 - Install: `pnpm add -D @jcode.labs/ragmir`
 - First use: `pnpm exec rgr setup && pnpm exec rgr ingest`
-- CLI: `rgr search "query"`, `rgr doctor`, `rgr audit`, and `rgr security-audit`
+- CLI: `rgr preview`, `rgr search "query" --explain`, `rgr bases`, `rgr doctor`, `rgr audit`, and
+  `rgr security-audit`
 - Core behavior: cited retrieval only. `ask` returns evidence, while synthesis belongs to the calling
   agent or optional local chat add-on.
 - Default retrieval: local-hash, with no model download. Semantic embeddings and local GGUF chat are
@@ -20,6 +21,12 @@ store.
   when the user chooses that workflow, under that provider's data policy.
 - OCR boundary: embedded PDF text comes first; a configured local executable runs only for blank
   pages. Ragmir has no cloud OCR integration.
+- Retrieval inspection: preview redacted chunks without writing storage; optionally expose RRF
+  contributions and filter by source or structural context.
+- Monorepos: the nearest configured base is active, nested indexes remain isolated, and generated MCP
+  helpers pin a distinct base root.
+- MCP resources: `ragmir://context` gives bounded readiness and capability context;
+  `ragmir://sources` gives capped source detail with complete totals.
 
 ## Documentation
 
diff --git a/packages/ragmir-core/README.md b/packages/ragmir-core/README.md
index d95ce24..79e12f7 100644
--- a/packages/ragmir-core/README.md
+++ b/packages/ragmir-core/README.md
@@ -55,7 +55,10 @@ npx rgr audit --unsupported
 npx rgr security-audit
 
 # Retrieval
+npx rgr preview --path docs --max-chunks 3
 npx rgr search "deployment decision"
+npx rgr search "deployment decision" --explain
+npx rgr search "deployment decision" --context-path "Operations > Deployment"
 npx rgr ask "What evidence supports the deployment decision?"
 npx rgr research "deployment obligations" --compact
 
@@ -88,7 +91,10 @@ Frequently used exports:
 | Export | Purpose |
 | --- | --- |
 | `setupProject`, `addSourceEntries` | Initialize project state and select files |
+| `discoverKnowledgeBases`, `knowledgeBaseIdentity` | Route root and nested monorepo bases |
+| `getKnowledgeBaseContext`, `getKnowledgeBaseSourceCatalog` | Give agents bounded readiness and source context |
 | `ingest`, `audit` | Build the index and compare it with files on disk |
+| `previewChunks` | Inspect redacted chunks and distributions without writing storage |
 | `search`, `ask`, `research`, `expandCitation` | Retrieve or expand cited passages |
 | `doctor`, `securityAudit` | Inspect readiness and local privacy posture |
 | `serveMcp` | Start the read-focused local MCP server |
@@ -109,6 +115,10 @@ exposes status, search, ask, research, exact citation expansion, audit, evaluati
 security tools. Retrieval responses have a global byte ceiling and expose metadata-only output
 metrics. The server does not expose index deletion.
 
+For a monorepo with root and app-specific bases, run `rgr bases --json` before retrieval when scope
+is unclear. The nearest configured base is active, nested MCP helpers get unique names, and every
+helper pins `RAGMIR_PROJECT_ROOT` so clients cannot drift to a sibling index.
+
 ## Retrieval modes
 
 | Mode | Network requirement | Best for |
diff --git a/packages/ragmir-core/scripts/mcp-smoke.mjs b/packages/ragmir-core/scripts/mcp-smoke.mjs
index 128fffb..e95502e 100644
--- a/packages/ragmir-core/scripts/mcp-smoke.mjs
+++ b/packages/ragmir-core/scripts/mcp-smoke.mjs
@@ -23,6 +23,7 @@ const requiredTools = [
   "ragmir_usage_report",
   "ragmir_security_audit",
 ]
+const requiredResources = ["ragmir://context", "ragmir://sources"]
 
 const client = new Client({ name: "ragmir-mcp-smoke", version: "0.0.0" })
 const transport = new StdioClientTransport({
@@ -58,10 +59,47 @@ try {
     }
   }
 
+  const resourcesResult = await client.listResources(undefined, { timeout: 5_000 })
+  const resourceUris = resourcesResult.resources.map((resource) => resource.uri)
+  for (const resourceUri of requiredResources) {
+    if (!resourceUris.includes(resourceUri)) {
+      throw new Error(`Missing MCP resource: ${resourceUri}`)
+    }
+  }
+  const contextResource = parseJsonResource(
+    await client.readResource({ uri: "ragmir://context" }, { timeout: 10_000 }),
+    "ragmir://context",
+  )
+  if (
+    contextResource.knowledgeBaseId !== "." ||
+    contextResource.indexFreshness?.manifestFound !== true ||
+    !contextResource.tools?.includes("ragmir_search")
+  ) {
+    throw new Error(
+      `MCP context resource returned unexpected data: ${JSON.stringify(contextResource)}`,
+    )
+  }
+  const sourcesResource = parseJsonResource(
+    await client.readResource({ uri: "ragmir://sources" }, { timeout: 10_000 }),
+    "ragmir://sources",
+  )
+  if (
+    sourcesResource.totals?.indexedFiles < 1 ||
+    !Array.isArray(sourcesResource.indexedFiles) ||
+    sourcesResource.indexedFiles.length < 1
+  ) {
+    throw new Error(
+      `MCP source resource returned unexpected data: ${JSON.stringify(sourcesResource)}`,
+    )
+  }
+
   const status = await callJsonTool(client, "ragmir_status", {})
   if (status.chunksIndexed < 1) {
     throw new Error("MCP status reported an empty index.")
   }
+  if (status.knowledgeBaseId !== ".") {
+    throw new Error(`MCP status reported an ambiguous knowledge base: ${JSON.stringify(status)}`)
+  }
   if (status.mcpMaxOutputBytes !== 32_768) {
     throw new Error(`MCP status reported an unexpected output budget: ${JSON.stringify(status)}`)
   }
@@ -139,6 +177,7 @@ try {
     query: "offline retrieval approval",
     topK: 5,
     includePaths: ["raw/review-notes.evidence"],
+    explain: true,
   })
   if (
     !Array.isArray(filteredSearchResults) ||
@@ -149,6 +188,31 @@ try {
       `MCP search path filter returned unexpected results: ${JSON.stringify(filteredSearchResults)}`,
     )
   }
+  if (
+    filteredSearchResults.some(
+      (result) => result.score?.fusion !== "rrf" || typeof result.score?.combinedScore !== "number",
+    )
+  ) {
+    throw new Error(
+      `MCP search explanation returned unexpected results: ${JSON.stringify(filteredSearchResults)}`,
+    )
+  }
+
+  const contextFilteredResults = await callJsonTool(client, "ragmir_search", {
+    query: "remote model loading disabled",
+    topK: 5,
+    includePaths: ["raw/incident-timeline.jsonl"],
+    contextPaths: ["$[1..4]"],
+  })
+  if (
+    !Array.isArray(contextFilteredResults) ||
+    contextFilteredResults.length < 1 ||
+    !contextFilteredResults.every((result) => result.contextPath === "$[1..4]")
+  ) {
+    throw new Error(
+      `MCP structural context filter returned unexpected results: ${JSON.stringify(contextFilteredResults)}`,
+    )
+  }
 
   const answer = await callJsonTool(client, "ragmir_ask", {
     query: "What evidence supports offline operation?",
@@ -202,6 +266,7 @@ try {
         ok: true,
         projectRoot: demoRoot,
         tools: requiredTools,
+        resources: resourceUris,
         chunksIndexed: status.chunksIndexed,
         searchResults: searchResults.length,
         expandedPassages: expanded.passages.length,
@@ -250,3 +315,15 @@ function parseJsonToolResult(result, name) {
 
   return JSON.parse(textItem.text)
 }
+
+function parseJsonResource(result, resourceUri) {
+  const content = result.contents[0]
+  if (!content || !("text" in content)) {
+    throw new Error(`${resourceUri} returned no text content.`)
+  }
+  try {
+    return JSON.parse(content.text)
+  } catch (error) {
+    throw new Error(`${resourceUri} returned invalid JSON: ${String(error)}`)
+  }
+}
diff --git a/packages/ragmir-core/skills/ragmir/SKILL.md b/packages/ragmir-core/skills/ragmir/SKILL.md
index 02282ba..7ec00d8 100644
--- a/packages/ragmir-core/skills/ragmir/SKILL.md
+++ b/packages/ragmir-core/skills/ragmir/SKILL.md
@@ -43,11 +43,15 @@ acceptable. Normal confidential indexing keeps remote model loading disabled.
 
 | Need | Command or MCP tool |
 | --- | --- |
+| Active base, readiness, and capabilities | Read `ragmir://context` or run `rgr status --json` |
+| Bounded source coverage and index drift | Read `ragmir://sources` or run `rgr audit` |
 | Readiness | `rgr doctor` or `ragmir_status` |
 | Repair setup or stale data | `rgr doctor --fix` |
 | Check unindexed or unsupported files | `rgr audit --unsupported` |
+| Preview redacted chunks before indexing | `rgr preview --path <prefix> --json` |
 | Check privacy posture | `rgr security-audit` |
 | Retrieve exact passages | `rgr search "query" --compact` or `ragmir_search` |
+| Explain hybrid ranking | `rgr search "query" --explain` or `ragmir_search` with `explain: true` |
 | Expand one returned citation | `ragmir_expand` |
 | Gather broad cited evidence | `rgr research "topic" --compact` or `ragmir_research` |
 | Return deterministic context | `rgr ask "question"` or `ragmir_ask` |
@@ -57,6 +61,21 @@ Use `rgr route-prompt "..." --json` or `ragmir_route_prompt` only when it is unc
 current request needs the local corpus. The router is deterministic and does not retrieve or store
 the prompt.
 
+## Monorepo routing
+
+When a monorepo has a root Ragmir base and nested app bases, select the base before retrieval:
+
+1. Run `rgr bases --json` from the directory in scope. The nearest configured ancestor is
+   `activeId`.
+2. Use the root base for shared architecture or cross-app questions. Use the nested base for an
+   app-specific question.
+3. If the shell working directory is not inside the intended base, pass
+   `--project-root /absolute/path/to/base` before the command.
+4. For MCP, call `ragmir_status` when the active base is uncertain and verify `knowledgeBaseId`.
+   Generated helpers pin `RAGMIR_PROJECT_ROOT`; nested bases receive distinct server names.
+5. Never silently combine citations from different bases. Label each base when a task genuinely
+   requires evidence from more than one.
+
 ## Indexing
 
 Use `.ragmir/config.json` for sources, with paths, globs, and `!` exclusions:
@@ -80,6 +99,11 @@ OCR stays opt-in and never calls a remote service by default.
 `local-hash` is the default retrieval provider. It supports cited local retrieval but is not
 semantic embeddings. Use the Transformers provider only after an explicit model preload.
 
+Before a costly ingest or after changing chunk settings, run `rgr preview --json`. Review redaction
+counts, citations, `contextPath`, omitted chunks, and p50/p95 sizes. Search, ask, research, MCP
+retrieval, and golden queries can restrict retrieval with source paths and structural context paths.
+Use explanations to inspect RRF ranks and contributions, not as an independent relevance score.
+
 ## MCP
 
 `rgr setup` writes local MCP helpers under `.ragmir/` for Claude Code, Codex, Kimi, OpenCode, and
@@ -105,6 +129,10 @@ only when the exact chunk or neighboring context is needed. Retrieval tools acce
 the configured `mcpMaxOutputBytes` remains the hard ceiling. Inspect `_meta["ragmir/output"]` to see
 whether the response was compacted or truncated.
 
+When MCP resources are supported, read `ragmir://context` first for a bounded identity, readiness,
+freshness, coverage, and capability overview. Read `ragmir://sources` only when source coverage or
+index drift matters; its per-file lists are capped while totals remain complete.
+
 MCP is read-focused. Only remove an index with the explicit shell command:
 
 ```sh
diff --git a/packages/ragmir-core/src/chunk-stats.test.ts b/packages/ragmir-core/src/chunk-stats.test.ts
new file mode 100644
index 0000000..45b8a8e
--- /dev/null
+++ b/packages/ragmir-core/src/chunk-stats.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from "vitest"
+import { summarizeChunkStats } from "./chunk-stats.js"
+
+describe("summarizeChunkStats", () => {
+  it("should return zeroed metadata when no chunks exist", () => {
+    expect(summarizeChunkStats([])).toEqual({
+      count: 0,
+      minChars: 0,
+      averageChars: 0,
+      p50Chars: 0,
+      p95Chars: 0,
+      maxChars: 0,
+      contextualChunks: 0,
+      contextualRatio: 0,
+    })
+  })
+
+  it("should summarize chunk lengths and structural-context coverage", () => {
+    const result = summarizeChunkStats([
+      { text: "a".repeat(10), contextPath: "" },
+      { text: "b".repeat(20), contextPath: "Guide" },
+      { text: "c".repeat(40), contextPath: "Guide > MCP" },
+    ])
+
+    expect(result).toEqual({
+      count: 3,
+      minChars: 10,
+      averageChars: 70 / 3,
+      p50Chars: 20,
+      p95Chars: 40,
+      maxChars: 40,
+      contextualChunks: 2,
+      contextualRatio: 2 / 3,
+    })
+  })
+})
diff --git a/packages/ragmir-core/src/chunk-stats.ts b/packages/ragmir-core/src/chunk-stats.ts
new file mode 100644
index 0000000..ea4b6bf
--- /dev/null
+++ b/packages/ragmir-core/src/chunk-stats.ts
@@ -0,0 +1,40 @@
+import type { ChunkStats } from "./types.js"
+
+interface ChunkShape {
+  contextPath: string
+  text: string
+}
+
+export function summarizeChunkStats(chunks: readonly ChunkShape[]): ChunkStats {
+  if (chunks.length === 0) {
+    return {
+      count: 0,
+      minChars: 0,
+      averageChars: 0,
+      p50Chars: 0,
+      p95Chars: 0,
+      maxChars: 0,
+      contextualChunks: 0,
+      contextualRatio: 0,
+    }
+  }
+
+  const lengths = chunks.map((chunk) => chunk.text.length).sort((left, right) => left - right)
+  const contextualChunks = chunks.filter((chunk) => chunk.contextPath.trim().length > 0).length
+
+  return {
+    count: chunks.length,
+    minChars: lengths[0] ?? 0,
+    averageChars: lengths.reduce((sum, length) => sum + length, 0) / lengths.length,
+    p50Chars: percentile(lengths, 0.5),
+    p95Chars: percentile(lengths, 0.95),
+    maxChars: lengths.at(-1) ?? 0,
+    contextualChunks,
+    contextualRatio: contextualChunks / chunks.length,
+  }
+}
+
+function percentile(sortedValues: number[], quantile: number): number {
+  const index = Math.ceil(quantile * sortedValues.length) - 1
+  return sortedValues[Math.max(0, index)] ?? 0
+}
diff --git a/packages/ragmir-core/src/cli.ts b/packages/ragmir-core/src/cli.ts
index 0ea2add..32db6fa 100644
--- a/packages/ragmir-core/src/cli.ts
+++ b/packages/ragmir-core/src/cli.ts
@@ -26,10 +26,12 @@ import { countSkippedByReason } from "./files.js"
 import { getIndexFreshnessWarning, getLexicalScanWarning } from "./index-diagnostics.js"
 import { audit, ingest } from "./ingest.js"
 import { initProject } from "./init.js"
+import { discoverKnowledgeBases, knowledgeBaseIdentity } from "./knowledge-bases.js"
 import { ingestionLimits } from "./limits.js"
 import { serveMcp } from "./mcp.js"
 import { configurePdfOcr, extractPdfPage, inspectPdfOcr, parsePdfOcrEngine } from "./ocr.js"
 import { rgrCommand } from "./package-manager.js"
+import { previewChunks } from "./preview.js"
 import { routePrompt } from "./prompt-routing.js"
 import { ask, search } from "./query.js"
 import { compactResearchReport, compactSearchResults, research } from "./research.js"
@@ -45,7 +47,7 @@ import {
 } from "./skill.js"
 import { addSourceEntries, listSourceEntries } from "./sources.js"
 import { countRows } from "./store.js"
-import type { ResearchReport } from "./types.js"
+import type { PreviewChunksOptions, ResearchReport } from "./types.js"
 import { VERSION } from "./version.js"
 
 const SEARCH_TEXT_PREVIEW_LENGTH = 900
@@ -234,7 +236,10 @@ program
     `Agent MCP helpers to generate: all, ${SUPPORTED_AGENT_TARGETS.join(", ")}.`,
     "all",
   )
-  .option("--mcp-name <name>", "MCP server name used in generated config.", "ragmir")
+  .option(
+    "--mcp-name <name>",
+    "MCP server name. Nested monorepo bases get a unique name by default.",
+  )
   .option("--mcp-command <command>", "Custom MCP stdio command for generated helper files.")
   .option(
     "--mcp-arg <arg>",
@@ -253,7 +258,7 @@ program
       options: {
         targetDir: string
         agents: string
-        mcpName: string
+        mcpName?: string
         mcpCommand?: string
         mcpArg: string[]
         semantic?: boolean
@@ -267,8 +272,8 @@ program
         cwd,
         targetDir: options.targetDir,
         agents: parseAgentTargets(options.agents),
-        mcpServerName: options.mcpName,
       }
+      addOption(setupOptions, "mcpServerName", options.mcpName)
       addOption(setupOptions, "semantic", options.semantic)
       addOption(setupOptions, "ingest", options.ingest)
       addOption(setupOptions, "mcpCommand", options.mcpCommand)
@@ -405,6 +410,74 @@ program
     }
   })
 
+program
+  .command("preview")
+  .description("Preview redacted chunks and structure without writing the index.")
+  .option(
+    "--path <prefix>",
+    "Preview only source paths under this prefix. Repeat for multiple prefixes.",
+    collectOptionValue,
+    [],
+  )
+  .option("--max-files <number>", "Maximum number of matching files to parse.", parsePositiveInt)
+  .option("--max-chunks <number>", "Maximum number of chunks to show per file.", parsePositiveInt)
+  .option("--json", "Print machine-readable JSON.")
+  .action(
+    async (
+      options: { path: string[]; maxFiles?: number; maxChunks?: number; json?: boolean },
+      command: Command,
+    ) => {
+      const cwd = projectRoot(command)
+      const previewOptions: PreviewChunksOptions = { cwd }
+      if (options.path.length > 0) {
+        previewOptions.paths = options.path
+      }
+      addOption(previewOptions, "maxFiles", options.maxFiles)
+      addOption(previewOptions, "maxChunksPerFile", options.maxChunks)
+      const report = await previewChunks(previewOptions)
+      if (options.json) {
+        console.log(JSON.stringify(report, null, 2))
+        if (
+          report.errors.length > 0 ||
+          (report.requestedPaths.length > 0 && report.matchedFiles === 0)
+        ) {
+          process.exitCode = 1
+        }
+        return
+      }
+
+      console.log(`chunkSize=${report.chunkSize}`)
+      console.log(`chunkOverlap=${report.chunkOverlap}`)
+      console.log(`matchedFiles=${report.matchedFiles}`)
+      console.log(`omittedFiles=${report.omittedFiles}`)
+      for (const unmatchedPath of report.unmatchedPaths) {
+        console.log(pc.yellow(`unmatched: ${unmatchedPath}`))
+      }
+      for (const file of report.files) {
+        console.log(
+          `\n${pc.cyan(file.relativePath)} chunks=${file.chunkStats.count} redactions=${file.redactions} minChars=${file.chunkStats.minChars} p50Chars=${file.chunkStats.p50Chars} p95Chars=${file.chunkStats.p95Chars} maxChars=${file.chunkStats.maxChars} contextualRatio=${file.chunkStats.contextualRatio.toFixed(3)}`,
+        )
+        for (const chunk of file.chunks) {
+          const context = chunk.contextPath ? ` context=${chunk.contextPath}` : ""
+          console.log(`\n${pc.dim(chunk.citation)}${context}`)
+          console.log(chunk.text.slice(0, SEARCH_TEXT_PREVIEW_LENGTH))
+        }
+        if (file.omittedChunks > 0) {
+          console.log(pc.dim(`omittedChunks=${file.omittedChunks}`))
+        }
+      }
+      for (const error of report.errors) {
+        console.error(pc.red(`${error.path}: ${error.message}`))
+      }
+      if (
+        report.errors.length > 0 ||
+        (report.requestedPaths.length > 0 && report.matchedFiles === 0)
+      ) {
+        process.exitCode = 1
+      }
+    },
+  )
+
 program
   .command("search")
   .description("Retrieve the most relevant passages without calling an LLM.")
@@ -427,6 +500,13 @@ program
     collectOptionValue,
     [],
   )
+  .option(
+    "--context-path <prefix>",
+    "Search only chunks under this structural context. Repeat for multiple prefixes.",
+    collectOptionValue,
+    [],
+  )
+  .option("--explain", "Include hybrid score contributions, ranks, and matched terms.")
   .option("--compact", "Return short snippets instead of full passages.")
   .option("--json", "Print machine-readable JSON.")
   .action(
@@ -437,6 +517,8 @@ program
         contextRadius?: number
         includePath: string[]
         excludePath: string[]
+        contextPath: string[]
+        explain?: boolean
         compact?: boolean
         json?: boolean
       },
@@ -470,6 +552,15 @@ program
         console.log(
           "snippet" in result ? result.snippet : result.text.slice(0, SEARCH_TEXT_PREVIEW_LENGTH),
         )
+        if (result.score) {
+          const vectorRank = result.score.vectorRank ?? "n/a"
+          const lexicalRank = result.score.lexicalRank ?? "n/a"
+          console.log(
+            pc.dim(
+              `score=${result.score.combinedScore.toFixed(6)} fusion=${result.score.fusion} vector=${result.score.vectorContribution.toFixed(6)} lexical=${result.score.lexicalContribution.toFixed(6)} vectorRank=${vectorRank} lexicalRank=${lexicalRank} matchedTerms=${result.score.matchedTerms.join(",") || "n/a"}`,
+            ),
+          )
+        }
       }
     },
   )
@@ -496,6 +587,13 @@ program
     collectOptionValue,
     [],
   )
+  .option(
+    "--context-path <prefix>",
+    "Use only chunks under this structural context. Repeat for multiple prefixes.",
+    collectOptionValue,
+    [],
+  )
+  .option("--explain", "Include hybrid score contributions, ranks, and matched terms.")
   .option("--json", "Print machine-readable JSON.")
   .action(
     async (
@@ -505,6 +603,8 @@ program
         contextRadius?: number
         includePath: string[]
         excludePath: string[]
+        contextPath: string[]
+        explain?: boolean
         json?: boolean
       },
       command: Command,
@@ -526,7 +626,8 @@ program
       if (result.sources.length > 0) {
         console.log(pc.dim("Sources:"))
         for (const [index, source] of result.sources.entries()) {
-          console.log(`  [${index + 1}] ${source.citation} chunk=${source.chunkIndex}`)
+          const score = source.score ? ` score=${source.score.combinedScore.toFixed(6)}` : ""
+          console.log(`  [${index + 1}] ${source.citation} chunk=${source.chunkIndex}${score}`)
         }
       }
     },
@@ -550,6 +651,12 @@ program
     collectOptionValue,
     [],
   )
+  .option(
+    "--context-path <prefix>",
+    "Use only chunks under this structural context. Repeat for multiple prefixes.",
+    collectOptionValue,
+    [],
+  )
   .option("--compact", "Return snippets instead of full retrieved passages.")
   .option("--json", "Print machine-readable JSON.")
   .action(
@@ -560,6 +667,7 @@ program
         code?: boolean
         includePath: string[]
         excludePath: string[]
+        contextPath: string[]
         compact?: boolean
         json?: boolean
       },
@@ -716,6 +824,13 @@ program
     console.log(`sensitiveFiles=${countSkippedByReason(report.skippedFiles, "sensitive-name")}`)
     console.log(`indexedFiles=${report.indexedFiles.length}`)
     console.log(`totalChunks=${report.totalChunks}`)
+    console.log(`chunkStats.minChars=${report.chunkStats.minChars}`)
+    console.log(`chunkStats.averageChars=${report.chunkStats.averageChars.toFixed(1)}`)
+    console.log(`chunkStats.p50Chars=${report.chunkStats.p50Chars}`)
+    console.log(`chunkStats.p95Chars=${report.chunkStats.p95Chars}`)
+    console.log(`chunkStats.maxChars=${report.chunkStats.maxChars}`)
+    console.log(`chunkStats.contextualChunks=${report.chunkStats.contextualChunks}`)
+    console.log(`chunkStats.contextualRatio=${report.chunkStats.contextualRatio.toFixed(3)}`)
     console.log(`emptyTextFiles=${report.emptyTextFiles.length}`)
     console.log(`missingFromIndex=${report.missingFromIndex.length}`)
     console.log(`staleInIndex=${report.staleInIndex.length}`)
@@ -817,6 +932,27 @@ program
     }
   })
 
+program
+  .command("bases")
+  .description("List Ragmir knowledge bases in the active monorepo and mark the selected base.")
+  .option("--json", "Print machine-readable JSON.")
+  .action(async (options: { json?: boolean }, command: Command) => {
+    const inventory = await discoverKnowledgeBases(projectRoot(command))
+    if (options.json) {
+      console.log(JSON.stringify(inventory, null, 2))
+      return
+    }
+
+    console.log(`workspaceRoot=${inventory.workspaceRoot}`)
+    console.log(`activeBase=${inventory.activeId ?? "none"}`)
+    console.log(`bases=${inventory.bases.length}`)
+    for (const base of inventory.bases) {
+      const marker = base.active ? "*" : "-"
+      const format = base.legacy ? "legacy" : "ragmir"
+      console.log(`${marker} ${base.id} format=${format} root=${base.projectRoot}`)
+    }
+  })
+
 program
   .command("status")
   .description("Show active configuration and index row count.")
@@ -824,8 +960,10 @@ program
   .action(async (options: { json?: boolean }, command: Command) => {
     const cwd = projectRoot(command)
     const config = await loadConfig(cwd)
+    const identity = knowledgeBaseIdentity(config.projectRoot)
     const rows = await countRows(config)
     const status = {
+      knowledgeBaseId: identity?.id ?? null,
       projectRoot: config.projectRoot,
       rawDir: config.rawDir,
       storageDir: config.storageDir,
@@ -859,6 +997,7 @@ program
       return
     }
 
+    console.log(`knowledgeBaseId=${identity?.id ?? "none"}`)
     console.log(`projectRoot=${config.projectRoot}`)
     console.log(`rawDir=${config.rawDir}`)
     console.log(`storageDir=${config.storageDir}`)
@@ -1121,7 +1260,10 @@ program
     `Agent MCP helpers to generate: all, ${SUPPORTED_AGENT_TARGETS.join(", ")}.`,
     "all",
   )
-  .option("--mcp-name <name>", "MCP server name used in generated config.", "ragmir")
+  .option(
+    "--mcp-name <name>",
+    "MCP server name. Nested monorepo bases get a unique name by default.",
+  )
   .option("--mcp-command <command>", "Custom MCP stdio command for generated helper files.")
   .option(
     "--mcp-arg <arg>",
@@ -1134,7 +1276,7 @@ program
       options: {
         targetDir: string
         agents: string
-        mcpName: string
+        mcpName?: string
         mcpCommand?: string
         mcpArg: string[]
       },
@@ -1145,8 +1287,8 @@ program
         cwd,
         targetDir: options.targetDir,
         agents: parseAgentTargets(options.agents),
-        mcpServerName: options.mcpName,
       }
+      addOption(installOptions, "mcpServerName", options.mcpName)
       addOption(installOptions, "mcpCommand", options.mcpCommand)
       if (options.mcpArg.length > 0) {
         installOptions.mcpArgs = options.mcpArg
@@ -1283,6 +1425,8 @@ function withSearchOptions(
     contextRadius?: number
     includePath?: string[]
     excludePath?: string[]
+    contextPath?: string[]
+    explain?: boolean
   },
 ): {
   cwd: string
@@ -1290,6 +1434,8 @@ function withSearchOptions(
   contextRadius?: number
   includePaths?: string[]
   excludePaths?: string[]
+  contextPaths?: string[]
+  explain?: boolean
 } {
   const result: {
     cwd: string
@@ -1297,16 +1443,19 @@ function withSearchOptions(
     contextRadius?: number
     includePaths?: string[]
     excludePaths?: string[]
+    contextPaths?: string[]
+    explain?: boolean
   } = { cwd }
   addOption(result, "topK", options.topK)
   addOption(result, "contextRadius", options.contextRadius)
   addPathFilters(result, options)
+  addOption(result, "explain", options.explain)
   return result
 }
 
 function addPathFilters(
-  target: { includePaths?: string[]; excludePaths?: string[] },
-  options: { includePath?: string[]; excludePath?: string[] },
+  target: { includePaths?: string[]; excludePaths?: string[]; contextPaths?: string[] },
+  options: { includePath?: string[]; excludePath?: string[]; contextPath?: string[] },
 ): void {
   if (options.includePath && options.includePath.length > 0) {
     target.includePaths = options.includePath
@@ -1314,6 +1463,9 @@ function addPathFilters(
   if (options.excludePath && options.excludePath.length > 0) {
     target.excludePaths = options.excludePath
   }
+  if (options.contextPath && options.contextPath.length > 0) {
+    target.contextPaths = options.contextPath
+  }
 }
 
 interface AudioOptions {
diff --git a/packages/ragmir-core/src/config.test.ts b/packages/ragmir-core/src/config.test.ts
index 324a1fe..ebc3ad0 100644
--- a/packages/ragmir-core/src/config.test.ts
+++ b/packages/ragmir-core/src/config.test.ts
@@ -54,6 +54,26 @@ describe("loadConfig", () => {
     expect(config.legacyWordTimeoutMs).toBe(120_000)
   })
 
+  it("should select the nearest Ragmir config inside a monorepo", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-config-monorepo-"))
+    tempDirs.push(root)
+    const app = path.join(root, "apps", "web")
+    const appSource = path.join(app, "src", "features")
+    await mkdir(path.join(root, ".ragmir"), { recursive: true })
+    await mkdir(path.join(app, ".ragmir"), { recursive: true })
+    await mkdir(appSource, { recursive: true })
+    await writeFile(path.join(root, ".ragmir", "config.json"), "{}\n", "utf8")
+    await writeFile(
+      path.join(app, ".ragmir", "config.json"),
+      JSON.stringify({ rawDir: ".ragmir/app-raw" }),
+      "utf8",
+    )
+
+    expect(findProjectRoot(root)).toBe(root)
+    expect(findProjectRoot(appSource)).toBe(app)
+    expect((await loadConfig(appSource)).rawDir).toBe(path.join(app, ".ragmir", "app-raw"))
+  })
+
   it("keeps inline source paths and globs from config", async () => {
     const root = await mkdtemp(path.join(os.tmpdir(), "jcode-kb-"))
     tempDirs.push(root)
diff --git a/packages/ragmir-core/src/context-resources.test.ts b/packages/ragmir-core/src/context-resources.test.ts
new file mode 100644
index 0000000..b67678f
--- /dev/null
+++ b/packages/ragmir-core/src/context-resources.test.ts
@@ -0,0 +1,64 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { getKnowledgeBaseContext, getKnowledgeBaseSourceCatalog } from "./context-resources.js"
+import { ingest } from "./ingest.js"
+import { initProject } from "./init.js"
+
+const tempDirs: string[] = []
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true })
+  }
+})
+
+describe("context resources", () => {
+  it("should return a bounded agent context with readiness and routing", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-context-resource-"))
+    tempDirs.push(root)
+    await initProject(root)
+    await writeFile(
+      path.join(root, ".ragmir", "raw", "policy.md"),
+      "Verified local retrieval policy.\n",
+      "utf8",
+    )
+    await ingest({ cwd: root })
+
+    const context = await getKnowledgeBaseContext(root)
+
+    expect(context.knowledgeBaseId).toBe(".")
+    expect(context.ready).toBe(true)
+    expect(context.coverage.indexedFiles).toBe(1)
+    expect(context.coverage.chunksIndexed).toBeGreaterThan(0)
+    expect(context.routing.discoverCommand).toBe("rgr bases --json")
+    expect(context.tools).toContain("ragmir_search")
+    expect(context.resources).toEqual(["ragmir://context", "ragmir://sources"])
+  })
+
+  it("should cap source details while preserving complete totals", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-source-resource-"))
+    tempDirs.push(root)
+    await initProject(root)
+    const rawDir = path.join(root, ".ragmir", "raw")
+    await mkdir(rawDir, { recursive: true })
+    await Promise.all(
+      Array.from({ length: 55 }, (_value, index) =>
+        writeFile(
+          path.join(rawDir, `source-${index.toString().padStart(2, "0")}.md`),
+          `Indexed source evidence ${index}.\n`,
+          "utf8",
+        ),
+      ),
+    )
+    await ingest({ cwd: root })
+
+    const catalog = await getKnowledgeBaseSourceCatalog(root)
+
+    expect(catalog.totals.indexedFiles).toBe(55)
+    expect(catalog.indexedFiles).toHaveLength(50)
+    expect(catalog.omitted.indexedFiles).toBe(5)
+    expect(catalog.totals.chunks).toBeGreaterThanOrEqual(55)
+  })
+})
diff --git a/packages/ragmir-core/src/context-resources.ts b/packages/ragmir-core/src/context-resources.ts
new file mode 100644
index 0000000..e5a0632
--- /dev/null
+++ b/packages/ragmir-core/src/context-resources.ts
@@ -0,0 +1,103 @@
+import { loadConfig } from "./config.js"
+import { doctor } from "./doctor.js"
+import { audit } from "./ingest.js"
+import { knowledgeBaseIdentity } from "./knowledge-bases.js"
+import type {
+  KnowledgeBaseContextReport,
+  KnowledgeBaseSourceCatalog,
+  SkippedSourceFile,
+} from "./types.js"
+
+const SOURCE_CATALOG_LIMIT = 50
+const RAGMIR_MCP_TOOLS = [
+  "ragmir_status",
+  "ragmir_route_prompt",
+  "ragmir_search",
+  "ragmir_ask",
+  "ragmir_research",
+  "ragmir_expand",
+  "ragmir_audit",
+  "ragmir_evaluate",
+  "ragmir_usage_report",
+  "ragmir_security_audit",
+]
+const RAGMIR_MCP_RESOURCES = ["ragmir://context", "ragmir://sources"]
+
+export async function getKnowledgeBaseContext(
+  cwd = process.cwd(),
+): Promise<KnowledgeBaseContextReport> {
+  const config = await loadConfig(cwd)
+  const report = await doctor(config.projectRoot)
+  const identity = knowledgeBaseIdentity(config.projectRoot)
+
+  return {
+    knowledgeBaseId: identity?.id ?? null,
+    projectRoot: config.privacyProfile === "strict" ? "." : config.projectRoot,
+    privacyProfile: config.privacyProfile,
+    retrievalProfile: config.retrievalProfile,
+    embeddingProvider: config.embeddingProvider,
+    ready: report.ready,
+    coverage: {
+      supportedFiles: report.supportedFiles,
+      indexedFiles: report.indexedFiles,
+      chunksIndexed: report.chunksIndexed,
+      missingFromIndex: report.missingFromIndex,
+      staleInIndex: report.staleInIndex,
+      emptyTextFiles: report.emptyTextFiles,
+    },
+    indexFreshness: report.indexFreshness,
+    securityWarningCount: report.securityWarnings.length,
+    nextSteps: report.nextSteps,
+    routing: {
+      selection: "nearest-configured-ancestor",
+      discoverCommand: "rgr bases --json",
+    },
+    tools: [...RAGMIR_MCP_TOOLS],
+    resources: [...RAGMIR_MCP_RESOURCES],
+  }
+}
+
+export async function getKnowledgeBaseSourceCatalog(
+  cwd = process.cwd(),
+): Promise<KnowledgeBaseSourceCatalog> {
+  const config = await loadConfig(cwd)
+  const report = await audit(config.projectRoot)
+  const identity = knowledgeBaseIdentity(config.projectRoot)
+  const indexedFiles = report.indexedFiles.slice(0, SOURCE_CATALOG_LIMIT)
+  const missingFromIndex = report.missingFromIndex.slice(0, SOURCE_CATALOG_LIMIT)
+  const staleInIndex = report.staleInIndex.slice(0, SOURCE_CATALOG_LIMIT)
+  const emptyTextFiles = report.emptyTextFiles.slice(0, SOURCE_CATALOG_LIMIT)
+
+  return {
+    knowledgeBaseId: identity?.id ?? null,
+    totals: {
+      indexedFiles: report.indexedFiles.length,
+      chunks: report.totalChunks,
+      missingFromIndex: report.missingFromIndex.length,
+      staleInIndex: report.staleInIndex.length,
+      emptyTextFiles: report.emptyTextFiles.length,
+      skippedFiles: report.skippedFiles.length,
+    },
+    indexedFiles,
+    missingFromIndex,
+    staleInIndex,
+    emptyTextFiles,
+    skippedByReason: skippedCounts(report.skippedFiles),
+    omitted: {
+      indexedFiles: report.indexedFiles.length - indexedFiles.length,
+      missingFromIndex: report.missingFromIndex.length - missingFromIndex.length,
+      staleInIndex: report.staleInIndex.length - staleInIndex.length,
+      emptyTextFiles: report.emptyTextFiles.length - emptyTextFiles.length,
+    },
+  }
+}
+
+function skippedCounts(skippedFiles: SkippedSourceFile[]): Record<string, number> {
+  const counts = new Map<string, number>()
+  for (const skipped of skippedFiles) {
+    counts.set(skipped.reason, (counts.get(skipped.reason) ?? 0) + 1)
+  }
+  return Object.fromEntries(
+    [...counts.entries()].sort(([left], [right]) => left.localeCompare(right)),
+  )
+}
diff --git a/packages/ragmir-core/src/evaluate.test.ts b/packages/ragmir-core/src/evaluate.test.ts
index 321130e..c4f552e 100644
--- a/packages/ragmir-core/src/evaluate.test.ts
+++ b/packages/ragmir-core/src/evaluate.test.ts
@@ -1,10 +1,11 @@
-import { cp, mkdtemp, rm, writeFile } from "node:fs/promises"
+import { cp, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"
 import os from "node:os"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
 import { afterEach, describe, expect, it } from "vitest"
 import { evaluateGoldenQueries } from "./evaluate.js"
 import { ingest } from "./ingest.js"
+import { initProject } from "./init.js"
 
 const tempDirs: string[] = []
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
@@ -185,6 +186,48 @@ describe("evaluateGoldenQueries", () => {
     expect(result?.returnedPaths).not.toContain("raw/security-policy.yaml")
   })
 
+  it("applies structural context filters declared by each golden query", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-evaluate-context-filter-"))
+    tempDirs.push(root)
+    await initProject(root)
+    await mkdir(path.join(root, ".ragmir", "raw"), { recursive: true })
+    await writeFile(
+      path.join(root, ".ragmir", "raw", "runbook.md"),
+      [
+        "# Operations",
+        "",
+        "## Current",
+        "Verified approval evidence for the current workflow.",
+        "",
+        "## Archive",
+        "Verified approval evidence for the archived workflow.",
+      ].join("\n"),
+      "utf8",
+    )
+    await writeFile(
+      path.join(root, "context-golden.json"),
+      JSON.stringify([
+        {
+          query: "verified approval evidence",
+          expectedPaths: [".ragmir/raw/runbook.md"],
+          contextPaths: ["Operations > Archive"],
+          topK: 3,
+        },
+      ]),
+      "utf8",
+    )
+    await ingest({ cwd: root })
+
+    const report = await evaluateGoldenQueries({
+      cwd: root,
+      goldenPath: "context-golden.json",
+    })
+
+    expect(report.cases[0]?.hit).toBe(true)
+    expect(report.cases[0]?.contextPaths).toEqual(["Operations > Archive"])
+    expect(report.cases[0]?.returnedPaths).toEqual([".ragmir/raw/runbook.md"])
+  })
+
   it("reports a miss when no expected path is retrieved", async () => {
     const parent = await mkdtemp(path.join(os.tmpdir(), "ragmir-evaluate-miss-"))
     tempDirs.push(parent)
diff --git a/packages/ragmir-core/src/evaluate.ts b/packages/ragmir-core/src/evaluate.ts
index 91bee7e..95f280c 100644
--- a/packages/ragmir-core/src/evaluate.ts
+++ b/packages/ragmir-core/src/evaluate.ts
@@ -19,6 +19,7 @@ const goldenQuerySchema = z
     expectedCitations: z.array(z.string().min(1)).min(1).optional(),
     includePaths: z.array(z.string().min(1).max(500)).max(20).optional(),
     excludePaths: z.array(z.string().min(1).max(500)).max(20).optional(),
+    contextPaths: z.array(z.string().min(1).max(500)).max(20).optional(),
     topK: z.number().int().positive().optional(),
   })
   .strict()
@@ -49,6 +50,7 @@ export async function evaluateGoldenQueries(options: EvaluationOptions): Promise
       topK,
       ...(goldenQuery.includePaths === undefined ? {} : { includePaths: goldenQuery.includePaths }),
       ...(goldenQuery.excludePaths === undefined ? {} : { excludePaths: goldenQuery.excludePaths }),
+      ...(goldenQuery.contextPaths === undefined ? {} : { contextPaths: goldenQuery.contextPaths }),
     })
     const latencyMs = performance.now() - startedAt
     const returnedPaths = results.map((result) => result.relativePath)
@@ -103,6 +105,9 @@ export async function evaluateGoldenQueries(options: EvaluationOptions): Promise
     if (goldenQuery.excludePaths !== undefined) {
       result.excludePaths = goldenQuery.excludePaths
     }
+    if (goldenQuery.contextPaths !== undefined) {
+      result.contextPaths = goldenQuery.contextPaths
+    }
     cases.push(result)
   }
 
@@ -169,6 +174,9 @@ function normalizeGoldenQuery(value: z.infer<typeof goldenQuerySchema>): GoldenQ
   if (value.excludePaths !== undefined) {
     result.excludePaths = value.excludePaths
   }
+  if (value.contextPaths !== undefined) {
+    result.contextPaths = value.contextPaths
+  }
   return result
 }
 
diff --git a/packages/ragmir-core/src/index.ts b/packages/ragmir-core/src/index.ts
index 9c71c71..f41a988 100644
--- a/packages/ragmir-core/src/index.ts
+++ b/packages/ragmir-core/src/index.ts
@@ -1,5 +1,9 @@
 export { accessLogUsageReport } from "./access-log.js"
 export { loadConfig } from "./config.js"
+export {
+  getKnowledgeBaseContext,
+  getKnowledgeBaseSourceCatalog,
+} from "./context-resources.js"
 export { destroyIndex } from "./destroy.js"
 export { doctor } from "./doctor.js"
 export { clearTransformersCache, pullEmbeddingModel } from "./embeddings.js"
@@ -11,6 +15,7 @@ export {
 } from "./index-diagnostics.js"
 export { audit, ingest } from "./ingest.js"
 export { initProject } from "./init.js"
+export { discoverKnowledgeBases, knowledgeBaseIdentity } from "./knowledge-bases.js"
 export { ingestionLimits } from "./limits.js"
 export { serveMcp } from "./mcp.js"
 export type {
@@ -25,6 +30,7 @@ export type {
 export { configurePdfOcr, extractPdfPage, inspectPdfOcr } from "./ocr.js"
 export type { PackageManager, RagmirCommand } from "./package-manager.js"
 export { detectPackageManager, kbCommand, ragmirCommand, rgrCommand } from "./package-manager.js"
+export { previewChunks } from "./preview.js"
 export type { PromptRouteDecision, PromptRouteTool } from "./prompt-routing.js"
 export { routePrompt } from "./prompt-routing.js"
 export { ask, expandCitation, search } from "./query.js"
@@ -64,6 +70,7 @@ export type {
   AccessLogUsageReport,
   AskResult,
   AuditReport,
+  ChunkStats,
   CodeEvidence,
   CompactSearchResult,
   Config,
@@ -79,9 +86,18 @@ export type {
   IndexManifestFile,
   IngestionLimitsReport,
   IngestResult,
+  KnowledgeBaseContextReport,
+  KnowledgeBaseIdentity,
+  KnowledgeBaseInfo,
+  KnowledgeBaseInventory,
+  KnowledgeBaseSourceCatalog,
   McpOutputTool,
   McpOutputUsageReport,
   ParsedPage,
+  PreviewChunk,
+  PreviewChunksOptions,
+  PreviewFile,
+  PreviewReport,
   PrivacyProfile,
   ResearchEvidence,
   ResearchOptions,
@@ -89,6 +105,7 @@ export type {
   RetrievalProfile,
   SearchContextChunk,
   SearchResult,
+  SearchScoreExplanation,
   SecurityAuditReport,
   SourceDiagnostics,
   SourceDuplicateCandidate,
diff --git a/packages/ragmir-core/src/ingest.test.ts b/packages/ragmir-core/src/ingest.test.ts
index 284ebe6..914df0d 100644
--- a/packages/ragmir-core/src/ingest.test.ts
+++ b/packages/ragmir-core/src/ingest.test.ts
@@ -44,6 +44,10 @@ describe("ingest", () => {
     expect(report.supportedBytes).toBeGreaterThan(0)
     expect(report.largestFileBytes).toBeGreaterThan(0)
     expect(report.staleInIndex).toEqual([".ragmir/raw/evidence.md"])
+    expect(report.chunkStats.count).toBe(1)
+    expect(report.chunkStats.minChars).toBeGreaterThan(0)
+    expect(report.chunkStats.p95Chars).toBe(report.chunkStats.maxChars)
+    expect(report.chunkStats.contextualRatio).toBe(0)
     expect(report.skippedFiles).toEqual([
       expect.objectContaining({
         relativePath: ".ragmir/raw/scan.heic",
diff --git a/packages/ragmir-core/src/ingest.ts b/packages/ragmir-core/src/ingest.ts
index 0a4b3ae..50085cf 100644
--- a/packages/ragmir-core/src/ingest.ts
+++ b/packages/ragmir-core/src/ingest.ts
@@ -1,4 +1,5 @@
 import { recordAccess } from "./access-log.js"
+import { summarizeChunkStats } from "./chunk-stats.js"
 import { chunkDocument, chunkSearchText } from "./chunking.js"
 import { loadConfig } from "./config.js"
 import { VECTOR_DISTANCE_METRIC } from "./defaults.js"
@@ -289,12 +290,18 @@ export async function audit(cwd = process.cwd()): Promise<AuditReport> {
       missingFromIndex: supportedFiles.filter((file) => !emptyTextFiles.has(file)),
       staleInIndex: [],
       totalChunks: 0,
+      chunkStats: summarizeChunkStats([]),
     }
   }
 
-  const rows = (await table.query().select(["relativePath", "checksum"]).toArray()) as Array<{
+  const rows = (await table
+    .query()
+    .select(["relativePath", "checksum", "contextPath", "text"])
+    .toArray()) as Array<{
     relativePath: string
     checksum?: string
+    contextPath: string
+    text: string
   }>
   const counts = new Map<string, number>()
   const checksums = new Map<string, Set<string>>()
@@ -337,6 +344,7 @@ export async function audit(cwd = process.cwd()): Promise<AuditReport> {
       })
       .sort(),
     totalChunks: rows.length,
+    chunkStats: summarizeChunkStats(rows),
   }
 }
 
diff --git a/packages/ragmir-core/src/knowledge-bases.test.ts b/packages/ragmir-core/src/knowledge-bases.test.ts
new file mode 100644
index 0000000..f02331c
--- /dev/null
+++ b/packages/ragmir-core/src/knowledge-bases.test.ts
@@ -0,0 +1,72 @@
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { discoverKnowledgeBases, knowledgeBaseIdentity } from "./knowledge-bases.js"
+
+const tempDirs: string[] = []
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true })
+  }
+})
+
+describe("knowledge bases", () => {
+  it("should discover nested bases and select the nearest configured ancestor", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-bases-"))
+    tempDirs.push(root)
+    const web = path.join(root, "apps", "web")
+    const api = path.join(root, "apps", "api")
+    const webSource = path.join(web, "src", "features")
+    await writeConfig(root)
+    await writeConfig(web)
+    await writeConfig(api)
+    await mkdir(webSource, { recursive: true })
+
+    expect(knowledgeBaseIdentity(webSource)).toEqual({
+      id: "apps/web",
+      projectRoot: web,
+      workspaceRoot: root,
+    })
+
+    const inventory = await discoverKnowledgeBases(webSource)
+
+    expect(inventory.workspaceRoot).toBe(root)
+    expect(inventory.activeProjectRoot).toBe(web)
+    expect(inventory.activeId).toBe("apps/web")
+    expect(inventory.bases.map((base) => base.id)).toEqual([".", "apps/api", "apps/web"])
+    expect(inventory.bases.find((base) => base.active)?.id).toBe("apps/web")
+  })
+
+  it("should report descendant bases when invoked from an unconfigured workspace", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-bases-unconfigured-"))
+    tempDirs.push(root)
+    await writeConfig(path.join(root, "packages", "docs"))
+    await writeConfig(path.join(root, "node_modules", "ignored"))
+
+    const inventory = await discoverKnowledgeBases(root)
+
+    expect(inventory.activeId).toBeNull()
+    expect(inventory.bases.map((base) => base.id)).toEqual(["packages/docs"])
+  })
+
+  it("should prefer a current Ragmir config when a legacy config also exists", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-bases-legacy-"))
+    tempDirs.push(root)
+    await writeConfig(root)
+    await mkdir(path.join(root, ".kb"), { recursive: true })
+    await writeFile(path.join(root, ".kb", "config.json"), "{}\n", "utf8")
+
+    const inventory = await discoverKnowledgeBases(root)
+
+    expect(inventory.bases).toHaveLength(1)
+    expect(inventory.bases[0]?.legacy).toBe(false)
+    expect(inventory.bases[0]?.configPath).toBe(path.join(root, ".ragmir", "config.json"))
+  })
+})
+
+async function writeConfig(projectRoot: string): Promise<void> {
+  await mkdir(path.join(projectRoot, ".ragmir"), { recursive: true })
+  await writeFile(path.join(projectRoot, ".ragmir", "config.json"), "{}\n", "utf8")
+}
diff --git a/packages/ragmir-core/src/knowledge-bases.ts b/packages/ragmir-core/src/knowledge-bases.ts
new file mode 100644
index 0000000..003ca19
--- /dev/null
+++ b/packages/ragmir-core/src/knowledge-bases.ts
@@ -0,0 +1,129 @@
+import { existsSync } from "node:fs"
+import path from "node:path"
+import fg from "fast-glob"
+import { CONFIG_PATH, LEGACY_CONFIG_PATH } from "./defaults.js"
+import type { KnowledgeBaseIdentity, KnowledgeBaseInfo, KnowledgeBaseInventory } from "./types.js"
+
+const KNOWLEDGE_BASE_PATTERNS = [
+  CONFIG_PATH,
+  `**/${CONFIG_PATH}`,
+  LEGACY_CONFIG_PATH,
+  `**/${LEGACY_CONFIG_PATH}`,
+]
+const KNOWLEDGE_BASE_DISCOVERY_IGNORES = [
+  "**/.git/**",
+  "**/node_modules/**",
+  "**/.pnpm/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/.next/**",
+  "**/.astro/**",
+  "**/.svelte-kit/**",
+  "**/.turbo/**",
+  "**/coverage/**",
+]
+
+interface ConfiguredRoot {
+  projectRoot: string
+  configPath: string
+  legacy: boolean
+}
+
+export function knowledgeBaseIdentity(start = process.cwd()): KnowledgeBaseIdentity | null {
+  const configuredRoots = configuredAncestors(start)
+  const active = configuredRoots[0]
+  const workspace = configuredRoots.at(-1)
+  if (!active || !workspace) {
+    return null
+  }
+  return {
+    id: knowledgeBaseId(workspace.projectRoot, active.projectRoot),
+    projectRoot: active.projectRoot,
+    workspaceRoot: workspace.projectRoot,
+  }
+}
+
+export async function discoverKnowledgeBases(
+  start = process.cwd(),
+): Promise<KnowledgeBaseInventory> {
+  const resolvedStart = path.resolve(start)
+  const identity = knowledgeBaseIdentity(resolvedStart)
+  const workspaceRoot = identity?.workspaceRoot ?? resolvedStart
+  const configPaths = await fg(KNOWLEDGE_BASE_PATTERNS, {
+    cwd: workspaceRoot,
+    absolute: true,
+    dot: true,
+    onlyFiles: true,
+    unique: true,
+    followSymbolicLinks: false,
+    ignore: KNOWLEDGE_BASE_DISCOVERY_IGNORES,
+  })
+  const byProjectRoot = new Map<string, ConfiguredRoot>()
+  for (const configPath of configPaths.sort()) {
+    const configuredRoot = configuredRootForConfig(configPath)
+    const existing = byProjectRoot.get(configuredRoot.projectRoot)
+    if (!existing || (existing.legacy && !configuredRoot.legacy)) {
+      byProjectRoot.set(configuredRoot.projectRoot, configuredRoot)
+    }
+  }
+  const bases: KnowledgeBaseInfo[] = [...byProjectRoot.values()]
+    .map((base) => ({
+      id: knowledgeBaseId(workspaceRoot, base.projectRoot),
+      projectRoot: base.projectRoot,
+      configPath: base.configPath,
+      legacy: base.legacy,
+      active: base.projectRoot === identity?.projectRoot,
+    }))
+    .sort((left, right) => left.id.localeCompare(right.id))
+
+  return {
+    start: resolvedStart,
+    workspaceRoot,
+    activeProjectRoot: identity?.projectRoot ?? null,
+    activeId: identity?.id ?? null,
+    bases,
+  }
+}
+
+function configuredAncestors(start: string): ConfiguredRoot[] {
+  const roots: ConfiguredRoot[] = []
+  let current = path.resolve(start)
+  while (true) {
+    const configuredRoot = configuredRootAt(current)
+    if (configuredRoot) {
+      roots.push(configuredRoot)
+    }
+    const parent = path.dirname(current)
+    if (parent === current) {
+      return roots
+    }
+    current = parent
+  }
+}
+
+function configuredRootAt(projectRoot: string): ConfiguredRoot | null {
+  const configPath = path.join(projectRoot, CONFIG_PATH)
+  if (existsSync(configPath)) {
+    return { projectRoot, configPath, legacy: false }
+  }
+  const legacyConfigPath = path.join(projectRoot, LEGACY_CONFIG_PATH)
+  if (existsSync(legacyConfigPath)) {
+    return { projectRoot, configPath: legacyConfigPath, legacy: true }
+  }
+  return null
+}
+
+function configuredRootForConfig(configPath: string): ConfiguredRoot {
+  const configDirectory = path.dirname(configPath)
+  const legacy = path.basename(configDirectory) === path.dirname(LEGACY_CONFIG_PATH)
+  return {
+    projectRoot: path.dirname(configDirectory),
+    configPath,
+    legacy,
+  }
+}
+
+function knowledgeBaseId(workspaceRoot: string, projectRoot: string): string {
+  const relativePath = path.relative(workspaceRoot, projectRoot)
+  return relativePath.length === 0 ? "." : relativePath.split(path.sep).join("/")
+}
diff --git a/packages/ragmir-core/src/mcp.test.ts b/packages/ragmir-core/src/mcp.test.ts
index 5e591b1..aa592c3 100644
--- a/packages/ragmir-core/src/mcp.test.ts
+++ b/packages/ragmir-core/src/mcp.test.ts
@@ -36,6 +36,21 @@ describe("resolveMcpProjectRoot", () => {
     )
     expect(resolveMcpProjectRoot({}, "/repo/cwd")).toBe("/repo/cwd")
   })
+
+  it("should resolve the nearest nested base before a monorepo root", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-mcp-monorepo-"))
+    tempDirs.push(root)
+    const app = path.join(root, "apps", "web")
+    const appSource = path.join(app, "src")
+    await mkdir(path.join(root, ".ragmir"), { recursive: true })
+    await mkdir(path.join(app, ".ragmir"), { recursive: true })
+    await mkdir(appSource, { recursive: true })
+    await writeFile(path.join(root, ".ragmir", "config.json"), "{}\n", "utf8")
+    await writeFile(path.join(app, ".ragmir", "config.json"), "{}\n", "utf8")
+
+    expect(resolveMcpProjectRoot({}, appSource)).toBe(app)
+    expect(resolveMcpProjectRoot({ RAGMIR_PROJECT_ROOT: root }, appSource)).toBe(root)
+  })
 })
 
 describe("searchOptions", () => {
@@ -54,13 +69,23 @@ describe("searchOptions", () => {
     expect((await searchOptions(root, undefined)).topK).toBe(5)
     expect((await searchOptions(root, 2, 20)).contextRadius).toBe(3)
     expect(
-      await searchOptions(root, 2, 1, [".ragmir/raw/primary"], [".ragmir/raw/research"]),
+      await searchOptions(
+        root,
+        2,
+        1,
+        [".ragmir/raw/primary"],
+        [".ragmir/raw/research"],
+        ["Operations > Release"],
+        true,
+      ),
     ).toEqual({
       cwd: root,
       topK: 2,
       contextRadius: 1,
       includePaths: [".ragmir/raw/primary"],
       excludePaths: [".ragmir/raw/research"],
+      contextPaths: ["Operations > Release"],
+      explain: true,
     })
   })
 })
diff --git a/packages/ragmir-core/src/mcp.ts b/packages/ragmir-core/src/mcp.ts
index 83b74e5..33a4f0a 100644
--- a/packages/ragmir-core/src/mcp.ts
+++ b/packages/ragmir-core/src/mcp.ts
@@ -5,9 +5,11 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod"
 import { accessLogUsageReport, recordMcpOutput } from "./access-log.js"
 import { findProjectConfig, loadConfig } from "./config.js"
+import { getKnowledgeBaseContext, getKnowledgeBaseSourceCatalog } from "./context-resources.js"
 import { RAGMIR_PROJECT_ROOT_ENV } from "./defaults.js"
 import { evaluateGoldenQueries } from "./evaluate.js"
 import { audit } from "./ingest.js"
+import { knowledgeBaseIdentity } from "./knowledge-bases.js"
 import { ingestionLimits } from "./limits.js"
 import type {
   BudgetedMcpResult,
@@ -39,6 +41,8 @@ const queryToolInputSchema = z.object({
   maxBytes: z.number().int().min(MIN_MCP_OUTPUT_BYTES).optional(),
   includePaths: z.array(z.string().min(1).max(500)).max(20).optional(),
   excludePaths: z.array(z.string().min(1).max(500)).max(20).optional(),
+  contextPaths: z.array(z.string().min(1).max(500)).max(20).optional(),
+  explain: z.boolean().optional(),
 })
 
 const askToolInputSchema = queryToolInputSchema.extend({
@@ -53,6 +57,7 @@ const researchToolInputSchema = z.object({
   maxBytes: z.number().int().min(MIN_MCP_OUTPUT_BYTES).optional(),
   includePaths: z.array(z.string().min(1).max(500)).max(20).optional(),
   excludePaths: z.array(z.string().min(1).max(500)).max(20).optional(),
+  contextPaths: z.array(z.string().min(1).max(500)).max(20).optional(),
 })
 
 const searchToolInputSchema = queryToolInputSchema.extend({
@@ -85,6 +90,30 @@ export async function serveMcp(cwd = resolveMcpProjectRoot()): Promise<void> {
     version: VERSION,
   })
 
+  server.registerResource(
+    "ragmir-context",
+    "ragmir://context",
+    {
+      title: "Ragmir Knowledge Base Context",
+      description:
+        "Active base identity, readiness, freshness, coverage, and available operations.",
+      mimeType: "application/json",
+    },
+    async (uri) => jsonResource(uri, await getKnowledgeBaseContext(cwd)),
+  )
+
+  server.registerResource(
+    "ragmir-sources",
+    "ragmir://sources",
+    {
+      title: "Ragmir Source Catalog",
+      description:
+        "Bounded source coverage, skipped-file counts, and index drift for the active base.",
+      mimeType: "application/json",
+    },
+    async (uri) => jsonResource(uri, await getKnowledgeBaseSourceCatalog(cwd)),
+  )
+
   server.registerTool(
     "ragmir_status",
     {
@@ -94,9 +123,11 @@ export async function serveMcp(cwd = resolveMcpProjectRoot()): Promise<void> {
     },
     async () => {
       const config = await loadConfig(cwd)
+      const identity = knowledgeBaseIdentity(config.projectRoot)
       const chunksIndexed = await countRows(config)
       const strict = config.privacyProfile === "strict"
       const output = {
+        knowledgeBaseId: identity?.id ?? null,
         projectRoot: strict ? "." : config.projectRoot,
         rawDir: strict ? path.relative(config.projectRoot, config.rawDir) : config.rawDir,
         storageDir: strict
@@ -154,11 +185,29 @@ export async function serveMcp(cwd = resolveMcpProjectRoot()): Promise<void> {
       description: "Retrieve relevant passages from the local Ragmir knowledge base.",
       inputSchema: searchToolInputSchema,
     },
-    async ({ query, topK, contextRadius, compact, maxBytes, includePaths, excludePaths }) => {
+    async ({
+      query,
+      topK,
+      contextRadius,
+      compact,
+      maxBytes,
+      includePaths,
+      excludePaths,
+      contextPaths,
+      explain,
+    }) => {
       const config = await loadConfig(cwd)
       const results = await search(
         query,
-        await searchOptions(cwd, topK, contextRadius, includePaths, excludePaths),
+        await searchOptions(
+          cwd,
+          topK,
+          contextRadius,
+          includePaths,
+          excludePaths,
+          contextPaths,
+          explain,
+        ),
       )
       const compactResults = compactSearchResults(results)
       const compactOutput = config.privacyProfile === "strict" || compact === true
@@ -184,9 +233,27 @@ export async function serveMcp(cwd = resolveMcpProjectRoot()): Promise<void> {
       description: "Return cited retrieval context for a question without calling an LLM.",
       inputSchema: askToolInputSchema,
     },
-    async ({ query, topK, contextRadius, compact, maxBytes, includePaths, excludePaths }) => {
+    async ({
+      query,
+      topK,
+      contextRadius,
+      compact,
+      maxBytes,
+      includePaths,
+      excludePaths,
+      contextPaths,
+      explain,
+    }) => {
       const config = await loadConfig(cwd)
-      const options = await searchOptions(cwd, topK, contextRadius, includePaths, excludePaths)
+      const options = await searchOptions(
+        cwd,
+        topK,
+        contextRadius,
+        includePaths,
+        excludePaths,
+        contextPaths,
+        explain,
+      )
       let fullPayload: AskResult
       if (config.privacyProfile === "strict") {
         const results = await search(query, options)
@@ -226,14 +293,31 @@ export async function serveMcp(cwd = resolveMcpProjectRoot()): Promise<void> {
         "Run an audit-backed multi-query research pass with cited evidence and optional code matches.",
       inputSchema: researchToolInputSchema,
     },
-    async ({ query, topK, includeCode, compact, maxBytes, includePaths, excludePaths }) => {
+    async ({
+      query,
+      topK,
+      includeCode,
+      compact,
+      maxBytes,
+      includePaths,
+      excludePaths,
+      contextPaths,
+    }) => {
       const config = await loadConfig(cwd)
-      const options = await searchOptions(cwd, topK, undefined, includePaths, excludePaths)
+      const options = await searchOptions(
+        cwd,
+        topK,
+        undefined,
+        includePaths,
+        excludePaths,
+        contextPaths,
+      )
       const researchOptions: Parameters<typeof research>[1] = { cwd }
       addOption(researchOptions, "topK", options.topK)
       addOption(researchOptions, "includeCode", includeCode)
       addOption(researchOptions, "includePaths", options.includePaths)
       addOption(researchOptions, "excludePaths", options.excludePaths)
+      addOption(researchOptions, "contextPaths", options.contextPaths)
       const result = await research(query, researchOptions)
       const compactResult = compactResearchReport(result)
       const compactOutput = config.privacyProfile === "strict" || compact === true
@@ -391,6 +475,21 @@ function textResult(value: unknown): { content: Array<{ type: "text"; text: stri
   }
 }
 
+function jsonResource(
+  uri: URL,
+  value: unknown,
+): { contents: Array<{ uri: string; mimeType: string; text: string }> } {
+  return {
+    contents: [
+      {
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(value, null, 2),
+      },
+    ],
+  }
+}
+
 async function recordBudgetedOutput(
   config: Awaited<ReturnType<typeof loadConfig>>,
   bounded: BudgetedMcpResult,
@@ -410,12 +509,16 @@ export async function searchOptions(
   contextRadius?: number | undefined,
   includePaths?: string[] | undefined,
   excludePaths?: string[] | undefined,
+  contextPaths?: string[] | undefined,
+  explain?: boolean | undefined,
 ): Promise<{
   cwd: string
   topK?: number
   contextRadius?: number
   includePaths?: string[]
   excludePaths?: string[]
+  contextPaths?: string[]
+  explain?: boolean
 }> {
   const config = await loadConfig(cwd)
   const boundedTopK = Math.min(topK ?? config.topK, config.mcpMaxTopK)
@@ -427,6 +530,8 @@ export async function searchOptions(
     contextRadius?: number
     includePaths?: string[]
     excludePaths?: string[]
+    contextPaths?: string[]
+    explain?: boolean
   } = {
     cwd,
     topK: boundedTopK,
@@ -434,6 +539,8 @@ export async function searchOptions(
   addOption(result, "contextRadius", boundedContextRadius)
   addOption(result, "includePaths", includePaths)
   addOption(result, "excludePaths", excludePaths)
+  addOption(result, "contextPaths", contextPaths)
+  addOption(result, "explain", explain)
   return result
 }
 
diff --git a/packages/ragmir-core/src/preview.test.ts b/packages/ragmir-core/src/preview.test.ts
new file mode 100644
index 0000000..f2a667e
--- /dev/null
+++ b/packages/ragmir-core/src/preview.test.ts
@@ -0,0 +1,76 @@
+import { existsSync } from "node:fs"
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+import { afterEach, describe, expect, it } from "vitest"
+import { initProject } from "./init.js"
+import { previewChunks } from "./preview.js"
+
+const tempDirs: string[] = []
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) {
+    await rm(dir, { recursive: true, force: true })
+  }
+})
+
+describe("previewChunks", () => {
+  it("should preview redacted structured chunks without writing an index", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-preview-"))
+    tempDirs.push(root)
+    await initProject(root)
+    await mkdir(path.join(root, ".ragmir", "raw", "guides"), { recursive: true })
+    await writeFile(
+      path.join(root, ".ragmir", "config.json"),
+      JSON.stringify({ chunkSize: 80, chunkOverlap: 10 }),
+      "utf8",
+    )
+    await writeFile(
+      path.join(root, ".ragmir", "raw", "guides", "operations.md"),
+      [
+        "# Operations",
+        "",
+        "## Release evidence",
+        "Contact owner@example.com before the signed release is promoted to production.",
+        "",
+        "A second paragraph makes the section large enough to produce another exact chunk.",
+      ].join("\n"),
+      "utf8",
+    )
+
+    const report = await previewChunks({
+      cwd: root,
+      paths: [".ragmir/raw/guides"],
+      maxChunksPerFile: 1,
+    })
+
+    expect(report.matchedFiles).toBe(1)
+    expect(report.unmatchedPaths).toEqual([])
+    expect(report.files[0]?.redactions).toBe(1)
+    expect(report.files[0]?.chunkStats.count).toBeGreaterThan(1)
+    expect(report.files[0]?.chunkStats.contextualRatio).toBe(1)
+    expect(report.files[0]?.chunks).toHaveLength(1)
+    expect(report.files[0]?.chunks[0]?.contextPath).toContain("Operations")
+    expect(report.files[0]?.chunks[0]?.citation).toContain(":L")
+    expect(report.files[0]?.chunks[0]?.text).not.toContain("owner@example.com")
+    expect(report.files[0]?.omittedChunks).toBeGreaterThan(0)
+    expect(existsSync(path.join(root, ".ragmir", "storage"))).toBe(false)
+  })
+
+  it("should report unmatched source prefixes without parsing unrelated files", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-preview-unmatched-"))
+    tempDirs.push(root)
+    await initProject(root)
+
+    const report = await previewChunks({ cwd: root, paths: ["missing"] })
+
+    expect(report.matchedFiles).toBe(0)
+    expect(report.unmatchedPaths).toEqual(["missing"])
+    expect(report.files).toEqual([])
+  })
+
+  it("should reject invalid limits at the library boundary", async () => {
+    await expect(previewChunks({ maxFiles: 0 })).rejects.toThrow("maxFiles")
+    await expect(previewChunks({ maxChunksPerFile: 1.5 })).rejects.toThrow("maxChunksPerFile")
+  })
+})
diff --git a/packages/ragmir-core/src/preview.ts b/packages/ragmir-core/src/preview.ts
new file mode 100644
index 0000000..7bb6f8e
--- /dev/null
+++ b/packages/ragmir-core/src/preview.ts
@@ -0,0 +1,161 @@
+import { summarizeChunkStats } from "./chunk-stats.js"
+import { chunkDocument } from "./chunking.js"
+import { loadConfig } from "./config.js"
+import { inventorySourceFiles } from "./files.js"
+import { parseFile } from "./parsing.js"
+import { redactText, totalRedactions } from "./redaction.js"
+import type {
+  PreviewChunk,
+  PreviewChunksOptions,
+  PreviewFile,
+  PreviewReport,
+  SourceFile,
+  TextChunk,
+} from "./types.js"
+
+const DEFAULT_MAX_FILES = 5
+const DEFAULT_MAX_CHUNKS_PER_FILE = 5
+const MAX_PREVIEW_FILES = 25
+const MAX_PREVIEW_CHUNKS_PER_FILE = 50
+
+export async function previewChunks(options: PreviewChunksOptions = {}): Promise<PreviewReport> {
+  const config = await loadConfig(String(options.cwd ?? process.cwd()))
+  const inventory = await inventorySourceFiles(config)
+  const requestedPaths = normalizePathPrefixes(options.paths)
+  const maxFiles = boundedPositiveInteger(
+    options.maxFiles,
+    DEFAULT_MAX_FILES,
+    MAX_PREVIEW_FILES,
+    "maxFiles",
+  )
+  const maxChunksPerFile = boundedPositiveInteger(
+    options.maxChunksPerFile,
+    DEFAULT_MAX_CHUNKS_PER_FILE,
+    MAX_PREVIEW_CHUNKS_PER_FILE,
+    "maxChunksPerFile",
+  )
+  const matchingFiles = inventory.supportedFiles
+    .filter((file) => requestedPaths.length === 0 || matchesAnyPath(file, requestedPaths))
+    .sort((left, right) => left.relativePath.localeCompare(right.relativePath))
+  const selectedFiles = matchingFiles.slice(0, maxFiles)
+  const unmatchedPaths = requestedPaths.filter(
+    (prefix) => !inventory.supportedFiles.some((file) => matchesPath(file.relativePath, prefix)),
+  )
+
+  const previews = await Promise.all(
+    selectedFiles.map((file) => previewFile(file, config, maxChunksPerFile)),
+  )
+  const files: PreviewFile[] = []
+  const errors: PreviewReport["errors"] = []
+  for (const preview of previews) {
+    if ("error" in preview) {
+      errors.push(preview.error)
+    } else {
+      files.push(preview.file)
+    }
+  }
+
+  return {
+    chunkSize: config.chunkSize,
+    chunkOverlap: config.chunkOverlap,
+    requestedPaths,
+    unmatchedPaths,
+    matchedFiles: matchingFiles.length,
+    omittedFiles: Math.max(0, matchingFiles.length - selectedFiles.length),
+    files,
+    errors,
+  }
+}
+
+async function previewFile(
+  file: SourceFile,
+  config: Awaited<ReturnType<typeof loadConfig>>,
+  maxChunksPerFile: number,
+): Promise<{ file: PreviewFile } | { error: { path: string; message: string } }> {
+  try {
+    const parsed = await parseFile(file, config)
+    const redacted = redactText(parsed.text, config)
+    const chunks = chunkDocument(
+      { ...parsed, text: redacted.text },
+      config.chunkSize,
+      config.chunkOverlap,
+    )
+    return {
+      file: {
+        source: file.source,
+        relativePath: file.relativePath,
+        extension: file.extension,
+        bytes: file.bytes,
+        parsedChars: redacted.text.length,
+        redactions: totalRedactions(redacted.counts),
+        chunkStats: summarizeChunkStats(chunks),
+        chunks: chunks.slice(0, maxChunksPerFile).map(previewChunk),
+        omittedChunks: Math.max(0, chunks.length - maxChunksPerFile),
+      },
+    }
+  } catch (error) {
+    return {
+      error: {
+        path: file.relativePath,
+        message: error instanceof Error ? error.message : String(error),
+      },
+    }
+  }
+}
+
+function previewChunk(chunk: TextChunk): PreviewChunk {
+  return {
+    chunkIndex: chunk.chunkIndex,
+    contextPath: chunk.contextPath,
+    citation: citationForChunk(chunk),
+    text: chunk.text,
+    charStart: chunk.charStart,
+    charEnd: chunk.charEnd,
+    lineStart: chunk.lineStart,
+    lineEnd: chunk.lineEnd,
+    pageStart: chunk.pageStart ?? null,
+    pageEnd: chunk.pageEnd ?? null,
+  }
+}
+
+function citationForChunk(chunk: TextChunk): string {
+  const pageSegment =
+    chunk.pageStart === undefined
+      ? ""
+      : `:p${chunk.pageStart}${chunk.pageEnd !== undefined && chunk.pageEnd !== chunk.pageStart ? `-p${chunk.pageEnd}` : ""}`
+  return `${chunk.relativePath}${pageSegment}:L${chunk.lineStart}-L${chunk.lineEnd}#${chunk.chunkIndex}`
+}
+
+function matchesAnyPath(file: SourceFile, prefixes: string[]): boolean {
+  return prefixes.some((prefix) => matchesPath(file.relativePath, prefix))
+}
+
+function matchesPath(relativePath: string, prefix: string): boolean {
+  return relativePath === prefix || relativePath.startsWith(`${prefix}/`)
+}
+
+function normalizePathPrefixes(prefixes: string[] | undefined): string[] {
+  return [
+    ...new Set(
+      (prefixes ?? [])
+        .map((prefix) => prefix.trim().replaceAll("\\", "/").replace(/^\.\//u, ""))
+        .map((prefix) => prefix.replace(/\/+$/u, ""))
+        .filter(Boolean),
+    ),
+  ]
+}
+
+function boundedPositiveInteger(
+  value: number | undefined,
+  fallback: number,
+  maximum: number,
+  name: string,
+): number {
+  if (value === undefined) {
+    return fallback
+  }
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`${name} must be a positive integer.`)
+  }
+  return Math.min(value, maximum)
+}
diff --git a/packages/ragmir-core/src/query.test.ts b/packages/ragmir-core/src/query.test.ts
index b5fe42e..a7d94e1 100644
--- a/packages/ragmir-core/src/query.test.ts
+++ b/packages/ragmir-core/src/query.test.ts
@@ -83,6 +83,102 @@ describe("search", () => {
     )
   })
 
+  it("should filter retrieval by structural context prefixes", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-query-context-filter-"))
+    tempDirs.push(root)
+    await initProject(root)
+    await mkdir(path.join(root, ".ragmir", "raw"), { recursive: true })
+    await writeFile(
+      path.join(root, ".ragmir", "raw", "runbook.md"),
+      [
+        "# Operations",
+        "",
+        "## Release",
+        "The verified control evidence belongs to the active release workflow.",
+        "",
+        "## Archive",
+        "The verified control evidence belongs to the archived workflow.",
+      ].join("\n"),
+      "utf8",
+    )
+    await ingest({ cwd: root })
+
+    const results = await search("verified control evidence", {
+      cwd: root,
+      contextPaths: ["Operations > Archive"],
+    })
+
+    expect(results.length).toBeGreaterThan(0)
+    expect(results.every((result) => result.contextPath === "Operations > Archive")).toBe(true)
+    expect(results.every((result) => result.text.includes("archived workflow"))).toBe(true)
+  })
+
+  it("should keep root and app indexes isolated in a monorepo", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-query-monorepo-"))
+    tempDirs.push(root)
+    const app = path.join(root, "apps", "checkout")
+    const appSource = path.join(app, "src")
+    await initProject(root)
+    await initProject(app)
+    await mkdir(appSource, { recursive: true })
+    await writeFile(
+      path.join(root, ".ragmir", "raw", "architecture.md"),
+      "Root atlasproof describes the shared monorepo architecture.\n",
+      "utf8",
+    )
+    await writeFile(
+      path.join(app, ".ragmir", "raw", "payments.md"),
+      "Checkout vaultproof describes the isolated payment workflow.\n",
+      "utf8",
+    )
+    await ingest({ cwd: root })
+    await ingest({ cwd: app })
+
+    const rootResults = await search("atlasproof architecture", { cwd: root })
+    const appResults = await search("vaultproof payment", { cwd: appSource })
+    const rootLeak = await search("vaultproof", { cwd: root })
+    const appLeak = await search("atlasproof", { cwd: appSource })
+
+    expect(rootResults[0]?.text).toContain("atlasproof")
+    expect(appResults[0]?.text).toContain("vaultproof")
+    expect(rootLeak).toEqual([])
+    expect(appLeak).toEqual([])
+  })
+
+  it("should explain hybrid retrieval without changing the default result shape", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-query-explain-"))
+    tempDirs.push(root)
+    await initProject(root)
+    await mkdir(path.join(root, ".ragmir", "raw"), { recursive: true })
+    await writeFile(
+      path.join(root, ".ragmir", "raw", "security.md"),
+      "Token rotation requires signed source-control evidence.\n",
+      "utf8",
+    )
+    await writeFile(
+      path.join(root, ".ragmir", "raw", "facilities.md"),
+      "Facilities planning covers staffing and maintenance.\n",
+      "utf8",
+    )
+    await ingest({ cwd: root })
+
+    const plain = await search("token rotation evidence", { cwd: root, topK: 1 })
+    const explained = await search("token rotation evidence", { cwd: root, topK: 1, explain: true })
+    const score = explained[0]?.score
+
+    expect(plain[0]).not.toHaveProperty("score")
+    expect(explained[0]?.relativePath).toBe(plain[0]?.relativePath)
+    expect(score?.fusion).toBe("rrf")
+    expect(score?.combinedScore).toBeCloseTo(
+      (score?.vectorContribution ?? 0) + (score?.lexicalContribution ?? 0),
+    )
+    expect(score?.vectorRank).toBeGreaterThan(0)
+    expect(score?.lexicalRank).toBeGreaterThan(0)
+    expect(score?.vectorDistance).toBe(explained[0]?.distance)
+    expect(score?.lexicalBackendScore).toBeGreaterThan(0)
+    expect(score?.matchedTerms).toEqual(expect.arrayContaining(["token", "rotation", "evidence"]))
+  })
+
   it("uses the full-text lexical index when the fallback scan limit is narrow", async () => {
     const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-query-fts-"))
     tempDirs.push(root)
diff --git a/packages/ragmir-core/src/query.ts b/packages/ragmir-core/src/query.ts
index 5d1063d..cae51b2 100644
--- a/packages/ragmir-core/src/query.ts
+++ b/packages/ragmir-core/src/query.ts
@@ -40,6 +40,10 @@ interface RankedRow {
   vectorScore: number
   lexicalScore: number
   combinedScore: number
+  vectorRank: number | null
+  lexicalRank: number | null
+  lexicalBackendScore: number | null
+  matchedTerms: string[]
 }
 
 const VECTOR_CANDIDATE_POLICY: Record<
@@ -101,14 +105,21 @@ export async function search(query: string, options: SearchOptions = {}): Promis
   }
 
   const topK = options.topK ?? config.topK
-  const pathPredicate = sourcePathPredicate(options.includePaths, options.excludePaths)
+  const retrievalPredicate = searchPredicate(
+    options.includePaths,
+    options.excludePaths,
+    options.contextPaths,
+  )
   const [vector, textRows] = await Promise.all([
     embedText(sanitized.query, config),
-    lexicalCandidateRows(table, sanitized.query, config.hybridTextScanLimit, pathPredicate),
+    lexicalCandidateRows(table, sanitized.query, config.hybridTextScanLimit, retrievalPredicate),
   ])
   await assertVectorIndexCompatibility(config, vector.length)
   const vectorQuery = table.vectorSearch(vector).select(VECTOR_SEARCH_COLUMNS)
-  const vectorRows = (await (pathPredicate ? vectorQuery.where(pathPredicate) : vectorQuery)
+  const vectorRows = (await (retrievalPredicate
+    ? vectorQuery.where(retrievalPredicate)
+    : vectorQuery
+  )
     .limit(vectorCandidateLimit(topK, config.retrievalProfile))
     .toArray()) as SearchRow[]
   const rankedRows = rankHybridRows(sanitized.query, vectorRows, textRows)
@@ -124,22 +135,40 @@ export async function search(query: string, options: SearchOptions = {}): Promis
     options.contextRadius ?? defaultContextRadius,
   )
 
-  const results = rows.map((row) => ({
-    source: row.row.source,
-    relativePath: row.row.relativePath,
-    chunkIndex: row.row.chunkIndex,
-    contextPath: row.row.contextPath,
-    citation: citationForRow(row.row),
-    text: row.row.text,
-    distance: typeof row.row._distance === "number" ? row.row._distance : null,
-    charStart: nullableNumber(row.row.charStart),
-    charEnd: nullableNumber(row.row.charEnd),
-    lineStart: nullableNumber(row.row.lineStart),
-    lineEnd: nullableNumber(row.row.lineEnd),
-    pageStart: nullablePageNumber(row.row.pageStart),
-    pageEnd: nullablePageNumber(row.row.pageEnd),
-    context: contextByRow.get(rowKey(row.row)) ?? [],
-  }))
+  const results = rows.map((row) => {
+    const vectorDistance = typeof row.row._distance === "number" ? row.row._distance : null
+    return {
+      source: row.row.source,
+      relativePath: row.row.relativePath,
+      chunkIndex: row.row.chunkIndex,
+      contextPath: row.row.contextPath,
+      citation: citationForRow(row.row),
+      text: row.row.text,
+      distance: vectorDistance,
+      charStart: nullableNumber(row.row.charStart),
+      charEnd: nullableNumber(row.row.charEnd),
+      lineStart: nullableNumber(row.row.lineStart),
+      lineEnd: nullableNumber(row.row.lineEnd),
+      pageStart: nullablePageNumber(row.row.pageStart),
+      pageEnd: nullablePageNumber(row.row.pageEnd),
+      context: contextByRow.get(rowKey(row.row)) ?? [],
+      ...(options.explain
+        ? {
+            score: {
+              fusion: "rrf" as const,
+              combinedScore: row.combinedScore,
+              vectorContribution: row.vectorScore,
+              lexicalContribution: row.lexicalScore,
+              vectorRank: row.vectorRank,
+              lexicalRank: row.lexicalRank,
+              vectorDistance,
+              lexicalBackendScore: row.lexicalBackendScore,
+              matchedTerms: row.matchedTerms,
+            },
+          }
+        : {}),
+    }
+  })
   await recordAccess(config, {
     action: "search",
     query: sanitized.query,
@@ -406,12 +435,14 @@ async function lexicalCandidateRows(
     .toArray()) as SearchRow[]
 }
 
-function sourcePathPredicate(
+function searchPredicate(
   includePaths: string[] | undefined,
   excludePaths: string[] | undefined,
+  contextPaths: string[] | undefined,
 ): string | null {
   const includes = normalizePathPrefixes(includePaths)
   const excludes = normalizePathPrefixes(excludePaths)
+  const contexts = normalizeContextPaths(contextPaths)
   const clauses: string[] = []
 
   if (includes.length > 0) {
@@ -420,6 +451,9 @@ function sourcePathPredicate(
   if (excludes.length > 0) {
     clauses.push(`NOT (${excludes.map(pathPrefixPredicate).join(" OR ")})`)
   }
+  if (contexts.length > 0) {
+    clauses.push(`(${contexts.map(contextPathPredicate).join(" OR ")})`)
+  }
   return clauses.length === 0 ? null : clauses.join(" AND ")
 }
 
@@ -438,6 +472,19 @@ function pathPrefixPredicate(prefix: string): string {
   return `(relativePath = ${sqlString(prefix)} OR starts_with(relativePath, ${sqlString(`${prefix}/`)}))`
 }
 
+function normalizeContextPaths(contextPaths: string[] | undefined): string[] {
+  return [...new Set((contextPaths ?? []).map((value) => value.trim()).filter(Boolean))]
+}
+
+function contextPathPredicate(prefix: string): string {
+  return [
+    `contextPath = ${sqlString(prefix)}`,
+    `starts_with(contextPath, ${sqlString(`${prefix} > `)})`,
+    `starts_with(contextPath, ${sqlString(`${prefix}.`)})`,
+    `starts_with(contextPath, ${sqlString(`${prefix}[`)})`,
+  ].join(" OR ")
+}
+
 async function contextChunksByRow(
   table: RowsTable,
   rows: RankedRow[],
@@ -566,6 +613,7 @@ function rankHybridRows(
   lexicalRanked.forEach(([key], index) => {
     lexicalRanks.set(key, index)
   })
+  const lexicalScores = new Map(lexicalRanked)
 
   return rows
     .map((row) => {
@@ -583,7 +631,16 @@ function rankHybridRows(
         lexicalScore = RRF_LEXICAL_WEIGHT / (RRF_K + lexicalRank)
         combinedScore += lexicalScore
       }
-      return { row, vectorScore, lexicalScore, combinedScore }
+      return {
+        row,
+        vectorScore,
+        lexicalScore,
+        combinedScore,
+        vectorRank: vectorRank === undefined ? null : vectorRank + 1,
+        lexicalRank: lexicalRank === undefined ? null : lexicalRank + 1,
+        lexicalBackendScore: lexicalScores.get(key) ?? null,
+        matchedTerms: matchedQueryTerms(queryTokens, row.searchText),
+      }
     })
     .filter((ranked) => ranked.combinedScore > 0)
     .sort((a, b) => {
@@ -601,6 +658,13 @@ function rankHybridRows(
     })
 }
 
+function matchedQueryTerms(queryTokens: string[], text: string): string[] {
+  const textTokens = tokenize(text)
+  return [...new Set(queryTokens)].filter((queryToken) =>
+    textTokens.some((textToken) => tokensAreLexicallyRelated(queryToken, textToken)),
+  )
+}
+
 function mergeRows(vectorRows: SearchRow[], textRows: SearchRow[]): SearchRow[] {
   const rows = new Map<string, SearchRow>()
   for (const row of textRows) {
diff --git a/packages/ragmir-core/src/research.ts b/packages/ragmir-core/src/research.ts
index 4162395..d983a2f 100644
--- a/packages/ragmir-core/src/research.ts
+++ b/packages/ragmir-core/src/research.ts
@@ -98,6 +98,7 @@ export async function research(
         topK: perQueryTopK,
         ...(options.includePaths ? { includePaths: options.includePaths } : {}),
         ...(options.excludePaths ? { excludePaths: options.excludePaths } : {}),
+        ...(options.contextPaths ? { contextPaths: options.contextPaths } : {}),
       }),
     })),
   )
@@ -177,6 +178,7 @@ export function compactSearchResults(
     lineEnd: result.lineEnd,
     pageStart: result.pageStart,
     pageEnd: result.pageEnd,
+    ...(result.score === undefined ? {} : { score: result.score }),
   }))
 }
 
diff --git a/packages/ragmir-core/src/setup.ts b/packages/ragmir-core/src/setup.ts
index f001971..0ea836e 100644
--- a/packages/ragmir-core/src/setup.ts
+++ b/packages/ragmir-core/src/setup.ts
@@ -40,7 +40,7 @@ export interface SetupResult {
 
 const CONFIGURATION_PROMPT = `You are helping configure Ragmir for this repository.
 
-Work from the repository root where \`rgr setup\` was run. Your goal is to improve \`.ragmir/config.json\` so Ragmir indexes useful repository knowledge without indexing secrets, generated files, or noisy bulk data.
+Work from the knowledge-base root where \`rgr setup\` was run. Your goal is to improve \`.ragmir/config.json\` so Ragmir indexes useful repository knowledge without indexing secrets, generated files, or noisy bulk data. In a monorepo with nested Ragmir bases, keep an app base scoped to that app; only the root base should index shared or cross-app knowledge.
 
 Tasks:
 1. Inspect the repository structure and the current \`.ragmir/config.json\`.
diff --git a/packages/ragmir-core/src/skill.test.ts b/packages/ragmir-core/src/skill.test.ts
index 6cb4e33..ccdde96 100644
--- a/packages/ragmir-core/src/skill.test.ts
+++ b/packages/ragmir-core/src/skill.test.ts
@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs"
-import { lstat, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises"
+import { lstat, mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises"
 import os from "node:os"
 import path from "node:path"
 import { afterEach, describe, expect, it } from "vitest"
@@ -24,12 +24,20 @@ describe("installSkill", () => {
     const reportSkill = await readFile(path.join(result.reportSkillPath, "SKILL.md"), "utf8")
     const legalSkill = await readFile(path.join(result.legalSkillPath, "SKILL.md"), "utf8")
     const mcpConfig = JSON.parse(await readFile(result.mcpConfigPath, "utf8")) as {
-      mcpServers: { ragmir: { command: string; args: string[]; cwd: string } }
+      mcpServers: {
+        ragmir: {
+          command: string
+          args: string[]
+          cwd: string
+          env: { RAGMIR_PROJECT_ROOT: string }
+        }
+      }
     }
     const claudeConfig = JSON.parse(await readFile(result.claudeConfigPath, "utf8")) as {
       type: string
       command: string
       args: string[]
+      env: { RAGMIR_PROJECT_ROOT: string }
     }
     const kimiConfig = JSON.parse(await readFile(result.kimiConfigPath, "utf8")) as {
       mcpServers: { ragmir: { env: { RAGMIR_PROJECT_ROOT: string } } }
@@ -57,10 +65,12 @@ describe("installSkill", () => {
     expect(mcpConfig.mcpServers.ragmir.command).toBe("pnpm")
     expect(mcpConfig.mcpServers.ragmir.args).toEqual(["exec", "rgr", "serve-mcp"])
     expect(mcpConfig.mcpServers.ragmir.cwd).toBe(root)
+    expect(mcpConfig.mcpServers.ragmir.env.RAGMIR_PROJECT_ROOT).toBe(root)
     expect(claudeConfig).toEqual({
       type: "stdio",
       command: "pnpm",
       args: ["exec", "rgr", "serve-mcp"],
+      env: { RAGMIR_PROJECT_ROOT: root },
     })
     expect(codexConfig).toContain("[mcp_servers.ragmir]")
     expect(codexConfig).toContain('command = "pnpm"')
@@ -84,6 +94,34 @@ describe("installSkill", () => {
     expect(agentSetup).toContain("Cline")
   })
 
+  it("should generate unique rooted MCP helpers for a nested monorepo base", async () => {
+    const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-skill-monorepo-"))
+    tempDirs.push(root)
+    const app = path.join(root, "apps", "web")
+    await writeRagmirConfig(root)
+    await writeRagmirConfig(app)
+
+    const result = await installSkill({ cwd: app, agents: ["claude", "codex"] })
+    const mcpConfig = JSON.parse(await readFile(result.mcpConfigPath, "utf8")) as {
+      mcpServers: Record<string, { cwd: string; env: { RAGMIR_PROJECT_ROOT: string } }>
+    }
+    const claudeConfig = JSON.parse(await readFile(result.claudeConfigPath, "utf8")) as {
+      env: { RAGMIR_PROJECT_ROOT: string }
+    }
+    const codexConfig = await readFile(result.codexConfigPath, "utf8")
+
+    expect(result.mcpServerName).toBe("ragmir-apps-web")
+    expect(mcpConfig.mcpServers["ragmir-apps-web"]).toEqual(
+      expect.objectContaining({
+        cwd: app,
+        env: { RAGMIR_PROJECT_ROOT: app },
+      }),
+    )
+    expect(claudeConfig.env.RAGMIR_PROJECT_ROOT).toBe(app)
+    expect(codexConfig).toContain("[mcp_servers.ragmir-apps-web]")
+    expect(codexConfig).toContain(`cwd = ${JSON.stringify(app)}`)
+  })
+
   it("adds Ragmir runtime folders to gitignore without duplicating entries", async () => {
     const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-skill-"))
     tempDirs.push(root)
@@ -146,6 +184,7 @@ describe("installSkill", () => {
     const claudeConfig = JSON.parse(await readFile(result.claudeConfigPath, "utf8")) as {
       command: string
       args: string[]
+      env: { RAGMIR_PROJECT_ROOT: string }
     }
     const codexConfig = await readFile(result.codexConfigPath, "utf8")
     const readme = await readFile(result.readmePath, "utf8")
@@ -157,6 +196,7 @@ describe("installSkill", () => {
       type: "stdio",
       command: "./scripts/serve-mcp.sh",
       args: ["--stdio"],
+      env: { RAGMIR_PROJECT_ROOT: root },
     })
     expect(codexConfig).toContain("[mcp_servers.project-docs]")
     expect(codexConfig).toContain('command = "./scripts/serve-mcp.sh"')
@@ -176,6 +216,11 @@ describe("installSkill", () => {
   })
 })
 
+async function writeRagmirConfig(projectRoot: string): Promise<void> {
+  await mkdir(path.join(projectRoot, ".ragmir"), { recursive: true })
+  await writeFile(path.join(projectRoot, ".ragmir", "config.json"), "{}\n", "utf8")
+}
+
 describe("installAgentSkills", () => {
   it("links selected skills into native project-scope agent folders by default", async () => {
     const root = await mkdtemp(path.join(os.tmpdir(), "ragmir-agent-"))
diff --git a/packages/ragmir-core/src/skill.ts b/packages/ragmir-core/src/skill.ts
index 610d12e..412a8e2 100644
--- a/packages/ragmir-core/src/skill.ts
+++ b/packages/ragmir-core/src/skill.ts
@@ -3,6 +3,7 @@ import path from "node:path"
 import { fileURLToPath } from "node:url"
 import { DEFAULT_SKILL_TARGET_DIR, RAGMIR_DIR, RAGMIR_PROJECT_ROOT_ENV } from "./defaults.js"
 import { ensureRagmirGitignore } from "./gitignore.js"
+import { knowledgeBaseIdentity } from "./knowledge-bases.js"
 import { type RagmirCommand, rgrCommand } from "./package-manager.js"
 
 export type AgentTarget = "claude" | "codex" | "kimi" | "opencode" | "cline"
@@ -191,7 +192,7 @@ export async function installSkill(options: InstallSkillOptions = {}): Promise<I
   const targetDir = path.resolve(cwd, options.targetDir ?? DEFAULT_SKILL_TARGET_DIR)
   const agents = options.agents ? parseAgentTargets(options.agents) : [...SUPPORTED_AGENT_TARGETS]
   const agentSet = new Set<AgentTarget>(agents)
-  const mcpServerName = normalizeMcpServerName(options.mcpServerName)
+  const mcpServerName = normalizeMcpServerName(options.mcpServerName ?? suggestedMcpServerName(cwd))
   const skillPath = path.join(targetDir, PRIMARY_SKILL_NAME)
   const audioSkillPath = path.join(targetDir, AUDIO_SKILL_NAME)
   const reportSkillPath = path.join(targetDir, REPORT_SKILL_NAME)
@@ -222,7 +223,11 @@ export async function installSkill(options: InstallSkillOptions = {}): Promise<I
   const installAgentCommand = await rgrCommand(cwd, ["install-agent", "--agents", agents.join(",")])
   await writeFile(
     mcpConfigPath,
-    `${JSON.stringify(mcpConfig(cwd, serveCommand, undefined, mcpServerName), null, 2)}\n`,
+    `${JSON.stringify(
+      mcpConfig(cwd, serveCommand, { [RAGMIR_PROJECT_ROOT_ENV]: cwd }, mcpServerName),
+      null,
+      2,
+    )}\n`,
     "utf8",
   )
 
@@ -413,6 +418,46 @@ function normalizeMcpServerName(value: string | undefined): string {
   return name
 }
 
+function suggestedMcpServerName(cwd: string): string {
+  const identity = knowledgeBaseIdentity(cwd)
+  if (!identity || identity.id === ".") {
+    return DEFAULT_MCP_SERVER_NAME
+  }
+  const suffix = sanitizeMcpServerSuffix(identity.id)
+  return suffix ? `${DEFAULT_MCP_SERVER_NAME}-${suffix}` : DEFAULT_MCP_SERVER_NAME
+}
+
+function sanitizeMcpServerSuffix(value: string): string {
+  let suffix = ""
+  let replacingInvalidRun = false
+
+  for (const character of value.toLowerCase()) {
+    const code = character.charCodeAt(0)
+    const allowed =
+      (code >= 97 && code <= 122) ||
+      (code >= 48 && code <= 57) ||
+      character === "_" ||
+      character === "-"
+    if (allowed) {
+      suffix += character
+      replacingInvalidRun = false
+    } else if (!replacingInvalidRun) {
+      suffix += "-"
+      replacingInvalidRun = true
+    }
+  }
+
+  let start = 0
+  let end = suffix.length
+  while (start < end && suffix[start] === "-") {
+    start += 1
+  }
+  while (end > start && suffix[end - 1] === "-") {
+    end -= 1
+  }
+  return suffix.slice(start, end)
+}
+
 async function writeAgentMcpHelper(
   agent: AgentTarget,
   input: WriteAgentMcpHelperInput,
@@ -421,7 +466,7 @@ async function writeAgentMcpHelper(
     case "claude":
       await writeFile(
         input.claudeConfigPath,
-        `${JSON.stringify(claudeMcpServer(input.serveCommand), null, 2)}\n`,
+        `${JSON.stringify(claudeMcpServer(input.cwd, input.serveCommand), null, 2)}\n`,
         "utf8",
       )
       return
@@ -595,11 +640,12 @@ function mcpConfig(
   return config
 }
 
-function claudeMcpServer(serveCommand: McpCommand): unknown {
+function claudeMcpServer(cwd: string, serveCommand: McpCommand): unknown {
   return {
     type: "stdio",
     command: serveCommand.command,
     args: serveCommand.args,
+    env: { [RAGMIR_PROJECT_ROOT_ENV]: cwd },
   }
 }
 
@@ -697,6 +743,10 @@ ${input.serveCommand}
 
 Use \`ragmir_route_prompt\` when an agent hook or skill needs to decide whether the current user
 prompt should call Ragmir before answering. The router is local and does not store prompt text.`,
+    `This helper is pinned to one knowledge-base root. In a monorepo, keep the generated server name
+\`${input.mcpServerName}\` and generate a separate helper from each nested base. Call
+\`ragmir_status\` and verify \`knowledgeBaseId\` before retrieval when the active base is unclear.`,
+    "Read `ragmir://context` for bounded base identity, readiness, freshness, and capabilities. Read `ragmir://sources` only when source coverage or index drift matters.",
   ]
 
   if (hasAgentHelper(input, "claude")) {
diff --git a/packages/ragmir-core/src/types.ts b/packages/ragmir-core/src/types.ts
index 0be7680..b8ecad7 100644
--- a/packages/ragmir-core/src/types.ts
+++ b/packages/ragmir-core/src/types.ts
@@ -201,6 +201,17 @@ export interface TextChunk {
   mtimeMs: number
 }
 
+export interface ChunkStats {
+  count: number
+  minChars: number
+  averageChars: number
+  p50Chars: number
+  p95Chars: number
+  maxChars: number
+  contextualChunks: number
+  contextualRatio: number
+}
+
 export interface VectorRow extends TextChunk {
   searchText: string
   vector: number[]
@@ -235,12 +246,128 @@ export interface IngestResult {
   errors: Array<{ path: string; message: string }>
 }
 
+export interface PreviewChunksOptions {
+  cwd?: PathLike
+  paths?: string[]
+  maxFiles?: number
+  maxChunksPerFile?: number
+}
+
+export interface PreviewChunk {
+  chunkIndex: number
+  contextPath: string
+  citation: string
+  text: string
+  charStart: number
+  charEnd: number
+  lineStart: number
+  lineEnd: number
+  pageStart: number | null
+  pageEnd: number | null
+}
+
+export interface PreviewFile {
+  source: string
+  relativePath: string
+  extension: string
+  bytes: number
+  parsedChars: number
+  redactions: number
+  chunkStats: ChunkStats
+  chunks: PreviewChunk[]
+  omittedChunks: number
+}
+
+export interface PreviewReport {
+  chunkSize: number
+  chunkOverlap: number
+  requestedPaths: string[]
+  unmatchedPaths: string[]
+  matchedFiles: number
+  omittedFiles: number
+  files: PreviewFile[]
+  errors: Array<{ path: string; message: string }>
+}
+
+export interface KnowledgeBaseIdentity {
+  id: string
+  projectRoot: string
+  workspaceRoot: string
+}
+
+export interface KnowledgeBaseInfo {
+  id: string
+  projectRoot: string
+  configPath: string
+  legacy: boolean
+  active: boolean
+}
+
+export interface KnowledgeBaseInventory {
+  start: string
+  workspaceRoot: string
+  activeProjectRoot: string | null
+  activeId: string | null
+  bases: KnowledgeBaseInfo[]
+}
+
+export interface KnowledgeBaseContextReport {
+  knowledgeBaseId: string | null
+  projectRoot: string
+  privacyProfile: PrivacyProfile
+  retrievalProfile: RetrievalProfile
+  embeddingProvider: EmbeddingProvider
+  ready: boolean
+  coverage: {
+    supportedFiles: number
+    indexedFiles: number
+    chunksIndexed: number
+    missingFromIndex: number
+    staleInIndex: number
+    emptyTextFiles: number
+  }
+  indexFreshness: DoctorReport["indexFreshness"]
+  securityWarningCount: number
+  nextSteps: string[]
+  routing: {
+    selection: "nearest-configured-ancestor"
+    discoverCommand: "rgr bases --json"
+  }
+  tools: string[]
+  resources: string[]
+}
+
+export interface KnowledgeBaseSourceCatalog {
+  knowledgeBaseId: string | null
+  totals: {
+    indexedFiles: number
+    chunks: number
+    missingFromIndex: number
+    staleInIndex: number
+    emptyTextFiles: number
+    skippedFiles: number
+  }
+  indexedFiles: Array<{ source: string; chunks: number }>
+  missingFromIndex: string[]
+  staleInIndex: string[]
+  emptyTextFiles: string[]
+  skippedByReason: Record<string, number>
+  omitted: {
+    indexedFiles: number
+    missingFromIndex: number
+    staleInIndex: number
+    emptyTextFiles: number
+  }
+}
+
 export interface SearchOptions {
   cwd?: PathLike
   topK?: number
   contextRadius?: number
   includePaths?: string[]
   excludePaths?: string[]
+  contextPaths?: string[]
+  explain?: boolean
 }
 
 export interface SearchContextChunk {
@@ -271,6 +398,19 @@ export interface SearchResult {
   pageStart: number | null
   pageEnd: number | null
   context: SearchContextChunk[]
+  score?: SearchScoreExplanation
+}
+
+export interface SearchScoreExplanation {
+  fusion: "rrf"
+  combinedScore: number
+  vectorContribution: number
+  lexicalContribution: number
+  vectorRank: number | null
+  lexicalRank: number | null
+  vectorDistance: number | null
+  lexicalBackendScore: number | null
+  matchedTerms: string[]
 }
 
 export interface ExpandCitationOptions {
@@ -299,6 +439,7 @@ export interface CompactSearchResult {
   lineEnd: number | null
   pageStart: number | null
   pageEnd: number | null
+  score?: SearchScoreExplanation
 }
 
 export interface SourceDuplicateCandidate {
@@ -323,6 +464,7 @@ export interface ResearchOptions {
   includeCode?: boolean
   includePaths?: string[]
   excludePaths?: string[]
+  contextPaths?: string[]
 }
 
 export interface ResearchEvidence {
@@ -379,6 +521,7 @@ export interface GoldenQuery {
   expectedCitations?: string[]
   includePaths?: string[]
   excludePaths?: string[]
+  contextPaths?: string[]
   topK?: number
 }
 
@@ -395,6 +538,7 @@ export interface EvaluationCaseResult {
   expectedPaths: string[]
   includePaths?: string[]
   excludePaths?: string[]
+  contextPaths?: string[]
   topK: number
   returnedPaths: string[]
   returnedCitations: string[]
@@ -447,6 +591,7 @@ export interface AuditReport {
   missingFromIndex: string[]
   staleInIndex: string[]
   totalChunks: number
+  chunkStats: ChunkStats
 }
 
 export interface DestroyIndexResult {
diff --git a/packages/ragmir-landing/messages/en.json b/packages/ragmir-landing/messages/en.json
index 54d3aa5..bdbf673 100644
--- a/packages/ragmir-landing/messages/en.json
+++ b/packages/ragmir-landing/messages/en.json
@@ -143,13 +143,13 @@
   "features_title": "Core retrieval first, optional add-ons when you need output.",
   "features_text": "Ragmir is split deliberately: the core indexes and retrieves cited local context, while optional packages add audio or local chat without turning the retrieval engine into a hosted AI platform.",
   "features_core_title": "Ragmir Core",
-  "features_core_text": "The default package keeps the product focused on local indexing, cited search, MCP, and agent setup.",
-  "features_core_item_1": "Indexes the local sources, raw files, and text extensions selected by the project.",
-  "features_core_item_2": "Returns cited passages with file and chunk references.",
-  "features_core_item_3": "Exposes CLI, TypeScript API, and MCP tools for agents.",
-  "features_core_item_4": "Keeps generated state in git-ignored .ragmir/ folders.",
-  "features_core_item_5": "Runs offline in local-hash mode with no model or API key.",
-  "features_core_item_6": "Prefers embedded PDF text and can run optional local OCR only for blank pages.",
+  "features_core_text": "The default package keeps local retrieval inspectable before indexing, explainable after search, and bounded when agents consume it.",
+  "features_core_item_1": "Previews redacted structured chunks and size distributions without writing an index.",
+  "features_core_item_2": "Explains RRF contributions and retriever ranks, with source and structural-context filters.",
+  "features_core_item_3": "Routes isolated root and app bases in monorepos and exposes bounded MCP context resources.",
+  "features_core_item_4": "Returns verifiable file, chunk, line, and PDF page citations when available.",
+  "features_core_item_5": "Keeps indexes, logs, models, and generated output in git-ignored .ragmir/ folders.",
+  "features_core_item_6": "Runs offline in local-hash mode, with explicit semantic embeddings and local OCR as opt-ins.",
   "features_tts_title": "Ragmir TTS",
   "features_tts_text": "The audio add-on turns cited text into reviewable speech while keeping generated files under local Ragmir state.",
   "features_tts_item_1": "Renders MP3 or WAV summaries from local text.",
diff --git a/packages/ragmir-landing/messages/fr.json b/packages/ragmir-landing/messages/fr.json
index f46c403..94be083 100644
--- a/packages/ragmir-landing/messages/fr.json
+++ b/packages/ragmir-landing/messages/fr.json
@@ -143,13 +143,13 @@
   "features_title": "D'abord le cœur de recherche, puis des modules optionnels pour générer.",
   "features_text": "Ragmir est séparé volontairement : le cœur indexe et récupère du contexte local cité, tandis que les packages optionnels ajoutent l'audio ou le chat local sans transformer le moteur de recherche en plateforme IA hébergée.",
   "features_core_title": "Ragmir Core",
-  "features_core_text": "Le package par défaut reste concentré sur l'indexation locale, la recherche citée, MCP et la configuration des agents.",
-  "features_core_item_1": "Indexe les sources locales, fichiers bruts et extensions texte choisis par le projet.",
-  "features_core_item_2": "Renvoie des passages cités avec références de fichier et de chunk.",
-  "features_core_item_3": "Expose CLI, API TypeScript et outils MCP pour les agents.",
-  "features_core_item_4": "Garde l'état généré dans des dossiers .ragmir/ ignorés par Git.",
-  "features_core_item_5": "Tourne hors-ligne en mode local-hash, sans modèle ni clé API.",
-  "features_core_item_6": "Préfère le texte PDF intégré et peut lancer un OCR local optionnel uniquement sur les pages vides.",
+  "features_core_text": "Le package par défaut rend la recherche locale inspectable avant l'indexation, explicable après la recherche et bornée lorsqu'un agent la consomme.",
+  "features_core_item_1": "Prévisualise les chunks structurés et expurgés ainsi que leurs distributions, sans écrire d'index.",
+  "features_core_item_2": "Explique les contributions RRF et les rangs, avec des filtres de source et de contexte structurel.",
+  "features_core_item_3": "Route des bases racine et applicatives isolées dans les monorepos et expose des ressources MCP bornées.",
+  "features_core_item_4": "Renvoie des citations vérifiables de fichier, chunk, ligne et page PDF lorsqu'elles existent.",
+  "features_core_item_5": "Garde index, journaux, modèles et sorties générées dans des dossiers .ragmir/ ignorés par Git.",
+  "features_core_item_6": "Tourne hors-ligne en mode local-hash, avec embeddings sémantiques et OCR local explicitement optionnels.",
   "features_tts_title": "Ragmir TTS",
   "features_tts_text": "L'add-on audio transforme du texte cité en voix réécoutable tout en gardant les fichiers générés dans l'état local Ragmir.",
   "features_tts_item_1": "Génère des résumés MP3 ou WAV depuis du texte local.",
diff --git a/scripts/smoke.mjs b/scripts/smoke.mjs
index c2178c6..12d08e0 100644
--- a/scripts/smoke.mjs
+++ b/scripts/smoke.mjs
@@ -4,6 +4,7 @@ import {
   chmod,
   cp,
   lstat,
+  mkdir,
   mkdtemp,
   readFile,
   realpath,
@@ -146,6 +147,32 @@ try {
     throw new Error("setup should not create a private directory for new projects")
   }
 
+  const nestedApp = path.join(tempRoot, "apps", "catalog")
+  const nestedSource = path.join(nestedApp, "src")
+  await mkdir(nestedSource, { recursive: true })
+  const nestedSetup = parseJson(
+    (await runKb(["setup", "--no-ingest", "--agents", "claude", "--json"], nestedApp)).stdout,
+    "nested setup JSON",
+  )
+  if (nestedSetup.agentKit?.mcpServerName !== "ragmir-apps-catalog") {
+    throw new Error(
+      `nested setup should generate a unique MCP name, got ${JSON.stringify(nestedSetup)}`,
+    )
+  }
+  const basesJson = parseJson(
+    (await runKb(["bases", "--json"], nestedSource)).stdout,
+    "knowledge bases JSON",
+  )
+  if (
+    basesJson.activeId !== "apps/catalog" ||
+    !Array.isArray(basesJson.bases) ||
+    basesJson.bases.map((base) => base.id).join(",") !== ".,apps/catalog"
+  ) {
+    throw new Error(
+      `bases --json should identify nested monorepo knowledge bases, got ${JSON.stringify(basesJson)}`,
+    )
+  }
+
   const initialDoctor = await runKb(["doctor"], tempRoot)
   assertIncludes(initialDoctor.stdout, "supportedFiles=0", "doctor should ignore generated README")
   assertIncludes(initialDoctor.stdout, "nextSteps:", "doctor should print actionable next steps")
@@ -182,6 +209,28 @@ try {
   await configureProject(tempRoot)
   await writeFixtureDocuments(tempRoot)
 
+  const previewJson = parseJson(
+    (
+      await runKb(
+        ["preview", "--path", ".ragmir/raw/tax.md", "--max-chunks", "1", "--json"],
+        tempRoot,
+      )
+    ).stdout,
+    "preview JSON",
+  )
+  if (
+    previewJson.matchedFiles !== 1 ||
+    previewJson.files?.[0]?.chunks?.[0]?.contextPath !== "Tax situation" ||
+    previewJson.files?.[0]?.chunks?.[0]?.text?.includes("maintainer@example.com")
+  ) {
+    throw new Error(
+      `preview --json should expose redacted structured chunks, got ${JSON.stringify(previewJson)}`,
+    )
+  }
+  if (existsSync(path.join(tempRoot, ".ragmir", "storage", "chunks.lance"))) {
+    throw new Error("preview should not create an index table")
+  }
+
   const fixedDoctor = await runKb(["doctor", "--fix"], tempRoot)
   assertIncludes(fixedDoctor.stdout, "Ragmir repair complete.", "doctor --fix should repair setup")
   assertIncludes(
@@ -202,6 +251,11 @@ try {
   if (typeof statusJson.chunksIndexed !== "number" || statusJson.chunksIndexed <= 0) {
     throw new Error(`status --json should expose chunksIndexed, got ${statusJson.chunksIndexed}`)
   }
+  if (statusJson.knowledgeBaseId !== ".") {
+    throw new Error(
+      `status --json should identify the active root base, got ${statusJson.knowledgeBaseId}`,
+    )
+  }
   if (statusJson.mcpMaxOutputBytes !== 32_768) {
     throw new Error(
       `status --json should expose mcpMaxOutputBytes, got ${statusJson.mcpMaxOutputBytes}`,
@@ -243,7 +297,21 @@ try {
   }
 
   const searchJson = parseJson(
-    (await runKb(["search", "French tax residency", "--top-k", "1", "--json"], tempRoot)).stdout,
+    (
+      await runKb(
+        [
+          "search",
+          "French tax residency",
+          "--top-k",
+          "1",
+          "--context-path",
+          "Tax situation",
+          "--explain",
+          "--json",
+        ],
+        tempRoot,
+      )
+    ).stdout,
     "search JSON",
   )
   if (searchJson.results?.[0]?.relativePath !== ".ragmir/raw/tax.md") {
@@ -254,6 +322,15 @@ try {
       `search --json should expose line-aware citations, got ${JSON.stringify(searchJson)}`,
     )
   }
+  if (
+    searchJson.results?.[0]?.contextPath !== "Tax situation" ||
+    searchJson.results?.[0]?.score?.fusion !== "rrf" ||
+    typeof searchJson.results?.[0]?.score?.combinedScore !== "number"
+  ) {
+    throw new Error(
+      `search --context-path --explain should expose filtered score evidence, got ${JSON.stringify(searchJson)}`,
+    )
+  }
 
   const includedSearchJson = parseJson(
     (
@@ -357,6 +434,7 @@ try {
   const audit = await runKb(["audit"], tempRoot)
   assertIncludes(audit.stdout, "missingFromIndex=0", "audit should find no missing files")
   assertIncludes(audit.stdout, "staleInIndex=0", "audit should find no stale files")
+  assertIncludes(audit.stdout, "chunkStats.p95Chars=", "audit should expose chunk distributions")
   const unsupportedAudit = await runKb(["audit", "--unsupported"], tempRoot)
   assertIncludes(
     unsupportedAudit.stdout,
@@ -433,6 +511,16 @@ try {
     "utf8",
   )
   assertIncludes(skill, "name: ragmir", "install-skill should copy the bundled skill")
+  assertIncludes(
+    skill,
+    "rgr bases --json",
+    "installed skill should route agents to the nearest monorepo base",
+  )
+  assertIncludes(
+    skill,
+    "knowledgeBaseId",
+    "installed skill should verify the active MCP knowledge base",
+  )
   assertIncludes(
     audioSkill,
     "name: ragmir-audio-summary",