specrails-desktop 2.0.0

package/docs/codex.md

@@ -0,0 +1,210 @@
+# 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.)
+
+> 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
+> `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.
+
+## 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) |
+| 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 |
+
+The app's `Add Project` dialog runs a live prerequisites check. It
+disables the Codex provider checkbox with a "not found" hint when the
+binary isn't on `PATH`; it shows install commands if you click "More info".
+
+## Adding a codex project
+
+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.
+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:
+   - `.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
+     (implement, batch-implement, why, compat-check, …).
+   - `.codex/skills/rails/sr-*/SKILL.md` — the pipeline rails.
+   - `AGENTS.md` — top-level instructions file with a sentinel-protected
+     managed block. Anything outside the sentinels is preserved on
+     updates.
+
+   The exact rail and lifecycle skill set is produced by
+   `specrails-core`, not the app, so the precise file list can vary by
+   core version.
+
+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.
+
+## Running both providers 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."*
+
+Once both are installed:
+
+- **Per-invocation engine pickers** let you choose Claude vs Codex 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
+  single-provider projects these pickers don't render — there's nothing
+  to choose.
+- The **selected engine is remembered per project** (it defaults to the
+  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.
+
+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 |
+
+## Estimated cost
+
+Codex does not report `total_cost_usd` natively. The app computes an
+estimate from the captured `usage` (input / output / cached input
+tokens × the local rate-card in `server/pricing.ts`) and stores it in
+`ai_invocations.total_cost_usd` with `total_cost_usd_estimated = 1`.
+
+The Analytics page surfaces this in two places:
+
+- **The cost cell** in the Raw Invocations table shows a `~` prefix
+  (e.g. `~$0.012`) and a tooltip explaining the fallback when you
+  hover.
+- **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.
+
+The pricing table is reviewed quarterly. The reference date sits on
+each entry as `lastReviewedAt`. If OpenAI raises prices mid-quarter,
+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.
+
+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
+`~/.codex/config.toml`, so those servers are available natively — no extra plumbing required.
+
+## Troubleshooting
+
+**"codex binary not found" when adding a project** — install codex CLI
+and restart the app so PATH refreshes. The app's
+`/api/setup-prerequisites` endpoint surfaces the absolute path it
+resolved, useful for diagnosing Homebrew-vs-npm install collisions.
+
+**"codex 0.120.0 is older than required 0.128.0"** — upgrade. The
+adapter pins the minimum because earlier versions don't support
+`exec --json` or `exec resume`.
+
+**"codex mcp add serena failed: auth missing"** — run `codex login`
+or set `OPENAI_API_KEY`. The app doesn't proxy auth.
+
+**Cost shows as `—` for codex jobs even though tokens are non-zero**
+— the spawned model isn't in `server/pricing.ts` (e.g. a brand-new
+model OpenAI shipped after our last review). Update the pricing table
+and reload the page.
+
+**Cost on the Hero looks too high after a long Explore session** —
+remember that codex Explore uses real `exec resume`, so every turn
+re-feeds the prior conversation. Long sessions accumulate input-
+token cost the same way Claude's `--resume` does. The Hero footnote
+calls this out.
+
+**"Enrich with Contract Layer" did nothing on a codex spec** — that's
+expected. Contract Refine is a Claude-only capability; the Add Spec UI
+hides the toggle for codex, and the server skips it defensively if a
+codex conversation reaches the refine path. There's no error — the
+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:
+
+```bash
+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).
+
+`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.
+
+## Architecture pointers (for specrails-desktop developers)
+
+The codex integration lives in:
+
+- `server/providers/codex-adapter.ts` — `ProviderAdapter`
+  implementation for codex 0.128.0+. Fixtures under
+  `server/providers/__fixtures__/codex/0.128.0/`.
+- `server/pricing.ts` — local pricing table + `estimateCostUsd`.
+- `server/codex-otel-bridge.ts` — synthetic OTEL traces / metrics /
+  logs derived from JSONL events.
+- `server/plugins/codex-mcp.ts` — `codex mcp add/remove/list` wrapper
+  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`.
+
+## See also
+
+- [Adding a provider](internals/adding-a-provider.md) — the developer
+  guide to wiring a third 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

@@ -0,0 +1,197 @@
+# 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.
+
+## Creating a spec
+
+Open the Dashboard and click **Add** (the Plus button on the SpecsBoard toolbar). The **Add Spec** dialog opens with three modes:
+
+- **Quick** — you describe what you want; the AI writes the full spec.
+- **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.
+
+### Quick mode
+
+For when you already know what you want. Type your idea; the AI generates the full spec. This is usually a single turn — but it runs multi-turn when you give it the full codebase (the context slider's higher presets) or attach files, so it can read what it needs first.
+
+**Controls:**
+
+- **Engine + model** — the engine selector (multi-provider only) and a model picker. The model defaults to a sensible choice for the engine and can be overridden per spec.
+- **Context slider** — Quick mode shows the same context preset slider as Explore, capped at the **Max** preset (see the table below).
+- **Fine-tune** — expand to toggle the underlying flags by hand, including **Enrich with Contract Layer**.
+- **From a website** — when the browser-capture feature is enabled, this opens an embedded browser so you can capture a page (DOM, screenshots, network) and turn it into a spec.
+- **Attachments** — drop mockups, briefs, or data files into the idea field. Attachments give the AI more to work with (and switch Quick generation to multi-turn).
+
+**Enrich with Contract Layer** appends a structured block to the generated description so downstream agents don't have to guess names or shapes:
+
+- **Naming Contract** — exact identifiers to reuse
+- **Data Shapes** — JSON-ish payloads
+- **State Machine** — transitions
+- **Invariants** — must-hold properties
+- **File Touch List** — files the implementation will edit
+
+Your last choice for this toggle is remembered per project.
+
+While the spec is being generated, a toast in the corner shows the project name, a truncated copy of your idea, and the **elapsed time** ("Generating… 0:12"). When it finishes it switches to "Generated in <time>" with a **View** action that jumps straight to the new spec.
+
+### Explore mode
+
+For when the spec needs shaping. You converse with the AI; a live draft updates each turn.
+
+**Context preset slider** — pick how much the AI sees before it answers. Each preset flips a set of concrete flags:
+
+| Preset | What the AI sees |
+|--------|------------------|
+| Minimal | Just your message — nothing else loaded. Fastest and cheapest. |
+| Light | + your specrails tickets (`.specrails/local-tickets.json`). |
+| Standard | + specrails tickets **and** OpenSpec specs. |
+| Rich | + full-codebase read access (Read / Grep / Glob). |
+| Max | Rich, plus a **Contract Layer** enrichment pass. |
+| Desktop | Max, plus **project MCPs** (`.mcp.json`) **and your own approved MCP servers**. |
+
+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.
+
+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.
+
+**Buttons in the shell:**
+
+- **Save as Draft** — persists the conversation as a draft ticket so you can come back later. Available once you've sent at least one user message. The draft carries `origin_conversation_id` pointing back at this conversation so you can resume it from the dashboard.
+- **Review →** — opens a Review overlay that diffs the proposed spec against the baseline before you commit.
+- **Create Spec** — promotes the live draft to a real spec (status `todo`). When you're editing an existing spec the same button reads **Update Spec** instead. The conversation stays in history.
+- **Minimize** — parks the conversation as a chip in the minimized-chats dock; click the chip later to restore it.
+- **Discard** — destructive, asks for confirmation.
+
+### Raw mode
+
+No AI. Whatever you type is saved verbatim as a spec, with a title (auto-derived from the first line, editable), a priority, and optional labels. Use it when you already have the spec text and just want it on the board.
+
+## Drafts
+
+A draft is an in-progress Explore conversation saved as a ticket with status `draft`. Drafts behave like normal tickets but:
+
+- Carry a `Draft` pill where the priority pill would be.
+- Live in the active (Todo) bucket with a subtly tinted border — there's no separate Backlog column.
+- Have a **Continue Editing** action in the detail modal that re-opens the original conversation with its full chat history.
+
+Drafts are never auto-deleted. You either discard them explicitly or commit them to a real status.
+
+> Pro tip: when you're not sure if a spec is worth doing, save it as a draft and let it sit. The next morning, open the draft, glance at the description, and decide.
+
+## Compare two specs side by side
+
+Open any spec modal. Then either:
+
+- **Drag the modal header** toward the left or right edge of the screen — once you cross 20% of the viewport it snaps to a half-screen panel and a picker of your other todo specs appears on the opposite side.
+- **Click "Compare"** in the modal toolbar — same result, no drag.
+
+```
+Drag left:                          Drag right:
+┌────────┬─────────┐                ┌─────────┬────────┐
+│ Spec A │ Picker  │                │ Picker  │ Spec A │
+│        │ ┌─────┐ │                │ ┌─────┐ │        │
+│        │ │ #2  │ │                │ │ #2  │ │        │
+│        │ │ #5  │ │                │ │ #5  │ │        │
+│        │ └─────┘ │                │ └─────┘ │        │
+└────────┴─────────┘                └─────────┴────────┘
+```
+
+Click a picker card and that side becomes a second detail modal — now you have two specs open side by side, fully interactive.
+
+**Resize the split** by dragging the vertical divider, or focus it and use arrow keys / Home / End / 0. The ratio is clamped between 25% and 75%.
+
+**Exit rules:**
+
+- Backdrop click → close both.
+- `×` on the *original* (origin) side → close both.
+- `×` on the *other* side → return that side to the picker.
+- Open a third spec from a link inside either panel (e.g. an epic chip in the SMASH sidebar, or **Continue Editing** on a draft) → split-view collapses and the third spec opens centred.
+
+**URL persistence:** the comparison is encoded in the URL as `?compare=<id>&compareSide=<side>&compareOrigin=<id>`, so a page refresh restores the split.
+
+**Viewport:** disabled below 900px. If you shrink the window while in split, the app collapses cleanly to a centred modal.
+
+## SMASH a big spec
+
+Got an epic that's clearly too big? Open it and click **SMASH Spec into Sub-Specs** in the toolbar. The AI decomposes it into a family of sub-specs. Each child:
+
+- 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.
+
+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).
+
+## Continue Editing — refine an existing spec
+
+For any spec with status `draft`, `todo`, or `backlog`, the detail modal shows a **Continue Editing** button. Click it and:
+
+1. The spec opens in a fresh Explore shell with the draft pane pre-seeded with the current title, description, priority, labels, and acceptance criteria.
+2. If the spec was originally an Explore draft (i.e. it has `origin_conversation_id`), that original conversation is resumed — you see the chat history.
+3. You type the first refinement. The AI updates the live draft.
+4. The Review step shows a real diff against the current spec before you commit.
+5. On commit, the spec is PATCH-ed — no new ticket is created.
+
+Continue Editing works from the dashboard or from inside a split-view comparison — triggering it from a split-view panel collapses the comparison automatically because the shell needs the full screen.
+
+The Contract Layer (if a spec has one) is shown inside the detail modal as a collapsible disclosure with an `N/5 populated` badge. You can re-run the enrichment for a single ticket from there.
+
+## Status visuals
+
+Every spec card shows a status indicator that stays consistent across view modes:
+
+| Status | Indicator | Border |
+|--------|-----------|--------|
+| `draft` | Accent-secondary dot, `Draft` pill | Subtle accent-secondary tint, dashed on postit |
+| `todo` | Gray dot, muted text | Dashed left border |
+| `in_progress` | Blue pulsing dot, bold text | Solid blue left border |
+| `done` | Green checkmark, dimmed text | Solid green left border |
+| `cancelled` | Red X, dimmed text | No border |
+
+## Filtering and sorting
+
+The SpecsBoard toolbar has 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).
+
+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
+
+Right-click any spec card (in any view mode):
+
+- **Delete ticket** — with confirmation.
+- **Change status → Todo / Done**
+- **Set priority → Critical / High / Medium / Low**
+
+## View modes
+
+The SpecsBoard has **two** view modes, switched from a toolbar toggle and remembered per project:
+
+- **List view** (`row`) — compact one-line rows.
+- **Post-it view** (`postit`, the default) — postit-style cards with short summaries; drag a card onto a rail to queue it.
+
+(The separate List / Grid / Post-it picker you may see elsewhere — like the split-view comparison picker — is its own surface and unrelated to this toggle.)
+
+## What happens behind the scenes
+
+You don't need this to use the feature, but it's nice to know:
+
+- Specs live in `<project>/.specrails/local-tickets.json` (a JSON store).
+- A file watcher catches external edits (e.g. when an agent flips a spec to `in_progress`) and broadcasts a WebSocket event, so the board updates instantly.
+- Every AI CLI invocation that creates or refines a spec is recorded in your analytics under one of these surfaces:
+  - `quick-spec` — Quick mode generation (and the Quick-mode Contract Refine pass).
+  - `explore-spec` — every Explore conversation turn (and the Explore Contract Refine pass).
+  - `ai-edit` — Continue Editing / AI Edit refine turns.
+- Drafts are linked to their conversation via `origin_conversation_id`. Deleting a draft cascades to its conversation when no other ticket references it; deleting a conversation clears the field on any linked tickets.
+
+## Where to go next
+
+- [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.

package/docs/customizing.md

@@ -0,0 +1,197 @@
+# Customising the app
+
+Every setting you can change, grouped by where you'll find it.
+
+## Themes
+
+Open **Desktop Settings** (gear icon at the bottom of the Arc sidebar) → **Appearance**.
+
+Five built-in themes:
+
+| Theme | Vibe |
+|-------|------|
+| **SpecRails** *(default)* | Brand theme — deep navy-indigo with saturated cyan accents |
+| **Dracula** | The original — dark purple-tinted with vivid neon accents |
+| **Aurora Light** | Premium light — Linear-inspired indigo on warm off-white |
+| **Obsidian Dark** | Premium dark — near-black blue-tinted with electric accents |
+| **Matrix** | Phosphor terminal — soft mint on green-tinted near-black |
+
+The selection is app-wide (one theme across all projects) and applies instantly:
+
+- All UI components recolour live.
+- The terminal panel reconfigures without losing scrollback or shell integration.
+- Recharts charts in Analytics recolour live.
+- Syntax-highlighted code blocks recolour live.
+
+There's an inline anti-FOUC script in `client/index.html` so a page refresh never shows a flash of the wrong theme.
+
+The active theme persists to `desktop_settings.ui_theme` on the server and mirrors to `localStorage` so the desktop app and browser stay in sync if you use both.
+
+> Want a sixth theme? It's a small contribution — see `client/src/lib/themes.ts` and [internals/architecture.md](internals/architecture.md) for the contract.
+
+## Sidebars
+
+Both sidebars cycle through the same three states with their pin icon:
+
+- **Pinned-open** — always wide.
+- **Pinned-collapsed** — always a narrow strip of icons.
+- **Unpinned** *(default)* — collapsed strip that expands on hover.
+
+Keyboard shortcuts:
+
+| Shortcut | Action |
+|----------|--------|
+| `Cmd+B` / `Ctrl+B` | Cycle the **right** project sidebar (Chat) |
+| `⌥⌘B` / `Ctrl+Alt+B` | Cycle the **left** Arc sidebar |
+
+State is per-machine (local UI preference, not synced).
+
+> Press `?` anywhere for the full keyboard-shortcuts cheatsheet. `Cmd+K` / `Ctrl+K` opens the command palette; `Cmd+J` / `Ctrl+J` toggles the terminal panel.
+
+## Per-project settings
+
+Open **Settings** from the project navbar (top right of any project page).
+
+### Budget
+
+| Setting | Behaviour |
+|---------|-----------|
+| **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).
+
+### Rail pre-prompt
+
+A custom instruction appended to every **Implement** and **Batch-implement** rail job, after the ticket context and before execution. Use it for stable project guidance that should accompany every rail run (e.g. "keep migrations backward compatible, add tests for every change"). Leave it blank for none.
+
+### Ultracode pre-prompt
+
+The instruction sent to Claude for **Ultracode** rails (Claude-only). Ultracode skips the OpenSpec pipeline — it hands Claude this pre-prompt plus the spec text and lets it implement autonomously. The spec text is appended automatically after the pre-prompt. Leave it blank to use the built-in default.
+
+### Telemetry
+
+Opt-in OpenTelemetry capture for rail runs.
+
+| Setting | Behaviour |
+|---------|-----------|
+| **Enable pipeline telemetry** | Default OFF. When ON, every rail spawn gets OTLP env vars injected. Each rail's traces/metrics/logs are captured to a `.ndjson.gz` blob. |
+
+When telemetry is on, the **Diagnostic ZIP** button appears on every job's detail page. The ZIP contains `job-metadata.json`, `telemetry.ndjson`, `logs.txt`, `summary.md`, and per-job snapshots of the agent profile and active plugins.
+
+Retention: raw blobs > 7 days old are compacted at startup (file deleted, aggregates kept).
+
+Scope: rails only. The sidebar chat, Explore, AI Edit, and the setup wizard are not instrumented (telemetry env injection happens only in the queue manager).
+
+### Terminal panel
+
+Hot-reload semantics: font family/size, copy-on-select, long-running command threshold, and notify-on-completion apply **live** to existing sessions on save. Render mode, shell integration, and image rendering apply on **the next spawned session**.
+
+| Setting | Default | What it does |
+|---------|---------|--------------|
+| Font family | `'DM Mono', 'JetBrains Mono', ui-monospace, Menlo, monospace` | Terminal font |
+| Font size | 12 px | Cmd+= / Cmd+- live-zooms within a session |
+| Copy on select | off | Auto-copy when text is selected |
+| Render mode | auto | `auto` picks WebGL when available; falls back to canvas on context loss |
+| Shell integration | on | Inject OSC 133 / 1337 shim per shell |
+| Image rendering | on | Decode Sixel + iTerm2 inline images (`@xterm/addon-image`) |
+| Long-running command threshold | 60 s | Trigger a notification after this duration |
+| Notify on completion when unfocused | on | Emits a desktop notification when a long-running command finishes and the window isn't focused |
+
+Project overrides win per-field; missing fields fall back to app defaults; missing app defaults fall back to built-ins.
+
+See [terminal.md](terminal.md) for the full reference of keyboard shortcuts and shell integration.
+
+## App-wide settings
+
+Open **Desktop Settings** from the Arc sidebar. These apply across every project.
+
+| Section | What it does |
+|---------|--------------|
+| **Appearance** | Theme picker — see above. |
+| **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. |
+| **OS Notifications** | Native desktop notifications when jobs complete or fail. Notifications only fire when the tab isn't focused. Filter on all / completed-only / failed-only. |
+| **Outbound Webhooks** | Notify external tools (Slack, Zapier, CI/CD) on app events. Requests are signed with `X-Specrails-Signature` when a secret is set. |
+| **Terminal Panel** | The same terminal fields as per-project, applied app-wide as defaults. Per-project values override them. |
+| **Onboarding** | Re-run the welcome tour. |
+| **Desktop Information** | Version, paths, and diagnostics. |
+
+## Authentication
+
+There is no token to configure — the app manages it for you.
+
+On first run the app generates a token and persists it to `~/.specrails/desktop.token` (mode `0600`). Every `/api/*` route requires it (the only exceptions are `/api/health` and `/api/token`), and WebSocket upgrades carry it as a subprotocol. The browser client fetches the token same-origin, so you never see it.
+
+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.
+
+## 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.
+
+### 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_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_TERMINAL_PANEL=false` | Disable the bottom terminal panel everywhere |
+| `SPECRAILS_CODE_EXPLORER=false` | Disable the read-only Code section server-side |
+| `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_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_ALLOW_LOCAL_WEBHOOKS=1` | Allow outbound webhooks to target loopback / private-network addresses |
+
+### Client-side (Vite — set at build time)
+
+These feature flags are **default ON**. Set the flag to `false` to hide the feature.
+
+| Variable | Effect |
+|----------|--------|
+| `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_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 |
+
+> **Port:** the app doesn't read an env var for its port — use the `--port <n>` global flag: `specrails-desktop --port 5000 start`.
+
+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.
+
+## Resetting the app
+
+To wipe all app state (project registry, settings, theme) but keep your project source code intact:
+
+```bash
+specrails-desktop stop
+rm -rf ~/.specrails/desktop.sqlite* ~/.specrails/projects/
+specrails-desktop start
+```
+
+The `desktop.sqlite*` glob also removes the SQLite WAL/SHM sidecars. This deletes the project registry and every per-project SQLite. Your project directories on disk and their `.specrails/` folders (specs, profiles, plugins) are untouched. `desktop.token` and `manager.pid` regenerate harmlessly on the next start.
+
+For a more surgical reset (e.g. clear job history for one project but keep the registration), see [internals/operations-runbook.md](internals/operations-runbook.md).
+
+## Backup
+
+Everything the app knows is in `~/.specrails/`. Back it up:
+
+```bash
+tar -czf specrails-backup-$(date +%F).tar.gz -C ~ .specrails
+```
+
+Restore by extracting the archive in `~/`.
+
+Per-project specs, profiles, and plugins live in your project directories (`<project>/.specrails/`), so they ride along with `git`.
+
+## Where to go next
+
+- [Tracking cost](tracking-cost.md) — set a daily budget so you can stop checking the bill.
+- [Terminal panel](terminal.md) — fine-tune the bottom panel.
+- [Operations runbook](internals/operations-runbook.md) — port conflicts, stale PID files, recovery procedures.