init repo

CLAUDE.md

@@ -0,0 +1,164 @@
+# 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.