doctor enhancements, setup, enhancements, ui functionality and design consolidation and , test projects fixes , product advisory attestation/rekor and delta verfications enhancements

2026-01-19 09:02:59 +02:00
parent 8c4bf54aed
commit 17419ba7c4
809 changed files with 170738 additions and 12244 deletions
--- a/docs/modules/ui/architecture-rework.md
+++ b/docs/modules/ui/architecture-rework.md
@@ -0,0 +1,326 @@
+# UI Rework Architecture - Release Control Plane
+
+> **Ownership:** UI Guild, Platform Team
+> **Status:** Planned
+> **Related:** [Current UI Architecture](architecture.md), [Wireframes](guides/wireframes-flagship-pages.md), [Migration Map](guides/migration-map.md)
+
+This document defines the target UI architecture for Stella Ops as an **evidence-based release control plane** with **hybrid reachability** as a first-class gate and explanation layer.
+
+---
+
+## 0) Vision Summary
+
+The current UI tells users "scanner + admin console." The new UI must communicate:
+
+1. **"What is deployed where"** (by digest, per environment/target)
+2. **"What is allowed to ship next"** (promotion requests + approvals)
+3. **"Why it is allowed/blocked"** (policy gates + reachability evidence)
+4. **"Where the evidence is"** (one-click proof chain and export)
+
+Everything else (vuln explorer, SBOM graph, VEX hub, feeds, ops health) is supporting detail.
+
+---
+
+## 1) New UX Mental Model
+
+### 1.1 Core Objects (first-class nouns everywhere)
+
+| Object | Description |
+|--------|-------------|
+| **Release** | Bundle of component-to-digest mappings (immutable identity) |
+| **Environment** | Dev/QA/Staging/Prod (policies, windows, approvals) |
+| **Promotion** | Request to move a Release to an Environment |
+| **Deployment** | Execution instance (workflow run against targets) |
+| **Evidence Packet** | Signed bundle of inputs/outputs of a decision/run |
+
+### 1.2 Core Jobs (UI must optimize for these first)
+
+1. **Ship a release**: create -> request promotion -> approve -> deploy
+2. **Explain/justify a decision**: why allowed/blocked + evidence
+3. **Operate with confidence**: drift, CVE updates, replay, audit export
+
+---
+
+## 2) Information Architecture
+
+### 2.1 Current Top-Level Nav (scanner-centric)
+
+```
+HOME / ANALYZE / TRIAGE / POLICY / OPS / NOTIFY / ADMIN
+```
+
+### 2.2 New Top-Level Nav (release control plane)
+
+```
+CONTROL PLANE / RELEASES / APPROVALS / SECURITY / EVIDENCE / OPERATIONS / SETTINGS
+```
+
+### 2.3 Navigation Mapping
+
+| New Section | Contains | Replaces |
+|-------------|----------|----------|
+| **Control Plane** | Pipeline overview, Action Inbox, Pending Promotions, Drift/Risk | Home dashboard |
+| **Releases** | Release list, Release detail, Environment detail | Release Orchestrator (hidden) |
+| **Approvals** | Approval inbox, Approval detail | Release Orchestrator approvals |
+| **Security** | Overview, Findings, Vulnerabilities, SBOM Graph, VEX, Exceptions | Analyze + Triage + VEX Hub |
+| **Evidence** | Packets, Proof Chains, Replay/Verify, Export, Audit Bundles | Scattered evidence views |
+| **Operations** | Orchestrator, Quotas, Dead-letter, SLO, Health, Feeds, Scheduler | Ops/* + Scheduler |
+| **Settings** | Integrations, Trust, Admin, Notifications, Policy Governance | Console/Admin + scattered config |
+
+---
+
+## 3) Shell & Layout Architecture
+
+### 3.1 Shell Blueprint
+
+```
+------------------------------------------------------------------------------+
+| Stella Ops   [Global Search: release|digest|CVE|env]   [Tenant] [User]       |
+| Offline: OK | Feed Snapshot: 2026-01-15 | Policy: v3.1 | Evidence: ON        |
+---------------+--------------------------------------------------------------+
+| CONTROL PLANE | Breadcrumb: Section > Page                                   |
+| RELEASES      |                                                              |
+| APPROVALS     |  <router-outlet>                                             |
+| SECURITY      |                                                              |
+| EVIDENCE      |                                                              |
+| OPERATIONS    |                                                              |
+| SETTINGS      |                                                              |
+---------------+--------------------------------------------------------------+
+```
+
+### 3.2 Shell Components
+
+| Component | Responsibility |
+|-----------|---------------|
+| `AppShellComponent` | Top-level layout with topbar + sidebar + outlet + overlay hosts |
+| `AppTopbarComponent` | Global search, tenant context, status chips, user menu |
+| `AppSidebarComponent` | Left navigation rail with nav groups and items |
+| `BreadcrumbComponent` | Context-aware breadcrumbs from router data |
+| `GlobalSearchComponent` | Unified search across releases, digests, CVEs, environments |
+| `ContextChipsRowComponent` | Offline status, feed snapshot, policy baseline, evidence mode |
+
+---
+
+## 4) Folder Structure (Angular 17+ Standalone)
+
+```
+src/app/
+  core/                     # auth, api client, guards, nav config, app init
+  layout/                   # app shell, sidebar, topbar, page scaffolding
+  shared/
+    ui/                     # design system primitives (buttons, chips, tables)
+    domain/                 # domain widgets (digest chip, gate badges, evidence link)
+    overlays/               # drawers/modals (evidence drawer, witness drawer)
+    pipes/                  # formatting
+    util/                   # helpers, comparators, trackBy fns
+  features/
+    control-plane/          # / - Control Plane Overview
+    releases/               # /releases, /releases/:id
+    approvals/              # /approvals, /approvals/:id
+    environments/           # /environments, /environments/:id
+    deployments/            # /deployments, /deployments/:id
+    security/               # /security/*
+    evidence/               # /evidence/*
+    reachability/           # /witness/:id
+    operations/             # /operations/*
+    settings/               # /settings/*
+```
+
+---
+
+## 5) Shared Domain Widgets (The Moat UI)
+
+These components encode Stella's differentiators and must be consistent everywhere.
+
+### 5.1 Digest Identity
+
+| Component | Inputs | Behavior |
+|-----------|--------|----------|
+| `DigestChipComponent` | `digest`, `label?`, `variant` | Short digest display, copy on click, full on hover |
+| `BundleDigestHeaderComponent` | `releaseId`, `bundleDigest`, `createdAt`, `sourceRef` | Release identity block |
+
+### 5.2 Gate System
+
+| Component | Inputs | Behavior |
+|-----------|--------|----------|
+| `GateBadgeComponent` | `state`, `label` | PASS/WARN/BLOCK badges |
+| `GateSummaryPanelComponent` | `gates[]`, `policyRef`, `snapshotRef` | Compact gate list with drill-down |
+| `GateExplainDrawerComponent` | `gateRunId` | K4 lattice explanation, rule hits, evidence |
+
+### 5.3 Evidence UX
+
+| Component | Inputs | Behavior |
+|-----------|--------|----------|
+| `EvidenceLinkComponent` | `evidenceId`, `type`, `verified`, `signed` | Consistent evidence link |
+| `EvidencePacketSummaryComponent` | `EvidencePacketHeaderVM` | Who/What/Why/How/When audit block |
+| `ProofChainLinkComponent` | `subjectDigest` | Standard proof chain entry |
+
+### 5.4 Reachability Witness
+
+| Component | Inputs | Behavior |
+|-----------|--------|----------|
+| `ReachabilityStateChipComponent` | `state`, `confidence` | Reachable/Unreachable/Uncertain + confidence |
+| `WitnessPathPreviewComponent` | `path[]`, `guards`, `deterministic` | Call path preview with drill-down |
+| `WitnessViewerComponent` | `witnessId` | Full witness page with exports and replay |
+
+---
+
+## 6) Flagship Pages
+
+### 6.1 Control Plane Overview (`/`)
+
+**Goal:** Answer in one screen: what's deployed, what's pending, what changed, what needs attention.
+
+**Components:**
+- `EnvironmentPipelineWidgetComponent` - Dev -> QA -> Staging -> Prod visualization
+- `ActionInboxWidgetComponent` - Pending approvals, blocked promotions, failed deployments
+- `DriftRiskDeltaWidgetComponent` - CVE updates, feed staleness, config drifts
+- `PendingPromotionsTableComponent` - Release promotions waiting for action
+
+### 6.2 Release Detail (`/releases/:releaseId`)
+
+**Goal:** One flagship screen tying promotion + gates + reachability + evidence + proof chain.
+
+**Tabs:**
+- Overview (deployment map, gate summary, security impact, latest evidence)
+- Components (digest inventory)
+- Gates (detailed policy evaluation)
+- Promotions (promotion history)
+- Deployments (deployment runs)
+- Evidence (linked evidence packets)
+- Proof Chain (full proof chain viewer)
+
+### 6.3 Approval Detail (`/approvals/:approvalId`)
+
+**Goal:** Everything needed to make a decision without navigating away.
+
+**Panels:**
+- Diff-first panel (what changed)
+- Gates panel (expandable gate results)
+- Decision panel (approve/reject/comment)
+- Reachability Witness panel (the moat)
+- Evidence quick panel
+
+### 6.4 Evidence Packet Viewer (`/evidence/:evidenceId`)
+
+**Goal:** Evidence as structured "who/what/why/how/when" record + bundle contents + verify.
+
+**Sections:**
+- Summary (audit-friendly header)
+- Contents (SBOM, verdict, witness slice, VEX, attestations)
+- Verification (signature + Rekor inclusion proofs)
+
+---
+
+## 7) State Management
+
+### 7.1 Signal Store Pattern
+
+Each major page/container has a dedicated store service:
+
+```typescript
+@Injectable()
+export class ReleaseDetailStore {
+  private state = signal<ReleaseDetailState>({ ... });
+
+  release = computed(() => this.state().release);
+  gateSummary = computed(() => this.state().gateSummary);
+
+  load(releaseId: string) { /* triggers effects + sets loading/error */ }
+  refresh() { /* re-runs queries */ }
+  requestPromotion() { /* command method */ }
+}
+```
+
+### 7.2 Cross-Cutting Stores
+
+| Store | Responsibility |
+|-------|---------------|
+| `AppContextStore` | Tenant, user, offline mode, feed snapshot, evidence mode |
+| `GlobalSearchStore` | Query -> aggregated results across types |
+| `OverlayStore` | Open/close drawers (evidence, witness, gate explain) |
+
+---
+
+## 8) Overlays (Drawers/Modals)
+
+Essential for "small pages, deep drill-down" requirement:
+
+| Overlay | Purpose |
+|---------|---------|
+| `EvidencePacketDrawerComponent` | Opens from anywhere; condensed evidence view |
+| `WitnessDrawerComponent` | Preview witness path + quick export + open full |
+| `GateExplainDrawerComponent` | K4 lattice reasoning + rule hits + evidence anchors |
+| `CreateReleaseModalComponent` | New release creation flow |
+| `RequestPromotionModalComponent` | Promotion request flow |
+| `RollbackModalComponent` | Rollback confirmation |
+| `RequestExceptionModalComponent` | Exception request flow |
+
+---
+
+## 9) UX Contracts
+
+### 9.1 Gate State Presentation
+
+| State | Badge | Color |
+|-------|-------|-------|
+| PASS | `[PASS]` | Green |
+| WARN | `[WARN]` | Amber |
+| BLOCK | `[BLOCK]` | Red |
+
+Always show with one-line reason.
+
+### 9.2 Reachability State Presentation
+
+| State | Display |
+|-------|---------|
+| Reachable | State + Confidence + Witness link |
+| Unreachable | State + Confidence (0.90+) |
+| Uncertain | State + Confidence + "why uncertain" + resolution hints |
+
+### 9.3 Digest Visibility
+
+- Show short digest everywhere (`sha256:abc...123`)
+- Full digest on hover/copy
+- Copy buttons for operational fields
+
+### 9.4 Evidence Traceability
+
+- Policy baseline version shown where decisions are made
+- Feed snapshot version shown where decisions are made
+- "Open Evidence" and "Open Proof Chain" always one click away
+
+---
+
+## 10) Implementation Priority
+
+### Phase 1 (Highest ROI)
+
+1. **Make `/` the Control Plane Overview** (pipeline + inbox + drift)
+2. **Consolidate Settings** (stop configuration fragmentation)
+3. **Make Approvals evidence-first with reachability witness** (moat on display)
+
+### Phase 2 (Core Product)
+
+4. Shell & navigation redesign (left rail)
+5. Releases feature (list + detail flagship)
+6. Evidence unification
+
+### Phase 3 (Polish)
+
+7. Security consolidation (merge Analyze + Triage)
+8. Environments & Deployments features
+9. Route migration & legacy redirect telemetry
+
+---
+
+## 11) Related Documentation
+
+- [Wireframes](guides/wireframes-flagship-pages.md) - ASCII wireframes for flagship pages
+- [Migration Map](guides/migration-map.md) - Route migration from current to new IA
+- [Component Breakdown](guides/component-breakdown.md) - Detailed Angular component inventory
+- [Current Architecture](architecture.md) - Existing UI architecture reference
+
+---
+
+*Last updated: 2026-01-18*
--- a/docs/modules/ui/components/README.md
+++ b/docs/modules/ui/components/README.md
@@ -46,6 +46,56 @@ Findings can have special flags indicating evidence quality:
 | `anchored` | [A] | Violet | Score anchored with DSSE/Rekor attestation |
 | `hard-fail` | [!] | Red | Policy hard-fail triggered |

+## Witness Visualization Components
+
+> **Sprint:** SPRINT_20260118_020_FE_witness_visualization
+
+The witness visualization component suite provides UI for runtime witness display, static vs runtime path comparison, and witness gate results in release promotion flows.
+
+### Components
+
+| Component | Purpose | Location |
+|-----------|---------|----------|
+| [WitnessStatusChip](./witness-visualization.md#witness-status-chip) | Status badge showing witness state (witnessed/unwitnessed/stale/failed) | `shared/domain/witness-status-chip/` |
+| [WitnessComparison](./witness-visualization.md#witness-comparison-component) | Side-by-side static vs runtime path comparison | `shared/components/witness-comparison/` |
+| [UnwitnessedAdvisory](./witness-visualization.md#unwitnessed-advisory-component) | Advisory panel for paths without witnesses | `shared/components/unwitnessed-advisory/` |
+| [GateSummaryPanel](./witness-visualization.md#gate-summary-panel-extended) | Extended gate summary with witness metrics | `shared/domain/gate-summary-panel/` |
+
+### Witness States
+
+| State | Badge Color | Description |
+|-------|-------------|-------------|
+| `witnessed` | Green | Path confirmed by runtime observation |
+| `unwitnessed` | Yellow | Path not yet observed at runtime |
+| `stale` | Orange | Witness data is outdated |
+| `failed` | Red | Witness verification failed |
+
+### Usage
+
+```typescript
+import {
+  WitnessStatusChipComponent,
+  WitnessComparisonComponent,
+  UnwitnessedAdvisoryComponent,
+  GateSummaryPanelComponent,
+} from '@app/shared/domain';
+```
+
+```html
+<!-- Witness Status Chip -->
+<app-witness-status-chip [status]="'witnessed'" [showCount]="true" />
+
+<!-- Witness Comparison -->
+<app-witness-comparison [data]="comparisonData" (stepClick)="onStepClick($event)" />
+
+<!-- Unwitnessed Advisory -->
+<app-unwitnessed-advisory [data]="advisoryData" (createTestTask)="onCreateTask($event)" />
+```
+
+See [witness-visualization.md](./witness-visualization.md) for full documentation.
+
+---
+
 ## Grey Queue Components

 > **Sprint:** SPRINT_20260112_011_FE_policy_unknowns_queue_integration
--- a/docs/modules/ui/components/witness-visualization.md
+++ b/docs/modules/ui/components/witness-visualization.md
@@ -0,0 +1,352 @@
+# Witness Visualization Components
+
+> **Sprint:** SPRINT_20260118_020_FE_witness_visualization
+
+The witness visualization component suite provides UI for displaying runtime witness data, comparing static analysis paths with runtime observations, and managing witness gate results in release promotion flows.
+
+## Overview
+
+Runtime witnesses confirm that static analysis reachability paths are actually exercised during application execution. These components visualize:
+
+- **Witness Status**: Whether a path has been witnessed at runtime
+- **Static vs Runtime Comparison**: Side-by-side or overlay views comparing predicted and observed paths
+- **Gate Results**: Witness gate outcomes for release promotion decisions
+- **Unwitnessed Advisories**: Paths requiring runtime exercise before promotion
+
+## Components
+
+### Core Components
+
+| Component | Purpose | Location |
+|-----------|---------|----------|
+| `WitnessStatusChipComponent` | Status badge showing witness state | `shared/domain/witness-status-chip/` |
+| `WitnessComparisonComponent` | Static vs runtime path comparison | `shared/components/witness-comparison/` |
+| `UnwitnessedAdvisoryComponent` | Advisory panel for unwitnessed paths | `shared/components/unwitnessed-advisory/` |
+| `GateSummaryPanelComponent` | Gate results with witness metrics | `shared/domain/gate-summary-panel/` |
+
+### Witness Status Chip
+
+Displays the witness status of a reachability path with color-coded badges.
+
+```typescript
+import { WitnessStatusChipComponent, WitnessStatus } from '@app/shared/domain/witness-status-chip';
+```
+
+#### States
+
+| State | Color | Icon | Description |
+|-------|-------|------|-------------|
+| `witnessed` | Green | ✓ | Path confirmed by runtime observation |
+| `unwitnessed` | Yellow | ○ | Path not yet observed at runtime |
+| `stale` | Orange | ⏱ | Witness data is outdated |
+| `failed` | Red | ✗ | Witness verification failed |
+
+#### Usage
+
+```html
+<!-- Basic usage -->
+<app-witness-status-chip [status]="'witnessed'" />
+
+<!-- With details for tooltip -->
+<app-witness-status-chip
+  [status]="'witnessed'"
+  [details]="{
+    status: 'witnessed',
+    lastObserved: '2026-01-15T10:30:00Z',
+    observationCount: 42,
+    rekorLogIndex: 12345
+  }"
+  [showCount]="true"
+  (chipClick)="onChipClick()"
+/>
+```
+
+#### Input Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `status` | `WitnessStatus` | required | Witness status to display |
+| `details` | `WitnessStatusDetails` | `null` | Optional metadata for tooltip |
+| `showCount` | `boolean` | `true` | Whether to show observation count |
+
+---
+
+### Witness Comparison Component
+
+Side-by-side or overlay view comparing static analysis paths with runtime observations. The main visualization for understanding witness coverage.
+
+```typescript
+import {
+  WitnessComparisonComponent,
+  WitnessComparisonData,
+  ComparisonPathStep,
+  ComparisonMetrics,
+} from '@app/shared/components/witness-comparison';
+```
+
+#### Features
+
+- **View Modes**: List view (vertical) or overlay view (side-by-side columns)
+- **Color Coding**: Green (confirmed), yellow (static only), orange (runtime only/unexpected)
+- **Filtering**: Filter by confirmation status
+- **Metrics Summary**: Totals and confirmation rate display
+- **Step Drill-down**: Click steps for detailed information
+
+#### Usage
+
+```html
+<app-witness-comparison
+  [data]="comparisonData"
+  (stepClick)="onStepClick($event)"
+  (refresh)="onRefresh()"
+/>
+```
+
+#### Input Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | `WitnessComparisonData` | Comparison data with paths and metrics |
+
+#### Output Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `stepClick` | `ComparisonPathStep` | Emitted when user clicks a step |
+| `refresh` | `void` | Emitted when user requests data refresh |
+
+#### Data Models
+
+```typescript
+interface ComparisonPathStep {
+  nodeId: string;
+  symbol: string;
+  file?: string;
+  line?: number;
+  package?: string;
+  inStatic: boolean;      // Found in static analysis
+  inRuntime: boolean;     // Observed at runtime
+  runtimeInvocations?: number;
+  lastObserved?: string;
+}
+
+interface ComparisonMetrics {
+  totalSteps: number;
+  confirmedSteps: number;      // Both static and runtime
+  staticOnlySteps: number;     // Static only (unwitnessed)
+  runtimeOnlySteps: number;    // Runtime only (unexpected)
+  confirmationRate: number;    // Percentage confirmed
+}
+
+interface WitnessComparisonData {
+  claimId: string;
+  cveId?: string;
+  packageName: string;
+  packageVersion?: string;
+  pathSteps: ComparisonPathStep[];
+  metrics: ComparisonMetrics;
+  generatedAt: string;
+}
+```
+
+---
+
+### Unwitnessed Advisory Component
+
+Advisory panel displayed when release promotion encounters paths without runtime witnesses. Used in the gate flow to inform operators about witness coverage gaps.
+
+```typescript
+import {
+  UnwitnessedAdvisoryComponent,
+  UnwitnessedAdvisoryData,
+  UnwitnessedPath,
+} from '@app/shared/components/unwitnessed-advisory';
+```
+
+#### Features
+
+- **Severity Summary**: Visual breakdown by vulnerability severity
+- **Path List**: Sortable list of unwitnessed paths
+- **Blocking/Advisory Mode**: Different styling based on gate configuration
+- **Action Buttons**: Create test tasks for individual paths or all at once
+
+#### Usage
+
+```html
+<app-unwitnessed-advisory
+  [data]="advisoryData"
+  (createTestTask)="onCreateTestTask($event)"
+  (createAllTestTasks)="onCreateAllTestTasks()"
+  (viewComparison)="onViewComparison()"
+/>
+```
+
+#### Input Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `data` | `UnwitnessedAdvisoryData` | Advisory data with paths and configuration |
+
+#### Output Events
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `createTestTask` | `UnwitnessedPath` | Create test task for specific path |
+| `createAllTestTasks` | `void` | Create test tasks for all paths |
+| `viewComparison` | `void` | Open full comparison view |
+
+#### Data Models
+
+```typescript
+interface UnwitnessedPath {
+  pathId: string;
+  cveId?: string;
+  vulnId: string;
+  packageName: string;
+  packageVersion?: string;
+  entrypoint: string;
+  sink: string;
+  severity: 'critical' | 'high' | 'medium' | 'low' | 'unknown';
+  confidence: number;
+  lastAnalyzed?: string;
+}
+
+interface UnwitnessedAdvisoryData {
+  totalUnwitnessed: number;
+  paths: UnwitnessedPath[];
+  targetEnvironment?: string;
+  isBlocking: boolean;
+}
+```
+
+---
+
+### Gate Summary Panel (Extended)
+
+Extended to support witness gate display with metrics, expandable details, and comparison links.
+
+```typescript
+import {
+  GateSummaryPanelComponent,
+  GateResult,
+  WitnessGateMetrics,
+  WitnessPathSummary,
+} from '@app/shared/domain/gate-summary-panel';
+```
+
+#### Witness Gate Support
+
+The `GateResult` interface now supports witness-specific properties:
+
+```typescript
+interface GateResult {
+  id: string;
+  name: string;
+  state: 'PASS' | 'WARN' | 'BLOCK' | 'SKIP';
+  reason?: string;
+  ruleHits?: number;
+  gateType?: 'standard' | 'witness' | 'cve' | 'sbom';
+  witnessMetrics?: WitnessGateMetrics;
+}
+
+interface WitnessGateMetrics {
+  totalPaths: number;
+  witnessedPaths: number;
+  unwitnessedPaths: number;
+  stalePaths?: number;
+  unwitnessedPathDetails?: WitnessPathSummary[];
+}
+
+interface WitnessPathSummary {
+  pathId: string;
+  entrypoint: string;
+  sink: string;
+  severity?: 'critical' | 'high' | 'medium' | 'low' | 'unknown';
+  vulnId?: string;
+}
+```
+
+#### Usage
+
+```html
+<app-gate-summary-panel
+  [gates]="gates"
+  [policyRef]="policyReference"
+  [snapshotRef]="snapshotReference"
+  (openExplain)="onOpenExplain($event)"
+  (openEvidence)="onOpenEvidence()"
+  (openComparison)="onOpenComparison($event)"
+/>
+```
+
+#### Witness Gate Features
+
+- **Metrics Display**: Shows X/Y witnessed paths, unwitnessed count, stale count
+- **Advisory Styling**: Yellow border and background for WARN state witness gates
+- **Expandable Details**: Click "Details" to see unwitnessed path list
+- **Compare Button**: Opens full comparison view
+
+---
+
+## Color Coding Reference
+
+### Comparison States
+
+| State | Color | CSS Variable | Meaning |
+|-------|-------|--------------|---------|
+| Confirmed | Green | `--green-500` | Path in both static and runtime |
+| Static Only | Yellow | `--yellow-500` | Path predicted but not observed |
+| Runtime Only | Orange | `--orange-500` | Unexpected path observed |
+
+### Severity Colors
+
+| Severity | Color | CSS Variable |
+|----------|-------|--------------|
+| Critical | Red | `--red-500` |
+| High | Orange | `--orange-500` |
+| Medium | Yellow | `--yellow-500` |
+| Low | Blue | `--blue-500` |
+| Unknown | Gray | `--gray-400` |
+
+---
+
+## Integration with Existing Components
+
+The witness visualization components integrate with several existing UI elements:
+
+| Existing Component | Integration |
+|--------------------|-------------|
+| `WitnessDrawerComponent` | Can embed comparison view |
+| `WitnessPageComponent` | Full reachability analysis page |
+| `TimelineListComponent` | Display witness observation timeline |
+| `GateExplainDrawerComponent` | Show witness gate explanation |
+
+---
+
+## Accessibility
+
+All witness visualization components follow WCAG 2.1 AA guidelines:
+
+- ARIA labels for all interactive elements
+- Keyboard navigation support
+- Focus management for expandable sections
+- Color + icon combinations (not color alone)
+- Screen reader announcements for status changes
+
+---
+
+## Testing
+
+Unit tests are located alongside components:
+
+- `witness-status-chip.component.spec.ts`
+- `witness-comparison.component.spec.ts`
+- `unwitnessed-advisory.component.spec.ts`
+- `gate-summary-panel.component.spec.ts`
+
+Run tests:
+
+```bash
+cd src/Web/StellaOps.Web
+npm test -- --include="**/*witness*" --include="**/*gate-summary*"
+```
--- a/docs/modules/ui/guides/setup-guide.md
+++ b/docs/modules/ui/guides/setup-guide.md
@@ -0,0 +1,209 @@
+# UI Setup Wizard Guide
+
+This guide covers the web-based Setup Wizard for initial configuration of Stella Ops.
+
+## Overview
+
+The Setup Wizard guides you through configuring all required and optional components. Both CLI and UI setup wizards follow the same **Infrastructure-First** order and provide identical capabilities.
+
+## Accessing the Setup Wizard
+
+Navigate to `/setup` in your browser to access the Setup Wizard. The wizard is available when:
+- First-time installation (no configuration exists)
+- Explicitly navigating to `/setup` as an administrator
+- Using reconfiguration mode to modify existing settings
+
+## Setup Steps
+
+Steps are organized in phases. Required steps must be completed; optional steps can be skipped.
+
+### Phase 1: Core Infrastructure (Required)
+
+| Step | Description |
+|------|-------------|
+| **Database** | PostgreSQL connection for persistent storage |
+| **Cache** | Valkey/Redis connection for caching and distributed locks |
+| **Migrations** | Apply database schema migrations |
+
+### Phase 2: Security Foundation (Required)
+
+| Step | Description |
+|------|-------------|
+| **Authority** | Authentication provider (Standard or LDAP) |
+| **Users** | Initial super user account (skipped if LDAP selected) |
+| **Crypto** | Cryptographic provider for signing/encryption |
+
+### Phase 3: Secrets Management (Optional)
+
+| Step | Description | Configure Later |
+|------|-------------|-----------------|
+| **Vault** | External secrets vault (HashiCorp Vault, Azure Key Vault, AWS Secrets Manager, GCP Secret Manager) | Settings > Trust & Signing |
+
+### Phase 4: Integrations (Optional)
+
+| Step | Description | Configure Later |
+|------|-------------|-----------------|
+| **Registry** | Container registries for image scanning (supports multiple) | Settings > Integrations |
+| **SCM** | Source control connections (supports multiple) | Settings > Integrations |
+| **Sources** | Advisory data sources (NVD, GHSA, OSV, VEX feeds, custom mirrors) | Settings > Security Data |
+
+### Phase 5: Observability (Optional)
+
+| Step | Description | Configure Later |
+|------|-------------|-----------------|
+| **Telemetry** | OpenTelemetry configuration | Settings > System > Telemetry |
+| **Notify** | Notification channels (supports multiple) | Settings > Notifications |
+
+### Phase 6: AI Features (Optional)
+
+| Step | Description | Configure Later |
+|------|-------------|-----------------|
+| **LLM** | AI/LLM provider for AdvisoryAI (OpenAI, Claude, Gemini, Ollama) | Settings > Integrations > AdvisoryAI |
+
+### Phase 7: Configuration Store (Optional)
+
+| Step | Description | Configure Later |
+|------|-------------|-----------------|
+| **Settings Store** | External configuration store (Consul, etcd, Azure App Config, AWS) | Settings > System |
+
+### Phase 8: Release Orchestration (Optional)
+
+| Step | Description | Configure Later |
+|------|-------------|-----------------|
+| **Environments** | Define deployment environments (dev, staging, production) | Settings > Environments |
+| **Agents** | Register deployment agents | Settings > Agents |
+
+## Multiple Integrations
+
+The **Registry**, **SCM**, and **Notify** steps support configuring multiple instances:
+
+### Container Registries
+Add multiple registries for different purposes:
+- Production registry (e.g., ECR, GCR)
+- Development registry (e.g., Harbor)
+- Third-party images (e.g., Docker Hub)
+
+One registry can be marked as **Primary** for default operations.
+
+### Source Control Connections
+Add connections to multiple SCM providers:
+- Main organization GitHub
+- Internal GitLab instance
+- Partner organization Bitbucket
+
+One connection can be marked as **Primary** for default operations.
+
+### Notification Channels
+Add multiple notification destinations:
+- Operations team Slack channel
+- Security team email distribution
+- Custom webhook for SIEM integration
+
+All channels can receive notifications based on event rules.
+
+## Wizard Navigation
+
+### Progress Indicator
+The left sidebar shows:
+- Completed steps (green checkmark)
+- Current step (highlighted)
+- Pending steps (gray)
+- Skipped steps (dash)
+
+### Step Actions
+Each step provides:
+- **Test Connection**: Validate configuration without applying
+- **Apply Configuration**: Save and validate the step
+- **Skip this step**: Available for optional steps
+
+### Skip Warnings
+When skipping optional steps, warnings explain the implications:
+
+| Skipped Step | Warning |
+|--------------|---------|
+| Vault | Secrets stored in configuration files (less secure) |
+| Registry | Container scanning capabilities limited |
+| SCM | Pipeline integration unavailable |
+| Sources | Advisory feeds require manual updates |
+| Telemetry | System observability limited |
+| LLM | AdvisoryAI features unavailable |
+| Environments | Manual deployment tracking only |
+| Agents | Release orchestration unavailable |
+
+## Cryptographic Provider Selection
+
+The **Crypto** step allows selecting regional cryptographic standards:
+
+| Provider | Standards | Use Case |
+|----------|-----------|----------|
+| **Default** | AES-256-GCM, SHA-256/512, Ed25519, ECDSA P-256 | General use |
+| **FIPS 140-2** | FIPS-compliant algorithms with optional HSM | US government compliance |
+| **GOST R 34.10-2012** | Kuznechik/Magma, Streebog, GOST signatures | Russian compliance |
+| **SM2/SM3** | SM4, SM3, SM2 | Chinese national standards |
+
+## Advisory Data Sources
+
+The **Sources** step supports multiple feed types:
+
+### CVE/Vulnerability Feeds
+- NVD (NIST National Vulnerability Database)
+- GHSA (GitHub Security Advisories)
+- OSV (Open Source Vulnerabilities)
+- Distribution feeds (Red Hat, Ubuntu, Debian, Alpine, Wolfi)
+
+### VEX Sources
+- CSAF VEX feeds from vendors
+- OpenVEX format feeds
+- CycloneDX BOM with embedded VEX
+
+### Custom Mirrors
+- Self-hosted advisory mirrors for air-gapped environments
+- Supports Basic Auth, Bearer Token, or mTLS authentication
+- Configurable sync intervals
+
+## Environment Patterns
+
+The **Environments** step provides quick-start patterns:
+
+| Pattern | Environments | Description |
+|---------|--------------|-------------|
+| **Standard** | Dev > Staging > Production | Common three-tier pipeline |
+| **Simple** | Staging > Production | Minimal two-tier setup |
+| **Extended** | Dev > QA > Staging > Pre-Prod > Production | Enterprise pipeline |
+| **Custom** | User-defined | Flexible custom configuration |
+
+## Resuming Setup
+
+If setup is interrupted:
+1. Return to `/setup` to resume where you left off
+2. Session state is preserved automatically
+3. Completed steps remain configured
+
+## Reconfiguration Mode
+
+To modify existing configuration:
+1. Navigate to `/setup?mode=reconfigure`
+2. Previously configured steps show current values
+3. Modify and re-apply any step as needed
+
+## Keyboard Navigation
+
+| Key | Action |
+|-----|--------|
+| Tab | Move between form fields |
+| Enter | Submit current form / Activate button |
+| Escape | Cancel current operation |
+
+## Accessibility
+
+The Setup Wizard follows WCAG 2.1 AA guidelines:
+- All form fields have associated labels
+- Error messages are announced to screen readers
+- Focus is managed through step transitions
+- Color is not the only indicator of status
+
+## Related Documentation
+
+- [CLI Setup Guide](../../cli/guides/setup-guide.md) - Command-line setup
+- [Settings Architecture](../architecture.md) - Settings page structure
+- [API Strategy](../api-strategy.md) - Backend API contracts