# Repository Guidelines

## Project Structure

- `cmd/banger` and `cmd/bangerd` are the main user entrypoints.
- `internal/` contains the daemon, CLI, RPC, storage, Firecracker integration, guest helpers, and web UI.
- `scripts/` contains explicit manual helper workflows for rootfs and kernel preparation.
- `build/bin/` is the canonical source-checkout build output.
- `build/manual/` is the canonical source-checkout location for manual rootfs/kernel artifacts.

## Build and Test

- `make build` builds `./build/bin/banger`, `./build/bin/bangerd`, and `./build/bin/banger-vsock-agent`.
- `make test` runs `go test ./...`.
- `./build/bin/banger doctor` checks host readiness.
- `./build/bin/banger image build --from-image <image>` builds a managed image from an existing registered image.
- `./build/bin/banger image register ...` registers an unmanaged host-side image stack.
- `./build/bin/banger image promote <image>` copies an unmanaged image into daemon-owned managed artifacts.
- `make void-kernel`, `make rootfs-void`, and `make void-register` drive the experimental Void flow under `./build/manual`.

## Image Model

- Managed images own the full boot set: rootfs, optional work-seed, kernel, optional initrd, and optional modules.
- There is no runtime bundle and no auto-registered default image from disk paths.
- `default_image_name` selects a registered image only.

## Config

- Config lives at `~/.config/banger/config.toml`.
- Firecracker comes from `PATH` by default, or `firecracker_bin`.
- SSH uses `ssh_key_path` or an auto-managed default key at `~/.config/banger/ssh/id_ed25519`.

## Coding Style

- Prefer small, direct Go code and standard library solutions.
- Keep shell scripts strict with `set -euo pipefail`.
- Use `gofmt` for Go formatting.
- When a CLI accepts either an inline string or a file input, always prefer the file-based form.
- For shell commands and AI/LLM tooling, prefer passing files as input whenever the CLI allows it.
- Create temporary files as needed to follow the file-first rule.
- Examples: use `git commit -F <file>` instead of `git commit -m <message>`, and use prompt files instead of inline prompt strings when invoking LLM CLIs.

## Testing Guidance

- Primary automated coverage is `go test ./...`.
- For lifecycle changes, smoke-test with `vm create`, `vm ssh`, `vm stop`, and `vm delete`.
- If guest provisioning changes, document whether existing images must be rebuilt or recreated.

## Security

- Do not commit secrets.
- VM workflows require `sudo` and `/dev/kvm`.
- The default SSH key is local configuration, not a checked-in runtime artifact.