Finalize UI truthfulness and bootstrap hardening

docs/modules/platform/platform-service.md

@@ -25,9 +25,13 @@ Provide a single, deterministic aggregation layer for cross-service UX workflows
 
 ### Health aggregation
 - GET `/api/v1/platform/health/summary`
+- GET `/api/v1/platform/health/readiness`
 - GET `/api/v1/platform/health/dependencies`
 - GET `/api/v1/platform/health/incidents`
 - GET `/api/v1/platform/health/metrics`
+- `GET /api/v1/platform/health/readiness` is the canonical readiness contract for both setup gating and post-boot diagnostics.
+- Required setup-blocking dependencies currently include the five converged setup steps (`database`, `cache`, `migrations`, `admin-bootstrap`, `crypto-profile`) plus live `frontdoor` and `authority` probes.
+- Optional post-boot dependencies are discovered from configured `STELLAOPS_*_URL` endpoints and currently include `release-orchestrator`, `policy-engine`, `scanner`, `signals`, `notify`, `scheduler`, `registry-token`, `sbomservice`, `packsregistry`, and `advisoryai`.
 
 ### Quota aggregation
 - GET `/api/v1/platform/quotas/summary`
@@ -162,7 +166,7 @@ Provide a single, deterministic aggregation layer for cross-service UX workflows
 - `release.topology_workflow_inventory` (workflow template projection for topology routes)
 - `release.topology_gate_profile_inventory` (gate profile projection bound to region/environment inventory)
 - `release.topology_sync_watermarks` (projection synchronization watermark state for deterministic replay/cutover checks)
-- Schema reference: `docs/db/schemas/platform.sql` (PostgreSQL; in-memory stores used until storage driver switches).
+- Schema reference: `docs/db/schemas/platform.sql` (PostgreSQL; in-memory stores are `Testing`-only harnesses).
 
 ## Dependencies
 - Authority (tenant/user identity, quotas, RBAC)
@@ -268,9 +272,20 @@ Current runtime behavior:
   Migration `064_EnvironmentSettingsInstallationScopeConvergence.sql` upgrades
   older compose-created tables that still used the legacy `(tenant_id, key)`
   primary key.
-- The persisted store keeps only non-sensitive draft configuration plus step
-  state, timestamps, and check results. Secret material is still expected to be
-  staged through a secret authority rather than stored in wizard session state.
+- The persisted session document keeps only non-sensitive `draftValues` plus
+  step state, timestamps, and check results.
+- Sensitive step inputs retained for resume/apply are stored separately in
+  `platform.setup_session_secrets` via migration
+  `066_PlatformSetupSessionSecrets.sql`. Session reads expose only
+  `secretDrafts` metadata (`key`, `stepId`, `updatedAtUtc`), never plaintext.
+- Probe/apply hydrate retained setup secrets server-side, and finalize deletes
+  the retained secret records for the completed session.
+- Setup session reads now also include a required-only readiness snapshot so
+  CLI and UI status flows can show operational blockers without treating
+  optional post-boot services as setup failures.
+- Setup secret protection key precedence is
+  `Platform:Setup:SecretProtectionKey`,
+  `STELLAOPS_SECRETS_ENCRYPTION_KEY`, then `STELLAOPS_BOOTSTRAP_KEY`.
 - The live wizard now owns only the five control-plane steps the running
   control plane can truthfully validate and converge: `database`, `cache`,
   `migrations`, `admin`, and `crypto`.
@@ -292,6 +307,11 @@ Current runtime behavior:
 - `POST /api/v1/setup/sessions/{sessionId}/finalize` - Finalize the current session with convergence checks
 - `POST /api/v1/setup/sessions/finalize` - Compatibility finalize path
 
+Session payloads distinguish:
+- `draftValues` - non-sensitive persisted config only
+- `secretDrafts` - retained-secret metadata only; no plaintext secret values
+- `readiness` - required-only operational readiness summary for installation bootstrap
+
 #### Steps
 - `POST /api/v1/setup/sessions/{sessionId}/steps/{stepId}/probe` - Run a diagnostic probe without completing the step
 - `POST /api/v1/setup/sessions/{sessionId}/steps/{stepId}/apply` - Apply the current step and persist the new state
@@ -354,9 +374,10 @@ to the authenticated onboarding surfaces instead.
 - After setup is marked complete, anonymous setup session reads and mutations
   return `401` and the normal authenticated `platform.setup.*` policies apply.
 - `Finalize` succeeds only after every required control-plane step has
-  converged.
+  converged and the required readiness dependencies are not blocked.
 
 ### Security and scopes
+- Health: `ops.health` (summary, readiness, dependencies, incidents), `ops.admin` (metrics)
 - Read: `platform.setup.read`
 - Write: `platform.setup.write`
 - Admin: `platform.setup.admin`