GEMINI.md for Bevy

# GEMINI.md

Project context for the Gemini CLI in this Bevy repository. Read it before editing.
Other agents can follow the same rules, but Gemini loads this filename automatically.

## Stack

This repository is a Bevy game. Data lives in components, behavior lives in systems, and schedules stay explicit. Do not reach for a God object.

## Layout

- Plugins group related systems. The app binary adds plugins. It does not contain the rules.
- Components are plain data. Systems are functions.
- Assets use the project's asset path and handles, not filesystem reads scattered through systems.

## Commands

- Run: `cargo run`
- Test: `cargo test`
- Check: `cargo clippy --all-targets -- -D warnings`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Query the smallest component set that proves the rule.
- Use commands to spawn and despawn. Do not mutate the world unsafely.
- Exclusive systems are rare. Prefer a normal system with the right system param.
- Put one-shot work in `OnEnter` or an event. Do not gate it with a boolean checked every frame.
- Do not `unwrap` on a missing asset handle.
- Run `cargo fmt` and clippy on gameplay changes.

## Testing

Add or update tests when behavior changes.

Test a pure system with a minimal App or a plain function. Do not boot the full game.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Log a missing asset and skip the spawn. A missing optional component is absence, not a panic.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not store an Entity and assume it still exists next frame without a check.
- Do not allocate a new collection inside a hot system every frame.
- Do not use thread-local hacks to smuggle state. Use a resource.
- Do not add a second ECS mindset. Bevy's world is the world.

## Done when

- The requested behavior works.
- `cargo test` passes and `cargo clippy --all-targets -- -D warnings` is clean for non-trivial changes.
- The diff stays inside the task.
- You list anything you could not run.