# Coverage

What's covered by the admin-app walkthrough. Live status in
[`routes.csv`](./routes.csv).

## At a glance

| Bucket                                                | Count | Walkthrough status |
| ----------------------------------------------------- | ----- | ------------------ |
| Total `page.tsx` files in `apps/oshun/admin/src/app/` | 34    | —                  |
| **Drafted**                                           | 34    | 100%               |

## Group breakdown

Derived from `OSHUN_ADMIN_WORKSPACE_MODEL.group` in
`libs/oshun/navigation/src/admin-ia.ts`.

| Group         | Routes | Folder                   |
| ------------- | ------ | ------------------------ |
| governance    | 5      | `workspaces/governance/` |
| safety        | 7      | `workspaces/safety/`     |
| content       | 4      | `workspaces/content/`    |
| operations    | 5      | `workspaces/operations/` |
| isis          | 8      | `isis/`                  |
| cross-product | 2      | `cross-product/`         |
| meta          | 3      | `meta/`                  |

### Governance (5)

- `/` (`dashboard`)
- `/inbox`
- `/review`
- `/review/[reviewId]`
- `/policy`

### Safety (7)

- `/trust-safety`
- `/trust-safety/voice-abuse`
- `/lilith`
- `/egbe`
- `/rights`
- `/incidents`
- `/trust-safety/maya-anticheat`

### Content (4)

- `/editorial`
- `/research-integrity`
- `/personas`
- `/models`

### Operations (5)

- `/support`
- `/privacy`
- `/analytics`
- `/admin-tools` _(P3 2026-05-25; cross-cutting utility panels moved here from
  `/analytics`)_
- `/crashes`

### Isis (8)

- `/isis/civitai-intake`
- `/isis/comfy-nodes`
- `/isis/lora-training`
- `/isis/model-merging`
- `/isis/output-gallery`
- `/isis/runpod-endpoints`
- `/isis/voice-cloning`
- `/isis/workflow-editor`

### Cross-product (2)

- `/messaging/telegram-channels`
- `/tenant-console/living-scenes`

### Meta (3)

- `/handoff` — privileged-handoff entry point (public path)
- `/unauthorized` — auth-denial UI (public path)
- `/__test/v1-aweb-104` — Playwright visual-regression fixture

## Method

`routes.csv` was generated from `find apps/oshun/admin/src/app -name page.tsx`
and grouped by:

- **group** — for routes that map to `OSHUN_ADMIN_WORKSPACE_MODEL`, the
  `definition.group` value; for sub-routes (e.g., `/review/[reviewId]`), the
  parent workspace's group; for special routes (`/handoff`, `/unauthorized`,
  `/__test/*`), the synthetic `meta` group; Isis admin sub-routes get their own
  `isis` group; multi-product surfaces (`/messaging/*`, `/tenant-console/*`) get
  `cross-product`.

## Status legend

- `stub` — file exists with header only
- `drafted` — content from code; not verified live
- `walked` — verified against the running admin app on a known commit
- `stale` — code drifted since last walk

## What's done so far

**Scaffold + shell + sweep (session 8, 2026-05-24):**

- [x] `README.md` — overview, group breakdown, surface map
- [x] `00-conventions.md` — references parent conventions; admin-specific
      frontmatter and walking discipline
- [x] `shell/01-app-shell.md` — AdminShell, sidebar, header, command palette,
      assistant panel, density toggle, error/loading/not-found
- [x] `shell/02-routing-layouts.md` — middleware, public paths, rate limit,
      request ID, sub-route patterns
- [x] `shell/03-auth-session.md` — admin session cookie, scopes matrix,
      privileged handoff, unauthorized reasons
- [x] `shell/04-workspace-pattern.md` — canonical page shape,
      `getAdminServerSession` + `loadWorkspaceDetail` + `WorkspaceEntryPoint`
- [x] All 34 per-view files drafted
- [x] 6 admin journeys + index drafted:
  - `journeys/privileged-handoff.md` — auth entry
  - `journeys/review-cycle-admin.md` — governance flow
  - `journeys/incident-handling-admin.md` — safety flow
  - `journeys/trust-safety-voice-abuse-response.md` — safety flow
  - `journeys/persona-release-cycle.md` — content/persona flow
  - `journeys/isis-lora-training-admin.md` — Isis ops flow

## Cross-cutting findings from the admin per-view sweep

Surfaced by the parallel agent. These are issues in the admin app's underlying
code, not walkthrough quality issues.

1. **BFF id vs IA id drift — FULLY ALIGNED (P3, 2026-05-26).** Originally four
   workspaces had `bffWorkspaceId` values that did not match their IA id
   (`trust-safety` ↔ `moderation`, `incidents` ↔ `incident`, `personas` ↔
   `persona`, `models` ↔ `model`). 2026-05-25 codified the drift as the
   `OSHUN_ADMIN_BFF_ID_DRIFT` constant + the `resolveBffWorkspaceIdFromIaId` /
   `resolveAdminWorkspaceIdFromBffId` helpers, with a contract test guarding the
   canonical pairs. 2026-05-25 → 2026-05-26 worked through the four coordinated
   `apps/oshun/bff/src/admin/state.ts` rename commits (persona → personas →
   model → models → incident → incidents → moderation → trust-safety) to
   eliminate the drift at the source. The constant is now empty; the helpers +
   contract test stay so any reintroduced drift fails loud. Each rename also
   touched `OSHUN_ADMIN_WORKSPACE_BFF_BINDINGS`, `ADMIN_LINKABLE_WORKSPACE_IDS`,
   the IA model `bffWorkspaceId` field, the admin-cross-links dispatch, the
   inbox-workspace subset, and every `record.<id>` property access. Unrelated
   semantic unions that happened to share the same literal words
   (`AdminPolicyDomain`, `AdminModelLane`, `AdminCopilotMetricsSurfaceId`, etc.)
   were left alone — they are separate types that happen to share a word.

2. **11 bypass routes — RESOLVED across P2.2 + P3 (2026-05-25).** The eight
   `/isis/*` routes, both `/messaging/telegram-channels` and
   `/tenant-console/living-scenes`, and `/trust-safety/voice-abuse` previously
   skipped the canonical AdminShell pattern. P2.2 added them to
   `OSHUN_ADMIN_WORKSPACE_MODEL` (so they appear in the IA and the sidebar) and
   wrapped each route in `AdminShell` + `getAdminServerSession()`. What P2.2 did
   not add was the explicit per-workspace scope check — the canonical pattern
   uses `loadWorkspaceDetail` which calls `sessionCanEnterWorkspace` internally,
   but these 11 routes have their own data loaders (Isis binding pattern, custom
   server actions, etc.) and never invoked that check.

   This P3 pass closes the remaining gap. Each of the 11 routes now calls
   `sessionCanEnterWorkspace(session, '<workspaceId>')` immediately after the
   session check, redirecting to
   `/unauthorized?reason=forbidden-workspace&returnTo=<path>` when the session
   lacks the required `admin:*` / `admin:studio` / `admin:workspace:<id>` scope.
   The IA model carries the workspace-specific scope claims
   (`admin:workspace:isis`, `admin:workspace:messaging`,
   `admin:workspace:tenant-console`, `admin:workspace:trust-safety`), so a
   handoff that grants only one workspace can no longer reach the others.

3. **Module-level mutable loader binding — INVESTIGATED + FLAGGED (P3,
   2026-05-25).** Confirmed as an **intentional dependency-injection seam**, not
   a leaked fixture. The pattern (`let binding | null` plus `bindXxxLoader`) was
   designed to let tests inject fixtures and to give the production BFF a
   binding point once `/v1/admin/isis/*` endpoints ship. Today only
   `bindIntakeSearchCandidatesLoader` has an actual caller
   (`isis-admin-panels.test.tsx`); the other seven exported `bindXxxLoader`
   functions are dangling but harmless.
   - The intake loader docstring already documents the intent — "for now the
     loader returns an empty list and an anonymous operator id, both of which
     can be replaced via the injection hooks."
   - The `workflow-editor` route is an exception: its loader returns a curated
     default workflow class + 16 approved node types, so it renders functionally
     and does not get a placeholder banner.
   - **`comfy-nodes` migrated to BFF (P3 follow-up, 2026-05-25).** The
     `bindNodeRegistryLoader` injection seam is removed; the page now reads from
     `GET /v1/admin/isis/comfy-nodes` via `loadComfyNodes`. Store + route
     - admin loader split sets the canonical pattern for the rest. 4 BFF route
       tests cover auth, scope gating, and the seeded 10-node registry
       (including the deprecated `ControlNetLoader` row with its
       `alternativeClassType`).
   - **`lora-training` migrated to BFF (P3 follow-up, 2026-05-25).**
     `bindTrainingRunsLoader` removed; page reads from
     `GET /v1/admin/isis/lora-training` via `loadLoraTrainingRuns`. Store seeds
     two representative runs covering `training` and `pending-promotion`
     lifecycle states, each with full `rightsAttestation`, `checkpoints`, and
     `history`. 4 BFF route tests.
   - **`voice-cloning` migrated to BFF (P3 follow-up, 2026-05-25).**
     `bindVoiceCloningLoader` removed; page reads from
     `GET /v1/admin/isis/voice-cloning` via `loadVoiceCloningRecords`. Store
     seeds two clone-workflow records — `pending-signoff` (one safety signoff
     complete, awaiting rights/engineering/creator) and `released` (all four
     signoff roles complete, profile registered). Both carry consent records,
     sample manifests, naturalness scores, watermark verification, and
     abuse-risk scorecards. 4 BFF route tests.
   - **`model-merging` migrated to BFF (P3 follow-up, 2026-05-25).**
     `bindMergeContextLoader` removed; page reads from
     `GET /v1/admin/isis/model-merging` via `loadModelMergingContext`. Store
     seeds five candidate components (2 base checkpoints, 3 LoRA adapters with
     hashes and weights) plus 3 fixture sets for A/B preview. 4 BFF route tests.
   - **`output-gallery` migrated to BFF (P3 follow-up, 2026-05-25).**
     `bindGalleryAdminLoader` removed; page reads from
     `GET /v1/admin/isis/output-gallery` via `loadOutputGalleryContext`. Store
     seeds 6 output records spanning Veritas/Tara/Nyx/Nisaba/Arete domains, four
     output kinds (image / audio-narration / audio-music / mesh-3d covered
     between them), three entitlement tiers
     (contemplative/curated-creator/aaa-creator), and one taken-down row so the
     filter facets exercise real values. 4 BFF route tests.
   - **`runpod-endpoints` migrated to BFF (P3 follow-up, 2026-05-25).**
     `bindRunpodDashboardLoader` removed; page reads from
     `GET /v1/admin/isis/runpod-endpoints` via `loadRunpodDashboardContext`.
     Store seeds two endpoints (a `green` US East A100 pool and an `amber` EU
     West H100 pool with sustained latency), two tenant cost windows + budget
     envelopes that exercise the alert / kill-switch logic, a 3-job queue
     snapshot, one failover entry, and one secret rotation (`complete` state
     with the full five-event history). 4 BFF route tests.
   - **`civitai-intake` migrated to BFF (P3 follow-up, 2026-05-25).** Seventh
     and final Isis loader migration. Page reads from
     `GET /v1/admin/isis/civitai-intake` via `loadCivitaiIntakeContext`. Store
     seeds one review-queue entry currently in the `rights` stage with full
     2-event history (intake → rights), the operator id, and one searchable
     candidate so the search-results view exercises real shape. The
     `intake-loader.ts` injection seam is intentionally kept intact (its
     `bindIntakeSearchCandidatesLoader` + `loadIntakeSearchCandidates` pair is
     exercised directly by `isis-admin-panels.test.tsx` without rendering the
     page); the page just no longer reads from it. 4 BFF route tests + the 19
     existing isis-admin-panels tests both pass.

   All seven Isis loader migrations complete. The injection-seam pattern is now
   retained only where a test caller exists (`intake-loader.ts`); every admin
   Isis page reads from a typed BFF endpoint and surfaces a degraded alert when
   the BFF call fails.

4. **Happy-path `WorkspaceEntryPoint` duplication — RESOLVED (P3, 2026-05-25).**
   P1.12 collapsed the entry-point header to null / related-handoffs-only when a
   BFF-backed detail fetch succeeded (`accessible && detail.ok === true`). That
   left a remaining gap for workspaces that have no BFF detail to fetch at all —
   `composed-from-workspaces` surfaces (`dashboard`, `admin-tools`) and
   `backend-pending` surfaces (`editorial`, `research-integrity`, `messaging`,
   `tenant-console`) — where `loadWorkspaceDetail` returns
   `{ accessible: true, result: null }`. The entry-point now also collapses for
   those cases (`accessible && detail == null`). The denial card (`!accessible`)
   and the unavailable card (`detail.ok === false`) still render the full
   fallback UI as before. A new `WorkspaceEntryPoint.test.tsx` locks the five
   cases (BFF happy path, composed-from-workspaces happy path, backend-pending
   happy path, denial, unavailable).
5. **`Admin*Panel` clustering — RESOLVED via new `/admin-tools` workspace (P3,
   2026-05-25).** The seven cross-cutting utility panels (audit log explorer,
   bulk operations, bulk exports, developer portal, integrations registry,
   notification templates, broadcast communications) have been moved to a new
   `/admin-tools` workspace under the Operations group. `/analytics` now hosts
   only its actual analytics panels (`ReadinessDashboardPanel`,
   `ReleaseReadinessGoNoGoPanel`). The new workspace is registered in
   `OSHUN_ADMIN_WORKSPACE_MODEL` as `composed-from-workspaces` since each
   utility keeps its own BFF backing — `loadWorkspaceDetail` returns
   `{ accessible, result: null }` for the workspace itself and
   `WorkspaceEntryPoint` renders the related-workspace summary above the panel
   stack. Total canonical admin workspaces: 18 → 19.
6. **Triple+ overlap on voice cloning lifecycle — DOCUMENTED ownership map
   (P3.6, 2026-05-24).** Four surfaces touch cloned-voice state. Until a
   consolidation pass ships, the canonical owner per lifecycle stage is:
   - `/isis/voice-cloning` — **training-time owner**. Hosts the clone workflow
     records, training jobs, and per-clone configuration. Mutations: start /
     cancel / re-run training.
   - `/personas` — **registry owner**. Hosts the voice profile definition (one
     row per attested voice), policy pack attestation, release channel (preview
     / staging / production). Mutations: promote, demote, attest, retire.
   - `/trust-safety` — **moderation owner**. Hosts the cloned-voice review
     queue + offender history + safety-rule hits for the domain. Mutations:
     review verdicts, appeal handling.
   - `/trust-safety/voice-abuse` — **incident-and-revocation owner**. Hosts the
     abuse alert stream and revocation cascade preview / commit. Mutations:
     cascade revocation across consent ledger. In the (common) case where a
     single voice is visible across all four, the surfaces share the underlying
     `@iris/voice` data model but each writes through its own mutation path. The
     flagged consolidation risk is real but bounded: editorial in `/personas`
     should not appeal a moderation decision; trust-safety should not promote a
     voice to production. Cross-surface guard is enforced by the BFF (see
     `apps/oshun/bff/src/routes/admin-*.ts`). If a fifth surface wants to touch
     voice state, it must declare which stage it owns and route mutations
     through the appropriate BFF endpoint.
7. **Hardcoded seed data — both routes now BFF-backed (P3 follow-up,
   2026-05-25).**
   - `/messaging/telegram-channels` no longer renders hardcoded `SEED_BINDINGS`.
     The BFF endpoint `GET /v1/admin/messaging/telegram-channels` reads from
     `telegramChannelBindingsStore` (in-memory, same seed rows, single source of
     truth); the page fetches via `loadTelegramChannelBindings`. If the BFF call
     fails, a degraded "Bindings unavailable" alert surfaces the failure reason.
     **Mutating actions are now BFF-backed too (P3 follow-up, 2026-05-25):**
     - `POST /v1/admin/messaging/telegram-channels` — bind a new channel.
     - `POST /v1/admin/messaging/telegram-channels/<handle>/crisis-suppression`
       — explicit `{ enabled }` body (no implicit toggle; the server action
       reads current state, flips it, and posts the desired next value).
     - `POST /v1/admin/messaging/telegram-channels/<handle>/takedown` — removes
       the binding; requires an audited rationale.

     The admin server actions in `actions.ts` now call those endpoints with the
     admin session token and invoke
     `revalidatePath('/messaging/telegram-channels')` so the page reflects the
     new state after each mutation. The local in-memory audit log is preserved
     for now (auditLog still stamps bind / toggle / takedown events with
     operator + timestamp + payload). 11 BFF route tests cover the four
     endpoints plus the bind-conflict, missing-rationale, and unknown-handle
     paths.

   - `/tenant-console/living-scenes` now reads a non-editable,
     version-controlled policy baseline and live audit evidence from
     `GET /v1/admin/tenant-console/living-scenes/governance` via
     `loadTenantLivingScenesGovernance`. Only the durable Living Scene share
     authority supplies audit rows: the production path has no sample events,
     fake policy controls, or unimplemented revoke action. If the BFF call
     fails, a degraded "Governance unavailable" alert identifies the local Lotus
     Sangha fallback as non-live and shows zero audit evidence. The endpoint
     accepts an explicit `x-oshun-viewer-tenant-id` header, while the current
     page omits it and uses the sole `tenant_lotus` deployment baseline. Seven
     BFF route tests cover authentication, scope gating, tenant handling,
     provenance, and live-authority rows; strict loader/component tests and a
     Playwright/axe walkthrough cover the rendered operator surface.

## Maintenance

- When a new admin route lands, append a row to `routes.csv` (`stub`) and create
  the corresponding file in the right group folder
- When a workspace's `OSHUN_ADMIN_WORKSPACE_MODEL` entry changes (label, scopes,
  backend status), set the related row to `stale`
- A future enhancement: a CI check that diff-compares the CSV against
  `find apps/oshun/admin/src/app -name page.tsx` and fails on drift