up

docs/ui/explainers.md

@@ -0,0 +1,40 @@
+# Policy Explainers (UI)
+
+> **Imposed rule:** Explain views must show evidence hashes, signals, and rule rationale; omit or obfuscate none. AOC tenants must see AOC badge and tenant-only data.
+
+This guide describes how the Console renders explainability for policy decisions.
+
+## 1. Surfaces
+- **Findings table**: each row links to an explainer drawer.
+- **Explainer drawer**: rule stack, inputs, signals, evidence hashes, reachability path, VEX statements, attestation refs.
+- **Timeline tab**: events for submit/approve/publish/activate and recent runs.
+- **Runs tab**: runId, input cursors, IR hash, shadow flag, coverage evidence.
+
+## 2. Drawer layout
+- Header: status, severity, policy version, shadow flag, AOC badge.
+- Evidence panel: SBOM digest, advisory snapshot, VEX IDs, reachability graph hash, runtime hit flag, attestation refs.
+- Rule hits: ordered list with `because`, signals snapshot, actions taken.
+- Reachability path: signed call path when available; shows graph hash + edge bundle hash; link to Verify.
+- Signals: `trust_score`, `reachability.state/score`, `entropy_penalty`, `uncertainty.level`, `runtime_hits`.
+
+## 3. Interactions
+- **Verify evidence**: button triggers `stella policy explain --verify` equivalent; shows DSSE/Rekor status.
+- **Toggle baseline**: compare against previous policy version; highlights changed rules/outcomes.
+- **Download**: export explain as JSON with evidence hashes; offline-friendly.
+
+## 4. Accessibility
+- Keyboard navigation: Tab order header → evidence → rules → actions; Enter activates verify/download.
+- Screen reader labels include status, severity, reachability state, trust score.
+
+## 5. Offline
+- Drawer works on offline bundles; verify uses embedded DSSE/attestations; if Rekor unavailable, show “offline verify” with bundle digest.
+
+## 6. Error states
+- Missing evidence: display `unknown` chips; prompt to rerun when inputs unfrozen.
+- Attestation mismatch: show warning badge and link to governance doc.
+
+## References
+- `docs/policy/overview.md`
+- `docs/policy/runtime.md`
+- `docs/policy/governance.md`
+- `docs/policy/api.md`