docs: fix runbook markdown lint + regenerate AI config mirrors

aram-devdocs · claude · aram-devdocs · commit 4eaa76896174 · 2026-07-07T14:27:19.000-06:00
Add blank lines around tables (MD058) and backtick-wrap _TYPE_ALIASES (MD037);
regenerate .cursor/rules/*.mdc mirrors for the three new .agents/rules files
(sync-agent-configs). Fixes the Lint Markdown and Validate AI Config Sync checks.

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.cursor/rules/perf-work.mdc b/.cursor/rules/perf-work.mdc
@@ -0,0 +1,31 @@
+---
+description: Performance Work Rules (ENG2)
+globs: 
+alwaysApply: true
+---
+
+<!-- AUTO-GENERATED by scripts/sync-agent-configs.py. Edit .agents/rules/perf-work.md, then rerun the generator. -->
+# Performance Work Rules (ENG2)
+
+Applies to any change under `**/rendering/**`, `**/graphics/**`, `**/benches/**`, `scripts/bench-gate.py`, or any issue labeled `area:performance`.
+
+## Definition of done (non-negotiable)
+
+A performance change is done only when BOTH hold:
+
+1. **A named scripted scene hits its numeric target** — S1–S5/H1/cull_scaling from `docs/src/runbook/perf-dod.md`, captured via `scripts/perf-capture` (3-run median on Apple M-series/Metal) or the CI `scripts/bench-gate.py` ratio-gate for CI-runnable benches.
+2. **A phase counter attributes the cost.** The relevant GPU/CPU phase timing is non-zero and accounts for the frame.
+
+**A counter that reads zero means the instrumentation is broken, never that the work is free.** GPU cost surfaces at surface-acquire/present, not in a CPU command-record timer — measure it with a real GPU timestamp (QuerySet), do not infer it.
+
+## Rules
+
+- No optimization without a measurement first. Post the before-number, then the after-number, on the issue.
+- Never silently cap coverage (top-N, sampling, windowing) to hit a number — `log`/document what was dropped. A scene-windowing workaround is a consumer band-aid, not an engine fix.
+- The target is **O(visible), not O(total)**: per-frame CPU cost must not scale with total scene/entity count. If it does, that is the bug, regardless of FPS.
+- Steady-state render frame (no scene mutation) must perform **0 heap allocations** in the render path — assert it with the alloc-budget harness (ENG2-P0-15), do not eyeball it.
+- Aim for headroom, not the 60 FPS floor: the v2 targets are 120+ FPS for tens of thousands of visible entities.
+
+## Before closing
+
+Run the relevant bench-gate scene, attach the capture (scene, numbers, phase breakdown, delta vs baseline). See `docs/src/runbook/perf-dod.md` for scenes and targets and `[perf-work]`↔`[render-v2]`↔`[testing-v2]` for the companion rules.
diff --git a/.cursor/rules/render-v2.mdc b/.cursor/rules/render-v2.mdc
@@ -0,0 +1,32 @@
+---
+description: Render Core v2 Rules (ENG2 Phases 2 & 6)
+globs: 
+alwaysApply: true
+---
+
+<!-- AUTO-GENERATED by scripts/sync-agent-configs.py. Edit .agents/rules/render-v2.md, then rerun the generator. -->
+# Render Core v2 Rules (ENG2 Phases 2 & 6)
+
+Applies to `**/graphics/**` and the renderer paths. These invariants supersede the performance/submission guidance in `graphics-patterns.md` (the backend-isolation and Renderer-trait rules there still hold). Full design: `docs/src/runbook/phases/phase-2.md` and RFC-0005.
+
+## Submission model
+
+- **O(visible), never O(total).** No per-frame iteration over the entire scene-object set. Cull against a spatial index (grid/BVH) *before* any transform/uniform/encode work. A culled object must pay zero per-frame cost.
+- **Dense storage, not hash-map iteration.** Scene objects live in slot arrays with generational handles, iterated contiguously — not a per-frame walk of a `FxHashMap`.
+- **Instancing by identity.** Draws are grouped by `(mesh id, material id)` and submitted instanced by default — including `CreatePlane`/`CreateCube`/`CreateSphere`/`CreateCylinder` primitives, not only `InstantiateModel`. A config flag that claims to enable instancing must actually drive the instanced path or not exist.
+
+## Uniforms & buffers
+
+- **Per-frame constants uploaded once** (camera, lights, fog) into one bind group. **Per-object data goes in dynamic-offset slots** — never copy a full multi-KB uniform block per draw, never issue one `write_buffer` per draw. Coalesce writes into one upload per frame.
+- **Persistent, dirty-tracked instance/transform buffers.** Upload only changed ranges. Never rebuild the whole buffer, and never CPU-pre-transform vertices into a static VBO that must be re-baked on any change.
+- Do not clone per-instance CPU vertex data for instances that share a mesh.
+
+## Data seam
+
+- Transforms are a **structure-of-arrays column shared between ECS and the renderer** (ENG2-P2-13). The renderer consumes dirty ranges from that column; it does not receive per-entity transforms across FFI one at a time.
+
+## Every render/UI/particle change
+
+- Add or update a **story** in the scene gallery (ENG2-P0-14) with a golden image and metric budget — see `[testing-v2]`.
+- Meet the perf definition of done — see `[perf-work]` and `docs/src/runbook/perf-dod.md`.
+- Raw GPU calls stay in `libs/graphics/backend/` (unchanged boundary).
diff --git a/.cursor/rules/testing-v2.mdc b/.cursor/rules/testing-v2.mdc
@@ -0,0 +1,37 @@
+---
+description: Testing v2 Rules (ENG2)
+globs: 
+alwaysApply: true
+---
+
+<!-- AUTO-GENERATED by scripts/sync-agent-configs.py. Edit .agents/rules/testing-v2.md, then rerun the generator. -->
+# Testing v2 Rules (ENG2)
+
+Applies to all ENG2 work. Full strategy: `docs/src/runbook/testing-strategy.md`. Extends `testing.md` (GL-context and unit conventions there still hold).
+
+## Spec-first (TDD)
+
+- Every behavioral issue gets a spec test at `goud_engine/tests/spec/eng2_p<N>_<nn>_<slug>.rs` encoding its Acceptance Criteria as executable assertions. The spec **is** the gate evidence.
+- Write the spec RED before the implementation; make it GREEN; then REFACTOR. A reviewer confirms it was red-before-green.
+- The issue's Verification section names the spec path. Do not close an issue whose spec test does not exist or does not assert its acceptance criteria.
+
+## Tiers — put each test at the right level
+
+- **Unit** — pure logic, no GPU. Design v2 render/ECS logic (culling, instancing-grouping, sort-key, propagation) to be unit-testable without a GPU context.
+- **Isolation** — one subsystem behind its null/provider boundary (`NullBackend`, null net/audio, in-memory VFS). If the seam to mock a dependency is missing, add the null/mock provider.
+- **Integration** — cross-layer in-process; assert exact draw/culled/visible counts (generalize `tests/renderer3d_frame_counts.rs`).
+- **E2E** — SDK-driven headless engine (ENG2-P0-17); C#/TS/Python boot a real engine, run a scripted game, assert counts/world-hash/flat-RSS.
+
+## Story gallery
+
+- Every render/UI/particle/animation change adds or updates a **story** (ENG2-P0-14): scene + camera + knobs + expected invariants + golden image. CI renders it headless, diffs the golden, checks metric budgets, and publishes the HTML gallery.
+- Changing a golden requires the documented golden-update approval — do not silently overwrite baselines.
+
+## Determinism, property, fuzz
+
+- Sim/scheduling changes run the determinism fixture (3 seeds × 10k ticks, hash-compare). Do not introduce nondeterminism (unordered iteration, wall-clock reads, FP drift).
+- Component-store and command-decoder changes add/extend `proptest` + `cargo-fuzz` targets (ENG2-P0-18, P3-09).
+
+## Don't game the gate
+
+Never weaken an assertion, widen a tolerance, or skip a scene to make a gate pass. If a gate is wrong, fix the gate in the same PR with justification.
diff --git a/docs/src/runbook/phase-specs.md b/docs/src/runbook/phase-specs.md
@@ -141,7 +141,7 @@ CI runners cannot measure Metal. Two enforcement layers:
 
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
-| ENG2-P1-03 | Generate ffi_mapping.json from the Rust manifest; delete the 30-entry _TYPE_ALIASES drift table | A | M | — |
+| ENG2-P1-03 | Generate ffi_mapping.json from the Rust manifest; delete the 30-entry `_TYPE_ALIASES` drift table | A | M | — |
 | ENG2-P1-04 | Per-SDK export-parity CI gate: diff each generated SDK against the manifest | A | M | P1-03 |
 | ENG2-P1-05 | Bring wasm/web bridge under manifest codegen + coverage gate; wasm-pack modernization (#425) | B | L | P1-03 |
 
@@ -393,20 +393,23 @@ CI runners cannot measure Metal. Two enforcement layers:
 **Goal:** Four sprite renderers become one instanced core; 2D camera and culling move engine-side. 8 issues.
 
 ### Batch 6.0 — Decision record
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P6-01 | RFC-0008: Unified instanced 2D sprite core | — | S | Phase 4 gate |
 
 - Four parallel renderers today: immediate FFI (~15 GL-state calls/sprite, `ffi/renderer/draw/internal.rs:107-132`), batched FFI (full rebuild/sort/upload per call, `draw/batch.rs:171-343`), retained ECS SpriteBatch (unreachable from FFI, `rendering/sprite_batch/batch.rs`), WASM batcher (`wasm/sprite_renderer/renderer_core.rs`). Zero GPU instancing anywhere — every sprite CPU-expanded to 4 vertices.
 
 ### Batch 6.1 — Core
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P6-02 | Instanced sprite core: static unit quad + dirty-tracked per-instance buffer (incl. flip flags, #424) | — | L | P6-01 |
 
 - Per-instance {transform, size, uv-rect, color, tex-index, flags}; persistent buffers, changed-only uploads (replaces `batch.rs:234-242` CPU corner rotation + `batch.rs:355-417` per-frame vertex gen). Reuses Phase 2 instancing patterns behind the backend trait.
 
 ### Batch 6.2 — Path unification (3 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P6-03 | Route FFI sprite paths through the core; delete immediate + rebuild-per-call paths | A | M | P6-02 |
@@ -416,6 +419,7 @@ CI runners cannot measure Metal. Two enforcement layers:
 - **P6-05:** FFI batch sets only `u_viewport` (`draw/batch.rs:355`); Throne does world→screen math + visibility in C# per sprite (`GoudRenderPort.cs:275`). Camera uniform + grid/quadtree culling before submission; #554's configurable origin lands in the camera.
 
 ### Batch 6.3 — 2D scale features (3 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P6-06 | Chunked tilemap renderer from TileLayer gids | A | M | P6-02 |
@@ -439,6 +443,7 @@ CI runners cannot measure Metal. Two enforcement layers:
 **Goal:** The built-but-unwired services become real: async assets, mipmaps, one audio stack, one 2D physics, retained UI, multi-window. 6 issues.
 
 ### Batch 7.1 — Assets & media (3 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P7-01 | Wire async asset pipeline into the runtime; background decode incl. RGB→RGBA off main thread | A | M | Phase 4 gate |
@@ -450,6 +455,7 @@ CI runners cannot measure Metal. Two enforcement layers:
 - **P7-03:** `assets/audio_manager/` (2832 LOC) vs `libs/providers/impls/rodio_audio.rs:118-138` — two full rodio wrappers, two unsafe Send/Sync blocks; keep the provider-trait one, bridge asset data through it.
 
 ### Batch 7.2 — Physics, UI, windowing (3 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P7-04 | Consolidate 2D physics on rapier2d; delete the custom ECS solver | A | M | P3-07 |
@@ -474,6 +480,7 @@ CI runners cannot measure Metal. Two enforcement layers:
 **Goal:** "Any game" credibility: navigation, particles, save/load, procedural primitives, terrain. Every capability ships FFI + 10-SDK parity + integration test + docs page (per the Phase 1 gates, now cheap). 11 issues.
 
 ### Batch 8.1 — Highest-demand capabilities (4 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P8-01 | Grid A* + flow fields reusing ecs/spatial_grid; nav FFI surface (#546) | A | L | P5-03 |
@@ -487,6 +494,7 @@ CI runners cannot measure Metal. Two enforcement layers:
 - **P8-04:** No `rand`/`noise` in engine deps; cross-language determinism requires an engine-owned seeded PRNG (ties to P5-04 hashing).
 
 ### Batch 8.2 — Gameplay services (4 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P8-05 | Engine event bus with FFI subscription (#547) | A | M | — |
@@ -498,6 +506,7 @@ CI runners cannot measure Metal. Two enforcement layers:
 - **P8-08:** Deliberately late: Phases 2/3/6 already deleted much cgmath-using code; migrate the remainder onto `core/math`, drop the advisory-ignored dep.
 
 ### Batch 8.3 — Big-world (2 groups)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P8-09 | Navmesh generation/query for 3D navigation | A | L | P8-01 |
@@ -519,6 +528,7 @@ CI runners cannot measure Metal. Two enforcement layers:
 **Goal:** Every kept platform is CI-real; developers can see and author scenes; examples prove the v2 API. 9 issues.
 
 ### Batch 9.1 — Platforms & tooling (4 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P9-01 | Scene inspector MVP (egui or web client over the MCP relay): entity tree + live component editing | A | L | P7-06 |
@@ -533,6 +543,7 @@ CI runners cannot measure Metal. Two enforcement layers:
 - **P9-05:** `providers/impls/webrtc_network/mod.rs:1-17` is custom UDP+STUN labeled WebRTC, `net-webrtc=[]` pulls no crate; ~7-8k LOC networking has zero production consumers — decision record on tiering (default-feature status) + honest naming.
 
 ### Batch 9.2 — Examples, docs, agent configs (4 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P9-06 | Compiled Rust examples in the engine crate (currently zero .rs examples) | A | M | — |
diff --git a/docs/src/runbook/phases/phase-1.md b/docs/src/runbook/phases/phase-1.md
@@ -22,7 +22,7 @@ _Authoritative spec. See also the [phase index](../phase-index.md), [perf-dod](.
 
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
-| ENG2-P1-03 | Generate ffi_mapping.json from the Rust manifest; delete the 30-entry _TYPE_ALIASES drift table | A | M | — |
+| ENG2-P1-03 | Generate ffi_mapping.json from the Rust manifest; delete the 30-entry `_TYPE_ALIASES` drift table | A | M | — |
 | ENG2-P1-04 | Per-SDK export-parity CI gate: diff each generated SDK against the manifest | A | M | P1-03 |
 | ENG2-P1-05 | Bring wasm/web bridge under manifest codegen + coverage gate; wasm-pack modernization (#425) | B | L | P1-03 |
 
diff --git a/docs/src/runbook/phases/phase-6.md b/docs/src/runbook/phases/phase-6.md
@@ -9,20 +9,23 @@ _Authoritative spec. See also the [phase index](../phase-index.md), [perf-dod](.
 **Goal:** Four sprite renderers become one instanced core; 2D camera and culling move engine-side. 8 issues.
 
 ### Batch 6.0 — Decision record
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P6-01 | RFC-0008: Unified instanced 2D sprite core | — | S | Phase 4 gate |
 
 - Four parallel renderers today: immediate FFI (~15 GL-state calls/sprite, `ffi/renderer/draw/internal.rs:107-132`), batched FFI (full rebuild/sort/upload per call, `draw/batch.rs:171-343`), retained ECS SpriteBatch (unreachable from FFI, `rendering/sprite_batch/batch.rs`), WASM batcher (`wasm/sprite_renderer/renderer_core.rs`). Zero GPU instancing anywhere — every sprite CPU-expanded to 4 vertices.
 
 ### Batch 6.1 — Core
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P6-02 | Instanced sprite core: static unit quad + dirty-tracked per-instance buffer (incl. flip flags, #424) | — | L | P6-01 |
 
 - Per-instance {transform, size, uv-rect, color, tex-index, flags}; persistent buffers, changed-only uploads (replaces `batch.rs:234-242` CPU corner rotation + `batch.rs:355-417` per-frame vertex gen). Reuses Phase 2 instancing patterns behind the backend trait.
 
 ### Batch 6.2 — Path unification (3 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P6-03 | Route FFI sprite paths through the core; delete immediate + rebuild-per-call paths | A | M | P6-02 |
@@ -32,6 +35,7 @@ _Authoritative spec. See also the [phase index](../phase-index.md), [perf-dod](.
 - **P6-05:** FFI batch sets only `u_viewport` (`draw/batch.rs:355`); Throne does world→screen math + visibility in C# per sprite (`GoudRenderPort.cs:275`). Camera uniform + grid/quadtree culling before submission; #554's configurable origin lands in the camera.
 
 ### Batch 6.3 — 2D scale features (3 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P6-06 | Chunked tilemap renderer from TileLayer gids | A | M | P6-02 |
diff --git a/docs/src/runbook/phases/phase-7.md b/docs/src/runbook/phases/phase-7.md
@@ -9,6 +9,7 @@ _Authoritative spec. See also the [phase index](../phase-index.md), [perf-dod](.
 **Goal:** The built-but-unwired services become real: async assets, mipmaps, one audio stack, one 2D physics, retained UI, multi-window. 6 issues.
 
 ### Batch 7.1 — Assets & media (3 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P7-01 | Wire async asset pipeline into the runtime; background decode incl. RGB→RGBA off main thread | A | M | Phase 4 gate |
@@ -20,6 +21,7 @@ _Authoritative spec. See also the [phase index](../phase-index.md), [perf-dod](.
 - **P7-03:** `assets/audio_manager/` (2832 LOC) vs `libs/providers/impls/rodio_audio.rs:118-138` — two full rodio wrappers, two unsafe Send/Sync blocks; keep the provider-trait one, bridge asset data through it.
 
 ### Batch 7.2 — Physics, UI, windowing (3 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P7-04 | Consolidate 2D physics on rapier2d; delete the custom ECS solver | A | M | P3-07 |
diff --git a/docs/src/runbook/phases/phase-8.md b/docs/src/runbook/phases/phase-8.md
@@ -9,6 +9,7 @@ _Authoritative spec. See also the [phase index](../phase-index.md), [perf-dod](.
 **Goal:** "Any game" credibility: navigation, particles, save/load, procedural primitives, terrain. Every capability ships FFI + 10-SDK parity + integration test + docs page (per the Phase 1 gates, now cheap). 11 issues.
 
 ### Batch 8.1 — Highest-demand capabilities (4 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P8-01 | Grid A* + flow fields reusing ecs/spatial_grid; nav FFI surface (#546) | A | L | P5-03 |
@@ -22,6 +23,7 @@ _Authoritative spec. See also the [phase index](../phase-index.md), [perf-dod](.
 - **P8-04:** No `rand`/`noise` in engine deps; cross-language determinism requires an engine-owned seeded PRNG (ties to P5-04 hashing).
 
 ### Batch 8.2 — Gameplay services (4 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P8-05 | Engine event bus with FFI subscription (#547) | A | M | — |
@@ -33,6 +35,7 @@ _Authoritative spec. See also the [phase index](../phase-index.md), [perf-dod](.
 - **P8-08:** Deliberately late: Phases 2/3/6 already deleted much cgmath-using code; migrate the remainder onto `core/math`, drop the advisory-ignored dep.
 
 ### Batch 8.3 — Big-world (2 groups)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P8-09 | Navmesh generation/query for 3D navigation | A | L | P8-01 |
diff --git a/docs/src/runbook/phases/phase-9.md b/docs/src/runbook/phases/phase-9.md
@@ -11,6 +11,7 @@ _Authoritative spec. See also the [phase index](../phase-index.md), [perf-dod](.
 **Goal:** Every kept platform is CI-real; developers can see and author scenes; examples prove the v2 API. 9 issues.
 
 ### Batch 9.1 — Platforms & tooling (4 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P9-01 | Scene inspector MVP (egui or web client over the MCP relay): entity tree + live component editing | A | L | P7-06 |
@@ -25,6 +26,7 @@ _Authoritative spec. See also the [phase index](../phase-index.md), [perf-dod](.
 - **P9-05:** `providers/impls/webrtc_network/mod.rs:1-17` is custom UDP+STUN labeled WebRTC, `net-webrtc=[]` pulls no crate; ~7-8k LOC networking has zero production consumers — decision record on tiering (default-feature status) + honest naming.
 
 ### Batch 9.2 — Examples, docs, agent configs (4 groups, parallel)
+
 | ID | Title | Grp | Effort | Blocked by |
 |---|---|---|---|---|
 | ENG2-P9-06 | Compiled Rust examples in the engine crate (currently zero .rs examples) | A | M | — |
