specrails-desktop 2.7.0 → 2.9.0

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

@@ -0,0 +1,68 @@
+# Spec hinzufügen – Explore-Modus
+
+Der Explore-Modus ist eine Unterhaltung. Statt die Spec selbst zu schreiben, durchdenkst du die Idee gemeinsam mit der KI – sie agiert als Denkpartner, stellt Fragen, schlägt eine Struktur vor und baut dabei einen **Live-Entwurf** der Spec auf. Wenn du zufrieden bist, überführst du den Entwurf in eine echte Spec.
+
+Greif zu Explore, wenn die Idee noch nicht ganz ausgereift ist, wenn es Abwägungen zu besprechen gibt oder wenn du möchtest, dass die KI sich deinen tatsächlichen Code ansieht, bevor die Spec festgezurrt wird.
+
+## Eine Spec im Explore-Modus erstellen
+
+So formst du eine Spec im Explore-Modus:
+
+1. Klicke auf dem Dashboard auf **Hinzufügen** und wähle dann **Explore**.
+2. Tippe deine erste Nachricht – die Idee, eine Frage oder einen halbgaren Gedanken.
+3. Lies die Antwort der KI und antworte weiter. Mit jedem Zug verfeinert sie ihr Verständnis.
+4. Beobachte, wie sich der **Live-Entwurf** neben dem Chat aktualisiert – das ist die Spec, die Gestalt annimmt.
+5. Wenn der Entwurf passt, klicke auf **Spec erstellen**.
+
+Die Unterhaltung bleibt in deinem Verlauf, sodass du jederzeit zurückkommen kannst, um zu sehen, wie die Spec entstanden ist.
+
+## Der Live-Entwurf
+
+Während du dich unterhältst, zeigt ein Entwurfsbereich die Spec in ihrem aktuellen Stand – Titel, Beschreibung, Priorität, Labels, Akzeptanzkriterien. Sie schreibt sich mit jedem Zug auf Basis des Besprochenen neu. Du bearbeitest sie nicht direkt; du steuerst sie über die Unterhaltung („mach die Priorität doch hoch", „füge ein Kriterium zur Fehlerbehandlung hinzu" und so weiter).
+
+Das ist das Herzstück des Explore-Modus: Du starrst nie auf ein leeres Formular. Du blickst immer auf eine echte, sich entwickelnde Spec.
+
+## Wie viel die KI sieht: der Kontext-Schieberegler
+
+Bevor die KI antwortet, entscheidest du, wie viel von deinem Projekt sie sehen darf. Ein Schieberegler mit Kontext-Presets lässt dich Geschwindigkeit gegen Tiefe abwägen:
+
+| Preset | Was die KI sieht |
+|--------|------------------|
+| **Minimal** | Nur deine Nachricht. Am schnellsten und günstigsten. |
+| **Leicht** | + deine vorhandenen Specs. |
+| **Standard** | + deine Specs und die OpenSpec-Specs deines Projekts. |
+| **Umfangreich** | + Lesezugriff auf deine gesamte Codebasis, damit sie Antworten in echtem Code verankern kann. |
+| **Max** | Umfangreich, plus ein Contract-Layer-Anreicherungsdurchgang beim Commit. |
+| **Desktop** | Max, plus die MCP-Server deines Projekts und deine eigenen freigegebenen MCP-Server. |
+
+Starte niedrig für schnelles Brainstorming; geh höher, wenn du möchtest, dass die KI ihre Vorschläge gegen deinen tatsächlichen Code prüft. Die Wahl wird an der Unterhaltung gespeichert, sie schwappt also nicht in andere Explore-Sessions über.
+
+Wenn du feinere Kontrolle möchtest, klicke auf **Feinabstimmung**, um die zugrunde liegenden Optionen von Hand umzulegen – darunter **Meine freigegebenen MCPs**, das die MCP-Server lädt, die du lokal bereits freigegeben hast, ohne die Session zu verlangsamen.
+
+## Schaltflächen in der Explore-Oberfläche
+
+- **Spec erstellen** – befördert den Live-Entwurf zu einer echten Spec mit Status **To-do**. (Wenn du eine bestehende Spec bearbeitest, heißt diese Schaltfläche stattdessen **Spec aktualisieren** und patcht die Spec an Ort und Stelle.)
+- **Prüfen →** – öffnet ein Prüf-Overlay, das die vorgeschlagene Spec vor dem Commit gegen die Ausgangsbasis abgleicht, damit es keine Überraschungen gibt.
+- **Als Entwurf speichern** – speichert die Unterhaltung als Entwurfsticket, damit du sie später aufgreifen kannst. Verfügbar, sobald du mindestens eine Nachricht gesendet hast. Siehe unten.
+- **Minimieren** – parkt die Unterhaltung als Chip im Dock der minimierten Chats unten links. Klicke jederzeit auf den Chip, um direkt in die Unterhaltung zurückzuspringen – nichts geht verloren.
+- **Verwerfen** – wirft die Unterhaltung weg (fragt vorher nach Bestätigung).
+
+## Als Entwurf speichern
+
+Noch nicht bereit zum Committen, aber du willst die Überlegungen nicht verlieren? Klicke auf **Als Entwurf speichern**. Die Unterhaltung wird zu einer **Entwurfs-Spec** auf deinem Board, und der Entwurf bleibt mit der dahinterliegenden Unterhaltung verknüpft.
+
+Öffne den Entwurf später vom Board aus und klicke auf **Weiter bearbeiten** – die ursprüngliche Unterhaltung öffnet sich erneut mit vollständig erhaltenem Chatverlauf, und du machst genau dort weiter, wo du aufgehört hast. Entwürfe werden nie automatisch gelöscht; sie warten auf dich.
+
+Damit lässt sich Explore unbesorgt für halbgare Ideen nutzen: starte eine Unterhaltung, komm ein Stück weit, speichere sie als Entwurf und komm morgen zurück.
+
+Alles rund um Entwürfe – inklusive der Contract-Layer-Anreicherung – findest du unter [Entwürfe & der Contract Layer](drafts-and-contract-layer.md).
+
+## Hinweis zu mehreren Providern
+
+Wenn in deinem Projekt mehr als ein KI-Provider installiert ist, lässt dich eine Engine-Auswahl bestimmen, welche die Explore-Unterhaltung antreibt. Projekte mit nur einem Provider zeigen sie nicht.
+
+## Wie es weitergeht
+
+- [Entwürfe & der Contract Layer](drafts-and-contract-layer.md) – Arbeit zwischenspeichern und Specs für die Pipeline anreichern.
+- [Spec hinzufügen – Quick-Modus](add-spec-quick-mode.md) – wenn die Idee schon klar ist.
+- [Pipelines ausführen](running-pipelines.md) – setze deine Spec um, sobald sie bereit ist.

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

@@ -0,0 +1,81 @@
+# Entwürfe & der Contract Layer
+
+Diese Seite behandelt zwei Wege, mehr aus deinen Specs herauszuholen: **Entwürfe** (eine in Arbeit befindliche Idee speichern, um sie später fortzusetzen) und den **Contract Layer** (eine optionale Anreicherung, die Specs für die KI-Pipeline präziser macht).
+
+## Entwürfe: eine Idee in Arbeit speichern
+
+Ein **Entwurf** ist eine noch in Arbeit befindliche [Explore](add-spec-explore-mode.md)-Unterhaltung, die als Spec gespeichert wurde. Damit kannst du mitten im Gedanken aufhören, ohne etwas zu verlieren, und zurückkommen, wenn du bereit bist.
+
+### Einen Entwurf speichern
+
+Klicke während einer Explore-Unterhaltung auf **Als Entwurf speichern** (verfügbar, sobald du mindestens eine Nachricht gesendet hast). Die App:
+
+- Erstellt eine Spec mit Status **Entwurf** auf deinem Board.
+- Vergibt ihr automatisch einen Titel, falls du keinen festgelegt hast (eine kurze Zusammenfassung der Unterhaltung).
+- Verknüpft sie zurück mit der Unterhaltung, sodass der vollständige Chatverlauf erhalten bleibt.
+
+Das Speichern ist idempotent – wenn du dieselbe Unterhaltung zweimal speicherst, wird der bestehende Entwurf aktualisiert, statt ein Duplikat anzulegen.
+
+### Wie Entwürfe auf dem Board aussehen
+
+Entwürfe liegen im selben aktiven Bereich wie deine To-do-Specs – es gibt keine eigene Spalte. Du erkennst sie an:
+
+- Einem `Draft`-Pill an der Stelle, wo normalerweise das Prioritäts-Pill sitzt.
+- Einem dezent eingefärbten Rand auf der Karte.
+
+Ein Entwurf darf *keine Priorität* haben – die Priorität legst du fest, wenn du ihn in eine echte Spec überführst.
+
+### Einen Entwurf fortsetzen
+
+So machst du dort weiter, wo du aufgehört hast:
+
+1. Öffne den Entwurf vom Board aus.
+2. Klicke im Detail-Modal auf **Weiter bearbeiten**.
+3. Die ursprüngliche Explore-Unterhaltung öffnet sich erneut mit vollständigem Chatverlauf, und der Live-Entwurfsbereich ist mit allem vorbefüllt, was du bislang geformt hast.
+4. Sprich weiter. Wenn du fertig bist, befördert **Spec erstellen** den Entwurf zu einer echten Spec (Status **To-do**, mit der von dir gewählten Priorität).
+
+### Einen Entwurf verwerfen
+
+Entwürfe werden **nie automatisch gelöscht**. Sie verschwinden nur, wenn du sie ausdrücklich verwirfst oder wenn du sie in einen Nicht-Entwurfs-Status überführst. Beim Verwerfen eines Entwurfs wird auch die verknüpfte Unterhaltung aufgeräumt, sofern nichts anderes auf sie verweist.
+
+> Tipp: Wenn du dir nicht sicher bist, ob eine Spec die Mühe wert ist, speichere sie als Entwurf und lass sie liegen. Öffne sie am nächsten Morgen, wirf einen Blick auf die Beschreibung und entscheide mit frischem Blick.
+
+## Der Contract Layer: Präzision für die Pipeline
+
+Der **Contract Layer** ist eine optionale Anreicherung, die der Beschreibung einer Spec einen strukturierten Block anhängt. Seine Aufgabe ist es, den KI-Agenten, die die Spec umsetzen, das Rätselraten zu nehmen – damit sie die richtigen Namen wiederverwenden, die erwarteten Datenformen treffen und die richtigen Dateien anfassen, statt sich eigene auszudenken.
+
+### Was er hinzufügt
+
+Der Contract Layer besteht aus fünf kurzen Abschnitten, die der Spec angehängt werden:
+
+- **Naming Contract** – die genauen Bezeichner (Funktionen, Felder, Routen), die die Implementierung wiederverwenden soll.
+- **Data Shapes** – die beteiligten JSON-artigen Payloads.
+- **State Machine** – die Übergänge oder Zustände, die das Feature durchläuft.
+- **Invariants** – Eigenschaften, die immer gelten müssen.
+- **File Touch List** – die Dateien, die die Implementierung voraussichtlich bearbeitet.
+
+Stell es dir so vor, als würdest du der Pipeline eine präzise Bauanleitung statt einer Skizze in die Hand geben. Besonders wertvoll ist das bei Specs, die in bestehenden Code eingreifen, wo ein von der KI geratener Name oder eine geratene Form Nacharbeit verursachen würde.
+
+### Wie du ihn hinzufügst
+
+Es gibt drei Wege, den Contract Layer anzuwenden:
+
+- **Quick-Modus** – leg vor dem Generieren den Schalter **Mit Contract Layer anreichern** um. Deine letzte Wahl wird pro Projekt gemerkt. (Siehe [Spec hinzufügen – Quick-Modus](add-spec-quick-mode.md).)
+- **Explore-Modus** – wähle das Kontext-Preset **Max** oder **Desktop** (die die Anreicherung beim Commit automatisch ausführen), oder öffne **Feinabstimmung** und leg ihn von Hand um. (Siehe [Spec hinzufügen – Explore-Modus](add-spec-explore-mode.md).)
+- **An einer bestehenden Spec** – öffne das Detail-Modal der Spec und führe die Anreicherung von dort aus erneut aus.
+
+### Wo er auftaucht
+
+Sobald eine Spec einen Contract Layer hat, zeigt ihn das Detail-Modal als einklappbares Element mit einem Badge wie `3/5 befüllt` – das sagt dir, wie viele der fünf Abschnitte tatsächlich befüllt wurden (manche Features haben schlicht zum Beispiel keine State Machine, und solche Abschnitte werden als nicht zutreffend markiert). Klapp es aus, um den vollständigen Contract zu lesen; klapp es ein, um die Beschreibung aufgeräumt zu halten.
+
+Falls die Anreicherung einmal nicht durchläuft, zeigt die App eine Benachrichtigung mit einer Aktion **Wiederholen**, sodass du sie erneut auslösen kannst.
+
+### Lohnt er sich immer?
+
+Nicht immer. Eine kleine, in sich geschlossene Spec kann die KI auch ohne ihn problemlos umsetzen. Der Contract Layer verdient sich seinen Platz bei Specs, die eng mit bestehendem Code verzahnt sind, wo es auf exakte Namen und Formen ankommt – dann erspart dir das frühe Festzurren des Contracts später eine Runde Korrekturen.
+
+## Wie es weitergeht
+
+- [Spec hinzufügen – Explore-Modus](add-spec-explore-mode.md) – woher Entwürfe kommen.
+- [Spec hinzufügen – Quick-Modus](add-spec-quick-mode.md) – der Contract-Layer-Schalter im Quick-Modus.
+- [Pipelines ausführen](running-pipelines.md) – setze eine Spec um, sobald sie bereit ist.

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

@@ -0,0 +1,38 @@
+# Meet the agents
+
+When you launch an **Implement** rail, Specrails doesn't hand your spec to a single AI and hope for the best. It runs a small team of specialised *agents*, each with one job, in a deliberate order. This page introduces who's on that team and what each one does.
+
+## The baseline trio
+
+Every pipeline run uses these three agents — they're the backbone, and a project can't run a rail without them.
+
+| Agent | Role | What it does |
+|-------|------|--------------|
+| **sr-architect** | The planner | Reads your spec, inspects the codebase, and produces a concrete implementation plan — which files to touch, what shape the change takes, what to watch out for. It thinks before anyone writes code. |
+| **sr-developer** | The builder | Takes the architect's plan and actually writes the code: new files, edits, tests. This is where your spec turns into a real diff. |
+| **sr-reviewer** | The critic | Validates the developer's work against the spec and the plan, catches regressions, and pushes back when something's off. It's the quality gate before the change is considered done. |
+
+Think of it as **design → build → review**, the same loop a careful human team would follow. Each agent hands its output to the next, so the developer never works blind and the reviewer always has the original intent to check against.
+
+## Specialist agents
+
+Beyond the trio, a project can include optional **specialist agents** that handle specific kinds of work. The most common one you'll see is:
+
+- **sr-merge-resolver** — a utility agent that helps untangle merge conflicts and reconcile overlapping changes. It's optional: profiles include it only when you want it, and it never blocks the pipeline if it's absent.
+
+Specialists are opt-in. A fresh project runs with just the trio; you add specialists (and your own **custom agents** — see [Custom agents & the catalog](custom-agents-catalog)) when a project's workflow calls for them.
+
+## How tasks reach the right agent
+
+Within a run, work is *routed*. A task carries tags, and a profile's routing rules send tagged tasks to the agent best suited for them — with a final catch-all rule that sends everything else to the developer. You don't have to think about this for normal use; the default setup routes everything sensibly out of the box. When you're ready to direct specific kinds of work to specific agents, see [Customizing models per agent](customizing-models-per-agent).
+
+## One important idea, up front
+
+The *definition* of each agent — its instructions, its personality, what it's allowed to do — is **shared**. These live as files (`.claude/agents/<id>.md`) that travel with your repository, so your whole team runs the same architect, the same reviewer.
+
+What's **per-project** is the *configuration* on top: which model each agent runs with, and which combination of agents you pick for a given rail. That's what profiles are for — and that's the next page.
+
+## Where to go next
+
+- [Profiles & the balanced default](profiles-and-the-balanced-default) — how the team's setup is packaged and selected.
+- [Customizing models per agent](customizing-models-per-agent) — tune cost and quality.

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

@@ -0,0 +1,45 @@
+# Profiles & the balanced default
+
+A **profile** is a saved recipe for a pipeline run. It answers three questions in one place:
+
+1. **Which agents** participate (the baseline trio, plus any specialists or custom agents).
+2. **Which model** each agent runs with.
+3. **How tasks are routed** to those agents.
+
+You'll find profiles in the **Agents** section of any project (right sidebar → **Agents** → the **Profiles** tab).
+
+## The balanced default
+
+Out of the box, a project resolves to a sensible **default** profile. It includes the baseline trio — `sr-architect`, `sr-developer`, `sr-reviewer` — and routes every task to the developer through a single catch-all rule. The models are balanced for everyday work: a capable model where it matters, without reaching for the most expensive option on every step.
+
+If your project already had agent models configured the old way (in the agent files' frontmatter), the **Migrate** button reads those and builds a `default` profile that mirrors today's behaviour exactly — zero loss, nothing changes until you decide to tune it.
+
+The headline: **you don't have to create a profile to use Specrails.** The default just works. Profiles are how you go further.
+
+## How a profile is chosen for a run
+
+When you launch a rail, Specrails picks a profile in this order:
+
+1. **Your explicit choice** in the rail header (see below).
+2. Your **per-developer preference** — a profile you've marked as your personal default for this project (it's local to you and not committed).
+3. The project's **`default`** profile.
+
+The profile is *snapshotted at launch*, so each rail in a batch can run a different profile, and changing a profile later never rewrites jobs that already started.
+
+## Selecting a profile per rail
+
+Profile selection happens right where you launch — in the **rail header**, via the profile selector.
+
+- Pick a profile from the dropdown to use it for **this launch only**.
+- Use the persist option to make a profile the rail's standing choice going forward.
+
+That's the whole flow: choose a profile, launch, done. Concurrent rails in the same batch can each carry their own profile, so a quick fix and a heavy feature can run side by side with different setups.
+
+## When the Agents section is quiet
+
+Profiles are a Claude capability. On a project that includes a non-Claude provider (Codex or Gemini), the Agents section is hidden and rails run without profiles — that's expected, not a bug. Profiles also require a recent enough `specrails-core` in the project; if it's older, you'll see a yellow banner. Profiles you create still **save** — they just don't affect the pipeline until core is updated. Update with the command shown in the banner to unlock them.
+
+## Where to go next
+
+- [Customizing models per agent](customizing-models-per-agent) — build `fast` and `max` profiles.
+- [Custom agents & the catalog](custom-agents-catalog) — see and extend the team.

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

@@ -0,0 +1,60 @@
+# Customizing models per agent
+
+The single most useful thing profiles let you do is **pick the right model for each step**. A planning step might deserve your strongest model; a routine build step might be perfectly happy on something faster and cheaper. Profiles let you express exactly that.
+
+This is where the shared-vs-per-project split pays off:
+
+- The agent *definitions* stay shared across your team.
+- The *model each agent runs with* is configured **per project**, inside a profile, and only affects your project.
+
+Change a model and you change cost and behaviour for that project — without touching anyone else's setup or the agent's underlying instructions.
+
+## Changing which model an agent uses
+
+In **Agents → Profiles**, select a profile and open its agent chain editor. Each agent in the chain has a model field. There's also an **orchestrator** model that runs the top-level coordination of the pipeline.
+
+The model values are aliases — for Claude that's `opus`, `sonnet`, and `haiku` (most capable → fastest). Set the alias you want per agent:
+
+- Leave an agent's model **blank** to fall back to the agent file's own default.
+- Set it explicitly to override just for this profile.
+
+Save, and the next rail launched with that profile uses the new models. Jobs already running keep their snapshot.
+
+## Creating profiles like `fast` and `max`
+
+The natural pattern is a couple of named profiles you reach for depending on the job:
+
+**A `fast` profile** — for small, low-risk changes where you want speed and a smaller bill:
+
+- Architect: a mid or fast model — the plan is simple.
+- Developer: a fast model — the change is mechanical.
+- Reviewer: keep it solid, but you can trim here too.
+
+**A `max` profile** — for gnarly, high-stakes features where you want every step to be as sharp as possible:
+
+- Architect, developer, and reviewer: your strongest model across the board.
+
+### Two ways to build one
+
+1. **Duplicate and tweak** *(recommended).* Select your `default` profile, **Duplicate** it, give the copy a kebab-case name like `fast` or `max`, then adjust each agent's model. You inherit a known-good chain and routing and only change what you mean to.
+2. **Start blank.** Create a **Blank profile** and assemble the chain yourself. You must still include the baseline trio (`sr-architect`, `sr-developer`, `sr-reviewer`) — the pipeline depends on all three — and exactly one terminal catch-all routing rule, which must be last.
+
+Profile names are lowercase kebab-case (e.g. `fast`, `max`, `cheap-and-cheerful`).
+
+## Routing tasks to specific agents
+
+A profile's **routing rules** decide which agent handles a tagged task. Each rule lists task tags and a target agent; the first rule whose tags match wins, and a single `default: true` rule at the end catches everything else. Only agents that are actually in the profile's chain can be routing targets — the editor enforces this.
+
+For everyday use you won't touch routing: the catch-all sends work to the developer and that's correct. Reach for tag rules when you want, say, work tagged `migration` to go to a specialist instead.
+
+## Picking the profile when you launch
+
+All of this comes together at launch: in the rail header, choose `fast`, `max`, or `default` per rail. A batch can mix them — a tiny fix on `fast`, a big feature on `max`, both running at once. See [Profiles & the balanced default](profiles-and-the-balanced-default) for the selection flow.
+
+## A note on safety
+
+Deleting a profile is safe for in-flight work: jobs already launched with it keep their snapshot, and future launches simply fall back through the resolution order. Experiment freely.
+
+## Where to go next
+
+- [Custom agents & the catalog](custom-agents-catalog) — add agents to put in your chains.

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

@@ -0,0 +1,43 @@
+# Custom agents & the catalog
+
+Profiles decide *which agents run and with what models*. But where do the agents themselves come from? That's the **Agents catalog**.
+
+Open **Agents → Catalog** in any project. It's a read-only viewer of every agent available to that project, in two groups:
+
+- **Upstream agents** — the agents that ship with `specrails-core`: the baseline trio (`sr-architect`, `sr-developer`, `sr-reviewer`) and any specialists like `sr-merge-resolver`.
+- **Custom agents** — agents you've added yourself, named `custom-*`.
+
+Each catalog entry shows what the agent is for and its default model, so you can see the full roster before wiring agents into a profile chain.
+
+## Adding a custom agent
+
+Custom agents are plain Markdown files in your repository under `.claude/agents/`, named `custom-<something>.md`. The file contains the agent's instructions (its system prompt) and a small frontmatter header that includes a default `model:`.
+
+Once the file exists in the project, it appears in the catalog as a custom agent, and you can add its id to any profile's agent chain (and route tasks to it). The id must match the filename — an entry for `custom-docs` maps to `.claude/agents/custom-docs.md`.
+
+Because they live in your repo, custom agents are **committable team assets**: commit the file and your whole team gets the agent. This mirrors the core idea throughout the Agents section —
+
+> **Agent definitions are shared (they live in the repo and travel with `git`). Model configuration is per-project (it lives in profiles).**
+
+The `custom-*` namespace is reserved and protected: `specrails-core`'s `init` and `update` commands never touch `.claude/agents/custom-*.md`, so your custom agents survive core upgrades untouched. (The same protection covers plugin-contributed fragments like `custom-serena.md`.)
+
+## Putting a custom agent to work
+
+The typical flow:
+
+1. Write `.claude/agents/custom-<name>.md` with instructions and a default model.
+2. Confirm it shows up in **Agents → Catalog** under Custom.
+3. In **Agents → Profiles**, add the agent to a profile's chain (optionally overriding its model for that profile).
+4. Add a routing rule so tasks with the right tags reach it — or rely on the chain order.
+5. Launch a rail with that profile from the rail header.
+
+## Watching how profiles perform
+
+The Agents section also has a **Usage** tab — a per-profile breakdown of how many jobs ran under each profile over a selected window. It's a quick way to confirm your `fast`/`max` split is actually being used the way you intended, and to spot which profile your team gravitates to.
+
+## Recap of the whole section
+
+- **Agents** are the specialised team members — the shared trio plus specialists and your custom agents. ([Meet the agents](meet-the-agents))
+- **Profiles** package which agents run, with which models, and how tasks route — selected per rail at launch. The default profile is the balanced everyday choice. ([Profiles & the balanced default](profiles-and-the-balanced-default))
+- **Models** are tuned per agent, per project, inside profiles — build `fast` and `max` to match the job. ([Customizing models per agent](customizing-models-per-agent))
+- **The catalog** shows every agent, and the `custom-*` namespace lets you grow the team — definitions shared, config per-project.

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

@@ -0,0 +1,49 @@
+# What is specrails
+
+Welcome to **specrails** — a desktop app that turns an AI coding assistant into a real software team that works on *your* projects, on *your* machine.
+
+Instead of copy-pasting prompts back and forth, you describe what you want as a **spec**, and specrails runs it through a complete development pipeline — designing, building, reviewing, and shipping the change — while you watch it happen live.
+
+## Spec-driven AI development
+
+The heart of specrails is a simple idea: **the best way to get good code out of AI is to start from a clear spec.**
+
+A *spec* is a short, structured description of one piece of work — a feature, a fix, a refactor. You can write one in seconds, or shape one through a guided chat that asks the right questions and drafts it for you. Each spec becomes a **ticket** on your project board, just like a task in any issue tracker.
+
+From there, you hand the spec to the pipeline and let the AI do the heavy lifting.
+
+## The pipeline: Architect → Developer → Reviewer → Ship
+
+When you launch a spec, specrails runs it through four stages, each played by a focused AI agent:
+
+1. **Architect** — reads your spec and the surrounding code, then plans the change: what files to touch, what the shape of the solution should be.
+2. **Developer** — writes the actual code, following the plan.
+3. **Reviewer** — checks the work for correctness and quality, catching issues before you do.
+4. **Ship** — finalizes the change so it's ready to commit.
+
+You see every stage as it runs, with live logs streaming straight from the AI. Nothing is hidden — if something goes sideways, you'll see exactly where.
+
+## Projects
+
+Everything in specrails is organized around **projects**. A project is simply a folder on your computer that holds a codebase. You can add as many projects as you like and switch between them instantly — each one keeps its own specs, job history, analytics, and settings.
+
+Specrails never touches code you didn't ask it to. It works inside your existing repository, and you stay in control of what gets committed.
+
+## Choose your AI provider
+
+Specrails works with the major AI coding CLIs:
+
+- **Claude** (Claude Code)
+- **Codex** (Codex CLI)
+- **Gemini** (Gemini CLI)
+
+Pick whichever you already use — or install more than one and choose per task. A project can run on a single provider or several at once, so you're never locked in.
+
+## Why you'll like it
+
+- **Speed without chaos** — specs keep the AI focused, so you get useful changes instead of sprawling guesses.
+- **Full visibility** — live logs, a clear pipeline view, and per-project analytics show you exactly what happened and what it cost.
+- **Your machine, your code** — everything runs locally against your real repository.
+- **One place for everything** — specs, jobs, chat, a built-in terminal, and cost tracking, all in a single window.
+
+Ready to get going? Next up: [Installing & first run](installing-and-first-run).

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

@@ -0,0 +1,42 @@
+# Installing & first run
+
+Getting specrails onto your machine takes a couple of minutes. Here's the whole flow.
+
+## 1. Download and install
+
+Grab the installer for your platform:
+
+- **macOS (Apple Silicon)** — a `.dmg` file. Open it and drag **specrails** into your Applications folder.
+- **Windows** — a `.exe` setup installer. Run it and follow the prompts.
+
+> **Heads-up on macOS and Windows security prompts**
+>
+> - On **Windows**, the installer isn't code-signed yet, so SmartScreen may show a warning. Click **More info → Run anyway** to continue.
+> - On **macOS**, the app is signed and notarized, so it should open cleanly.
+
+## 2. What you'll need (prerequisites)
+
+Specrails runs AI development pipelines by driving real command-line tools, so a few things need to be available. The good news: the desktop app **bundles most of them for you** (Node.js, npm, and Git ship inside the app), so on a fresh machine there's usually nothing to install.
+
+The one thing specrails can't bundle is the **AI provider CLI** itself. You'll need at least one of:
+
+- **Claude Code**
+- **Codex CLI**
+- **Gemini CLI**
+
+Install whichever you plan to use, sign in to it once from your terminal, and you're set. Specrails detects which providers are present automatically.
+
+> If you ever see a tool flagged as missing, the app shows a **More info** link with copy-paste install commands tailored to your operating system (Homebrew on macOS, winget on Windows, apt/dnf on Linux). You can re-check at any time without restarting.
+
+## 3. First launch — the welcome screen
+
+The first time you open specrails, you'll land on a clean **welcome screen**. There are no projects yet, so the app invites you to add your first one.
+
+You'll see:
+
+- A short description of what specrails does.
+- A single **Add your first project** button.
+
+That's the whole onboarding — no account to create, no sign-up. Specrails works entirely on your machine.
+
+Click **Add your first project** and continue to [Adding your first project](adding-your-first-project).

package/docs/guide/en/getting-started/3-adding-your-first-project.md

@@ -0,0 +1,58 @@
+# Adding your first project
+
+A project is just a folder on your computer that contains a codebase. Let's connect one.
+
+## Open the Add Project dialog
+
+Click **Add your first project** on the welcome screen (or the **Add project** button in the left sidebar later on). A small dialog appears.
+
+## Fill in the details
+
+**Project folder** *(required)*
+
+Point specrails at the folder that holds your code. On the desktop app you can click the folder icon to browse and pick it visually, or paste the full path. This should be the root of your repository — the folder that contains your code and (usually) a `.git` directory.
+
+**Project name** *(optional)*
+
+A friendly label shown in the sidebar. If you leave it blank, specrails uses the folder name.
+
+**Providers**
+
+Choose which AI provider(s) this project should use. Specrails shows you the ones it detected on your machine:
+
+- 🤖 **Claude**
+- ⚡ **Codex**
+- ✨ **Gemini**
+
+Providers it didn't find are greyed out and marked *not found* — install and sign in to one, then re-open the dialog. By default every available provider is pre-selected, but you can deselect down to just the one you want. If you pick more than one, the **first** becomes the project's default; you'll be able to choose per task later.
+
+> A quick check runs in the background to confirm the required tools are present. If something essential is missing, the **Add** button stays disabled and a **More info** link gives you exact install commands.
+
+Click **Add** to continue.
+
+## Setup that runs in seconds
+
+If the folder already has specrails configured, you're done — the project appears in your sidebar instantly.
+
+If it's a fresh project, a short **setup wizard** runs. It has three steps:
+
+1. **Configure** — confirm the basics for each provider you chose.
+2. **Install** — specrails sets up the project automatically. This is the *quick* install: ready-to-use template agents that are in place within seconds. You'll see a live log as it runs.
+3. **Done** — a summary confirming everything's ready.
+
+For a multi-provider project, the install runs once per provider, one after another, and the Done step shows a card for each.
+
+## What gets installed
+
+Setup is deliberately light and **non-invasive**. Specrails adds a small amount of configuration to your project so the pipeline knows how to run:
+
+- A `.specrails/` folder holding your project's agent profiles and local settings.
+- Agent definitions under `.claude/agents/` that power the Architect → Developer → Reviewer → Ship pipeline.
+
+That's it — specrails won't rewrite your source code during setup, and these files are safe to commit if you want to share the configuration with your team.
+
+> **Want the deep setup instead?** The app ships the fast template install on purpose. If you'd prefer the AI-enriched flow (codebase analysis and custom agent personas), you can run `npx specrails-core@latest init` from your project folder in a terminal.
+
+## You're in
+
+Once setup finishes, specrails drops you into your project's dashboard. Time for the tour — see [The dashboard tour](the-dashboard-tour).

package/docs/guide/en/getting-started/4-the-dashboard-tour.md

@@ -0,0 +1,53 @@
+# The dashboard tour
+
+With a project added, you're looking at your **project dashboard** — your home base for turning specs into shipped code. Here's how to find your way around.
+
+## The big picture
+
+The window has three zones:
+
+- **Left sidebar** — your list of projects. Click any project to switch to it instantly; everything else in the window updates to match. The **Add project** button lives here too.
+- **Main area** — the dashboard for the active project: your specs and the pipeline that runs them.
+- **Right sidebar** — navigation between the sections of the current project.
+
+## The main dashboard
+
+This is where the work happens. The dashboard shows:
+
+- **Your specs** — the tickets you've created, organized by status (Backlog/To-Do through Done). You can view them as a list, a grid, or sticky-note cards, whichever you prefer.
+- **A way to add a spec** — start a new piece of work. You can write a quick spec directly, or open a guided **Explore** chat that helps you shape it through conversation and drafts the ticket for you.
+- **Rails** — these are the lanes where specs get built. Drop a spec onto a rail and launch it to send it through the Architect → Developer → Reviewer → Ship pipeline. Multiple rails can run at once, so you can work on several things in parallel.
+
+When a spec is running, you'll see its pipeline progress and live logs — the AI's real-time output as it designs, codes, and reviews your change.
+
+## The right sidebar: project sections
+
+The right sidebar is your switchboard for the current project. Hover it to expand, or pin it open. The sections you'll see:
+
+- **Dashboard** — the specs board and rails (where you just were).
+- **Jobs** — every pipeline run for this project, past and present, with status, duration, and the ability to dig into any run's detail and logs.
+- **Analytics** — what your AI usage is costing. Spending broken down by day, by activity, by model, and by ticket — so there are no surprises.
+- **Agents** — your project's agent profiles: which agents run in the pipeline and which AI models they use. *(Claude-powered projects only.)*
+- **Code** — a read-only file browser with plain-language AI summaries, and chips showing which files the AI has touched. Great for non-developers who want to follow along.
+- **Integrations** — optional add-ons, like connecting your specs to a **Jira** board or enabling extra tooling for the AI.
+- **Settings** — per-project options (telemetry, budgets, provider configuration, and more).
+
+> Some sections only appear when they make sense for the providers you chose — for example, **Agents** is specific to Claude. If you don't see a section, it simply doesn't apply to this project's setup.
+
+## The status bar
+
+A thin strip runs along the very bottom of the window. It's small but handy:
+
+- **Connection indicator** (left) — a coloured dot and label showing the app is live: green for *connected*, amber while *reconnecting*, blue while *syncing* just after a reconnect. You'll rarely need it, but it's reassuring when you do.
+- **Total spend** (right) — a running total of what you've spent, so cost is always one glance away.
+- **Terminal toggle** (far right) — open the built-in terminal panel. Press **Cmd+J** (macOS) or **Ctrl+J** (Windows/Linux) to toggle it any time. It's a full shell, opened right in your project folder.
+
+## A few handy shortcuts
+
+- **Cmd/Ctrl+B** — pin or collapse the sidebars.
+- **Cmd/Ctrl+J** — toggle the terminal panel.
+- **Cmd/Ctrl+K** — open search.
+
+## Where to go next
+
+That's the lay of the land. From here, the natural first move is to **add a spec** and launch it on a rail — watch the pipeline run end to end, then check **Analytics** to see what it cost. Welcome aboard.

package/docs/guide/en/insights/1-analytics-and-cost-tracking.md

@@ -0,0 +1,78 @@
+# Analytics & cost tracking
+
+Every time Specrails runs an AI CLI on your behalf — a pipeline job, a quick spec, an Explore session, an AI edit, a file summary — it records what happened: which model ran, how many tokens went in and out, how long it took, and what it cost. The **Analytics** section turns all of that into a single dashboard so you always know where your AI spend is going.
+
+Open it from the right sidebar (it's labelled **Analytics**). Everything you see is scoped to the project you're currently in — switch projects and the numbers follow.
+
+## What counts as spend
+
+Specrails tracks five kinds of AI activity, called *surfaces*. Each one is colour-coded consistently across every chart so you can spot it at a glance:
+
+- **Job** — a pipeline rail running Architect → Developer → Reviewer → Ship.
+- **Quick spec** — a spec generated through the fast Add Spec path.
+- **Explore spec** — an Explore conversation where you shape a spec by chatting.
+- **AI edit** — an AI-assisted refine on an agent or file.
+- **File summary** — the plain-language summaries that power the Code explorer.
+
+A couple of things are deliberately *not* tracked: the chat sidebar and the setup wizard both spawn AI CLIs, but they never show up in your spend. So the dashboard reflects real, repeatable work rather than incidental chatter.
+
+## Reading the dashboard
+
+The page is built from a handful of blocks, top to bottom:
+
+### The burn meter (Hero)
+
+The big number at the top is your total spend for the selected period, with a **vs prev** delta so you can tell at a glance whether you're trending up or down compared to the previous window. If you've only just started using a project, the empty state tells you when tracking began ("Tracking started YYYY-MM-DD") — there's no historical backfill, so the meter only knows about runs that happened while you were on this version.
+
+### Daily timeline
+
+A stacked bar chart of spend per day, broken down by surface. Days with no activity are shown as zero rather than skipped, so the shape of your week is honest. This is the fastest way to see *when* a costly batch ran.
+
+### Quick vs Explore
+
+A side-by-side card comparing your two spec-creation styles. If you've run fewer than five Explore sessions, it shows a gentle call-to-action instead of misleading averages — small samples don't make for trustworthy comparisons.
+
+### By model
+
+Your top models by spend (up to ten). Click any model to filter the whole dashboard down to just that model — handy when you want to know how much a particular high-end model is really costing you.
+
+### Cost vs turns scatter
+
+Each point is one invocation, plotting cost against the number of turns. Outliers — the expensive, many-turn runs — jump right out. (The scatter shows your most recent 500 points to stay responsive.)
+
+### Top tickets
+
+Your ten most expensive tickets across *all* surfaces combined, so a ticket that cost a little in Explore and a lot in a job shows its true total. Deleted tickets and unattributed runs get their own buckets so nothing silently vanishes from the totals.
+
+### Raw invocations table
+
+The ground truth: one row per invocation. This block has its own secondary filters that only affect the table, so you can drill in without disturbing the charts above.
+
+## Filtering
+
+The sticky header at the top carries the two primary filters — **period** and **surface** — and both are saved into the page URL. That means you can bookmark or share a filtered view ("last 30 days, jobs only") and it'll reopen exactly as you left it. The raw table's filters are separate and stay local to that block.
+
+A note on accuracy: failed and aborted runs are kept out of *cost averages* (they'd skew the per-run numbers) but they still count toward your total run count and failure rate. So the averages stay clean while the reliability picture stays complete.
+
+## Per-ticket cost
+
+You don't have to come to the Analytics page to see what a spec cost. Open any ticket and, if it has any spend attached, you'll see a one-line summary right under the title:
+
+> $0.42 · 6 turns · 1m 12s active · breakdown
+
+Click it and you land on the Analytics page already filtered to that ticket. It's the quickest path from "what did this feature cost me?" to the full breakdown.
+
+## Exporting your data
+
+When you need the numbers outside the app — a spreadsheet, a finance report, your own analysis — use the **Export** dropdown. It offers four formats:
+
+- **Summary CSV** — a multi-section file with totals, the daily timeline, by-surface, by-model, and top tickets.
+- **Summary JSON** — the same summary, structured.
+- **Raw CSV** — every invocation row (up to 10,000; it notes if it had to truncate).
+- **Raw JSON** — the same raw rows, structured.
+
+Exports respect whatever period and surface filters you currently have applied, and files are named so they sort sensibly: `<project>-analytics-<period>-<date>.csv`. The button is disabled when there's nothing to export, and you'll get a clear error toast if a download fails.
+
+## Staying live
+
+You don't need to refresh. When a new invocation is recorded anywhere in the project, the open dashboard quietly refetches itself a moment later, so the burn meter keeps pace with work as it finishes.