diff --git a/AGENTS.md b/AGENTS.md
index e58b31bdf..0b4d626b5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -23,6 +23,10 @@ macOS note: if `cargo nextest run` fails with `Too many open files (os error 24)
 - `cd apps/fabro-web && bun run typecheck` — type check
 - `cd apps/fabro-web && bun run build` — production build
 
+### Docker image
+- `bin/dev/docker-build.sh` — builds the local Docker image from the current tree using the release pipeline's cargo-zigbuild approach. Honors `--arch amd64|arm64`, `--tag <name>` (default `fabro`), and `--compile-only` (stages `docker-context/<arch>/fabro` without `docker build`). Prefer this over writing a throwaway Dockerfile; the release pipeline, `Dockerfile`, and this script share the same binary layout.
+- Refresh the embedded SPA before rebuilding the image after any `apps/fabro-web` change: `scripts/refresh-fabro-spa.sh` runs the bun build and copies `dist/` into `lib/crates/fabro-spa/assets/`. Skipping this step produces a Docker image whose Rust binary embeds a stale SPA bundle.
+
 ### Marketing site (apps/marketing)
 - `cd apps/marketing && bun run dev` — start Astro dev server
 - `cd apps/marketing && bun run build` — production build
diff --git a/bin/dev/docker-build.sh b/bin/dev/docker-build.sh
index a714c154f..fee091486 100755
--- a/bin/dev/docker-build.sh
+++ b/bin/dev/docker-build.sh
@@ -9,6 +9,7 @@
 # Usage:
 #   bin/dev/docker-build.sh                    # host arch, build image at end
 #   bin/dev/docker-build.sh --arch amd64       # force amd64 (uses QEMU on non-amd64 hosts — slow)
+#   bin/dev/docker-build.sh --tag fabro:smoke  # tag image as fabro:smoke (default: fabro)
 #   bin/dev/docker-build.sh --arch arm64 --compile-only
 #                                              # stage binary only; skip `docker build`
 #                                              # (useful for multi-arch buildx verification)
@@ -19,12 +20,17 @@ cd "$(dirname "$0")/../.."
 
 arch=""
 compile_only=0
+tag="fabro"
 while [ $# -gt 0 ]; do
   case "$1" in
     --arch)
       arch="$2"
       shift 2
       ;;
+    --tag)
+      tag="$2"
+      shift 2
+      ;;
     --compile-only)
       compile_only=1
       shift
@@ -90,5 +96,5 @@ if [ "$compile_only" -eq 1 ]; then
   exit 0
 fi
 
-echo "Building Docker image..."
-docker build --platform "linux/$arch" -t fabro .
+echo "Building Docker image as $tag..."
+docker build --platform "linux/$arch" -t "$tag" .