V1 Web PWA · Surface walkthrough

V2 — Knowledge Roadmap (Sophia-backed)

A per-surface walkthrough of the V1 Web PWA customer surface: layout, states, interactions, data, and cross-references.

walked
8sections2 minread
Markdown source
On this page

Context. surface customer · domain v2-knowledge · route /v2/roadmap · auth anon · source apps/oshun/web/src/app/v2/roadmap/page.tsx

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

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

Purpose#

Status page for V2 out-of-game surfaces: companion app, public API, wiki / glossary, roadmap widget, patch notes archive, PTB opt-in, email digest delivery. Each lane carries a state badge (done / active / queued), progress percent, owner, and Sophia RAG citations. Same V2KnowledgeSurface component used by /v2/wiki and /v2/glossary; differs by 'roadmap' surface-id.

Entry points#

  • Sub-nav "Roadmap" item from any V2 page
  • "Sophia knowledge → Roadmap" panel link on /v2
  • Direct URL / bookmark — yes, anon
  • Outbound from "what's shipping" links in V2 in-game UI (when V2 ships)

Layout regions#

page.tsx async server component: const model = await buildV2KnowledgeSurfaceModel('roadmap'); renders <V2KnowledgeSurface model={...} />. Layout matches /v2/wiki and /v2/glossary, with an additional roadmap-lanes rail.

  • Header: LWebShell chrome — customer nav + V2 sub-nav (active="roadmap")
  • Section head: kicker "Sophia RAG / release state", title "Knowledge roadmap"
  • Coverage strip: answer citations / source documents / average confidence
  • RAG answer panel: composed status answer
  • Roadmap lanes panel: rows of V2RoadmapLane with id, label, state badge, progress bar, owner, per-lane citation chips
  • Entries panel: roadmap-themed knowledge entries
  • Citations rail: per-citation cards

States#

  • Loading — server-rendered; no client suspense
  • Empty — N/A
  • Populated — roadmap lanes + entries from the model
  • Error — N/A in current local impl
  • Offline — cacheable
  • Gated — N/A, anon
  • Standalone PWA — clean

Interactions#

Top chrome#

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

Roadmap lanes#

  • State badge — one of done / active / queued; non-interactive
  • Progress bar — visualizes lane.progress (0–1); ARIA progress role
  • Per-lane citation chips — anchor to citations rail

Citation chips#

  • Citation chip — anchor to matching citation card
    • Keyboard: tab; enter activates anchor
    • Screen reader: announces label + linked title

Data & contracts#

  • Reads: buildV2KnowledgeSurfaceModel('roadmap') → V2KnowledgeSurfaceModel (includes roadmap: readonly V2RoadmapLane[])
  • Writes: none
  • Realtime: none
  • Caching: static (local corpus); SWR/ISR when swapped to live Sophia
  • Auth/role check: anon

Cross-references#

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

Open questions / known gaps#

  • Same local-Sophia swap concern as /v2/wiki
  • No filter on lane state (e.g., show only active lanes)
  • No per-lane permalink for external sharing