---
path: /v2/wiki
surface: customer
domain: v2-knowledge
auth: anon
source: apps/oshun/web/src/app/v2/wiki/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 — Frame-data Wiki (Sophia-backed)

> Out of V1 scope. Documented for completeness; route exists under
> `apps/oshun/web/src/app/v2/wiki/page.tsx`.

## Purpose

Player-facing reference for V2 frame data, ruleset mechanics, fighter guides,
stage walkthroughs, tutorial videos, PDF cheat sheets, and CPU AI behavior. Each
answer is grounded by Sophia RAG citations (`@sophia/client`) with confidence
scores and quoted excerpts.

## Entry points

- Sub-nav "Wiki" item from `/v2`, `/v2/glossary`, `/v2/roadmap`
- "Sophia knowledge → Wiki" panel link on `/v2`
- Direct URL / bookmark — yes, anon
- Outbound from in-game companion deep links (when V2 ships)

## Layout regions

`page.tsx` is an async server component:
`const model = await buildV2KnowledgeSurfaceModel('wiki')`; renders
`<V2KnowledgeSurface model={...} />`. The same surface component serves
`/v2/wiki`, `/v2/glossary`, `/v2/roadmap` — the only difference is the
surface-id passed to the model builder.

- **Header**: `LWebShell` chrome with `LCustomerNav active="explore"` +
  `LSubNav active="wiki"` items (Featured / V2 / Wiki / Glossary / Roadmap)
- **Hero / section head**: kicker `"Sophia RAG / frame data"`, title "Frame-data
  wiki", summary paragraph
- **Coverage strip**: 3 metrics — answer citations / source documents / average
  confidence
- **RAG answer panel**: the composed Sophia response body with inline citation
  chips (each chip is a Link to the citation in the citations rail)
- **Entries panel**: list of `V2KnowledgeEntry` rows
  - title, tag chip, body paragraph
  - per-entry metrics rail (label + value)
  - per-entry citation chips
- **Citations rail (right column or bottom on mobile)**: each
  `V2KnowledgeCitationView` rendered with label, title, source path, section,
  confidence score, quoted excerpt

## States

- [ ] **Loading** — server-rendered; no client suspense boundary
- [ ] **Empty** — N/A (deterministic local RAG corpus; always populated)
- [ ] **Populated** — entries + citations from
      `createLocalSophiaClient(...).answer({ query })`
- [ ] **Error** — N/A in current implementation (local client deterministic);
      live BFF swap is a future concern
- [ ] **Offline** — server-rendered output cacheable; SW serves from cache
- [ ] **Gated** — N/A; anon-readable
- [ ] **Standalone PWA** — sub-nav + content render cleanly without URL bar

## Interactions

### Top chrome

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

### Citation chips

- [ ] **Citation chip** (Link/anchor) — clicking jumps to the matching citation
      card in the citations rail; chip text is the citation label, e.g. `[1]`
  - Keyboard: tab-focusable; enter activates anchor
  - Screen reader: announces label + linked citation title

### Entries

- [ ] **Per-entry citation chips** — same anchor behavior as above

## Data & contracts

- **Reads**: `buildV2KnowledgeSurfaceModel('wiki')` → `V2KnowledgeSurfaceModel`
  (composed in-process via `createLocalSophiaClient`)
- **Writes**: none
- **Realtime**: none
- **Caching**: static at the moment (deterministic local corpus); when swapped
  to a real `@sophia/client` BFF target, becomes SWR/ISR
- **Auth/role check**: none — anon-readable

## Cross-references

- Sibling: [`v2.md`](./v2.md), [`v2-glossary.md`](./v2-glossary.md),
  [`v2-roadmap.md`](./v2-roadmap.md)
- Component source: `apps/oshun/web/src/components/v2/V2KnowledgeSurface.tsx`
- Model source: `apps/oshun/web/src/v2/sophia-rag.ts` —
  `buildV2KnowledgeSurfaceModel`, `SURFACE_DEFINITIONS['wiki']`
- Scope: [`../../matrix/coverage.md`](../../matrix/coverage.md) "Out-of-V1
  (excluded)"

## Open questions / known gaps

- [ ] The local Sophia client is deterministic. Swap to the real
      `@sophia/client` RAG target (base URL `http://localhost:3737` in dev per
      `V2_SOPHIA_BASE_URL`) before V2 launch
- [ ] Citation chips currently anchor to the rail by id — no SEO-friendly URL to
      a specific citation
- [ ] No copy/share/pin per-citation affordance