stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 1 Releases Wiki Activity
Files
55464f84984ae579eca18456874ba5ccac6ccf29
git.stella-ops.org/docs/examples/ui-tours.md
root 68da90a11a
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
Restructure solution layout by module
2025-10-28 15:10:40 +02:00

11 KiB
Raw Blame History

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

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.
    Tour A – dashboard criticals
  • docs/assets/ui/tours/triage-step-03.png — filter tray with severity/time window applied.
    Tour A – filter tray
  • docs/assets/ui/tours/triage-step-04.png — explain drawer evidence tab.
    Tour A – explain drawer evidence
  • docs/assets/ui/tours/triage-flow.gif — 20 s screen recording of steps 1–5 with annotations.
    Tour A – walkthrough GIF

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

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).
    Tour B – manifest verification
  • docs/assets/ui/tours/audit-step-05.png — exports tab showing evidence bundle ready.
    Tour B – exports tab
  • docs/assets/ui/tours/audit-flow.gif — 25 s capture from manifest view through export download.
    Tour B – walkthrough GIF

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

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.
    Tour C – editor checklist
  • docs/assets/ui/tours/policy-step-04.png — simulation diff comparing Active vs Staged.
    Tour C – simulation diff
  • docs/assets/ui/tours/policy-flow.gif — 30 s clip from draft view through promotion confirmation.
    Tour C – walkthrough GIF

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

  • Tour scripts cover triage, audit evidence, and policy rollout scenarios requested in DOCS-CONSOLE-23-017.
  • Each tour references authoritative workspace docs and CLI parity commands.
  • Capture checklist names align with docs/assets/ui/tours/ convention.
  • Offline and sealed-mode notes included for every flow.
  • Security considerations (scopes, fresh-auth, evidence handling) highlighted.
  • Observability/telemetry pointers surfaced to support Ops follow-up.
  • Media hygiene guidance documented (assets, compression, versioning).
  • Document timestamp reflects Sprint 23 delivery.

Last updated: 2025-10-27 (Sprint 23).