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

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

## Purpose

Searchable fighting-game language reference: frame advantage, meaty, rollback,
hitstop, hitlag, kara cancel, OS, shimmy, frame trap, ukemi, and community
slang. Same `V2KnowledgeSurface` component as `/v2/wiki` and `/v2/roadmap`;
differs only by the `'glossary'` surface-id passed to
`buildV2KnowledgeSurfaceModel`.

## Entry points

- Sub-nav "Glossary" item from any V2 page
- "Sophia knowledge → Glossary" panel link on `/v2`
- Direct URL / bookmark — yes, anon
- Inbound link from tutorials / commentator surfaces (when V2 ships)

## Layout regions

`page.tsx` is an async server component:
`const model = await buildV2KnowledgeSurfaceModel('glossary')`; renders
`<V2KnowledgeSurface model={...} />`. Identical layout to `/v2/wiki`.

- **Header**: `LWebShell` chrome — customer nav + V2 sub-nav
  (`active="glossary"`)
- **Section head**: kicker `"Sophia RAG / terminology"`, title "Combat glossary"
- **Coverage strip**: 3 metrics (answer citations / source documents / average
  confidence)
- **RAG answer panel**: composed glossary answer with citation chips
- **Entries panel**: term entries with body, metrics, citations
- **Citations rail**: per-citation cards (label / title / source / section /
  confidence / excerpt)

## States

- [ ] **Loading** — server-rendered
- [ ] **Empty** — N/A
- [ ] **Populated** — glossary entries from
      `buildV2KnowledgeSurfaceModel('glossary')`
- [ ] **Error** — N/A in current local impl
- [ ] **Offline** — cacheable
- [ ] **Gated** — N/A, anon
- [ ] **Standalone PWA** — clean render

## Interactions

### Top chrome

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

### Citation chips

- [ ] **Citation chip** — anchor to matching citation card in the rail
  - Keyboard: tab-focusable; enter activates
  - Screen reader: announces label + linked title

### Entries

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

## Data & contracts

- **Reads**: `buildV2KnowledgeSurfaceModel('glossary')` →
  `V2KnowledgeSurfaceModel`
- **Writes**: none
- **Realtime**: none
- **Caching**: static (local corpus); SWR/ISR when swapped to real
  `@sophia/client` target
- **Auth/role check**: anon

## Cross-references

- Sibling: [`v2.md`](./v2.md), [`v2-wiki.md`](./v2-wiki.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` —
  `SURFACE_DEFINITIONS['glossary']`
- Scope: [`../../matrix/coverage.md`](../../matrix/coverage.md) "Out-of-V1
  (excluded)"

## Open questions / known gaps

- [ ] Same local-Sophia swap concern as `/v2/wiki`
- [ ] No alphabetical jump-list or quick search field within the glossary
- [ ] No bookmark / pin per term