# Admin journeys

End-to-end multi-workspace flows for the admin app. Per-view files verify each
workspace individually; journeys catch the bugs that hide between workspaces —
broken handoffs, scope-gating gaps, audit trails that miss a step.

Same shape as the V1 PWA's `WALKTHROUGH/journeys/`: `# Journey:` heading, no
frontmatter, then Personas → Pre-conditions → Steps → Post-conditions → Failure
modes → E2E coverage when automation exists → Per-view files touched →
Cross-references → Open questions.

## When to walk an admin journey

- **Before an admin app release** — walk the relevant journeys for workspaces
  whose code changed.
- **After a structural change** — middleware refactor, session-cookie rotation,
  scope taxonomy change, BFF endpoint move.
- **When an operator reports a confusing flow** — find the matching journey; the
  failure mode is probably already there.

## Journey bucket map

### Auth and entry (1)

| Journey                                            | What it walks                                                                                                                                                         |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`privileged-handoff.md`](./privileged-handoff.md) | Customer (or anon) → `/handoff` → out-of-band token mint → admin session cookie set → land at `returnTo`. Also covers expired-session re-handoff and rate-limit edge. |

### Governance flows (1)

| Journey                                            | What it walks                                                                                                                                                                   |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`review-cycle-admin.md`](./review-cycle-admin.md) | `/review` queue → `/review/[reviewId]` detail → stage graph + copilot draft → Approve/Request changes/Reject → sealed decision in audit. High-risk approval + delegation paths. |

### Safety flows (2)

| Journey                                                                          | What it walks                                                                                                                                                                         |
| -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`incident-handling-admin.md`](./incident-handling-admin.md)                     | Auto-INC fires → `/inbox` → `/incidents` detail → acknowledge / assign / runbook / customer comms → resolve → postmortem → audit. Handoffs to `/policy`, `/trust-safety`, `/support`. |
| [`trust-safety-voice-abuse-response.md`](./trust-safety-voice-abuse-response.md) | Voice abuse alert → `/trust-safety` → `/trust-safety/voice-abuse` → revocation cascade preview → commit → consent ledger updates → take-downs → optional S1 incident escalation.      |

### Content / persona flows (1)

| Journey                                                  | What it walks                                                                                                                                                                                                                                |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`persona-release-cycle.md`](./persona-release-cycle.md) | `/personas` add → voice consent verified at `/rights` → policy pack attested at `/policy` → submit to `/review` → approval → promote `preview` → `staging` → `production`. Cross-links to V1 PWA Tara surface and the LoRA training journey. |

### Isis ops flows (1)

| Journey                                                        | What it walks                                                                                                                                                                                                                                    |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`isis-lora-training-admin.md`](./isis-lora-training-admin.md) | `/isis/civitai-intake` → rights check → `/isis/comfy-nodes` + `/isis/workflow-editor` → `/isis/runpod-endpoints` → `/isis/lora-training` → `/isis/output-gallery` → optional `/isis/model-merging` → submit to `/review` → promote in `/models`. |

## Cross-cutting findings worth surfacing

Recorded as the journeys were drafted. Several depend on per-view sweep results
— refer to [`../matrix/coverage.md`](../matrix/coverage.md) for the consolidated
cross-cutting findings.

1. **The handoff back-channel is opaque.** The privileged-handoff journey
   describes the visible UI but the token-mint step is out-of-band — flagged in
   open questions for every admin journey that depends on a fresh session.
2. **Audit-log writes are the universal stamp.** Every admin journey ends with
   verifying entries in `apps/oshun/bff/src/routes/admin-audit-log.ts`. Event
   taxonomies (`incident.*`, `review.*`, `trust-safety.*`, `persona.*`,
   `isis.*`) are documented per journey.
3. **The dashboard is composed from workspace summaries.** Operators landing at
   `/` see `WorkspaceSummaryCard`s for every workspace they can access. The
   journey-relevant view is each individual workspace, but the dashboard's
   `loadWorkspaceOverview` is the first read the operator makes.
4. **Cross-workspace handoffs use `listOshunAdminWorkspaceRelationships()`** —
   see `WorkspaceEntryPoint`'s "Handoffs from here" block. Journeys reference
   these relationships explicitly.
5. **Lilith workspace (`backendStatus: 'backend-pending'`) blocks any journey
   that needs Lilith-room observability** — flagged in
   `persona-release-cycle.md` open questions.
6. **The V1 PWA has parallel operator surfaces.** `/operator/admin` in the V1
   PWA mirrors `/inbox` here. `/operator/admin/isis/provenance` is the
   provenance inspector that this admin app's Isis flows produce bundles for.
   Cross-links go in both directions.
7. **Rate limit is per-replica in-memory.** A multi-replica deploy will limit
   per-replica, not globally. Flagged in `privileged-handoff.md` failure modes
   and `shell/02-routing-layouts.md` open questions.

## Adding a new admin journey

1. Pick a flow that traverses ≥ 2 admin workspaces (or ≥ 1 admin workspace + the
   V1 PWA) and has clear pre- and post-conditions.
2. Confirm every workspace it touches has a per-view file; if not, write those
   first.
3. Copy [`privileged-handoff.md`](./privileged-handoff.md) as a starting shape.
4. Ground every step in real component / route / BFF endpoint names from the
   per-view files. Don't invent.
5. Use `ls` to confirm every per-view link target exists before committing.
6. Add the new entry to the bucket map above with a one-line summary.