feat(core): add repository-aware guided setup

AGENTS.md

@@ -41,6 +41,8 @@
 - The root `README.md` is the short canonical entrypoint: what Ragmir is, installation, first use, library API, MCP, and links to focused docs.
 - 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 the English setup prompt identical across Core, the landing, root and package READMEs,
+  `docs/quick-start.md`, and the wiki. The public-surface smoke test enforces repository copies.
 - 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.
 - Lead public documentation with the value proposition, a working quick start, and the strongest

CLAUDE.md

@@ -26,6 +26,8 @@ commit them. The root README is the canonical documentation entrypoint; keep pac
 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.
+Keep the English setup prompt identical across Core, the landing, root and package READMEs,
+`docs/quick-start.md`, and the wiki. The public-surface smoke test enforces repository copies.
 Lead public documentation with the value proposition, a working quick start, and the strongest
 guarantees. Move operational depth to focused guides instead of repeating it across READMEs.
 Present team use as a positive workflow: shared sources and configuration, one local ingest per

README.md

@@ -20,7 +20,53 @@ typed TypeScript API, or keep the complete workflow local with the optional Chat
 
 ## Start in 60 seconds
 
-Ragmir requires Node.js 22 or later. Install it in the project that owns the files to search:
+The fastest path is to let your coding agent inspect the repository and tailor the setup.
+
+<!-- ragmir-setup-prompt:start -->
+<details>
+<summary><strong>Option 1: paste this into your coding agent</strong></summary>
+
+~~~text
+Set up Ragmir in this repository. Work interactively: inspect first, ask one concise numbered batch of questions, wait for my answers, then execute. Never assume consent for dependency changes, model downloads, replacing skills, or sharing data.
+
+Outcome: Core installed with the repository's package manager; useful sources selected; secrets and generated noise excluded; tools connected; cited retrieval verified. Semantic retrieval, team features, Chat, and TTS are optional.
+
+1. Inspect without changes:
+- Find the repository or monorepo root. Read package.json packageManager, lockfiles, workspace and Node/version-manager files, .gitignore, existing .ragmir state, README, AGENTS/CLAUDE/CODEX guidance, docs, specs/ADRs, apps/packages, important config, source, and tests.
+- Detect Node 22+ and pnpm, npm, Yarn, or Bun. Prefer packageManager, then the lockfile. Respect workspace-root flags and mise/asdf/Volta. Never create a second lockfile. If signals conflict, ask.
+- If Ragmir exists, inspect its version, config, status, sources, and rgr upgrade --check before changing it.
+
+2. Ask only what the repository did not answer, then wait:
+1) Which repository/monorepo base should own the knowledge base, and are nested app bases wanted?
+2) Which clients: Claude Code, Codex, Kimi, OpenCode, Cline, another MCP client, or none?
+3) Keep default offline local-hash, or allow one semantic-model download for better natural-language retrieval?
+4) Solo or team use? If team, what Git/Drive/folder revision is authoritative and who may receive metadata-only snapshots?
+5) Core only, or optional Chat? For Chat choose lite (~0.49 GB), fast (~3.35 GB), or quality (~5.15 GB).
+6) Optional TTS? Ask language (en/fr/es offline; ja/th/zh require explicit Edge unless a local model is supplied) and whether text may reach Edge.
+7) Which private/external folders are allowed, which must never be indexed, and may I install packages, edit local config, and run approved downloads now?
+
+3. Implement after approval:
+- Install @jcode.labs/ragmir as a dev dependency with the detected manager. Install Chat/TTS only if selected, at a compatible version.
+- Run the matching rgr setup --no-ingest --agents <selected> command. Keep project scope. If a same-name skill is unmanaged, show the diff and ask before --force.
+- Build a narrow .ragmir/config.json. Prefer stable relative globs for root guidance, docs/specs/ADRs, package READMEs/manifests, useful app config, and source/tests that explain behavior. Include locales only when useful.
+- Exclude .env*, credentials, keys, unapproved dumps/customer data, dependencies, generated/build/cache/coverage/log folders, vendored code, binaries/media, and .ragmir storage/models. In monorepos, keep nested bases scoped and shared knowledge at root.
+- Run preview and audit --unsupported before ingest. Review redactions, unsupported/oversized files, duplicates, chunks, and sensitive paths. Fix config first, then ingest.
+- For an existing install, use rgr upgrade and doctor --fix as indicated. Never delete the active index first. Rebuild only for incompatible embedding, chunk, or index-policy changes.
+- Enable semantic retrieval, preload Chat, or preload TTS only after consent. Use non-sensitive TTS preload text.
+- For teams, ingest locally, create an ignored metadata-only snapshot, compare it, explain every drift, and never choose authority automatically.
+
+4. Prove the result:
+- Run rgr doctor --deep, rgr audit --unsupported, and rgr security-audit.
+- Run representative searches with citations and --explain. Create a small local golden suite for project questions and run rgr evaluate; do not weaken gates to pass.
+- Report detected tools, answers, packages, downloads, config/sources/exclusions, changed files, readiness, retrieval results, team status, and exact remaining actions.
+
+Never commit .ragmir, corpus files, models, snapshots, logs, or secrets. Never claim offline, semantic, team synchronization, or retrieval quality without evidence.
+~~~
+
+</details>
+<!-- ragmir-setup-prompt:end -->
+
+Prefer manual setup? Ragmir requires Node.js 22 or later. Install it in the project that owns the files to search:
 
 ```bash
 pnpm add -D @jcode.labs/ragmir
@@ -244,6 +290,7 @@ Installing Core does not install Chat or TTS.
 
 | Resource | Use it for |
 | --- | --- |
+| [Quick start](./docs/quick-start.md) | Agent-guided or manual repository setup |
 | [Confidential local RAG demo](./packages/ragmir-core/examples/sovereign-rag-demo/README.md) | Complete fictional CLI workflow |
 | [Library API demo](./packages/ragmir-core/examples/library-api-demo/README.md) | Persistent TypeScript client pattern |
 | [Document evidence benchmark](./packages/ragmir-core/examples/document-evidence-benchmark/README.md) | Exact path, line, chunk, and PDF-page expectations |

context7.json

@@ -19,6 +19,7 @@
   ],
   "excludeFiles": ["CHANGELOG.md", "pnpm-lock.yaml"],
   "rules": [
+    "Use the canonical English setup prompt in docs/quick-start.md for a repository-aware installation; it detects the package manager and existing state, asks before changes or downloads, and verifies retrieval.",
     "Ragmir Core returns cited retrieval context only; it does not synthesize answers itself.",
     "Any compatible coding agent, script, CLI, TypeScript application, or MCP client can consume Core results; use a local consumer when no passage may leave the machine.",
     "Use one `createRagmirClient()` per project root for repeated work in a stateful Node.js process; it caches one immutable read snapshot until atomic generation replacement and flushes metadata-only access logs during close. Use top-level functions for one-shot scripts.",

docs/agent-integration.md

@@ -4,6 +4,10 @@ Ragmir indexes the selected project files locally and gives the AI or automation
 passages through CLI or one stdio MCP server. The default `local-hash` path keeps ingestion and
 retrieval offline. Core is model-agnostic, never uploads the corpus, and never calls a model itself.
 
+For an interactive repository-aware installation, paste the canonical prompt from the
+[quick-start guide](./quick-start.md) into the coding agent. It detects the package manager and
+existing Ragmir state, asks one approval batch, then configures and verifies the selected clients.
+
 Choose the handoff that matches the corpus:
 
 | Path | What stays local | What crosses the boundary |

docs/cli-reference.md

@@ -5,6 +5,9 @@ are the source of truth for option details.
 
 ## First use
 
+Use the [agent-guided quick start](./quick-start.md) when the setup should adapt to the repository,
+package manager, existing installation, team workflow, and optional Chat or TTS choices.
+
 ```bash
 rgr setup
 rgr ingest

docs/quick-start.md

@@ -0,0 +1,77 @@
+# Quick start
+
+Ragmir requires Node.js 22 or later. Choose the guided setup for a repository-aware installation,
+or use the manual commands below.
+
+<!-- ragmir-setup-prompt:start -->
+<details>
+<summary><strong>Option 1: paste this into your coding agent</strong></summary>
+
+~~~text
+Set up Ragmir in this repository. Work interactively: inspect first, ask one concise numbered batch of questions, wait for my answers, then execute. Never assume consent for dependency changes, model downloads, replacing skills, or sharing data.
+
+Outcome: Core installed with the repository's package manager; useful sources selected; secrets and generated noise excluded; tools connected; cited retrieval verified. Semantic retrieval, team features, Chat, and TTS are optional.
+
+1. Inspect without changes:
+- Find the repository or monorepo root. Read package.json packageManager, lockfiles, workspace and Node/version-manager files, .gitignore, existing .ragmir state, README, AGENTS/CLAUDE/CODEX guidance, docs, specs/ADRs, apps/packages, important config, source, and tests.
+- Detect Node 22+ and pnpm, npm, Yarn, or Bun. Prefer packageManager, then the lockfile. Respect workspace-root flags and mise/asdf/Volta. Never create a second lockfile. If signals conflict, ask.
+- If Ragmir exists, inspect its version, config, status, sources, and rgr upgrade --check before changing it.
+
+2. Ask only what the repository did not answer, then wait:
+1) Which repository/monorepo base should own the knowledge base, and are nested app bases wanted?
+2) Which clients: Claude Code, Codex, Kimi, OpenCode, Cline, another MCP client, or none?
+3) Keep default offline local-hash, or allow one semantic-model download for better natural-language retrieval?
+4) Solo or team use? If team, what Git/Drive/folder revision is authoritative and who may receive metadata-only snapshots?
+5) Core only, or optional Chat? For Chat choose lite (~0.49 GB), fast (~3.35 GB), or quality (~5.15 GB).
+6) Optional TTS? Ask language (en/fr/es offline; ja/th/zh require explicit Edge unless a local model is supplied) and whether text may reach Edge.
+7) Which private/external folders are allowed, which must never be indexed, and may I install packages, edit local config, and run approved downloads now?
+
+3. Implement after approval:
+- Install @jcode.labs/ragmir as a dev dependency with the detected manager. Install Chat/TTS only if selected, at a compatible version.
+- Run the matching rgr setup --no-ingest --agents <selected> command. Keep project scope. If a same-name skill is unmanaged, show the diff and ask before --force.
+- Build a narrow .ragmir/config.json. Prefer stable relative globs for root guidance, docs/specs/ADRs, package READMEs/manifests, useful app config, and source/tests that explain behavior. Include locales only when useful.
+- Exclude .env*, credentials, keys, unapproved dumps/customer data, dependencies, generated/build/cache/coverage/log folders, vendored code, binaries/media, and .ragmir storage/models. In monorepos, keep nested bases scoped and shared knowledge at root.
+- Run preview and audit --unsupported before ingest. Review redactions, unsupported/oversized files, duplicates, chunks, and sensitive paths. Fix config first, then ingest.
+- For an existing install, use rgr upgrade and doctor --fix as indicated. Never delete the active index first. Rebuild only for incompatible embedding, chunk, or index-policy changes.
+- Enable semantic retrieval, preload Chat, or preload TTS only after consent. Use non-sensitive TTS preload text.
+- For teams, ingest locally, create an ignored metadata-only snapshot, compare it, explain every drift, and never choose authority automatically.
+
+4. Prove the result:
+- Run rgr doctor --deep, rgr audit --unsupported, and rgr security-audit.
+- Run representative searches with citations and --explain. Create a small local golden suite for project questions and run rgr evaluate; do not weaken gates to pass.
+- Report detected tools, answers, packages, downloads, config/sources/exclusions, changed files, readiness, retrieval results, team status, and exact remaining actions.
+
+Never commit .ragmir, corpus files, models, snapshots, logs, or secrets. Never claim offline, semantic, team synchronization, or retrieval quality without evidence.
+~~~
+
+</details>
+<!-- ragmir-setup-prompt:end -->
+
+The agent must inspect first, ask once, and wait for approval before it installs dependencies,
+downloads models, replaces skills, or shares metadata.
+
+## Manual setup
+
+Install Core in the project that owns the files:
+
+~~~bash
+pnpm add -D @jcode.labs/ragmir
+pnpm exec rgr setup --agents codex,claude,kimi,opencode,cline
+pnpm exec rgr sources add "README.md" "docs/**/*.md"
+pnpm exec rgr ingest
+pnpm exec rgr search "Which decision changed the rollout?"
+~~~
+
+Use the package manager already declared by the project. Ragmir detects pnpm, npm, Yarn, and Bun.
+At a pnpm workspace root, add the workspace-root flag. Never create a second lockfile.
+
+Generated configuration, indexes, helpers, reports, and metadata-only logs stay under ignored
+`.ragmir/` state. Run `rgr doctor --deep`, `rgr audit --unsupported`, and
+`rgr security-audit` before relying on retrieval.
+
+For an existing installation, update the package, run `rgr upgrade --check`, then run `rgr upgrade`
+when requested. Ragmir preserves the active index until a validated replacement is ready.
+
+Next: [CLI reference](./cli-reference.md), [configuration](./configuration.md),
+[agent integration](./agent-integration.md), [Chat](./offline-chat-preload.md), and
+[TTS](./offline-tts-preload.md).

llms.txt

@@ -8,6 +8,8 @@ the corpus, and calls no model.
 ## Core facts
 
 - Install: `pnpm add -D @jcode.labs/ragmir`
+- Agent-guided setup: use the canonical English prompt in
+  https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/docs/quick-start.md
 - First use: `pnpm exec rgr setup && pnpm exec rgr ingest`
 - Resumable ingestion: `rgr ingest` commits 25 files per durable batch by default. Re-run it after an
   interruption, inspect progress with `rgr status --json`, and use `--batch-size` to change the
@@ -87,6 +89,7 @@ the corpus, and calls no model.
 ## Documentation
 
 - [Documentation wiki](https://github.com/jcode-works/jcode-ragmir/wiki)
+- [Quick start](https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/docs/quick-start.md)
 - [README](https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/README.md)
 - [CLI reference](https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/docs/cli-reference.md)
 - [API reference](https://raw.githubusercontent.com/jcode-works/jcode-ragmir/main/docs/api-reference.md)

packages/ragmir-chat/README.md

@@ -17,6 +17,52 @@ not discover or index project files.
 
 Requires Node.js 22 or later and enough disk and memory for the selected model.
 
+<!-- ragmir-setup-prompt:start -->
+<details>
+<summary><strong>Option 1: paste this into your coding agent</strong></summary>
+
+~~~text
+Set up Ragmir in this repository. Work interactively: inspect first, ask one concise numbered batch of questions, wait for my answers, then execute. Never assume consent for dependency changes, model downloads, replacing skills, or sharing data.
+
+Outcome: Core installed with the repository's package manager; useful sources selected; secrets and generated noise excluded; tools connected; cited retrieval verified. Semantic retrieval, team features, Chat, and TTS are optional.
+
+1. Inspect without changes:
+- Find the repository or monorepo root. Read package.json packageManager, lockfiles, workspace and Node/version-manager files, .gitignore, existing .ragmir state, README, AGENTS/CLAUDE/CODEX guidance, docs, specs/ADRs, apps/packages, important config, source, and tests.
+- Detect Node 22+ and pnpm, npm, Yarn, or Bun. Prefer packageManager, then the lockfile. Respect workspace-root flags and mise/asdf/Volta. Never create a second lockfile. If signals conflict, ask.
+- If Ragmir exists, inspect its version, config, status, sources, and rgr upgrade --check before changing it.
+
+2. Ask only what the repository did not answer, then wait:
+1) Which repository/monorepo base should own the knowledge base, and are nested app bases wanted?
+2) Which clients: Claude Code, Codex, Kimi, OpenCode, Cline, another MCP client, or none?
+3) Keep default offline local-hash, or allow one semantic-model download for better natural-language retrieval?
+4) Solo or team use? If team, what Git/Drive/folder revision is authoritative and who may receive metadata-only snapshots?
+5) Core only, or optional Chat? For Chat choose lite (~0.49 GB), fast (~3.35 GB), or quality (~5.15 GB).
+6) Optional TTS? Ask language (en/fr/es offline; ja/th/zh require explicit Edge unless a local model is supplied) and whether text may reach Edge.
+7) Which private/external folders are allowed, which must never be indexed, and may I install packages, edit local config, and run approved downloads now?
+
+3. Implement after approval:
+- Install @jcode.labs/ragmir as a dev dependency with the detected manager. Install Chat/TTS only if selected, at a compatible version.
+- Run the matching rgr setup --no-ingest --agents <selected> command. Keep project scope. If a same-name skill is unmanaged, show the diff and ask before --force.
+- Build a narrow .ragmir/config.json. Prefer stable relative globs for root guidance, docs/specs/ADRs, package READMEs/manifests, useful app config, and source/tests that explain behavior. Include locales only when useful.
+- Exclude .env*, credentials, keys, unapproved dumps/customer data, dependencies, generated/build/cache/coverage/log folders, vendored code, binaries/media, and .ragmir storage/models. In monorepos, keep nested bases scoped and shared knowledge at root.
+- Run preview and audit --unsupported before ingest. Review redactions, unsupported/oversized files, duplicates, chunks, and sensitive paths. Fix config first, then ingest.
+- For an existing install, use rgr upgrade and doctor --fix as indicated. Never delete the active index first. Rebuild only for incompatible embedding, chunk, or index-policy changes.
+- Enable semantic retrieval, preload Chat, or preload TTS only after consent. Use non-sensitive TTS preload text.
+- For teams, ingest locally, create an ignored metadata-only snapshot, compare it, explain every drift, and never choose authority automatically.
+
+4. Prove the result:
+- Run rgr doctor --deep, rgr audit --unsupported, and rgr security-audit.
+- Run representative searches with citations and --explain. Create a small local golden suite for project questions and run rgr evaluate; do not weaken gates to pass.
+- Report detected tools, answers, packages, downloads, config/sources/exclusions, changed files, readiness, retrieval results, team status, and exact remaining actions.
+
+Never commit .ragmir, corpus files, models, snapshots, logs, or secrets. Never claim offline, semantic, team synchronization, or retrieval quality without evidence.
+~~~
+
+</details>
+<!-- ragmir-setup-prompt:end -->
+
+Prefer manual setup:
+
 ```bash
 npm install --save-dev @jcode.labs/ragmir @jcode.labs/ragmir-chat
 npx rgr setup