docs: panopticon auto-update for snow_trail

.pi/skills/panopticon/SKILL.md

@@ -21,4 +21,4 @@ Pure Rust retro-aesthetic 3D game using SDL3 windowing, wgpu rendering, and rapi
 
 - [Structure](structure.md) — modules, types, data flow, dependencies
 - [Guide](guide.md) — conventions, patterns, anti-patterns, testing
-- [Changelog](changelog.md) — recent changes, active areas, stability
+- [Changelog](changelog.md) — recent changes, active areas, stability

.pi/skills/panopticon/changelog.md

@@ -1,25 +1,32 @@
 # Changelog
 
-*Last updated: Friday, April 3, 2026*
+*Last updated: Tuesday, April 7, 2026*
 
 ## Active Areas
 
 | Area | Changes (30d) | Status |
 |------|---|---|
-| Main loop & systems | 9 churn | Active — intent-based architecture solidifying |
+| Main loop & systems | 9 churn | Active — explicit storage parameters |
 | Dialog system | 10 churn | Active — projectiles, camera, rendering |
 | Render core | 15 churn | Active — text pipeline, font atlas, globals |
 | World state | 8 churn | Active — intent storage, component management |
 | Player mechanics | 6 churn | Stable — character bundle, player states |
 | Shader system | 4 churn | Active — gizmo lines, dissolve, snow light |
+| Content pipeline | 1 churn | New — Blender export addon |
 
 ## Recent Changes
 
+### System Signature Refactor (Major)
+- **Completed**: All 16 systems refactored to take explicit `Storage<T>` parameters instead of `&World`/`&mut World`.
+- **Pattern**: Functions receive only storages they need (e.g., `camera_follow_system` takes `&Storage<FollowComponent>`, `&Storage<CameraComponent>`, `&mut Storage<Transform>`).
+- **Benefit**: Explicit data dependencies improve borrow checker clarity and code readability.
+- **Main loop** (`src/main.rs`): Updated to pass individual storage fields at call sites rather than whole `World` reference.
+- **Affected systems**: `camera_input_system`, `camera_intent_system`, `camera_follow_system`, `camera_noclip_system`, `camera_ground_clamp_system`, `dialog_camera_transition_system`, `dialog_camera_system`, `player_input_system`, `physics_sync_system`, `render_system`, `particle_intent_system`, `particle_update_system`, `trigger_system`, `dialog_system`, `dialog_projectile_system`, all state machines.
+
 ### Intent-Based Architecture
-- **Completed major refactor** (3 weeks ago): Systems now communicate through one-frame `Storage<T>` intents instead of direct function calls.
+- **Completed major refactor** (3 weeks ago): Systems communicate through one-frame `Storage<T>` intents instead of direct function calls.
-- **Intent types**: `FollowPlayerIntent`, `StopFollowingIntent`, `CameraTransitionIntent`, `SpawnParticleIntent`
+- **Intent types**: `FollowPlayerIntent`, `StopFollowingIntent`, `CameraTransitionIntent`, `SpawnParticleIntent`.
 - **Consumer pattern**: Systems read intents from world storage, act on them, then remove them. Producers don't import consumer modules.
-- **Documented pattern** in `docs/intent-based-architecture.md` with full execution order contract.
 
 ### Dialog System Suite
 - **Dialog state machine**: Ink-based story progression with display timer, projectile phases, parry mechanics.
@@ -33,51 +40,58 @@
 - **Vertex-based text**: Custom `TextVertex` (position, UV) fed into dedicated text pipeline with view-proj uniform.
 
 ### Particle System
-- **Intent-driven spawning**: `SpawnParticleIntent` queues particle emissions; `particle_intent_system` transfers into persistent `ParticleBuffers`.
+- **Intent-driven spawning**: `particle_intent_system` reads `spawn_particle_intents` Vec, transfers configs into persistent `ParticleBuffers`.
 - **Configurable emitters**: Burst count, lifetime range, speed range, directional spread (cone), gravity, size range, color gradient.
-- **Snow particle integration**: Spawned continuously at camera position for screen-fill effect.
+- **Snow particle integration**: Spawned continuously at camera position for screen-fill effect; `spawn_snow_particles` adds particles to `ParticleBuffers`.
 
 ### Render Pipeline
-- **Global renderer via thread-local**: `render::global` module centralizes `Device`/`Queue` access for loaders and systems; long-term goal is explicit `RenderContext` params.
+- **Global renderer via thread-local**: `render::global` module centralizes `Device`/`Queue` access for loaders and systems.
-- **Gizmo shader**: Fragment shader outputs world-normal as axis color (X=red, Y=green, Z=blue) for entity transform editing.
+- **Draw call generation**: `render_system` reads `entities`, `transforms`, `meshes`, `dissolves` storages; generates `DrawCall` per visible entity.
-- **Snow light accumulation**: Persistent texture tracking deformation; blue-noise dithering maps snow brightness into tile pattern (brightness > threshold → dither step).
+- **Gizmo shader**: Fragment shader outputs world-normal as axis color (X=red, Y=green, Z=blue).
+- **Snow light accumulation**: Persistent texture tracking deformation; blue-noise dithering maps snow brightness into tile pattern.
 - **Dissolve shader**: Blue-noise masked alpha cutoff; controlled by `enable_dissolve` uniform.
 
 ### Tree Occlusion & Instances
-- **Tree dissolve system**: Per-instance dissolve amounts lerp toward targets at configurable speed.
+- **Tree dissolve system**: Per-instance dissolve amounts lerp toward targets; updated via `tree_occlusion_system` which reads player transforms and cameras.
-- **Occlusion detection**: Instances between camera and player dissolve based on perpendicular distance to camera-to-player ray.
+- **Instance buffer sync**: `tree_instance_buffer_update_system` syncs dissolve state changes to GPU buffer after state updates.
-- **Instance buffer sync**: Tree instances updated into GPU buffer after dissolve state changes.
 
 ### Trigger & Event Flow
-- **Sphere-based triggers**: Continuous state tracking (Idle ↔ Inside); fires `TriggerEvent` with `Entered`/`Exited` kinds.
+- **Sphere-based triggers**: `trigger_system` runs each fixed step; reads `triggers`, `transforms`, `player_tags` storages; fires `TriggerEvent` with `Entered`/`Exited` kinds.
 - **Activation filtering**: `TriggerFilter::Player` specifies which entity types can activate.
-- **Event queue**: Events collected in `world.trigger_events` and consumed by dialog system to spawn bubbles.
+- **Event queue**: Events collected in `world.trigger_events` and consumed by `dialog_system` to spawn bubbles.
 
 ### Player State Machine
 - **State hierarchy**: Idle, Walking, Jumping, Falling, Leaping (dash), Rolling.
+- **Physics per-state**: `state_machine_physics_system` applies damping on enter (Idle), horizontal input application (Walking), vertical velocity control (Jumping).
 - **Transition logic**: Grounded checks, input presence, airtime duration.
-- **Physics per-state**: Damping on enter (Idle), horizontal input application (Walking), vertical velocity control (Jumping).
 
 ### Editor & Inspector
 - **Dear ImGui integration**: Inspector window with player state display, entity transform gizmos.
-- **Entity selection**: Right-click picking; gizmo renders for selected entity when editor active.
+- **Entity selection**: Right-click picking calls `picking::pick_entity` with ray; gizmo renders for selected entity when editor active.
 - **UI mode gating**: Systems check `editor.wants_keyboard()`/`wants_mouse()` to suppress game input during inspector focus.
 
+### Blender Export Addon
+- **Plugin**: `blender/addons/snow_trail_export.py` provides one-click glTF + EXR export from Blender 5.0.
+- **glTF operator** (`SNOWTRAIL_OT_export_gltf`): Exports selected mesh objects to `assets/meshes/{blend_filename}.gltf` with configurable modifiers, vertex colors, materials.
+- **Heightmap bake operator** (`SNOWTRAIL_OT_export_heightmap`): Calls `generate_heightmap.py` to bake terrain Z-position as 32-bit EXR to `assets/textures/terrain_heightmap.exr` (1024px default).
+- **UI panel**: "Snow Trail" category in 3D viewport; auto-discovers project root by walking directory tree until `assets/` and `blender/` found.
+
 ## Stability
 
 | Area | Last Changed | Status |
 |---|---|---|
 | Physics manager | 80+ days | Stable |
-| Camera follow | 30 days | Stable — intent system reduced coupling |
+| Camera follow | 30 days | Stable — now takes explicit storage params |
 | Movement component | 30+ days | Stable |
 | Mesh loader | 30+ days | Stable |
-| Spotlight sync | 30 days | Stable |
+| Spotlight sync | 30 days | Stable — explicit storage params applied |
-| State machine physics | 30 days | Stable — core transitions unchanged |
+| State machine physics | 30 days | Stable |
 | Debug colliders | 30+ days | Stable |
+| System signatures | New | Stable — refactor complete, no behavioral changes |
 
 ## Open Threads
 
-- **Global renderer thread-local**: Marked for gradual migration to explicit `RenderContext` parameters on systems/loaders. Current implementation works; refactor is low-priority.
+- **Global renderer thread-local**: Marked for gradual migration to explicit `RenderContext` parameters on systems/loaders.
-- **Text rendering completeness**: Font atlas + text pipeline in place; scaling and color support functional. No known issues.
+- **Dialog parry mechanics**: Gameplay tuning (PARRY_WINDOW_RADIUS, HIT_RADIUS) ongoing.
-- **Dialog parry mechanics**: Projectile system complete; integration with Ink outcomes working. Gameplay tuning (PARRY_WINDOW_RADIUS, HIT_RADIUS) ongoing.
+- **Tree occlusion performance**: Occlusion system runs every frame; no visibility culling yet. Scalability unknown for >100 trees.
-- **Tree occlusion performance**: Occlusion system runs every frame; no visibility culling yet. Scalability unknown for >100 trees.
+- **Heightmap bake normalization**: Exported EXR uses raw Z-coordinate; game may need per-level scale application.

.pi/skills/panopticon/guide.md

@@ -42,16 +42,24 @@ pub struct CameraTransitionIntent {
 }
 
 // systems/camera.rs - consumer
-pub fn camera_intent_system(world: &mut World) {
+pub fn camera_intent_system(
-    let transition_entities: Vec<EntityHandle> = world.camera_transition_intents.all();
+    follow_player_intents: &mut Storage<FollowPlayerIntent>,
+    stop_following_intents: &mut Storage<StopFollowingIntent>,
+    camera_transition_intents: &mut Storage<CameraTransitionIntent>,
+    follows: &mut Storage<FollowComponent>,
+    transforms: &mut Storage<Transform>,
+    cameras: &mut Storage<CameraComponent>,
+    player_tags: &Storage<()>,
+    camera_transitions: &mut Storage<CameraTransition>,
+) {
+    let transition_entities: Vec<EntityHandle> = camera_transition_intents.all();
     for entity in transition_entities {
-        let duration = world
+        let duration = camera_transition_intents
-            .camera_transition_intents
             .get(entity)
             .map(|i| i.duration)
             .unwrap_or(0.5);
-        start_camera_transition(world, entity, duration);
+        start_camera_transition(camera_transitions, transforms, cameras, entity, duration);
-        world.camera_transition_intents.remove(entity);  // consumed
+        camera_transition_intents.remove(entity);
     }
 }
 ```
@@ -135,18 +143,17 @@ state_machine.add_transition::<IdleState, WalkingState>(move |world| {
 
 ```rust
 // systems/spotlight_sync.rs
-pub fn spotlight_sync_system(world: &World) -> Vec<Spotlight> {
+pub fn spotlight_sync_system(spotlights: &Storage<SpotlightComponent>, transforms: &Storage<Transform>) -> Vec<Spotlight> {
-    let mut spotlights = Vec::new();
+    let mut result = Vec::new();
-    for entity in world.spotlights.all() {
+    for entity in spotlights.all() {
-        // Closure captures immutably—safe to call multiple times
+        if let Some(spotlight_component) = spotlights.get(entity) {
-        if let Some(spotlight_component) = world.spotlights.get(entity) {
+            if let Some(transform) = transforms.get(entity) {
-            if let Some(transform) = world.transforms.get(entity) {
                 let position = transform.position + spotlight_component.offset;
-                spotlights.push(Spotlight::new(position, ..));
+                result.push(Spotlight::new(position, ..));
             }
         }
     }
-    spotlights
+    result
 }
 
 // With mutation
@@ -155,25 +162,46 @@ world.movements.with_mut(entity, |movement| {
 });
 ```
 
-### System Function Signature
+### System Function Signature (Explicit Storage Parameters)
-**Why**: Pass only the storages (or immutable `World`) that the system needs. Makes data dependencies explicit.
+**Why**: Pass only the specific storages (or read-only `&World`) that the system needs. Makes data dependencies explicit for the reader and borrow checker. **This is the standard pattern—all systems follow this.**
 
 ```rust
 // Good: explicit dependencies
-pub fn camera_follow_system(world: &mut World) {
+pub fn camera_follow_system(
-    let camera_entities: Vec<_> = world.follows.all();
+    follows: &mut Storage<FollowComponent>,
+    cameras: &Storage<CameraComponent>,
+    transforms: &mut Storage<Transform>,
+) {
+    let camera_entities: Vec<_> = follows.all();
     for camera_entity in camera_entities {
-        // Access what's needed
+        if let Some(follow) = follows.get(camera_entity) {
-        if let Some(follow) = world.follows.get(camera_entity) {
+            if let Some(camera) = cameras.get(camera_entity) {
-            world.transforms.with_mut(camera_entity, |t| {
+                transforms.with_mut(camera_entity, |t| {
-                t.position = target_position + new_offset;
+                    t.position = follow.target_position + new_offset;
-            });
+                });
+            }
         }
     }
 }
 
-// For read-only systems
+// Read-only system
-pub fn spotlight_sync_system(world: &World) -> Vec<Spotlight> { .. }
+pub fn spotlight_sync_system(spotlights: &Storage<SpotlightComponent>, transforms: &Storage<Transform>) -> Vec<Spotlight> { .. }
+
+// Dialog system example
+pub fn dialog_system(
+    entities: &mut EntityManager,
+    trigger_events: &[TriggerEvent],
+    dialog_sources: &Storage<DialogSourceComponent>,
+    bubble_tags: &mut Storage<()>,
+    dialog_bubbles: &mut Storage<DialogBubbleComponent>,
+    transforms: &mut Storage<Transform>,
+    names: &mut Storage<String>,
+    player_tags: &Storage<()>,
+    projectile_tags: &mut Storage<()>,
+    dialog_projectiles: &mut Storage<DialogProjectileComponent>,
+    dialog_outcomes: &mut Vec<DialogOutcomeEvent>,
+    delta: f32,
+) { .. }
 ```
 
 ### Default Trait for Configuration Components
@@ -227,14 +255,14 @@ fn system_a(world: &mut World) {
 **Do this instead:**
 ```rust
 // ✅ Good: intent in queue, flat pipeline
-pub fn system_a(world: &mut World) {
+pub fn system_a(cameras: &mut Storage<CameraComponent>) {
-    world.some_intents.insert(entity, MyIntent { .. });
+    cameras.insert(entity, CameraTransitionIntent { .. });
 }
 
-pub fn system_b(world: &mut World) {
+pub fn system_b(camera_transitions: &mut Storage<CameraTransition>) {
-    for entity in world.some_intents.all() {
+    for entity in camera_transitions.all() {
         // process
-        world.some_intents.remove(entity);
+        camera_transitions.remove(entity);
     }
 }
 ```
@@ -273,46 +301,24 @@ use crate::physics::PhysicsManager;
 let velocity = *PhysicsManager::with_rigidbody_mut(..);
 ```
 
-### Global or Context-Based Component Queries
-**Don't do this:**
-```rust
-// ❌ Bad: loses intent, repeats queries
-for entity in world.meshes.all() {
-    if let Some(mesh) = world.meshes.get(entity) { .. }
-}
-for entity in world.meshes.all() {
-    if let Some(mesh) = world.meshes.get(entity) { .. }
-}
-```
-
-**Do this instead:**
-```rust
-// ✅ Good: query once, iterate clearly
-let entities: Vec<_> = world.meshes.all();
-for entity in entities {
-    if let Some(mesh_comp) = world.meshes.get(entity) {
-        // process
-    }
-}
-```
-
 ### Overly Generic (World/&mut World) Parameters
 **Don't do this:**
 ```rust
-// ❌ Bad: implicit dependencies
+// ❌ Bad: implicit dependencies, breaks borrow checker
-fn update_position(world: &mut World, entity: EntityHandle) {
+pub fn camera_follow_system(world: &mut World) {
-    // What do we actually need?
+    // What storages do we actually need?
 }
 ```
 
 **Do this instead:**
 ```rust
-// ✅ Good: explicit dependencies
+// ✅ Good: explicit, focused dependencies
-fn update_position(
+pub fn camera_follow_system(
+    follows: &mut Storage<FollowComponent>,
+    cameras: &Storage<CameraComponent>,
     transforms: &mut Storage<Transform>,
-    entity: EntityHandle,
 ) {
-    transforms.with_mut(entity, |t| t.position.y += 1.0);
+    // Clear what data is needed
 }
 ```
 
@@ -351,4 +357,6 @@ cargo test -- --nocapture  # Show output
 - See **CLAUDE.md** in project root for authoritative style rules (no inline comments, doc comments for public APIs only)
 - See **docs/self-gating-systems.md** for detailed intent-based pipeline patterns
 - See `src/states/player_states.rs` for canonical State impl examples
-- See `src/bundles/player.rs` for complete Bundle pattern with state machine setup
+- See `src/bundles/player.rs` for complete Bundle pattern with state machine setup
+- See `src/systems/camera.rs` for canonical system function signatures with explicit storage parameters
+- See `src/systems/dialog_system.rs` for complex multi-storage system example

.pi/skills/panopticon/structure.md

@@ -25,16 +25,16 @@ Component types define entity data. Key storages:
 Per-entity state machine: `StateMachine` holds current `TypeId`, registered state types, and transitions. `State` trait defines lifecycle (`on_enter`, `on_physics_update`, `on_exit`). Transitions are condition predicates checked each update. Player entity uses this for locomotion states.
 
 ### `src/systems/`
-Flat list of update functions called in main loop. No cross-system coupling; all communication via world state and intents.
+Flat list of update functions called in main loop. Systems receive specific storage parameters (e.g., `&mut Storage<Transform>`, `&Storage<PhysicsComponent>`) instead of `&World`/`&mut World`. This makes data dependencies explicit for both borrow checker and reader. No cross-system coupling; all communication via world state and intents.
-- **Camera**: `camera_input_system` → generates intents; `camera_intent_system` consumes them; `camera_follow_system` (follows player), `camera_noclip_system`, `camera_transition_system`, `camera_ground_clamp_system`
+- **Camera**: `camera_input_system(cameras, follows, input_state)` → generates intents; `camera_intent_system(follow_player_intents, stop_following_intents, camera_transition_intents, ...)` consumes them; `camera_follow_system(follows, cameras, transforms)`, `camera_noclip_system(cameras, follows, transforms, input_state, delta)`, `camera_transition_system(camera_transitions, transforms, cameras, delta)`, `camera_ground_clamp_system(cameras, follows, transforms)`
-- **Input**: `player_input_system` reads SDL3 `InputState`, writes `InputComponent`
+- **Input**: `player_input_system(cameras, follows, player_tags, inputs, input_state)` reads SDL3 `InputState`, writes `InputComponent`
-- **Physics**: `state_machine_physics_system` (fixed-step), `PhysicsManager::physics_step()`, `physics_sync_system` (copies rapier bodies back to transforms), `trigger_system` (AABB overlap → events)
+- **Physics**: `state_machine_physics_system(&mut World, FIXED_TIMESTEP)` (fixed-step), `PhysicsManager::physics_step()`, `physics_sync_system(entities, physics, transforms)` copies rapier bodies back to transforms, `trigger_system(trigger_events, triggers, transforms, player_tags)` (AABB overlap → events)
-- **Dialog**: `dialog_system` (ticks story state), `dialog_projectile_system` (moves projectiles), `dialog_camera_system` (focuses camera on speaker), `dialog_bubble_render_system` (generates billboard/text draw calls)
+- **Dialog**: `dialog_system(entities, trigger_events, dialog_sources, bubble_tags, dialog_bubbles, transforms, names, player_tags, projectile_tags, dialog_projectiles, dialog_outcomes, delta)` ticks story state; `dialog_projectile_system(player_tags, transforms, projectile_tags, dialog_projectiles, spawn_particle_intents, dialog_outcomes, leaping_states, rolling_states, input_state)` moves projectiles; `dialog_camera_system(cameras, transforms, bubble_tags, player_pos, delta)` focuses camera on speaker; `dialog_bubble_render_system(transforms, dialog_bubbles, bubble_tags, camera_pos, view_proj)` generates billboard/text draw calls
-- **Rendering**: `render_system` collects `DrawCall` from meshes/transforms; `spotlight_sync_system` syncs light positions to shader uniform
+- **Rendering**: `render_system(entities, transforms, meshes, dissolves)` → `Vec<DrawCall>` from all meshes; snow layer adds clipmap draw calls; debug adds collider/gizmo calls; `spotlight_sync_system(spotlights, transforms)` syncs light positions to shader uniform
-- **State machine**: `state_machine_system` (per-frame), `state_machine_physics_system` (fixed-step) tick state lifecycle
+- **State machine**: `state_machine_system(&mut World, delta)` (per-frame), `state_machine_physics_system(&mut World, FIXED_TIMESTEP)` (fixed-step) tick state lifecycle
-- **Trees**: `tree_occlusion_system` (culls trees behind camera), `tree_dissolve_update_system` (animates dissolve), `tree_instance_buffer_update_system` (writes GPU buffer)
+- **Trees**: `tree_occlusion_system(player_tags, transforms, cameras, tree_instances)` culls trees behind camera; `tree_dissolve_update_system(tree_instances, delta)` animates dissolve; `tree_instance_buffer_update_system(tree_instances)` writes GPU buffer
-- **Snow**: `snow_system` deforms snow layer at physics contacts; `particle_intent_system`/`particle_update_system` manage particle emitters
+- **Snow**: `snow_system(cameras, transforms, player_tags, follows, snow_layer)` deforms snow layer at physics contacts; `particle_intent_system(particle_buffers, spawn_particle_intents)`/`particle_update_system(particle_buffers, delta)` manage particle emitters
-- **Rotate**: `rotate_system` rotates entities by delta
+- **Rotate**: `rotate_system(rotates, transforms, delta)` rotates entities by delta
 
 ### `src/bundles/`
 Factory functions to spawn pre-configured entity groups:
@@ -90,26 +90,26 @@ Utility modules: ray casting for mouse pick, fullscreen blit/framebuffer downsam
 
 1. **Initialization** (`main.rs` `init()`): SDL3 window → wgpu renderer (Vulkan) → World creation → load scene (Space from glTF) → spawn bundles (player, terrain, camera, lights) → initialize physics
 2. **Main loop** (`main.rs` `main()` with 60 Hz fixed physics + variable-rate graphics):
-   - **Per-frame** (delta): Input events → `player_input_system` (fills `InputComponent`) + `camera_input_system` (generates intents)
+   - **Per-frame** (delta): Input events → `player_input_system(cameras, follows, player_tags, inputs, input_state)` (fills `InputComponent`) + `camera_input_system(cameras, follows, input_state)` (generates intents)
-   - **Intent processing**: `camera_intent_system` consumes intents, updates `CameraComponent`/`CameraTransition`
+   - **Intent processing**: `camera_intent_system(follow_player_intents, stop_following_intents, camera_transition_intents, follows, transforms, cameras, player_tags, camera_transitions)` consumes intents, updates `CameraComponent`/`CameraTransition`
-   - **Camera systems**: follow player, noclip, transition, clamp to ground
+   - **Camera systems**: `camera_follow_system(follows, cameras, transforms)` follows player; `camera_noclip_system(cameras, follows, transforms, input_state, delta)` noclip mode; `camera_transition_system(camera_transitions, transforms, cameras, delta)` animated transitions; `camera_ground_clamp_system(cameras, follows, transforms)` clamps to ground
    - **Fixed physics** (1/60s accumulator):
-     - `state_machine_physics_system`: tick state's `on_physics_update()`
+     - `state_machine_physics_system(&mut World, FIXED_TIMESTEP)`: tick state's `on_physics_update()`
      - `PhysicsManager::physics_step()`: rapier integration
-     - `physics_sync_system`: copy rigidbody poses to `Transform`
+     - `physics_sync_system(entities, physics, transforms)`: copy rigidbody poses to `Transform`
-     - `trigger_system`: detect collisions, emit events
+     - `trigger_system(trigger_events, triggers, transforms, player_tags)`: detect collisions, emit events
-     - `dialog_system`, `dialog_projectile_system`: Ink story tick, projectile movement
+     - `dialog_system(entities, trigger_events, dialog_sources, bubble_tags, dialog_bubbles, transforms, names, player_tags, projectile_tags, dialog_projectiles, dialog_outcomes, delta)` ticks story state; `dialog_projectile_system(player_tags, transforms, projectile_tags, dialog_projectiles, spawn_particle_intents, dialog_outcomes, leaping_states, rolling_states, input_state)` moves projectiles
-   - **Per-frame systems**: `state_machine_system` (non-physics update), rotate, particle, tree dissolve, snow deformation, spotlight sync
+   - **Per-frame systems**: `state_machine_system(&mut World, delta)` ticks state lifecycle; `rotate_system(rotates, transforms, delta)` rotates entities; `particle_intent_system(particle_buffers, spawn_particle_intents)`/`particle_update_system(particle_buffers, delta)` manage particles; `tree_occlusion_system(player_tags, transforms, cameras, tree_instances)` culls; `tree_dissolve_update_system(tree_instances, delta)`/`tree_instance_buffer_update_system(tree_instances)` updates dissolve; `snow_system(cameras, transforms, player_tags, follows, snow_layer)` deforms snow; `spotlight_sync_system(spotlights, transforms)` syncs lights
-   - **Render collection**: `render_system` → `Vec<DrawCall>` from all meshes; snow layer adds clipmap draw calls; debug adds collider/gizmo calls
+   - **Render collection**: `render_system(entities, transforms, meshes, dissolves)` → `Vec<DrawCall>` from all meshes; snow layer adds clipmap draw calls; debug adds collider/gizmo calls
    - **Submission**: `submit_frame()` renders draw calls, dialog bubbles/text, particles to framebuffer; blit to screen; optional ImGui overlay
-3. **Frame cleanup**: `InputState::clear_just_pressed()` (flags reset for next frame)
+3. **Frame cleanup**: `InputState::clear_just_pressed()` resets one-frame flags
 
 ## Key Types
 
 | Type | Module | Description |
 |------|--------|-------------|
 | `EntityHandle` | entity | u64 opaque entity ID |
-| `Storage<T>` | world | HashMap storage for per-entity component data |
+| `Storage<T>` | world | HashMap storage for per-entity component data; exposes `.get()`, `.get_mut()`, `.with_mut()`, `.all()` methods |
 | `World` | world | ECS container: entities, 20+ storages, intent queues, singleton state |
 | `Transform` | utility/transform | Position (Vec3), rotation (Quat), scale (Vec3); matrix conversions |
 | `StateMachine` | states/state | Per-entity state machine: current state TypeId, registered states, transitions |
@@ -146,10 +146,10 @@ Utility modules: ray casting for mouse pick, fullscreen blit/framebuffer downsam
 
 ## Dependencies
 
-- **Engine**: wgpu (GPU), rapier3d (physics), glam (math), nalgebra (nalgebra for physics conversions), SDL3 (windowing/input)
+- **Engine**: wgpu (GPU), rapier3d (physics), glam (math), nalgebra (physics conversions), SDL3 (windowing/input)
 - **Content**: bladeink (Ink story scripting), image crate (EXR heightmaps), gltf (scene loading)
 - **Editor**: Dear ImGui via imgui crate + SDL3 integration
-- **Internal**: All systems read/write `World`; systems are called in fixed sequence from main loop; no circular dependencies
+- **Internal**: All systems take explicit storage parameters from `World`; systems are called in fixed sequence from main loop; no circular dependencies
 - **Thread-local singletons**: `Renderer` (render/global.rs), `PhysicsManager` (physics.rs), `GLOBAL_RENDERER`, `GLOBAL_PHYSICS`
 
 ## Initialization Order