diff --git a/CHANGELOG.md b/CHANGELOG.md
index 727eaec..499d7db 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,23 @@ Pre-v1.0.0 tags followed the pi npm version (`v{pi_version}[letter]`).
 
 ---
 
+## Unreleased
+
+### Fixed
+
+- **`yq` is now mikefarah's Go yq, not Debian's Python `yq`.** The base image
+  previously apt-installed `yq`, which on Debian/Ubuntu is the unrelated
+  kislyuk/`yq` (a jq wrapper, v3.x) — incompatible with the mikefarah v4 syntax
+  the `cloud-init` repo's `provision.sh`/`deploy.sh` expect. Dropped the apt
+  package and install a pinned mikefarah binary instead
+  (`ARG YQ_VERSION=v4.53.3`, multi-arch amd64/arm64, follows the repo's
+  tealdeer-style `latest`-or-pin pattern; override with `--build-arg`),
+  matching the `yq` used on control machines (Homebrew `yq` v4.x). The
+  build-time `smoke-test.sh` gate now asserts `yq --version` reports
+  `mikefarah`, so a regression back to the Python package fails CI.
+
+---
+
 ## v1.2.2 — 2026-06-24
 
 Patch release: pick up **pi `0.80.2`** (npm `latest`) and **mempalace `3.5.0`**,
diff --git a/Dockerfile.base b/Dockerfile.base
index 63614c5..ba08faf 100644
--- a/Dockerfile.base
+++ b/Dockerfile.base
@@ -51,7 +51,8 @@ ENV DEBIAN_FRONTEND=noninteractive
 #                  See the bundled `dot-watch` helper for live .dot -> PNG
 #                  re-render (handy with pi-studio's image preview).
 #   imagemagick  — image conversion / resizing for thumbnails, etc. ~50 MB.
-#   yq           — YAML-aware companion to jq.
+#   (yq is NOT apt-installed: Debian's `yq` is the unrelated Python tool;
+#    mikefarah's Go yq is installed as a pinned binary further down.)
 #   socat        — TCP relay. Powers `studio-expose`, which bridges
 #                  pi-studio's container-loopback server to the container's
 #                  external interface so a published port can reach it.
@@ -66,7 +67,6 @@ RUN apt-get update && \
     openssh-client \
     gnupg \
     jq \
-    yq \
     ripgrep \
     fd-find \
     tree \
@@ -404,6 +404,24 @@ RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "x86_64" ;; arm64) echo "aarch64"
     chmod +x /usr/local/bin/tldr && \
     tldr --version
 
+# ── yq (mikefarah) — YAML processor, jq's companion for YAML ─────────
+# Installed as the mikefarah Go binary — NOT Debian's `yq` apt package, which
+# is the unrelated Python kislyuk/yq (a jq wrapper with different syntax and
+# version line, e.g. 3.x). The cloud-init repo's deploy.sh/provision.sh
+# require mikefarah yq v4; pinned here to the v4.x release used on the
+# control machines (override with --build-arg YQ_VERSION=latest|vX.Y.Z).
+ARG YQ_VERSION=v4.53.3
+RUN ARCH=$(case "${TARGETARCH}" in amd64) echo "amd64" ;; arm64) echo "arm64" ;; *) echo "amd64" ;; esac) && \
+    V="${YQ_VERSION}" && \
+    if [ "$V" = "latest" ]; then \
+      V=$(curl -sI --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/mikefarah/yq/releases/latest" | awk 'tolower($1)=="location:" { sub(/\r$/,"",$2); n=split($2,a,"/"); print a[n] }'); \
+    fi && \
+    [ -n "$V" ] && \
+    echo "Installing mikefarah yq ${V}" && \
+    curl -fsSL --retry 5 --retry-delay 5 --retry-all-errors "https://github.com/mikefarah/yq/releases/download/${V}/yq_linux_${ARCH}" -o /usr/local/bin/yq && \
+    chmod +x /usr/local/bin/yq && \
+    yq --version
+
 # ── AWS CLI v2 (for SSO/Bedrock authentication) ─────────────────────
 RUN ARCH=$(case "${TARGETARCH}" in \
       amd64) echo "x86_64" ;; \
diff --git a/scripts/smoke-test.sh b/scripts/smoke-test.sh
index cbccc53..3a96d3a 100755
--- a/scripts/smoke-test.sh
+++ b/scripts/smoke-test.sh
@@ -76,7 +76,7 @@ run "mempalace-mcp"   "mempalace-mcp --help"
 run "pandoc"          "pandoc --version"
 run "graphviz (dot)"  "dot -V"
 run "imagemagick"     "magick --version"
-run "yq"              "yq --version"
+run "yq (mikefarah v4)" "yq --version | grep -q mikefarah"
 run "tldr (tealdeer)" "tldr --version"
 run "socat"           "socat -V"
 run "studio-expose helper" "test -x /usr/local/bin/studio-expose"