git.stella-ops.org/docs/UI_GUIDE.md

Console (Web UI) Guide

The StellaOps Console is the operator-facing web UI. It is built for fast triage and auditability: decisions link back to concrete evidence, and workflows continue to work in air-gapped deployments via Offline Kit snapshots.

This is a usage guide (what the Console does and how to operate it). For UI implementation architecture, see docs/modules/ui/architecture.md.

Scope

• Console workspaces and what each is for
• Common operator workflows (triage, evidence review, exports)
• Offline/air-gap posture and what to expect in the UI
• Links to deeper module documentation

Out of scope: API shapes, schema details, and UI component implementation.

Core Concepts

• Tenant context: most views are tenant-scoped; switching tenants changes what evidence you see and what actions you can take.
• Evidence-linked decisions: verdicts (ship/block/needs-exception) should link to the SBOM facts, advisory/VEX observations, reachability proofs, and policy explanations that justify them.
• Effective VEX: the platform computes an effective status using issuer trust and policy rules, without rewriting upstream VEX (see docs/VEX_CONSENSUS_GUIDE.md).
• Snapshots and staleness: offline sites operate on snapshots; the Console should surface snapshot identity and freshness rather than hide it.

Workspaces (Navigation)

The Console is organized into workspaces. Names vary slightly by build, but the intent is stable:

• Dashboard: fleet status, feed/VEX age, queue depth, and policy posture.
• Scans / SBOM: scan history and scan detail; SBOM viewing and export.
• Findings / Triage: the vulnerability triage surface (case view + evidence rail).
• Advisories & VEX: provider status, conflicts, provenance, and issuer trust.
• Policies: policy packs, previews, promotion workflow, and waiver/exception flows.
• Runs / Scheduler: background jobs, re-evaluation, and reachability/delta work.
• Downloads / Offline: Offline Kit and signed artifact distribution and mirroring.
• Admin: tenants, roles/scopes, clients, quotas, and operational settings.

Common Operator Workflows

Triage a Finding

1. Open Findings and filter to the tenant/environment you care about.
2. Open a finding to review:
   • Verdict + "why" summary
   • Effective VEX status and issuer provenance
   • Reachability/impact signals (when available)
   • Policy explanation trace and the gate that produced the verdict
3. Record a triage action (assign/comment/ack/mute/exception request) with justification.
4. Export an evidence bundle when review, escalation, or offline verification is required.

See docs/VULNERABILITY_EXPLORER_GUIDE.md for the conceptual model and determinism requirements.

AI Remediation and Pull Requests

Sprint: SPRINT_20260112_012_FE_remediation_pr_ui_wiring

The AI Remediate panel provides automated remediation guidance and can create pull requests to fix vulnerabilities.

Opening the AI Remediate Panel:

1. From a finding detail view, click AI Remediate.
2. The panel generates remediation recommendations (upgrade, patch, mitigate, workaround).
3. Review recommendations sorted by priority and effort level.

Creating a Remediation PR:

When SCM connections are configured:

1. Select an SCM connection from the dropdown.
2. Click Open PR to create a pull request with the recommended fix.
3. Monitor progress with the loading indicator.
4. On success, view the PR link, branch name, and CI status.

PR Status Display:

Status	Badge	Description
Draft	Gray	PR created as draft
Open	Green	PR open for review
Review Requested	Green	Review explicitly requested
Approved	Blue	PR approved
Changes Requested	Yellow	Changes requested by reviewer
Merged	Purple	PR merged
Closed	Red	PR closed without merge

CI Status Indicators:

Status	Color	Description
Pending	Yellow	CI checks queued
Running	Yellow	CI checks in progress
Success	Green	All CI checks passed
Failure	Red	One or more CI checks failed
Skipped	Gray	CI checks skipped

When SCM Not Configured:

If no SCM connections are available, the panel shows a link to the Integrations Hub to configure GitHub, GitLab, or other SCM providers.

Error Handling:

Error	Description	Action
No SCM connection	No provider configured	Configure in Integrations Hub
SCM auth failed	Authentication expired	Re-authenticate provider
Repository not found	Repo no longer accessible	Verify repository access
Branch conflict	Branch already exists	Use existing PR or delete branch
Rate limited	API rate limit exceeded	Wait and retry
PR already exists	Duplicate PR	View existing PR

Remediation PR Settings:

Sprint: SPRINT_20260112_012_FE_remediation_pr_ui_wiring (REMPR-FE-004)

Configure remediation PR behavior in Settings > AI > Remediation Pull Requests:

Setting	Default	Description
Enable Remediation PRs	On	Allow creating pull requests from AI suggestions
Attach Evidence Card	On	Include evidence card reference in PR description
Add AI Summary Comment	On	Post AI-generated summary comment on the PR
Auto-assign Reviewers	Off	Automatically assign default reviewers
Apply Default Labels	On	Add configured labels to created PRs

Organization-Level Settings:

Some settings are controlled at the organization level:

• Enabled: If disabled at org level, all PR creation is blocked
• Require Approval: When enabled, PRs require approval before merge
• Default Labels: Labels added automatically to all remediation PRs
• Default Reviewers: Reviewers assigned automatically when enabled

Storage Key: stellaops.remediation-pr.preferences

Review VEX Conflicts and Issuer Trust

• Use Advisories & VEX to see which providers contributed statements, whether signatures verified, and where conflicts exist.
• The Console should not silently hide conflicts; it should show what disagrees and why, and how policy resolved it.

See docs/VEX_CONSENSUS_GUIDE.md for the underlying concepts.

Bootstrap Integrations in the Recommended Order

• Use Setup > Integrations as the first-stop onboarding page for new tenants.
• The Suggested Setup Order card now shows the recommended sequence, a short "why this matters" explanation for each connector class, and a completion badge driven by the live connector counts.
• The intended order is: Registries -> Source Control -> CI/CD -> Advisory & VEX Sources -> Secrets.
• Treat the badges as an onboarding checklist: Done means Stella already has at least one connector in that category; Not started means the category still blocks part of the release-evidence flow.

Contextual Helper and Educational Empty States

• The Stella Helper is no longer route-only on key onboarding surfaces. Dashboard, Approvals, Integrations, topology pages, Deployments, Supply-Chain Data, Unknowns, and Policy Audit now push live context such as no-environments, approval-pending, critical-open, agents-none, no-sbom-components, no-audit-events, empty-table, and empty-list so the helper can explain what the operator should do next.
• Treat helper context wiring as a page-owned responsibility: each page should publish a scoped set of current states, and clear that scope automatically on destroy so stale tips do not leak across routes.
• Empty states should teach, not just report absence. On queue, release, security, topology, and audit screens, prefer: what data is missing, why Stella needs it, and the next action to take.
• The current baseline examples are the Releases catalog, the Audit & Compliance overview, and the shared topology inventory page. All three now explain what should eventually appear in the table, why the page matters, and where the operator should go next when it is empty.
• Route pages should also render the shared About this page panel directly under the title area. The panel opens by default on a first visit, explains key concepts and common actions, and persists the user's collapsed state through StellaPreferencesService.

Sidebar Context

• The sidebar now reuses the canonical navigation metadata as operator-facing context, instead of relying on unlabeled section names alone.
• Section headers should include a short description of what belongs in that area of the product. Keep these explanations one sentence and action-oriented.
• Top-level navigation items may render a short helper line under the label when the sidebar is expanded. Use the canonical item tooltip text first; only add local fallback copy when the route is not present in navigation.config.ts.
• Badge chips should explain what they count. Current examples: Deployments combines failed runs and pending approvals, Releases counts blocked gates, and Vulnerabilities counts critical findings still awaiting triage.
• On first-visit paths, highlight only the next recommended onboarding stop and auto-open its nav group. The current guided order is: Diagnostics -> Integrations -> Scan Image -> Dashboard.

Command Palette Help

• The Ctrl+K palette now supports inline help commands without leaving the current flow.
• Use help: <term> to search the current glossary terms. Example: help: sbom explains the term and routes to the most relevant page for deeper context.
• Use guide: first setup to launch the setup wizard from the palette, with the setup workflow steps surfaced inline first.
• Use guide: scan image to show the scan workflow as ordered inline steps: open the scan form, review supply-chain data, then triage the findings.
• Plain searches can surface Help & Guides results alongside indexed docs/API/Doctor results, so glossary and workflow guidance stays visible even when the user does not type the explicit command prefix.

Glossary Tooltips

• Stella now keeps a central domain glossary in the plain-language service and uses it for both command-palette help results and inline tooltip annotations.
• Tooltip definitions are written for developers, not security specialists. Each definition should answer two questions quickly: what the term means, and why the operator should care.
• Auto-detection wraps only the first occurrence of a term inside a given block of copy to avoid turning whole paragraphs into link soup.
• Shared onboarding surfaces now annotate glossary terms by default: ContextHeaderComponent, both app-empty-state implementations, and the pages that already opted into stellaopsGlossaryTooltip.
• Legacy routed pages that still render raw header.page-header or div.page-header blocks are covered centrally from AppShellComponent, so older screens inherit glossary help without per-page imports.
• High-value terms now covered include: SBOM, VEX, CVE, CVSS, EPSS, KEV, Reachability, DSSE, Attestation, Policy Gate, Policy Pack, Evidence Bundle, Promotion, Exception, Digest, and Provenance.

Status Chip Guidance

• The topbar status chips are part of onboarding, not just diagnostics chrome. Tooltips should explain what each signal means in plain language and what the operator should do when it goes red or stale.
• Current warning states include actionable guidance, such as missing policy baselines or offline advisory feeds, so the tooltip can point the operator at the next setup or recovery step.
• Keep the copy practical: what changed, why it matters to release decisions, and which page or workflow resolves it.

Export and Verify Evidence Bundles

• Exports are intended to be portable and verifiable (audits, incident response, air-gap review).
• Expect deterministic ordering, UTC timestamps, and hash manifests.

See docs/OFFLINE_KIT.md for packaging and offline verification workflows.

Export Evidence Cards (v1.1)

Evidence Cards are single-file exports containing SBOM excerpt, DSSE envelope, and optional Rekor receipt for offline verification.

To export an Evidence Card:

1. Open an evidence pack from Findings or Runs workspace.
2. Click the Export dropdown in the pack viewer header.
3. Select Evidence Card for full export or Evidence Card (Compact) for a smaller file without full SBOM.
4. The browser downloads a .evidence-card.json file.

Evidence Card contents:

• cardId: Unique card identifier
• version: Schema version (e.g., "1.0.0")
• packId: Source evidence pack ID
• subject: Finding/CVE/component metadata
• envelope: DSSE signature envelope (when signed)
• sbomExcerpt: Relevant SBOM component data (full export only)
• rekorReceipt: Sigstore Rekor transparency log receipt (when available)
• contentDigest: SHA-256 digest for verification

Content types:

• Full: application/vnd.stellaops.evidence-card+json
• Compact: application/vnd.stellaops.evidence-card-compact+json

See docs/api/evidence-decision-api.openapi.yaml for the complete schema.

Grey Queue and Unknowns Triage

Sprint: SPRINT_20260112_009_FE_unknowns_queue_ui

The Grey Queue surfaces observations with uncertain status requiring operator attention or additional evidence. This is distinct from the standard triage queue.

Grey Queue Panel Features:

• Band indicator: Shows priority band (HOT, WARM, COLD, GREY) with color coding
• Observation state badge: Displays current state (PendingDeterminization, Disputed, GuardedPass)
• Fingerprint section: Shows deterministic reanalysis fingerprint for reproducibility
• Triggers list: Sorted by receivedAt (descending), shows what events caused reanalysis
• Conflicts section: Highlights conflicting evidence with severity coloring
• Next actions: Badges showing suggested resolution paths (await_vex, run_reachability, manual_review)
• Triage actions: Buttons for resolve, escalate, and defer actions

Observation States:

State	Badge Color	Description
PendingDeterminization	Yellow	Evidence incomplete; monitoring active
Disputed	Orange	Conflicting evidence; manual adjudication required
GuardedPass	Blue	Allowed with runtime guardrails
Resolved	Green	Operator has made a determination

Accessing the Grey Queue:

1. Navigate to Findings > Grey Queue tab.
2. Filter by observation state, priority band, or trigger type.
3. Click an item to open the Grey Queue Panel with full details.
4. Review conflicts and suggested next actions.
5. Take a triage action (resolve, escalate, or defer) with justification.

Conflict Display:

Conflicts show the source disagreements:

• Status mismatch: Different providers report conflicting vulnerability status
• VEX/reachability contradiction: VEX says not_affected but reachability proves otherwise
• Trust tie: Equal trust scores with opposite conclusions

See docs/VEX_CONSENSUS_GUIDE.md for conflict detection semantics.

Risk Line Display

Sprint: SPRINT_20260112_004_FE_risk_line_runtime_trace_ui

The Risk Line is an always-visible summary bar in finding detail views showing reachability evidence at a glance.

Risk Line Sections:

Section	Display	Description
Reachability	Score (0-100%) with progress bar	Likelihood that vulnerable code is reachable from application entry points
Runtime	Badge (Confirmed/Not Observed/Unknown/Pending)	Whether runtime monitoring has observed the vulnerable code path executing
Evidence	Rekor link with log index	Transparency log entry for verifiable evidence timestamp
Method	Badge (Hybrid/Runtime/Static/None)	Analysis method used to determine reachability

Reachability Score Levels:

Level	Score Range	Color	Meaning
High	>= 70%	Red	Strong evidence of reachability; prioritize remediation
Medium	30-69%	Amber	Moderate evidence; may warrant investigation
Low	< 30%	Green	Low likelihood of reachability
Unknown	--	Gray	No reachability analysis available

Runtime Status Badges:

Status	Icon	Color	Description
Confirmed	[+]	Green	Runtime traces observed execution through vulnerable path
Not Observed	[-]	Yellow	Monitoring active but path not observed in window
Pending	[?]	Blue	Analysis in progress
Unknown	[--]	Gray	No runtime monitoring data available

Evidence Link:

When evidence is anchored to a Rekor transparency log:

• Click the Log #NNNNNN link to view the entry in Rekor
• A [OK] badge indicates the log entry has been verified
• The timestamp shows when evidence was recorded

Graceful Fallbacks:

• If reachability data is unavailable, the score displays "--" with "(no data)" hint
• If runtime status is unknown, the UI clearly shows "Unknown" rather than implying "Not Observed"
• Missing Rekor entries display "No Rekor entry" message

Trace Export

Sprint: SPRINT_20260112_004_FE_risk_line_runtime_trace_ui

Export reachability call graphs for offline analysis or integration with other tools.

Export Formats:

Format	Extension	Use Case
GraphSON	.graphson.json	Graph databases (TinkerPop, JanusGraph)
JSON	.trace.json	General purpose, human-readable
SARIF	.sarif	IDE integration, GitHub Code Scanning

To Export a Trace:

1. Open a finding with reachability evidence.
2. In the reachability panel, click Export.
3. Select the desired format.
4. The file downloads with a deterministic filename: {artifactDigest}_{findingId}.{format}

Export Contents:

• Nodes: Functions/methods in the call path with file:line locations
• Edges: Call relationships with type (direct/indirect/virtual/async)
• Runtime confirmation: Which edges were observed in runtime traces
• Metadata: Analysis timestamp, analyzer version, confidence scores

Determinism Guarantee:

Exports use deterministic ordering:

• Nodes sorted by canonical ID
• Edges sorted by (from, to) tuple
• Timestamps in ISO-8601 UTC format

AI Code Guard Badge

Sprint: SPRINT_20260112_010_FE_ai_code_guard_console

The AI Code Guard Badge displays scan results for AI-generated code in scan and PR views.

Badge States:

State	Icon	Color	Description
Pass	Check	Green	No findings or all findings are low severity
Review	Warning	Amber	Warnings requiring human review
Block	X	Red	Critical or high severity findings blocking release
Error	Dash	Gray	Scan encountered an error
Pending	Search	Blue	Scan in progress

Count Badge:

When findings exist, a count badge shows the total with severity-based coloring:

• Critical count > 0: Red background
• High count > 0: Red background (lighter)
• Medium count > 0: Amber background
• Low count > 0: Gray background

Accessibility:

The badge includes proper ARIA attributes:

• role="status" for screen reader announcements
• aria-label with verdict and count (e.g., "AI Code Guard: Block, 3 findings")

Usage:

The badge appears in:

• Scan summary views
• PR/MR check status
• Finding detail headers
• Policy gate results

Binary Diff Explain Panel

Sprint: SPRINT_20260112_010_FE_binary_diff_explain_panel

The Binary Diff Explain Panel shows binary artifact comparison evidence in the evidence panel tabs.

Panel Sections:

Section	Description
Summary	Hash comparison, size delta, modification stats, confidence score
Sections	Binary sections with offset, size, type, and modification status
Symbol Changes	Added/removed/modified symbols with addresses and size changes
Footer	Analysis timestamp and export button

Section Status:

Status	Border Color	Description
Identical	None	Section unchanged between versions
Modified	Amber	Section contents differ
Added	Green	Section exists only in head
Removed	Red	Section exists only in base

Segment Types:

Type	Badge Color	Description
code	Blue	Executable code section (.text)
data	Purple	Writable data section (.data)
rodata	Amber	Read-only data section (.rodata)
header	Gray	File headers
symbol	Green	Symbol tables

Symbol Change Types:

Type	Description
function	Function/method symbol
variable	Data variable symbol
import	Imported symbol from external library
export	Exported public symbol

Confidence Levels:

Level	Score Range	Badge
High	>= 90%	Green "High (95%)"
Medium	70-89%	Amber "Medium (78%)"
Low	< 70%	Red "Low (45%)"

Export:

Click Export to download the full binary diff analysis as JSON for offline review or integration with other tools.

Show More:

When sections or symbols exceed 5 items, a "Show More" button expands the full list. Click "Show Less" to collapse.

Runtime-Confirmed Call Graph

The reachability call graph highlights runtime-confirmed paths:

Legend:

Key	Icon	Color	Description
Runtime Confirmed	[+]	Green	Edge observed in runtime execution traces
Static Analysis	[~]	Indigo	Edge inferred from static code analysis
Unknown	[?]	Gray	Edge status not determined
Entry Point	[>]	Blue	Application entry point or public API
Vulnerable	[!]	Red	Location of vulnerable code

User Settings:

Runtime overlays and trace export can be toggled in Settings > Display Preferences:

• Show Runtime Overlays: Highlight runtime-confirmed edges (default: on)
• Enable Trace Export: Show export actions in reachability panel (default: on)

Display Preferences

Sprint: SPRINT_20260112_004_FE_risk_line_runtime_trace_ui (FE-RISK-006)

The Display Preferences panel allows users to customize triage and finding views. Settings are persisted to browser localStorage and apply immediately.

Access: Navigate to Settings > Display > Triage Display Preferences

Available Settings:

Setting	Default	Description
Show Runtime Overlays	On	Highlight runtime-confirmed edges in call graphs
Enable Trace Export	On	Show GraphSON/JSON/SARIF export buttons in reachability panel
Show Risk Line	On	Display the risk line summary bar in finding detail views
Show Signed Override Indicators	On	Display DSSE badge and Rekor link for signed VEX overrides
Expand Runtime Evidence	Off	Expand runtime evidence section by default

Graph Settings:

Setting	Default	Range	Description
Max Graph Nodes	50	10-200	Maximum nodes to render in call graph visualizations
Runtime Highlight Style	Both	Bold/Color/Both	How runtime-confirmed edges are highlighted

Storage Key: stellaops.display.preferences

Reset: Click Reset to Defaults to restore all settings to their default values.

Offline / Air-Gap Expectations

• The Console must operate against Offline Kit snapshots (no external lookups required).
• The UI should surface snapshot identity and staleness budgets (feeds, VEX, policy versions).
• Upload/import workflows for Offline Kit bundles should be auditable (who imported what, when).

Setup Wizard

The Setup Wizard provides a guided interface for initial platform configuration and reconfiguration. It communicates with the Platform backend via /api/v1/setup/* endpoints.

Wizard Features

• Session-based workflow: Sessions track progress across steps, enabling resume after interruption.
• Step validation: Each step includes Doctor checks that validate configuration before proceeding.
• Dry-run mode: Preview configuration changes before applying them.
• Error handling: Problem+JSON errors are mapped to user-friendly messages with suggested fixes.
• Data freshness: Stale data banners show when cached information may be outdated.
• Retry support: Failed operations can be retried with backoff and attempt tracking.

Wizard Steps

The wizard guides operators through these configuration areas:

Step	Category	Required	Description
Database	Infrastructure	Yes	PostgreSQL connection and migrations
Cache	Infrastructure	Yes	Valkey/Redis connection
Vault	Security	No	HashiCorp Vault, Azure Key Vault, or AWS Secrets Manager
Settings Store	Configuration	No	Consul, etcd, or PostgreSQL-backed configuration
Registry	Integration	No	Container registry connections
Telemetry	Observability	No	OTLP endpoint configuration

Using the Wizard

1. Access the Setup Wizard from Admin > Configuration Wizard or during first-run.
2. Complete required steps (Database, Cache) before optional integrations.
3. Use Test Connection to validate credentials before applying.
4. Review validation checks (Doctor diagnostics) for each step.
5. Use dry-run mode to preview changes before committing.
6. After completion, restart services to apply the configuration.

Determinization Configuration Pane

Sprint: SPRINT_20260112_013_FE_determinization_config_pane

The Determinization Config Pane allows policy admins to view and edit grey queue settings.

Accessing the Configuration Pane:

1. Navigate to Admin > Policy Configuration.
2. Select the Determinization tab.
3. Non-admins see read-only view; admins see an Edit button.

Configuration Sections:

Section	Description
Reanalysis Triggers	Toggle events that trigger grey queue reanalysis
Conflict Handling	Set actions for different conflict types
Environment Thresholds	Configure per-environment (dev/staging/prod) thresholds

Editing Configuration:

1. Click Edit to enter edit mode.
2. Modify trigger toggles, conflict actions, or thresholds.
3. Server-side validation errors appear inline.
4. Provide a change reason (required for audit trail).
5. Click Save to apply changes.
6. View change history in the Audit Log section.

Environment Threshold Presets:

Environment	MinConfidence	MaxEntropy	EPSS Threshold
Development	0.40	0.7	0.6
Staging	0.60	0.5	0.4
Production	0.75	0.3	0.3

Notes:

• Configuration changes require policy-admin scope.
• Changes are audited with timestamp, user, and reason.
• In offline deployments, config is read from Offline Kit bundles.

Reconfiguration

To modify existing configuration:

• Use stella setup --reconfigure (CLI) or Admin > Configuration Wizard (UI).
• Individual steps can be reconfigured without re-running the entire wizard.

See docs/setup/setup-wizard-ux.md for detailed UX specifications and CLI parity.

Security and Access

• Authentication is typically OIDC/OAuth2 via Authority; scopes/roles govern write actions.
• Treat tokens as sensitive; avoid copying secrets into notes/tickets.
• For CSP, scopes, and DPoP posture, see docs/security/console-security.md.

Observability and Accessibility

• UI telemetry and metrics guidance: docs/modules/telemetry/guides/ui-telemetry.md.
• Accessibility baseline and keyboard model: docs/accessibility.md.

Deploy and Install References

• Deployment configuration and health checks: docs/deploy/console.md.
• Container install recipes: docs/operations/console-docker-install.md.

Detailed References

Operator-facing deep dives (Console):

• docs/modules/ui/operations/airgap-console.md
• docs/modules/ui/operations/admin-tenants.md
• docs/modules/ui/operations/forensics.md
• docs/modules/ui/operations/observability-guide.md

UX and interaction contracts:

• docs/modules/ui/guides/ux/TRIAGE_UX_GUIDE.md

Related Docs

• docs/VEX_CONSENSUS_GUIDE.md
• docs/VULNERABILITY_EXPLORER_GUIDE.md
• docs/OFFLINE_KIT.md
• docs/cli-vs-ui-parity.md
• docs/technical/architecture/console-admin-rbac.md
• docs/technical/architecture/console-branding.md