Sync docs with current implementation

Author: rgilks

README.md

@@ -120,7 +120,7 @@ For the comprehensive ruleset detailing movement edge cases, damage tables, and
 - [x] **Runtime Payload Validation**: Strict server-side WebSocket payload validation before dispatch.
 - [x] **Orbital Bases**: Carrying and emplacing strategic stations during play.
 - [ ] **Client-Side Test Coverage**: Browser-facing orchestration, UI, and input flows still need dedicated tests.
-- [ ] **Asteroid Map Visuals**: The in-game tactical map should match [docs/map.png](/Users/robertgilks/Source/delta-v/docs/map.png) and visibly render asteroid fields.
+- [ ] **Asteroid Map Visuals**: The in-game tactical map should match [docs/map.png](./docs/map.png) and visibly render asteroid fields.
 - [ ] **Spectator Mode**: Allowing third-party connections to watch ongoing battles.
 
 ---

docs/ARCHITECTURE.md

@@ -10,7 +10,7 @@ Delta-V employs a full-stack TypeScript architecture built around a **shared pur
 - **Language**: TypeScript (strict mode) across the entire stack.
 - **Frontend**: HTML5 Canvas 2D API for rendering (`client/renderer.ts`), raw DOM/Events for UI and Input. No heavy frameworks (React/Vue/etc.) are used, ensuring maximum performance for the game loop.
 - **Backend**: Cloudflare Workers for HTTP routing and Cloudflare Durable Objects for authoritative game state and WebSocket management.
-- **Build & Tools**: `esbuild` for lightening-fast client bundling, `wrangler` for local testing and deployment, and `vitest` for unit testing.
+- **Build & Tools**: `esbuild` for lightning-fast client bundling, `wrangler` for local testing and deployment, and `vitest` for unit testing.
 
 ---
 

docs/SECURITY.md

@@ -9,7 +9,7 @@ Delta-V now has a materially stronger authoritative-server boundary than the ori
 - WebSocket actions are still resolved server-side against the authoritative game engine.
 - Hidden-identity state is filtered per player before broadcast, so the fugitive flag itself is not sent to the opponent.
 - Room creation is now authoritative: `/create` initializes the room, locks the scenario up front, and rejects room-code collisions.
-- The room creator receives a reserved player token for seat 0, and the copied invite link carries a guest-seat token for seat 1.
+- The room creator receives a reserved player token for seat 0, and the copied invite link carries a guest invite token for seat 1.
 - Once the guest joins, that invite token is rotated into a private reconnect token for that player.
 - Reconnects require the stored player token, which prevents the old "next socket steals the disconnected seat" failure mode.
 - Client-to-server WebSocket messages are runtime-validated before any engine handler executes, and malformed payloads are rejected instead of being trusted structurally.

docs/SIMULATION_TESTING.md

@@ -1,17 +1,20 @@
 # Delta-V Simulation Testing Strategy
 
-To ensure game balance, test edge cases, and validate the stability of the Durable Objects backend, we can implement two distinct types of simulation testing: **Headless Engine Simulation (AI vs AI)** and **Network Integration Simulation (PvP Bot Stress Testing)**.
+Delta-V now has one established simulation layer and one still-planned layer:
 
-Since the core `game-engine.ts` is purely functional and deterministic, creating high-speed simulations is extremely feasible.
+- **Headless Engine Simulation (AI vs AI)** is implemented and runs in CI.
+- **Network Integration Simulation (PvP Bot Stress Testing)** is still future work.
+
+Since the core `game-engine.ts` is purely functional and deterministic apart from injected RNG, high-speed simulation is practical.
 
 ---
 
 ## 1. Headless Engine Simulation (AI vs AI)
 
-**Goal:** Run thousands of games in seconds to test scenario balance, AI effectiveness, and find crash-inducing edge cases deep in the game tree. (Implemented in `scripts/simulate-ai.ts`).
+**Goal:** Run large batches of AI-vs-AI games quickly to test scenario balance, AI effectiveness, and find crash-inducing edge cases deep in the game tree. This is implemented in `scripts/simulate-ai.ts`.
 
 **Approach:**
-Create a new Node script (e.g., `scripts/simulate-ai.ts`) that runs outside the browser and the Cloudflare Worker, executing purely in Node.js.
+The current runner executes entirely in Node.js, outside the browser and Cloudflare Worker runtime.
 
 1. **Setup:** Initialize `GameState` using `createGame(SCENARIOS[name], map, ...)`.
 2. **Game Loop:** Put the engine in a `while (state.phase !== 'gameOver')` loop.
@@ -22,17 +25,22 @@ Create a new Node script (e.g., `scripts/simulate-ai.ts`) that runs outside the
 4. **Data Collection:** Track metrics like win rates (Player 0 vs Player 1), average turns to win, fuel consumed, and most common causes of death (combat vs crashes).
 
 **Implementation Details:**
-- Because the `game-engine.ts` has no DOM or Canvas dependencies, this can run extraordinarily fast.
+- Because the `game-engine.ts` has no DOM or Canvas dependencies, this runs very quickly in practice.
 - You can run Monte Carlo simulations (e.g., 10,000 runs of the 'Escape' scenario) to definitively prove if the scenario favors the escaping player or the blockading player.
 - **Randomness:** The combat engine relies on `Math.random()`. Passing a seeded random number generator (RNG) into `processCombat` and `processAstrogation` allows for completely reproducible replays when a simulation encounters a crash or an infinite loop.
 
+**Current usage:**
+- `npm run simulate` runs 100 headless games of the default scenario.
+- `npm run simulate all 100 -- --ci` is the current CI stress pass across all scenarios.
+- `--ci` fails the process on engine crashes and prints balance warnings without making them fatal.
+
 ---
 
 ## 2. Network Integration Simulation (PvP Stress Testing)
 
 **Goal:** Validate the Cloudflare Durable Object lifecycle, WebSocket handling, reconnection logic, and server scaling.
 
-**Approach:**
+**Approach (planned):**
 Create a headless WebSocket bot client using a library like `ws` in Node.js (e.g., `scripts/load-test.ts`).
 
 1. **Lobby Creation:** The script makes an HTTP POST request to `/create` to get a 5-letter game code.
@@ -48,5 +56,5 @@ Create a headless WebSocket bot client using a library like `ws` in Node.js (e.g
 ## Summary of Progress
 
 1. **RNG Extraction**: Completed. Engine functions accept optional RNG for deterministic simulations.
-2. **AI Runner**: Implemented. `npm run simulate` executes headless matches.
+2. **AI Runner**: Implemented. `npm run simulate` executes headless matches, and CI runs the multi-scenario `--ci` pass.
 3. **Load Tester**: Planned for future infrastructure stress testing.

docs/SPEC.md

@@ -48,7 +48,7 @@ static/
 
 **Worker (lobby-worker):**
 - `GET /` — Serves the SPA (index.html + bundled JS/CSS)
-- `POST /create` — Generates a 5-character invite code plus creator/guest tokens, initializes the Durable Object room, and locks the chosen scenario
+- `POST /create` — Generates a 5-character invite code plus a creator reconnect token and a guest invite token, initializes the Durable Object room, and locks the chosen scenario
 - `GET /ws/:code` — WebSocket upgrade, proxied to the Durable Object
 
 **Durable Object (game-do):**
@@ -61,7 +61,7 @@ static/
 
 ### Invite / Join Flow (No Lobby, No Login)
 
-1. Player 1 clicks "Create Game" → `POST /create` → receives 5-char code plus creator and guest tokens
+1. Player 1 clicks "Create Game" → `POST /create` → receives a 5-char code plus a creator reconnect token and a guest invite token
 2. UI shows the code prominently + a shareable invite link (`https://delta-v.example.com/?code=K7M2X&playerToken=...`)
 3. Player 1 can copy link or share via native Share API
 4. Player 2 receives the invite link or an equivalent tokenized join URL
@@ -90,25 +90,24 @@ When a player is planning movement, subtle dot markers or a faint radial guide m
 The map represents the inner Solar System along the ecliptic plane:
 
 **Celestial Bodies (with gravity hexes):**
-- **Sol** (Sun) — center of map, large body, multiple gravity hexes, any contact = destruction
-- **Mercury** — small, 2 bases, gravity hexes
-- **Venus** — medium, bases on all 6 sides, gravity hexes
-- **Terra** (Earth) — medium, 2 bases, gravity hexes
-  - **Luna** — small satellite, weak gravity (hollow arrows), 1 base
-- **Mars** — medium, 2 bases, gravity hexes
-  - Has two tiny moons (no gameplay effect in basic scenarios)
-- **Jupiter** — large, off-map or map edge, gravity hexes
-  - **Io** — satellite, weak gravity, 1 base
-  - **Callisto** — satellite, weak gravity, 1 base
-  - **Ganymede** — satellite, no base in basic scenarios
-- **Ceres** — asteroid, 1 base
-- **Asteroid Belt** — scattered asteroid hexes between Mars and Jupiter
+- **Sol** (Sun) — center of map, radius-2 body with two full-gravity rings; any contact = destruction
+- **Mercury** — single-hex body with one full-gravity ring and 2 base hexes
+- **Venus** — radius-1 body with one full-gravity ring and bases on all 6 sides
+- **Terra** (Earth) — radius-1 body with one full-gravity ring and bases on all 6 sides
+  - **Luna** — single-hex moon with one weak-gravity ring and bases on all 6 sides
+- **Mars** — single-hex body with one full-gravity ring and bases on all 6 sides
+- **Jupiter** — large northern body with two full-gravity rings
+  - **Io** — single-hex moon with one weak-gravity ring and 1 base
+  - **Callisto** — single-hex moon with one weak-gravity ring and 1 base
+  - **Ganymede** — single-hex moon with one weak-gravity ring and no base
+- **Ceres** — single-hex asteroid body with 1 base and no gravity
+- **Asteroid Belt** — scattered asteroid hexes between the inner planets and Jupiter
 
 **Gravity types:**
 - **Full gravity**: mandatory 1-hex deflection toward the body for any object passing through
-- **Weak gravity** (Luna, Io): player may choose to use or ignore when passing through a single weak gravity hex. Two consecutive weak gravity hexes = full gravity effect on the second.
+- **Weak gravity** (Luna, Io, Callisto, Ganymede): player may choose to use or ignore when passing through a single weak gravity hex. Two consecutive weak gravity hexes = full gravity effect on the second.
 
-**The map data is defined as a static JSON structure** listing every hex with its terrain type (empty, gravity, asteroid, planet surface, base).
+**The map data lives in a static TypeScript module** that programmatically builds body surfaces, gravity rings, base hexes, asteroid terrain, and scenario definitions.
 
 ### Vector Movement
 
@@ -790,14 +789,15 @@ interface ScenarioPlayer {
 - [x] Server hardening for competitive play (tokenized room access, authenticated reconnect tokens, scenario locking at room creation, and runtime WebSocket payload validation)
 - [x] Runtime WebSocket payload validation
 - [x] Orbital bases (carrying, emplacing, torpedo launching)
+- [x] PWA support (installable shell with offline-capable single-player)
 - [ ] Browser-side orchestration and UI test coverage
+- [ ] Asteroid map visuals to match `docs/map.png`
 - [ ] Advanced features: looting, surrender, rescue, and richer logistics
 - [ ] Improved animations (particle effects for thrust, gravity lensing)
 - [ ] Turn history replay
 - [ ] Spectator mode
 - [ ] Game state persistence (resume interrupted games across sessions)
 - [ ] Performance optimization for mobile
-- [ ] PWA support (installable, offline-capable menu)
 
 ## Open Questions