# 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.

### 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.

### 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.

## 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.

### 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`