# Endgate Documentation Index

## Start here

| If you want... | Read |
|---|---|
| **Wave loop** (waves, retry, energy, auto-timing target) | [`systems/gd-wave-loop.md`](systems/gd-wave-loop.md) |
| **Village building** (zones, buildings, walls, construction target) | [`systems/gd-village-building.md`](systems/gd-village-building.md) |
| **Characters** (roster, stats, skills, assignment target) | [`systems/gd-characters.md`](systems/gd-characters.md) |
| **Combat** (horde spawning, goblin templates, tick resolution) | [`systems/gd-combat.md`](systems/gd-combat.md) |
| **Map** (terrain generation, flow field, scouting) | [`systems/gd-map-and-terrain.md`](systems/gd-map-and-terrain.md) |
| **Progression** (energy, upgrades, prestige target) | [`systems/gd-progression.md`](systems/gd-progression.md) |
| **Shell and panels** (chrome, modes, keyboard, density) | [`ux/gd-shell-and-panels.md`](ux/gd-shell-and-panels.md) |
| **Tactical viewport** (Three.js renderer, camera, scenes) | [`ux/gd-tactical-viewport.md`](ux/gd-tactical-viewport.md) |
| **HUD** (top/bottom bars, world messages, mood) | [`ux/gd-hud.md`](ux/gd-hud.md) |

---

## Game systems

One doc per feature area. Each doc describes what's **shipped** (current code)
and what's **target** (the realtime village loop + wave reset direction).

| Document | Covers |
|---|---|
| [`systems/gd-wave-loop.md`](systems/gd-wave-loop.md) | Wave catalog, run phases, retry, energy economy, auto-wave target |
| [`systems/gd-village-building.md`](systems/gd-village-building.md) | Zone grid, buildings, walls, instant build, timed construction target |
| [`systems/gd-characters.md`](systems/gd-characters.md) | Roster, defender stats, movement, character sheet, zone assignment target |
| [`systems/gd-combat.md`](systems/gd-combat.md) | Goblin templates (SECS entities), spawn system, tick order, combat events, flow field |
| [`systems/gd-map-and-terrain.md`](systems/gd-map-and-terrain.md) | Seeded generation, obstacles, flow grid, spawn arcs, scouting |
| [`systems/gd-progression.md`](systems/gd-progression.md) | Energy, village upgrades, first-session guidance, prestige target |

---

## UX screens

| Document | Covers |
|---|---|
| [`ux/gd-shell-and-panels.md`](ux/gd-shell-and-panels.md) | ShellChrome, 7 panel modes, panel sizing, keyboard, situation items |
| [`ux/gd-tactical-viewport.md`](ux/gd-tactical-viewport.md) | Three.js renderer, camera tiers, scene layers, minimap, build interaction |
| [`ux/gd-hud.md`](ux/gd-hud.md) | TopHud, BottomHud, world messages, notifications, visual mood |

---

## Contracts

Authority boundary and transport docs — updated when commands or snapshots change.

| Document | Role |
|---|---|
| [`architecture.md`](architecture.md) | Authority flow, tick loop, server ownership |
| [`secs-contracts.md`](secs-contracts.md) | Content/Generated triangle, SECS boundary, command/query surface |
| [`client-authority-rules.md`](client-authority-rules.md) | What the browser may and must-not do |
| [`renderer-contract.md`](renderer-contract.md) | Snapshot shape, transport protocol, Three.js layer list |

---

## Agent and tooling

| Document | Role |
|---|---|
| [`agent-bridge.md`](agent-bridge.md) | `window.__endgateCapture` dev API |
| [`agent-playtest-protocol.md`](agent-playtest-protocol.md) | Playwright/agent test scenarios |
| [`ai-player-requirements.md`](ai-player-requirements.md) | What the AI needs to play Endgate interactively |
| [`runbook.md`](runbook.md) | Dev stack, zellij, URLs, smoke flow |
| [`performance-runbook.md`](performance-runbook.md) | Stress drills, benchmarks, bottleneck targets |

---

## History

Completed wave specs, superseded designs, and prior status tracking. Reference
only — do not use for "what to build next" without checking the system docs.

| Document | Status |
|---|---|
| [`history/realtime-village-loop.md`](history/realtime-village-loop.md) | **Draft** — detailed target design for RTL waves |
| [`history/wave-reset-persistent-village.md`](history/wave-reset-persistent-village.md) | **Draft** — macro loop, prestige, failure reset |
| [`history/horde-map-rewrite.md`](history/horde-map-rewrite.md) | **Shipped** — Phase 1 visual rewrite spec |
| [`history/horde-map-rewrite-specification.md`](history/horde-map-rewrite-specification.md) | **Shipped** — Phase 1 detailed command/layout tables |
| [`history/wave-status.md`](history/wave-status.md) | **Complete** — EG-RTS-01 through EG-RTS-08 status |
| [`history/wave-queue.md`](history/wave-queue.md) | **Complete** — shipped wave queue and EG-RTL target queue |
| [`history/aaa-gap-register.md`](history/aaa-gap-register.md) | Baseline-vs-production gap register |
| [`history/crystal-day-loop-character-progression.md`](history/crystal-day-loop-character-progression.md) | **Superseded** by wave-reset + realtime loop |
| [`history/performance-plan.md`](history/performance-plan.md) | Performance investigation notes |

---

## Baseline vs target (quick reference)

| Topic | Shipped baseline | Target (realtime-village-loop + wave-reset) |
|---|---|---|
| Start wave | Player `wave.start_next` | Server auto timer |
| On loss | Same wave retry | Wave counter → 1; village damaged |
| Build | Instant energy → structure | Blueprint + timed proximity jobs |
| Repair | Instant command | Timed repair jobs; ghosts |
| Move | Straight-line; teleport between waves | Always A* pathfind |
| Orders | Point `move_to` | Zone hold / patrol / build job |
| Build during combat | Blocked entirely | Jobs only; no free placement |
| Waves | 10 authored SECS scripts | Procedural from threat budget (long term) |
| UI | Build panel can show during combat (disabled) | Phase-locked planning vs fight |