# 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