# Bevy Nix Template - Detailed Dev Guide

This is the canonical deep guide for newcomers and AI agents working in this repo.

## Project Snapshot

- Purpose: minimal Bevy template for fast workshop iteration with optional local AI workflows.
- Stack:
  - Rust `1.95.0` target (via `flake.nix` dev shell)
  - Bevy `0.18.1`
  - 2D-first project scope
- Current app behavior (`src/main.rs`):
  - starts Bevy app with a titled 1280x720 window
  - spawns a single `Camera2d`

## Canonical File Map

Authoritative files:

- `AGENTS.md`: coding and architecture rules for this template.
- `Cargo.toml`: Rust package and Bevy dependency configuration.
- `flake.nix`: reproducible Nix development environment.
- `justfile`: daily dev commands.
- `.opencode/opencode.json`: OpenCode command templates and permissions.
- `ai/scripts/*.sh`: local context and llama automation scripts.
- `docs/ai/*.md`: Bevy design and debugging references.
- `src/main.rs`: current game entrypoint.

Generated files:

- `ai/context/project-context.md`: generated by `just context` or `./ai/scripts/build-context.sh`.
  - Do not hand-edit this file.
  - Regenerate when source/docs change and before context-heavy AI prompts.

## Setup Paths

Recommended path (reproducible):

```bash
nix develop
cargo run
```

Optional host-native path:

```bash
# install rust + tooling yourself, then run
cargo run
```

Run prerequisites checker:

```bash
bash ./scripts/check-requirements.sh --mode native
bash ./scripts/check-requirements.sh --mode nix-host
nix develop -c bash ./scripts/check-requirements.sh --mode nix-shell
```

On macOS, install Xcode Command Line Tools if missing:

```bash
xcode-select --install
```

## Fast Iteration Workflows

Native commands:

```bash
cargo run
cargo watch -x run
cargo fmt --all
cargo check
cargo clippy --workspace --all-targets --all-features -- -D warnings
```

Nix-wrapped equivalents:

```bash
nix develop -c cargo run
nix develop -c cargo watch -x run
nix develop -c cargo fmt --all
nix develop -c cargo check
nix develop -c cargo clippy --workspace --all-targets --all-features -- -D warnings
```

Just shortcuts:

```bash
just run
just watch
just check
just lint
just test
```

## VS Code Tasks

Tasks are defined in `.vscode/tasks.json` and cover:

- requirements checks (native and nix)
- build check (native and nix)
- lint pipeline (`fmt -> check -> clippy`, native and nix)
- dev run/watch (native and nix)
- release run with `--no-default-features` (native and nix)

Use:

```text
Cmd/Ctrl+Shift+P -> "Tasks: Run Task"
```

## AI Workflows

Build/update project context:

```bash
just context
# or
./ai/scripts/build-context.sh
```

Run local llama flows:

```bash
export LLAMA_MODEL=/absolute/path/to/model.gguf
just ai-chat
just ai-plan "add player movement"
just ai-fix "camera jitters on move"
just ai-review "review ECS plugin split"
```

OpenCode config:

- Canonical config: `.opencode/opencode.json`
- It expects `ai/context/project-context.md` to exist or be refreshed.

## Verification Workflow

After Rust code edits, run in this order:

```bash
cargo fmt --all
cargo check
cargo clippy --workspace --all-targets --all-features -- -D warnings
```

For runtime smoke checks:

```bash
cargo run
cargo watch -x run
```

## Troubleshooting

- `Could not resolve host: index.crates.io`:
  - network access is required for first dependency download.
- `xcode-select` errors on macOS:
  - install CLT with `xcode-select --install`.
- `llama-cli: command not found`:
  - install `llama.cpp` tooling or skip local llama commands.
- missing `ai/context/project-context.md`:
  - run `just context` before prompts that read project context.