specrails-desktop 2.8.0 → 2.9.0

package/docs/codex.md

@@ -1,23 +1,33 @@
 # Using Specrails with the Codex CLI
 
-Specrails supports **two AI providers**: Anthropic's
-[Claude Code](https://claude.com/claude-code) and OpenAI's
-[Codex CLI](https://developers.openai.com/codex). You pick one or
-both when you add a project; the rest of the app behaves identically
-across them. (See [Running both providers in one
-project](#running-both-providers-in-one-project) below.)
+Specrails supports **three AI providers** — Claude, Codex, and Gemini —
+and they are interchangeable. This guide covers OpenAI's
+[Codex CLI](https://developers.openai.com/codex). For the others, see
+[Claude Code](https://claude.com/claude-code) and the
+[Gemini guide](gemini.md).
+
+> **Just want to get going?** Install the `codex` CLI, log in, then in
+> the app click **Add Project → check Codex → Submit**. The rest of the
+> app (specs, rails, chat, analytics) works the same as it does for
+> Claude. Everything below is detail for when you need it.
+
+You pick one, two, or all three providers when you add a project — and
+you can mix them in a single project too (see [Running more than one
+provider in one project](#running-more-than-one-provider-in-one-project)
+below). All three are enabled by default.
 
 > The codex path is enabled by default. To temporarily disable it
-> (e.g. as an emergency rollback during a beta window), set
-> `SPECRAILS_CODEX_BETA=0` in the app's environment (the legacy
+> (e.g. as an emergency rollback), set `SPECRAILS_CODEX_BETA=0` in the
+> app's environment. **Only the exact string `0` disables it** — `false`,
+> `off`, `1`, or leaving it unset all mean "enabled". The legacy
 > `SPECRAILS_HUB_CODEX_BETA` name is still read as a fallback when the
-> new variable is unset). Unset or set to `1` to re-enable.
+> new variable is unset.
 
 ## Prerequisites
 
 | What | Why | How |
 |---|---|---|
-| `codex` CLI ≥ 0.128.0 | Earlier versions don't support `exec --json` + `exec resume` semantics the app relies on | `brew install codex` (macOS) · winget / download from https://developers.openai.com/codex (Windows / Linux) |
+| `codex` CLI ≥ 0.128.0 | Earlier versions don't support `exec --json` + `exec resume` semantics the app relies on | `npm i -g @openai/codex` · or download from https://developers.openai.com/codex |
 | Authentication | Codex needs OAuth or an API key | `codex login` (ChatGPT OAuth) or set `OPENAI_API_KEY` |
 | `uv` ≥ 0.1.0 (optional) | Required if you want to install the Serena plugin | `brew install uv` · `pipx install uv` · or the curl installer at https://docs.astral.sh/uv |
 | `git`, `node`, `npm`, `npx` | Same as Claude — needed for `specrails-core init` | Use your usual installer |
@@ -31,13 +41,16 @@ binary isn't on `PATH`; it shows install commands if you click "More info".
 1. Open the app UI and click **Add Project**.
 2. Pick the project's path.
 3. In the **AI providers** row, check **Codex** (you can check
-   **Claude** too — see [Running both providers in one
-   project](#running-both-providers-in-one-project)). The first
-   provider you select becomes the project default.
+   **Claude** and/or **Gemini** too — see [Running more than one
+   provider in one project](#running-more-than-one-provider-in-one-project)).
+   The first provider you select becomes the project default.
 4. Submit. The app writes `.specrails/install-config.yaml` (with
    `provider: codex` and `tier: quick` as YAML keys) and spawns
-   `npx specrails-core@latest init --from-config <file>` — the provider
-   and tier live in the YAML, not as CLI flags. The install produces:
+   `npx --yes --prefer-online specrails-core@^4.8.0 init --yes --from-config <file>`
+   — the provider and tier live in the YAML, not as CLI flags. (The app
+   pins `specrails-core@^4.8.0`; that floor is the version that ships the
+   per-provider targets, including the Codex skill set.) The install
+   produces:
    - `.codex/config.toml` — model, reasoning effort, sandbox mode, and
      approval policy (all top-level keys per the codex 0.128.0+ schema).
    - `.codex/skills/sr-*/SKILL.md` — general specrails skills
@@ -53,21 +66,23 @@ binary isn't on `PATH`; it shows install commands if you click "More info".
 
 The provider **set** you choose is immutable after creation — you
 can't add or remove a provider on an existing project (the on-disk
-layouts are disjoint and we don't want to ask you to migrate two trees
-in place). Install both up front if you want the choice later.
+layouts are disjoint and we don't want to ask you to migrate the trees
+in place). Install every provider you might want up front if you want
+the choice later.
 
-## Running both providers in one project
+## Running more than one provider in one project
 
-A single project can install **both** Claude and Codex. In the
-**Add Project** dialog the **AI providers** control is a multi-select —
-check both and the app runs each provider's install sequentially. The
-first provider you select is the **primary/default**; the helper text
-spells this out: *"Both engines will be set up. The first is the
-project default. Cannot be changed after creation."*
+A single project can install **any combination** of Claude, Codex, and
+Gemini. In the **Add Project** dialog the **AI providers** control is a
+multi-select — check the ones you want and the app runs each provider's
+install sequentially. The first provider you select is the
+**primary/default**; the helper text spells this out: *"The engines will
+be set up. The first is the project default. Cannot be changed after
+creation."*
 
-Once both are installed:
+Once more than one is installed:
 
-- **Per-invocation engine pickers** let you choose Claude vs Codex each
+- **Per-invocation engine pickers** let you choose which engine runs each
   time you spawn work. The picker appears in the **Add Spec** dialog
   (`AiEngineSelector`), in the **rail header** (`RailEngineSelector`),
   and in the terminal's **Open AI CLI** menu (`CliLaunchMenu`). On
@@ -77,28 +92,51 @@ Once both are installed:
   primary), so you don't have to re-pick on every spawn.
 - **Capability intersection.** The right sidebar only shows sections
   that *every* installed provider supports. Because Codex has no agent
-  profiles and no plugins, the **Agents** and **Integrations** sections
-  are **hidden** while both providers are installed. Single-provider
-  projects are unaffected.
+  profiles, the **Agents** section is **hidden** whenever a non-Claude
+  provider is installed. The **Integrations** section stays **visible** —
+  it hosts the provider-agnostic Jira card. What gets filtered there is
+  the **Serena plugin** entry, which needs a Claude-style project MCP
+  registration (so it shows for Claude and Gemini, but not for Codex).
+  See [Plugins and MCP on codex projects](#plugins-and-mcp-on-codex-projects).
+  Single-provider projects are unaffected.
 
 When only one provider is installed the app behaves byte-identically to
 a single-provider project — no engine pickers, no provider persisted on
 spawns, no overrides.
 
-## What's different vs Claude
-
-| Surface | Claude | Codex |
-|---|---|---|
-| **CLI** | `claude` | `codex` |
-| **Project dir** | `.claude/` | `.codex/` |
-| **Instructions file** | `CLAUDE.md` | `AGENTS.md` |
-| **Agent format** | `.claude/agents/<id>.md` with `model:` frontmatter | `.codex/skills/<id>/SKILL.md` Skill format |
-| **Agent profiles** | Full support (rail `RailProfileSelector`) | **None** — codex rails force the profile to `null`; the Agents section is Claude-only |
-| **Contract Refine** | Claude-only (it `--resume`s the Explore session and runs `/specrails:contract-refine`) | **Skipped** — toggling "Enrich with Contract Layer" on a codex spec is a no-op |
-| **MCP registration** | Surgical merge of `<project>/.mcp.json` | `codex mcp add` against per-project `CODEX_HOME=~/.specrails/projects/<slug>/codex-home/` (isolated) |
-| **Session resume** | `--resume <session_id>` | `exec resume <thread_id>` |
-| **Native cost report** | `result.total_cost_usd` from `--output-format stream-json` | None — cost is **estimated** by the app from `turn.completed.usage` and the local pricing table at `server/pricing.ts` |
-| **Telemetry** | `OTEL_EXPORTER_OTLP_*` env vars consumed by claude itself | Synthesised by the app from `codex exec --json` events and POSTed to the same in-process OTLP receiver — telemetry export ZIP works identically |
+## What's different vs Claude (and Gemini)
+
+The table below puts Codex side by side with Claude, plus a Gemini column
+so you can see where each provider lands. (For the full Gemini picture see
+the [Gemini guide](gemini.md).)
+
+| Surface | Claude | Codex | Gemini |
+|---|---|---|---|
+| **CLI** | `claude` | `codex` | `gemini` |
+| **Min CLI version** | none pinned | `0.128.0` | `0.11.0` |
+| **Project dir** | `.claude/` | `.codex/` | `.gemini/` |
+| **Instructions file** | `CLAUDE.md` | `AGENTS.md` | `GEMINI.md` |
+| **Default model** | `sonnet` | `gpt-5.5` | `gemini-3.5-flash` |
+| **Agent format** | `.claude/agents/<id>.md` with `model:` frontmatter | `.codex/skills/<id>/SKILL.md` Skill format | `.gemini/` command + agent target |
+| **Agent profiles** | Full support (rail `RailProfileSelector`) | **None** — rails force the profile to `null` | **None** — rails force the profile to `null` |
+| **Pipeline rails** | ✅ all rail types | ✅ (except Ultracode) | ✅ (except Ultracode) |
+| **Ultracode rails** | ✅ Claude-only | ❌ rejected (`Ultracode requires the Claude provider`) | ❌ rejected |
+| **Contract Refine** | Claude-only (it `--resume`s the Explore session and runs `/specrails:contract-refine`) | **Skipped** — toggling "Enrich with Contract Layer" is a no-op | **Skipped** |
+| **MCP registration** | Surgical merge of `<project>/.mcp.json` | `codex mcp add` against per-project `CODEX_HOME=~/.specrails/projects/<slug>/codex-home/` (isolated) | Project `.mcp.json` (so Serena-style plugins **do** resolve) |
+| **Session resume** | `--resume <session_id>` | `exec resume <thread_id>` | `--resume` |
+| **Native cost report** | `result.total_cost_usd` from `--output-format stream-json` | None — cost is **estimated** by the app from `turn.completed.usage` and the local pricing table at `server/pricing.ts` | None — **estimated** the same way as Codex |
+| **Telemetry** | `OTEL_EXPORTER_OTLP_*` env vars consumed by claude itself | **Synthesised** by the app from `codex exec --json` events and POSTed to the same in-process OTLP receiver | **Native** OTLP — Gemini honours the same `OTEL_*` env vars Claude does (no synthetic bridge) |
+
+A few Codex-specific behaviours worth calling out:
+
+- **Rail sandbox.** Codex rail jobs spawn with `--sandbox danger-full-access`
+  (not the `workspace-write` sandbox used for one-off `codex exec` runs), so
+  a rail can read and write anywhere in the project. This is intentional —
+  rails need to apply edits across the repo — but it's worth knowing if
+  you're surprised by a rail touching files outside the working tree.
+- **Ultracode rails are Claude-only.** Launching an Ultracode rail on a
+  Codex (or Gemini) engine is rejected with a 400 (`Ultracode requires the
+  Claude provider`). Pick Claude for that rail.
 
 ## Estimated cost
 
@@ -115,9 +153,11 @@ The Analytics page surfaces this in two places:
 - **The Hero** shows a small italic suffix next to the invocation
   count (`· includes ~$X.XX estimated`) when any row in the active
   window came from the fallback.
-- **A new "By provider" card** between the Hero and the Timeline
-  splits per-provider cost into authoritative vs estimated columns
-  whenever the project has invoked both providers.
+- **A "By provider" card** between the Hero and the Timeline splits
+  cost per provider into authoritative vs estimated whenever the project
+  has invoked more than one. Claude rows are authoritative (the CLI
+  reports cost); Codex and Gemini rows are estimated from token counts
+  and the local rate-card.
 
 The pricing table is reviewed quarterly. The reference date sits on
 each entry as `lastReviewedAt`. If OpenAI raises prices mid-quarter,
@@ -125,12 +165,20 @@ ship an out-of-band update to `server/pricing.ts`.
 
 ## Plugins and MCP on codex projects
 
-The **Integrations** (plugins) marketplace is a **Claude-only** capability. The app
-hides the Integrations tab for any project that includes codex — both codex-only and
-dual-provider (Claude + Codex) projects — because the sidebar only shows sections that
-*every* installed provider supports (the capability intersection in
-`provider-capabilities.ts`). So there is no in-app plugins page to install Serena on a
-codex project.
+The **Integrations** section stays **visible** on codex projects — it hosts
+the provider-agnostic **Jira** integration, which works for any provider.
+What's filtered out is the **Serena plugin**: it requires a project-level
+`.mcp.json` registration that Codex doesn't use (Codex registers MCP servers
+via `codex mcp add`, Claude and Gemini use the project `.mcp.json`). So a
+codex-only project still has the Integrations tab and the Jira card, but no
+Serena plugin entry.
+
+> Why: the right sidebar shows the capability intersection (sections every
+> installed provider supports). Only **Agents** is Claude-only; **Integrations**
+> is not. The per-provider filter lives inside the Integrations page
+> (`client/src/pages/IntegrationsPage.tsx`, `showPlugins` requires a
+> Claude-style provider), not in the section-level intersection
+> (`provider-capabilities.ts`).
 
 To give a codex project MCP servers, register them with `codex mcp add` from your
 terminal: codex chat / Explore turns spawn with your own environment and read your global
@@ -170,7 +218,9 @@ spec just commits without a Contract Layer block.
 ## Emergency rollback
 
 If you need to disable the codex path, set `SPECRAILS_CODEX_BETA=0`
-in the app's environment. For a source checkout that's:
+in the app's environment. **Only the exact string `0` disables Codex** —
+`false`, `off`, `1`, or unset all leave it enabled. For a source checkout
+that's:
 
 ```bash
 SPECRAILS_CODEX_BETA=0 npm run dev
@@ -179,10 +229,13 @@ SPECRAILS_CODEX_BETA=0 npm run dev
 For the packaged desktop app, set the variable in the environment the app
 process inherits (the `npm run dev` form is for source runs only).
 
+(Gemini has the same kill switch, `SPECRAILS_GEMINI_BETA=0`, but **no**
+legacy `SPECRAILS_HUB_*` fallback name.)
+
 `GET /api/available-providers` will report `codex: false` and
 `POST /api/projects` will refuse new codex projects. Existing
-codex projects keep functioning — only new-project gating is gated by
-the env var.
+codex projects keep functioning — the env var only gates creating
+*new* codex projects.
 
 ## Architecture pointers (for specrails-desktop developers)
 
@@ -198,13 +251,18 @@ The codex integration lives in:
   with per-project `CODEX_HOME`.
 
 The contract every provider implements is at
-`server/providers/types.ts`. Adding a new provider in the future is
-one new adapter file + one entry in `server/providers/index.ts`.
+`server/providers/types.ts`. Adding a provider is essentially one new
+adapter file + one `register(...)` entry in `server/providers/index.ts`
+(the rest of the codebase is registry-driven and provider-id-agnostic).
+`server/providers/gemini-adapter.ts` is the freshest worked example —
+see [Adding a provider](internals/adding-a-provider.md).
 
 ## See also
 
+- [Using Gemini](gemini.md) — the Gemini CLI provider (the other
+  provider with estimated cost).
 - [Adding a provider](internals/adding-a-provider.md) — the developer
-  guide to wiring a third AI CLI adapter.
+  guide to wiring an AI CLI adapter.
 - [Tracking cost](tracking-cost.md) — how the Analytics page surfaces
   per-invocation cost across every surface (including the estimated
   codex rows described above).

package/docs/creating-specs.md

@@ -1,6 +1,8 @@
 # Creating specs
 
-A **spec** in specrails-desktop is a description of work you want done — what the AI agents will read and act on. This guide walks through every way you can create, refine, compare, and organise them. Specs are engine-agnostic: depending on how the project was set up, they can be generated by Claude or by Codex.
+A **spec** in specrails-desktop is a description of work you want done — what the AI agents will read and act on. This guide walks through every way you can create, refine, compare, and organise them.
+
+Specs are engine-agnostic: depending on how the project was set up, they can be generated by **Claude, Codex, or Gemini** — whichever providers you installed for the project. The flows below are identical no matter which one you use; only the engine picker and the default model differ.
 
 ## Creating a spec
 
@@ -10,7 +12,7 @@ Open the Dashboard and click **Add** (the Plus button on the SpecsBoard toolbar)
 - **Explore** — you converse with the AI and shape the spec turn by turn.
 - **Raw** — your prompt is saved verbatim as a spec, with **no AI** involved.
 
-On a multi-provider project (one set up with both Claude and Codex), an **AI engine** selector sits at the top of the dialog so you can pick which engine generates this spec. The choice is remembered per project. Single-provider projects don't show the selector.
+If the project has **more than one provider installed** — any combination of Claude, Codex, and Gemini — an **AI engine** selector sits at the top of the dialog so you can pick which engine generates this spec. The choice is remembered per project. Projects with a single provider don't show the selector; it would have nothing to choose between.
 
 ### Quick mode
 
@@ -53,9 +55,11 @@ For when the spec needs shaping. You converse with the AI; a live draft updates
 
 Rich and Max both load the full codebase — they differ only in whether the Contract Layer pass runs. The decision is per-conversation (saved on `chat_conversations.context_scope`) so it doesn't bleed into other Explore sessions.
 
+The **Desktop** preset is Explore-only — Quick mode caps the slider at **Max** (no project/approved MCPs), as noted under [Quick mode](#quick-mode) above.
+
 Click **Fine-tune** to set the flags individually. One toggle only appears here:
 
-- **My approved MCPs** — loads the MCP servers you've already approved locally (`claude mcp add` / `codex mcp add`) without changing where the spawn runs. Explore-only; disabled in Quick mode.
+- **My approved MCPs** — loads the MCP servers you've already approved locally (`claude mcp add` / `codex mcp add`) without changing where the spawn runs. Explore-only; disabled in Quick mode. On a **Gemini** project, Gemini reads your own approved MCP servers from its native config (`~/.gemini`) automatically, so this toggle isn't needed there.
 
 **Buttons in the shell:**
 
@@ -120,7 +124,7 @@ Got an epic that's clearly too big? Open it and click **SMASH Spec into Sub-Spec
 
 - Gets `parent_epic_id` pointing back at the epic.
 - Carries an execution order (the SMASH agent decides the right order).
-- Carries a short summary (the agent aims for roughly 120 characters) surfaced on its postit card.
+- Carries a short summary surfaced on its postit card. The agent is asked to keep it to ~120 characters; the server hard-caps it at 240 characters as a safety net.
 
 Inside the epic's modal you'll see an **Epic Family Sidebar** listing all children. Inside each child's modal, an **Epic Breadcrumb** lets you jump back to the parent. If the epic already has children, the button reads **Re-SMASH** and regenerates the family (after a confirmation).
 
@@ -152,13 +156,20 @@ Every spec card shows a status indicator that stays consistent across view modes
 
 ## Filtering and sorting
 
-The SpecsBoard toolbar has four controls plus the Add button:
+The SpecsBoard toolbar always shows these four controls plus the Add button:
 
 - **Status filter** — a single-select dropdown with three values: **All**, **ToDo**, **Done**. Defaults to **All**, which shows everything (including drafts and done specs).
 - **Label dropdown** — multi-select across every label used in the project.
 - **Sort** — **Default**, **Ticket #**, or **Priority**, each with an ascending/descending toggle.
 - **View toggle** — switch between List view and Post-it view (see below).
 
+Two more filters appear **only once your board has the data for them**, so don't be surprised if you see five or six controls. Both are surfaced only on **Jira-linked** projects:
+
+- **Epic filter** — appears once at least one spec carries a Jira epic, letting you narrow the board to one epic's children.
+- **Sprint filter** — appears when specs carry Jira sprint data.
+
+On a **Jira-linked** project the Sort dropdown also gains a fourth mode, **Jira key**, so you can order the board by Jira ticket number.
+
 Priority itself is set per spec from the right-click menu (below), not from a toolbar filter — there is no priority filter and no search box on the board.
 
 ## Right-click context menu
@@ -169,6 +180,8 @@ Right-click any spec card (in any view mode):
 - **Change status → Todo / Done**
 - **Set priority → Critical / High / Medium / Low**
 
+On a **Jira-backed** spec the first item changes from **Delete ticket** to **Move to `<status>`** (which transitions the linked Jira issue) with a separate **Discard** flow, since a Jira-backed spec can't simply be deleted locally.
+
 ## View modes
 
 The SpecsBoard has **two** view modes, switched from a toolbar toggle and remembered per project:
@@ -195,3 +208,4 @@ You don't need this to use the feature, but it's nice to know:
 - [Running pipelines](running-pipelines.md) — drag those specs onto rails and launch the implementation pipeline.
 - [Tracking cost](tracking-cost.md) — see what each spec is costing you.
 - [Customising the app](customizing.md) — set a daily budget so you can stop worrying.
+- [Using Codex](codex.md) / [Using Gemini](gemini.md) — provider-specific notes if you generate specs with Codex or Gemini.

package/docs/customizing.md

@@ -59,7 +59,7 @@ Open **Settings** from the project navbar (top right of any project page).
 | **Daily budget (USD)** | The queue auto-pauses when this project's spend for the current calendar day exceeds the cap. Blank = no cap. |
 | **Per-job cost alert (USD)** | OS notification when a single job in this project exceeds this amount. Blank = disabled. |
 
-The daily counter is the sum of completed-job cost since midnight, so it resets at the start of each calendar day. When the cap is hit you see a "Daily budget exceeded — Queue is paused" banner on the project (plus a toast). Resume by raising or clearing the budget (and waiting for the next day if you've genuinely spent it).
+The daily counter is the sum of completed-job cost since midnight, so it resets at the start of each calendar day. When the cap is hit you see a "Daily budget exceeded — spent $X of $Y. Queue is paused." banner on the project (plus a toast). Resume by raising or clearing the budget (and waiting for the next day if you've genuinely spent it).
 
 ### Rail pre-prompt
 
@@ -109,6 +109,8 @@ Open **Desktop Settings** from the Arc sidebar. These apply across every project
 | Section | What it does |
 |---------|--------------|
 | **Appearance** | Theme picker — see above. |
+| **Language** | UI language picker. Eight locales (English, Spanish, French, German, Portuguese, Italian, Chinese, Japanese). Hot-switches the whole app — no restart. First run follows your OS language until you pick one explicitly. |
+| **Code section** | Defaults for the Code section: the plain-language file-summary language (English or Spanish) and a monthly summary budget cap in USD. Hidden when the Code section is disabled. |
 | **Registered Projects** | The project registry. Re-resolve, rename, or remove projects. |
 | **specrails-tech** | Base URL for the external specrails-tech agents service (default `http://localhost:3000`). |
 | **Budget & Alerts** | App-wide daily budget (a global spend cap across all projects — queues auto-pause when exceeded) plus a per-job cost alert threshold. Distinct from the per-project budget. |
@@ -126,26 +128,41 @@ On first run the app generates a token and persists it to `~/.specrails/desktop.
 
 The app binds to `127.0.0.1` only, so it's never exposed to your network. To rotate the token, stop the app, delete `~/.specrails/desktop.token`, and start it again — a fresh token is generated on the next boot.
 
+## Providers
+
+The app works with **three interchangeable AI providers — Claude, Codex, and Gemini — all enabled by default.** When you add a project you pick which provider(s) to install (you can install any subset; the first one becomes the project's default). The engine pickers on Add Spec, the rail header, and the terminal's "Open AI CLI" button appear automatically whenever more than one provider is installed.
+
+You normally don't configure anything here — providers are selected per project in the UI. The only knobs are the **emergency rollback** env vars below (one per provider), which force a provider back to "unavailable" without redeploying. See [codex.md](codex.md) and [gemini.md](gemini.md) for each provider's setup, auth, and limitations.
+
 ## Environment variables
 
 Most settings live in the UI. A few app-level switches are env-only because they're guardrails ops people want to flip without opening the dashboard.
 
+> **How values are read** (the rules differ by flag type):
+> - **Section gates** (`SPECRAILS_*_SECTION`, `SPECRAILS_TERMINAL_PANEL`, `SPECRAILS_CODE_EXPLORER`, …) are ON unless set to the **exact string `false`**.
+> - **Provider rollbacks** (`SPECRAILS_CODEX_BETA`, `SPECRAILS_GEMINI_BETA`) disable on the **exact string `0`** only — `false`/`off` do *not* disable them.
+> - **Kill switches** (`SPECRAILS_SMASH`, `SPECRAILS_EXPLORE_CONTRACT_REFINE`) accept `0` / `false` / `off`.
+> - **Opt-in hatches** (`SPECRAILS_EXPLORE_LEGACY_CWD`, `SPECRAILS_ALLOW_LOCAL_WEBHOOKS`) enable on the **exact string `1`**.
+
 ### Server-side (read at app startup or by spawned children)
 
 | Variable | Effect |
 |----------|--------|
-| `SPECRAILS_CORE_BIN` | Override the `specrails-core` binary (default: `npx --yes --prefer-online specrails-core@latest`) |
+| `SPECRAILS_CORE_BIN` | Override the `specrails-core` binary (default: `npx --yes --prefer-online specrails-core@^4.8.0` — the 4.8.0 floor is the release that ships the Gemini provider target) |
 | `SPECRAILS_TECH_URL` | Override the specrails-tech proxy base URL |
 | `SPECRAILS_AGENTS_SECTION=false` | Hide the Agents section from every project |
 | `SPECRAILS_PLUGINS_SECTION=false` | Hide the Integrations section from every project |
+| `SPECRAILS_JIRA_SECTION=false` | Hide the Jira integration and 404 its routes |
 | `SPECRAILS_TERMINAL_PANEL=false` | Disable the bottom terminal panel everywhere |
-| `SPECRAILS_CODE_EXPLORER=false` | Disable the read-only Code section server-side |
+| `SPECRAILS_CODE_EXPLORER=false` | Disable the Code section server-side |
+| `SPECRAILS_INTERACTIVE_JOBS=false` | Reject the interactive-ultracode toggle and the per-job message/finalize routes |
 | `SPECRAILS_BROWSER_CAPTURE=false` | Disable Add-Spec-from-browser capture |
-| `SPECRAILS_CODEX_BETA=0` | Emergency rollback — disable the Codex provider (legacy `SPECRAILS_HUB_CODEX_BETA` still honoured as a fallback) |
+| `SPECRAILS_CODEX_BETA=0` | Emergency rollback — disable the Codex provider (only the exact string `0`; the legacy `SPECRAILS_HUB_CODEX_BETA` is read as a fallback **only when `SPECRAILS_CODEX_BETA` is unset**) |
+| `SPECRAILS_GEMINI_BETA=0` | Emergency rollback — disable the Gemini provider (default unset = enabled; only the exact string `0` disables; **no legacy fallback name**) |
 | `SPECRAILS_SMASH=0` | Kill switch for SMASH spec decomposition (`0` / `false` / `off`; endpoints return 409) |
 | `SPECRAILS_EXPLORE_CONTRACT_REFINE=0` | App-wide kill switch for Contract Refine (auto-fire + retry endpoint; accepts `0` / `false` / `off`) |
 | `SPECRAILS_EXPLORE_LEGACY_CWD=1` | Force Explore spawns to use the project root instead of the app-managed `explore-cwd/` |
-| `SPECRAILS_FILE_SUMMARY_MODEL` | Override the model used for Code-section file summaries |
+| `SPECRAILS_FILE_SUMMARY_MODEL` | Override the model used for Code-section file summaries. Per-provider overrides take precedence: `SPECRAILS_FILE_SUMMARY_MODEL_CLAUDE` (Claude) and `SPECRAILS_FILE_SUMMARY_MODEL_CODEX` (Codex); the generic var is the fallback |
 | `SPECRAILS_ALLOW_LOCAL_WEBHOOKS=1` | Allow outbound webhooks to target loopback / private-network addresses |
 
 ### Client-side (Vite — set at build time)
@@ -156,7 +173,9 @@ These feature flags are **default ON**. Set the flag to `false` to hide the feat
 |----------|--------|
 | `VITE_FEATURE_TERMINAL_PANEL=false` | Hide the bottom terminal panel |
 | `VITE_FEATURE_AGENTS_SECTION=false` | Hide the Agents section |
-| `VITE_FEATURE_CODE_EXPLORER=false` | Hide the read-only Code section |
+| `VITE_FEATURE_CODE_EXPLORER=false` | Hide the Code section |
+| `VITE_FEATURE_JIRA=false` | Hide the Jira integration UI (settings section + spec badges) |
+| `VITE_FEATURE_INTERACTIVE_JOBS=false` | Hide the interactive-ultracode UI (rail "Interactive" toggle + in-job chat + Finalize) |
 | `VITE_FEATURE_EXPLORE_REVIEW=false` | Disable the Review step in the Explore shell |
 | `VITE_FEATURE_EXPLORE_PREMIUM_UX=false` | Disable the "Conectando…/Pensando…/Consultando código…" pills above the Explore streaming bubble |
 
@@ -164,6 +183,8 @@ These feature flags are **default ON**. Set the flag to `false` to hide the feat
 
 Set them in the shell that launches the app. Desktop app users can set them in their shell rc files since the desktop app inherits the launchd PATH and env.
 
+> **Not env vars:** a few `SPECRAILS_*` names you might spot in the source are *not* settings you can flip. `SPECRAILS_DIR` is a code constant; `SPECRAILS_PROFILE_PATH`, `SPECRAILS_PLUGINS_ACTIVE`, and `SPECRAILS_PLUGINS_SNAPSHOT` are values the app injects *into* the AI CLI it spawns. Setting them yourself has no effect. The desktop-only `SPECRAILS_IS_DESKTOP` / `SPECRAILS_BUNDLED_RUNTIMES_PATH` are set by the packaged app, never by you.
+
 ## Resetting the app
 
 To wipe all app state (project registry, settings, theme) but keep your project source code intact: