specrails-desktop 2.8.0 → 2.9.0

package/docs/gemini.md

@@ -1,106 +1,258 @@
 # Using Specrails with the Gemini CLI
 
-Specrails supports Google's [Gemini CLI](https://github.com/google-gemini/gemini-cli)
-as a third AI provider alongside Claude Code and the Codex CLI.
-
-> **Beta — opt-in.** Gemini is gated behind `SPECRAILS_GEMINI_BETA` and is **off by
-> default**. Until you set it, Gemini is invisible everywhere (it won't show in Add
-> Project and can't be selected). See [Enabling the beta](#enabling-the-beta).
->
-> **Scope today.** With the beta on, Gemini powers the *non-pipeline* surfaces —
-> Explore Spec, Quick spec, AI Edit, the terminal launcher, and cost analytics.
-> The full **rails pipeline** (`/specrails:implement`, `batch-implement`) needs a
-> Gemini artifact target in `specrails-core` (`.gemini/commands/*.toml` +
-> `.gemini/agents/sr-*.md`), which ships separately. Rails are hidden for Gemini
-> projects until then.
+Specrails supports **three AI providers**: Anthropic's
+[Claude Code](https://claude.com/claude-code), OpenAI's
+[Codex CLI](https://developers.openai.com/codex), and Google's
+[Gemini CLI](https://github.com/google-gemini/gemini-cli). You pick one,
+two, or all three when you add a project, and the rest of the app behaves
+the same across them.
 
-## Prerequisites
+> **Gemini is enabled by default** (parity with Claude and Codex). It shows
+> up in **Add Project** and is selectable whenever the `gemini` CLI is on
+> your `PATH`. To disable it as an emergency rollback, set
+> `SPECRAILS_GEMINI_BETA=0` in the app's environment — only the exact string
+> `0` disables it; `1`, `true`, and unset all mean **enabled**. (Unlike
+> Codex, there is no legacy `SPECRAILS_HUB_*` fallback name.)
 
-- **Gemini CLI ≥ 0.11.0** on your `PATH` (`npm i -g @google/gemini-cli`; `gemini --version`).
-  Older versions lack `--output-format stream-json` and headless `--resume`.
-- **A Gemini API key.** Specrails spawns Gemini headlessly, so it needs
-  non-interactive auth: set `GEMINI_API_KEY` (a paid Gemini Developer API key from
-  [Google AI Studio](https://aistudio.google.com/apikey)). The free OAuth
-  "Login with Google" tier exists but is being wound down for the CLI and is not a
-  reliable unattended path — use an API key.
+**What works with Gemini:** Explore Spec, Quick spec, AI Edit, the terminal
+"Open AI CLI" launcher, cost analytics, **and the full rails pipeline**
+(`/specrails:implement`, `batch-implement`). The one exception is
+**Ultracode rails**, which remain Claude-only.
 
-## Enabling the beta
+## Prerequisites
 
-Set the env var where the Specrails server runs, then restart the app:
+| What | Why | How |
+|---|---|---|
+| `gemini` CLI ≥ 0.11.0 | Earlier versions lack `--output-format stream-json` + headless `--resume`, which the app relies on | `npm i -g @google/gemini-cli` · check with `gemini --version` |
+| A Gemini API key | The app spawns Gemini headlessly, so it needs non-interactive auth | Set `GEMINI_API_KEY` to a paid Gemini Developer API key from [Google AI Studio](https://aistudio.google.com/apikey) |
+| `specrails-core` ≥ 4.8.0 in the project | 4.8.0 ships the Gemini provider target (`.gemini/` commands + agents) that the rails pipeline needs | The Add-Project install flow uses `specrails-core@^4.8.0` automatically |
+| `git`, `node`, `npm`, `npx` | Same as Claude — needed for `specrails-core init` | Use your usual installer |
 
-```bash
-SPECRAILS_GEMINI_BETA=1   # or 'true'
-```
+> **Two different minimums.** The `gemini` **binary** floor is **0.11.0**.
+> The `specrails-core` **package** floor is **4.8.0** (a single shared
+> version for all providers). They are separate things — the binary on your
+> machine vs. the artifacts installed into the project.
+
+**On the API key.** The free OAuth "Login with Google" tier exists, but it
+is being wound down for the CLI and is not a reliable unattended path. Use a
+real `GEMINI_API_KEY` so headless rails and Explore turns can authenticate
+without a browser prompt. Free-tier keys serve the Flash models; Pro/preview
+models need billing enabled.
 
-With it set, `GET /api/available-providers` reports Gemini's real install status,
-Add Project shows a **Gemini** checkbox, and projects can select it.
+The app's **Add Project** dialog runs a live prerequisites check. It disables
+the Gemini provider checkbox with a "not found" hint when the binary isn't on
+`PATH`, and shows install commands if you click "More info".
 
 ## Adding a Gemini project
 
-Add Project → tick **Gemini** (visible once the beta is on and `gemini` is on PATH).
-A project can install Gemini alongside Claude/Codex; the first provider selected is
-the primary/default, and per-invocation engine pickers let you choose per spec/rail.
+1. Open the app UI and click **Add Project**.
+2. Pick the project's path.
+3. In the **AI providers** row, check **Gemini** (you can check Claude and/or
+   Codex too — see [Running multiple providers in one
+   project](#running-multiple-providers-in-one-project)). The first provider
+   you select becomes the project default.
+4. Submit. The app writes `.specrails/install-config.yaml` and spawns
+   `npx --yes --prefer-online specrails-core@^4.8.0 init --yes --from-config <file>`.
+   The install produces the `.gemini/` artifacts (commands + `sr-*` agents),
+   plus a `GEMINI.md` instructions file.
+
+The provider **set** you choose is **immutable after creation** — you can't
+add or remove a provider on an existing project. Install everything you may
+want up front.
+
+## Using Gemini (per-spec and per-rail)
+
+When more than one provider is installed, **per-invocation engine pickers**
+let you choose which CLI runs each piece of work:
+
+- **Per spec:** Dashboard → **+ Add Spec** → the engine selector at the top
+  of the dialog → choose **Gemini**. The Explore/Quick session then runs on
+  Gemini.
+- **Per rail:** open a rail's header → the **engine selector** → choose
+  **Gemini** → **Launch**. The rail job spawns `gemini` headlessly.
+- **In the terminal:** the **Open AI CLI** (Sparkles) button → pick
+  **Gemini** to launch an interactive `gemini` session in the project dir.
+
+Your last-used engine is remembered per project (defaulting to the primary),
+so you don't have to re-pick every time. On a single-provider Gemini project
+these pickers don't render — there's nothing to choose.
+
+## Running multiple providers in one project
+
+A single project can install **Claude, Codex, and Gemini** in any
+combination. In **Add Project** the **AI providers** control is a
+multi-select; check the ones you want and the app runs each provider's
+install sequentially. The first you select is the **primary/default**.
+
+Once more than one is installed:
+
+- **Engine pickers** (above) appear on Add Spec, the rail header, and the
+  terminal launcher.
+- **Capability intersection.** The right sidebar only shows sections that
+  *every* installed provider supports. Because Gemini and Codex have no
+  agent profiles, the **Agents** section is **hidden** on a mixed project.
+  The **Integrations** section stays visible (it hosts the
+  provider-agnostic Jira card); only the Serena **plugin** entry inside it
+  is filtered per-provider. In the Add Spec dialog, the SMASH and Contract
+  Layer options are hidden when the selected engine is Gemini.
+
+When only one provider is installed the app behaves byte-identically to a
+single-provider project — no engine pickers, no provider persisted on spawns.
 
 ## What's different vs Claude
 
-- **Cost is estimated, not native.** Gemini does not report a USD cost in its
-  stream, so Specrails estimates it from a rate card (`server/pricing.ts`,
-  keys `gemini:<model>`). Token counts (incl. cached) come straight from the run.
-- **No per-agent profiles / SMASH / Contract Refine.** These are Claude-only; on a
-  mixed project the capability intersection hides them (same as Codex).
+| Capability | Claude | Codex | Gemini |
+|---|---|---|---|
+| **CLI / project dir** | `claude` / `.claude/` | `codex` / `.codex/` | `gemini` / `.gemini/` |
+| **Instructions file** | `CLAUDE.md` | `AGENTS.md` | `GEMINI.md` |
+| **Native cost report** | ✅ `total_cost_usd` | ❌ estimated | ❌ estimated |
+| **Native OTEL** | ✅ | 🔧 synthesized by the app | ✅ native (no bridge) |
+| **`--system-prompt` flag** | ✅ | ❌ folded into prompt | ❌ folded into prompt |
+| **Rails pipeline** | ✅ | ✅ | ✅ |
+| **Ultracode rails** | ✅ | ❌ Claude-only | ❌ Claude-only |
+| **Agent profiles on rails** | ✅ | ❌ forced legacy | ❌ forced legacy |
+| **SMASH / Contract Refine** | ✅ | ❌ Claude-only | ❌ Claude-only |
+| **Plugins (Serena)** | ✅ | ❌ | ✅ |
+
+A few of these deserve a fuller explanation:
+
+- **Cost is estimated, not native.** Gemini reports token counts (including
+  cached) but no USD cost in its stream, so Specrails estimates the cost from
+  a rate card (`server/pricing.ts`, keys `gemini:<model>`). Estimated rows
+  show a `~` prefix on the Analytics page.
+- **OTEL is native.** Like Claude, Gemini honours the standard `OTEL_*`
+  telemetry env vars, so QueueManager injects the same telemetry env
+  (`buildTelemetryEnv`) for Gemini rail spawns — no synthetic bridge (unlike
+  Codex). There is no Gemini-specific OTEL env builder.
 - **System prompt is folded.** Gemini has no `--system-prompt` flag, so for
-  non-Explore actions the system prompt is folded into the user prompt. Explore
-  turns stay user-only and trust the app-managed `GEMINI.md` in the explore cwd.
-- **OTEL is native.** Unlike Codex, Gemini emits OTLP via `GEMINI_TELEMETRY_*`, so
-  pipeline telemetry needs no synthetic bridge.
+  non-Explore actions the system prompt is folded into the user prompt.
+  Explore turns stay user-only and trust the app-managed `GEMINI.md` in the
+  explore cwd.
+- **Agent profiles aren't selectable for Gemini rails.** The rails router
+  forces the profile to `null` (legacy mode) for any non-Claude engine. (UI
+  limitation: the rail header may still render a profile picker for a Gemini
+  rail, but the server ignores the selection.)
+- **Plugins do work.** Unlike Codex, Gemini uses `project-json` MCP
+  registration (like Claude), so `project-json` plugins such as **Serena**
+  load for Gemini rails.
+
+## How rails work headlessly (`prepareHeadlessSpawn`)
+
+Rails run `gemini -p` in headless mode. Gemini *discovers*
+`<project>/.gemini/agents/*.md` but only *enables* a project's custom
+subagents after an interactive "New Agents Discovered → Acknowledge and
+Enable" prompt — which never fires in a headless spawn. Without
+acknowledgment, `invoke_agent sr-architect` returns "Subagent not found" and
+the pipeline silently falls back to a generic agent.
+
+The Gemini adapter implements a unique `prepareHeadlessSpawn` hook
+(`server/providers/gemini-agent-ack.ts`) that QueueManager calls right before
+each Gemini rail spawn. It writes the acknowledgment file
+(`~/.gemini/acknowledgments/agents.json`, keyed by project root, value =
+sha256 of each agent's markdown) so the specialised `sr-architect` /
+`sr-developer` / `sr-reviewer` personas load in headless mode. This is the
+load-bearing mechanic that makes the rails pipeline actually work on Gemini.
+It's best-effort and merged, so other projects and agents are never disturbed.
 
 ## Models
 
-Curated catalog (`server/providers/gemini-adapter.ts`): `gemini-2.5-pro` (default),
-`gemini-2.5-flash`, `gemini-2.5-flash-lite`, `gemini-3.1-pro-preview`. Concrete GA
-ids are pinned (preview ids rotate). Free-tier API keys serve Flash; Pro/preview
-need billing.
+The curated catalog (`server/providers/gemini-adapter.ts`) is:
+
+- **`gemini-3.5-flash`** — the default.
+- `gemini-3.1-pro-preview`
+- `gemini-3.1-flash-lite`
+- `gemini-2.5-flash-lite`
+
+Concrete GA ids are pinned (preview ids rotate). Free-tier API keys serve the
+Flash models; Pro/preview need billing.
+
+> A few older ids (`gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-3-flash-preview`)
+> are **not** selectable models. They survive only as historic pricing rows in
+> `server/pricing.ts` so that already-recorded invocations on those models still
+> price correctly.
 
 ## Trusted folders (headless)
 
-Gemini's "trusted folders" gate silently overrides `--yolo` back to `default` —
-blocking *every* tool call — in a directory it doesn't trust. Specrails injects
-`GEMINI_CLI_TRUST_WORKSPACE=true` into every Gemini spawn (`server/util/cli-prompt.ts`
-`spawnGemini`) so headless rails/explore can actually run tools. No action needed
-from you.
+Gemini's "trusted folders" gate silently overrides `--yolo` back to
+`default` — blocking *every* tool call — in a directory it doesn't trust.
+Specrails injects `GEMINI_CLI_TRUST_WORKSPACE=true` into every Gemini spawn
+(`server/util/cli-prompt.ts`, `spawnGemini`) so headless rails and Explore
+turns can actually run tools. **No action is needed from you.**
 
 ## Troubleshooting
 
-- **"Gemini" never appears in Add Project** → the beta is off (`SPECRAILS_GEMINI_BETA`
-  unset), or `gemini` isn't on PATH. Check `GET /api/available-providers`.
-- **Tools never run / job does nothing** → almost always auth or trust. Confirm
-  `GEMINI_API_KEY` is set in the server env; the trust var is handled automatically.
-- **`limit: 0` / quota errors on Pro** → free-tier API keys don't serve Pro models;
-  use a Flash model or enable billing.
-- **Cost shows `—`** → no `gemini:<model>` pricing row for the model used; add one to
-  `server/pricing.ts`.
+**"Gemini" never appears in Add Project** — `gemini` isn't on `PATH`, or the
+emergency rollback is active (`SPECRAILS_GEMINI_BETA=0`). Check
+`GET /api/available-providers`; install the CLI and restart the app so PATH
+refreshes if needed.
+
+**"gemini 0.10.0 is older than required 0.11.0"** — upgrade with
+`npm i -g @google/gemini-cli`. Earlier versions lack the stream-json and
+headless resume support the app relies on.
+
+**Tools never run / a job does nothing** — almost always auth or trust.
+Confirm `GEMINI_API_KEY` is set in the server env; the trust var is handled
+automatically.
+
+**A rail's agents don't specialise (`Subagent not found`)** — the project's
+`.gemini/agents/*.md` weren't acknowledged. This is normally handled
+automatically by `prepareHeadlessSpawn` (above); make sure the project was
+installed with `specrails-core` ≥ 4.8.0 so the `.gemini/` agents exist.
+
+**`limit: 0` / quota errors on Pro** — free-tier API keys don't serve Pro or
+preview models; use a Flash model or enable billing.
+
+**Cost shows `—`** — there's no `gemini:<model>` pricing row for the model
+that ran (e.g. a brand-new model Google shipped after our last review). Cost
+estimation fails soft (it returns nothing rather than guessing). Add a row to
+`server/pricing.ts` and reload.
 
 ## Emergency rollback
 
-Unset `SPECRAILS_GEMINI_BETA` (or set it to `0`). Gemini disappears from the UI and
-becomes unselectable immediately; existing non-Gemini projects are unaffected. The
-adapter stays registered but dormant.
+To disable the Gemini path, set `SPECRAILS_GEMINI_BETA=0` in the app's
+environment. For a source checkout that's:
+
+```bash
+SPECRAILS_GEMINI_BETA=0 npm run dev
+```
+
+For the packaged desktop app, set the variable in the environment the app
+process inherits. Only the exact string `0` disables Gemini — `1`, `true`,
+and unset all mean enabled.
+
+With it set, `GET /api/available-providers` reports `gemini: false` and
+`POST /api/projects` refuses new Gemini projects. Existing non-Gemini projects
+are unaffected; the adapter stays registered but dormant.
 
 ## Architecture pointers (for specrails-desktop developers)
 
-- Adapter: `server/providers/gemini-adapter.ts` (`nativeCostUsd:false`,
-  `nativeOtelEnv:true`, `systemPromptArg:false`, `instructionsFilename:'GEMINI.md'`,
-  `mcpRegistration:'project-json'`). Registered in `server/providers/index.ts`.
-- Stream schema (validated against gemini 0.46): `init{session_id,model}` /
-  `message{role,content,delta}` / `tool_use{tool_name,tool_id,parameters}` /
-  `tool_result` / `result{stats}`. `stats.input_tokens` includes `stats.cached`.
-- Beta gate + provider list: `server/desktop-router.ts` (`isGeminiBetaEnabled`,
-  `/available-providers`, `POST /projects`).
-- Trust-folder env: `server/util/cli-prompt.ts` `spawnGemini`.
+- **Adapter:** `server/providers/gemini-adapter.ts` (`nativeCostUsd: false`,
+  `nativeOtelEnv: true`, `systemPromptArg: false`, `profileEnvSupport: true`,
+  `instructionsFilename: 'GEMINI.md'`, `mcpRegistration: 'project-json'`,
+  `minCliVersion: '0.11.0'`). Registered in `server/providers/index.ts`.
+- **Headless subagent ack:** `server/providers/gemini-agent-ack.ts`
+  (`acknowledgeGeminiProjectAgents`), wired as the adapter's
+  `prepareHeadlessSpawn` and called by `server/queue-manager.ts` before each
+  rail spawn.
+- **Stream schema** (pinned to the gemini-cli 0.11 contract, locked by the
+  fixtures under `server/providers/__fixtures__/gemini-*.ndjson`):
+  `init{session_id,model}` / `message{role,content,delta}` /
+  `tool_use{tool_name,tool_id,parameters}` / `tool_result` / `result{stats}`.
+  `stats.input_tokens` includes `stats.cached`.
+- **Beta gate + provider list:** `server/desktop-router.ts`
+  (`isGeminiBetaDisabled` — returns `true` only when
+  `SPECRAILS_GEMINI_BETA === '0'`; `/available-providers`, `POST /projects`).
+- **Pricing / cost estimation:** `server/pricing.ts` (`gemini:<model>` rows +
+  `estimateCostUsd`, which returns `null` when no row matches).
+- **Trust-folder env:** `server/util/cli-prompt.ts`, `spawnGemini`.
 
 ## See also
 
-- [`docs/codex.md`](./codex.md) — the Codex provider (the other non-native provider).
-- [`docs/adding-a-provider.md`](./adding-a-provider.md) — how to add a provider.
-- [`docs/gemini-cli-provider-study.md`](./gemini-cli-provider-study.md) — the design study.
-- [`docs/gemini-core-support-evaluation.md`](./gemini-core-support-evaluation.md) — the rails/core work.
+- [`docs/codex.md`](./codex.md) — the Codex provider (the other provider with
+  estimated cost).
+- [Adding a provider](internals/adding-a-provider.md) — the developer guide to
+  wiring a new AI CLI adapter (Gemini is the freshest worked example).
+- [`docs/gemini-cli-provider-study.md`](./gemini-cli-provider-study.md) — the
+  original design study.
+- [`docs/gemini-core-support-evaluation.md`](./gemini-core-support-evaluation.md)
+  — the rails/core support work.

package/docs/getting-started.md

@@ -4,7 +4,7 @@ This guide walks you from "I just heard about specrails-desktop" to "I just ship
 
 ## What you'll need
 
-- **An AI CLI signed in** — either [Claude Code](https://claude.com/claude-code) (via Claude subscription login or an `ANTHROPIC_API_KEY`) or the Codex CLI. You can use one or both — see [Codex](codex.md).
+- **An AI CLI signed in** — [Claude Code](https://claude.com/claude-code) (via Claude subscription login or an `ANTHROPIC_API_KEY`), the [Codex CLI](codex.md) (`codex` ≥ 0.128.0), or the [Gemini CLI](gemini.md) (`gemini` ≥ 0.11.0, with `GEMINI_API_KEY` set). You can mix and match — install Claude, Codex, Gemini, or any combination.
 - A project you want to work on (any Git repository works)
 
 If you install with **npm** (Option 2 below) you'll also need **Node.js 20+** and **`git`** on your PATH. The **desktop app** bundles its own Node and Git runtimes, so you don't need those installed separately.
@@ -22,7 +22,7 @@ Download a signed build for your OS from `https://specrails.dev/downloads/specra
 - **macOS** — `specrails-desktop-<version>-aarch64.dmg` (Apple Silicon, notarised)
 - **Windows** — `specrails-desktop-<version>-x64-setup.exe` (NSIS) or `.msi`
 
-Open the installer, drag to Applications (macOS) or click through the wizard (Windows). The app bundles the server, so you don't need a separate process. macOS handles all the Homebrew/Volta/nvm PATH gymnastics for you — see [platforms/macos.md](platforms/macos.md) if anything looks off.
+Open the installer, drag to Applications (macOS) or click through the wizard (Windows). The app bundles the server, so you don't need a separate process. The desktop app resolves your PATH for you at startup — no manual Homebrew/Volta/nvm setup needed — see [platforms/macos.md](platforms/macos.md) if anything looks off.
 
 > First Windows launch shows a SmartScreen warning until the installer is code-signed. Click **More info → Run anyway**. Details and hash-verification steps in [platforms/windows.md](platforms/windows.md).
 
@@ -43,7 +43,7 @@ There are two ways. Pick whichever feels natural.
 
 1. Click **+** in the left sidebar.
 2. Enter the absolute path to your project (e.g. `/Users/you/repos/my-app`).
-3. Pick your **AI providers**. Check **Claude**, **Codex**, or both — when you select both, the first one becomes the project default. The provider set is fixed once the project is created.
+3. Pick your **AI providers**. Check **Claude**, **Codex**, **Gemini**, or any combination — the first one in the list (Claude, then Codex, then Gemini) that you check becomes the project default. The provider set is fixed once the project is created.
 4. The prerequisites panel verifies `node`, `npm`, `npx`, `git`. If anything's missing, the panel surfaces OS-aware install commands you can copy.
 5. Click **Add**.
 
@@ -54,12 +54,14 @@ specrails-desktop add /path/to/your/project
 specrails-desktop list   # verify
 ```
 
+> Heads-up: if you run a spec from the CLI while no app server is running, the offline fallback always invokes `claude` — regardless of the project's primary provider — and records nothing to Analytics. Start the app (or `specrails-desktop start`) to use Codex or Gemini and to capture cost tracking.
+
 ### If the project doesn't have specrails-core yet
 
 The setup wizard runs automatically. Three steps:
 
 1. **Configure** — choose which agents to install (the baseline trio `sr-architect`, `sr-developer`, `sr-reviewer` is always selected; optional agents like Test Writer or Security Reviewer are opt-in). Pick a model preset (Balanced / Budget / Max) and optionally override the model per agent.
-2. **Install** — the app runs the installer (`npx specrails-core@latest init --yes --from-config <config>`) non-interactively and streams the output live.
+2. **Install** — the app runs the installer (`npx --yes --prefer-online specrails-core@^4.8.0 init --yes --from-config <config>`) non-interactively and streams the output live. The version is pinned to the core release the app ships with — it never silently jumps to a new major.
 3. **Done** — a summary tells you how many agents and commands landed. Click **Continue to project**.
 
 That's the whole onboarding. No tier picker, no second wizard. You can manage agents and their per-agent models later from the **Agents** page (Profiles tab).
@@ -74,7 +76,7 @@ When you already know what you want:
 
 1. On the Dashboard, click **+ Add Spec → Quick**.
 2. Type a one-line title (e.g. *"Add a webhook retry with exponential backoff"*).
-3. (Optional) toggle **Enrich with Contract Layer** to get a structured block of names, data shapes, invariants, and a file touch list appended to the description.
+3. (Optional) toggle **Enrich with Contract Layer** to get a structured block of names, data shapes, invariants, and a file touch list appended to the description. (Contract Layer enrichment is a Claude-only feature — on Codex and Gemini projects the toggle is shown but the refinement step is skipped.)
 4. Hit Enter.
 
 Your AI CLI generates the full spec in one turn. A small toast at the bottom right shows the project, the spec title, and live elapsed time ("Generating… 0:12") — it turns into a success or failure toast (with a **View** action) when generation finishes.
@@ -113,6 +115,7 @@ Token usage, duration, and cost are tracked per turn and surface in:
 - **[Running pipelines](running-pipelines.md)** — agent profiles, plugins (Serena), telemetry export.
 - **[Tracking cost](tracking-cost.md)** — analytics deep dive and CSV exports.
 - **[Codex](codex.md)** — using the Codex CLI as a provider, alongside or instead of Claude.
+- **[Gemini](gemini.md)** — using the Gemini CLI as a provider, alongside or instead of Claude.
 - **[Terminal panel](terminal.md)** — the built-in per-project terminal (toggle with `Cmd/Ctrl+J`).
 - **[Customising the app](customizing.md)** — themes, terminal settings, kill switches.
 - **[CLI reference](cli.md)** — drive specrails-desktop from the terminal.
@@ -127,13 +130,19 @@ specrails-desktop stop                # stops the running server cleanly
 lsof -i :4200    # macOS / Linux
 ```
 
-**The `claude` command isn't found inside the app**
+**Your AI CLI (`claude`, `codex`, or `gemini`) isn't found inside the app**
+
+On macOS, this usually means the app was launched from Finder/Dock and didn't pick up Homebrew/Volta paths. The app resolves PATH at startup automatically, but if it still fails, see [platforms/macos.md](platforms/macos.md).
+
+**The setup wizard fails on `npx specrails-core init`**
 
-On macOS, this usually means the app was launched from Finder/Dock and didn't pick up Homebrew/Volta paths. The app fixes this at startup automatically, but if it still fails, see [platforms/macos.md](platforms/macos.md).
+Most likely Node is missing from the shell environment that launched the app, or whichever AI CLI your project uses isn't authenticated:
 
-**The setup wizard fails on `npx specrails-core@latest init`**
+- **Claude** — sign in to the `claude` CLI or set `ANTHROPIC_API_KEY`.
+- **Codex** — sign in to the `codex` CLI.
+- **Gemini** — make sure `gemini` is on your PATH and `GEMINI_API_KEY` is set (headless spawns can't use the interactive "Login with Google" flow).
 
-Most likely Node is missing from the shell environment that launched the app, or your AI CLI isn't authenticated (sign in to the `claude` CLI or set `ANTHROPIC_API_KEY`; for Codex, sign in to the `codex` CLI). Click **Copy diagnostics** in the install-instructions modal — that prints the resolved PATH, where the app found each tool, and login-shell status. Paste it into a bug report if you can't figure it out.
+Click **Copy diagnostics** in the install-instructions modal — that prints the resolved PATH, where the app found each tool, and login-shell status. Paste it into a bug report if you can't figure it out.
 
 **More**
 

package/docs/guide/de/agents/1-meet-the-agents.md

@@ -0,0 +1,38 @@
+# Die Agents im Überblick
+
+Wenn du eine **Implement**-Rail startest, übergibt Specrails deine Spec nicht einfach einer einzigen KI und hofft auf das Beste. Stattdessen arbeitet ein kleines Team spezialisierter *Agents*, jeder mit einer einzigen Aufgabe und in einer bewusst gewählten Reihenfolge. Diese Seite stellt dir vor, wer zu diesem Team gehört und was jeder Einzelne tut.
+
+## Das Basis-Trio
+
+Jeder Pipeline-Durchlauf nutzt diese drei Agents – sie bilden das Rückgrat, und ohne sie kann ein Projekt keine Rail starten.
+
+| Agent | Rolle | Aufgabe |
+|-------|------|--------------|
+| **sr-architect** | Der Planer | Liest deine Spec, inspiziert die Codebasis und erstellt einen konkreten Umsetzungsplan – welche Dateien angefasst werden, welche Form die Änderung annimmt und worauf zu achten ist. Er denkt nach, bevor irgendjemand Code schreibt. |
+| **sr-developer** | Der Umsetzer | Nimmt den Plan des Architekten und schreibt den Code tatsächlich: neue Dateien, Änderungen, Tests. Hier wird aus deiner Spec ein echtes Diff. |
+| **sr-reviewer** | Der Kritiker | Prüft die Arbeit des Developers gegen Spec und Plan, findet Regressionen und meldet sich, wenn etwas nicht stimmt. Er ist das Qualitätstor, bevor die Änderung als fertig gilt. |
+
+Stell es dir als **Design → Build → Review** vor – derselbe Ablauf, dem auch ein sorgfältiges menschliches Team folgen würde. Jeder Agent übergibt sein Ergebnis an den nächsten, sodass der Developer nie blind arbeitet und der Reviewer stets die ursprüngliche Absicht zum Abgleich hat.
+
+## Spezialisten-Agents
+
+Über das Trio hinaus kann ein Projekt optionale **Spezialisten-Agents** enthalten, die bestimmte Arten von Arbeit übernehmen. Der häufigste, der dir begegnet, ist:
+
+- **sr-merge-resolver** – ein Hilfs-Agent, der dabei hilft, Merge-Konflikte zu entwirren und sich überschneidende Änderungen in Einklang zu bringen. Er ist optional: Profile binden ihn nur ein, wenn du es möchtest, und er blockiert die Pipeline nie, wenn er fehlt.
+
+Spezialisten sind opt-in. Ein frisches Projekt läuft nur mit dem Trio; Spezialisten (und deine eigenen **Custom-Agents** – siehe [Custom-Agents & der Katalog](custom-agents-catalog)) fügst du hinzu, wenn der Workflow eines Projekts danach verlangt.
+
+## Wie Aufgaben zum richtigen Agent gelangen
+
+Innerhalb eines Durchlaufs wird Arbeit *geroutet*. Eine Aufgabe trägt Tags, und die Routing-Regeln eines Profils schicken getaggte Aufgaben an den am besten geeigneten Agent – mit einer abschließenden Auffangregel, die alles Übrige an den Developer leitet. Für den normalen Gebrauch musst du dir darüber keine Gedanken machen; das Standardsetup routet von Haus aus alles sinnvoll. Wenn du bereit bist, bestimmte Arten von Arbeit an bestimmte Agents zu lenken, schau dir [Modelle pro Agent anpassen](customizing-models-per-agent) an.
+
+## Eine wichtige Idee vorab
+
+Die *Definition* jedes Agents – seine Anweisungen, seine Persönlichkeit, was er darf – ist **geteilt**. Sie lebt als Datei (`.claude/agents/<id>.md`), die mit deinem Repository mitreist, sodass dein ganzes Team denselben Architekten und denselben Reviewer nutzt.
+
+Was **pro Projekt** gilt, ist die *Konfiguration* darüber: mit welchem Modell jeder Agent läuft und welche Kombination von Agents du für eine bestimmte Rail wählst. Genau dafür sind Profile da – und das ist die nächste Seite.
+
+## Wie es weitergeht
+
+- [Profile & der ausgewogene Standard](profiles-and-the-balanced-default) – wie das Setup des Teams verpackt und ausgewählt wird.
+- [Modelle pro Agent anpassen](customizing-models-per-agent) – Kosten und Qualität feinjustieren.

package/docs/guide/de/agents/2-profiles-and-the-balanced-default.md

@@ -0,0 +1,45 @@
+# Profile & der ausgewogene Standard
+
+Ein **Profil** ist ein gespeichertes Rezept für einen Pipeline-Durchlauf. Es beantwortet drei Fragen an einem Ort:
+
+1. **Welche Agents** mitwirken (das Basis-Trio plus etwaige Spezialisten oder Custom-Agents).
+2. **Mit welchem Modell** jeder Agent läuft.
+3. **Wie Aufgaben** an diese Agents geroutet werden.
+
+Du findest Profile im Bereich **Agents** jedes Projekts (rechte Seitenleiste → **Agents** → Tab **Profile**).
+
+## Der ausgewogene Standard
+
+Von Haus aus löst ein Projekt auf ein sinnvolles **default**-Profil auf. Es enthält das Basis-Trio – `sr-architect`, `sr-developer`, `sr-reviewer` – und routet über eine einzige Auffangregel jede Aufgabe an den Developer. Die Modelle sind für den Alltag ausgewogen: ein leistungsfähiges Modell dort, wo es zählt, ohne bei jedem Schritt zur teuersten Option zu greifen.
+
+Falls dein Projekt die Agent-Modelle bereits auf die alte Weise konfiguriert hatte (in der Frontmatter der Agent-Dateien), liest der **Migrieren**-Button diese aus und baut ein `default`-Profil, das das heutige Verhalten exakt abbildet – verlustfrei, nichts ändert sich, bis du dich entscheidest, daran zu drehen.
+
+Die Kernaussage: **Du musst kein Profil erstellen, um Specrails zu nutzen.** Der Standard funktioniert einfach. Profile sind der Weg, weiterzugehen.
+
+## Wie ein Profil für einen Durchlauf gewählt wird
+
+Wenn du eine Rail startest, wählt Specrails ein Profil in dieser Reihenfolge:
+
+1. **Deine ausdrückliche Wahl** im Rail-Header (siehe unten).
+2. Deine **persönliche Vorgabe** – ein Profil, das du als deinen persönlichen Standard für dieses Projekt markiert hast (sie ist lokal bei dir und wird nicht committet).
+3. Das **`default`**-Profil des Projekts.
+
+Das Profil wird *beim Start als Snapshot festgehalten*, sodass jede Rail in einem Batch ein anderes Profil ausführen kann und das spätere Ändern eines Profils nie bereits gestartete Jobs umschreibt.
+
+## Ein Profil pro Rail auswählen
+
+Die Profilwahl passiert genau dort, wo du startest – im **Rail-Header**, über den Profil-Selektor.
+
+- Wähle ein Profil aus dem Dropdown, um es **nur für diesen Start** zu verwenden.
+- Nutze die Option zum Festschreiben, um ein Profil künftig zur dauerhaften Wahl der Rail zu machen.
+
+Das ist der ganze Ablauf: Profil wählen, starten, fertig. Gleichzeitig laufende Rails im selben Batch können jeweils ihr eigenes Profil tragen, sodass ein schneller Fix und ein umfangreiches Feature mit unterschiedlichen Setups nebeneinander laufen können.
+
+## Wenn der Agents-Bereich still ist
+
+Profile sind eine Claude-Fähigkeit. Bei einem Projekt, das einen Nicht-Claude-Provider (Codex oder Gemini) enthält, ist der Agents-Bereich ausgeblendet und Rails laufen ohne Profile – das ist so gewollt, kein Fehler. Außerdem setzen Profile ein hinreichend aktuelles `specrails-core` im Projekt voraus; ist es älter, siehst du ein gelbes Banner. Die von dir erstellten Profile werden trotzdem **gespeichert** – sie wirken sich nur erst auf die Pipeline aus, wenn core aktualisiert ist. Aktualisiere mit dem im Banner gezeigten Befehl, um sie freizuschalten.
+
+## Wie es weitergeht
+
+- [Modelle pro Agent anpassen](customizing-models-per-agent) – `fast`- und `max`-Profile bauen.
+- [Custom-Agents & der Katalog](custom-agents-catalog) – das Team ansehen und erweitern.

package/docs/guide/de/agents/3-customizing-models-per-agent.md

@@ -0,0 +1,60 @@
+# Modelle pro Agent anpassen
+
+Das Nützlichste, was Profile dir ermöglichen, ist, **für jeden Schritt das richtige Modell zu wählen**. Ein Planungsschritt verdient vielleicht dein stärkstes Modell; ein routinemäßiger Build-Schritt ist mit etwas Schnellerem und Günstigerem womöglich vollkommen zufrieden. Profile lassen dich genau das ausdrücken.
+
+Hier zahlt sich die Trennung von Geteiltem und Projektbezogenem aus:
+
+- Die Agent-*Definitionen* bleiben in deinem Team geteilt.
+- Das *Modell, mit dem jeder Agent läuft*, wird **pro Projekt** innerhalb eines Profils konfiguriert und wirkt sich nur auf dein Projekt aus.
+
+Änderst du ein Modell, änderst du Kosten und Verhalten für dieses Projekt – ohne das Setup von irgendwem sonst oder die zugrunde liegenden Anweisungen des Agents anzufassen.
+
+## Das Modell eines Agents ändern
+
+Wähle unter **Agents → Profile** ein Profil aus und öffne seinen Agent-Ketten-Editor. Jeder Agent in der Kette hat ein Modellfeld. Zusätzlich gibt es ein **Orchestrator**-Modell, das die übergeordnete Koordination der Pipeline übernimmt.
+
+Die Modellwerte sind Aliasse – für Claude sind das `opus`, `sonnet` und `haiku` (am leistungsfähigsten → am schnellsten). Setze pro Agent den gewünschten Alias:
+
+- Lass das Modell eines Agents **leer**, um auf den Standard der Agent-Datei zurückzufallen.
+- Setze es ausdrücklich, um es nur für dieses Profil zu überschreiben.
+
+Speichere, und die nächste mit diesem Profil gestartete Rail nutzt die neuen Modelle. Bereits laufende Jobs behalten ihren Snapshot.
+
+## Profile wie `fast` und `max` erstellen
+
+Das naheliegende Muster sind ein paar benannte Profile, zu denen du je nach Aufgabe greifst:
+
+**Ein `fast`-Profil** – für kleine, risikoarme Änderungen, bei denen du Tempo und eine kleinere Rechnung willst:
+
+- Architect: ein mittleres oder schnelles Modell – der Plan ist einfach.
+- Developer: ein schnelles Modell – die Änderung ist mechanisch.
+- Reviewer: halte ihn solide, aber du kannst auch hier abspecken.
+
+**Ein `max`-Profil** – für knifflige Features mit hohem Einsatz, bei denen jeder Schritt so scharf wie möglich sein soll:
+
+- Architect, Developer und Reviewer: durchweg dein stärkstes Modell.
+
+### Zwei Wege, eines zu bauen
+
+1. **Duplizieren und anpassen** *(empfohlen).* Wähle dein `default`-Profil, **dupliziere** es, gib der Kopie einen kebab-case-Namen wie `fast` oder `max` und passe dann das Modell jedes Agents an. Du erbst eine bewährte Kette samt Routing und änderst nur, was du auch ändern willst.
+2. **Leer starten.** Erstelle ein **leeres Profil** und stelle die Kette selbst zusammen. Du musst trotzdem das Basis-Trio (`sr-architect`, `sr-developer`, `sr-reviewer`) einbinden – die Pipeline hängt von allen dreien ab – sowie genau eine abschließende Auffang-Routing-Regel, die als Letztes stehen muss.
+
+Profilnamen sind in Kleinbuchstaben im kebab-case (z. B. `fast`, `max`, `cheap-and-cheerful`).
+
+## Aufgaben an bestimmte Agents routen
+
+Die **Routing-Regeln** eines Profils entscheiden, welcher Agent eine getaggte Aufgabe übernimmt. Jede Regel listet Aufgaben-Tags und einen Ziel-Agent auf; die erste Regel, deren Tags passen, gewinnt, und eine einzige `default: true`-Regel am Ende fängt alles Übrige ab. Nur Agents, die tatsächlich in der Kette des Profils stehen, können Routing-Ziele sein – der Editor setzt das durch.
+
+Für den Alltag fasst du das Routing nicht an: Die Auffangregel schickt Arbeit an den Developer, und das ist richtig. Greife zu Tag-Regeln, wenn du etwa möchtest, dass mit `migration` getaggte Arbeit an einen Spezialisten geht.
+
+## Das Profil beim Start wählen
+
+All das kommt beim Start zusammen: Wähle im Rail-Header pro Rail `fast`, `max` oder `default`. Ein Batch kann sie mischen – ein winziger Fix auf `fast`, ein großes Feature auf `max`, beide gleichzeitig laufend. Den Ablauf der Auswahl findest du unter [Profile & der ausgewogene Standard](profiles-and-the-balanced-default).
+
+## Eine Anmerkung zur Sicherheit
+
+Das Löschen eines Profils ist für laufende Arbeit unbedenklich: Bereits damit gestartete Jobs behalten ihren Snapshot, und künftige Starts fallen einfach durch die Auflösungsreihenfolge zurück. Experimentiere ruhig.
+
+## Wie es weitergeht
+
+- [Custom-Agents & der Katalog](custom-agents-catalog) – Agents hinzufügen, die du in deine Ketten einbinden kannst.

package/docs/guide/de/agents/4-custom-agents-catalog.md

@@ -0,0 +1,43 @@
+# Custom-Agents & der Katalog
+
+Profile entscheiden, *welche Agents mit welchen Modellen laufen*. Doch woher kommen die Agents selbst? Aus dem **Agents-Katalog**.
+
+Öffne in einem beliebigen Projekt **Agents → Katalog**. Es ist eine schreibgeschützte Ansicht jedes Agents, der diesem Projekt zur Verfügung steht, in zwei Gruppen:
+
+- **Upstream-Agents** – die Agents, die mit `specrails-core` ausgeliefert werden: das Basis-Trio (`sr-architect`, `sr-developer`, `sr-reviewer`) und etwaige Spezialisten wie `sr-merge-resolver`.
+- **Custom-Agents** – Agents, die du selbst hinzugefügt hast, benannt als `custom-*`.
+
+Jeder Katalogeintrag zeigt, wofür der Agent da ist und welches Standardmodell er nutzt, sodass du die vollständige Aufstellung sehen kannst, bevor du Agents in eine Profil-Kette einbindest.
+
+## Einen Custom-Agent hinzufügen
+
+Custom-Agents sind schlichte Markdown-Dateien in deinem Repository unter `.claude/agents/`, benannt als `custom-<etwas>.md`. Die Datei enthält die Anweisungen des Agents (seinen System-Prompt) und einen kleinen Frontmatter-Header mit einem Standard-`model:`.
+
+Sobald die Datei im Projekt existiert, erscheint sie im Katalog als Custom-Agent, und du kannst ihre id zur Agent-Kette jedes Profils hinzufügen (und Aufgaben an sie routen). Die id muss zum Dateinamen passen – ein Eintrag für `custom-docs` verweist auf `.claude/agents/custom-docs.md`.
+
+Weil sie in deinem Repo leben, sind Custom-Agents **committfähige Team-Assets**: Committe die Datei, und dein ganzes Team bekommt den Agent. Das spiegelt die Kernidee, die sich durch den gesamten Agents-Bereich zieht –
+
+> **Agent-Definitionen sind geteilt (sie leben im Repo und reisen mit `git` mit). Die Modellkonfiguration ist projektbezogen (sie lebt in Profilen).**
+
+Der `custom-*`-Namespace ist reserviert und geschützt: Die Befehle `init` und `update` von `specrails-core` fassen `.claude/agents/custom-*.md` nie an, sodass deine Custom-Agents Core-Upgrades unangetastet überstehen. (Derselbe Schutz gilt für von Plugins beigesteuerte Fragmente wie `custom-serena.md`.)
+
+## Einen Custom-Agent einsetzen
+
+Der typische Ablauf:
+
+1. Schreibe `.claude/agents/custom-<name>.md` mit Anweisungen und einem Standardmodell.
+2. Stelle sicher, dass er unter **Agents → Katalog** im Bereich Custom auftaucht.
+3. Füge den Agent unter **Agents → Profile** zur Kette eines Profils hinzu (und überschreibe optional sein Modell für dieses Profil).
+4. Ergänze eine Routing-Regel, damit Aufgaben mit den passenden Tags ihn erreichen – oder verlasse dich auf die Reihenfolge der Kette.
+5. Starte eine Rail mit diesem Profil aus dem Rail-Header.
+
+## Beobachten, wie sich Profile schlagen
+
+Der Agents-Bereich hat außerdem einen **Nutzung**-Tab – eine Aufschlüsselung pro Profil, wie viele Jobs in einem gewählten Zeitraum unter jedem Profil liefen. Das ist eine schnelle Möglichkeit zu prüfen, ob deine Aufteilung in `fast`/`max` tatsächlich so genutzt wird, wie du es beabsichtigt hast, und zu erkennen, zu welchem Profil dein Team tendiert.
+
+## Zusammenfassung des gesamten Bereichs
+
+- **Agents** sind die spezialisierten Teammitglieder – das geteilte Trio plus Spezialisten und deine Custom-Agents. ([Die Agents im Überblick](meet-the-agents))
+- **Profile** bündeln, welche Agents mit welchen Modellen laufen und wie Aufgaben geroutet werden – pro Rail beim Start ausgewählt. Das default-Profil ist die ausgewogene Alltagswahl. ([Profile & der ausgewogene Standard](profiles-and-the-balanced-default))
+- **Modelle** werden pro Agent, pro Projekt, innerhalb von Profilen feinjustiert – baue `fast` und `max`, passend zur Aufgabe. ([Modelle pro Agent anpassen](customizing-models-per-agent))
+- **Der Katalog** zeigt jeden Agent, und der `custom-*`-Namespace lässt dich das Team erweitern – Definitionen geteilt, Konfiguration projektbezogen.