specrails-desktop 2.64.2 → 2.65.0

package/docs/guide/en/integrations/8-flow-mode.md

@@ -0,0 +1,69 @@
+# Flow: build first, spec later {#flow-mode}
+
+Flow is a way to build with an agent when you do not know yet exactly what you want. You talk to the agent in your mission, it writes and runs real code on its own Flow branch (a separate copy of your project), and when the result is right you press **Hand off**: a rail takes your changes, derives the spec and runs the usual verification, review and delivery.
+
+Implement is for delegating work you can already describe. Flow is for discovering it.
+
+## How a Flow starts
+
+You never have to ask for Flow by name. When you describe something exploratory or visual ("I want to try…", "I don't know how it should look"), the mission shows a card with two paths:
+
+- **Flow**: build it together now; the spec comes at the end.
+- **Spec + Implement**: agree on a spec first, then delegate it to a rail.
+
+Both paths carry the same weight and always appear in the same order: neither is recommended, you choose. Under **Why the agent asked** the agent says in one sentence what made it ask, and it will not insist whichever path you pick or if you press **Not now**.
+
+Choosing Flow opens a confirmation: Specrails makes a separate copy of the project on its own Flow branch, where the agent can write code, and your main branch is not touched. Press **Start Flow**. A placeholder spec appears on the board with the **In Flow** label (click it to jump back to the mission).
+
+If your Specrails Core cannot run Flow yet, Start is disabled and the card lists what is missing. Usually an update of Specrails Core fixes it.
+
+## Start a Flow from a spec you already have
+
+Any spec can be built in Flow, not only a new idea. Flow and Implement stay two equal ways to work on it:
+
+- on the board, right-click a spec and choose **Start in Flow** (next to dragging it onto a rail); in the spec detail, **Start in Flow** sits next to **Move to Rail**;
+- in a mission, when you ask to implement a spec without naming a rail, the agent shows the same two-path card for that spec: **Flow** works on it with you, **Spec + Implement** launches it on a rail;
+- a rail-launch card for one spec also offers **Start in Flow** next to its launch.
+
+The spec itself goes **In Flow**: no placeholder is created, and the agent's first turn receives the spec (its acceptance criteria, Contract Layer, out-of-scope list and open addenda). Started from the board, the Flow opens in the spec's own mission, or in a new mission named after the spec. In a project with several Git repositories, when the spec does not name exactly one of them, a small dialog first asks where the Flow runs: only the Git repositories are listed, the spec's own repository (or else the primary) is preselected, and the arrow keys change the choice. **Start in Flow** is disabled, with the reason on hover, when the spec is already in Flow, done or cancelled, sits on a rail, or Flow is not available.
+
+**Discard** gives the spec back exactly as it was, with its previous status: your spec is never deleted. When the Flow is delivered, the spec is rewritten from what was built, and its original text is first kept as a comment, **Original spec before Flow**, so nothing is lost. A spec already linked to Jira updates that same issue and moves it to the status mapped for review; no second issue is created.
+
+## While you are in Flow
+
+Flow mode is named where you look, in its own Flow color: the composer shows a **Flow** chip next to the autonomy chip and the hint *Tell the agent what to change in this Flow…*; the mission title reads **In Flow**, and so does its row in the mission list. The conversation marks where you entered and left Flow, and the agent's replies written in Flow carry a small **Flow** mark next to their time.
+
+The strip just above the composer shows the Flow in one short row: its status, **Flow · 7 files**, **Pause Flow** and the main action, **Hand off**. When an action is unavailable (the Flow is still saving, another action runs), hovering it says why. Open the row with its chevron, like any other run, to see the rest:
+
+- the **branch** (click to copy its name), the **changes** with lines added and removed (click to list every changed file with its status and +/−), and the **cost so far** as billed by the provider. It shows `—` until a turn has a reported cost, and never an estimate; a `*` marks a total that leaves out unpriced turns, with a note saying how many;
+- **Preview** while the Flow's app runs (see below);
+- **Discard**, set apart, deletes the Flow's changes, its branch and the placeholder spec. The confirmation lists what you lose: the changed files with their +/−, the branch and the spec.
+
+**Pause Flow** stops the agent and keeps your changes and the spec. The row then shows **Resume Flow**.
+
+You can write while the agent is working: in Flow your message **interrupts** the current step (the send button turns into a lightning bolt) and the agent continues with your new information right away. While the Flow is open, the git strip under the composer steps aside: the Flow's panel already shows its branch.
+
+## Try the app
+
+The Flow agent runs the typecheck and the tests itself to check its work. When there is something to try, it asks with three choices: **Start the app**, **Start and expose on the local network** or **Not now**. Exposing it lets you open the app from a phone on the same Wi-Fi or VPN, and anyone on that network can reach it.
+
+Once the app is listening, the agent gives you its addresses as links and the Flow's panel shows **Preview** with a green dot: it opens the app in your browser. Its menu has the network address and **Stop app**. The app runs from the Flow's copy, never from your main checkout, and Specrails stops it when you pause, discard or hand off the Flow.
+
+## Hand off {#flow-hand-off}
+
+When you are happy with the result, press **Hand off**. The row reads **Ready to turn into a PR** and opens one line above it: *Rail 2 will turn your 7 changed files into a reviewed PR. If it fails, your work is safe.* Press **Launch**, or **Not yet** to go back to the Flow; **Esc** is the same as **Not yet**; a click elsewhere only folds the line away, and the row keeps **Ready to turn into a PR** with **Launch**. If your conversation's engine cannot run the hand-off on this machine, a note right under the line says so and the rail's default engine is used.
+
+The rail, engine, model and effort are already chosen for you (a free rail and your conversation's engine). To change them, open **Change how**; it also shows what changed. The cost so far is on the main line. Your choices are kept if you press **Not yet** and hand off again later. While the hand-off starts, the strip shows it launching, with no gap, and then follows the run step by step. If the review limit or a budget is reached, the line says so and nothing launches. If the run has not shown after 45 seconds, the strip stops spinning and reads **Still handing off to Rail 2…** with **Refresh**, which checks again and keeps waiting until the run shows.
+
+The rail derives the spec and its spec change from what you built, verifies and reviews it, and the delivery card appears in the mission as with any run.
+
+If the run fails for a technical reason, the work comes back to this Flow on its own, intact: the card says in plain words what failed (the codes stay under **Technical details**) and the agent receives the error and explains it. If the review asks for changes, the card offers **Back to Flow** or **Relaunch**. When the delivery settles, the mission closes the Flow with a summary: the pull request, the spec rewritten from what you built, the archived spec change and the Jira issue when there is one.
+
+## Good to know
+
+- Flow writes only on its own branch. Missions stay read-only outside Flow.
+- One Flow per mission at a time. Pausing survives an app restart.
+- If the Flow's copy of the project disappears, the Flow is marked **needs review** (for your information, nothing to decide) and nothing is deleted.
+- The strip never swaps the run you are looking at. If another run starts needing you meanwhile, its name in the strip's switcher says **needs you**.
+- Jira receives nothing while you are in Flow or if you discard it.
+- Flow cost appears in Analytics as its own surface, **Flow**, and inside the agent missions block.

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

@@ -38,14 +38,14 @@ That's it. The rail spins up an AI CLI process in the right execution context an
 | **Profile picker** | Which provider-scoped agent profile runs (Claude rails). Only appears once the effective provider has at least one profile. |
 | **▶ Play / ■ Stop** | Start or cancel. |
 
-### What a rail runs: Loops
+### What a rail runs: Loops {#rail-loops}
 
 A rail runs a **Loop** — the recipe for the work. Two loops are **built in** and cover the common cases:
 
 | Built-in loop | Command | What it does |
 |------|---------|--------------|
 | **Implement** | `/specrails:implement` | One job covering all specs on the rail. Runs the full Architect → Developer → Reviewer → Ship pipeline. The everyday default. |
-| **Freestyle** | Freestyle | A capable provider implements each spec autonomously, **bypassing** the pipeline. One independent job per spec. Claude support it. |
+| **Freestyle** | Freestyle | The rail's provider implements each spec autonomously, **bypassing** the pipeline; verification and the Loop Decider then refine it until green. One independent run per spec. Works on Claude, Codex, Gemini, Kimi and local engines; the interactive in-job chat is Claude-only. |
 
 To run several specs, put related ones (up to 3) on one rail — `Implement` runs them as one aggregate job — or spread independent specs across several rails: each git-backed rail runs in parallel in its own isolated worktree.
 
@@ -85,7 +85,26 @@ If something looks wrong:
 - **Auto-pause on budget** — set a daily budget and the queue pauses itself when that day's spend hits the cap.
 - **Everything** — quit the desktop app, or run `specrails-desktop stop`.
 
+## Integrate locally with uncommitted changes
+
+**Integrate locally** merges an approved delivery into your integration branch (for example `main`) on this computer, without a PR. You do not need a clean checkout first:
+
+- Uncommitted changes that do not touch the delivered files simply stay where they are.
+- If your changes touch the same files, Specrails saves them as a git stash named `specrails: before integrating #N (…)`, integrates, and puts them back. The toast reads *Saved your local changes, integrated #N, and restored them.*
+- If putting them back conflicts with the integrated code, Specrails leaves the branch exactly as integrated and **keeps the stash** — nothing is lost. The card shows *Your local changes are saved as a stash* with the conflicting files, **Restore my changes** (try again, for example after you changed the code) and the stash name to copy. Specrails then restores them itself on a new branch `specrails/restore-local-<id>` in a separate worktree: if they apply cleanly there it commits them; otherwise an AI conflict resolver works only inside that worktree, keeping both your intent and the integrated code, and Specrails commits the result. The card lists the restored files; **Bring them back to <branch>** moves them onto your branch (only then is the stash dropped) and **Discard the restored branch** removes the branch and keeps the stash. A mission is only told what happened; it never has to run anything. OpenSpec skills and commands that Specrails generates (for example `.claude/skills/openspec-*/SKILL.md`) are not treated as your changes: on a conflict they keep the integrated version.
+- Ignored files are never stashed: if one of them collides with the delivery, Specrails asks you to move it first.
+- If the app stops between saving and restoring, it restores your changes the next time the project opens (only while the same branch is checked out).
+
+## Time and cost forecast {#launch-forecast}
+
+Before you press Launch, a rail can show how long runs like this usually take and, where it is meaningful, what they usually cost, for example *Usually 6–9 min · $2–4 for runs like this*.
+
+The range is the middle half of your own history: the 25th to 75th percentile of completed runs in this project that used the same loop or command and the same engine. It needs at least 5 comparable runs. Until then the line reads *Not enough history yet* instead of a guess. Only costs the provider reported are used; estimated costs are left out. It is an estimate, never a bill.
+
+The dollar figure shows only when the engine is known to bill per use (for example an API key). On a subscription plan, or while the billing mode is not known yet, only the time shows. When the rail holds several specs the band is for one spec and says *(per spec)*. If today's spend plus the top of the range could reach your daily budget, the line adds *May pause at budget* with a link to the budget settings. If today's budget is already used up, Launch asks you to confirm first, because the run would pause until it resets.
+
+
 ## Where to go next
 
 - [The Loop Builder](the-loop-builder) — what a rail runs, and how to build your own loops.
-- [The Job Detail view](the-job-detail-view) — phases, live metrics, ticket cards.
+- [The Job Detail view](the-job-detail-view) — phases, live metrics, spec cards.

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

@@ -1,6 +1,6 @@
 # The Job Detail view
 
-Click any job card on the **Jobs** page and you land here: the cockpit for a single rail run. It's built around one promise — **the live numbers you see are real, never guesses.** This page walks through the phases, the live metrics, the ticket cards — and the composer that lets you **talk to the running job**.
+Click any job card on the **Jobs** page and you land here: the cockpit for a single rail run. It's built around one promise — **the live numbers you see are real, never guesses.** This page walks through the phases, the live metrics, the spec cards — and the composer that lets you **talk to the running job**.
 
 ## The layout
 
@@ -10,7 +10,7 @@ Two panels sit above the full streaming log; on a running Claude job, a chat com
 ┌─────────────────────────────────────────────┐
 │  Status header  (icon · live duration · …)  │
 ├─────────────────────────────────────────────┤
-│  Ticket header  ( #12  #14  #15 )           │
+│  Spec header  ( #12  #14  #15 )           │
 ├─────────────────────────────────────────────┤
 │                                             │
 │  Streaming log  (auto-scroll · search · …)  │
@@ -54,14 +54,14 @@ The design principle: **no approximate or estimated mid-run numbers.** Duration
 
 The header label and icon map to the job's status, and the panel renders for `running`, `completed`, and `failed` jobs alike — so a finished job's detail view shows the same metrics frozen at their final values.
 
-## The ticket cards
+## The spec cards
 
-The **ticket header** sits between the status header and the log. It's a premium identity card showing a chip for every spec the job touched — matched from the launched command, so it reflects exactly which tickets this run was about.
+The **spec header** sits between the status header and the log. It's a premium identity card showing a chip for every spec the job touched — matched from the launched command, so it reflects exactly which specs this run was about.
 
-- **2–3 tickets** — shown as a list of chips.
+- **2–3 specs** — shown as a list of chips.
 - **4 or more** — collapse into a compact `+ N more` mode with an expand chevron, so the header stays tidy.
 
-Clicking a chip opens that spec's detail **over the job page** — you don't lose your place or change route. It's a quick way to re-read what a job is supposed to deliver while you watch it work. (On tablet-width screens you can even drag a ticket modal aside to compare two specs side by side.)
+Clicking a chip opens that spec's detail **over the job page** — you don't lose your place or change route. It's a quick way to re-read what a job is supposed to deliver while you watch it work. (On tablet-width screens you can even drag a spec modal aside to compare two specs side by side.)
 
 ## The streaming log
 
@@ -82,7 +82,7 @@ When the job is a **loop run** (see [The Loop Builder](the-loop-builder)), the f
 - **Follow mode** is on by default: the running step stays open and auto-scrolls while earlier steps fold out of the way. The moment you scroll up or open an older step, following pauses so you can read — a floating **Resume follow** pill takes you back to live. **Expand all / collapse all** sit in the toolbar, and typing in the search box looks across every step at once.
 - **Interrupted steps are honest too.** A step that never got to report an outcome — the run was cancelled or the app went down mid-step — is marked **Interrupted** with a dashed border, rather than pretending it finished.
 
-Everything else on this page works exactly the same for loop runs — the live metrics, the ticket cards, the composer. Non-loop jobs keep the classic streaming log above.
+Everything else on this page works exactly the same for loop runs — the live metrics, the spec cards, the composer. Non-loop jobs keep the classic streaming log above.
 
 ## Talk to the running job
 
@@ -107,6 +107,18 @@ If [telemetry](../settings/customizing) was enabled for the job, an **Export dia
 
 Handy for sharing a run with a teammate, or filing a precise bug report.
 
+## When a run fails
+
+When a job fails, stalls or is blocked, the terminal state starts with a **diagnosis card** that says what happened in plain words, for example *Tests failed in the Reviewer phase after 4 fix rounds*, and why when the app knows:
+
+- **Tests failed** — the checks still fail after the correction rounds.
+- **Provider limit** — the AI provider's usage limit was reached. The card quotes when it resets, in the provider's own words.
+- **Environment** — the machine cannot run the checks (credentials, a missing toolchain, a failing setup command). *Fix the environment* shows exactly what to run or change.
+- **Blocked**, **ran out of time**, **went quiet** and **stopped unexpectedly** name the limit or the process that stopped the run.
+- **Unknown cause** — the app does not guess. It shows the end of the log so you can read it yourself.
+
+Under the diagnosis you get up to three ranked remedies, and only the ones that can work here: **Resume from** the phase that stopped, **Run again**, **Edit spec and relaunch** (the spec's addenda carry your change into the next run), **Fix the environment** and **Open logs at the failure**. The same cause appears as a one-line label in the [inbox](../getting-started/the-dashboard-tour), and the mission's run card shows the same card.
+
 ## Where to go next
 
 - [Rails & jobs](rails-and-jobs) — launching and queueing.

package/docs/guide/en/pipeline/3-reviewing-a-delivery.md

@@ -0,0 +1,43 @@
+<!-- guide-revision: mission-first-v1 -->
+
+# Review a delivery in the app {#review-a-delivery}
+
+A delivery that is ready for review has two views: **Overview** (the verdict, the evidence and the decision buttons) and **Changes** (what the delivery actually changed). Open the review from the delivery's **Review** button, then choose **Changes**.
+
+## Read the changes
+
+The file list on the left shows every changed file with its status (added, modified, deleted, renamed), its `+` and `−` line counts and a tick once you mark it viewed. The diff on the right loads one file at a time, so a large change stays fast. Switch between **Unified** and **Split** layouts; Specrails remembers your choice. A very large file shows its first lines with **Load full file diff**; a binary file is listed as binary.
+
+The changes are measured from the point where the delivery branched off its base branch, so work that landed on the base afterwards does not appear. When a delivery has no combined branch yet you can pick which spec's branch to read.
+
+## Reviewer notes on the code
+
+The reviewer's findings, the risks it flagged and any review comments the run was launched to resolve appear under the line they are about. Notes that name no file or line are listed above the file list, so nothing is hidden. Older deliveries, and reviewers that did not name a place, show their findings in that list.
+
+## Ask the agent to change something
+
+Select lines by clicking their numbers (Shift-click extends the range), then choose **Ask agent for a change** and describe the change. Specrails saves it as review feedback on the spec, with the file, the line range and the selected code, and shows a message with a link to the spec. The next run on that spec is briefed with it. To start the run now, use **Ask for changes** on the Overview. There are no comment threads between people here; discuss with your team on GitHub.
+
+## Open in your editor
+
+**Open in editor** opens the file, at the selected line, in VS Code, Cursor or a JetBrains IDE. Choose the editor in **Settings → Code → Editor**. The file opens from your own checkout of the project, where the review branch may not be checked out.
+
+## Choose what happens to a delivery {#pr-decision}
+
+A finished run asks you one thing: what to do with its result. The card shows one main button for the next step (create the PR, publish it or verify it) and, next to it, **Review**, which opens the plain-language review packet. Everything else sits behind **More actions**:
+
+- **Checkout** puts the branch in your project folder so you can try it.
+- **Integrate locally** merges the result into your base branch on this computer. It needs no GitHub, and you confirm first.
+- **Discard** drops the result and its branch. You confirm first.
+
+If an action fails, the notice names what could not be done and offers **Retry**.
+
+## Keyboard
+
+| Key | Action |
+| --- | --- |
+| `j` / `k` | Next / previous changed file |
+| `n` / `p` | Next / previous reviewer note |
+| `v` | Mark the file viewed |
+
+The keys are ignored while you type in a field. Marking a file viewed is private to you; if the file changes in a later revision it shows **Changed since you viewed it** and counts as unviewed again.

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

@@ -1,6 +1,6 @@
 <!-- guide-revision: mission-first-v1 -->
 
-# Choose a provider and its capabilities
+# Choose a provider and its capabilities {#provider-capabilities}
 
 Execution settings belong to the chosen provider. A familiar model name does not imply that every provider supports the same reasoning, structured output or approval controls.
 
@@ -12,7 +12,7 @@ Claude and Codex have different adapters. Unsupported combinations should fail b
 
 ## Use the right level of control
 
-A rail's provider/model choice controls its execution. Role profiles and per-agent routing depend on the provider and on the Core workflow Desktop installed in the project; inspect the effective configuration rather than assuming a profile changes every call.
+A rail's provider/model choice controls its execution. Freestyle runs on every CLI provider and local engine; only Claude adds the interactive in-job chat. Role profiles and per-agent routing depend on the provider and on the Core workflow Desktop installed in the project; inspect the effective configuration rather than assuming a profile changes every call.
 
 When comparing runs, keep the same spec, repository revision and verification criteria. Treat reported, estimated and unavailable cost separately. See [profiles](/docs/agents-profiles-and-the-balanced-default) and [usage](/docs/insights-analytics-and-cost-tracking).
 

package/docs/guide/en/pipeline/5-the-loop-builder.md

@@ -1,4 +1,4 @@
-# The Loop Builder
+# The Loop Builder {#loop-builder}
 
 ## Core workflows
 
@@ -55,7 +55,7 @@ Edges connect the steps in order. The **Loop Decider** has two labelled outputs
 
 Inside any AI Step or Decider you can reference:
 
-- **Spec data** — `{{spec.title}}`, `{{spec.description}}`, `{{spec.ids}}` (the rail's ticket IDs). Filled in from the spec(s) on the rail at run time.
+- **Spec data** — `{{spec.title}}`, `{{spec.description}}`, `{{spec.ids}}` (the rail's spec IDs). Filled in from the spec(s) on the rail at run time.
 - **Magic commands** — `{{cmd:implement}}` and friends expand to the matching pipeline command.
 - **Constants** — `{{const:NAME}}` pulls from the global **constants library** (drag them in from the palette). Built-in sentinels like the verification PASS/FAIL markers are always available; you can add your own and reuse them across every loop.
 

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

@@ -1,4 +1,4 @@
-# Themes
+# Themes {#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.
 

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

@@ -1,4 +1,4 @@
-# Pipeline telemetry & diagnostics
+# Pipeline telemetry & diagnostics {#telemetry}
 
 Telemetry records pipeline diagnostics locally. It is **on by default** for projects without a saved preference. You can turn it off per project; an explicitly saved choice is preserved.
 
@@ -20,7 +20,7 @@ From that point forward, pipeline jobs in that project record telemetry. Other p
 
 ### 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.
+Telemetry applies to jobs that run through the project's **job queue**: CLI pipeline runs (rails when Loops are disabled, and `implement` commands sent from the `specrails-desktop` CLI). Loop runs — the default way rails run — and interactive sessions such as chat, Explore and missions are not instrumented.
 
 ## Where the data lives
 

package/docs/guide/en/settings/5-project-environment.md

@@ -1,4 +1,4 @@
-# Project environment
+# Project environment {#project-environment}
 
 Some projects need a credential at run time, such as `NODE_AUTH_TOKEN` for private npm packages. In **Project Settings → Environment**, add the **names** of the variables your rails and loops need. Specrails stores only the names, never the values.
 

package/docs/guide/en/settings/6-updates.md

@@ -0,0 +1,24 @@
+# Updates {#updates}
+
+Specrails keeps two things up to date: the **Specrails Desktop** app itself and the **specrails-core** framework your projects use. Both live in **Settings ▸ Updates**.
+
+## Update channel
+
+Pick how quickly you receive new versions:
+
+- **Latest** (default): every release as soon as it ships. You get new features and fixes first.
+- **Stable**: only releases that spent at least a week on Latest with green CI and were then promoted by the maintainers. Choose it when your team prefers fewer, well-tested updates.
+
+The channel applies to both the app and specrails-core. If specrails-core has no stable release yet, Core follows Latest and the Core card tells you so.
+
+On Stable, if no release has been promoted yet, **Check for updates** says so instead of offering a Latest build.
+
+## How updates arrive
+
+- **Specrails Desktop** checks at launch and every 6 hours. When an update is available a card appears; download, install and restart from there. You can also click **Check for updates**.
+- **specrails-core** never updates on its own. Click **Check for updates** on the Core card, then **Update** to install it. Your projects switch to the new framework without restarting the app.
+
+## Good to know
+
+- Switching from Latest to Stable never downgrades you. You stay on your version until Stable catches up.
+- Every update is signed and verified before it installs, on both channels.

package/docs/guide/en/settings/7-existing-projects.md

@@ -0,0 +1,33 @@
+# Working in an existing project {#existing-projects}
+
+These features help runs respect a project that already exists: what a spec leaves out, the questions the architect has before planning, which requirements a test actually proves, how to describe old code before changing it, and the rules your team already writes down. Each one needs a specrails-core version that supports it; until then its switch is greyed out with an "update Core" note.
+
+## Out of scope
+
+Every spec can list what it deliberately does **not** change. Quick and Explore fill it in for you; in the spec window it appears as **Out of scope** under the description, one item per line, and you can edit it like any other field. The agents see it with the spec on every launch.
+
+## Architect questions on Jira
+
+In **Settings ▸ Existing-project anchoring**, turn on **Post architect clarifications to Jira**. When a run stops because the architect needs an answer, or goes ahead on assumptions, Specrails posts them as one comment on the linked Jira issue. Reply to that comment in Jira: the reply is added to the spec as a clarification, and the next run of the spec reads it. You can still answer a paused run from the app.
+
+## Requirements demonstrated
+
+When a test names the requirement it proves (`[spec:<capability>/<requirement>]` in its title), the review page shows **Requirements demonstrated X/Y**: which requirements a passing test proves, which do not have one yet, and which the change itself touched. Analytics shows the same per loop. To fail CI when a changed requirement has no test, add `specrails-core pipeline trace --check --tests-passed` after your tests.
+
+The loop library also offers **Drift sweep**, a read-only loop that compares what each spec says with what the code does and lists every contradiction. It changes nothing.
+
+## Baseline on touch
+
+Turn on **Baseline on touch** to make a change that reaches code no spec describes start by describing it: tests of how the code behaves today, proven on the unchanged code, and a short spec of what exists. The review page shows **Spec created where the work passed** with the module, the requirements and the tests, and its cost is shown apart from the change. If those tests fail on the unchanged code, the run stops before editing the module and says so.
+
+## Project rules {#project-rules}
+
+**Settings ▸ Project rules** lists the checks your project already runs (lint, type checks, tests, CI) and every rule written in files like `CLAUDE.md` or `AGENTS.md`, sorted into:
+
+- **Enforced**: a check already guarantees it.
+- **Automatable**: a check could. **Create spec** turns it into a spec in one click.
+- **Human only**: someone has to look. These appear on every review page under **Needs human eyes**.
+
+Rules Core could not classify yet (for example right after adding the project, when the inventory runs offline) are listed as **Unclassified**; **Re-run inventory** with a provider configured classifies them.
+
+**Re-run inventory** refreshes the list. When a project has no verification commands yet, the agent runtime settings offer these checks first.

package/docs/guide/en/settings/8-accessibility.md

@@ -0,0 +1,23 @@
+# Accessibility and personalisation {#accessibility}
+
+Specrails adapts to how you work. Everything here lives in **Settings ▸ Appearance** and applies at once; it is saved on this computer.
+
+## Density {#density}
+
+**Comfortable** keeps cards and rows roomy. **Compact** fits more on screen: the specs board starts as compact rows, the jobs list uses tighter rows and the job story tightens its timeline. A saved board view keeps its own layout, so a view that was saved as post-it cards still opens as post-it cards. If this project's board already has its own layout, **Use this for the board too** under the choice makes it follow the density again.
+
+## Reduce motion {#reduce-motion}
+
+**Follow system** respects your operating system. **Reduce** turns animations and transitions off inside Specrails whatever the system says: the rail pill rests at its position, live dots stop pulsing and the Builder halo and the theme effects stay still. **Full motion** animates even when the system asks for less.
+
+## Move a spec from the keyboard {#keyboard-moves}
+
+Focus a spec card on the board (Tab or the arrow keys) and press **M**. A small picker lists the statuses and the rails; choose one with the arrow keys and **Enter**. It does the same as dragging the card there, including Jira-backed specs, which move through your Jira workflow. If the card is part of a multi-selection (**X** selects the focused card), the move applies to every selected spec. The command palette offers the same thing as **Move focused spec…**. **M** does nothing while you are typing in a field.
+
+## Run updates for screen readers {#live-status}
+
+Specrails announces run changes through a polite live region, for the project you are looking at: a run started, paused, needs you, failed, finished or has a review ready. Bursts are merged and repeats are dropped, so a busy rail never floods the reader. Undo toasts already announce themselves.
+
+## Keyboard focus {#focus}
+
+Every button, link, menu item, card and tree row shows a visible focus ring when you reach it with the keyboard. Information that used to live only in a tooltip, such as a spec reference on a rail strip, is also available to keyboard and screen reader users.

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

@@ -1,8 +1,6 @@
-# Specs & the backlog
+# Specs & the backlog {#specs-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.
+A **spec** is the unit of work the AI pipeline implements. Think of it as a short brief: 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.
 
 ## The board
 
@@ -13,7 +11,27 @@ The board has two view modes, switched from a toolbar toggle and remembered per
 - **Post-it view** (the default) — card-style tiles with short summaries.
 - **List view** — compact one-line rows.
 
-The toolbar's **status selector** shows every status as its own chip with a live count — plus two smart buckets: **Active** (the default — everything still moving: drafts, todos, in-progress and on-review specs) and **All** (everything, with Done pinned at the bottom). Your pick is remembered per project and mirrored to the URL, so a refresh or a shared link restores the exact view. On Jira-connected projects an extra **Jira status** dropdown appears, listing the board's *real* workflow statuses (their raw names, e.g. "Code Review", each with a live count) grouped under the state they map to — it combines with the status chips. You can also filter by **label**, and sort by **Default**, **Ticket #**, or **Priority** (each with an ascending/descending toggle).
+The Specs toolbar has two rows. The first holds a **search** field (press `/` to jump to it; it matches title, `#number`, label or Jira key), a single **Filters** button, the sort and view controls, and **New spec**. The second row is the **status selector**: every status as its own segment with a live count, plus two smart buckets, **Active** (the default: everything still moving, so drafts, todos, in-progress and on-review specs) and **All** (everything, with Done pinned at the bottom). When the column is narrow, the less-used statuses fold into a **More** menu, and the status you picked always stays visible. Your pick is remembered per project and mirrored to the URL, so a refresh or a shared link restores the exact view. **Filters** opens one panel with a section per dimension: **labels** (multi-select), and on Jira-connected projects **epic**, **sprint** and **Jira status** (the board's *real* workflow statuses, e.g. "Code Review", grouped under the state they map to, combining with the status selector). While a search or filter narrows the board, a third row lists each one as a removable chip, shows "x of y" specs, and offers **Clear all** (which keeps your status pick). Sort by **Default**, **Spec #** or **Priority**, each with an ascending/descending toggle.
+
+### Selecting several specs
+
+Triage in bulk instead of one spec at a time. Press `x` on a focused card, `Ctrl`/`⌘`-click a card, or `Shift`-click to select a range (a range stays inside one column: the active specs or the Done bucket). `Ctrl`/`⌘`+`A` selects the whole column you are in, and `Esc` clears the selection. Each card shows a checkbox when you hover or focus it; selected cards get a highlighted border. None of these keys act while you are typing in the search field.
+
+As soon as one spec is selected, a bar floats at the bottom of the board with the count and the actions:
+
+- **Move to** changes the status. Local specs get the local statuses; specs that come from Jira get the Jira board's real workflow statuses and move through the same Jira queue as a single move.
+- **Label** adds a label to the selection, or removes one the specs carry.
+- **Priority** sets one priority for all of them.
+- **Add to rail** puts the selection on a rail.
+- **Launch all** gives each selected spec its own free rail and starts them in parallel, after the same confirmation and daily-budget check as *Launch all* on the rails. Specs that cannot launch yet (for example, on review without an open PR) or that find no free rail are skipped and counted in the summary.
+- **Delete** removes them to *Recently deleted*.
+- **Clear** (or `Esc`) drops the selection.
+
+Delete, status, label and priority changes are undoable as one step: a single *Undo* toast (or `⌘Z`) restores every spec it changed. If some specs fail, one toast says how many worked and how many did not. The selection only ever holds specs you can see: a filter that hides a selected spec drops it from the selection.
+
+### Saved views
+
+The **Views** button next to **Filters** saves the board as you have it now: the status selector, the filters, the sort and the density (not the search text). Choose **Save current view…**, name it ("Ready to launch", "Sprint 42", "Failed this week") and pick it from the same menu later. **Manage views…** renames a view, updates it from the board as it is now, copies its link, or deletes it. Views belong to the project. A copied link (`?view=…`) applies the view when opened in this app, and the command palette (`⌘K`) can save the current view or switch to another.
 
 ## Statuses
 
@@ -38,7 +56,7 @@ Drafts are the one exception: a draft can have *no* priority at all, because it'
 
 ## 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:
+To create a spec, click **New spec** (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).
@@ -50,6 +68,24 @@ Which one you reach for depends on how clear the idea already is. Know exactly w
 
 When a spec already has work behind it — a PR under review, a merged feature — and you want *more*, don't rewrite its description: that drifts the spec (and syncs the drift to Jira) and makes the next run re-plan everything. Open the spec and add an **addendum** instead: a short note with a kind (change request, review feedback, clarification, constraint) and your words. Open addenda ride automatically into the next launch of that spec on any loop — Implement, SDD Quick, Freestyle — so the run changes only what you asked, and the review packet reports each one as applied, partially applied or blocked. If the run fails or you discard the delivery, they return to **Open** on their own. The mission agent can add them for you when you ask it to change something about an existing spec.
 
+## Reviewing a delivery — what to look at first
+
+When a run finishes, its review packet opens with **What to look at**: the AI reviewer's short brief listing the riskiest spots first (high, then medium, then low, each with a file and line), the behaviour that changes, the rules the change leans on, the code paths no test exercises and the checks only a person can do. The same risks, untested paths and checks appear in a short block at the top of the pull request, and the mission card shows the top risk in one line. The brief is advice for your review, not a verification result: it never blocks Accept. Runs made with an older Specrails Core have no brief, and their packet looks as before.
+
+## Undo, and Recently deleted {#recently-deleted}
+
+Deleting a spec, moving it to another status, changing its labels or taking it off a rail all happen at once — there is no "Are you sure?" first. Instead a toast offers **Undo** for about eight seconds, and **⌘Z** (**Ctrl+Z** on Windows and Linux) does the same while you are not typing in a field. Undo is per project: switching project closes the window.
+
+A deleted spec (and a deleted mission) is not gone. It moves to **Settings → Recently deleted** in the project settings, where you can **Restore** it for 30 days or **Delete permanently**, which does ask first. After 30 days it is removed for good. Discarding unpushed work, force-closing a pull request and removing a project are the actions that still ask first, because they cannot be reversed. A Jira-backed spec is still moved with **Move to** rather than deleted.
+
+## The spec timeline and hand-off {#spec-timeline}
+
+Open a spec and switch to the **Timeline** tab to read its whole story in one place: the edits and addenda, the missions that touched it, every run with its phases and agent actions, the pull request events and the reviewer's verdict with its findings. Entries are grouped by day, the chips filter by kind, and each entry has a link to the mission, run or review it came from. Long groups (phases, agent actions, mission turns) are collapsed with a count and expand in place.
+
+Cost appears next to the entry that spent it, with the two kinds kept apart: a figure the provider reported, and a figure estimated from the local pricing table (marked "est."). If a provider is billed through a plan, the timeline and the exports show turns, never dollars; a run that reported no cost simply shows none.
+
+**Export hand-off** (the menu beside the tabs, or ⌘K → *Export hand-off for #N*) writes a Markdown file or a self-contained HTML page with the summary, the decisions (addenda, clarifications, reviewer verdicts), the diff stats, the cost and what is still open (open addenda and unresolved review findings). **Copy as PR description** (also in ⌘K) puts a shorter Markdown version on the clipboard. Headings follow the app language. Everything is passed through the same secret redaction the agent actions audit uses, and the toast tells you when something was hidden.
+
 ## Where to go next
 
 - [Add Spec — Quick mode](add-spec-quick-mode.md) — the fastest way to turn an idea into a spec.

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

@@ -6,7 +6,7 @@ Quick mode is for when you already know what you want. You type your idea, the A
 
 To create a spec quickly:
 
-1. On the Dashboard, click **Add** (the Plus button on the SpecsBoard toolbar).
+1. On the Dashboard, click **New spec** (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.

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

@@ -22,7 +22,7 @@ As you converse, a draft pane shows the spec as it currently stands — title, d
 
 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
+## How much the AI sees: the context slider {#context-scope}
 
 Before the AI answers, you decide how much of your project it can see. A context preset slider lets you trade speed for depth:
 
@@ -43,7 +43,7 @@ If you want finer control, click **Fine-tune** to flip the underlying options by
 
 - **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.
+- **Save as Draft** — persists the conversation as a draft spec 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).
 

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

@@ -1,4 +1,4 @@
-# Conoce a los agentes
+# Conoce a los agentes {#agents}
 
 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.
 

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

@@ -24,7 +24,7 @@ Cuando lanzas un rail, Specrails elige un perfil en este orden:
 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.
+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 trabajos que ya empezaron.
 
 ## Seleccionar un perfil por rail
 

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

@@ -18,7 +18,7 @@ Los valores de modelo son alias — para Claude son `opus`, `sonnet` y `haiku` (
 - Deja el modelo de un agente **en blanco** para que recurra al default propio del rol — en el trío base son el proveedor y el modelo configurados en **Ajustes → Motor de agentes**; un agente personalizado recurre al frontmatter de su archivo.
 - 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.
+Guarda, y el próximo rail lanzado con ese perfil usará los nuevos modelos. Los trabajos que ya están en marcha conservan su snapshot.
 
 ## Crear perfiles como `fast` y `max`
 
@@ -53,7 +53,7 @@ Todo esto se junta en el lanzamiento: en la cabecera del rail, elige `fast`, `ma
 
 ## 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.
+Eliminar un perfil es seguro para el trabajo en marcha: los trabajos 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
 

package/docs/guide/es/agents/4-custom-agents-catalog.md

@@ -21,7 +21,7 @@ El flujo típico:
 
 ## Vigilar cómo rinden los perfiles
 
-La sección Agentes también tiene una pestaña **Uso** — un desglose por perfil de cuántos jobs corrieron bajo cada perfil en una ventana seleccionada. Es una forma rápida de confirmar que tu reparto `fast`/`max` se está usando realmente como pretendías, y de detectar hacia qué perfil gravita tu equipo.
+La sección Agentes también tiene una pestaña **Uso** — un desglose por perfil de cuántos trabajos corrieron bajo cada perfil en una ventana seleccionada. Es una forma rápida de confirmar que tu reparto `fast`/`max` se está usando realmente como pretendías, y de detectar hacia qué perfil gravita tu equipo.
 
 ## Resumen de toda la sección
 

package/docs/guide/es/getting-started/1-what-is-specrails.md

@@ -8,7 +8,7 @@ En lugar de copiar y pegar prompts de un lado a otro, describes lo que quieres c
 
 El corazón de specrails es una idea sencilla: **la mejor forma de conseguir buen código de una IA es partir de una spec clara.**
 
-Una *spec* es una descripción breve y estructurada de un trabajo concreto: una funcionalidad, una corrección, un refactor. Puedes escribir una en segundos, o darle forma a través de un chat guiado que te hace las preguntas adecuadas y la redacta por ti. Cada spec se convierte en un **ticket** en el tablero de tu proyecto, igual que una tarea en cualquier gestor de incidencias.
+Una *spec* es una descripción breve y estructurada de un trabajo concreto: una funcionalidad, una corrección, un refactor. Puedes escribir una en segundos, o darle forma a través de un chat guiado que te hace las preguntas adecuadas y la redacta por ti. Cada spec se convierte en un **spec** en el tablero de tu proyecto, igual que una tarea en cualquier gestor de incidencias.
 
 A partir de ahí, le pasas la spec al pipeline y dejas que la IA haga el trabajo pesado.
 
@@ -25,7 +25,7 @@ Ves cada etapa a medida que se ejecuta, con logs en directo que llegan directame
 
 ## Proyectos
 
-Todo en specrails se organiza en torno a **proyectos**. Un proyecto no es más que una carpeta de tu ordenador que contiene una base de código. Puedes añadir tantos proyectos como quieras y cambiar entre ellos al instante; cada uno conserva sus propias specs, su historial de jobs, sus analíticas y sus ajustes.
+Todo en specrails se organiza en torno a **proyectos**. Un proyecto no es más que una carpeta de tu ordenador que contiene una base de código. Puedes añadir tantos proyectos como quieras y cambiar entre ellos al instante; cada uno conserva sus propias specs, su historial de trabajos, sus analíticas y sus ajustes.
 
 specrails nunca toca código que no le hayas pedido tocar. Trabaja dentro de tu repositorio existente, y tú mantienes el control de lo que acaba en un commit.
 
@@ -43,6 +43,6 @@ Elige el que ya uses, o instala más de uno y escoge según la tarea. Un proyect
 - **Velocidad sin caos** — las specs mantienen a la IA centrada, así que obtienes cambios útiles en lugar de divagaciones interminables.
 - **Visibilidad total** — logs en directo, una vista clara del pipeline y analíticas por proyecto te muestran exactamente qué pasó y cuánto costó.
 - **Tu máquina, tu código** — todo se ejecuta en local contra tu repositorio real.
-- **Todo en un solo sitio** — specs, jobs, chat, una terminal integrada y seguimiento de costes, todo en una única ventana.
+- **Todo en un solo sitio** — specs, trabajos, chat, una terminal integrada y seguimiento de costes, todo en una única ventana.
 
 ¿Listo para empezar? Lo siguiente: [Instalación y primer arranque](installing-and-first-run).

package/docs/guide/es/getting-started/2-installing-and-first-run.md

@@ -39,3 +39,5 @@ Verás:
 Eso es toda la puesta en marcha: ninguna cuenta que crear, ningún registro. specrails funciona por completo en tu máquina.
 
 Haz clic en **Añadir tu primer proyecto** y continúa con [Añadir tu primer proyecto](adding-your-first-project).
+
+O empieza con el [proyecto de ejemplo](try-the-sample-project): un pequeño juego y tres specs ya escritas, con el coste indicado de antemano.