diff --git a/README.md b/README.md
index 4b6913e..cbacbd0 100644
--- a/README.md
+++ b/README.md
@@ -34,15 +34,18 @@ docker run --rm -v "$PWD:/app" casjaysdev/go:latest
 
 ### Production mode
 
-Set `GO_PROD=1` to strip binaries for release: `-trimpath` removes all local
+Set `MODE=prod` to strip binaries for release: `-trimpath` removes all local
 file system paths; `-ldflags=-s -w` strips the symbol table and DWARF debug
 info. Applied to `go build` only — `go test` is unaffected so stack traces
 stay readable.
 
 ```shell
-docker run --rm -v "$PWD:/app" -e GO_PROD=1 casjaysdev/go:latest
+docker run --rm -v "$PWD:/app" -e MODE=prod casjaysdev/go:latest
 ```
 
+`MODE=production` is also accepted. `GO_PROD=1` is a legacy alias that still
+works when `MODE` is not set.
+
 ### One-shot commands
 
 Pass any command and it runs directly instead of the default workflow:
@@ -192,12 +195,16 @@ volumes:
 | `GOPATH` | `/usr/local/share/go` | Workspace; declared as `VOLUME` |
 | `GOBIN` | `/usr/local/bin` | Destination for `go install` binaries |
 | `GOCACHE` | `/usr/local/share/go/cache` | Build cache (persisted in volume) |
+| `GOWORKDIR` | *(cwd / `/app`)* | Override the working directory used by `go-workflow` |
+| `GOOS` | *(host OS)* | Target OS for cross-compilation — e.g. `linux`, `darwin`, `windows` |
+| `GOARCH` | *(host arch)* | Target architecture — e.g. `amd64`, `arm64` |
 | `CGO_ENABLED` | `0` | Static builds by default — override per build |
 | `GOTOOLCHAIN` | `auto` | Auto-fetch the Go version declared in `go.mod` |
 | `GOFLAGS` | `-buildvcs=false` | Suppress VCS stamp errors on mounted projects |
 | `GOPROXY` | `https://proxy.golang.org,direct` | Module proxy — override for private registries |
 | `GOTELEMETRY` | `off` | Disable Go 1.23+ telemetry |
-| `GO_PROD` | *(unset)* | Set to `1` to enable `-trimpath -ldflags=-s -w` on `go build` |
+| `MODE` | `development` | Build mode: `prod`/`production` or `dev`/`devel`/`development` |
+| `GO_PROD` | *(unset)* | Legacy alias for `MODE=prod` — set to `1`; superseded by `MODE` |
 | `TZ` | `America/New_York` | Override at run time with `-e TZ=...` |
 
 Opt into CGO per build without changing the image:
diff --git a/rootfs/usr/local/bin/go-workflow b/rootfs/usr/local/bin/go-workflow
index 50401c9..5d547a5 100755
--- a/rootfs/usr/local/bin/go-workflow
+++ b/rootfs/usr/local/bin/go-workflow
@@ -29,16 +29,28 @@ run_step() {
   echo ""
 }
 
-# Production mode: GO_PROD=1 strips binaries and removes local source paths.
-# Enabled via: docker run --env GO_PROD=1 ...
-# -trimpath  removes all local file system paths from the compiled binary
-# -ldflags=-s strips the symbol table; -w strips DWARF debug info
-# Both reduce binary size and avoid leaking build-host paths into the output.
-# Applied to go build only — not go test — so stack traces stay readable.
+# Resolve build mode from MODE or the legacy GO_PROD=1 flag.
+# MODE=prod|production  → strip binary (-trimpath -ldflags=-s -w); applied to go build only
+# MODE=dev|devel|development → default; full debug info, readable stack traces
+# GO_PROD=1 is kept for backwards compatibility and takes effect when MODE is unset.
+_IS_PROD=0
+case "${MODE:-}" in
+  prod | production)           _IS_PROD=1 ;;
+  dev | devel | development)   _IS_PROD=0 ;;
+  "")
+    [ "${GO_PROD:-0}" = "1" ] && _IS_PROD=1
+    ;;
+  *)
+    echo "Warning: unknown MODE '${MODE}' — expected prod|production|dev|devel|development; defaulting to development" >&2
+    ;;
+esac
+
 BUILD_FLAGS=()
-if [ "${GO_PROD:-0}" = "1" ]; then
-  echo "  (production mode: -trimpath -ldflags=-s -w)"
+if [ "$_IS_PROD" = "1" ]; then
+  echo "  (mode: production — -trimpath -ldflags=-s -w)"
   BUILD_FLAGS=(-trimpath -ldflags="-s -w")
+else
+  echo "  (mode: development)"
 fi
 
 # 1. Sync module graph and go.sum before anything reads them