diff --git a/AGENTS.md b/AGENTS.md index 8a4efc3..8ea7f6e 100644 --- a/AGENTS.md +++ b/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 diff --git a/CLAUDE.md b/CLAUDE.md index 058ba85..09b293d 100644 --- a/CLAUDE.md +++ b/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 diff --git a/README.md b/README.md index 889eb01..e25c9c9 100644 --- a/README.md +++ b/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. + + +
+Option 1: paste this into your coding agent + +~~~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 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. +~~~ + +
+ + +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 | diff --git a/context7.json b/context7.json index 3f5fff9..2a48a70 100644 --- a/context7.json +++ b/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.", diff --git a/docs/agent-integration.md b/docs/agent-integration.md index 408cb39..04c3ae9 100644 --- a/docs/agent-integration.md +++ b/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 | diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 8717813..6f1bc25 100644 --- a/docs/cli-reference.md +++ b/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 diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 0000000..cebaa1f --- /dev/null +++ b/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. + + +
+Option 1: paste this into your coding agent + +~~~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 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. +~~~ + +
+ + +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). diff --git a/llms.txt b/llms.txt index e0d3084..7a73490 100644 --- a/llms.txt +++ b/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) diff --git a/packages/ragmir-chat/README.md b/packages/ragmir-chat/README.md index 2cd45a7..e9efa95 100644 --- a/packages/ragmir-chat/README.md +++ b/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. + +
+Option 1: paste this into your coding agent + +~~~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 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. +~~~ + +
+ + +Prefer manual setup: + ```bash npm install --save-dev @jcode.labs/ragmir @jcode.labs/ragmir-chat npx rgr setup diff --git a/packages/ragmir-core/README.md b/packages/ragmir-core/README.md index 5f1d668..2d0b8eb 100644 --- a/packages/ragmir-core/README.md +++ b/packages/ragmir-core/README.md @@ -18,6 +18,52 @@ LLM, and opens no HTTP port. Requires Node.js 22 or later. + +
+Option 1: paste this into your coding agent + +~~~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 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. +~~~ + +
+ + +Prefer manual setup: + ```bash npm install --save-dev @jcode.labs/ragmir npx rgr setup --agents codex,claude,kimi,opencode,cline diff --git a/packages/ragmir-core/src/index.ts b/packages/ragmir-core/src/index.ts index ca9308b..e39e774 100644 --- a/packages/ragmir-core/src/index.ts +++ b/packages/ragmir-core/src/index.ts @@ -59,6 +59,7 @@ export type { EnableSemanticEmbeddingsResult } from "./semantic-config.js" export { enableSemanticEmbeddings } from "./semantic-config.js" export type { SetupOptions, SetupResult, SetupSemanticResult } from "./setup.js" export { setupProject } from "./setup.js" +export { RAGMIR_SETUP_PROMPT } from "./setup-prompt.js" export type { AgentHelperFile, AgentInstallMode, diff --git a/packages/ragmir-core/src/setup-prompt.ts b/packages/ragmir-core/src/setup-prompt.ts new file mode 100644 index 0000000..cf105c8 --- /dev/null +++ b/packages/ragmir-core/src/setup-prompt.ts @@ -0,0 +1,34 @@ +export const RAGMIR_SETUP_PROMPT = `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 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.` diff --git a/packages/ragmir-core/src/setup.test.ts b/packages/ragmir-core/src/setup.test.ts index f54c836..6261d6e 100644 --- a/packages/ragmir-core/src/setup.test.ts +++ b/packages/ragmir-core/src/setup.test.ts @@ -33,9 +33,12 @@ describe("setupProject", () => { expect(result.doctor.agentKitInstalled).toBe(true) expect(result.semantic).toBeNull() expect(result.ingested).toBeNull() - expect(result.configurationPrompt).toContain("You are helping configure Ragmir") - expect(result.configurationPrompt).toContain("rgr sources add") - expect(result.configurationPrompt).toContain("Do not add every locale by default") + expect(result.configurationPrompt).toContain("Set up Ragmir in this repository") + expect(result.configurationPrompt).toContain("ask one concise numbered batch of questions") + expect(result.configurationPrompt).toContain("Core only, or optional Chat") + expect(result.configurationPrompt).toContain("Optional TTS") + expect(result.configurationPrompt).toContain("rgr upgrade --check") + expect(result.configurationPrompt.length).toBeLessThanOrEqual(4_000) expect(mcpConfig.mcpServers.ragmir.command).toBe("node") expect(mcpConfig.mcpServers.ragmir.args).toEqual([result.agentKit.runnerPath, "serve-mcp"]) expect(result.agentInstallations.map((installation) => installation.agent)).toEqual([ diff --git a/packages/ragmir-core/src/setup.ts b/packages/ragmir-core/src/setup.ts index b49c572..df51ba3 100644 --- a/packages/ragmir-core/src/setup.ts +++ b/packages/ragmir-core/src/setup.ts @@ -6,6 +6,7 @@ import { ingest } from "./ingest.js" import { initProject } from "./init.js" import { type PackageManager, rgrCommand } from "./package-manager.js" import { type EnableSemanticEmbeddingsResult, enableSemanticEmbeddings } from "./semantic-config.js" +import { RAGMIR_SETUP_PROMPT } from "./setup-prompt.js" import { type AgentSkillInstallation, type AgentTarget, @@ -46,21 +47,6 @@ export interface SetupResult { configurationPrompt: string } -const CONFIGURATION_PROMPT = `You are helping configure Ragmir for this repository. - -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\`. -2. Add concise \`sources\` entries for durable knowledge: root README files, AGENTS/CLAUDE/CODEX guidance, CONTRIBUTING/CHANGELOG files, docs, specs, architecture notes, package README files, app/package metadata, and important project configuration. -3. Include translation or locale files only when they help explain product behavior. Prefer English first; if the project primarily uses another language, include that language too. Do not add every locale by default. -4. Exclude generated output, dependency folders, build caches, coverage, logs, vendored code, binaries, screenshots/media dumps, \`.env*\`, credentials, private keys, raw customer data, and \`.ragmir/storage\` or \`.ragmir/models\`. -5. Prefer stable globs over long file lists, but keep the set narrow enough that \`rgr audit\` remains readable. -6. If you can edit files, update the \`sources\` array in \`.ragmir/config.json\`. If you are read-only, return exact \`rgr sources add ...\` commands instead. -7. If you can execute commands, run \`rgr audit --unsupported\` and \`rgr doctor --fix\`, then report what you added, what you deliberately excluded, and any skipped files Ragmir reported. - -Keep all proposed paths relative to the repository root. Do not add secrets or private documents to Git.` - export async function setupProject(options: SetupOptions = {}): Promise { const cwd = path.resolve(options.cwd ?? process.cwd()) const created = await initProject(cwd) @@ -107,7 +93,7 @@ export async function setupProject(options: SetupOptions = {}): Promise void handleCopy()} + type="button" + > + {copied ? ( +