# Repository Guidelines

## Project Structure & Module Organization
- `run.sh` is the primary launcher script; it builds the per-VM state and configures Firecracker over the local API socket.
- `firecracker`, `vmlinux`, and `rootfs.ext4` are runtime artifacts required to boot the guest.
- `state/` is created at runtime to store per-VM sockets, logs, and metadata (safe to delete when no VMs are running).
- `firecracker.log` is produced by Firecracker; additional per-VM logs live under `state/vm-*/`.

## Build, Test, and Development Commands
- `./run.sh` launches a VM using Firecracker, sets up a bridge/TAP device, and prints the guest IP plus SSH command.
- `ssh -i "./id_ed25519" root@<guest_ip>` connects to the guest once it boots.
- `reboot` (inside the guest) shuts down the VM.
- There is no build step in this repo; binaries and images are checked in.

## Coding Style & Naming Conventions
- Shell scripts use Bash with `set -euo pipefail`; keep new scripts strict and explicit.
- Indentation is two spaces in `run.sh`; match existing formatting and quoting style.
- Filenames are short and descriptive (e.g., `run.sh`, `rootfs.ext4`). Prefer lowercase with dashes or dots.
- No formatter or linter is configured; keep changes small and readable.

## Testing Guidelines
- No automated test framework is present.
- Manual verification: run `./run.sh`, confirm the guest boots, and verify SSH access.
- If adding tests, document how to run them in this file and keep them self-contained.

## Commit & Pull Request Guidelines
- Git history uses short, informal commit summaries (e.g., "ignore", "Document expected log noise").
- Prefer imperative, single-line subjects; keep them under ~50 characters when possible.
- PRs should describe the change, list any new runtime requirements, and include logs or screenshots if behavior changes.

## Security & Configuration Tips
- The script requires `sudo` and `/dev/kvm` access; avoid committing secrets or private keys.
- `id_ed25519` is a local SSH key for the guest; rotate or replace it if sharing the repository.