specrails-desktop 2.7.0 → 2.9.0

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

@@ -0,0 +1,94 @@
+# Rails & Jobs
+
+Du hast Specs auf dem Board. Hier werden sie zu Code. Eine **Rail** ist die Spur, die eine Spec durch die komplette Pipeline schiebt — Architect → Developer → Reviewer → Ship — und dabei echte KI-Agents direkt in deinem Projektverzeichnis laufen lässt. Diese Seite zeigt dir, wie du eine Rail startest, wie die Job-Queue funktioniert und wie du der Arbeit live zusiehst.
+
+## Was eine Rail ist
+
+Stell dir deinen Bildschirm in zwei Hälften vor:
+
+```
+SpecsBoard (links)          Rails (rechts)
+─────────────────            ─────────────────
+#1 Login flow      ─┐
+#2 Webhook retry    │  ziehen auf
+#3 Cost limits      │ ────────────►   Rail 1   ▶ Play
+#4 Audit log        │
+                    └────────────►   Rail 2   ▶ Play
+```
+
+Eine Rail ist eine **Ausführungsspur**. Du ziehst eine Spec-Karte vom SpecsBoard auf eine Rail und drückst dann **▶ Play**. Die Rail startet die Pipeline und arbeitet die Spec von vorne bis hinten ab — direkt im Arbeitsverzeichnis deines Projekts: Dateien werden bearbeitet, Tests laufen, alles inklusive.
+
+Du kannst mehrere Rails anlegen, um deine Arbeit in benannten Spuren zu organisieren (eine für das Feature, an dem du gerade dran bist, eine weitere, die dahinter wartet). Mehr zu mehreren Rails und zum Stapelbetrieb findest du unter [Batch implement & Multi-Feature](batch-implement-and-multi-feature).
+
+## Eine Rail auf einer Spec starten
+
+1. **Zieh eine Spec-Karte** vom SpecsBoard auf eine Rail. Die ID der Spec taucht in der Spec-Liste der Rail auf. (Du ziehst lieber nicht? Nutze das **Move to rail**-Popover auf der Spec-Karte — es zeigt pro Rail einen Status-Punkt, damit du keine Arbeit auf eine belegte Spur ablegst.)
+2. **Wähle einen Modus**, falls du etwas anderes als den Standard möchtest — die segmentierte Auswahl im Rail-Header bietet `Implement`, `Batch` und (nur bei Claude-Rails) `Ultra`.
+3. **Drück ▶ Play.**
+
+Das war's. Die Rail startet einen KI-CLI-Prozess in deinem Projekt und legt mit der Pipeline los.
+
+### Was im Rail-Header steckt
+
+| Element | Was es macht |
+|---------|--------------|
+| **Status-Pill** | `idle`, `running` oder `failed`. Es gibt kein eigenes „completed“ — eine Rail kehrt auf `idle` zurück, wenn ihr Job sauber durchläuft. |
+| **Spec-Liste** | Die IDs, die dieser Rail zugewiesen sind. Zieh weitere hinein oder heraus, um sie wieder zu lösen. |
+| **Modus-Auswahl** | `Implement` / `Batch` / `Ultra` — siehe Tabelle unten. Pro Rail gespeichert. |
+| **Profil-Auswahl** | Welches Agent-Profil läuft (nur bei Claude-Rails). Erscheint erst, wenn das Projekt mindestens ein Profil hat. |
+| **Engine-Auswahl** | Welcher installierte Provider diese Rail ausführt — Claude, Codex oder Gemini. Wird nur angezeigt, wenn das Projekt mehr als einen Provider hat. Siehe [Engine pro Rail wählen](picking-an-engine-per-rail). |
+| **▶ Play / ■ Stop** | Starten oder abbrechen. |
+
+### Die drei Rail-Modi
+
+| Modus | Befehl | Was er macht |
+|------|---------|--------------|
+| **Implement** | `/specrails:implement` | Ein Job für alle Specs auf der Rail. Durchläuft die komplette Pipeline Architect → Developer → Reviewer → Ship. Der Alltagsstandard. |
+| **Batch** | `/specrails:batch-implement` | Ein Job, der die Specs der Rail nacheinander abarbeitet — in abhängigkeitsbewussten Wellen. Ideal für mehrere zusammenhängende Specs. |
+| **Ultra** | Ultracode | Claude implementiert jede Spec eigenständig und **umgeht** dabei die Pipeline. Ein unabhängiger Job pro Spec. Nur Claude. |
+
+Ultra ist der Sonderfall: Es überspringt die Agent-Kette und übergibt Claude die rohe Spec, an der es mit seinen nativen Tools arbeitet. Das ist offen angelegt, deshalb öffnet Play zuerst eine Bestätigung, und eine Modell-Auswahl pro Rail lässt dich zwischen Haiku / Sonnet / Opus wählen. Ultra erscheint nur, wenn die Engine der Rail Claude ist.
+
+## Die Job-Queue
+
+Jedes Mal, wenn du Play drückst, wird der Rail-Lauf zu einem **Job**. Die wichtigste Regel, die du verinnerlichen solltest:
+
+> **Ein Job pro Projekt — immer nur einer.** Jedes Projekt hat eine einzige Queue. Innerhalb eines Projekts läuft jeweils nur ein Rail-Job; der Rest stellt sich dahinter an und startet automatisch, sobald ein Platz frei wird.
+
+Das überrascht Leute, die drei Rails anlegen und erwarten, dass sie parallel laufen. Tun sie nicht — jedenfalls nicht innerhalb desselben Projekts. Rails hinzuzufügen *organisiert* deine Arbeit in Spuren; es lässt diese Spuren nicht gleichzeitig laufen.
+
+**Echte Parallelität gibt es zwischen Projekten.** Jedes Projekt hat seine eigene, unabhängige Queue — eine Rail in Projekt A und eine Rail in Projekt B laufen also gleichzeitig, ohne sich in die Quere zu kommen. Du willst mehr Durchsatz? Öffne mehr Projekte.
+
+Es gibt keinen globalen Regler für die Parallelität. Die einzige automatische Bremse ist budgetbasiert: Wenn du ein Tagesbudget gesetzt hast (pro Projekt oder app-weit), pausiert die Queue von selbst, sobald die Ausgaben des Tages das Limit erreichen.
+
+## Beim Laufen zusehen
+
+Jeden Job findest du unter **Jobs** in der rechten Seitenleiste des Projekts — eine Kartenliste, die neuesten zuerst. Jede Karte zeigt ein Status-Badge, das Profil-Badge, ein Prioritäts-Badge, die Dauer, die Kosten und den gestarteten Befehl. Über der Liste:
+
+- **Status-Filter-Chips** — zeigen nur Jobs in einem bestimmten Status.
+- **Datumsbereich-Filter** — engt auf ein Zeitfenster ein.
+- **Compare** — wähle zwei Jobs und betrachte sie nebeneinander.
+
+Klick auf eine beliebige Karte, um die **Job-Detail-Ansicht** zu öffnen, in der das Live-Streaming-Log und die Live-Metriken stecken. Das ist die nächste Seite: [Die Job-Detail-Ansicht](the-job-detail-view).
+
+## Einen Job abbrechen
+
+Klick im Rail-Header auf **■ Stop**. Die App sendet `SIGTERM` an den Subprozess, wartet **5 Sekunden** auf einen sauberen Ausstieg und schickt dann `SIGKILL`. Es bleibt nichts halb gestartet zurück.
+
+## Wenn eine Rail nicht starten will
+
+Wenn du eine Engine wählst, deren CLI nicht auf deinem Rechner installiert ist, **schlägt der Start sofort fehl**, anstatt einen kaputten Job zu starten — es wird nichts gestartet. Installiere die fehlende Provider-CLI ([Codex verwenden](../integrations/using-codex), [Gemini verwenden](../integrations/using-gemini)) und starte erneut. Ein fehlendes Claude oder Codex liefert eine präzise „*<provider> CLI not found*“-Meldung; ein fehlendes Gemini zeigt heute eine generische Startfehlermeldung, aber das Ergebnis ist dasselbe.
+
+## Alles stoppen
+
+Wenn etwas nicht stimmt:
+
+- **Eine einzelne Rail** — klick in ihrem Header auf **■ Stop**.
+- **Auto-Pause beim Budget** — setze ein Tagesbudget, und die Queue pausiert sich selbst, sobald die Ausgaben des Tages das Limit erreichen.
+- **Alles** — beende die Desktop-App oder führe `specrails-desktop stop` aus.
+
+## Wie es weitergeht
+
+- [Die Job-Detail-Ansicht](the-job-detail-view) — Phasen, Live-Metriken, Ticket-Karten.
+- [Batch implement & Multi-Feature](batch-implement-and-multi-feature) — mehrere Specs auf einmal ausführen.
+- [Engine pro Rail wählen](picking-an-engine-per-rail) — Claude vs. Codex vs. Gemini.

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

@@ -0,0 +1,90 @@
+# Die Job-Detail-Ansicht
+
+Klick auf eine beliebige Job-Karte auf der **Jobs**-Seite, und du landest hier: dem Cockpit für einen einzelnen Rail-Lauf. Alles dreht sich um ein Versprechen — **die Live-Zahlen, die du siehst, sind echt, niemals geraten.** Diese Seite führt dich durch die Phasen, die Live-Metriken und die Ticket-Karten.
+
+## Das Layout
+
+Über dem vollständigen Streaming-Log sitzen zwei Panels:
+
+```
+┌─────────────────────────────────────────────┐
+│  Status-Header  (Icon · Live-Dauer · …)     │
+├─────────────────────────────────────────────┤
+│  Ticket-Header  ( #12  #14  #15 )           │
+├─────────────────────────────────────────────┤
+│                                             │
+│  Streaming-Log  (Auto-Scroll · Suche · …)   │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+## Pipeline-Phasen
+
+Bei `Implement`- und `Batch`-Jobs durchläuft der Lauf die Phasen, die der Slash-Befehl definiert — standardmäßig:
+
+```
+Architect ──► Developer ──► Reviewer ──► Ship
+```
+
+Jede Phase ist ein spezialisierter Agent, den die Engine der Rail in deinem Projektverzeichnis aufruft:
+
+| Phase | Agent | Was er macht |
+|-------|-------|--------------|
+| **Architect** | `sr-architect` | Plant die Implementierung. |
+| **Developer** | `sr-developer` | Schreibt den Code. |
+| **Reviewer** | `sr-reviewer` | Prüft das Ergebnis. |
+| **Ship** | (variiert) | Letzter Feinschliff: Tests, Commit, PR-Entwurf. |
+
+Welcher Agent welche Phase übernimmt, entscheidet das **Agent-Profil** des Projekts. Das Basistrio (`sr-architect`, `sr-developer`, `sr-reviewer`) ist immer vorhanden; Routing-Regeln in einem Profil können weitere Agents hinzufügen oder austauschen, wer eine Phase ausführt. Die Phasen-Fortschrittsleiste erscheint nur, wenn der Befehl tatsächlich Phasen definiert — Ultracode-Jobs (die die Pipeline umgehen) zeigen keine an.
+
+## Live-Metriken — ehrlich von Grund auf
+
+Der Status-Header ist die Schlagzeile. Er zeigt ein Status-Icon, eine Aktivitätszeile, die beschreibt, was der Job *gerade jetzt* tut, eine Zählung der ausgeführten Schritte und eine Reihe von Metriken:
+
+| Metrik | Wann du den echten Wert siehst |
+|--------|------------------------------|
+| **Dauer** | **Live.** Ein 1-Sekunden-Ticker zählt hoch, während der Job läuft — das ist die einzige wirklich live aktualisierte Zahl. |
+| **Turns** | Inkrementell aus den gestreamten Assistant-Events abgeleitet, sobald sie eintreffen. |
+| **Tokens** | Inkrementell aus demselben Stream zusammengezählt (tolerant gegenüber Events, denen Usage-Felder fehlen). |
+| **Kosten** | Werden als `—` angezeigt, bis der Job endet, dann als verbindlicher `total_cost_usd` enthüllt. |
+
+Das Designprinzip: **keine ungefähren oder geschätzten Zahlen während des Laufs.** Die Dauer ist echt, weil sie nichts anderes als eine Uhr ist. Turns und Tokens werden aus tatsächlich gestreamter Aktivität aufaddiert. Die Kosten werden während des Laufs bewusst *nicht* geschätzt — sie erscheinen als ausstehend und lösen sich erst zu ihrer finalen, verbindlichen Zahl auf, wenn der Provider sie beim Job-Ende meldet. Wenn eine Zahl so aussieht, als würde sie warten, ist das Absicht — dir wird die Wahrheit gezeigt, keine Hochrechnung.
+
+Das Label und das Icon im Header entsprechen dem Status des Jobs, und das Panel wird für `running`-, `completed`- und `failed`-Jobs gleichermaßen gerendert — die Detail-Ansicht eines abgeschlossenen Jobs zeigt also dieselben Metriken, eingefroren auf ihren Endwerten.
+
+## Die Ticket-Karten
+
+Der **Ticket-Header** sitzt zwischen dem Status-Header und dem Log. Es ist eine hochwertige Identitäts-Karte, die einen Chip für jede Spec zeigt, die der Job berührt hat — aus dem gestarteten Befehl abgeglichen, sodass er exakt widerspiegelt, um welche Tickets es bei diesem Lauf ging.
+
+- **2–3 Tickets** — als Liste von Chips angezeigt.
+- **4 oder mehr** — werden zu einem kompakten `+ N more`-Modus mit einem Aufklapp-Chevron zusammengefasst, damit der Header aufgeräumt bleibt.
+
+Ein Klick auf einen Chip öffnet die Detailansicht dieser Spec **über der Job-Seite** — du verlierst deinen Platz nicht und wechselst die Route nicht. Eine schnelle Möglichkeit, noch einmal nachzulesen, was ein Job liefern soll, während du ihm bei der Arbeit zusiehst. (Auf tabletbreiten Bildschirmen kannst du ein Ticket-Modal sogar zur Seite ziehen, um zwei Specs nebeneinander zu vergleichen.)
+
+## Das Streaming-Log
+
+Unter den Panels liegt das vollständige Log des Laufs, in Echtzeit über den WebSocket gestreamt:
+
+- **Auto-Scroll** hält die neueste Ausgabe im Blick (scrollst du hoch, pausiert es, damit du in Ruhe lesen kannst).
+- **Suche**, um zu einer Stelle zu springen.
+- **Copy**, um das ganze Log zu greifen.
+
+Das ist die rohe Wahrheit darüber, was die KI tut — jeder Tool-Aufruf, jede Dateibearbeitung, jeder Testlauf.
+
+## Diagnose-Export
+
+Wenn [Telemetrie](../settings/customizing) für den Job aktiviert war, erscheint im Header ein Button **Export diagnostic**. Er lädt ein ZIP herunter, das Folgendes enthält:
+
+- `job-metadata.json` — Befehl, Status, Profil, Plugins.
+- `telemetry.ndjson` — unkomprimierte OTLP/JSON-Signale.
+- `logs.txt` — das vollständige Streaming-Log.
+- `summary.md` — menschenlesbare Highlights.
+- `profile.json`, `plugins.json` — exakte Snapshots dessen, was lief (sofern vorhanden).
+
+Praktisch, um einen Lauf mit einem Teammitglied zu teilen oder einen präzisen Fehlerbericht einzureichen.
+
+## Wie es weitergeht
+
+- [Rails & Jobs](rails-and-jobs) — Starten und Einreihen in die Queue.
+- [Batch implement & Multi-Feature](batch-implement-and-multi-feature) — viele Specs, abhängigkeitsbewusste Wellen.
+- [Kosten verfolgen](../analytics/tracking-cost) — aus Kosten pro Job Projekt-Analysen machen.

package/docs/guide/de/pipeline/3-batch-implement-and-multi-feature.md

@@ -0,0 +1,78 @@
+# Batch implement & Multi-Feature
+
+Eine Spec nach der anderen ist völlig okay, aber viel echte Arbeit kommt in Bündeln — ein Feature plus seine Tests plus seine Migration, oder ein Backlog, das du in einer Sitzung abräumen willst. Diese Seite zeigt, wie du mehrere Specs zusammen ausführst: den Batch-Modus, Abhängigkeits-Wellen und wie die Pipeline verhindert, dass gleichzeitige Arbeit miteinander kollidiert.
+
+## Mehrere Specs auf einmal ausführen
+
+Der einfachste Weg, einen ganzen Stapel Specs aus einer Rail laufen zu lassen, ist der **Batch**-Modus:
+
+1. **Zieh alle Specs**, die du willst, auf eine einzige Rail. Sie stapeln sich in der Spec-Liste dieser Rail.
+2. **Stell den Modus der Rail auf Batch** (die segmentierte Auswahl im Rail-Header).
+3. **Drück ▶ Play.**
+
+Die Rail startet **einen** `/specrails:batch-implement`-Job, der jede zugewiesene Spec abarbeitet. Beobachte ihn wie jeden anderen Job auf der Jobs-Seite — es ist ein einzelner Job für das gesamte Set, nicht ein Job pro Spec.
+
+Das ist wichtig wegen der **Ein-Job-pro-Projekt-Queue**. Da ein Projekt immer nur einen Rail-Job auf einmal ausführt, ist der Batch-Modus auch der sauberste Weg, eine Liste von Specs zu *verketten*, ohne mit mehreren Rails zu jonglieren und auf das Leeren jeder einzelnen zu warten.
+
+### Implement vs. Batch — welcher Modus?
+
+| | **Implement** | **Batch** |
+|---|---|---|
+| Befehl | `/specrails:implement` | `/specrails:batch-implement` |
+| Specs pro Job | Alle auf der Rail, als eine Arbeitseinheit behandelt | Alle auf der Rail, **nacheinander** abgearbeitet |
+| Am besten für | Eine eng verzahnte Änderung | Mehrere eigenständige Features, die du der Reihe nach abräumen willst |
+| Reihenfolge | n/v | Abhängigkeitsbewusste Wellen (siehe unten) |
+
+Wenn die Specs wirklich eine Änderung sind, nimm **Implement**. Wenn sie eine Liste separater Features sind, nimm **Batch** und lass es sie sequenzieren.
+
+## Abhängigkeits-Wellen
+
+Der Batch-Modus arbeitet die Specs nicht einfach von oben nach unten ab — er berechnet eine **abhängigkeitsbewusste Ausführungsreihenfolge** und gruppiert die Specs in *Wellen*. Der Orchestrator (`/specrails:batch-implement`) ermittelt, welche Specs von welchen abhängen, und plant sie dann so ein, dass nichts vor der Arbeit läuft, auf der es aufbaut.
+
+Konzeptionell:
+
+```
+Welle 1:  #2 (Datenmodell)         ← keine Abhängigkeiten, läuft zuerst
+Welle 2:  #4 (API auf dem Modell)  ← wartet auf #2
+          #5 (CLI auf dem Modell)  ← wartet auf #2
+Welle 3:  #7 (Docs über alles)     ← wartet auf #4 und #5
+```
+
+Innerhalb des Jobs werden die Specs jeder Welle implementiert, bevor die nächste Welle beginnt. Du konfigurierst das nicht von Hand — der Orchestrator leitet die Wellen aus den Specs selbst ab. Sieh dabei zu, wie es sich in der [Job-Detail-Ansicht](the-job-detail-view) entfaltet: Das Streaming-Log erzählt, an welcher Spec der Batch gerade arbeitet, und der Ticket-Header zeigt jede Spec, die der Job berührt hat.
+
+## Worktree-Isolation
+
+Wenn in einem Lauf mehrere Specs implementiert werden, hält die Pipeline jede Arbeitseinheit isoliert, damit gleichzeitige oder aufeinanderfolgende Änderungen sich nicht gegenseitig die Dateien zertrampeln. Der Batch-Orchestrator führt die Implementierung jeder Spec in ihrem eigenen sauberen Arbeitskontext aus und integriert dann die Ergebnisse — eine halbfertige Spec hinterlässt deinen Tree also nie in einem kaputten Zwischenzustand, den die nächste zu sehen bekäme.
+
+In der Praxis heißt das:
+
+- Jede Spec bekommt zum Implementieren eine saubere Ausgangslage, statt die noch laufenden Änderungen der vorherigen Spec mitten im Fluss zu erben.
+- Reviews und Ship-Schritte arbeiten auf einem kohärenten Snapshot, nicht auf einem beweglichen Ziel.
+- Ein Fehler in einer Welle bleibt eingegrenzt — er beschädigt nicht stillschweigend die Specs, die bereits ausgeliefert wurden.
+
+Die App protokolliert pro Job genau, welche Dateien berührt wurden und welches Ticket sie berührt hat (du siehst das als Provenance-Chips im **Code**-Bereich und als „Von diesem Ticket berührte Dateien“-Liste im Detail-Modal jeder Spec). Genau diese Zuordnung lässt dich einem Multi-Spec-Lauf vertrauen: Du kannst eine Dateiänderung immer bis zu der Spec zurückverfolgen, die sie verursacht hat.
+
+## Multi-Feature über Projekte hinweg
+
+Wenn du echte Parallelität willst — zwei große Features, die gleichzeitig gebaut werden — teile sie **über Projekte** auf, nicht über Rails in einem Projekt. Jedes Projekt hat seine eigene unabhängige Queue, also:
+
+```
+Projekt A   ▶ Rail baut Feature X   ┐
+                                    ├─ laufen gleichzeitig
+Projekt B   ▶ Rail baut Feature Y   ┘
+```
+
+Es gibt kein globales Parallelitäts-Limit und keinen Wettstreit zwischen Projekten. Öffne beide, starte in jedem eine Rail, und sie kommen zusammen voran. Die einzige geteilte Bremse ist dein Budget-Limit, das die Queues pro Projekt oder app-weit pausiert, sobald die Ausgaben des Tages das Limit erreichen.
+
+## Tipps für große Batches
+
+- **Gruppiere verwandte Specs auf einer Rail**, bevor du auf Batch umstellst — die Abhängigkeits-Wellen sehen nur, was auf dieser Rail liegt.
+- **Setze ein Tagesbudget**, bevor du einen großen Batch startest, damit ein unerwartet teurer Lauf automatisch pausiert, statt davonzulaufen. Konfiguriere es unter [Budget](../settings/customizing).
+- **Nutze danach den Compare-Button** auf der Jobs-Seite, um zwei Batch-Läufe nebeneinander zu vergleichen.
+- **Exportiere eine Diagnose** (falls Telemetrie an war), um den exakten Profil- und Plugin-Snapshot für den gesamten Batch zu erhalten.
+
+## Wie es weitergeht
+
+- [Rails & Jobs](rails-and-jobs) — das Queue-Modell im Detail.
+- [Die Job-Detail-Ansicht](the-job-detail-view) — einem Batch-Lauf live zusehen.
+- [Engine pro Rail wählen](picking-an-engine-per-rail) — beachte: Batch läuft auf jedem Provider; Ultra gibt es nur bei Claude.

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

@@ -0,0 +1,60 @@
+# Engine pro Rail wählen
+
+Specrails desktop behandelt **Claude Code**, **Codex CLI** und **Gemini CLI** als gleichwertige Engines. Ein Projekt kann eine, zwei oder alle drei installiert haben — und wenn mehr als eine vorhanden ist, wählst du, welche Engine jede Rail ausführt. Diese Seite zeigt die Engine-Auswahl pro Rail und wann du zu welcher greifst.
+
+## Wann die Auswahl erscheint
+
+Die **Engine-Auswahl** sitzt im Rail-Header, direkt neben der Modus-Auswahl. Sie wird nur angezeigt, wenn das Projekt **mehr als einen** Provider installiert hat.
+
+> **Projekte mit nur einem Provider verhalten sich byteidentisch.** Hat ein Projekt nur eine Engine, erscheint keine Auswahl, und an der Provider-Wahl ändert sich nichts — es läuft einfach auf dieser Engine. Die Auswahl ist ausschließlich für Multi-Provider-Projekte da.
+
+Wenn sie erscheint, gilt deine Wahl **pro Rail und pro Start** — verschiedene Rails können verschiedene Engines ausführen, und deine Wahl wird pro Projekt gemerkt (mit der primären Engine des Projekts als Voreinstellung).
+
+## So wählst du eine Engine
+
+1. Vergewissere dich, dass die Engine-Auswahl der Rail sichtbar ist (Projekt hat 2+ Provider).
+2. Klick darauf und wähle **Claude**, **Codex** oder **Gemini**.
+3. Starte die Rail mit **▶ Play**.
+
+Die ausgewählte Engine führt jede Phase der Pipeline dieser Rail aus. Ist die CLI der gewählten Engine nicht installiert, schlägt der Start sofort fehl — es wird nichts gestartet. Installiere die fehlende CLI und versuch es erneut.
+
+## Wofür jede Engine gut ist
+
+Alle drei führen die Standard-Pipelines **Implement** und **Batch** aus. Hier ein praktischer Leitfaden zur Auswahl:
+
+| Engine | Greif dazu, wenn… | Hinweise |
+|--------|--------------------|-------|
+| **Claude** | Du den vollen Funktionsumfang willst: Agent-Profile, Ultracode, native Kostenmeldung, die umfangreichste Tool-Unterstützung. Der Standard für die meiste Arbeit. | Die einzige Engine, die **Agent-Profile**, **Ultracode** und ein paar Claude-exklusive Spec-Features (Contract Layer, SMASH) unterstützt. |
+| **Codex** | Du die OpenAI Codex CLI bevorzugst oder Implementierungen über verschiedene Provider hinweg vergleichen willst. | `codex` ≥ 0.128.0. Keine native Kostenmeldung — die App ergänzt die Kosten aus ihrer Preistabelle. Profile gelten nicht. |
+| **Gemini** | Du Googles Gemini CLI, native Telemetrie oder einen günstigeren Lauf für Routine-Specs willst. | `gemini` ≥ 0.11.0 (setze `GEMINI_API_KEY`). Native OTLP-Telemetrie. Profile gelten nicht. |
+
+### Die Claude-exklusiven Features
+
+Ein paar Dinge funktionieren nur auf Claude-Rails — wähle Claude, wenn du sie brauchst:
+
+- **Agent-Profile** — Modell-Routing pro Agent. Auf Codex- oder Gemini-Rails läuft der Lauf immer im Legacy-Modus, und ein ausgewähltes Profil wird **ignoriert**. Die Profil-Auswahl ist für Nicht-Claude-Engines ausgeblendet.
+- **Ultracode (`Ultra`-Modus)** — der autonome, pipeline-umgehende Modus. Das `Ultra`-Segment und seine Haiku/Sonnet/Opus-Modell-Auswahl erscheinen nur, wenn die Engine der Rail Claude ist.
+- **Contract Layer & SMASH** — Claude-exklusive Features zur Spec-Verfeinerung (das sind Add-Spec-Optionen, keine Rail-Optionen, aber dieselbe Einschränkung gilt).
+
+Wenn ein Projekt Engines mischt, zeigt die rechte Seitenleiste nur Bereiche, die **jeder** installierte Provider unterstützt — der **Agents**-Bereich verschwindet also komplett bei einem Projekt, das irgendeinen Nicht-Claude-Provider enthält, weil Profile Claude-spezifisch sind.
+
+## Ein praktischer Workflow
+
+Multi-Provider-Projekte spielen ihre Stärken aus, wenn du **vergleichen** oder **kostenoptimieren** willst:
+
+- **Implementierungen vergleichen.** Leg dieselbe Spec auf zwei Rails, stell eine auf Claude und eine auf Codex, starte beide (über Projekte hinweg oder nacheinander in der Queue desselben Projekts) und nutze dann den **Compare**-Button auf der Jobs-Seite, um die Ergebnisse zu vergleichen.
+- **Pro Spec kostenoptimieren.** Lass wichtige Specs auf Claude mit einem `max`-Profil laufen; lass Routine-Aufräum-Specs auf Gemini laufen, um Ausgaben zu sparen. Filtere `/analytics` nach Engine, um die Aufschlüsselung zu sehen.
+- **Sinnvoll voreinstellen.** Lege deine meistgenutzte Engine als primäre Engine des Projekts fest, damit Rails standardmäßig darauf laufen, und wechsle nur pro Rail, wenn eine bestimmte Spec eine andere will.
+
+## Worauf du achten solltest
+
+- **Die Provider-Wahl ist nach dem Anlegen des Projekts unveränderlich** (v1). Du wählst die installierten Provider beim Hinzufügen des Projekts; es gibt keinen Einstellungs-Schalter, um später einen hinzuzufügen oder zu entfernen.
+- **Kosten werden immer verfolgt**, auch für Engines ohne native Kostenmeldung — die App greift auf eine Preistabelle zurück, sodass auch Codex- und Gemini-Läufe in den [Analysen](../analytics/tracking-cost) auftauchen.
+- **Der „Open AI CLI“-Button im Terminal** bietet bei Multi-Provider-Projekten ebenfalls eine Provider-Auswahl, falls du eine CLI lieber von Hand bedienst.
+
+## Wie es weitergeht
+
+- [Codex verwenden](../integrations/using-codex) — installieren und anmelden.
+- [Gemini verwenden](../integrations/using-gemini) — installieren, `GEMINI_API_KEY`, Telemetrie.
+- [Rails & Jobs](rails-and-jobs) — die Queue und der Start-Flow.
+- [Kosten verfolgen](../analytics/tracking-cost) — Kostenaufschlüsselung pro Engine.

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

@@ -0,0 +1,37 @@
+# Themes
+
+Gestalte Specrails so, wie es dir gefällt. Die App bringt fünf sorgfältig abgestimmte Themes mit, zwischen denen du jederzeit blitzschnell wechseln kannst – ohne Neustart, ohne Neukompilieren, ganz ohne Konfiguration.
+
+## Die fünf eingebauten Themes
+
+| Theme | Charakter |
+| --- | --- |
+| **Specrails** | Der Standard. Ausgewogen, ruhig, im Markenlook. |
+| **Dracula** | Klassisches dunkles Violett. Schont die Augen bei Nacht. |
+| **Aurora Light** | Ein helles, luftiges Light-Theme für die Arbeit am Tag. |
+| **Obsidian Dark** | Tiefer, kontrastreicher Dark Mode. |
+| **Matrix** | Grün auf Schwarz – für das Gefühl, mitten im Mainframe zu sitzen. |
+
+## So wechselst du
+
+1. Öffne die **Einstellungen** (das app-weite Einstellungsfenster).
+2. Wechsle zum Bereich **Erscheinungsbild**.
+3. Wähle ein Theme. Es wird sofort in der gesamten App angewendet.
+
+Das war's schon. Die Änderung greift in dem Moment, in dem du klickst – die Oberfläche bekommt live ihr neues Aussehen.
+
+## Wo es überall greift
+
+Deine Theme-Wahl gilt **app-weit**, nicht pro Projekt. Jedes Projekt, jede Seite, jedes Panel folgt demselben Theme. Es erreicht auch Stellen, an die du vielleicht gar nicht denkst:
+
+- **Das Terminal-Panel** färbt sich live um und behält dabei deine Ausgabe-Historie und jede laufende Shell-Sitzung unverändert bei.
+- **Diagramme** auf der Analytics-Seite passen ihre Farben an.
+- **Code-Syntaxhervorhebung** im Code-Viewer folgt ebenfalls dem Theme.
+
+## Es merkt sich deine Wahl
+
+Deine Auswahl wird mit der App gespeichert und bleibt so über Neustarts hinweg erhalten. Damit beim ersten Öffnen nicht kurz die falschen Farben aufblitzen, wendet Specrails dein gespeichertes Theme bereits an, bevor die Oberfläche überhaupt fertig geladen ist – so stimmt das Bild schon ab dem allerersten Frame.
+
+## Eine Anmerkung für Neugierige
+
+Themes basieren auf einer kleinen Menge semantischer Farbrollen (einer „Akzent“-Farbe, einer „Surface“-Farbe und so weiter) statt auf fest verdrahteten Farbtönen. Deshalb lässt sich das nächste Theme so leicht ergänzen, und deshalb bleibt jedes Theme in sich stimmig – jedes belegt diese Rollen einfach neu. Du musst dir darüber keine Gedanken machen, um es zu nutzen; es ist schlicht der Grund, warum sich das Theming so nahtlos anfühlt.

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

@@ -0,0 +1,39 @@
+# Sprache
+
+Specrails spricht deine Sprache. Die Oberfläche ist vollständig in acht Sprachen übersetzt und richtet sich standardmäßig nach der Sprache, die auf deinem Computer eingestellt ist – für die meisten erscheint sie also schon beim ersten Start in der richtigen Sprache.
+
+## Unterstützte Sprachen
+
+- English (Englisch)
+- Español (Spanisch)
+- Français (Französisch)
+- Deutsch
+- Português (Portugiesisch)
+- Italiano (Italienisch)
+- 中文 (Chinesisch)
+- 日本語 (Japanisch)
+
+## Es startet in deiner Betriebssystemsprache
+
+Wenn du Specrails zum ersten Mal öffnest, schaut es sich die Spracheinstellungen deines Betriebssystems an und ordnet sie der am besten passenden unterstützten Sprache zu. Ist dein Mac oder PC auf Spanisch eingestellt, siehst du Spanisch. Bei einer regionalen Variante (etwa `es-ES` oder `zh-Hans-CN`) ordnet Specrails sie automatisch der passenden Basissprache zu.
+
+Du musst nichts weiter tun – und solange du die Spracheinstellung nie anrührst, folgt Specrails weiter deinem Betriebssystem. Stellst du die Sprache deines Computers später um, zieht Specrails einfach mit.
+
+## Selbst eine Sprache wählen
+
+Du möchtest etwas anderes als die Standardsprache deines Betriebssystems? Dann wähle sie ausdrücklich:
+
+1. Öffne die **Einstellungen**.
+2. Wechsle zum Bereich **Sprache**.
+3. Wähle deine Sprache.
+
+Der Wechsel ist **sofort** – die gesamte Oberfläche wird ohne Neustart in der neuen Sprache neu aufgebaut. Sobald du dich einmal ausdrücklich festgelegt hast, merkt sich Specrails das und folgt nicht mehr dem Betriebssystem, sodass deine Wahl bei jedem Öffnen der App respektiert wird.
+
+## Was übersetzt wird
+
+Alles, was du in der Oberfläche liest – Schaltflächen, Beschriftungen, Statusmeldungen, Seitentitel, Dialoge. Auch Datumsangaben passen sich deiner gewählten Sprache an, sodass sie so formatiert sind, wie es diese Sprache erwartet.
+
+## Gut zu wissen
+
+- **Englisch ist die Ausgangssprache.** Wenn eine brandneue Funktion erscheint, bevor ihre Übersetzung fertig ist, siehst du hier und da kurz eine englische Beschriftung – sie wird in einem der nächsten Updates übersetzt.
+- Deine Sprachwahl gilt **app-weit**, in allen deinen Projekten gleich.

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

@@ -0,0 +1,46 @@
+# Pipeline-Telemetrie & Diagnose
+
+Wenn ein Pipeline-Job nicht so läuft, wie du es erwartet hast, liefert dir die Telemetrie eine detaillierte Aufzeichnung dessen, was die AI-CLI hinter den Kulissen tatsächlich getan hat. Sie ist **standardmäßig aus** und vollständig optional, pro Projekt – aktiviere sie nur dann, wenn du sie wirklich willst.
+
+## Was es ist
+
+Die Telemetrie erfasst strukturierte Diagnosesignale (Traces, Metriken und Logs), die die AI-CLI während eines Pipeline-Jobs aussendet. Stell es dir wie einen Flugschreiber für deine Pipeline-Läufe vor: Zeitabläufe, Token-Verbrauch und die Aktivität Schritt für Schritt – lokal aufgezeichnet, damit du einen Job im Nachhinein untersuchen kannst.
+
+Es baut auf **OpenTelemetry** auf, einem offenen Standardformat – die Daten sind also nicht in einer proprietären Blackbox eingesperrt.
+
+## Aktivieren
+
+Die Telemetrie wird **pro Projekt** konfiguriert:
+
+1. Öffne die **Einstellungen** des Projekts (die projektspezifische Einstellungsseite).
+2. Suche den Schalter **Pipeline-Telemetrie**.
+3. Schalte ihn ein.
+
+Ab diesem Moment zeichnen Pipeline-Jobs in diesem Projekt Telemetrie auf. Andere Projekte bleiben davon unberührt – jedes Projekt entscheidet für sich selbst.
+
+### Was abgedeckt ist
+
+Die Telemetrie gilt für **Pipeline-Jobs** (die in der Queue eingereihten Architect → Developer → Reviewer → Ship-Rail-Läufe). Interaktive Sitzungen wie der Chat und der Einrichtungsassistent sind bewusst ausgenommen – die Telemetrie ist für die wiederholbaren, untersuchbaren Pipeline-Läufe gedacht, nicht für einmalige Unterhaltungen.
+
+## Wo die Daten liegen
+
+Alles bleibt auf deinem Rechner, in deinem Home-Verzeichnis (`~/.specrails/`) – niemals in deinem Repository. Die Rohaufzeichnungen werden komprimiert neben ihrem Job gespeichert, und ältere Aufzeichnungen werden nach einer Woche automatisch zu kompakten Zusammenfassungen verdichtet, damit alles aufgeräumt bleibt. Du musst nichts davon von Hand verwalten.
+
+## Ein Diagnose-Paket exportieren
+
+Das Nützlichste, was die Telemetrie ermöglicht, ist der **Diagnose-Export** – ein einzelnes ZIP, das alles zu einem Job bündelt, um Probleme zu untersuchen oder Informationen zu teilen.
+
+Sobald für einen Job Telemetrie aufgezeichnet wurde, erscheint auf seiner Job-Karte eine **Export-Schaltfläche**. Klick darauf, um ein ZIP herunterzuladen, das Folgendes enthält:
+
+- **`job-metadata.json`** – Identität und Parameter des Jobs
+- **`telemetry.ndjson`** – die aufgezeichneten Rohsignale
+- **`logs.txt`** – die erfasste Log-Ausgabe
+- **`summary.md`** – eine gut lesbare Zusammenfassung des Laufs
+
+Verwendet das Projekt Plugins, enthält das Paket zusätzlich eine Momentaufnahme, welche Plugins für diesen Job aktiv waren.
+
+Genau dieses Paket schnappst du dir, wenn du einen kniffligen Lauf nachvollziehen, eine Aufzeichnung aufbewahren oder jemandem die Details geben willst, der dir beim Debuggen hilft.
+
+## Deaktivieren
+
+Stell den Schalter jederzeit wieder aus. Neue Jobs hören sofort auf aufzuzeichnen. Was bereits erfasst wurde, bleibt auf der Festplatte, bis es verdichtet wird oder du das Projekt entfernst – nichts wird irgendwohin gesendet oder hinter deinem Rücken verloren.

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

@@ -0,0 +1,48 @@
+# Wo deine Daten liegen
+
+Kurz gesagt: **Specrails hält deine Repositories sauber.** Wenn du die App auf eines deiner Projekte richtest, zieht sie nicht bei dir ein, streut keine Konfigurationsdateien wild umher und schreibt nichts um, worum du nicht gebeten hast. Dein Code bleibt deiner – und bleibt sauber.
+
+## Dein Repository bleibt sauber
+
+Specrails' eigene Dateien – seine Datenbanken, der projektspezifische Zustand, die Agent-Definitionen, Einstellungen, Telemetrie, Zusammenfassungen und alles andere, was es zum Laufen braucht – liegen an einem einzigen, ordentlichen Ort in deinem Home-Verzeichnis:
+
+```
+~/.specrails/
+```
+
+Dieser Ordner ist der private Arbeitsbereich der App. Hier leben die Projektregistrierung, die projektspezifischen Datenbanken, die mitgelieferten Tools und alle betrieblichen Bestandteile. Deine eigentlichen Code-Repositories werden für nichts davon als Ablageplatz missbraucht.
+
+Das bedeutet:
+
+- Die `.gitignore` deines Repositorys wird von der App **nicht** umgeschrieben.
+- Dein Repository wird nicht mit Tool-Konfigurationen oder versteckten Zustandsverzeichnissen vollgemüllt.
+- Wenn du ein Projekt aus Specrails entfernst, bleibt kein Durcheinander in deinem Code zurück.
+
+Falls du schon Tools genutzt hast, die klammheimlich überall in deinem Projekt Ordner und Dateien angelegt haben: Das hier ist ein bewusster Gegenentwurf. Specrails ist so gebaut, dass es für die git-Historie eines Repositorys ein **Nicht-Ereignis** ist, die App darauf zu richten.
+
+## Das eine, was *doch* committet wird – mit Absicht
+
+Es gibt genau eine bewusste Ausnahme, und sie ist der ganze Sinn des Tools: **deine OpenSpec-Specs.**
+
+Specs leben in deinem Repository, und zwar unter:
+
+```
+openspec/
+```
+
+Das ist Absicht. Deine Specs sind ein **Ergebnis** – eine versionierte, überprüfbare Aufzeichnung dessen, was du bauen wolltest und warum. Sie gehören neben deinen Code, nachverfolgt in git, sichtbar in Pull Requests, geteilt mit deinem Team. Genau darin liegt der Wert: Specs sind kein wegwerfbarer Zwischenstand, sondern Teil der Geschichte deines Projekts.
+
+Die Regel ist also einfach und ehrlich:
+
+- **`openspec/`** → liegt in deinem Repository, wird committet, mit Absicht.
+- **Alles andere, was Specrails braucht** → liegt unter `~/.specrails/`, dir aus dem Weg.
+
+## Warum das so funktioniert
+
+Specrails führt die AI-Tools aus seinem eigenen privaten Arbeitsbereich aus (unter `~/.specrails/`) und greift nur für die Dinge in dein echtes Repository zurück, die es wirklich berühren müssen – deinen Code lesen und die Specs schreiben, um die du gebeten hast. Die Tools, die Framework-Definitionen und die Buchführung bleiben allesamt im Home-Ordner der App.
+
+Was das für dich bedeutet: Du kannst ein Projekt hinzufügen, Pipelines laufen lassen, Specs erkunden und Dinge ausprobieren – in der Gewissheit, dass sich Working Tree und git-Historie deines Repositorys immer nur auf die Weise ändern, die du erwartest – deine committeten Specs und der Code, den deine Pipelines schreiben. Sonst schleicht sich nichts ein.
+
+## Ein Projekt entfernen
+
+Wenn du ein Projekt aus Specrails entfernst, räumt die App ihren eigenen projektspezifischen Zustand unter `~/.specrails/` auf. Die Specs, die bereits in dein Repository committet wurden, bleiben dort, wo sie hingehören – in deinem Repository –, denn sie gehören dir.

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

@@ -0,0 +1,52 @@
+# Specs & das Backlog
+
+Eine **Spec** ist die Arbeitseinheit, die die KI-Pipeline umsetzt. Stell sie dir wie ein Ticket vor: ein Titel, eine Beschreibung dessen, was du erledigt haben möchtest, eine Priorität und optionale Labels. Wenn du die Pipeline startest, lesen die KI-Agenten die Spec und handeln danach – eine klare Spec ist also der mit Abstand wichtigste Input für ein gutes Ergebnis.
+
+Specs werden in der App manchmal auch **Tickets** genannt – beide Begriffe meinen dasselbe.
+
+## Das Board
+
+Jedes Projekt öffnet sich auf seinem **Dashboard**, das das **SpecsBoard** zeigt – die Liste aller Specs des Projekts. Das ist dein Backlog. Von hier aus erstellst du neue Specs, legst ihre Priorität fest, ziehst sie auf eine Rail, um sie umzusetzen, und beobachtest, wie sich ihr Status während der Arbeit ändert.
+
+Das Board hat zwei Ansichtsmodi, die du über einen Umschalter in der Toolbar wechselst und die pro Projekt gemerkt werden:
+
+- **Post-it-Ansicht** (Standard) – kartenartige Kacheln mit kurzen Zusammenfassungen.
+- **Listenansicht** – kompakte, einzeilige Zeilen.
+
+Du kannst außerdem nach **Status** (Alle / To-do / Fertig) und nach **Label** filtern sowie nach **Standard**, **Ticket #** oder **Priorität** sortieren (jeweils mit Umschalter für auf- und absteigend).
+
+## Status
+
+Eine Spec durchläuft eine überschaubare Reihe von Status. Das Board gibt jedem davon einen einheitlichen visuellen Hinweis, damit du den Zustand deines Backlogs auf einen Blick erfassen kannst:
+
+| Status | Bedeutung |
+|--------|-----------|
+| **Entwurf** | Eine noch in Arbeit befindliche Idee, die aus einer Explore-Unterhaltung gespeichert wurde. Noch nicht bereit zur Umsetzung – du kannst zurückkommen und sie weiter ausarbeiten. Zeigt ein `Draft`-Pill. |
+| **To-do** | Bereit, in Angriff genommen zu werden. Hier landet eine fertige Spec, wenn du sie erstellst. |
+| **In Arbeit** | Die Pipeline arbeitet gerade daran (ein pulsierender blauer Punkt). |
+| **Fertig** | Von der Pipeline abgeschlossen (ein grünes Häkchen). |
+| **Abgebrochen** | Verworfen (ein rotes X). |
+
+Entwürfe liegen im selben aktiven Bereich wie To-do-Specs – es gibt keine eigene Spalte für sie –, tragen aber einen dezent eingefärbten Rand und ein `Draft`-Pill, sodass sie leicht zu erkennen sind. Die ganze Geschichte rund um Entwürfe findest du unter [Entwürfe & der Contract Layer](drafts-and-contract-layer.md).
+
+## Prioritäten
+
+Jede Spec, die kein Entwurf ist, hat eine Priorität: **Kritisch**, **Hoch**, **Mittel** oder **Niedrig**. Die Priorität ist rein ein Ordnungswerkzeug – sie hilft dir zu entscheiden, was du als Nächstes umsetzt, und erlaubt dir, das Board zu sortieren. Du legst sie beim Erstellen einer Spec fest und kannst sie jederzeit ändern, indem du mit der rechten Maustaste auf die Spec-Karte klickst und **Priorität festlegen** wählst.
+
+Entwürfe sind die einzige Ausnahme: Ein Entwurf darf *gar keine* Priorität haben, weil er noch eine Idee in Arbeit ist. Die Priorität wird festgelegt, sobald du den Entwurf in eine echte Spec überführst.
+
+## Eine Spec erstellen
+
+Um eine Spec zu erstellen, klicke auf **Hinzufügen** (die Plus-Schaltfläche in der SpecsBoard-Toolbar). Der Dialog **Spec hinzufügen** öffnet sich mit mehreren Arbeitsweisen:
+
+- **Quick-Modus** – du beschreibst, was du möchtest, und die KI schreibt die vollständige Spec in einem Rutsch. Siehe [Spec hinzufügen – Quick-Modus](add-spec-quick-mode.md).
+- **Explore-Modus** – du unterhältst dich mit der KI, und sie hilft dir, die Spec Zug um Zug zu formen. Siehe [Spec hinzufügen – Explore-Modus](add-spec-explore-mode.md).
+- **Raw-Modus** – was auch immer du eintippst, wird wortwörtlich als Spec gespeichert, ganz ohne KI. Nutze ihn, wenn du den Spec-Text bereits geschrieben hast.
+
+Welchen du wählst, hängt davon ab, wie klar die Idee schon ist. Du weißt genau, was du willst? Quick. Du tüftelst noch daran? Explore. Du hast den Text schon? Raw.
+
+## Wie es weitergeht
+
+- [Spec hinzufügen – Quick-Modus](add-spec-quick-mode.md) – der schnellste Weg, eine Idee in eine Spec zu verwandeln.
+- [Spec hinzufügen – Explore-Modus](add-spec-explore-mode.md) – eine Spec im Gespräch formen.
+- [Entwürfe & der Contract Layer](drafts-and-contract-layer.md) – Arbeit zwischenspeichern und Specs für die Pipeline anreichern.

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

@@ -0,0 +1,45 @@
+# Spec hinzufügen – Quick-Modus
+
+Der Quick-Modus ist für die Momente gedacht, in denen du bereits weißt, was du willst. Du tippst deine Idee ein, die KI schreibt die vollständige Spec, und sie landet als **To-do** auf deinem Board. Kein Hin und Her – einfach beschreiben und los.
+
+## Eine Spec im Quick-Modus erstellen
+
+So erstellst du schnell eine Spec:
+
+1. Klicke auf dem Dashboard auf **Hinzufügen** (die Plus-Schaltfläche in der SpecsBoard-Toolbar).
+2. Wähle den Modus **Quick**.
+3. Tippe deine Idee ins Textfeld – ein Satz oder ein Absatz, was immer sie auf den Punkt bringt.
+4. Klicke auf Generieren.
+
+Während die Spec geschrieben wird, zeigt ein kleiner Toast in der Ecke den Projektnamen, einen Ausschnitt deiner Idee und die **vergangene Zeit** („Wird generiert… 0:12"). Sobald es fertig ist, wechselt der Toast zu „Generiert in <Zeit>" mit einer Aktion **Anzeigen**, die direkt zu deiner neuen Spec springt.
+
+Das ist der ganze Ablauf. Alles Weitere unten ist optionale Feinjustierung.
+
+## Was du anpassen kannst
+
+**Modell** – standardmäßig wählt die KI ein sinnvolles Modell. Du kannst es pro Spec über die Modellauswahl überschreiben, wenn du ein schnelleres oder leistungsfähigeres möchtest.
+
+**Engine** – wenn in deinem Projekt mehr als ein KI-Provider installiert ist (irgendeine Mischung aus Claude, Codex und Gemini), sitzt oben im Dialog eine Engine-Auswahl, mit der du festlegst, welche diese Spec generiert. Deine Wahl wird pro Projekt gemerkt. Projekte mit nur einem Provider zeigen das nicht – es gibt ja nichts zu wählen.
+
+**Kontext** – der Quick-Modus läuft meist als einzelner Durchgang, weil er deine Codebasis nicht lesen muss, um aus deiner Beschreibung eine Spec zu schreiben. Aber ein Kontext-Schieberegler erlaubt dir, ihm mehr an die Hand zu geben:
+
+- In der niedrigsten Einstellung liest er nur deine Beschreibung.
+- In höheren Einstellungen kann er vor dem Schreiben deine vorhandenen Specs, die OpenSpec-Specs deines Projekts und sogar deine gesamte Codebasis lesen.
+
+Je mehr Kontext du ihm gibst, desto länger dauert die Generierung (er wechselt in den Mehrfach-Durchgang, um vorher lesen zu können), dafür kommt die Spec aber fest in deinem tatsächlichen Projekt verankert zurück. Greif zu höherem Kontext, wenn die Spec echten Code, Dateinamen oder bestehendes Verhalten referenzieren muss.
+
+**Anhänge** – zieh Mockups, Briefings oder Datendateien ins Ideenfeld. Die KI liest sie beim Schreiben der Spec mit. (Anhänge schalten die Generierung ebenfalls auf den Mehrfach-Durchgang um.)
+
+**Mit Contract Layer anreichern** – ein Schalter, der der generierten Spec einen strukturierten Block anhängt, damit die nachgelagerte Pipeline keine Namen oder Datenformen raten muss. Er ist optional und standardmäßig aus; deine letzte Wahl wird pro Projekt gemerkt. Was er hinzufügt und wann er sich lohnt, liest du unter [Entwürfe & der Contract Layer](drafts-and-contract-layer.md).
+
+## Wann Quick-Modus, wann Explore
+
+Nutze **Quick**, wenn die Idee in deinem Kopf schon klar ist – du könntest die Spec selbst schreiben, du lässt sie nur lieber von der KI verfassen. Nutze [**Explore**](add-spec-explore-mode.md), wenn du sie noch durchdenkst und einen Partner möchtest, der dir beim Formen hilft.
+
+Eine im Quick-Modus erstellte Spec ist eine ganz normale Spec: Du kannst sie später öffnen und in einer Explore-Session **weiter bearbeiten**, falls sie noch Feinschliff braucht.
+
+## Wie es weitergeht
+
+- [Spec hinzufügen – Explore-Modus](add-spec-explore-mode.md) – für Specs, die noch geformt werden müssen.
+- [Entwürfe & der Contract Layer](drafts-and-contract-layer.md) – die Contract-Layer-Anreicherung erklärt.
+- [Pipelines ausführen](running-pipelines.md) – zieh deine neue Spec auf eine Rail und setze sie um.