# Repository Guidelines

Always run `make build` before commit.

## Project Structure

- `cmd/banger` and `cmd/bangerd` are the main user entrypoints.
- `internal/` contains the daemon, CLI, RPC, storage, Firecracker integration, guest helpers, and the experimental web UI.
- `internal/daemon/` is the composition root; pure helpers live in its subpackages (`opstate`, `dmsnap`, `fcproc`, `imagemgr`, `session`, `workspace`). See `internal/daemon/ARCHITECTURE.md`.
- `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 ./...`.
- `make lint` runs `gofmt -l`, `go vet ./...`, and `shellcheck --severity=error` on `scripts/*.sh`. Run before commits.
- `./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`.
- `scripts/publish-kernel.sh <name>` packages a locally-imported kernel and uploads it to the catalog; see `docs/kernel-catalog.md`.
- `banger image pull <oci-ref> --kernel-ref <name>` pulls a rootfs from any OCI registry; see `docs/oci-import.md` (experimental — file-ownership caveat).

## 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.