docs consolidation and others

docs/modules/ui/operations/admin-tenants.md

@@ -0,0 +1,43 @@
+# Console Tenant Administration
+
+This document describes tenant administration workflows in the Console: creating tenants, managing access, and operating safely in multi-tenant deployments.
+
+## Tenant Lifecycle
+
+Typical tenant operations:
+
+- Create and deactivate tenants
+- Configure tenant identity and display attributes (name, tags)
+- Review tenant-level configuration and capabilities (feature exposure is configuration-driven)
+
+## Access Control
+
+Tenant administration typically includes:
+
+- Role assignment (who can operate vs approve vs audit)
+- Scope allocation (what each role is allowed to do)
+- Optional ABAC filters (environment/project constraints)
+
+See:
+
+- `docs/security/scopes-and-roles.md`
+- `docs/security/tenancy-overview.md`
+- `docs/architecture/console-admin-rbac.md`
+
+## Safety and Auditability
+
+- All admin actions must be auditable (who, what, when, tenant).
+- Prefer reversible operations:
+  - deactivate instead of delete
+  - rotate credentials instead of reusing
+- Make tenant context explicit in the UI to avoid cross-tenant mistakes.
+
+## Offline / Air-Gap Notes
+
+- Admin actions should remain available in sealed-mode, but any import/export should be explicit and verified.
+- When operating from Offline Kit snapshots, show snapshot identity and staleness for admin-relevant views (feeds, policies, issuer trust).
+
+## References
+
+- Console operator guide: `docs/UI_GUIDE.md`
+- Offline Kit: `docs/OFFLINE_KIT.md`

docs/modules/ui/operations/airgap-console.md

@@ -0,0 +1,52 @@
+# Console Air-Gap UX (Sealed Mode)
+
+This document describes the Console surfaces and operator expectations when running against Offline Kit snapshots or in sealed/air-gapped deployments.
+
+## Goals
+
+- Make offline operation explicit (never “pretend online”).
+- Show snapshot identity and staleness budgets so operators can reason about freshness.
+- Keep import workflows auditable and tenant-scoped.
+
+## Required Surfaces
+
+### Offline / Sealed Status Badge
+
+The Console should surface:
+
+- Whether the site is operating in **sealed/offline mode**.
+- The current **snapshot identity** (bundle ID / generation / content digest).
+- The **last import time** and configured freshness/staleness budgets.
+
+### Import Workflow
+
+When imports are supported via Console:
+
+- Use a clear stepper flow: select bundle → verify → apply → confirm.
+- Display verification results (signature status, digest) without exposing secrets.
+- Emit an auditable event: who imported what, when, and which snapshot became active.
+
+### Staleness Dashboard
+
+Operators need a quick view of:
+
+- Advisory/VEX/policy ages relative to configured budgets
+- Tenants/environments nearing expiry thresholds
+- “Why stale?” explanations (missing time anchor, expired bundle, etc.)
+
+## Staleness Rules
+
+- Treat staleness as **a first-class signal**: show it prominently when it affects decision confidence.
+- Use UTC timestamps; avoid local time ambiguity.
+- When a time anchor is missing, surface “unknown staleness” instead of silently defaulting.
+
+## Security and Guardrails
+
+- Import is an admin operation (scoped and audited).
+- Always display tenant context for imports and status surfaces.
+- Avoid displaying long hashes without context; prefer short digests with a “copy full digest” action.
+
+## References
+
+- Offline Kit packaging and verification: `docs/OFFLINE_KIT.md`
+- Air-gap workflows: `docs/airgap/`

docs/modules/ui/operations/attestor-ui.md

@@ -0,0 +1,25 @@
+# Attestor UI (Console)
+
+The Console includes surfaces for viewing and verifying attestations produced by StellaOps services.
+
+## Views
+
+- **Attestation list:** filter by tenant, issuer, predicate/type, verification status.
+- **Attestation detail:** show subject, predicate, timestamps, signer identity, and verification outcome.
+- **Verification panel:** signature status, certificate chain/key identity, and transparency proof (when configured).
+
+## Actions
+
+- Download DSSE envelope (and referenced artifacts where applicable)
+- Copy digests and correlation IDs for audit trails
+- Open transparency proof details (when enabled)
+
+## Guardrails
+
+- The UI must not “derive” verdicts from attestations; it should display verification state and referenced evidence.
+- Tenancy must always be explicit; exports should preserve tenant context and verification metadata.
+
+## References
+
+- Console operator guide: `docs/UI_GUIDE.md`
+- Offline Kit verification: `docs/OFFLINE_KIT.md`

docs/modules/ui/operations/forensics.md

@@ -0,0 +1,40 @@
+# Console Forensics and Evidence Review
+
+This document describes how the Console supports forensic review of decisions: timelines, evidence viewing, attestation verification, and audit exports.
+
+## Timeline Explorer
+
+The timeline view should enable:
+
+- Filtering by tenant, artifact, finding, and time window
+- Drill-down from a verdict to its evidence objects (SBOM slice, VEX observation/linkset, reachability proof, policy explain trace)
+- Visibility into operator actions (triage actions, exceptions, approvals) as append-only events
+
+## Evidence Viewer
+
+Evidence viewing should prioritize:
+
+- Clear provenance (issuer identity, timestamps, digests)
+- Verification state (signature verified/failed/unknown)
+- Deterministic identifiers so auditors can replay and compare
+
+## Attestation Verification
+
+When presenting attestations (DSSE/in-toto):
+
+- Display verification status and key identity
+- Link to transparency log proof when configured
+- Allow exporting the DSSE envelope and the referenced artifacts
+
+## Export / Verify Workflows
+
+Exports are the bridge between online and offline review:
+
+- Exports should be deterministic (stable ordering, UTC timestamps).
+- Export bundles should include integrity metadata (digests) so offline reviewers can verify without trusting a live service.
+
+## References
+
+- Console operator guide: `docs/UI_GUIDE.md`
+- Offline Kit: `docs/OFFLINE_KIT.md`
+- Vulnerability Explorer guide (triage model): `docs/VULNERABILITY_EXPLORER_GUIDE.md`

docs/modules/ui/operations/observability-guide.md

@@ -0,0 +1,41 @@
+# Console Observability
+
+This document describes Console observability expectations: what telemetry matters, how to correlate UI actions with backend traces, and what to surface in air-gapped deployments.
+
+## What to Measure (UI)
+
+Recommended UI metrics include:
+
+- **Time-to-verdict (TTFV):** from navigation to verdict banner rendered.
+- **Time-to-evidence:** from clicking a fact/badge to evidence preview available.
+- **Export latency and success rate:** evidence bundle generation time and failures.
+- **Mute/exception usage:** how often operators suppress or escalate findings (counts, reversal rate).
+
+## What to Log (Structured)
+
+Console logs should be structured and tenant-scoped:
+
+- `tenantId`, `actor`, `actionType`
+- `artifactId` / image digest
+- `findingId` / vulnerability identifiers (when relevant)
+- `traceId` / correlation IDs that tie UI requests to backend traces
+
+## Error Surfaces
+
+Operators need actionable error messaging:
+
+- Distinguish client validation errors from server failures.
+- Provide a copyable correlation/trace ID for support.
+- Avoid leaking stack traces or secrets into UI notifications.
+
+## Offline / Sealed Mode Telemetry
+
+In sealed mode, surface:
+
+- snapshot identity and staleness budgets
+- which data is stale vs fresh (policy pack version, VEX snapshot time, feed ages)
+
+## References
+
+- UI telemetry guidance: `docs/observability/ui-telemetry.md`
+- Accessibility baseline: `docs/accessibility.md`

docs/modules/ui/operations/risk-ui.md

@@ -0,0 +1,20 @@
+# Console Risk UI (Overview)
+
+This document describes how risk and explainability concepts should surface in the Console.
+
+## Concepts to Surface
+
+- **Verdict and “why”:** a short, narrative explanation above the fold.
+- **Evidence rail:** links to proofs that justify each fact (SBOM, VEX, reachability, policy explain trace).
+- **Risk signals:** severity, exploit signals, exposure context, and confidence/uncertainty indicators.
+
+## Explainability Expectations
+
+- Every blocking decision must link to the policy gate and the evidence inputs that triggered it.
+- Uncertainty must remain explicit (avoid false safety when evidence is missing or conflicts exist).
+
+## References
+
+- Risk model overview: `docs/modules/risk-engine/guides/overview.md`
+- Policy explainability: `docs/modules/risk-engine/guides/explainability.md`
+- Vulnerability Explorer guide: `docs/VULNERABILITY_EXPLORER_GUIDE.md`