diff --git a/.woodpecker/publish.yml b/.woodpecker/publish.yml
index 187e600..8eb4685 100644
--- a/.woodpecker/publish.yml
+++ b/.woodpecker/publish.yml
@@ -4,6 +4,23 @@
 variables:
   - &node_image 'node:22-alpine'
   - &enable_pnpm 'corepack enable'
+  # Heavy kaniko image builds (~25 min) — gate them so a merge that only touches
+  # the npm-only CLI (@mosaicstack/mosaic) or docs does NOT rebuild the platform
+  # images (gateway/appservice/web do not depend on @mosaicstack/mosaic). Releases
+  # (tags) always build everything. Exclude-list keeps the default SAFE: any
+  # non-excluded change still builds, so no transitive dep can silently go stale.
+  # (Woodpecker: `when` entries are OR'd; `path` applies to push/PR only — hence
+  # the separate `event: tag` entry.)
+  - &image_build_when
+    - event: tag
+    - event: [push, manual]
+      branch: main
+      path:
+        exclude:
+          - 'packages/mosaic/**'
+          - 'docs/**'
+          - '**/*.md'
+          - '.woodpecker/**'
 
 when:
   - branch: [main]
@@ -26,6 +43,15 @@ steps:
 
   publish-npm:
     image: *node_image
+    # Publish only when a publishable package changed (or on a release tag); a
+    # pure-docs merge runs no publish. Cheap step, but gated for cleanliness.
+    when:
+      - event: tag
+      - event: [push, manual]
+        branch: main
+        path:
+          include:
+            - 'packages/**'
     environment:
       NPM_TOKEN:
         from_secret: gitea_token
@@ -91,6 +117,7 @@ steps:
 
   build-gateway:
     image: gcr.io/kaniko-project/executor:debug
+    when: *image_build_when
     environment:
       REGISTRY_USER:
         from_secret: gitea_username
@@ -116,6 +143,7 @@ steps:
 
   build-appservice:
     image: gcr.io/kaniko-project/executor:debug
+    when: *image_build_when
     environment:
       REGISTRY_USER:
         from_secret: gitea_username
@@ -141,6 +169,7 @@ steps:
 
   build-web:
     image: gcr.io/kaniko-project/executor:debug
+    when: *image_build_when
     environment:
       REGISTRY_USER:
         from_secret: gitea_username