docs: module dossier + install/quickstart sync for truthful cutover sprints

- API_CLI_REFERENCE.md, INSTALL_GUIDE.md, quickstart.md, architecture/integrations.md, dev/DEV_ENVIRONMENT_SETUP.md, integrations/LOCAL_SERVICES.md: reflect real-service wiring.
- docs/modules/**: module dossier updates across the modules touched by SPRINT_20260415_001..007 + SPRINT_20260416_003..017 + SPRINT_20260417_018..024 + SPRINT_20260418_025 + SPRINT_20260419_026.
- docs/features/checked/web/**: update feature notes where UI changed.
- docs/qa/feature-checks/runs/web/evidence-presentation-ux/: QA evidence artifacts.
- docs/setup/**, docs/technical/**: align with setup wizard contracts.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
master
2026-04-19 14:45:09 +03:00
parent ad62ba7f76
commit fdf95e0f46
67 changed files with 590 additions and 360 deletions

View File

@@ -7,7 +7,7 @@ This document defines the functional requirements for the Stella Ops Setup Wizar
The Setup Wizard provides a guided, step-by-step configuration experience that:
- Validates infrastructure dependencies (PostgreSQL, Valkey)
- Runs database migrations
- Bootstraps the initial admin and crypto profile
- Bootstraps the initial admin, crypto 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
@@ -57,8 +57,9 @@ The system reaches "Production-Ready" state when:
| `migrations` | Database Migrations | Yes | No | Infrastructure |
| `admin` | Admin Bootstrap | Yes | No | Security |
| `crypto` | Crypto Profile | Yes | No | Security |
| `sources` | Advisory & VEX Sources | No | Yes | Data |
Only these five core steps are current runtime setup step IDs. The integration and orchestration catalogs below are historical handoff targets and are no longer accepted by the current setup APIs or `stella setup` command group.
Current runtime setup step IDs now include the five required control-plane steps plus the optional `sources` step. The integration and orchestration catalogs below are historical handoff targets and are no longer accepted by the current setup APIs or `stella setup` command group.
### 3.2 Integration Handoffs (Not current setup steps)
@@ -77,13 +78,11 @@ Only these five core steps are current runtime setup step IDs. The integration a
|---------|------|----------|-----------|----------|
| `environments` | Environment Definition | No | Yes | Orchestration |
| `agents` | Agent Registration | No | Yes | Orchestration |
| `feeds` | Vulnerability Feeds | No | Yes | Data |
---
## 4. Step Specifications
Sections 4.1-4.5 describe the current installation-scoped setup steps. Sections 4.6 and later remain useful as onboarding capability notes, but those inputs now belong to authenticated post-bootstrap surfaces rather than the setup wizard step catalog.
Sections 4.1-4.5 and 4.5.1 describe the current installation-scoped setup steps. Sections 4.6 and later remain useful as onboarding capability notes, but those inputs now belong to authenticated post-bootstrap surfaces rather than the setup wizard step catalog.
### 4.1 Database Setup (`database`)
@@ -226,6 +225,39 @@ Sections 4.1-4.5 describe the current installation-scoped setup steps. Sections
---
### 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.
**Inputs:**
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| `mode` | enum | Yes | `mirror` | `mirror` enables StellaOps Mirror only; `manual` exposes explicit source selection |
| `mirror.url` | string | Required when `mode=mirror` | `https://mirror.stella-ops.org` | StellaOps Mirror base URL |
| `mirror.apiKey` | secret | No | - | Optional StellaOps Mirror API key |
| `enabled` | string[] | Required when `mode=manual` | `[]` | Advisory/VEX source IDs to enable |
**Outputs:**
- Selected sources are persisted through Concelier durable source storage
- `mirror` mode enables only `stella-mirror`
- `manual` mode enables only the explicitly selected upstream sources
- Initial aggregation is scheduled for newly enabled sources
**Validation:**
- Mirror URL must be an absolute URI
- Manual mode must select at least one real source
- `stella-mirror` is reserved for mirror mode and cannot be mixed into manual selections
**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.6 Vault Integration (`vault`)
**Purpose:** Configure secrets management provider.
@@ -481,7 +513,7 @@ The wizard stores user preferences in the settings store:
"notifications": "slack"
},
"completedAt": "2026-01-13T10:30:00Z",
"skippedSteps": ["identity", "feeds"]
"skippedSteps": ["identity", "sources"]
}
}
```

View File

@@ -28,17 +28,34 @@ design material later in this document.
- The implemented UI bootstrap flow persists authoritative installation-scoped
state in `platform.setup_sessions`.
- On a completed installation, anonymous entry to `/setup-wizard/*` no longer
pretends bootstrap is still open. The first setup-session create/read returns
`401`, then the same route can continue as an authenticated reconfiguration
session once the operator signs in.
- Fresh compose bootstrap no longer pre-seeds `SetupComplete=true`; a clean
local database now lands in the setup wizard until the control-plane steps
are actually finalized. Legacy local volumes are auto-converged by Platform
release migration `064_EnvironmentSettingsInstallationScopeConvergence.sql`.
- The current live step inventory is limited to the five control-plane steps
the running platform can truthfully validate and converge:
`database`, `cache`, `migrations`, `admin`, and `crypto`.
- The `admin` step now seeds the same local standard-provider and superuser
defaults into wizard draft state that it renders in the visible form, so an
operator can accept the prefilled values without retyping them and still get
a truthful backend apply.
- The current live step inventory includes the five required control-plane
steps the running platform can truthfully validate and converge plus one
optional data-onboarding step:
`database`, `valkey`, `migrations`, `admin`, `crypto`, and `sources`.
- The `sources` step defaults to StellaOps Mirror only. Operators can switch
to manual advisory/VEX feed selection or skip the step explicitly.
- Skipping `sources` leaves advisories and VEX off. The Advisory & VEX Sources
integrations page then surfaces that disabled state and offers a one-click
StellaOps Mirror enable path without rerunning bootstrap.
- Using `sources` now performs a live reachability check of the selected
mirror/source configuration before the step can complete. Operators must
fix the mirror URL or skip the step if the endpoint is unreachable.
- Local browser automation may ignore local dev certificates, but product
advisory aggregation still requires a hostname-valid certificate and will
report TLS/certificate failures directly in the setup step and integrations
UI.
- The `admin` step now seeds only non-secret local standard-provider and
superuser defaults into wizard draft state. Username and email can stay
prefilled, but the operator must deliberately enter the initial admin
password instead of inheriting a baked-in demo value.
- Session reads now separate sanitized `draftValues` from `secretDrafts`
metadata. Secret-bearing inputs such as admin or database passwords are
retained only in protected server-side companion storage, can survive resume,
@@ -50,8 +67,11 @@ design material later in this document.
installation-scoped setup session APIs rather than a separate local state
machine.
- Repeatable tenant onboarding work such as integrations, notifications,
advisory sources, environments, agents, and branding lives on `/setup/*`
and other authenticated module surfaces, not inside the bootstrap wizard.
environments, agents, and branding lives on `/setup/*` and other
authenticated module surfaces, not inside the bootstrap wizard.
- Advisory/VEX onboarding is the one intentional exception: the wizard can
seed initial source configuration because it directly governs whether
aggregation starts at all on a fresh install.
- Secret material is no longer an out-of-band prerequisite for GitLab-class UI
onboarding. The Integrations Hub can stage credentials through the Secret
Authority API and then bind the returned `authref://...` URI to the created
@@ -678,6 +698,7 @@ When the system detects first-run (no database connection or admin user):
| `migrations` | Database Migrations | Apply schema updates |
| `admin` | Admin Bootstrap | Create administrator account |
| `crypto` | Crypto Profile | Configure signing keys |
| `sources` | Advisory & VEX Sources | Enable StellaOps Mirror or manual feeds |
| `vault` | Vault Integration | Configure secrets management |
| `scm` | SCM Integration | Connect source control |
| `notifications` | Notification Channels | Configure alerts and notifications |