Conventions

---
path: /exact/route/pattern
surface: customer | studio | operator | workspace
domain: <the controlled domain slug used by the matching routes.csv row>
auth: anon | signed-in | signed-in + role:<role> | signed-in + tenant:<tenant>
source: apps/oshun/web/src/app/<path>/page.tsx
status: stub | drafted | walked | stale
last_walked: 'YYYY-MM-DD by <walker/method>, against commit <sha>'
---

# <Human-readable view name>

## Purpose

One paragraph (≤ 3 sentences). What is this view for, and who uses it. Avoid
restating what's already in `V1/features.md` — link to the relevant anchor
instead.

## Entry points

How a user arrives at this view.

- Linked from `<route>` via `<link element / button label>`
- Deep link from `<email / push / SMS / share target>`
- Search result from `/search` for query `<example>`
- Direct URL (bookmarkable / shareable / role-gated / hidden)
- Shell nav (home / explore / activity / library / profile / domain switcher)

## Layout regions

The named visual regions a user can identify, top to bottom (or left-to-right on
wide breakpoints). Use the actual region names from the page component.

- **Header**: <variant — shell header / domain header / minimal>
- **Hero / above-the-fold**: <what's here>
- **Main**: <primary content panel>
- **Aside / secondary panel**: <if any>
- **Footer / sticky bottom**: <if any>

## States

Every observable visual state of the view. Produce it in local development when
the required system is available; otherwise mark it N/A with a reason or leave
it unchecked with the exact external prerequisite. Never invent reachability.

- [ ] **Loading** — skeleton or spinner matches final layout dimensions (no
      CLS); skeleton respects theme tokens; loading attribute announced to
      screen readers
- [ ] **Empty** — no data; on-brand copy; CTA points to a productive next
      action; not just a "nothing here" placeholder
- [ ] **Populated (short)** — 1–5 items; expected layout
- [ ] **Populated (long)** — 50+ items; pagination/virtualization/infinite
      scroll works; scroll position restored on back-navigation
- [ ] **Error (recoverable)** — failed query; retry button works; original query
      parameters preserved
- [ ] **Error (unrecoverable)** — 500/403; support contact link; navigation away
      still works
- [ ] **Offline** — network unreachable; SW serves cached read where sensible;
      writes are queued or disabled with explanation; offline banner visible
- [ ] **Gated** — auth/role/feature-flag denies; user sees why and how to
      unlock; no information leak
- [ ] **Standalone PWA** — view renders cleanly when launched from home-screen
      icon; URL bar absent; safe-area insets respected

If a state cannot occur for this view, write
`- [x] **<state>** — N/A because <reason>` so the omission is auditable.

## Interactions

One bullet per discrete interactive element. Drill into nested elements (e.g., a
menu's items, a modal's buttons).

Each bullet uses this micro-template:

```
- [ ] **<Element label>** (<element type: button / input / link / tab / etc.>)
  - Function: <what it does>
  - Keyboard: <key activates; tab order position>
  - Screen reader: announces "<text>"
  - Touch target: ≥ 44×44 CSS px on coarse pointers
  - Mobile (≤ 640 px): <any layout/behavior delta>
  - Disabled when: <condition> → tooltip/aria-disabled text "<text>"
  - Offline behavior: <queue / disable / no-op>
  - Telemetry: <event name fired>
```

If a sub-element exists (e.g., menu items, dialog content), nest its bullets one
level deeper.

## Data & contracts

What this view reads, writes, and subscribes to.

- **Reads**: `<BFF route or lib call>` — returns `<contract type>`
- **Writes**: `<BFF route>` — accepts `<contract type>`
- **Realtime**: `<channel/topic if any>` — `<events handled>`
- **Caching**: SSR / SWR / ISR / static / SW-cached (which cache key)
- **Auth/role check**: `<middleware.ts rule or BFF policy>`

Link to the contract in `libs/contracts/` or `libs/openapi/`.

## Cross-references

- Feature spec: [`V1/features.md#<anchor>`](../V1/features.md#anchor)
- Architecture: [`V1/ARCHITECTURE.md#<anchor>`](../V1/ARCHITECTURE.md#anchor)
- Journeys that pass through this view: `journeys/<file>.md`
- Sibling routes: `<list>`
- Component sources: `apps/oshun/web/src/<dir>/<file>.tsx`

## Open questions / known gaps

- [ ] <items the walker noted but couldn't resolve in one pass>

/**
 * E2E · Journey: WALKTHROUGH/journeys/<journey-name>.md
 * Covers: steps 1–6 (proxy boundary 307/404 → /aaa-upgrade page → AaaGate embed leak).
 * Coverage matrix: WALKTHROUGH/journeys/coverage.md
 *
 * A spec may cover one journey, part of a journey, or steps shared by several
 * journeys — list each journey it backs on its own `Journey:` line.
 */

## E2E coverage

- [`apps/oshun/web/e2e/<file>.spec.ts`](../../apps/oshun/web/e2e/<file>.spec.ts)
  — steps 1–6; drives the proxy boundary, the disclosure page, and the embed
  gate.
- **Coverage depth**: deep | partial | shallow | none — see
  [`coverage.md`](./coverage.md).
- **Uncovered**: list any step/failure-mode no spec exercises yet, with the
  reason (blocked on a missing route, requires a testnet, etc.). `_None._` when
  whole.