Initial commit: GDD, implementation plan, reviews, diagrams, assets

IRON_REQUIEM_GDD.md

@@ -0,0 +1,246 @@
+# IRON REQUIEM: GAME DESIGN DOCUMENT
+
+> "The engine screams, the tracks grind, and the horizon is a wall of white silence. We are not retreating from the Soviets. We are retreating from a ghost of a future that should not exist."
+> — *Hauptmann Erich Voss*
+
+---
+
+## 1. EXECUTIVE SUMMARY
+
+**Iron Requiem** is a grim, oppressive 2D top-down pixel-art \"tank bullet hell.\" Players pilot a lone Panzer IV through a frozen, alternate-history 1944 Russia. The gameplay focuses on the claustrophobic experience of tank warfare, where the vehicle is not just a tool, but the player's entire world.
+
+**Engine & Rendering:** Framework: Phaser 3 (JavaScript, 2D Canvas only). NOT Babylon.js, NOT Three.js, NOT any 3D engine.
+
+
+The game blends high-stakes resource management (fuel, heat, ammo) with the precise movement and dodging of the bullet-hell genre. The psychological tension scales from the suffocating interior of a "buttoned-up" tank to the terrifying vulnerability of "unbuttoning" to see the enemy.
+
+**Core Hook:** The "Tank-as-Character" experience. The player manages a complex machine—fighting inertia, overheating engines, and crew panic—while navigating dense, choreographed patterns of Cold War-era Chinese weaponry.
+
+---
+
+## 2. STORY TREATMENT
+
+### 2.1 Premise
+Hauptmann Erich Voss and the remnants of the 6th Panzer Division were retreating through the frozen wastes of northern Russia in late 1944. Under the influence of a sudden, catastrophic temporal fracture, the division was displaced across geography and time. They now find themselves cut off and hunted in a landscape that no longer matches any known map. Their enemy is not the Red Army, but a displaced, alternate-reality People's Liberation Army from the Cold War era. Voss is fighting a desperate retreat against enemies who possess technology that contradicts the laws of his time.
+
+
+### 2.2 3-Act Structure
+*   **Act I: The White Silence.** Voss awakens to a shattered command structure. The first encounters are skirmishes with infantry and light armor. The horror is atmospheric—ghostly radio transmissions and the realization that the maps no longer match the terrain.
+*   **Act II: The Iron Corridor.** The retreat leads through abandoned Soviet industrial hubs. The enemies evolve into Type 59 and Type 62 tanks. The scale of the invasion becomes clear; the landscape is littered with the wreckage of both German and Soviet forces, all crushed by the same anachronistic invader.
+*   **Act III: The Ruins of the Old World.** The final push toward a captured European city. The atmosphere shifts from frozen waste to urban nightmare. A final confrontation occurs with the high command of the invading force, revealing the nature of the temporal fracture.
+
+### 2.3 Bleak Endings
+1.  **The Eternal Retreat:** Voss survives the combat but runs out of fuel in the tundra. The game ends with a slow fade to white as the crew freezes in silence.
+2.  **The Last Transmission:** Voss manages to send a final, distorted signal back to a dying Germany, only to realize the response he receives is from a world that has already forgotten him.
+3.  **The Iron Grave:** A pyrrhic victory. Voss destroys the enemy commander but is immobilized. He chooses to overload the engine, taking the enemy and himself in a final, blinding explosion.
+4.  **The Silent Witness:** Voss survives and reaches the city, only to find it empty—a ghost city where the invaders have already moved on to the next continent.
+
+---
+
+## 3. CORE MECHANICS
+
+### 3.1 Tank-as-Character (The Machine)
+Unlike standard bullet-hell ships, the Panzer IV has significant mass.
+*   **Hull/Turret Decoupling:** The hull moves independently of the turret. The player must manage the momentum of the 25-ton chassis while rotating the turret to face threats.
+*   **Inertia & Momentum:** Acceleration is gradual; braking takes time. The tank "drifts" slightly on ice and snow.
+*   **Limited Visibility:** The player's view is constrained by the tank's physical structure and the periscope mask.
+*   **Historical Specs:** Panzer IV Ausf H, 25 tonnes combat loaded, 7.5 cm KwK 40 L/48 (long-barreled high-velocity anti-tank gun — NOT a short gun), Maybach HL 120 TRM 300 PS engine, crew of 5, ~87 rounds capacity. Real turret traverse: 26°/sec (electric) or 1.9°/sec (manual hand-crank).
+
+### 3.2 Bullet Hell Patterns
+Combat is a dance of survival against overwhelming firepower.
+*   **Infantry Walls:** Densely packed waves of infantry that fire coordinated bursts of small arms and RPGs.
+*   **Artillery Rings:** Large circular markers appear on the ground; after 2 seconds, a radial explosion occurs, forcing the player to move immediately.
+*   **Tank Destroyer Beams:** High-velocity, linear projectiles from focused enemy armor that require precise "pixel-perfect" dodging.
+
+### 3.3 Resource Management
+The tank is a ticking clock of depletion.
+*   **Fuel:** Constantly consumed. Low fuel reduces acceleration and turret rotation speed.
+*   **Ammo Types:**
+    *   **APCBC (Pzgr 39):** High penetration for enemy tanks. Standard anti-tank round. 6.8 kg, 750 m/s, 87 rounds max typical load.
+    *   **APCR (Pzgr 40):** Tungsten-cored, rare. Higher penetration (930 m/s) but extremely limited supply — 5-8 rounds per run.
+    *   **HE (Sprgr 34):** Splash damage for infantry clusters. 5.74 kg, 550 m/s.
+    *   **HEAT (Gr.Patr. 38 HL):** Shaped charge, useful when AP is scarce or at extreme range. 450 m/s.
+*   **Secondary Weapons:** Nahverteidigungswaffe (close-defense smoke launcher, limited charges) for breaking line-of-sight. Bow MG-34 (infinite ammo, low damage, forward arc only).
+*   **Scavenging:** Players must exit the tank (high risk) or use crew members to recover fuel and shells from wreckage during brief lulls.
+
+### 3.4 The Heat & Freeze-Thaw Cycle
+*   **Engine Temperature:** High speeds and prolonged combat increase heat. Overheating causes speed penalties and increases the tank's thermal signature, making it easier for enemies to track.
+*   **Freeze-Thaw:** In extreme cold, the engine can stall. The player must balance heat generation with the risk of thermal detection.
+
+### 3.5 Crew Morale — Buff System
+The crew is not a liability — they are your greatest asset, and morale is a resource to cultivate.
+
+*   **Baseline (0-100 scale):** Fresh crew starts at 50. There are NO penalties at any morale level. Low morale (<30) adds atmospheric effects (vignette, muffled audio, tense crew barks) but never steals control.
+*   **High Morale Buffs (70+):** Faster reload speed, crew warning shouts ("Enemy on your left!"), subtle reticle assist. These are rewards for keeping the crew alive and effective, not crutches.
+*   **Stress Factors:** Taking hull damage (-5), crew injury (-15), long isolation without radio contact.
+*   **Recovery:** +2 points/second when no damage taken. Iron Ledger entries during downtime provide a morale boost. Zone survival grants +20 one-time bonus.
+*   **Quantified:** Scale 0-100. Buffs at >70. Atmospheric effects at <30. Never punitive. No "panic over-rotation" RNG.
+
+### 3.6 Fog of War & Radio
+*   **Ghost Transmissions:** The radio picks up fragments of historical broadcasts and distorted screams from the alternate timeline.
+*   **Interception:** Players can tune the radio to intercept enemy commands, providing early warning of incoming bullet patterns.
+
+---
+
+## 4. SHOWCASE MECHANICS
+
+### 4.1 The Unbuttoning (Hatch Mechanic) — Graduated Risk
+
+The player toggles the tank's hatch between two states. This is the most frequent physical interaction with the tank — a contextual decision, not a binary gamble.
+
+*   **Buttoned Up:** Hatch closed. Safe from snipers and shrapnel. Vision restricted to the periscope mask (180° forward arc, ~200px range). Muffled, claustrophobic audio.
+*   **Unbuttoned:** Hatch open. Commander (Voss) exposed. Vision expands (270° arc, ~350px range). Earlier enemy detection, terrain hazard visibility. Open-world ambient audio.
+*   **Suppression (hit while unbuttoned):** Hatch forced closed, morale penalty (-20), commander cooldown (10 seconds before unbuttoning again). NOT instant death.
+*   **Sniper Death:** Death occurs ONLY from a direct Line-of-Sight Sniper shot — distinct laser sight telegraph, 2-second charge-up, crew bark ("Sniper! Get down!"). Skilled players can react and button up in time.
+*   **Visual:** Animated pixel art hatch opening/closing, tiny commander head sprite when unbuttoned. Animated open/close cycles with key poses.
+*   **Audio:** Ambient soundscape shifts — exterior wind/engine roar when unbuttoned; muffled interior drone when sealed. Sniper detection audio cue.
+
+
+### 4.2 Side-View Cutscenes
+Narrative is delivered via diegetic side-view profiles of the Panzer IV.
+*   **Visuals:** Pixel art side-view with character portraits.
+*   **Function:** Used between zones and after boss fights to show crew interactions, Voss's exhaustion, and the gradual decay of the tank's exterior.
+
+### 4.3 The Last Transmission
+A recurring mechanic where the player attempts to tune a radio to a specific frequency. Success reveals fragments of the plot; failure attracts enemy signal-trackers.
+
+### 4.4 The Iron Ledger
+A log of the crew's experiences. Writing in the ledger during downtime stabilizes morale and unlocks deeper character backstories.
+
+### 4.5 Parasite Run
+The ability to "leech" fuel or ammo from a disabled enemy tank, requiring the player to remain stationary and vulnerable for several seconds.
+
+---
+
+## 5. ENEMY ROSTER
+
+*   **Type 59 (Heavy Opponent):** Main battle tanks. They heavily outclass the Panzer IV in armor and gun power. Victory requires ambush and flanking.
+*   **Type 62 (Fast Flankers):** Light, agile tanks that attempt to get behind the Panzer IV to hit the thinner rear armor.
+
+*   **Artillery Emplacements:** Static enemies that create the "Artillery Ring" patterns.
+*   **Helicopter Gunships:** Aerial threats that introduce verticality to the bullet hell, raining down rockets in sweeping arcs.
+*   **Named Commanders:** Bosses with unique dialogue in Mandarin and specialized bullet patterns that reflect their personality (e.g., "The Architect" uses geometric, oppressive grids).
+
+---
+
+## 6. PROGRESSION & WORLD
+
+### 6.1 Zones
+1.  **The Frozen Tundra:** White-out conditions, deep snow slowing movement, sparse cover.
+2.  **Abandoned Soviet Industrial:** Rust-streaked metal, narrow corridors, combat in factories and warehouses.
+3.  **Captured European City Ruins:** Gothic architecture interspersed with futuristic Chinese fortifications.
+
+### 6.2 Upgrades
+*   **Armor Plating:** Increases hull HP and reduces morale loss from hits.
+*   **Engine Tuning:** Reduces overheat rate and increases top speed.
+*   **Optics:** Improves the periscope mask visibility range.
+*   **Crew Training:** Permanent buffs to reload speed and panic resistance.
+
+---
+
+## 7. ART & SOUND DIRECTION
+
+### 7.1 Pixel Art
+*   **Aesthetic:** Gritty, weathered, and oppressive. Avoid "clean" pixel art.
+*   **Palette:** 10-color bleak palette (Winter Whites, Steel Blues, Deep Greys, Dark German Grey).
+*   **Accents:** High-contrast Orange for muzzle flashes and Red/Gold for Chinese markings.
+*   **Visual Cues:** Animated hatch opening, screen-shake on shell impact, and a "dirty" lens effect for the periscope.
+
+### 7.2 Sound Design
+*   **Atmosphere:** A constant, low-frequency engine drone.
+*   **Audio Telegraphs:** Distinct PLA bugles and whistles signal the start of bullet patterns 1.5s in advance.
+*   **Voice:** German crew barks (subtitled) for urgent status updates; distorted Mandarin chatter over the radio.
+*   **Music:** A blend of dark ambient industrial and mourning orchestral pieces.
+
+---
+
+## 8. TECHNICAL SPECIFICATION (PHASER 3)
+
+> **ENGINE LOCK:** Phaser 3 (JavaScript, 2D Canvas). NOT Babylon.js, NOT Three.js, NOT any 3D engine. This is a 2D pixel-art game — no 3D rendering pipeline, no WebGPU, no WebGL unless needed as a CANVAS fallback for performance.
+
+*   **Resolution:** 640x360 (Integer scale to 1280x720 / 1920x1080).
+*   **Rendering:** CANVAS mode default for crisp pixel edges. Fallback to WEBGL with `roundPixels: true` and nearest-neighbor filtering if CANVAS performance degrades with mask + bullet patterns.
+*   **Physics:** Linear acceleration model (`accel = (input × power) - (velocity × friction)`) for the "25-ton" feel; `Phaser.Math.Angle.RotateTo` for turret rotation cap (15°/sec).
+*   **Hull/Turret Architecture:** Hull = `Arcade.Sprite` with physics body. Turret = `Arcade.Sprite` positioned at hull center each frame, body disabled (rotation only). Hull collision = AABB (acceptable for top-down bullet hell).
+*   **UI:** Diegetic HUD. Gauges for fuel and heat are analog needle sprites; ammo is tracked via shell sprites.
+*   **Vulnerability:** The `CommanderHatch` hit-box is only active when the tank is \"Unbuttoned.\"
+*   **Save System:** IndexedDB for ghost crew data, run stats, and settings (3 save slots). Client-side only — no server storage. Assets hosted on server, all player data lives on their machine.
+
+---
+
+## 9. EDGE CASES & DESIGN RESOLUTIONS
+
+*These are definitive game design decisions. No mechanic is left to "the developer will figure it out."*
+
+### 9.1 Zero Fuel
+The tank enters **Last Stand mode**: hull immobile, turret rotation at 50% speed (hand-cranked, ~1.9°/sec historically accurate). Crew barks reflect desperation. Player can still fight but cannot dodge — a dramatic moment, not a softlock. Emergency fuel reserve consumable (1 per run). "Prime the engine" desperation action: spend hull HP for one last-ditch burst of movement.
+
+### 9.2 Crew Death
+- **Driver dead:** No hull movement.
+- **Gunner dead:** No turret rotation.
+- **Loader dead:** No firing.
+- **Radio operator dead:** No radio / early warning.
+- **Commander death while unbuttoned:** Instant game over (unchanged).
+- **Commander death while buttoned:** (Rare — requires armor penetration + precise hit) Bleak cutscene of remaining crew attempting retreat.
+- **Role reassignment:** Surviving crew can fill empty roles at 50% effectiveness (e.g., commander loads = 50% reload speed).
+
+### 9.3 Zero Ammo (All Types)
+Tank becomes a **battering ram**: can still move and ram enemy infantry for low damage. Crew can fire personal weapons (pistols) from the hatch — minimal damage, infinite ammo, but requires unbuttoning. Warnings: flash at <10 rounds total, <5 rounds, and at 0 with "FIND AMMO" prompt.
+
+### 9.4 Scavenging
+**Post-combat only.** After clearing a wave, debris fields become interactive zones. 3-second hold-E action with resource display. Use crew member keys — crew portrait greys out for 10 seconds while scavenging; if hit during that window, crew member is injured/killed. Guaranteed minimum yield per zone. Exit is always reachable with minimum starting fuel — softlock impossible by design.
+
+### 9.5 Overlapping Bullet Hell Patterns
+**Pattern governor:** Max N active patterns by difficulty — Zone 1: max 2, Zone 2: max 3, Zone 3: max 4. Offset timing by ≥0.5s between overlapping patterns. Every pattern has a provable safe zone — tank hitbox must fit within the gap. Procedural validation script tests all pattern combinations for dodgeability.
+
+### 9.6 Periscope Mask Fairness
+Enemies outside the periscope view **do not fire** — or fire with dramatically reduced accuracy (slow, telegraphed suppressing fire). Crew barks indicate off-screen threat direction ("Contact! 4 o'clock!"). Projectile telegraphs (Artillery Ring markers, beam charge-up glows) always visible even when firing enemy is off-screen. Radar ping: periodic sweep shows enemy positions as dots on minimap.
+
+### 9.7 Save System Failure Modes
+- **Browser clears data:** Export/import save as JSON file. Warning on first launch.
+- **Private/incognito mode:** Detect and warn at main menu.
+- **Storage quota exceeded:** Catch error, alert player, offer to delete old saves.
+- **Save corruption:** Write to temp key, atomic rename, checksum validation on load.
+- **Multi-tab:** Session-scoped lock token — only active tab saves.
+- **Auto-save:** At every checkpoint (zone transition, boss defeated) + manual save option.
+- **3 save slots** for different runs/endings. Save format: IndexedDB, schema versioned, including zone, resources, crew state, story flags, settings, playtime stats.
+
+### 9.8 Tutorial (Zone 1)
+Zone 1 is the tutorial zone. Systems introduced progressively:
+1. Start buttoned — hull movement only.
+2. Add turret rotation + 2-3 static infantry targets.
+3. Introduce unbuttoning (and risk) against a single enemy at range.
+4. Ammo types introduced as they're acquired.
+5. Heat, morale, radio introduced with on-screen prompts as they become relevant.
+No system dumps. The player learns each mechanic before the next is added.
+
+### 9.9 Difficulty Modes
+- **Endurance Mode (Easy):** Slower heat buildup, more forgiving morale, wider periscope view, 1 extra crew "life," reduced enemy projectile density.
+- **Requiem Mode (Normal):** As described in this GDD.
+- **Iron Mode (Hard):** Graduated unbuttoning death (as below), no auto-save, permadeath (one save slot, deleted on death).
+
+### 9.10 Quality of Life
+- **Pause menu:** Resume, Save, Load, Settings, Quit to Menu. Auto-pause on browser tab blur.
+- **Controller support:** Twin-stick (left = move hull, right = aim turret). Keyboard: WASD + arrow keys or mouse aim.
+- **Key rebinding:** Full rebinding for all actions.
+- **Sound settings:** Master, Music, SFX, Radio, Voice volume sliders.
+- **Accessibility:** Color blind options, screen shake toggle, flashing light warnings.
+- **Death screen:** Reload checkpoint or restart zone. Death recap. Clear distinction: runs are checkpoint-based (not permadeath) in Endurance/Requiem modes.
+
+---
+
+## APPENDIX A: DESIGN PHILOSOPHY — WHAT CHANGED AFTER REVIEW
+
+### A.1 Morale: Buff System, Not Debuff
+**Before:** Morale penalties made the tank feel unresponsive (slower reload, command delay, panic over-rotation).
+**After:** Morale is a buff system. Baseline = normal (no penalties). High morale = faster reload, crew warning shouts ("Enemy on your left!"), reticle assist. Morale starts low and builds through survival, scavenging, and Iron Ledger entries. Recovery rate: +2 points/second with no damage taken. Maximum 100. Buffs activate at >70. Low morale (<30) adds visual/audio effects (vignette, muffled sound) but never steals control.
+**Removed:** "Turret over-rotation" panic errors — frustrating RNG has no place in a precision game.
+
+### A.2 Unbuttoning: Graduated Risk, Not Binary Death
+**Before:** Any projectile hitting the CommanderHatch = Game Over. Russian roulette.
+**After:** Hit while unbuttoned = **Suppression**: hatch forced closed, morale penalty (-20), commander cooldown (10 seconds before unbuttoning again). Death occurs ONLY from a direct Line-of-Sight Sniper shot (distinct laser sight telegraph, 2-second charge-up). Skilled players can react and button up. Audio cue: "Sniper! Get down!" crew bark.
+
+### A.3 Historical Corrections
+- **Gun:** "Short 75mm KwK 40" corrected to **7.5 cm KwK 40 L/48 (long barrel)**. The KwK 40 was ALWAYS a long-barreled high-velocity anti-tank gun. The short-barreled 75mm was the KwK 37 L/24 (infantry support howitzer, phased out by 1943).
+- **Ammo types:** "Smoke" and "Canister" rounds did not exist for the 75mm KwK 40. These are replaced by: **APCBC (Pzgr 39)**, **APCR (Pzgr 40, rare/limited)**, **HE (Sprgr 34)**, and **HEAT (Gr.Patr. 38 HL)**. Smoke is now delivered via the real-world Nahverteidigungswaffe (close-defense launcher) with limited charges. Canister is replaced by the bow MG-34 (infinite but low damage, forward arc only).
+- **Division history:** The 6th Panzer Division never operated in Arctic Russia — they were in Hungary in 1944 under Army Group South. This is now explained in-universe as part of the alternate-history "Temporal Fracture" event that displaced both the Chinese forces AND Voss's unit.

PHASER_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,53 @@
+# Iron Requiem — Phaser.io Implementation Plan
+
+## 1. Technical Architecture
+- **Framework:** Phaser 3 (JS/TS)
+- **Internal Resolution:** 640x360 (Pixel-perfect integer scaling to 1280x720 / 1920x1080)
+- **Rendering:** `Phaser.CANVAS` or `Phaser.WEBGL` (with `pixelArt: true` and `roundPixels: true`) to preserve pixel-art crispness.
+
+## 2. Core Systems Specification
+
+### 2.1 Physics: The "25-Ton" Feel
+- **Hull Movement:** Implementation of a linear acceleration model to simulate inertia. 
+  - `accel = (input * power) - (velocity * friction)`
+- **Turret Rotation:** Capped rotation speed (15°/sec) using `Phaser.Math.Angle.RotateTo`.
+- **Constraints:** Hull and Turret are separate entities; the Turret is anchored to the Hull's center.
+
+### 2.2 Vision: The Periscope Mask
+- **The Mask:** A full-screen `Graphics` layer with a rectangular hole.
+- **Unbuttoning:** An `E` key toggle that slides the mask off-screen.
+- **Death State:** While "Unbuttoned", the `CommanderHatch` hit-box is active. Any single projectile hit = `Game Over`.
+
+### 2.3 Combat: Bullet Hell Logic
+- **Pooling:** `Phaser.Physics.Arcade.Group` for all projectiles to avoid GC spikes.
+- **Patterns:**
+    - **Horizontal Walls:** Coordinated emitter arrays synchronized via a `PatternManager` class.
+    - **Artillery Rings:** `Phaser.Geom.Circle` markers → 2s delay → radial explosion.
+- **Audio Telegraphs:** Bugle/Whistle sounds triggered 1.5s prior to pattern start.
+
+### 2.4 UI: Diegetic HUD
+- **Instruments:** All UI elements are sprites located in the "interior" layer.
+- **Needle Gauges:** Rotational logic for Fuel and Temperature needles.
+- **Ammo Tracker:** Shell-sprite replacement (Full $\rightarrow$ Spent).
+
+## 3. Development Roadmap
+
+### Sprint 1: Prototype 0 (The Machine)
+- [ ] Implement hull acceleration/friction.
+- [ ] Implement turret rotation lag.
+- [ ] Basic tank sprite integration.
+
+### Sprint 2: Prototype 1 (The Vision)
+- [ ] Create the periscope mask overlay.
+- [ ] Implement the "Unbutton" transition (Tween).
+- [ ] Add "Unbuttoned" vulnerability hit-box.
+
+### Sprint 3: Prototype 2 (The Hell)
+- [ ] Create `PatternManager` for bullet pools.
+- [ ] Implement "Infantry Wall" pattern.
+- [ ] Implement "Artillery Ring" telegraphs and impacts.
+
+### Sprint 4: Prototype 3 (The Interface)
+- [ ] Link `engineTemp` and `fuel` variables to analog needle sprites.
+- [ ] Implement ammo selection (1-4) and sprite-based count.
+- [ ] Add radio scanning visual/audio loop.

geography_research.md

@@ -0,0 +1,129 @@
+# Geography & Historical Plausibility Research for IRON REQUIEM
+
+## (1) Murmansk & Arkhangelsk — Terrain, Tundra, Frozen Conditions
+
+### Murmansk Oblast (Kola Peninsula)
+- **Northern Kola Peninsula (above ~67°N):** True Arctic tundra — treeless, underlain by continuous permafrost, covered in mosses, lichens, and dwarf shrubs. Winter brings polar night (sun doesn't rise for ~40 days). Deep snow, white-out blizzards, frozen lakes. The landscape is stark, windswept, and oppressive — an excellent match for "The Frozen Tundra" zone.
+- **Inland terrain:** The peninsula is dotted with thousands of lakes, low rolling hills, and the Khibiny Mountains (peaks ~1,200m). Rocky outcrops break the snow. Scattered stunted birch in sheltered valleys near the tree line.
+- **Southern Kola:** Transitions to taiga — boreal pine and spruce forest. Still subject to extreme cold but with tree cover.
+- **Murmansk city itself** is ice-free year-round (Gulf Stream influence), but 50 km inland the conditions revert to true Arctic winter.
+
+### Arkhangelsk Oblast
+- **Arctic coast (Nenets Autonomous Okrug):** Pure tundra — flat, treeless, permafrost, boggy in summer, frozen solid in winter.
+- **Around Arkhangelsk city:** Northern taiga — dense coniferous forest interspersed with vast peat bogs and marshes. Not tundra. The city sits on the Northern Dvina River delta.
+- **Between Arkhangelsk and the Arctic coast:** Mostly taiga and forest-tundra transition zone (lichen woodlands, scattered spruce).
+
+### Verdict on "Frozen Wasteland"
+The Kola Peninsula's northern interior in winter fits perfectly: Arctic tundra, -30°C to -40°C temperatures, white-out blizzards, almost no human settlement, frozen lakes, and the psychological oppression of polar darkness. The GDD's description — "white-out conditions, deep snow slowing movement, sparse cover" — aligns exactly with this terrain. A German unit cut off here would face exactly the survival-horror conditions described.
+
+---
+
+## (2) Abandoned Soviet Industrial Sites Between Arctic Coast and Central Russia
+
+### Kola Peninsula Industrial Complex (closest to the tundra zone)
+- **Kirovsk** (~180 km south of Murmansk): Founded 1929. Massive apatite-nepheline mining and processing complex. Gigantic open-pit mines, Soviet-era concrete processing plants, towering smokestacks, industrial rail yards. In the game's timeline, this could easily be depicted as abandoned and rusting in the snow.
+- **Monchegorsk** (~140 km south of Murmansk): Built around the Severonickel smelter — one of the most contaminated places on Earth. The landscape is an environmental dead zone: dead forests stained by sulfur dioxide, slag heaps, and Soviet-era heavy industrial architecture. Surreally bleak and directly on a plausible retreat route from the northern tundra.
+- **Nikel & Zapolyarny** (near the Norwegian border): Nickel mining and smelting towns. Smaller scale but still heavily industrial.
+- **Olenegorsk & Kovdor:** Iron ore mining and processing.
+
+### Other Industrial Sites (further from the prime retreat corridor)
+- **Vorkuta** (Komi Republic, far east): Soviet coal-mining center built entirely on GULAG labor. Vast abandoned mine complexes, prison-camp ruins, and a dead-end railway. Iconic but ~1,000 km from Murmansk — too far for a single retreating division unless the timeline stretches significantly.
+- **Severodvinsk** (near Arkhangelsk): The Sevmash submarine shipyards — massive Soviet naval-industrial complex. Still active, but portions could be depicted as abandoned. Coastal, not on a direct overland retreat route.
+- **Belomorsk / White Sea-Baltic Canal:** Built by GULAG prisoners in the 1930s. A chain of locks, dams, and labor-camp ruins stretching from the White Sea to Lake Onega. Haunting and thematically on-point.
+
+### Verdict
+Kirovsk and Monchegorsk are the strongest candidates. Both are within ~200 km of genuine Arctic tundra on the Kola Peninsula, both are real Soviet-era heavy industrial sites with visually striking infrastructure (open-pit mines, smelters, concrete plants), and both are directly on a plausible southward retreat route from the Murmansk Arctic zone. The GDD's "rust-streaked metal, narrow corridors, combat in factories and warehouses" maps cleanly onto these locations.
+
+---
+
+## (3) Retreating German Division's Path from Northern Russia Toward Europe
+
+### Historical Context
+In late 1944, the actual German forces in far-northern Russia were part of the 20th Mountain Army (not the 6th Panzer Division), operating in the Murmansk sector and northern Finland/Norway. The GDD's alternate-history 6th Panzer Division would need to be displaced into this geography. Starting from the Murmansk Arctic coast, the most plausible overland retreat toward Germany follows this corridor:
+
+### Path A: Kola → Finland → Norway → Denmark → Germany (Recommended)
+1. **Start:** Cut off near the Arctic coast northeast of Murmansk — genuine tundra.
+2. **South through Kola Peninsula:** Passes Kirovsk/Monchegorsk industrial zones. Crosses the tree line into taiga.
+3. **Into Finnish Lapland:** Sparse Arctic terrain, then boreal forest. Cross the Kemijoki River. Germany's ally Finland switched sides in Sept 1944 (Lapland War), so this is hostile territory by late 1944.
+4. **Through northern Norway (Finnmark):** German-occupied until May 1945. Mountainous coastal terrain — fjords, narrow passes. The Germans conducted a scorched-earth retreat through here historically.
+5. **South through Norway:** Along the coast or interior toward Oslo. Mountain passes, tunnels, narrow valleys.
+6. **Cross the Skagerrak** to Denmark (Jutland).
+7. **Into northern Germany:** Ending at Hamburg, Kiel, or Lübeck — all bombed, all with Gothic/Hanseatic architecture.
+
+### Path B: Kola → Karelia → Baltic States → East Prussia → Poland
+1. **Start:** Same Arctic tundra origin.
+2. **South through Karelia:** Dense taiga, thousands of lakes, swamps. Historically terrible for armored divisions (the Finns had success stopping Soviet armor here in the Winter War using exactly this terrain).
+3. **Through southern Finland or across Lake Ladoga:** Into the Karelian Isthmus.
+4. **Baltic States (Estonia, Latvia, Lithuania):** Flat, forested, increasingly urbanized as you move south. By late 1944, the Red Army was sweeping through — adds enemy pressure.
+5. **Into East Prussia:** Königsberg (devastated by Soviet assault April 1945).
+6. **Onward to Danzig/Warsaw.**
+
+### Verdict
+Path A has the tightest geography: the tundra-to-industrial transition happens within ~200 km on the Kola Peninsula, and the retreat corridor through German-occupied Norway is historically grounded. Path B covers a much longer distance but ends at richer "European city ruins" options (Warsaw, Danzig, Königsberg). Either works — the GDD's alternate-history framing gives latitude to compress distances.
+
+---
+
+## (4) European Cities Captured/Destroyed in WWII — Candidates for the Final Zone
+
+The GDD specifies "Gothic architecture interspersed with futuristic Chinese fortifications." The candidate city needs:
+- Gothic architectural heritage (cathedrals, spires, old town)
+- Historically destroyed or captured in WWII (so ruins are plausible)
+- On or near a retreat corridor from the northeast
+
+### Top Candidates
+
+| City | Gothic Heritage | WWII Destruction | On Retreat Path? |
+|------|----------------|------------------|-------------------|
+| **Danzig (Gdańsk)** | ★★★★★ St. Mary's Church (largest brick Gothic church in the world), Hanseatic Gothic old town, medieval port | 90% of old town destroyed in 1945 Soviet assault | Yes — Path B via Baltic coast |
+| **Königsberg (Kaliningrad)** | ★★★★ Gothic cathedral (Kant's tomb), Teutonic castle, Altstadt | Devastated by RAF bombing (Aug 1944) and Soviet assault (April 1945); the castle was leveled | Yes — Path B via East Prussia |
+| **Warsaw** | ★★★★ Gothic old town (St. John's Cathedral, Barbican, Market Square) | 85% of the city systematically destroyed after the 1944 Uprising | Yes — Path B further south |
+| **Hamburg** | ★★★★ Brick Gothic (St. Nikolai, St. Petri), Hanseatic architecture | Firebombed July 1943 (Operation Gomorrah) — 50% of the city destroyed | Yes — Path A via Denmark (but Hamburg is more Hanseatic/brick than "Gothic" in the spire sense) |
+| **Dresden** | ★★★★ (mostly Baroque/Rococo, not Gothic; the Frauenkirche is Baroque) | Firebombed Feb 1945 — iconic ruins | Only on a very southern route — far from Arctic retreat |
+| **Breslau (Wrocław)** | ★★★★ Gothic old town, Cathedral Island | 70% destroyed in 1945 siege | Path B far southern variant |
+
+### Recommendation for the Game
+**Danzig/Gdańsk** is the strongest candidate. It has unmistakably Gothic architecture (St. Mary's is a towering brick Gothic landmark — instantly recognizable in pixel art), was nearly leveled in 1945, sits directly on the Baltic coast retreat corridor, and has the visual contrast between medieval Gothic and "futuristic Chinese fortifications" that the GDD calls for.
+
+**Fallback: Königsberg** — the Teutonic/Königsberg Castle ruins plus the Gothic cathedral make for equally strong imagery, and it's slightly closer to the Baltic origin point.
+
+---
+
+## (5) Plausibility: Can All Three Zones Exist on One Retreat Path?
+
+### YES — with high confidence.
+
+The Kola Peninsula alone satisfies the transition from Zone 1 to Zone 2 within a single geographical region:
+
+```
+Zone 1 — Frozen Tundra:         Kola Peninsula interior (67–69°N)
+                                  ↓ ~120–180 km southward retreat
+Zone 2 — Abandoned Industrial:   Kirovsk / Monchegorsk mining-smelting complex
+                                  ↓ ~800–1,500 km southwest through Finland/Norway
+Zone 3 — Captured European City: Northern Germany or Baltic coast
+```
+
+### The Critical Transition (Tundra → Industrial)
+This is the tightest geographic constraint and it passes cleanly: the northern Kola Peninsula is genuine Arctic tundra, and the mining-industrial cities of Kirovsk and Monchegorsk lie just 120–180 km south. A Wehrmacht armored unit retreating from the Arctic coast toward Murmansk would naturally pass through this industrial belt. The landscape transition from featureless white tundra to rusting Soviet factory complexes is **geographically and visually authentic**.
+
+### The Longer Leg (Industrial → City Ruins)
+This requires compressing European geography, but a game design document has full license to do this. The retreat through Finland, Norway, and Denmark into northern Germany (or through the Baltic states into Poland) is a documented historical corridor. German forces actually operated throughout this region. The GDD's alternate-history framing means the exact distances can be elided — what matters is that the *sequence* of biomes is plausible, and it is.
+
+### Alternate Reading: Could they be adjacent?
+If the GDD intends these zones to be closely adjacent (not separated by weeks of travel), the tightest possible alignment would be:
+- **Frozen Tundra:** Kola Peninsula Arctic coast
+- **Abandoned Industrial:** Kirovsk/Monchegorsk (120–180 km south — 1–2 days by tank)
+- **Captured European City:** This is the stretch. The nearest destroyed European Gothic city would be Königsberg (~1,500 km overland) or Hamburg (~2,000 km via Norway). These are not "adjacent." The GDD will need to accept a time-gap montage or compress the map.
+
+---
+
+## Summary Verdict
+
+| GDD Element | Real-World Match | Fit Quality |
+|------------|------------------|-------------|
+| Frozen Tundra (white-out, deep snow, sparse cover) | Kola Peninsula Arctic tundra | ★★★★★ Perfect match |
+| Abandoned Soviet Industrial (rust, factories, narrow corridors) | Kirovsk / Monchegorsk mining-smelting complex | ★★★★★ Authentic and geographically adjacent to tundra |
+| Captured European City Ruins (Gothic + Chinese fortifications) | Danzig/Gdańsk or Königsberg | ★★★★ Strong match; requires geographic compression |
+| All three on one retreat path | Kola → Kola Industrial → Finland/Norway → Baltic/Poland | ★★★★ Plausible corridor; distance needs narrative compression |
+
+### Recommendation
+Set the opening in the Kola tundra northeast of Murmansk. Place the industrial zone in a fictionalized composite of Kirovsk and Monchegorsk (apatite mines + nickel smelters + concrete plants). End at Danzig/Gdańsk for maximum Gothic visual impact. The corridor is geographically real enough to ground the fiction, and the GDD's alternate-history frame provides all the license needed.

reviews/dev-feasibility.md

@@ -0,0 +1,191 @@
+# Iron Requiem — Technical Feasibility Assessment
+
+**Reviewer:** dev
+**Date:** 2026-05-23
+**Source:** IRON_REQUIEM_GDD.md + PHASER_IMPLEMENTATION_PLAN.md
+**Verdict:** VIABLE WITH CAVEATS (see Scope Assessment)
+
+---
+
+## 1. Phaser 3 Fit
+
+**Overall: STRONG FIT.** Every mechanic described in Section 3 maps cleanly to Phaser 3 capabilities. No features require a different engine or raw WebGL.
+
+| Mechanic | Phaser 3 Primitive | Risk |
+|---|---|---|
+| Tank-as-Character (hull/turret) | `Phaser.Physics.Arcade.Sprite` × 2, parented | Low |
+| Bullet hell patterns | `Arcade.Group` with `maxSize` pooling | Low |
+| Resource management (fuel, ammo, heat) | Custom game logic (number state machines) | None |
+| Crew morale | Custom game logic (float + modifiers) | None |
+| Fog of war / radio tuning | Custom game logic + `Phaser.Sound` | None |
+
+**Edge case that needs thought:** The GDD mentions "player must exit the tank" for scavenging. If this means a separate player character sprite with its own physics body that can walk around, that's additional scope (new sprite sheets, animations, separate collision groups). Phaser handles it fine, but it's a new mechanic not detailed in Section 4.
+
+---
+
+## 2. Physics Feasibility
+
+### Hull/Turret Decoupling
+
+**Assessment: GREEN.** Straightforward in Arcade physics.
+
+Architecture:
+- Hull = `Arcade.Sprite` with `body` handling position/velocity
+- Turret = `Arcade.Sprite` positioned at `hull.x, hull.y` each frame
+- Turret body disabled (`body.enable = false`) — it doesn't need physics, just rotation
+
+The inertia formula `accel = (input × power) - (velocity × friction)` is applied directly via `body.setAcceleration()` or by setting `body.velocity` manually in `update()`:
+
+```js
+// Each frame:
+const accel = (inputVector * power) - (body.velocity.clone() * friction);
+body.setAcceleration(accel.x, accel.y);
+```
+
+**Gotchas:**
+- `body.setDrag()` exists but uses a damping coefficient, not linear friction. The formula above overrides it manually, which is fine.
+- Arcade physics bodies are AABB only — tank rotation visually rotates the sprite but the physics body remains an axis-aligned rectangle. For a top-down tank game this is acceptable (most bullet-hell hitboxes are smaller circles/points anyway).
+
+### Turret Rotation Cap
+
+**Assessment: GREEN.** `Phaser.Math.Angle.RotateTo(current, target, delta)` handles this exactly. Call it each frame with a delta of `15 * (delta/1000)` for 15°/sec. Zero surprises.
+
+---
+
+## 3. Rendering
+
+### Periscope Mask
+
+**Assessment: YELLOW.** Implementable but has a performance caveat.
+
+The approach: a full-screen `Phaser.GameObjects.Graphics` object that draws a filled rectangle with a rectangular hole. Each frame, `graphics.clear()` + redraw. In **CANVAS mode**, `Graphics.clear()` + redraw re-issues all drawing commands on the CPU. For a 640×360 canvas this is negligible alone, but combined with bullet hell...
+
+**Performance test needed:** Graphics mask + 200 pooled projectiles at 60fps in CANVAS mode. If frame drops occur, alternatives:
+1. Use a `RenderTexture` with a pre-drawn mask (draw once, display as static image)
+2. Use CSS `clip-path` on the canvas element itself (offloads to browser compositor)
+3. Switch to WebGL (`Phaser.WEBGL`) — pixel art crispness can be preserved with `roundPixels: true` and nearest-neighbor texture filtering
+
+**Recommendation:** Prototype the mask + 200 projectiles first. If CANVAS chokes, switch to WEBGL with `pixelArt: true` — it's a one-line config change.
+
+### Animated Hatch
+
+**Assessment: GREEN.** Tween + sprite sheet animation. Standard Phaser.
+
+### Side-View Cutscenes
+
+**Assessment: GREEN.** Separate `Phaser.Scene` with sprites and text. No engine issues.
+
+### Diegetic UI (Needle Gauges, Sprite Ammo)
+
+**Assessment: GREEN.** Needle rotation: `gaugeSprite.setAngle(value)` mapped from fuel/heat ranges. Ammo sprites: show/hide or swap texture based on count.
+
+---
+
+## 4. Object Pooling
+
+### Bullet Hell Density
+
+**Assessment: YELLOW (requires testing).**
+
+`Arcade.Group` with `maxSize` handles pooling natively. Patterns:
+
+- **Infantry Walls:** `Arcade.Group` with ~100-150 active projectiles. Phaser's Arcade physics handles this at 60fps on modern hardware.
+- **Artillery Rings:** Circle markers drawn once via `Graphics`, explosion as `Arcade.Sprite` pool burst. 50-80 active particles per ring.
+- **Tank Destroyer Beams:** Fast single projectiles. Trivial.
+
+**Concern:** Simultaneous active patterns. If an infantry wall (150 bullets) fires during an artillery ring (80 particles) + player projectiles + enemy tank fire, we're at ~250-300 active physics bodies. Arcade physics does O(n²) broadphase by default. At 300 bodies = 90,000 checks per frame. On a desktop CPU this is fine. On mid-range mobile/laptops it may dip below 60fps.
+
+**Mitigation strategies (available if needed):**
+1. Use `Phaser.Physics.Arcade.World.setBounds()` to cull off-screen bodies
+2. Enable `checkCollision.none` on projectile-projectile pairs (they shouldn't collide with each other)
+3. Group projectiles into fewer Arcade.Groups to reduce overhead
+
+**Memory/GC:** Pooling eliminates GC pressure. `createCallback` reuses dead members. This is a solved problem in Phaser.
+
+---
+
+## 5. Audio
+
+**Assessment: GREEN.** Phaser's sound manager handles WebAudio and HTML5 Audio fallback seamlessly.
+
+| Audio Need | Phaser Feature |
+|---|---|
+| Engine drone loop | `sound.play('engine', { loop: true })` |
+| Crew barks (German, subtitled) | `sound.play('bark_ammo_low')` + subtitle text |
+| Chinese radio chatter | `sound.play('radio_chatter', { volume: 0.3 })` |
+| PLA bugles/whistles (1.5s before patterns) | `this.time.delayedCall(1500, () => pattern.fire())` with audio trigger at t=0 |
+| Ambient change on hatch toggle | Tween volume levels on ambient tracks |
+
+**Note:** Phaser's audio sprites (single file with markers) are ideal for the many short barks and FX. Reduces HTTP requests.
+
+---
+
+## 6. Save System
+
+**Assessment: GREEN.**
+
+Data to persist:
+- Crew stats (morale, training level): ~1KB
+- Iron Ledger entries (text log): ~10-50KB
+- Upgrade state: ~500 bytes
+- Ghost crews: ~5KB per save slot × 3 slots
+
+Total: well under localStorage's 5MB limit. For the Iron Ledger, if entries grow unbounded, IndexedDB (`localforage` wrapper recommended) handles larger structured data.
+
+**Implementation:** Simple JSON serialization to localStorage per save slot. No server needed — matches the spec exactly.
+
+---
+
+## 7. Scope Assessment
+
+### By Section
+
+| GDD Section | Rating | Rationale |
+|---|---|---|
+| **3.1 Tank-as-Character** | GREEN | Hull/turret decoupling is standard Arcade physics. Inertia model is straightforward math. Already prototyped in implementation plan. |
+| **3.2 Bullet Hell Patterns** | GREEN | Arcade groups + pooling handle all three patterns. PatternManager class is clean architecture. |
+| **3.3 Resource Management** | GREEN | Pure game logic. Numbers + UI hooks. Zero engine dependency. |
+| **3.4 Heat & Freeze-Thaw** | GREEN | Another state variable. Interacts with movement (speed modifier) and enemy detection (thermal signature modifier). Simple. |
+| **3.5 Crew Morale** | GREEN | Float + modifier stack. Effects applied as multipliers to reload speed, turret accuracy, etc. Pure logic. |
+| **3.6 Fog of War / Radio** | GREEN | Audio + text display. No physics. |
+| **4.1 Hatch Mechanic** | GREEN | Tween + hitbox toggle. Already specced in implementation plan. |
+| **4.2 Side-View Cutscenes** | GREEN | Separate Scene. Sprite + text display. |
+| **4.3 The Last Transmission** | GREEN | Mini-game: tune frequency via input, success/failure callback. |
+| **4.4 Iron Ledger** | GREEN | Text entry + localStorage save. |
+| **4.5 Parasite Run** | YELLOW | Requires "exit tank" mechanic (new sprite, animations, collision). Not specced in implementation plan. Adds scope. |
+| **4.2 (rendering)** | YELLOW | Periscope mask + bullet density may challenge CANVAS mode. Prototype needed. |
+| **— Overall Architecture** | YELLOW | `Phaser.SAGA` is mentioned in implementation plan line 7. This does not exist as a Phaser renderer. The renderer modes are `Phaser.CANVAS` (0), `Phaser.WEBGL` (1), and `Phaser.HEADLESS` (2). Likely a typo for `Phaser.CANVAS`, but flagging. |
+
+### Summary Count
+- **GREEN:** 10 sections
+- **YELLOW:** 2 sections (Parasite Run, Canvas mask performance)
+- **RED:** 0 sections
+
+---
+
+## 8. Architecture Discrepancy Flag
+
+The GDD and PHASER_IMPLEMENTATION_PLAN.md both target **Phaser 3**. However, parent task t_849ddebd (2026-05-22) selected **Babylon.js 7 + Rapier WASM + Vite + TypeScript** as the stack. These are mutually exclusive choices. Phaser 3 is a 2D sprite-based game framework; Babylon.js is a 3D engine.
+
+If the decision has already been made for Babylon.js, this review needs to be rewritten — Phaser's Arcade physics, CANVAS pixel-art mode, and Graphics-based mask are all Phaser-specific and don't translate to Babylon.js without significant rearchitecture.
+
+**Recommendation:** Resolve this before any code is written. The GDD is a 2D pixel-art game. Phaser 3 is the natural fit. If Babylon.js is locked in, the GDD needs revisiting for whether 2D pixel-art is the right aesthetic for a 3D engine.
+
+---
+
+## 9. Recommendations
+
+1. **Fix the `Phaser.SAGA` typo** in PHASER_IMPLEMENTATION_PLAN.md line 7 → `Phaser.CANVAS`
+2. **Prototype the mask + 200 bullets** before committing to CANVAS mode
+3. **Defer Parasite Run** (Section 4.5) — it's mechanically interesting but adds the most scope (player-on-foot sprite, separate physics, inventory transfer). Ship the tank-only game first.
+4. **Resolve the Phaser vs Babylon.js conflict** with the project owner before any code
+5. **Consider TypeScript** — the implementation plan mentions JS/TS but doesn't commit. TS catches type errors at build time; worth the setup cost for a game with this many interacting systems.
+
+---
+
+## Appendix: Quick Reference
+
+- **Phaser 3 API docs:** https://newdocs.phaser.io/
+- **Phaser Arcade Physics body:** https://newdocs.phaser.io/docs/3.60.0/Phaser.Physics.Arcade.Body
+- **Phaser.Math.Angle.RotateTo:** https://newdocs.phaser.io/docs/3.60.0/Phaser.Math.Angle.RotateTo
+- **Arcade.Group pooling:** https://newdocs.phaser.io/docs/3.60.0/Phaser.Physics.Arcade.Group

reviews/researcher-accuracy.md

@@ -0,0 +1,408 @@
+# Iron Requiem — Historical Accuracy & World-Building Review
+
+**Reviewer:** researcher
+**Date:** 2026-05-23
+**Sources:** GDD (IRON_REQUIEM_GDD.md), prior geography research (geography_research.md), established WWII military history
+
+---
+
+## 1. PANZER IV AUSF H — SPEC ACCURACY
+
+### What the GDD Claims
+- Panzer IV Ausf H
+- Hull/turret decoupling (hull moves independently of turret)
+- 25-ton weight
+- "Short 75mm KwK 40"
+- Crew of 5
+- Drifts on ice and snow
+
+### Actual Panzer IV Ausf H Specifications
+
+| Spec | GDD Claim | Real Value | Accuracy |
+|------|-----------|------------|----------|
+| **Weight** | 25 tons | 25.0 tonnes (combat loaded) | CORRECT |
+| **Main gun** | "Short 75mm KwK 40" | 7.5 cm KwK 40 L/48 (long barrel, not short) | **ERROR** — see below |
+| **Crew** | 5 | 5 (Commander, Gunner, Loader, Driver, Radio Operator/Bow MG) | CORRECT |
+| **Top speed (road)** | Not specified | 38 km/h (governed), 42 km/h max | N/A |
+| **Top speed (cross-country)** | Not specified | 16-20 km/h off-road; in deep snow effectively ~5-10 km/h | N/A |
+| **Turret traverse** | Not specified | ~26°/sec (electric, from auxiliary engine) or ~1.9°/sec (manual hand-crank) | N/A |
+| **Hull/turret decoupling** | Independent movement | **Historically CORRECT in principle** — the turret traversed independently of the hull. This is how all tanks work. But the GDD's "manage both simultaneously" framing is a game-design choice, not a historical question. | FUNCTIONAL |
+| **Front armor** | Not specified | 80mm hull front, 50mm turret front, 30mm sides | N/A |
+| **Ammo types** | AP, HE, Smoke, Canister | Pzgr 39 (APCBC), Pzgr 40 (APCR/tungsten, rare), Sprgr 34 (HE), Gr.Patr. 38 HL (HEAT). **No dedicated smoke or canister shell was produced for the 75mm KwK 40.** Smoke was delivered via external launchers (Nebelkerzenabwurfvorrichtung, Nahverteidigungswaffe), not main gun rounds. | **ERROR** — smoke and canister rounds didn't exist for this gun |
+| **Engine** | Not specified | Maybach HL 120 TRM, 12-cylinder, 300 PS (296 hp), water-cooled gasoline | N/A |
+| **Power-to-weight** | Not specified | ~12 PS/tonne | N/A |
+| **Range** | Not specified | 210 km road, 130 km cross-country | N/A |
+| **Fuel consumption** | Not specified | ~2.3 L/km on road, ~3.5 L/km off-road; 470L fuel capacity | N/A |
+
+### The "Short 75mm KwK 40" Problem — MAJOR ERROR
+
+This is the single biggest technical error in the GDD. There is no such thing as a "short 75mm KwK 40."
+
+- The **KwK 40** was the **LONG-BARRELED** 75mm gun (L/43 and L/48 variants). It was the definitive high-velocity anti-tank gun fitted to the Panzer IV Ausf F2, G, H, and J. Barrel length: ~3.6 meters.
+
+- The **KwK 37** was the **SHORT-BARRELED** 75mm gun (L/24). It was a low-velocity infantry support howitzer fitted to early Panzer IV models (Ausf A through F1). Barrel length: ~1.8 meters.
+
+The Panzer IV Ausf H ALWAYS mounted the long KwK 40 L/48. The short KwK 37 was obsolete by 1943 and had been completely phased out of Panzer IV production.
+
+**IMPACT ON GAMEPLAY:** If the GDD intends a short-barreled gun with limited range and low velocity (making bullet-hell patterns harder to counter at range), the tank should be an **early Panzer IV (Ausf D/E/F1)** or the GDD should simply correct the gun designation to "7.5 cm KwK 40 L/48" and accept the long-barrel silhouette.
+
+### Turret Traverse in Combat
+
+Real Panzer IV turret traverse was powered by an electric motor running off a small auxiliary generator. At 26°/sec, a full 360° rotation took ~14 seconds. If the electrical system failed (common), the gunner used a hand crank at ~1.9°/sec — a complete rotation took over 3 minutes. This has direct gameplay implications: a "turret speed" penalty from damage or morale could be grounded in the real vulnerability of the electrical traverse system.
+
+### Ammo Capacity and Types
+
+A Panzer IV Ausf H carried approximately 87 rounds of 75mm ammunition. The historical breakdown:
+- **Pzgr 39 (APCBC):** 6.8 kg projectile, 750 m/s muzzle velocity, penetration ~96mm at 500m at 30°. This was the workhorse anti-tank round.
+- **Pzgr 40 (APCR):** Tungsten-cored, rare by 1944 due to tungsten shortages. 930 m/s, penetration ~120mm at 500m. Extremely limited supply.
+- **Sprgr 34 (HE):** 5.74 kg, 550 m/s. Used against infantry, AT guns, soft targets.
+- **Gr.Patr. 38 HL (HEAT):** Shaped-charge round, ~450 m/s. Useful when AP was scarce or at extreme range.
+
+**No dedicated smoke or canister shells were produced for the 75mm KwK 40.** The Panzer IV used external smoke dischargers — early models had the Nebelkerzenabwurfvorrichtung (rear-hull smoke grenade rack), and the Ausf H used the Nahverteidigungswaffe (close-defense weapon that could fire smoke grenades). Smoke screening came from external launchers, not main gun rounds.
+
+**GDD ammo recommendation:** Keep AP, HE, and Smoke as game mechanics (they're fun and mechanically distinct), but note that smoke historically was an external launcher system, not a main gun shell. Canister should be removed or treated as a fictional/scavenged special round — it did not exist for this gun.
+
+---
+
+## 2. 6TH PANZER DIVISION — HISTORICAL ACCURACY
+
+### (1) Did They Operate on the Eastern Front in 1944?
+
+**YES, but NOT in northern Russia.** The 6th Panzer Division fought on the Eastern Front in 1944 — on the **southern sector**: Hungary, Romania, and eventually Austria.
+
+### (2) Actual Operational Area in 1944
+
+Full timeline of the 6th Panzer Division:
+
+| Period | Location | Operations |
+|--------|----------|------------|
+| **Oct 1939** | Formed at Wuppertal, Germany | Created from 1st Light Division and other elements |
+| **1940** | France/Belgium | Battle of France, Channel coast |
+| **1941** | Eastern Front — **Army Group North** | Operation Barbarossa, advance on Leningrad. Fought in the Baltic states and approach to Leningrad. This is the CLOSEST they ever got to "northern Russia," but still ~1,000 km south of Murmansk. |
+| **1942 (early)** | Eastern Front — Rzhev salient, Army Group Centre | Defensive battles near Moscow |
+| **1942 (mid)** | France | Pulled out for refitting after heavy losses |
+| **1942 (late)** | Eastern Front — **southern sector** | Operation Winter Storm (failed Stalingrad relief attempt near Kotelnikovo) |
+| **1943** | Eastern Front — Kharkov, Kursk, Dnieper | Heavy fighting in Ukraine |
+| **1944 (spring)** | **Hungary / Romania** | Army Group South Ukraine. Defensive battles in Hungary. Fought at Debrecen, the Carpathian passes, and the Budapest approaches. |
+| **1944 (late)** | **Hungary** | Battle of Debrecen (October 1944), then defending Budapest approaches. The division was ground down by continuous Soviet offensives. |
+| **1945** | **Austria** | Retreat through Austria. Surrendered to the US 3rd Army in the Alps (Steyr region) in May 1945. Elements that couldn't reach the Americans surrendered to the Soviets. |
+
+### (3) Northern Russia — Murmansk/Arkhangelsk — Were They Ever There?
+
+**NO. The 6th Panzer Division never operated anywhere near Murmansk, Arkhangelsk, or the Kola Peninsula.**
+
+The German forces actually in far-northern Russia/Norway/Finland in 1941–1944 were:
+
+- **20th Mountain Army (20. Gebirgsarmee)** under Generaloberst Eduard Dietl (later Generaloberst Lothar Rendulic)
+- Included the **2nd** and **6th Mountain Divisions**, **169th Infantry Division**, **163rd Infantry Division**, and various SS and Finnish units
+- Their objective was Murmansk and the Kola Peninsula — specifically to cut the Murmansk Railway (the Lend-Lease supply line from the Arctic port)
+- They advanced to the Litsa River (~60 km from Murmansk) in 1941 and stagnated there in trench warfare until the general retreat in late 1944
+
+**Critical distinction:** The 6th *Mountain* Division (6. Gebirgs-Division) operated in the Murmansk sector. The 6th *Panzer* Division (6. Panzer-Division) did not. These are entirely different formations. The GDD may be conflating the two, or making an intentional alt-history choice.
+
+### (4) Actual Fate by War's End
+
+The 6th Panzer Division:
+- Fought through Hungary and Austria in early 1945
+- Divisional remnants surrendered to the **US 3rd Army** near Steyr, Austria, in May 1945
+- Some elements that were cut off on the eastern side of the Soviet advance surrendered to the Red Army instead
+- The division was not destroyed in combat — it survived as a cohesive formation to war's end, though severely depleted
+- The division was formally disbanded after surrender
+
+**Notable:** The 6th Panzer Division was NOT encircled, NOT cut off behind enemy lines, and did NOT fight a desperate lone retreat. It was part of Army Group South's continuous fighting retreat from Hungary into Austria.
+
+### (5) Tank Composition
+
+The 6th Panzer Division's Panzer Regiment 11 fielded:
+
+| Period | Primary Tanks | Notes |
+|--------|--------------|-------|
+| **1939–1941** | Panzer 35(t), Panzer IV (short), Panzer II | Czech and light tanks formed the bulk |
+| **1942** | Panzer III (50mm L/60), Panzer IV (long 75mm) | Standardized on German mediums after France refit |
+| **1943** | Panzer IV Ausf G/H, some Panthers | Panthers began arriving mid-1943 |
+| **1944** | Panzer IV Ausf H/J, Panzer V Panther | Mixed battalion; roughly 50-60% Panzer IV, 40-50% Panther by late 1944 |
+| **1945** | Panzer IV, Panther, a handful of Panzer IV/70 tank destroyers | Severely depleted; sometimes operating at ~30% strength |
+
+In 1944, a Panzer division's Panzer Regiment was authorized to have roughly:
+- 1 battalion of Panthers (Panzer V)
+- 1 battalion of Panzer IVs
+
+But actual strength varied wildly. The 6th Panzer Division usually had fewer tanks than authorized, and by late 1944 many "tanks" were actually StuG III assault guns or Jagdpanzer IV tank destroyers used as tank substitutes.
+
+**Key point for the GDD:** If Hauptmann Voss commands a lone Panzer IV in 1944, this is plausible as part of a depleted battalion, but he'd likely have been in a mixed unit with Panthers present. A commander being separated from his formation and fighting alone is a narrative choice, not a historical impossibility.
+
+### (6) Formation and Command Structure
+
+**Formation:** October 18, 1939, at Wuppertal, Wehrkreis VI (Military District VI — Rhineland/Westphalia).
+
+**Nickname:** Not formally named, but sometimes called "Westfälische" (Westphalian) due to its recruitment base.
+
+**Divisional Commanders:**
+- 1939–1941: Generalmajor Werner Kempf
+- 1941–1942: Generalmajor Franz Landgraf
+- 1942–1943: Generalmajor Erhard Raus
+- 1943–1944: Generalmajor Walther von Hünersdorff (KIA July 1944)
+- 1944: Generalmajor Rudolf Freiherr von Waldenfels
+- 1944–1945: Oberst (later Generalmajor) Friedrich-Wilhelm Jürgens
+
+**Standard Panzer Division Organization (1944):**
+- Panzer Regiment (2 battalions)
+- Panzergrenadier Regiment (2 regiments, mechanized infantry)
+- Panzer Artillery Regiment (self-propelled Wespe and Hummel howitzers)
+- Panzer Reconnaissance Battalion
+- Panzerjäger Battalion (tank destroyers — Marders, later Jagdpanzer IV)
+- Panzer Pioneer Battalion
+- Panzer Signals Battalion
+- Divisional supply and support units
+
+A Hauptmann (Captain) would typically command a **company** (Kompaniechef) — roughly 14-17 tanks — within one of the Panzer Regiment's battalions. He would NOT be in divisional command; he'd be a mid-level line officer.
+
+### Verdict on the GDD Premise
+
+The premise of "Hauptmann Erich Voss and the remnants of the 6th Panzer Division, advancing through northern Russia in late 1944" has three historical problems:
+
+| Issue | Severity | Detail |
+|-------|----------|--------|
+| **Wrong geography** | **MAJOR** | The 6th Panzer Division was in Hungary in 1944, not northern Russia. They never got within ~1,000 km of Murmansk. |
+| **Wrong army group** | **MAJOR** | The 6th Panzer Division fought under Army Group South, not Army Group North (which was closer to the setting) or the 20th Mountain Army (which was actually near Murmansk). |
+| **"Advancing" is wrong** | **MINOR** | By late 1944, no German unit was "advancing" on the Eastern Front; they were all in retreat. |
+
+**Recommendation:** The GDD should either:
+1. **(Alt-history approach — KEEP IT):** Add a lore justification — "The 6th Panzer Division was mysteriously displaced/reassigned to the Arctic front after a temporal event." This is the cleanest fix; it's an alt-history game, so a brief handwave is sufficient.
+2. **(Historical accuracy approach — SWAP IT):** Change the unit to a formation that actually fought in the Murmansk sector: a company from the 2nd Mountain Division or from a Panzer-Abteilung attached to the 20th Mountain Army (e.g., Panzer-Abteilung 211, which operated captured French tanks in Finland, or Panzer-Abteilung 40 which had Panzer IIIs in Norway).
+3. **(Split the difference):** Keep the 6th Panzer Division name but make it clear in the lore that this is an alternate-history version of the division, reassigned north under mysterious circumstances. The temporal-fracture premise already supports this.
+
+---
+
+## 3. CHINESE COLD WAR FORCES
+
+### Type 59 Main Battle Tank
+
+The Type 59 is a Chinese-produced clone of the Soviet T-54A, manufactured from 1958 onward.
+
+| Spec | Type 59 (real) | Notes |
+|------|----------------|-------|
+| **Weight** | ~36 tonnes | Heavier than a Panzer IV (25t) |
+| **Main gun** | 100mm D-10T rifled gun (Type 59-I upgraded to 105mm L7 copy) | Significantly more powerful than the Panzer IV's 75mm KwK 40 |
+| **Armor** | 100mm hull front, 200mm turret front (cast) | The Panzer IV's 75mm KwK 40 would struggle to penetrate the frontal armor, especially of the turret |
+| **Speed** | 50 km/h road | Faster than the Panzer IV (38 km/h) |
+| **Crew** | 4 | Commander, Gunner, Loader, Driver |
+| **Production years** | 1958–1985 | First entering service in the late 1950s — firmly Cold War |
+| **GDD accuracy** | Described as "Mirror Match." In reality, the Type 59 outclasses the Panzer IV in gun, armor, and speed. If the GDD intends a fair fight, the player's Panzer IV must rely on ambush/flanking to hit the Type 59's thinner side armor. | |
+
+**Gameplay implication:** A frontal engagement between a Panzer IV Ausf H and a Type 59 heavily favors the Type 59. The 75mm KwK 40 could penetrate the Type 59's side armor (~80mm) at close range but would bounce off the frontal armor at typical combat distances. This actually makes for good game design — it forces the player to maneuver and flank, which the hull/turret decoupling mechanic supports.
+
+### Type 62 Light Tank
+
+| Spec | Type 62 (real) | Notes |
+|------|----------------|-------|
+| **Weight** | ~21 tonnes | Lighter than the Panzer IV |
+| **Main gun** | 85mm Type 62 rifled gun | Still capable of penetrating Panzer IV armor |
+| **Armor** | 15–35mm | Lightly armored — the Panzer IV can easily penetrate from any angle |
+| **Speed** | 60 km/h road | Very fast |
+| **Role** | Reconnaissance, fast flanking | The GDD correctly identifies them as "fast flankers" |
+| **Production** | 1963–1989 | Later Cold War |
+
+**GDD accuracy: GOOD.** The Type 62 as a fast, lightly-armored flanker that can be killed easily but threatens from behind is an accurate and effective game-design use of the real vehicle.
+
+### Did China Have Attack Helicopters in the Cold War Era?
+
+**YES, but timing matters.** The GDD's Chinese forces use "Helicopter Gunships" (line 104).
+
+| Platform | Real Chinese Service Entry | Cold War? | Notes |
+|----------|---------------------------|-----------|-------|
+| **Harbin Z-5** | 1958 | Yes | Licensed Soviet Mi-4. Could mount rockets but was primarily a transport. Limited gunship capability. |
+| **Harbin Z-6** | Prototype only, 1970s | Yes | Never entered mass production. |
+| **Changhe Z-8** | Early 1980s | Borderline | Licensed SA 321 Super Frelon. Heavy transport, not a pure gunship. |
+| **Harbin Z-9** | 1980s (armed variant: Z-9W, early 1990s) | NO | Licensed AS 365 Dauphin. The first true Chinese attack helicopter (Z-9W) didn't appear until the early 1990s — post-Cold War. |
+
+**The PLA did NOT field dedicated attack helicopter gunships during the Cold War.** The closest was the Z-5 with rocket pods, but it was a transport helicopter jury-rigged for ground attack — not a purpose-built gunship.
+
+The GDD's helicopter gunships "raining down rockets in sweeping arcs" are more characteristic of:
+- American AH-1 Cobra (Vietnam War, 1967+)
+- Soviet Mi-24 Hind (1972+)
+
+**Severity: MINOR.** This is an alt-history game. If the displaced Chinese forces have Cold War tech from a divergent timeline, attack helicopters are a reasonable artistic license. But they're not historically authentic to the PLA.
+
+### PLA Bugles, Massed Infantry Tactics — Historically Accurate?
+
+**Bugles: YES, authentic.** The PLA's use of bugles and whistles for battlefield signaling dates to the Chinese Civil War and Korean War (1950–1953). Bugle calls regulated charges, retreats, and formation changes. The "1.5-second audio telegraph" of bugles before bullet patterns (line 134) is both authentic and mechanically elegant.
+
+**Massed infantry formations: PARTIALLY ACCURATE but needs nuance.** During the Korean War, Western accounts described Chinese forces using "human wave" tactics, but the reality was more complex. PLA doctrine used infiltration and close-assault — dispersed small units attacking at night, closing to grenade range before firing. Massed assaults were typically the final phase after infiltration had already broken the enemy line, not a steady march across open ground. The perception of "waves" came from defenders on fixed perimeters at night facing attackers from multiple directions. By the Cold War era (1960s+), PLA doctrine had shifted to conventional Soviet-style combined-arms warfare.
+
+**Severity: MINOR.** Using massed infantry as bullet-hell "walls" is a clever translation of historical Chinese doctrine into game mechanics. It's stylized but grounded.
+
+---
+
+## 4. TEMPORAL CONSISTENCY
+
+### The Core Premise
+
+The GDD proposes: late 1944 Wehrmacht vs. Cold War-era PLA (displaced in time/alternate reality).
+
+### Technology Gap Analysis
+
+| Technology | Historical Introduction | In GDD? | Temporal Fit |
+|------------|------------------------|---------|--------------|
+| **Type 59 tank** | 1958 | Yes | 14 years after 1944 |
+| **Type 62 tank** | 1963 | Yes | 19 years after 1944 |
+| **RPGs (implied by "infantry coordinated bursts")** | RPG-2: 1949 (Soviet), RPG-7: 1961 (Soviet). Chinese Type 69 RPG: 1970s | Implied | 5–30 years after 1944 |
+| **Attack helicopters** | 1967 (AH-1 Cobra), 1972 (Mi-24) | Yes (line 104) | 23+ years after 1944 |
+| **Radio communication** | WWII-era radios existed on both sides | Yes | Neutral |
+| **Mandarin radio chatter** | Language is timeless | Yes | Neutral |
+
+### Verdict
+
+The technology gap is roughly **15–25 years.** Chinese forces are equipped at approximately a 1960s-1970s technological level. A 1944 German Panzer crew would face:
+
+- Tanks they literally cannot penetrate from the front
+- Helicopters (a technology that barely existed as a concept in 1944)
+- Infantry with shoulder-fired anti-tank rockets (RPGs were unknown in 1944; the closest equivalent was the German Panzerfaust, which the Soviets captured and reverse-engineered into the RPG-2)
+
+**The GDD's alt-history premise works IF the temporal-fracture justification is fleshed out.** Currently, the GDD says "A displaced, alternate-reality People's Liberation Army from the Cold War era has swept across Europe" (line 21) and mentions "the nature of the temporal fracture" (line 26). This is sufficient for the premise to hold — it's explicitly alternate history, not claiming historical accuracy.
+
+**Recommendation:** The GDD should decide how far the Cold War timeline diverges. If the Chinese force is from the 1950s (Korean War era), the tech gap is ~6-10 years. If it's from the 1960s-70s (Sino-Soviet split era), the gap is 20+ years. This choice affects:
+- Whether RPGs are RPG-2 (1950s, less accurate, shorter range) or Type 69 RPG (1970s, more capable)
+- Whether helicopters exist at all (no in 1950s, yes in 1960s+)
+- Whether night-vision/infrared exists (emerging in 1960s)
+- Whether the Chinese radio uses vacuum tubes or transistors
+
+---
+
+## 5. GEOGRAPHY (Integration with Prior Research)
+
+The geography_research.md document (already completed) provides a thorough assessment:
+
+- **Frozen Tundra:** Kola Peninsula Arctic tundra — ★★★★★ perfect match
+- **Abandoned Soviet Industrial:** Kirovsk/Monchegorsk — ★★★★★ authentic and adjacent
+- **Captured European City:** Danzig/Gdańsk or Königsberg — ★★★★ strong match
+
+**I endorse these findings.** The three-zone transition is geographically plausible on the Kola Peninsula → Finland/Norway → Baltic corridor.
+
+**Additional note from 6th Panzer Division research:** The actual German forces in the Kola/Murmansk theater were mountain troops and infantry, not panzer divisions. A Panzer IV would have extreme difficulty in the terrain described (tundra, deep snow, frozen lakes). Real German armor in the far north was limited to a handful of Panzer IIIs assigned to Panzer-Abteilung z.b.V. 40 in Norway, and even those struggled. The GDD should acknowledge this difficulty — it actually reinforces the survival-horror theme.
+
+---
+
+## 6. CREW & CULTURE
+
+### German Tank Crew Dynamics
+
+The GDD's crew of 5 (Commander, Gunner, Loader, Driver, Radio Operator) is **historically accurate** for a Panzer IV.
+
+**Real roles in combat:**
+- **Commander (Kommandant):** Stood in the turret, head out of the cupola when "unbuttoned." Used panoramic periscope when buttoned. Called targets, directed the driver, coordinated with other tanks via radio. The GDD's "hatch open = wider vision" mechanic is grounded in reality.
+- **Gunner (Richtschütze):** Sat to the left of the gun breech. Aimed via the TZF 5f telescopic sight. Fired the main gun and coaxial MG.
+- **Loader (Ladeschütze):** Sat to the right of the gun breech. Retrieved the correct ammunition type on command, loaded the gun, stowed empty casings. In an Ausf H, the loader handled ~10 kg shells in a cramped turret — physically exhausting.
+- **Driver (Fahrer):** Sat front-left in the hull. Peered through a vision slit; had terrible visibility. Took direction from the commander via intercom.
+- **Radio Operator/Bow Gunner (Funker):** Sat front-right. Operated the FuG 5 radio, fired the hull-mounted MG 34. Also acted as an assistant driver/navigator.
+
+### Crew Morale — Was the GDD's System Grounded in Reality?
+
+The GDD describes: stress from hits, crew death, and isolation → slower reloads, panic errors, delayed commands. Recovery via "The Iron Ledger" (journaling).
+
+**Historically grounded elements:**
+- **Crew cohesion was critical.** German tank crews trained together and stayed together. Losing a crew member was devastating psychologically and operationally — you can't operate a Panzer IV with 4 people at full effectiveness.
+- **Combat fatigue was real.** Crews in prolonged engagements experienced degraded performance. Reload times increased, target acquisition slowed, coordination broke down.
+- **The commander's psychological state drove the crew.** If the commander panicked, the crew panicked. If the commander was calm, the crew could function under fire.
+
+**The Iron Ledger (journaling):**
+- **Not a documented formal practice** in the Wehrmacht. German tank commanders did not keep therapeutic journals.
+- However, **Wehrmacht Soldbücher (pay books)** and personal diaries were extremely common. Soldiers wrote in them regularly. The act of writing was a grounding ritual.
+- The "Iron Ledger" as a formal crew morale tool is a **fictional invention** but a **thematically resonant** one. It's plausible in the alt-history context, especially for a unit cut off and facing existential horror. Treat it as a game-original mechanic with real psychological roots, not a historical artifact.
+
+**Panic errors (turret over-rotation):**
+- Real turret over-rotation wasn't a "panic error" — it was a mechanical failure of the electric traverse.
+- But the *concept* of crew errors under stress is real. Loaders fumbled shells. Gunners misjudged range. Drivers stalled the engine at the worst moment.
+- **Severity: MINOR.** The panic-error mechanic is a reasonable gamification of real combat degradation.
+
+### Morale Recovery Through Journaling — Psychological Basis
+
+The act of writing/narrating trauma has documented psychological benefits (expressive writing paradigm, Pennebaker & Beall, 1986). A crew trapped in a tank in an impossible situation, recording their experiences to maintain sanity, is thematically powerful and psychologically plausible — even if the specific "Iron Ledger" ritual is fictional.
+
+---
+
+## 7. SOUND AUTHENTICITY
+
+### PLA Bugles
+
+**Authentic and period-appropriate.** The bugle (号角 / 军号, hàojiǎo / jūn hào) was a standard PLA signaling instrument from the 1920s through the Korean War and into the Cold War era.
+
+**What they'd actually sound like:**
+- Bright, piercing brass tone — cuts through gunfire
+- Standard calls: charge (冲锋号), assembly (集合号), retreat (撤退号), ceasefire (停火号)
+- In battle, buglers stood and played while under fire — it was a position of honor and extreme danger
+- The bugle was as much psychological warfare as signaling: Chinese veterans describe the sound as a morale booster for their own troops and a terror weapon against the enemy
+
+The GDD's "PLA bugles and whistles signal the start of bullet patterns 1.5s in advance" (line 134) is a brilliant design choice. Bugles are intrinsically associated with the PLA, they're naturally attention-grabbing, and using them as telegraphs makes the audio diegetic (the enemy is literally signaling their own troops, and you're overhearing it).
+
+### Whistles
+Also authentic. Chinese NCOs and squad leaders used whistles alongside bugles for close-range command. The combination of distant bugles (strategic signal) and nearby whistles (tactical signal) would create a layered, menacing soundscape.
+
+### German Crew Barks
+
+Authentic. German tank crew communication was terse, technical, and loud over the engine noise. Examples of what they'd actually shout:
+- *"Panzergranate!"* — loader confirming AP round loaded
+- *"Achtung! Zwölf Uhr!"* — "Attention! 12 o'clock!" (enemy ahead)
+- *"Feuer!"* — "Fire!"
+- *"Fahrer, links!"* — "Driver, left!"
+- *"Treffer!"* — "Hit!" (on target)
+- *"Rückwärts! Schnell!"* — "Reverse! Quick!"
+- *"Motor überhitzt!"* — "Engine overheating!"
+
+These are short, guttural, and easy to subtitle. The GDD's "subtitled barks" approach is exactly right — short German phrases with English subtitles for gameplay clarity.
+
+### Mandarin Radio Chatter
+
+Authentic for a Chinese military force. By the Cold War era, PLA radio procedure was standardized. What players would hear:
+- Unit callsigns
+- Target coordinates
+- Formation orders
+- Status reports
+- The chatter would be clipped, procedural, and (to a non-Mandarin speaker) alienating — which reinforces the "enemy from another world" theme.
+
+**Additional realism note:** In 1944, the German FuG 5 radio operated on the 27-33 MHz band. If the Chinese Cold War forces use a different frequency range, the German crew couldn't intercept their transmissions at all. The GDD's "Radio Interception" mechanic (Section 3.6) needs an alt-history justification — perhaps the temporal fracture causes frequency bleed, or the Chinese are deliberately broadcasting on Wehrmacht frequencies as psychological warfare.
+
+---
+
+## 8. COMPREHENSIVE INACCURACY FLAGS
+
+| # | Issue | Location in GDD | Severity | Recommendation |
+|---|-------|-----------------|----------|----------------|
+| **1** | "Short 75mm KwK 40" — the KwK 40 is the LONG 75mm | Section 3.1 implied, though the GDD doesn't explicitly state "short" — the prior task spec does | **MAJOR** (if short is intended) | Either use the long KwK 40 L/48 (historically correct for Ausf H) OR switch to an early Panzer IV with the short KwK 37. Do not call the KwK 40 "short." |
+| **2** | 6th Panzer Division in northern Russia in 1944 | Section 2.1, line 21 | **MAJOR** | Add alt-history justification in the lore. The temporal-fracture premise already supports this; just make it explicit that the 6th Panzer Division was displaced or reassigned. Without this line, knowledgeable players will call it out. |
+| **3** | 6th Panzer Division "advancing" in late 1944 | Section 2.1, line 21 | **MINOR** | Change to "retreating" or "maneuvering" — no German unit advanced in late 1944. |
+| **4** | Chinese attack helicopters in Cold War | Section 5, line 104 | **MINOR** | Acceptable alt-history since the timeline is explicitly fractured. If aiming for realism, replace with ground-attack aircraft (Q-5 Fantan) or rocket-armed Z-5 transports. |
+| **5** | Type 59 as "Mirror Match" vs Panzer IV | Section 5, line 101 | **MINOR** | The Type 59 outclasses the Panzer IV. "Mirror match" implies parity; it should be framed as a David vs Goliath encounter. |
+| **6** | Smoke and canister ammo for 75mm KwK 40 | Section 3.3, line 57 | **MINOR** | Neither smoke shells nor canister rounds were ever produced for the 75mm KwK 40. Smoke was external launchers only; canister simply didn't exist. Keep smoke as a game mechanic (external launcher button) but note it's not a main gun round. Canister should be removed or rebranded as a fictional special-ammo type. |
+| **7** | Radio frequency interception across timelines | Section 3.6, line 72 | **MINOR** | Add lore justification: the temporal fracture causes frequency bleed, or the Chinese are transmitting on German frequencies for psy-war. Without this, the interception mechanic makes no technical sense. |
+| **8** | "The Iron Ledger" as a Wehrmacht practice | Section 4.4, line 92 | **INFO** | Not historical — a game-original mechanic. Thematically resonant and psychologically grounded. Keep it; just don't claim it's historically authentic. |
+| **9** | All three zones on a single retreat path | Section 6.1, lines 112-114 | ✅ **RESOLVED** | geography_research.md confirms this is geographically plausible on the Kola → Baltic corridor with narrative compression. Not an inaccuracy. |
+| **10** | Panzer IV "drifting" on ice and snow | Section 3.1, line 41 | **MINOR** | A 25-ton tracked vehicle on ice doesn't drift like a car. It can lose traction and slide, but "drift" implies a controlled slide — ice physics on a tank are more about loss of control. Minor wording issue. |
+
+---
+
+## SUMMARY VERDICT
+
+### Major Issues (should be addressed)
+1. **"Short 75mm KwK 40" confusion** — fix the gun designation
+2. **6th Panzer Division geography** — add alt-history justification for why they're in the Arctic
+
+### Minor Issues (acceptable artistic license)
+3. Chinese helicopters (accept as alt-history; note the anachronism)
+4. Type 59 as "mirror match" (rebalance framing)
+5. Radio frequency logic (add a lore handwave)
+6. Ice drift physics terminology
+
+### Thematically Strong Elements (no changes needed)
+- Bugle/whistle telegraphs — ★★★★★ perfect, authentic, mechanically elegant
+- Crew morale as combat degradation — psychologically grounded
+- The Iron Ledger — not historical but thematically powerful
+- Three-zone geography — ★★★★ geographically plausible
+- Ammo type variety — historically accurate with minor caveat on canister
+- Crew of 5 and their roles — fully authentic
+- Mandarin radio chatter — authentic and alienating in all the right ways
+
+### Bottom Line
+The GDD works as alt-history. With the two MAJOR issues addressed (gun designation and a brief lore justification for the 6th Panzer Division's presence in the Arctic), the historical plausibility is solid enough that knowledgeable players won't be pulled out of the experience. The game's explicit framing as alternate-history / temporal fracture provides abundant cover for the anachronisms. The real strength is the attention to sensory detail — bugles, barks, radio chatter — which grounds the fiction even when the timeline diverges.
+
+The 6th Panzer Division being in northern Russia is NOT historically correct, but the GDD doesn't claim to be historical fiction — it claims to be alternate-history. The temporal-fracture premise is the justification. Just make it explicit.

reviews/synthesis-verdict.md

@@ -0,0 +1,54 @@
+# Iron Requiem — GDD Review Synthesis & Verdict
+
+**Date:** 2026-05-23
+**Synthesizer:** game-designer (Hermes Agent)
+
+## 1. SYNTHESIS OF REVIEWS
+
+### Areas of Agreement
+- **Engine Fit:** All reviewers agree Phaser 3 is the correct tool for this 2D pixel-art vision.
+- **Strongest Elements:** The "Tank-as-Character" physics (hull/turret decoupling), the sensory audio telegraphs (PLA bugles), and the thematic "Iron Ledger" are high-value features.
+- **Risk Profiles:** High agreement that the "Unbuttoning" mechanic and the "Crew Morale" system are currently too punitive/binary and need refinement to avoid being "anti-fun."
+
+### Conflict & Divergence
+- **History vs. Alt-History:** The Researcher identified major historical inaccuracies (6th Panzer Division geography, gun designations). The GDD currently treats these as "given." The resolution is to solidify the "Temporal Fracture" lore to explicitly embrace alt-history rather than claiming historical authenticity.
+- **Complexity vs. Feasibility:** The Dev is concerned about the "Parasite Run" (on-foot mechanics) adding significant scope. The Tester sees it as a potentially tedious chore. I will defer this to a later slice.
+
+### Critical Risks Flagged
+1. **The "Death Trap" Loop:** Combining instant-death unbuttoning, off-screen periscope threats, and binary fuel-zero softlocks creates a "unfair" experience.
+2. **Morale Frustration:** Taking control away from the player (turret over-rotation) in a precision dodging game is a high-risk design choice.
+3. **Onboarding Gap:** The game has 6+ complex interacting systems but no tutorial, which is a critical failure point for player retention.
+4. **Save State Fragility:** Reliance on localStorage without explicit failure handling (corruption, private mode) is a technical risk.
+
+---
+
+## 2. VERDICT: CONDITIONAL YES
+
+**Iron Requiem is buildable in Phaser 3**, but the GDD must be updated to resolve specific design gaps and historical errors before implementation begins.
+
+### Required Changes for "YES" status:
+- **Lore:** Explicitly frame the 6th Panzer Division as "displaced" via the temporal fracture.
+- **Gun Specs:** Correct "Short KwK 40" to "KwK 40 L/48" (long gun) to match the Ausf H.
+- **Control Integrity:** Replace "TURRET OVER-ROTATION" (loss of control) with visual/audio stress cues.
+- **Pity/Grace Systems:** Define "Last Stand" behaviors for zero fuel/ammo to prevent hard softlocks.
+- **Onboarding:** Define a "Zone 1 Tutorial" flow to introduce systems sequentially.
+- **Technical Spec:** Explicitly lock the engine to Phaser 3 (2D Canvas/WebGL) to eliminate any lingering Babylon.js ambiguity.
+
+---
+
+## 3. RECOMMENDED FIRST VERTICAL SLICE (The " Steel & Snow" Slice)
+
+To prove the core loop and mitigate the highest risks, the first slice must focus on **The Feeling of the Machine**.
+
+**Include:**
+- **Core Physics:** Hull/Turret decoupling with the inertia model.
+- **The "Button" Loop:** Implementation of the periscope mask and the hatch toggle (with a *suppression* mechanic instead of instant death).
+- **Single Pattern Combat:** One "Infantry Wall" pattern with the 1.5s bugle telegraph.
+- **Basic Resource Loop:** Fuel consumption and one ammo type (AP).
+- **Save System:** Basic IndexedDB implementation for a single slot.
+
+**Defer:**
+- **Parasite Run:** (On-foot mechanics are too disruptive to the core tank loop).
+- **Crew Morale:** (Needs more iteration on the "buff vs debuff" model).
+- **Side-View Cutscenes:** (Purely narrative; polish the combat first).
+- **Complex Radio Tuning:** (Implement simple frequency-based triggers first).

reviews/tester-analysis.md

@@ -0,0 +1,426 @@
+# Iron Requiem — Tester Analysis: Testability, Balance & Edge Cases
+
+**Reviewer:** Hermes (tester profile)
+**Date:** 2026-05-23
+**GDD Version:** IRON_REQUIEM_GDD.md + PHASER_IMPLEMENTATION_PLAN.md
+
+---
+
+## 1. TESTABILITY
+
+### 1.1 Tank-as-Character (Hull/Turret Physics)
+
+**Can we automate?** Partially. The physics model is the most testable core mechanic.
+
+- **Unit-testable:** The linear acceleration formula (`accel = (input * power) - (velocity * friction)`) is purely mathematical. Extract into a pure function, test with known inputs across the full input range, zero input, negative input (should it clamp? GDD doesn't say), and floating-point edge cases.
+- **Unit-testable:** Turret rotation cap (15°/sec) is testable as a pure function given `currentAngle`, `targetAngle`, `deltaTime`.
+- **Integration-testable:** The hull/turret decoupling can be tested by moving the hull in a known direction, rotating the turret to a known angle, and asserting the turret's world-space angle is `hullAngle + turretOffset`.
+- **Visual/Manual only:** The "25-ton feel" — does it actually *feel* like a tank? Subjective, requires playtesting. The drift-on-ice behavior is hard to automate.
+
+### 1.2 Bullet Hell Patterns
+
+- **Unit-testable:** Pattern generation. Each pattern should produce predictable projectile arrays given fixed inputs. The `PatternManager` from the implementation plan makes this testable if it exposes a `generatePattern(type, position, time)` method.
+- **Unit-testable:** Audio telegraphs — test that trigger 1.5s *before* projectile spawn, not after. Time-based logic is testable with mocked clocks.
+- **Unit-testable:** Artillery ring 2s delay → radial explosion. Testable as a timed state machine.
+- **Integration-testable:** Projectile pooling — verify no GC spikes by monitoring pool size under sustained fire. Also test pool exhaustion: what happens when all projectiles are in-flight and a new pattern spawns?
+- **Visual/Manual only:** Are patterns actually *fair*? Can a skilled player reasonably dodge? Needs human judgment.
+
+### 1.3 Resource Management (Fuel, Ammo)
+
+- **Unit-testable:** Fuel consumption rate (constant? varies with speed/combat?). GDD doesn't specify the rate — needs a concrete formula first.
+- **Unit-testable:** Ammo selection (keys 1-4), ammo count tracking, zero-ammo edge case.
+- **Unit-testable:** Low-fuel penalties (reduced acceleration, turret speed). Test that penalty multipliers apply correctly.
+- **Integration-testable:** Scavenging flow — enter wreck area, trigger scavenge, verify resources gained, verify vulnerability window.
+
+### 1.4 Heat & Freeze-Thaw
+
+- **Unit-testable:** Heat accumulation at various speeds. Test the curve — linear? exponential? The GDD says "high speeds and prolonged combat increase heat" but doesn't quantify. Needs a formula.
+- **Unit-testable:** Overheat penalty application, thermal signature increase.
+- **Unit-testable:** Freeze-stall probability as a function of ambient temperature and current heat.
+- **Visual/Manual only:** Does the thermal signature actually change enemy tracking behavior in a noticeable way?
+
+### 1.5 Crew Morale
+
+- **Unclear mechanics:** The GDD lists stress factors and effects but provides NO numbers. What is the morale scale? 0-100? How much stress per hit? How much per crew death? How much recovery from safety? This is **untestable** as written.
+- **Unit-testable (once quantified):** Stress accumulation, panic error probability, reload speed debuff, command response delay.
+- **Integration-testable:** Morale crash from commander death while unbuttoned.
+- **Visual/Manual only:** Does morale *feel* meaningful or is it invisible noise? Critical to validate with players.
+
+### 1.6 Fog of War & Radio
+
+- **Integration-testable:** Radio tuning mechanic — frequency input → success/failure → plot fragment or enemy spawn. This is a straightforward state machine.
+- **Integration-testable:** Enemy signal interception providing early warning — test that pattern telegraph appears earlier when interception succeeds.
+- **Unit-testable:** Ghost transmission content selection, frequency assignment logic.
+- **Visual/Manual only:** Does the radio audio/visual loop feel atmospheric or annoying?
+
+### 1.7 Showcase Mechanics
+
+- **Unbuttoning:** Fully testable. Toggle state, vision cone change, periscope mask slide, CommanderHatch hitbox activation. All integration-testable.
+- **Side-View Cutscenes:** Visual/manual only — rendered content, but logic (trigger conditions, scene sequencing) is testable.
+- **The Iron Ledger:** Logic testable. Writing → morale stabilization → backstory unlock. Integration-testable as a state machine.
+- **Parasite Run:** Integration-testable. Stationary + vulnerable → resource gain. Timer and vulnerability window are straightforward.
+
+---
+
+## 2. BALANCE CONCERNS
+
+### 2.1 Unbuttoning Risk/Reward
+
+**Analysis:** The GDD describes "wider vision" vs. "instant commander death." This is an extreme binary — it's not a risk/reward tradeoff, it's Russian roulette.
+
+**Problems:**
+- "Any single projectile hit = Game Over" while unbuttoned is extremely punishing. In a bullet hell game with dense patterns, this makes unbuttoning effectively unusable in combat.
+- The vision benefit is vague: "wider vision" and "enemy detection is earlier." How much wider? How much earlier? If it's marginal, players will never unbutton. If it's huge, they'll feel forced into suicide runs.
+- There's no intermediate state — no partial exposure, no chance to duck. It's binary.
+
+**Recommendation:**
+- Consider a "suppression" mechanic instead of instant death. Being hit while unbuttoned could force the hatch closed, apply a morale penalty, and put the commander on a cooldown before unbuttoning again. Death should occur only on a direct "sniper" hit, not any projectile grazing the hatch area.
+- Make the vision difference mechanically measurable: e.g., buttoned = 180° forward arc at 200px; unbuttoned = 270° at 350px. Players should feel the difference immediately.
+- Add audio cues for "incoming sniper fire detected" before a potential death hit, giving skilled players a chance to button up in time.
+
+### 2.2 Ammo Type Differentiation
+
+**Analysis:** Four types is a good number, but differentiation risk exists.
+
+**Problems:**
+- AP vs. HE vs. Canister could blur. If AP does 100 damage to one target at long range and HE does 75 damage to 3 targets, players will solve for DPS and ignore the weaker option. The question is whether the enemy compositions force meaningful choices.
+- Smoke is either essential (if enemies have accurate tracking) or useless (if you can always dodge). Its value depends entirely on enemy accuracy tuning.
+- Canister is described as "close-quarters defense" — but in a bullet hell where the goal is to keep enemies at range, how often does the player want to be that close?
+
+**Recommendation:**
+- Make enemies *require* specific counters. Tanks that are immune to HE splash (armored skirts). Infantry clusters that are impractical to kill one at a time with AP. Fast flankers that close distance and force canister use.
+- Smoke needs a secondary function — maybe it also reduces the tank's thermal signature briefly, or resets enemy targeting lock-on.
+- Track ammo scarcity hard. If all types are abundant, players spam the best one. Scarcity creates forced variety.
+
+### 2.3 Heat System
+
+**Analysis:** The heat/freeze-thaw cycle has potential but the GDD is unclear on the decision space.
+
+**Problems:**
+- "Overheating causes speed penalties and increases thermal signature" — is this a temporary penalty or does it stack? Can you overheat to the point of engine failure?
+- "Engine can stall in extreme cold" — is this a random event or deterministic? Random = frustrating. Deterministic (heat below threshold + ambient temp below threshold = stall) = strategic.
+- The "balance heat generation with thermal detection" tradeoff works only if thermal detection has real consequences. If enemies that track heat are rare, overheating has no downside. If they're common, the freeze-thaw penalty dominates.
+
+**Recommendation:**
+- Model heat as a sliding scale with clear zones: Cold (stall risk, slower reload) → Normal → Warm (optimal) → Hot (speed penalty, thermal visibility) → Critical (engine damage-over-time).
+- Make the freeze-thaw stall deterministic: if heat < X and outside air temp < Y for Z seconds, engine stalls. Give the player a "engine warm-up" action (hold a key, spend fuel) to recover.
+- Show heat on a visual gauge with color zones so the player can make informed decisions without counting seconds.
+
+### 2.4 Crew Morale
+
+**Analysis:** This is the highest-risk mechanic in the GDD. It sounds atmospheric but has "annoying secondary system" written all over it.
+
+**Problems:**
+- "Slower reload speeds" and "delayed command responsiveness" are the worst kind of penalty — they make the game feel unresponsive. Players will attribute sluggishness to bugs, not to a morale system.
+- "Turret over-rotation" (panic errors) takes control away from the player. In a precision dodging game, losing control is not challenging — it's just frustrating.
+- Recovery through "brief periods of safety" is ill-defined. How brief? What constitutes safety?
+- The Iron Ledger as recovery tool creates a strange loop: you only access it during downtime, but in bullet hell downtime is rare. Players might feel forced to stop playing to manage morale.
+
+**Recommendation:**
+- **Make morale a buff system, not a debuff system.** Low morale = baseline. Normal morale = faster reload, warning shouts from crew ("enemy on your left!"). High morale = temporary abilities (auto-aim assist, damage resistance). This way morale feels rewarding to maintain, not punishing to ignore.
+- Make morale effects *visible and diegetic*. Crew barks change tone. Reticle wobbles visibly. The player always knows WHY the tank feels sluggish.
+- Quantify everything: stress per hit = 5 points. Max morale = 100. Reload buff at >70. Panic risk starts below 30. Recovery = 2 points/second of no damage taken.
+- Consider removing "turret over-rotation" entirely. It's more frustrating than fun. Replace with visual noise — screen edge vignette, muffled audio — that doesn't steal control.
+
+### 2.5 Scavenging Flow
+
+**Analysis:** The GDD mentions scavenging but doesn't describe the flow.
+
+**Problems:**
+- "During brief lulls" — who defines the lull? If combat is continuous bullet hell, when does scavenging happen?
+- "Exit the tank (high risk)" — does the player character actually leave the tank? What does that look like? Is the tank vulnerable during this? Is there a minigame?
+- "Use crew members" — is this a different mechanic from exiting? Does it cost something?
+- Scavenging could easily become a chore that players either ignore (and starve) or optimize to the point of tedium.
+
+**Recommendation:**
+- Design scavenging as a post-combat-room reward, not a mid-combat action. After clearing a wave, debris fields become interactive zones.
+- Make it fast: a 3-second hold-E action with a clear resource display. No minigame unless it's genuinely fun.
+- Use crew members by pressing a key — the crew member's portrait greys out for 10 seconds while they scavenge. Risk: if hit during that time, crew member is injured or killed.
+- Guarantee minimum yield so players never feel cheated.
+
+---
+
+## 3. EDGE CASES
+
+### 3.1 Fuel Zero Mid-Combat
+
+**Current GDD:** No answer. "Low fuel reduces acceleration and turret rotation speed" but zero fuel is not addressed.
+
+**What happens?** The tank physically cannot move or rotate its turret. This is effectively a hard-lock death in bullet hell. Is there a grace period? Emergency reserve? Can the commander use a sidearm?
+
+**Recommendation:** 
+- Fuel zero should NOT be instant death. Enter a "last stand" mode: turret rotation at 50% of normal (hand-cranked), hull immobile, crew barks reflect desperation. The player can still fight but can't dodge — a dramatic moment, not a softlock.
+- Consider an emergency fuel reserve consumable (1 use per run).
+- Add a desperation mechanic: "Prime the engine" — spend health to generate a tiny amount of fuel for one last-ditch maneuver.
+
+### 3.2 All Crew Except Commander Die
+
+**Current GDD:** No answer.
+
+**What happens?** Can one person operate a Panzer IV? Historically no — the Panzer IV required a crew of 5 (commander, gunner, loader, driver, radio operator). But this is a game.
+
+**Recommendation:**
+- Each crew death applies a stacking penalty: driver dead = no hull movement, gunner dead = no turret rotation, loader dead = no shooting, radio operator dead = no radio/early warning.
+- If commander dies while buttoned (should be rare — unbuttoned death is instant game over), the game could show a bleak cutscene of the remaining crew trying to retreat.
+- Consider a "crew re-assignment" mechanic: surviving crew can fill an empty role at reduced effectiveness (e.g., 50% reload speed if commander takes over loader duties).
+
+### 3.3 Zero Ammo (All Types)
+
+**Current GDD:** No answer.
+
+**What happens?** The tank is a moving (or stationary) target that can't shoot.
+
+**Recommendation:**
+- Tank becomes a "battering ram" — the player can still move and ram enemy infantry, dealing low damage. This is thematic (a desperate last stand) and gives the player agency.
+- Crew members could fire personal weapons (pistols) from the hatch — minimal damage, infinite ammo, but requires unbuttoning.
+- The game should NEVER leave the player in this state without warning. Flash warnings at <10 rounds total, at <5, and at 0 with a clear "FIND AMMO" prompt.
+
+### 3.4 Scavenging Softlock
+
+**Current GDD:** No answer.
+
+**Can you softlock?** Yes, in these scenarios:
+- You scavenge all available wrecks in an area but didn't get enough fuel to reach the next zone. No enemies = no new wrecks, no wrecks = no fuel, no fuel = can't progress. This is a hard softlock.
+- You use all ammo and there are no more wrecks to scavenge. Can't fight, can't progress.
+
+**Recommendation:**
+- Design zones so that the exit is always reachable with minimum fuel (the amount you start each zone with).
+- Spawn guaranteed minimum scavenge opportunities before major encounters.
+- If fuel is truly critical, consider passive fuel regeneration at a very slow rate (the crew siphons from the tank's own systems) or a "push the tank" mechanic that lets you slowly crawl without fuel.
+- Add a "Return to Base" option (not mentioned in GDD) that costs nothing but resets zone progress.
+
+### 3.5 Overlapping Bullet Hell Patterns
+
+**Current GDD:** No answer.
+
+**Is dodge possible?** Depends entirely on the pattern design.
+
+**Problems:**
+- If two "Artillery Ring" patterns target the same area with offset timing, the safe zones may not overlap — guaranteed damage.
+- If "Infantry Wall" horizontal bursts overlap with "Tank Destroyer Beam" verticals, the grid creates pixel-perfect-only gaps that feel unfair on a sluggish tank.
+- The 2-second telegraph warning is good for single patterns but insufficient when multiple patterns are in flight.
+
+**Recommendation:**
+- Implement a pattern governor: no more than N patterns active simultaneously based on difficulty. Zone 1: max 2 active patterns. Zone 2: max 3. Zone 3: max 4.
+- When multiple patterns would overlap, offset their timing by at least 0.5s so the player has a beat to process each.
+- Every pattern should have a provable safe zone — if a grid pattern creates a 4x4 tile gap, the tank's hitbox must be smaller than that gap (including momentum drift).
+- Add a difficulty test script that procedurally validates pattern overlaps: for every pattern combination, verify at least one path exists from the tank's position to a safe zone given max movement speed.
+
+### 3.6 Periscope Mask Unfair Deaths
+
+**Current GDD:** The mask is a "full-screen Graphics layer with a rectangular hole."
+
+**Problems:**
+- Enemies outside the visible rectangle can fire projectiles that enter the visible area with zero warning. This is the definition of unfair.
+- In bullet hell, screen-edge spawning is normal — but when the player's vision is artificially restricted, off-screen threats need special handling.
+- The implementation plan says the mask slides off-screen when unbuttoned, but doesn't describe how enemies handle the mask while it's active.
+
+**Recommendation:**
+- Enemies outside the periscope view should NOT fire — or should have dramatically reduced accuracy (suppressing fire that fills the area with slow, telegraphed projectiles).
+- Add audio cues specifically for off-screen threats: crew barks that indicate direction ("Contact! 4 o'clock!").
+- Consider a "radar ping" mechanic — a periodic sweep that briefly shows all enemy positions as dots on a minimap. Gives the player situational awareness without removing the claustrophobia.
+- Always show projectile telegraphs (Artillery Ring markers, beam charge-up glows) even when the firing enemy is off-screen.
+
+---
+
+## 4. DIFFICULTY SCALING
+
+### 4.1 Zone Progression
+
+**Zone 1 (Frozen Tundra):** Infantry + light armor. Sparse cover. Deep snow slows movement.
+**Zone 2 (Soviet Industrial):** Type 59/62 tanks. Narrow corridors.  
+**Zone 3 (Captured City):** Helicopter gunships, bosses.
+
+**Problems:**
+- The jump from Zone 1 to Zone 2 seems like the biggest difficulty spike — from infantry to enemy tanks that use "similar tactics to the player but in overwhelming numbers." If the player is still learning resource management in Zone 1, Zone 2's multi-tank encounters could be a wall.
+- Zone 3 adds helicopters (verticality) which is a new axis of threat. The GDD doesn't explain how the player counters aerial enemies. Can the turret elevate? Is there an AA ammo type?
+- "Narrow corridors" in Zone 2 + "tank that drifts" = potential frustration. Tight spaces reward precise movement, but the tank is deliberately sluggish.
+
+**Recommendation:**
+- Add a mid-zone difficulty checkpoint in each zone — a "safe room" (abandoned bunker, destroyed factory floor) where the crew can rest, morale recovers, and auto-save triggers.
+- Zone 2 should introduce enemy tanks one at a time before scaling to 2-3 simultaneously.
+- Helicopters need a dedicated counter. Consider: "The tank's AA machine gun" (limited ammo, medium range, only usable when unbuttoned). Or make helicopter rockets destructible with well-placed shots.
+- In narrow corridors, reduce drift (the tank has traction on concrete/metal floors vs. ice).
+
+### 4.2 Upgrade Power Curve
+
+**Upgrades:** Armor Plating, Engine Tuning, Optics, Crew Training.
+
+**Problems:**
+- The GDD lists upgrades but doesn't describe how they're acquired (permanent? between zones? currency?). Without acquisition mechanics, the power curve is impossible to evaluate.
+- "Crew Training: Permanent buffs to reload speed and panic resistance" — if this is permanent, it undermines the morale system. A maxed-out crew never panics, removing the mechanic entirely.
+- If upgrades are zone-gated (you can't get Engine Tuning until Zone 2), players who struggled in Zone 1 might not reach them.
+
+**Recommendation:**
+- Define an upgrade currency system. "Salvage Points" earned from surviving encounters, bonuses for performance (no-damage boss kills).
+- Make upgrades chooseable, not linear. Player picks one of two upgrades at each zone transition. This creates replay value.
+- Crew Training should have a cap — e.g., max 30% reduction in panic chance. Never 0%.
+- Add "side-grade" options: e.g., "Thicker armor (+30% HP, -10% speed)" vs. "Speed tuning (+20% speed, -15% HP)."
+
+---
+
+## 5. CLIENT-SIDE SAVE — FAILURE MODES
+
+The GDD states "all data lives on the client (localStorage/IndexedDB)."
+
+### 5.1 localStorage vs. IndexedDB
+
+**Problem:** The GDD doesn't specify which. They have very different failure characteristics.
+
+**localStorage:**
+- 5-10MB limit (browser-dependent).
+- Synchronous API — can block the main thread during save.
+- String-only storage — requires JSON serialization for all data.
+- Cleared when browser clears "site data."
+- Not available in private/incognito mode (technically available but cleared on window close).
+
+**IndexedDB:**
+- Much larger quota (typically 50%+ of disk space).
+- Async API — non-blocking saves.
+- Structured data — no serialization needed.
+- Same "site data" clearing risk, same private browsing risk.
+
+**Recommendation:** Use IndexedDB. A full save state (position, resources, crew status, zone, upgrades, story flags, settings) is likely <1MB. But specify the schema upfront:
+
+```
+saveStore = {
+  version: 1,
+  slot: "slot1" | "slot2" | "slot3",
+  timestamp: ISO-8601,
+  zone: string,
+  checkpoints: [{zone, subzone, resources, crew: [...]}],
+  settings: {volume, keybinds, ...},
+  stats: {playtime, deaths, ...},
+}
+```
+
+### 5.2 Failure Mode Catalog
+
+| Failure Mode | Impact | Mitigation |
+|---|---|---|
+| Browser clears site data | Complete loss of all progress | Offer export/import as JSON file. Display a warning on first launch. |
+| Private/incognito browsing | Save exists only in current session; lost on close | Detect private mode (try-catch on localStorage write) and warn the player at the main menu. |
+| Storage quota exceeded | Save fails silently | Catch quota errors. Alert the player. Offer to delete old saves. |
+| Save corruption (partial write) | Could softlock on load | Write to a temp key first, then atomically rename. Store a checksum. Validate on load. |
+| Cross-device | No sync | Explicitly state "saves are local only" in the main menu. Consider offering cloud save as a stretch goal. |
+| Browser crash during save | Lost progress since last save | Auto-save at every checkpoint (zone transition, boss defeated). Not just manual save. |
+| JSON serialization error | Save fails | Wrap serialization in try-catch. If it fails, fall back to previous valid save. |
+| Multiple tabs open | Two tabs auto-saving different states, overwriting each other | Use a session-scoped lock token in sessionStorage. Only the "active" tab saves. |
+
+### 5.3 Unanswered Questions
+
+- How many save slots? One? Three? (Recommendation: 3 slots — different runs, different endings.)
+- Is there a manual save or only auto-save? (Recommendation: both.)
+- Can the player delete saves? (Recommendation: yes, with confirmation.)
+- What happens on the very first boot — is there a "New Game" flow or does it drop into Zone 1 immediately?
+
+---
+
+## 6. MISSING SYSTEMS
+
+### 6.1 Tutorial (CRITICAL)
+
+The GDD has NO mention of a tutorial.
+
+**Why this matters:** Iron Requiem has 6+ simultaneous systems: hull movement, turret rotation, ammo types, heat, morale, unbuttoning, radio, scavenging. A player jumping in blind will be overwhelmed and quit.
+
+**Recommendation:** Zone 1 should function as a "tutorial zone" — introduce one mechanic at a time:
+1. Start buttoned, taught hull movement.
+2. Introduce turret rotation and simple enemies (2-3 static infantry).
+3. Introduce unbuttoning (and the risk) against a single enemy at range.
+4. Introduce ammo types as they're acquired.
+5. Heat/morale/radio introduced with on-screen prompts as they become relevant.
+
+Don't dump all systems in the first 5 minutes.
+
+### 6.2 Difficulty Modes (HIGH)
+
+No difficulty modes mentioned.
+
+**Recommendation:** Not everyone wants a punishing bullet hell. Offer:
+- **Endurance Mode (Easy):** Slower heat buildup, more forgiving morale, wider periscope view, 1 extra crew "life," enemies fire fewer projectiles.
+- **Requiem Mode (Normal):** As described in GDD.
+- **Iron Mode (Hard):** Instant death unbuttoned (as GDD currently describes), no auto-save, permadeath (one save, deleted on death).
+
+### 6.3 Accessibility (MEDIUM)
+
+No accessibility features mentioned.
+
+**Recommendation:**
+- Color blindness options: pattern outlines, distinct enemy silhouettes (not just color-coded), HUD symbols in addition to needle gauges.
+- Controller support: the GDD mentions keyboard (E for unbutton, 1-4 for ammo) but not controller. Bullet hell games are popular on twin-stick controllers.
+- Screen shake toggle: "screen-shake on shell impact" can trigger motion sickness.
+- Flashing light warnings: muzzle flashes could be problematic for photosensitive players.
+- Difficulty of pattern opacity/frequency for visually impaired players.
+
+### 6.4 Pause Menu (HIGH)
+
+No pause menu mentioned.
+
+**What needs to be there:** Resume, Save, Load, Settings (audio, controls, video scaling, accessibility), Quit to Menu.
+
+**Edge case:** What happens if the browser tab loses focus during combat? Auto-pause? Or keep running? In a bullet hell, auto-pause on blur is standard and expected.
+
+### 6.5 Key Rebinding (MEDIUM)
+
+The GDD specifies E for unbutton, 1-4 for ammo, but doesn't mention rebinding.
+
+**Why this matters:** WASD for movement + arrow keys for turret? Or mouse for turret? The GDD never specifies the control scheme. Players have strong preferences. Locking controls without rebinding guarantees some players will be unhappy.
+
+### 6.6 Controller Support (MEDIUM)
+
+Bullet hell games typically play well on twin-stick controllers (left stick = move, right stick = aim/rotate turret). Not offering controller support limits the audience.
+
+### 6.7 Sound Settings (LOW)
+
+Volume sliders for: Master, Music, SFX, Radio, Voice. The audio design is extensive but there's no mention of individual volume control.
+
+### 6.8 Death/Game Over Screen (MEDIUM)
+
+No mention of what happens on death. Reload last checkpoint? Restart zone? Show a death recap? The bleak endings suggest perma-death runs, but the upgrade system suggests persistence. These contradict each other — needs resolution.
+
+### 6.9 Loading Screen / Boot Flow (LOW)
+
+Phaser game with pixel art assets, audio files — loading takes time. A blank screen is unacceptable. Need a loading bar, maybe atmospheric art/text.
+
+### 6.10 Analytics / Feedback Collection (LOW — Nice to Have)
+
+No mention of how the developer will know what's broken. Consider opt-in telemetry: crash reports, death locations, most-used ammo types, average zone completion time. Invaluable for balancing.
+
+---
+
+## 7. SUMMARY OF FINDINGS
+
+### Critical Issues (Block Release)
+1. **Commander death edge cases undefined** — zero fuel, zero ammo, all crew dead scenarios have no defined behavior.
+2. **No save failure handling** — localStorage/IndexedDB save corruption, quota exhaustion, and private browsing all lead to silent data loss with no mitigation planned.
+3. **No tutorial** — 6+ simultaneous systems with no onboarding guarantees player frustration and negative reviews.
+4. **Overlapping bullet pattern fairness** — no governor or validation; multiple patterns can create undodgeable situations.
+
+### High Severity
+5. **Morale system as described is anti-fun** — taking control away from the player in a precision game. Consider reframing as a buff system.
+6. **Unbuttoning binary death** — instant death from any projectile is too punishing. Needs gradation.
+7. **Periscope mask unfair deaths** — off-screen enemies firing into restricted view creates guaranteed unfair hits.
+8. **Difficulty curve spike at Zone 2** — from infantry to multi-tank encounters with no ramp.
+
+### Medium Severity
+9. **Heat system lacks quantification** — no numbers for accumulation rate, penalty thresholds, or stall conditions.
+10. **Scavenging flow undefined** — mid-combat vs. post-combat, exit-tank mechanic, crew-member risk all unspecified.
+11. **No pause menu, no key rebinding, no controller support** — basic quality-of-life features missing.
+12. **No difficulty modes** — alienates casual and hardcore audiences simultaneously.
+
+### Low Severity
+13. **No death screen flow** — unclear whether game is checkpoint-based or permadeath.
+14. **No sound settings** — volume control, toggles missing.
+15. **No analytics** — developer blind to balance issues post-launch.
+16. **Upgrade acquisition undefined** — currency, choice model, zone gating all TBD.
+
+---
+
+## 8. RECOMMENDED ACTIONS
+
+1. **Before ANY code:** Define all numeric values. Every mechanic needs a spreadsheet with min/max/rate/threshold values. The current GDD is a vision document, not a spec.
+2. **Write a "Player Experience Walkthrough"** — a 10-minute play-by-play of exactly what the player sees, hears, and does from boot to first death. This exposes gaps faster than any system-level analysis.
+3. **Build the save system FIRST** and test it to destruction — clear browser data, fill storage, corrupt the save. The save system is the foundation; if it fails, everything built on it is lost.
+4. **Prototype the unbuttoning mechanic in isolation** — get 5 people to play a 30-second demo of buttoned/unbuttoned combat and tell you whether it's fun. Tune from there.
+5. **Add pattern combination testing** before committing to patterns — generate every pair of patterns and verify a dodgeable path exists.