# 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/16_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/20_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/16_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/24_OFFLINE_KIT.md` for packaging and offline verification workflows.

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

## 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/observability/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/install/docker.md`.

## Legacy Pages

Several older, topic-specific pages were consolidated into this guide and related canonical docs. The previous locations remain as short "archived" stubs for compatibility:

- `docs/ui/*.md`
- `docs/console/*.md`
- `docs/ux/*.md`
- `docs/vuln/*.md`

## Related Docs

- `docs/16_VEX_CONSENSUS_GUIDE.md`
- `docs/20_VULNERABILITY_EXPLORER_GUIDE.md`
- `docs/24_OFFLINE_KIT.md`
- `docs/cli-vs-ui-parity.md`
- `docs/architecture/console-admin-rbac.md`
- `docs/architecture/console-branding.md`