Setup Wizard - Capability Specification

Audience: engineers and product owners implementing or extending the Stella Ops Setup Wizard across the CLI and Console. For the user-facing flow, see setup-wizard-ux.md; for the validation/remediation contract, see setup-wizard-doctor-contract.md.

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

Source of truth (verified against src/). The backend-authoritative step contract is SetupStepDefinitions.All in src/Platform/StellaOps.Platform.WebService/Contracts/SetupWizardModels.cs. It defines exactly six steps: Database, Valkey, Migrations, Admin, Crypto (required) and Sources (optional). The Platform setup API (SetupEndpoints.cs) and PlatformSetupService.ProbeStepCoreAsync reject any other step id with “is not part of the installation bootstrap contract”. Sections in this doc that describe additional steps (Vault, Settings Store, SCM, Registry, Notifications, Identity, Environments, Agents, Assurance) are onboarding/handoff capability notes, not setup-wizard steps — they are not accepted by the current setup APIs or the stella setup command group. Where this doc disagrees with the code, the code wins.

1. Overview

The Setup Wizard provides a guided, step-by-step configuration experience that:

• Validates infrastructure dependencies (PostgreSQL, Valkey)
• Runs database migrations
• Bootstraps the initial admin, crypto/compliance profile, and optional advisory/VEX source configuration
• Exposes a truthful required-readiness summary for setup completion
• Hands tenant onboarding to authenticated /setup/* and integration command surfaces instead of pretending they are bootstrap steps

2. Completion Thresholds

2.1 Operational (Minimum Required)

The system enters “Operational” state when the required platform dependencies report ready. PlatformHealthService.BuildReadinessAsync (src/Platform/StellaOps.Platform.WebService/Services/PlatformHealthService.cs) builds the readiness summary from five setup-step-derived dependencies plus two live HTTP probes, and PlatformSetupService.FinalizeSessionAsync blocks finalize unless ReadyToProceed is true (or Force=true):

Reconciled: the previous “Doctor Check” column listed IDs such as check.services.core.healthy, check.crypto.profile.valid, and check.auth.admin.exists. These are not the IDs emitted by the setup probes, and the readiness gate is not a Doctor-plugin run — it is the step-derived dependency summary above. Setup-step Doctor check IDs are listed per step in §4; the Doctor module’s own catalog (src/Doctor/**) uses unrelated namespaces (check.agent.*, check.scanner.*, check.notify.*, …).

Gating Behavior: Setup status and finalize gate only on this operational threshold. Optional post-boot services may still be degraded and are surfaced through health diagnostics instead of blocking bootstrap completion.

2.2 Production-Ready (Recommended)

Roadmap / out of scope for the wizard. None of the items below are required-readiness signals in the current code, and none of the check.* IDs in this table exist in src/. They describe operator best-practice that is configured through authenticated post-bootstrap surfaces (Integrations, Identity & Access, Notifications, Trust & Signing, Orchestrator), not the setup wizard. Treat this section as a hardening checklist, not a contract.

A production deployment is typically configured with:

3. Step Catalog

3.1 Core Steps

The backend-authoritative inventory is SetupStepDefinitions.All (SetupWizardModels.cs). It is exactly the following six steps; the API projects these (and only these) to the Console and CLI:

Notes verified against src/:

• The frontend step id for the Valkey step is cache(see ToFrontendStepId / TryParseStepId in SetupEndpoints.cs); the SetupStepId enum value is Valkey.
• The Web wizard model (setup-wizard.models.ts) exposes a welcome introductory step in createTruthfulSetupSteps(); it carries no validation checks and is not a backend step.
• There is no assurance step. It is absent from SetupStepDefinitions.All, from the Web SetupStepId union, and from the CLI SetupStepCatalog. The assurance rows and the check.assurance.* identifiers previously documented here do not exist in code — see §4.5.2.

The integration and orchestration catalogs below are historical handoff targets and are not accepted by the current Platform setup API (PlatformSetupService.ProbeStepCoreAsync rejects them) nor surfaced by the stella setup command group’s backend-authoritative flow.

3.2 Integration Handoffs (Not current setup steps)

The Platform backend rejects these step ids. Note that the CLI still ships matching ISetupStep implementations in src/Cli/StellaOps.Cli/Commands/Setup/Steps/Implementations/ (e.g. VaultSetupStep, ScmSetupStep, NotifySetupStep, RegistrySetupStep, SettingsStoreSetupStep, LlmSetupStep, TelemetrySetupStep), and the Web DEFAULT_SETUP_STEPS fallback list still enumerates them — but Identity as a standalone step is not in either inventory (OIDC/LDAP is configured via the authority/admin provider selection and post-bootstrap Identity & Access surfaces).

3.3 Orchestration Handoffs (Not current setup steps)

The Platform backend rejects these step ids. The CLI registers EnvironmentsSetupStep / AgentsSetupStep and the Web DEFAULT_SETUP_STEPS fallback enumerates them, but they are not part of the backend bootstrap contract.

4. Step Specifications

Sections 4.1–4.5.1 describe the current installation-scoped setup steps that the Platform API accepts (Database, Valkey, Migrations, Admin, Crypto, Sources). §4.5.2 (Assurance) is not a step — see the annotation there.

Sections 4.6 and later are capability notes, not Platform setup steps. The Platform API rejects these step ids (ProbeStepCoreAsync → “is not part of the installation bootstrap contract”). Their inputs belong to: (a) the CLI setup steps under src/Cli/StellaOps.Cli/Commands/Setup/Steps/Implementations/, which the CLI runner can execute independently, and (b) authenticated post-bootstrap surfaces (Integrations, Notify, Trust & Signing, Identity & Access, ReleaseOrchestrator). Field/connector tables below were not re-verified line-by-line against each connector implementation; treat them as design reference, and verify against the owning module before relying on a specific field name or default.

4.1 Database Setup (database)

Purpose: Configure PostgreSQL connection and verify accessibility.

Inputs (config keys consumed by ProbeDatabaseAsync / ResolveDatabaseConnectionString):

When no override is supplied, the probe falls back to the platform’s configured Platform:Storage:PostgresConnectionString.

Reconciled: the previously documented sslMode and poolSize inputs are not read by the setup probe (the discrete-field fallback builds Host=…;Port=…;Database=…;Username=…;Password=…;Timeout=5). SSL/pool tuning is a machine-bootstrap connection-string concern.

Outputs / Validation (reconciled):

• Opens an NpgsqlConnection and reads PostgreSqlVersion (this is the connectivity + version check). There is no SELECT 1, no settings-store write of the connection string, and no CREATE SCHEMA permission probe in the current code.

Doctor Checks:

• Step definition (SetupStepDefinitions) declares: check.database.connectivity, check.database.permissions, check.database.version.
• Probe (ProbeDatabaseAsync) actually emits: check.database.connectivity and check.database.version (reports the server version; it does not gate on >= 16 and does not run a separate check.database.permissions probe — connectivity opens an NpgsqlConnection).

Persistence (reconciled):

• The wizard does not persist the database connection string from the step. ApplyStepCoreAsync for Database returns “PostgreSQL connectivity verified. Runtime database configuration remains a machine bootstrap concern.” The connection string is resolved from Platform:Storage:PostgresConnectionString (machine bootstrap), with optional in-session override fields (database.host/port/database/user/password) used only for the probe.
• Sensitive draft values (anything matching password/secret/token/*.connectionstring) are stored via PlatformSetupSecretStore, never echoed back, and stripped from applied config.

4.2 Valkey/Redis Setup (valkey)

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

Inputs (config keys consumed by ProbeCacheAsync):

Reconciled: the previously documented password, database, useTls, and abortOnConnectFail inputs are not read by the setup probe. The quick-check path additionally derives cache.host/cache.port from the runtime ConnectionStrings:Redis / Router:Messaging:valkey:ConnectionString / STELLAOPS_VALKEY_URL values (BuildCacheConfigFromRuntime).

Outputs / Validation (reconciled):

• Performs a raw TCP ConnectAsync to host:port. There is no AUTH, no PING command, and no connection-string write to the settings store. Apply returns “Cache connectivity verified. Runtime cache configuration remains a machine bootstrap concern.”

Doctor Checks:

• check.services.valkey.connectivity (the only check emitted; the previously documented check.services.valkey.ping does not exist)

4.3 Database Migrations (migrations)

Purpose: Converge the required platform schemas (no pending startup or release migrations).

Inputs (reconciled):

• The migrations step takes no operator inputs. ProbeMigrationsAsync / ApplyMigrationsAsync operate over a fixed set RequiredMigrationModules = ["Platform", "ReleaseOrchestrator"] and call migrationAdminService.RunAsync(module, category: null, dryRun: false, timeoutSeconds: null).
• The previously documented modules, dryRun, and force inputs are not part of the setup contract.

Behavior:

• Probe: for each required module, reads status and fails if PendingReleaseCount + PendingStartupCount > 0 or there are checksum errors.
• Apply: runs the migration for any module with pending migrations, then re-reads status to confirm convergence. (Migrations is the one step where apply runs even if the probe reported pending — running it is the corrective action.)

Doctor Checks (reconciled):

• Step definition declares: check.database.migrations.pending.
• Probe emits: check.database.migrations.pending (and check.database.migrations.module when a module is missing).
• Apply emits: check.database.migrations.applied.
• The previously documented check.database.migrations.checksums and check.database.schema.version are not emitted; checksum errors are reported through the pending/applied checks.

4.4 Admin Bootstrap (admin)

Purpose: Ensure the bootstrap administrator exists via the Authority service.

Inputs (config keys consumed by ProbeAdminAsync / ApplyAdminAsync):

Behavior:

• Apply POSTs the super user to the Authority internal endpoint internal/users with Roles: ["admin"] and RequirePasswordReset: false (via the AuthorityInternal HTTP client).
• Provider normalization: the wizard surfaces the built-in local provider as sql (SQL / Local Users), but Authority registers that plugin under the descriptor name standard (devops/etc/authority.yaml → plugins.descriptors.standard, defaultIdentityProvider: "standard"). Apply maps sql/local/standard → standard before forwarding; an empty value defers to Authority’s DefaultIdentityProvider. Without this, the bootstrap fails with Specified identity provider was not found..
• Additional users: each non-empty users.additional.{i} row is provisioned with its own internal/users POST carrying Roles: [<role>] (default role/service-release-contributor). A row with a username but no password fails the step with a clear message; empty rows are skipped.

Validation (reconciled):

• Username, email, and password are required (presence checks).
• Password minimum length is 12 characters — that is the only complexity rule enforced here. The previously documented “mixed case, numbers, symbols” rule and the “email format” / “username uniqueness” checks are not enforced by the setup probe (uniqueness/idempotency is delegated to Authority’s internal/users endpoint).
• The probe also calls the Authority health endpoint before declaring readiness.

Doctor Checks:

• check.auth.admin.exists and check.auth.password.policy (payload validation).
• check.authority.admin.exists (Authority health probe; this is also the single check id declared in the step definition).

4.5 Cryptography (crypto)

Purpose: Choose a regional cryptography profile and prepare optional compliance evidence support (NIS2 / DORA / CRA). This is a required step in the backend contract (the Web shell labels it “Compliance” and treats it as the final touch after the other required steps).

Reconciled — this step does not configure signing keys. The previously documented profileType (local/kms/hsm/sigstore), keyAlgorithm, keyId, certificatePath, privateKeyPath inputs, the “key material accessible / certificate chain valid” validation, and the check.crypto.profile.valid / check.crypto.signing.test checks do not exist in ProbeCryptoAsync / ApplyCryptoAsync / ResolveCryptoSettingsAsync. The step writes a regional profile + compliance flags to the environment settings store; signing-key material is a Trust & Signing / Signer concern outside the setup wizard.

Inputs (config keys consumed by ResolveCryptoSettingsAsync):

When a compliance flag is enabled, the probe additionally looks for prerequisite settings and emits warnings (not failures) if they are missing — e.g. NIS2 checks for an Authority compliance-profile URL, DORA for a Notify channel, CRA for a manufacturer mailbox + intake key fingerprint.

Note: the Web CRYPTO_PROVIDERS catalog also lists a korean (KCMVP) profile and marks russian as disabled under European Edition. The backend NormalizeCryptoRegion currently maps to international/eidas/russian/chinese only — korean is a frontend-only option pending backend support.

Outputs:

• ApplyCryptoAsync writes the canonical settings (Crypto:Region, Crypto:FipsMode, Compliance:Nis2:Enabled, Compliance:Dora:Enabled, Compliance:Cra:Enabled) to the environment settings store.

Doctor Checks (reconciled):

• check.crypto.profile — selected regional profile.
• check.crypto.fips — FIPS-140 mode state (warns if enabled for a non-International profile).
• check.compliance.nis2.prerequisites
• check.compliance.dora.prerequisites
• check.compliance.cra.prerequisites

4.5.1 Advisory & VEX Sources (sources)

Purpose: Optionally enable advisory and VEX aggregation during bootstrap without forcing operators through the full integrations catalog on first run.

Flow: The Platform step is a thin pass-through. ProbeSourcesAsync / ApplySourcesAsync forward the sources.*-prefixed config to Concelier’s internal setup endpoints (POST internal/setup/advisory-sources/probe and /apply, retried while Concelier reports transient 502/503/504), which own source validation and persistence (ConfiguredAdvisorySourceService).

Inputs (config keys, sources.-prefixed at the wire — verified in Concelier ConfiguredAdvisorySourceService):

Reconciled: the previous unprefixed names (mode, mirror.url, …) are the conceptual fields; the wire keys are sources.*. Only sources.* keys are forwarded by FilterConfigForStep(Sources, …).

Outputs:

• Selected sources are persisted through Concelier durable source storage (mirror id is stella-mirror)
• mirror mode enables only stella-mirror
• manual mode enables only the explicitly selected upstream sources

Validation (enforced in Concelier):

• Mirror URL is normalized/validated as an absolute URI
• Manual mode must select at least one real source
• stella-mirror is reserved for mirror mode

Doctor Checks:

• check.sources.feeds.configured
• check.sources.feeds.connectivity

Skip behavior:

• Skipping this optional step leaves advisory and VEX aggregation off
• The integrations Advisory & VEX Sources page must surface that off-state and offer later enablement without rerunning bootstrap

4.5.2 Assurance Packs (assurance) — NOT IMPLEMENTED as a setup step

NOT IMPLEMENTED. There is no assurance setup step. It is absent from the backend SetupStepDefinitions.All, from the Web SetupStepId union and DEFAULT_SETUP_STEPS, and from the CLI SetupStepCatalog. The check.assurance.packs.optional, check.assurance.nis2.soa.prerequisites, and check.assurance.cra.publication.preflight identifiers do not appear anywhere in src/. The wizard does not probe, apply, skip, or report assurance-pack state.

What does exist: (1) the Crypto step (§4.5) carries the optional NIS2 / DORA / CRA compliance evidence enable flags and their prerequisite warnings; (2) Assurance Packs are a post-bootstrap capability surfaced by the Console Compliance feature (src/Web/StellaOps.Web/src/app/features/compliance/**, assurance-packs.client.ts) and routed through Authority / ExportCenter / Notify / Trust / /assurance. The text below is retained only as a forward- looking description of that post-setup capability — it is not a setup-wizard contract.

Intended post-bootstrap behavior (roadmap / Compliance surfaces, not the wizard):

• No Assurance pack is enabled by default; review is non-blocking.
• Enabling a pack configures evidence support and workflow readiness. It is not a legal compliance certification.
• Operators are routed to Authority, ExportCenter, Notify, Trust, and /assurance surfaces.

Pack lines (capability notes):

4.6 Vault Integration (vault)

Purpose: Configure secrets management provider.

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

Connector Options:

Inputs (HashiCorp Vault):

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:

Inputs (Consul KV):

Inputs (etcd):

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:

Inputs (GitHub App):

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:

Inputs (Slack):

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:

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:

Outputs:

• Registration token (one-time, 24-hour expiry)
• Agent installation command

Generated Command:

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

Scope note: the multi-connector model below applies to the CLI/integration connector catalogs and post-bootstrap Integrations surfaces, not to the six-step Platform setup contract. The Platform setup session stores draft values and secret-draft metadata per step (SetupSession.DraftValues / SecretDrafts); it does not implement per-category connector instances or lastConnectors preference persistence. Treat instance limits and selection heuristics as design intent unless verified in the owning module.

5.1 Connector Categories

Each integration category supports multiple instances:

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:

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

Reconciled: identity is not a setup step, so it cannot appear in skippedSteps (only the optional sources step is skippable in the Platform contract). This lastConnectors shape is illustrative for the connector catalogs; the Platform setup session does not persist it.

6. Resume/Re-run Behavior

6.1 Idempotency Requirements

All steps must be safe to re-run:

6.2 Re-run and Reconfigure Access (reconciled)

The CLI setup command group (SetupCommandGroup.cs) exposes these subcommands — there is no --reconfigure flag:

• stella setup run — run from the beginning or continue from the last checkpoint (--step <database|cache|migrations|admin|crypto>, --skip <step…>, --dry-run, --force to re-run completed steps, --config, --non-interactive/-y).
• stella setup resume [--session <id>]
• stella setup status [--session <id>] [--json]
• stella setup reset [--step <id> | --all] [--force]
• stella setup validate --config <path>

On the server side, re-running is supported because steps are idempotent and a session can be re-created with ForceRestart (preserving prior draft values). The Console exposes the wizard at the setup-wizard route; “Settings > Configuration Wizard” is descriptive, not a verified menu label.

7. Security Posture

7.1 Secret Storage

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 (reconciled)

Mutating setup endpoints are decorated with .Audited(AuditModules.Platform, AuditActions.Platform.<action>, "setup") — e.g. CreateSetupSession, ExecuteSetupStep, SkipSetupStep, FinalizeSetup (see SetupEndpoints.cs). Admin bootstrap is performed through the Authority internal/users endpoint, so the admin-creation audit lives in Authority.

Reconciled: the previously documented “Timeline service with HLC timestamps” and “Doctor run history for check results” are not the mechanism for setup-action auditing in the current code. Setup uses the Platform audit emission decorator above.

8. Error Handling

8.1 Validation Errors

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

FinalizeSessionAsync completes the session (Completed) only when:

• All required steps (Database, Valkey, Migrations, Admin, Crypto) are Passed, otherwise finalize throws unless Force=true.
• The platform readiness summary reports ReadyToProceed (required dependencies ready), otherwise finalize throws with the blocking dependencies unless Force=true.

A skipped optional Sources step does not block completion.

9.2 Completion Actions (reconciled)

On finalize success, the code performs:

1. Mark the session Completed (sets CompletedAtUtc).
2. Delete the session’s secret drafts (secretStore.DeleteSessionAsync).
3. Write SetupComplete=true to the environment settings store and invalidate the cache, so /platform/envsettings.json reports setup: "complete" and the frontend stops redirecting to the wizard.
4. Return nextSteps pointing to /setup/integrations and the Secrets/Integrations surfaces (restartRequired: false).

Reconciled / NOT IMPLEMENTED: the finalize path does not run a full Doctor diagnostic, does not generate a Markdown setup report (FinalizeSetupSessionResponse.ReportPath is null), and does not emit a setup.completed timeline event. Completion is signalled by the SetupComplete env-settings flag (SetupStateDetector.SetupCompleteKey). A separate POST /api/v1/setup/quick-check shortcut probes database/cache/migrations/authority and sets the same flag without walking the wizard.

Related Documents

• setup-wizard-ux.md — user-experience flows for the CLI and Console wizard (the canonical UX boundary).
• setup-wizard-doctor-contract.md — per-step validation, check IDs, and remediation guidance.
• setup-wizard-inventory.md — orientation map of the setup-related source under src/.
• setup-wizard-sprint-plan.md — implementation plan and milestones.