init repo

docs/ai/bevy-debug-playbook.md

@@ -0,0 +1,62 @@
+# Bevy Debug Playbook
+
+## When build fails
+
+Run:
+
+```bash
+cargo check
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+Quote exact compiler error. Fix smallest cause first.
+
+## When game opens but nothing visible
+
+Check:
+
+1. camera spawned?
+2. entity has render component?
+3. transform in view?
+4. asset path correct?
+5. window created?
+6. alpha / color not invisible?
+7. system registered in right schedule/state?
+
+## When movement broken
+
+Check:
+
+- input system runs?
+- query matches entity?
+- transform or velocity changed?
+- another system overwrites transform?
+- delta time used correctly?
+
+## When UI broken
+
+Check:
+
+- UI entity spawned?
+- text component updated?
+- wrong state schedule?
+- score resource/event exists?
+- UI and gameplay mixed too tightly?
+
+## When architecture feels messy
+
+Refactor by:
+- extracting plugin
+- moving singleton data into resource
+- replacing direct calls with events
+- introducing state for flow
+- shrinking system queries
+
+## Review output format for AI
+
+When AI reviews code, demand:
+
+1. top 3 bugs
+2. top 3 architecture risks
+3. concrete patch plan
+4. exact commands to verify

docs/ai/bevy-project-patterns.md

@@ -0,0 +1,94 @@
+# Bevy Project Patterns
+
+## Start small
+
+For workshop speed, stay in one crate.
+When code grows, split by feature modules, not by technical layer only.
+
+Good early structure:
+
+```text
+src/
+├── main.rs
+├── player.rs
+├── ui.rs
+├── state.rs
+└── game.rs
+```
+
+Later:
+
+```text
+src/
+├── main.rs
+├── game/
+│   ├── mod.rs
+│   ├── plugin.rs
+│   ├── events.rs
+│   └── state.rs
+├── player/
+│   ├── mod.rs
+│   ├── components.rs
+│   ├── systems.rs
+│   └── plugin.rs
+└── ui/
+    ├── mod.rs
+    ├── components.rs
+    ├── systems.rs
+    └── plugin.rs
+```
+
+## Thin main
+
+`main.rs` should mostly:
+
+- create `App`
+- add plugins
+- init resources
+- add states
+- run
+
+Business logic lives in feature plugins.
+
+## Plugin boundaries
+
+Each plugin should own:
+
+- components
+- resources
+- events
+- systems
+- setup hooks
+
+## Event flow example
+
+Input system -> movement system -> collision system -> score event -> UI system
+
+Good because:
+- no direct UI coupling in gameplay code
+- each step easy to test and inspect
+
+## State flow example
+
+`Loading -> Menu -> Playing -> GameOver`
+
+Each state should have:
+- enter setup
+- update systems
+- exit cleanup if needed
+
+## Asset handling
+
+- keep asset paths stable
+- store handles in resources or components
+- preload if startup hitches matter
+- keep workshop assets tiny and few
+
+## Debug helpers
+
+Worth adding early:
+
+- `Name` components on important entities
+- debug print on critical events
+- optional debug plugin
+- one place for feature flags and tuning constants

docs/ai/bevy-quick-reference.md

@@ -0,0 +1,112 @@
+# Bevy Quick Reference
+
+## Core mental model
+
+Bevy app = plugins + schedules + systems + ECS data.
+
+- **Entity**: ID
+- **Component**: data attached to entity
+- **System**: function operating on ECS data
+- **Resource**: singleton global-ish state
+- **Event**: decoupled message
+- **State**: app/game phase control
+- **Plugin**: feature boundary
+
+## Default 2D startup
+
+Typical minimum:
+
+- add `DefaultPlugins`
+- spawn `Camera2d`
+- later: sprites, transforms, input systems
+
+## Good first feature order
+
+1. camera
+2. player entity
+3. movement
+4. bounds / collision
+5. score / HUD
+6. game state
+7. win / lose loop
+8. juice: audio, particles, animation
+
+## ECS rules
+
+Good:
+
+- data-only components
+- small systems
+- clear queries
+- events for cross-feature signaling
+
+Bad:
+
+- single mega resource for all state
+- one system doing input + movement + combat + UI
+- hidden state mutation in many places
+- coupling features through direct queries everywhere
+
+## Naming
+
+Prefer:
+
+- `Player`
+- `Velocity`
+- `Health`
+- `Score`
+- `GameState`
+- `spawn_player`
+- `move_player`
+- `update_score_ui`
+
+Avoid vague names:
+
+- `Data`
+- `Info`
+- `do_stuff`
+- `manager`
+
+## Common patterns
+
+### Resource pattern
+Use for global config, score, timers, handles, current run state.
+
+### Event pattern
+Use when one system announces and another reacts:
+- enemy died
+- score changed
+- level completed
+- damage taken
+
+### State pattern
+Use for flow:
+- `Loading`
+- `Menu`
+- `Playing`
+- `Paused`
+- `GameOver`
+
+### Plugin pattern
+Use for feature isolation:
+- player
+- UI
+- combat
+- level
+
+## Performance-first habits
+
+- query only data needed
+- avoid expensive string churn each frame
+- keep UI rebuilds scoped
+- avoid asset reloading loops
+- prefer change detection / explicit triggers when useful
+
+## Workshop-safe scope
+
+Keep small:
+- one-screen loop
+- one mechanic
+- one UI counter
+- one win/lose condition
+- one polish pass

docs/ai/bevy-source-index.md

@@ -0,0 +1,34 @@
+# Bevy Source Index
+
+Use these official sources first.
+
+## Start here
+
+- Quick start setup
+- Learn page
+- API docs
+- Official examples
+- Migration guides
+- Plugin development page
+
+## Official URLs
+
+- https://bevy.org/learn/quick-start/getting-started/setup/
+- https://bevy.org/learn/
+- https://docs.rs/bevy
+- https://github.com/bevyengine/bevy/tree/latest/examples
+- https://bevy.org/news/bevy-0-18/
+- https://bevy.org/learn/quick-start/plugin-development/
+
+## Search order for AI
+
+1. local project files
+2. `docs/ai/*.md`
+3. official examples
+4. API docs
+5. migration / release notes
+
+## Rule
+
+Do not suggest deprecated Bevy APIs from old blog posts or random tutorials.
+Match examples to `0.18.1`.

docs/ai/workshop-scope.md

@@ -0,0 +1,56 @@
+# Workshop Scope Map
+
+## Agenda to feature translation
+
+### Day 1
+Focus:
+- Bevy basics
+- ECS basics
+- setup
+- first app
+
+Project target:
+- app boots
+- 2D camera
+- one visible entity
+- one moving entity
+
+### Day 2
+Focus:
+- player movement
+- collision
+- mechanics
+- UI
+- scoring
+- polish
+
+Project target:
+- main loop playable in one room / one screen
+- score counter
+- game rule
+- fail or win condition
+
+### Day 3
+Focus:
+- animation
+- sound
+- extended systems
+- free project work
+
+Project target:
+- one polish mechanic
+- one feedback channel: sound, animation, particles, screen effect
+- project cleanup
+- final showcase build
+
+## Scope kill list
+
+Cut first if time low:
+
+- procedural generation
+- networking
+- save system
+- complex AI
+- plugin rabbit holes
+- large asset pipelines
+- ECS over-abstraction