Onboarding-Wizard

Der Wizard läuft im Portal, sobald du ein neues Projekt zum ersten Mal öffnest.

Er führt dich durch vier Schritte und validiert jeden, bevor es weitergeht.

Übersicht

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌───────────┐
│ Sprache  │───►│   KI-    │───►│ Projekt- │───►│ Preflight │
│ & Theme  │    │ Provider │    │  Import  │    │  Checks   │
└──────────┘    └──────────┘    └──────────┘    └───────────┘
   Schritt 1     Schritt 2      Schritt 3      Schritt 4

Der Wizard läuft komplett im Browser. Der lokale Agent liefert die Projektdaten (Datei-Scan, Node-/Git-Versionen, Playwright-Config) über die WebSocket-Bridge.

Schritt 1: Sprache & Theme

Englisch oder Deutsch wählen, dazu ein UI-Theme. Steuert alle Portal-Labels, Tooltips und KI-Prompt-Templates.

Siehe Sprachauswahl.

Schritt 2: KI-Verbindung

Provider verbinden — Gemini, OpenAI, Claude, Azure OpenAI, OpenRouter, Groq, DeepSeek, Ollama, LM Studio oder dein AI-Proxy. Der Agent verschlüsselt den Key client-seitig; der Klartext-Key landet nicht in der Portal-DB.

Alternativ Observer-Mode wählen und KI komplett überspringen — Runner, Test Hub, Accessibility Auditor und Reports laufen auch so.

Siehe KI-Verbindung.

Schritt 3: Projekt-Import

Der Agent scannt das Projektverzeichnis und meldet:

• Page-Object-Models, Fixtures, Test-Dateien
• node_modules und Playwright-Browser-Binaries
• playwright.config.ts (Projekte, baseURL, Reporter)

Du bestätigst die erkannten Pfade oder scaffoldest mit npm init playwright@latest.

Siehe Projekt-Import.

Schritt 4: Preflight-Checks

Der Agent prüft die Umgebung:

• Node.js-Version (≥ 20)
• Git verfügbar (≥ 2.30)
• Schreibrechte im Projekt
• Playwright-Browser-Binaries

Rote Checks blockieren den Abschluss. Grün heißt: bereit.

Siehe Preflight-Checks.

TIP

Wizard jederzeit erneut ausführen über Portal → Settings → Allgemein → Wizard erneut ausführen. Praktisch beim Projektwechsel oder Key-Rotation.

Nach Abschluss

Sind alle vier Schritte grün, öffnet das Portal das Overview-Dashboard. Test Hub und Runner laden die Dateibäume des Agents; Brain und Swarm aktivieren sich, sobald KI verbunden ist.

Per-Projekt-Wizard-State liegt portal-seitig, gekeyed über den Projekt-Root, den der Agent meldet.

Troubleshooting

Symptom	Ursache	Fix
Wizard erscheint nicht	Bereits abgeschlossen für dieses Projekt	Aus Settings neu starten
KI-Schritt verwirft Key	Falsche Region/Provider oder abgelaufener Key	Korrekte Region; Key rotieren
Projekt-Import schlägt fehl	Keine playwright.config.ts	Gültiges Playwright-Projekt wählen oder Initialisieren
Preflight rot	Node 20+ / Git 2.30+ fehlt	Installieren oder updaten; Agent neu starten
Agent-Verbindung weg	Terminal geschlossen, Netz weg	npx @xyva/agent start --project . neu, Portal refreshen