From 58464ac28c894bea33a5c7de188c9376de8d4295 Mon Sep 17 00:00:00 2001
From: Thales Maciel <thales@thalesmaciel.com>
Date: Mon, 20 Apr 2026 13:03:50 -0300
Subject: [PATCH] docs + doctor: be honest about amd64-only support
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The README sold the product as "Linux with /dev/kvm"; the deeper docs
admit that the Makefile pins companion builds to GOARCH=amd64, the
kernel catalog ships only x86_64 entries, and OCI import pulls
linux/amd64 layers. arm64 users who show up through the README only
discover that after install fails in non-obvious ways.

Two surface-level fixes:

- README requirements list leads with "x86_64 / amd64 Linux — arm64 is
  not supported today", with a short note on the three places that
  assumption lives so users understand it's not a last-mile gap.
- `banger doctor` now runs an architecture check that passes on amd64
  and FAILS (not warns) on anything else, referencing the three
  downstream assumptions. Hard-fail rather than warn so a user on an
  arm64 machine doesn't waste time chasing unrelated preflight items.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                 |  6 +++++-
 internal/daemon/doctor.go | 20 ++++++++++++++++++++
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7cc850b..6a77cf2 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,11 @@ download); subsequent `vm run`s are seconds.
 
 ## Requirements
 
-- Linux with `/dev/kvm`
+- **x86_64 / amd64 Linux** — arm64 is not supported today. The companion
+  binaries, the published kernel catalog, and the OCI import path all
+  assume `linux/amd64`. `banger doctor` surfaces this as a failing
+  check on other architectures.
+- `/dev/kvm`
 - `sudo`
 - Firecracker on `PATH`, or `firecracker_bin` set in config
 - host tools checked by `banger doctor`
diff --git a/internal/daemon/doctor.go b/internal/daemon/doctor.go
index 055c1e0..9e0b0fd 100644
--- a/internal/daemon/doctor.go
+++ b/internal/daemon/doctor.go
@@ -3,6 +3,7 @@ package daemon
 import (
 	"context"
 	"fmt"
+	"runtime"
 	"strings"
 
 	"banger/internal/config"
@@ -38,6 +39,8 @@ func Doctor(ctx context.Context) (system.Report, error) {
 func (d *Daemon) doctorReport(ctx context.Context, storeErr error) system.Report {
 	report := system.Report{}
 
+	addArchitectureCheck(&report)
+
 	if storeErr != nil {
 		report.AddFail(
 			"state store",
@@ -57,6 +60,23 @@ func (d *Daemon) doctorReport(ctx context.Context, storeErr error) system.Report
 	return report
 }
 
+// addArchitectureCheck surfaces a hard-fail when banger is running on
+// a non-amd64 host. Companion binaries are pinned to amd64 in the
+// Makefile, the published kernel catalog ships only x86_64 images, and
+// OCI import pulls linux/amd64 layers. Letting users discover this
+// through cryptic downstream failures is worse than saying it up front.
+func addArchitectureCheck(report *system.Report) {
+	if runtime.GOARCH == "amd64" {
+		report.AddPass("host architecture", "amd64")
+		return
+	}
+	report.AddFail(
+		"host architecture",
+		fmt.Sprintf("running on %s; banger today only supports amd64/x86_64 hosts", runtime.GOARCH),
+		"companion build, kernel catalog, and OCI import all assume linux/amd64",
+	)
+}
+
 // addVMDefaultsCheck surfaces the effective VM sizing that `vm run` /
 // `vm create` will apply when the user omits the flags. Shown as a
 // PASS check so it always renders, with per-field provenance