specrails-desktop 2.0.0

package/docs/platforms/macos.md

@@ -0,0 +1,130 @@
+# Specrails on macOS
+
+## Supported configurations
+
+- **macOS on Apple Silicon (arm64)** — the only architecture the shipped desktop build targets. The official `.dmg` is built on Apple-Silicon CI and named `specrails-desktop-<version>-aarch64.dmg`.
+- Intel Macs are supported only via Rosetta / forward-compat. There is no native x86_64 macOS build today.
+
+## Installation
+
+Signed, notarized builds are published on every release under:
+
+> 📥 `https://specrails.dev/downloads/specrails-desktop/latest/`
+
+- `specrails-desktop-<version>-aarch64.dmg` — the Apple Silicon installer.
+
+Versioned copies live at `downloads/specrails-desktop/v<version>/` for archival and deep-linking. A machine-readable `manifest.json` in `latest/` describes the current release (version, sha256, size) so you can verify a download:
+
+```bash
+shasum -a 256 specrails-desktop-<version>-aarch64.dmg
+```
+
+Compare the output against `platforms["darwin-arm64"].sha256` in `https://specrails.dev/downloads/specrails-desktop/latest/manifest.json`.
+
+To install: open the `.dmg` and drag **Specrails** into `Applications/`.
+
+## Gatekeeper / first launch
+
+Official installers from the release pipeline are **code-signed and notarized**, so they open cleanly — double-click to launch, no extra steps.
+
+**Local or self-built `.app` bundles are unsigned.** Gatekeeper will warn that the app is from an unidentified developer. To run an unsigned local build:
+
+- Right-click the app in `Applications/` → **Open** → confirm **Open** in the dialog, or
+- Clear the quarantine attribute from a terminal:
+
+  ```bash
+  xattr -dr com.apple.quarantine "/Applications/Specrails.app"
+  ```
+
+You only need this once per build. It does not apply to the notarized installers above.
+
+## Prerequisites
+
+When you add a project, the app checks for the tools it needs and surfaces them in a **prerequisites panel** (in the `Add Project` dialog and the setup wizard). It checks:
+
+- **Bundled tools** — `node`, `npm`, `npx`, `git`.
+- **Provider CLIs** — **Claude Code** and **Codex**. These are always probed via your system `PATH` (never bundled). **At least one provider must be installed and working** before Add Project is enabled — if neither is usable the panel blocks the dialog.
+
+When everything is in order, the panel collapses to a single line: **All required tools detected** (no per-tool rows, no version numbers). The detailed per-tool list — with versions, and including the Claude/Codex provider rows — only renders when something is **missing**, below its minimum version, or broken.
+
+## PATH resolution
+
+GUI apps on macOS inherit a minimal `PATH` from launchd when launched from Finder, Dock, or Spotlight. On Apple Silicon this typically omits `/opt/homebrew/bin` and any tool-version-manager shims. The app resolves this differently depending on whether it is running as the shipped desktop app or as a plain server.
+
+### Desktop app (the default for `.dmg` users)
+
+The shipped desktop app bundles its own Node and Git runtimes. When those bundled binaries are present, the Tauri host sets `SPECRAILS_IS_DESKTOP=1` and `SPECRAILS_BUNDLED_RUNTIMES_PATH` before spawning the embedded server (`src-tauri/src/lib.rs`). In that mode `resolveStartupPath()` (in `server/path-resolver.ts`):
+
+- Prepends the **bundled** `node` and `git` bin directories to the front of `process.env.PATH`. A system Homebrew or nvm-managed `node`/`git` can never shadow them.
+- **Skips** the Homebrew fast-path prepend entirely.
+- **Skips** the login-shell merge — `augmentPathFromLoginShell()` is a no-op so it cannot reorder system tools ahead of the bundled ones (`loginShellStatus: "skipped"`).
+
+If a build ships **without** the bundled runtimes (or has a partial/botched extraction), the desktop app does **not** dead-end: it falls through to the same system discovery described below, so a system-installed `node`/`git` still satisfies the requirement.
+
+### Server / non-bundled fallback
+
+When the app runs without an active bundle (a runtimes-less build, or `npm run dev:server`), the app reconstructs `PATH` in two steps:
+
+1. **Fast path (sync)** — `resolveStartupPath()` prepends any missing well-known package-manager directories to `process.env.PATH`:
+   - `/opt/homebrew/bin`, `/opt/homebrew/sbin` (Apple Silicon Homebrew prefix)
+   - `/usr/local/bin`, `/usr/local/sbin` (Intel/Rosetta forward-compat and `.pkg` installer destination)
+
+   Existing entries keep their original order; the fast path only fills gaps.
+
+2. **Login-shell merge (async)** — right after the HTTP server starts listening, `augmentPathFromLoginShell()` spawns `$SHELL -l -i` once (1500 ms timeout) and merges whatever `PATH` that login + interactive shell exposes. This recovers the segments that Volta, nvm, fnm, asdf, etc. add only inside your interactive shell — whatever your `$SHELL` produces, no specific rc file is assumed. On timeout or non-zero exit, the fast-path `PATH` stays in effect and a single warning is logged.
+
+The resolved `PATH` is stored on `process.env.PATH`, so every downstream spawn inherits it (`QueueManager` → provider CLI, `SetupManager` → `npx specrails-core`, `terminalManager` PTYs, etc.).
+
+## Broken-symlink detection
+
+If `which node` succeeds but `node --version` fails (typical with a stale `/usr/local/bin/node` symlink left by an old installer pointing at a deleted `Cellar` target), the prerequisites response sets:
+
+- `installed: true`
+- `executable: false`
+- `meetsMinimum: false`
+- `installHint`: `node found at <path> but failed to execute — possibly a broken symlink or a stale install. Reinstall node or remove the stale link at <path>.`
+
+This points you at the actual fix (remove the stale link) instead of sending you in circles reinstalling Node. A separate state — installed, executable, but **below** the required version — reads as `<version> found — needs <minVersion>+`.
+
+## Diagnostic endpoint
+
+`GET /api/setup-prerequisites?diagnostic=1` returns the standard payload plus a `diagnostic` block. Example (illustrative — real payloads also carry `pathSources: "bundled"` segments in desktop mode):
+
+```jsonc
+{
+  "diagnostic": {
+    "pathSegments": ["/opt/homebrew/bin", "/opt/homebrew/sbin", "/usr/local/bin", "/usr/local/sbin", "/usr/bin", "/bin"],
+    "pathSources": ["fast-path", "fast-path", "fast-path", "fast-path", "inherited", "inherited"],
+    "loginShellStatus": "ok",       // "ok" | "skipped" | "timeout" | "error"
+    "whichResults": {               // also includes provider CLIs (and "uv" when applicable)
+      "node": "/opt/homebrew/bin/node",
+      "npm": "/opt/homebrew/bin/npm",
+      "npx": "/opt/homebrew/bin/npx",
+      "git": "/usr/bin/git",
+      "claude": "/opt/homebrew/bin/claude",
+      "codex": null
+    },
+    "nodeEnv": "production",
+    "platform": "darwin"
+  }
+}
+```
+
+`whichResults` is keyed by command name for **every** prerequisite the panel checks, so it includes `claude`/`codex` (and `uv` when probed) on top of the four bundled tools.
+
+The install-instructions modal exposes a **Copy diagnostics** button that fetches this endpoint and copies the JSON to the clipboard for bug reports. The base endpoint (no `?diagnostic=1`) omits the `diagnostic` field, keeping the regular UI poll small.
+
+## Verifying manually
+
+After installing or reinstalling Node (or a provider CLI):
+
+1. Quit Specrails completely (**Cmd-Q**, not just close the window).
+2. Relaunch from `Applications/`.
+3. Open the `Add Project` dialog.
+4. The panel should collapse to **All required tools detected**. If something is still flagged, the per-tool list expands — find the red row, click **More info → Copy diagnostics**, and inspect its `whichResults` entry and `pathSegments` to see whether the resolver found the binary you expect.
+
+## Known limitations
+
+- **Provider requirement**: at least one of Claude Code or Codex must be installed and on `PATH`; otherwise Add Project stays disabled.
+- **Port 4200** must be free on launch. The app binds `127.0.0.1:4200` for its API + WebSocket; if another process holds the port, the server cannot start.
+- **Terminal panel**: the bottom terminal panel spawns `$SHELL -l -i`, so your `.zshrc` / `.bashrc` loads as it would in a normal login shell. Per-session shell selection is not yet exposed in the UI — set `SHELL` to override the default.

package/docs/platforms/windows.md

@@ -0,0 +1,81 @@
+# Specrails on Windows
+
+> The installed app, its Start Menu entry, and its window title all read **Specrails** — that is the packaged product name.
+
+## Supported configurations
+
+- **Windows 10** (1809 or newer) and **Windows 11**.
+- Both **x64** and **ARM64** are first-class targets — each release publishes native installers for both architectures.
+- The terminal panel uses ConPTY, which requires **Windows 10 1809+** (always available on Windows 11).
+
+## Installation
+
+Installers are published on every release under:
+
+> 📥 `https://specrails.dev/downloads/specrails-desktop/latest/`
+
+Pick the pair that matches your CPU architecture:
+
+| Architecture | NSIS installer (recommended) | MSI installer (enterprise/group-policy) |
+| --- | --- | --- |
+| x64 | `specrails-desktop-<version>-x64-setup.exe` | `specrails-desktop-<version>-x64.msi` |
+| ARM64 | `specrails-desktop-<version>-arm64-setup.exe` | `specrails-desktop-<version>-arm64.msi` |
+
+If you are unsure which to use, the NSIS `-setup.exe` is the right choice for individual installs; the MSI exists for enterprise deployment. Versioned copies live at `downloads/specrails-desktop/v<version>/` for archival and deep-linking.
+
+A machine-readable `manifest.json` in `latest/` describes the current release (version, sha256, size) per platform, including `windows-x64` and `windows-arm64` entries — consumers can read it to build download links without hardcoding a version.
+
+## SmartScreen warning
+
+The Windows installers are **not code-signed** in v1. Running them triggers Microsoft SmartScreen:
+
+> **Windows protected your PC**
+> Microsoft Defender SmartScreen prevented an unrecognized app from starting. Running this app might put your PC at risk.
+
+To install:
+
+1. Click **More info**
+2. Click **Run anyway**
+
+This warning is expected and will persist until Authenticode code signing is added in a later release. The installer and the bundled server binary are built by GitHub Actions from source, and their sha256 hashes are published in `manifest.json` — verify before running if you want higher assurance:
+
+```powershell
+Get-FileHash specrails-desktop-<version>-x64-setup.exe -Algorithm SHA256
+```
+
+Compare the output against the matching architecture's `sha256` (`platforms["windows-x64"].sha256` or `platforms["windows-arm64"].sha256`) in `https://specrails.dev/downloads/specrails-desktop/latest/manifest.json`.
+
+## What's bundled
+
+The desktop app ships its own **Node** and **Git** runtimes inside the bundle, so you do **not** need to pre-install them:
+
+- `runtimes/node/{node.exe, npm.cmd, npx.cmd}`
+- `runtimes/git/cmd/git.exe`
+
+When the bundle is present, the Tauri host sets `SPECRAILS_IS_DESKTOP=1` and `SPECRAILS_BUNDLED_RUNTIMES_PATH`, and the embedded server prepends the bundled `node`/`git` directories to the front of `PATH` so a system install can never shadow them. If a build ships **without** the runtimes (or a partial extraction occurs), the app does not dead-end — it falls back to discovering `node`/`git` on your system `PATH` (probed with Windows `where.exe`) instead of reporting a corrupted bundle.
+
+The **provider CLIs** — **Claude Code** and **Codex** — are **never bundled**. They are always probed via your system `PATH`, in every mode. Install at least one before adding a project; the prerequisites panel blocks Add Project until one is usable.
+
+## Updates
+
+The desktop app self-updates via the Tauri updater plugin. It checks a GitHub Releases `latest.json` endpoint and, on Windows, applies updates with `installMode: "passive"` — the update runs with a minimal progress UI and the app relaunches into the new version. Because the installers are unsigned, an applied update may surface the same SmartScreen prompt; click **More info → Run anyway** as during the first install.
+
+## Setup wizard
+
+When you add a project, the setup wizard runs `npx specrails-core@latest init --from-config` under the hood (the full spawn is `npx --yes --prefer-online specrails-core@latest init --yes --from-config <tempPath>`, with the app writing a temporary `install-config.yaml`). The wizard has three steps — **Configure / Install / Done**.
+
+This requires **specrails-core ≥ 4.1.0** — the Node-native installer floor enforced by the app (`MIN_NODE_NATIVE_CORE_VERSION`). Earlier bash/python3 installers cannot run on Windows without WSL. The app pins `@latest` on every spawn, so the constraint resolves automatically as long as you have internet access at install time.
+
+Reserved paths (`.specrails/profiles/**`, `.claude/agents/custom-*.md`) are preserved across re-runs per the contract documented in [specrails-core's README](https://github.com/fjpulidop/specrails-core#reserved-paths).
+
+## Uninstall
+
+- NSIS: use the **Start Menu → Specrails → Uninstall** entry, or *Settings → Apps*.
+- MSI: use *Settings → Apps* or `msiexec /x <msi-path>`.
+
+## Known limitations
+
+- **Terminal panel shell**: the bottom terminal panel auto-prefers **PowerShell 7 (`pwsh.exe`)** when it is on your `PATH`, then falls back to Windows PowerShell (`powershell.exe`), and finally `COMSPEC`/`cmd.exe`. Set the `SHELL` environment variable to override the platform default with any shell you prefer. Per-session shell selection is not yet exposed in the UI.
+- **Port 4200** must be free on launch. The app binds `127.0.0.1:4200` for its API + WebSocket. If another process holds it, the app shows a native **Specrails — Port Conflict** dialog and exits.
+- **Custom window chrome**: the app uses a frameless window with a custom titlebar; the min/max/close controls are rendered by the app.
+- **Code signing**: Windows builds are unsigned in v1 (see SmartScreen above). Authenticode signing is deferred to a later release.

package/docs/running-pipelines.md

@@ -0,0 +1,240 @@
+# Running pipelines
+
+You have specs on the board. Now let's ship them. This guide covers launching a rail, the three rail modes, agent profiles, plugins, and the Jobs page.
+
+## The big picture
+
+```
+SpecsBoard (left)            Rails (right)
+─────────────────            ─────────────────
+#1 Login flow      ─┐
+#2 Webhook retry    │  drag onto
+#3 Cost limits      │ ────────────►   Rail 1
+#4 Audit log        │                 ▶ Play
+                    │
+                    └────────────►   Rail 2
+                                     ▶ Play
+
+                     Each rail runs Architect → Developer → Reviewer → Ship
+                     in your project directory.
+```
+
+A **rail** is an execution lane. Drag a spec card from the SpecsBoard onto a rail and press **▶ Play** to launch the pipeline. Rails let you organise and queue work into named lanes.
+
+Rails run on **Claude** by default. If your project has both providers installed, a per-rail engine selector lets you launch a rail on **Codex** instead — see [Using Codex](codex.md).
+
+> **One job at a time per project.** Each project has a single queue, so within a project only one rail job runs at a time; the rest queue behind it. Real parallelism is **across projects** — open two projects and their rails run independently. See [Running multiple rails](#running-multiple-rails).
+
+## Rails
+
+Each rail has a header with:
+
+- **Status pill** — `idle`, `running`, or `failed`. (There's no separate "completed" state — a rail returns to `idle` when its job finishes cleanly.)
+- **Spec list** — the IDs of the specs assigned to this rail. Drag in more, drag out to detach. You can also use the **Move to rail** popover from a spec card; it shows a status dot per rail so you don't push work onto a busy lane.
+- **Mode segmented control** — `Implement`, `Batch`, and (Claude rails only) `Ultra`. See [Rail modes](#rail-modes).
+- **Profile picker** — which agent profile this rail uses. This only appears once the project has **at least one** profile (create them on the Agents page). When present, `No profile` runs the rail in legacy mode.
+- **Engine selector** — Claude vs Codex. Only renders on projects with more than one provider installed.
+- **Play / Stop button** — start or cancel.
+
+### Rail modes
+
+The mode is a segmented control in the rail header, persisted per rail.
+
+| Mode | Command | What it does |
+|------|---------|--------------|
+| **Implement** | `/specrails:implement` | One job covering all the specs on the rail. Runs the full Architect → Developer → Reviewer → Ship pipeline. |
+| **Batch** | `/specrails:batch-implement` | One job that works through the rail's specs sequentially, in dependency-aware waves. |
+| **Ultra** | (Ultracode) | Claude implements each spec autonomously, **bypassing** the OpenSpec pipeline. One independent job per spec. Claude only. |
+
+### Pipeline phases
+
+`Implement` and `Batch` run the pipeline phases defined by the slash command's frontmatter — by default:
+
+```
+Architect ──► Developer ──► Reviewer ──► Ship
+```
+
+Each phase is a specialised Claude Code agent invoked in your project's working 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 |
+
+The exact agent for each phase is determined by your project's agent profile. The baseline trio (`sr-architect`, `sr-developer`, `sr-reviewer`) is mandatory; routing rules in the profile can fan-out or override. The phase progress bar only renders when the command defines phases.
+
+### Ultracode mode
+
+`Ultra` is a Claude-only mode that skips the Architect → Developer → Reviewer → Ship pipeline entirely. Instead of orchestrating the agent chain, it hands Claude a configurable pre-prompt plus the full spec text and lets it work autonomously with its native tools.
+
+- **One job per spec.** If the rail has three specs, `Ultra` launches three independent jobs.
+- **Variable cost.** Because the run is open-ended, pressing Play opens a confirmation dialog before anything spawns.
+- **Model picker.** A per-rail control lets you pick **Haiku / Sonnet / Opus** (default Sonnet) for the Ultracode run.
+- **Claude only.** The `Ultra` segment and its model picker only appear when the rail's engine is Claude. Agent profiles don't apply to Ultracode rails.
+
+You can customise the Ultracode pre-prompt per project on the [Settings page](customizing.md#per-project-settings).
+
+### Running multiple rails
+
+Within a single project, jobs are **serialised** — the project runs one rail job at a time and queues the rest. Adding more rails organises your work into lanes, but it doesn't make them run concurrently inside that project.
+
+True parallelism is **across projects**: each project has its own queue, so rails in different projects run at the same time without contending. There is no global concurrency limit to configure — the only automatic throttle is budget-based (see [Stopping everything](#stopping-everything)).
+
+## Jobs
+
+Every rail run becomes a **Job**. Find them under **Jobs** in the project's right sidebar.
+
+### Jobs page
+
+A card list of every job for the active project, newest first. Each card shows:
+
+- A status badge, the profile badge, a priority badge, duration, cost, and the launched command.
+
+Controls above the list:
+
+- **Status filter chips** — click to show only jobs in a given status.
+- **Date-range filter** — narrow to a window of time.
+- **Compare** — enter compare mode, select two jobs, and open a side-by-side comparison.
+
+Click a card to open the **Job Detail page**.
+
+### Job Detail page
+
+Two purpose-built components above the streaming log:
+
+- **`JobStatusPanel`** — header with a status icon, a live duration ticker, and an incremental counter for turns + tokens + cost (derived from streaming `assistant` events). Cost shows `—` until the authoritative `total_cost_usd` arrives at job exit.
+- **`JobTicketHeader`** — chips for every ticket the job touched (resolved by parsing the `command` and matching against the spec board). Click a chip to open the spec's detail modal over the job page without changing the route. A `+N more` collapse mode kicks in at ≥ 4 tickets.
+
+Below: the full streaming log with auto-scroll, search, and copy.
+
+### Cancelling a job
+
+Click **Stop** on the rail header. The app sends `SIGTERM` to the subprocess, waits **5 s**, then `SIGKILL`.
+
+### Diagnostic export
+
+Visible only when [telemetry](customizing.md#telemetry) was enabled for the job. Click **Export diagnostic** in the Job Detail header to download a ZIP containing:
+
+- `job-metadata.json` — command, status, profile, plugins
+- `telemetry.ndjson` — uncompressed OTLP/JSON
+- `logs.txt` — full streaming log
+- `summary.md` — human-readable highlights
+- `profile.json`, `plugins.json` — exact snapshots of what ran (when present)
+
+## Agent profiles
+
+A **profile** is a named JSON file that bundles the agent chain + per-agent models + routing rules. Different rails can run different profiles.
+
+### Why use profiles
+
+Without profiles, every rail uses the project's frontmatter-baked models. With profiles, you can:
+
+- Keep a `default` profile for everyday work (Sonnet across the board).
+- Add a `budget` profile that swaps Developer to Haiku and routes simple tasks away from Architect.
+- Add a `max` profile for high-stakes work with Opus + every optional agent.
+
+### Browse / create profiles
+
+Open **Agents** in the project's right sidebar. Two sub-tabs:
+
+- **Profiles** — full CRUD over `.specrails/profiles/*.json`. The live validator enforces the baseline trio and routing ordering — Save is disabled with an "N issues to resolve" hint while the profile is broken.
+- **Agents Catalog** — read-only viewer of upstream `sr-*` agents and your `custom-*` agents.
+
+The empty state offers **Migrate from current agents**: one click creates a `default` profile mirroring today's frontmatter.
+
+Each profile gets a per-profile analytics card showing usage for the last 7 / 30 / 90 days: jobs, success rate, avg tokens, avg duration.
+
+### Pick a profile at launch
+
+Pick the profile from the **rail header's profile dropdown**. It's preselected to the project's resolved default, and your choice **persists per rail** across launches. The selection is sent with the launch; rails in the same batch can run different profiles.
+
+The **`No profile`** option always exists — use it to run a rail exactly as it did pre-4.1.0. (The dropdown itself only appears once the project has at least one profile.)
+
+### Custom agents (Agent Studio)
+
+From the Agents Catalog tab, the toolbar offers three creation entry points:
+
+| Button | Behaviour |
+|--------|-----------|
+| **Generate with Claude** | Describe the agent in natural language; Claude drafts the full `.md`. |
+| **Template** | Start from the catalog of 50 templates across 13 categories (Software Engineering, Testing & QA, Data & Analytics, Security & Compliance, Product & Design, …). |
+| **Blank** | Start from a minimal template. |
+
+You can also **Duplicate** any existing agent (upstream or custom) from its card.
+
+Custom agents live at `.claude/agents/custom-*.md` and are **never touched** by specrails-core's installer/update scripts. Every save appends a version row — open **History** in the Studio to browse and restore.
+
+Click **Test** in the Studio to run the current draft against a sample task in an isolated `claude` invocation — no files written; output + token count + duration shown inline.
+
+### Requirements
+
+Profiles require `specrails-core ≥ 4.1.0` in the project. Without it, you can still create and edit profiles in the app, but the pipeline runs in legacy mode (no env injection). A yellow banner on the Agents page tells you when to upgrade.
+
+For deeper internals (resolution order, snapshotting, file format), see [internals/profiles.md](internals/profiles.md).
+
+## Plugins
+
+Per-project bundled integrations. Click **Integrations** in the project's right sidebar.
+
+### Bundled today
+
+- **Serena** — semantic code navigation via LSP + MCP. Requires `uv` on PATH (the app auto-detects).
+
+### Installing a plugin
+
+Each plugin tile has:
+
+- **Status** — `not installed`, `installed`, `orphan` (state file mentions it but `.mcp.json` doesn't), or `degraded` (verify failed).
+- **Preview install** — shows which `mcpServers` entries and agent fragments will land where, so you can sanity-check before clicking.
+- **Install** — applies the changes. Progress streams over the WebSocket (`plugin.install_progress` event).
+- **Uninstall** — removes the surgical changes; never wholesale rewrites your `.mcp.json`.
+- **Health** — on-demand verify (probes a `--version`-style command with a 2 s timeout).
+
+### How plugins affect your pipeline
+
+Before each rail spawn, the app:
+
+1. Resolves the project's installed plugins (parallel verify, per-plugin 2 s timeout).
+2. Classifies them into `active` and `degraded`.
+3. Writes a per-job snapshot to `~/.specrails/projects/<slug>/jobs/<jobId>/plugins.json` (chmod 400).
+4. Injects two env vars into the subprocess: `SPECRAILS_PLUGINS_ACTIVE` (CSV) and `SPECRAILS_PLUGINS_SNAPSHOT` (file path).
+
+Degraded plugins are **non-blocking** — the rail spawns anyway, but a `plugin.degraded` toast surfaces in the UI.
+
+### Reserved paths
+
+The app never wholesale rewrites these files:
+
+- `<project>/.mcp.json` — surgical merge per plugin.
+- `<project>/.specrails/plugins/state.json` — install registry.
+- `<project>/.specrails/plugins/snapshots/<jobId>.json` — per-job snapshots.
+- `<project>/.claude/agents/custom-<plugin>.md` — optional fragment per plugin.
+
+specrails-core's installer also guarantees it never touches `.specrails/plugins/**` or `.claude/agents/custom-*.md`.
+
+## Running many specs at once
+
+Want a whole batch of specs to run from one rail? Use **Batch** mode:
+
+1. Drag all the specs you want onto a single rail.
+2. Switch that rail's mode to **Batch**.
+3. Press **▶ Play**.
+
+The rail launches one `/specrails:batch-implement` job that works through every assigned spec in dependency-aware waves. Monitor progress on the Jobs page. Because a project runs one job at a time, this is also the way to chain a list of specs without juggling multiple rails.
+
+## Stopping everything
+
+If something looks wrong:
+
+- **One rail** — click **Stop** on the rail header.
+- **Auto-pause on budget** — if you set a daily budget (project or app-wide), the queue automatically pauses once that day's spend hits the cap. Configure it under [Budget](customizing.md#budget).
+- **Everything** — quit the desktop app, or run `specrails-desktop stop`.
+
+## Where to go next
+
+- [Tracking cost](tracking-cost.md) — see what each rail run is costing you.
+- [Customising the app](customizing.md) — daily budget, per-job alerts, telemetry.
+- [Using Codex](codex.md) — run rails on the Codex CLI.
+- [Agent profile internals](internals/profiles.md) — for power users.

package/docs/terminal.md

@@ -0,0 +1,138 @@
+# Terminal panel
+
+specrails-desktop ships a full-featured terminal at the bottom of the window. Toggle it with `Cmd+J` (macOS) or `Ctrl+J` (other). It's a real xterm.js with WebGL rendering, shell integration, scrollback search, file drag-and-drop, inline images, and a few quality-of-life touches you won't find in a plain terminal app.
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│   Dashboard content                                         │
+│                                                              │
+├─────────────────────────────── Cmd+J ────────────────────────┤
+│ ▶ specrails-desktop  /Users/you/repos/my-app                │
+│ $ git status                                                 │
+│ ↳ 28ms · cwd: /Users/you/repos/my-app                       │
+│                                                              │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Why use the built-in terminal?
+
+You don't have to. You can keep using iTerm/Windows Terminal/Alacritty/whatever you love. But the built-in panel buys you:
+
+- **Per-prompt timing** — every command taking ≥ 500 ms shows a small live timer in the terminal's top-left corner; once done, the duration sits there as a record.
+- **Long-running command notifications** — when a command exceeds 60 seconds and you've context-switched away, you get a native desktop notification.
+- **Open this directory** in the right-click menu when a CWD has been observed (Tauri desktop app only).
+- **Drag a file from Finder/Explorer** onto the terminal to paste its absolute path (Tauri desktop app only).
+- **Live theme switching** — the terminal recolours when you change the app theme without losing scrollback.
+
+### Toolbar shortcuts
+
+The panel header carries three one-click shortcuts:
+
+- **Open AI CLI** (✨ Sparkles) — spins up a fresh session and types your CLI for you. On a single-provider project it launches that provider's CLI directly (`claude` or `codex`); on a multi-provider project it opens a small picker so you choose which CLI to start.
+- **Open in browser** (🌐 Globe) — opens the URL from the `browserShortcutUrl` setting (default `https://specrails.dev`). Right-click it to jump to the setting and change the URL.
+- **Paste quick script** (`</>`) — writes the snippet from the `quickScript` setting (which defaults to a personalised `echo "Wake up, <username> …"` reminder, editable in Settings) into the active session. Right-click it to edit the snippet in Settings. Disabled when there's no active terminal or the snippet is empty.
+
+## Keyboard shortcuts
+
+| Action | macOS | Other |
+|--------|-------|-------|
+| Toggle panel | `Cmd+J` | `Ctrl+J` |
+| Copy selection | `Cmd+C` | `Ctrl+C` |
+| Paste (bracketed) | `Cmd+V` | `Ctrl+V` |
+| Clear scrollback | `Cmd+K` | `Ctrl+K` |
+| Find in scrollback | `Cmd+F` | `Ctrl+F` |
+| Zoom font in / out | `Cmd+=` / `Cmd+-` | `Ctrl+=` / `Ctrl+-` |
+| Reset font size | `Cmd+0` | `Ctrl+0` |
+| Jump to previous prompt | `Cmd+ArrowUp` | `Ctrl+ArrowUp` |
+| Jump to next prompt | `Cmd+ArrowDown` | `Ctrl+ArrowDown` |
+
+`Cmd+C` only consumes the keystroke when there's a non-empty selection; otherwise it passes through to the PTY so apps like vim still receive `Ctrl+C`. Inside alt-screen apps with mouse reporting (tmux, htop), hold `Shift` while dragging to bypass mouse-mode and use native xterm selection.
+
+## Right-click menu
+
+Right-click anywhere in the active terminal:
+
+- Copy / Paste / Select All / Clear / Search… / Save scrollback to file…
+- **Open `<cwd>`** — when shell integration has reported a CWD via OSC 1337 (Tauri desktop app only). In a plain browser context this item never appears.
+
+Menu position flips when near the bottom-right corner of the viewport.
+
+## Shell integration
+
+Shell integration is **on by default** (toggle in Settings → Terminal panel). The app auto-injects a small shim per shell that emits OSC 133 prompt marks plus OSC 1337 `CurrentDir=…`. The shim runs only in the app's spawned shell — your normal terminal apps elsewhere are untouched.
+
+Per shell:
+
+| Shell | Mechanism |
+|-------|-----------|
+| zsh | `ZDOTDIR=<shim dir>`; the shim's `.zshrc` sources `~/.zshrc` first |
+| bash | `--rcfile <shim path>`; the shim sources `~/.bashrc` first |
+| fish | `fish -C "source '<bundled shim>'"` (`--init-command`); runs after `config.fish` / `conf.d`, so your real fish config is preserved |
+| PowerShell | `-NoLogo -NoExit -File <shim.ps1>`; the shim dot-sources the original `$PROFILE` |
+
+Each shim sets `SPECRAILS_SHELL_INTEGRATION_LOADED=1` as a sentinel.
+
+If shell integration doesn't bootstrap — for example your `~/.zshrc` runs `exec zsh` (which throws away our `ZDOTDIR`) or a similarly aggressive customisation — there's no error message. The panel detects the missing prompt marks silently; the gutter, per-prompt timing badge, and long-running notifications simply won't appear. If that happens, disable shell integration in Settings; the rest of the panel keeps working.
+
+## Drag and drop
+
+Inside the Tauri desktop app, drop one or more files from Finder/Explorer onto the terminal viewport to paste their absolute paths into the active session. Paths are shell-quoted for your host platform:
+
+- macOS / Linux — POSIX single-quote
+- Windows — double-quote with `^`-escaped percent/caret (matches `cmd.exe` rules)
+
+In a plain browser context this is a silent no-op — the browser doesn't expose `File.path`.
+
+## Inline images
+
+The panel decodes Sixel and iTerm2 inline-image protocols via `@xterm/addon-image`. Try `imgcat foo.png` or any tool that emits Sixel.
+
+Disable in Settings → Terminal panel → Image rendering if you hit memory pressure on heavy image streams. The per-frame cap is 8 megapixels.
+
+## Settings
+
+Two layers:
+
+- **App-wide defaults** — Desktop Settings (gear icon on the sidebar) → Terminal panel.
+- **Per-project overrides** — Project Settings (gear in the project navbar) → Terminal panel.
+
+Project wins per-field; absent fields fall back to app-wide defaults.
+
+Hot-reload semantics:
+
+| Setting | Hot-reload | Notes |
+|---------|------------|-------|
+| Font family / size | Live | Existing sessions reconfigure immediately |
+| Copy on select | Live | |
+| Long-running threshold | Live | |
+| Notify on completion | Live | |
+| Browser shortcut URL | Live | The Open-in-browser toolbar button uses the new value next click |
+| Quick script | Live | The Paste-quick-script toolbar button uses the new value next click |
+| Render mode (auto / canvas / webgl) | Next session | Live sessions keep their boot-time config |
+| Shell integration | Next session | |
+| Image rendering | Next session | |
+
+Render mode `auto` picks WebGL when the WebView exposes WebGL2; on `webglcontextlost` the panel transparently reverts to xterm's default renderer.
+
+## Limits and edge cases
+
+- **Sessions per project** — hard cap of 10.
+- **Closing a project** — kills all its sessions immediately.
+- **Window close / quit** — graceful: SIGTERM, 2 s grace, SIGKILL.
+- **Cmd+J inside an open Dialog** — ignored. The panel won't toggle on top of a modal.
+
+## Diagnostics
+
+If something looks broken:
+
+1. Open Settings → Terminal panel and confirm shell integration is enabled.
+2. Check that `printenv SPECRAILS_SHELL_INTEGRATION_LOADED` outputs `1` inside a freshly opened terminal.
+3. Open a session, then `printf '\x1b]133;A\x07'` manually and watch the gutter — a marker should appear.
+4. As a last resort, disable shell integration in Settings and re-enable; new sessions receive a fresh shim.
+
+For deeper inspection of how the panel resolves PATH at startup (relevant for Volta/nvm/asdf shims), call `GET /api/setup-prerequisites?diagnostic=1` from the app and check the `pathSegments` / `pathSources` in the response. The install-instructions modal has a **Copy diagnostics** button that does this for you.
+
+## Where to go next
+
+- [Customising the app](customizing.md) — terminal settings, themes.
+- [Getting started](getting-started.md) — registering a project.