git.stella-ops.org/docs/qa/FIRST_TIME_USER_AUDIT_20260316.md

First-Time User Audit — Stella Ops

Date: 2026-03-16 Method: Documentation review + Playwright live walkthrough (41 pages) + source analysis Stack: 63 containers, 111/111 canonical routes passing, demo-prod tenant

---

Executive Summary

Stella Ops is technically impressive — 41 pages load without crashes, all 111 routes pass, and the product surface is vast (releases, security, evidence, policy, operations, integrations, administration). However, a first-time user faces significant onboarding friction: the product assumes prior knowledge, empty states don't guide next steps, and the navigation depth is overwhelming without a guided tour.

41 pages audited, 27 findings identified (4 critical, 8 high, 10 medium, 5 low).

---

Findings

CRITICAL

C1. No 404 Page — Unknown Routes Show Dashboard

Route: /nonexistent-route-12345 → renders Dashboard (title: "Dashboard") Impact: Users who mistype URLs or follow stale links see the dashboard instead of "Page Not Found". They won't realize they're in the wrong place. Solution: Add a wildcard catch-all route that renders a dedicated 404 component with: "This page doesn't exist" message, search bar, and links to common pages. Effort: S Files: src/Web/StellaOps.Web/src/app/app.routes.ts — add { path: '**', component: NotFoundComponent }

C2. System Health / Signals / Dead-Letter Show Error Text

Routes: /ops/operations/system-health, /ops/operations/signals, /ops/operations/dead-letter Impact: Three operational pages show visible error text to the user. On a fresh setup, this makes the platform look broken. Solution: Replace raw error text with the ErrorStateComponent pattern (alert icon + "Something went wrong" + retry button). For fresh installs, show "No data yet" instead of errors. Effort: M Files: System health, signals, dead-letter component .ts files

C3. Documentation Mentions Internal Codenames Without Explanation

Impact: Docs reference "Concelier", "Excititor", "VexHub", "VexLens" without explaining what they are. The Feature Matrix says "Concelier + CLI" for advisory ingest. A new user won't know these are service names. Solution: Add a glossary section to docs/README.md or a standalone docs/GLOSSARY.md. In each doc that mentions a codename, add a brief parenthetical: "Concelier (the advisory feed aggregator)". Effort: M Files: docs/README.md, docs/GLOSSARY.md (new), docs/CONCELIER_CLI_QUICKSTART.md

C4. Feature Matrix Shows Release Orchestration as "Planned" (⏳) but UI Is Built

Impact: The Feature Matrix (rev 5.1, Jan 2026) lists Environment CRUD, Release Bundles, Promotion Workflows, etc. all as ⏳ (planned). But the live UI has working releases, approvals, promotions, environments. A buyer reading this would think the product can't do releases yet. Solution: Update docs/FEATURE_MATRIX.md to reflect current implementation status. Mark shipped features with ✅. Effort: M Files: docs/FEATURE_MATRIX.md

---

HIGH

H1. No Onboarding Wizard or First-Run Detection

Impact: After login, the user lands on the Mission Control dashboard with mock/seed data. There's no "Welcome to Stella Ops — let's set up your first environment" flow. The Platform Setup page exists but isn't discoverable from the dashboard. Solution: Add a first-run banner on the Dashboard that detects if the tenant has 0 real environments/targets configured. Show: "Welcome! Start by setting up your deployment topology" with a CTA to /ops/platform-setup/topology-wizard. Effort: M Files: dashboard-v3.component.ts, new first-run-banner.component.ts

H2. Sidebar Has 40+ Items — No Progressive Disclosure

Impact: The sidebar shows all navigation items at once: Releases (6 children), Operations (11 children), Security (6 children), Evidence (6 children), Setup (8+ children). A first-time user doesn't know where to start. Solution: Consider collapsing all groups by default for first-time users (or until the user has interacted). Add a "Getting Started" pinned item at the top of the sidebar that links to a setup checklist. Effort: M Files: app-sidebar.component.ts

H3. No "What Is This?" Help on Complex Pages

Impact: Pages like "Policy Decisioning Studio", "Decision Capsules", "Shadow Mode", "Promotion Gate", "Risk Budget" use domain-specific language without inline help. A new user can't understand what these do. Solution: Add (?) tooltip icons next to page titles that show a 2-sentence explanation. Use the existing glossary/tooltip component pattern. Effort: L Files: Multiple page components, new help-tooltip.component.ts

H4. Tenant Switching Not Obvious

Impact: The tenant selector is in the secondary topbar row, which may not be visible or recognizable. Demo has 3 tenants but users might not know they can switch. Solution: If multiple tenants are available, show a more prominent tenant indicator. Consider adding tenant context to the breadcrumb trail. Effort: S Files: app-topbar.component.ts

H5. Quickstart Doesn't Mention Default Credentials

Impact: The quickstart guide says "Open https://stella-ops.local" but doesn't tell the user what credentials to use. The login page shows an OIDC form. User has to guess or search the seed SQL. Solution: Add to docs/quickstart.md after step 5: "Log in with: admin / Admin@Stella2026! (demo-prod tenant)". Effort: S Files: docs/quickstart.md

H6. Empty Integrations Hub on Fresh Install

Routes: /setup/integrations, /setup/integrations/registries, /setup/integrations/scm Impact: All integration categories show "No connector plugins installed" with disabled "+ Add" buttons. There's no explanation of what plugins are or how to get them. User hits a dead end. Solution: Add a "Getting started with integrations" card that explains: plugins are installed via the CLI or Docker overlays. Link to docs/PLUGIN_SDK_GUIDE.md. For the advisory/VEX section, highlight that it works out of the box (75 sources). Effort: M Files: integrations-hub.component.ts

H7. Topology Setup Shows "Loading" Without Progress

Route: /setup/topology Impact: The topology overview shows a "Loading" state on page load without indicating what it's loading or how long it'll take. On slow networks this could look stuck. Solution: Add a skeleton loader pattern and "Loading topology data..." text. If the load takes >5s, show a retry option. Effort: S Files: Topology overview component

H8. UI Guide References Workspace Names That Don't Match Sidebar

Impact: docs/UI_GUIDE.md lists workspaces as "Scans/SBOM", "Findings/Triage", "Advisories & VEX", "Runs/Scheduler", "Downloads/Offline". But the sidebar uses "Security Posture", "Supply-Chain Data", "Disposition", "Scheduled Jobs", "Offline Kit". Names don't match. Solution: Update docs/UI_GUIDE.md workspace names to match the current sidebar labels exactly. Effort: S Files: docs/UI_GUIDE.md

---

MEDIUM

M1. Dashboard Shows Seed Data That Looks Real

Impact: The Mission Board shows "Active Promotions: 2", "Blocked: 1", environments with risk scores, SBOM metrics. These are seed/mock values but look like real production data. A new user can't tell what's real vs. demo. Solution: Add a subtle "Demo data" indicator on cards populated from seed data. Or detect when the tenant is demo-prod and show a dismissible banner: "You're viewing demo data. Create your own environment to see real metrics." Effort: M

M2. Security Posture "Configure sources" Links to Ops Route

Route: /security/posture Impact: The "Configure sources" action links to /ops/integrations/advisory-vex-sources (ops path) instead of /setup/integrations/advisory-vex-sources (setup path). This inconsistency may confuse users who navigated through Setup. Effort: S

M3. Evidence "Decision Capsules" Name Is Unclear

Route: /evidence/capsules Impact: "Decision Capsules" is a unique Stella Ops term. Without context, a first-time user won't know what this page does. The page renders content but the concept isn't self-documenting. Solution: Add a subtitle under the heading: "Sealed evidence bundles that package inputs, verdicts, and approvals for each release decision." Effort: S

M4. Policy Studio Needs a "What to Do First" Panel

Route: /ops/policy/overview Impact: The Policy Decisioning Studio has many tabs (Baselines, Gates, Simulation, Waivers, Risk Budget, etc.) but no guidance on what order to use them. New users don't know if they should start with baselines, gates, or simulation. Solution: Add a collapsible "Getting Started with Policies" panel that suggests: 1. Review baselines → 2. Define gates → 3. Test with simulation → 4. Enable shadow mode. Effort: M

M5. "Ctrl+K" Command Palette Not Shown as Hint

Impact: The command palette is powerful (search + quick actions) but there's no UI hint that it exists. Users who don't know the shortcut will miss it entirely. Solution: Add a "Search (Ctrl+K)" pill in the topbar search area. The current search icon doesn't communicate the keyboard shortcut. Effort: S

M6. Operations Hub Has 11+ Sub-pages Without Grouping

Route: /ops/operations Impact: Jobs, Signals, Offline Kit, Dead Letter, AOC, Doctor, Packs, AI Runs, Notifications, Status — these are listed flat without category headers. New users can't prioritize. Solution: Group operations into: "Health & Monitoring" (System Health, SLO, Doctor, Signals), "Job Management" (JobEngine, Scheduler, Dead Letter, Packs), "Other" (Offline Kit, AOC, AI Runs). Effort: M

M7. Admin Pages Duplicated Across /setup and /administration Routes

Impact: /setup/identity-access and /administration/identity-access exist. /setup/trust-signing and /administration/trust-signing redirect to the same components. This route duplication is confusing — users might bookmark one path while docs reference another. Solution: Canonicalize to one path family (/setup/ for all admin). Add permanent redirects from /administration/* to /setup/*. Effort: M

M8. Notifications Setup Has No Preview/Test

Route: /setup/notifications Impact: Users can configure notification channels and rules but there's no "Send test notification" button to verify the channel works before going live. Solution: Add a "Test" button next to each channel that sends a sample notification. Effort: M

M9. Usage & Limits Shows Configuration But No Actual Usage

Route: /setup/usage Impact: The page shows quota configuration (limits, thresholds) but doesn't show current consumption. Users can't see "how much of my quota am I using?" Solution: Add current usage metrics next to quota limits: "Storage: 24 GB / 100 GB (24%)", "API calls today: 312 / 600". Effort: M (backend may already have this data via QuotaCompatibilityEndpoints)

M10. Trust & Signing Page Has No Clear First Step

Route: /setup/trust-signing Impact: The trust management page has many tabs (Keys, Issuers, Certificates, Watchlist, Audit, Air-Gap, Incidents, Analytics) but no "start here" guidance for a fresh install. Solution: Add a setup checklist: 1. Generate signing key → 2. Register issuer → 3. Import CA certificates. Effort: S

---

LOW

L1. Quickstart Database Connection String Is Hardcoded

Impact: The quickstart shows Host=127.1.1.1;Port=5432;Database=stellaops_platform;Username=stellaops;Password=stellaops as a command-line argument. This works for local dev but exposes credentials in shell history. Solution: Note in docs that the connection string should use environment variables in production. Add --connection $STELLAOPS_DB pattern. Effort: S

L2. Screenshot/Visual Guide Missing from Docs

Impact: All docs are text-only. No screenshots of the UI, no annotated diagrams showing where to click. Visual learners have no reference. Solution: Add a "Visual Tour" section to docs/UI_GUIDE.md with annotated screenshots of: Dashboard, Sidebar, Releases, Security Posture, Policy Studio. Effort: L

L3. Config Sample File Has Internal Service URLs

Impact: src/Web/StellaOps.Web/src/config/config.sample.json contains URLs like http://router.stella-ops.local which only work in the Docker network. An external deployer wouldn't know what to change. Solution: Add comments/documentation in config.sample.json explaining each URL and what to replace for external deployment. Effort: S

L4. Air-Gap Mode Not Discoverable from Main Navigation

Impact: Offline/air-gap is a key differentiator but the feature is buried under Operations → Offline Kit. A user evaluating air-gap support might not find it. Solution: Add "Air-Gap Mode" as a visible chip/badge in the topbar when offline mode is configured. Add a link from the Platform Setup home page. Effort: S

L5. CLI stella topology Commands Not Documented in User Docs

Impact: The CLI has topology setup, validate, status, rename, delete commands but they're not mentioned in the quickstart or UI guide. Users might not know the CLI exists. Solution: Add a CLI reference section to docs/quickstart.md or a new docs/CLI_REFERENCE.md. Effort: M

---

Priority Matrix

Effort\Severity	Critical	High	Medium	Low
S	—	H4, H5, H7, H8	M2, M3, M5, M10	L1, L3, L4
M	C3, C4	H1, H2, H6	M1, M4, M6, M7, M8, M9	L5
L	—	H3	—	L2
S (code)	C1	—	—	—
M (code)	C2	—	—	—

Recommended attack order: C1 → H5 → C4 → C3 → H1 → C2 → H8 → H4 → M5 → M3

---

Verification

• Playwright audit script: src/Web/StellaOps.Web/scripts/live-first-time-user-audit.mjs
• Audit results: src/Web/StellaOps.Web/output/playwright/first-time-user-audit.json
• Screenshots: src/Web/StellaOps.Web/output/playwright/first-time-user-audit/
• 41 pages audited, 0 page crashes, 0 API errors, 3 visible error text instances