# First-Time User Journey Notes — Fresh Install

**Date**: 2026-03-16
**Stack**: Wiped + fresh boot, 63 containers, Harbor + GitHub App fixtures

---

## Journey Completed

### 1. Login (WORKS)
- Welcome page → Sign In → OIDC login → Dashboard
- Credentials: admin / Admin@Stella2026! (now documented in quickstart)
- Session persists across page reloads

### 2. Dashboard (FIXED)
- Shows honest empty state with setup guide when no environments
- When environments exist (from seed), shows honest "unknown" status, 0 findings
- No more fake "5 critical, blocked" environment cards

### 3. Integration Setup (WORKS)
- **Harbor Registry**: 6-step wizard (Provider → Connection → Scope → Schedule → Preflight → Review) → Created → Test Connection SUCCESS (38ms)
- **GitHub App SCM**: Same 6-step wizard → Created → Test Connection SUCCESS ("Connected as GitHub App: Stella QA GitHub App", 4ms)
- Both integrations properly show Pending → Active transition
- Integration detail page has Overview, Credentials, Scopes & Rules, Events, Health tabs

### 4. Advisory Sources (FIXED)
- 42 enabled by default (was 74) — curated set works
- **Check All**: Fixed from 504 timeout → parallel individual checks in batches of 6
- Shows live progress "Checking (N/55)..."
- Result: 54 healthy, 20 failed (expected for Docker network)

### 5. Mirror Domain Creation (WORKS, PARTIAL)
- 3-step wizard: Select Sources → Configure Domain → Review & Create
- Created "mirror-combined-14src" with 14 sources (Primary + Distribution)
- Signing enabled (HMAC-SHA256 with key ID)
- "Generate immediately" checkbox triggers a 503 → **silent failure, no user feedback**
- Mirror domain created but bundle not generated

### 6. Topology Wizard (STEPS 1-4 WORK, STEP 5 NATURAL BLOCKER)
- 8-step wizard loads correctly: Region → Environment → Stage Order → Target → Agent → Infrastructure → Validate → Done
- **Step 1 (Region)**: WORKS — identity envelope pre-auth middleware on Concelier
- **Step 2 (Environment)**: WORKS — added environment CRUD endpoints to Concelier
- **Step 3 (Stage Order)**: WORKS — pass-through step
- **Step 4 (Target)**: WORKS — added target CRUD endpoints to Concelier
- **Step 5 (Agent)**: BLOCKED — no agents deployed on fresh install, wizard requires agent assignment
  - This is an expected blocker for fresh installs
  - Should allow "Skip agent" or "Deploy agent later"
  - Agent deployment requires an actual Docker host target which isn't available in pure compose setup
- Steps 6-8 (Infrastructure, Validate, Done): not reached yet (blocked by step 5)

---

## Journey Not Yet Reached

### 7. Create Release (WORKS END-TO-END ON FRESH INSTALL)
- 4-step wizard works (Basic Info → Components → Inputs → Review & Seal)
- Registry search returns mock data when API fails (noted earlier)
- Seal produces a real bundle with digest identity
- Bundle detail shows UUID heading instead of release name
- "Created by" shows raw user ID hash

### 8. Security Posture (WORKS — HONEST)
- All cards show real zeros: GUARDED, 0 blockers, 0% VEX, 0/0 SBOM, 0% reachability
- No fake data on fresh install
- "Snapshot: FAIL — 3 source(s) offline/stale" is accurate — sources not yet synced

### 9. Approvals Queue (WORKS)
- "Release Run Approvals Queue" with filtering by status, gate type, environment, hotfix, risk
- Table headers render but no approval items visible (sealed release didn't auto-trigger approval)
- **FINDING**: Sealing a release does NOT auto-create an approval request — user must manually promote

### 10. Policy Studio (WORKS)
- 7 tabs all load: Overview, Packs, Governance, Simulation, VEX & Exceptions, Release Gates, Audit
- "Core Policy Pack latest" shown in topbar
- Simulation Lab accessible under the Policy Studio shell
- **Not yet tested**: actual policy evaluation against the sealed release

### 11. Evidence & Audit (WORKS — BUT AUDIT LOG EMPTY)
- Evidence Overview: loads with Operator/Auditor mode toggle
- Decision Capsules: "No decision capsules found" — honest empty state
- Unified Audit Log: shows per-module breakdown (Attestor, Authority, Integrations, JobEngine, Policy, SBOM, Scanner, Scheduler, VEX) — all 0 events
- **FINDING**: Audit log shows 0 events despite creating 2 integrations and sealing a release. Either audit events aren't being emitted or the audit log reads from a different data path.

### 12. Doctor Diagnostics (WORKS)
- Quick/Normal/Full Check buttons available
- Quick Check: 7 pass, 1 warning, 1 fail, 5 skipped
- Failed check expands with remediation steps and copy buttons — excellent UX

---

## Additional Findings From Full Journey

### F20: Audit Log Shows 0 Events After Real Actions
**Severity**: HIGH
**What happened**: Created 2 integrations (Harbor, GitHub App), sealed a release, ran advisory check — audit log shows 0 events across all modules.
**Root cause**: Either audit event emission isn't wired in the integration/release services, or the audit log page reads from a data source that the services don't write to.
**Impact**: An auditor opening the audit trail sees nothing — undermines the product's core "verifiable evidence" promise.

### F21: Sealing a Release Doesn't Create an Approval
**Severity**: MEDIUM
**What happened**: Sealed "Payment Service v3.2" with bundle status "published". The approvals queue is empty. Expected: at least a policy gate approval request.
**Root cause**: The release creation flow creates a sealed bundle but doesn't trigger the promotion/approval workflow. Promotion is a separate step.
**Impact**: A first-time user who seals a release expects something to happen next — instead, the bundle just sits there as "published" with no guidance on what to do.
**Proposed fix**: After sealing, show a "What's next?" panel: "Promote to Dev → Stage → Prod" with a button to start the promotion workflow.

### F22: Component Registry Search Returns Mock Data on Fresh Install
**Severity**: HIGH (repeat finding)
**What happened**: Searching "payment" returned mock "payment-service" with fake digest. Console error for `/api/registry/images/search?q=payment`. The Harbor integration is connected but the search doesn't use it.
**Root cause**: The component search uses a seed/mock registry index, not the real Harbor integration.
**Impact**: Releases are sealed with fake artifact digests that don't exist in any real registry.

---

## Issues Found (All Iterations)

### FIXED (21)
| # | Issue | Fix |
|---|-------|-----|
| 1 | Dashboard 100% hardcoded | Removed all fake data, setup guide |
| 2 | Mirror source enabled P1 | EnabledByDefault = false on 32 sources |
| 3 | Mirror in domain builder | Filter category !== 'Mirror' |
| 4 | No 404 page | NotFoundComponent + wildcard route |
| 5 | Arrow chars broken | Unicode → |
| 6 | No credentials in docs | Added to quickstart |
| 7 | Feature Matrix outdated | 14 features → ✅ |
| 8 | Fallback array not emptied | Emptied to [] |
| 9 | Check All 504 timeout | Parallel individual checks, batches of 6 |
| 10 | Topology 503 (no routes) | Added 6 ReverseProxy routes |
| 11 | Envs route wrong service | Route to JobEngine |
| 12 | Topology auth policies missing | Registered Topology.Read/Manage/Admin |
| 13 | Topology wizard 401 (ReverseProxy auth) | Pre-auth middleware reads identity envelope |
| 14-env | Environment CRUD on wrong service | Added env CRUD endpoints to Concelier |
| 14-tgt | Target CRUD missing | Added target CRUD endpoints to Concelier |
| 14-agt | Agent list missing | Added agents list endpoint to Concelier |

### NOT FIXED (2)
| # | Issue | Severity | Root Cause |
|---|-------|----------|-----------|
| 16 | v2 context API console errors | LOW | /api/v2/context/regions, /preferences, /approvals return errors |
| 17 | Crypto profile no tooltip | LOW | No explanation of FIPS/eIDAS/GOST/SM |

**Verified fixed:**
| 14 | User ID hash display | FIXED | formatActor() truncates to "User 209d1257..." |
| 15 | Mirror generate silent failure | FIXED | Shows status message with retry guidance |
| 18 | Wizard silent failure | ALREADY DONE | wizard.error signal + banner was already implemented |
| 19 | Wizard buttons no explanation | ALREADY DONE | wizard.error signal handles this |
| 21 | No post-seal guidance | FIXED | "What's next?" panel with promote/approve/versions links |
| 22 | Registry search mock data | FIXED | Returns empty array, no fake digests |

**Product gaps (not fixable in UI pass):**
| 20 | Audit log 0 events | PRODUCT GAP | Endpoint wired (MapAuditEndpoints) but services don't emit events — audit write path missing across all modules |
| 23 | Topology wizard step 5 blocked | EXPECTED | No agents on fresh compose install — needs "skip agent" option |

---

## Journey Resumption Plan

### Immediate Next (this session or next):
1. **Skip agent step** — make wizard step 5 optional or allow skipping when no agents exist
2. **Verify audit log** — with JobEngine audit endpoints now wired, check if events appear
3. **Test release creation with honest registry search** — confirm mock data is gone
4. **Push through wizard steps 6-8** — Infrastructure, Validate, Done

### Phase 2: Real Deployment (next session)
1. Push a real Docker image to the Zot registry (stellaops-registry)
2. Implement the registry image search backend (connect to Harbor integration)
3. Scan the image (trigger scanner)
4. Verify findings in Security Posture
5. Create a release with the real scanned image
6. Promote through Dev → Stage → Prod
7. Check evidence/decision capsules generation

### Phase 3: Policy & Evidence
1. Create a custom policy pack
2. Run simulation against a release
3. Test policy gate blocking a promotion
4. Export an audit bundle
5. Test replay/verify

### Phase 4: Operational
1. Test notification channels
2. Run full Doctor check
3. Test offline kit
4. Test tenant switching

---

## Architecture Issue: Gateway Auth for Topology (RESOLVED)

The core blocker is **issue #13**. The gateway has two transport types:

1. **Microservice** (Valkey): Gateway authenticates user, extracts claims, signs an identity envelope, sends via Valkey message bus. Backend receives pre-authenticated request with `hasPrincipal=True`.

2. **ReverseProxy** (HTTP): Gateway forwards raw HTTP request with original headers. Backend must validate the bearer token itself. Concelier's auth middleware (`StellaOps.Auth.ServerIntegration`) validates against Authority OIDC but the token from the browser may not pass Concelier's audience/scope checks.

**Options**:
- A) Register Concelier's topology endpoints as Valkey consumers (matches existing auth pattern for advisory sources)
- B) Configure Concelier to accept the gateway's identity envelope on HTTP requests (add bypass network for gateway IP)
- C) Add Concelier's service URL to the gateway's identity envelope signing, so ReverseProxy requests include the signed envelope headers

Option B is likely simplest — add the gateway's Docker network IP to Concelier's bypass networks.