specrails-desktop 2.8.0 → 2.9.1

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

@@ -0,0 +1,49 @@
+# Was ist specrails
+
+Willkommen bei **specrails** – einer Desktop-App, die einen KI-Programmierassistenten in ein echtes Software-Team verwandelt, das an *deinen* Projekten arbeitet, auf *deinem* Rechner.
+
+Statt Prompts hin und her zu kopieren, beschreibst du als **Spec**, was du haben möchtest, und specrails schickt sie durch eine komplette Entwicklungs-Pipeline – Entwerfen, Bauen, Prüfen und Ausliefern der Änderung – und du schaust live dabei zu.
+
+## Spec-getriebene KI-Entwicklung
+
+Das Herzstück von specrails ist eine einfache Idee: **Der beste Weg zu gutem Code aus einer KI führt über eine klare Spec.**
+
+Eine *Spec* ist eine kurze, strukturierte Beschreibung einer einzelnen Aufgabe – ein Feature, ein Fix, ein Refactoring. Du schreibst sie in Sekunden oder formst sie in einem geführten Chat, der die richtigen Fragen stellt und sie für dich entwirft. Jede Spec wird zu einem **Ticket** auf deinem Projektboard, genau wie eine Aufgabe in jedem Issue-Tracker.
+
+Von dort aus übergibst du die Spec an die Pipeline und überlässt der KI die Schwerarbeit.
+
+## Die Pipeline: Architect → Developer → Reviewer → Ship
+
+Wenn du eine Spec startest, läuft sie bei specrails durch vier Phasen, jede gespielt von einem spezialisierten KI-Agenten:
+
+1. **Architect** – liest deine Spec und den umgebenden Code und plant dann die Änderung: welche Dateien anzufassen sind und wie die Lösung aussehen soll.
+2. **Developer** – schreibt den eigentlichen Code, gemäß dem Plan.
+3. **Reviewer** – prüft die Arbeit auf Korrektheit und Qualität und fängt Probleme ab, bevor du sie bemerkst.
+4. **Ship** – finalisiert die Änderung, sodass sie bereit zum Commit ist.
+
+Du siehst jede Phase, während sie läuft, mit Live-Logs direkt von der KI. Nichts bleibt verborgen – wenn etwas schiefläuft, siehst du genau, wo.
+
+## Projekte
+
+In specrails dreht sich alles um **Projekte**. Ein Projekt ist einfach ein Ordner auf deinem Computer, der eine Codebasis enthält. Du kannst beliebig viele Projekte hinzufügen und blitzschnell zwischen ihnen wechseln – jedes behält seine eigenen Specs, seine Job-Historie, seine Analytics und seine Einstellungen.
+
+specrails fasst niemals Code an, um den du nicht gebeten hast. Es arbeitet in deinem bestehenden Repository, und du behältst die Kontrolle darüber, was committet wird.
+
+## Wähle deinen KI-Provider
+
+specrails arbeitet mit den großen KI-Programmier-CLIs zusammen:
+
+- **Claude** (Claude Code)
+- **Codex** (Codex CLI)
+- **Gemini** (Gemini CLI)
+
+Nimm einfach den, den du ohnehin schon nutzt – oder installiere mehrere und wähle pro Aufgabe. Ein Projekt kann mit einem einzelnen Provider oder mit mehreren gleichzeitig laufen, sodass du dich nie festlegen musst.
+
+## Warum es dir gefallen wird
+
+- **Tempo ohne Chaos** – Specs halten die KI fokussiert, sodass du brauchbare Änderungen bekommst statt ausufernder Rätselraterei.
+- **Volle Transparenz** – Live-Logs, eine übersichtliche Pipeline-Ansicht und Analytics pro Projekt zeigen dir genau, was passiert ist und was es gekostet hat.
+- **Dein Rechner, dein Code** – alles läuft lokal gegen dein echtes Repository.
+- **Alles an einem Ort** – Specs, Jobs, Chat, ein integriertes Terminal und Kostenverfolgung, alles in einem einzigen Fenster.
+
+Bereit loszulegen? Als Nächstes: [Installation & erster Start](installing-and-first-run).

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

@@ -0,0 +1,42 @@
+# Installation & erster Start
+
+specrails auf deinen Rechner zu bekommen, dauert nur ein paar Minuten. Hier ist der gesamte Ablauf.
+
+## 1. Herunterladen und installieren
+
+Schnapp dir den Installer für deine Plattform:
+
+- **macOS (Apple Silicon)** – eine `.dmg`-Datei. Öffne sie und zieh **specrails** in deinen Programme-Ordner.
+- **Windows** – ein `.exe`-Setup-Installer. Führe ihn aus und folge den Anweisungen.
+
+> **Hinweis zu Sicherheitsmeldungen unter macOS und Windows**
+>
+> - Unter **Windows** ist der Installer noch nicht code-signiert, deshalb zeigt SmartScreen möglicherweise eine Warnung. Klicke auf **Weitere Informationen → Trotzdem ausführen**, um fortzufahren.
+> - Unter **macOS** ist die App signiert und notarisiert, sie sollte sich also problemlos öffnen.
+
+## 2. Was du brauchst (Voraussetzungen)
+
+specrails führt KI-Entwicklungs-Pipelines aus, indem es echte Kommandozeilen-Tools ansteuert – ein paar Dinge müssen also verfügbar sein. Die gute Nachricht: Die Desktop-App **bringt die meisten davon schon für dich mit** (Node.js, npm und Git stecken in der App), sodass auf einem frischen Rechner meist nichts zu installieren ist.
+
+Das Einzige, was specrails nicht mitbringen kann, ist die **KI-Provider-CLI** selbst. Du brauchst mindestens eine davon:
+
+- **Claude Code**
+- **Codex CLI**
+- **Gemini CLI**
+
+Installiere die, die du nutzen möchtest, melde dich einmal über dein Terminal an – fertig. specrails erkennt automatisch, welche Provider vorhanden sind.
+
+> Falls einmal ein Tool als fehlend markiert wird, zeigt die App einen **Weitere Informationen**-Link mit Installationsbefehlen zum Kopieren, passend zu deinem Betriebssystem (Homebrew unter macOS, winget unter Windows, apt/dnf unter Linux). Du kannst jederzeit erneut prüfen, ohne neu zu starten.
+
+## 3. Erster Start – der Willkommensbildschirm
+
+Wenn du specrails zum ersten Mal öffnest, landest du auf einem aufgeräumten **Willkommensbildschirm**. Es gibt noch keine Projekte, deshalb lädt dich die App ein, dein erstes hinzuzufügen.
+
+Du siehst:
+
+- Eine kurze Beschreibung dessen, was specrails leistet.
+- Eine einzelne Schaltfläche **Dein erstes Projekt hinzufügen**.
+
+Das ist das gesamte Onboarding – kein Konto anzulegen, keine Registrierung. specrails läuft komplett auf deinem Rechner.
+
+Klicke auf **Dein erstes Projekt hinzufügen** und weiter geht's mit [Dein erstes Projekt hinzufügen](adding-your-first-project).

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

@@ -0,0 +1,58 @@
+# Dein erstes Projekt hinzufügen
+
+Ein Projekt ist einfach ein Ordner auf deinem Computer, der eine Codebasis enthält. Verbinden wir eins.
+
+## Den Dialog „Projekt hinzufügen“ öffnen
+
+Klicke auf dem Willkommensbildschirm auf **Dein erstes Projekt hinzufügen** (oder später auf die Schaltfläche **Projekt hinzufügen** in der linken Seitenleiste). Ein kleiner Dialog erscheint.
+
+## Die Details ausfüllen
+
+**Projektordner** *(erforderlich)*
+
+Zeige specrails den Ordner, der deinen Code enthält. In der Desktop-App kannst du auf das Ordnersymbol klicken, um ihn visuell auszuwählen, oder den vollständigen Pfad einfügen. Das sollte das Wurzelverzeichnis deines Repositorys sein – der Ordner, der deinen Code und (üblicherweise) ein `.git`-Verzeichnis enthält.
+
+**Projektname** *(optional)*
+
+Ein freundliches Label, das in der Seitenleiste angezeigt wird. Lässt du es leer, verwendet specrails den Ordnernamen.
+
+**Provider**
+
+Wähle, welche KI-Provider dieses Projekt nutzen soll. specrails zeigt dir die, die es auf deinem Rechner gefunden hat:
+
+- 🤖 **Claude**
+- ⚡ **Codex**
+- ✨ **Gemini**
+
+Nicht gefundene Provider sind ausgegraut und als *nicht gefunden* markiert – installiere einen, melde dich an und öffne den Dialog dann erneut. Standardmäßig ist jeder verfügbare Provider vorausgewählt, du kannst die Auswahl aber auf genau den reduzieren, den du möchtest. Wählst du mehr als einen, wird der **erste** zum Standard des Projekts; pro Aufgabe kannst du später trotzdem wählen.
+
+> Im Hintergrund läuft eine schnelle Prüfung, um sicherzustellen, dass die benötigten Tools vorhanden sind. Fehlt etwas Wesentliches, bleibt die **Hinzufügen**-Schaltfläche deaktiviert, und ein **Weitere Informationen**-Link liefert dir die genauen Installationsbefehle.
+
+Klicke auf **Hinzufügen**, um fortzufahren.
+
+## Setup, das in Sekunden läuft
+
+Ist der Ordner bereits für specrails konfiguriert, bist du fertig – das Projekt erscheint sofort in deiner Seitenleiste.
+
+Handelt es sich um ein frisches Projekt, läuft ein kurzer **Einrichtungsassistent**. Er hat drei Schritte:
+
+1. **Konfigurieren** – bestätige die Grundlagen für jeden Provider, den du ausgewählt hast.
+2. **Installieren** – specrails richtet das Projekt automatisch ein. Das ist die *schnelle* Installation: einsatzbereite Vorlagen-Agenten, die in Sekunden bereitstehen. Du siehst dabei ein Live-Log.
+3. **Fertig** – eine Zusammenfassung, die bestätigt, dass alles bereit ist.
+
+Bei einem Projekt mit mehreren Providern läuft die Installation einmal pro Provider, nacheinander, und der Schritt „Fertig“ zeigt für jeden eine eigene Karte.
+
+## Was installiert wird
+
+Das Setup ist bewusst schlank und **nicht-invasiv**. specrails fügt deinem Projekt eine kleine Menge Konfiguration hinzu, damit die Pipeline weiß, wie sie laufen soll:
+
+- Einen `.specrails/`-Ordner, der die Agent-Profile und lokalen Einstellungen deines Projekts enthält.
+- Agent-Definitionen unter `.claude/agents/`, die die Pipeline Architect → Developer → Reviewer → Ship antreiben.
+
+Mehr nicht – specrails schreibt deinen Quellcode beim Setup nicht um, und diese Dateien lassen sich problemlos committen, wenn du die Konfiguration mit deinem Team teilen möchtest.
+
+> **Lieber das tiefgehende Setup?** Die App liefert bewusst die schnelle Vorlagen-Installation. Wenn du den KI-angereicherten Ablauf bevorzugst (Codebasis-Analyse und individuelle Agent-Personas), kannst du `npx specrails-core@latest init` aus deinem Projektordner in einem Terminal ausführen.
+
+## Du bist drin
+
+Sobald das Setup abgeschlossen ist, setzt specrails dich direkt ins Dashboard deines Projekts. Zeit für die Tour – siehe [Die Dashboard-Tour](the-dashboard-tour).

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

@@ -0,0 +1,53 @@
+# Die Dashboard-Tour
+
+Mit einem hinzugefügten Projekt blickst du nun auf dein **Projekt-Dashboard** – deine Basis, um Specs in ausgelieferten Code zu verwandeln. So findest du dich zurecht.
+
+## Das große Ganze
+
+Das Fenster hat drei Bereiche:
+
+- **Linke Seitenleiste** – deine Projektliste. Klicke auf ein beliebiges Projekt, um sofort dorthin zu wechseln; alles andere im Fenster passt sich an. Auch die Schaltfläche **Projekt hinzufügen** ist hier zu Hause.
+- **Hauptbereich** – das Dashboard des aktiven Projekts: deine Specs und die Pipeline, die sie ausführt.
+- **Rechte Seitenleiste** – Navigation zwischen den Abschnitten des aktuellen Projekts.
+
+## Das Haupt-Dashboard
+
+Hier passiert die Arbeit. Das Dashboard zeigt:
+
+- **Deine Specs** – die Tickets, die du erstellt hast, nach Status sortiert (Backlog/To-do bis Fertig). Du kannst sie als Liste, als Raster oder als Haftnotiz-Karten anzeigen, ganz wie du magst.
+- **Eine Möglichkeit, eine Spec hinzuzufügen** – starte eine neue Aufgabe. Du kannst direkt eine schnelle Spec schreiben oder einen geführten **Explore**-Chat öffnen, der dir hilft, sie im Gespräch zu formen und das Ticket für dich zu entwerfen.
+- **Rails** – das sind die Spuren, auf denen Specs gebaut werden. Lege eine Spec auf ein Rail und starte sie, um sie durch die Pipeline Architect → Developer → Reviewer → Ship zu schicken. Mehrere Rails können gleichzeitig laufen, sodass du an mehreren Dingen parallel arbeiten kannst.
+
+Während eine Spec läuft, siehst du ihren Pipeline-Fortschritt und Live-Logs – die Echtzeit-Ausgabe der KI, während sie deine Änderung entwirft, programmiert und prüft.
+
+## Die rechte Seitenleiste: Projektabschnitte
+
+Die rechte Seitenleiste ist deine Schaltzentrale für das aktuelle Projekt. Fahre mit der Maus darüber, um sie auszuklappen, oder pinne sie offen an. Diese Abschnitte findest du:
+
+- **Dashboard** – das Specs-Board und die Rails (wo du gerade warst).
+- **Jobs** – jeder Pipeline-Lauf dieses Projekts, vergangen und aktuell, mit Status, Dauer und der Möglichkeit, in die Details und Logs jedes Laufs einzutauchen.
+- **Analytics** – was deine KI-Nutzung kostet. Ausgaben aufgeschlüsselt nach Tag, nach Aktivität, nach Modell und nach Ticket – damit es keine Überraschungen gibt.
+- **Agenten** – die Agent-Profile deines Projekts: welche Agenten in der Pipeline laufen und welche KI-Modelle sie nutzen. *(Nur bei Claude-betriebenen Projekten.)*
+- **Code** – ein schreibgeschützter Datei-Browser mit KI-Zusammenfassungen in einfacher Sprache und Chips, die zeigen, welche Dateien die KI angefasst hat. Ideal für Nicht-Entwickler, die mitverfolgen möchten.
+- **Integrationen** – optionale Erweiterungen, etwa das Verbinden deiner Specs mit einem **Jira**-Board oder das Aktivieren zusätzlicher Werkzeuge für die KI.
+- **Einstellungen** – projektspezifische Optionen (Telemetrie, Budgets, Provider-Konfiguration und mehr).
+
+> Manche Abschnitte erscheinen nur, wenn sie für die gewählten Provider sinnvoll sind – zum Beispiel ist **Agenten** spezifisch für Claude. Siehst du einen Abschnitt nicht, gilt er für das Setup dieses Projekts schlicht nicht.
+
+## Die Statusleiste
+
+Ein schmaler Streifen verläuft ganz unten am Fenster. Klein, aber praktisch:
+
+- **Verbindungsanzeige** (links) – ein farbiger Punkt mit Beschriftung, der zeigt, dass die App aktiv ist: Grün für *verbunden*, Bernstein während des *Neuverbindens*, Blau während des *Synchronisierens* direkt nach einer erneuten Verbindung. Du wirst sie selten brauchen, aber wenn doch, beruhigt sie.
+- **Gesamtausgaben** (rechts) – eine laufende Summe dessen, was du ausgegeben hast, sodass die Kosten immer nur einen Blick entfernt sind.
+- **Terminal-Umschalter** (ganz rechts) – öffnet das integrierte Terminal-Panel. Drücke **Cmd+J** (macOS) oder **Ctrl+J** (Windows/Linux), um es jederzeit ein- oder auszublenden. Es ist eine vollwertige Shell, direkt in deinem Projektordner geöffnet.
+
+## Ein paar praktische Tastenkürzel
+
+- **Cmd/Ctrl+B** – Seitenleisten anpinnen oder einklappen.
+- **Cmd/Ctrl+J** – Terminal-Panel ein-/ausblenden.
+- **Cmd/Ctrl+K** – Suche öffnen.
+
+## Wie es weitergeht
+
+Das war die grobe Übersicht. Von hier aus ist der natürliche erste Schritt, eine **Spec hinzuzufügen** und sie auf einem Rail zu starten – schau der Pipeline von Anfang bis Ende zu und prüfe dann unter **Analytics**, was sie gekostet hat. Willkommen an Bord.

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

@@ -0,0 +1,78 @@
+# Analytics & Kostenverfolgung
+
+Jedes Mal, wenn Specrails in deinem Auftrag eine KI-CLI ausführt – einen Pipeline-Job, eine Quick-Spec, eine Explore-Sitzung, eine KI-Bearbeitung, eine Dateizusammenfassung – wird festgehalten, was passiert ist: welches Modell gelaufen ist, wie viele Tokens hinein- und hinausgingen, wie lange es gedauert hat und was es gekostet hat. Der Bereich **Analytics** verwandelt all das in ein einziges Dashboard, damit du immer weißt, wohin deine KI-Ausgaben fließen.
+
+Du öffnest ihn über die rechte Seitenleiste (Beschriftung **Analytics**). Alles, was du siehst, bezieht sich auf das Projekt, in dem du dich gerade befindest – wechselst du das Projekt, ziehen die Zahlen mit.
+
+## Was als Ausgabe zählt
+
+Specrails verfolgt fünf Arten von KI-Aktivität, sogenannte *Surfaces*. Jede ist in allen Diagrammen einheitlich farblich gekennzeichnet, damit du sie auf einen Blick erkennst:
+
+- **Job** – ein Pipeline-Rail, das Architect → Developer → Reviewer → Ship durchläuft.
+- **Quick-Spec** – eine Spec, die über den schnellen „Spec hinzufügen“-Weg erstellt wurde.
+- **Explore-Spec** – eine Explore-Unterhaltung, in der du eine Spec im Gespräch ausarbeitest.
+- **KI-Bearbeitung** – eine KI-gestützte Verfeinerung an einem Agenten oder einer Datei.
+- **Dateizusammenfassung** – die verständlichen Zusammenfassungen, die den Code-Explorer speisen.
+
+Ein paar Dinge werden bewusst *nicht* verfolgt: Sowohl die Chat-Seitenleiste als auch der Einrichtungsassistent starten KI-CLIs, tauchen aber nie in deinen Ausgaben auf. So spiegelt das Dashboard echte, wiederholbare Arbeit wider statt beiläufigem Geplauder.
+
+## Das Dashboard lesen
+
+Die Seite besteht aus einer Handvoll Blöcke, von oben nach unten:
+
+### Der Burn-Meter (Hero)
+
+Die große Zahl ganz oben sind deine Gesamtausgaben für den gewählten Zeitraum, mit einem **ggü. Vorperiode**-Delta, an dem du auf einen Blick ablesen kannst, ob du im Vergleich zum vorherigen Fenster nach oben oder unten tendierst. Wenn du ein Projekt gerade erst nutzt, verrät dir der Leerzustand, wann das Tracking begonnen hat („Tracking gestartet am JJJJ-MM-TT“) – es gibt keine rückwirkende Erfassung, der Meter kennt also nur Läufe, die während dieser Version stattgefunden haben.
+
+### Täglicher Verlauf
+
+Ein gestapeltes Balkendiagramm der Ausgaben pro Tag, aufgeschlüsselt nach Surface. Tage ohne Aktivität werden als Null angezeigt und nicht übersprungen, damit das Bild deiner Woche ehrlich bleibt. Das ist der schnellste Weg, um zu sehen, *wann* ein teurer Durchlauf stattgefunden hat.
+
+### Quick vs. Explore
+
+Eine Vergleichskarte, die deine beiden Stile der Spec-Erstellung nebeneinanderstellt. Wenn du weniger als fünf Explore-Sitzungen durchgeführt hast, zeigt sie statt irreführender Durchschnittswerte einen sanften Handlungshinweis – kleine Stichproben taugen nicht für verlässliche Vergleiche.
+
+### Nach Modell
+
+Deine teuersten Modelle nach Ausgaben (bis zu zehn). Klicke auf ein beliebiges Modell, um das gesamte Dashboard auf genau dieses Modell zu filtern – praktisch, wenn du wissen willst, was ein bestimmtes High-End-Modell wirklich kostet.
+
+### Streudiagramm Kosten vs. Runden
+
+Jeder Punkt steht für einen Aufruf und trägt die Kosten gegen die Anzahl der Runden auf. Ausreißer – die teuren Läufe mit vielen Runden – springen sofort ins Auge. (Das Streudiagramm zeigt deine 500 jüngsten Punkte, damit es reaktionsschnell bleibt.)
+
+### Top-Tickets
+
+Deine zehn teuersten Tickets über *alle* Surfaces hinweg zusammengefasst, sodass ein Ticket, das in Explore wenig und in einem Job viel gekostet hat, seine wahre Gesamtsumme zeigt. Gelöschte Tickets und nicht zugeordnete Läufe bekommen eigene Sammelposten, damit nichts stillschweigend aus den Summen verschwindet.
+
+### Tabelle der Rohaufrufe
+
+Die nackte Wahrheit: eine Zeile pro Aufruf. Dieser Block hat eigene Sekundärfilter, die nur die Tabelle betreffen, sodass du ins Detail gehen kannst, ohne die Diagramme darüber zu stören.
+
+## Filtern
+
+Die fixierte Kopfzeile ganz oben trägt die beiden Hauptfilter – **Zeitraum** und **Surface** – und beide werden in der Seiten-URL gespeichert. Das heißt, du kannst eine gefilterte Ansicht („letzte 30 Tage, nur Jobs“) als Lesezeichen speichern oder teilen, und sie öffnet sich wieder genau so, wie du sie verlassen hast. Die Filter der Rohtabelle sind davon getrennt und bleiben lokal in diesem Block.
+
+Eine Anmerkung zur Genauigkeit: Fehlgeschlagene und abgebrochene Läufe bleiben aus den *Kostendurchschnitten* heraus (sie würden die Werte pro Lauf verzerren), zählen aber weiterhin in deine Gesamtzahl der Läufe und deine Fehlerquote ein. So bleiben die Durchschnitte sauber, während das Bild der Zuverlässigkeit vollständig bleibt.
+
+## Kosten pro Ticket
+
+Du musst nicht zur Analytics-Seite kommen, um zu sehen, was eine Spec gekostet hat. Öffne ein beliebiges Ticket, und wenn ihm Ausgaben zugeordnet sind, siehst du direkt unter dem Titel eine einzeilige Zusammenfassung:
+
+> $0.42 · 6 Runden · 1m 12s aktiv · Aufschlüsselung
+
+Klicke darauf und du landest auf der Analytics-Seite, bereits auf dieses Ticket gefiltert. Das ist der schnellste Weg von „Was hat mich dieses Feature gekostet?“ zur vollständigen Aufschlüsselung.
+
+## Daten exportieren
+
+Wenn du die Zahlen außerhalb der App brauchst – eine Tabelle, einen Finanzbericht, deine eigene Auswertung – nutze das Dropdown **Export**. Es bietet vier Formate:
+
+- **Zusammenfassung CSV** – eine Datei aus mehreren Abschnitten mit Summen, dem täglichen Verlauf, nach Surface, nach Modell und Top-Tickets.
+- **Zusammenfassung JSON** – dieselbe Zusammenfassung, strukturiert.
+- **Rohdaten CSV** – jede Aufrufzeile (bis zu 10.000; es wird vermerkt, falls gekürzt werden musste).
+- **Rohdaten JSON** – dieselben Rohzeilen, strukturiert.
+
+Exporte berücksichtigen die aktuell angewendeten Zeitraum- und Surface-Filter, und die Dateien sind so benannt, dass sie sich sinnvoll sortieren lassen: `<project>-analytics-<period>-<date>.csv`. Die Schaltfläche ist deaktiviert, wenn es nichts zu exportieren gibt, und du erhältst eine klare Fehlermeldung als Toast, falls ein Download fehlschlägt.
+
+## Immer live
+
+Du musst nicht neu laden. Sobald irgendwo im Projekt ein neuer Aufruf erfasst wird, lädt sich das geöffnete Dashboard kurz darauf still neu, sodass der Burn-Meter mit der Arbeit Schritt hält, während sie fertig wird.

package/docs/guide/de/insights/2-the-integrated-terminal.md

@@ -0,0 +1,46 @@
+# Das integrierte Terminal
+
+Specrails hat ein echtes Terminal direkt eingebaut – das Panel, das vom unteren Rand des Fensters nach oben fährt, genau wie in VS Code oder Cursor. Es führt deine tatsächliche Shell in deinem tatsächlichen Projektverzeichnis aus, sodass du `git`, `npm`, Tests oder alles andere ausführen kannst, ohne die App zu verlassen.
+
+## Öffnen und schließen
+
+Am schnellsten geht es über die Tastatur: **Cmd+J** (macOS) bzw. **Ctrl+J** (Windows/Linux) öffnet und schließt das Panel und fokussiert das Terminal in dem Moment, in dem es erscheint, sodass du sofort lostippen kannst. Du kannst auch das Chevron in der Statusleiste verwenden.
+
+Das Panel hat drei Zustände:
+
+- **Ausgeblendet** – weggeräumt.
+- **Wiederhergestellt** – das normale Panel in geteilter Höhe.
+- **Maximiert** – übernimmt den Arbeitsbereich, wenn du Platz brauchst, um Ausgaben zu lesen.
+
+Das Minimieren des Panels (über das Chevron) beendet **nichts** – deine Shells laufen im Hintergrund weiter. Das Einzige, was eine Sitzung wirklich beendet, ist das Schließen (das Papierkorb-Symbol oder das ✕ pro Tab).
+
+## Mehrere Sitzungen
+
+Du kannst im selben Projekt mehrere Terminals gleichzeitig laufen lassen – bis zu zehn. Jedes bekommt seinen eigenen Tab; du kannst sie umbenennen, damit „Dev-Server“ und „Tests“ nicht durcheinandergeraten. Sie starten alle in deinem Projektordner und laden dein Shell-Profil (`.zshrc`, `.bashrc` und so weiter), sodass deine Aliase und dein PATH genau das sind, was du erwartest.
+
+Und jetzt der wichtige Teil: Deine Terminals **überstehen den Wechsel von Projekten und Tabs**. Specrails hält jede Sitzung im Hintergrund am Leben und intakt – Scrollback, laufende Prozesse, einfach alles –, sodass ein Abstecher zu Analytics und zurück deine Shell nicht zurücksetzt oder einen lang laufenden Befehl unterbricht. Sitzungen enden nur, wenn du sie ausdrücklich schließt (oder wenn du das gesamte Projekt entfernst).
+
+## Pro Projekt, gemerkt
+
+Ob das Panel geöffnet ist, wie hoch du es gezogen hast, welche Tabs existieren – all das wird **pro Projekt** gemerkt. Kehrst du zu einem Projekt zurück, ist es so eingerichtet, wie du es verlassen hast.
+
+## Die Premium-Funktionen
+
+Das ist keine Konsole von der Stange. Das Terminal bringt die Annehmlichkeiten mit, die du von einem erstklassigen Terminal erwartest:
+
+- **Schnelles, gestochen scharfes Rendering** dank WebGL (mit automatischem Fallback, damit es nie kaputtgeht), vollständiger Unicode-Breitenbehandlung und Schrift-Ligaturen.
+- **Durchsuche deinen Scrollback** mit **Cmd+F** – ideal, um den Fehler zu finden, der 500 Zeilen weiter oben vergraben liegt.
+- **Schrift-Zoom** mit **Cmd+=**, **Cmd+-** und **Cmd+0** zum Zurücksetzen.
+- **Zwischenablage-Kürzel** – Cmd+C / Cmd+V zum Kopieren und Einfügen, Cmd+K zum Leeren – plus ein Kontextmenü per Rechtsklick.
+- **Dateipfade per Drag-and-drop** (in der Desktop-App): Ziehe eine Datei auf das Terminal, und ihr Pfad wird eingefügt – korrekt für deine Shell maskiert.
+- **Sanftes Anpassen der Größe** – das Ziehen der Panel-Höhe oder das Einklappen der Seitenleiste lässt die Ausgabe nicht ruckeln.
+- **Inline-Bilder** – Terminals, die Bilder im Sixel- oder iTerm2-Stil ausgeben, stellen sie direkt an Ort und Stelle dar.
+- **Shell-Integration** – Specrails weiß, wo jeder Befehl beginnt und endet, kann also deinen Befehlsverlauf nachverfolgen und dich benachrichtigen, wenn ein lang laufender Befehl fertig ist (eine Desktop-Benachrichtigung, mit Browser-Fallback). Falls deine Shell aus irgendeinem Grund nicht instrumentiert werden kann, läuft alles leise weiter und du wirst einmal darauf hingewiesen.
+
+## Einstellungen
+
+Terminal-Einstellungen liegen auf zwei Ebenen: einer app-weiten Voreinstellung und einer optionalen projektspezifischen Überschreibung. Die projektspezifische Einstellung gewinnt, wenn sie vorhanden ist, sodass du ein globales Erscheinungsbild beibehalten und gleichzeitig ein einzelnes Projekt anpassen kannst, das etwas anderes braucht.
+
+## Ausschalten
+
+Das Terminal ist standardmäßig aktiviert. Wenn du es lieber nicht haben möchtest, kannst du es über die Flags `VITE_FEATURE_TERMINAL_PANEL` (Client) oder `SPECRAILS_TERMINAL_PANEL` (Server) deaktivieren – setze eines der beiden auf `false`. Die meisten lassen es einfach an.

package/docs/guide/de/insights/3-code-explorer.md

@@ -0,0 +1,50 @@
+# Code-Explorer
+
+Der Bereich **Code** bietet dir ein freundliches, schreibgeschütztes Fenster in dein Repository – besonders gedacht für alle, die verstehen möchten, was die KI gebaut hat, ohne ständig in einem Editor zu leben. Links siehst du einen Dateibaum, rechts einen Code-Viewer und über dem Code eine verständliche Zusammenfassung dessen, was jede Datei tatsächlich tut.
+
+In dieser Version ist alles strikt schreibgeschützt: Nichts, was du hier tust, verändert deine Dateien. Stell dir das eher als Lesesaal vor, nicht als Werkstatt.
+
+Du öffnest ihn über die rechte Seitenleiste (**Code**), und wie alles andere bezieht er sich auf dein aktuelles Projekt.
+
+## Der Dateibaum
+
+Der linke Bereich ist ein virtualisierter Baum der Dateien deines Projekts – schnell selbst bei großen Repos. Er respektiert deine `.gitignore` sowie eine eingebaute Sperrliste, sodass du die Dateien siehst, die zählen, und nicht ein Meer aus Build-Artefakten und `node_modules`.
+
+Neben Dateien fallen dir **Herkunfts-Chips** auf – kleine Markierungen, die dir sagen, dass eine Datei *von der KI bearbeitet* wurde. Das ist das Herzstück des Code-Explorers: Specrails hält fest, welche Dateien jeder Pipeline-Job erstellt oder verändert hat, und verknüpft sie mit dem Ticket, das die Arbeit ausgelöst hat. So kannst du auf einen Blick die Frage beantworten: „Hat die KI das geschrieben oder ich?“
+
+Oben im Baum gibt es einen Filter:
+
+- **Tocado por IA / Von KI bearbeitet** (die Voreinstellung) – nur Dateien, die die KI verändert hat.
+- **Alle Dateien** – der vollständige Baum.
+
+Deine Auswahl wird pro Projekt gemerkt, sodass du, wenn dir vor allem KI-erstellte Änderungen wichtig sind, sie jedes Mal zuerst zu sehen bekommst.
+
+## Der Code-Viewer
+
+Klicke auf eine Datei und sie öffnet sich in einem voll ausgestatteten Viewer (angetrieben von Monaco, derselben Engine wie VS Code) mit ordentlichem Syntax-Highlighting, das zu deinem gewählten App-Theme passt. Ein paar sinnvolle Grenzen halten alles flüssig: Binärdateien werden höflich abgelehnt, und sehr große Dateien (über 2 MB) werden nicht geladen.
+
+Deine aktuelle Datei wird in der Seiten-URL gespeichert, sodass du einen Link direkt zu einer bestimmten Datei als Lesezeichen speichern oder teilen kannst.
+
+Da das Bearbeiten in dieser Version nicht vorgesehen ist, bietet der Viewer eine Schaltfläche **In externem Editor öffnen**, die den absoluten Pfad der Datei kopiert – füge ihn in deinen bevorzugten Editor ein und mach dort weiter.
+
+## KI-Zusammenfassungen
+
+Über dem Code siehst du eine **verständliche Zusammenfassung** der Datei – wofür sie da ist, was sie tut – so geschrieben, dass auch Nicht-Entwickler folgen können. Diese werden für dich generiert und zwischengespeichert, sodass das Öffnen einer Datei, die du schon einmal angesehen hast, sofort geht.
+
+Die Zusammenfassungen sind klug, was die Aktualität angeht: Sie sind an den Inhalt der Datei gebunden, sodass eine Zusammenfassung neu generiert wird, wenn sich eine Datei wirklich ändert, unveränderte Dateien aber nicht unnötig erneut zusammengefasst werden. Wenn du eine Datei selbst bearbeitest, wird ihre Zusammenfassung als veraltet markiert statt stillschweigend neu generiert – du behältst die Kontrolle darüber, wann sie aktualisiert wird. Es gibt eine Aktion **Neu generieren**, wenn du bei Bedarf eine frische Einschätzung möchtest.
+
+Ein paar Leitplanken halten die Kosten im Rahmen: Die Generierung von Zusammenfassungen läuft innerhalb eines **monatlichen Budgets** (standardmäßig ein paar Dollar, in den Einstellungen konfigurierbar), und es gibt Obergrenzen dafür, wie viele Zusammenfassungen ein einzelner Job anstoßen darf. Wird eine Zusammenfassung übersprungen, sagt dir die App, warum – Budget erreicht, eine Obergrenze pro Job oder die Datei wurde schlicht nicht gefunden.
+
+Du kannst außerdem die **Sprache der Zusammenfassungen** (Englisch oder Spanisch) in den globalen Einstellungen im Bereich *Code* wählen.
+
+## Code zurück mit Specs verbinden
+
+Die Herkunftsverknüpfung funktioniert in beide Richtungen. Innerhalb des Code-Explorers öffnet ein Klick auf den Ticket-Chip einer Datei die Detailansicht dieses Tickets. Und aus der anderen Richtung hat die **Ticket-Detailansicht** einen Abschnitt *Von diesem Ticket bearbeitete Dateien* – klicke dort auf eine Datei und du springst direkt in den Code-Explorer, mit der Datei geöffnet. Das schließt den Kreis zwischen „hier ist die Spec, die wir geschrieben haben“ und „hier ist der Code, der dabei herausgekommen ist“.
+
+## Was er (noch) nicht kann
+
+Um die Erwartungen klar zu setzen: Diese erste Version lässt absichtlich ein paar Dinge weg: das Bearbeiten in der App, Zusammenfassungen pro Symbol oder pro Verzeichnis, eine erzählende Diff-Ansicht und das dialogorientierte „Frag die KI zu dieser Datei“. Die Herkunft ordnet eine Datei nur ihrem primären Ticket zu. Das sind die Art von Dingen, die mit der Zeit wachsen könnten.
+
+## Ausschalten
+
+Der Code-Explorer ist standardmäßig aktiviert. Er lässt sich über die Flags `VITE_FEATURE_CODE_EXPLORER` (Client) oder `SPECRAILS_CODE_EXPLORER` (Server) deaktivieren – setze eines der beiden auf `false`. Beim Ausschalten bleiben alle erfassten Daten und Zusammenfassungen sicher und unangetastet auf der Festplatte, falls du ihn wieder einschaltest.

package/docs/guide/de/integrations/1-ai-providers.md

@@ -0,0 +1,64 @@
+# KI-Anbieter (Claude, Codex, Gemini)
+
+Specrails ist nicht an eine einzige KI gebunden. Jeder Teil der App, der mit einer KI spricht — Explore Spec, Quick-Spec, Rails, Chat, AI Edit, der „Open AI CLI“-Button im Terminal — kann über einen von drei vollwertigen Anbietern laufen. Du legst fest, welche ein Projekt verwendet, und kannst sogar pro Aufgabe umschalten.
+
+## Die drei Anbieter
+
+| Anbieter | CLI | Hersteller | Hinweise |
+|---|---|---|---|
+| **Claude** | `claude` | Anthropic | Der mit Abstand umfangreichste. Der einzige Anbieter für Agents (Profile), Ultracode-Rails und Contract Refine. |
+| **Codex** | `codex` | OpenAI | Benötigt codex `0.128.0+`. Liest seine MCP-Server aus deiner globalen `~/.codex/config.toml`. |
+| **Gemini** | `gemini` | Google | Benötigt gemini `0.11.0+`. Nutzt native Telemetrie und eine `GEMINI.md`-Instruktionsdatei. |
+
+Alle drei sind **standardmäßig aktiviert**. Ein Anbieter taucht in **Projekt hinzufügen** auf, sobald seine CLI installiert ist und in deinem `PATH` liegt. Der erste Schritt ist also immer derselbe: Installiere die gewünschte CLI und melde dich damit an — genau so, wie es in der jeweiligen Dokumentation des Tools beschrieben ist. Sobald `claude --version` (oder `codex` bzw. `gemini`) in deinem Terminal funktioniert, kann Specrails es nutzen.
+
+## Einen Anbieter für ein Projekt installieren
+
+Wenn du ein Projekt hinzufügst, fragt dich der Einrichtungsassistent, welche(n) Anbieter du installieren möchtest. Wähle einen aus, klicke dich durch den Installationsschritt — fertig. Ab da *hat* das Projekt diesen Anbieter einfach, und du musst nie wieder darüber nachdenken. Specs, Rails, Chat und Analytics funktionieren gleich, egal für welchen du dich entschieden hast.
+
+Falls eine gewünschte CLI in „Projekt hinzufügen“ nicht angeboten wird, liegt das fast immer daran, dass die CLI nicht installiert ist oder nicht in deinem `PATH` liegt. Installiere sie und öffne „Projekt hinzufügen“ erneut.
+
+## Mehrere Anbieter für ein Projekt installieren
+
+Du kannst **mehr als einen** Anbieter in dasselbe Projekt installieren — zum Beispiel Claude *und* Gemini. In **Projekt hinzufügen** wird die Anbieterliste zu einer Reihe von Checkboxen; hake alles an, was du möchtest. Der erste, den du auswählst, wird zum **primären** (Standard-)Anbieter des Projekts; die übrigen stehen als Alternativen bereit.
+
+Ein paar Dinge, die du über Multi-Anbieter-Projekte wissen solltest:
+
+- **Ein einzelner Anbieter verhält sich genau wie zuvor.** Hat ein Projekt nur einen einzigen Anbieter, siehst du nirgendwo eine Anbieterauswahl — die App bleibt schlank und einfach.
+- **Die rechte Seitenleiste zeigt nur Bereiche, die jeder installierte Anbieter unterstützt.** Da Agents (Profile) ein reines Claude-Konzept ist, verschwindet der Bereich **Agents** in dem Moment, in dem ein Projekt einen Nicht-Claude-Anbieter enthält. Alles andere (Specs, Code, Analytics, Integrationen, Terminal, Chat) bleibt erhalten.
+- **Die Anbieterwahl ist nach dem Anlegen festgelegt.** In dieser Version wählst du deine Anbieter beim Hinzufügen des Projekts, und sie lassen sich später nicht mehr über die Einstellungen ändern. Brauchst du eine andere Kombination, ist das ein neues Projekt.
+
+## Pro Aufruf einen Anbieter wählen
+
+Der eigentliche Gewinn eines Multi-Anbieter-Projekts liegt darin, für jede Aufgabe die richtige KI zu wählen — ohne irgendeine globale Einstellung zu ändern. Überall dort, wo eine KI läuft, erscheint eine kleine Anbieterauswahl (nur, wenn das Projekt mehr als einen Anbieter hat):
+
+- **Spec hinzufügen** — über die Engine-Auswahl kannst du eine Spec mit dem Anbieter deiner Wahl per Explore oder Quick erzeugen.
+- **Rail-Kopf** — wähle die Engine für genau diese Rail, bevor du sie startest.
+- **Terminal** — der „Open AI CLI“-Button (Sparkles) öffnet ein Anbietermenü, über das du in jede installierte CLI im Verzeichnis dieses Projekts springen kannst.
+
+Deine Wahl wird pro Projekt gemerkt und fällt standardmäßig auf den primären Anbieter zurück — du musst also nicht jedes Mal neu wählen.
+
+## Was nur Claude kann
+
+Eine Handvoll Funktionen sind ihrer Natur nach Claude-spezifisch und werden daher ausgeblendet oder übersprungen, wenn ein anderer Anbieter im Spiel ist:
+
+- **Agents (Profile)** — der projektbezogene Agenten-Katalog und das Modell-Routing. Auf jedem Projekt ausgeblendet, das einen Nicht-Claude-Anbieter enthält.
+- **Ultracode-Rails** — laufen immer auf Claude.
+- **Contract Refine** — der zusätzliche „Contract Layer“-Durchlauf auf einer committeten Spec läuft nur, wenn der Anbieter der Konversation Claude ist.
+- **Erweiterte Modi bei „Spec hinzufügen“** (SMASH / Contract Layer) — bei Nicht-Claude-Engines ausgeblendet.
+
+Alles andere — Explore, Quick-Spec, die vollständige Rails-Pipeline, AI Edit, Chat, Kosten-Analytics — funktioniert über alle drei hinweg.
+
+## Kostenverfolgung über alle Anbieter hinweg
+
+Die **Analytics**-Seite erfasst jeden abrechenbaren Aufruf unabhängig vom Anbieter. Auf Multi-Anbieter-Projekten ergänzt sie Engine-Filter-Chips, mit denen du die Ausgaben pro Anbieter vergleichen kannst. Claude meldet seine eigenen exakten Kosten; für Codex und Gemini schätzt Specrails die Kosten anhand einer eingebauten Preistabelle — die Zahlen sind also gute Näherungswerte, keine tatsächlich abgerechneten Beträge.
+
+## Fehlerbehebung
+
+- **Ein installierter Anbieter wird nicht angeboten.** Stelle sicher, dass die CLI in deinem `PATH` liegt (probiere `claude --version` / `codex --version` / `gemini --version` in einem frischen Terminal). Die App prüft Anbieter-CLIs über deinen System-`PATH`.
+- **Codex-MCP-Server werden im Chat nicht geladen.** Codex liest MCP-Server aus deiner globalen `~/.codex/config.toml` — registriere sie dort mit `codex mcp add`.
+- **Notabschaltung.** Ein Anbieter lässt sich app-weit über eine Umgebungsvariable abschalten (`SPECRAILS_CODEX_BETA=0` oder `SPECRAILS_GEMINI_BETA=0`). Das blendet den Anbieter nur aus der *Auswahl* aus; es wird selten gebraucht.
+
+## Siehe auch
+
+Die dedizierten Anbieter-Guides gehen tiefer auf jede CLI ein: Der Codex-Guide und der Gemini-Guide behandeln jeweils Einrichtung, Funktionsumfang und anbieterspezifische Besonderheiten.

package/docs/guide/de/integrations/2-plugins.md

@@ -0,0 +1,44 @@
+# Plugins (Integrationen)
+
+Der Bereich **Integrationen** ist ein projektbezogener Marktplatz für optionale Erweiterungen, die den Funktionsumfang der KI ausbauen. Jedes Projekt entscheidet eigenständig, welche Plugins es haben möchte — ein Plugin in einem Projekt zu installieren, berührt nie ein anderes.
+
+Plugins funktionieren, indem sie unauffällig einen **MCP-Server** (Model Context Protocol) in deinem Projekt registrieren und der KI so neue Tools an die Hand geben, die sie während Rails und Chat aufrufen kann. Du musst MCP nicht verstehen, um sie zu nutzen — installieren, und beim nächsten Rail-Lauf stehen sie bereit.
+
+## Was heute verfügbar ist
+
+Diese Version wird **ausschließlich gebündelt** ausgeliefert: Die installierbaren Plugins sind die, die in die App eingebaut sind. Es gibt keine Remote-Registry, keine von Nutzern hochgeladenen Plugins und kein Laden von Drittanbieter-Code — alles im Katalog ist also geprüft und wird mit Specrails ausgeliefert.
+
+Das Vorzeige-Plugin ist:
+
+- **Serena** — semantische Code-Navigation. Es gibt der KI ein vom Language-Server gestütztes Verständnis deiner Codebasis (Gehe-zu-Definition, Referenzen finden, symbolbewusste Suche) statt schlichtem Textabgleich. Ideal für größere oder unbekannte Repos, in denen der Agent über echte Symbole schlussfolgern soll.
+
+  Serena benötigt das Tool `uv` in deinem `PATH` (es läuft über `uvx`). Die App erkennt automatisch, ob `uv` vorhanden ist, und weist dich darauf hin, falls es fehlt.
+
+## Ein Plugin installieren
+
+1. Öffne **Integrationen** über die rechte Seitenleiste.
+2. Finde das Plugin im Katalog. Jede Karte zeigt einen Status: **Nicht installiert**, **Installiert**, **Beeinträchtigt** oder **Verwaist**.
+3. Klicke in das Plugin hinein, um die **Installation vorab anzusehen** — das zeigt dir genau, welche Dateien sich ändern werden, bevor irgendetwas passiert.
+4. Klicke auf **Installieren**. Du siehst den Fortschritt live, während es eingerichtet wird.
+
+Im Hintergrund läuft die Installation *chirurgisch und additiv* ab: Sie fügt der `.mcp.json` deines Projekts nur ihre eigenen Einträge hinzu (und bei manchen Plugins eine Fragment-Datei im geschützten `.claude/agents/`-Namensraum). Sie schreibt deine Konfiguration nie komplett neu, und ein zweites Plugin kann das erste niemals stören. Kann sich eine Installation nicht als fehlerfrei verifizieren, wird sie sauber zurückgerollt.
+
+## Installierte Plugins verwalten
+
+- **Gesundheit.** Jedes Plugin hat eine Gesundheitsprüfung auf Abruf. Ein Plugin, das sich zwar installieren lässt, später aber nicht starten kann, wird als **Beeinträchtigt** markiert — es blockiert deine Rails nicht, du siehst nur das Badge und einen Grund.
+- **Deinstallieren.** Beim Entfernen eines Plugins werden chirurgisch nur die Einträge gelöscht, die ihm gehören; der Rest deiner Konfiguration bleibt unangetastet.
+- **Verwaiste Einträge.** Bleiben die Dateien eines Plugins ohne sauberen Zustand zurück (etwa nach einer abgebrochenen Änderung), erscheint es als **Verwaist** und du kannst es mit einem Klick aufräumen.
+
+## Wie Plugins in deiner Arbeit auftauchen
+
+- **Rails.** Bevor eine Rail läuft, prüft Specrails, welche Plugins installiert und fehlerfrei sind, und stellt deren Tools dem Agent für diesen Job bereit. Ein beeinträchtigtes Plugin wird für diesen Lauf einfach übersprungen — die Rail startet trotzdem normal. Jeder Job speichert einen Schnappschuss davon, welche Plugins aktiv waren; den siehst du im diagnostischen Export des Jobs.
+- **Chat.** Der Chat übernimmt automatisch die MCP-Konfiguration deines Projekts, sodass installierte Plugins auch dort verfügbar sind.
+- **Einrichtung.** Während ein Projekt noch eingerichtet wird, werden Plugins ignoriert — sie kommen ins Spiel, sobald das Projekt bereit ist.
+
+## Anbieterhinweise
+
+Plugins sind anbieterbewusst. Serena und ähnliche MCP-Plugins greifen bei Anbietern, die MCP über die `.mcp.json` des Projekts registrieren (Claude und Gemini). Bei Codex-Projekten werden MCP-Server stattdessen über Codex' eigene globale Konfiguration verwaltet, sodass Plugin-Einträge in **Integrationen** entsprechend gefiltert werden. Die Jira-Karte in den Integrationen ist anbieterunabhängig und erscheint für alle — siehe den Jira-Guide.
+
+## Reservierte Dateien
+
+Plugins verwalten eine kleine, klar abgegrenzte Menge an Dateien in deinem Projekt: deine `.mcp.json` (chirurgisch zusammengeführt), etwas Zustand unter `.specrails/plugins/` sowie pro Plugin Agenten-Fragmente unter `.claude/agents/custom-<plugin>.md`. Das sind committbare Team-Assets, falls du eine Integration mit deinen Teamkolleg:innen teilen möchtest — die App überschreibt sie nie blind.

package/docs/guide/de/integrations/3-jira-integration.md

@@ -0,0 +1,71 @@
+# Jira-Integration
+
+Du möchtest, dass deine Specs auf einem echten **Jira-Board** leben statt in Specrails? Die Jira-Integration hinterlegt die Specs eines Projekts mit Jira-Vorgängen, hält die Status synchron, während Rails laufen, und hält sich die übrige Zeit zurück. Jedes Projekt synchronisiert sich mit **seinem eigenen** Jira-Board.
+
+## So funktioniert es (die Kurzfassung)
+
+Specrails agiert als **Sync-Schicht** zwischen Jira und deinem Projekt. Die Grundidee: Dein lokaler Spec-Speicher bleibt das Maßgebliche, das die Pipeline liest, und Specrails ist dafür verantwortlich, ihn und Jira in Übereinstimmung zu halten.
+
+- Wenn du eine Rail startest, verschiebt Specrails den verknüpften Jira-Vorgang nach **In Arbeit**.
+- Wenn ein Job abschließt, überführt Specrails den Vorgang (nach **Fertig** oder zurück nach **To Do**, falls er fehlgeschlagen ist) und postet einen Abschlusskommentar mit Job-ID, Kosten und Dauer.
+- In regelmäßigen Abständen **pollt** Specrails Jira nach Änderungen, die jemand auf dem Board vorgenommen hat, und spiegelt sie zurück in deine Specs.
+
+Alle Rückschreibungen laufen über eine dauerhafte, absturzsichere Outbox, sodass ein kurzzeitiger Jira-Aussetzer niemals einen Job kaputtmacht — das Update wird einfach erneut versucht.
+
+## Ein Board verbinden
+
+Du verbindest dich über die **Einstellungen**-Seite eines Projekts (am Ende des „Projekt hinzufügen“-Assistenten gibt es zusätzlich einen optionalen Schritt „Jira konfigurieren“). Der Verbindungsassistent führt dich durch:
+
+1. **Testen** — gib deine Jira-URL und deine Zugangsdaten ein, und Specrails überprüft die Verbindung.
+2. **Projekt wählen** — wähle aus, mit welchem Jira-Projekt synchronisiert werden soll.
+3. **Statuszuordnung (optional)** — ordne deine Jira-Workflow-Status den Zuständen von Specrails zu, falls die automatische Erkennung etwas Hilfe braucht (mehr dazu unten).
+4. **Verbinden** — fertig. Deine Specs spiegeln nun dieses Board.
+
+### Authentifizierung
+
+Diese Version nutzt **Token-Einfügen** zur Authentifizierung — schnell, lokal auf dem Gerät und ganz ohne Backend:
+
+- **Jira Cloud:** deine Konto-E-Mail plus ein API-Token.
+- **Jira Data Center / Server:** ein Personal Access Token (PAT).
+
+Dein Token wird **verschlüsselt auf deinem eigenen Rechner** gespeichert und verlässt ihn nie. Die App zeigt nur an, ob ein Token vorhanden ist, niemals das Token selbst.
+
+## Statuszuordnung
+
+Der kniffligste Teil jeder Jira-Synchronisierung ist es, *deinen* Workflow auf die einfachen Zustände von Specrails abzubilden (To Do / In Arbeit / Fertig, plus Abbruch-/Ship-Varianten). Specrails löst das in zwei Stufen:
+
+1. **Deine explizite Statuszuordnung**, falls du im Assistenten eine festgelegt hast — sie gewinnt immer.
+2. **Automatische Erkennung** anhand der Kategorie jedes Status (new / in-progress / done) plus intelligentem Abgleich für Abbruch- und Ship-artige Status.
+
+Muss ein Vorgang über einen Workflow mit gesteuerten Übergängen bewegt werden, findet Specrails Schritt für Schritt einen gültigen Pfad und füllt unterwegs alle erforderlichen Felder aus (etwa eine Resolution). Lässt sich ein Status wirklich nicht erreichen, wird die Operation als Dead-Letter geparkt und dir angezeigt, statt still fehlzuschlagen — du siehst dann einen **Beeinträchtigt**-Hinweis und kannst es erneut versuchen.
+
+## Hot-Swap: sicher ein- und ausschalten
+
+Die Jira-Verknüpfung ist **pro Spec**, festgehalten in dem Moment, in dem du eine Rail startest — kein globaler Alles-oder-nichts-Schalter für das Board. Das macht das Umschalten sicher:
+
+- **Aktivieren oder Deaktivieren** der Integration ordnet deine bestehenden Specs nie neu zu.
+- **Trennen** versetzt dein Projekt zurück in das normale Verhalten mit lokalen Specs.
+- Specs, die bereits eine Jira-Verknüpfung haben, behalten ihre Rückschreibung; Specs ohne werden in Ruhe gelassen.
+
+So kannst du frei experimentieren — anschalten, ein paar Rails laufen lassen, ausschalten — ohne dein Board oder deine lokalen Specs durcheinanderzubringen.
+
+## Im Alltag
+
+Nach dem Verbinden zeigt die Einstellungen-Seite des Projekts eine **Verbunden-Karte**, auf der du:
+
+- **Jetzt synchronisieren** — ein sofortiges Pollen erzwingen, statt auf den Timer zu warten.
+- **Dead-Letter erneut versuchen** — alle hängengebliebenen Rückschreibungen erneut ausführen.
+- **Hot-Swap-Schalter** — die Integration vorübergehend pausieren/fortsetzen.
+- **Trennen** — das Board sauber lösen.
+
+Specs, die mit Jira hinterlegt sind, zeigen ein **Jira-Schlüssel-Badge** (etwa `PROJ-123`) auf ihrer Karte, und ein Klick darauf führt zurück zum Vorgang. Außerdem bekommst du kleine Benachrichtigungen, wenn eine Synchronisierung abschließt, wenn ein Auth-Token abläuft (damit du es erneuern kannst) oder wenn die Integration in einen beeinträchtigten Zustand gerät.
+
+## Was du im Hinterkopf behalten solltest
+
+- **Polling statt Webhooks.** Da Specrails lokal läuft, pollt es Jira nach eingehenden Änderungen, statt Push-Benachrichtigungen zu empfangen. Änderungen erscheinen innerhalb des Poll-Intervalls, nicht sofort.
+- **Ein Board pro Projekt.** Verschiedene Projekte können sich mit verschiedenen Boards synchronisieren; ein einzelnes Projekt synchronisiert sich mit genau einem.
+- **Last-Write-Wins bei Konflikten** für den seltenen Fall, dass zwei Tabs denselben Entwurf gleichzeitig bearbeiten.
+
+## Ausschalten
+
+Wenn du jemals vollständig aussteigen möchtest, **trenne** einfach in den Einstellungen. Deine Specs kehren zum reinen Lokal-Verhalten zurück, und die Jira-Metadaten liegen einfach ungenutzt herum — es wird nichts zerstört.

package/docs/guide/de/integrations/4-mobile-companion.md

@@ -0,0 +1,38 @@
+# Der mobile Companion
+
+Specrails hat eine Companion-App fürs Smartphone, mit der du deine Rails im Blick behältst, während du nicht am Schreibtisch sitzt — Jobs laufen sehen, ihren Abschluss verfolgen und auf dem Laufenden bleiben, ohne vor dem Dashboard zu sitzen.
+
+## Wofür sie da ist
+
+Der Companion ist eine **Monitoring**-Oberfläche. Er verbindet sich über dein lokales Netzwerk mit deiner laufenden Specrails-Desktop-App und spiegelt die Live-Aktivität von Projekten und Jobs auf dein Smartphone. Stell ihn dir als ein Fenster auf einen Blick zu denselben Rails vor, die du sonst auf dem Dashboard beobachten würdest.
+
+## Dein Smartphone koppeln
+
+Das Koppeln baut auf einem **QR-Code** auf, damit du nichts Umständliches eintippen musst:
+
+1. Stelle sicher, dass deine Specrails-Desktop-App läuft und dein Smartphone im **selben lokalen Netzwerk** ist (gleiches WLAN).
+2. Öffne in der Desktop-App den Kopplungsbildschirm, um einen QR-Code anzuzeigen.
+3. Scanne diesen Code in der Companion-App auf deinem Smartphone.
+4. Das Smartphone entdeckt die Desktop-App im Netzwerk und verbindet sich.
+
+Von da an hält der Companion eine Live-Verbindung und streamt Projektlisten und Job-Updates, sobald sie passieren.
+
+## Wie die Verbindung funktioniert
+
+Die Desktop-App macht sich in deinem lokalen Netzwerk bekannt, damit das Smartphone sie finden kann, und der QR-Code trägt die Details, die das Smartphone für eine sichere Verbindung braucht. Alles bleibt in deinem lokalen Netzwerk — der Companion spricht direkt mit deinem Rechner, nicht über irgendeinen Cloud-Dienst.
+
+Weil es auf dem lokalen Netzwerk basiert, müssen beide Geräte füreinander erreichbar sein. Falls das Koppeln nicht klappt:
+
+- Stelle sicher, dass beide Geräte im **selben WLAN** sind (und dass das Netzwerk Clients nicht voneinander isoliert).
+- Achte darauf, dass die Desktop-App beim Scannen **läuft**.
+- Öffne den Kopplungsbildschirm erneut, um den QR-Code aufzufrischen, und versuche erneut zu scannen.
+
+## Was du sehen wirst
+
+Sobald gekoppelt, zeigt der Companion deine Projekte und ihre Live-Job-Aktivität — du bekommst also dieselben Echtzeit-Rail-Updates, die ins Desktop-Dashboard fließen, direkt auf dein Smartphone gespielt, sobald sie eintreten. Es ist der einfachste Weg, den Moment mitzubekommen, in dem eine lang laufende Rail fertig wird.
+
+## Gut zu wissen
+
+- **Monitoring zuerst.** Der Companion ist dafür gedacht, Rails im Auge zu behalten, nicht dazu, den vollständigen Desktop-Workflow vom Smartphone aus zu steuern.
+- **Nur lokal.** Kein Konto, kein Cloud-Relay — nur dein Rechner und dein Smartphone, in deinem Netzwerk.
+- **Halte den Desktop wach.** Der Companion spiegelt eine laufende Desktop-App; geht dein Rechner in den Ruhezustand oder schließt die App, pausieren die Live-Updates, bis sie zurück ist.