From 8ba920eda66590d7fea99808c0f957b6845d2296 Mon Sep 17 00:00:00 2001
From: Thales Maciel <thales@thalesmaciel.com>
Date: Wed, 18 Mar 2026 14:23:22 -0300
Subject: [PATCH] Refresh docs for current VM workflows

Keep the user-facing docs aligned with the current Go control plane instead of the older one-VM-at-a-time and ambiguous rootfs rebuild flows.

Document concurrent multi-VM lifecycle and set commands, clarify that rebuilt images now include mise plus opencode, and spell out when make rootfs needs an explicit base image. Also update the repo guidelines so future changes keep those behaviors documented.
---
 AGENTS.md |  2 ++
 README.md | 22 +++++++++++++++++++++-
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index a7f041f..59ea7a7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,6 +14,7 @@
 - `./banger vm create --name testbox` creates and starts a VM.
 - `./banger vm ssh testbox` connects to a running guest.
 - `./banger vm stop testbox` stops a VM while preserving its disks.
+- `./banger vm stop vm-a vm-b vm-c` and `./banger vm set --nat web-1 web-2` are supported; multi-VM lifecycle and `set` actions fan out concurrently through the CLI.
 - `./banger tui` launches the terminal UI.
 - `make test` runs `go test ./...`.
 - `./verify.sh` runs the smoke test for the Go VM workflow.
@@ -27,6 +28,7 @@
 ## Testing Guidelines
 - Primary automated coverage is `go test ./...`.
 - Manual verification for VM lifecycle changes: `./banger vm create`, confirm SSH access, then stop/delete the VM.
+- Rebuilt images now include `mise` plus `opencode` by default; if you change guest provisioning, document whether users need to rebuild `./runtime/rootfs-docker.ext4` or another base image to pick it up.
 - If you add a new operational workflow, document how to exercise it in `README.md`.
 - For NAT changes, verify both guest outbound access and host rule cleanup, for example with `./verify.sh --nat`.
 
diff --git a/README.md b/README.md
index c5906f6..8cd1aa6 100644
--- a/README.md
+++ b/README.md
@@ -111,6 +111,14 @@ Update stopped VM settings:
 banger vm set calm-otter --memory 2048 --vcpu 4 --disk-size 32G
 ```
 
+Lifecycle and `set` actions also accept multiple VM refs and run them
+concurrently:
+```bash
+banger vm stop calm-otter buildbox api-1
+banger vm kill --signal KILL aa12bb34 cc56dd78
+banger vm set --nat web-1 web-2 web-3
+```
+
 Launch the TUI:
 ```bash
 banger tui
@@ -146,7 +154,7 @@ Useful config keys:
 - `firecracker_bin`
 - `ssh_key_path`
 - `namegen_path`
-- `customize_script`
+- `customize_script` (manual helper compatibility; `banger image build` is Go-native)
 - `default_rootfs`
 - `default_base_rootfs`
 - `default_kernel`
@@ -174,6 +182,10 @@ Build a managed image:
 banger image build --name docker-dev --docker
 ```
 
+Rebuilt images install a pinned `mise` at `/usr/local/bin/mise`, activate it
+for bash login and interactive shells, and install `opencode` through `mise`
+by default.
+
 Show or delete images:
 ```bash
 banger image show docker-dev
@@ -215,6 +227,12 @@ To rebuild the source-checkout default image in `./runtime/rootfs-docker.ext4`:
 make rootfs
 ```
 
+If your runtime bundle does not include `./runtime/rootfs.ext4`, pass an
+explicit base image instead:
+```bash
+./make-rootfs.sh --base-rootfs /path/to/base-rootfs.ext4
+```
+
 If the package manifest changed and you want a fresh source-checkout image:
 ```bash
 rm -f ./runtime/rootfs-docker.ext4 ./runtime/rootfs-docker.ext4.packages.sha256
@@ -223,6 +241,8 @@ make rootfs
 
 `make rootfs` expects a bootstrapped runtime bundle. If `./runtime/rootfs.ext4`
 is not available, pass an explicit `--base-rootfs` to `./make-rootfs.sh`.
+Existing VMs keep using their current image and disks; rebuilds only affect VMs
+created from the rebuilt image afterward.
 
 ## Maintaining The Runtime Bundle
 The checked-in [`runtime-bundle.toml`](/home/thales/projects/personal/banger/runtime-bundle.toml)