---
path: /studio/isis/lora-training
surface: studio
domain: isis
auth:
  signed-in + studio entitlement (AAA-gated — `lora-training` is in
  `AAA_ONLY_STUDIO_ROUTES`)
source: apps/oshun/web/src/app/studio/isis/lora-training/page.tsx
status: walked
last_walked:
  '2026-06-28 Codex automated deepening — route boundary, real-BFF LoRA
  lifecycle, loading/unauthorized/malformed states, route-map/sibling targets,
  and mobile overflow covered by
  apps/oshun/web/e2e/studio-isis-lora-training.spec.ts. Prior: 2026-05-29
  automated runtime walk (Playwright headless) — render, /v1 data (2xx),
  console/page-errors, expected content, screenshot verified.'
---

# Isis LoRA Training

## Purpose

Admin §24.5 operator console for the LoRA training queue: it reads the live run
set from `GET /v1/admin/isis/lora-training` and drives each run through its
lifecycle (rights attestation → pre-flight → training → evaluation → promotion)
via `POST …/runs/:runId/transition`, plus a create form (`POST …/runs`). The BFF
state machine is the enforcer — the panel only offers the transitions valid for
a run's current state. It is admin-scoped and fails closed (no run data without
the Isis scope).

## Entry points

- Sibling quick-action from `/studio/isis/civitai-integration`
- Studio index (`/studio`)
- Direct URL / bookmark (AAA entitlement required)

## Layout regions

`page.tsx` mounts `<ShellLayout active="studio">` (no breadcrumb panel) and
three panels: the workspace, the Route Map, and sibling quick-actions.

- **Header**: shell header
- **Workspace panel** (`data-isis-lora-training-workspace`):
  - `<h1>` (`WorkspaceHeading`) "Isis LoRA Training Workspace"
  - Summary paragraph (`data-isis-lora-training-summary`) + per-state counts
    (`data-lora-state-count`)
  - Run list (`data-lora-run-list`, each `data-lora-run-row` / active
    `data-lora-run-row-active`); empty state `data-lora-run-list-empty`; filter
    `data-lora-search`
  - Create-run form (`data-lora-create-form`, toggled by
    `data-lora-create-toggle`)
  - Run detail (`data-lora-detail`) with the action panel
    (`data-lora-action-panel`) offering only the transitions valid for the run's
    current state
- **Route Map panel** (`data-isis-lora-training-route-map`):
  `<h2>Route Map</h2>` over `STUDIO_ISIS_LORA_TRAINING_ROUTE_MAP` (5 entries)
- **Sibling quick-actions panel**: `/studio/isis/civitai-integration`, `/studio`

## States

- [x] **Loading** — `data-lora-loading`
- [x] **Unauthorized** — 401/403 admin-scope fail-closed;
      `data-lora-unauthorized` (governance message, no run data)
- [x] **Error** — non-OK or malformed response; `data-lora-error`
- [x] **Ready** — runs present; list + detail + action panel render
- [x] **Result** — after a create or transition POST,
      `data-lora-create-result`/`data-lora-action-result` with
      `data-lora-create-status` / `data-lora-action-status`

## Interactions

### Create-run form (`data-lora-create-form`)

- [x] **Create fields** (`data-lora-create-field=<field>`) — run config inputs
- [x] **Create** (`data-lora-create-submit`) —
      `POST /v1/admin/isis/lora-training/runs`

### Run action panel (`data-lora-action-panel`) — state-gated transitions

- [x] **Attest rights** (`data-lora-action-attest` →
      `data-lora-action-attest-submit`)
- [x] **Start** (`data-lora-action-start`)
- [x] **Pause** (`data-lora-action-pause`)
- [x] **Evaluate** (`data-lora-action-evaluate`)
- [x] **Complete** (`data-lora-action-complete` →
      `data-lora-action-complete-submit`)
- [x] **Promote** (`data-lora-action-promote` →
      `data-lora-action-promote-submit`)
- [x] **Abort** (`data-lora-action-abort` → `data-lora-action-abort-submit`)
- Each transition → `POST /v1/admin/isis/lora-training/runs/:runId/transition`

### Route Map

- [x] **Route-map articles** ×5

### Sibling quick-actions

- [x] **Open Isis Civitai Integration workspace** →
      `/studio/isis/civitai-integration` (target href verified; destination has
      its own route walkthrough)
- [x] **Back to Studio workspace index** → `/studio` (target href verified)

## Current E2E Evidence

`apps/oshun/web/e2e/studio-isis-lora-training.spec.ts` covers this route against
the real Next dev shell plus the real BFF. The production AAA route boundary
stays hard-blocked/AAA-redirected; the spec reaches the underlying Studio Isis
lane only through an explicit localhost-only `__oshunStudioIsisLaneE2E=1` bypass
that is enabled in Playwright env and rejected for non-local hosts.

- Boundary: direct `/studio/isis/lora-training` returns the Studio boundary
  headers for hard-block and AAA CTA cases.
- Lifecycle: seeded rows render, search/filter/empty state work, route-map
  entries and sibling targets render, then a created run moves through
  pending-rights-attestation → pre-flight → training → paused → training →
  evaluating → pending-promotion → promoted. A second run is attested to
  pre-flight and then aborted.
- Failure states: insufficient BFF scope renders `data-lora-unauthorized`;
  delayed/malformed BFF response renders loading and then `data-lora-error`.
- Mobile: 390px viewport opens the workspace/create form with no horizontal
  document overflow.

## Data & contracts

- **Reads**: `GET /v1/admin/isis/lora-training` (run set + per-state counts)
- **Writes**:
  - `POST /v1/admin/isis/lora-training/runs` (create a run)
  - `POST /v1/admin/isis/lora-training/runs/:runId/transition` (drive the
    lifecycle state machine)
- **Realtime**: none
- **Caching**: client fetch on mount, `cache: 'no-store'`,
  `buildBffAuthHeaders()`
- **Auth/role check**: admin-scoped, fail-closed (401/403); route gated on
  signed-in + studio entitlement (AAA segment)
- **Component sources**:
  - `apps/oshun/web/src/components/studio/StudioIsisLoRATrainingWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioIsisLoRATrainingRouteMap.ts`

## Cross-references

- Studio overview: [`../../studio-overview.md`](../../studio-overview.md)
- AAA gating: `libs/isis/entitlements/src/studio-boundary.ts`
- Sibling routes:
  - [`studio-isis-civitai-integration.md`](./studio-isis-civitai-integration.md)
  - [`studio-isis-model-registry.md`](./studio-isis-model-registry.md)

## Open questions / known gaps

- [ ] No breadcrumb on this route — navigation is via sibling quick-actions
- [ ] Manual AT pass still pending for live screen-reader behavior and touch
      ergonomics beyond automated axe/mobile overflow coverage