Onboarding Wizard

The Wizard runs automatically on first launch and guides you through four steps to configure xyva for your environment. Each step validates its inputs before allowing you to proceed.

Overview

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌───────────┐
│ Language  │───►│   Auth   │───►│ Project  │───►│ Preflight │
│ Selection │    │  Doctor  │    │  Import  │    │  Checks   │
└──────────┘    └──────────┘    └──────────┘    └───────────┘
   Step 1          Step 2          Step 3          Step 4

Step 1: Language Selection

Choose between English and German (Deutsch). This setting controls all UI labels, tooltips, and AI prompt templates.

See Language Selection for details.

Step 2: Auth Doctor

The Auth Doctor scans your system for existing AI provider credentials — gcloud CLI tokens, OpenAI environment variables, Azure configurations. If found, xyva offers to reuse them. Otherwise, you can enter API keys manually or skip with Observer Mode.

See Auth Doctor for details.

Step 3: Project Import

Import an existing Playwright project from disk or scaffold a new one. xyva performs automatic framework detection and architectural mapping:

• Counts Page Object Models, Fixtures, and Test files
• Checks for node_modules and browser binaries
• Reads playwright.config.ts for project settings

See Project Import for details.

Step 4: Preflight Checks

A system validation pass that confirms your environment is ready:

• Node.js version check
• Git availability
• File system write permissions
• Playwright browser binaries

See Preflight Checks for details.

TIP

You can re-run the Wizard at any time from Settings > General > Re-run Wizard. This is useful when switching projects or updating AI credentials.

Wizard Completion

After passing all four steps, xyva opens the Overview dashboard. Your project is loaded, and you can start running tests immediately. If AI credentials were configured, the AI Assistant and Swarm QA modules become available.

INFO

The Wizard stores its configuration in the project's .xyva/ directory. Each project maintains its own settings independently.

Troubleshooting

Symptom	Cause	Fix
Wizard does not appear	Already completed for this project	Re-run from Settings
Auth Doctor finds no credentials	No CLI tools or env vars configured	Enter API key manually
Project import fails	Missing playwright.config.ts	Ensure you select a valid Playwright project
Preflight shows red checks	Missing dependencies	Install Node.js 18+ and Git 2.30+