Update docs

3 files changed, 145 insertions, 58 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index e94eeb5..a2453f7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -153,12 +153,17 @@ See `requirements/milestones.org` for the live checklist. Roughly:
 
 - **M0–M3 done:** scaffolding, rendering/physics, building system, structural
   destruction (stress/collapse/fire).
-- **M4 in progress:** cannon (ballistic) + laser (beam/fire) with the Forts
-  select-a-weapon-and-aim-in-its-arc UX. Missing: mortar, flak/point-defence,
-  machinegun/sniper (hitscan), guided missiles, EMP, per-shot recoil.
-- **M5 in progress:** reactors + win/loss + restart (R), real resource economy
+- **M4 mostly done:** per-strut HP, cannon (ballistic) + laser (beam/fire) with
+  the Forts select-a-weapon-and-aim-in-its-arc UX, direct-vs-splash delivery,
+  fire + spread. Missing: mortar, flak/point-defence, machinegun/sniper
+  (hitscan), guided missiles, EMP, per-shot recoil, metal-per-shot.
+- **M5 mostly done:** reactors + win/loss + restart (R), real resource economy
   (mines on deposits, turbines by height, storage caps, firing costs energy),
-  device framework + placement.
+  device framework + placement. Two gaps: fire does **not** damage devices, and
+  devices are not mounted on the strut graph, so the "cut its supports and the
+  reactor falls" victory path does not exist.
+- **M6 partial:** enemy fort (`data/mods/enemy-fort/`) + deposits both sides;
+  terrain is still a flat half-plane and there is no sky backdrop.
 - **Not started / later:** repair & recycle (M7), armour/door/shield materials,
   tech tree + upgrades, commanders, real map/terrain, AI, netcode.
 
@@ -177,6 +182,27 @@ consult it before deciding what to build; don't guess from vibes.
 - **Build before you claim done** (compile in the container) and validate any Lua
   you touched with a standalone `lua` run. Be honest about what you couldn't
   verify (the GUI can't run headless here).
+- **Keep the status docs in sync — same commit as the change.** When you land,
+  extend or remove a feature, update all three in the commit that changes the
+  behaviour, not later:
+  1. `requirements/milestones.org` — tick the boxes you actually delivered, and
+     fix any item whose *description* no longer matches what was built.
+  2. `research/gameplay-gaps.org` — the "What we HAVE" baseline, the affected
+     `**` section, the roadmap table, and the "smallest next steps" queue.
+  3. `CLAUDE.md` §6 — the milestone summary, plus §2/§3/§4 if the architecture,
+     the physics model or the data schema moved.
+
+  Rules that make this worth doing:
+  - **Verify against the code, not memory.** Grep for the thing before ticking
+    it. These docs drove a real prioritisation error once: every M4/M5 box sat
+    unchecked and the gaps doc still claimed "we have ZERO devices" long after
+    reactors, mines, turbines, the economy and win/loss had shipped.
+  - **Record the gap, not just the win.** Half-done is `[~]` plus a one-line
+    note on exactly what is missing (e.g. M5's reactor exists, but nothing
+    mounts it on the strut graph, so there is no collapse-victory path). A
+    `[X]` that hides a caveat is worse than an unticked box.
+  - §6 tells everyone to consult `gameplay-gaps.org` before choosing work,
+    not to guess from vibes. That holds only while the doc is true.
 - **Don't commit game assets** (§5), `builddir/`, or `imgui.ini`.
 - Match surrounding code style; keep the engine/game split; prefer data (Lua)
   over hard-coded constants.
diff --git a/requirements/milestones.org b/requirements/milestones.org
index 9aa5a5a..3aeb4a9 100644
--- a/requirements/milestones.org
+++ b/requirements/milestones.org
@@ -25,6 +25,11 @@ Notes:
 - Pivoted from bgfx to SDL3 renderer for M0. bgfx init fails silently on this
   system (EGL-only Linux backend, GLX removed upstream). SDL3 OpenGL renderer
   works perfectly. Revisit bgfx later in the project.
+- Follow-up: no source file =#include=s bgfx, SoLoud, ENet or EnTT, so
+  =meson.build= now treats them as OPTIONAL (linked only if a source build has
+  put them in /usr/local) and falls back to system packages otherwise. That is
+  what makes a native (non-container) build possible -- see README. Promote each
+  back to a required dependency when it is actually wired up.
 - Header collision: -I/usr/local/include/bx caused sys/types.h to find
   bx/endian.h instead of glibc endian.h. Fixed by using single
   -I/usr/local/include with qualified <bx/...> includes.
@@ -104,9 +109,9 @@ graph, and form structures.
 - [X] Build-grace radial timer on un-triangulated struts (temporary rigid hold)
 - [X] Building costs: placing a piece deducts metal + energy
 - [X] Simple HUD: resource bars + current-material indicator
-- [ ] Resource system: Metal (mines on deposits) + Energy (wind turbines)
-      -- DEFERRED to M5 (needs the reactor / game-loop context). For now metal
-      and energy are fixed starting pools that only deplete.
+- [X] Resource system: Metal (mines on deposits) + Energy (wind turbines)
+      -- was deferred to M5 and DELIVERED there (generation, storage caps,
+      build + firing costs).
 
 * M3: Structural Destruction  [MOSTLY DONE]
   (swapped with weapons -- destruction goes hand-in-hand with M2 building)
@@ -126,47 +131,64 @@ This is the purely-structural half of Forts destruction (no weapons yet).
 - [X] Disconnection -> fall -> destroy: a chunk that loses its path to a
       foundation simply falls under gravity and dies on the ground
 - [X] Materials: wood, background bracing, ropes (tension-only)
-- [ ] Per-strut HP pool (separate from stress) -- belongs with M4 weapon damage
-- [ ] Fire (damage-over-time, strut-to-strut spread) -- M4
+- [X] Per-strut HP pool (separate from stress) -- delivered in M4
+- [X] Fire (damage-over-time, strut-to-strut spread) -- delivered in M4
 
-* M4: Weapons & Damage
+* M4: Weapons & Damage  [MOSTLY DONE]
   (swapped with destruction)
 
 Goal: Place and fire all three weapons. They feed the M3 graph via two damage
 models (per-strut HP and radius splash) plus fire.
 
-- [ ] Per-strut HP pool, depleted by weapon hits (independent of stress)
-- [ ] Cannon: click-drag angle/power, Box2D ballistic projectile, splash
-      damage with linear radius falloff, knockback impulse, ~25% fire chance
-- [ ] Laser: click-drag beam; stops at wood, passes bg-brace/ropes; 100% ignite
+- [X] Per-strut HP pool, depleted by weapon hits (independent of stress)
+- [X] Cannon: ballistic projectile, splash damage with linear radius falloff,
+      knockback impulse, ~25% fire chance, per-shot energy cost.
+      NOTE: the UX is Forts' select-a-weapon-and-aim-within-its-arc, not the
+      click-drag angle/power originally sketched here. The projectile uses our
+      own integrator; Box2D is still idle.
+- [X] Laser: beam; stops at wood, passes bg-brace/ropes; 100% ignite
 - [ ] Flak: auto-target incoming shells within an arc; hitscan/fast projectile
-- [ ] Direct vs splash delivery: foreground struts block direct fire;
+- [X] Direct vs splash delivery: foreground struts block direct fire;
       background bracing is passed through by direct hits but takes splash + fire
-- [ ] Fire system: ignition flag, damage-over-time, spread along the graph,
+- [X] Fire system: ignition flag, damage-over-time, spread along the graph,
       burns background bracing faster (the counter to the bg-brace trick)
 
-* M5: Reactor, Resources & Game Loop
+Still missing from the vanilla roster / mechanics (see gameplay-gaps.org #5, #8):
+mortar, flak + point-defence, machinegun/sniper (hitscan), guided swarm
+missiles, EMP, and per-shot RECOIL on the firing structure (we apply knockback
+to targets only).
+
+* M5: Reactor, Resources & Game Loop  [MOSTLY DONE]
 
 Goal: There's a reactor to destroy, and a real economy to build it with.
 
-- [ ] Reactor entity -- large block, HP bar
-- [ ] Player reactor on left, dummy reactor on right
-- [ ] Reactor takes damage from direct hits, fire, falling/collision
-- [ ] Win condition: destroy reactor HP OR disconnect it from its foundation
-      (collapse) -- two distinct victory paths
-- [ ] Resource system (deferred from M2): mines on metal deposits, wind
-      turbines for energy, generation rates, "can't build when broke"
-- [ ] Win/lose condition + restart (R key)
+- [X] Reactor entity -- large block, HP bar (a device with =is_core=)
+- [X] Player reactor on left, enemy reactor on right (via the enemy-fort mod)
+- [~] Reactor takes damage from direct hits, fire, falling/collision
+      -- splash and beam damage hit devices; FIRE does not damage devices, and
+      devices are not attached to the strut graph, so they never fall.
+- [~] Win condition: destroy reactor HP OR disconnect it from its foundation
+      (collapse) -- only the HP path exists. The round ends when a team has no
+      surviving =is_core= device. The collapse path needs devices mounted on
+      the graph (see M6 / gameplay-gaps.org #3).
+- [X] Resource system (deferred from M2): mines on metal deposits, wind
+      turbines for energy, generation rates, storage caps, build/fire costs
+- [X] Win/lose condition + restart (R key)
 
-* M6: Dummy Fort & Map
+* M6: Dummy Fort & Map  [PARTIAL]
 
 Goal: The dummy fort on the right is a hand-crafted target. The map has metal
 deposits and a complete layout.
 
-- [ ] Dummy fort pre-built structure (reactor, wood walls, bg-brace, ropes)
-- [ ] Map layout: terrain with metal deposits on both sides
-- [ ] Player starting area: reactor + small starter shell + nearby deposits
-- [ ] Visual polish: distinct colors for materials, simple sky backdrop
+- [X] Dummy fort pre-built structure -- =data/mods/enemy-fort/= builds a
+      triangulated fort at x=25..29 with the enemy reactor inside. Wood only;
+      no bg-brace or ropes in it yet.
+- [~] Map layout: metal deposits on both sides exist (=data/map.lua=), but the
+      terrain is still a flat half-plane, not a real heightmap.
+- [~] Player starting area: player reactor + nearby deposits on the left; there
+      is no pre-built starter shell.
+- [~] Visual polish: materials are visually distinct and can load real Forts art
+      (see CLAUDE.md section 5); no sky backdrop is drawn yet.
 
 * M7: Polish & Controls
 
@@ -175,7 +197,10 @@ Goal: Everything feels good. Controls are responsive. Visuals are clear.
 - [ ] Repair tool: right-click damaged piece, pay resources to restore HP
 - [ ] Recycle: shift+click to remove piece, recover partial resources
 - [X] Camera feel: pan (arrows / middle-drag), scroll zoom (basic; edge-scroll TBD)
-- [ ] Visual feedback: damage states, fire glow
+- [~] Visual feedback: fire glow done (burning struts flicker orange); no
+      per-damage-state art yet. Forts ships damage-state textures
+      (=materials/wood_panel_damaged_1..3.tga=, =bracing-d1/d2=, =armor-d1/d2=)
+      that a =texture_forts=-style field could pick up.
 - [X] Build UX: ghost/extrusion previews, hover highlights, build-grace timers
 - [ ] Edge cases: zero resources enforcement, etc.
 
diff --git a/research/gameplay-gaps.org b/research/gameplay-gaps.org
index 4974ef6..c6d1b17 100644
--- a/research/gameplay-gaps.org
+++ b/research/gameplay-gaps.org
@@ -17,20 +17,38 @@ constants.lua) cross-checked against community docs:
 
 * What we HAVE (baseline)
 
+Re-verified against the code on <2026-07-18>. Keep this section honest: it is
+what the rest of the document is measured against.
+
 Building (wood / bg-brace / rope), mass-spring structural sim with stress +
 axial/angle breaking + cascading collapse, ground destroys debris, fire
-(DoT + spread), HP, two weapons (cannon = ballistic, laser = beam/ignite),
-a static enemy fort, Lua-data + mods, a dev UI. Resources are a placeholder
-(depleting pools, no generation).
+(DoT + spread), per-strut HP, two weapons (cannon = ballistic, laser =
+beam/ignite) with per-shot energy cost and firing arcs, a pre-built enemy fort
+(=data/mods/enemy-fort/=), Lua-data + mods, a dev UI.
+
+Since the first draft of this document we also have:
+- *Devices*: reactor (=is_core=), mine, wind turbine, battery -- placeable, with
+  HP, damaged by splash and beams.
+- *A real economy*: mines on metal deposits, turbines scaling with height,
+  storage caps, and metal/energy actually spent on building and firing.
+- *A game loop*: win/lose when a team loses its last =is_core= device, plus
+  restart on R.
+- *Bring-your-own Forts art*: =texture_forts= paths load real sprites from the
+  player's own install, falling back to the CC0 placeholders.
 
 * MISSING — grouped by system, each with the in-game reference
 
-** 1. The Reactor + win/loss  [CRITICAL — this is the actual game]
+** 1. The Reactor + win/loss  [MOSTLY DONE — M5]
 The core the whole game is about. =devices/reactor.lua=: HitPoints 100 (fragile),
 and it is ALSO a generator (EnergyProductionRate 100, MetalProductionRate 5).
 Win = destroy the enemy reactor by (a) direct damage, (b) fire/splash, or
-(c) cutting its supports so it falls. We have no reactor, no win/loss, no restart.
--> our M5.
+(c) cutting its supports so it falls.
+
+DONE: the reactor exists as an =is_core= device that also generates, takes
+splash and beam damage, and ends the round when a team has none left; R
+restarts. STILL MISSING: fire does not damage devices, and path (c) does not
+exist -- devices sit at fixed coordinates rather than being mounted on the strut
+graph, so cutting the supports under a reactor never drops it.
 
 ** 2. Real resource economy  [CRITICAL for the core loop]
 Two resources, generated by devices (all values from =devices/*.lua=):
@@ -43,9 +61,17 @@ Two resources, generated by devices (all values from =devices/*.lua=):
   Resources are capped, not infinite pools.
 - *Costs*: building pieces, weapons, devices, AND FIRING all cost metal/energy
   (cannon EnergyFireCost 2000, MetalFireCost 50). Repair costs too.
-We have placeholder pools only. -> deferred to our M5.
+DONE in M5: mines on deposits, turbines scaling with height, battery storage
+caps, and metal/energy spent on both building and firing. STILL MISSING: the
+upgraded variants (mine2, turbine2), the derrick and the metal store, and
+repair costs (see #7).
+
+** 3. Devices  [PARTIAL — we now have 4 of them]
+We have reactor, mine, turbine and battery, placeable with HP. Two structural
+gaps remain: devices are NOT mounted on the strut graph (they sit at fixed
+coordinates, so they cannot fall when their supports are cut -- see #1), and
+most of the catalogue below is still absent.
 
-** 3. Devices (whole category — we have ZERO)
 From =devices/device_list.lua=:
 - Resource: mine, mine2, turbine, turbine2, derrick, battery (energy store),
   store (metal store), reactor, minireactor.
@@ -89,7 +115,8 @@ Doors and shields are real tactical mechanics (open to shoot, shield vs lasers).
 
 ** 8. Weapon aiming/firing details we simplified
 - Cannon/weapons cost energy+metal PER SHOT (EnergyFireCost) — firing is
-  resource-limited, not just reload-limited.
+  resource-limited, not just reload-limited. DONE for energy (=energy_cost= per
+  weapon); the per-shot METAL cost is still missing.
 - Recoil/kickback pushes the fort (we apply knockback to targets only, not
   recoil to the firing structure — Forts Recoil 600000, KickbackMean 40).
 - Spotters: sniper reveals targets and guides swarm missiles.
@@ -115,29 +142,38 @@ replays (trivial with deterministic lockstep), sandbox. All post-v0.1.
 
 Mapping the above onto the (already-reordered) milestones:
 
-| Gap                                   | Milestone | Notes                          |
+| Gap                                   | Milestone | Status / notes                 |
 |---------------------------------------+-----------+--------------------------------|
-| Reactor + win/loss + restart          | M5        | the actual objective           |
-| Resource economy (mine/turbine/store) | M5        | deposits, generation, caps     |
-| Repair + Recycle                      | M7        | resource-cost actions          |
-| Devices framework (mount on struts)   | M5/M6     | reactor is the first device    |
+| Reactor + win/loss + restart          | M5        | DONE; no collapse-win path     |
+| Resource economy (mine/turbine/store) | M5        | DONE (no mine2/turbine2/store) |
+| Per-shot energy cost                  | M4        | DONE (metal-per-shot missing)  |
+| Devices framework (mount on struts)   | M5/M6     | not mounted on strut graph     |
 | Armour + Door + Shield materials      | M4/M7     | data-driven, small each        |
+| Firing recoil on the shooter          | M4        | small, faithful, not started   |
 | More weapons (mortar/flak/mg/missile) | M4        | point-defence + guided are new |
-| Per-shot energy cost + recoil         | M4        | small, faithful                |
+| Repair + Recycle                      | M7        | resource-cost actions          |
 | Tech tree + Upgrades                  | post-v0.1 | big; build-order strategy      |
 | Commanders/Factions                   | post-v0.1 | defines identity, large        |
-| Map deposits / terrain / foundations  | M6        | needs a real map format        |
+| Map deposits / terrain / foundations  | M6        | deposits done; terrain flat    |
 | AI / campaign / multiplayer           | post-v1   | out of scope                   |
 
 * Smallest high-value next steps (concrete)
 
-1. *Reactor as a device + win/loss* (M5 kickoff): a mountable block with HP that,
-   at 0 HP or when disconnected from a foundation, ends the round. Gives the game
-   an actual goal to shoot for. (We already destroy struts and detect
-   foundation-connectivity, so both victory paths are within reach.)
-2. *Real resources*: mines on deposits (+metal, -energy), turbines (+energy by
-   height), storage caps, and make building/firing actually spend them.
-3. *Armour + Door materials*: data-only additions to the Lua material table
-   (armour = high HP/stiff/heavy; door = toggles blocking) — cheap, high value.
-4. *Per-shot energy cost + firing recoil* on the cannon/laser — a few lines,
-   makes combat feel like Forts.
+Items 1 and 2 of the original list (reactor + win/loss, real resources) are DONE;
+what follows is the refreshed queue.
+
+1. *Armour material*: data-only addition to =data/materials.lua= (Forts armour is
+   HP 400, +25% stiffness, 2x mass). The material system already has every field
+   it needs, and =materials/armor.tga= is a TGA, so =texture_forts= picks up the
+   real sprite for free. Cheapest real gameplay depth available.
+2. *Firing recoil*: apply an impulse to the FIRING structure, not just the target
+   (Forts Recoil 600000, KickbackMean 40). The knockback machinery already
+   exists; this is a few lines and makes combat feel like Forts.
+3. *Mount devices on the strut graph*: attach devices to nodes so cutting the
+   supports drops them. Unlocks the second victory path in #1 and makes reactors
+   killable by collapse, which is a signature Forts moment.
+4. *Door material*: toggles =blocks_projectiles= so you can open to shoot and
+   close to tank. Needs a small mechanic, not just data.
+5. *Mortar or flak*: the next weapons. Flak brings a genuinely new mechanic
+   (point-defence intercepting incoming shells); mortar is a high-arc,
+   high-building-damage counterpart to the cannon.