STARGAZER

`SimulationLaunchDefaults` owns the default interactive AI count, combat flag, spawn profile, and static-target rule; `BroadsideTarget` AI uses a broadside-hold pilot mode with longer visible beam pulses. Visual proof: [`screenshots/2026-05-23/074906-default-engagement-ai-laser.jpg`](https://github.com/mechaghost/StarGazer/blob/92cc7cb/screenshots/2026-05-23/074906-default-engagement-ai-laser.jpg).

The normal playable launch drifted away from the laser-duel proof, and loiter steering moved the enemy out of arc before the player could reliably see engagement.

Expose filesystem-only getters `getLogEntriesFromFs` and `getBlogPostsFromFs` in `[dataParser.ts](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/src/lib/dataParser.ts)`. Refactor `[sync-db.ts](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/scripts/sync-db.ts)` to consume these getters rather than database-backed methods.

The database synchronization script `sync-db.ts` relies on parsing local markdown records to sync the database, but calling the generic getters in `dataParser.ts` fell back to querying the database itself if `DATABASE_URL` was configured. This created a dependency loop that returned empty datasets when updating a clean database.

Configure `"engines": { "node": ">=20.9.0" }` in `[package.json](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/package.json)` and set `NIXPACKS_NODE_VERSION = "20"` in `[nixpacks.toml](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/nixpacks.toml)`. Rewrite `[prebuild.ts](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/scripts/prebuild.ts)` to use `fs.lstatSync` instead of `fs.existsSync` to safely identify and unlink broken symbolic links before creating the screenshots folder.

Railway's Nixpacks builder defaults to Node 18, which is unsupported by Next.js 16+ and crashes during build compilation. In addition, Nixpacks' isolated context means the parent `screenshots/` directory is absent at build time, causing `fs.existsSync` to mistake the broken symlink as non-existent and fail to recreate it due to name conflicts.

Configure `[nixpacks.toml](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/nixpacks.toml)` to install `git-lfs` during the setup phase. Add `[prebuild.ts](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/scripts/prebuild.ts)` running `git lfs pull` and replacing the `public/screenshots` symbolic link with a physical directory copy during the prebuild script. Configure `[dataParser.ts](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/src/lib/dataParser.ts)` to fall back to `public/screenshots` if the parent `../screenshots` directory is missing.

Railway pulls code without running Git LFS by default, leaving only text pointer files. Installing `git-lfs` and pulling LFS files at build time fetches the binaries, and copying them into `/public` ensures they are bundled into the final Nixpacks production runner image (since Nixpacks only copies the build directory `/web` into the runner). Falling back to the public path at runtime prevents broken image links or crashes on the deployed server.

Change the default value of the `variant` parameter in `[OrnamentalFrame.tsx](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/src/components/OrnamentalFrame.tsx)` from `"celestial"` to `"minimal"`. Update homepage frames and detail page layouts to either use or default to `"minimal"`, and update layout navigation in `[Navbar.tsx](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/src/components/Navbar.tsx)` to include the new About page link.

Tones down the celestial ornamentation across components to "slight hints" instead of visually dominant concentric circles and stars, resulting in a cleaner, more focused user interface that still carries the high-fantasy Space Knight motif.

`DebugTriangleCullRenderer` now uses ONE `DynamicVertexBuffer` per ship sized for the GLB's full triangle list. Each cook-time chunk owns a fixed slice (`VertexOffset + VertexCount`); on damage we only rewrite the affected slice via `SetData(offsetInBytes, …, SetDataOptions.NoOverwrite)`. Dead triangles are written as degenerate (all-zero) vertices so the GPU clipper drops them for free. Drawing collapses to ONE `SetVertexBuffer` + ONE `DrawPrimitives` per ship per frame. The chunked dirty-rebuild architecture is preserved — buffer uploads are still gated on chunk state-version changes, never per-frame.

With the half-voxel-size default (~0.067u edge, 120k voxels per ship), the prior per-chunk `DynamicVertexBuffer` layout was issuing ~1,900 `SetVertexBuffer + DrawPrimitives` calls per ship per frame. FNA's per-call CPU overhead summed to ~30ms/frame at 7 ships, dropping live frame rate from 60 to ~23 fps. Coalescing keeps the dirty-region rebuild benefit (only the affected chunk's slice re-uploads on damage) but stops paying for ~13,300 redundant draw calls every frame. Confirmed restore: live capture at tick 60 with 7 ships shows 60.9 fps, matching the pre-fine-voxel baseline.

`Simulation.ResolveVoxelContact` voxel-refines every ship-vs-ship contact before publishing `LastShipContact`. When a contact event fires between two ship bodies, the simulation raycasts from ship A's center toward ship B using `VoxelHitMapper`; the hit world position becomes `ShipContactSummary.ContactPoint` (new field) and the impacting voxel face's outward normal becomes `.Normal`. Falls back to the OBB midpoint + center-to-center vector when one of the bodies has no voxel state (asteroid, debris, static target sphere) or the ray misses. Regression test `runtime:ship-contact-on-voxel` in `--voxel-test-suite` asserts the contact point lands inside ship B's bounds and is measurably away from the midpoint — verified by reverting the fix and watching the assertion fail (`dist_from_midpt=0.3` instead of the expected `16.5`).

Audit of the physics layer found `PhysicsWorld.TryGetPairContactData` was setting contact normal to a simple `(positionB - positionA).Normalize()` and contact position to the body midpoint — both broadphase placeholders that pretended every collision was sphere-to-sphere. Physics broadphase can't know about voxel state; the simulation layer is the right place to refine. Same pattern as the beam-endpoint fix: physics for broadphase only, voxels for "what actually touched."

Add an in-process git activity calendar (`[CommitCalendar.tsx](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/src/components/CommitCalendar.tsx)`) and codebase statistics sidebar (`[DiagnosticsPanel.tsx](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/src/components/DiagnosticsPanel.tsx)`) fetching metrics (LOC, commits, screenshot size) directly via `child_process` hooks.

Exposing raw codebase sizing (C# vs Web LOC, files count) and git activity grids anchors development transparency in real metrics that change dynamically with each update.

Whenever a ship has voxel state, any visual or player-facing feedback that depends on "where the interaction hit the ship" must derive its position from the voxel hit (e.g. `beamStart + direction * VoxelHit.T`), never from the physics broadphase / OBB sweep result. The `MissileSweepResult.Position` on a ship body is on the surface of the coarse `0.7r × 0.3r × 1.8r` collider — it overshoots the actual hull by several voxels and is for broadphase culling and rigid-body dynamics only. `TryQueueVoxelBeamDamage` now returns the corrected world-space hit; `FireBeamAtShip` feeds that into `Weapon.LastBeamEnd` / `CombatBeam.End`. Regression-test scenario `beam-endpoint-on-voxel` in `Sim/Ships/Voxels/Testing/VoxelTestSuiteRunner.cs` asserts the beam length matches `LastVoxelBeamHit.T` within 1.5 voxel sizes; verified by temporarily reverting the fix and watching the test fail with `beam_length=74.0 voxel_hit_t=78.5` before restoring.

The user noticed beam glow floating multiple voxels past the actual hull. Root cause was the visual endpoint reading from the OBB sweep result while the damage path correctly used the voxel raycast. Lining both up on voxel hit eliminates the gap and codifies the rule for every future "thing that visually touches a ship" — missile splatters, decal positions, particle spawn origins, etc.

Designed and implemented three React components: `[GoldDivider.tsx](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/src/components/GoldDivider.tsx)`, `[OrnamentalCorner.tsx](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/src/components/OrnamentalCorner.tsx)`, and `[OrnamentalFrame.tsx](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/src/components/OrnamentalFrame.tsx)` in `web/src/components/`. The components support three distinct design variants (`"celestial"`, `"imperial"`, and `"minimal"`) utilizing inline high-fantasy SVG vectors (8-pointed stars, crescent moons, astronomical alignments, and knightly chevrons), customizable colors/glow filters, and full responsiveness via CSS scaling and flexbox dividers. The corners use a single top-left coordinate space and rotate/mirror dynamically via inline CSS transforms to fit all four slots.

To establish a premium, high-fantasy "Space Knight" thematic aesthetic on the developer chronicles website, aligning the web interface with the game's core space-combat and capital ship lore. Combining paths, using relative flex containers, and mirroring a single SVG corner reduces asset size, eliminates asset loading overhead, and guarantees crisp vector renders across all screen resolutions.

Migrate the Next.js developer chronicles to a PostgreSQL database using Prisma ORM with offline-first static filesystem fallbacks. We defined the schema models in `[schema.prisma](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/prisma/schema.prisma)`, built an out-of-process ingestion tool `[sync-db.ts](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/scripts/sync-db.ts)`, and exposed machine-readable `[/llms.txt](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/src/app/llms.txt/route.ts)` and `[/llms-full.txt](https://github.com/mechaghost/StarGazer/blob/92cc7cb/web/src/app/llms-full.txt/route.ts)` feeds.

To support scalable timeline sorting, pagination, and fast searches across thousands of commits, logs, and screenshots without degrading game simulation performance (since the database layer remains strictly out-of-process and isolated).

`Render/Hud/HudButtonPanel` adds a clickable vertical button stack in the upper-right corner of the screen. Buttons cover Reset battle, Cycle ship, Cycle camera, Battle (6 AI), Duel (1 AI), Peaceful, Front-breach FX, Damage cycle, and Voxel debug cycle. Each button also has a keyboard shortcut (R / `[ ]` / Tab / 1 / 2 / 3 / F / V / B), and Game1 listens for both. Scenario switching builds a new `effectiveSimulationConfig` and calls `ResetSimulation()` so the new spawn profile takes effect immediately. Damage/voxel render modes are now runtime-mutable instead of `readonly`. The damage renderer + voxel asset are always cooked at launch so toggles don't have to rebuild GPU resources. Visual proof: [`screenshots/2026-05-23/122111-hud-buttons.jpg`](https://github.com/mechaghost/StarGazer/blob/92cc7cb/screenshots/2026-05-23/122111-hud-buttons.jpg).

The user wants to try different scenarios and visual states without restarting with new CLI flags every time. The architectural tenet keeps the keyboard shortcuts as the primary entry (so headless scenarios and screenshot automation still work); the buttons are a mouse-friendly mirror of the same actions.

`dotnet run` / `scripts/run-game` now drops the user into a 6-AI-ship "Battle" formation with the orbit camera set to an overhead RTS view (60° pitch, 220-unit distance), damage rendering on, voxel overlay off, and the player slot as a `Faction.Neutral` spectator. Even-indexed AI ships spawn on `Faction.Player`, odd-indexed on `Faction.Ai`; both lines use BroadsideHold and each AI ship picks its own nearest enemy-faction ship via `AiPilotSystem.FindNearestEnemyShip` (was hard-coded to the player). `DamageableShipRenderer` is now keyed by `EntityId` so any ship can be the cap/cavity target, but the render pipeline only emits full damage geometry for the selected ship — `[` / `]` cycles which ship gets the close-up wounds. Visual proof: [`screenshots/2026-05-23/115648-rts-battle-default.jpg`](https://github.com/mechaghost/StarGazer/blob/92cc7cb/screenshots/2026-05-23/115648-rts-battle-default.jpg).

The user wants the default run to be the showcase — AI vs AI from above so battles unfold and damage is visible. Per-ship damage rendering for every combatant scaled badly on the FNA/Metal path (chunk rebuilds + buffer uploads × ships); selected-ship-only matches the original Render/Damage plan's LOD tiers and keeps the frame rate playable.

`InteriorDetailGenerator` only emits the full structural wound (jagged armor lip + cavity backdrop + decks + ribs + pipes + machinery + sparks + smoke) when a cluster has ≥2 wound boundary records. Single-record clusters get only a small hot scorch ring (`AppendScorchScar`) on the wound face — no cavity backdrop, no decks. Visual proof: [`screenshots/2026-05-23/111732-live-damage-after-fix.jpg`](https://github.com/mechaghost/StarGazer/blob/92cc7cb/screenshots/2026-05-23/111732-live-damage-after-fix.jpg).

A 1-voxel beam hit generates a wound record on all 5–6 live face-neighbors of the destroyed voxel, so the unconstrained generator was painting 5–6 voxel-sized dark cavity backdrops around every tiny hit — they read as floating black "planes" instead of damage. Front-breach demo still looks the same because big wounds always have many records per cluster.

`ShipShieldRenderer` is deleted; `SceneRenderers` no longer carries a `ShipShields` slot; `RenderPipeline` no longer draws bubble shields; `Game1` no longer instantiates one. StarGazer ships do not have energy shields — combat reads exclusively through armor wear, voxel destruction, and the damage-render slice. Plan items 23 (sci-fi shield Fresnel) and 3.6 (shield bubble pass) in [`DOC/VISUAL-RENDERING-PLAN.md`](https://github.com/mechaghost/StarGazer/blob/92cc7cb/VISUAL-RENDERING-PLAN.md) are out of scope and will not ship.

A shield bubble in front of the hull hides exactly the damage geometry the `Render/Damage/*` slice exists to show; the combat fiction is grounded in physical damage, not energy fields.

`Render/Damage/InteriorDetailGenerator` now builds ONE structural wound per face axis from all retained wound boundary records (chunkIndex=-1), rendered in a separate ship-wide pass after the per-chunk dark cap backdrops; `DebugTriangleCullRenderer` also drops triangles whose centroid OR any vertex lands in a destroyed voxel so forward-protruding fins/antennas don't poke through the breach from inside the cavity. The front-breach demo also suppresses the magenta rim light + non-essential renderers so the wound dominates the capture. Visual proof: [`screenshots/2026-05-23/100404-front-breach-interior.jpg`](https://github.com/mechaghost/StarGazer/blob/92cc7cb/screenshots/2026-05-23/100404-front-breach-interior.jpg).

The first slice had per-voxel hot-edge dashes that read as a Minecraft grid, and the ship's own GLB tail-fin triangles (owner voxel alive but vertices in destroyed space) painted a pink "lightning bolt" through the wound regardless of how dark the cap was. Aggregating per-axis gives one authored-looking breach; vertex-level culling stops the GLB bleed-through; the cap stays per-voxel/dirty-region so simple beam hits still rebuild cheaply.

`Render/Damage/*` now owns selected-ship damage cook scaffolding, retained wound history, chunked cap/interior buffers, and `--damage-render-demo front-breach` proof capture. Visual proof: [`screenshots/2026-05-23/092831-front-breach-interior.jpg`](https://github.com/mechaghost/StarGazer/blob/92cc7cb/screenshots/2026-05-23/092831-front-breach-interior.jpg).

The first damage-render slice needs to look like layered ship wreckage while keeping voxel state as gameplay truth and leaving triangle deletion as `debug-cull`.

Damage rendering will keep render-side wound boundary history and precomputed interior patch templates so caps, age, smoke, sparks, decks, halls, and debris remain stable after voxel cleanup.

Live voxel state alone cannot reconstruct dramatic wounds after destroyed voxels detach or disappear; render history preserves visuals without becoming gameplay authority.

High-quality ship damage will live in `Render/Damage/*` as chunked render meshes derived from sim voxel state, with generated wound caps/interiors and no sim ownership changes.

The simulation must stay deterministic and voxel-authoritative while the renderer becomes visually rich; the reviewed implementation checklist is [`DOC/SHIP-DAMAGE-RENDERING-PLAN.md`](https://github.com/mechaghost/StarGazer/blob/92cc7cb/SHIP-DAMAGE-RENDERING-PLAN.md).

`Program` now defaults `VoxelDebugMode` to `Overlay`, `VoxelShipDebugRenderer` keeps a separate translucent overlay cache, and `CombatBeam` carries its trace radius for scaled beam rendering.

The default visual proof needs damageable GLB triangles, voxel debug surfaces, and beam width to agree without making voxel-only debug captures transparent.

`AiPilotSystem` owns the deterministic broadside-orbit goal, side-selection, yaw alignment, and local thrust intent for AI combat ships.

Orbit combat is simulation behavior, not render/gameplay glue; keeping it in the AI system makes it findable and keeps coordinate math consuming ship pose basis vectors.

`scripts/run-game` generates a one-shot LaunchAgent with `RunAtLoad` but no `KeepAlive`, then bootstraps it after clearing stale jobs and processes.

`launchctl submit` keeps failed programs alive, while plain background/nohup launches can be reaped by Codex's shell; a non-keepalive LaunchAgent survives launch but does not respawn after close.

Beam voxel damage destroys the direct hit voxel but applies low splash to neighboring voxels, instead of overkilling every voxel in the impact box. Visual proof: [`screenshots/2026-05-23/081008-damage-progression-tick-245-tuned.jpg`](https://github.com/mechaghost/StarGazer/blob/92cc7cb/screenshots/2026-05-23/081008-damage-progression-tick-245-tuned.jpg).

The mesh-damage renderer exposed that repeated 1000-damage clusters detached nearly the whole GLB from the core after a few hits, making ships disappear.

`Game1` enables stable render systems, including `ShipShieldRenderer`, for the default launch path; opt-outs stay behind explicit CLI flags. Visual proof: [`screenshots/2026-05-23/080449-default-showcase-all-effects.jpg`](https://github.com/mechaghost/StarGazer/blob/92cc7cb/screenshots/2026-05-23/080449-default-showcase-all-effects.jpg).

The default live run is the showcase surface, so compiled visual systems should not be silently left null unless they are broken or explicitly disabled.

`Program` initializes `voxelDebugMode` to `VoxelDebugMode.MeshDamage`, while explicit `--voxel-debug` flags still override it; beam impact clusters are a one-voxel radius for readable breaches. Visual proof: [`screenshots/2026-05-23/075601-run-default-visible-voxel-damage.jpg`](https://github.com/mechaghost/StarGazer/blob/92cc7cb/screenshots/2026-05-23/075601-run-default-visible-voxel-damage.jpg).

Combat was applying voxel damage, but default rendering stayed on the static GLB path; once visible, the older larger impact cluster deleted too much hull too quickly.

`Program` initializes `cameraMode` to `CameraMode.Orbit`, while explicit `--camera` flags still override it for screenshots and scenarios. Visual proof: [`screenshots/2026-05-23/075159-run-default-orbit-combat.jpg`](https://github.com/mechaghost/StarGazer/blob/92cc7cb/screenshots/2026-05-23/075159-run-default-orbit-combat.jpg).

The app runner and plain `dotnet run` share `Program`; putting the default there keeps the interactive launch, screenshot proof, and future agent runs from drifting.

`--voxel-test-suite` now runs the voxel validation matrix, construction scenarios, destruction/debris ownership scenarios, benchmark smoke profiles, and the default GLB ship-slice cook as one aggregate headless gate. The construction matrix includes disconnected/floating pieces, diagonal-only contact, impossible bounds, too-small/too-large bounds, non-watertight shell fallback, triangle-budget fallback, mirrored transform, multi-mesh, and nested-shell probes.

Individual voxel probes are useful during development, but agents need one obvious command that catches construction, split/debris, DDA, performance smoke, and real-model cook regressions before committing later voxel work.

`--voxel-ship-slice` now loads GLB geometry through a CPU-only SharpGLTF path, applies the centralized model-local to ship-voxel-local conversion, cooks deterministic voxel cells, validates the resulting asset, and writes a regenerable marker under `obj/voxel-cache/`. The default `Content/models/spaceship.glb` currently cooks to 1,186 connected voxels from 45,846 triangles with hash `0x400A17B7C964BA9C`.

Synthetic topology tests prove rules exactly, but the cornerstone feature also needs an early real-model proof that GLB traversal, coordinate conversion, density selection, validation, and cache boundaries can work without touching render GPU buffers.

BEPU-backed body spawns and `PhysicsBodyPoseSnapshot` use `VelocityPerSecond` and `AngularVelocityPerSecond`, while the legacy ship sim keeps its existing per-tick velocity fields.

Seconds-based BEPU integration and tick-based ship tuning coexist during migration, so the unit boundary must be visible in API names.

The first voxel execution slice adds synthetic voxel assets, stable validation codes, construction/destruction CLI scenarios, deterministic debris records for split islands, O(1) voxel DDA lookup, and `--bench-voxels` profiles for leaf skips, bridge cuts, DDA, and chunk remesh smoke. Initial gate results are recorded in [`DOC/PHYSICS-PERFORMANCE-GATES.md`](https://github.com/mechaghost/StarGazer/blob/ b650bf/PHYSICS-PERFORMANCE-GATES.md).

Before GLB voxel cooking lands, the topology and ownership rules need exact synthetic proofs. These tests catch disconnected construction, diagonal-only contact, core errors, leaf-vs-bridge topology behavior, and detached pieces accidentally remaining live/player/AI-owned.

Voxel implementation now has a dedicated automated test and performance plan covering validation message codes, synthetic topology fixtures, GLB construction edge cases, destruction/split scenarios, debris ownership rules, DDA/coordinate tests, chunk-remesh visual proofs, and voxel-specific benchmark profiles. Detached voxel islands must emit deterministic debris records and immediately leave player/AI/live-ship ownership, even if full physical debris remains deferred. Full plan: [`DOC/VOXEL-SHIP-TEST-PLAN.md`](https://github.com/mechaghost/StarGazer/blob/ b650bf/VOXEL-SHIP-TEST-PLAN.md).

The voxel system can fail in subtle ways that screenshots will not catch: floating source pieces, diagonal-only contact, impossible bounds, sliver-triangle cook explosions, bridge cuts that leave hidden ownership bugs, or split debris still responding to player/AI systems. Capturing these as machine-readable CLI scenarios and benchmarks makes the cornerstone damage system testable before it becomes too large to reason about.

The voxel ship plan now requires chunked exposed-face rendering in V1, asset-owned O(1) coordinate lookup for DDA, tiered/lazy detailed voxel state backed by pooled slabs, topology prechecks before full BFS, cook-time spatial acceleration/budgets, and benchmark metrics for topology skips, DDA steps, dirty chunk rebuilds, mesh upload bytes, and command batch ordering. Review source: Minecraft/Unity/voxel-engine performance pass captured in [`DOC/VOXEL-SHIP-IMPLEMENTATION-PLAN.md`](https://github.com/mechaghost/StarGazer/blob/ b650bf/VOXEL-SHIP-IMPLEMENTATION-PLAN.md).

The earlier plan was directionally right but still allowed expensive fallback implementations: full-ship remeshes, full BFS for leaf damage, binary-search/hash lookup during DDA, per-ship heap islands, and runtime GLB voxelization. Those would pass the first screenshot while failing the "hundreds or thousands of ships" goal.

Voxel ships will start as GLB-cooked logical damage cells owned by deterministic simulation state, while each ship keeps one coarse BEPU `BodyRef` for movement and collision. Cooking code belongs under source folders such as `VoxelCooking/`, raw sidecars remain under `Content/`, runtime caches are regenerable under `obj/voxel-cache/`, and render/debug views consume tick-latched voxel snapshots rather than mutable sim arrays. Full implementation checklist: [`DOC/VOXEL-SHIP-IMPLEMENTATION-PLAN.md`](https://github.com/mechaghost/StarGazer/blob/ b650bf/VOXEL-SHIP-IMPLEMENTATION-PLAN.md).

One-physics-body-per-voxel would not scale to hundreds or thousands of ships and would leak backend physics details into damage rules. Keeping voxels as dense deterministic arrays gives us stable IDs, replayable damage ordering, cheap core-connectivity checks, and a clean path to future systems tags without forcing collider rebuilding in the first slice.

Ship simulation now supports `LoiterSparse`, `DenseContact`, and `CollisionCourse` spawn profiles. `--bench-ships` reports contacts per tick plus AI/control, physics, snapshot/contact, and hash timing splits. Visual proof of sparse setup: [`screenshots/2026-05-22/160526-sparse-fleet-profile.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/160526-sparse-fleet-profile.jpg).

The old benchmark spawn layout mixed normal fleet scale with worst-case contact load, making it unclear whether cost came from AI/control, BEPU stepping, or contact publication. Sparse and dense profiles let agents compare normal space spread against deliberate contact stress.

`SelectedShipDebugRenderer` renders selected-ship markers, forward/right/up basis vectors, velocity direction, and AI goal lines from published `BodyPoseSnapshot` data. `Game1` owns selected index and camera targeting; `Simulation` only exposes AI goal lookup by ship index.

Debug vectors must use the same sim-owned basis conventions as gameplay, not render-side matrix reconstruction. Keeping selection in the game layer avoids adding UI-only state to deterministic simulation.

`Game1` now measures draw-to-draw frame time with `Stopwatch`, smooths FPS/frame time over a short window, and renders those metrics in the compact HUD panel.

Fixed sim ticks prove deterministic step cadence, but live playtesting needs a quick render-loop signal while AI/physics scale changes land.

`--bench-ships` now runs the BEPU-backed player/AI ship simulation headlessly, reports timing/allocation/contact/wake/hash metrics, repeats the same seed for determinism, compares a different seed for AI variance, and runs threaded multi-instance simulations to prove worker-isolated repeatability.

Fleet gameplay needs evidence from the actual ship/control/AI/physics path before scaling visual debug or combat behavior. Multi-instance threading is the first safe threading gate because same-world parallel mutation belongs behind a deliberate `PhysicsWorld` worker-dispatch design.

Player and AI ships now live in `ShipStore` with dense slot-order arrays for entity/body ownership, authority/faction metadata, movement intent, yaw/roll control state, pose snapshots, and AI pilot state. `ShipControlSystem` is the only normal path that turns ship intent into BEPU orientation/velocity, using `PhysicsWorld.SetBodyControlMotion` so controlled bodies do not rewrite position every tick.

Scaling from one player body to many ships needs one agent-findable path that preserves BEPU collision response and avoids singleton fields or per-feature control code.

The app icon source and platform derivatives live under `Assets/icons/`, while `Content/icons/stargazer-runtime.png` is linked to output as `StarGazer.png`.

FNA/SDL discovers the window icon by title-named PNG beside the executable, while raw icon derivatives keep the asset pipeline simple and cross-platform.

`PhysicsWorld` now treats `BeginTick` as the only event-tick owner, validates finite body/query inputs, tracks contacts with sorted current/previous pair buffers, preserves last contact metadata for exits, and keeps live debug snapshots in reusable buffers with capped rendering.

The first gameplay migration exposed agent-review gaps that would scale poorly: next-tick query stamps, O(n^2) contact diffs, invalid values poisoning BEPU, and debug overlays that could silently truncate or allocate every frame.

The default camera is now an explicit ship-local `Chase` mode tracking the physics anchor, with `Follow`, `Orbit`, and `Fixed` kept as named modes; orbit controls report when they consume arrow-key yaw.

Tying the view target to a rotated model bounds center made real translation look like rotation-only movement, and shared arrow keys made camera/ship ownership ambiguous.

`PhysicsWorld.SetBodyMotion` wakes dynamic bodies whenever sim-owned controls apply linear or angular velocity.

BEPU can put idle bodies to sleep; without an explicit wake, ship rotation stayed responsive while translation appeared dead after waiting at launch.

`Simulation` now owns the live `PhysicsWorld`; the player ship and target dummy are physics bodies, render snapshots read physics position/velocity plus sim-owned orientation, and broadside firing uses a physics sweep.

The BEPU migration needed to stop living only in CLI proofs so gameplay, debug overlays, weapons, and benchmarks exercise the same runtime body/event/query path agents will extend.

Sweep results and ordered physics events now include hit owner, collision channel, and response in addition to the `BodyRef`.

Gameplay needs enough metadata to resolve hits without doing backend lookups or guessing which response path produced the hit.

Body spawns and sweep queries now carry `CollisionChannel`, and `PhysicsWorld` filters BEPU sweep hits through `CollisionResponseMatrix`.

Runtime collision behavior needs to use the same channel contract as authored physics assets, otherwise agents would reimplement filters per feature.

Repo workflow now forbids concurrent `dotnet build` / `run` / `publish` commands in one checkout; parallel verification belongs in separate worktrees.

MSBuild apphost and intermediate DLL writes race inside one `obj/` tree, producing false failures that waste agent time.

`PhysicsWorld` now maps BEPU dynamic and static handle families to the same StarGazer `BodyRef` surface, with static snapshots and destroy semantics.

Non-ship physics objects include immobile obstacles, stations, beacons, and environmental colliders; exposing BEPU static handles would split the agent-facing API.

`--bench-physics` now measures BEPU-backed step, query, snapshot, and churn cost separately from the pre-BEPU dense sim benchmark.

Scaling decisions need runtime collision-world numbers before adding pooling, multithreaded stepping, or more body systems.

`PhysicsWorld` now creates bodies through StarGazer-owned spawn/shape records, supports generation-safe body destruction, growable body/event bookkeeping, and named missile sweep queries with ignored bodies.

Future agents need reusable physics primitives and lifecycle behavior before adding many object types, not spike-only helpers capped at 64 bodies.

Physics performance gates now track RID publishes, local runtime smoke, a named SteamDeck-class benchmark profile, and first-pass budgets in `DOC/PHYSICS-PERFORMANCE-GATES.md`.

The physics migration needs measurable platform gates before more BEPU, compound, and debug-overlay complexity lands.

`--compound-slice` proves rigid child hit-zone lookup, detachable module velocity inheritance, breakable fixed attachment events, and cooked collider preview data before real articulated joints.

Detach and hit-zone semantics need stable headless outputs before BEPU constraints make failures harder to inspect.

`--physics-debug-overlay` renders body bounds, query-hit markers, body IDs, bounds, and awake state from the same collision-slice debug snapshot used by the CLI.

Visual physics debugging should consume the tested snapshot/event path, not a second renderer-only interpretation of physics state.

The first collision vertical slice begins as `--collision-slice`, a headless BEPU-backed spawn/sweep/debug-event proof before visual overlays consume the same data.

Ordered body events and debug records need to be stable before rendering them, or visual overlay work will paper over event ordering bugs.

BEPU 2.4.0 is introduced behind `Sim/Physics` with `PhysicsWorld`, `PhysicsSystem`, and converter boundaries rather than exposing BEPU handles to gameplay/render code.

The first runtime spike must prove body creation and missile sweep hits without letting backend types leak into the rest of the game.

Physics authoring now starts as validated `PhysicsAssetDefinition` data with cooked summaries, response matrices, and a capital-ship compound proxy before BEPU runtime bodies exist.

Collider, mass, and response rules need a diffable contract before gameplay systems depend on them.

`Simulation` now publishes the current ship through `BodyPoseSnapshot` and generation-checked `BodyRef` scaffolding before the generic physics body layer is complete.

Render, debug, and scenario code need to migrate to body snapshots incrementally so BEPU/ECS work can land without rewriting every consumer at once.

`--bench-sim` runs a headless pre-BEPU dense-body workload with deterministic hashes and timing/allocation metrics.

The physics migration needs a cheap baseline for body iteration, event buffers, churn, and snapshot publication before final ECS handles or BEPU integration lock in structure.

Current ship behavior parity is captured through `--sim-scenario` headless fixed-tick runs before moving toward generic body physics.

The BEPU/ECS migration needs a fast, windowless baseline for thrust, yaw, roll, brake, and fire behavior so architecture work does not silently change ship feel.

`DOC/PHYSICS-ECS-PLAN.md` now treats rigid compounds, detachable modules, and BEPU-backed joints as separate physics structures with explicit platform gates.

Capital ships need child hit zones, detachable pieces, and possible articulated/docking/tether behavior without leaking BEPU handles or weakening PC/Mac/Linux portability.

The scaling proposal for ships and non-ship physics objects lives in [`DOC/PHYSICS-ECS-PLAN.md`](https://github.com/mechaghost/StarGazer/blob/ b650bf/PHYSICS-ECS-PLAN.md), with BEPU behind a StarGazer-owned body/ECS boundary as the candidate direction.

Large numbers of colliding space objects need real broadphase/collision while gameplay systems still need clear ownership, coordinate boundaries, and agent-friendly extension points.

`AGENTS.md` is the canonical top-level repo instruction file; `CLAUDE.md` is only a compatibility shim that points agents back to it.

Multiple agents will touch StarGazer, and mirrored instruction files would drift as skills and workflow rules change.

Transform, axis, rotation, camera, model-import, weapon-arc, and debug-vector work must use `stargazer-coordinate-conventions` before changing signs or matrices.

Recent roll and firing-arc fixes showed that ad hoc inverse/sign patches drift fast unless future agents identify coordinate spaces and ownership first.

Ship-local right/up basis vectors use the same roll sign as `ShipRenderRotation`, so debug arcs, thrust axes, and weapon gating rotate with the visible ship.

A render/sim sign mismatch made broadside arcs roll opposite the model, which breaks visual trust while testing weapons.

Ship movement, yaw/roll integration, damping, caps, and ship-local basis conversion live in `Sim/ShipPhysics.cs`; `Simulation` coordinates tick order and combat state.

Physics will get tuned often, so agents need one obvious ownership file instead of editing the general sim loop.

Ship state now carries roll orientation/angular velocity; `Z`/`C` and `--roll` rotate the ship around its forward axis and ship-local right/up vectors follow that roll.

Roll needs to affect thrust/debug vectors and broadside posture, not just visually tilt the model.

Agents must terminate existing StarGazer processes before any live run, hot-reload run, or screenshot capture.

Hung FNA/dotnet windows accumulate invisibly and make testing confusing; one fresh process keeps verification and human playtests honest.

The first combat-adjacent slice is a static sim-owned target position with render-side debug lines for forward vector, velocity, target line, range, and bearing.

Target/range/bearing feedback lets movement feel and approach geometry be tested before committing to weapon rules.

Interactive controls use `Shift` for upward thrust and `Space` for brake assist, while `--brake` stays the scripted capture hook.

`Space` reads as a deliberate stop/brake command in this prototype, and `Shift` is easier to hold while combining vertical thrust with WASD.

Ship state now carries yaw orientation/angular velocity, and thrust inputs are interpreted in ship-local axes before becoming world velocity.

The early physics prototype needs momentum to respect where the bow points without jumping to a full six-degree rigid body simulation.

Linear ship movement now integrates velocity from thrust, caps top speed, coasts without drag, and exposes brake assist through `Shift` / `--brake`.

This gives space-like momentum without jumping straight to orbital mechanics or full rigid-body simulation.

Until ship rotation exists, StarGazer treats the default GLB's visible bow direction as world `+Z` and visual right as world `-X`; `W`/`D` move the ship forward/right.

The model's nose faces `+Z` and its visual right side faces `-X`, while the first mappings used XNA-style `-Z` and then world `+X`, making controls feel backward.

`AiPilotSystem` reads completed ship snapshots, advances an owned `SimRng` forked from `SimulationConfig.RunSeed`, and emits movement-only `ShipIntent` for loiter or collision-course scenarios. Combat remains gated by `SimulationConfig.CombatEnabled`; AI has no fire intent in this slice.

The first AI ship needs to exercise the same scalable sim path as the player while keeping deterministic replay and no-combat separation clean.

`Simulation` owns per-ship laser cooldowns, active beam events, enemy ship targeting, and deterministic voxel burn clusters; `--sim-scenario laser-duel` guards player/AI hull life loss. Visual proof: [`screenshots/2026-05-22/225306-laser-duel-glb-voxel-damage-rebased.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/225306-laser-duel-glb-voxel-damage-rebased.jpg).

Beam rendering and voxel hit mapping already existed, but gameplay needed one owner that could connect ship targeting, damage transactions, GLB mesh removal, and HUD life values without render-side state.

The hull-breach voxel box lives in `VoxelDamageDemoPatterns`, and `--voxel-mesh-damage-scenario glb-hull-breach-demo` asserts the same pattern removes GLB triangles without killing the ship.

Programmatic visual states need headless guards so agents can tune camera/rendering without silently drifting the underlying damage scenario.

`--mesh-damage-demo hull-breach` now configures mesh-damage mode, voxel size, camera orbit, selected ship, and a deterministic top-hull damage box. Visual proof: [`screenshots/2026-05-22/223447-mesh-damage-demo-clean.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/223447-mesh-damage-demo-clean.jpg).

Agents need a one-flag live/screenshot state for GLB mesh damage instead of brittle hand-written lists of voxel damage commands.

`--voxel-debug mesh-damage` builds a damageable GLB triangle cache mapped through `ModelToShipVoxelSpace` to cooked voxels, then removes/deforms selected-ship GLB triangles when their owner voxels are damaged. Visual proof: [`screenshots/2026-05-22/221915-glb-mesh-damage-before-rebased.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/221915-glb-mesh-damage-before-rebased.jpg), [`screenshots/2026-05-22/221925-glb-mesh-damage-large-region-rebased.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/221925-glb-mesh-damage-large-region-rebased.jpg).

Voxels should remain the gameplay truth, but the visible ship must preserve the authored GLB silhouette and lose mesh regions instead of becoming visible blocks.

Voxel debug rendering now uses dense asset chunk indices, state-owned per-chunk versions, and persistent chunk-local `DynamicVertexBuffer` meshes that rebuild only when their chunk version changes. Visual proof: [`screenshots/2026-05-22/220315-chunked-voxel-cache-rebased.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/220315-chunked-voxel-cache-rebased.jpg), [`screenshots/2026-05-22/220315-chunked-voxel-dirty-damage-rebased.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/220315-chunked-voxel-dirty-damage-rebased.jpg).

Full per-draw voxel surface rebuilds were fine for proof but wrong for the cornerstone damage system; chunk versions give render a cheap dirty boundary while keeping coordinate conversion owned by `ModelToShipVoxelSpace`.

The voxel debug renderer now emits full-size exposed-face triangle blocks instead of shrunken line-list wire cubes for live hull, damaged cells, core markers, and detached debris. Visual proof: [`screenshots/2026-05-22/215034-connected-voxel-damaged-cell.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/215034-connected-voxel-damaged-cell.jpg), [`screenshots/2026-05-22/215034-connected-voxel-bridge-cut.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/215034-connected-voxel-bridge-cut.jpg), [`screenshots/2026-05-22/215034-glb-connected-voxel-blocks.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/215034-glb-connected-voxel-blocks.jpg).

Wire cubes proved topology but were unreadable as gameplay visuals; exposed faces remove the fake gaps and make voxel damage and splits legible in the live demo.

`ShipVoxelStateStore.Apply` now walks the already-sorted damage command buffer by contiguous target-ship runs and resolves each run through an entity-to-ship index table, instead of scanning every command for every ship. `--voxel-state-scenario command-run-apply` proves 9 commands against 3 ships in a 1,000-ship store produce exactly 3 command runs and 3 affected ships.

Broadside and explosion damage should scale with command runs, not `shipCount * commandCount`. The sorted command buffer already provides target grouping; the store should preserve that shape.

`--voxel-damage-demo line-bridge` configures a fixed camera, synthetic line-bridge voxel fixture, and timed damage commands so live launches show damaged cells, removed voxels, and detached debris markers. Visual proof: [`screenshots/2026-05-22/213643-voxel-demo-damaged-cell.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/213643-voxel-demo-damaged-cell.jpg), [`screenshots/2026-05-22/213643-voxel-demo-first-break.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/213643-voxel-demo-first-break.jpg), [`screenshots/2026-05-22/213643-voxel-demo-bridge-cut.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/213643-voxel-demo-bridge-cut.jpg).

Voxel correctness screenshots were useful, but the working loop needs an obvious live demo for watching damage progress over time.

Interactive launches go through `scripts/run-game`, which builds, kills stale instances, sets `DOTNET_ROOT`, runs from the repo root through a launchd wrapper, submits the native apphost to `launchctl`, and verifies the process stays alive.

Backgrounded `dotnet run` leaves a parent/child process pair and plain `nohup` launches can die when the agent shell session ends; launchd owns the app after command exit, but must be pointed back at the repo root so relative dev paths like `obj/voxel-cache` do not resolve under `/`.

Voxel debris records now include a deterministic ship voxel-local center, and the debug renderer hides removed cells while drawing a magenta debris marker for detached islands. Visual proof: [`screenshots/2026-05-22/211020-voxel-bridge-cut-debris-marker.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/211020-voxel-bridge-cut-debris-marker.jpg).

Debug visuals must reflect live ownership: removed islands are no longer part of the ship, but agents still need a visible marker proving where the split happened.

Scene, HUD, and physics-debug rendering moved out of `Game1.Draw` into `Render/RenderPipeline.cs` (built in `LoadContent`, called per-frame with a `RenderFrame` state struct). `Game1.Draw` shrinks from 162 lines to 11. Visual proof: [`screenshots/2026-05-22/195813-phase0-1-default.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/195813-phase0-1-default.jpg), [`screenshots/2026-05-22/195813-phase0-1-voxel-overlay.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/195813-phase0-1-voxel-overlay.jpg). Phase 0.1 of [`DOC/VISUAL-RENDERING-PLAN.md`](https://github.com/mechaghost/StarGazer/blob/ b650bf/VISUAL-RENDERING-PLAN.md).

The pre-Phase-0 Draw method had become a 162-line dump mixing scene, HUD, and physics-debug rendering; subsequent visual phases (HDR fp16 RT, AGX tonemap, bloom, lens flare, FSR1, PBR, CSM, WBOIT, etc.) need a single seam to layer onto without re-disturbing `Game1`.

Sim scenarios now include `killed-player-input` and `killed-ai-input`, and the voxel suite asserts killed player/AI ships produce zero control wake requests after core destruction.

Debris/kill ownership rules need coverage through runtime input and AI systems, not only metadata on synthetic debris records.

`ShipVoxelStateStore.CoreVoxelAt` exposes immutable core ids without allocating detailed state, and `Simulation.TryQueueCoreDamage` uses it so promotion happens only when the queued damage applies.

Debug and scripted damage need asset metadata, but metadata reads should not defeat aggregate fleet LOD before the damage transaction actually lands.

`aggregate-invalid-no-promotion` proves invalid damage against an aggregate fleet ship counts as a no-op without allocating detailed voxel state, and empty damage applies reset command-run counters.

Fleet-scale LOD only works if debug, benchmark, and combat misses do not accidentally promote far ships into detailed HP/alive/BFS arrays.

`--bench-voxels` now reports topology scan voxels, max dirty ships per tick, dirty-ship cap, full-BFS work caps, and cap-overflow ticks; `fleet-lod-1000` uses the real `ShipVoxelStateStore` aggregate/promotion path instead of preallocating detailed state for every ship.

Voxel splitting performance needs real per-tick topology and LOD signals before the pending-topology queue exists, or scale regressions can hide behind aggregate totals and synthetic counters.

`ShipVoxelState.ApplyDamageBatch` now resolves a topology split before later commands in the same ship run, and `ShipVoxelStateStore.Apply` counts only non-noop runs as affected. `store-same-tick-detach` proves a later same-tick hit against a detached island is ignored through the real buffer/store path.

The damage transaction path must match gameplay ownership rules: once an island detaches from the core, later commands in that ordered run cannot keep damaging it as live ship hull.

Sim scenario output now reports `VOXEL_SHIPS count=<n> detailed=<n> aggregate=<n> detailed_cap=<n>`, and CLI runs can set `--detailed-voxel-cap`. The voxel suite includes a runtime cap-report gate with five ships, two detailed slots, and three aggregate slots.

Agents need a direct headless signal that fleet LOD caps are active in the real simulation, not only in synthetic state runners and benchmark counters.

`--voxel-state-scenario detailed-scale-ladder` now creates 1, 10, and 100 fully detailed voxel ships, applies one deterministic damage command per ship, and verifies every detailed state is affected exactly once. The aggregate voxel suite includes this state scale ladder.

Fleet LOD proves far ships can stay aggregate, but combat tuning also needs a clean headless ladder for fully detailed ships before broadside/explosion command volumes rise.

`ShipVoxelStateStore` can now register ships as aggregate-only slots without allocating dense HP/alive/topology arrays, then promote a slot to detailed state when damage/debug access needs it. `--voxel-state-scenario fleet-lod-promotion` proves a 1,000-ship store starts with 64 detailed and 936 aggregate slots, then damage to one aggregate ship promotes exactly that ship and applies voxel damage.

The game needs hundreds or thousands of physics objects, but only selected/combat-near ships should carry detailed voxel state. This gives the sim an explicit ownership boundary for fleet LOD without changing default gameplay, which still uses detailed state unless a cap/scenario opts in.

`--voxel-hit-scenario empty-crossing-no-alloc` now runs a sparse-grid DDA through empty voxel cells before hitting a live cell, repeats the query 2,000 times, and requires `alloc_bytes=0`. The aggregate voxel suite includes this hit-mapping gate.

Capital ships will be sparse and beams can traverse long empty spans before hitting damage cells. The hot path must stay bounded and allocation-free before weapon volume increases.

Beam fire now uses BEPU only to identify the hit ship body, then maps the original weapon ray into that ship's voxel-local axes and runs `VoxelHitMapper` DDA against the ship's asset-owned coord lookup. The first alive voxel hit receives a deterministic `DamageCommand` in the same fixed sim tick. Headless proof: `--voxel-hit-scenario starboard|port|forward|aft|up|down|outside-clip|scaled-voxel-size` and `--sim-scenario broadside-ai-voxel-hit`. Visual proof: [`screenshots/2026-05-22/voxel-beam-hit-ai-cavity-visible.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/voxel-beam-hit-ai-cavity-visible.jpg).

Voxel damage has to come from actual weapon rays, not hand-entered voxel ids. Keeping BEPU at the coarse-body layer preserves the one-body-per-ship scaling rule while DDA gives deterministic, allocation-free per-voxel targeting.

`--voxel-debug` now cooks the selected GLB into an immutable voxel asset only for explicit debug runs, passes that asset into `SimulationConfig`, and renders voxel debug cells from `ShipVoxelDefinition.LocalCenter` and `ShipVoxelAsset.VoxelSize` instead of a ship-radius placeholder scale. The HUD now reports selected-ship voxel count and voxel size. Visual proof: [`screenshots/2026-05-22/voxel-glb-density-035.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/voxel-glb-density-035.jpg).

The previous runtime overlay used the synthetic 27-cell cube and a radius-derived display scale, which made the voxel system look much coarser than the GLB cook actually supports. Explicit debug cooking keeps normal gameplay startup free of GLB voxelization while giving us honest density proof for damage-cell iteration.

`scripts/hooks/pre-push` now captures Git's pre-push ref list, keeps the existing build gate, runs `git lfs fsck`, and delegates to `git lfs pre-push` so referenced screenshot LFS objects upload before Git refs move. The StarGazer commit/push skill now explicitly requires LFS fsck and a one-time `git lfs push --all` after LFS migrations or missing-object incidents.

`core.hooksPath=scripts/hooks` replaces Git LFS's default `.git/hooks/pre-push` hook. That let Git commits containing screenshot pointer files reach GitHub while the binary LFS objects stayed only in the local checkout, causing fresh clones to fail during smudge with 404 missing-object errors.

Runtime body creation records owned BEPU shape indices and removes them during `DestroyBody`, without exposing `TypedIndex` outside `PhysicsWorld`.

Spawn/despawn churn should release backend shape bookkeeping while preserving the StarGazer `BodyRef` API boundary.

Render architecture is HDR fp16 forward with MRT (color + velocity + normals), AGX tonemap, SMAA 1x, FSR1 spatial upscale, COD mip-chain bloom, screen-space lens flare and god rays, per-biome 3D LUT color grading, CSM shadows, Karis split-sum IBL, WBOIT for transparents, hardware-instanced particles. All shaders authored as HLSL SM3, compiled to `.fxb` via FXC and translated by MojoShader. Full plan and phasing: [`DOC/VISUAL-RENDERING-PLAN.md`](https://github.com/mechaghost/StarGazer/blob/ b650bf/VISUAL-RENDERING-PLAN.md).

FNA's Effect API caps at Shader Model 3 with no compute/geometry/tessellation, so the renderer must be built from pixel/vertex passes only; targeting Steam Deck (1.6 TFLOPS RDNA2, 1280×800) forces tight per-pass budgets and rules out TAA, FSR 2/3, and Forward+. This stack is the cheapest path to a modern look that survives all four supported backends (D3D11 + SDL_GPU → D3D12/Vulkan/Metal).

Runtime screenshots can now enable `--voxel-debug overlay|voxel-only`; the selected ship renders a wire voxel debug view and the HUD reports live/dead/debris/killed voxel counts. Visual proof: [`screenshots/2026-05-22/191719-voxel-debug-overlay.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/191719-voxel-debug-overlay.jpg), [`screenshots/2026-05-22/191930-voxel-single-damage.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/191930-voxel-single-damage.jpg), and [`screenshots/2026-05-22/191749-voxel-core-kill.jpg`](https://github.com/mechaghost/StarGazer/blob/ b650bf/screenshots/2026-05-22/191749-voxel-core-kill.jpg).

Voxel topology and core death need visible proof in the running game before combat hit mapping and chunked mesh rendering build on top.

`Simulation` now creates a voxel state for every player/AI ship, queues scripted voxel damage through a deterministic `DamageCommandBuffer`, applies sorted batches in a voxel damage phase, and exposes `--damage-voxel`, `--damage-local`, and `--destroy-core` through `--sim-scenario`.

Voxel damage has to exercise the same sim-owned ship lifecycle as movement, AI, weapons, and hashes before render overlays or combat hit mapping can be trusted.

Voxel cooks now guard triangle/lookup budgets before large allocations, `VoxelCookOptions.Default` uses explicit nonzero values, voxel CLI gates set failure exit codes, and `--voxel-test-suite` covers all 12 planned benchmark profiles including startup-cache, fleet LOD, and thread-repeat.

Runtime voxel wiring needs trustworthy automated gates; false determinism claims, zero-default cook options, or unbounded pre-validation allocations would hide the next real scaling bugs.

`--voxel-test-suite` aggregates deterministic hashes from test names, pass/fail state, final result lines, and explicit `hash=0x...` tokens instead of timing-bearing benchmark text.

Performance output should still show elapsed/p95/p99 metrics, but those values cannot participate in repeatable scenario hashes.

`ShipVoxelState` now records all live non-core hull voxels as one deterministic debris record when the core is destroyed, and the destruction scenario gate requires that ownership boundary.

A killed ship must stop exposing live controllable/targetable voxels even when the final hit destroys only the core cell.

Engine-facing behavior is split by responsibility into named system classes, with `Game1` reserved for lifecycle/wiring and CLI/debug paths for programmatic control.

AI agents need obvious search targets and small ownership boundaries to extend camera, input, rendering, and sim systems without scattering behavior through the game loop.

Default perspective camera far plane is 10x the original bounds-derived distance, while `--camera-far` remains the explicit override.

Space scenes need more draw-distance headroom than the first ship-framing camera; making the default deeper avoids clipping future world/grid/ship content during orbit inspection.

Ship orbit inspection is `CameraMode.Orbit` in `Camera.cs`, controlled interactively by keyboard/gamepad and reproducibly by `--camera orbit --camera-yaw --camera-pitch --camera-distance`.

Orbiting is a viewing tool, not simulation state; keeping it render-side preserves determinism while letting agents and humans inspect ships from exact angles.

Perspective camera logic lives in `Camera.cs` outside `Sim/`, with default follow mode and CLI-addressable fixed mode via `--camera`, `--camera-pos`, `--camera-target`, and lens flags.

Agents need a fast, scriptable way to frame screenshots without polluting deterministic simulation or adopting a heavy camera/scene library.

Ship movement verification uses a static world-space grid plus `--thrust x,y,z` scripted input for deterministic screenshot captures.

The camera follows the ship, so motion needs a fixed reference frame and a non-manual way to drive movement during `--screenshot` runs.

Project skills live under `.agents/skills`; solo work commits to `main`, while parallel worktree agents commit to their current branch and never switch branches during commit.

Codex agents need one visible skill home, and parallel work needs branch isolation without weakening the small-commit solo workflow.

FNA copied into the repo as vendored source under `FNA/` — recursive submodules pulled, then every `.git` directory stripped. No submodule, no upstream link, no contribute-back.

User wants full ownership of the runtime — returning to indie roots from XNA days, ability to patch FNA source directly without coordinating upstream. The MIT / MS-PL licenses are preserved under `FNA/licenses/` and `FNA/lib/*/LICENSE` for Steam release.

Model render path uses `RasterizerState.CullClockwise`. Reference capture after fix: [`screenshots/2026-05-21/191500-spaceship-glb-winding-fixed.jpg`](https://github.com/mechaghost/StarGazer/blob/ 517140/screenshots/2026-05-21/191500-spaceship-glb-winding-fixed.jpg). Captures with the bug for comparison: [`190700-spaceship-glb-first-render.jpg`](https://github.com/mechaghost/StarGazer/blob/ 517140/screenshots/2026-05-21/190700-spaceship-glb-first-render.jpg) (inside-out — outer hull culled, interior cavity walls visible).

The glTF spec winds front-facing triangles counter-clockwise when viewed from outside the surface. FNA's `Matrix.CreateLookAt` + `Matrix.CreatePerspectiveFieldOfView` are right-handed, which preserves that CCW winding all the way into NDC. Setting `CullCounterClockwise` therefore culls the *front* faces and leaves the *back* faces drawn — the entire ship rendered inside-out. `CullClockwise` correctly culls the backfaces and shows the hull from outside.

[`GlbLoader.cs`](https://github.com/mechaghost/StarGazer/blob/ 517140/GlbLoader.cs) now extracts POSITION + NORMAL into FNA's stock `VertexPositionNormalTexture` (dummy UVs) and computes an AABB-derived `BoundingSphere` for camera framing. [`Game1.cs`](https://github.com/mechaghost/StarGazer/blob/ 517140/Game1.cs) loads `Content/models/spaceship.glb` on startup (or whatever `--model <path>` points at), renders it via `BasicEffect.EnableDefaultLighting()` on a depth-buffered `RenderTarget2D`, with the camera placed at `bounds.Center + (0.6, 0.45, 1.0) * radius * 1.7` looking at `bounds.Center`. When no model loads (file missing), falls back to the "HELLO, STARGAZER" text. First successful capture: [`screenshots/2026-05-21/190700-spaceship-glb-first-render.jpg`](https://github.com/mechaghost/StarGazer/blob/ 517140/screenshots/2026-05-21/190700-spaceship-glb-first-render.jpg).

The GLB loader has existed since the scaffold but nothing rendered. To turn "loads geometry" into "shows a ship" we needed lighting (flat-white silhouette is unverifiable), which needed normals, which forced a vertex-format upgrade from `VertexPositionColor` to `VertexPositionNormalTexture`. `BasicEffect` is FNA's built-in fixed-function-style effect — zero HLSL to ship, zero asset pipeline, "looks 3D" for free. Bounding-sphere framing makes the camera auto-frame any GLB the user drops in, so `--model <path>` is genuinely useful instead of requiring per-model camera tuning. The `--model` flag itself is the programmatic-control tenet applied — any ship reachable from the command line without recompiling.

The game renders the scene to an offscreen `RenderTarget2D` matching backbuffer dimensions, then composites that target to the backbuffer for display. A `--screenshot <path>` CLI flag triggers `RenderTarget2D.SaveAsJpeg` after the second rendered frame and then `Exit()`. JPEG quality is controlled by the `FNA_GRAPHICS_JPEG_SAVE_QUALITY` env var (default 82 → ~20–150KB at 1280×720). Screenshots are saved under [`screenshots/YYYY-MM-DD/HHMMSS-<slug>.jpg`](https://github.com/mechaghost/StarGazer/blob/ 517140/screenshots/) and tracked in git as the visual changelog. First verified capture: [`screenshots/2026-05-21/184910-hello-world-first-capture.jpg`](https://github.com/mechaghost/StarGazer/blob/ 517140/screenshots/2026-05-21/184910-hello-world-first-capture.jpg).

Implements the screenshot half of the [programmatic-control tenet](https://github.com/mechaghost/StarGazer/blob/ 517140/DESIGN-LOG.md) — the game itself is the screenshot source, no external tools, no OS permission gates, no app-resolver friction, identical behavior on Win/Mac/Linux. Render-to-target is also the foundation for any post-processing later (bloom, color grading, tonemapping, UI compositing) — paying that architectural cost now is cheaper than retrofitting after gameplay landed.

Text rendering uses `FontStashSharp.PlatformAgnostic` 1.5.5 (NuGet) plus a hand-written `FnaFontRenderer` / `FnaTexture2DManager` in [`FnaFontRenderer.cs`](https://github.com/mechaghost/StarGazer/blob/ 517140/FnaFontRenderer.cs) that implements FontStashSharp's `IFontStashRenderer` and `ITexture2DManager` interfaces against FNA's `SpriteBatch` and `Texture2D`. First font shipped: JetBrains Mono Regular (OFL 1.1) under `Content/fonts/`.

PlatformAgnostic has no XNA/MonoGame transitive dependency, so it composes cleanly with vendored FNA. The ~70-line custom renderer is the price of using vendored FNA instead of NuGet — small, understandable, owned by us, no version drift. FontStashSharp does runtime TTF rasterization, so we can swap typefaces (or add weights/sizes) without a content build step.

First-pass "Hello World" is delivered via the window title (`Window.Title = "StarGazer — Hello, World"`), not via on-screen text rendering. Choice of text rendering library is deferred until UI requirements are concrete.

Attempted to wire `FontStashSharp.XNA` 1.5.5 — it only targets .NET Framework 4.8 and the NuGet fallback dragged in the original Microsoft XNA reference assemblies (`PublicKeyToken=842cf8be1de50553`), producing CS0433 type-conflict errors against our vendored FNA (`FNA, Version=26.5.0.0`). `FNA.NET.FontStashSharp` would conflict in the reverse direction (depends on a separate `FNA.NET` NuGet package incompatible with our vendored source). The clean path exists — `FontStashSharp.PlatformAgnostic` + a custom ~80-line `IFontStashRenderer2` adapter against FNA's SpriteBatch — but that's a focused workstream, not scaffold-verification work. Choosing a font library before knowing whether we need kerned vector text, pixel-style bitmap fonts, rich text, or localization would lock in the wrong tool.

All meaningful design and code decisions get logged under `DOC/DESIGN-LOG.md` and `DOC/CODE-LOG.md` via the `stargazer-docs` skill.

Vibe-coded projects lose decision reasoning between sessions because the user didn't physically type the code. The log is the durable memory the future-us reads first when reopening the repo.

Commits land directly on `main`; no branches, no PRs. The `stargazer-commit-push` skill automates commit + push at every coherent unit of work.

Solo developer, no team to coordinate. Multi-machine work (Windows + Mac travel) needs frequent pushes to avoid stranded uncommitted state. Always-green main + small commits gives natural rollback points.

Add `SharpGLTF.Core` 1.0.6 as a NuGet PackageReference, with a thin `GlbLoader` adapter bridging glTF mesh data to FNA's `VertexBuffer`/`IndexBuffer`.

Canonical .NET glTF library, actively maintained, pure managed code (no native deps). Small utility scope — NuGet is appropriate here. The vendor-source rule is strongest for framework-level deps like FNA, not for utilities.

Per-platform native libraries (SDL3, FNA3D, FAudio, libtheorafile, D3D12 Agility SDK) live under `runtimes/win-x64/native/`, `runtimes/linux-x64/native/`, `runtimes/osx/native/`. The csproj uses RID-aware MSBuild conditions to copy the right set into the output directory.

Idiomatic .NET layout. Honors `dotnet publish -r <rid>` for cross-platform publishing while falling back to the host RID for `dotnet run`. The D3D12 Agility SDK folder structure is preserved on Windows because FNA3D refuses to load it otherwise.

Modern FNA's SDL3 platform layer is used. Only SDL3 native binaries are shipped; SDL2 is treated as deprecated even though FNA's source still includes both bindings.

This is what current `fnalibs-dailies` ships (no SDL2 binary in 2026 builds). FNA auto-detects the available platform at runtime and prefers SDL3. SDL3 has better controller, HiDPI, and Wayland support — all relevant for SteamDeck and Mac.

All projects target `net8.0`.

Current LTS, fully cross-platform, native ARM64 on Apple Silicon, no Mono dependency. FNA's `FNA.Core.csproj` already targets net8.0 so we inherit cleanly.