---
path: /v2
surface: customer
domain: v2-shell
auth: anon
source: apps/oshun/web/src/app/v2/page.tsx
status: walked
last_walked:
  '2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data
  (2xx), console/page-errors, expected content, screenshot verified; live
  screen-reader, touch, offline, and telemetry-delivery checks pending a manual
  AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md'
v1_scope: out-of-v1
---

# V2 — Fighting-game shell tile

> Out of V1 scope. Documented here because the route exists in
> `apps/oshun/web/src/app/v2/page.tsx` and ships with V1 builds. The route is
> covered by the broader Oshun PWA shell but is not in the V1 feature map.

## Purpose

The V2 fighting-game web surface running as a **tile inside the shared Oshun
shell**, not as a standalone Next.js app. Renders the V2 stack ledger:
shell-core clients, auth-feature counts, persistence contracts, developer-portal
doc, retired standalone stack. Read-only — V2 product surfaces live under
`/v2/wiki`, `/v2/glossary`, `/v2/roadmap`.

## Entry points

- Direct URL / bookmark — yes, anon
- Sub-nav "V2" item rendered by `LSubNav` on any V2 page
- Inbound link from `/explore` sub-nav (no card today)
- Linked from `WALKTHROUGH/matrix/coverage.md` "Out-of-V1 (excluded)" section

## Layout regions

`page.tsx` builds `V2ShellTileModel` from `buildV2ShellTileModel()` and mounts
`V2ShellSurface`. Surface composes `LWebShell` with a top chrome
(`LCustomerNav active="explore"` + `LSubNav active="v2"` with five tabs:
Featured/Collections/V2/Wiki/Roadmap).

- **Header**: shell chrome — customer nav + V2 sub-nav
- **Back link**: `<- Explore` link at top
- **Section head**: kicker "V2" + title "Fighting game operations, inside the
  shell." + right chip "Shell-native"
- **`V2ShellTile`**: the canonical capability table (route, title, eyebrow,
  summary; serialized `data-testid="v2-shell-tile"`)
- **`v2-shell-grid`**: 4 panels
  - **Client surface** — `model.clients[]` (`@oshun/shell-core`,
    `@oshun/auth-client`, `@oshun/developer-portal`, `@oshun/persistence`)
  - **Shell map** — `model.shellEntryPoints[]` (primary visibility from
    `listConsumerShellEntryPoints`) as links to canonical PWA routes
  - **Persistence** — first 6 of `model.persistenceContracts[]` (V1 object +
    enum contracts grouped by domain)
  - **Developer portal** — `model.developerDoc` (slug `v2/shell-surface`,
    section `integrations`, version)
  - **Sophia knowledge** — three links to `/v2/wiki`, `/v2/glossary`,
    `/v2/roadmap` (annotated `@sophia/client`)
- **`v2-shell-stack-note`**: retired standalone stack callout (Standalone
  Next.js, Sanity CMS, Contentful CMS) + `route:/v2` code chip

## States

- [ ] **Loading** — server-rendered shell; static body, no client hydration
      gates
- [ ] **Empty** — N/A (model is deterministic; always populated)
- [ ] **Populated** — every panel renders rows from `V2ShellTileModel`;
      `data-testid="v2-shell-surface"` present
- [ ] **Error (recoverable)** — N/A; no fetch
- [ ] **Offline** — fully cacheable; SW should serve from cache
- [ ] **Gated** — N/A; anon-readable per `PUBLIC_PATHS` in `proxy.ts`
- [ ] **Standalone PWA** — renders cleanly without URL bar

## Interactions

### Top chrome

- [ ] **Customer nav** (`LCustomerNav`) — `active="explore"`; primary shell nav
- [ ] **V2 sub-nav** (`LSubNav`) — 5 items
  - [ ] **Featured** → `/explore`
  - [ ] **Collections** → `/explore`
  - [ ] **V2** (current) → `/v2`
  - [ ] **Wiki** → `/v2/wiki`
  - [ ] **Roadmap** → `/v2/roadmap`

### Back link

- [ ] **Explore** (Link) — back to `/explore`

### Shell map links

- [ ] **Shell entry-point links** — N links rendered from
      `model.shellEntryPoints`; each links to its canonical PWA route
      (`buildConsumerShellEntryPointHref(entry.id, 'web')`)

### Developer portal panel

- [ ] **Library surface** (Link) — `/library`

### Sophia knowledge panel

- [ ] **Wiki link** → `/v2/wiki`
- [ ] **Glossary link** → `/v2/glossary`
- [ ] **Roadmap link** → `/v2/roadmap`

## Data & contracts

- **Reads**: `buildV2ShellTileModel()` (synchronous, in-process) →
  `V2ShellTileModel`
- **Writes**: none
- **Realtime**: none
- **Caching**: static; suitable for SSG/ISR
- **Auth/role check**: none — anon-readable

## Cross-references

- Sibling: [`v2-wiki.md`](./v2-wiki.md), [`v2-glossary.md`](./v2-glossary.md),
  [`v2-roadmap.md`](./v2-roadmap.md)
- Component source: `apps/oshun/web/src/components/v2/V2ShellSurface.tsx`,
  `apps/oshun/web/src/components/v2/V2ShellTile.tsx`
- Model source: `apps/oshun/web/src/v2/shell-tile.ts`
- Scope: V2 is out of V1; see
  [`../../matrix/coverage.md`](../../matrix/coverage.md) "Out-of-V1 (excluded)"
  section

## Open questions / known gaps

- [ ] No explicit V2-vs-V1 surface boundary documented in the user-facing UI;
      sub-nav implies V2 is a peer of Explore/Collections
- [ ] No outbound link from V2 surface back to the V1 customer hub other than
      shell-entry-point links
- [ ] Walkthrough is drafted from code-reading only — surface is forward-looking
      and may evolve before V2 launch