From 99430cf1135bd1b1893ffb4e212c84b40edbed95 Mon Sep 17 00:00:00 2001
From: Pat Nakajima <patnakajima@gmail.com>
Date: Sun, 24 May 2026 20:21:10 +0000
Subject: [PATCH] add a readme

---
 README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..671ed81
--- /dev/null
+++ b/README.md
@@ -0,0 +1,65 @@
+# toes-image-builder
+
+Builds a Raspberry Pi Ubuntu Server image for Toes hardware.
+
+## What it does
+
+`build.sh` starts from the Ubuntu 24.04.4 preinstalled ARM64 Raspberry Pi image, mounts it locally, chroots into it, and installs/configures:
+
+- Toes app and systemd service
+- Matter service
+- audio overlay, ALSA config, and audio init service
+- Wi-Fi via `wpa_supplicant` and `systemd-networkd`
+- Bluetooth/Avahi support
+- SSH password login
+- USB serial gadget login
+
+## Requirements
+
+Run on an Ubuntu/Debian host with `sudo` access. On non-ARM64 hosts, the build expects `qemu-aarch64` binfmt support.
+
+Bootstrap the host once:
+
+```sh
+scripts/bootstrap-repo.sh
+```
+
+## Build
+
+```sh
+./build.sh
+```
+
+The script downloads the base image into `cache/`, writes build artifacts into `build/`, mounts the image under `mnt/`, and cleans up mounts on exit.
+
+Final image path:
+
+```text
+build/toes-ubuntu-base.img
+```
+
+## Default image access
+
+- Hostname: `toes`
+- User: `toes`
+- Password: set by `scripts/build-in-chroot.sh`
+- SSH password auth: enabled
+- USB serial gadget: enabled on `ttyGS0`
+
+## Layout
+
+- `build.sh` - top-level build pipeline
+- `scripts/` - host-side build phases
+- `audio/` - audio overlay, ALSA config, and init service
+- `matter/` - Matter systemd service
+- `cache/` - downloaded Ubuntu image and checksums
+- `build/` - generated image files
+- `mnt/` - temporary mount points
+
+## Cleanup
+
+If a build is interrupted and mounts are left behind, run:
+
+```sh
+scripts/cleanup.sh
+```