specrails-desktop 2.7.0 → 2.9.0

package/docs/guide/en/pipeline/4-picking-an-engine-per-rail.md

@@ -0,0 +1,60 @@
+# Picking an engine per rail
+
+Specrails desktop treats **Claude Code**, **Codex CLI**, and **Gemini CLI** as first-class engines. A project can have one, two, or all three installed — and when more than one is present, you choose which engine runs each rail. This page covers the per-rail engine selector and when to reach for each.
+
+## When the selector appears
+
+The **engine selector** lives in the rail header, right alongside the mode control. It only renders when the project has **more than one** provider installed.
+
+> **Single-provider projects behave byte-identically.** If a project has just one engine, no selector shows and nothing about provider selection changes — it just runs on that engine. The selector is purely for multi-provider projects.
+
+When it does appear, your choice is **per rail and per launch** — different rails can run different engines, and your pick is remembered per project (defaulting to the project's primary engine).
+
+## How to pick an engine
+
+1. Make sure the rail's engine selector is showing (project has 2+ providers).
+2. Click it and choose **Claude**, **Codex**, or **Gemini**.
+3. Launch the rail with **▶ Play**.
+
+The selected engine runs every phase of that rail's pipeline. If the chosen engine's CLI isn't installed, the launch fails fast — nothing spawns. Install the missing CLI and try again.
+
+## What each engine is good at
+
+All three run the standard **Implement** and **Batch** pipelines. Here's a practical guide to choosing:
+
+| Engine | Reach for it when… | Notes |
+|--------|--------------------|-------|
+| **Claude** | You want the full feature set: agent profiles, Ultracode, native cost reporting, the richest tool support. The default for most work. | The only engine that supports **agent profiles**, **Ultracode**, and a few Claude-only spec features (Contract Layer, SMASH). |
+| **Codex** | You prefer the OpenAI Codex CLI or want to compare implementations across providers. | `codex` ≥ 0.128.0. No native cost reporting — the app fills in cost from its rate card. Profiles don't apply. |
+| **Gemini** | You want Google's Gemini CLI, native telemetry, or a cheaper run for routine specs. | `gemini` ≥ 0.11.0 (set `GEMINI_API_KEY`). Native OTLP telemetry. Profiles don't apply. |
+
+### The Claude-only features
+
+A few things only work on Claude rails — pick Claude if you need them:
+
+- **Agent profiles** — per-agent model routing. On Codex or Gemini rails the run always uses legacy mode and any selected profile is **ignored**. The profile picker is hidden for non-Claude engines.
+- **Ultracode (`Ultra` mode)** — the autonomous, pipeline-bypassing mode. The `Ultra` segment and its Haiku/Sonnet/Opus model picker only appear when the rail's engine is Claude.
+- **Contract Layer & SMASH** — Claude-only spec-refinement features (these are Add-Spec options, not rail options, but the same constraint applies).
+
+If a project mixes engines, the right sidebar only shows sections **every** installed provider supports — so the **Agents** section disappears entirely on a project that includes any non-Claude provider, because profiles are Claude-specific.
+
+## A practical workflow
+
+Multi-provider projects shine when you want to **compare** or **cost-tune**:
+
+- **Compare implementations.** Put the same spec on two rails, set one to Claude and one to Codex, launch both (across projects, or one after the other in the same project's queue), then use the **Compare** button on the Jobs page to diff the results.
+- **Cost-tune by spec.** Run high-stakes specs on Claude with a `max` profile; run routine cleanup specs on Gemini to save on spend. Filter `/analytics` by engine to see the breakdown.
+- **Default sensibly.** Set your most-used engine as the project's primary so rails default to it, and only switch per-rail when a specific spec wants a different engine.
+
+## Things to keep in mind
+
+- **Provider selection is immutable after project creation** (v1). You choose installed providers when you add the project; there's no Settings toggle to add or remove one later.
+- **Cost is always tracked**, even for engines without native cost reporting — the app falls back to a rate card so Codex and Gemini runs still show up in [analytics](../analytics/tracking-cost).
+- **The terminal's "Open AI CLI" button** also offers a provider picker on multi-provider projects, if you'd rather drive a CLI by hand.
+
+## Where to go next
+
+- [Using Codex](../integrations/using-codex) — install and sign in.
+- [Using Gemini](../integrations/using-gemini) — install, `GEMINI_API_KEY`, telemetry.
+- [Rails & jobs](rails-and-jobs) — the queue and launch flow.
+- [Tracking cost](../analytics/tracking-cost) — per-engine cost breakdown.

package/docs/guide/en/settings/1-themes.md

@@ -0,0 +1,37 @@
+# Themes
+
+Make Specrails look the way you like. The app ships with five hand-tuned themes you can switch between instantly — no restart, no rebuild, nothing to configure.
+
+## The five built-in themes
+
+| Theme | Feel |
+| --- | --- |
+| **Specrails** | The default. Balanced, calm, brand-aligned. |
+| **Dracula** | Classic dark purple. Easy on the eyes at night. |
+| **Aurora Light** | A bright, airy light theme for daytime work. |
+| **Obsidian Dark** | Deep, high-contrast dark mode. |
+| **Matrix** | Green-on-black, for when you want to feel like you're in the mainframe. |
+
+## How to switch
+
+1. Open **Settings** (the app-wide settings modal).
+2. Go to the **Appearance** section.
+3. Pick a theme. It applies immediately across the whole app.
+
+That's it. The change takes effect the moment you click — the interface re-skins live.
+
+## Where it applies
+
+Your theme choice is **app-wide**, not per-project. Every project, every page, every panel follows the same theme. It also reaches the places you might not expect:
+
+- **The terminal panel** re-colours live, keeping your scrollback and any running shell session intact.
+- **Charts** on the Analytics page re-tint to match.
+- **Code syntax highlighting** in the Code viewer follows the theme too.
+
+## It remembers your choice
+
+Your selection is saved with the app, so it sticks across restarts. To avoid that brief flash of the wrong colours when the app first opens, Specrails applies your saved theme before the interface even finishes loading — so what you see is right from the very first frame.
+
+## A note for the curious
+
+Themes are built on a small set of semantic colour roles (an "accent" colour, a "surface" colour, and so on) rather than hard-coded shades. That's why adding the next theme is easy and why every theme stays internally consistent — each one just remaps those roles. You don't need to think about any of this to use it; it's simply why theming feels so seamless.

package/docs/guide/en/settings/2-language.md

@@ -0,0 +1,39 @@
+# Language
+
+Specrails speaks your language. The interface is fully translated into eight languages, and by default it follows whatever language your computer is set to — so for most people, it just shows up in the right language on first launch.
+
+## Supported languages
+
+- English
+- Español (Spanish)
+- Français (French)
+- Deutsch (German)
+- Português (Portuguese)
+- Italiano (Italian)
+- 中文 (Chinese)
+- 日本語 (Japanese)
+
+## It starts in your OS language
+
+The first time you open Specrails, it looks at your operating system's language preferences and matches them to the closest supported language. If your Mac or PC is set to Spanish, you'll see Spanish. If it's set to a regional variant (like `es-ES` or `zh-Hans-CN`), Specrails maps it to the right base language automatically.
+
+You don't have to do anything — and if you never touch the language setting, Specrails keeps following your OS. Change your computer's language later, and Specrails follows along.
+
+## Choosing a language yourself
+
+Want something different from your OS default? Pick it explicitly:
+
+1. Open **Settings**.
+2. Go to the **Language** section.
+3. Choose your language.
+
+The switch is **instant** — the whole interface re-renders in the new language with no restart. Once you make an explicit choice, Specrails remembers it and stops following the OS, so your pick is honoured every time you open the app.
+
+## What gets translated
+
+Everything you read in the interface — buttons, labels, status messages, page titles, dialogs. Dates also adapt to your chosen language, so they're formatted the way that language expects.
+
+## Good to know
+
+- **English is the source language.** If a brand-new feature ships before its translation is finished, you may briefly see an English label here or there — it will be translated in a following update.
+- Your language choice is **app-wide**, the same across all your projects.

package/docs/guide/en/settings/3-pipeline-telemetry-and-diagnostics.md

@@ -0,0 +1,46 @@
+# Pipeline telemetry & diagnostics
+
+When a pipeline job doesn't go the way you expected, telemetry gives you a detailed, behind-the-scenes record of what the AI CLI actually did. It's **off by default** and entirely opt-in, per project — turn it on only when you want it.
+
+## What it is
+
+Telemetry captures structured diagnostic signals (traces, metrics, and logs) emitted by the AI CLI while it runs a pipeline job. Think of it as a flight recorder for your pipeline runs: timings, token usage, and step-by-step activity, captured locally so you can inspect a job after the fact.
+
+It's built on **OpenTelemetry**, an open, standard format — so the data isn't locked into a proprietary box.
+
+## Turning it on
+
+Telemetry is configured **per project**:
+
+1. Open the project's **Settings** page (the per-project settings route).
+2. Find the **Pipeline telemetry** toggle.
+3. Switch it on.
+
+From that point forward, pipeline jobs in that project record telemetry. Other projects are unaffected — each project decides for itself.
+
+### What's covered
+
+Telemetry applies to **pipeline jobs** (the queued Architect → Developer → Reviewer → Ship rail runs). Interactive sessions like chat and the setup wizard are intentionally left out — telemetry is meant for the repeatable, inspectable pipeline runs, not one-off conversations.
+
+## Where the data lives
+
+Everything stays on your machine, under your home directory (`~/.specrails/`) — never in your repo. Raw recordings are stored compressed alongside their job, and older recordings are automatically condensed into compact summaries after a week to keep things tidy. You never have to manage any of this by hand.
+
+## Exporting a diagnostic bundle
+
+The most useful thing telemetry unlocks is the **diagnostic export** — a single ZIP that packages up everything about a job for troubleshooting or sharing.
+
+When a job has telemetry recorded, an **export button** appears on its job card. Click it to download a ZIP containing:
+
+- **`job-metadata.json`** — the job's identity and parameters
+- **`telemetry.ndjson`** — the raw recorded signals
+- **`logs.txt`** — the captured log output
+- **`summary.md`** — a human-readable summary of the run
+
+If the project uses plugins, the bundle also includes a snapshot of which plugins were active for that job.
+
+This is the bundle to grab when you want to understand a tricky run, keep a record, or hand details to someone helping you debug.
+
+## Turning it off
+
+Flip the toggle back off any time. New jobs stop recording immediately. Anything already captured stays on disk until it's compacted or you remove the project — nothing is sent anywhere or lost behind your back.

package/docs/guide/en/settings/4-where-your-data-lives.md

@@ -0,0 +1,48 @@
+# Where your data lives
+
+Short version: **Specrails keeps your repositories pristine.** When you point the app at one of your projects, it does not move in, scatter config files around, or rewrite anything you didn't ask it to. Your code stays yours, and clean.
+
+## Your repo stays clean
+
+Specrails's own files — its databases, per-project state, agent definitions, settings, telemetry, summaries, and everything else it needs to run — live in a single tidy home under your home directory:
+
+```
+~/.specrails/
+```
+
+That folder is the app's private workspace. It's where the project registry, per-project databases, bundled tooling, and all the operational bits live. Your actual code repositories are never used as a dumping ground for any of it.
+
+This means:
+
+- Your repo's `.gitignore` is **not** rewritten by the app.
+- Your repo isn't littered with tool config or hidden state directories.
+- Removing a project from Specrails doesn't leave a mess behind in your code.
+
+If you've used tools before that quietly added folders and files all over your project, this is a deliberate departure. Specrails is built so that pointing it at a repo is a **non-event** for that repo's git history.
+
+## The one thing that *is* committed — by design
+
+There's exactly one intentional exception, and it's the whole point of the tool: **your OpenSpec specs.**
+
+Specs live in your repository, under:
+
+```
+openspec/
+```
+
+This is on purpose. Your specs are a **deliverable** — a versioned, reviewable record of what you decided to build and why. They belong next to your code, tracked in git, visible in pull requests, shared with your team. That's the value: specs aren't disposable scratch state, they're part of your project's history.
+
+So the rule is simple and honest:
+
+- **`openspec/`** → lives in your repo, committed, by design.
+- **Everything else Specrails needs** → lives under `~/.specrails/`, out of your way.
+
+## Why it works this way
+
+Specrails runs the AI tooling from its own private workspace (under `~/.specrails/`) and reaches back into your real repository only for the things that genuinely need to touch it — reading your code, and writing the specs you asked for. The tooling, the framework definitions, and the bookkeeping all stay in the app's home folder.
+
+The upshot for you: you can add a project, run pipelines, explore specs, and try things out with confidence that your repository's working tree and git history only ever change in ways you'd expect — your committed specs, and the code your pipelines write. Nothing else sneaks in.
+
+## Removing a project
+
+When you remove a project from Specrails, the app cleans up its own per-project state under `~/.specrails/`. The specs already committed to your repo stay where they belong — in your repo — because they're yours.

package/docs/guide/en/specs/1-specs-and-the-backlog.md

@@ -0,0 +1,52 @@
+# Specs & the backlog
+
+A **spec** is the unit of work the AI pipeline implements. Think of it as a ticket: a title, a description of what you want done, a priority, and optional labels. When you launch the pipeline, the AI agents read the spec and act on it — so a clear spec is the single most important input to a good result.
+
+Specs are sometimes called **tickets** in the app — the two words mean the same thing.
+
+## The board
+
+Every project opens on its **Dashboard**, which shows the **SpecsBoard** — the list of all the project's specs. This is your backlog. From here you create new specs, set their priority, drag them onto a rail to implement them, and watch their status change as work happens.
+
+The board has two view modes, switched from a toolbar toggle and remembered per project:
+
+- **Post-it view** (the default) — card-style tiles with short summaries.
+- **List view** — compact one-line rows.
+
+You can also filter by **status** (All / ToDo / Done) and by **label**, and sort by **Default**, **Ticket #**, or **Priority** (each with an ascending/descending toggle).
+
+## Statuses
+
+A spec moves through a small set of statuses. The board gives each one a consistent visual cue so you can read the state of your backlog at a glance:
+
+| Status | What it means |
+|--------|---------------|
+| **Draft** | An in-progress idea saved from an Explore conversation. Not ready to implement yet — you can come back and keep shaping it. Shows a `Draft` pill. |
+| **Todo** | Ready to be picked up. This is where a finished spec lands when you create it. |
+| **In progress** | The pipeline is currently working on it (a pulsing blue dot). |
+| **Done** | Completed by the pipeline (a green checkmark). |
+| **Cancelled** | Abandoned (a red X). |
+
+Drafts live in the same active bucket as Todo specs — there's no separate column for them — but they carry a subtly tinted border and a `Draft` pill so they're easy to spot. See [Drafts & the Contract Layer](drafts-and-contract-layer.md) for the full story on drafts.
+
+## Priorities
+
+Every non-draft spec has a priority: **Critical**, **High**, **Medium**, or **Low**. Priority is purely an organising tool — it helps you decide what to implement next and lets you sort the board. You set it when you create a spec, and you can change it any time by right-clicking the spec card and choosing **Set priority**.
+
+Drafts are the one exception: a draft can have *no* priority at all, because it's still an idea in progress. The priority gets locked in when you commit the draft to a real spec.
+
+## Creating a spec
+
+To create a spec, click **Add** (the Plus button on the SpecsBoard toolbar). The **Add Spec** dialog opens with a few ways to work:
+
+- **Quick mode** — you describe what you want and the AI writes the full spec in one shot. See [Add Spec — Quick mode](add-spec-quick-mode.md).
+- **Explore mode** — you converse with the AI, and it helps you shape the spec turn by turn. See [Add Spec — Explore mode](add-spec-explore-mode.md).
+- **Raw mode** — whatever you type is saved verbatim as a spec, with no AI involved. Use it when you already have the spec text written.
+
+Which one you reach for depends on how clear the idea already is. Know exactly what you want? Quick. Still figuring it out? Explore. Already have the text? Raw.
+
+## Where to go next
+
+- [Add Spec — Quick mode](add-spec-quick-mode.md) — the fastest way to turn an idea into a spec.
+- [Add Spec — Explore mode](add-spec-explore-mode.md) — shape a spec in conversation.
+- [Drafts & the Contract Layer](drafts-and-contract-layer.md) — save work in progress and enrich specs for the pipeline.

package/docs/guide/en/specs/2-add-spec-quick-mode.md

@@ -0,0 +1,45 @@
+# Add Spec — Quick mode
+
+Quick mode is for when you already know what you want. You type your idea, the AI writes the full spec, and it lands on your board as a **Todo**. No back-and-forth — just describe it and go.
+
+## Create a spec in Quick mode
+
+To create a spec quickly:
+
+1. On the Dashboard, click **Add** (the Plus button on the SpecsBoard toolbar).
+2. Choose **Quick** mode.
+3. Type your idea in the text field — a sentence or a paragraph, whatever captures it.
+4. Click to generate.
+
+While the spec is being written, a small toast in the corner shows the project name, a snippet of your idea, and the **elapsed time** ("Generating… 0:12"). When it finishes, the toast switches to "Generated in <time>" with a **View** action that jumps straight to your new spec.
+
+That's the whole flow. Everything below is optional fine-tuning.
+
+## What you can tune
+
+**Model** — by default the AI picks a sensible model. You can override it per spec from the model picker if you want a faster or more capable one.
+
+**Engine** — if your project has more than one AI provider installed (any mix of Claude, Codex, and Gemini), an engine selector sits at the top of the dialog so you can choose which one generates this spec. Your choice is remembered per project. Single-provider projects don't show this — there's nothing to choose between.
+
+**Context** — Quick mode usually runs as a single turn, because it doesn't need to read your codebase to write a spec from your description. But a context slider lets you give it more to work with:
+
+- At the lowest setting it just reads your description.
+- At higher settings it can read your existing specs, your project's OpenSpec specs, and even your full codebase before writing.
+
+The more context you give it, the longer generation takes (it switches to multi-turn so it can read first), but the spec comes back grounded in your actual project. Reach for higher context when the spec needs to reference real code, file names, or existing behaviour.
+
+**Attachments** — drop mockups, briefs, or data files into the idea field. The AI reads them as part of writing the spec. (Attachments also switch generation to multi-turn.)
+
+**Enrich with Contract Layer** — a toggle that appends a structured block to the generated spec so the downstream pipeline doesn't have to guess names or data shapes. It's optional and off by default; your last choice is remembered per project. See [Drafts & the Contract Layer](drafts-and-contract-layer.md) for what it adds and when it's worth it.
+
+## When to use Quick mode vs Explore
+
+Use **Quick** when the idea is already clear in your head — you could write the spec yourself, you'd just rather the AI do it. Use [**Explore**](add-spec-explore-mode.md) when you're still thinking it through and want a partner to help you shape it.
+
+A spec created in Quick mode is a fully normal spec: you can later open it and **Continue Editing** in an Explore session if it needs refining.
+
+## Where to go next
+
+- [Add Spec — Explore mode](add-spec-explore-mode.md) — for specs that need shaping.
+- [Drafts & the Contract Layer](drafts-and-contract-layer.md) — the Contract Layer enrichment explained.
+- [Running pipelines](running-pipelines.md) — drag your new spec onto a rail and implement it.

package/docs/guide/en/specs/3-add-spec-explore-mode.md

@@ -0,0 +1,68 @@
+# Add Spec — Explore mode
+
+Explore mode is a conversation. Instead of writing the spec yourself, you talk through the idea with the AI — it acts as a thinking partner, asks questions, proposes structure, and builds a **live draft** of the spec as you go. When you're happy, you commit the draft to a real spec.
+
+Reach for Explore when the idea isn't fully formed yet, when there are trade-offs to talk through, or when you want the AI to look at your actual code before pinning down the spec.
+
+## Create a spec in Explore mode
+
+To shape a spec in Explore mode:
+
+1. On the Dashboard, click **Add**, then choose **Explore**.
+2. Type your first message — the idea, a question, or a half-formed thought.
+3. Read the AI's response and keep replying. Each turn, it refines its understanding.
+4. Watch the **live draft** update alongside the chat — this is the spec taking shape.
+5. When the draft looks right, click **Create Spec**.
+
+The conversation stays in your history, so you can always come back to see how the spec was shaped.
+
+## The live draft
+
+As you converse, a draft pane shows the spec as it currently stands — title, description, priority, labels, acceptance criteria. It rewrites itself each turn based on what you've discussed. You don't edit it directly; you steer it through the conversation ("actually, make the priority high", "add a criterion about error handling", and so on).
+
+This is the heart of Explore mode: you're never staring at a blank form. You're always looking at a real, evolving spec.
+
+## How much the AI sees: the context slider
+
+Before the AI answers, you decide how much of your project it can see. A context preset slider lets you trade speed for depth:
+
+| Preset | What the AI sees |
+|--------|------------------|
+| **Minimal** | Just your message. Fastest and cheapest. |
+| **Light** | + your existing specs. |
+| **Standard** | + your specs and your project's OpenSpec specs. |
+| **Rich** | + read access to your full codebase, so it can ground answers in real code. |
+| **Max** | Rich, plus a Contract Layer enrichment pass on commit. |
+| **Desktop** | Max, plus your project's MCP servers and your own approved MCP servers. |
+
+Start low for fast brainstorming; move up when you want the AI to verify its suggestions against your actual code. The choice is saved on the conversation, so it doesn't leak into other Explore sessions.
+
+If you want finer control, click **Fine-tune** to flip the underlying options by hand — including **My approved MCPs**, which loads the MCP servers you've already approved locally without slowing the session down.
+
+## Buttons in the Explore shell
+
+- **Create Spec** — promotes the live draft to a real spec with status **Todo**. (When you're editing an existing spec, this button reads **Update Spec** instead and patches that spec in place.)
+- **Review →** — opens a Review overlay that shows the proposed spec diffed against the baseline before you commit, so there are no surprises.
+- **Save as Draft** — persists the conversation as a draft ticket so you can pick it up later. Available as soon as you've sent at least one message. See below.
+- **Minimize** — parks the conversation as a chip in the minimized-chats dock at the bottom-left. Click the chip any time to drop right back into the conversation — nothing is lost.
+- **Discard** — throws the conversation away (asks for confirmation first).
+
+## Saving as a draft
+
+Not ready to commit, but don't want to lose the thinking? Click **Save as Draft**. The conversation becomes a **draft spec** on your board, and the draft stays linked to the conversation behind it.
+
+Later, open the draft from the board and click **Continue Editing** — the original conversation re-opens with its full chat history intact, and you carry on exactly where you left off. Drafts are never auto-deleted; they wait for you.
+
+This makes Explore safe to use for half-baked ideas: start a conversation, get somewhere, save it as a draft, and come back tomorrow.
+
+For everything about drafts — including the Contract Layer enrichment — see [Drafts & the Contract Layer](drafts-and-contract-layer.md).
+
+## Multi-provider note
+
+If your project has more than one AI provider installed, an engine selector lets you pick which one drives the Explore conversation. Single-provider projects don't show it.
+
+## Where to go next
+
+- [Drafts & the Contract Layer](drafts-and-contract-layer.md) — saving work in progress and enriching specs for the pipeline.
+- [Add Spec — Quick mode](add-spec-quick-mode.md) — when the idea is already clear.
+- [Running pipelines](running-pipelines.md) — implement your spec once it's ready.

package/docs/guide/en/specs/4-drafts-and-contract-layer.md

@@ -0,0 +1,81 @@
+# Drafts & the Contract Layer
+
+This page covers two ways to get more out of your specs: **drafts** (saving an in-progress idea so you can resume it later) and the **Contract Layer** (an optional enrichment that makes specs more precise for the AI pipeline).
+
+## Drafts: save an idea in progress
+
+A **draft** is an in-progress [Explore](add-spec-explore-mode.md) conversation saved as a spec. It lets you stop mid-thought without losing anything and come back when you're ready.
+
+### Saving a draft
+
+While you're in an Explore conversation, click **Save as Draft** (available once you've sent at least one message). The app:
+
+- Creates a spec with status **Draft** on your board.
+- Gives it a title automatically if you didn't set one (a short summary of the conversation).
+- Links it back to the conversation, so the full chat history is preserved.
+
+Saving is idempotent — if you save the same conversation twice, it updates the existing draft instead of creating a duplicate.
+
+### How drafts look on the board
+
+Drafts live in the same active bucket as your Todo specs — there's no separate column. You'll spot them by:
+
+- A `Draft` pill where the priority pill normally sits.
+- A subtly tinted border on the card.
+
+A draft is allowed to have *no priority* — you set the priority when you commit it to a real spec.
+
+### Resuming a draft
+
+To pick up where you left off:
+
+1. Open the draft from the board.
+2. Click **Continue Editing** in the detail modal.
+3. The original Explore conversation re-opens with its full chat history, and the live draft pane pre-filled with everything you'd shaped so far.
+4. Keep talking. When you're done, **Create Spec** promotes the draft to a real spec (status **Todo**, with the priority you choose).
+
+### Discarding a draft
+
+Drafts are **never auto-deleted**. They disappear only when you explicitly discard them, or when you commit them to a real status. Discarding a draft also cleans up its linked conversation when nothing else references it.
+
+> Tip: when you're not sure a spec is worth doing, save it as a draft and let it sit. Open it the next morning, glance at the description, and decide with fresh eyes.
+
+## The Contract Layer: precision for the pipeline
+
+The **Contract Layer** is an optional enrichment that appends a structured block to a spec's description. Its job is to remove guesswork for the AI agents that implement the spec — so they reuse the right names, match the expected data shapes, and touch the right files instead of inventing their own.
+
+### What it adds
+
+The Contract Layer is five short sections appended to the spec:
+
+- **Naming Contract** — the exact identifiers (functions, fields, routes) the implementation should reuse.
+- **Data Shapes** — the JSON-ish payloads involved.
+- **State Machine** — the transitions or states the feature moves through.
+- **Invariants** — properties that must always hold true.
+- **File Touch List** — the files the implementation is expected to edit.
+
+Think of it as handing the pipeline a precise blueprint instead of a sketch. It's especially valuable for specs that plug into existing code, where the AI guessing a name or a shape would cause rework.
+
+### How to add it
+
+There are three ways the Contract Layer gets applied:
+
+- **Quick mode** — flip the **Enrich with Contract Layer** toggle before generating. Your last choice is remembered per project. (See [Add Spec — Quick mode](add-spec-quick-mode.md).)
+- **Explore mode** — choose the **Max** or **Desktop** context preset (which run the enrichment automatically on commit), or open **Fine-tune** and toggle it by hand. (See [Add Spec — Explore mode](add-spec-explore-mode.md).)
+- **On an existing spec** — open the spec's detail modal and re-run the enrichment from there.
+
+### Where it shows up
+
+Once a spec has a Contract Layer, the detail modal shows it as a collapsible disclosure with a badge like `3/5 populated` — telling you how many of the five sections actually got filled in (some features simply don't have, say, a state machine, and those sections are marked as not applicable). Expand it to read the full contract; collapse it to keep the description tidy.
+
+If the enrichment ever fails to run, the app surfaces a notification with a **Retry** action so you can fire it again.
+
+### Is it always worth it?
+
+Not always. For a small, self-contained spec the AI can implement fine without it. The Contract Layer earns its keep on specs that integrate tightly with existing code, where exact names and shapes matter — that's when pinning down the contract up front saves you a round of corrections later.
+
+## Where to go next
+
+- [Add Spec — Explore mode](add-spec-explore-mode.md) — where drafts come from.
+- [Add Spec — Quick mode](add-spec-quick-mode.md) — the Contract Layer toggle in Quick mode.
+- [Running pipelines](running-pipelines.md) — implement a spec once it's ready.

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

@@ -0,0 +1,38 @@
+# Conoce a los agentes
+
+Cuando lanzas un rail de **Implement**, Specrails no le entrega tu spec a una sola IA con la esperanza de que salga bien. En su lugar, pone a trabajar a un pequeño equipo de *agentes* especializados, cada uno con una única tarea, en un orden deliberado. Esta página te presenta a quiénes forman ese equipo y qué hace cada uno.
+
+## El trío base
+
+Cada ejecución del pipeline usa estos tres agentes — son la columna vertebral, y un proyecto no puede lanzar un rail sin ellos.
+
+| Agente | Rol | Qué hace |
+|-------|------|--------------|
+| **sr-architect** | El que planifica | Lee tu spec, inspecciona el código y produce un plan de implementación concreto: qué archivos tocar, qué forma tendrá el cambio y a qué prestar atención. Piensa antes de que nadie escriba código. |
+| **sr-developer** | El que construye | Toma el plan del architect y escribe el código de verdad: archivos nuevos, ediciones, tests. Aquí es donde tu spec se convierte en un diff real. |
+| **sr-reviewer** | El crítico | Valida el trabajo del developer contra la spec y el plan, detecta regresiones y pone reparos cuando algo no encaja. Es el control de calidad antes de dar el cambio por terminado. |
+
+Piénsalo como **diseñar → construir → revisar**, el mismo ciclo que seguiría un equipo humano cuidadoso. Cada agente le pasa su resultado al siguiente, así que el developer nunca trabaja a ciegas y el reviewer siempre tiene la intención original con la que contrastar.
+
+## Agentes especialistas
+
+Más allá del trío, un proyecto puede incluir **agentes especialistas** opcionales que se encargan de tipos de trabajo específicos. El más común que verás es:
+
+- **sr-merge-resolver** — un agente de utilidad que ayuda a desenredar conflictos de merge y a reconciliar cambios que se solapan. Es opcional: los perfiles lo incluyen solo cuando lo quieres, y nunca bloquea el pipeline si no está presente.
+
+Los especialistas son opcionales y de adhesión voluntaria. Un proyecto recién creado funciona solo con el trío; añades especialistas (y tus propios **agentes personalizados** — consulta [Agentes personalizados y el catálogo](custom-agents-catalog)) cuando el flujo de trabajo del proyecto lo pide.
+
+## Cómo llega cada tarea al agente adecuado
+
+Dentro de una ejecución, el trabajo se *enruta*. Cada tarea lleva etiquetas, y las reglas de enrutado de un perfil envían las tareas etiquetadas al agente que mejor encaja con ellas — con una regla final que sirve de comodín y manda todo lo demás al developer. No tienes que pensar en esto para el uso normal; la configuración por defecto enruta todo con sentido desde el primer momento. Cuando estés listo para dirigir ciertos tipos de trabajo a ciertos agentes, consulta [Personalizar los modelos por agente](customizing-models-per-agent).
+
+## Una idea importante, de entrada
+
+La *definición* de cada agente — sus instrucciones, su personalidad, lo que tiene permitido hacer — es **compartida**. Vive en archivos (`.claude/agents/<id>.md`) que viajan con tu repositorio, así que todo tu equipo ejecuta el mismo architect, el mismo reviewer.
+
+Lo que es **por proyecto** es la *configuración* que se monta encima: con qué modelo corre cada agente y qué combinación de agentes eliges para un rail concreto. Para eso están los perfiles — y de eso trata la siguiente página.
+
+## A dónde ir después
+
+- [Perfiles y el equilibrado por defecto](profiles-and-the-balanced-default) — cómo se empaqueta y se selecciona la configuración del equipo.
+- [Personalizar los modelos por agente](customizing-models-per-agent) — ajusta coste y calidad.

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

@@ -0,0 +1,45 @@
+# Perfiles y el equilibrado por defecto
+
+Un **perfil** es una receta guardada para una ejecución del pipeline. Responde a tres preguntas en un solo sitio:
+
+1. **Qué agentes** participan (el trío base, más cualquier especialista o agente personalizado).
+2. **Con qué modelo** corre cada agente.
+3. **Cómo se enrutan las tareas** hacia esos agentes.
+
+Encontrarás los perfiles en la sección **Agentes** de cualquier proyecto (barra lateral derecha → **Agentes** → la pestaña **Perfiles**).
+
+## El equilibrado por defecto
+
+Desde el primer momento, un proyecto resuelve hacia un perfil **default** sensato. Incluye el trío base — `sr-architect`, `sr-developer`, `sr-reviewer` — y enruta cada tarea al developer mediante una única regla comodín. Los modelos están equilibrados para el trabajo del día a día: un modelo capaz donde importa, sin tirar de la opción más cara en cada paso.
+
+Si tu proyecto ya tenía los modelos de los agentes configurados a la antigua usanza (en el frontmatter de los archivos de agente), el botón **Migrar** los lee y construye un perfil `default` que replica el comportamiento actual exactamente — sin pérdidas, nada cambia hasta que tú decidas ajustarlo.
+
+El titular: **no necesitas crear un perfil para usar Specrails.** El default simplemente funciona. Los perfiles son la forma de llegar más lejos.
+
+## Cómo se elige un perfil para una ejecución
+
+Cuando lanzas un rail, Specrails elige un perfil en este orden:
+
+1. **Tu elección explícita** en la cabecera del rail (ver abajo).
+2. Tu **preferencia por desarrollador** — un perfil que has marcado como tu default personal para este proyecto (es local a ti y no se commitea).
+3. El perfil **`default`** del proyecto.
+
+El perfil se *toma como snapshot en el lanzamiento*, así que cada rail de un lote puede correr un perfil distinto, y cambiar un perfil más tarde nunca reescribe los jobs que ya empezaron.
+
+## Seleccionar un perfil por rail
+
+La selección de perfil ocurre justo donde lanzas — en la **cabecera del rail**, mediante el selector de perfil.
+
+- Elige un perfil del desplegable para usarlo en **este lanzamiento solamente**.
+- Usa la opción de persistir para convertir un perfil en la elección permanente del rail de ahí en adelante.
+
+Ese es todo el flujo: elige un perfil, lanza, listo. Los rails concurrentes de un mismo lote pueden llevar cada uno su propio perfil, así que un arreglo rápido y una feature pesada pueden correr en paralelo con configuraciones distintas.
+
+## Cuando la sección Agentes está en silencio
+
+Los perfiles son una capacidad de Claude. En un proyecto que incluye un proveedor que no es Claude (Codex o Gemini), la sección Agentes se oculta y los rails corren sin perfiles — eso es lo esperado, no un fallo. Los perfiles también requieren un `specrails-core` lo bastante reciente en el proyecto; si es más antiguo, verás un banner amarillo. Los perfiles que crees igualmente se **guardan** — simplemente no afectan al pipeline hasta que se actualice core. Actualiza con el comando que muestra el banner para desbloquearlos.
+
+## A dónde ir después
+
+- [Personalizar los modelos por agente](customizing-models-per-agent) — crea perfiles `fast` y `max`.
+- [Agentes personalizados y el catálogo](custom-agents-catalog) — conoce y amplía el equipo.

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

@@ -0,0 +1,60 @@
+# Personalizar los modelos por agente
+
+Lo más útil que te permiten hacer los perfiles es **elegir el modelo adecuado para cada paso**. Un paso de planificación quizá merezca tu modelo más potente; un paso de construcción rutinario seguramente esté la mar de contento con algo más rápido y barato. Los perfiles te dejan expresar exactamente eso.
+
+Aquí es donde la separación entre lo compartido y lo que es por proyecto da sus frutos:
+
+- Las *definiciones* de los agentes siguen siendo compartidas en todo tu equipo.
+- El *modelo con el que corre cada agente* se configura **por proyecto**, dentro de un perfil, y solo afecta a tu proyecto.
+
+Cambia un modelo y cambias el coste y el comportamiento para ese proyecto — sin tocar la configuración de nadie más ni las instrucciones subyacentes del agente.
+
+## Cambiar qué modelo usa un agente
+
+En **Agentes → Perfiles**, selecciona un perfil y abre su editor de cadena de agentes. Cada agente de la cadena tiene un campo de modelo. También hay un modelo **orquestador** que se encarga de la coordinación de alto nivel del pipeline.
+
+Los valores de modelo son alias — para Claude son `opus`, `sonnet` y `haiku` (de más capaz → más rápido). Asigna el alias que quieras por agente:
+
+- Deja el modelo de un agente **en blanco** para que recurra al default propio del archivo del agente.
+- Asígnalo explícitamente para sobrescribirlo solo en este perfil.
+
+Guarda, y el próximo rail lanzado con ese perfil usará los nuevos modelos. Los jobs que ya están en marcha conservan su snapshot.
+
+## Crear perfiles como `fast` y `max`
+
+El patrón natural es tener un par de perfiles con nombre a los que recurres según el trabajo:
+
+**Un perfil `fast`** — para cambios pequeños y de bajo riesgo donde quieres velocidad y una factura más reducida:
+
+- Architect: un modelo intermedio o rápido — el plan es simple.
+- Developer: un modelo rápido — el cambio es mecánico.
+- Reviewer: mantenlo sólido, aunque también puedes recortar aquí.
+
+**Un perfil `max`** — para features espinosas y de mucho en juego donde quieres que cada paso sea lo más afilado posible:
+
+- Architect, developer y reviewer: tu modelo más potente en todos los frentes.
+
+### Dos formas de construir uno
+
+1. **Duplicar y ajustar** *(recomendado).* Selecciona tu perfil `default`, **Duplícalo**, dale a la copia un nombre en kebab-case como `fast` o `max`, y luego ajusta el modelo de cada agente. Heredas una cadena y un enrutado que sabes que funcionan y solo cambias lo que pretendes cambiar.
+2. **Empezar en blanco.** Crea un **Perfil en blanco** y monta la cadena tú mismo. Sigues teniendo que incluir el trío base (`sr-architect`, `sr-developer`, `sr-reviewer`) — el pipeline depende de los tres — y exactamente una regla de enrutado comodín terminal, que debe ir la última.
+
+Los nombres de perfil van en minúsculas y kebab-case (p. ej. `fast`, `max`, `cheap-and-cheerful`).
+
+## Enrutar tareas a agentes concretos
+
+Las **reglas de enrutado** de un perfil deciden qué agente se encarga de una tarea etiquetada. Cada regla lista etiquetas de tarea y un agente de destino; gana la primera regla cuyas etiquetas coincidan, y una única regla `default: true` al final captura todo lo demás. Solo los agentes que están realmente en la cadena del perfil pueden ser destinos de enrutado — el editor lo obliga.
+
+Para el uso del día a día no tocarás el enrutado: la regla comodín manda el trabajo al developer y eso es correcto. Echa mano de las reglas por etiquetas cuando quieras, por ejemplo, que el trabajo etiquetado como `migration` vaya a un especialista en lugar del developer.
+
+## Elegir el perfil cuando lanzas
+
+Todo esto se junta en el lanzamiento: en la cabecera del rail, elige `fast`, `max` o `default` por rail. Un lote puede mezclarlos — un arreglo diminuto en `fast`, una feature grande en `max`, ambos corriendo a la vez. Consulta [Perfiles y el equilibrado por defecto](profiles-and-the-balanced-default) para el flujo de selección.
+
+## Una nota sobre seguridad
+
+Eliminar un perfil es seguro para el trabajo en marcha: los jobs que ya se lanzaron con él conservan su snapshot, y los lanzamientos futuros simplemente recurren al orden de resolución. Experimenta sin miedo.
+
+## A dónde ir después
+
+- [Agentes personalizados y el catálogo](custom-agents-catalog) — añade agentes para meter en tus cadenas.