init-rag-rat

init-rag-rat — configure a dormant rag-rat repo conversationally

rag-rat's MCP server boots dormant in a repo with no rag-rat.toml: ordinary tools return {"status":"no_index", "remedy":"Run rag-rat init … then restart"}. This skill turns that into a short guided setup. You own the conversation; rag-rat init owns the scan and validation — never hand-write a config blind, and let a real config load re-check it before indexing.

The common path

1. Detect state. You are here because a rag-rat tool returned status: "no_index", or the user asked to set up rag-rat. Confirm there is no rag-rat.toml at (or above) the repo root. If one already exists, this is a reconfigure — send the user to the interactive rag-rat init wizard and stop.

2. Resolve the CLI and use the same form throughout, from the target repo's root. It must match the version the rag-rat MCP server runs, so the index you create is one the server can read — do not use @latest, and don't blindly trust an on-PATH rag-rat:

   • If rag-rat is on PATH, check rag-rat --version and use it only if it matches the plugin/MCP version — a stale global install would build the index with the wrong binary.
   • Otherwise (or on a version mismatch) use npx -y @rag-rat/[email protected] … — the plugin pins @rag-rat/bin to its own version and caches the binary privately, so this is the version-matched CLI; npx runs it in the current directory.

3. Dry-run discovery. <rag-rat> init --yes --dry-run scans the repo and prints the auto-detected config (languages, path bindings, the default local FastEmbed backend) without writing. Read it; tell the user the material bits in a line or two (which languages and directories) — not every commented knob.

4. Default to FastEmbed unless the machine is powerful (or the repo is large). FastEmbed (all-MiniLM, 384-dim, local CPU) needs zero setup and is the right call for most repos on a modest workstation. Recommend it by default. Only raise a remote / GPU embedder when it earns its keep: a large repo, a wish for a stronger code-specific embedder, or an available GPU / cloud budget.

5. Only if a remote embedder makes sense, load the relevant reference and configure it. Start with the overview, then the one that fits — read the file into context on demand; do not inline its content here:

   • references/remote-embeddings.md — the [llm.embedding.remote] block, the local↔remote model pairing table, dim parity, and which of the two paths below to take.
   • references/local-infinity.md — run a local infinity server via Docker (Connect mode); the recommended default model + the CPU engine footgun.
   • references/ephemeral-providers.md — provision an ephemeral Modal/RunPod GPU worker (cookbook); GPU classes, the cost/trust boundary, and the local+cloud hybrid.

6. Preview and confirm. Pick the path and confirm with the user before writing anything. Neither installs git hooks — that's a separate, consented step (step 7).

   • FastEmbed (default): <rag-rat> init --yes --no-hooks writes rag-rat.toml, installs the model, and builds the initial index and embeddings in one step. --no-hooks is what keeps hook install a separate ask — plain init --yes would install the git hooks immediately. Preview first with <rag-rat> init --yes --dry-run if the user wants to see the config. No hand-editing, and no separate index/reconcile step for this path.
   • Custom remote backend: take the base from <rag-rat> init --yes --dry-run (which writes nothing), add the [llm.embedding.remote] block from step 5, show the final config, and write rag-rat.toml only after the user confirms.

7. Index + embed (custom path only), decide on the git hooks, then restart.

   • FastEmbed: step 6 already indexed and embedded — do not re-run.
   • Custom remote backend: validate the written config by loading it — <rag-rat> doctor fails loudly on a bad block (dim mismatch, gpu with endpoint, missing query_endpoint, …). Then run two commands, in order:
     1. <rag-rat> index --discover — builds the source/chunk rows. This does not compute embeddings.
     2. <rag-rat> reconcile — the embedding backfill: it computes the vectors over the configured remote backend (provisioning the ephemeral box if the config uses cookbook). Skip it and the repo has no semantic-search vectors until a later maintenance pass — always run it before declaring setup complete.
   • Git maintenance hooks — ask, then install. rag-rat can install managed post-checkout / post-merge / post-rewrite / post-commit hooks that keep the index fresh as the repo changes. They modify .git/hooks, so ask the user — nothing above installed them (the FastEmbed path ran with --no-hooks). If they agree: <rag-rat> hooks install — idempotent, and it never clobbers a foreign hook (if a non-rag-rat hook occupies a slot it errors "move it aside or merge manually"; surface that and move on). If they decline, or it isn't a git worktree, skip it — nothing to undo.
   • Then restart the rag-rat MCP server in the agent. A dormant server does not self-activate (that would be a half-active server without the watcher and hook listener). After restart it discovers rag-rat.toml, starts fully active, and ordinary tools work against the new index.

Guardrails

• Default to FastEmbed. Don't push a remote backend onto a small repo or a modest machine.
• localhost-only for any local embedder — never bind it to a public interface.
• Same model + dim everywhere. Mixing embedding models or dims across local and ephemeral corrupts the vector space; [llm.embedding] model must be a registry model whose dim matches what the server returns. A mismatch is rejected at load.
• Cost + trust. Never start a cookbook / ephemeral (cloud) run without explicit go-ahead — it spends money and runs third-party provisioning code with the user's cloud credentials.
• Never write config blind. Always go through init --yes --dry-run for the base and a real load (doctor / index) for validation.
• Keep the machine-global database. Never add an [index] database key — the keyless config init produces resolves to the global store, which is what lets the index and memories survive a git clean or a deleted checkout. A per-repo database path is the deprecated, un-consolidated deployment (it never syncs); do not introduce one.