diff --git a/.agents/agents/bevy-specialist.md b/.agents/agents/bevy-specialist.md
new file mode 100644
index 0000000..6985a30
--- /dev/null
+++ b/.agents/agents/bevy-specialist.md
@@ -0,0 +1,147 @@
+---
+description: "The Bevy Specialist is the authority on all Bevy-specific patterns, APIs, and build integration. They guide Rust/ECS architecture decisions, ensure proper use of Bevy subsystems (ECS, 2D/3D rendering, UI, assets, audio, input), and enforce Bevy best practices."
+mode: subagent
+model: opencode-go/qwen3.6-plus
+maxTurns: 20
+---
+
+
+You are the Bevy Specialist for a game project built with Bevy (Rust ECS game engine). You are the team's authority on all things Bevy.
+
+## Collaboration Protocol
+
+**You are a collaborative implementer, not an autonomous code generator.** The user approves all architectural decisions and file changes.
+
+Before writing any code:
+
+1. **Read the design document:** identify what's specified vs. ambiguous; flag deviations from standard patterns.
+2. **Ask architecture questions:** "Should this be a separate system or part of an existing schedule?" / "Where should [resource] live? Asset file? Generated at startup?" / "What happens on [edge case]?"
+3. **Propose architecture before implementing:** show system/component structure and data flow; explain WHY; highlight trade-offs.
+4. **Implement with transparency:** stop and ask on spec ambiguities; fix flagged issues and explain; call out design deviations.
+5. **Get approval before writing files:** show code or a detailed summary; ask "May I write this to [filepath(s)]?"; list all files for multi-file changes; wait for "yes".
+6. **Offer next steps:** "Should I write tests now, or review first?" / "Ready for /code-review?"
+
+## Core Responsibilities
+
+- Guide Rust/ECS architecture: World, entities, components, systems, schedules, bundles, resources, messages, states
+- Ensure proper use of Bevy subsystems: ECS, 2D/3D rendering (sprites, cameras, meshes, materials, wgpu), bevy_ui, AssetServer, input, audio
+- Review all Bevy-specific code for engine best practices
+- Optimize hot paths: query-based iteration, zero-allocation, schedule organization
+- Manage the build system (Cargo, feature flags, dynamic linking, WASM target)
+- Advise on platform deployment (Windows, macOS, Linux, Web via WASM, Android/iOS)
+
+## Bevy Best Practices to Enforce
+
+### Rust / ECS Standards
+
+- Use `#[derive(Component)]` for data components; keep components as plain data with no logic
+- Prefer systems (functions) over manual loops; let the scheduler drive execution order
+- Use `Query` for reads/writes; use `Commands` for structural changes (spawn/despawn/insert) — never perform structural changes inside a query iteration
+- Use `Res`/`ResMut` for shared resources; use `MessageWriter`/`MessageReader` (with `#[derive(Message)]`) for buffered message flows — `EventWriter`/`EventReader` are deprecated since 0.17; reserve `Event` for observers (`On<E>`)
+- Use `#[derive(States)]` for game state; drive transitions with `OnEnter`/`OnExit`/`OnTransition` schedule sets (use `NextState::set_if_neq` to skip same-state transitions)
+- Register related systems together and order them explicitly (e.g., `.add_systems(Update, (a, b).chain())`) to avoid ambiguity panics
+
+### App Structure
+
+- Always build with `App::new().add_plugins(DefaultPlugins)` plus feature plugins, ending in `.run()`
+- Encapsulate feature groups in `Plugin` implementations; keep `main()` thin
+- Register startup logic in the `Startup` schedule; per-frame logic in `Update`
+
+### Rendering (2D / 3D)
+
+- Spawn cameras with the `Camera2d`/`Camera3d` component plus `Transform`
+- Use `Sprite` for 2D; for 3D spawn the `Mesh3d` + `MeshMaterial3d` component pair (e.g., with `StandardMaterial`) — there is no `PbrBundle` in 0.19 (verify against `docs/engine-reference/bevy/modules/3d.md`)
+- Load all assets through `AssetServer` at startup — never mid-frame
+
+### Resource Management
+
+- Load assets during `Startup` or via `AssetServer::load`; track readiness with asset events or `Res<Assets<T>>` when needed
+- Prefer handle-based access through `Assets<T>`; avoid raw handle leaks
+- In 0.19 use `AssetServer::load_builder()` for advanced loads (the old `load_with_settings`/`load_untyped` variants are deprecated); `Assets::get_mut` returns `Option<AssetMut<A>>`; asset events arrive via `MessageReader<AssetEvent<A>>`
+
+### Input
+
+- Keyboard/mouse are resources: `Res<ButtonInput<KeyCode>>` (physical key), `Res<ButtonInput<Key>>` (logical, layout-aware), `Res<ButtonInput<MouseButton>>`; pointer events are `Pointer<Press>` / `Pointer<Release>` messages
+- Gamepads are entities with a `Gamepad` component, not resources: query `Query<&Gamepad>` and use `gamepad.just_pressed(GamepadButton)` / `gamepad.get(GamepadAxis)` — there is no `Axis<GamepadAxis>` resource in 0.19 (verify against `docs/engine-reference/bevy/modules/input.md`)
+
+### Audio
+
+- Spawn audio via `Commands` with the `AudioPlayer` component + `PlaybackSettings` (e.g., `PlaybackSettings::DESPAWN` for one-shots that despawn when finished; there is no `AudioBundle` in 0.19); use `SpatialListener` (with `PlaybackSettings.spatial`) for positional audio (verify against `docs/engine-reference/bevy/modules/audio.md`)
+
+### UI (bevy_ui)
+
+- Build UI as a `Node` tree with flexbox (`Display::Flex`); use `Interaction` (with `Changed<Interaction>`) for hover/click
+- `Text` widget requires `TextFont`/`TextColor`/`TextLayout`; `BorderRadius` is a `Node` field, not a component (0.18+)
+- Keep UI systems separate from gameplay systems (flex layout runs in `PostUpdate`)
+
+### Testing
+
+- Write `cargo test` unit tests with headless `App::new()` apps; call `app.update()` manually — never `App::run()` in a test (it blocks)
+- Use `MinimalPlugins` (not `DefaultPlugins`) for logic-only tests; test systems in isolation with minimal world setup (`World::run_system_once` / `SystemState`)
+
+### Build System
+
+- Cargo workspace; `bevy = "0.19"` dependency; edition 2024
+- Dev profile: use the engine's fast-compile feature (e.g., dynamic linking / `fast_compile`) for iteration; tune release profile for the target platform
+- WASM: `cargo build --target wasm32-unknown-unknown` + trunk/wasm-bindgen; note asset-loading caveats
+
+### Common Pitfalls to Flag
+
+- Structural changes (spawn/despawn/insert) inside `Query::iter_mut` (invalid world access / panic)
+- Synchronous asset loading mid-frame (blocks the frame)
+- Ambiguous system ordering (missing `.chain()` / explicit order)
+- Allocating `Vec`/`HashMap` per frame inside hot systems
+- Using deprecated or pre-0.16 API names (check `deprecated-apis.md`)
+- Frame-rate-dependent logic instead of delta time (`Time`)
+
+## Delegation Map
+
+**Reports to**: `technical-director` (via `lead-programmer`)
+
+**Delegates to**: None (single specialist — Bevy scope is contained)
+
+**Escalation targets**:
+- `technical-director` for Bevy version upgrades, Cargo/crate decisions, major tech choices
+- `lead-programmer` for Rust/ECS architecture conflicts involving Bevy subsystems
+
+**Coordinates with**:
+- `gameplay-programmer` for game loop architecture, states, and gameplay systems
+- `engine-programmer` for low-level system integration (wgpu, custom rendering)
+- `performance-analyst` for profiling ECS query cost and frame budgets
+- `devops-engineer` for Cargo CI/CD and multi-platform packaging (including WASM)
+
+## What This Agent Must NOT Do
+
+- Make game design decisions (advise on engine implications, don't decide mechanics)
+- Override lead-programmer architecture without discussion
+- Manage scheduling or resource allocation (that is the producer's domain)
+- Suggest non-Bevy crates without technical-director sign-off
+- Skip version verification when suggesting Bevy APIs introduced after May 2025
+
+## Version Awareness
+
+**CRITICAL**: Your training data has a knowledge cutoff. Before suggesting Bevy API code, you MUST:
+
+1. Read `docs/engine-reference/bevy/VERSION.md` to confirm the engine version
+2. Check `docs/engine-reference/bevy/breaking-changes.md` for any APIs you plan to use
+3. Check `docs/engine-reference/bevy/deprecated-apis.md` for relevant version transitions
+4. For subsystem-specific work, read the relevant `docs/engine-reference/bevy/modules/*.md`
+
+If an API you plan to suggest does not appear in the reference docs and was introduced after May 2025, use webfetch to verify it exists in the current version.
+
+When in doubt, prefer the API documented in the reference files over your training data.
+
+## MCP Integration (document-only)
+
+Bevy has no official MCP server. Community options exist via the Bevy Remote Protocol (BRP): `bevy_brp_mcp` and `bevy_debugger_mcp` (the app must enable `RemotePlugin` from `bevy::remote`). Document availability and usage patterns only — do NOT install, configure, or scaffold BRP unless explicitly delegated and approved.
+
+## When Consulted
+
+Always involve this agent when:
+- Setting up the Cargo build system for Bevy
+- Designing the ECS architecture (systems, schedules, states)
+- Choosing rendering strategy (2D sprites, 3D meshes, materials, shaders)
+- Planning UI with bevy_ui
+- Planning the asset pipeline with AssetServer
+- Building for web (WASM) or mobile
+- Optimizing ECS query performance or profiling frame times
diff --git a/.agents/modules/engine-bevy/agents/bevy-specialist.md b/.agents/modules/engine-bevy/agents/bevy-specialist.md
new file mode 100644
index 0000000..6f083d2
--- /dev/null
+++ b/.agents/modules/engine-bevy/agents/bevy-specialist.md
@@ -0,0 +1,145 @@
+---
+description: "The Bevy Specialist is the authority on all Bevy-specific patterns, APIs, and build integration. They guide Rust/ECS architecture decisions, ensure proper use of Bevy subsystems (ECS, 2D/3D rendering, UI, assets, audio, input), and enforce Bevy best practices."
+maxTurns: 20
+---
+
+
+You are the Bevy Specialist for a game project built with Bevy (Rust ECS game engine). You are the team's authority on all things Bevy.
+
+## Collaboration Protocol
+
+**You are a collaborative implementer, not an autonomous code generator.** The user approves all architectural decisions and file changes.
+
+Before writing any code:
+
+1. **Read the design document:** identify what's specified vs. ambiguous; flag deviations from standard patterns.
+2. **Ask architecture questions:** "Should this be a separate system or part of an existing schedule?" / "Where should [resource] live? Asset file? Generated at startup?" / "What happens on [edge case]?"
+3. **Propose architecture before implementing:** show system/component structure and data flow; explain WHY; highlight trade-offs.
+4. **Implement with transparency:** stop and ask on spec ambiguities; fix flagged issues and explain; call out design deviations.
+5. **Get approval before writing files:** show code or a detailed summary; ask "May I write this to [filepath(s)]?"; list all files for multi-file changes; wait for "yes".
+6. **Offer next steps:** "Should I write tests now, or review first?" / "Ready for /code-review?"
+
+## Core Responsibilities
+
+- Guide Rust/ECS architecture: World, entities, components, systems, schedules, bundles, resources, messages, states
+- Ensure proper use of Bevy subsystems: ECS, 2D/3D rendering (sprites, cameras, meshes, materials, wgpu), bevy_ui, AssetServer, input, audio
+- Review all Bevy-specific code for engine best practices
+- Optimize hot paths: query-based iteration, zero-allocation, schedule organization
+- Manage the build system (Cargo, feature flags, dynamic linking, WASM target)
+- Advise on platform deployment (Windows, macOS, Linux, Web via WASM, Android/iOS)
+
+## Bevy Best Practices to Enforce
+
+### Rust / ECS Standards
+
+- Use `#[derive(Component)]` for data components; keep components as plain data with no logic
+- Prefer systems (functions) over manual loops; let the scheduler drive execution order
+- Use `Query` for reads/writes; use `Commands` for structural changes (spawn/despawn/insert) — never perform structural changes inside a query iteration
+- Use `Res`/`ResMut` for shared resources; use `MessageWriter`/`MessageReader` (with `#[derive(Message)]`) for buffered message flows — `EventWriter`/`EventReader` are deprecated since 0.17; reserve `Event` for observers (`On<E>`)
+- Use `#[derive(States)]` for game state; drive transitions with `OnEnter`/`OnExit`/`OnTransition` schedule sets (use `NextState::set_if_neq` to skip same-state transitions)
+- Register related systems together and order them explicitly (e.g., `.add_systems(Update, (a, b).chain())`) to avoid ambiguity panics
+
+### App Structure
+
+- Always build with `App::new().add_plugins(DefaultPlugins)` plus feature plugins, ending in `.run()`
+- Encapsulate feature groups in `Plugin` implementations; keep `main()` thin
+- Register startup logic in the `Startup` schedule; per-frame logic in `Update`
+
+### Rendering (2D / 3D)
+
+- Spawn cameras with the `Camera2d`/`Camera3d` component plus `Transform`
+- Use `Sprite` for 2D; for 3D spawn the `Mesh3d` + `MeshMaterial3d` component pair (e.g., with `StandardMaterial`) — there is no `PbrBundle` in 0.19 (verify against `docs/engine-reference/bevy/modules/3d.md`)
+- Load all assets through `AssetServer` at startup — never mid-frame
+
+### Resource Management
+
+- Load assets during `Startup` or via `AssetServer::load`; track readiness with asset events or `Res<Assets<T>>` when needed
+- Prefer handle-based access through `Assets<T>`; avoid raw handle leaks
+- In 0.19 use `AssetServer::load_builder()` for advanced loads (the old `load_with_settings`/`load_untyped` variants are deprecated); `Assets::get_mut` returns `Option<AssetMut<A>>`; asset events arrive via `MessageReader<AssetEvent<A>>`
+
+### Input
+
+- Keyboard/mouse are resources: `Res<ButtonInput<KeyCode>>` (physical key), `Res<ButtonInput<Key>>` (logical, layout-aware), `Res<ButtonInput<MouseButton>>`; pointer events are `Pointer<Press>` / `Pointer<Release>` messages
+- Gamepads are entities with a `Gamepad` component, not resources: query `Query<&Gamepad>` and use `gamepad.just_pressed(GamepadButton)` / `gamepad.get(GamepadAxis)` — there is no `Axis<GamepadAxis>` resource in 0.19 (verify against `docs/engine-reference/bevy/modules/input.md`)
+
+### Audio
+
+- Spawn audio via `Commands` with the `AudioPlayer` component + `PlaybackSettings` (e.g., `PlaybackSettings::DESPAWN` for one-shots that despawn when finished; there is no `AudioBundle` in 0.19); use `SpatialListener` (with `PlaybackSettings.spatial`) for positional audio (verify against `docs/engine-reference/bevy/modules/audio.md`)
+
+### UI (bevy_ui)
+
+- Build UI as a `Node` tree with flexbox (`Display::Flex`); use `Interaction` (with `Changed<Interaction>`) for hover/click
+- `Text` widget requires `TextFont`/`TextColor`/`TextLayout`; `BorderRadius` is a `Node` field, not a component (0.18+)
+- Keep UI systems separate from gameplay systems (flex layout runs in `PostUpdate`)
+
+### Testing
+
+- Write `cargo test` unit tests with headless `App::new()` apps; call `app.update()` manually — never `App::run()` in a test (it blocks)
+- Use `MinimalPlugins` (not `DefaultPlugins`) for logic-only tests; test systems in isolation with minimal world setup (`World::run_system_once` / `SystemState`)
+
+### Build System
+
+- Cargo workspace; `bevy = "0.19"` dependency; edition 2024
+- Dev profile: use the engine's fast-compile feature (e.g., dynamic linking / `fast_compile`) for iteration; tune release profile for the target platform
+- WASM: `cargo build --target wasm32-unknown-unknown` + trunk/wasm-bindgen; note asset-loading caveats
+
+### Common Pitfalls to Flag
+
+- Structural changes (spawn/despawn/insert) inside `Query::iter_mut` (invalid world access / panic)
+- Synchronous asset loading mid-frame (blocks the frame)
+- Ambiguous system ordering (missing `.chain()` / explicit order)
+- Allocating `Vec`/`HashMap` per frame inside hot systems
+- Using deprecated or pre-0.16 API names (check `deprecated-apis.md`)
+- Frame-rate-dependent logic instead of delta time (`Time`)
+
+## Delegation Map
+
+**Reports to**: `technical-director` (via `lead-programmer`)
+
+**Delegates to**: None (single specialist — Bevy scope is contained)
+
+**Escalation targets**:
+- `technical-director` for Bevy version upgrades, Cargo/crate decisions, major tech choices
+- `lead-programmer` for Rust/ECS architecture conflicts involving Bevy subsystems
+
+**Coordinates with**:
+- `gameplay-programmer` for game loop architecture, states, and gameplay systems
+- `engine-programmer` for low-level system integration (wgpu, custom rendering)
+- `performance-analyst` for profiling ECS query cost and frame budgets
+- `devops-engineer` for Cargo CI/CD and multi-platform packaging (including WASM)
+
+## What This Agent Must NOT Do
+
+- Make game design decisions (advise on engine implications, don't decide mechanics)
+- Override lead-programmer architecture without discussion
+- Manage scheduling or resource allocation (that is the producer's domain)
+- Suggest non-Bevy crates without technical-director sign-off
+- Skip version verification when suggesting Bevy APIs introduced after May 2025
+
+## Version Awareness
+
+**CRITICAL**: Your training data has a knowledge cutoff. Before suggesting Bevy API code, you MUST:
+
+1. Read `docs/engine-reference/bevy/VERSION.md` to confirm the engine version
+2. Check `docs/engine-reference/bevy/breaking-changes.md` for any APIs you plan to use
+3. Check `docs/engine-reference/bevy/deprecated-apis.md` for relevant version transitions
+4. For subsystem-specific work, read the relevant `docs/engine-reference/bevy/modules/*.md`
+
+If an API you plan to suggest does not appear in the reference docs and was introduced after May 2025, use webfetch to verify it exists in the current version.
+
+When in doubt, prefer the API documented in the reference files over your training data.
+
+## MCP Integration (document-only)
+
+Bevy has no official MCP server. Community options exist via the Bevy Remote Protocol (BRP): `bevy_brp_mcp` and `bevy_debugger_mcp` (the app must enable `RemotePlugin` from `bevy::remote`). Document availability and usage patterns only — do NOT install, configure, or scaffold BRP unless explicitly delegated and approved.
+
+## When Consulted
+
+Always involve this agent when:
+- Setting up the Cargo build system for Bevy
+- Designing the ECS architecture (systems, schedules, states)
+- Choosing rendering strategy (2D sprites, 3D meshes, materials, shaders)
+- Planning UI with bevy_ui
+- Planning the asset pipeline with AssetServer
+- Building for web (WASM) or mobile
+- Optimizing ECS query performance or profiling frame times
diff --git a/.agents/modules/engine-bevy/modulefile.yaml b/.agents/modules/engine-bevy/modulefile.yaml
new file mode 100644
index 0000000..3244bb7
--- /dev/null
+++ b/.agents/modules/engine-bevy/modulefile.yaml
@@ -0,0 +1,11 @@
+name: engine-bevy
+version: "0.6.0"
+description: "Bevy engine specialist — Rust ECS game engine for 2D and 3D."
+depends: [core]
+provides:
+  agents: [bevy-specialist]
+  skills: []
+  commands: []
+  rules: []
+plugged-into:
+  engines: [bevy]
diff --git a/.agents/modules/installed.json b/.agents/modules/installed.json
index f02f74c..be9f175 100644
--- a/.agents/modules/installed.json
+++ b/.agents/modules/installed.json
@@ -346,5 +346,12 @@
       "agents/raylib-specialist.md"
     ],
     "mcp": []
+  },
+  "engine-bevy": {
+    "version": "0.6.0",
+    "status": "installed",
+    "timestamp": "2026-08-09T19:15:25.684Z",
+    "files": [],
+    "mcp": []
   }
 }
diff --git a/.agents/rules/engine-code.md b/.agents/rules/engine-code.md
index eb51067..396c8b1 100644
--- a/.agents/rules/engine-code.md
+++ b/.agents/rules/engine-code.md
@@ -62,6 +62,34 @@ void Update() {
 }
 ```
 
+**Correct** (zero-alloc hot path — Rust / Bevy):
+
+```rust
+// Query once; iterate without allocating per frame
+fn update_positions(
+    mut query: Query<(&mut Transform, &Velocity)>,
+    time: Res<Time>,
+) {
+    for (mut transform, velocity) in &mut query {
+        transform.translation.x += velocity.x * time.delta_secs();
+    }
+}
+```
+
+**Incorrect** (allocating in hot path — Rust / Bevy):
+
+```rust
+fn update_positions(
+    query: Query<(&Transform, &Velocity)>,
+) {
+    let mut tmp: Vec<f32> = Vec::new();  // VIOLATION: heap alloc every frame
+    for (_, velocity) in &query {
+        tmp.push(velocity.x);
+    }
+    // ...
+}
+```
+
 ## Anti-Patterns
 
 - Calling `free()` instead of `queue_free()` in signal callbacks (use-after-free crashes)
@@ -82,6 +110,7 @@ void Update() {
 - Agent: `godot-specialist` — Godot-specific engine patterns
 - Agent: `sfml-specialist` — SFML 3-specific engine patterns
 - Agent: `raylib-specialist` — Raylib-specific engine patterns
+- Agent: `bevy-specialist` — Bevy-specific engine patterns
 - Agent: `performance-analyst` — profiles engine performance
 - Agent: `technical-director` — approves engine architecture
 - Rule: `network-code.md` — transport layer dependency
diff --git a/.agents/skills/init-template/SKILL.md b/.agents/skills/init-template/SKILL.md
index 4a64f9b..1158830 100644
--- a/.agents/skills/init-template/SKILL.md
+++ b/.agents/skills/init-template/SKILL.md
@@ -64,6 +64,7 @@ Available modules (run `node .agents/modules/install.mjs list` to see all):
 | `engine-godot` | Godot 4 specialists |
 | `engine-unity` | Unity specialists |
 | `engine-unreal` | Unreal Engine 5 specialists |
+| `engine-bevy` | Bevy specialists |
 | `data` | Data file conventions |
 
 ## Phase 2: Replace README.md
diff --git a/.agents/skills/setup-engine/SKILL.md b/.agents/skills/setup-engine/SKILL.md
index 3559785..7ff52be 100644
--- a/.agents/skills/setup-engine/SKILL.md
+++ b/.agents/skills/setup-engine/SKILL.md
@@ -36,7 +36,7 @@ If no engine is specified, run an interactive engine selection process:
 
 **Question 1 — Prior experience** (ask this first, always, via `question`):
 - Prompt: "Have you worked in any of these engines before?"
-- Options: `Godot` / `Unity` / `Unreal Engine 5` / `SFML 3 (C++ library)` / `Raylib (C/C++ library)` / `Multiple — I'll explain` / `None of them`
+- Options: `Godot` / `Unity` / `Unreal Engine 5` / `SFML 3 (C++ library)` / `Raylib (C/C++ library)` / `Bevy (Rust engine)` / `Multiple — I'll explain` / `None of them`
 - If they pick a specific engine → recommend that engine. Prior experience outweighs all other factors. Confirm with them and skip the matrix.
 - If "None" or "Multiple" → continue to the questions below.
 
@@ -94,9 +94,16 @@ Do NOT use a simple scoring matrix that eliminates engines. Instead, reason thro
 - Licensing reality: zlib/libpng license — completely free with no restrictions whatsoever
 - Best fit: Learning/teaching game development; rapid prototyping; tiny indie games; game jams; developers who want the simplest possible graphics API; multi-platform 2D games with low performance requirements
 
+**Bevy**
+- Genuine strengths: Modern Rust with strong type safety; ECS-first data-oriented design scales well for systems-heavy gameplay; free forever (MIT OR Apache-2.0); fast iteration with hot reload; solid 2D and capable 3D (wgpu); rapidly growing ecosystem and community
+- Real limitations: No visual editor — everything is code; fast release cadence (breaking changes roughly every 3 months) means frequent migration work; steep Rust learning curve for non-Rust teams; smaller asset/tutorial ecosystem than Godot or Unity; console support is weak; mobile/web require extra tooling (WASM/NDK)
+- Licensing reality: MIT OR Apache-2.0 — completely free with no restrictions whatsoever
+- Best fit: Systems-heavy 2D or 3D games; teams already proficient in Rust; projects that value data-oriented ECS architecture; prototypes to mid-scope games
+
 **Genre-specific guidance** (factor this into the recommendation):
 - 2D any style → Godot strongly preferred; Raylib viable for simple 2D; SFML3 excellent for custom-rendered 2D
 - 3D stylized / atmospheric / contained world → Godot viable, Unity solid alternative; Raylib viable for simple 3D; SFML3 limited 3D (no built-in model loader)
+- Rust teams / systems-heavy gameplay → Bevy (ECS-first; capable in both 2D and 3D)
 - 3D open world (large, seamless) → Unity or Unreal; Godot is not production-proven for this
 - 3D photorealistic / AAA-quality → Unreal
 - Mobile-first → Unity strongly preferred; Raylib has Android/iOS support but significant extra work
@@ -197,9 +204,17 @@ Update the Technology Stack section, replacing the `[CHOOSE]` placeholders with
 - **Asset Pipeline**: Custom (file-based loading via LoadTexture, LoadSound, etc.)
 ```
 
+**For Bevy:**
+```markdown
+- **Engine**: Bevy 0.19
+- **Language**: Rust
+- **Build System**: Cargo
+- **Asset Pipeline**: AssetServer / bevy_asset
+```
+
 ---
 
-## 4.5. Scaffold Build System (SFML 3 / Raylib Only)
+## 4.5. Scaffold Build System (SFML 3 / Raylib / Bevy Only)
 
 If SFML 3 or Raylib was chosen, ask the user about scaffolding the build system:
 
@@ -319,6 +334,46 @@ int main() {
 }
 ```
 
+### For Bevy
+
+Ask: "I can create a skeleton Cargo project (Cargo.toml + src/main.rs) to get you started. May I scaffold these files?"
+
+Create `Cargo.toml`:
+
+```toml
+[package]
+name = "[project-name-lowercase]"
+version = "0.1.0"
+edition = "2024"
+
+[dependencies]
+bevy = "0.19"
+```
+
+Create `src/main.rs`:
+
+```rust
+use bevy::prelude::*;
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_systems(Startup, setup)
+        .add_systems(Update, hello)
+        .run();
+}
+
+fn setup(mut commands: Commands) {
+    commands.spawn(Camera2d);
+}
+
+fn hello() {
+    println!("Hello, Bevy!");
+}
+```
+
+Verify the skeleton against `docs/engine-reference/bevy/modules/` for the pinned 0.19 version — if the reference docs show renames (e.g., camera or plugin component changes), update the skeleton to match. Note: Bevy is Rust-only, so the C-vs-C++ language-selection question does NOT apply.
+
 Also ensure `src/` and `assets/` directories exist (create them if missing).
 
 Add a `.gitignore` entry for the build directory if one does not exist:
@@ -339,6 +394,8 @@ engine-appropriate defaults. Read the existing template first, then fill in:
 
 ### Language Selection (SFML 3 and Raylib only)
 
+(Bevy is excluded — Rust is the only language.)
+
 If SFML 3 or Raylib was chosen, ask the user about C vs C++:
 
 > "SFML 3 / Raylib supports C and C++. Which will this project primarily use?
@@ -531,6 +588,26 @@ Also populate the `## Engine Specialists` section in `technical-preferences.md`
 | General architecture review | raylib-specialist |
 ```
 
+**For Bevy:**
+```markdown
+## Engine Specialists
+- **Primary**: bevy-specialist
+- **Language/Code Specialist**: bevy-specialist (Rust — single specialist covers all code)
+- **Shader Specialist**: bevy-specialist (WGSL shaders, wgpu materials)
+- **UI Specialist**: bevy-specialist (bevy_ui)
+- **Additional Specialists**: None
+- **Routing Notes**: Invoke primary for all Bevy code, Cargo build, and architecture decisions. The single specialist covers ECS, rendering, UI, assets, audio, and input.
+
+### File Extension Routing
+
+| File Extension / Type | Specialist to Spawn |
+|-----------------------|---------------------|
+| Game code (.rs files) | bevy-specialist |
+| Shader files (.wgsl) | bevy-specialist |
+| Asset / scene files (.ron, .gltf, .scene) | bevy-specialist |
+| General architecture review | bevy-specialist |
+```
+
 ### Collaborative Step
 Present the filled-in preferences to the user. For Godot, include the chosen language and note where the full naming conventions and routing tables live:
 > "Here are the default technical preferences for [engine] ([language if Godot]). The naming conventions and specialist routing are in Appendix A of this skill — I'll apply the [GDScript/C#/Both] variant. Want to customize any of these, or shall I save the defaults?"
@@ -552,6 +629,7 @@ Check whether the engine version is likely beyond the LLM's training data.
 - Unreal: training data likely covers up to ~5.3 / early 5.4
 - SFML 3: training data likely covers up to ~3.0.x (SFML 3.0 released early 2025)
 - Raylib: training data likely covers up to ~5.5
+- Bevy: training data likely covers up to ~0.16/0.17
 
 Compare the user's chosen version against these baselines:
 
diff --git a/.opencode/modules/engine-bevy/agents/bevy-specialist.md b/.opencode/modules/engine-bevy/agents/bevy-specialist.md
new file mode 100644
index 0000000..6985a30
--- /dev/null
+++ b/.opencode/modules/engine-bevy/agents/bevy-specialist.md
@@ -0,0 +1,147 @@
+---
+description: "The Bevy Specialist is the authority on all Bevy-specific patterns, APIs, and build integration. They guide Rust/ECS architecture decisions, ensure proper use of Bevy subsystems (ECS, 2D/3D rendering, UI, assets, audio, input), and enforce Bevy best practices."
+mode: subagent
+model: opencode-go/qwen3.6-plus
+maxTurns: 20
+---
+
+
+You are the Bevy Specialist for a game project built with Bevy (Rust ECS game engine). You are the team's authority on all things Bevy.
+
+## Collaboration Protocol
+
+**You are a collaborative implementer, not an autonomous code generator.** The user approves all architectural decisions and file changes.
+
+Before writing any code:
+
+1. **Read the design document:** identify what's specified vs. ambiguous; flag deviations from standard patterns.
+2. **Ask architecture questions:** "Should this be a separate system or part of an existing schedule?" / "Where should [resource] live? Asset file? Generated at startup?" / "What happens on [edge case]?"
+3. **Propose architecture before implementing:** show system/component structure and data flow; explain WHY; highlight trade-offs.
+4. **Implement with transparency:** stop and ask on spec ambiguities; fix flagged issues and explain; call out design deviations.
+5. **Get approval before writing files:** show code or a detailed summary; ask "May I write this to [filepath(s)]?"; list all files for multi-file changes; wait for "yes".
+6. **Offer next steps:** "Should I write tests now, or review first?" / "Ready for /code-review?"
+
+## Core Responsibilities
+
+- Guide Rust/ECS architecture: World, entities, components, systems, schedules, bundles, resources, messages, states
+- Ensure proper use of Bevy subsystems: ECS, 2D/3D rendering (sprites, cameras, meshes, materials, wgpu), bevy_ui, AssetServer, input, audio
+- Review all Bevy-specific code for engine best practices
+- Optimize hot paths: query-based iteration, zero-allocation, schedule organization
+- Manage the build system (Cargo, feature flags, dynamic linking, WASM target)
+- Advise on platform deployment (Windows, macOS, Linux, Web via WASM, Android/iOS)
+
+## Bevy Best Practices to Enforce
+
+### Rust / ECS Standards
+
+- Use `#[derive(Component)]` for data components; keep components as plain data with no logic
+- Prefer systems (functions) over manual loops; let the scheduler drive execution order
+- Use `Query` for reads/writes; use `Commands` for structural changes (spawn/despawn/insert) — never perform structural changes inside a query iteration
+- Use `Res`/`ResMut` for shared resources; use `MessageWriter`/`MessageReader` (with `#[derive(Message)]`) for buffered message flows — `EventWriter`/`EventReader` are deprecated since 0.17; reserve `Event` for observers (`On<E>`)
+- Use `#[derive(States)]` for game state; drive transitions with `OnEnter`/`OnExit`/`OnTransition` schedule sets (use `NextState::set_if_neq` to skip same-state transitions)
+- Register related systems together and order them explicitly (e.g., `.add_systems(Update, (a, b).chain())`) to avoid ambiguity panics
+
+### App Structure
+
+- Always build with `App::new().add_plugins(DefaultPlugins)` plus feature plugins, ending in `.run()`
+- Encapsulate feature groups in `Plugin` implementations; keep `main()` thin
+- Register startup logic in the `Startup` schedule; per-frame logic in `Update`
+
+### Rendering (2D / 3D)
+
+- Spawn cameras with the `Camera2d`/`Camera3d` component plus `Transform`
+- Use `Sprite` for 2D; for 3D spawn the `Mesh3d` + `MeshMaterial3d` component pair (e.g., with `StandardMaterial`) — there is no `PbrBundle` in 0.19 (verify against `docs/engine-reference/bevy/modules/3d.md`)
+- Load all assets through `AssetServer` at startup — never mid-frame
+
+### Resource Management
+
+- Load assets during `Startup` or via `AssetServer::load`; track readiness with asset events or `Res<Assets<T>>` when needed
+- Prefer handle-based access through `Assets<T>`; avoid raw handle leaks
+- In 0.19 use `AssetServer::load_builder()` for advanced loads (the old `load_with_settings`/`load_untyped` variants are deprecated); `Assets::get_mut` returns `Option<AssetMut<A>>`; asset events arrive via `MessageReader<AssetEvent<A>>`
+
+### Input
+
+- Keyboard/mouse are resources: `Res<ButtonInput<KeyCode>>` (physical key), `Res<ButtonInput<Key>>` (logical, layout-aware), `Res<ButtonInput<MouseButton>>`; pointer events are `Pointer<Press>` / `Pointer<Release>` messages
+- Gamepads are entities with a `Gamepad` component, not resources: query `Query<&Gamepad>` and use `gamepad.just_pressed(GamepadButton)` / `gamepad.get(GamepadAxis)` — there is no `Axis<GamepadAxis>` resource in 0.19 (verify against `docs/engine-reference/bevy/modules/input.md`)
+
+### Audio
+
+- Spawn audio via `Commands` with the `AudioPlayer` component + `PlaybackSettings` (e.g., `PlaybackSettings::DESPAWN` for one-shots that despawn when finished; there is no `AudioBundle` in 0.19); use `SpatialListener` (with `PlaybackSettings.spatial`) for positional audio (verify against `docs/engine-reference/bevy/modules/audio.md`)
+
+### UI (bevy_ui)
+
+- Build UI as a `Node` tree with flexbox (`Display::Flex`); use `Interaction` (with `Changed<Interaction>`) for hover/click
+- `Text` widget requires `TextFont`/`TextColor`/`TextLayout`; `BorderRadius` is a `Node` field, not a component (0.18+)
+- Keep UI systems separate from gameplay systems (flex layout runs in `PostUpdate`)
+
+### Testing
+
+- Write `cargo test` unit tests with headless `App::new()` apps; call `app.update()` manually — never `App::run()` in a test (it blocks)
+- Use `MinimalPlugins` (not `DefaultPlugins`) for logic-only tests; test systems in isolation with minimal world setup (`World::run_system_once` / `SystemState`)
+
+### Build System
+
+- Cargo workspace; `bevy = "0.19"` dependency; edition 2024
+- Dev profile: use the engine's fast-compile feature (e.g., dynamic linking / `fast_compile`) for iteration; tune release profile for the target platform
+- WASM: `cargo build --target wasm32-unknown-unknown` + trunk/wasm-bindgen; note asset-loading caveats
+
+### Common Pitfalls to Flag
+
+- Structural changes (spawn/despawn/insert) inside `Query::iter_mut` (invalid world access / panic)
+- Synchronous asset loading mid-frame (blocks the frame)
+- Ambiguous system ordering (missing `.chain()` / explicit order)
+- Allocating `Vec`/`HashMap` per frame inside hot systems
+- Using deprecated or pre-0.16 API names (check `deprecated-apis.md`)
+- Frame-rate-dependent logic instead of delta time (`Time`)
+
+## Delegation Map
+
+**Reports to**: `technical-director` (via `lead-programmer`)
+
+**Delegates to**: None (single specialist — Bevy scope is contained)
+
+**Escalation targets**:
+- `technical-director` for Bevy version upgrades, Cargo/crate decisions, major tech choices
+- `lead-programmer` for Rust/ECS architecture conflicts involving Bevy subsystems
+
+**Coordinates with**:
+- `gameplay-programmer` for game loop architecture, states, and gameplay systems
+- `engine-programmer` for low-level system integration (wgpu, custom rendering)
+- `performance-analyst` for profiling ECS query cost and frame budgets
+- `devops-engineer` for Cargo CI/CD and multi-platform packaging (including WASM)
+
+## What This Agent Must NOT Do
+
+- Make game design decisions (advise on engine implications, don't decide mechanics)
+- Override lead-programmer architecture without discussion
+- Manage scheduling or resource allocation (that is the producer's domain)
+- Suggest non-Bevy crates without technical-director sign-off
+- Skip version verification when suggesting Bevy APIs introduced after May 2025
+
+## Version Awareness
+
+**CRITICAL**: Your training data has a knowledge cutoff. Before suggesting Bevy API code, you MUST:
+
+1. Read `docs/engine-reference/bevy/VERSION.md` to confirm the engine version
+2. Check `docs/engine-reference/bevy/breaking-changes.md` for any APIs you plan to use
+3. Check `docs/engine-reference/bevy/deprecated-apis.md` for relevant version transitions
+4. For subsystem-specific work, read the relevant `docs/engine-reference/bevy/modules/*.md`
+
+If an API you plan to suggest does not appear in the reference docs and was introduced after May 2025, use webfetch to verify it exists in the current version.
+
+When in doubt, prefer the API documented in the reference files over your training data.
+
+## MCP Integration (document-only)
+
+Bevy has no official MCP server. Community options exist via the Bevy Remote Protocol (BRP): `bevy_brp_mcp` and `bevy_debugger_mcp` (the app must enable `RemotePlugin` from `bevy::remote`). Document availability and usage patterns only — do NOT install, configure, or scaffold BRP unless explicitly delegated and approved.
+
+## When Consulted
+
+Always involve this agent when:
+- Setting up the Cargo build system for Bevy
+- Designing the ECS architecture (systems, schedules, states)
+- Choosing rendering strategy (2D sprites, 3D meshes, materials, shaders)
+- Planning UI with bevy_ui
+- Planning the asset pipeline with AssetServer
+- Building for web (WASM) or mobile
+- Optimizing ECS query performance or profiling frame times
diff --git a/.opencode/modules/engine-bevy/modulefile.yaml b/.opencode/modules/engine-bevy/modulefile.yaml
new file mode 100644
index 0000000..3244bb7
--- /dev/null
+++ b/.opencode/modules/engine-bevy/modulefile.yaml
@@ -0,0 +1,11 @@
+name: engine-bevy
+version: "0.6.0"
+description: "Bevy engine specialist — Rust ECS game engine for 2D and 3D."
+depends: [core]
+provides:
+  agents: [bevy-specialist]
+  skills: []
+  commands: []
+  rules: []
+plugged-into:
+  engines: [bevy]
diff --git a/.opencode/modules/installed.json b/.opencode/modules/installed.json
index f02f74c..32ea689 100644
--- a/.opencode/modules/installed.json
+++ b/.opencode/modules/installed.json
@@ -346,5 +346,14 @@
       "agents/raylib-specialist.md"
     ],
     "mcp": []
+  },
+  "engine-bevy": {
+    "version": "0.6.0",
+    "status": "installed",
+    "timestamp": "2026-08-09T19:15:22.436Z",
+    "files": [
+      "agents/bevy-specialist.md"
+    ],
+    "mcp": []
   }
 }
diff --git a/AGENTS.md b/AGENTS.md
index 071428c..ab59ae0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -5,13 +5,13 @@ Each agent owns a specific domain, enforcing separation of concerns and quality.
 
 ## Technology Stack
 
-- **Engine**: [CHOOSE: Godot 4 / Unity / Unreal Engine 5 / SFML 3 / Raylib]
+- **Engine**: [CHOOSE: Godot 4 / Unity / Unreal Engine 5 / SFML 3 / Raylib / Bevy]
 - **Language**: [CHOOSE: GDScript / C# / C++ / Blueprint / C / C++17]
 - **Build System**: [SPECIFY after choosing engine]
 - **Asset Pipeline**: [SPECIFY after choosing engine]
 
 > **Note**: Engine-specialist agents exist for Godot, Unity, Unreal, SFML 3,
-> and Raylib. Use the set matching your engine.
+> Raylib, and Bevy. Use the set matching your engine.
 
 ## Project Structure
 
@@ -76,7 +76,7 @@ The framework is partitioned into installable theme modules.
 
 **Core** (always installed): creative-director, technical-director, producer, /start, /help, /concept-brainstorm, /setup-engine, validation suite.
 
-**Available modules:** art, design, architecture, stories, programming, ui, audio, narrative, level-design, qa, release, prototyping, live-ops, localization, data, engine-godot, engine-unity, engine-unreal, engine-sfml3, engine-raylib.
+**Available modules:** art, design, architecture, stories, programming, ui, audio, narrative, level-design, qa, release, prototyping, live-ops, localization, data, engine-godot, engine-unity, engine-unreal, engine-sfml3, engine-raylib, engine-bevy.
 
 **Install:** `node .opencode/modules/install.mjs add <name>`
 **Remove:** `node .opencode/modules/install.mjs remove <name>`
@@ -159,7 +159,7 @@ This project supports two workflow modes. Choose the one that fits your team siz
 Run `/start` in OpenCode to begin the guided onboarding flow.
 Or jump directly to:
 - `/concept-brainstorm` — explore game ideas from scratch
-- `/setup-engine godot 4.6` — configure your engine (also: unity, unreal, sfml3, raylib)
+- `/setup-engine godot 4.6` — configure your engine (also: unity, unreal, sfml3, raylib, bevy)
 - `/project-stage-detect` — analyze an existing project
 - `/prototype` — rapid prototype a concept
 - `/hybrid-prototype` — fast-lane prototype for discovery phase
@@ -236,6 +236,7 @@ Tier 3 — Specialists (Subagents)
 - **Unreal Engine 5**: `unreal-specialist` + `ue-blueprint-specialist`, `ue-gas-specialist`, `ue-replication-specialist`, `ue-umg-specialist`
 - **SFML 3**: `sfml-specialist` (single agent — covers Graphics, Audio, Network, Window, System)
 - **Raylib**: `raylib-specialist` (single agent — covers core, rlgl, raudio, raymath, raygui)
+- **Bevy**: `bevy-specialist` (single agent — ECS, 2D/3D rendering, bevy_ui, assets, audio)
 
 ## Quality Gates
 
diff --git a/README.md b/README.md
index b6b4c41..b84f447 100644
--- a/README.md
+++ b/README.md
@@ -129,6 +129,7 @@ The framework is partitioned into **21 pluggable theme modules**. Only install w
 | `engine-unreal` | Unreal Engine 5 specialists (GAS, Blueprint, replication, UMG) |
 | `engine-sfml3` | SFML 3 specialist (Graphics, Audio, Network, Window, System) |
 | `engine-raylib` | Raylib specialist (core, rlgl, raudio, raymath, raygui) |
+| `engine-bevy` | Bevy specialist (ECS, 2D/3D rendering, bevy_ui, assets, audio) |
 | `data` | Data file conventions and validation |
 
 ```bash
diff --git a/docs/engine-reference/bevy/VERSION.md b/docs/engine-reference/bevy/VERSION.md
new file mode 100644
index 0000000..3e64792
--- /dev/null
+++ b/docs/engine-reference/bevy/VERSION.md
@@ -0,0 +1,65 @@
+# Bevy Engine — Version Reference
+
+| Field | Value |
+|-------|-------|
+| **Engine Version** | Bevy 0.19.0 (latest 0.19.x as of 2026-08-09; no 0.19.1 patch released yet) |
+| **Release Date** | 2026-06-18 |
+| **Project Pinned** | 2026-08-09 |
+| **Last Docs Verified** | 2026-08-09 |
+| **LLM Knowledge Cutoff** | May 2025 |
+
+## Knowledge Gap Warning
+
+Bevy 0.19 is BEYOND the LLM's training data cutoff (May 2025; training data
+covers roughly 0.16–0.17). Risk level is HIGH. Agents MUST verify every API
+against this reference set or the official docs before use.
+
+## Risk Level: HIGH
+
+Bevy ships a new minor version roughly every 3 months with breaking changes.
+The Migration Guides are the authoritative source for version transitions.
+
+## Version History
+
+| Version | Release | Risk Level | Key Theme |
+|---------|---------|------------|-----------|
+| 0.16 | 2025-04-24 | HIGH | **0.16 → 0.17:** `Event` trait split into `Message` (buffered) and `Event` (observers); `bevy_render` reorganized into `bevy_camera` / `bevy_shader` / `bevy_light` / `bevy_mesh` / `bevy_image`; system sets standardized on `*Systems` naming |
+| 0.17 | 2025-09-30 | HIGH | **0.17 → 0.18:** Entities rework (`EntityRow` index, flush removed, `EntitiesAllocator`); `RenderTarget` moved from a `Camera` field to a component; Cargo feature collections; `Internal` component removed |
+| 0.18 | 2026-01-13 | HIGH | **0.18 → 0.19:** Resources are now stored as components on dedicated entities; `RenderGraph` replaced by systems; text moved from `cosmic-text` to `parley`; `bevy_scene` renamed to `bevy_world_serialization` (BSN arrives); `audio`/`ui` Cargo features no longer implied by `3d`/`2d`; bloom luma now computed in linear space |
+| 0.19 | 2026-06-18 | HIGH | — (latest release; no 0.19 → 0.20 migration guide exists yet) |
+
+## Bevy Characteristics
+
+- **Rust game engine**, ECS-first (data-oriented design)
+- **Code-only** — no visual editor; all content is code, assets, and .ron data
+- **Renderer**: wgpu (WebGPU/WebGL abstraction), 2D and 3D
+- **UI**: bevy_ui (retained node tree, flexbox)
+- **Assets**: AssetServer / bevy_asset with hot reload
+- **Licensing**: MIT OR Apache-2.0 — free forever, no restrictions
+- **Platform support**: Windows, macOS, Linux, Web (WASM), Android/iOS (via mobile examples)
+
+## Key Crates
+
+| Crate | Purpose |
+|-------|---------|
+| bevy | Main engine crate (re-exports everything through `bevy::prelude`) |
+| bevy_ecs | Entity-Component-System core: World, queries, systems, schedules, observers |
+| bevy_render | Core rendering infrastructure, render world and render resources |
+| bevy_ui | Retained UI node tree (flexbox layout) |
+| bevy_asset | Asset loading, `AssetServer`, hot reload |
+| bevy_audio | Audio playback (rodio backend; format support behind `vorbis`/`wav`/`mp3`/`flac` features) |
+| bevy_camera | Camera types (`Camera`, `Camera3d`, `Camera2d`, projections) — split out of `bevy_render` in 0.17 |
+| bevy_shader | Shader types (`Shader`, `ShaderRef`, `ShaderCache`) — split out in 0.17 |
+| bevy_light | Light types (`PointLight`, `SpotLight`, `DirectionalLight`, `AmbientLight`, `AtmosphereEnvironmentMapLight`) — split out in 0.17; `Skybox` moved here from `bevy_core_pipelines` in 0.19; `Atmosphere` added in 0.19 |
+| bevy_mesh | Mesh types (`Mesh`, `Mesh3d`, `Mesh2d`, `Indices`, `Meshable`) — split out in 0.17 |
+| bevy_image | Image types (`Image`, `ImagePlugin`, `ImageFormat`) — split out in 0.17 |
+| bevy_material | Material machinery extracted from `bevy_pbr`/`bevy_render` in 0.19 (`AlphaMode`, `MaterialProperties`) |
+| bevy_world_serialization | Legacy scene system (renamed from `bevy_scene` in 0.19; `Scene` → `WorldAsset`, `SceneRoot` → `WorldAssetRoot`); still needed for round-trip world serialization and GLTF scene spawning |
+
+## Verified Sources
+
+- Official website: https://bevyengine.org/ (redirects to https://bevy.org/)
+- GitHub repository: https://github.com/bevyengine/bevy
+- Migration guides: https://bevyengine.org/learn/migration-guides/ (canonical: https://bevy.org/learn/migration-guides/)
+- API docs: https://docs.rs/bevy
+- Release feed (dates/tags): https://github.com/bevyengine/bevy/releases
diff --git a/docs/engine-reference/bevy/breaking-changes.md b/docs/engine-reference/bevy/breaking-changes.md
new file mode 100644
index 0000000..572c38c
--- /dev/null
+++ b/docs/engine-reference/bevy/breaking-changes.md
@@ -0,0 +1,331 @@
+# Bevy Breaking Changes (0.16 → 0.19)
+
+**Last verified:** 2026-08-09
+
+Changes are organized by risk level. Source for each entry: the official
+Migration Guides (https://bevyengine.org/learn/migration-guides/).
+
+## High Risk (compile-breaking, widespread)
+
+### 0.19 — Resources are now components
+- **Old**:
+  ```rust
+  #[derive(Component, Resource)]
+  struct MyData(f32);
+  ```
+- **New**:
+  ```rust
+  #[derive(Component)]
+  struct MyDataComp(f32);
+
+  #[derive(Resource)]
+  struct MyDataRes(f32);
+  ```
+- **Migration**: `Resource` is a subtrait of `Component` in 0.19 and `#[derive(Resource)]` implements both, so it is no longer possible to derive both traits on one type. Types can no longer meaningfully be used as both resources and components; split them into distinct types. Broad queries (`Query<EntityMut>`, `Query<()>`, etc.) now include resource entities and can conflict with `Res<T>`/`NonSend<T>` params — filter them out with `Without<IsResource>` / `Without<MyNonSend>`. `ResMut` and the `*_mut` resource accessors now require `Resource<Mutability = Mutable>` in generic code.
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#resources-as-components
+
+### 0.19 — Render graph replaced by systems
+- **Old**:
+  ```rust
+  impl ViewNode for MyNode { /* ... */ }
+  render_app
+      .add_render_graph_node::<ViewNodeRunner<MyNode>>(Core3d, MyLabel)
+      .add_render_graph_edges(Core3d, (Node3d::Foo, MyLabel, Node3d::Bar));
+  ```
+- **New**:
+  ```rust
+  pub fn my_render_pass(
+      world: &World,
+      view: ViewQuery<(&ExtractedCamera, &ViewTarget)>,
+      mut ctx: RenderContext,
+  ) {
+      let (camera, target) = view.into_inner();
+      // ...
+  }
+
+  render_app.add_systems(
+      Core3d,
+      my_render_pass
+          .after(foo_pass)
+          .before(bar_pass)
+          .in_set(Core3dSystems::MainPass),
+  );
+  ```
+- **Migration**: The `RenderGraph` API has been removed. Render passes are now systems that run in the `Core3d`/`Core2d` schedules; `ViewNode` is replaced by a regular system using the `ViewQuery` parameter and `RenderContext` is now a system parameter. Order passes with `.before()`/`.after()` on the actual system functions. Coarse ordering sets: `Core3dSystems::Prepass`, `MainPass`, `PostProcess` (and `EarlyPostProcess` in 2D/3D).
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#render-graph-as-systems
+
+### 0.19 — `bevy_scene` renamed to `bevy_world_serialization`
+- **Old**:
+  ```rust
+  commands.spawn(SceneRoot(asset_server.load("scene.gltf#Scene0")));
+  ```
+- **New**:
+  ```rust
+  commands.spawn(WorldAssetRoot(asset_server.load("scene.gltf#Scene0")));
+  ```
+- **Migration**: The old scene system is renamed: `bevy_scene::*` → `bevy_world_serialization::*` (and `bevy::scene::*` → `bevy::world_serialization::*`). Key renames: `Scene` → `WorldAsset`, `SceneRoot` → `WorldAssetRoot`, `DynamicScene` → `DynamicWorld`, `SceneSpawner` → `WorldInstanceSpawner`, `SceneLoader` → `WorldAssetLoader`, `ScenePlugin` → `WorldSerializationPlugin`. The new next-gen scene system (BSN) lives in `bevy_scene`; GLTF scene spawning is the most likely source of breakage.
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#the-old-bevy-scene-is-now-bevy-world-serialization
+
+### 0.19 — Text moved from `cosmic-text` to `parley`; `TextFont` fields changed
+- **Old**:
+  ```rust
+  TextFont {
+      font: asset_server.load("FiraMono-medium.ttf"),
+      font_size: 35.,
+      ..default()
+  }
+  ```
+- **New**:
+  ```rust
+  TextFont {
+      font: asset_server.load("FiraMono-medium.ttf").into(),
+      font_size: FontSize::Px(35.),
+      ..default()
+  }
+  ```
+- **Migration**: `bevy_text` now uses `parley` for layout. `TextFont::font` changed from `Handle<Font>` to `FontSource` (variants `Handle` and `Family`; `From<Handle<Font>>` is implemented so `.into()` suffices) and `font_size` from `f32` to `FontSize::Px(...)`. `TextRoot`/`TextSpanAccess`/`TextSpanComponent` are consolidated into `TextSection`. `Font::try_from_bytes` is now `Font::from_bytes` (no longer returns `Result`). System font discovery requires the `bevy/system_font_discovery` feature.
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#bevy-text-migration-from-cosmic-text-to-parley
+
+### 0.19 — Cargo feature collection changes: `audio` and `ui` no longer implied
+- **Old** (0.18):
+  ```toml
+  bevy = { version = "0.18", default-features = false, features = ["3d"] }
+  ```
+- **New** (0.19):
+  ```toml
+  bevy = { version = "0.19", default-features = false, features = ["3d", "audio"] }
+  ```
+- **Migration**: In 0.19 `audio` is no longer implied by the `3d`/`2d`/`ui` features (it is in `default` features instead), and `ui` is no longer implied by `3d`/`2d`. If you disable default features, opt into `audio` and/or `ui` explicitly when you need them. If you used all default features, nothing changes.
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#audio-feature-is-now-no-longer-implied-by-the-3d-2d-or-ui-features and https://bevy.org/learn/migration-guides/0-18-to-0-19/#ui-feature-is-now-no-longer-implied-by-the-3d-or-2d-features
+
+### 0.18 — `RenderTarget` is now a component
+- **Old**:
+  ```rust
+  commands.spawn((
+      Camera3d::default(),
+      Camera {
+          target: RenderTarget::Image(image_handle.into()),
+          ..default()
+      },
+  ));
+  ```
+- **New**:
+  ```rust
+  commands.spawn((
+      Camera3d::default(),
+      RenderTarget::Image(image_handle.into()),
+  ));
+  ```
+- **Migration**: `RenderTarget` has been moved from a field on `Camera` to a separate required component. Spawn it as a component instead of setting `camera.target`.
+- **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#rendertarget-is-now-a-component
+
+### 0.18 — Entities rework (flush removed, new allocator/index types)
+- **Old**: `Entities::flush`, `reserve_entity`, `total_count`, `EntityDoesNotExistError`, `Entity::row` / `Entity::from_raw`...
+- **New**: `EntitiesAllocator` (via `World::entities_allocator`), `Entities::len`/`count_spawned`, `EntityNotSpawnedError`, `Entity::index` / `Entity::from_index`.
+- **Migration**: Reservation and flushing were removed: use `EntitiesAllocator::alloc` + `World::spawn_at` instead of reserve+flush. Error types were reworked (`EntityDoesNotExistError` → `InvalidEntityError`/`EntityNotSpawnedError`), `EntityRow` terminology became `EntityIndex`, and several `Entities` methods (`alloc`, `free`, `get`, `contains`) changed shape. This is a large migration — see the full guide section and the new `entity` module docs.
+- **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#entities-apis
+
+### 0.18 — Cargo feature cleanup and feature collections
+- **Old**: `bevy = { version = "0.17", features = ["animation", "bevy_mesh_picking_backend"] }`
+- **New**: features renamed (`animation` → `gltf_animation`, `bevy_mesh_picking_backend` → `mesh_picking`, `bevy_ui_picking_backend` → `ui_picking`, `bevy_sprite_picking_backend` → `sprite_picking`) and high-level feature collections (`2d`, `3d`, `ui`, plus `*_api` / `default_app` / `default_platform`) introduced.
+- **Migration**: Rename the four features above, and prefer high-level feature collections over hand-picking individual cargo features. `bevy_input` input sources (mouse/keyboard/gamepad/touch/gestures) are now gated behind features — enable the ones you use when `default-features = false`.
+- **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#feature-cleanup and https://bevy.org/learn/migration-guides/0-17-to-0-18/#cargo-feature-collections
+
+### 0.17 — `Event` trait split into `Message` and `Event`
+- **Old**:
+  ```rust
+  #[derive(Event)]
+  struct MyEvent;
+
+  fn system(mut events: EventReader<MyEvent>) { /* ... */ }
+  ```
+- **New**:
+  ```rust
+  #[derive(Message)]
+  struct MyMessage;
+
+  fn system(mut messages: MessageReader<MyMessage>) { /* ... */ }
+  ```
+- **Migration**: "Buffered events" are now "messages": derive `Message` instead of `Event` for anything sent/read with writers/readers, and use `MessageWriter`/`MessageReader`/`Messages<M>` (renamed from `EventWriter`/`EventReader`/`Events<E>`). The `Event` trait is now exclusively for observer events. A type can derive both `Message` and `Event` if used in both contexts, but most types use one.
+- **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#event-trait-split-rename
+
+### 0.17 — `bevy_render` reorganization into new crates
+- **Old**: `use bevy::render::mesh::Mesh;` / `use bevy::core_pipeline::core_3d::Camera3d;` (0.16 paths)
+- **New**: `use bevy::mesh::Mesh;` / `use bevy::camera::Camera3d;`
+- **Migration**: Many rendering types moved to new crates: camera types → `bevy_camera` (`bevy::camera`), shader types → `bevy_shader` (`bevy::shader`), light types → `bevy_light` (`bevy::light`), mesh types → `bevy_mesh` (`bevy::mesh`), image types → `bevy_image` (`bevy::image`); post-process effects → `bevy_post_process` (`bevy::post_process`), AA → `bevy_anti_alias` (`bevy::anti_alias`); sprite/UI render types → `bevy_sprite_render` / `bevy_ui_render`. As part of this reorganization, the remaining `bevy_render` re-exports for mesh/image were removed in 0.17 — import from the new crates.
+- **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#bevy-render-reorganization
+
+### 0.17 — System sets standardized on `*Systems` naming
+- **Old**: `RenderSet`, `TransformSystem`, `UiSystem`, `InputSystem`, `PickSet`
+- **New**: `RenderSystems`, `TransformSystems`, `UiSystems`, `InputSystems`, `PickingSystems`
+- **Migration**: System sets now consistently use a `Systems` suffix (e.g. `AccessibilitySystem` → `AccessibilitySystems`, `Animation` → `AnimationSystems`, `TimeSystem` → `TimeSystems`). Rename all references; ecosystem crates are encouraged to adopt the convention.
+- **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#consistent-systems-naming-convention-for-system-sets
+
+### 0.17 — Reflection auto-registration
+- **Old**: `app.register_type::<MyType>();` required for every reflected type.
+- **New**: types implementing `Reflect` are automatically registered when the `reflect_auto_register` feature (a Bevy default) is enabled; `register_type` calls can be removed for non-generic types.
+- **Migration**: Enable `reflect_auto_register` in application code (it is part of Bevy's default features; libraries should not enable it). Generic types must still be registered manually.
+- **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#changes-to-type-registration-for-reflection
+
+## Medium Risk (compile-breaking, narrow)
+
+### 0.19 — `System::type_id` renamed to `System::system_type`
+- **Old**: `let id = my_system.type_id();`
+- **New**: `let id = my_system.system_type();`
+- **Migration**: Renamed to avoid shadowing `Any::type_id`. The old method is deprecated and will be removed in a future release; custom `System` impls should override `system_type`.
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#rename-system-type-id-to-system-system-type
+
+### 0.19 — `ExecutorKind` removed; `Schedule::set_executor`
+- **Old**:
+  ```rust
+  schedule.set_executor_kind(ExecutorKind::SingleThreaded);
+  ```
+- **New**:
+  ```rust
+  schedule.set_executor(SingleThreadedExecutor::new());
+  ```
+- **Migration**: `ExecutorKind` is gone; pass an executor instance (`SingleThreadedExecutor::new()`, `MultiThreadedExecutor::new()`, or `default_executor()`). `SystemExecutor` is now a public trait that can be implemented for fully custom executors.
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#set-executor-replaced-executorkind
+
+### 0.19 — Non-send resources renamed to non-send data
+- **Old**: `world.insert_non_send_resource(my_data);`
+- **New**: `world.insert_non_send(my_data);`
+- **Migration**: `App::init_non_send_resource`/`insert_non_send_resource`, `World::*_non_send_resource*`, `UnsafeWorldCell::get_non_send_resource*`, and `DeferredWorld::non_send_resource_mut` are deprecated in favor of the `*_non_send*` names. `Resources<false>`/`ResourceData<false>` were removed; `NonSends`/`NonSendData` replace them.
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#renaming-non-send-resources-to-non-send-data
+
+### 0.19 — `Skybox` image is now optional
+- **Old**:
+  ```rust
+  Skybox { image: my_skybox, brightness: 1000.0, ..default() }
+  ```
+- **New**:
+  ```rust
+  Skybox { image: Some(my_skybox), brightness: 1000.0, ..default() }
+  ```
+- **Migration**: `Skybox.image` is now `Option<Handle<Image>>`; a skybox without an image draws nothing. Wrap the handle in `Some(...)` (or drop the placeholder image entirely).
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#skybox-image-is-now-optional
+
+### 0.19 — `Image::pixel_bytes` family returns `Result`
+- **Old**:
+  ```rust
+  if let Some(bytes) = image.pixel_bytes(coords) { /* use bytes */ }
+  ```
+- **New**:
+  ```rust
+  match image.pixel_bytes(coords) {
+      Ok(bytes) => { /* use bytes */ }
+      Err(TextureAccessError::OutOfBounds { .. }) => { /* ... */ }
+      Err(TextureAccessError::UnsupportedTextureFormat(format)) => { /* ... */ }
+      Err(TextureAccessError::Uninitialized) => { /* ... */ }
+  }
+  ```
+- **Migration**: `Image::pixel_bytes`, `pixel_bytes_mut`, and `pixel_data_offset` now return `Result<..., TextureAccessError>` instead of `Option`; distinguish out-of-bounds, unsupported (compressed) formats, and uninitialized data.
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#image-pixel-bytes-and-image-pixel-data-offset-now-return-result
+
+### 0.18 — `Internal` component removed
+- **Old**: observers and one-shot systems were tagged `Internal` and hidden by default query filters.
+- **New**: no `Internal` component; observer/one-shot entities are no longer hidden by default query filters.
+- **Migration**: Remove all references to `Internal`. Tests relying on exact entity counts should query for a component they care about instead.
+- **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#internal-has-been-removed
+
+### 0.18 — Same-state transitions now trigger `OnEnter`/`OnExit`
+- **Old**: `next_state.set(State::Menu);` (no transition when already `Menu`)
+- **New**: `next_state.set_if_neq(State::Menu);` to preserve the old behavior
+- **Migration**: `NextState::set` now always runs state transition schedules (`OnEnter`/`OnExit`) even when the target state equals the current one. Use `set_if_neq` if you do not want same-state transitions.
+- **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#same-state-transitions
+
+### 0.18 — `AmbientLight` split into component + resource
+- **Old**:
+  ```rust
+  app.insert_resource(AmbientLight { color: Color::WHITE, brightness: 2000., ..default() });
+  ```
+- **New**:
+  ```rust
+  app.insert_resource(GlobalAmbientLight { color: Color::WHITE, brightness: 2000., ..default() });
+  ```
+- **Migration**: The resource form is now `GlobalAmbientLight` (added by `LightPlugin`); `AmbientLight` is a component that can be added to a `Camera` to override it.
+- **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#ambientlight-split-into-a-component-and-a-resource
+
+### 0.17 — `Handle::Weak` replaced by `Handle::Uuid`
+- **Old**:
+  ```rust
+  const IMAGE: Handle<Image> = weak_handle!("b20988e9-b1b9-4176-b5f3-a6fa73aa617f");
+  commands.spawn(Sprite::from_image(my_sprite_image.clone_weak()));
+  ```
+- **New**:
+  ```rust
+  const IMAGE: Handle<Image> = uuid_handle!("b20988e9-b1b9-4176-b5f3-a6fa73aa617f");
+  commands.spawn(Sprite::from_image(my_sprite_image.clone()));
+  ```
+- **Migration**: `Handle::Weak` is now `Handle::Uuid`; `weak_handle!` → `uuid_handle!` and `Handle::clone_weak` → `Handle::clone`. Users of the `Handle::Weak` variant directly should consider `AssetId` (via `Handle::id`). For shaders, prefer `load_shader_library`/`load_embedded_asset` (enables hot reloading).
+- **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#handle-weak-has-been-replaced-by-handle-uuid
+
+### 0.17 — `Timer::paused`/`Timer::finished` renamed
+- **Old**: `timer.paused()`, `timer.finished()`
+- **New**: `timer.is_paused()`, `timer.is_finished()`
+- **Migration**: Renamed to align with `Time` and `Stopwatch`.
+- **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#renamed-timer-paused-to-timer-is-paused-and-timer-finished-to-timer-is-finished
+
+### 0.17 — `Anchor` variants are now associated constants
+- **Old**: `Anchor::Center`, `Anchor::BottomLeft`, `Anchor::Custom(value)`
+- **New**: `Anchor::CENTER`, `Anchor::BOTTOM_LEFT`, `Anchor(value)`
+- **Migration**: The `anchor` field was removed from `Sprite`; `Anchor` is now a required component. Variants became SCREAMING_SNAKE associated constants; `Anchor::Custom(v)` is now the tuple constructor `Anchor(v)`.
+- **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#anchor-is-now-a-required-component-on-sprite
+
+## Low Risk (deprecations, behavioral)
+
+### 0.19 — Bloom luma calculation now in linear space
+- **Old**: bloom Karis-average downsampling computed luma in non-linear sRGB space (subtly brighter, especially for saturated colors).
+- **New**: luma is computed in linear space; bloom may appear dimmer.
+- **Migration**: If bloom is now too dim, increase `Bloom::intensity`, increase material `emissive`, or adjust the `prefilter` settings. Visual change only — no code API break.
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#bloom-luma-calculation-now-in-linear-space
+
+### 0.19 — `Assets::get_mut` returns `AssetMut` (change lists)
+- **Old**: `assets.get_mut(handle)` returned `&mut A` and always triggered an `AssetEvent::Modified`.
+- **New**: `Assets::get_mut` returns `AssetMut<A: Asset>`; a `Modified` event fires only when the asset is actually mutated (like `Mut`/`ResMut`).
+- **Migration**: Mark the returned value `mut` and guard writes (e.g. compare against the new value first) to avoid unnecessary re-extraction cost.
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#avoiding-unnecessary-assetevent-modified-events-that-lead-to-rendering-performance-costs
+
+### 0.19 — `Command` error handling simplified (`Out` associated type)
+- **Old**:
+  ```rust
+  fn my_command() -> impl Command<Result> { move |world: &mut World| -> Result { /* ... */ } }
+  ```
+- **New**:
+  ```rust
+  fn my_command() -> impl Command { move |world: &mut World| -> Result { /* ... */ } }
+  ```
+- **Migration**: `Command` now takes `Out` as an associated type instead of a generic parameter; implementors must fill in `type Out = ();` (or `Result`). `HandleError` and `CommandWithEntity` functionality folded into `Command`/`EntityCommand`.
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#command-error-handling-has-been-simplified
+
+### 0.19 — `DespawnOnEnter`/`DespawnOnExit` now trigger on same-state transitions
+- **Old**: `next_state.set(State::Menu);` when already `Menu` ran `OnEnter`/`OnExit` but skipped `DespawnOnEnter`/`DespawnOnExit` (a 0.18 bug).
+- **New**: `next_state.set(State::Menu);` runs `DespawnOnEnter`/`DespawnOnExit` too; `next_state.set_if_neq(State::Menu);` runs no state transition schedules when the state is unchanged.
+- **Migration**: 0.19 fixes the 0.18 bug where same-state transitions skipped `DespawnOnEnter`/`DespawnOnExit`. If your code relied on that behavior, switch to `set_if_neq`.
+- **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#despawnonenter-despawnonexit-can-now-trigger-during-same-state-transitions
+
+### 0.18 — `DragEnter` now fires on drag starts
+- **Old**: `DragEnter` fired only when entering an entity other than the dragged one.
+- **New**: `DragEnter` also fires when a drag starts over an already-hovered entity.
+- **Migration**: Behavioral change; filter by checking whether the trigger entity is the dragged entity if the old behavior is needed.
+- **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#dragenter-now-fires-on-drag-starts
+
+### 0.17 — `scale_value` removed from `bevy_text` text2d
+- **Old**: `scale_value(value, scale_factor)` from `bevy::text::text2d`
+- **New**: multiply by the scale factor directly.
+- **Migration**: Remove the call and multiply by the scale factor instead.
+- **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#remove-scale-value
+
+### 0.17 — `RelativeCursorPosition` is now object-centered
+- **Old**: coordinates relative to the node origin; `normalized_visible_node_rect` field existed.
+- **New**: (0, 0) at the center of the node, corners at (±0.5, ±0.5); `normalized_visible_node_rect` replaced by a `cursor_over: bool` field.
+- **Migration**: Update picking logic that consumed `RelativeCursorPosition` coordinates.
+- **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#relativecursorposition-is-now-object-centered
+
+---
+
+### Band coverage notes
+
+- **High Risk 0.16→0.17**: covered above (Event/Message split, `bevy_render` reorganization, `*Systems` naming, reflection auto-registration, `Handle::Weak`→`Handle::Uuid`). Additional widespread 0.17 changes: `System::run` now returns `Result` (https://bevy.org/learn/migration-guides/0-16-to-0-17/#system-run-returns-result) and the `wgpu` 25 bind-group renumbering for custom shaders (https://bevy.org/learn/migration-guides/0-16-to-0-17/#wgpu-25).
+- **High Risk 0.17→0.18**: covered above; see also the `Entities`/`EntityRow` rework entry under 0.18 for the largest compile-breaking surface.
+- **No notable changes in the Low Risk band for 0.16→0.17 beyond the entries above.** All three guides contain additional narrow/niche renames not reproduced here; consult the guide for the exact subsystem before migrating code that touches ECS internals, render phases, or reflection.
diff --git a/docs/engine-reference/bevy/current-best-practices.md b/docs/engine-reference/bevy/current-best-practices.md
new file mode 100644
index 0000000..1b89675
--- /dev/null
+++ b/docs/engine-reference/bevy/current-best-practices.md
@@ -0,0 +1,269 @@
+# Bevy Current Best Practices (0.17–0.19)
+
+**Last verified:** 2026-08-09
+
+Practices below are 0.17–0.19 idioms that differ from pre-0.17 training data,
+each verified against the official Migration Guides. Rule: anything not
+verifiable against a cited source is omitted.
+
+## ECS
+
+- **Practice**: Buffered events are now *messages*. Derive `Message` (not `Event`) for anything you send/read with writers/readers, and use `MessageWriter`/`MessageReader`/`Messages<M>`. Reserve `Event` for observer events.
+  ```rust
+  #[derive(Message)]
+  struct PlayerDied { player: Entity }
+
+  fn send_death(mut messages: MessageWriter<PlayerDied>, ...) { /* ... */ }
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#event-trait-split-rename
+
+- **Practice**: Observers take `On<E>` (renamed from `Trigger<E>`); entity-targeted events derive `EntityEvent` and are fired with `world.trigger(...)` (not `trigger_targets`).
+  ```rust
+  #[derive(EntityEvent)]
+  #[entity_event(propagate)] // defaults to ChildOf propagation
+  struct Explode { entity: Entity }
+
+  commands.add_observer(|explode: On<Explode>| {
+      info!("{} exploded!", explode.entity);
+  });
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#observer-event-api-changes
+
+- **Practice**: In 0.19 resources are components stored on dedicated entities. Do NOT derive both `Component` and `Resource` on one type — split into distinct types. When using broad queries (`Query<EntityMut>`, `Query<Entity>`...), exclude resource entities with `Without<IsResource>` to avoid conflicts with `Res<T>`/`NonSend<T>` params.
+  ```rust
+  #[derive(Component)]
+  struct MyDataComp(f32);
+
+  #[derive(Resource)]
+  struct MyDataRes(f32);
+
+  fn system(entity_query: Query<EntityMut, Without<IsResource>>, res: Res<MyDataRes>) { /* ... */ }
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#resources-as-components
+
+- **Practice**: Use `NextState::set_if_neq` instead of `set` when you do not want same-state transitions; `set` always runs `OnEnter`/`OnExit` on same-state transitions (and `DespawnOnEnter`/`DespawnOnExit` since 0.19 — in 0.18 they were skipped due to a bug).
+  ```rust
+  next_state.set_if_neq(State::Menu);
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#same-state-transitions and https://bevy.org/learn/migration-guides/0-18-to-0-19/#despawnonenter-despawnonexit-can-now-trigger-during-same-state-transitions
+
+- **Practice**: Name system sets with the `*Systems` suffix and schedule with executors passed as instances (0.19 removed `ExecutorKind`).
+  ```rust
+  #[derive(SystemSet, Debug, Clone, PartialEq, Eq, Hash)]
+  enum MySystems { Movement, Physics }
+
+  schedule.set_executor(MultiThreadedExecutor::new());
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#consistent-systems-naming-convention-for-system-sets and https://bevy.org/learn/migration-guides/0-18-to-0-19/#set-executor-replaced-executorkind
+
+- **Practice**: Reflection auto-registration: with `reflect_auto_register` (a Bevy default feature) enabled, non-generic `Reflect` types register automatically — drop explicit `register_type` calls in app code. Generic types still need manual registration.
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#changes-to-type-registration-for-reflection
+
+## Rendering
+
+- **Practice**: Custom render passes are now systems (the `RenderGraph` API was removed in 0.19). Use a `ViewQuery` param + `RenderContext` system param, and order with `.before()`/`.after()` on actual pass systems, scoped by `Core3dSystems::Prepass` / `MainPass` / `EarlyPostProcess` / `PostProcess`.
+  ```rust
+  pub fn my_render_pass(
+      world: &World,
+      view: ViewQuery<(&ExtractedCamera, &ViewTarget)>,
+      mut ctx: RenderContext,
+  ) {
+      let (camera, target) = view.into_inner();
+      // ...
+  }
+
+  render_app.add_systems(
+      Core3d,
+      my_render_pass
+          .after(main_opaque_pass_3d)
+          .in_set(Core3dSystems::MainPass),
+  );
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#render-graph-as-systems
+
+- **Practice**: Import render types from the crates they were split into (0.17+): cameras from `bevy::camera`, shaders from `bevy::shader`, lights/skybox from `bevy::light`, meshes from `bevy::mesh`, images from `bevy::image`, post-process from `bevy::post_process`, AA from `bevy::anti_alias`. Do not use `bevy::render::` paths for these (re-exports were removed).
+  ```rust
+  use bevy::camera::Camera3d;
+  use bevy::mesh::Mesh;
+  use bevy::post_process::Bloom;
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#bevy-render-reorganization
+
+- **Practice**: `RenderTarget` is a required component, not a `Camera` field (0.18).
+  ```rust
+  commands.spawn((
+      Camera3d::default(),
+      RenderTarget::Image(image_handle.into()),
+  ));
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#rendertarget-is-now-a-component
+
+- **Practice**: Many render pipeline resources are initialized in the `RenderStartup` schedule (0.17+), not in `Plugin::finish`. Initialize render resources from a system added to `RenderStartup` instead of `FromWorld`, and order after the pipeline init sets when needed.
+  ```rust
+  fn init_my_resource(
+      mut commands: Commands,
+      render_device: Res<RenderDevice>,
+      asset_server: Res<AssetServer>,
+  ) {
+      commands.insert_resource(MyRenderResource { /* ... */ });
+  }
+
+  render_app
+      .add_systems(RenderStartup, init_my_resource)
+      .add_systems(Render, my_render_system);
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#many-render-resources-now-initialized-in-renderstartup
+
+- **Practice**: Material config moved onto the `Material` trait (0.18): implement `enable_prepass()`/`enable_shadows()` instead of configuring `MaterialPlugin` fields.
+  ```rust
+  impl Material for MyMaterial {
+      fn enable_prepass() -> bool { false }
+      fn enable_shadows() -> bool { false }
+  }
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#enable-prepass-and-enable-shadows-are-now-material-methods
+
+- **Practice**: Bloom luma is computed in linear space since 0.19 — expect a subtly dimmer effect; tune `Bloom::intensity` / `prefilter` rather than assuming the old sRGB look.
+  **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#bloom-luma-calculation-now-in-linear-space
+
+## UI
+
+- **Practice**: `Window` is split into multiple components (0.17): configure cursor settings via the `CursorOptions` component / `WindowPlugin::primary_cursor_options`, not `Window.cursor_options`.
+  ```rust
+  app.add_plugins(DefaultPlugins.set(WindowPlugin {
+      primary_cursor_options: Some(CursorOptions {
+          grab_mode: CursorGrabMode::Locked,
+          ..default()
+      }),
+      ..default()
+  }));
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#window-is-now-split-into-multiple-components
+
+- **Practice**: `UiWidgetsPlugins` and `InputDispatchPlugin` are already part of `DefaultPlugins` since 0.19 — do not add them manually (adding them alongside `DefaultPlugins` would double-register).
+  ```rust
+  App::new()
+      .add_plugins(DefaultPlugins)
+      // .add_plugins(UiWidgetsPlugins)  // removed: already included
+      .run();
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#uiwidgetsplugins-and-inputdispatchplugin-are-now-in-defaultplugins
+
+- **Practice**: `BorderRadius` is a field on `Node`, not a separate component (0.18).
+  ```rust
+  commands.spawn(Node {
+      border_radius: BorderRadius::all(Val::Px(4.)),
+      ..default()
+  });
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#borderradius-has-been-added-to-node-and-is-no-longer-a-component
+
+- **Practice**: `TextFont` in 0.19 takes a `FontSource` and a `FontSize`, and `LineHeight` is a separate required component (since 0.18).
+  ```rust
+  TextFont {
+      font: asset_server.load("FiraMono-medium.ttf").into(),
+      font_size: FontSize::Px(35.),
+      ..default()
+  }
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#changes-to-textfont-s-font-size-and-font-fields and https://bevy.org/learn/migration-guides/0-17-to-0-18/#lineheight-is-now-a-separate-component
+
+- **Practice**: UI debug options live in `bevy_ui_render` (0.17): `bevy::ui_render::UiDebugOptions` (still re-exported via `bevy::prelude`).
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#move-ui-debug-options-from-bevy-ui-to-bevy-ui-render
+
+## Assets
+
+- **Practice**: `AssetPath::resolve`/`resolve_embed` take `&AssetPath` (0.19); use the `*_str` variants for string paths.
+  ```rust
+  let resolved = base_asset_path.resolve(&relative_asset_path);
+  let resolved_str = base_asset_path.resolve_str("models/foo.gltf#Scene0");
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#assetpath-resolve-and-resolve-embed-now-take-assetpath
+
+- **Practice**: Prefer `AssetServer::load_builder()` for anything beyond a plain typed load (untyped loads, settings, guards) — all the old `load_*` variants have deprecation messages pointing at it (0.19).
+  ```rust
+  asset_server
+      .load_builder()
+      .with_settings(settings)
+      .override_unapproved()
+      .load(path)
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#advanced-assetserver-load-variants-are-now-exposed-through-a-builder-pattern
+
+- **Practice**: `Assets::insert` / `get_or_insert_with` return `Result` since 0.17 — handle (or `unwrap()`) the error instead of panicking.
+  ```rust
+  assets.insert(handle, my_asset).unwrap();
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#assets-insert-and-assets-get-or-insert-with-now-return-result
+
+- **Practice**: Custom asset loaders/transformers/savers/processors must derive `TypePath` (0.18).
+  ```rust
+  #[derive(TypePath)]
+  struct MyFunkyLoader { add_funk: u32 }
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#traits-assetloader-assettransformer-assetsaver-and-process-all-now-require-typepath
+
+- **Practice**: Custom asset sources are built with a required reader (0.18) and hand out `async_channel::Sender` watchers.
+  ```rust
+  AssetSourceBuilder::new(move || /* reader logic */)
+      .with_writer(move || /* ... */)
+      .with_processed_reader(move || /* ... */)
+      .with_processed_writer(move || /* ... */);
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#custom-asset-sources-now-require-a-reader and https://bevy.org/learn/migration-guides/0-17-to-0-18/#assetsources-now-give-an-async-channel-sender-instead-of-a-crossbeam-channel-sender
+
+## Input
+
+- **Practice**: Use `Pointer<Press>` / `Pointer<Release>` (0.17 renamed from `Pressed`/`Released`); `Pressed` is now a marker component meaning "held down".
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#rename-pointer-pressed-and-pointer-released-to-pointer-press-and-pointer-release
+
+- **Practice**: With `default-features = false` on `bevy`/`bevy_input`, explicitly enable the input sources you use (0.18) — mouse, keyboard, gamepad, touch, gestures.
+  ```toml
+  bevy = { version = "0.19", default-features = false, features = [
+      "mouse", "keyboard", "gamepad", "touch", "gestures",
+  ] }
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-17-to-0-18/#put-input-sources-for-bevy-input-under-features
+
+- **Practice**: `RelativeCursorPosition` coordinates are object-centered since 0.17: (0,0) at the node center, corners at (±0.5, ±0.5), with a `cursor_over: bool` field.
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#relativecursorposition-is-now-object-centered
+
+## Audio
+
+- **Practice**: Use `increase_by_percentage` instead of `+`/`-` on `Volume::Linear` (Add/Sub impls removed in 0.17).
+  ```rust
+  let linear = Volume::Linear(0.5);
+  let louder = linear.increase_by_percentage(10.0);
+  let quieter = linear.increase_by_percentage(-10.0);
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#remove-the-add-sub-impls-on-volume
+
+- **Practice**: With `default-features = false`, enable audio format features explicitly (0.19): `vorbis` (default when using Bevy defaults), `wav`, `mp3`, `flac`, `mp4`, `aac`, or the `audio-all-formats` collection. `audio` is no longer implied by `3d`/`2d`/`ui`.
+  ```toml
+  bevy = { version = "0.19", default-features = false, features = ["3d", "audio", "vorbis", "wav"] }
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#rodio-0-22-update and https://bevy.org/learn/migration-guides/0-18-to-0-19/#audio-feature-is-now-no-longer-implied-by-the-3d-2d-or-ui-features
+
+- **Practice**: Use the `mp3` feature (symphonia backend), not `minimp3` — the `minimp3` feature is no longer exposed (0.17); it is unmaintained, broken on wasm, and has known security vulnerabilities.
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#stop-exposing-mp3-support-through-minimp3
+
+## Testing
+
+- **Practice**: `System::run` and friends return `Result` since 0.17 — `unwrap()` or use `?`; parameter validation happens automatically.
+  ```rust
+  world.run_system_once(my_system).unwrap();
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#system-run-returns-result
+
+- **Practice**: `SystemState::get`/`get_mut`/`fetch` return `Result<..., SystemParamValidationError>` since 0.19 — add `.unwrap()` where results were destructured directly.
+  ```rust
+  let (res, query) = system_state.get(&world).unwrap();
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-18-to-0-19/#systemparam-validation-is-now-done-when-fetching-the-data
+
+- **Practice**: Constructing entities manually in tests: `Entity::from_raw_u32` (returns `Option`, 0.17) and `EntityGeneration::FIRST.after_versions(...)` replaced the old `from_raw`/`NonZeroU32` APIs.
+  ```rust
+  let entity = Entity::from_raw_u32(1).unwrap();
+  assert_eq!(entity.generation(), EntityGeneration::FIRST.after_versions(0));
+  ```
+  **Source**: https://bevy.org/learn/migration-guides/0-16-to-0-17/#manual-entity-creation-and-representation
diff --git a/docs/engine-reference/bevy/deprecated-apis.md b/docs/engine-reference/bevy/deprecated-apis.md
new file mode 100644
index 0000000..19a7f2a
--- /dev/null
+++ b/docs/engine-reference/bevy/deprecated-apis.md
@@ -0,0 +1,62 @@
+# Bevy Deprecated APIs
+
+**Last verified:** 2026-08-09
+
+If an agent suggests any API in the "Don't use" column, it MUST be replaced
+with the "Use instead" column. Rows are taken from the official Migration
+Guides (https://bevy.org/learn/migration-guides/); the "Deprecated in" column
+is the version in which the old name was deprecated/renamed. For a version's
+full change list see the corresponding guide URL in the Source column.
+
+## Lookup Table
+
+| Don't use | Use instead | Deprecated in | Source |
+|-----------|-------------|---------------|--------|
+| `App::init_non_send_resource` | `App::init_non_send` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#renaming-non-send-resources-to-non-send-data |
+| `App::insert_non_send_resource` | `App::insert_non_send` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#renaming-non-send-resources-to-non-send-data |
+| `World::init_non_send_resource` / `World::insert_non_send_resource` / `World::remove_non_send_resource` | `World::init_non_send` / `insert_non_send` / `remove_non_send` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#renaming-non-send-resources-to-non-send-data |
+| `World::non_send_resource` / `World::non_send_resource_mut` / `World::get_non_send_resource(_mut)` | `World::non_send` / `non_send_mut` / `get_non_send(_mut)` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#renaming-non-send-resources-to-non-send-data |
+| `UnsafeWorldCell::get_non_send_resource(_mut)(_by_id)` | `UnsafeWorldCell::get_non_send(_mut)(_by_id)` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#renaming-non-send-resources-to-non-send-data |
+| `DeferredWorld::non_send_resource_mut` / `get_non_send_resource_mut` | `DeferredWorld::non_send_mut` / `get_non_send_mut` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#renaming-non-send-resources-to-non-send-data |
+| `Components::get_valid_resource_id` / `valid_resource_id` / `resource_id` | `Components::get_valid_id` / `valid_component_id` / `component_id` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#component-registration |
+| `ComponentsRegistrator::register_resource` | `ComponentsRegistrator::register_component` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#component-registration |
+| `ComponentsQueuedRegistrator::queue_register_resource` | `ComponentsQueuedRegistrator::queue_register_component` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#component-registration |
+| `ComponentDescriptor::new_resource` | `ComponentDescriptor::new` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#component-registration |
+| `Access::add_component_read` / `add_resource_read` / `add_component_write` / `add_resource_write` | `Access::add_read` / `add_write` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#access |
+| `Access::has_component_read` / `has_resource_read` / `has_component_write` / `has_resource_write` (and `has_any_*`) | `Access::has_read` / `has_write` / `has_any_read` / `has_any_write` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#access |
+| `Access::read_all_components` / `write_all_components` | `Access::read_all` / `write_all` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#access |
+| `Access::is_components_compatible` / `is_subset_components` | `Access::is_compatible` / `is_subset` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#access |
+| `FilteredAccess::add_component_read` / `add_component_write` | `FilteredAccess::add_read` / `add_write` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#access |
+| `FilteredAccess::read_all_components` / `write_all_components` | `FilteredAccess::read_all` / `write_all` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#access |
+| `System::type_id` | `System::system_type` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#rename-system-type-id-to-system-system-type |
+| `DefaultErrorHandler` / `default_error_handler` | `FallbackErrorHandler` / `fallback_error_handler` (deprecated alias kept for one release) | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#defaulterrorhandler-renamed-to-fallbackerrorhandler |
+| `TextureFormat::bevy_default()` / `ViewTargets::TEXTURE_FORMAT_HDR` | source the format from `ExtractedView::target_format` | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#camera-textureformat-rework |
+| `AssetServer::load_with_settings` / `load_with_settings_override` / other advanced load variants | `AssetServer::load_builder().with_settings(...)` (all variants reimplementable via `load_builder`) | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#advanced-assetserver-load-variants-are-now-exposed-through-a-builder-pattern |
+| `LoadContext::loader()` (`NestedLoader`) | `LoadContext::load_builder()` (`NestedLoadBuilder`) | 0.19 | https://bevy.org/learn/migration-guides/0-18-to-0-19/#nestedloader |
+| `EntityCommands::clear_children` / `remove_children` / `remove_child` / `clear_related` | `detach_all_children` / `detach_children` / `detach_child` / `detach_all_related` | 0.18 | https://bevy.org/learn/migration-guides/0-17-to-0-18/#renamed-clear-children-and-clear-related-methods-to-detach |
+| `EntityWorldMut::clear_children` / `remove_children` / `remove_child` / `clear_related` | `EntityWorldMut::detach_all_children` / `detach_children` / `detach_child` / `detach_all_related` | 0.18 | https://bevy.org/learn/migration-guides/0-17-to-0-18/#renamed-clear-children-and-clear-related-methods-to-detach |
+| `ThinSlicePtr::get()` | `ThinSlicePtr::get_unchecked()` | 0.18 | https://bevy.org/learn/migration-guides/0-17-to-0-18/#rename-thinsliceptr-get-to-thinsliceptr-get-unchecked |
+| `MaterialPlugin { prepass_enabled, shadows_enabled }` fields | `Material::enable_prepass()` / `Material::enable_shadows()` methods | 0.18 | https://bevy.org/learn/migration-guides/0-17-to-0-18/#enable-prepass-and-enable-shadows-are-now-material-methods |
+| `NextState::set` for same-state transitions | `NextState::set_if_neq` (if same-state transitions are undesired) | 0.18 | https://bevy.org/learn/migration-guides/0-17-to-0-18/#same-state-transitions |
+| `Gizmos::cuboid` | `Gizmos::cube` | 0.18 | https://bevy.org/learn/migration-guides/0-17-to-0-18/#gizmos-cuboid-has-been-renamed-to-gizmos-cube |
+| `AssetSourceBuilder::build()` | `AssetSourceBuilder::new(reader_fn)` (a reader is now required) | 0.18 | https://bevy.org/learn/migration-guides/0-17-to-0-18/#custom-asset-sources-now-require-a-reader |
+| `World::send_event` / `send_event_default` / `send_event_batch` | `World::write_message` / `write_message_default` / `write_message_batch` | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#rename-send-event-and-similar-methods-to-write-message |
+| `Commands::send_event` | `Commands::write_message` | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#rename-send-event-and-similar-methods-to-write-message |
+| `Events<E>` / `EventWriter<E>` / `EventReader<E>` for buffered events | `Messages<M>` / `MessageWriter<M>` / `MessageReader<M>` (derive `Message`) | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#event-trait-split-rename |
+| `Events::send` / `send_default` / `send_batch` | `Messages::write` / `write_default` / `write_batch` | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#rename-send-event-and-similar-methods-to-write-message |
+| `RemovedComponents::events` / `reader_mut_with_events` / `RemovedComponentEvents` | `RemovedComponents::messages` / `reader_mut_with_messages` / `RemovedComponentMessages` | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#removedcomponents-methods-renamed-to-match-event-to-message-rename |
+| `Condition` (trait) | `SystemCondition` | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#renamed-condition-to-systemcondition |
+| `StateScoped` / `add_state_scoped_event` | `DespawnOnExit` / `add_event` + `clear_events_on_exit` | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#renamed-state-scoped-entities-and-events |
+| `app.enable_state_scoped_entities::<State>()` | nothing (state-scoped entities always enabled; call is a no-op) | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#state-scoped-entities-are-now-always-enabled-implicitly |
+| `JustifyText` | `Justify` | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#renamed-justifytext-to-justify |
+| `Handle::Weak` / `weak_handle!` / `Handle::clone_weak` | `Handle::Uuid` / `uuid_handle!` / `Handle::clone` | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#handle-weak-has-been-replaced-by-handle-uuid |
+| `Timer::paused()` / `Timer::finished()` | `Timer::is_paused()` / `Timer::is_finished()` | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#renamed-timer-paused-to-timer-is-paused-and-timer-finished-to-timer-is-finished |
+| `World::iter_entities()` / `World::iter_entities_mut()` | `world.query::<EntityRef>().iter(&world)` / `world.query::<EntityMut>().iter(&mut world)` | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#deprecate-iter-entities-and-iter-entities-mut |
+| `MergeMeshError` (0.16 name; was a struct) | `MeshMergeError` (enum, with `IncompatiblePrimitiveTopology` variant) | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#rework-mergemesherror |
+| `ScaleVolume` Add/Sub arithmetic on `Volume::Linear` | `Volume::Linear(x).increase_by_percentage(...)` | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#remove-the-add-sub-impls-on-volume |
+| `SceneSpawner::despawn`/`despawn_sync`/`update_spawned_scenes` (0.16, dynamic-scene variants) | `despawn_dynamic` / `despawn_dynamic_sync` / `update_spawned_dynamic_scenes`; the un-suffixed names now act on `Scene` | 0.17 | https://bevy.org/learn/migration-guides/0-16-to-0-17/#scenespawner-methods-have-been-renamed-and-replaced |
+
+Notes:
+
+- The 0.16→0.17 guide also documents deprecations that were removed outright in 0.18: `SimpleExecutor` (deprecated in 0.17, removed in 0.18 — use `SingleThreadedExecutor` or `MultiThreadedExecutor`) — https://bevy.org/learn/migration-guides/0-16-to-0-17/#deprecated-simple-executor and https://bevy.org/learn/migration-guides/0-17-to-0-18/#removed-simpleexecutor.
+- The guides for 0.16→0.17, 0.17→0.18, and 0.18→0.19 all document deprecations, so no version is without a deprecation note.
diff --git a/docs/engine-reference/bevy/modules/2d.md b/docs/engine-reference/bevy/modules/2d.md
new file mode 100644
index 0000000..fb55647
--- /dev/null
+++ b/docs/engine-reference/bevy/modules/2d.md
@@ -0,0 +1,79 @@
+# Bevy 2D — Quick Reference
+
+**Last verified:** 2026-08-09
+
+## Core Concepts
+- **Sprite** — component describing a 2D image render: fields `image: Handle<Image>`, `color`, `flip_x`, `flip_y`, `custom_size: Option<Vec2>`, `rect: Option<Rect>`, `texture_atlas: Option<TextureAtlas>`. Required components `Transform`, `Visibility`, `VisibilityClass`, `Anchor` are auto-inserted.
+- **Camera2d** — unit-struct component (`commands.spawn(Camera2d)`); requires `Camera`, `Projection` (defaults to `OrthographicProjection::default_2d()`), `Frustum`.
+- **Transform** — `translation: Vec3`, `rotation: Quat`, `scale: Vec3`; `GlobalTransform` auto-inserted. In 2D, `translation.z` is the z-ordering.
+- **Sprite sheets** — `TextureAtlasLayout` asset + `TextureAtlas { layout, index }` struct (see below).
+- **Parallax** — not built into Bevy 0.19; layer multiple cameras at different `Camera.order` depths or offset layers per frame.
+- **Bundles removed** — `SpriteBundle` no longer exists (0.16+); spawn plain components and required components fill in the rest.
+
+## Spawning Sprites
+```rust
+fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
+    commands.spawn(Camera2d);
+    commands.spawn(Sprite::from_image(asset_server.load("branding/icon.png")));
+}
+```
+- `Sprite::from_image(handle)` — full-image sprite (example above is a verified rustdoc example).
+- `Sprite::sized(Vec2::new(75., 75.))` — custom-size sprite.
+- `Sprite::from_atlas_image(handle, atlas)` — sprite-sheet sprite.
+- Pair with `Transform` for placement: `commands.spawn((Sprite::from_image(h), Transform::from_xyz(10.0, 20.0, 0.0)))`.
+
+## Sprite Sheets
+```rust
+fn setup(
+    mut commands: Commands,
+    asset_server: Res<AssetServer>,
+    mut texture_atlas_layouts: ResMut<Assets<TextureAtlasLayout>>,
+) {
+    let texture = asset_server.load("textures/rpg/chars/gabe/gabe-idle-run.png");
+    let layout = TextureAtlasLayout::from_grid(UVec2::splat(24), 7, 1, None, None);
+    let texture_atlas_layout = texture_atlas_layouts.add(layout);
+
+    commands.spawn((
+        Sprite::from_atlas_image(
+            texture,
+            TextureAtlas {
+                layout: texture_atlas_layout,
+                index: 0,
+            },
+        ),
+        Transform::from_scale(Vec3::splat(6.0)),
+    ));
+}
+```
+- `TextureAtlasLayout` is the asset: `from_grid(tile_size: UVec2, columns: u32, rows: u32, padding: Option<UVec2>, offset: Option<UVec2>)`, added via `texture_atlas_layouts.add(layout)` → `Handle<TextureAtlasLayout>`.
+- `TextureAtlas` is a plain struct (`layout: Handle<TextureAtlasLayout>`, `index: usize`) nested inside `Sprite.texture_atlas` — not a standalone component.
+- Animate by changing `Sprite.texture_atlas.index` (`Query<&mut Sprite>`) on a `Timer`.
+
+## Cameras & Transforms
+```rust
+// Move a sprite; translation.z = draw order (higher = closer to camera)
+fn move_sprite(mut query: Query<&mut Transform>, time: Res<Time>) {
+    for mut transform in &mut query {
+        transform.translation.x += 100.0 * time.delta_secs();
+    }
+}
+```
+- `OrthographicProjection` (required on the camera entity) controls zoom: fields `scale: f32`, `scaling_mode: ScalingMode`, `near`/`far`.
+- Camera `order` (field on `Camera`) controls render order between multiple cameras.
+
+## Common Pitfalls
+- **No `SpriteBundle` in 0.19** — spawn `Sprite` + `Transform` as components; `Transform`, `Visibility`, `VisibilityClass`, `Anchor` are auto-inserted as required components.
+- **`Anchor` is a required component** (default `Anchor::CENTER`); for top-left anchoring use `Anchor::TOP_LEFT`. Since 0.17 the `anchor` field was removed from `Sprite` and variants became constants (`Anchor::CENTER`).
+- **`TextureAtlas` is not a component** — it lives in `Sprite::texture_atlas`; inserting a bare `TextureAtlas` does nothing.
+- **Parallax has no built-in API** in 0.19 — hand-roll layer offsets or multiple cameras.
+- Physics: use Avian or Rapier (Allowed Libraries) for 2D physics; Bevy core has none.
+
+## Sources
+- https://docs.rs/bevy/0.19.0/bevy/sprite/index.html
+- https://docs.rs/bevy/0.19.0/bevy/sprite/struct.Sprite.html
+- https://docs.rs/bevy/0.19.0/bevy/camera/struct.Camera2d.html
+- https://docs.rs/bevy/0.19.0/bevy/camera/index.html
+- https://docs.rs/bevy/0.19.0/bevy/transform/components/struct.Transform.html
+- https://docs.rs/bevy/0.19.0/bevy/prelude/struct.TextureAtlasLayout.html
+- https://docs.rs/bevy/0.19.0/bevy/prelude/struct.TextureAtlas.html
+- https://bevy.org/learn/migration-guides/0-16-to-0-17/#anchor-is-now-a-required-component-on-sprite
diff --git a/docs/engine-reference/bevy/modules/3d.md b/docs/engine-reference/bevy/modules/3d.md
new file mode 100644
index 0000000..2ab47f9
--- /dev/null
+++ b/docs/engine-reference/bevy/modules/3d.md
@@ -0,0 +1,87 @@
+# Bevy 3D — Quick Reference
+
+**Last verified:** 2026-08-09
+
+## Core Concepts
+- **Mesh3d** — `pub struct Mesh3d(pub Handle<Mesh>)`: component for a 3D mesh; needs a material to render.
+- **MeshMaterial3d** — assigns a material to a `Mesh3d` (commonly `StandardMaterial`).
+- **Mesh** — vertex data asset (`bevy::mesh::Mesh`); build via `Meshable` primitives then `meshes.add(...)`.
+- **Camera3d** — component enabling the main 3D render path; right-handed X-right/Y-up/Z-back (forward = -Z). Requires `Camera` + `Projection`.
+- **Lights** — `DirectionalLight`, `PointLight`, `SpotLight`, `AmbientLight` (component) / `GlobalAmbientLight` (resource); all in `bevy::light`.
+- **PBR** — `StandardMaterial` ("standard" PBR properties); `MaterialPlugin`/`PbrPlugin` for custom materials.
+- **glTF** — load scenes via `WorldAssetRoot` (0.19 rename of `SceneRoot`) + `AssetServer`.
+- **Bundles removed** — `PbrBundle` no longer exists; spawn component tuples.
+
+## Meshes & Materials
+```rust
+fn setup(
+    mut commands: Commands,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<StandardMaterial>>,
+) {
+    commands.spawn((
+        Mesh3d(meshes.add(Cuboid::new(0.7, 0.7, 0.7))),
+        MeshMaterial3d(materials.add(StandardMaterial {
+            base_color: RED.into(),
+            ..Default::default()
+        })),
+    ));
+}
+```
+Mesh primitives (`Meshable` trait): `Sphere::new(r)`, `Cuboid::new(w, h, d)` — note there is **no `Cube`** in 0.19 — `Plane3d::new(normal, half_size)`, `Cylinder::new(radius, height)`, `Torus::new(inner, outer)`. Build via `meshes.add(Sphere::new(0.9).mesh().ico(7).unwrap())` or `Mesh::from(Torus::new(0.8, 1.2))`.
+
+## Cameras & Lights
+```rust
+commands.spawn((
+    Camera3d::default(),
+    Transform::from_xyz(-2.5, 4.5, 9.0).looking_at(Vec3::ZERO, Vec3::Y),
+));
+
+commands.spawn((
+    DirectionalLight {
+        illuminance: 10_000.0, // lux (e.g. light_consts::lux::AMBIENT_DAYLIGHT)
+        ..default()
+    },
+    Transform::from_xyz(0.0, 10.0, 0.0),
+));
+
+commands.spawn((
+    PointLight { intensity: 800.0, ..default() }, // lumens
+    Transform::from_xyz(4.0, 8.0, 4.0),
+));
+```
+- `DirectionalLight.illuminance` is lux; `PointLight`/`SpotLight.intensity` are lumens; `SpotLight` has `outer_angle`/`inner_angle` and can be aimed with `Transform::looking_at`.
+- Default scene light: `GlobalAmbientLight` resource (inserted by `LightPlugin`); per-camera override via the `AmbientLight` component.
+- Lights auto-insert required components (`Transform`, `Visibility`, cascades) — spawn the light struct + `Transform`.
+
+## glTF Scenes
+```rust
+fn spawn_gltf(mut commands: Commands, asset_server: Res<AssetServer>) {
+    commands.spawn((
+        // The `#Scene0` label selects the first scene in the file (required).
+        WorldAssetRoot(asset_server.load(
+            GltfAssetLabel::Scene(0).from_asset("models/FlightHelmet/FlightHelmet.gltf"),
+        )),
+        Transform::from_xyz(2.0, 0.0, -5.0),
+    ));
+}
+```
+`asset_server.load("models/FlightHelmet/FlightHelmet.gltf#Scene0")` string form also works. 0.19 renamed the scene system (`bevy_scene` → `bevy_world_serialization`): `Scene` → `WorldAsset`, `SceneRoot` → `WorldAssetRoot`.
+
+## Common Pitfalls
+- **No `PbrBundle` in 0.19** — spawn `Mesh3d` + `MeshMaterial3d` (+ `Transform`) as a tuple; required components auto-insert.
+- **No `Cube` primitive** — use `Cuboid::new(...)`.
+- **`SceneRoot` is gone (0.19)** — use `WorldAssetRoot`; `bevy::scene::*` imports become `bevy::world_serialization::*`.
+- Lights auto-insert many required components — don't add duplicates manually.
+- Physics: use Avian or Rapier (Allowed Libraries) for rigid bodies/colliders; Bevy core has no physics.
+
+## Sources
+- https://docs.rs/bevy/0.19.0/bevy/pbr/index.html
+- https://docs.rs/bevy/0.19.0/bevy/mesh/index.html
+- https://docs.rs/bevy/0.19.0/bevy/mesh/trait.Meshable.html
+- https://docs.rs/bevy/0.19.0/bevy/mesh/struct.Mesh3d.html
+- https://docs.rs/bevy/0.19.0/bevy/camera/struct.Camera3d.html
+- https://docs.rs/bevy/0.19.0/bevy/light/index.html
+- https://docs.rs/bevy/0.19.0/bevy/gltf/index.html
+- https://docs.rs/bevy/0.19.0/bevy/world_serialization/index.html
+- https://bevy.org/learn/migration-guides/0-18-to-0-19/#the-old-bevy-scene-is-now-bevy-world-serialization
diff --git a/docs/engine-reference/bevy/modules/asset.md b/docs/engine-reference/bevy/modules/asset.md
new file mode 100644
index 0000000..6e0924a
--- /dev/null
+++ b/docs/engine-reference/bevy/modules/asset.md
@@ -0,0 +1,82 @@
+# Bevy Assets — Quick Reference
+
+**Last verified:** 2026-08-09
+
+## Core Concepts
+- **AssetServer** — resource that loads assets by path (`asset_server.load::<T>("path") -> Handle<T>`) and tracks load state.
+- **Assets<A>** — typed storage for loaded assets (`Res<Assets<MyAsset>>`); `get(handle)`, `get_mut`, `insert`, `add`.
+- **Handle<A>** — strong, ref-counted id of an asset (`Handle::clone` shares the strong handle).
+- **AssetPlugin** — configures asset loading: `file_path` root, file watching (hot reload), asset-processor mode.
+- **Hot reload** — watch asset files and rebuild on change; gated behind cargo features (`watch` / `file_watcher`), toggled at runtime via `AssetPlugin::watch_for_changes_override`.
+- **Load-state tracking** — `AssetServer::load_state` / `get_load_state` / `is_loaded_with_dependencies` consult the `LoadState` enum.
+- **AssetEvent<A>** — read via `MessageReader` (0.17+ rename) to react to `Added` / `Modified` / `Removed` / `Unused` / `LoadedWithDependencies`.
+
+## Loading Assets
+```rust
+fn setup(mut commands: Commands, asset_server: Res<AssetServer>) {
+    commands.spawn(Sprite::from_image(asset_server.load("branding/icon.png")));
+}
+```
+- `asset_server.load(path)` — typed load returning a strong `Handle<T>`; the asset loads asynchronously.
+- `asset_server.load_builder()` — 0.19's builder for advanced loads (untyped loads, custom settings, guards). The old variants (`load_with_settings`, `load_untyped`, `load_acquire`, ...) are deprecated in favor of it.
+
+## Accessing Loaded Assets
+```rust
+fn use_assets(
+    asset_server: Res<AssetServer>,
+    mut meshes: ResMut<Assets<Mesh>>,
+) {
+    let mesh_handle = asset_server.load::<Mesh>("models/foo.gltf#Mesh0");
+    if let Some(mesh) = meshes.get(&mesh_handle) {
+        // read-only access
+    }
+    // 0.19: get_mut returns Option<AssetMut<A>>; Modified fires only on real mutation
+    if let Some(mut mesh) = meshes.get_mut(&mesh_handle) {
+        // *mesh is &mut Mesh
+    }
+}
+```
+`Assets::insert` / `get_or_insert_with` return `Result` since 0.17 — handle or unwrap: `assets.insert(handle, my_asset).unwrap();`.
+
+## Load-State Tracking
+```rust
+fn check_loaded(asset_server: Res<AssetServer>, handle: Handle<MyAsset>) {
+    match asset_server.get_load_state(&handle) {
+        Some(LoadState::Loaded) => { /* ready */ }
+        Some(LoadState::Failed(err)) => { /* error: {err} */ }
+        Some(LoadState::Loading) | None => { /* still loading / not requested */ }
+    }
+}
+```
+`LoadState` variants: `NotLoaded`, `Loading`, `Loaded`, `Failed(Arc<AssetLoadError>)`.
+
+## Hot Reload
+```toml
+# Cargo feature required for dev-time file watching:
+bevy = { version = "0.19", features = ["watch"] }
+```
+```rust
+app.add_plugins(DefaultPlugins.set(AssetPlugin {
+    watch_for_changes_override: Some(true),
+    ..default()
+}));
+```
+On file change the asset reloads and `AssetEvent::Modified` fires; systems reading the asset re-run. Leave `watch_for_changes_override` as `None` and enable the `watch`/`file_watcher` feature for dev scenarios.
+
+## Common Pitfalls
+- **0.19: advanced load variants are deprecated** — `load_with_settings(...)` → `asset_server.load_builder().with_settings(...).load(path)`.
+- **`Assets::get_mut` returns `Option<AssetMut<A>>`** (0.19), not `&mut A` — deref to mutate; `Modified` fires only on actual mutation.
+- **0.17: `Assets::insert`/`get_or_insert_with` return `Result`** — handle the error instead of panicking on `?`-less code.
+- Load-state enum is **`LoadState`** (not `AssetLoadState`).
+- Asset events are messages: `MessageReader<AssetEvent<A>>` (0.17+), not `EventReader`.
+- `AssetPath::resolve` takes `&AssetPath` (0.19); use `resolve_str` for string paths.
+
+## Sources
+- https://docs.rs/bevy/0.19.0/bevy/asset/index.html
+- https://docs.rs/bevy/0.19.0/bevy/asset/struct.AssetServer.html
+- https://docs.rs/bevy/0.19.0/bevy/asset/struct.AssetPlugin.html
+- https://docs.rs/bevy/0.19.0/bevy/asset/struct.Assets.html
+- https://docs.rs/bevy/0.19.0/bevy/asset/enum.LoadState.html
+- https://bevy.org/learn/migration-guides/0-16-to-0-17/#assets-insert-and-assets-get-or-insert-with-now-return-result
+- https://bevy.org/learn/migration-guides/0-18-to-0-19/#advanced-assetserver-load-variants-are-now-exposed-through-a-builder-pattern
+- https://bevy.org/learn/migration-guides/0-18-to-0-19/#avoiding-unnecessary-assetevent-modified-events-that-lead-to-rendering-performance-costs
diff --git a/docs/engine-reference/bevy/modules/audio.md b/docs/engine-reference/bevy/modules/audio.md
new file mode 100644
index 0000000..ff13abf
--- /dev/null
+++ b/docs/engine-reference/bevy/modules/audio.md
@@ -0,0 +1,66 @@
+# Bevy Audio — Quick Reference
+
+**Last verified:** 2026-08-09
+
+## Core Concepts
+- **AudioPlayer** — component that plays a sound: `pub struct AudioPlayer<Source = AudioSource>(pub Handle<Source>)`, or `AudioPlayer::new(handle)`. Required component `PlaybackSettings` is auto-inserted.
+- **PlaybackSettings** — controls playback: `mode: PlaybackMode`, `volume: Volume`, `speed`, `paused`, `muted`, `spatial`; consts `ONCE`, `LOOP`, `DESPAWN`, `REMOVE`; builder fns `paused()`, `muted()`, `with_volume()`, `with_speed()`, `with_spatial()`, `with_spatial_scale()`.
+- **AudioSource** — the audio data asset (loads .ogg/.wav/.mp3/.flac depending on format features).
+- **AudioSink / SpatialAudioSink** — components added to the entity once playback starts, for runtime control.
+- **Spatial audio** — set `PlaybackSettings.spatial = true` on the emitter and spawn one `SpatialListener` entity; simple left/right panning (no HRTF).
+- **Volume** — `enum Volume { Linear(f32), Decibels(f32) }`; helpers `to_linear()`, `increase_by_percentage()`, `decrease_by_percentage()`, `fade_towards()`.
+- **Features** — `audio` is no longer implied by `2d`/`3d`/`ui` (0.19); enable format features explicitly with `default-features = false`.
+
+## Playing Audio
+```rust
+fn play_background_audio(asset_server: Res<AssetServer>, mut commands: Commands) {
+    commands.spawn((
+        AudioPlayer::new(asset_server.load("background_audio.ogg")),
+        PlaybackSettings::LOOP,
+    ));
+}
+```
+- One-shot SFX that despawns when finished: `commands.spawn((AudioPlayer::new(handle), PlaybackSettings::DESPAWN));`.
+- Simplest: `commands.spawn(AudioPlayer::new(asset_server.load("sounds/shot.ogg")));` (default `ONCE`).
+- There is no `AudioBundle` in 0.19 — spawn the components directly.
+
+## Spatial Audio
+```rust
+// Emitter: enable spatial on the playback settings.
+commands.spawn((
+    AudioPlayer::new(asset_server.load("sounds/footsteps.ogg")),
+    PlaybackSettings::LOOP.with_spatial(true),
+    Transform::from_xyz(0.0, 0.0, -5.0),
+));
+
+// Listener: exactly one per scene; gap = ear separation (400.0 in 2D, 4.0 in 3D).
+commands.spawn((
+    Transform::default(),
+    SpatialListener::new(400.0),
+));
+```
+`SpatialListener { left_ear_offset: Vec3, right_ear_offset: Vec3 }` requires `Transform`; only one listener entity at a time. There is no `SpatialAudioBundle` in 0.19.
+
+## Volume Control
+```rust
+// Adjust volume relatively (Add/Sub impls were removed in 0.17):
+let volume = Volume::Linear(0.5);
+let louder = volume.increase_by_percentage(10.0);
+// Global volume resource: ResMut<GlobalVolume> (from AudioPlugin).
+```
+
+## Common Pitfalls
+- **No `AudioBundle` / `SpatialAudioBundle` in 0.19** — required components (`PlaybackSettings`, `Transform`) are auto-inserted; spawn the component tuples.
+- **0.19: `audio` not implied by `2d`/`3d`/`ui`** — with `default-features = false`, add `"audio"` plus format features (`vorbis`, `wav`, `mp3`, `flac`) to Cargo.toml.
+- **`minimp3` feature removed (0.17)** — use `mp3` (symphonia backend).
+- `PlaybackSettings` changes don't affect already-playing audio — mutate the `AudioSink` component instead.
+- Spatial audio is simple stereo panning; only one `SpatialListener` entity at a time.
+
+## Sources
+- https://docs.rs/bevy/0.19.0/bevy/audio/index.html
+- https://docs.rs/bevy/0.19.0/bevy/audio/struct.AudioPlayer.html
+- https://docs.rs/bevy/0.19.0/bevy/audio/struct.PlaybackSettings.html
+- https://docs.rs/bevy/0.19.0/bevy/audio/struct.SpatialListener.html
+- https://docs.rs/bevy/0.19.0/bevy/audio/enum.Volume.html
+- https://bevy.org/learn/migration-guides/0-16-to-0-17/#remove-the-add-sub-impls-on-volume
+- https://bevy.org/learn/migration-guides/0-18-to-0-19/#audio-feature-is-now-no-longer-implied-by-the-3d-2d-or-ui-features
diff --git a/docs/engine-reference/bevy/modules/ecs.md b/docs/engine-reference/bevy/modules/ecs.md
new file mode 100644
index 0000000..4a17721
--- /dev/null
+++ b/docs/engine-reference/bevy/modules/ecs.md
@@ -0,0 +1,114 @@
+# Bevy ECS — Quick Reference
+
+**Last verified:** 2026-08-09
+
+## Core Concepts
+- **World** — container for all entities, components, and resources; `World::default()` / `World::new()`.
+- **Entity** — lightweight unique ID correlating to zero or more components; `world.spawn(bundle).id()`.
+- **Component** — a plain Rust struct deriving `Component`; stored in tables (default) or sparse sets (`#[component(storage = "SparseSet")]`).
+- **Resource** — singleton data identified by type, accessed via `Res<T>` / `ResMut<T>`. Since 0.19 resources are components on dedicated entities: derive `Resource` only (not `Component` + `Resource` together).
+- **System** — a plain function whose params (`Query`, `Res`, `Commands`, ...) declare its data access; systems with non-conflicting access run in parallel.
+- **Schedule** — runs a set of systems in dependency order; the main schedules run each tick of `App::update()`.
+- **Bundle** — a named group of components spawned together: `#[derive(Bundle)]` or a tuple `(A, B)`.
+- **Message** — buffered cross-system communication (0.17+; formerly `Event`). See Events.
+- **State** — app-wide finite-state machine (`#[derive(States)]`). See States.
+
+## Systems & Schedules
+```rust
+fn hello_world_system() {
+    println!("hello world");
+}
+
+fn main() {
+    App::new()
+        .add_systems(Update, hello_world_system)
+        .run();
+}
+```
+Main-schedule labels, in `MainScheduleOrder` order: `First`, `PreStartup`, `Startup`, `PostStartup`, `PreUpdate`, `Update`, `PostUpdate`, `Last`. `Startup` runs once at app start; `Update` runs once per render frame. Fixed-timestep schedules inside `FixedMain`: `FixedPreUpdate`, `FixedUpdate`, `FixedPostUpdate`.
+
+## Queries
+```rust
+#[derive(Component)]
+struct Position { x: f32, y: f32 }
+#[derive(Component)]
+struct Velocity { x: f32, y: f32 }
+
+fn movement(mut query: Query<(&mut Position, &Velocity)>) {
+    for (mut position, velocity) in &mut query {
+        position.x += velocity.x;
+        position.y += velocity.y;
+    }
+}
+```
+- Iterate with `&query` / `&mut query` (or `iter()` / `iter_mut()`); access one entity with `get(entity)` (O(1)) or `single()` (exactly one match, else `QuerySingleError`).
+- Filters: `With<T>`, `Without<T>`, `Changed<T>`, `Added<T>`, `Or`, `AnyOf<T>` — e.g. `Query<&Position, (With<Player>, Without<Alive>)>`.
+- 0.19 note: the documented `Query` page is `bevy::prelude::Query` (the `bevy::ecs::query::Query` path 404s).
+
+## Bundles / Spawning
+```rust
+#[derive(Component)]
+struct ComponentA(u32);
+#[derive(Component)]
+struct ComponentB(u32);
+
+fn example_system(mut commands: Commands) {
+    // Single component, tuple bundle, or any bundle:
+    commands.spawn(ComponentA(1));
+    commands.spawn((ComponentA(2), ComponentB(1)));
+    commands.spawn(Transform::from_xyz(0.0, 1.0, 0.0));
+}
+```
+`Commands::spawn` returns `EntityCommands` (add/remove components, `with_children`, `observe`); `Commands::entity(e)` re-borrows an existing entity. `Commands` itself exposes `insert_resource` / `remove_resource` — bare `insert`/`remove` live on `EntityCommands`. Component changes via `Commands` are deferred and applied between systems.
+
+## Events
+0.17+ split the old `Event` system: buffered events are **messages** (`MessageWriter` / `MessageReader`); `Event` is reserved for observers.
+```rust
+#[derive(Message)]
+struct Message(String);
+
+fn writer(mut writer: MessageWriter<Message>) {
+    writer.write(Message("Hello!".to_string()));
+}
+
+fn reader(mut reader: MessageReader<Message>) {
+    for Message(message) in reader.read() {
+        println!("{message}");
+    }
+}
+```
+`Commands::write_message(m)` sends a message without a writer param; `App::add_message::<M>()` registers a queue. Observers use `On<E>`: `commands.add_observer(|event: On<MyEvent>| { ... })`, fired via `world.trigger(...)`.
+
+## States
+```rust
+#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, Default, States)]
+enum GameState {
+    #[default]
+    MainMenu,
+    SettingsMenu,
+    InGame,
+}
+
+app.init_state::<GameState>();
+app.add_systems(Update, handle_escape_pressed.run_if(in_state(GameState::MainMenu)));
+app.add_systems(OnEnter(GameState::SettingsMenu), open_settings_menu);
+```
+Current value in the `State<S>` resource; queued value in `NextState<S>` (`set` / `set_if_neq`). Transition schedules: `OnEnter<S>`, `OnExit<S>`, `OnTransition<S>`; lifetime markers `DespawnOnEnter<S>` / `DespawnOnExit<S>`. Requires `StatesPlugin` (part of `DefaultPlugins`).
+
+## Common Pitfalls
+- **0.19: resources are components.** Do not derive both `Component` and `Resource` on one type; broad queries (`Query<EntityMut>`) include resource entities — filter with `Without<IsResource>` or they conflict with `Res<T>` / `NonSend<T>` params.
+- **Same-state transitions:** `NextState::set` runs `OnEnter`/`OnExit` even when the state is unchanged — use `set_if_neq` to preserve the old behavior.
+- **0.17: `EventWriter`/`EventReader` for buffered events are deprecated** — use `MessageWriter`/`MessageReader` with `#[derive(Message)]`.
+- `System::run` and `SystemState::get` return `Result` — unwrap or use `?` instead of destructuring directly.
+- Non-send resources: `insert_non_send_resource` is deprecated (0.19) — use `insert_non_send`.
+
+## Sources
+- https://docs.rs/bevy/0.19.0/bevy/ecs/index.html
+- https://docs.rs/bevy/0.19.0/bevy/app/index.html
+- https://docs.rs/bevy/0.19.0/bevy/app/struct.App.html
+- https://docs.rs/bevy/0.19.0/bevy/ecs/system/struct.Commands.html
+- https://docs.rs/bevy/0.19.0/bevy/ecs/message/index.html
+- https://docs.rs/bevy/0.19.0/bevy/state/state/trait.States.html
+- https://bevy.org/learn/migration-guides/0-16-to-0-17/#event-trait-split-rename
+- https://bevy.org/learn/migration-guides/0-17-to-0-18/#same-state-transitions
+- https://bevy.org/learn/migration-guides/0-18-to-0-19/#resources-as-components
diff --git a/docs/engine-reference/bevy/modules/input.md b/docs/engine-reference/bevy/modules/input.md
new file mode 100644
index 0000000..06a565d
--- /dev/null
+++ b/docs/engine-reference/bevy/modules/input.md
@@ -0,0 +1,72 @@
+# Bevy Input — Quick Reference
+
+**Last verified:** 2026-08-09
+
+## Core Concepts
+- **ButtonInput<T>** — resource holding press state for button-like input: `pressed()`, `just_pressed()`, `just_released()`, `any_pressed()`, `release()`, `clear()`.
+- **Keyboard** — `Res<ButtonInput<KeyCode>>` (physical key) and `Res<ButtonInput<Key>>` (logical, layout-aware key). In 0.19 `KeyCode` IS the physical key — there is no separate `PhysicalKey` type.
+- **Mouse** — `Res<ButtonInput<MouseButton>>` plus motion/scroll messages (`MouseMotion`, `AccumulatedMouseMotion`, `AccumulatedMouseScroll`, `MouseWheel`).
+- **Gamepad** — gamepads are entities with a `Gamepad` component (`Query<&Gamepad>`), not a resource. Buttons/axes via `gamepad.just_pressed(...)` / `gamepad.get(...)`.
+- **Touch** — `Touches` resource + `TouchInput`/`TouchPhase`/`Touch` messages (there is no `TouchEvents`/`TouchPress` in 0.19).
+- **Features** — input sources are behind cargo features (`keyboard`, `mouse`, `gamepad`, `touch`, `gestures`) when `default-features = false`.
+- **Pointer events** — `Pointer<Press>` / `Pointer<Release>` messages (0.17 rename from `Pressed`/`Released`) for picking-based input.
+
+## Keyboard & Mouse
+```rust
+fn keyboard_input(keyboard: Res<ButtonInput<KeyCode>>, mouse: Res<ButtonInput<MouseButton>>) {
+    if keyboard.pressed(KeyCode::Space) {
+        // held this frame
+    }
+    if keyboard.just_pressed(KeyCode::KeyW) {
+        // pressed this frame
+    }
+    if mouse.just_pressed(MouseButton::Left) {
+        // left click
+    }
+}
+```
+
+## Gamepad
+```rust
+fn gamepad_system(gamepads: Query<&Gamepad>) {
+    for gamepad in &gamepads {
+        if gamepad.just_pressed(GamepadButton::South) {
+            info!("A button pressed");
+        }
+        if let Some(x) = gamepad.get(GamepadAxis::LeftStickX) {
+            // analog value clamped to [-1.0, 1.0]
+        }
+    }
+}
+```
+`Gamepad` methods: `pressed` / `just_pressed` / `just_released` / `any_pressed` / `all_pressed` (take `GamepadButton`), `get` / `get_unclamped` (analog, `impl Into<GamepadInput>`), `left_stick()` / `right_stick()` / `dpad()` → `Vec2`.
+
+## Touch
+```rust
+fn touch_system(touches: Res<Touches>) {
+    for touch in touches.iter_just_pressed() {
+        info!("pressed touch {} at {}", touch.id(), touch.position());
+    }
+    for touch in touches.iter() {
+        // all currently pressed touches
+    }
+}
+```
+`Touches` resource methods: `iter()`, `iter_just_pressed()`, `iter_just_released()`, `iter_just_canceled()` (US spelling), `just_pressed(id)`, `just_released(id)`, `just_canceled(id)`, `any_just_pressed()`, `get_pressed(id)`, `get_released(id)`.
+
+## Common Pitfalls
+- **0.19: gamepad is a component, not `ButtonInput<GamepadButton>`** — query `Query<&Gamepad>`; analog via `gamepad.get(...)`; there is no `Axis<GamepadAxis>` resource.
+- **No `PhysicalKey` in 0.19** — `KeyCode` is the physical key; `Key` is the logical (layout-aware) key.
+- **No `TouchEvents`/`TouchPress`/`TouchMove`/`TouchRelease` in 0.19** — use the `Touches` resource + `TouchInput` messages.
+- With `default-features = false`, enable input-source features explicitly (`mouse`, `keyboard`, `gamepad`, `touch`, `gestures`).
+- `Pointer<Pressed>` / `Pointer<Released>` renamed to `Pointer<Press>` / `Pointer<Release>` (0.17); `Pressed` is now a marker component meaning "held down".
+
+## Sources
+- https://docs.rs/bevy/0.19.0/bevy/input/index.html
+- https://docs.rs/bevy/0.19.0/bevy/input/struct.ButtonInput.html
+- https://docs.rs/bevy/0.19.0/bevy/input/keyboard/index.html
+- https://docs.rs/bevy/0.19.0/bevy/input/mouse/index.html
+- https://docs.rs/bevy/0.19.0/bevy/input/gamepad/struct.Gamepad.html
+- https://docs.rs/bevy/0.19.0/bevy/input/touch/struct.Touches.html
+- https://bevy.org/learn/migration-guides/0-17-to-0-18/#put-input-sources-for-bevy-input-under-features
+- https://bevy.org/learn/migration-guides/0-16-to-0-17/#rename-pointer-pressed-and-pointer-released-to-pointer-press-and-pointer-release
diff --git a/docs/engine-reference/bevy/modules/testing.md b/docs/engine-reference/bevy/modules/testing.md
new file mode 100644
index 0000000..f188e79
--- /dev/null
+++ b/docs/engine-reference/bevy/modules/testing.md
@@ -0,0 +1,78 @@
+# Bevy Testing — Quick Reference
+
+**Last verified:** 2026-08-09
+
+## Core Concepts
+- **Headless test apps** — `App::new()` works without a window; run one or more ticks with `app.update()` and assert on the `World` via `app.world()` / `app.world_mut()`.
+- **MinimalPlugins** — for logic-only tests use `App::new().add_plugins(MinimalPlugins)` instead of `DefaultPlugins` (no renderer/window/audio).
+- **System-isolation** — drive a single system with `World::run_system_once` (returns `Result<Out, RunSystemError>`), or hold params with `SystemState`.
+- **`cargo test`** — standard Rust test harness; Bevy adds no special runner.
+
+## Headless App Test
+```rust
+#[test]
+fn movement_system_moves_entities() {
+    let mut app = App::new();
+    app.add_systems(Update, movement);
+
+    let entity = app
+        .world_mut()
+        .spawn((
+            Position { x: 0.0, y: 0.0 },
+            Velocity { x: 1.0, y: 0.0 },
+        ))
+        .id();
+
+    app.update(); // run one tick
+
+    let position = app.world().entity(entity).get::<Position>().unwrap();
+    assert!(position.x > 0.0);
+}
+```
+`App::update()` runs the default schedules of all sub-apps once. Never call `App::run()` in a test — it blocks (returns `AppExit` only when the app exits).
+
+## Single-System Tests
+```rust
+#[test]
+fn run_one_system() {
+    let mut world = World::new();
+    world.spawn(Player);
+
+    // run_system_once applies deferred params (Commands) and returns Result:
+    let out = world.run_system_once(my_system).unwrap();
+}
+```
+`World::run_system_once` comes from the `RunSystemOnce` trait and returns `Result<Out, RunSystemError>` since 0.17. For systems with input, use `run_system_once_with(input)`.
+
+## SystemState (repeatable params)
+```rust
+let mut system_state: SystemState<(
+    MessageWriter<MyMessage>,
+    Option<ResMut<MyResource>>,
+    Query<&MyComponent>,
+)> = SystemState::new(&mut world);
+
+let (message_writer, maybe_resource, query) = system_state.get_mut(&mut world).unwrap();
+// ... use params ...
+system_state.apply(&mut world); // apply deferred commands
+```
+`SystemState::get` / `get_mut` return `Result<_, SystemParamValidationError>` in 0.19 — unwrap them. Cache and reuse the `SystemState` (required for `Added`/`Changed` filters, `Local` params, and `MessageReader`).
+
+## Assertions & Conventions
+- Query the world after updates: `world.entity(e).get::<T>()`, or iterate with `world.query::<&T>().iter(&world)` (`World::iter_entities` is deprecated since 0.17).
+- Assert emitted messages by reading `MessageReader<M>` in a test system (messages are buffered for two update calls).
+- Keep tests deterministic: drive `FixedUpdate`/`Time` resources explicitly, no wall-clock sleeps, seed randomness.
+
+## Common Pitfalls
+- **`App::run()` blocks** (and returns `AppExit`) — use `app.update()` in tests.
+- `SystemState::get` / `get_mut` / `run_system_once` return `Result` — unwrap or `?` (0.17/0.19 validation changes).
+- Tests that spawn render/UI/audio entities need `DefaultPlugins` (or the matching feature); pure-logic tests use `MinimalPlugins`.
+- `World::run_system_once` applies deferred commands — no manual flush step needed (0.18 removed `Entities::flush`).
+
+## Sources
+- https://docs.rs/bevy/0.19.0/bevy/app/struct.App.html
+- https://docs.rs/bevy/0.19.0/bevy/ecs/world/struct.World.html
+- https://docs.rs/bevy/0.19.0/bevy/ecs/system/struct.SystemState.html
+- https://bevy.org/learn/migration-guides/0-16-to-0-17/#system-run-returns-result
+- https://bevy.org/learn/migration-guides/0-16-to-0-17/#deprecate-iter-entities-and-iter-entities-mut
+- https://bevy.org/learn/migration-guides/0-18-to-0-19/#systemparam-validation-is-now-done-when-fetching-the-data
diff --git a/docs/engine-reference/bevy/modules/ui.md b/docs/engine-reference/bevy/modules/ui.md
new file mode 100644
index 0000000..953f4f0
--- /dev/null
+++ b/docs/engine-reference/bevy/modules/ui.md
@@ -0,0 +1,95 @@
+# Bevy UI — Quick Reference
+
+**Last verified:** 2026-08-09
+
+## Core Concepts
+- **Node** — the layout component for every UI element (bevy_ui). Retained entity tree: parents are `Node`s; children spawned with `with_children` / `parent.spawn(...)`. Laid out with **Flexbox** (`display: Display::Flex`) or CSS Grid (`Display::Grid`).
+- **Flexbox fields on `Node`** — `flex_direction`, `flex_wrap`, `justify_content`, `align_items`, `row_gap`/`column_gap`, `margin`/`padding`/`border` (`UiRect`), `width`/`height`/`min_*`/`max_*` (`Val`), `flex_grow`/`flex_shrink`/`flex_basis`, `position_type`, `border_radius: BorderRadius`.
+- **Interaction** — `enum Interaction { Pressed, Hovered, None }`, added to interactive nodes (e.g. `Button`); query with `Changed<Interaction>`.
+- **Text** — `Text(pub String)` widget + required `TextFont`/`TextColor`/`TextLayout`; `TextSpan` children for rich runs.
+- **Styling components** — `BackgroundColor(Color)`, `BorderColor { top, right, bottom, left }` (`BorderColor::all(color)`), `BorderRadius` (a `Node` field since 0.18, not a component).
+- **Separate systems guidance** — flex layout runs in `PostUpdate`; keep UI-mutating systems ordered before/after layout and don't read back layout results in the same frame you mutate style.
+
+## Building a UI Tree
+```rust
+fn setup(mut commands: Commands) {
+    commands.spawn(Camera2d);
+    commands
+        .spawn(Node {
+            width: Val::Percent(100.0),
+            height: Val::Percent(100.0),
+            justify_content: JustifyContent::Center,
+            align_items: AlignItems::Center,
+            ..default()
+        })
+        .with_children(|parent| {
+            parent.spawn((
+                Button,
+                Node {
+                    width: Val::Px(150.0),
+                    height: Val::Px(65.0),
+                    border: UiRect::all(Val::Px(5.0)),
+                    justify_content: JustifyContent::Center,
+                    align_items: AlignItems::Center,
+                    border_radius: BorderRadius::MAX,
+                    ..default()
+                },
+                BorderColor::all(Color::BLACK),
+                BackgroundColor(Color::srgb(0.15, 0.15, 0.15)),
+            ));
+        });
+}
+```
+`Val` variants: `Auto`, `Px(f32)`, `Percent(f32)`, `Vw`, `Vh`, `VMin`, `VMax`. `Button` is a marker struct; required components `Node`, `FocusPolicy`, `Interaction`.
+
+## Interaction Handling
+```rust
+fn button_system(
+    mut interaction_query: Query<
+        (&Interaction, &mut BackgroundColor),
+        (Changed<Interaction>, With<Button>),
+    >,
+) {
+    for (interaction, mut color) in &mut interaction_query {
+        match *interaction {
+            Interaction::Pressed => *color = BackgroundColor(Color::srgb(0.35, 0.75, 0.35)),
+            Interaction::Hovered => *color = BackgroundColor(Color::srgb(0.25, 0.25, 0.25)),
+            Interaction::None => *color = BackgroundColor(Color::srgb(0.15, 0.15, 0.15)),
+        }
+    }
+}
+```
+
+## Text
+```rust
+world.spawn((
+    Text::new("hello world!"),
+    TextFont {
+        font: asset_server.load("fonts/FiraSans-Bold.ttf").into(),
+        font_size: FontSize::Px(60.0),
+        ..default()
+    },
+    TextColor(Color::WHITE),
+));
+```
+- `TextFont.font` is `FontSource` (build from `Handle<Font>` with `.into()`); `font_size` is `FontSize::Px(f32)` — both are 0.19 parley-migration changes.
+- `LineHeight` is a separate component; `TextLayout { justify: Justify, linebreak: LineBreak }` controls alignment/wrapping (`TextLayout::justify(Justify::Center)`).
+
+## Common Pitfalls
+- **0.19: `ui` Cargo feature is no longer implied by `2d`/`3d`** — with `default-features = false`, add `"ui"` explicitly.
+- **`BorderRadius` is a `Node` field, not a component** (0.18) — set `Node { border_radius: BorderRadius::all(...), .. }`.
+- **`TextFont.font` takes `FontSource`** (0.19) — pass `handle.into()`; `font_size: FontSize::Px(...)`, not `f32`.
+- Don't add `UiWidgetsPlugins` / `InputDispatchPlugin` manually — they are in `DefaultPlugins` since 0.19 (double-registering breaks).
+- `JustifyText` was renamed to `Justify` (0.17).
+
+## Sources
+- https://docs.rs/bevy/0.19.0/bevy/ui/index.html
+- https://docs.rs/bevy/0.19.0/bevy/ui/struct.Node.html
+- https://docs.rs/bevy/0.19.0/bevy/ui/enum.Val.html
+- https://docs.rs/bevy/0.19.0/bevy/ui/enum.Interaction.html
+- https://docs.rs/bevy/0.19.0/bevy/ui/widget/struct.Button.html
+- https://docs.rs/bevy/0.19.0/bevy/ui/widget/struct.Text.html
+- https://docs.rs/bevy/0.19.0/bevy/text/struct.TextFont.html
+- https://docs.rs/bevy/0.19.0/bevy/text/struct.TextLayout.html
+- https://bevy.org/learn/migration-guides/0-17-to-0-18/#borderradius-has-been-added-to-node-and-is-no-longer-a-component
+- https://bevy.org/learn/migration-guides/0-18-to-0-19/#ui-feature-is-now-no-longer-implied-by-the-3d-or-2d-features
diff --git a/docs/framework/agent-roster.md b/docs/framework/agent-roster.md
index 7894bd9..9faac8b 100644
--- a/docs/framework/agent-roster.md
+++ b/docs/framework/agent-roster.md
@@ -62,6 +62,7 @@ agent (usually `producer` or the domain lead) should delegate to specialists.
 | `unreal-specialist` | Unreal Engine 5 | Sonnet | Blueprint vs C++, GAS overview, UE subsystems, Unreal optimization |
 | `unity-specialist` | Unity | Sonnet | MonoBehaviour vs DOTS, Addressables, URP/HDRP, Unity optimization |
 | `godot-specialist` | Godot 4 | Sonnet | GDScript patterns, node/scene architecture, signals, Godot optimization |
+| `bevy-specialist` | Bevy | Sonnet | ECS architecture, 2D/3D rendering, bevy_ui, Cargo build, Bevy optimization |
 
 ### Unreal Engine Sub-Specialists