init-rag-rat git:20260923.7774461A

Immutable. This exact content is served forever at /api/v1/blob/41f5b201ff2f1cb2.

---
name: init-rag-rat
description: >
  Use to set up rag-rat in a repository that is not indexed yet — when the rag-rat MCP server is
  DORMANT (its tools return {"status":"no_index"} with a "Run rag-rat init … then restart" remedy),
  or when the user asks to initialize / configure / "set up rag-rat" / "index this repo" / choose an
  embedding backend. Drives the setup conversationally: scans the repo, explains only the material
  choices, recommends the local FastEmbed default for a modest machine, and — only when a remote /
  GPU embedder is worth it — loads a reference for local infinity (Docker) or an ephemeral
  Modal/RunPod worker, then previews the config, writes it after confirmation, runs the first index,
  offers to set up the git maintenance hooks (asks before touching `.git/hooks`), and tells the user
  to restart the MCP server. Triggers: "set up rag-rat", "rag-rat is dormant",
  "no rag-rat.toml", "index this repo", "configure rag-rat embeddings".
---

# 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. With
     the plugin, `~/.local/bin/rag-rat` is its version-matched binary (the MCP server links it when
     it starts), so try that path too if `rag-rat` alone is not found.
   - Otherwise (or on a version mismatch) use `npx -y @rag-rat/bin@0.23.2 …` — 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. It downloads the model and indexes and
     embeds the whole repo, so on anything but a small repo **run it in the background** (or with
     your longest command timeout) and poll until it exits — a foreground call can time out partway.
     Its closing "connect your coding agent … `claude mcp add` / `codex mcp add`" hint is for users
     **without** the plugin: **do not run those commands** — the plugin already registered the
     server, and a second registration runs two servers against one index.
   - **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 **all or nothing**: if a hook rag-rat does not manage occupies any slot, it installs none and
     names each one. Tell the user which hooks are in the way and that they can move them aside and
     re-run `hooks install`; don't leave them thinking the index will stay fresh. 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 — in Claude Code the user runs `/mcp` and
     reconnects `rag-rat`; in Codex and opencode, a new session. 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.