specrails-desktop 2.8.0 → 2.9.1

package/docs/guide/en/insights/2-the-integrated-terminal.md

@@ -0,0 +1,46 @@
+# The integrated terminal
+
+Specrails has a real terminal built right in — the panel that slides up from the bottom of the window, just like the one in VS Code or Cursor. It runs your actual shell, in your actual project directory, so you can run `git`, `npm`, tests, or anything else without leaving the app.
+
+## Opening and closing it
+
+The fastest way is the keyboard: **Cmd+J** (macOS) or **Ctrl+J** (Windows/Linux) toggles the panel open and closed, and focuses the terminal the moment it appears so you can start typing immediately. You can also use the chevron in the status bar.
+
+The panel has three states:
+
+- **Hidden** — tucked away.
+- **Restored** — the normal split-height panel.
+- **Maximized** — taking over the work area when you need room to read output.
+
+Minimizing the panel (the chevron) does **not** stop anything — your shells keep running in the background. The only thing that actually ends a session is closing it (the trash icon, or the per-tab ✕).
+
+## Multiple sessions
+
+You can run several terminals at once in the same project — up to ten. Each gets its own tab; you can rename them so "dev server" and "tests" don't get confused. They all start in your project folder and load your shell profile (`.zshrc`, `.bashrc`, and so on), so your aliases and PATH are exactly what you'd expect.
+
+Here's the important part: your terminals **survive switching projects and tabs**. Specrails keeps each session alive and intact behind the scenes — scrollback, running processes, everything — so flipping over to Analytics and back doesn't reset your shell or interrupt a long-running command. Sessions only end when you explicitly close them (or when you remove the whole project).
+
+## Per-project, remembered
+
+Whether the panel is open, how tall you've dragged it, which tabs exist — all of that is remembered **per project**. Come back to a project and it's set up the way you left it.
+
+## The premium features
+
+This isn't a bare-bones console. The terminal ships with the niceties you'd want from a first-class one:
+
+- **Fast, crisp rendering** via WebGL (with an automatic fallback so it never breaks), full Unicode width handling, and font ligatures.
+- **Search your scrollback** with **Cmd+F** — great for finding that error buried 500 lines up.
+- **Font zoom** with **Cmd+=**, **Cmd+-**, and **Cmd+0** to reset.
+- **Clipboard shortcuts** — Cmd+C / Cmd+V to copy and paste, Cmd+K to clear — plus a right-click context menu.
+- **Drag-and-drop file paths** (in the desktop app): drop a file onto the terminal and its path is inserted, correctly quoted for your shell.
+- **Smooth resizing** — dragging the panel height or collapsing the sidebar won't make the output jitter.
+- **Inline images** — terminals that emit Sixel or iTerm2-style images render them right in place.
+- **Shell integration** — Specrails knows where each command starts and ends, so it can track your command history and notify you when a long-running command finishes (a desktop notification, with a browser fallback). If your shell can't be instrumented for some reason, it degrades quietly and tells you once.
+
+## Settings
+
+Terminal preferences live in two layers: an app-wide default and an optional per-project override. The per-project setting wins when present, so you can keep a global look-and-feel while tweaking one project that needs something different.
+
+## Turning it off
+
+The terminal is on by default. If you'd rather not have it, it can be disabled via the `VITE_FEATURE_TERMINAL_PANEL` (client) or `SPECRAILS_TERMINAL_PANEL` (server) flags — set either to `false`. Most people will simply leave it on.

package/docs/guide/en/insights/3-code-explorer.md

@@ -0,0 +1,50 @@
+# Code explorer
+
+The **Code** section gives you a friendly, read-only window into your repository — designed especially for people who want to understand what the AI has been building without living in an editor. You get a file tree on the left, a code viewer on the right, and, above the code, a plain-language summary of what each file actually does.
+
+It's strictly read-only in this version: nothing you do here changes your files. Think of it as a reading room, not a workshop.
+
+Open it from the right sidebar (**Code**), and like everything else it's scoped to your current project.
+
+## The file tree
+
+The left pane is a virtualised tree of your project's files — fast even on large repos. It respects your `.gitignore` and a built-in deny-list, so you see the files that matter, not a sea of build artifacts and `node_modules`.
+
+Next to files you'll notice **provenance chips** — little markers that tell you a file was *touched by AI*. This is the heart of the Code explorer: Specrails records which files each pipeline job created or modified, and ties them back to the ticket that prompted the work. So you can answer, at a glance, "did the AI write this, or did I?"
+
+At the top of the tree there's a filter:
+
+- **Tocado por IA / Touched by AI** (the default) — only files the AI has changed.
+- **All files** — the full tree.
+
+Your choice is remembered per project, so if you mostly care about AI-authored changes you'll see them first every time.
+
+## The code viewer
+
+Click a file and it opens in a full-featured viewer (powered by Monaco, the same engine as VS Code) with proper syntax highlighting that matches your chosen app theme. A few sensible limits keep things smooth: binary files are politely refused, and very large files (over 2 MB) won't load.
+
+Your current file is saved in the page URL, so you can bookmark or share a link straight to a specific file.
+
+Since editing isn't part of this version, the viewer offers an **Edit in external editor** button that copies the file's absolute path — paste it into your editor of choice and pick up there.
+
+## AI summaries
+
+Above the code you'll see a **plain-language summary** of the file — what it's for, what it does — written so a non-developer can follow along. These are generated for you and cached, so opening a file you've looked at before is instant.
+
+Summaries are smart about staying fresh: they're keyed to the file's contents, so when a file genuinely changes the summary is regenerated, but unchanged files don't get re-summarised needlessly. If you edit a file yourself, its summary is marked as stale rather than silently regenerated — you stay in control of when it's refreshed. There's a **regenerate** action when you want a fresh take on demand.
+
+A couple of guardrails keep costs sane: summary generation runs within a **monthly budget** (a few dollars by default, configurable in Settings), and there are caps on how many summaries a single job will kick off. If a summary is skipped, the app tells you why — budget reached, a per-job cap, or the file simply not being found.
+
+You can also choose the **summary language** (English or Spanish) in the global settings under the *Code section* area.
+
+## Connecting code back to specs
+
+The provenance link runs both ways. Inside the Code explorer, clicking a ticket chip on a file opens that ticket's detail. And from the other direction, the **ticket detail** view has a *Files touched by this ticket* section — click a file there and you jump straight into the Code explorer with it open. It closes the loop between "here's the spec we wrote" and "here's the code that came out of it."
+
+## What it doesn't do (yet)
+
+To set expectations clearly, this first version intentionally leaves a few things out: in-app editing, per-symbol or directory-level summaries, a narrative diff view, and conversational "ask the AI about this file." Provenance attributes a file to its primary ticket only. These are the kinds of things that may grow over time.
+
+## Turning it off
+
+The Code explorer is on by default. It can be disabled with the `VITE_FEATURE_CODE_EXPLORER` (client) or `SPECRAILS_CODE_EXPLORER` (server) flags — set either to `false`. Turning it off leaves all your recorded data and summaries safely on disk, untouched, in case you switch it back on.

package/docs/guide/en/integrations/1-ai-providers.md

@@ -0,0 +1,64 @@
+# AI providers (Claude, Codex, Gemini)
+
+Specrails isn't tied to a single AI. Every part of the app that talks to an AI — Explore Spec, Quick spec, rails, chat, AI Edit, the terminal's "Open AI CLI" button — can run through any of three first-class providers. You pick which ones a project uses, and you can even switch on a per-task basis.
+
+## The three providers
+
+| Provider | CLI | Made by | Notes |
+|---|---|---|---|
+| **Claude** | `claude` | Anthropic | The most fully featured. The only provider for Agents (profiles) and Ultracode rails, and for Contract Refine. |
+| **Codex** | `codex` | OpenAI | Needs codex `0.128.0+`. Reads its MCP servers from your global `~/.codex/config.toml`. |
+| **Gemini** | `gemini` | Google | Needs gemini `0.11.0+`. Uses native telemetry and a `GEMINI.md` instructions file. |
+
+All three are **enabled by default**. A provider shows up in **Add Project** whenever its CLI is installed and on your `PATH`. So the first step is always the same: install the CLI you want and log in with it, exactly as that tool's own docs describe. Once `claude --version` (or `codex`, or `gemini`) works in your terminal, Specrails can use it.
+
+## Installing one provider for a project
+
+When you add a project, the setup wizard asks which provider(s) to install. Pick one, click through the install step, and you're done. From there on the project just *has* that provider — you never have to think about it again. Specs, rails, chat, and analytics all work the same regardless of which one you chose.
+
+If a CLI you want isn't offered in Add Project, it's almost always because the CLI isn't installed or isn't on your `PATH`. Install it, then reopen Add Project.
+
+## Installing several providers for one project
+
+You can install **more than one** provider into the same project — for example Claude *and* Gemini. In **Add Project**, the provider list becomes a set of checkboxes; tick everything you want. The first one you select becomes the project's **primary** (default) provider; the rest are available as alternatives.
+
+A few things worth knowing about multi-provider projects:
+
+- **One provider behaves exactly like before.** If a project has just a single provider, you'll never see a provider picker anywhere — the app stays clean and simple.
+- **The right sidebar only shows sections every installed provider supports.** Because Agents (profiles) is a Claude-only concept, the **Agents** section disappears the moment a project includes any non-Claude provider. Everything else (Specs, Code, Analytics, Integrations, Terminal, Chat) stays.
+- **Provider choice is locked after creation.** In this version you choose your providers when you add the project and they can't be changed later from Settings. If you need a different mix, that's a fresh project.
+
+## Picking a provider per invocation
+
+The real payoff of a multi-provider project is choosing the right AI for each task — without changing any global setting. Wherever an AI runs, a small provider picker appears (only when the project has more than one):
+
+- **Add Spec** — an engine selector lets you Explore or Quick-generate a spec with whichever provider you like.
+- **Rail header** — pick the engine for that specific rail before launching it.
+- **Terminal** — the "Open AI CLI" (Sparkles) button opens a provider menu so you can drop into any installed CLI in that project's directory.
+
+Your choice is remembered per project, defaulting to the primary provider, so you don't have to re-pick every time.
+
+## What only Claude can do
+
+A handful of features are Claude-specific by nature, so they're either hidden or skipped when another provider is in play:
+
+- **Agents (profiles)** — the per-project agent catalog and model routing. Hidden on any project that includes a non-Claude provider.
+- **Ultracode rails** — always run on Claude.
+- **Contract Refine** — the extra "Contract Layer" pass on a committed spec runs only when the conversation's provider is Claude.
+- **Add Spec advanced modes** (SMASH / Contract Layer) — hidden for non-Claude engines.
+
+Everything else — Explore, Quick spec, the full rails pipeline, AI Edit, chat, cost analytics — works across all three.
+
+## Cost tracking across providers
+
+The **Analytics** page tracks every billable invocation regardless of provider. On multi-provider projects it adds engine filter chips so you can compare spend by provider. Claude reports its own exact cost; for Codex and Gemini, Specrails estimates cost from a built-in rate card, so the numbers are close approximations rather than billed amounts.
+
+## Troubleshooting
+
+- **A provider I installed isn't offered.** Confirm the CLI is on your `PATH` (try `claude --version` / `codex --version` / `gemini --version` in a fresh terminal). The app probes provider CLIs through your system `PATH`.
+- **Codex MCP servers aren't loading in chat.** Codex reads MCP servers from your global `~/.codex/config.toml` — register them there with `codex mcp add`.
+- **Emergency disable.** A provider can be turned off app-wide via an environment variable (`SPECRAILS_CODEX_BETA=0` or `SPECRAILS_GEMINI_BETA=0`). This only hides the provider from *selection*; it's rarely needed.
+
+## See also
+
+The dedicated provider guides go deeper on each CLI: the Codex guide and the Gemini guide each cover setup, what works, and provider-specific quirks.

package/docs/guide/en/integrations/2-plugins.md

@@ -0,0 +1,44 @@
+# Plugins (Integrations)
+
+The **Integrations** section is a per-project marketplace of optional add-ons that extend what the AI can do. Each project decides independently which plugins it wants — installing a plugin in one project never touches another.
+
+Plugins work by quietly registering an **MCP server** (Model Context Protocol) into your project, giving the AI new tools to call during rails and chat. You don't have to understand MCP to use them — install, and they're available the next time a rail runs.
+
+## What's available today
+
+This version ships **bundled-only**: the plugins you can install are the ones built into the app. There's no remote registry, no user-uploaded plugins, and no third-party code loading — so everything in the catalog is vetted and shipped with Specrails.
+
+The headline plugin is:
+
+- **Serena** — semantic code navigation. It gives the AI language-server-backed understanding of your codebase (jump-to-definition, find references, symbol-aware search) instead of plain text matching. Great for larger or unfamiliar repos where you want the agent to reason about real symbols.
+
+  Serena requires the `uv` tool on your `PATH` (it runs via `uvx`). The app auto-detects whether `uv` is present and tells you if it's missing.
+
+## Installing a plugin
+
+1. Open **Integrations** from the right sidebar.
+2. Find the plugin in the catalog. Each card shows a status: **Not installed**, **Installed**, **Degraded**, or **Orphan**.
+3. Click into the plugin to **preview the install** — this shows you exactly what files will change before anything happens.
+4. Click **Install**. You'll see live progress as it sets up.
+
+Under the hood the install is *surgical and additive*: it only adds its own entries to your project's `.mcp.json` (and, for some plugins, a fragment file in the protected `.claude/agents/` namespace). It never rewrites your config wholesale, and adding a second plugin can never disturb the first. If the install can't verify itself as healthy, it rolls back cleanly.
+
+## Managing installed plugins
+
+- **Health.** Each plugin has an on-demand health check. A plugin that installs fine but later can't start up is marked **Degraded** — it won't block your rails, you'll just see the badge and a reason.
+- **Uninstall.** Removing a plugin surgically deletes only the entries it owns, leaving the rest of your config untouched.
+- **Orphans.** If a plugin's files are left behind without proper state (for example after an interrupted change), it shows as an **Orphan** and you can clean it up with one click.
+
+## How plugins show up in your work
+
+- **Rails.** Before a rail runs, Specrails checks which plugins are installed and healthy, and makes those tools available to the agent for that job. A degraded plugin is simply skipped for that run — the rail still launches normally. Each job records a snapshot of which plugins were active, which you can see in the job's diagnostic export.
+- **Chat.** Chat automatically picks up your project's MCP config, so installed plugins are available there too.
+- **Setup.** Plugins are ignored while a project is still being set up — they come into play once the project is ready.
+
+## Provider notes
+
+Plugins are provider-aware. Serena and similar MCP plugins resolve for providers that register MCP through the project's `.mcp.json` (Claude and Gemini). For Codex projects, MCP servers are managed through Codex's own global config instead, so plugin entries in **Integrations** are filtered accordingly. The Jira card in Integrations is provider-agnostic and shows for everyone — see the Jira guide.
+
+## Reserved files
+
+Plugins manage a small, well-defined set of files in your project: your `.mcp.json` (merged surgically), some state under `.specrails/plugins/`, and per-plugin agent fragments at `.claude/agents/custom-<plugin>.md`. These are committable team assets if you want to share an integration with your teammates — the app never blindly overwrites them.

package/docs/guide/en/integrations/3-jira-integration.md

@@ -0,0 +1,71 @@
+# Jira integration
+
+Want your specs to live on a real **Jira board** instead of inside Specrails? The Jira integration backs a project's specs with Jira issues, keeps statuses in sync as rails run, and stays out of the way the rest of the time. Each project syncs with **its own** Jira board.
+
+## How it works (the short version)
+
+Specrails acts as a **sync layer** between Jira and your project. The big idea: your local spec store stays the canonical thing the pipeline reads, and Specrails is responsible for keeping it and Jira in agreement.
+
+- When you launch a rail, Specrails moves the linked Jira issue to **In Progress**.
+- When a job finishes, Specrails transitions the issue (to **Done**, or back to **To Do** if it failed) and posts a completion comment with the job id, cost, and duration.
+- Periodically Specrails **polls** Jira for changes anyone made on the board and reflects them back into your specs.
+
+All write-backs go through a durable, crash-safe outbox, so a momentary Jira hiccup never breaks a job — the update just retries.
+
+## Connecting a board
+
+You connect from a project's **Settings** page (there's also an optional "Configure Jira" step at the end of the Add-Project wizard). The connect wizard walks you through:
+
+1. **Test** — enter your Jira URL and credentials, and Specrails verifies the connection.
+2. **Pick a project** — choose which Jira project to sync with.
+3. **Status map (optional)** — map your Jira workflow statuses onto Specrails' states if the automatic detection needs a hand (more below).
+4. **Connect** — done. Your specs now mirror that board.
+
+### Authentication
+
+This version uses **token-paste** auth — quick, on-device, and with no backend involved:
+
+- **Jira Cloud:** your account email plus an API token.
+- **Jira Data Center / Server:** a Personal Access Token (PAT).
+
+Your token is stored **encrypted on your own machine** and never leaves it. The app shows only whether a token is present, never the token itself.
+
+## Status mapping
+
+The trickiest part of any Jira sync is matching *your* workflow to Specrails' simple states (To Do / In Progress / Done, plus cancel/ship variants). Specrails resolves this in two tiers:
+
+1. **Your explicit status map**, if you set one in the wizard — always wins.
+2. **Automatic detection** from each status's category (new / in-progress / done) plus smart matching for cancel and ship-style statuses.
+
+When it needs to move an issue across a workflow that has gated transitions, it finds a valid path step by step and fills in any required fields (like a resolution) along the way. If a status genuinely can't be reached, the operation is parked as a dead-letter and surfaced to you rather than silently failing — you'll see a **degraded** indicator and can retry.
+
+## Hot-swap: turn it on and off safely
+
+The Jira link is **per spec**, captured at the moment you launch a rail — not a global, all-or-nothing switch on the board. That makes it safe to toggle:
+
+- **Enabling or disabling** the integration never re-homes your existing specs.
+- **Disconnecting** restores your project to normal local-spec behavior.
+- Specs that already have a Jira link keep their write-back; specs that don't are left alone.
+
+So you can experiment freely — flip it on, run a few rails, flip it off — without scrambling your board or your local specs.
+
+## Day-to-day
+
+Once connected, the project's Settings page shows a **connected card** where you can:
+
+- **Sync now** — force an immediate poll instead of waiting for the timer.
+- **Retry dead-letters** — re-run any write-backs that got stuck.
+- **Hot-swap toggle** — temporarily pause/resume the integration.
+- **Disconnect** — cleanly detach the board.
+
+Specs backed by Jira show a **Jira key badge** (like `PROJ-123`) on their card, and clicking through links back to the issue. You'll also get small notifications when a sync completes, when an auth token expires (so you can refresh it), or when the integration enters a degraded state.
+
+## Things to keep in mind
+
+- **Polling, not webhooks.** Because Specrails runs locally, it polls Jira for inbound changes rather than receiving push notifications. Changes appear within the poll interval, not instantly.
+- **One board per project.** Different projects can sync with different boards; a single project syncs with exactly one.
+- **Last-write-wins on conflicts** for the rare case where two tabs edit the same draft simultaneously.
+
+## Turning it off
+
+If you ever want to fully back out, just **Disconnect** from Settings. Your specs return to local-only behavior, and the Jira metadata simply sits unused — nothing is destroyed.

package/docs/guide/en/integrations/4-mobile-companion.md

@@ -0,0 +1,38 @@
+# The mobile companion
+
+Specrails has a companion phone app so you can keep an eye on your rails while you're away from your desk — watch jobs run, see them finish, and stay in the loop without sitting in front of the dashboard.
+
+## What it's for
+
+The companion is a **monitoring** surface. It connects to your running Specrails desktop app over your local network and mirrors live project and job activity to your phone. Think of it as a glanceable window into the same rails you'd otherwise watch on the dashboard.
+
+## Pairing your phone
+
+Pairing is built around a **QR code** so you don't have to type anything fiddly:
+
+1. Make sure your desktop Specrails app is running and your phone is on the **same local network** (same Wi-Fi).
+2. In the desktop app, open the pairing screen to display a QR code.
+3. In the companion app on your phone, scan that code.
+4. The phone discovers the desktop app on the network and connects.
+
+From then on the companion keeps a live connection and streams project lists and job updates as they happen.
+
+## How the connection works
+
+The desktop app advertises itself on your local network so the phone can find it, and the QR code carries the details the phone needs to connect securely. Everything stays on your local network — the companion talks directly to your machine, not through any cloud service.
+
+Because it's local-network based, the two devices need to be reachable to each other. If pairing doesn't take:
+
+- Confirm both devices are on the **same Wi-Fi** (and that the network doesn't isolate clients from each other).
+- Make sure the desktop app is **running** when you scan.
+- Re-open the pairing screen to refresh the QR code and try scanning again.
+
+## What you'll see
+
+Once paired, the companion surfaces your projects and their live job activity, so you get the same real-time rail updates that flow into the desktop dashboard — pushed to your phone as they occur. It's the easiest way to know the moment a long-running rail wraps up.
+
+## Good to know
+
+- **Monitoring first.** The companion is designed for keeping tabs on rails, not for driving the full desktop workflow from your phone.
+- **Local only.** No account, no cloud relay — your machine and your phone, on your network.
+- **Keep the desktop awake.** The companion mirrors a running desktop app; if your machine sleeps or the app closes, live updates pause until it's back.

package/docs/guide/en/pipeline/1-rails-and-jobs.md

@@ -0,0 +1,94 @@
+# Rails & jobs
+
+You've got specs on the board. This is where they turn into code. A **rail** is the lane that drives a spec through the full pipeline — Architect → Developer → Reviewer → Ship — running real AI agents inside your project directory. This page covers launching a rail, the job queue, and watching the work happen live.
+
+## What a rail is
+
+Think of your screen split in two:
+
+```
+SpecsBoard (left)            Rails (right)
+─────────────────            ─────────────────
+#1 Login flow      ─┐
+#2 Webhook retry    │  drag onto
+#3 Cost limits      │ ────────────►   Rail 1   ▶ Play
+#4 Audit log        │
+                    └────────────►   Rail 2   ▶ Play
+```
+
+A rail is an **execution lane**. You drag a spec card from the SpecsBoard onto a rail, then press **▶ Play**. The rail launches the pipeline and works the spec end to end, right in your project's working directory — editing files, running tests, the works.
+
+You can have several rails to organise work into named lanes (one for the feature you're focused on, another queued behind it). More on multi-rail and batching in [Batch implement & multi-feature](batch-implement-and-multi-feature).
+
+## Launching a rail on a spec
+
+1. **Drag a spec card** from the SpecsBoard onto a rail. The spec's ID shows up in the rail's spec list. (Prefer not to drag? Use the **Move to rail** popover on the spec card — it shows a status dot per rail so you don't drop work onto a busy lane.)
+2. **Pick a mode** if you want something other than the default — the segmented control in the rail header offers `Implement`, `Batch`, and (Claude rails only) `Ultra`.
+3. **Press ▶ Play.**
+
+That's it. The rail spins up an AI CLI process in your project and starts the pipeline.
+
+### What's in a rail header
+
+| Control | What it does |
+|---------|--------------|
+| **Status pill** | `idle`, `running`, or `failed`. There's no separate "completed" — a rail returns to `idle` when its job finishes cleanly. |
+| **Spec list** | The IDs assigned to this rail. Drag more in, drag them out to detach. |
+| **Mode control** | `Implement` / `Batch` / `Ultra` — see the table below. Persisted per rail. |
+| **Profile picker** | Which agent profile runs (Claude rails only). Only appears once the project has at least one profile. |
+| **Engine selector** | Which installed provider runs this rail — Claude, Codex, or Gemini. Only renders when the project has more than one provider. See [Picking an engine per rail](picking-an-engine-per-rail). |
+| **▶ Play / ■ Stop** | Start or cancel. |
+
+### The three rail modes
+
+| Mode | Command | What it does |
+|------|---------|--------------|
+| **Implement** | `/specrails:implement` | One job covering all specs on the rail. Runs the full Architect → Developer → Reviewer → Ship pipeline. The everyday default. |
+| **Batch** | `/specrails:batch-implement` | One job that works through the rail's specs sequentially, in dependency-aware waves. Best for several related specs. |
+| **Ultra** | Ultracode | Claude implements each spec autonomously, **bypassing** the pipeline. One independent job per spec. Claude only. |
+
+Ultra is the odd one out: it skips the agent chain and hands Claude the raw spec to work on with its native tools. It's open-ended, so pressing Play opens a confirmation first, and a per-rail model picker lets you choose Haiku / Sonnet / Opus. It only appears when the rail's engine is Claude.
+
+## The job queue
+
+Every time you press Play, the rail run becomes a **job**. The most important rule to internalise:
+
+> **One job at a time, per project.** Each project has a single queue. Within one project only one rail job runs at a time — the rest queue behind it and start automatically as slots free up.
+
+This surprises people who add three rails expecting them to run in parallel. They won't — not inside the same project. Adding rails *organises* your work into lanes; it doesn't make those lanes run concurrently.
+
+**Real parallelism is across projects.** Each project has its own independent queue, so a rail in Project A and a rail in Project B run at the same time without contending. Want more throughput? Open more projects.
+
+There's no global concurrency knob to tune. The only automatic throttle is budget-based: if you've set a daily budget (project or app-wide), the queue auto-pauses once that day's spend hits the cap.
+
+## Watching it run
+
+Find every job under **Jobs** in the project's right sidebar — a card list, newest first. Each card shows a status badge, the profile badge, a priority badge, duration, cost, and the launched command. Above the list:
+
+- **Status filter chips** — show only jobs in a given status.
+- **Date-range filter** — narrow to a time window.
+- **Compare** — pick two jobs and view them side by side.
+
+Click any card to open the **Job Detail view**, where the live streaming log and the live metrics live. That's the next page: [The Job Detail view](the-job-detail-view).
+
+## Cancelling a job
+
+Click **■ Stop** on the rail header. The app sends `SIGTERM` to the subprocess, waits **5 seconds** for a clean exit, then `SIGKILL`s it. Nothing is left half-spawned.
+
+## If a rail won't launch
+
+If you pick an engine whose CLI isn't installed on your machine, the launch **fails fast** instead of starting a broken job — nothing spawns. Install the missing provider CLI ([Using Codex](../integrations/using-codex), [Using Gemini](../integrations/using-gemini)) and launch again. Missing Claude or Codex gives a precise "*<provider> CLI not found*" message; missing Gemini surfaces a generic launch error today, but the outcome is the same.
+
+## Stopping everything
+
+If something looks wrong:
+
+- **One rail** — click **■ Stop** on its header.
+- **Auto-pause on budget** — set a daily budget and the queue pauses itself when that day's spend hits the cap.
+- **Everything** — quit the desktop app, or run `specrails-desktop stop`.
+
+## Where to go next
+
+- [The Job Detail view](the-job-detail-view) — phases, live metrics, ticket cards.
+- [Batch implement & multi-feature](batch-implement-and-multi-feature) — run several specs at once.
+- [Picking an engine per rail](picking-an-engine-per-rail) — Claude vs Codex vs Gemini.

package/docs/guide/en/pipeline/2-the-job-detail-view.md

@@ -0,0 +1,90 @@
+# The Job Detail view
+
+Click any job card on the **Jobs** page and you land here: the cockpit for a single rail run. It's built around one promise — **the live numbers you see are real, never guesses.** This page walks through the phases, the live metrics, and the ticket cards.
+
+## The layout
+
+Two panels sit above the full streaming log:
+
+```
+┌─────────────────────────────────────────────┐
+│  Status header  (icon · live duration · …)  │
+├─────────────────────────────────────────────┤
+│  Ticket header  ( #12  #14  #15 )           │
+├─────────────────────────────────────────────┤
+│                                             │
+│  Streaming log  (auto-scroll · search · …)  │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+## Pipeline phases
+
+For `Implement` and `Batch` jobs, the run moves through the phases defined by the slash command — by default:
+
+```
+Architect ──► Developer ──► Reviewer ──► Ship
+```
+
+Each phase is a specialised agent the rail's engine invokes in your project directory:
+
+| Phase | Agent | What it does |
+|-------|-------|--------------|
+| **Architect** | `sr-architect` | Plans the implementation. |
+| **Developer** | `sr-developer` | Writes the code. |
+| **Reviewer** | `sr-reviewer` | Reviews the output. |
+| **Ship** | (varies) | Final wrap-up: tests, commit, PR draft. |
+
+Which agent handles each phase is decided by the project's **agent profile**. The baseline trio (`sr-architect`, `sr-developer`, `sr-reviewer`) is always present; routing rules in a profile can add agents or swap which one runs a phase. The phase progress bar only appears when the command actually defines phases — Ultracode jobs (which bypass the pipeline) won't show one.
+
+## Live metrics — honest by design
+
+The status header is the headline. It shows a status icon, an activity line describing what the job is doing *right now*, a count of steps taken, and a row of metrics:
+
+| Metric | When you see the real value |
+|--------|------------------------------|
+| **Duration** | **Live.** A 1-second ticker counts up while the job runs — this is the one genuinely live number. |
+| **Turns** | Derived incrementally from streamed assistant events as they arrive. |
+| **Tokens** | Aggregated incrementally from the same stream (tolerant of events missing usage fields). |
+| **Cost** | Shown as `—` until the job exits, then revealed as the authoritative `total_cost_usd`. |
+
+The design principle: **no approximate or estimated mid-run numbers.** Duration is real because it's just a clock. Turns and tokens are accumulated from actual streamed activity. Cost is deliberately *not* estimated while running — it shows as pending and only resolves to its final, authoritative figure when the provider reports it at job exit. If a number looks like it's waiting, that's intentional — you're being shown truth, not a projection.
+
+The header label and icon map to the job's status, and the panel renders for `running`, `completed`, and `failed` jobs alike — so a finished job's detail view shows the same metrics frozen at their final values.
+
+## The ticket cards
+
+The **ticket header** sits between the status header and the log. It's a premium identity card showing a chip for every spec the job touched — matched from the launched command, so it reflects exactly which tickets this run was about.
+
+- **2–3 tickets** — shown as a list of chips.
+- **4 or more** — collapse into a compact `+ N more` mode with an expand chevron, so the header stays tidy.
+
+Clicking a chip opens that spec's detail **over the job page** — you don't lose your place or change route. It's a quick way to re-read what a job is supposed to deliver while you watch it work. (On tablet-width screens you can even drag a ticket modal aside to compare two specs side by side.)
+
+## The streaming log
+
+Below the panels is the full log of the run, streamed in real time over the WebSocket:
+
+- **Auto-scroll** keeps the newest output in view (scroll up and it pauses so you can read).
+- **Search** to jump to a phrase.
+- **Copy** to grab the whole log.
+
+This is the raw truth of what the AI is doing — every tool call, every file edit, every test run.
+
+## Diagnostic export
+
+If [telemetry](../settings/customizing) was enabled for the job, an **Export diagnostic** button appears in the header. It downloads a ZIP containing:
+
+- `job-metadata.json` — command, status, profile, plugins.
+- `telemetry.ndjson` — uncompressed OTLP/JSON signals.
+- `logs.txt` — the full streaming log.
+- `summary.md` — human-readable highlights.
+- `profile.json`, `plugins.json` — exact snapshots of what ran (when present).
+
+Handy for sharing a run with a teammate, or filing a precise bug report.
+
+## Where to go next
+
+- [Rails & jobs](rails-and-jobs) — launching and queueing.
+- [Batch implement & multi-feature](batch-implement-and-multi-feature) — many specs, dependency waves.
+- [Tracking cost](../analytics/tracking-cost) — turn per-job costs into project analytics.

package/docs/guide/en/pipeline/3-batch-implement-and-multi-feature.md

@@ -0,0 +1,78 @@
+# Batch implement & multi-feature
+
+One spec at a time is fine, but a lot of real work comes in clusters — a feature plus its tests plus its migration, or a backlog you want cleared in one sitting. This page covers running several specs together: Batch mode, dependency waves, and how the pipeline keeps concurrent work from colliding.
+
+## Running several specs at once
+
+The simplest way to run a pile of specs from one rail is **Batch** mode:
+
+1. **Drag all the specs** you want onto a single rail. They stack up in that rail's spec list.
+2. **Switch the rail's mode to Batch** (the segmented control in the rail header).
+3. **Press ▶ Play.**
+
+The rail launches **one** `/specrails:batch-implement` job that works through every assigned spec. Monitor it like any other job on the Jobs page — it's a single job covering the whole set, not one job per spec.
+
+This matters because of the **one-job-per-project queue**. Since a project runs only one rail job at a time, Batch mode is also the cleanest way to *chain* a list of specs without juggling multiple rails and waiting for each to drain.
+
+### Implement vs Batch — which mode?
+
+| | **Implement** | **Batch** |
+|---|---|---|
+| Command | `/specrails:implement` | `/specrails:batch-implement` |
+| Specs per job | All on the rail, treated as one unit of work | All on the rail, worked **sequentially** |
+| Best for | A tightly coupled change | Several distinct features you want cleared in order |
+| Ordering | n/a | Dependency-aware waves (see below) |
+
+If the specs are really one change, use **Implement**. If they're a list of separate features, use **Batch** and let it sequence them.
+
+## Dependency waves
+
+Batch mode doesn't just run specs top to bottom — it computes a **dependency-aware execution order** and groups specs into *waves*. The orchestrator (`/specrails:batch-implement`) figures out which specs depend on which, then schedules them so that nothing runs before the work it builds on.
+
+Conceptually:
+
+```
+Wave 1:  #2 (data model)        ← no dependencies, runs first
+Wave 2:  #4 (API on the model)  ← waits for #2
+         #5 (CLI on the model)  ← waits for #2
+Wave 3:  #7 (docs across all)   ← waits for #4 and #5
+```
+
+Within the job, each wave's specs are implemented before the next wave starts. You don't configure this by hand — the orchestrator derives the waves from the specs themselves. Watch it unfold in the [Job Detail view](the-job-detail-view): the streaming log narrates which spec the batch is on, and the ticket header shows every spec the job touched.
+
+## Worktree isolation
+
+When several specs are implemented in one run, the pipeline keeps each unit of work isolated so concurrent or sequential changes don't trample each other's files. The batch orchestrator runs each spec's implementation in its own clean working context, then integrates the results — so a half-finished spec never leaves your tree in a broken intermediate state visible to the next one.
+
+In practice this means:
+
+- Each spec gets a clean slate to implement against, rather than inheriting the in-flight edits of the previous spec mid-stream.
+- Reviews and ship steps operate on a coherent snapshot, not a moving target.
+- A failure in one wave is contained — it doesn't silently corrupt the specs that already shipped.
+
+The app records, per job, exactly which files were touched and which ticket touched them (you'll see this surface as provenance chips in the **Code** section and as a "Files touched by this ticket" list on each spec's detail modal). That attribution is what lets you trust a multi-spec run: you can always trace a file change back to the spec that caused it.
+
+## Multi-feature across projects
+
+If you want genuine parallelism — two big features building at the same time — split them **across projects**, not across rails in one project. Each project has its own independent queue, so:
+
+```
+Project A   ▶ Rail running feature X   ┐
+                                       ├─ run simultaneously
+Project B   ▶ Rail running feature Y   ┘
+```
+
+There's no global concurrency limit and no contention between projects. Open both, launch a rail in each, and they progress together. The only shared throttle is your budget cap, which pauses queues per-project or app-wide once the day's spend hits the limit.
+
+## Tips for big batches
+
+- **Group related specs on one rail** before switching to Batch — the dependency waves only see what's on that rail.
+- **Set a daily budget** before a large batch so an unexpectedly expensive run auto-pauses instead of running away. Configure it under [Budget](../settings/customizing).
+- **Use the Compare button** on the Jobs page afterward to diff two batch runs side by side.
+- **Export a diagnostic** (if telemetry was on) to get the exact profile + plugin snapshot for the whole batch.
+
+## Where to go next
+
+- [Rails & jobs](rails-and-jobs) — the queue model in depth.
+- [The Job Detail view](the-job-detail-view) — watch a batch run live.
+- [Picking an engine per rail](picking-an-engine-per-rail) — note that Batch runs on any provider; Ultra is Claude-only.