docs(@projects/@magic-civilization): 📝 update hex grid and tech tree design docs

Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>

.project/designs/README.md

@@ -1,8 +1,22 @@
-# Tech / Culture Tree — Designs
+# Engineering Designs
 
-Visual reference for the research-tree UX. Both trees share the same screen
-(`KnowledgeTree` base scene); only the data source, vocabulary, and signal
-names change.
+Visual references for system architecture and screens. These designs document what is rendered, how data flows, and the geometric primitives the simulation runs on. They are not user-facing tutorials; they exist so someone modifying the relevant code can see the whole shape at once.
+
+## Hex grid
+
+The hex tile geometry — the SQ + QL formation duality that distinguishes our hex grid from every other 4X.
+
+| File | What it shows |
+|---|---|
+| [hex-formation-duality.md](hex-formation-duality.md) | Annotated hex with SQ-half / QL-half / spine; slot-direction lookup; ramifications inventory |
+| [hex-formation-sketch.html](hex-formation-sketch.html) | Interactive single-page mockup; click halves or slots to highlight |
+| [formation-slot-anatomy.md](formation-slot-anatomy.md) | A single slot's contents — role, exposure mask, damage order |
+
+**Source of truth.** [`public/games/age-of-dwarves/docs/HEX_GEOMETRY.md`](../../public/games/age-of-dwarves/docs/HEX_GEOMETRY.md) is the canonical specification. The engineering designs in this section illustrate it; if they conflict, the canonical doc wins.
+
+## Tech / Culture trees
+
+Visual reference for the research-tree UX. Both trees share the same screen (`KnowledgeTree` base scene); only the data source, vocabulary, and signal names change.
 
 | File | What it shows |
 |---|---|
@@ -15,16 +29,20 @@ names change.
 | [data-flow.md](data-flow.md) | JSON → Rust → GDExtension → GDScript → UI pipeline |
 | [unlock-categorization.md](unlock-categorization.md) | How each typed bucket renders (units / buildings / wonders / lenses / resources / mechanics) |
 
-**Audience.** These designs document what the screen *renders* and how the
-data flows. They are not user-facing tutorials; they exist so someone
-modifying the tree code (visual tweaks, a new pillar, a new unlock kind)
-can see the whole shape at once.
+**Source of truth.** The actual visual rendering lives in `src/game/engine/scenes/knowledge_tree/knowledge_tree.gd`. If a design disagrees with the code, the code wins — open a PR to update the design.
 
-**Source of truth.** The actual visual rendering lives in
-`src/game/engine/scenes/knowledge_tree/knowledge_tree.gd`. If a design
-disagrees with the code, the code wins — open a PR to update the design.
+## Other sketches
 
-**See also.** `UI_DESIGN_SYSTEM.md` (this directory) — top-level art
-direction brief covering mood, palette, and typography for the whole
-game. The per-screen designs above inherit those rules; they don't
-override them.
+Standalone HTML mockups for individual screens — not yet indexed under a category here:
+
+- `combat-preview-sketch.html`
+- `hud-sketch.html`
+- `main-menu-sketch.html`
+- `tech-tree-sketch.html`
+- `promotion-picker-sketch.html`
+- `city-screen-sketch.html`
+- `design-gallery.html`
+
+## See also
+
+`UI_DESIGN_SYSTEM.md` (this directory) — top-level art direction brief covering mood, palette, and typography for the whole game. The per-screen designs above inherit those rules; they don't override them.

public/games/age-of-dwarves/docs/combat/COMBAT_SYSTEM.md

@@ -1,5 +1,16 @@
 # Combat System
 
+## Formations & the Hex
+
+Combat in this game is positional in a way most hex 4Xs are not: every hex tile is two formation halves — a **square half (SQ)** and a **quadrilateral half (QL)** — joined at a 2-cell **spine**. `4 + 4 − 2 = 6`. Attackers from a given direction hit only the slots in the half that direction belongs to; spine units take damage from any direction; the leader is damaged last.
+
+Forest-cover-on-attack, flanking by direction-half partition, leader survivability, and facing-aware ZOC all derive from this geometry — they are not separate rules. The damage matrix and R/P/S system below layer on top of the positional model.
+
+- **Canonical geometry:** [`../HEX_GEOMETRY.md`](../HEX_GEOMETRY.md)
+- **Per-shape slot mapping:** [`FORMATIONS.md`](FORMATIONS.md)
+
+---
+
 ## Armor Types
 
 | Armor | Description | Examples |

public/games/age-of-dwarves/docs/terrain/TERRAIN_SYSTEM.md

@@ -1,5 +1,13 @@
 # Terrain System
 
+## Tile structure
+
+Each hex tile carries **one** terrain (plains, forest, hill, …) at the data level — terrain fills the tile uniformly. The *perceived* boundary between two adjacent terrains is the shared hex edge, which is each tile's **QL** (quadrilateral half) on the side facing the other. This is the **biome contact membrane**: the geometric reason a forest unit attacking adjacent plains keeps its forest cover, and the reason all per-terrain combat modifiers are routed through the QL on the engagement side.
+
+For the SQ + QL partition itself and how it governs combat, flanking, and ZOC, see [`../HEX_GEOMETRY.md`](../HEX_GEOMETRY.md).
+
+---
+
 ## Terrain Types and Base Yields
 
 | Terrain | Food | Production | Gold | Cultural resistance | Notes |

public/games/age-of-dwarves/guide/src/App.tsx

@@ -25,7 +25,7 @@ import {
   PopulationDashboardPage, EcologyWebPage, LairsPage, EvolutionMapPage,
   RacesPage, PersonalityAxesPage, GovernmentPage, ErasPage, VictoryPage,
   TechTreePage, CultureTreePage,
-  UnitsPage, CombatPage, KeywordsPage, PromotionsPage, ItemsPage,
+  UnitsPage, CombatPage, HexGridPage, KeywordsPage, PromotionsPage, ItemsPage,
   BuildingsPage, ImprovementsPage, WondersPage, CommunicationsPage,
   HomePage, EarlyAccessPage,
   EpisodeDwarvesPage, FullGamePage, ExpansionsPage, ToolsPage,
@@ -155,11 +155,13 @@ export default function App(): ReactElement {
         {/* Military */}
         <Route path="/military/units"      element={<UnitsPage />} />
         <Route path="/military/combat"     element={<CombatPage />} />
+        <Route path="/military/hex-grid"   element={<HexGridPage />} />
         <Route path="/military/keywords"   element={<KeywordsPage />} />
         <Route path="/military/promotions" element={<PromotionsPage />} />
         <Route path="/military/items"      element={<ItemsPage />} />
         <Route path="/units"      element={<Navigate to="/military/units"      replace />} />
         <Route path="/combat"     element={<Navigate to="/military/combat"     replace />} />
+        <Route path="/hex-grid"   element={<Navigate to="/military/hex-grid"   replace />} />
         <Route path="/keywords"   element={<Navigate to="/military/keywords"   replace />} />
         <Route path="/promotions" element={<Navigate to="/military/promotions" replace />} />
         <Route path="/items"      element={<Navigate to="/military/items"      replace />} />

public/games/age-of-dwarves/guide/src/app/lazy-pages.ts

@@ -43,6 +43,7 @@ export const CultureTreePage        = lazy(() => import('@/pages/CultureTreePage
 // Military
 export const UnitsPage              = lazy(() => import('@/pages/UnitsPage'))
 export const CombatPage             = lazy(() => import('@/pages/CombatPage'))
+export const HexGridPage            = lazy(() => import('@/pages/HexGridPage'))
 export const KeywordsPage           = lazy(() => import('@/pages/KeywordsPage'))
 export const PromotionsPage         = lazy(() => import('@/pages/PromotionsPage'))
 export const ItemsPage              = lazy(() => import('@/pages/ItemsPage'))

public/games/age-of-dwarves/guide/src/pages/HexGridPage.tsx

@@ -0,0 +1 @@
+export { HexGridPage as default } from '@magic-civ/guide-engine'

src/packages/guide/src/index.ts

@@ -132,6 +132,7 @@ export { default as EcosystemPage } from './pages/engine/EcosystemPage'
 export { default as EvolutionMapPage } from './pages/engine/EvolutionMapPage'
 export { default as FoodWebPage } from './pages/engine/FoodWebPage'
 export { default as MapTypesPage } from './pages/engine/MapTypesPage'
+export { default as HexGridPage } from './pages/engine/HexGridPage'
 export { default as EpisodeDwarvesPage } from './pages/episodes/EpisodeDwarvesPage'
 export { default as CrowdfundPage } from './pages/meta/CrowdfundPage'
 export { default as ExpansionsPage } from './pages/meta/ExpansionsPage'

tooling/claude/CLAUDE.md

@@ -36,6 +36,7 @@ Modules live at `.claude/instructions/<file>.md` (symlink resolves to `tooling/c
 | When the task involves… | MUST load before acting… |
 |---|---|
 | Game 1 scope, Game 2 deferral, what-ships-where | `scope-game1-vs-game2.md` |
+| Hex tile geometry, formation duality (SQ + QL), why-hex, biome-edge contact | `public/games/age-of-dwarves/docs/HEX_GEOMETRY.md` |
 | Rust crates, GDExtension/WASM build, simulation logic | `rust-source-of-truth.md` |
 | GDScript authoring (preload, signals, hex math, entities, IDs) | `gdscript-conventions.md` |
 | "Where does this file go?" / `src/` tree / symlinks | `file-organization.md` |