# Setup Wizard - UX Flow Specification This document defines the user experience flows for both CLI and UI implementations of the Setup Wizard, ensuring feature parity across surfaces. ## 1. Design Principles ### 1.1 Core UX Goals 1. **Self-serve clarity** - Users should complete setup without reading external documentation 2. **Progressive disclosure** - Show only relevant options at each step 3. **Fail-forward** - Guide users through errors with actionable fixes 4. **Parity** - CLI and UI offer identical capabilities 5. **Resume-friendly** - Support interruption and resumption ### 1.2 Terminology | Term | Definition | |------|------------| | **Step** | A discrete configuration unit (e.g., "Database Setup") | | **Check** | A Doctor diagnostic that validates a step | | **Fix** | A remediation command generated by Doctor | | **Connector** | A specific integration provider (e.g., "HashiCorp Vault") | --- ## 2. CLI Flow ### 2.1 Command Structure ```bash # Interactive setup (default) stella setup # Non-interactive with config file stella setup --config setup.yaml # Reconfigure existing installation stella setup --reconfigure # Resume interrupted setup stella setup --resume # Specific step only stella setup --step database # Skip optional steps stella setup --skip vault,scm ``` ### 2.2 Global Options | Option | Type | Description | |--------|------|-------------| | `--config` | path | YAML configuration file | | `--non-interactive` | flag | Fail on missing required input | | `--reconfigure` | flag | Re-run on existing installation | | `--resume` | flag | Continue from last incomplete step | | `--step ` | string | Run specific step only | | `--skip ` | string | Comma-separated steps to skip | | `--verbose` | flag | Show detailed progress | | `--output ` | enum | `text`, `json`, `yaml` | ### 2.3 Interactive Flow ``` $ stella setup ____ _ _ _ ___ / ___|| |_ ___| | | __ _ / _ \ _ __ ___ \___ \| __/ _ \ | |/ _` | | | | '_ \/ __| ___) | || __/ | | (_| | |_| | |_) \__ \ |____/ \__\___|_|_|\__,_|\___/| .__/|___/ |_| Setup Wizard v2026.01 This wizard will guide you through the initial configuration. Press Ctrl+C at any time to exit. Progress is saved automatically. Detected environment: - Platform: linux-x64 - Docker: available - PostgreSQL: not detected - Valkey: not detected [1/10] Database Setup ---------------------- ? PostgreSQL host: localhost ? PostgreSQL port: [5432] ? Database name: [stellaops] ? Username: stellaops_admin ? Password: ******** Testing connection... [OK] Connected to PostgreSQL 16.2 [OK] User has CREATE SCHEMA permission [OK] Database 'stellaops' accessible Running Doctor checks... [PASS] check.database.connectivity [PASS] check.database.permissions [PASS] check.database.version Database setup complete. [2/10] Valkey/Redis Setup ------------------------- ... ``` ### 2.4 Error Handling Flow ``` Testing connection... [FAIL] Could not connect to PostgreSQL Likely causes: 1. PostgreSQL is not running 2. Firewall blocking port 5432 3. Incorrect host/port Suggested fixes: # If using Docker Compose: docker compose -f devops/compose/docker-compose.yml up -d postgres # If using systemd: sudo systemctl start postgresql sudo systemctl enable postgresql # Verify connectivity: pg_isready -h localhost -p 5432 ? Retry connection? [Y/n] ``` ### 2.5 Multi-Connector Flow ``` [6/10] Vault Integration (Optional) ----------------------------------- ? Configure a secrets provider? [Y/n] Y Detected: VAULT_ADDR=https://vault.example.com:8200 ? Use detected HashiCorp Vault? [Y/n] Y ? Vault address: [https://vault.example.com:8200] ? Authentication method: > Token AppRole Kubernetes ? Vault token: ******** Testing connection... [OK] Vault connected (version 1.15.0) [OK] KV v2 mount 'secret' accessible ? Add another secrets provider? [y/N] y ? Select provider: HashiCorp Vault > Azure Key Vault AWS Secrets Manager File Provider ... ``` ### 2.6 Skip Flow ``` [7/10] SCM Integration (Optional) --------------------------------- ? Configure source control integration? [Y/n] n Skipping SCM integration. Note: You can configure this later via 'stella setup --step scm' Skipped steps can be completed from: - CLI: stella setup --reconfigure - UI: Settings > Configuration Wizard ``` ### 2.7 Non-Interactive Mode ```yaml # setup.yaml database: host: postgres.example.com port: 5432 database: stellaops username: stellaops_admin password: ${POSTGRES_PASSWORD} # Environment variable valkey: host: valkey.example.com port: 6379 password: ${VALKEY_PASSWORD} vault: - type: hashicorp address: https://vault.example.com:8200 authMethod: kubernetes role: stellaops scm: - type: github-app appId: "123456" installationId: "789012" privateKeyPath: /etc/stellaops/github-app.pem notifications: - type: slack name: engineering webhookUrl: ${SLACK_WEBHOOK_URL} environments: - name: dev displayName: Development orderIndex: 0 - name: staging displayName: Staging orderIndex: 1 - name: prod displayName: Production orderIndex: 2 isProduction: true requiredApprovals: 2 ``` ```bash $ stella setup --config setup.yaml --non-interactive [1/10] Database Setup.............. [OK] [2/10] Valkey/Redis Setup.......... [OK] [3/10] Database Migrations......... [OK] [4/10] Admin Bootstrap............. [OK] [5/10] Crypto Profile.............. [OK] [6/10] Vault Integration........... [OK] [7/10] SCM Integration............. [OK] [8/10] Notification Channels....... [OK] [9/10] Environment Definition...... [OK] [10/10] Agent Registration......... [SKIP] (no agents defined) Setup complete. System status: Operational Run 'stella doctor run' for full diagnostics. ``` ### 2.8 Completion Output ``` Setup Complete! =============== Status: Operational Completed steps: [x] Database Setup [x] Valkey/Redis Setup [x] Database Migrations [x] Admin Bootstrap [x] Crypto Profile [x] Vault Integration [x] SCM Integration [x] Notification Channels Skipped steps: [ ] Identity Provider (OIDC/LDAP) [ ] Environment Definition [ ] Agent Registration [ ] Vulnerability Feeds To reach Production-Ready status, configure: - Identity Provider: stella setup --step identity - Environments: stella setup --step environments - Agents: stella setup --step agents Next steps: 1. Run first scan: stella scan image --image 2. View dashboard: https://localhost:8080 3. Full diagnostics: stella doctor run --mode full Setup report saved to: ~/.stellaops/setup-report-2026-01-13.md ``` --- ## 3. UI Flow ### 3.1 First-Run Blocking When the system detects first-run (no database connection or admin user): 1. **Intercept all routes** - Redirect to `/setup` 2. **Show blocking modal** - Cannot dismiss without completing required steps 3. **Progress indicator** - Show completion percentage ### 3.2 Wizard Layout ``` +------------------------------------------------------------------+ | [StellaOps Logo] [?] Help [X] Exit | +------------------------------------------------------------------+ | | | SETUP WIZARD Step 1 of 10| | | | +------------+ +------------+ +------------+ +------------+ | | | Database | | Valkey | | Migrations | | Admin | | | | [1] | | [2] | | [3] | | [4] | | | | [CURRENT] | | [PENDING] | | [PENDING] | | [PENDING] | | | +------------+ +------------+ +------------+ +------------+ | | | | +------------+ +------------+ +------------+ +------------+ | | | Crypto | | Vault | | SCM | | Notify | | | | [5] | | [6] | | [7] | | [8] | | | | [PENDING] | | [OPTIONAL] | | [OPTIONAL] | | [OPTIONAL] | | | +------------+ +------------+ +------------+ +------------+ | | | | +------------+ +------------+ | | | Environments| | Agents | | | | [9] | | [10] | | | | [OPTIONAL] | | [OPTIONAL] | | | +------------+ +------------+ | | | +------------------------------------------------------------------+ | | | DATABASE SETUP | | --------------- | | | | Configure PostgreSQL connection for Stella Ops data storage. | | | | +----------------------------------------------------------+ | | | Host [localhost ] | | | | Port [5432 ] | | | | Database [stellaops ] | | | | Username [ ] | | | | Password [ ] | | | | SSL Mode [prefer v ] | | | +----------------------------------------------------------+ | | | | [Test Connection] | | | | Connection Status: Not tested | | | +------------------------------------------------------------------+ | [Skip] [Continue] | +------------------------------------------------------------------+ ``` ### 3.3 Step States | State | Icon | Color | Description | |-------|------|-------|-------------| | **PENDING** | Circle | Gray | Not yet started | | **CURRENT** | Circle+Ring | Blue | Currently active | | **PASSED** | Checkmark | Green | Completed successfully | | **FAILED** | X | Red | Failed validation | | **SKIPPED** | Dash | Orange | Explicitly skipped | | **OPTIONAL** | Circle+O | Gray | Can be skipped | ### 3.4 Connection Test Flow ``` +------------------------------------------------------------------+ | | | [Test Connection] | | | | +----------------------------------------------------------+ | | | Testing connection... | | | | [=========> ] 30% | | | | | | | | [OK] TCP connection to localhost:5432 | | | | [ ] Authenticating... | | | | [ ] Checking permissions... | | | +----------------------------------------------------------+ | | | +------------------------------------------------------------------+ ``` ### 3.5 Error State with Fixes ``` +------------------------------------------------------------------+ | | | CONNECTION FAILED | | | | +----------------------------------------------------------+ | | | [!] Could not connect to PostgreSQL | | | | | | | | Error: Connection refused (ECONNREFUSED) | | | | | | | | LIKELY CAUSES: | | | | 1. PostgreSQL is not running | | | | 2. Firewall blocking port 5432 | | | | 3. Incorrect host or port | | | | | | | | SUGGESTED FIXES: | | | | | | | | If using Docker Compose: | | | | +------------------------------------------------------+ | | | | | docker compose up -d postgres [Copy]| | | | | +------------------------------------------------------+ | | | | | | | | If using systemd: | | | | +------------------------------------------------------+ | | | | | sudo systemctl start postgresql [Copy]| | | | | +------------------------------------------------------+ | | | | | | | | Verify connectivity: | | | | +------------------------------------------------------+ | | | | | pg_isready -h localhost -p 5432 [Copy]| | | | | +------------------------------------------------------+ | | | +----------------------------------------------------------+ | | | | [Retry] [Edit Configuration] | +------------------------------------------------------------------+ ``` ### 3.6 Multi-Connector Interface ``` +------------------------------------------------------------------+ | | | VAULT INTEGRATION (Optional) | | --------------------------- | | | | Configure secrets management providers. | | | | CONFIGURED PROVIDERS: | | +----------------------------------------------------------+ | | | [V] HashiCorp Vault [Edit] [X] | | | | https://vault.example.com:8200 | | | | Status: Connected | | | +----------------------------------------------------------+ | | | | [+ Add Another Provider] | | | | +----------------------------------------------------------+ | | | SELECT PROVIDER TYPE: | | | | | | | | [HashiCorp Vault] [Azure Key Vault] | | | | [AWS Secrets Mgr] [File Provider] | | | +----------------------------------------------------------+ | | | | Note: You can add up to 5 vault integrations. | | | +------------------------------------------------------------------+ | [Skip] [Continue] | +------------------------------------------------------------------+ ``` ### 3.7 Doctor Check Results Panel ``` +------------------------------------------------------------------+ | | | VALIDATION RESULTS | | ------------------ | | | | +----------------------------------------------------------+ | | | [PASS] check.database.connectivity | | | | PostgreSQL connection successful | | | | | | | | [PASS] check.database.permissions | | | | User has required permissions | | | | | | | | [PASS] check.database.version | | | | PostgreSQL 16.2 (minimum: 16.0) | | | | | | | | [WARN] check.database.poolsize | | | | Pool size 10 is below recommended 50 | | | | [Show Fix] | | | +----------------------------------------------------------+ | | | | All required checks passed. | | | +------------------------------------------------------------------+ ``` ### 3.8 Skip Confirmation Dialog ``` +------------------------------------------------------------------+ | | | +----------------------------------------------------------+ | | | | | | | SKIP VAULT INTEGRATION? | | | | ----------------------- | | | | | | | | Without a secrets provider: | | | | - Credentials stored in local keyring | | | | - Air-gap deployments may require manual setup | | | | - Production deployments not recommended | | | | | | | | You can configure this later from: | | | | Settings > Configuration Wizard > Vault | | | | | | | | +----------------------------------------------------+ | | | | | Reason for skipping (optional): | | | | | | [Will configure after infrastructure ready ] | | | | | +----------------------------------------------------+ | | | | | | | | [Cancel] [Skip This Step] | | | +----------------------------------------------------------+ | | | +------------------------------------------------------------------+ ``` ### 3.9 Completion Screen ``` +------------------------------------------------------------------+ | | | +----------------------------------------------------------+ | | | | | | | [Checkmark Icon] | | | | | | | | SETUP COMPLETE | | | | | | | | Status: OPERATIONAL | | | | | | | +----------------------------------------------------------+ | | | | COMPLETED STEPS: | | +----------------------------------------------------------+ | | | [x] Database Setup | | | | [x] Valkey/Redis Setup | | | | [x] Database Migrations | | | | [x] Admin Bootstrap | | | | [x] Crypto Profile | | | | [x] Vault Integration | | | | [x] SCM Integration | | | | [x] Notification Channels | | | +----------------------------------------------------------+ | | | | SKIPPED STEPS: | | +----------------------------------------------------------+ | | | [ ] Identity Provider (OIDC/LDAP) | | | | [ ] Environment Definition | | | | [ ] Agent Registration | | | +----------------------------------------------------------+ | | | | NEXT STEPS: | | +----------------------------------------------------------+ | | | 1. Run your first scan | | | | 2. Configure identity provider for SSO | | | | 3. Set up environments for deployments | | | +----------------------------------------------------------+ | | | | [Download Setup Report] [Go to Dashboard] | | | +------------------------------------------------------------------+ ``` --- ## 4. Configuration Pane (Post-Setup) ### 4.1 Access Points | Surface | Path | Menu Location | |---------|------|---------------| | **UI** | `/settings/configuration` | Settings > Configuration Wizard | | **CLI** | `stella setup --reconfigure` | N/A | ### 4.2 Configuration Pane Layout ``` +------------------------------------------------------------------+ | CONFIGURATION WIZARD | +------------------------------------------------------------------+ | | | Last configured: January 13, 2026 at 10:30 AM | | Status: Production-Ready | | | | INFRASTRUCTURE | | +----------------------------------------------------------+ | | | Database Setup [Healthy] [Reconfigure] | | | | PostgreSQL 16.2 at localhost:5432 | | | +----------------------------------------------------------+ | | +----------------------------------------------------------+ | | | Valkey/Redis Setup [Healthy] [Reconfigure] | | | | Valkey at localhost:6379 | | | +----------------------------------------------------------+ | | | | INTEGRATIONS | | +----------------------------------------------------------+ | | | Vault (2 providers) [Healthy] [Manage] | | | | HashiCorp Vault, Azure Key Vault | | | +----------------------------------------------------------+ | | +----------------------------------------------------------+ | | | SCM (1 provider) [Healthy] [Manage] | | | | GitHub App | | | +----------------------------------------------------------+ | | +----------------------------------------------------------+ | | | Notifications (3 channels) [Healthy] [Manage] | | | | Slack, Email, PagerDuty | | | +----------------------------------------------------------+ | | | | ORCHESTRATION | | +----------------------------------------------------------+ | | | Environments (3) [Healthy] [Manage] | | | | dev, staging, prod | | | +----------------------------------------------------------+ | | +----------------------------------------------------------+ | | | Agents (2) [1 Stale] [Manage] | | | | docker-prod-01, docker-prod-02 | | | +----------------------------------------------------------+ | | | | [Run Diagnostics] [Export Configuration] | +------------------------------------------------------------------+ ``` --- ## 5. Wording Guidelines ### 5.1 Step Titles | Step | Title | Subtitle | |------|-------|----------| | `database` | Database Setup | Configure PostgreSQL connection | | `valkey` | Valkey/Redis Setup | Configure caching and message queue | | `migrations` | Database Migrations | Apply schema updates | | `admin` | Admin Bootstrap | Create administrator account | | `crypto` | Crypto Profile | Configure signing keys | | `vault` | Vault Integration | Configure secrets management | | `scm` | SCM Integration | Connect source control | | `notifications` | Notification Channels | Configure alerts and notifications | | `environments` | Environment Definition | Define deployment environments | | `agents` | Agent Registration | Register deployment agents | ### 5.2 Button Labels | Action | Label | |--------|-------| | Proceed to next step | Continue | | Skip optional step | Skip | | Test configuration | Test Connection | | Retry after failure | Retry | | Add another connector | + Add Another | | Edit existing | Edit | | Remove | Remove | | Complete wizard | Finish Setup | ### 5.3 Status Messages | Status | Message | |--------|---------| | Testing | Testing connection... | | Success | Connection successful | | Failure | Could not connect | | Timeout | Connection timed out | | Permission denied | Permission denied | ### 5.4 Error Messages Format: `[What happened]. [Why it matters]. [What to do]` Example: > Could not connect to PostgreSQL. The database is required for all Stella Ops operations. Check that PostgreSQL is running and the connection details are correct. --- ## 6. Keyboard Navigation (UI) | Key | Action | |-----|--------| | `Tab` | Move to next field | | `Shift+Tab` | Move to previous field | | `Enter` | Submit form / Continue | | `Escape` | Cancel / Close dialog | | `Ctrl+C` | Copy command to clipboard | | `1-9` | Jump to step number | --- ## 7. Accessibility Requirements 1. **Screen reader support** - All form fields have labels 2. **Focus indicators** - Visible focus rings on all interactive elements 3. **Color contrast** - WCAG 2.1 AA compliance 4. **Keyboard navigation** - Full functionality without mouse 5. **Error announcements** - Errors announced to screen readers