` otherwise widens the
   track; `.grid > * { min-width: 0 }` in `globals.css` is the safety net); action rows wrap; tables and code
   panes scroll inside their card (`overflow-x-auto`), never the page. Two-column detail layouts collapse below
   `lg`. Check 375 px and 768 px.
10. **Accessible by default.** Every icon-only button has `aria-label`; every image `alt`; focus is visible
    (`focus-visible:ring-[3px]`); dialogs trap focus (Radix); colour is never the only signal (the `Badge` tone
    carries a word too); contrast >= 4.5:1 on both themes (`--brand-cyan-text` exists because cyan on white does
    not pass). Motion respects `prefers-reduced-motion`.

## Understanding behaviour before redesigning

Do not guess where people struggle - the platform records it, without prompts:

- **Funnel and time to value** - `GET /api/v1/admin/analytics/activation?days=` (console *Analytics*, card
  *Activation funnel*): the share of new workspaces that confirmed the e-mail, routed, got an answer, reported
  success, returned; the median hours to each. A step with a steep drop is a screen to redesign.
- **Stuck before the first request** - the same payload's `stuck` list: who signed up more than a day ago and
  never routed. Read their console page (`/platform/admin/workspaces/{id}`): did they create a key, open the
  playground, hit a 4xx?
- **Where errors happen** - `GET /api/v1/admin/activity?failed=true` and the events page; a 400 on
  `POST /api/v1/route` right after signup is a form or copy problem, not a user problem.
- **What people click on the public site** - GA4 events through `lib/analytics.ts` `track()` (`sign_up`, `login`,
  `select_content`), consent-gated (`ConsentBanner`), never on `/platform/dashboard/*` or `/platform/admin/*`
  (`isTrackedPath`). First-touch attribution (`lib/attribution.ts`) lands on the signup and in the funnel's
  `by_source`.
- **Support tickets and sales inquiries** (`/platform/admin/support`, `/leads`) are the qualitative signal;
  quote them in the PR when they motivate a change.
- **Watch someone.** For anything on the first-value path (signup -> key -> playground -> activity) sit with one
  person who has never seen it, say nothing, note every hesitation. Five people find most of what matters.

Write the finding as *observation -> hypothesis -> change -> metric that will move*, and put the metric in the
CHANGELOG entry ("activation funnel: first_route share").

## Building a page: the recipe

1. Data first: find or add the endpoint (`osr-platform`), then the TypeScript type in `lib/api/types.ts` with a
   one-line doc comment naming the route.
2. `useApi("/api/v1/...")` (workspace) or `useAdminApi` (console); design the four states before the
   happy path.
3. Compose from primitives: `PageHeader` -> `StatCard` row -> `Card` grid (`lg:grid-cols-[minmax(0,1.2fr)_minmax(0,1fr)]`)
   -> `DataTable` / `RankedBars` / `TimeBars`. Rows link to the thing they describe (`Link` to
   `/platform/admin/workspaces/{id}`, `/models/{id}`).
4. Register: nav (`site.ts` / `SECTIONS` / `ADMIN_NAV`) + `NavIcon` name, the `docs/PLATFORM.md` row, the
   CHANGELOG bullet.
5. Prove it: unit test for any pure helper (`tests/*.test.ts`), e2e coverage (below), then the visual pass in
   both themes at 375 / 768 / 1280.

## Validation - what "working" means here

```bash
cd platform/web
npm run check                 # eslint + tsc + vitest (tests/*.test.ts, .tsx)
npm run build                 # the standalone build the e2e harness serves
$env:OSR_E2E_DATABASE_URL="postgresql://osr:osr@127.0.0.1:55432/osr"   # docker start osr-test-pg
npx playwright test e2e/customer-journey.spec.ts      # sign up -> dashboard -> playground -> keys -> activity
npx playwright test e2e/accessibility.spec.ts         # axe WCAG 2.1 A/AA on the first-value pages (serious+ fails)
npx playwright test e2e/responsive.spec.ts            # no sideways scroll at 375 / 768 on every page
npx playwright test e2e/dashboard-pages.spec.ts e2e/console-pages.spec.ts   # every page renders real data, no crash
npx playwright test e2e/page-quality.spec.ts          # failed requests, console errors, leaked "undefined"/NaN, one h1,
                                                      # dead internal links, unknown slugs -> not-found page (not a skeleton)
```

- `e2e/global-setup.ts` spawns a throw-away API on 8111 and the standalone build on 3111 (`OSR_E2E_WEB` /
  `OSR_E2E_API` point at servers you already run - clear them afterwards, they linger in the shell).
- Helpers in `e2e/helpers.ts`: `signUp(tag)` (unique e-mail per run - the DB is shared across runs),
  `adoptSession(page, token)`, `operatorToken()`, `setPlan`, `field(page, /^Label/)`, `expectNoCrash(page)`.
  Locator lessons: `Field` labels with hints -> `getByRole("textbox", { name: /^Code/ })`; `getByRole("alert")`
  also matches Next's route announcer; Card titles are `h3`; a hidden streamed copy of a form exists in
  `div#S:0` -> use `:visible`.
- Add a new page to `PUBLIC` / `DASHBOARD` / `ADMIN` in `accessibility.spec.ts` and `responsive.spec.ts`, and
  to the page-walk in `dashboard-pages.spec.ts` / `console-pages.spec.ts`. A new journey gets its own spec
  named after what the person does ("open a ticket, get its reference and e-mail, operator answers...").
- Theme and contrast audit: run against `next dev` on 3001 (`OSR_API_URL=http://localhost:8080`), sign in by
  fetch (`POST /api/v1/signup` -> `localStorage osr.platform.apiKey`), parse colours through a 1x1 canvas
  (`getImageData`; Tailwind 4 emits `lab()` / `oklab()`). Screenshots go to `%TEMP%`, never under `platform/web`.
- Against the dev stack (`docker compose up -d --build`, containers run the image, no watch):
  `python -X utf8 platform/api/scripts/smoke.py --api http://localhost:3000 --web http://localhost:3000
  --operator admin:admin-dev-only` walks every page and API surface.
- Live: `platform/api/scripts/live_use_cases.py --key ` proves routing on production; open the deployed
  page in both themes on a phone before closing the task.

## Anti-patterns seen in this codebase (do not bring them back)

- A `1fr` grid track that grew to a `
` / install command and made the page scroll sideways on phones.
- `tailwind-merge` dropping `text-display-*` as a colour class; `shrink-0` action rows; fixed `w-64` inputs.
- A cache-only `useApi` page that showed stale numbers after a mutation without a `reload()`.
- A gated feature that disappeared on the free plan instead of explaining the gate.
- Provider "healthy" badges that were five days old; health must show *when* it was checked.
- Clicks that "worked" in the integrated browser but not on the deployed site - verify on the real origin.
- `notFound()` thrown by a detail page under a route-group `loading.tsx` left visitors on the skeleton with a 200:
  every route group that streams needs its own `not-found.tsx` (the public one is `app/(marketing)/not-found.tsx`).
- A checklist step that was "done" for the wrong reason (`user is None` on a key session read as verified): a step
  must be computed from the event it names, for every kind of principal.
- "100% succeeded" over zero requests; raw proxy errors (`platform API unavailable: fetch failed`) shown to a person.