setup and mock fixes

2026-02-21 20:14:23 +02:00
parent 1edce73165
commit a29f438f53
29 changed files with 1624 additions and 721 deletions
--- a/docs/dev/DEV_ENVIRONMENT_SETUP.md
+++ b/docs/dev/DEV_ENVIRONMENT_SETUP.md
@@ -7,13 +7,13 @@ For hybrid debugging workflows and service-specific guides, see [`docs/DEVELOPER

 ## Quick Start (automated)

-Setup scripts validate prerequisites, start infrastructure, build solutions and Docker images, and launch the full platform.
+Setup scripts validate prerequisites, build solutions and Docker images, and launch the full platform.

 **Windows (PowerShell 7):**

 ```powershell
 .\scripts\setup.ps1              # full setup
-.\scripts\setup.ps1 -InfraOnly   # infrastructure only (PostgreSQL, Valkey, SeaweedFS, Rekor, Zot)
+.\scripts\setup.ps1 -InfraOnly   # infrastructure only (PostgreSQL, Valkey, SeaweedFS, Zot; Rekor is opt-in)
 .\scripts\setup.ps1 -SkipBuild   # skip .NET builds, build images and start platform
 .\scripts\setup.ps1 -SkipImages  # build .NET but skip Docker images
 .\scripts\setup.ps1 -ImagesOnly  # only build Docker images
@@ -31,6 +31,36 @@ Setup scripts validate prerequisites, start infrastructure, build solutions and

 The scripts will check for required tools (dotnet 10.x, node 20+, npm 10+, docker, git), warn about missing hosts file entries, and copy `.env` from the example if needed. See the manual steps below for details on each stage.

+### Quick validation + demo seed (first-run path)
+
+```powershell
+# 1) Bring platform up quickly (reuse existing images)
+.\scripts\setup.ps1 -SkipBuild -SkipImages
+
+# 2) Validate platform health
+docker compose -f devops/compose/docker-compose.stella-ops.yml ps
+
+# 3) Preview seed work
+dotnet run --project src/Cli/StellaOps.Cli/StellaOps.Cli.csproj -- `
+  admin seed-demo --dry-run `
+  --connection "Host=127.1.1.1;Port=5432;Database=stellaops_platform;Username=stellaops;Password=stellaops"
+
+# 4) Execute demo seeding
+dotnet run --project src/Cli/StellaOps.Cli/StellaOps.Cli.csproj -- `
+  admin seed-demo --confirm `
+  --connection "Host=127.1.1.1;Port=5432;Database=stellaops_platform;Username=stellaops;Password=stellaops"
+```
+
+### Known warnings vs blocking failures
+
+| Output | Class | Meaning | Action |
+|---|---|---|---|
+| `health=starting` (RustFS) | Warning | Service still warming up | Wait and recheck `docker compose ... ps` |
+| `SM remote service probe failed (localhost:56080)` | Warning | Optional SM remote provider is unavailable | Ignore unless validating China SM remote crypto profile |
+| `stellaops-dev-rekor restarting` without `--profile sigstore` | Warning | Optional Sigstore container from prior run | Ignore for default profile or remove stale container |
+| `policy ... scheduler_exceptions_tenant_isolation already exists` | Blocking | Outdated Scheduler migration idempotency | Update code and rerun seeding |
+| `POST /api/v1/admin/seed-demo` returns 500 after patching source | Blocking | Running stale platform container image | Rebuild/restart platform image |
+
 ---

 ## 1. Prerequisites
@@ -112,8 +142,8 @@ Infrastructure versions (from `docker-compose.dev.yml`):
 |---------|---------|----------|------|
 | PostgreSQL | 18.1 | `db.stella-ops.local` | 5432 |
 | Valkey | 9.0.1 | `cache.stella-ops.local` | 6379 |
-| SeaweedFS (S3) | -- | `s3.stella-ops.local` | 8080 |
-| Rekor v2 | -- | `rekor.stella-ops.local` | 3322 |
+| SeaweedFS (S3) | -- | `s3.stella-ops.local` | 8333 |
+| Rekor v2 (optional `sigstore` profile) | -- | `rekor.stella-ops.local` | 3322 |
 | Zot (OCI registry) | v2.1.3 | `registry.stella-ops.local` | 80 |

 ---
@@ -281,7 +311,31 @@ docker compose -f devops/compose/docker-compose.stella-ops.yml ps

 ---

-## 8. Hybrid debugging (quick reference)
+## 8. Seed demo data and verify endpoint errors
+
+Use the CLI seeder for local bootstraps and demo datasets:
+
+```powershell
+# dry-run
+dotnet run --project src/Cli/StellaOps.Cli/StellaOps.Cli.csproj -- `
+  admin seed-demo --dry-run `
+  --connection "Host=127.1.1.1;Port=5432;Database=stellaops_platform;Username=stellaops;Password=stellaops"
+
+# execute
+dotnet run --project src/Cli/StellaOps.Cli/StellaOps.Cli.csproj -- `
+  admin seed-demo --confirm `
+  --connection "Host=127.1.1.1;Port=5432;Database=stellaops_platform;Username=stellaops;Password=stellaops"
+```
+
+Seed API behavior (`POST /api/v1/admin/seed-demo`) now returns deterministic non-500 errors for expected failure modes:
+- `401/403` for auth policy failures (`platform.setup.admin`)
+- `503` when demo seeding is disabled (`STELLAOPS_ENABLE_DEMO_SEED=false`)
+- `400` for invalid module filters (for example, mixing `all` with specific modules)
+- `503` when database connection settings are missing
+
+---
+
+## 9. Hybrid debugging (quick reference)

 1. Start the full platform in Docker (section 7).
 2. Stop the container for the service you want to debug:
--- a/docs/implplan/SPRINT_20260221_042_FE_mock_data_to_real_endpoint_cutover.md
+++ b/docs/implplan/SPRINT_20260221_042_FE_mock_data_to_real_endpoint_cutover.md
@@ -120,7 +120,7 @@ Completion criteria:
 - [x] Runtime behavior uses tokenized API abstraction with real endpoint backing

 ### 042-T9 - Replace inline component mock datasets with backend loads
-Status: TODO
+Status: DONE
 Dependency: 042-T1, 042-T7, 042-T8
 Owners: Developer (FE)
 Task description:
@@ -128,8 +128,8 @@ Task description:
 - For surfaces lacking existing backend endpoints, mark task `BLOCKED` with explicit endpoint gap and keep temporary fallback isolated.

 Completion criteria:
- [ ] Runtime components prefer backend data and only use fallback when explicitly unavailable
- [ ] Any unresolved surfaces are tracked as `BLOCKED` with endpoint gap details
+- [x] Runtime components prefer backend data and only use fallback when explicitly unavailable
+- [x] Any unresolved surfaces are tracked as `BLOCKED` with endpoint gap details

 ### 042-T10 - Contract transformations, telemetry, and error semantics
 Status: TODO
@@ -156,7 +156,7 @@ Completion criteria:
 - [ ] E2E/API evidence confirms runtime uses real backend responses

 ### 042-T12 - Docs and contract ledger synchronization
-Status: TODO
+Status: DOING
 Dependency: 042-T1, 042-T11
 Owners: Documentation author, Developer (FE)
 Task description:
@@ -164,7 +164,7 @@ Task description:
 - Link doc updates in sprint Decisions & Risks and keep migration guidance deterministic/offline-aware.

 Completion criteria:
- [ ] `docs/modules/ui/**` and endpoint ledger reflect final binding reality
+- [x] `docs/modules/ui/**` and endpoint ledger reflect final binding reality
 - [ ] Sprint records unresolved gaps, decisions, and mitigation paths

 ## Execution Log
@@ -177,6 +177,9 @@ Completion criteria:
 | 2026-02-21 | Unblocked `web-checked-feature-recheck` by preventing `**/policy/**` route stubs from hijacking document navigations; full Playwright run completed with 222 passed, 187 skipped, 0 failed (`npx playwright test --workers=2 --reporter=list`). | QA / Developer (FE) |
 | 2026-02-21 | Completed runtime DI cutover for evidence/policy-simulation/proof plus store-level tokenization (delta verdict, risk budget, fix verification, scoring, ABAC) and removed runtime `useClass: Mock...`/`inject(Mock...)` paths in `src/Web/StellaOps.Web/src/app/**`. | Developer (FE) |
 | 2026-02-21 | Validation: `npm run build` passed; targeted specs passed: `npx ng test --watch=false --include=src/tests/audit_reason_capsule/findings-list.reason-capsule.spec.ts`, `npx ng test --watch=false --include=src/tests/triage/vex-trust-column-in-findings-and-triage-lists.behavior.spec.ts`, `npx ng test --watch=false --include=src/tests/policy_studio/policy-simulation.behavior.spec.ts`, `npx ng test --watch=false --include=src/tests/signals_runtime_dashboard/signals-runtime-dashboard.service.spec.ts`, `npx ng test --watch=false --include=src/tests/policy_governance/risk-budget-dashboard.component.spec.ts`. | Developer (FE) |
+| 2026-02-21 | 042-T9 completed for inline runtime datasets: `simulation-history.component.ts`, `conflict-detection.component.ts`, `batch-evaluation.component.ts`, and `graph-explorer.component.ts` now load backend data through `POLICY_SIMULATION_API` and `GRAPH_PLATFORM_API` instead of inline mocks; app config now binds graph runtime base/token providers. | Developer (FE) |
+| 2026-02-21 | Validation after T9 cutover: `npm run build` (with `NODE_OPTIONS=--max-old-space-size=6144`) passed; targeted tests passed: `npx ng test --watch=false --include=src/tests/policy_studio/policy-simulation.behavior.spec.ts --include=src/tests/signals_runtime_dashboard/signals-runtime-dashboard.service.spec.ts` and `npx ng test --watch=false --include=src/tests/security-risk/security-risk-routes.spec.ts --include=src/tests/security-risk/sbom-graph-page.component.spec.ts`. | Developer (FE) |
+| 2026-02-21 | T12 documentation sync started: updated `docs/modules/ui/README.md` with runtime endpoint cutover summary and updated `docs/modules/ui/v2-rewire/S00_endpoint_contract_ledger_v2_pack22.md` with Policy Simulation + Graph Explorer endpoint rows reflecting runtime bindings. | Developer / Documentation author |
 ## Decisions & Risks
 - Decision: runtime DI must resolve API tokens to HTTP clients; mock classes are test/dev assets only.
 - Decision: no new backend contracts are assumed in this sprint; if a required endpoint is missing, task becomes `BLOCKED` with explicit contract gap.
@@ -184,6 +187,8 @@ Completion criteria:
 - Risk: component-level `providers` can silently override global DI. Mitigation: inventory + explicit removal task (042-T7) with verification.
 - Risk: direct `inject(Mock...)` usage bypasses app config contracts. Mitigation: mandatory tokenized refactor task (042-T8).
 - Cross-module note: docs updates required in `docs/modules/ui/**` and endpoint ledger docs under `docs/modules/ui/v2-rewire/`.
+- `BLOCKED` endpoint gap: `src/Web/StellaOps.Web/src/app/features/releases/state/release-detail.store.ts` still uses inline mock state and `setTimeout` flows; the store is not yet mapped to a finalized release-detail endpoint contract in the Pack 22 ledger row `S22-T03-REL-02`.
+- `BLOCKED` endpoint gap: `src/Web/StellaOps.Web/src/app/features/lineage/components/lineage-why-safe-panel/lineage-why-safe-panel.component.ts` still returns inline mock explanations; a tokenized API client/contract for "why-safe" explanation is not yet present in `core/api/**` runtime bindings.

 ## Next Checkpoints
 - 2026-02-22 UTC: Complete T1 inventory and finalize endpoint mapping/risk list.
--- a/docs/implplan/SPRINT_20260221_043_DOCS_setup_seed_error_handling_stabilization.md
+++ b/docs/implplan/SPRINT_20260221_043_DOCS_setup_seed_error_handling_stabilization.md
@@ -0,0 +1,176 @@
+# Sprint 20260221_043 - Setup + Seed Error-Handling Stabilization
+
+## Topic & Scope
+- Stabilize local bootstrap so first-time setup succeeds deterministically without misleading health failures.
+- Fix demo seeding paths so expected failure modes return explicit API/CLI errors instead of HTTP 500 or opaque crashes.
+- Harden migration + seed workflow ordering to prevent schema-missing failures on fresh databases.
+- Improve onboarding docs for new operators with a minimal "first 30 minutes" path and troubleshooting matrix.
+- Working directory: `docs/implplan`.
+- Expected evidence: reproducible setup transcript, targeted test outputs, API response samples, updated docs with cross-links.
+
+## Dependencies & Concurrency
+- Depends on current compose baseline in `devops/compose/` and current seed SQL set under module persistence projects.
+- Can run in parallel:
+- Platform API error handling tasks can run in parallel with compose setup script fixes.
+- Docs updates can run in parallel with code fixes after API/CLI contracts are stable.
+- Must run sequentially:
+- Migration-ordering validation must complete before final seed API/CLI validation.
+- QA sign-off must run after all code + doc tasks are complete.
+
+## Documentation Prerequisites
+- `docs/quickstart.md`
+- `docs/dev/DEV_ENVIRONMENT_SETUP.md`
+- `docs/operations/devops/` (compose/bootstrap runbooks)
+- `docs/modules/platform/architecture-overview.md`
+- `docs/modules/cli/AGENTS.md` and relevant CLI docs
+- `docs/modules/scheduler/architecture.md`
+
+## Delivery Tracker
+
+### PM-001 - Scope lock and owner mapping
+Status: DONE
+Dependency: none
+Owners: Project Manager
+Task description:
+- Confirm final issue list from bootstrap + seeding runs and map each issue to an owning module/team.
+- Freeze acceptance criteria for setup reliability, seed API behavior, seed CLI behavior, and onboarding docs before coding starts.
+
+Completion criteria:
+- [x] Issue inventory is captured with owner + priority + target artifact.
+- [x] Exit criteria are explicit for each issue (pass/fail objective, no ambiguity).
+
+### DEVOPS-001 - Setup script reliability and health reporting fixes
+Status: DONE
+Dependency: PM-001
+Owners: Developer, Test Automation
+Task description:
+- Update setup smoke checks and health summary logic in `scripts/setup.ps1` to use active container names and avoid false negatives from duplicate compose scope checks.
+- Ensure setup output distinguishes blocking failures vs. advisory warnings.
+
+Completion criteria:
+- [x] Fresh reset + setup run completes without false "container missing" errors.
+- [x] Health summary reports exact unhealthy services with no duplicate/noisy entries.
+
+### PLATFORM-001 - Seed API authorization contract fix
+Status: DONE
+Dependency: PM-001
+Owners: Developer
+Task description:
+- Replace invalid seed endpoint authorization policy usage with a registered platform policy.
+- Ensure unauthorized/forbidden requests return 401/403, not 500.
+
+Completion criteria:
+- [x] `POST /api/v1/admin/seed-demo` no longer throws due to missing policy.
+- [x] Automated endpoint tests verify 401/403 behavior paths.
+
+### PLATFORM-002 - Seed API deterministic error responses
+Status: DONE
+Dependency: PLATFORM-001
+Owners: Developer, Test Automation
+Task description:
+- Harden seed endpoint request validation and operational error handling with structured ProblemDetails responses (bad module filter, disabled seeding, missing DB config, module execution failures).
+- Preserve partial module result visibility while preventing unhandled exceptions from surfacing as generic 500s.
+
+Completion criteria:
+- [x] Known error paths return deterministic status codes and machine-readable payloads.
+- [x] No unhandled exceptions are emitted for expected user/operator errors.
+
+### CLI-001 - Seed/migration CLI hardening for first-run flows
+Status: DONE
+Dependency: PM-001
+Owners: Developer
+Task description:
+- Improve CLI guidance and behavior so users can reliably run startup migrations before seed migrations on empty databases.
+- Fix dry-run reporting semantics so output correctly reflects pending seed migrations.
+- Eliminate seed command instability/crash regressions observed in repeated runs.
+
+Completion criteria:
+- [x] CLI clearly guides required sequence: startup migrations -> seed migrations.
+- [x] Dry-run output accurately reports discovered seed migrations.
+- [x] Repeated seed command runs are stable and idempotent.
+
+### SCHEDULER-001 - Scheduler startup migration idempotency repair
+Status: DONE
+Dependency: PM-001
+Owners: Developer, Test Automation
+Task description:
+- Fix `scheduler` startup migration trigger creation logic to be rerunnable without duplicate-trigger errors.
+- Add regression test coverage for rerun-on-existing-schema migration behavior.
+
+Completion criteria:
+- [x] Re-running scheduler startup migration on an initialized schema succeeds cleanly.
+- [x] Regression tests cover duplicate-trigger prevention.
+
+### DEVOPS-002 - Dev compose auxiliary service stability (rekor/rustfs)
+Status: DONE
+Dependency: PM-001
+Owners: Developer
+Task description:
+- Resolve `rekor-v2` restart-loop configuration and validate `rustfs` port/command consistency between compose profiles.
+- Ensure setup docs call out optional vs required auxiliary services where appropriate.
+
+Completion criteria:
+- [x] Dev compose profile no longer restart-loops for known default path.
+- [x] Service status after bootstrap is consistent with documented expectations.
+
+### QA-001 - End-to-end bootstrap + seed verification
+Status: DONE
+Dependency: DEVOPS-001
+Owners: QA, Test Automation
+Task description:
+- Run full verification pipeline on a clean environment:
+- from-scratch bootstrap,
+- startup migrations,
+- API-based seed checks,
+- CLI-based seed checks,
+- DB-level validation of seeded demo entities.
+- Capture command output snippets and API response payloads as evidence.
+
+Completion criteria:
+- [x] Tiered verification evidence confirms setup and seeding success.
+- [x] Expected error scenarios return documented structured responses.
+
+### DOCS-001 - New-operator onboarding hardening
+Status: DONE
+Dependency: PM-001
+Owners: Documentation author
+Task description:
+- Update quickstart/onboarding docs with:
+- explicit bootstrap sequence,
+- migration/seed sequence,
+- expected service states,
+- first login/demo exploration path,
+- troubleshooting decision tree for common failures.
+- Add a compact "known warnings vs blocking failures" section.
+
+Completion criteria:
+- [x] New operator can follow docs from clean clone to seeded demo state without tribal knowledge.
+- [x] Troubleshooting table covers observed failure modes from this sprint.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-02-21 | Sprint created to track setup, seed error handling, and onboarding stabilization planning. | Project Manager |
+| 2026-02-21 | Issue inventory and owner mapping finalized; implementation started with setup reliability fixes. | Project Manager |
+| 2026-02-21 | Setup reliability hardening completed (`scripts/setup.ps1`), including active-service health filtering and clean full-stack bootstrap behavior. | Developer |
+| 2026-02-21 | Seed API/CLI hardening completed with deterministic ProblemDetails responses, auth-path regression tests (`401/403`), and migration-ordering fixes. | Developer |
+| 2026-02-21 | Scheduler migration idempotency regressions fixed (`001` + `003`) with new rerun coverage; CLI demo seeding rerun succeeded. | Developer |
+| 2026-02-21 | Onboarding docs updated: `docs/quickstart.md`, `docs/dev/DEV_ENVIRONMENT_SETUP.md` with first-30-min path and troubleshooting matrix. | Documentation author |
+| 2026-02-21 | Rebuilt `stellaops/platform:dev`, restarted platform service, and verified live `POST /api/v1/admin/seed-demo` now returns `401 Unauthorized` (no stale-policy 500). | QA |
+
+## Decisions & Risks
+- Cross-module edits are expected for implementation despite this sprint living in `docs/implplan`: `scripts/`, `devops/compose/`, `src/Platform/`, `src/Cli/`, `src/Scheduler/`, and `docs/`.
+- Risk: seed endpoint contract changes may affect UI clients and automation expecting legacy response shape.
+- Mitigation: define and freeze ProblemDetails contract + success payload schema before implementation.
+- Risk: migration idempotency fixes can introduce drift against existing persisted schemas.
+- Mitigation: run replayable migration tests on both empty and already-initialized schemas.
+- Risk: compose auxiliary service hardening may differ across host OS networking stacks.
+- Mitigation: validate on Windows and Linux runners and document host-specific notes.
+- Risk: live docker stack may still return legacy behavior if local images were not rebuilt after source changes.
+- Mitigation: call out rebuild/restart requirement in troubleshooting docs and verification notes.
+- Risk: MTP currently ignores legacy `--filter` semantics in this repo's configuration.
+- Mitigation: capture full project run counts in evidence and validate targeted behavior with dedicated test classes.
+
+## Next Checkpoints
+- 2026-02-21: Sprint implementation complete; ready for maintainer review/merge.
+- 2026-02-22: Optional follow-up: rebuild/publish refreshed `stellaops/platform:dev` image to align live stack behavior with source patches.
--- a/docs/modules/ui/README.md
+++ b/docs/modules/ui/README.md
@@ -6,11 +6,20 @@

 > **Related:** See [`../web/`](../web/) for triage-specific UX documentation (Smart-Diff, Triage Canvas, Risk Dashboard).

-The Console presents operator dashboards for scans, policies, VEX evidence, runtime posture, and admin workflows.
-
-## Latest updates (2025-11-30)
- Docs refreshed per `docs/implplan/SPRINT_0331_0001_0001_docs_modules_ui.md`; added observability runbook stub and TASKS mirror.
- Access-control guidance from 2025-11-03 remains valid; ensure Authority scopes are verified before enabling uploads.
+The Console presents operator dashboards for scans, policies, VEX evidence, runtime posture, and admin workflows.
+
+## Latest updates (2026-02-21)
+- Runtime mock cutover completed for policy simulation history/conflict/batch flows and graph explorer data loading in `src/Web/StellaOps.Web/src/app/**`.
+- Runtime bindings now resolve to backend APIs for:
+  - Policy simulation history/compare/reproducibility/pin (`/policy/simulations/**`)
+  - Policy conflict detection/resolution (`/policy/conflicts/**`)
+  - Policy batch evaluations (`/policy/batch-evaluations/**`)
+  - Graph explorer tile/metadata reads (`/api/graph/**`)
+- Inline component mock datasets were removed from these runtime paths; test/dev mock clients remain available only via explicit test wiring.
+
+## Latest updates (2025-11-30)
+- Docs refreshed per `docs/implplan/SPRINT_0331_0001_0001_docs_modules_ui.md`; added observability runbook stub and TASKS mirror.
+- Access-control guidance from 2025-11-03 remains valid; ensure Authority scopes are verified before enabling uploads.

 ## Responsibilities
 - Render real-time status for ingestion, scanning, policy, and exports via SSE.
--- a/docs/modules/ui/v2-rewire/S00_endpoint_contract_ledger_v2_pack22.md
+++ b/docs/modules/ui/v2-rewire/S00_endpoint_contract_ledger_v2_pack22.md
@@ -27,6 +27,8 @@ Supersedes for new IA planning: `S00_endpoint_contract_ledger_v1.md` remains his
 | Releases | Approvals queue (cross-release) | `source-of-truth.md 3.3`, `pack-22.md 5`, `pack-17.md` | `/release-control/approvals` (legacy) | Existing `/api/v1/approvals`; add `/api/v2/releases/approvals` alias with richer metadata | `EXISTS_COMPAT` | `Policy` + `ReleaseOrchestrator` + `Platform` | Existing reviewer/approver scopes (`orch:read` path for queue projection) | Shipped release identity fields, blocker summaries, and region/env filters in `/api/v2/releases/approvals` projection | Single queue UX dependency unblocked for FE contract migration; v1 approvals endpoint remains for backward compatibility | `S22-T03-REL-04` |
 | Topology | Regions, Environments, Targets/Hosts, Agents | `source-of-truth.md 3.4`, `pack-22.md 5`, `pack-18.md` | Legacy under `/release-control/regions`, `/platform-ops/agents`, `/integrations/hosts` | `GET /api/v2/topology/regions`; `GET /api/v2/topology/environments`; `GET /api/v2/topology/targets`; `GET /api/v2/topology/hosts`; `GET /api/v2/topology/agents` | `EXISTS_COMPAT` | `Platform` + `ReleaseOrchestrator` + `Integrations` | `platform.topology.read` policy now mapped to existing `orch:read` scope in Platform auth wiring | Shipped migration `049_TopologyInventory.sql` with normalized region/environment/target/host/agent projection tables and sync watermark tracking | Duplicate inventory placement can now be removed from Integrations/Operations nav during FE route migration | `S22-T04-TOP-01` |
 | Topology | Promotion Paths, Workflows, Gate Profiles | `source-of-truth.md 3.4`, `pack-22.md 5`, `pack-13.md` | Legacy setup pages under `/release-control/setup/*` | `GET /api/v2/topology/promotion-paths`; `GET /api/v2/topology/workflows`; `GET /api/v2/topology/gate-profiles`; write routes in follow-up sprint | `EXISTS_COMPAT` | `ReleaseOrchestrator` + `Policy` + `Platform` | Topology read policy uses existing `orch:read` scope; write-authoring scopes stay in module-owned follow-up routes | Shipped deterministic read projections for paths/workflows/gate profiles with region/environment filters; write contracts remain follow-up scope | FE can consume read contracts now; explicit write routes can phase in a subsequent sprint without blocking Pack 22 IA cutover | `S22-T04-TOP-02` |
+| Policy | Policy Simulation Studio (history, compare, reproducibility, conflicts, batch evaluations) | `source-of-truth.md 3.8`, `pack-22.md 5` | `/policy/simulation/*` | `GET /policy/simulations/history`; `GET /policy/simulations/compare`; `POST /policy/simulations/{simulationId}/verify`; `PATCH /policy/simulations/{simulationId}`; `POST /policy/conflicts/detect`; `POST /policy/conflicts/{conflictId}/resolve`; `POST /policy/conflicts/auto-resolve`; `POST /policy/batch-evaluations`; `GET /policy/batch-evaluations`; `GET /policy/batch-evaluations/{batchId}`; `POST /policy/batch-evaluations/{batchId}/cancel` | `EXISTS_COMPAT` | `Policy` | Existing `policy:simulate` + policy read scopes | FE runtime cutover (Sprint 042) removed inline component mock datasets and now binds these screens to backend responses through `POLICY_SIMULATION_API -> PolicySimulationHttpClient` | Keep mock simulation service for test harness wiring only; runtime bindings must remain tokenized in app config | `S22-T10-POL-01` |
+| Security | Graph Explorer (runtime graph metadata/tile fetch) | `source-of-truth.md 3.5`, `pack-19.md`, `pack-22.md 5` | `/analyze/graph` | `GET /api/graph/graphs`; `GET /api/graph/graphs/{graphId}/tiles` | `EXISTS_COMPAT` | `Graph` + `Platform` | Existing `graph:read` viewer scope | FE runtime cutover (Sprint 042) removed inline `MOCK_NODES`/`MOCK_EDGES` from graph explorer and now maps graph tile payloads to canvas node/edge view-models | If graph inventory is empty, UI renders deterministic empty state; endpoint aliasing remains gateway-owned | `S22-T10-SEC-04` |
 | Security | Findings unified explorer with pivots | `source-of-truth.md 3.5`, `pack-22.md 5`, `pack-19.md` | `/security-risk/findings`, `/security-risk/vulnerabilities`, `/security-risk/reachability` | `GET /api/v2/security/findings`; legacy `/api/v1/security/findings` and `/api/v1/security/vulnerabilities` retained during migration | `EXISTS_COMPAT` | `Scanner` + `Platform` | `platform.security.read` mapped to existing `findings:read` viewer scope in Platform policy map | Shipped pivot/facet schema (CVE/package/component/release/environment), disposition summary columns, and deterministic filter/sort envelope in B22-04 | Legacy endpoints stay available through cutover window; FE security explorer can migrate to v2 contract | `S22-T05-SEC-01` |
 | Security | Disposition (VEX + Exceptions UX join) | `source-of-truth.md 2.3`, `source-of-truth.md 3.5`, `pack-22.md 5` | `/security-risk/vex`, `/security-risk/exceptions` (legacy split) | `GET /api/v2/security/disposition`; `GET /api/v2/security/disposition/{findingId}`; exception/VEX writes remain module-owned routes | `EXISTS_COMPAT` | `Policy` + `Scanner` + `Platform` | `platform.security.read` mapped to `findings:read` for read projection; exception/VEX writes keep module approval scopes | Shipped migration `050_SecurityDispositionProjection.sql` for read-only disposition projection joining VEX state and exception state | Write authority boundaries preserved by design: no combined `/api/v2/security/disposition/exceptions` POST route in Platform | `S22-T05-SEC-02` |
 | Security | SBOM Explorer (table/graph/diff) | `source-of-truth.md 2.3`, `source-of-truth.md 3.5`, `pack-22.md 5` | `/security-risk/sbom`, `/security-risk/sbom-lake` | `GET /api/v2/security/sbom-explorer?mode=table|graph|diff` with release compare filters | `EXISTS_COMPAT` | `Scanner` + `Graph` + `Platform` | `platform.security.read` mapped to existing `findings:read` viewer scope | Shipped unified response envelope for table/graph/diff views with deterministic diff composition from migration `050` projection objects | Enables FE to collapse dual SBOM routes onto one v2 explorer contract | `S22-T05-SEC-03` |
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -22,7 +22,7 @@ git clone <your-gitea-instance>/stella-ops/stella-ops.git
 cd stella-ops
 ```

-## 2. Run the setup script
+## 2. Run setup

 **Windows (PowerShell 7):**

@@ -36,33 +36,50 @@ cd stella-ops
 ./scripts/setup.sh
 ```

-The script will:
+The setup script will:
 - Verify all prerequisites are installed
 - Offer to add hosts file entries (50 services need unique loopback IPs)
 - Create `.env` from the example template (works out of the box, no editing needed)
- Start infrastructure (PostgreSQL, Valkey, RustFS)
 - Build .NET solutions and Docker images
- Launch the full platform
+- Launch the full platform stack (`docker-compose.stella-ops.yml`)
 - Run health checks and report status

 ### Infrastructure only (faster)

-To skip builds and just start infrastructure:
+To skip builds and only start infrastructure:

 ```powershell
 .\scripts\setup.ps1 -InfraOnly     # Windows
 ./scripts/setup.sh --infra-only    # Linux/macOS
 ```

-## 3. Open the platform
+## 3. First 30 minutes path

-Once setup completes, open **https://stella-ops.local** in your browser.
-
-Accept the self-signed certificate warning on first visit.
+1. Start platform quickly (reuse existing images):
+   ```powershell
+   .\scripts\setup.ps1 -SkipBuild -SkipImages
+   ```
+2. Confirm service health:
+   ```powershell
+   docker compose -f devops/compose/docker-compose.stella-ops.yml ps
+   ```
+3. Preview demo seeding:
+   ```powershell
+   dotnet run --project src/Cli/StellaOps.Cli/StellaOps.Cli.csproj -- `
+     admin seed-demo --dry-run `
+     --connection "Host=127.1.1.1;Port=5432;Database=stellaops_platform;Username=stellaops;Password=stellaops"
+   ```
+4. Seed demo data:
+   ```powershell
+   dotnet run --project src/Cli/StellaOps.Cli/StellaOps.Cli.csproj -- `
+     admin seed-demo --confirm `
+     --connection "Host=127.1.1.1;Port=5432;Database=stellaops_platform;Username=stellaops;Password=stellaops"
+   ```
+5. Open **https://stella-ops.local**.

 ## What's running

-After a full setup, you'll have 45+ services running locally:
+After a full setup, you'll have 60+ services running locally:

 | Service | URL | Purpose |
 |---------|-----|---------|
@@ -72,16 +89,27 @@ After a full setup, you'll have 45+ services running locally:
 | Concelier | https://concelier.stella-ops.local | Advisory aggregation |
 | PostgreSQL | db.stella-ops.local:5432 | Primary database |
 | Valkey | cache.stella-ops.local:6379 | Cache and messaging |
+| RustFS | s3.stella-ops.local:8333 | S3-compatible object storage |

 Full service list: `devops/compose/docker-compose.stella-ops.yml`

+Optional Sigstore services (`rekor-v2`, `rekor-cli`, `cosign`) are enabled only with:
+
+```bash
+docker compose -f devops/compose/docker-compose.stella-ops.yml --profile sigstore up -d
+```
+
 ## Troubleshooting

-**"stella-ops.local not found"** -- The hosts file entries are missing. Re-run the setup script and accept the hosts file installation, or manually append `devops/compose/hosts.stellaops.local` to your hosts file.
-
-**Containers unhealthy** -- Check logs with `docker compose -f devops/compose/docker-compose.stella-ops.yml logs <service-name>`.
-
-**Port conflicts** -- Override ports in `devops/compose/.env`. See `devops/compose/env/stellaops.env.example` for available port variables.
+| Symptom | Meaning | Action |
+|---------|---------|--------|
+| `stella-ops.local` not found | Hosts entries missing | Re-run setup and accept hosts installation, or append `devops/compose/hosts.stellaops.local` manually |
+| `health=starting` for RustFS during setup | Advisory startup lag | Wait 30-60 seconds and re-check `docker compose ... ps` |
+| `stellaops-dev-rekor` restarting without `--profile sigstore` | Optional profile container from older runs | Non-blocking for default setup; ignore or clean old container |
+| `SM remote service probe failed (localhost:56080)` in CLI | Optional China SM Remote plugin probe | Non-blocking for default crypto profile |
+| `admin seed-demo --confirm` fails with `scheduler_exceptions_tenant_isolation already exists` | Outdated Scheduler migration scripts | Pull latest code and rerun seeding |
+| Seed endpoint still returns HTTP 500 after patching source | Running old container image | Rebuild/restart platform image and retest |
+| Port conflicts | Local process already using mapped port | Override in `devops/compose/.env` (`devops/compose/env/stellaops.env.example`) |

 ## Next steps