From bc52b50cad0ce144d042199954106ede18f86aad Mon Sep 17 00:00:00 2001
From: Michael Czechowski <mail@dailysh.it>
Date: Tue, 16 Sep 2025 11:24:54 +0200
Subject: [PATCH] docs: update documentation for new build directory structure

- Add build locations section to AGENTS.md
- Update README.md with build directory information
- Fix AGENTS.md vm-run command reference
- Document that clean removes both ./build/ and ./result/
- Ensure consistency across all documentation files

Addresses documentation inconsistencies after Makefile changes.
---
 AGENTS.md | 8 +++++++-
 Makefile  | 8 +++++---
 README.md | 9 +++++++--
 3 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ab9721e..3b56667 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -44,7 +44,7 @@ This file provides guidelines for AI coding agents operating within this reposit
 
 1. Use `make vm-run` for local development
 2. Test with all 15 containers to match production
-3. Use `make usb-build` for workshop USB drives
+3. Use `make usb-build` for workshop USB drives (outputs to ./build/iso/)
 4. Deploy to cloud with `make deploy-cloud`
 
 ## General Guidelines
@@ -56,6 +56,12 @@ This file provides guidelines for AI coding agents operating within this reposit
 - Maintain feature parity between USB/VM environments where possible
 - **ALWAYS check package existence on search.nixos.org before adding new packages**
 
+## Build Locations
+
+- **USB ISOs**: `./build/iso/result/iso/*.iso` (custom build directory)
+- **VM builds**: `./result/` (Nix default symlink)
+- **Clean command**: Removes both `./build/` and `./result/` directories
+
 ## ⚠️ Critical Warnings
 
 - **NEVER RUN `nix-env`** - This can break your Nix environment. Use `nix-shell`, `nix develop`, or declarative approaches instead.
diff --git a/Makefile b/Makefile
index edbf8c2..32f0360 100644
--- a/Makefile
+++ b/Makefile
@@ -5,7 +5,8 @@ export
 
 DOMAIN := $(or $(WORKSHOP_DOMAIN),codecrispi.es)
 USB_DEVICE := $(or $(USB_DEVICE),/dev/sdX)
-ISO_FILE := $(shell ls result/iso/*.iso 2>/dev/null | head -1)
+BUILD_DIR := ./build
+ISO_FILE := $(shell ls $(BUILD_DIR)/iso/result/iso/*.iso 2>/dev/null | head -1)
 
 help:
 	@echo "CODE CRISPIES Workshop Infrastructure"
@@ -43,7 +44,8 @@ usb-build:
 		echo "Generate with: ssh-keygen -t ed25519"; \
 		exit 1; \
 	fi
-	nix build .#live-iso --show-trace
+	@mkdir -p $(BUILD_DIR)
+	nix build .#live-iso --out-link $(BUILD_DIR)/iso --show-trace
 	@echo "✅ ISO built: $(ISO_FILE)"
 	@echo "📦 Size: $$(du -h $(ISO_FILE) | cut -f1)"
 
@@ -108,7 +110,7 @@ destroy-cloud:
 	cd terraform && terraform destroy -auto-approve
 
 clean:
-	rm -rf result .direnv terraform/.terraform terraform/terraform.tfstate* workshop-vm.*
+	rm -rf result $(BUILD_DIR) .direnv terraform/.terraform terraform/terraform.tfstate* workshop-vm.*
 	@echo "🧹 Cleaned up build artifacts"
 
 opencode:
diff --git a/README.md b/README.md
index 5dffaf1..5e61dbd 100644
--- a/README.md
+++ b/README.md
@@ -74,11 +74,16 @@ make status-cloud  # Check health
 
 ```bash
 make vm             # Start VM (simulates USB environment)
-make usb-build      # Verify build (builds ISO)
+make usb-build      # Build ISO to ./build/iso/
+make usb-test       # Test ISO in QEMU
 ```
 
 The VM simulates the USB experience with identical configuration and commands.
 
+**Build Locations:**
+- **USB ISOs**: `./build/iso/result/iso/*.iso`
+- **VM builds**: `./result/` (Nix default)
+
 ## 📚 Complete Recipe Catalog
 
 Based on Co-op Cloud with quality scoring:
@@ -164,7 +169,7 @@ make opencode       # Start opencode in dev shell
 ## 🧹 Cleanup
 
 ```bash
-make clean         # Local artifacts
+make clean         # Clean build artifacts (./build/ and ./result/)
 make destroy-cloud # Cloud infrastructure
 ```