# Setup Wizard - Capability Specification

This document defines the functional requirements for the Stella Ops Setup Wizard, covering both CLI and UI implementations.

## 1. Overview

The Setup Wizard provides a guided, step-by-step configuration experience that:
- Validates infrastructure dependencies (PostgreSQL, Valkey)
- Runs database migrations
- Configures required integrations
- Sets up environments and agents
- Verifies each step via Doctor checks

---

## 2. Completion Thresholds

### 2.1 Operational (Minimum Required)

The system enters "Operational" state when:

| Requirement | Description | Doctor Check |
|-------------|-------------|--------------|
| Database connected | PostgreSQL is reachable and authenticated | `check.database.connectivity` |
| Migrations applied | All startup migrations complete, no pending release migrations | `check.database.migrations.applied` |
| Core services healthy | Gateway, Router, Authority respond to health probes | `check.services.core.healthy` |
| Admin user exists | At least one admin user with `admin:*` scope | `check.auth.admin.exists` |
| Crypto profile valid | At least one signing key configured | `check.crypto.profile.valid` |

**Gating Behavior:** UI blocks access to operational features until Operational threshold met.

### 2.2 Production-Ready (Recommended)

The system reaches "Production-Ready" state when:

| Requirement | Description | Doctor Check |
|-------------|-------------|--------------|
| OIDC/LDAP configured | External identity provider integrated | `check.security.identity.configured` |
| Vault connected | At least one secrets provider | `check.integration.vault.connected` |
| SCM integrated | At least one SCM (GitHub/GitLab) | `check.integration.scm.connected` |
| Notifications configured | At least one notification channel | `check.notify.channel.configured` |
| Feed sync enabled | Vulnerability feed mirroring active | `check.feeds.sync.enabled` |
| Environment defined | At least one environment created | `check.orchestrator.environment.exists` |
| Agent registered | At least one healthy agent | `check.orchestrator.agent.healthy` |
| TLS hardened | All endpoints using TLS 1.2+ | `check.security.tls.hardened` |

---

## 3. Step Catalog

### 3.1 Core Steps

| Step ID | Name | Required | Skippable | Category |
|---------|------|----------|-----------|----------|
| `database` | Database Setup | Yes | No | Infrastructure |
| `valkey` | Valkey/Redis Setup | Yes | No | Infrastructure |
| `migrations` | Database Migrations | Yes | No | Infrastructure |
| `admin` | Admin Bootstrap | Yes | No | Security |
| `crypto` | Crypto Profile | Yes | No | Security |

### 3.2 Integration Steps

| Step ID | Name | Required | Skippable | Category |
|---------|------|----------|-----------|----------|
| `vault` | Secrets Provider | No | Yes | Integration |
| `settingsstore` | Settings Store | No | Yes | Integration |
| `scm` | Source Control | No | Yes | Integration |
| `registry` | Container Registry | No | Yes | Integration |
| `notifications` | Notification Channels | No | Yes | Integration |
| `identity` | Identity Provider (OIDC/LDAP) | No | Yes | Security |

### 3.3 Orchestration Steps

| Step ID | Name | Required | Skippable | Category |
|---------|------|----------|-----------|----------|
| `environments` | Environment Definition | No | Yes | Orchestration |
| `agents` | Agent Registration | No | Yes | Orchestration |
| `feeds` | Vulnerability Feeds | No | Yes | Data |

---

## 4. Step Specifications

### 4.1 Database Setup (`database`)

**Purpose:** Configure PostgreSQL connection and verify accessibility.

**Inputs:**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `host` | string | Yes | `localhost` | PostgreSQL host |
| `port` | number | Yes | `5432` | PostgreSQL port |
| `database` | string | Yes | `stellaops` | Database name |
| `username` | string | Yes | - | Database user |
| `password` | secret | Yes | - | Database password |
| `sslMode` | enum | No | `prefer` | SSL mode (disable, prefer, require, verify-ca, verify-full) |
| `poolSize` | number | No | `100` | Connection pool size |

**Outputs:**
- Connection string stored in settings store
- Connection verified via `SELECT 1`
- Schema creation permissions validated

**Validation:**
- TCP connectivity to host:port
- Authentication with credentials
- `CREATE SCHEMA` permission check

**Doctor Checks:**
- `check.database.connectivity`
- `check.database.permissions`
- `check.database.version` (PostgreSQL >= 16)

**Persistence:**
- Environment: `STELLAOPS_POSTGRES_CONNECTION`
- Config: `Storage:ConnectionString` in Authority options
- Encrypted storage of password via configured Vault or local keyring

---

### 4.2 Valkey/Redis Setup (`valkey`)

**Purpose:** Configure Valkey/Redis for caching, queues, and session storage.

**Inputs:**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `host` | string | Yes | `localhost` | Valkey host |
| `port` | number | Yes | `6379` | Valkey port |
| `password` | secret | No | - | Valkey password |
| `database` | number | No | `0` | Database index (0-15) |
| `useTls` | boolean | No | `false` | Enable TLS |
| `abortOnConnectFail` | boolean | No | `false` | Fail fast on connection error |

**Outputs:**
- Connection string stored in settings
- PING response verified

**Validation:**
- TCP connectivity
- AUTH if password provided
- PING response within 5 seconds

**Doctor Checks:**
- `check.services.valkey.connectivity`
- `check.services.valkey.ping`

---

### 4.3 Database Migrations (`migrations`)

**Purpose:** Apply pending database migrations across all modules.

**Inputs:**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `modules` | string[] | No | `["all"]` | Modules to migrate |
| `dryRun` | boolean | No | `false` | Preview without applying |
| `force` | boolean | No | `false` | Allow release migrations |

**Outputs:**
- List of applied migrations per module
- Schema version recorded in `schema_migrations` table
- Checksum verification results

**Validation:**
- Advisory lock acquisition
- Checksum match for already-applied migrations
- No pending release migrations (unless force=true)

**Doctor Checks:**
- `check.database.migrations.applied`
- `check.database.migrations.checksums`
- `check.database.schema.version`

---

### 4.4 Admin Bootstrap (`admin`)

**Purpose:** Create initial administrator account.

**Inputs:**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `username` | string | Yes | `admin` | Admin username |
| `email` | string | Yes | - | Admin email |
| `password` | secret | Yes | - | Admin password |
| `displayName` | string | No | - | Display name |

**Validation:**
- Password complexity (min 12 chars, mixed case, numbers, symbols)
- Email format
- Username uniqueness

**Doctor Checks:**
- `check.auth.admin.exists`
- `check.auth.password.policy`

---

### 4.5 Crypto Profile (`crypto`)

**Purpose:** Configure cryptographic signing keys for attestations.

**Inputs:**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `profileType` | enum | Yes | - | `local`, `kms`, `hsm`, `sigstore` |
| `keyAlgorithm` | enum | No | `ecdsa-p256` | Key algorithm |
| `keyId` | string | Conditional | - | KMS/HSM key identifier |
| `certificatePath` | string | Conditional | - | Path to signing certificate |
| `privateKeyPath` | string | Conditional | - | Path to private key |

**Validation:**
- Key material accessible
- Algorithm supported
- Certificate chain valid (if provided)

**Doctor Checks:**
- `check.crypto.profile.valid`
- `check.crypto.signing.test`

---

### 4.6 Vault Integration (`vault`)

**Purpose:** Configure secrets management provider.

**Multi-Connector Support:** Yes - users can add multiple vault integrations.

**Connector Options:**

| Connector | Default | Description |
|-----------|---------|-------------|
| **HashiCorp Vault** | Yes (if detected) | KV v2 secrets engine |
| **Azure Key Vault** | Yes (if Azure env) | Azure-native secrets |
| **AWS Secrets Manager** | Yes (if AWS env) | AWS-native secrets |
| **File Provider** | Fallback | Local file-based secrets |

**Inputs (HashiCorp Vault):**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `address` | string | Yes | - | Vault server URL |
| `authMethod` | enum | Yes | `token` | token, approle, kubernetes |
| `mountPoint` | string | No | `secret` | KV mount point |
| `token` | secret | Conditional | - | Vault token |
| `roleId` | string | Conditional | - | AppRole role ID |
| `secretId` | secret | Conditional | - | AppRole secret ID |

**Default Selection Logic:**
1. If `VAULT_ADDR` env var set → HashiCorp Vault
2. If Azure IMDS available → Azure Key Vault
3. If AWS metadata available → AWS Secrets Manager
4. Otherwise → Prompt user

**Doctor Checks:**
- `check.integration.vault.connected`
- `check.integration.vault.auth`
- `check.integration.vault.secrets.access`

---

### 4.7 Settings Store Integration (`settingsstore`)

**Purpose:** Configure application settings and feature flag providers.

**Multi-Connector Support:** Yes - users can add multiple settings stores for different purposes.

**Connector Options:**

| Connector | Priority | Write | Watch | Feature Flags | Labels |
|-----------|----------|-------|-------|---------------|--------|
| **Consul KV** | P0 | Configurable | Yes | No | No |
| **etcd** | P0 | Configurable | Yes | No | No |
| **Azure App Configuration** | P1 | Read-only | Yes | Yes (native) | Yes |
| **AWS Parameter Store** | P1 | Configurable | No | No | Via path |
| **AWS AppConfig** | P2 | Read-only | Yes | Yes (native) | Yes |
| **ZooKeeper** | P2 | Configurable | Yes | No | No |
| **GCP Runtime Config** | P2 | Read-only | Yes | No | No |

**Inputs (Consul KV):**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `address` | string | Yes | - | Consul server URL |
| `token` | secret | No | - | ACL token |
| `tokenSecretRef` | string | No | - | Vault path to ACL token |
| `writeEnabled` | boolean | No | `false` | Enable write operations |

**Inputs (etcd):**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `address` | string | Conditional | - | Single endpoint URL |
| `endpoints` | string[] | Conditional | - | Multiple endpoint URLs |
| `username` | string | No | - | Authentication username |
| `password` | secret | No | - | Authentication password |
| `passwordSecretRef` | string | No | - | Vault path to password |
| `writeEnabled` | boolean | No | `false` | Enable write operations |

**Default Selection Logic:**
1. If `CONSUL_HTTP_ADDR` env var set -> Consul KV
2. If `ETCD_ENDPOINTS` env var set -> etcd
3. If Azure IMDS + App Config connection available -> Azure App Configuration
4. If AWS metadata + `/stellaops/` path exists -> AWS Parameter Store
5. Otherwise -> Prompt user

**Doctor Checks:**
- `check.integration.settingsstore.connectivity`
- `check.integration.settingsstore.auth`
- `check.integration.settingsstore.read`
- `check.integration.settingsstore.write` (if write enabled)
- `check.integration.settingsstore.latency`

---

### 4.8 SCM Integration (`scm`)

**Purpose:** Configure source control management integrations.

**Multi-Connector Support:** Yes - users can add GitHub AND GitLab simultaneously.

**Connector Options:**

| Connector | Description |
|-----------|-------------|
| **GitHub App** | GitHub.com or GHES via App installation |
| **GitLab Server** | GitLab.com or self-hosted |
| **Bitbucket** | Bitbucket Cloud or Server |
| **Gitea** | Self-hosted Gitea |
| **Azure DevOps** | Azure Repos |

**Inputs (GitHub App):**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `appId` | string | Yes | - | GitHub App ID |
| `installationId` | string | Yes | - | Installation ID |
| `privateKey` | secret | Yes | - | App private key (PEM) |
| `apiUrl` | string | No | `https://api.github.com` | API endpoint |

**Doctor Checks:**
- `check.integration.scm.github.auth`
- `check.integration.scm.github.permissions`

---

### 4.9 Notification Channels (`notifications`)

**Purpose:** Configure notification delivery channels.

**Multi-Connector Support:** Yes - multiple channels per type allowed.

**Channel Options:**

| Channel | Description |
|---------|-------------|
| **Slack** | Incoming webhook |
| **Teams** | Incoming webhook |
| **Email** | SMTP server |
| **Webhook** | Generic HTTP POST |
| **PagerDuty** | Incident alerts |

**Inputs (Slack):**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | Yes | - | Channel display name |
| `webhookUrl` | secret | Yes | - | Slack incoming webhook URL |
| `channel` | string | No | - | Default channel override |
| `username` | string | No | `StellaOps` | Bot username |
| `iconEmoji` | string | No | `:shield:` | Bot icon |

**Doctor Checks:**
- `check.notify.channel.configured`
- `check.notify.slack.webhook`
- `check.notify.delivery.test`

---

### 4.10 Environment Definition (`environments`)

**Purpose:** Define deployment environments (dev, staging, prod).

**Inputs:**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | Yes | - | Environment slug (lowercase) |
| `displayName` | string | Yes | - | Display name |
| `orderIndex` | number | Yes | - | Pipeline position (0=first) |
| `isProduction` | boolean | No | `false` | Production flag |
| `requiredApprovals` | number | No | `0` | Approval count |
| `requireSeparationOfDuties` | boolean | No | `false` | SoD enforcement |
| `autoPromoteFrom` | string | No | - | Auto-promote source |

**Validation:**
- Production environments require `requiredApprovals >= 1`
- `autoPromoteFrom` must reference existing environment with lower orderIndex
- Name must match `^[a-z][a-z0-9-]{1,31}$`

**Doctor Checks:**
- `check.orchestrator.environment.exists`
- `check.orchestrator.environment.valid`

---

### 4.11 Agent Registration (`agents`)

**Purpose:** Register deployment agents with the orchestrator.

**Inputs:**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `name` | string | Yes | - | Agent name |
| `capabilities` | string[] | Yes | - | `docker`, `compose`, `ssh`, `winrm` |
| `labels` | map | No | `{}` | Agent labels for selection |

**Outputs:**
- Registration token (one-time, 24-hour expiry)
- Agent installation command

**Generated Command:**
```bash
stella-agent register --token <token> --name <name> --orchestrator-url <url>
```

**Doctor Checks:**
- `check.orchestrator.agent.registered`
- `check.orchestrator.agent.healthy`
- `check.orchestrator.agent.certificate`

---

## 5. Multi-Connector Model

### 5.1 Connector Categories

Each integration category supports multiple instances:

| Category | Max Instances | Use Case |
|----------|---------------|----------|
| **Vault** | 5 | Separate vaults per environment |
| **Settings Store** | 5 | Config from Azure App Config + feature flags from Consul |
| **SCM** | 10 | GitHub + GitLab + internal Gitea |
| **Registry** | 10 | ECR + Harbor + internal registry |
| **Notifications** | 20 | Slack per team + email + PagerDuty |

### 5.2 Default Connector Selection

The wizard suggests a default connector based on:

1. **Environment Detection:**
   - `VAULT_ADDR` -> HashiCorp Vault
   - `CONSUL_HTTP_ADDR` -> Consul KV
   - `ETCD_ENDPOINTS` -> etcd
   - Azure IMDS -> Azure Key Vault / Azure App Configuration
   - AWS metadata -> AWS Secrets Manager / AWS Parameter Store
   - `GITHUB_TOKEN` -> GitHub
   - `GITLAB_TOKEN` -> GitLab

2. **Configuration Files:**
   - Existing `etc/*.yaml` samples
   - Docker Compose environment files

3. **Repository Defaults:**
   - Harbor (most commonly used registry)
   - Slack (most common notification)

### 5.3 Last Selected Connector Persistence

The wizard stores user preferences in the settings store:

```json
{
  "setupWizard": {
    "lastConnectors": {
      "vault": "hashicorp-vault",
      "settingsstore": "consul-kv",
      "scm": "github-app",
      "registry": "harbor",
      "notifications": "slack"
    },
    "completedAt": "2026-01-13T10:30:00Z",
    "skippedSteps": ["identity", "feeds"]
  }
}
```

---

## 6. Resume/Re-run Behavior

### 6.1 Idempotency Requirements

All steps must be safe to re-run:

| Step | Re-run Behavior |
|------|-----------------|
| `database` | Verify connection; no changes if already configured |
| `migrations` | Skip already-applied; apply only pending |
| `admin` | Skip if admin exists; offer password reset |
| `vault` | Add new integration; don't duplicate |
| `settingsstore` | Add new integration; don't duplicate |
| `scm` | Add new integration; don't duplicate |

### 6.2 Configuration Pane Access

After initial setup, the wizard is available from:
- **CLI:** `stella setup --reconfigure`
- **UI:** Settings > Configuration Wizard

Pre-populated with:
- Current configuration values
- Last selected connector per category
- Health status from Doctor checks

---

## 7. Security Posture

### 7.1 Secret Storage

| Secret Type | Storage Location |
|-------------|------------------|
| Database password | Vault (if configured) or local keyring |
| Valkey password | Vault (if configured) or local keyring |
| API tokens | Vault integration |
| Private keys | File system with 0600 permissions |

### 7.2 Redaction Rules

The wizard must never display:
- Full passwords
- API tokens
- Private key contents
- Vault tokens

Display format for sensitive fields:
- Masked: `********`
- Partial: `ghp_****1234` (first 4 + last 4)

### 7.3 Audit Trail

All wizard actions are logged to:
- Timeline service with HLC timestamps
- Authority audit log for admin operations
- Doctor run history for check results

---

## 8. Error Handling

### 8.1 Validation Errors

| Error Type | Behavior |
|------------|----------|
| Invalid input | Inline error message; prevent progression |
| Connection failure | Show error; offer retry with different params |
| Permission denied | Show required permissions; offer skip (if skippable) |
| Timeout | Show timeout; offer retry with increased timeout |

### 8.2 Partial Completion

If wizard exits mid-flow:
- Completed steps are persisted
- Resume shows current state
- Doctor checks identify incomplete setup

---

## 9. Exit Criteria

### 9.1 Successful Completion

The wizard completes successfully when:
- All required steps pass Doctor checks
- User has explicitly skipped or completed all steps
- Operational threshold is met

### 9.2 Completion Actions

On completion:
1. Run full Doctor diagnostic
2. Generate setup report (Markdown)
3. Emit `setup.completed` timeline event
4. Clear first-run flag
5. Redirect to dashboard (UI) or exit with success (CLI)