docs: ARM64 architecture support in orchestrator README

Document architecture naming conventions, SMT behavior, cross-arch
deployment via TARGET_ARCH, and path resolution strategy.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

packages/orchestrator/README.md

@@ -217,10 +217,67 @@ Flags:
 
 ---
 
+## Architecture (ARM64) Support
+
+The orchestrator supports both `amd64` (x86_64) and `arm64` (aarch64) architectures. Architecture is detected automatically via `runtime.GOARCH` at compile time.
+
+### Architecture naming convention
+
+This project uses **Go/Docker/Debian naming** (`amd64`/`arm64`) for architecture directories in binary paths and GCS buckets:
+
+| Convention | x86_64 name | ARM64 name | Used by |
+|------------|-------------|------------|---------|
+| **Go/Docker/Debian** | `amd64` | `arm64` | This repo, Docker, `dpkg --print-architecture` |
+| Linux/GNU | `x86_64` | `aarch64` | `uname -m`, kernel Makefiles |
+
+Binary paths follow the `{version}/{arch}/` layout:
+
+```
+# Firecracker (GCS bucket or FIRECRACKER_VERSIONS_DIR)
+fc-versions/v1.12.1_717921c/amd64/firecracker
+fc-versions/v1.12.1_717921c/arm64/firecracker
+
+# Kernels (GCS bucket or HOST_KERNELS_DIR)
+kernels/vmlinux-6.1.102/amd64/vmlinux.bin
+kernels/vmlinux-6.1.102/arm64/vmlinux.bin
+```
+
+> **Note:** The [fc-kernels](https://github.com/e2b-dev/fc-kernels) repo currently uses `x86_64` instead of `amd64` for its directory names. This will be aligned in a follow-up change.
+
+### ARM64-specific behavior
+
+- **SMT** is disabled (ARM processors don't support simultaneous multi-threading)
+- **CPU detection** uses fallback values since `gopsutil` doesn't populate Family/Model on ARM64
+- **OCI platform** is set to the target architecture instead of hardcoded `amd64`
+- **Busybox binary** must be swapped before building: `make fetch-busybox`
+
+### Cross-architecture deployment
+
+`TARGET_ARCH` is a **runtime** environment variable that overrides the architecture used for path resolution and OCI image pulls. When unset, defaults to the host architecture (`runtime.GOARCH`).
+
+```bash
+# Run orchestrator targeting amd64 paths from an arm64 host
+TARGET_ARCH=amd64 ./bin/orchestrator
+
+# Or in .env file (read at runtime)
+echo "TARGET_ARCH=amd64" >> .env.local
+```
+
+`TARGET_ARCH` affects:
+- Firecracker and kernel binary path resolution (`{version}/{arch}/...`)
+- OCI image platform for container pulls
+
+It does **not** affect:
+- Makefile compilation — use `GOARCH` directly for cross-compilation: `GOARCH=amd64 make build-local`
+- Hardware-dependent runtime behavior (SMT detection, CPU info) which always uses the actual host architecture
+
+---
+
 ## Environment Variables
 
 Automatically set in local mode. Set before running to override:
 
+- `TARGET_ARCH` - Target architecture override (`amd64` or `arm64`; default: host architecture)
 - `HOST_ENVD_PATH` - Envd binary path (default: `../envd/bin/envd`)
 - `HOST_KERNELS_DIR` - Kernel versions dir (local: `{storage}/kernels`, prod: `/fc-kernels`)
 - `FIRECRACKER_VERSIONS_DIR` - Firecracker versions dir (local: `{storage}/fc-versions`, prod: `/fc-versions`)