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-glossary.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 "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