Restructure solution layout by module
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
This commit is contained in:
root
@@ -1,154 +1,154 @@
|
||||
# StellaOps Console – Guided Tours (Sprint 23)
|
||||
|
||||
> **Audience:** Field enablement, Docs Guild writers, Console product leads, and onboarding facilitators.
|
||||
> **Scope:** Ready-to-run walkthrough scripts that showcase the Console’s critical workflows—triage, audit evidence, and policy rollout—while reinforcing CLI parity, tenancy, and offline expectations.
|
||||
|
||||
These tours stitch together the primary Console workspaces so trainers can deliver consistent demos or capture annotated media (screenshots/GIFs). Each tour lists prerequisites, live steps, CLI fallbacks, and assets to capture. Use them alongside the workspace dossiers in `/docs/ui/*.md` when preparing customer sessions or internal dry runs.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Prerequisites & Setup
|
||||
|
||||
- **Environment:** Console deployed per [deployment guide](../deploy/console.md) with Scheduler, Policy Engine, Concelier, Excititor, SBOM Service, and Downloads manifest available.
|
||||
- **Tenant & data:** Sample tenant populated with recent scans, findings, runs, and export bundles. Ensure Offline Kit snapshot exists for offline callouts.
|
||||
- **Scopes:** Presenter identity must hold `ui.read`, `findings.read`, `policy:*` (read/write/simulate/approve), `runs.read`, `downloads.read`, `aoc:verify`, and `ui.telemetry` to surface telemetry banners.
|
||||
- **Browser tooling:** Enable screen recording (1920×1080 @ 60 fps) and keyboard overlay if capturing walkthroughs.
|
||||
- **CLI parity:** Have `stella` CLI configured against the same tenant; keep terminal window ready for parity steps.
|
||||
- **Assets directory:** Store captures under `docs/assets/ui/tours/` (see [`README`](../assets/ui/tours/README.md)) with the naming convention `<tour>-step-<nn>.png` and `<tour>-flow.gif`.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Tour A — Critical Finding Triage
|
||||
|
||||
**Persona:** Security analyst responding to a fresh high-severity finding.
|
||||
**Goal:** Navigate from dashboard signal to remediation decision, highlighting explain trails and run evidence.
|
||||
|
||||
### 2.1 Key references
|
||||
- [Console overview](../ui/console-overview.md) – tenant switching, status ticker.
|
||||
- [Navigation](../ui/navigation.md) – command palette, shortcuts.
|
||||
- [Findings workspace](../ui/findings.md) – filters, explain drawer, exports.
|
||||
- [Runs workspace](../ui/runs.md) – live progress, evidence downloads.
|
||||
|
||||
### 2.2 Live walkthrough
|
||||
1. **Start on Dashboard:** Show status ticker surfacing new `Critical` badge. Call out tenant pill and offline banner behaviour (§3 of console overview).
|
||||
2. **Command palette jump:** Press `Ctrl/Cmd+K`, type `Findings`, hit `Enter`. Narrate keyboard accessibility from navigation guide.
|
||||
3. **Apply global filters:** Open filter tray (`Shift+F`), set `Severity = Critical`, `Status = affected`, time window `Last 24h`. Mention saved view presets triggered with `Ctrl/Cmd+1`.
|
||||
4. **Open explain drawer:** Select top finding, trigger `Explain` tab. Highlight rule chain, VEX impact, and evidence references (§5 of findings doc).
|
||||
5. **Dive into related run:** Click `Run ID` link inside explain drawer → opens Runs detail drawer filtered by run ID. Show segmented progress SSE updates.
|
||||
6. **Capture evidence:** In Runs drawer, download evidence bundle; note CLI parity `stella runs export --run <id>`. Mention offline fallback (download queue offline banner from runs doc §10).
|
||||
7. **Escalate / create ticket:** Use bulk action or comment (if configured) to demonstrate optional integration; mention Authority audit log tie-in.
|
||||
8. **Wrap with CLI:** Pop terminal and run `stella findings explain --policy <id> --finding <key> --format markdown` to show reproducibility.
|
||||
|
||||
### 2.3 Capture checklist
|
||||
- `docs/assets/ui/tours/triage-step-01.png` — dashboard ticker highlighting new criticals.
|
||||
|
||||
- `docs/assets/ui/tours/triage-step-03.png` — filter tray with severity/time window applied.
|
||||
|
||||
- `docs/assets/ui/tours/triage-step-04.png` — explain drawer evidence tab.
|
||||
|
||||
- `docs/assets/ui/tours/triage-flow.gif` — 20 s screen recording of steps 1–5 with annotations.
|
||||
|
||||
|
||||
### 2.4 Talking points & callouts
|
||||
- Call out Aggregation-Only boundaries: findings reference Concelier/Excititor provenance, UI stays read-only.
|
||||
- Mention `ui_route_render_seconds` telemetry for demos (see [observability guide](../observability/ui-telemetry.md)).
|
||||
- Offline note: highlight offline banner that appears if `/console/status` heartbeat fails (§6 of console overview).
|
||||
|
||||
---
|
||||
|
||||
## 3 · Tour B — Audit Evidence Export
|
||||
|
||||
**Persona:** Compliance lead compiling artefacts for an external audit.
|
||||
**Goal:** Retrieve signed manifests, export run/finding evidence, and verify parity with Offline Kit.
|
||||
|
||||
### 3.1 Key references
|
||||
- [Downloads workspace](../ui/downloads.md) – manifest, parity, export queue.
|
||||
- [Runs workspace](../ui/runs.md) – evidence panel.
|
||||
- [Console security posture](../security/console-security.md) – evidence handling.
|
||||
- [CLI vs UI parity matrix](../cli-vs-ui-parity.md).
|
||||
|
||||
### 3.2 Live walkthrough
|
||||
1. **Open Downloads:** Use left rail or command palette to reach `/console/downloads`. Point out snapshot banner, cosign verification status.
|
||||
2. **Verify manifest:** Click “Verify signature” quick action; narrate parity with `cosign verify --key <key> manifest.json` from downloads doc §3.
|
||||
3. **Compare Offline Kit:** Switch to “Offline Kits” tab, run parity check to ensure kit digest matches manifest. Demonstrate offline guidance (downloads doc §6).
|
||||
4. **Queue evidence bundle:** Navigate to Runs workspace, choose relevant run, trigger “Bundle for offline” (runs doc §8).
|
||||
5. **Return to Downloads → Exports tab:** Show newly generated evidence bundle with retention countdown.
|
||||
6. **Download & inspect:** Open detail drawer, copy CLI command `stella runs export --run <id> --bundle`. Mention location for storing evidence.
|
||||
7. **Log parity results:** Use notes or tags to flag audit package completion (if notifications configured).
|
||||
8. **CLI parity close-out:** Run `stella downloads manifest --channel stable` to mirror UI manifest retrieval. Confirm digests match.
|
||||
|
||||
### 3.3 Capture checklist
|
||||
- `docs/assets/ui/tours/audit-step-02.png` — manifest verification banner (green).
|
||||
|
||||
- `docs/assets/ui/tours/audit-step-05.png` — exports tab showing evidence bundle ready.
|
||||
|
||||
- `docs/assets/ui/tours/audit-flow.gif` — 25 s capture from manifest view through export download.
|
||||
|
||||
|
||||
### 3.4 Talking points & callouts
|
||||
- Stress deterministic manifests and Cosign signatures; reference deployment doc for TLS/CSP alignment.
|
||||
- Highlight audit trail: downloads actions recorded via `ui.download.commandCopied` logs and Authority audit entries.
|
||||
- Offline note: show guidance when parity check detects stale manifest; mention CLI fallback for sealed networks.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Tour C — Policy Rollout & Promotion
|
||||
|
||||
**Persona:** Policy owner preparing and promoting a new ruleset.
|
||||
**Goal:** Draft review, simulation, approval, and promotion within Console, with CLI parity.
|
||||
|
||||
### 4.1 Key references
|
||||
- [Policies workspace](../ui/policies.md) – simulations, approvals, promotion.
|
||||
- [Policy editor](../ui/policy-editor.md) – Monaco editor, linting.
|
||||
- [Runs workspace](../ui/runs.md) – policy run monitoring.
|
||||
- [Security posture](../security/console-security.md) – fresh-auth and scopes.
|
||||
|
||||
### 4.2 Live walkthrough
|
||||
1. **Policy overview:** Open `/console/policies`, filter by “Staged” state. Highlight list columns (owners, pending approvals).
|
||||
2. **Enter draft:** Select policy → open editor view. Show checklist sidebar (lint, simulation, determinism).
|
||||
3. **Run lint & simulation:** Hit `Run lint`, then `Run simulation`. Narrate asynchronous progress with SSE ticker; reference CLI `stella policy simulate`.
|
||||
4. **Review diff:** Open simulation diff view to compare Active vs Staged; highlight severity up/down badges (§6 of policies doc).
|
||||
5. **Approval workflow:** Assign reviewer, show comment thread. Trigger fresh-auth prompt when clicking “Submit for review” (security doc §1.2).
|
||||
6. **Promote policy:** After approvals, open promotion dialog, choose “Full run”. Emphasise policy run scheduling and RBAC.
|
||||
7. **Monitor run:** Jump to Runs workspace, filter by policy run; show progress segments and findings delta metrics.
|
||||
8. **Publish CLI parity:** Execute `stella policy promote --policy <id> --revision <rev> --run-mode full` to reinforce reproducibility.
|
||||
|
||||
### 4.3 Capture checklist
|
||||
- `docs/assets/ui/tours/policy-step-02.png` — editor checklist with lint/simulation statuses.
|
||||
|
||||
- `docs/assets/ui/tours/policy-step-04.png` — simulation diff comparing Active vs Staged.
|
||||
|
||||
- `docs/assets/ui/tours/policy-flow.gif` — 30 s clip from draft view through promotion confirmation.
|
||||
|
||||
|
||||
### 4.4 Talking points & callouts
|
||||
- Stress governance: approvals logged with correlation IDs, fresh-auth enforced.
|
||||
- Mention telemetry metrics (`ui_tenant_switch_total`, policy run charts) for monitoring adoption.
|
||||
- Offline note: show how promotion dialog surfaces CLI script when in sealed mode; reference offline guidance in policies doc §10.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Production Tips & Media Hygiene
|
||||
|
||||
- **Script timing:** Keep each tour ≤ 3 minutes live demo, ≤ 30 s GIF. Include captions for accessibility.
|
||||
- **Annotations:** Use consistent callouts (numbered badges, short labels) overlayed in post-processing; ensure final media compressed but legible (< 2 MB PNG, < 8 MB GIF). See `docs/assets/ui/tours/README.md` for shared template guidance.
|
||||
- **Versioning:** Annotated assets should include Console build hash in metadata or caption (align with `/console/downloads` manifest version).
|
||||
- **Storage:** Commit final media under `docs/assets/ui/tours/` and update `.gitattributes` if smudge filters required. Note large GIFs may need Git LFS depending on repository policy.
|
||||
- **Review cadence:** Re-run tours whenever workspaces change navigation or introduce new buttons; log updates in `docs/updates/<date>-console-tours.md` (create if absent).
|
||||
|
||||
---
|
||||
|
||||
## 6 · Compliance Checklist
|
||||
|
||||
- [x] Tour scripts cover triage, audit evidence, and policy rollout scenarios requested in DOCS-CONSOLE-23-017.
|
||||
- [x] Each tour references authoritative workspace docs and CLI parity commands.
|
||||
- [x] Capture checklist names align with `docs/assets/ui/tours/` convention.
|
||||
- [x] Offline and sealed-mode notes included for every flow.
|
||||
- [x] Security considerations (scopes, fresh-auth, evidence handling) highlighted.
|
||||
- [x] Observability/telemetry pointers surfaced to support Ops follow-up.
|
||||
- [x] Media hygiene guidance documented (assets, compression, versioning).
|
||||
- [x] Document timestamp reflects Sprint 23 delivery.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 23).*
|
||||
# StellaOps Console – Guided Tours (Sprint 23)
|
||||
|
||||
> **Audience:** Field enablement, Docs Guild writers, Console product leads, and onboarding facilitators.
|
||||
> **Scope:** Ready-to-run walkthrough scripts that showcase the Console’s critical workflows—triage, audit evidence, and policy rollout—while reinforcing CLI parity, tenancy, and offline expectations.
|
||||
|
||||
These tours stitch together the primary Console workspaces so trainers can deliver consistent demos or capture annotated media (screenshots/GIFs). Each tour lists prerequisites, live steps, CLI fallbacks, and assets to capture. Use them alongside the workspace dossiers in `/docs/ui/*.md` when preparing customer sessions or internal dry runs.
|
||||
|
||||
---
|
||||
|
||||
## 1 · Prerequisites & Setup
|
||||
|
||||
- **Environment:** Console deployed per [deployment guide](../deploy/console.md) with Scheduler, Policy Engine, Concelier, Excititor, SBOM Service, and Downloads manifest available.
|
||||
- **Tenant & data:** Sample tenant populated with recent scans, findings, runs, and export bundles. Ensure Offline Kit snapshot exists for offline callouts.
|
||||
- **Scopes:** Presenter identity must hold `ui.read`, `findings.read`, `policy:*` (read/write/simulate/approve), `runs.read`, `downloads.read`, `aoc:verify`, and `ui.telemetry` to surface telemetry banners.
|
||||
- **Browser tooling:** Enable screen recording (1920×1080 @ 60 fps) and keyboard overlay if capturing walkthroughs.
|
||||
- **CLI parity:** Have `stella` CLI configured against the same tenant; keep terminal window ready for parity steps.
|
||||
- **Assets directory:** Store captures under `docs/assets/ui/tours/` (see [`README`](../assets/ui/tours/README.md)) with the naming convention `<tour>-step-<nn>.png` and `<tour>-flow.gif`.
|
||||
|
||||
---
|
||||
|
||||
## 2 · Tour A — Critical Finding Triage
|
||||
|
||||
**Persona:** Security analyst responding to a fresh high-severity finding.
|
||||
**Goal:** Navigate from dashboard signal to remediation decision, highlighting explain trails and run evidence.
|
||||
|
||||
### 2.1 Key references
|
||||
- [Console overview](../ui/console-overview.md) – tenant switching, status ticker.
|
||||
- [Navigation](../ui/navigation.md) – command palette, shortcuts.
|
||||
- [Findings workspace](../ui/findings.md) – filters, explain drawer, exports.
|
||||
- [Runs workspace](../ui/runs.md) – live progress, evidence downloads.
|
||||
|
||||
### 2.2 Live walkthrough
|
||||
1. **Start on Dashboard:** Show status ticker surfacing new `Critical` badge. Call out tenant pill and offline banner behaviour (§3 of console overview).
|
||||
2. **Command palette jump:** Press `Ctrl/Cmd+K`, type `Findings`, hit `Enter`. Narrate keyboard accessibility from navigation guide.
|
||||
3. **Apply global filters:** Open filter tray (`Shift+F`), set `Severity = Critical`, `Status = affected`, time window `Last 24h`. Mention saved view presets triggered with `Ctrl/Cmd+1`.
|
||||
4. **Open explain drawer:** Select top finding, trigger `Explain` tab. Highlight rule chain, VEX impact, and evidence references (§5 of findings doc).
|
||||
5. **Dive into related run:** Click `Run ID` link inside explain drawer → opens Runs detail drawer filtered by run ID. Show segmented progress SSE updates.
|
||||
6. **Capture evidence:** In Runs drawer, download evidence bundle; note CLI parity `stella runs export --run <id>`. Mention offline fallback (download queue offline banner from runs doc §10).
|
||||
7. **Escalate / create ticket:** Use bulk action or comment (if configured) to demonstrate optional integration; mention Authority audit log tie-in.
|
||||
8. **Wrap with CLI:** Pop terminal and run `stella findings explain --policy <id> --finding <key> --format markdown` to show reproducibility.
|
||||
|
||||
### 2.3 Capture checklist
|
||||
- `docs/assets/ui/tours/triage-step-01.png` — dashboard ticker highlighting new criticals.
|
||||
|
||||
- `docs/assets/ui/tours/triage-step-03.png` — filter tray with severity/time window applied.
|
||||
|
||||
- `docs/assets/ui/tours/triage-step-04.png` — explain drawer evidence tab.
|
||||
|
||||
- `docs/assets/ui/tours/triage-flow.gif` — 20 s screen recording of steps 1–5 with annotations.
|
||||
|
||||
|
||||
### 2.4 Talking points & callouts
|
||||
- Call out Aggregation-Only boundaries: findings reference Concelier/Excititor provenance, UI stays read-only.
|
||||
- Mention `ui_route_render_seconds` telemetry for demos (see [observability guide](../observability/ui-telemetry.md)).
|
||||
- Offline note: highlight offline banner that appears if `/console/status` heartbeat fails (§6 of console overview).
|
||||
|
||||
---
|
||||
|
||||
## 3 · Tour B — Audit Evidence Export
|
||||
|
||||
**Persona:** Compliance lead compiling artefacts for an external audit.
|
||||
**Goal:** Retrieve signed manifests, export run/finding evidence, and verify parity with Offline Kit.
|
||||
|
||||
### 3.1 Key references
|
||||
- [Downloads workspace](../ui/downloads.md) – manifest, parity, export queue.
|
||||
- [Runs workspace](../ui/runs.md) – evidence panel.
|
||||
- [Console security posture](../security/console-security.md) – evidence handling.
|
||||
- [CLI vs UI parity matrix](../cli-vs-ui-parity.md).
|
||||
|
||||
### 3.2 Live walkthrough
|
||||
1. **Open Downloads:** Use left rail or command palette to reach `/console/downloads`. Point out snapshot banner, cosign verification status.
|
||||
2. **Verify manifest:** Click “Verify signature” quick action; narrate parity with `cosign verify --key <key> manifest.json` from downloads doc §3.
|
||||
3. **Compare Offline Kit:** Switch to “Offline Kits” tab, run parity check to ensure kit digest matches manifest. Demonstrate offline guidance (downloads doc §6).
|
||||
4. **Queue evidence bundle:** Navigate to Runs workspace, choose relevant run, trigger “Bundle for offline” (runs doc §8).
|
||||
5. **Return to Downloads → Exports tab:** Show newly generated evidence bundle with retention countdown.
|
||||
6. **Download & inspect:** Open detail drawer, copy CLI command `stella runs export --run <id> --bundle`. Mention location for storing evidence.
|
||||
7. **Log parity results:** Use notes or tags to flag audit package completion (if notifications configured).
|
||||
8. **CLI parity close-out:** Run `stella downloads manifest --channel stable` to mirror UI manifest retrieval. Confirm digests match.
|
||||
|
||||
### 3.3 Capture checklist
|
||||
- `docs/assets/ui/tours/audit-step-02.png` — manifest verification banner (green).
|
||||
|
||||
- `docs/assets/ui/tours/audit-step-05.png` — exports tab showing evidence bundle ready.
|
||||
|
||||
- `docs/assets/ui/tours/audit-flow.gif` — 25 s capture from manifest view through export download.
|
||||
|
||||
|
||||
### 3.4 Talking points & callouts
|
||||
- Stress deterministic manifests and Cosign signatures; reference deployment doc for TLS/CSP alignment.
|
||||
- Highlight audit trail: downloads actions recorded via `ui.download.commandCopied` logs and Authority audit entries.
|
||||
- Offline note: show guidance when parity check detects stale manifest; mention CLI fallback for sealed networks.
|
||||
|
||||
---
|
||||
|
||||
## 4 · Tour C — Policy Rollout & Promotion
|
||||
|
||||
**Persona:** Policy owner preparing and promoting a new ruleset.
|
||||
**Goal:** Draft review, simulation, approval, and promotion within Console, with CLI parity.
|
||||
|
||||
### 4.1 Key references
|
||||
- [Policies workspace](../ui/policies.md) – simulations, approvals, promotion.
|
||||
- [Policy editor](../ui/policy-editor.md) – Monaco editor, linting.
|
||||
- [Runs workspace](../ui/runs.md) – policy run monitoring.
|
||||
- [Security posture](../security/console-security.md) – fresh-auth and scopes.
|
||||
|
||||
### 4.2 Live walkthrough
|
||||
1. **Policy overview:** Open `/console/policies`, filter by “Staged” state. Highlight list columns (owners, pending approvals).
|
||||
2. **Enter draft:** Select policy → open editor view. Show checklist sidebar (lint, simulation, determinism).
|
||||
3. **Run lint & simulation:** Hit `Run lint`, then `Run simulation`. Narrate asynchronous progress with SSE ticker; reference CLI `stella policy simulate`.
|
||||
4. **Review diff:** Open simulation diff view to compare Active vs Staged; highlight severity up/down badges (§6 of policies doc).
|
||||
5. **Approval workflow:** Assign reviewer, show comment thread. Trigger fresh-auth prompt when clicking “Submit for review” (security doc §1.2).
|
||||
6. **Promote policy:** After approvals, open promotion dialog, choose “Full run”. Emphasise policy run scheduling and RBAC.
|
||||
7. **Monitor run:** Jump to Runs workspace, filter by policy run; show progress segments and findings delta metrics.
|
||||
8. **Publish CLI parity:** Execute `stella policy promote --policy <id> --revision <rev> --run-mode full` to reinforce reproducibility.
|
||||
|
||||
### 4.3 Capture checklist
|
||||
- `docs/assets/ui/tours/policy-step-02.png` — editor checklist with lint/simulation statuses.
|
||||
|
||||
- `docs/assets/ui/tours/policy-step-04.png` — simulation diff comparing Active vs Staged.
|
||||
|
||||
- `docs/assets/ui/tours/policy-flow.gif` — 30 s clip from draft view through promotion confirmation.
|
||||
|
||||
|
||||
### 4.4 Talking points & callouts
|
||||
- Stress governance: approvals logged with correlation IDs, fresh-auth enforced.
|
||||
- Mention telemetry metrics (`ui_tenant_switch_total`, policy run charts) for monitoring adoption.
|
||||
- Offline note: show how promotion dialog surfaces CLI script when in sealed mode; reference offline guidance in policies doc §10.
|
||||
|
||||
---
|
||||
|
||||
## 5 · Production Tips & Media Hygiene
|
||||
|
||||
- **Script timing:** Keep each tour ≤ 3 minutes live demo, ≤ 30 s GIF. Include captions for accessibility.
|
||||
- **Annotations:** Use consistent callouts (numbered badges, short labels) overlayed in post-processing; ensure final media compressed but legible (< 2 MB PNG, < 8 MB GIF). See `docs/assets/ui/tours/README.md` for shared template guidance.
|
||||
- **Versioning:** Annotated assets should include Console build hash in metadata or caption (align with `/console/downloads` manifest version).
|
||||
- **Storage:** Commit final media under `docs/assets/ui/tours/` and update `.gitattributes` if smudge filters required. Note large GIFs may need Git LFS depending on repository policy.
|
||||
- **Review cadence:** Re-run tours whenever workspaces change navigation or introduce new buttons; log updates in `docs/updates/<date>-console-tours.md` (create if absent).
|
||||
|
||||
---
|
||||
|
||||
## 6 · Compliance Checklist
|
||||
|
||||
- [x] Tour scripts cover triage, audit evidence, and policy rollout scenarios requested in DOCS-CONSOLE-23-017.
|
||||
- [x] Each tour references authoritative workspace docs and CLI parity commands.
|
||||
- [x] Capture checklist names align with `docs/assets/ui/tours/` convention.
|
||||
- [x] Offline and sealed-mode notes included for every flow.
|
||||
- [x] Security considerations (scopes, fresh-auth, evidence handling) highlighted.
|
||||
- [x] Observability/telemetry pointers surfaced to support Ops follow-up.
|
||||
- [x] Media hygiene guidance documented (assets, compression, versioning).
|
||||
- [x] Document timestamp reflects Sprint 23 delivery.
|
||||
|
||||
---
|
||||
|
||||
*Last updated: 2025-10-27 (Sprint 23).*
|
||||
|
||||
Reference in New Issue
Block a user