# apps/docs — Living Design Documentation

Package: `@void-nav/docs`
Port: `http://localhost:5173/docs`

This is the **design documentation hub** and interactive prototype playground. It contains the full GDD as 16 browsable pages, 14 interactive demos validating individual game subsystems, and a complete game-slice prototype implementing the full MVP loop in-browser with localStorage.

## Structure

```
src/
  App.tsx                    Route definitions (16 doc pages + 14 demo routes + 1 prototype)
  main.tsx                   Entry point
  components/                Shared UI: NotFound, Sidebar, TopBar
  data/
    nav.ts                   Sidebar navigation structure and page titles
    fakeBackend.ts           Mock data for demos
  layouts/
    DocsLayout.tsx           Sidebar + content layout wrapper
  lib/
    threeHelpers.ts          Shared Three.js utility functions
  pages/docs/                16 design doc page components:
    OverviewPage.tsx         Vision, pillars, core loop, HUD architecture, onboarding
    ArchitecturePage.tsx     System architecture, error handling, persistence, audio
    TechStackPage.tsx        Technology decisions
    BackendPage.tsx          56+ database tables, movement model, ER diagram
    AgentsPage.tsx           Scheduled agent system (3 scheduling strategies)
    GameplayPage.tsx         Core loop, security, NPC pirates, combat, missions, travel, events, balancer
    ShipsPage.tsx            Ship classes, fitting, acquisition, AI crew
    EconomyPage.tsx          Trade routes, info diffusion, refining, manufacturing, NPC pricing, faucets/sinks
    SocialPage.tsx           XP & skills, chat, bounty, kill feed, corporations
    ShipAIPage.tsx           Zora companion AI with soul depth and module gating
    RoadmapPage.tsx          16 phases (0-15), 2 eras, 6 integration gates
    RisksPage.tsx            Open risks and questions
    TodoPage.tsx             Living implementation status tracker (68 items across 8 phases)
    DemoGalleryPage.tsx      Links to all demos
    GapAnalysisPage.tsx      Cross-reference: specs vs demos vs readiness
    VerticalSliceEvaluationPage.tsx  Alignment matrix, phase readiness
    DesignDocPage.tsx        Original GDD reference
  prototypes/
    game-slice/              Full MVP loop prototype (localStorage, not SpacetimeDB)
    existing-demos/          14 standalone interactive demo components
    r3f/                     Reusable R3F 3D scenes (combat, galaxy, HUD, movement, navigation, starmap, warp)
    standalone-huds/         GameHudPrototype, PrototypeFrame
  styles/
    tailwind.css             Tailwind v4 entry point
public/
  docs/                      Markdown files: vertical-slice-evaluation.md, gap-analysis.md
  assets/                    Design doc (.docx), 3 concept drawings (.png)
```

## Key Design Decisions

- Docs are **React components**, not markdown files — this allows interactive demos inline with documentation
- The `game-slice/` prototype is a self-contained playable game that validates the full loop before backend migration
- All 14 demos in `existing-demos/` use the R3F scenes in `r3f/`