From 04c57e280a451bd3086dbebd100ad5fee011e26e Mon Sep 17 00:00:00 2001
From: wanghj <hj.wang@opencsg.com>
Date: Tue, 9 Jun 2026 16:48:08 +0800
Subject: [PATCH 1/3] build(embed): drive picoclaw image tags from agent.toml
 version

Embed templates are embedded directly without dist/ staging. Local
build-all bumps version and image.ref; GitLab CI on main builds and
pushes images only when version changes since the previous commit.
---
 .github/workflows/release.yml                 |  67 +---
 .gitignore                                    |   2 -
 .gitlab/ci-picoclaw-image.sh                  |  30 +-
 .gitlab/ci-picoclaw-manifest.sh               |  30 +-
 .gitlab/ci-picoclaw-version-check.sh          | 148 +++++++++
 .gitlab/ci.yml                                | 123 ++++---
 AGENTS.md                                     |   2 +-
 Makefile                                      | 100 +++---
 README.md                                     |   2 +-
 README.zh.md                                  |   2 +-
 docs/build.md                                 |  54 +--
 docs/build.zh.md                              |  54 +--
 internal/agent/workspace_test.go              |   8 +-
 internal/hub/template_manifest.go             |   1 +
 internal/templates/embed.go                   |   7 +-
 .../embed/picoclaw-manager/agent.toml         |   3 +-
 .../embed/picoclaw-worker/agent.toml          |   3 +-
 scripts/build-docker-embed-images.sh          |  28 +-
 scripts/bump-docker-embed-version.sh          |  30 ++
 scripts/check-docker-embed-manifests.sh       |  20 ++
 scripts/docker-embed-agent-toml-common.sh     | 313 ++++++++++++++++++
 scripts/patch-docker-embed-image-refs.sh      | 175 ----------
 scripts/patch-picoclaw-embed-image-refs.sh    |   2 -
 scripts/prepare-docker-embed-dist.sh          |  47 ---
 scripts/prepare-picoclaw-embed-dist.sh        |   2 -
 scripts/sync-docker-embed-image-refs.sh       |  30 ++
 web/app/package.json                          |   4 +-
 27 files changed, 826 insertions(+), 461 deletions(-)
 create mode 100755 .gitlab/ci-picoclaw-version-check.sh
 create mode 100755 scripts/bump-docker-embed-version.sh
 create mode 100755 scripts/check-docker-embed-manifests.sh
 create mode 100755 scripts/docker-embed-agent-toml-common.sh
 delete mode 100755 scripts/patch-docker-embed-image-refs.sh
 delete mode 100755 scripts/patch-picoclaw-embed-image-refs.sh
 delete mode 100755 scripts/prepare-docker-embed-dist.sh
 delete mode 100755 scripts/prepare-picoclaw-embed-dist.sh
 create mode 100755 scripts/sync-docker-embed-image-refs.sh

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index a73d5782..e17bb073 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -1,10 +1,8 @@
 # Release on tag v* / workflow_dispatch.
 #
-# Container images for embed templates (those with a Dockerfile) are built on GitLab CI (ACR).
-# This workflow only:
-#   1. Stages embed/<template>/dist/ for every template dir that contains a Dockerfile
-#   2. Patches dist/agent.toml [image].ref to ${ACR_REGISTRY}/opencsghq/<template>:<version>
-#   3. Builds csgclaw / csgclaw-cli release archives with the patched embed
+# Container images for embed templates are built on GitLab CI (main branch, ACR).
+# This workflow:
+#   1. Builds csgclaw / csgclaw-cli release archives with embed agent.toml from the tag commit
 #
 # <version> is the git tag (v*) or workflow_dispatch input.
 
@@ -105,48 +103,8 @@ jobs:
           path: web/static-dist/
           if-no-files-found: error
 
-  docker-embed-dist:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Resolve version
-        id: version
-        shell: bash
-        run: |
-          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-            version="${{ github.event.inputs.version }}"
-          else
-            version="${GITHUB_REF_NAME}"
-          fi
-          echo "value=${version}" >> "$GITHUB_OUTPUT"
-
-      - name: Stage docker embed dist and patch ACR image refs
-        shell: bash
-        env:
-          ACR_REGISTRY: ${{ env.ACR_REGISTRY }}
-          VERSION: ${{ steps.version.outputs.value }}
-        run: |
-          chmod +x scripts/list-docker-embed-templates.sh \
-            scripts/prepare-docker-embed-dist.sh \
-            scripts/patch-docker-embed-image-refs.sh
-          ./scripts/prepare-docker-embed-dist.sh
-          ./scripts/patch-docker-embed-image-refs.sh
-          while IFS= read -r name; do
-            echo "${name} ref:"
-            grep '^ref = ' "internal/templates/embed/${name}/dist/agent.toml"
-          done < <(./scripts/list-docker-embed-templates.sh)
-
-      - name: Upload patched docker embed directories
-        uses: actions/upload-artifact@v4
-        with:
-          name: docker-embed-dist-patched
-          path: internal/templates/embed/*/dist/
-          if-no-files-found: error
-
   build:
-    needs: [prepare, web, docker-embed-dist]
+    needs: [prepare, web]
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
@@ -167,20 +125,17 @@ jobs:
           name: web-static-dist
           path: web/static-dist
 
-      - name: Download patched docker embed directories
-        uses: actions/download-artifact@v4
-        with:
-          name: docker-embed-dist-patched
-          # Artifact root is internal/templates/embed/ (LCA of embed/*/dist paths).
-          path: internal/templates/embed
-
-      - name: Verify docker embed dist is present
+      - name: Verify embed agent manifests are present
         shell: bash
         run: |
           chmod +x scripts/list-docker-embed-templates.sh
           while IFS= read -r name; do
-            test -f "internal/templates/embed/${name}/dist/agent.toml"
-            grep '^ref = ' "internal/templates/embed/${name}/dist/agent.toml"
+            test -f "internal/templates/embed/${name}/agent.toml"
+            grep '^ref = ' "internal/templates/embed/${name}/agent.toml"
+            if grep -q '^ref = ""' "internal/templates/embed/${name}/agent.toml"; then
+              echo "missing image ref in internal/templates/embed/${name}/agent.toml" >&2
+              exit 1
+            fi
           done < <(./scripts/list-docker-embed-templates.sh)
 
       - name: Set up Go
diff --git a/.gitignore b/.gitignore
index 5ceeb568..fe1664fb 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,8 +30,6 @@ docker/
 
 # Generated embedded runtime workspaces
 /internal/agent/embed/
-# Docker embed dist/ is populated by make/CI (see make prepare-docker-embed-dist).
-# Note: go:embed ignores .gitignore, so these paths must not be listed here.
 
 # Editor / tool directories
 .cursor/
diff --git a/.gitlab/ci-picoclaw-image.sh b/.gitlab/ci-picoclaw-image.sh
index e466cc5a..00357039 100755
--- a/.gitlab/ci-picoclaw-image.sh
+++ b/.gitlab/ci-picoclaw-image.sh
@@ -11,16 +11,38 @@ dockerfile="$2"
 image_name="$3"
 
 : "${CI_PROJECT_DIR:?CI_PROJECT_DIR must be set}"
-: "${CI_COMMIT_TAG:?CI_COMMIT_TAG must be set}"
 : "${ACR_REGISTRY:?ACR_REGISTRY must be set}"
 
-archive="${CI_PROJECT_DIR}/dist/csgclaw-cli_${CI_COMMIT_TAG}_linux_${goarch}.tar.gz"
+manifest="${CI_PROJECT_DIR}/internal/templates/embed/${image_name}/agent.toml"
+if [ ! -f "${manifest}" ]; then
+  echo "missing manifest: ${manifest}" >&2
+  exit 1
+fi
+
+PICOCLAW_IMAGE_VERSION="$(awk -F= '
+  /^version[[:space:]]*=[[:space:]]*/ {
+    value = $2
+    gsub(/^[[:space:]]+|[[:space:]]+$/, "", value)
+    gsub(/^"/, "", value)
+    gsub(/"$/, "", value)
+    print value
+    exit
+  }
+' "${manifest}")"
+
+if [ -z "${PICOCLAW_IMAGE_VERSION}" ]; then
+  echo "missing version in ${manifest}" >&2
+  exit 1
+fi
+
+PICOCLAW_CLI_VERSION="${PICOCLAW_CLI_VERSION:-${CI_COMMIT_SHORT_SHA:-unknown}}"
+archive="${CI_PROJECT_DIR}/dist/csgclaw-cli_${PICOCLAW_CLI_VERSION}_linux_${goarch}.tar.gz"
 staging_dir="${CI_PROJECT_DIR}/bin"
 cli_path="${staging_dir}/csgclaw-cli"
 
 if [ ! -f "${archive}" ]; then
   echo "missing release artifact: ${archive}" >&2
-  echo "picoclaw image builds reuse csgclaw-cli from release-build (scripts/release-build-all.sh)" >&2
+  echo "picoclaw image builds reuse csgclaw-cli from picoclaw-cli-build (scripts/release-build-all.sh)" >&2
   exit 1
 fi
 
@@ -40,5 +62,5 @@ export PICOCLAW_BASE_TAG="${PICOCLAW_BASE_TAG:-2026.5.27}"
   --context "${CI_PROJECT_DIR}" \
   --dockerfile "${CI_PROJECT_DIR}/${dockerfile}" \
   --custom-platform "linux/${goarch}" \
-  --destination "${ACR_REGISTRY}/opencsghq/${image_name}:${CI_COMMIT_TAG}-${goarch}" \
+  --destination "${ACR_REGISTRY}/opencsghq/${image_name}:${PICOCLAW_IMAGE_VERSION}-${goarch}" \
   --build-arg PICOCLAW_IMAGE="${ACR_REGISTRY}/opencsghq/picoclaw:${PICOCLAW_BASE_TAG}"
diff --git a/.gitlab/ci-picoclaw-manifest.sh b/.gitlab/ci-picoclaw-manifest.sh
index 65038ad3..184e1e97 100755
--- a/.gitlab/ci-picoclaw-manifest.sh
+++ b/.gitlab/ci-picoclaw-manifest.sh
@@ -11,12 +11,34 @@ image_name="$1"
 : "${ACR_REGISTRY:?ACR_REGISTRY must be set}"
 : "${ACR_USERNAME:?ACR_USERNAME must be set}"
 : "${ACR_PASSWORD:?ACR_PASSWORD must be set}"
-: "${CI_COMMIT_TAG:?CI_COMMIT_TAG must be set}"
+: "${CI_PROJECT_DIR:?CI_PROJECT_DIR must be set}"
+
+manifest="${CI_PROJECT_DIR}/internal/templates/embed/${image_name}/agent.toml"
+if [ ! -f "${manifest}" ]; then
+  echo "missing manifest: ${manifest}" >&2
+  exit 1
+fi
+
+PICOCLAW_IMAGE_VERSION="$(awk -F= '
+  /^version[[:space:]]*=[[:space:]]*/ {
+    value = $2
+    gsub(/^[[:space:]]+|[[:space:]]+$/, "", value)
+    gsub(/^"/, "", value)
+    gsub(/"$/, "", value)
+    print value
+    exit
+  }
+' "${manifest}")"
+
+if [ -z "${PICOCLAW_IMAGE_VERSION}" ]; then
+  echo "missing version in ${manifest}" >&2
+  exit 1
+fi
 
 repo="${ACR_REGISTRY}/opencsghq/${image_name}"
-amd64_ref="${repo}:${CI_COMMIT_TAG}-amd64"
-arm64_ref="${repo}:${CI_COMMIT_TAG}-arm64"
-target_ref="${repo}:${CI_COMMIT_TAG}"
+amd64_ref="${repo}:${PICOCLAW_IMAGE_VERSION}-amd64"
+arm64_ref="${repo}:${PICOCLAW_IMAGE_VERSION}-arm64"
+target_ref="${repo}:${PICOCLAW_IMAGE_VERSION}"
 
 crane auth login "$ACR_REGISTRY" -u "$ACR_USERNAME" -p "$ACR_PASSWORD"
 
diff --git a/.gitlab/ci-picoclaw-version-check.sh b/.gitlab/ci-picoclaw-version-check.sh
new file mode 100755
index 00000000..9b23fa83
--- /dev/null
+++ b/.gitlab/ci-picoclaw-version-check.sh
@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# Detect embed agent.toml version changes on main for CI build gating.
+# CI never modifies agent.toml — it reads version/image.ref and builds images with that tag.
+# Writes picoclaw-build.env (GitLab dotenv report) for downstream jobs.
+set -euo pipefail
+
+: "${CI_COMMIT_SHA:?CI_COMMIT_SHA must be set}"
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+ENV_FILE="${CI_PROJECT_DIR:-${ROOT}}/picoclaw-build.env"
+MANAGER_TEMPLATE="picoclaw-manager"
+WORKER_TEMPLATE="picoclaw-worker"
+CURRENT_REF="HEAD"
+
+read_agent_toml_field_at_ref() {
+  local template="$1"
+  local git_ref="$2"
+  local field="$3"
+  local path="internal/templates/embed/${template}/agent.toml"
+
+  if ! git cat-file -e "${git_ref}:${path}" 2>/dev/null; then
+    return 0
+  fi
+
+  git show "${git_ref}:${path}" | awk -v field="${field}" '
+    $0 ~ "^" field "[[:space:]]*=" {
+      value = $0
+      sub(/^[^=]*=[[:space:]]*/, "", value)
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", value)
+      gsub(/^"/, "", value)
+      gsub(/"$/, "", value)
+      print value
+      exit
+    }
+  '
+}
+
+read_agent_toml_version_at_ref() {
+  read_agent_toml_field_at_ref "$1" "$2" "version"
+}
+
+read_agent_toml_image_ref_at_ref() {
+  read_agent_toml_field_at_ref "$1" "$2" "ref"
+}
+
+image_ref_tag() {
+  local ref="$1"
+  printf '%s' "${ref##*:}"
+}
+
+find_previous_main_commit() {
+  if git rev-parse "${CURRENT_REF}~1" >/dev/null 2>&1; then
+    git rev-parse "${CURRENT_REF}~1"
+    return 0
+  fi
+  return 1
+}
+
+version_changed() {
+  local template="$1"
+  local previous_ref="$2"
+  local current previous
+
+  current="$(read_agent_toml_version_at_ref "${template}" "${CURRENT_REF}")"
+  if [ -z "${previous_ref}" ]; then
+    if [ -n "${current}" ]; then
+      return 0
+    fi
+    return 1
+  fi
+
+  previous="$(read_agent_toml_version_at_ref "${template}" "${previous_ref}")"
+  if [ -z "${previous}" ]; then
+    return 0
+  fi
+  if [ -z "${current}" ]; then
+    echo "missing version in ${template}/agent.toml at ${CI_COMMIT_SHA}" >&2
+    exit 1
+  fi
+  [ "${current}" != "${previous}" ]
+}
+
+validate_version_and_ref() {
+  local template="$1"
+  local version="$2"
+  local ref ref_tag
+
+  if [ -z "${version}" ]; then
+    echo "missing version in ${template}/agent.toml at ${CI_COMMIT_SHA}" >&2
+    exit 1
+  fi
+
+  ref="$(read_agent_toml_image_ref_at_ref "${template}" "${CURRENT_REF}")"
+  if [ -z "${ref}" ]; then
+    echo "missing image.ref in ${template}/agent.toml at ${CI_COMMIT_SHA}" >&2
+    echo "bump version and image.ref locally with make build-all before merging to main" >&2
+    exit 1
+  fi
+
+  ref_tag="$(image_ref_tag "${ref}")"
+  if [ "${ref_tag}" != "${version}" ]; then
+    echo "image.ref tag ${ref_tag} does not match version ${version} in ${template}/agent.toml" >&2
+    echo "sync locally with make build-all before merging to main" >&2
+    exit 1
+  fi
+}
+
+previous_ref=""
+if previous_ref="$(find_previous_main_commit)"; then
+  echo "previous main commit: ${previous_ref}"
+else
+  echo "no previous commit found"
+fi
+
+manager_version="$(read_agent_toml_version_at_ref "${MANAGER_TEMPLATE}" "${CURRENT_REF}")"
+worker_version="$(read_agent_toml_version_at_ref "${WORKER_TEMPLATE}" "${CURRENT_REF}")"
+
+manager_build=false
+worker_build=false
+if version_changed "${MANAGER_TEMPLATE}" "${previous_ref:-}"; then
+  manager_build=true
+  validate_version_and_ref "${MANAGER_TEMPLATE}" "${manager_version}"
+fi
+if version_changed "${WORKER_TEMPLATE}" "${previous_ref:-}"; then
+  worker_build=true
+  validate_version_and_ref "${WORKER_TEMPLATE}" "${worker_version}"
+fi
+
+any_build=false
+if [ "${manager_build}" = true ] || [ "${worker_build}" = true ]; then
+  any_build=true
+fi
+
+{
+  printf 'PICOCLAW_MANAGER_VERSION=%s\n' "${manager_version}"
+  printf 'PICOCLAW_WORKER_VERSION=%s\n' "${worker_version}"
+  printf 'PICOCLAW_MANAGER_BUILD=%s\n' "${manager_build}"
+  printf 'PICOCLAW_WORKER_BUILD=%s\n' "${worker_build}"
+  printf 'PICOCLAW_ANY_BUILD=%s\n' "${any_build}"
+  if [ -n "${previous_ref}" ]; then
+    printf 'PICOCLAW_PREVIOUS_COMMIT=%s\n' "${previous_ref}"
+  fi
+} > "${ENV_FILE}"
+
+echo "picoclaw-manager version=${manager_version} build=${manager_build}"
+echo "picoclaw-worker version=${worker_version} build=${worker_build}"
+echo "picoclaw any_build=${any_build}"
+cat "${ENV_FILE}"
diff --git a/.gitlab/ci.yml b/.gitlab/ci.yml
index af213079..48de186a 100644
--- a/.gitlab/ci.yml
+++ b/.gitlab/ci.yml
@@ -1,12 +1,13 @@
-# GitLab CI: on tag v*, build release archives and a Docker image, then upload archives to SSH storage.
+# GitLab CI: release on tag v*; picoclaw embed images on main branch commits.
 #
 # Platform list: scripts/release-platforms.txt — keep parallel.matrix below in sync (same GOOS/GOARCH rows).
 #
-# Trigger: tags matching v* (e.g. pull mirror with "Trigger pipelines for mirror updates").
+# Triggers:
+#   - tag v* — release archives, csgclaw Docker image, SSH upload (uses committed embed agent.toml)
+#   - push / merge to default branch (main) — build/push picoclaw images when agent.toml version changed (uses committed version/ref; no bump)
 #
 # Implementation: scripts/release-build-all.sh (per matrix cell); .gitlab/ci-gitlab-release-upload.sh (upload only);
-# scripts/prepare-docker-embed-dist.sh (stage embed templates with Dockerfile into */dist/);
-# scripts/patch-docker-embed-image-refs.sh (patch dist/agent.toml image refs after image manifest merge);
+# .gitlab/ci-picoclaw-version-check.sh (gate builds when agent.toml version changed; never bumps version);
 # .gitlab/ci-picoclaw-image.sh (stage csgclaw-cli from dist/ into picoclaw manager/worker images); .gitlab/bookworm-mirror.sh (apt sources).
 #
 # Required CI/CD variables:
@@ -76,6 +77,10 @@ stages:
   rules:
     - if: $CI_COMMIT_TAG =~ /^v/
 
+.main_rules:
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_COMMIT_TAG == null
+
 .release_image:
   image:
     name: ${ACR_REGISTRY}/opencsg_public/golang:bookworm
@@ -107,16 +112,31 @@ stages:
   extends:
     - .kaniko_image
     - .kaniko_acr_auth
-    - .release_rules
+    - .main_rules
   stage: image
   needs:
-    - job: release-cli-build
+    - job: picoclaw-version-check
+      artifacts: true
+    - job: picoclaw-cli-build
       artifacts: true
   parallel:
     matrix:
       - GOARCH: amd64
       - GOARCH: arm64
   script:
+    - |
+      case "${PICOCLAW_IMAGE_NAME}" in
+        picoclaw-manager) build_flag="${PICOCLAW_MANAGER_BUILD:-false}" ;;
+        picoclaw-worker) build_flag="${PICOCLAW_WORKER_BUILD:-false}" ;;
+        *)
+          echo "unknown picoclaw image ${PICOCLAW_IMAGE_NAME}" >&2
+          exit 1
+          ;;
+      esac
+      if [ "${build_flag}" != "true" ]; then
+        echo "picoclaw embed version unchanged; skipping ${PICOCLAW_IMAGE_NAME} image build"
+        exit 0
+      fi
     - chmod +x .gitlab/ci-picoclaw-image.sh
     - sh .gitlab/ci-picoclaw-image.sh "${GOARCH}" "${PICOCLAW_DOCKERFILE}" "${PICOCLAW_IMAGE_NAME}"
 
@@ -139,28 +159,27 @@ web-build:
       - web/static-dist/
     expire_in: 1 day
 
-embed-templates-prepare:
+# Detect version changes and read build flags. Does not modify agent.toml.
+picoclaw-version-check:
   extends:
     - .release_image
-    - .release_rules
+    - .main_rules
   stage: build
   script:
-    - chmod +x scripts/prepare-docker-embed-dist.sh
-    - scripts/prepare-docker-embed-dist.sh
+    - chmod +x .gitlab/ci-picoclaw-version-check.sh
+    - ./.gitlab/ci-picoclaw-version-check.sh
   artifacts:
-    paths:
-      - internal/templates/embed/*/dist/
-    expire_in: 1 day
+    reports:
+      dotenv: picoclaw-build.env
 
-# Linux csgclaw-cli only — consumed by docker embed image builds before the full release.
-# Needs embed-templates-prepare: csgclaw-cli links internal/templates (go:embed embed/*/dist for Dockerfile templates).
-release-cli-build:
+# Linux csgclaw-cli for picoclaw embed image builds (main branch only).
+picoclaw-cli-build:
   extends:
     - .release_image
-    - .release_rules
+    - .main_rules
   stage: build
   needs:
-    - job: embed-templates-prepare
+    - job: picoclaw-version-check
       artifacts: true
   parallel:
     matrix:
@@ -173,11 +192,19 @@ release-cli-build:
     - bash .gitlab/bookworm-mirror.sh
     - apt-get update -qq && apt-get install -y --no-install-recommends zip ca-certificates
   script:
-    - export VERSION="$CI_COMMIT_TAG"
+    - |
+      if [ "${PICOCLAW_ANY_BUILD}" != "true" ]; then
+        echo "No picoclaw embed version changes since previous commit; skipping csgclaw-cli build for embed images"
+        mkdir -p "${DIST_DIR:-dist}"
+        echo "skipped" > "${DIST_DIR:-dist}/picoclaw-embed-cli-build.skipped"
+        exit 0
+      fi
+    - export VERSION="${CI_COMMIT_SHORT_SHA}"
     - export COMMIT="$(git rev-parse --short HEAD)"
     - export BUILD_TIME="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
     - export DIST_DIR="${DIST_DIR:-dist}"
     - export RELEASE_APPS="csgclaw-cli"
+    - export PICOCLAW_CLI_VERSION="${CI_COMMIT_SHORT_SHA}"
     - mkdir -p "$DIST_DIR" "${CI_PROJECT_DIR}/.gocache"
     - export GOCACHE="${GOCACHE:-${CI_PROJECT_DIR}/.gocache}"
     - export BOXLITE_CLI_VERSION="${BOXLITE_CLI_VERSION:-v0.9.0}"
@@ -196,8 +223,6 @@ release-build:
   needs:
     - job: web-build
       artifacts: true
-    - job: embed-templates-patch
-      artifacts: true
   parallel:
     matrix:
       - GOOS: linux
@@ -211,10 +236,20 @@ release-build:
       - GOOS: windows
         GOARCH: amd64
   before_script:
-    - chmod +x .gitlab/bookworm-mirror.sh scripts/release-build-all.sh
+    - chmod +x .gitlab/bookworm-mirror.sh scripts/release-build-all.sh scripts/list-docker-embed-templates.sh
     - bash .gitlab/bookworm-mirror.sh
     - apt-get update -qq && apt-get install -y --no-install-recommends zip ca-certificates
   script:
+    - |
+      while IFS= read -r name; do
+        manifest="internal/templates/embed/${name}/agent.toml"
+        test -f "${manifest}"
+        grep '^ref = ' "${manifest}"
+        if grep -q '^ref = ""' "${manifest}"; then
+          echo "missing image ref in ${manifest}" >&2
+          exit 1
+        fi
+      done < <(./scripts/list-docker-embed-templates.sh)
     - export VERSION="$CI_COMMIT_TAG"
     - export COMMIT="$(git rev-parse --short HEAD)"
     - export BUILD_TIME="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
@@ -235,7 +270,7 @@ docker-build-amd64:
     - .release_rules
   stage: release
   needs:
-    - job: embed-templates-patch
+    - job: web-build
       artifacts: true
   script:
     - export COMMIT="$(git rev-parse --short HEAD)"
@@ -269,17 +304,35 @@ picoclaw-worker-image:
 .picoclaw_manifest:
   extends:
     - .crane_image
-    - .release_rules
+    - .main_rules
   stage: image
+  needs:
+    - job: picoclaw-version-check
+      artifacts: true
   before_script:
     - chmod +x .gitlab/ci-picoclaw-manifest.sh
     - crane version
   script:
+    - |
+      case "${PICOCLAW_IMAGE_NAME}" in
+        picoclaw-manager) build_flag="${PICOCLAW_MANAGER_BUILD:-false}" ;;
+        picoclaw-worker) build_flag="${PICOCLAW_WORKER_BUILD:-false}" ;;
+        *)
+          echo "unknown picoclaw image ${PICOCLAW_IMAGE_NAME}" >&2
+          exit 1
+          ;;
+      esac
+      if [ "${build_flag}" != "true" ]; then
+        echo "picoclaw embed version unchanged; skipping ${PICOCLAW_IMAGE_NAME} manifest"
+        exit 0
+      fi
     - sh .gitlab/ci-picoclaw-manifest.sh "${PICOCLAW_IMAGE_NAME}"
 
 picoclaw-manager-manifest:
   extends: .picoclaw_manifest
   needs:
+    - job: picoclaw-version-check
+      artifacts: true
     - job: picoclaw-manager-image
       artifacts: false
   variables:
@@ -288,31 +341,13 @@ picoclaw-manager-manifest:
 picoclaw-worker-manifest:
   extends: .picoclaw_manifest
   needs:
+    - job: picoclaw-version-check
+      artifacts: true
     - job: picoclaw-worker-image
       artifacts: false
   variables:
     PICOCLAW_IMAGE_NAME: picoclaw-worker
 
-embed-templates-patch:
-  extends:
-    - .release_image
-    - .release_rules
-  stage: release
-  needs:
-    - job: embed-templates-prepare
-      artifacts: true
-    - job: picoclaw-manager-manifest
-      artifacts: false
-    - job: picoclaw-worker-manifest
-      artifacts: false
-  script:
-    - chmod +x scripts/patch-docker-embed-image-refs.sh
-    - scripts/patch-docker-embed-image-refs.sh
-  artifacts:
-    paths:
-      - internal/templates/embed/*/dist/
-    expire_in: 1 day
-
 release-upload:
   extends:
     - .release_image
diff --git a/AGENTS.md b/AGENTS.md
index 6c51964f..ddec7bd5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,7 +25,7 @@ web/static-dist/        generated Web UI assets for Go embed; run make web-build
 
 ## Commands
 
-See [docs/build.md](docs/build.md) or [docs/build.zh.md](docs/build.zh.md) for Makefile targets, embed dist staging, and optional Docker image builds.
+See [docs/build.md](docs/build.md) or [docs/build.zh.md](docs/build.zh.md) for Makefile targets, embed template versioning, and optional Docker image builds.
 
 ```bash
 make                    # default build (no docker images)
diff --git a/Makefile b/Makefile
index 37915445..3e21a1b4 100644
--- a/Makefile
+++ b/Makefile
@@ -27,8 +27,6 @@ CLI_BIN ?= $(BIN_DIR)/csgclaw-cli
 ACR_REGISTRY ?= opencsg-registry.cn-beijing.cr.aliyuncs.com
 IMAGE ?= $(ACR_REGISTRY)/opencsghq/picoclaw
 TAG ?= 2026.6.8
-DOCKER_EMBED_IMAGE_TAG ?= dev
-PICOCLAW_IMAGE_TAG ?= $(DOCKER_EMBED_IMAGE_TAG)
 LOCAL_IMAGE ?= picoclaw:local
 PICOCLAW_BASE_IMAGE ?= $(IMAGE):$(TAG)
 DOCKER_EMBED_DOCKER_GOOS ?= linux
@@ -40,28 +38,27 @@ PICOCLAW_DOCKER_CLI ?= $(DOCKER_EMBED_CLI)
 
 .DEFAULT_GOAL := build
 
-.PHONY: help fmt test check-web-toolchain check-web-layout ensure-web-deps web-install web-dev build-web build build-server build-server-bin stage-docker-embed-cli stage-picoclaw-docker-cli prepare-docker-embed-dist prepare-picoclaw-embed-dist patch-docker-embed-image-refs patch-picoclaw-embed-image-refs stage-docker-embed-dist stage-picoclaw-embed-dist ensure-docker-embed-dist build-docker-embed-images build-docker-embed-runtime-embed build-picoclaw-runtime-embed build-all run clean package package-all release tag push publish build-picoclaw-manager-image build-picoclaw-worker-image
+.PHONY: help fmt test check-web-toolchain check-web-layout ensure-web-deps web-install web-dev build-web build build-server build-server-bin stage-docker-embed-cli stage-picoclaw-docker-cli sync-docker-embed-image-refs sync-picoclaw-embed-image-refs bump-docker-embed-version bump-picoclaw-embed-version ensure-docker-embed-manifests build-docker-embed-images build-docker-embed-images-only build-docker-embed-runtime-embed build-picoclaw-runtime-embed build-all run clean package package-all release tag push publish build-picoclaw-manager-image build-picoclaw-worker-image
 
 help:
 	@printf '%s\n' \
-		'make            - build Web UI, ensure embed dist, bin/csgclaw, bin/csgclaw-cli (no docker images)' \
+		'make            - build Web UI, ensure embed image refs, bin/csgclaw, bin/csgclaw-cli (no docker images)' \
 		'make build      - same as default goal' \
-		'make build-all  - build plus docker-build all embed template images and patch refs' \
+		'make build-all  - build-web, bump embed versions, rebuild binaries, docker-build all embed images' \
 		'make fmt        - format Go files' \
-		'make test       - stage-docker-embed-dist (patched :dev refs), then go test ./...' \
+		'make test       - ensure embed agent.toml refs, then go test ./...' \
 		'make web-install - install Web UI dependencies' \
 		'make web-dev    - run Vite Web UI dev server' \
 		'make build-web  - build Web UI app into web/static-dist' \
-		'make build-server-bin - build bin/csgclaw and bin/csgclaw-cli (expects embed/*/dist; use stage-docker-embed-dist first)' \
-		'make stage-docker-embed-dist - prepare dist/ and patch dev image refs (no docker)' \
-		'make build-docker-embed-runtime-embed - stage linux cli, docker all embed templates with Dockerfile, patch refs' \
+		'make build-server-bin - build bin/csgclaw and bin/csgclaw-cli' \
+		'make build-docker-embed-runtime-embed - bump versions, stage linux cli, docker-build all embed templates' \
 		'make run        - build (no docker images), then run the server' \
 		'make clean      - remove local build outputs'
 
 fmt:
 	$(GOFMT) -w $(shell find cli cmd internal web -name '*.go')
 
-test: stage-docker-embed-dist
+test: ensure-docker-embed-manifests
 	env GOCACHE=$(GOCACHE) $(GO) test ./...
 
 check-web-toolchain:
@@ -115,7 +112,7 @@ build-web: ensure-web-deps
 		exit 1; \
 	}
 
-build: build-web ensure-docker-embed-dist build-server-bin
+build: build-web ensure-docker-embed-manifests build-server-bin
 
 build-server-bin:
 	mkdir -p $(BIN_DIR)
@@ -123,9 +120,9 @@ build-server-bin:
 	env GOCACHE=$(GOCACHE) CGO_ENABLED=$(CGO_ENABLED) GOOS=$(TARGET_OS) GOARCH=$(TARGET_ARCH) \
 		$(GO) build -ldflags "$(CLI_LDFLAGS)" -o $(BIN_DIR)/csgclaw-cli ./cmd/csgclaw-cli
 
-build-server: ensure-docker-embed-dist build-server-bin
+build-server: ensure-docker-embed-manifests build-server-bin
 
-$(DOCKER_EMBED_CLI): prepare-docker-embed-dist
+$(DOCKER_EMBED_CLI):
 	mkdir -p $(BIN_DIR)
 	env GOCACHE=$(GOCACHE) CGO_ENABLED=$(CGO_ENABLED) GOOS=$(DOCKER_EMBED_DOCKER_GOOS) GOARCH=$(DOCKER_EMBED_DOCKER_GOARCH) \
 		$(GO) build -ldflags "$(CLI_LDFLAGS)" -o $(DOCKER_EMBED_CLI) ./cmd/csgclaw-cli
@@ -133,68 +130,59 @@ $(DOCKER_EMBED_CLI): prepare-docker-embed-dist
 stage-docker-embed-cli: $(DOCKER_EMBED_CLI)
 stage-picoclaw-docker-cli: stage-docker-embed-cli
 
-prepare-docker-embed-dist:
-	chmod +x scripts/list-docker-embed-templates.sh scripts/prepare-docker-embed-dist.sh
-	scripts/prepare-docker-embed-dist.sh
+sync-docker-embed-image-refs:
+	chmod +x scripts/list-docker-embed-templates.sh scripts/sync-docker-embed-image-refs.sh
+	ACR_REGISTRY="$(ACR_REGISTRY)" \
+		scripts/sync-docker-embed-image-refs.sh
 
-prepare-picoclaw-embed-dist: prepare-docker-embed-dist
+sync-picoclaw-embed-image-refs: sync-docker-embed-image-refs
 
-patch-docker-embed-image-refs: prepare-docker-embed-dist
-	chmod +x scripts/list-docker-embed-templates.sh scripts/patch-docker-embed-image-refs.sh
-	ACR_REGISTRY="$(ACR_REGISTRY)" VERSION="$(DOCKER_EMBED_IMAGE_TAG)" \
-		scripts/patch-docker-embed-image-refs.sh
+bump-docker-embed-version:
+	chmod +x scripts/list-docker-embed-templates.sh scripts/bump-docker-embed-version.sh
+	ACR_REGISTRY="$(ACR_REGISTRY)" \
+		scripts/bump-docker-embed-version.sh
 
-patch-picoclaw-embed-image-refs: patch-docker-embed-image-refs
+bump-picoclaw-embed-version: bump-docker-embed-version
 
-stage-docker-embed-dist: prepare-docker-embed-dist patch-docker-embed-image-refs
-stage-picoclaw-embed-dist: stage-docker-embed-dist
-
-# Stage embed/*/dist when missing (no docker).
-ensure-docker-embed-dist:
+# Sync embed agent.toml image refs from version when missing or out of sync (no docker).
+ensure-docker-embed-manifests:
 	@mkdir -p "$(GOCACHE)"
-	@chmod +x scripts/list-docker-embed-templates.sh
-	@dist_missing=0; \
-	for name in $$(scripts/list-docker-embed-templates.sh); do \
-	  manifest="internal/templates/embed/$$name/dist/agent.toml"; \
-	  if [ ! -f "$$manifest" ] || ! grep -q '^ref = ' "$$manifest"; then \
-	    dist_missing=1; \
-	    break; \
-	  fi; \
-	done; \
-	if [ "$$dist_missing" -eq 1 ]; then \
-	  printf '%s\n' "docker embed dist/ missing or incomplete; running stage-docker-embed-dist"; \
-	  $(MAKE) stage-docker-embed-dist; \
+	@chmod +x scripts/list-docker-embed-templates.sh scripts/check-docker-embed-manifests.sh
+	@if ! scripts/check-docker-embed-manifests.sh; then \
+	  printf '%s\n' "docker embed agent.toml version/ref out of sync; running sync-docker-embed-image-refs"; \
+	  $(MAKE) sync-docker-embed-image-refs; \
 	fi
 
-build-docker-embed-images: stage-docker-embed-cli
+build-docker-embed-images: stage-docker-embed-cli bump-docker-embed-version
+	chmod +x scripts/build-docker-embed-images.sh
+	ACR_REGISTRY="$(ACR_REGISTRY)" PICOCLAW_BASE_IMAGE="$(PICOCLAW_BASE_IMAGE)" \
+		scripts/build-docker-embed-images.sh
+
+build-docker-embed-images-only: stage-docker-embed-cli
 	chmod +x scripts/build-docker-embed-images.sh
 	ACR_REGISTRY="$(ACR_REGISTRY)" PICOCLAW_BASE_IMAGE="$(PICOCLAW_BASE_IMAGE)" \
-		DOCKER_EMBED_IMAGE_TAG="$(DOCKER_EMBED_IMAGE_TAG)" \
 		scripts/build-docker-embed-images.sh
 
-build-docker-embed-runtime-embed: build-docker-embed-images patch-docker-embed-image-refs
+build-docker-embed-runtime-embed: build-docker-embed-images
 build-picoclaw-runtime-embed: build-docker-embed-runtime-embed
 
 build-picoclaw-manager-image: stage-docker-embed-cli
-	chmod +x scripts/prepare-docker-embed-dist.sh scripts/patch-docker-embed-image-refs.sh scripts/build-docker-embed-images.sh
-	scripts/prepare-docker-embed-dist.sh
-	ACR_REGISTRY="$(ACR_REGISTRY)" VERSION="$(DOCKER_EMBED_IMAGE_TAG)" \
-		scripts/patch-docker-embed-image-refs.sh
+	chmod +x scripts/bump-docker-embed-version.sh scripts/build-docker-embed-images.sh
+	ACR_REGISTRY="$(ACR_REGISTRY)" \
+		scripts/bump-docker-embed-version.sh picoclaw-manager
 	ACR_REGISTRY="$(ACR_REGISTRY)" PICOCLAW_BASE_IMAGE="$(PICOCLAW_BASE_IMAGE)" \
-		DOCKER_EMBED_IMAGE_TAG="$(DOCKER_EMBED_IMAGE_TAG)" \
 		scripts/build-docker-embed-images.sh picoclaw-manager
 
 build-picoclaw-worker-image: stage-docker-embed-cli
-	chmod +x scripts/prepare-docker-embed-dist.sh scripts/patch-docker-embed-image-refs.sh scripts/build-docker-embed-images.sh
-	scripts/prepare-docker-embed-dist.sh
-	ACR_REGISTRY="$(ACR_REGISTRY)" VERSION="$(DOCKER_EMBED_IMAGE_TAG)" \
-		scripts/patch-docker-embed-image-refs.sh
+	chmod +x scripts/bump-docker-embed-version.sh scripts/build-docker-embed-images.sh
+	ACR_REGISTRY="$(ACR_REGISTRY)" \
+		scripts/bump-docker-embed-version.sh picoclaw-worker
 	ACR_REGISTRY="$(ACR_REGISTRY)" PICOCLAW_BASE_IMAGE="$(PICOCLAW_BASE_IMAGE)" \
-		DOCKER_EMBED_IMAGE_TAG="$(DOCKER_EMBED_IMAGE_TAG)" \
 		scripts/build-docker-embed-images.sh picoclaw-worker
 
-build-all: build
-	$(MAKE) build-docker-embed-images patch-docker-embed-image-refs
+# Bump embed versions before go:embed so the server binary matches built images.
+build-all: build-web bump-docker-embed-version build-server-bin
+	$(MAKE) build-docker-embed-images-only
 
 run: build
 	$(BIN) serve
@@ -219,10 +207,6 @@ release: build-web
 
 clean:
 	rm -rf $(BIN_DIR) $(DIST_DIR) $(GOCACHE)
-	@for dir in internal/templates/embed/*/dist; do \
-	  [ -f "$${dir%/dist}/Dockerfile" ] || continue; \
-	  find "$$dir" -mindepth 1 ! -name .gitkeep -exec rm -rf {} + ; \
-	done
 
 tag:
 	docker tag $(LOCAL_IMAGE) $(IMAGE):$(TAG)
diff --git a/README.md b/README.md
index 9fbc1cef..225e511b 100644
--- a/README.md
+++ b/README.md
@@ -39,7 +39,7 @@ Official release bundles are also published for macOS amd64 and Windows amd64. W
 make build
 ```
 
-See [docs/build.md](docs/build.md) for embed dist staging, optional PicoClaw Docker image builds, and other Makefile targets.
+See [docs/build.md](docs/build.md) for embed template versioning, optional PicoClaw Docker image builds, and other Makefile targets.
 
 For most users, the install script above is the simpler option.
 
diff --git a/README.zh.md b/README.zh.md
index 64dcf512..41594b52 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -39,7 +39,7 @@ curl.exe -fsSL https://csgclaw.opencsg.com/install.ps1 | powershell -ExecutionPo
 make build
 ```
 
-Makefile 详细说明（embed dist、可选 Docker 镜像构建等）见 [docs/build.zh.md](docs/build.zh.md)。
+Makefile 详细说明（embed 模板 version、可选 Docker 镜像构建等）见 [docs/build.zh.md](docs/build.zh.md)。
 
 对大多数用户来说，直接使用上面的安装脚本会更简单。
 
diff --git a/docs/build.md b/docs/build.md
index a6272baf..2ff07c9d 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -30,7 +30,7 @@ make build
 This builds:
 
 1. Web UI assets into `web/static-dist/`
-2. Embed template `dist/` trees when missing (see [Embed dist](#embed-dist))
+2. Embed template `agent.toml` image refs when missing or out of sync with `version` (see [Embed templates](#embed-templates))
 3. `bin/csgclaw` (server CLI)
 4. `bin/csgclaw-cli` for the current platform
 
@@ -46,7 +46,7 @@ make run
 
 ## Full build
 
-`build-all` runs `build`, then docker-builds all embed templates with a `Dockerfile` and patches image refs:
+`build-all` builds the Web UI, bumps each embed template's `version` and syncs `image.ref`, rebuilds `csgclaw` (so embed matches image tags), then docker-builds all templates with a `Dockerfile` (**no `dist/` output**):
 
 ```bash
 make build-all
@@ -75,23 +75,26 @@ Frontend structure and verification details: [docs/web/development.md](web/devel
 
 `csgclaw-cli` is built with `CGO_ENABLED=0` so it runs inside musl-based PicoClaw and BoxLite sandbox images. Release CI uses the same setting (`scripts/release-build-all.sh`).
 
-## Embed dist
+## Embed templates
 
-Builtin PicoClaw templates ship source under `internal/templates/embed/<name>/`. Runtime files for `go:embed` live in each template's `dist/` directory and are generated locally or in CI.
+Builtin PicoClaw templates live under `internal/templates/embed/<name>/` and are embedded directly via `go:embed` (`agent.toml`, `workspace/`, etc.). Each docker embed template carries a `version` field and matching `image.ref`.
+
+**Local (before PR)**: `make build-all` bumps `version`, syncs `image.ref`, rebuilds `csgclaw` (so embed matches image tags), then builds Docker images.
+
+**GitLab CI (main)**: reads committed `version` / `image.ref`, builds and pushes images **without** modifying `agent.toml`; runs only when `version` changed since the previous commit.
 
 | Target | Description |
 |--------|-------------|
-| `make prepare-docker-embed-dist` | Copy template source into `embed/*/dist/` (no Docker) |
-| `make patch-docker-embed-image-refs` | Patch `dist/agent.toml` image refs (default tag `:dev`) |
-| `make stage-docker-embed-dist` | `prepare` + `patch` |
-| `make ensure-docker-embed-dist` | Stage dist when missing (used by `build-all`) |
+| `make sync-docker-embed-image-refs` | Sync `image.ref` from current `version` (no bump) |
+| `make bump-docker-embed-version` | Bump `version` and sync `image.ref` for all docker embed templates |
+| `make ensure-docker-embed-manifests` | Run `sync-docker-embed-image-refs` when `image.ref` is missing or out of sync with `version` (used by `make build` / `make test`) |
 
 Templates with a `Dockerfile` are discovered by `scripts/list-docker-embed-templates.sh` (currently `picoclaw-manager` and `picoclaw-worker`).
 
-If `make build-server-bin` fails with `pattern embed/.../dist: no matching files found`, run:
+If `image.ref` is empty or out of sync with `version`, run:
 
 ```bash
-make stage-docker-embed-dist
+make sync-docker-embed-image-refs
 ```
 
 ## Docker embed images (optional)
@@ -104,38 +107,39 @@ Local Docker image builds are **optional** and can be slow. The usual entry poin
 |---------|------------------------|
 | `make` / `make build` | No |
 | `make build-all` | Yes |
-| `make build-docker-embed-runtime-embed` | Yes (images + patch refs, without rebuilding binaries) |
+| `make build-docker-embed-runtime-embed` | Yes (bump versions + images, without rebuilding binaries) |
 
 ### Image build targets
 
 | Target | Description |
 |--------|-------------|
-| `make build-docker-embed-images` | Build all embed templates that have a `Dockerfile` |
-| `make build-picoclaw-manager-image` | Build manager image only |
-| `make build-picoclaw-worker-image` | Build worker image only |
-| `make build-docker-embed-runtime-embed` | Build linux CLI, docker-build all templates, patch refs |
+| `make build-docker-embed-images` | Bump versions and build all embed templates that have a `Dockerfile` |
+| `make build-picoclaw-manager-image` | Bump manager version and build manager image only |
+| `make build-picoclaw-worker-image` | Bump worker version and build worker image only |
+| `make build-docker-embed-runtime-embed` | Alias for `build-docker-embed-images` |
 
-Alias targets `build-picoclaw-runtime-embed`, `stage-picoclaw-embed-dist`, and similar names remain for compatibility.
+Alias targets `build-picoclaw-runtime-embed`, `sync-picoclaw-embed-image-refs`, `bump-picoclaw-embed-version`, and similar names remain for compatibility.
 
 ### Useful variables
 
 ```bash
-# Registry and tags (defaults shown)
+# Registry and base image (defaults shown)
 ACR_REGISTRY=opencsg-registry.cn-beijing.cr.aliyuncs.com
-DOCKER_EMBED_IMAGE_TAG=dev
 PICOCLAW_BASE_IMAGE=opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/picoclaw:2026.6.8
 
-# Example: build worker image with a custom tag
-make build-picoclaw-worker-image DOCKER_EMBED_IMAGE_TAG=local
+# Example: local pre-PR image test (bumps version and updates image.ref, e.g. 0.1.3 -> 0.1.4)
+make build-all
 ```
 
 Resulting images follow:
 
 ```text
-${ACR_REGISTRY}/opencsghq/picoclaw-manager:${DOCKER_EMBED_IMAGE_TAG}
-${ACR_REGISTRY}/opencsghq/picoclaw-worker:${DOCKER_EMBED_IMAGE_TAG}
+${ACR_REGISTRY}/opencsghq/picoclaw-manager:<agent.toml version>
+${ACR_REGISTRY}/opencsghq/picoclaw-worker:<agent.toml version>
 ```
 
+After a successful image build, the matching `agent.toml` files are updated in place (`version` and `image.ref`).
+
 Build context is the repository root; Dockerfiles expect `bin/csgclaw-cli` (linux) to be present—`stage-docker-embed-cli` creates it.
 
 ### BoxLite vs local Docker images
@@ -146,9 +150,9 @@ Images built with `make build-docker-embed-images` are stored in the **Docker**
 
 | Target | Description |
 |--------|-------------|
-| `make test` | `stage-docker-embed-dist`, then `go test ./...` |
+| `make test` | `ensure-docker-embed-manifests`, then `go test ./...` (does not overwrite committed version/ref) |
 | `make fmt` | Format Go sources under `cli/`, `cmd/`, `internal/`, `web/` |
-| `make clean` | Remove `bin/`, `dist/`, `.gocache/`, and generated embed `dist/` contents |
+| `make clean` | Remove `bin/`, `dist/`, and `.gocache/` |
 
 For targeted Go tests:
 
@@ -167,7 +171,7 @@ Maintainer targets:
 | `make package-all` | Full build plus `csgclaw` and `csgclaw-cli` packages |
 | `make release` | Cross-platform release bundles (darwin/linux, arm64/amd64) |
 
-CI release flows use `.github/workflows/release.yml` and GitLab jobs for embed dist and image builds.
+CI release flows use `.github/workflows/release.yml` (tag) and GitLab CI (tag for release archives; **main branch** builds and pushes picoclaw images from committed `version`, without editing `agent.toml`). Tag releases embed `agent.toml` from the tag commit as-is.
 
 ## Related docs
 
diff --git a/docs/build.zh.md b/docs/build.zh.md
index 749dfea7..9af56ec0 100644
--- a/docs/build.zh.md
+++ b/docs/build.zh.md
@@ -30,7 +30,7 @@ make build
 会依次构建：
 
 1. Web UI 产物到 `web/static-dist/`
-2. 缺失时的 embed 模板 `dist/` 目录（见 [Embed dist](#embed-dist)）
+2. 缺失或与 `version` 不一致时同步 embed 模板 `agent.toml` 的 `image.ref`（见 [Embed 模板](#embed-模板)）
 3. `bin/csgclaw`（服务端 CLI）
 4. 当前平台的 `bin/csgclaw-cli`
 
@@ -46,7 +46,7 @@ make run
 
 ## 完整构建
 
-`build-all` 先执行 `build`，再 docker build 所有带 `Dockerfile` 的 embed 模板并 patch 镜像 ref：
+`build-all` 会构建 Web UI、递增各 embed 模板的 `version` 并同步 `image.ref`、编译 `csgclaw`（使 embed 与镜像 tag 一致），再 docker build 所有带 `Dockerfile` 的模板（**不产生 `dist/`**）：
 
 ```bash
 make build-all
@@ -75,23 +75,26 @@ make build-all
 
 `csgclaw-cli` 使用 `CGO_ENABLED=0` 构建，以便在 musl 环境的 PicoClaw / BoxLite 沙箱中运行。Release CI 同样使用该设置（`scripts/release-build-all.sh`）。
 
-## Embed dist
+## Embed 模板
 
-内置 PicoClaw 模板源码位于 `internal/templates/embed/<name>/`。供 `go:embed` 使用的运行时文件在各模板的 `dist/` 目录，由本地或 CI 生成。
+内置 PicoClaw 模板位于 `internal/templates/embed/<name>/`，通过 `go:embed` 直接嵌入（`agent.toml`、`workspace/` 等）。每个 docker embed 模板在 `agent.toml` 中有 `version` 字段与对应的 `image.ref`。
+
+**本地（PR 前）**：`make build-all` 会先递增 `version`、同步 `image.ref`，再编译 `csgclaw`（使 embed 与镜像 tag 一致），最后构建 Docker 镜像。
+
+**GitLab CI（main）**：仅读取已提交的 `version` / `image.ref` 构建并 push 镜像，**不会**修改 `agent.toml`；仅当相对上一 commit 的 `version` 发生变化时才触发构建。
 
 | 目标 | 说明 |
 |------|------|
-| `make prepare-docker-embed-dist` | 将模板源码复制到 `embed/*/dist/`（不打 Docker） |
-| `make patch-docker-embed-image-refs` | 修补 `dist/agent.toml` 中的镜像 ref（默认 tag `:dev`） |
-| `make stage-docker-embed-dist` | `prepare` + `patch` |
-| `make ensure-docker-embed-dist` | 缺失时自动 stage dist（`build-all` 使用） |
+| `make sync-docker-embed-image-refs` | 按当前 `version` 同步 `image.ref`（不递增） |
+| `make bump-docker-embed-version` | 递增全部 docker embed 模板的 `version` 并同步 `image.ref` |
+| `make ensure-docker-embed-manifests` | `image.ref` 缺失或与 `version` 不一致时调用 `sync-docker-embed-image-refs`（`make build` / `make test` 使用） |
 
 带 `Dockerfile` 的模板由 `scripts/list-docker-embed-templates.sh` 发现（当前为 `picoclaw-manager` 和 `picoclaw-worker`）。
 
-若 `make build-server-bin` 报错 `pattern embed/.../dist: no matching files found`，请执行：
+若 `image.ref` 为空或与 `version` 不一致，请执行：
 
 ```bash
-make stage-docker-embed-dist
+make sync-docker-embed-image-refs
 ```
 
 ## Docker embed 镜像（可选）
@@ -104,38 +107,39 @@ make stage-docker-embed-dist
 |------|----------------------|
 | `make` / `make build` | 否 |
 | `make build-all` | 是 |
-| `make build-docker-embed-runtime-embed` | 是（仅镜像 + patch refs，不重建二进制） |
+| `make build-docker-embed-runtime-embed` | 是（递增 version + 构建镜像，不重建二进制） |
 
 ### 镜像构建目标
 
 | 目标 | 说明 |
 |------|------|
-| `make build-docker-embed-images` | 构建所有带 `Dockerfile` 的 embed 模板 |
-| `make build-picoclaw-manager-image` | 仅构建 manager 镜像 |
-| `make build-picoclaw-worker-image` | 仅构建 worker 镜像 |
-| `make build-docker-embed-runtime-embed` | 构建 linux CLI、docker build 全部模板、patch refs |
+| `make build-docker-embed-images` | 递增 version 并构建所有带 `Dockerfile` 的 embed 模板 |
+| `make build-picoclaw-manager-image` | 递增 manager version 并仅构建 manager 镜像 |
+| `make build-picoclaw-worker-image` | 递增 worker version 并仅构建 worker 镜像 |
+| `make build-docker-embed-runtime-embed` | `build-docker-embed-images` 的别名 |
 
-兼容别名包括 `build-picoclaw-runtime-embed`、`stage-picoclaw-embed-dist` 等。
+兼容别名包括 `build-picoclaw-runtime-embed`、`sync-picoclaw-embed-image-refs`、`bump-picoclaw-embed-version` 等。
 
 ### 常用变量
 
 ```bash
-#  registry 与 tag（默认值）
+# registry 与基础镜像（默认值）
 ACR_REGISTRY=opencsg-registry.cn-beijing.cr.aliyuncs.com
-DOCKER_EMBED_IMAGE_TAG=dev
 PICOCLAW_BASE_IMAGE=opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/picoclaw:2026.6.8
 
-# 示例：自定义 tag 构建 worker 镜像
-make build-picoclaw-worker-image DOCKER_EMBED_IMAGE_TAG=local
+# 示例：PR 前本地镜像测试（会递增 version 并更新 image.ref，如 0.1.3 -> 0.1.4）
+make build-all
 ```
 
 产物镜像命名：
 
 ```text
-${ACR_REGISTRY}/opencsghq/picoclaw-manager:${DOCKER_EMBED_IMAGE_TAG}
-${ACR_REGISTRY}/opencsghq/picoclaw-worker:${DOCKER_EMBED_IMAGE_TAG}
+${ACR_REGISTRY}/opencsghq/picoclaw-manager:<agent.toml version>
+${ACR_REGISTRY}/opencsghq/picoclaw-worker:<agent.toml version>
 ```
 
+镜像构建成功后，对应的 `agent.toml` 会原地更新（`version` 与 `image.ref`）。
+
 构建上下文为仓库根目录；Dockerfile 需要 `bin/csgclaw-cli`（linux），由 `stage-docker-embed-cli` 生成。
 
 ### BoxLite 与本地 Docker 镜像
@@ -146,9 +150,9 @@ ${ACR_REGISTRY}/opencsghq/picoclaw-worker:${DOCKER_EMBED_IMAGE_TAG}
 
 | 目标 | 说明 |
 |------|------|
-| `make test` | 先 `stage-docker-embed-dist`，再 `go test ./...` |
+| `make test` | 先 `ensure-docker-embed-manifests`，再 `go test ./...`（不修改已提交的 version/ref） |
 | `make fmt` | 格式化 `cli/`、`cmd/`、`internal/`、`web/` 下的 Go 源码 |
-| `make clean` | 删除 `bin/`、`dist/`、`.gocache/` 及 embed 生成的 `dist/` 内容 |
+| `make clean` | 删除 `bin/`、`dist/`、`.gocache/` |
 
 针对性测试：
 
@@ -167,7 +171,7 @@ go test ./...
 | `make package-all` | 完整构建并打包 `csgclaw` 与 `csgclaw-cli` |
 | `make release` | 跨平台 release bundle（darwin/linux，arm64/amd64） |
 
-CI 发布流程见 `.github/workflows/release.yml` 及 GitLab 中的 embed dist / 镜像 job。
+CI 发布流程见 `.github/workflows/release.yml`（tag）与 GitLab CI（tag 打 release 包；**main 分支**按已提交的 `version` 构建并 push picoclaw 镜像，不修改 `agent.toml`）。Tag release 直接使用 tag commit 中已提交的 `agent.toml`。
 
 ## 相关文档
 
diff --git a/internal/agent/workspace_test.go b/internal/agent/workspace_test.go
index 51ce1f28..99e985ec 100644
--- a/internal/agent/workspace_test.go
+++ b/internal/agent/workspace_test.go
@@ -23,13 +23,13 @@ func TestRuntimeTemplateFSEmbedsCompleteTemplateUnits(t *testing.T) {
 		},
 		{
 			name:         "picoclaw manager",
-			manifestPath: "embed/picoclaw-manager/dist/agent.toml",
-			workspaceDoc: "embed/picoclaw-manager/dist/workspace/AGENT.md",
+			manifestPath: "embed/picoclaw-manager/agent.toml",
+			workspaceDoc: "embed/picoclaw-manager/workspace/AGENT.md",
 		},
 		{
 			name:         "picoclaw worker",
-			manifestPath: "embed/picoclaw-worker/dist/agent.toml",
-			workspaceDoc: "embed/picoclaw-worker/dist/workspace/AGENT.md",
+			manifestPath: "embed/picoclaw-worker/agent.toml",
+			workspaceDoc: "embed/picoclaw-worker/workspace/AGENT.md",
 		},
 		{
 			name:         "openclaw worker",
diff --git a/internal/hub/template_manifest.go b/internal/hub/template_manifest.go
index 19a66fb4..24fcf43a 100644
--- a/internal/hub/template_manifest.go
+++ b/internal/hub/template_manifest.go
@@ -15,6 +15,7 @@ type templateManifest struct {
 	Description string               `toml:"description,omitempty"`
 	Role        string               `toml:"role"`
 	RuntimeKind string               `toml:"runtime_kind"`
+	Version     string               `toml:"version,omitempty"`
 	Image       templateImageSection `toml:"image"`
 	UpdatedAt   string               `toml:"updated_at,omitempty"`
 }
diff --git a/internal/templates/embed.go b/internal/templates/embed.go
index 1bff28b6..af15ca4a 100644
--- a/internal/templates/embed.go
+++ b/internal/templates/embed.go
@@ -6,12 +6,11 @@ const (
 	Root                = "embed"
 	ManifestFileName    = "agent.toml"
 	WorkspaceDirName    = "workspace"
-	PicoClawDistDirName = "dist"
-	PicoClawManagerRoot = Root + "/picoclaw-manager/" + PicoClawDistDirName
-	PicoClawWorkerRoot  = Root + "/picoclaw-worker/" + PicoClawDistDirName
+	PicoClawManagerRoot = Root + "/picoclaw-manager"
+	PicoClawWorkerRoot  = Root + "/picoclaw-worker"
 	OpenClawManagerRoot = Root + "/openclaw-manager"
 	OpenClawWorkerRoot  = Root + "/openclaw-worker"
 )
 
-//go:embed embed/picoclaw-manager/dist embed/picoclaw-worker/dist embed/openclaw-manager embed/openclaw-worker
+//go:embed embed/picoclaw-manager embed/picoclaw-worker embed/openclaw-manager embed/openclaw-worker
 var runtimeTemplateFS embed.FS
diff --git a/internal/templates/embed/picoclaw-manager/agent.toml b/internal/templates/embed/picoclaw-manager/agent.toml
index f5c6e41e..bd56c400 100644
--- a/internal/templates/embed/picoclaw-manager/agent.toml
+++ b/internal/templates/embed/picoclaw-manager/agent.toml
@@ -3,6 +3,7 @@ description = "Builtin PicoClaw manager template"
 role = "manager"
 runtime_kind = "picoclaw_sandbox"
 updated_at = "2026-05-27T00:00:00Z"
+version = "0.1.0"
 
 [image]
-ref = ""
\ No newline at end of file
+ref = "opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/picoclaw-manager:0.1.0"
diff --git a/internal/templates/embed/picoclaw-worker/agent.toml b/internal/templates/embed/picoclaw-worker/agent.toml
index 28035f95..04b54d3a 100644
--- a/internal/templates/embed/picoclaw-worker/agent.toml
+++ b/internal/templates/embed/picoclaw-worker/agent.toml
@@ -3,6 +3,7 @@ description = "Builtin PicoClaw worker template"
 role = "worker"
 runtime_kind = "picoclaw_sandbox"
 updated_at = "2026-05-27T00:00:00Z"
+version = "0.1.0"
 
 [image]
-ref = ""
\ No newline at end of file
+ref = "opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/picoclaw-worker:0.1.0"
diff --git a/scripts/build-docker-embed-images.sh b/scripts/build-docker-embed-images.sh
index a83aab17..78823eb9 100755
--- a/scripts/build-docker-embed-images.sh
+++ b/scripts/build-docker-embed-images.sh
@@ -1,17 +1,41 @@
 #!/usr/bin/env bash
 # Build container images for embed templates that include a Dockerfile.
+# Image tag defaults to agent.toml version (after bump-docker-embed-version.sh).
 set -euo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+COMMON="${ROOT}/scripts/docker-embed-agent-toml-common.sh"
 LIST_SCRIPT="${ROOT}/scripts/list-docker-embed-templates.sh"
 
+# shellcheck source=scripts/docker-embed-agent-toml-common.sh
+. "${COMMON}"
+
 : "${ACR_REGISTRY:?ACR_REGISTRY must be set}"
 : "${PICOCLAW_BASE_IMAGE:?PICOCLAW_BASE_IMAGE must be set}"
-: "${DOCKER_EMBED_IMAGE_TAG:?DOCKER_EMBED_IMAGE_TAG must be set}"
+
+image_tag_for_template() {
+  local name="$1"
+  local manifest version
+
+  manifest="$(docker_embed_manifest_path "${name}")"
+  if [ ! -f "${manifest}" ]; then
+    echo "missing manifest: ${manifest}" >&2
+    exit 1
+  fi
+  version="$(read_agent_toml_version "${manifest}")"
+  if [ -z "${version}" ]; then
+    echo "missing version in ${manifest}; run scripts/bump-docker-embed-version.sh first" >&2
+    exit 1
+  fi
+  printf '%s' "${version}"
+}
 
 build_one() {
   local name="$1"
-  local image="${ACR_REGISTRY}/opencsghq/${name}:${DOCKER_EMBED_IMAGE_TAG}"
+  local tag image
+
+  tag="$(image_tag_for_template "${name}")"
+  image="${ACR_REGISTRY}/opencsghq/${name}:${tag}"
   echo "docker build ${name} -> ${image}"
   docker build -f "${ROOT}/internal/templates/embed/${name}/Dockerfile" \
     --build-arg PICOCLAW_IMAGE="${PICOCLAW_BASE_IMAGE}" \
diff --git a/scripts/bump-docker-embed-version.sh b/scripts/bump-docker-embed-version.sh
new file mode 100755
index 00000000..91aef21d
--- /dev/null
+++ b/scripts/bump-docker-embed-version.sh
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Bump agent.toml version (last segment) and sync [image].ref for docker embed templates.
+#
+# Usage:
+#   ./scripts/bump-docker-embed-version.sh                    # all docker templates
+#   ./scripts/bump-docker-embed-version.sh picoclaw-manager   # one template
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+COMMON="${ROOT}/scripts/docker-embed-agent-toml-common.sh"
+LIST_SCRIPT="${ROOT}/scripts/list-docker-embed-templates.sh"
+
+# shellcheck source=scripts/docker-embed-agent-toml-common.sh
+. "${COMMON}"
+
+if [ "$#" -eq 0 ]; then
+  chmod +x "${LIST_SCRIPT}"
+  templates=()
+  while IFS= read -r name; do
+    [ -n "${name}" ] && templates+=("${name}")
+  done < <("${LIST_SCRIPT}")
+  if [ "${#templates[@]}" -eq 0 ]; then
+    exit 1
+  fi
+  set -- "${templates[@]}"
+fi
+
+for name in "$@"; do
+  bump_agent_toml_version_and_ref "${name}"
+done
diff --git a/scripts/check-docker-embed-manifests.sh b/scripts/check-docker-embed-manifests.sh
new file mode 100755
index 00000000..05edd5cd
--- /dev/null
+++ b/scripts/check-docker-embed-manifests.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+# Exit 0 when all docker embed agent.toml files are current; 1 when sync is needed.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+COMMON="${ROOT}/scripts/docker-embed-agent-toml-common.sh"
+LIST_SCRIPT="${ROOT}/scripts/list-docker-embed-templates.sh"
+
+# shellcheck source=scripts/docker-embed-agent-toml-common.sh
+. "${COMMON}"
+
+chmod +x "${LIST_SCRIPT}"
+while IFS= read -r name; do
+  [ -z "${name}" ] && continue
+  if ! docker_embed_manifest_is_current "${name}"; then
+    exit 1
+  fi
+done < <("${LIST_SCRIPT}")
+
+exit 0
diff --git a/scripts/docker-embed-agent-toml-common.sh b/scripts/docker-embed-agent-toml-common.sh
new file mode 100755
index 00000000..79dafe0f
--- /dev/null
+++ b/scripts/docker-embed-agent-toml-common.sh
@@ -0,0 +1,313 @@
+#!/usr/bin/env bash
+# Shared helpers for docker embed template agent.toml (version + image.ref).
+set -euo pipefail
+
+docker_embed_root() {
+  if [ -z "${DOCKER_EMBED_ROOT:-}" ]; then
+    DOCKER_EMBED_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+  fi
+  printf '%s' "${DOCKER_EMBED_ROOT}"
+}
+
+docker_embed_manifest_path() {
+  local template="$1"
+  printf '%s/internal/templates/embed/%s/agent.toml' "$(docker_embed_root)" "${template}"
+}
+
+toml_escape_basic_string() {
+  local value="$1"
+  value="${value//\\/\\\\}"
+  value="${value//\"/\\\"}"
+  printf '%s' "$value"
+}
+
+validate_image_ref() {
+  local ref="$1"
+  local stripped
+
+  stripped="${ref//$'\n'/}"
+  if [ "${#stripped}" -ne "${#ref}" ]; then
+    echo "image ref must not contain control characters" >&2
+    exit 1
+  fi
+  stripped="${ref//$'\r'/}"
+  if [ "${#stripped}" -ne "${#ref}" ]; then
+    echo "image ref must not contain control characters" >&2
+    exit 1
+  fi
+}
+
+read_agent_toml_version() {
+  local manifest="$1"
+  awk -F= '
+    /^version[[:space:]]*=[[:space:]]*/ {
+      value = $2
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", value)
+      gsub(/^"/, "", value)
+      gsub(/"$/, "", value)
+      print value
+      exit
+    }
+  ' "${manifest}"
+}
+
+read_agent_toml_image_ref() {
+  local manifest="$1"
+  awk '
+    /^ref[[:space:]]*=[[:space:]]*/ {
+      value = $0
+      sub(/^[^=]*=[[:space:]]*/, "", value)
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", value)
+      gsub(/^"/, "", value)
+      gsub(/"$/, "", value)
+      print value
+      exit
+    }
+  ' "${manifest}"
+}
+
+image_ref_tag() {
+  local ref="$1"
+  printf '%s' "${ref##*:}"
+}
+
+# Exit 0 when manifest version and image.ref tag are in sync; 1 when sync is needed.
+docker_embed_manifest_is_current() {
+  local template="$1"
+  local manifest version ref ref_tag
+
+  manifest="$(docker_embed_manifest_path "${template}")"
+  if [ ! -f "${manifest}" ]; then
+    return 1
+  fi
+
+  ref="$(read_agent_toml_image_ref "${manifest}")"
+  if [ -z "${ref}" ]; then
+    return 1
+  fi
+
+  version="$(read_agent_toml_version "${manifest}")"
+  if [ -z "${version}" ]; then
+    return 1
+  fi
+
+  ref_tag="$(image_ref_tag "${ref}")"
+  if [ "${ref_tag}" != "${version}" ]; then
+    return 1
+  fi
+
+  return 0
+}
+
+increment_version_last_segment() {
+  local version="$1"
+  if [[ ! "${version}" =~ ^([0-9]+(\.[0-9]+)*)\.([0-9]+)$ ]]; then
+    echo "invalid version format: ${version} (expected e.g. 0.1.0)" >&2
+    return 1
+  fi
+  local prefix="${BASH_REMATCH[1]}"
+  local last="${BASH_REMATCH[3]}"
+  printf '%s.%s' "${prefix}" "$((last + 1))"
+}
+
+embed_image_ref_env_key() {
+  local template="$1"
+  local key="EMBED_IMAGE_REF_${template}"
+  key="${key//-/_}"
+  printf '%s' "${key}"
+}
+
+legacy_image_ref_for_template() {
+  local template="$1"
+  case "${template}" in
+    picoclaw-manager)
+      if [ -n "${PICOCLAW_MANAGER_IMAGE_REF+x}" ]; then
+        printf '%s' "${PICOCLAW_MANAGER_IMAGE_REF}"
+        return 0
+      fi
+      ;;
+    picoclaw-worker)
+      if [ -n "${PICOCLAW_WORKER_IMAGE_REF+x}" ]; then
+        printf '%s' "${PICOCLAW_WORKER_IMAGE_REF}"
+        return 0
+      fi
+      ;;
+  esac
+  return 1
+}
+
+image_ref_for_template() {
+  local template="$1"
+  local tag="$2"
+  local key ref
+
+  if ref="$(legacy_image_ref_for_template "${template}")"; then
+    printf '%s' "${ref}"
+    return 0
+  fi
+
+  key="$(embed_image_ref_env_key "${template}")"
+  if [ -n "${!key+x}" ]; then
+    printf '%s' "${!key}"
+    return 0
+  fi
+
+  if [ -n "${ACR_REGISTRY:-}" ]; then
+    printf '%s' "${ACR_REGISTRY}/opencsghq/${template}:${tag}"
+    return 0
+  fi
+
+  return 1
+}
+
+patch_agent_toml_ref() {
+  local template="$1"
+  local image_ref="$2"
+  local manifest
+  local escaped_ref
+
+  manifest="$(docker_embed_manifest_path "${template}")"
+  if [ -z "${image_ref}" ]; then
+    return 0
+  fi
+  validate_image_ref "${image_ref}"
+  if [ ! -f "${manifest}" ]; then
+    echo "missing manifest: ${manifest}" >&2
+    exit 1
+  fi
+
+  escaped_ref="$(toml_escape_basic_string "${image_ref}")"
+  export PICOCLAW_IMAGE_REF="${escaped_ref}"
+
+  awk '
+    BEGIN {
+      ref = ENVIRON["PICOCLAW_IMAGE_REF"]
+      in_image = 0
+      ref_done = 0
+      has_image_section = 0
+    }
+    /^\[image\]/ {
+      has_image_section = 1
+      print
+      in_image = 1
+      next
+    }
+    in_image && /^ref = / {
+      print "ref = \"" ref "\""
+      ref_done = 1
+      in_image = 0
+      next
+    }
+    /^\[/ {
+      if (in_image && !ref_done) {
+        print "ref = \"" ref "\""
+        ref_done = 1
+      }
+      in_image = 0
+    }
+    { print }
+    END {
+      if (has_image_section && in_image && !ref_done) {
+        print "ref = \"" ref "\""
+        ref_done = 1
+      }
+      if (!has_image_section) {
+        print ""
+        print "[image]"
+        print "ref = \"" ref "\""
+      }
+    }
+  ' "${manifest}" > "${manifest}.tmp"
+
+  unset PICOCLAW_IMAGE_REF
+  mv "${manifest}.tmp" "${manifest}"
+}
+
+patch_agent_toml_version() {
+  local template="$1"
+  local version="$2"
+  local manifest
+  local escaped_version
+
+  manifest="$(docker_embed_manifest_path "${template}")"
+  if [ ! -f "${manifest}" ]; then
+    echo "missing manifest: ${manifest}" >&2
+    exit 1
+  fi
+
+  escaped_version="$(toml_escape_basic_string "${version}")"
+  export PICOCLAW_TEMPLATE_VERSION="${escaped_version}"
+
+  awk '
+    BEGIN {
+      version = ENVIRON["PICOCLAW_TEMPLATE_VERSION"]
+      version_done = 0
+    }
+    /^version[[:space:]]*=[[:space:]]*/ {
+      print "version = \"" version "\""
+      version_done = 1
+      next
+    }
+    { print }
+    END {
+      if (!version_done) {
+        print "version = \"" version "\""
+      }
+    }
+  ' "${manifest}" > "${manifest}.tmp"
+
+  unset PICOCLAW_TEMPLATE_VERSION
+  mv "${manifest}.tmp" "${manifest}"
+}
+
+bump_agent_toml_version_and_ref() {
+  local template="$1"
+  local manifest current next ref
+
+  manifest="$(docker_embed_manifest_path "${template}")"
+  if [ ! -f "${manifest}" ]; then
+    echo "missing manifest: ${manifest}" >&2
+    exit 1
+  fi
+
+  current="$(read_agent_toml_version "${manifest}")"
+  if [ -z "${current}" ]; then
+    next="0.1.0"
+  else
+    next="$(increment_version_last_segment "${current}")"
+  fi
+
+  if ! ref="$(image_ref_for_template "${template}" "${next}")"; then
+    echo "no image ref for ${template}; set ACR_REGISTRY or EMBED_IMAGE_REF_*" >&2
+    exit 1
+  fi
+
+  patch_agent_toml_version "${template}" "${next}"
+  patch_agent_toml_ref "${template}" "${ref}"
+  echo "bumped ${manifest} -> version=${next} ref=${ref}"
+}
+
+sync_agent_toml_version_and_ref() {
+  local template="$1"
+  local manifest version ref
+
+  manifest="$(docker_embed_manifest_path "${template}")"
+  if [ ! -f "${manifest}" ]; then
+    echo "missing manifest: ${manifest}" >&2
+    exit 1
+  fi
+
+  version="$(read_agent_toml_version "${manifest}")"
+  if [ -z "${version}" ]; then
+    version="0.1.0"
+    patch_agent_toml_version "${template}" "${version}"
+  fi
+
+  if ! ref="$(image_ref_for_template "${template}" "${version}")"; then
+    echo "no image ref for ${template}; set ACR_REGISTRY or EMBED_IMAGE_REF_*" >&2
+    exit 1
+  fi
+
+  patch_agent_toml_ref "${template}" "${ref}"
+  echo "synced ${manifest} -> version=${version} ref=${ref}"
+}
diff --git a/scripts/patch-docker-embed-image-refs.sh b/scripts/patch-docker-embed-image-refs.sh
deleted file mode 100755
index 5151944a..00000000
--- a/scripts/patch-docker-embed-image-refs.sh
+++ /dev/null
@@ -1,175 +0,0 @@
-#!/usr/bin/env bash
-# Write [image].ref into staged dist/agent.toml for docker embed templates.
-# Discovers templates via Dockerfile; default ref:
-#   ${ACR_REGISTRY}/opencsghq/<template-name>:${CI_COMMIT_TAG|VERSION|dev}
-#
-# Per-template override (optional):
-#   EMBED_IMAGE_REF_picoclaw_manager=registry.example/custom:tag
-#   (template dir picoclaw-manager -> EMBED_IMAGE_REF_picoclaw_manager)
-#
-# Legacy overrides (still supported):
-#   PICOCLAW_MANAGER_IMAGE_REF / PICOCLAW_WORKER_IMAGE_REF
-set -euo pipefail
-
-ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-LIST_SCRIPT="${ROOT}/scripts/list-docker-embed-templates.sh"
-
-# Escape a value for a TOML basic string (double-quoted).
-toml_escape_basic_string() {
-  local value="$1"
-  value="${value//\\/\\\\}"
-  value="${value//\"/\\\"}"
-  printf '%s' "$value"
-}
-
-validate_image_ref() {
-  local ref="$1"
-  local stripped
-
-  stripped="${ref//$'\n'/}"
-  if [ "${#stripped}" -ne "${#ref}" ]; then
-    echo "image ref must not contain control characters" >&2
-    exit 1
-  fi
-  stripped="${ref//$'\r'/}"
-  if [ "${#stripped}" -ne "${#ref}" ]; then
-    echo "image ref must not contain control characters" >&2
-    exit 1
-  fi
-}
-
-patch_agent_toml() {
-  local template="$1"
-  local image_ref="$2"
-  local manifest="${ROOT}/internal/templates/embed/${template}/dist/agent.toml"
-  local escaped_ref
-
-  if [ -z "${image_ref}" ]; then
-    return 0
-  fi
-  validate_image_ref "${image_ref}"
-  if [ ! -f "${manifest}" ]; then
-    echo "missing manifest: ${manifest} (run scripts/prepare-docker-embed-dist.sh first)" >&2
-    exit 1
-  fi
-
-  escaped_ref="$(toml_escape_basic_string "${image_ref}")"
-  export PICOCLAW_IMAGE_REF="${escaped_ref}"
-
-  awk '
-    BEGIN {
-      ref = ENVIRON["PICOCLAW_IMAGE_REF"]
-      in_image = 0
-      ref_done = 0
-      has_image_section = 0
-    }
-    /^\[image\]/ {
-      has_image_section = 1
-      print
-      in_image = 1
-      next
-    }
-    in_image && /^ref = / {
-      print "ref = \"" ref "\""
-      ref_done = 1
-      in_image = 0
-      next
-    }
-    /^\[/ {
-      if (in_image && !ref_done) {
-        print "ref = \"" ref "\""
-        ref_done = 1
-      }
-      in_image = 0
-    }
-    { print }
-    END {
-      if (has_image_section && in_image && !ref_done) {
-        print "ref = \"" ref "\""
-        ref_done = 1
-      }
-      if (!has_image_section) {
-        print ""
-        print "[image]"
-        print "ref = \"" ref "\""
-      }
-    }
-  ' "${manifest}" > "${manifest}.tmp"
-
-  unset PICOCLAW_IMAGE_REF
-  mv "${manifest}.tmp" "${manifest}"
-  echo "patched ${manifest} -> ${image_ref}"
-}
-
-embed_image_ref_env_key() {
-  local template="$1"
-  local key="EMBED_IMAGE_REF_${template}"
-  key="${key//-/_}"
-  printf '%s' "${key}"
-}
-
-legacy_image_ref_for_template() {
-  local template="$1"
-  case "${template}" in
-    picoclaw-manager)
-      if [ -n "${PICOCLAW_MANAGER_IMAGE_REF+x}" ]; then
-        printf '%s' "${PICOCLAW_MANAGER_IMAGE_REF}"
-        return 0
-      fi
-      ;;
-    picoclaw-worker)
-      if [ -n "${PICOCLAW_WORKER_IMAGE_REF+x}" ]; then
-        printf '%s' "${PICOCLAW_WORKER_IMAGE_REF}"
-        return 0
-      fi
-      ;;
-  esac
-  return 1
-}
-
-image_ref_for_template() {
-  local template="$1"
-  local key ref tag
-
-  if ref="$(legacy_image_ref_for_template "${template}")"; then
-    printf '%s' "${ref}"
-    return 0
-  fi
-
-  key="$(embed_image_ref_env_key "${template}")"
-  if [ -n "${!key+x}" ]; then
-    printf '%s' "${!key}"
-    return 0
-  fi
-
-  if [ -n "${ACR_REGISTRY:-}" ]; then
-    tag="${CI_COMMIT_TAG:-${VERSION:-dev}}"
-    printf '%s' "${ACR_REGISTRY}/opencsghq/${template}:${tag}"
-    return 0
-  fi
-
-  return 1
-}
-
-chmod +x "${LIST_SCRIPT}"
-templates=()
-while IFS= read -r name; do
-  [ -n "${name}" ] && templates+=("${name}")
-done < <("${LIST_SCRIPT}")
-
-patched=0
-for template in "${templates[@]}"; do
-  if ! ref="$(image_ref_for_template "${template}")"; then
-    echo "no image ref for ${template}; set ACR_REGISTRY or EMBED_IMAGE_REF_*" >&2
-    exit 1
-  fi
-  if [ -n "${ref}" ]; then
-    patch_agent_toml "${template}" "${ref}"
-    patched=1
-  fi
-done
-
-if [ "${patched}" -eq 0 ]; then
-  echo "no docker embed templates to patch" >&2
-  exit 1
-fi
diff --git a/scripts/patch-picoclaw-embed-image-refs.sh b/scripts/patch-picoclaw-embed-image-refs.sh
deleted file mode 100755
index f601f441..00000000
--- a/scripts/patch-picoclaw-embed-image-refs.sh
+++ /dev/null
@@ -1,2 +0,0 @@
-#!/usr/bin/env bash
-exec "$(cd "$(dirname "$0")" && pwd)/patch-docker-embed-image-refs.sh" "$@"
diff --git a/scripts/prepare-docker-embed-dist.sh b/scripts/prepare-docker-embed-dist.sh
deleted file mode 100755
index 67d42ca8..00000000
--- a/scripts/prepare-docker-embed-dist.sh
+++ /dev/null
@@ -1,47 +0,0 @@
-#!/usr/bin/env bash
-# Stage runtime files into dist/ for embed templates that build container images.
-# Discovers templates via Dockerfile (see scripts/list-docker-embed-templates.sh).
-#
-# Usage:
-#   ./scripts/prepare-docker-embed-dist.sh                    # all docker templates
-#   ./scripts/prepare-docker-embed-dist.sh picoclaw-manager   # one template
-set -euo pipefail
-
-ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-LIST_SCRIPT="${ROOT}/scripts/list-docker-embed-templates.sh"
-
-prepare_template_dist() {
-  local name="$1"
-  local src="${ROOT}/internal/templates/embed/${name}"
-  local dst="${src}/dist"
-
-  if [ ! -f "${src}/Dockerfile" ]; then
-    echo "template ${name} has no Dockerfile; skip prepare" >&2
-    exit 1
-  fi
-  if [ ! -d "${src}" ]; then
-    echo "missing template source: ${src}" >&2
-    exit 1
-  fi
-
-  rm -rf "${dst}"
-  mkdir -p "${dst}"
-  find "${src}" -mindepth 1 -maxdepth 1 ! -name Dockerfile ! -name dist -exec cp -R {} "${dst}/" \;
-  echo "prepared ${dst}"
-}
-
-if [ "$#" -eq 0 ]; then
-  chmod +x "${LIST_SCRIPT}"
-  templates=()
-  while IFS= read -r name; do
-    [ -n "${name}" ] && templates+=("${name}")
-  done < <("${LIST_SCRIPT}")
-  if [ "${#templates[@]}" -eq 0 ]; then
-    exit 1
-  fi
-  set -- "${templates[@]}"
-fi
-
-for name in "$@"; do
-  prepare_template_dist "${name}"
-done
diff --git a/scripts/prepare-picoclaw-embed-dist.sh b/scripts/prepare-picoclaw-embed-dist.sh
deleted file mode 100755
index 50a5ef62..00000000
--- a/scripts/prepare-picoclaw-embed-dist.sh
+++ /dev/null
@@ -1,2 +0,0 @@
-#!/usr/bin/env bash
-exec "$(cd "$(dirname "$0")" && pwd)/prepare-docker-embed-dist.sh" "$@"
diff --git a/scripts/sync-docker-embed-image-refs.sh b/scripts/sync-docker-embed-image-refs.sh
new file mode 100755
index 00000000..f53bd93b
--- /dev/null
+++ b/scripts/sync-docker-embed-image-refs.sh
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+# Sync agent.toml [image].ref from the current version field (no bump, no :dev).
+#
+# Usage:
+#   ./scripts/sync-docker-embed-image-refs.sh                    # all docker templates
+#   ./scripts/sync-docker-embed-image-refs.sh picoclaw-manager   # one template
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+COMMON="${ROOT}/scripts/docker-embed-agent-toml-common.sh"
+LIST_SCRIPT="${ROOT}/scripts/list-docker-embed-templates.sh"
+
+# shellcheck source=scripts/docker-embed-agent-toml-common.sh
+. "${COMMON}"
+
+if [ "$#" -eq 0 ]; then
+  chmod +x "${LIST_SCRIPT}"
+  templates=()
+  while IFS= read -r name; do
+    [ -n "${name}" ] && templates+=("${name}")
+  done < <("${LIST_SCRIPT}")
+  if [ "${#templates[@]}" -eq 0 ]; then
+    exit 1
+  fi
+  set -- "${templates[@]}"
+fi
+
+for name in "$@"; do
+  sync_agent_toml_version_and_ref "${name}"
+done
diff --git a/web/app/package.json b/web/app/package.json
index 4b0f6a0f..b809502c 100644
--- a/web/app/package.json
+++ b/web/app/package.json
@@ -5,12 +5,12 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "pnpm typecheck && vite build",
+    "build": "tsc --noEmit && vite build",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "format": "prettier . --write",
     "format:check": "prettier . --check",
-    "check": "pnpm lint && pnpm format:check && pnpm typecheck && pnpm test",
+    "check": "eslint . && prettier . --check && tsc --noEmit && vitest run",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },

From 9cead00e8bb961b2ef198d7548c9cfdfe48784e1 Mon Sep 17 00:00:00 2001
From: wanghj <hj.wang@opencsg.com>
Date: Tue, 9 Jun 2026 17:38:12 +0800
Subject: [PATCH 2/3] ci(embed): gate picoclaw builds on pushed agent.toml
 range

Compare CI_COMMIT_BEFORE_SHA..HEAD instead of HEAD~1 so multi-commit
pushes still trigger image builds when version bumps land earlier in
the range. Ignore locally generated picoclaw-build.env.
---
 .gitignore                           |  1 +
 .gitlab/ci-picoclaw-version-check.sh | 76 +++++++++++++++++++++++-----
 .gitlab/ci.yml                       |  6 +--
 docs/build.md                        |  2 +-
 docs/build.zh.md                     |  2 +-
 5 files changed, 68 insertions(+), 19 deletions(-)

diff --git a/.gitignore b/.gitignore
index fe1664fb..255389c8 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,7 @@
 bin/
 bin-csghub/
 dist/
+picoclaw-build.env
 *.test
 *.out
 
diff --git a/.gitlab/ci-picoclaw-version-check.sh b/.gitlab/ci-picoclaw-version-check.sh
index 9b23fa83..1fb7d971 100755
--- a/.gitlab/ci-picoclaw-version-check.sh
+++ b/.gitlab/ci-picoclaw-version-check.sh
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
-# Detect embed agent.toml version changes on main for CI build gating.
+# Detect embed agent.toml changes on main for CI build gating.
+# Compares the pushed range (CI_COMMIT_BEFORE_SHA..HEAD), not just HEAD~1.
 # CI never modifies agent.toml — it reads version/image.ref and builds images with that tag.
 # Writes picoclaw-build.env (GitLab dotenv report) for downstream jobs.
 set -euo pipefail
@@ -11,6 +12,7 @@ ENV_FILE="${CI_PROJECT_DIR:-${ROOT}}/picoclaw-build.env"
 MANAGER_TEMPLATE="picoclaw-manager"
 WORKER_TEMPLATE="picoclaw-worker"
 CURRENT_REF="HEAD"
+EMPTY_SHA="0000000000000000000000000000000000000000"
 
 read_agent_toml_field_at_ref() {
   local template="$1"
@@ -48,7 +50,22 @@ image_ref_tag() {
   printf '%s' "${ref##*:}"
 }
 
-find_previous_main_commit() {
+agent_toml_path() {
+  local template="$1"
+  printf 'internal/templates/embed/%s/agent.toml' "${template}"
+}
+
+find_compare_base() {
+  local before_sha="${CI_COMMIT_BEFORE_SHA:-}"
+
+  if [ -n "${before_sha}" ] && [ "${before_sha}" != "${EMPTY_SHA}" ]; then
+    if git cat-file -e "${before_sha}^{commit}" 2>/dev/null; then
+      printf '%s' "${before_sha}"
+      return 0
+    fi
+    echo "CI_COMMIT_BEFORE_SHA ${before_sha} is not reachable; falling back to HEAD~1" >&2
+  fi
+
   if git rev-parse "${CURRENT_REF}~1" >/dev/null 2>&1; then
     git rev-parse "${CURRENT_REF}~1"
     return 0
@@ -56,20 +73,40 @@ find_previous_main_commit() {
   return 1
 }
 
-version_changed() {
+manifest_changed_in_push() {
   local template="$1"
-  local previous_ref="$2"
+  local compare_base="$2"
+  local path
+
+  path="$(agent_toml_path "${template}")"
+  if [ -z "${compare_base}" ]; then
+    return 0
+  fi
+
+  if ! git cat-file -e "${compare_base}^{commit}" 2>/dev/null; then
+    return 0
+  fi
+
+  if git diff --name-only "${compare_base}" "${CURRENT_REF}" -- "${path}" | grep -q .; then
+    return 0
+  fi
+  return 1
+}
+
+version_changed_since_base() {
+  local template="$1"
+  local compare_base="$2"
   local current previous
 
   current="$(read_agent_toml_version_at_ref "${template}" "${CURRENT_REF}")"
-  if [ -z "${previous_ref}" ]; then
+  if [ -z "${compare_base}" ]; then
     if [ -n "${current}" ]; then
       return 0
     fi
     return 1
   fi
 
-  previous="$(read_agent_toml_version_at_ref "${template}" "${previous_ref}")"
+  previous="$(read_agent_toml_version_at_ref "${template}" "${compare_base}")"
   if [ -z "${previous}" ]; then
     return 0
   fi
@@ -80,6 +117,16 @@ version_changed() {
   [ "${current}" != "${previous}" ]
 }
 
+should_build_template() {
+  local template="$1"
+  local compare_base="$2"
+
+  if manifest_changed_in_push "${template}" "${compare_base}"; then
+    return 0
+  fi
+  version_changed_since_base "${template}" "${compare_base}"
+}
+
 validate_version_and_ref() {
   local template="$1"
   local version="$2"
@@ -105,11 +152,11 @@ validate_version_and_ref() {
   fi
 }
 
-previous_ref=""
-if previous_ref="$(find_previous_main_commit)"; then
-  echo "previous main commit: ${previous_ref}"
+compare_base=""
+if compare_base="$(find_compare_base)"; then
+  echo "compare base: ${compare_base} (range ${compare_base}..${CURRENT_REF})"
 else
-  echo "no previous commit found"
+  echo "no compare base found; treating embed manifests as new"
 fi
 
 manager_version="$(read_agent_toml_version_at_ref "${MANAGER_TEMPLATE}" "${CURRENT_REF}")"
@@ -117,11 +164,11 @@ worker_version="$(read_agent_toml_version_at_ref "${WORKER_TEMPLATE}" "${CURRENT
 
 manager_build=false
 worker_build=false
-if version_changed "${MANAGER_TEMPLATE}" "${previous_ref:-}"; then
+if should_build_template "${MANAGER_TEMPLATE}" "${compare_base:-}"; then
   manager_build=true
   validate_version_and_ref "${MANAGER_TEMPLATE}" "${manager_version}"
 fi
-if version_changed "${WORKER_TEMPLATE}" "${previous_ref:-}"; then
+if should_build_template "${WORKER_TEMPLATE}" "${compare_base:-}"; then
   worker_build=true
   validate_version_and_ref "${WORKER_TEMPLATE}" "${worker_version}"
 fi
@@ -137,8 +184,9 @@ fi
   printf 'PICOCLAW_MANAGER_BUILD=%s\n' "${manager_build}"
   printf 'PICOCLAW_WORKER_BUILD=%s\n' "${worker_build}"
   printf 'PICOCLAW_ANY_BUILD=%s\n' "${any_build}"
-  if [ -n "${previous_ref}" ]; then
-    printf 'PICOCLAW_PREVIOUS_COMMIT=%s\n' "${previous_ref}"
+  if [ -n "${compare_base}" ]; then
+    printf 'PICOCLAW_COMPARE_BASE=%s\n' "${compare_base}"
+    printf 'PICOCLAW_PREVIOUS_COMMIT=%s\n' "${compare_base}"
   fi
 } > "${ENV_FILE}"
 
diff --git a/.gitlab/ci.yml b/.gitlab/ci.yml
index 48de186a..97d0143e 100644
--- a/.gitlab/ci.yml
+++ b/.gitlab/ci.yml
@@ -4,10 +4,10 @@
 #
 # Triggers:
 #   - tag v* — release archives, csgclaw Docker image, SSH upload (uses committed embed agent.toml)
-#   - push / merge to default branch (main) — build/push picoclaw images when agent.toml version changed (uses committed version/ref; no bump)
+#   - push / merge to default branch (main) — build/push picoclaw images when embed agent.toml changed in the pushed range (uses committed version/ref; no bump)
 #
 # Implementation: scripts/release-build-all.sh (per matrix cell); .gitlab/ci-gitlab-release-upload.sh (upload only);
-# .gitlab/ci-picoclaw-version-check.sh (gate builds when agent.toml version changed; never bumps version);
+# .gitlab/ci-picoclaw-version-check.sh (gate builds on CI_COMMIT_BEFORE_SHA..HEAD; never bumps version);
 # .gitlab/ci-picoclaw-image.sh (stage csgclaw-cli from dist/ into picoclaw manager/worker images); .gitlab/bookworm-mirror.sh (apt sources).
 #
 # Required CI/CD variables:
@@ -194,7 +194,7 @@ picoclaw-cli-build:
   script:
     - |
       if [ "${PICOCLAW_ANY_BUILD}" != "true" ]; then
-        echo "No picoclaw embed version changes since previous commit; skipping csgclaw-cli build for embed images"
+        echo "No picoclaw embed agent.toml changes in pushed range; skipping csgclaw-cli build for embed images"
         mkdir -p "${DIST_DIR:-dist}"
         echo "skipped" > "${DIST_DIR:-dist}/picoclaw-embed-cli-build.skipped"
         exit 0
diff --git a/docs/build.md b/docs/build.md
index 2ff07c9d..a60adcce 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -81,7 +81,7 @@ Builtin PicoClaw templates live under `internal/templates/embed/<name>/` and are
 
 **Local (before PR)**: `make build-all` bumps `version`, syncs `image.ref`, rebuilds `csgclaw` (so embed matches image tags), then builds Docker images.
 
-**GitLab CI (main)**: reads committed `version` / `image.ref`, builds and pushes images **without** modifying `agent.toml`; runs only when `version` changed since the previous commit.
+**GitLab CI (main)**: reads committed `version` / `image.ref`, builds and pushes images **without** modifying `agent.toml`; runs when embed `agent.toml` changed in the pushed range (`CI_COMMIT_BEFORE_SHA..HEAD`) or `version` differs from the compare base.
 
 | Target | Description |
 |--------|-------------|
diff --git a/docs/build.zh.md b/docs/build.zh.md
index 9af56ec0..f6c1b6c2 100644
--- a/docs/build.zh.md
+++ b/docs/build.zh.md
@@ -81,7 +81,7 @@ make build-all
 
 **本地（PR 前）**：`make build-all` 会先递增 `version`、同步 `image.ref`，再编译 `csgclaw`（使 embed 与镜像 tag 一致），最后构建 Docker 镜像。
 
-**GitLab CI（main）**：仅读取已提交的 `version` / `image.ref` 构建并 push 镜像，**不会**修改 `agent.toml`；仅当相对上一 commit 的 `version` 发生变化时才触发构建。
+**GitLab CI（main）**：仅读取已提交的 `version` / `image.ref` 构建并 push 镜像，**不会**修改 `agent.toml`；当本次 push 范围内（`CI_COMMIT_BEFORE_SHA..HEAD`）embed `agent.toml` 发生变化或 `version` 相对 compare base 改变时触发构建。
 
 | 目标 | 说明 |
 |------|------|

From 92e10fdef2f436856de6c4f57c479a016d1cbf31 Mon Sep 17 00:00:00 2001
From: wanghj <hj.wang@opencsg.com>
Date: Tue, 9 Jun 2026 18:34:22 +0800
Subject: [PATCH 3/3] build(embed): default picoclaw base image from Dockerfile
 ARG

Use embed Dockerfile ARG PICOCLAW_IMAGE as the single source of truth;
omit docker build-arg unless PICOCLAW_BASE_IMAGE is explicitly set.
Fix empty-array expansion on macOS bash 3.2 and drop stale CI base tag.
---
 .gitlab/ci-picoclaw-image.sh                  | 16 +++++++----
 .gitlab/ci.yml                                |  3 +--
 Makefile                                      | 27 ++++++++++---------
 docs/build.md                                 |  8 +++---
 docs/build.zh.md                              |  8 +++---
 .../embed/picoclaw-manager/Dockerfile         |  1 +
 .../embed/picoclaw-worker/Dockerfile          |  1 +
 scripts/build-docker-embed-images.sh          | 13 ++++++---
 scripts/read-picoclaw-base-image.sh           | 19 +++++++++++++
 9 files changed, 67 insertions(+), 29 deletions(-)
 create mode 100755 scripts/read-picoclaw-base-image.sh

diff --git a/.gitlab/ci-picoclaw-image.sh b/.gitlab/ci-picoclaw-image.sh
index 00357039..043dd971 100755
--- a/.gitlab/ci-picoclaw-image.sh
+++ b/.gitlab/ci-picoclaw-image.sh
@@ -56,11 +56,17 @@ if [ ! -f "${cli_path}" ]; then
   exit 1
 fi
 
-export PICOCLAW_BASE_TAG="${PICOCLAW_BASE_TAG:-2026.5.27}"
-
-/kaniko/executor \
+set -- /kaniko/executor \
   --context "${CI_PROJECT_DIR}" \
   --dockerfile "${CI_PROJECT_DIR}/${dockerfile}" \
   --custom-platform "linux/${goarch}" \
-  --destination "${ACR_REGISTRY}/opencsghq/${image_name}:${PICOCLAW_IMAGE_VERSION}-${goarch}" \
-  --build-arg PICOCLAW_IMAGE="${ACR_REGISTRY}/opencsghq/picoclaw:${PICOCLAW_BASE_TAG}"
+  --destination "${ACR_REGISTRY}/opencsghq/${image_name}:${PICOCLAW_IMAGE_VERSION}-${goarch}"
+
+if [ -n "${PICOCLAW_BASE_IMAGE:-}" ]; then
+  set -- "$@" --build-arg "PICOCLAW_IMAGE=${PICOCLAW_BASE_IMAGE}"
+  echo "using PICOCLAW_IMAGE override: ${PICOCLAW_BASE_IMAGE}"
+else
+  echo "using PICOCLAW_IMAGE from Dockerfile default"
+fi
+
+exec "$@"
diff --git a/.gitlab/ci.yml b/.gitlab/ci.yml
index 97d0143e..fd0cdf3b 100644
--- a/.gitlab/ci.yml
+++ b/.gitlab/ci.yml
@@ -25,7 +25,7 @@
 # Optional:
 #   SSH_PORT – default 22
 #   REMOTE_BASE_DIR – default /data/csgclaw (releases under .../releases/<tag>/)
-#   PICOCLAW_BASE_TAG – upstream picoclaw base image tag; default 2026.5.27
+#   PICOCLAW_BASE_IMAGE – optional override for upstream picoclaw base (default: Dockerfile ARG)
 #   BOXLITE_CLI_VERSION – default v0.9.0
 #   BOXLITE_CLI_BASE_URL – boxlite-cli tarballs; default mirrors https://csgclaw.opencsg.com/boxlite-cli/{version}/{filename} (matches fetch-boxlite-cli.sh)
 #   BOXLITE_CURL_INSECURE – default 1 (TLS inspection); set 0 if csgclaw.opencsg.com is trusted as-is
@@ -63,7 +63,6 @@ variables:
   GOPROXY: "https://goproxy.cn,direct"
   DEBIAN_APT_MIRROR_DEB: "http://mirrors.aliyun.com/debian"
   DEBIAN_APT_MIRROR_SEC: "http://mirrors.aliyun.com/debian-security"
-  PICOCLAW_BASE_TAG: "2026.5.27"
   CRANE_VERSION: "v0.20.6"
 
 stages:
diff --git a/Makefile b/Makefile
index 3e21a1b4..1b4849ce 100644
--- a/Makefile
+++ b/Makefile
@@ -25,10 +25,9 @@ TARGET_ARCH ?= $(shell $(GO) env GOARCH)
 CLI_BIN ?= $(BIN_DIR)/csgclaw-cli
 
 ACR_REGISTRY ?= opencsg-registry.cn-beijing.cr.aliyuncs.com
-IMAGE ?= $(ACR_REGISTRY)/opencsghq/picoclaw
-TAG ?= 2026.6.8
+# Upstream picoclaw base image default: embed Dockerfile ARG PICOCLAW_IMAGE.
+# Optional build/CI override: export PICOCLAW_BASE_IMAGE=registry/.../picoclaw:tag
 LOCAL_IMAGE ?= picoclaw:local
-PICOCLAW_BASE_IMAGE ?= $(IMAGE):$(TAG)
 DOCKER_EMBED_DOCKER_GOOS ?= linux
 DOCKER_EMBED_DOCKER_GOARCH ?= $(TARGET_ARCH)
 DOCKER_EMBED_CLI ?= $(BIN_DIR)/csgclaw-cli
@@ -154,30 +153,30 @@ ensure-docker-embed-manifests:
 	fi
 
 build-docker-embed-images: stage-docker-embed-cli bump-docker-embed-version
-	chmod +x scripts/build-docker-embed-images.sh
-	ACR_REGISTRY="$(ACR_REGISTRY)" PICOCLAW_BASE_IMAGE="$(PICOCLAW_BASE_IMAGE)" \
+	chmod +x scripts/build-docker-embed-images.sh scripts/read-picoclaw-base-image.sh
+	ACR_REGISTRY="$(ACR_REGISTRY)" \
 		scripts/build-docker-embed-images.sh
 
 build-docker-embed-images-only: stage-docker-embed-cli
-	chmod +x scripts/build-docker-embed-images.sh
-	ACR_REGISTRY="$(ACR_REGISTRY)" PICOCLAW_BASE_IMAGE="$(PICOCLAW_BASE_IMAGE)" \
+	chmod +x scripts/build-docker-embed-images.sh scripts/read-picoclaw-base-image.sh
+	ACR_REGISTRY="$(ACR_REGISTRY)" \
 		scripts/build-docker-embed-images.sh
 
 build-docker-embed-runtime-embed: build-docker-embed-images
 build-picoclaw-runtime-embed: build-docker-embed-runtime-embed
 
 build-picoclaw-manager-image: stage-docker-embed-cli
-	chmod +x scripts/bump-docker-embed-version.sh scripts/build-docker-embed-images.sh
+	chmod +x scripts/bump-docker-embed-version.sh scripts/build-docker-embed-images.sh scripts/read-picoclaw-base-image.sh
 	ACR_REGISTRY="$(ACR_REGISTRY)" \
 		scripts/bump-docker-embed-version.sh picoclaw-manager
-	ACR_REGISTRY="$(ACR_REGISTRY)" PICOCLAW_BASE_IMAGE="$(PICOCLAW_BASE_IMAGE)" \
+	ACR_REGISTRY="$(ACR_REGISTRY)" \
 		scripts/build-docker-embed-images.sh picoclaw-manager
 
 build-picoclaw-worker-image: stage-docker-embed-cli
-	chmod +x scripts/bump-docker-embed-version.sh scripts/build-docker-embed-images.sh
+	chmod +x scripts/bump-docker-embed-version.sh scripts/build-docker-embed-images.sh scripts/read-picoclaw-base-image.sh
 	ACR_REGISTRY="$(ACR_REGISTRY)" \
 		scripts/bump-docker-embed-version.sh picoclaw-worker
-	ACR_REGISTRY="$(ACR_REGISTRY)" PICOCLAW_BASE_IMAGE="$(PICOCLAW_BASE_IMAGE)" \
+	ACR_REGISTRY="$(ACR_REGISTRY)" \
 		scripts/build-docker-embed-images.sh picoclaw-worker
 
 # Bump embed versions before go:embed so the server binary matches built images.
@@ -209,9 +208,11 @@ clean:
 	rm -rf $(BIN_DIR) $(DIST_DIR) $(GOCACHE)
 
 tag:
-	docker tag $(LOCAL_IMAGE) $(IMAGE):$(TAG)
+	chmod +x scripts/read-picoclaw-base-image.sh
+	docker tag $(LOCAL_IMAGE) $$(scripts/read-picoclaw-base-image.sh)
 
 push:
-	docker push $(IMAGE):$(TAG)
+	chmod +x scripts/read-picoclaw-base-image.sh
+	docker push $$(scripts/read-picoclaw-base-image.sh)
 
 publish: tag push
diff --git a/docs/build.md b/docs/build.md
index a60adcce..e5453b0e 100644
--- a/docs/build.md
+++ b/docs/build.md
@@ -123,11 +123,13 @@ Alias targets `build-picoclaw-runtime-embed`, `sync-picoclaw-embed-image-refs`,
 ### Useful variables
 
 ```bash
-# Registry and base image (defaults shown)
+# Registry (default shown)
 ACR_REGISTRY=opencsg-registry.cn-beijing.cr.aliyuncs.com
-PICOCLAW_BASE_IMAGE=opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/picoclaw:2026.6.8
 
-# Example: local pre-PR image test (bumps version and updates image.ref, e.g. 0.1.3 -> 0.1.4)
+# Upstream picoclaw base image defaults to embed Dockerfile ARG PICOCLAW_IMAGE
+# Optional override: PICOCLAW_BASE_IMAGE=registry.example/opencsghq/picoclaw:tag make build-all
+
+# Example: local pre-PR image test (bumps version and updates image.ref, e.g. 0.1.0 -> 0.1.1)
 make build-all
 ```
 
diff --git a/docs/build.zh.md b/docs/build.zh.md
index f6c1b6c2..3d111900 100644
--- a/docs/build.zh.md
+++ b/docs/build.zh.md
@@ -123,11 +123,13 @@ make sync-docker-embed-image-refs
 ### 常用变量
 
 ```bash
-# registry 与基础镜像（默认值）
+# registry（默认值）
 ACR_REGISTRY=opencsg-registry.cn-beijing.cr.aliyuncs.com
-PICOCLAW_BASE_IMAGE=opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/picoclaw:2026.6.8
 
-# 示例：PR 前本地镜像测试（会递增 version 并更新 image.ref，如 0.1.3 -> 0.1.4）
+# 上游 picoclaw 基础镜像默认见 embed Dockerfile 的 ARG PICOCLAW_IMAGE
+# 可选覆盖：PICOCLAW_BASE_IMAGE=registry.example/opencsghq/picoclaw:tag make build-all
+
+# 示例：PR 前本地镜像测试（会递增 version 并更新 image.ref，如 0.1.0 -> 0.1.1）
 make build-all
 ```
 
diff --git a/internal/templates/embed/picoclaw-manager/Dockerfile b/internal/templates/embed/picoclaw-manager/Dockerfile
index 7999abca..232bbfca 100644
--- a/internal/templates/embed/picoclaw-manager/Dockerfile
+++ b/internal/templates/embed/picoclaw-manager/Dockerfile
@@ -11,6 +11,7 @@
 #     --build-arg PICOCLAW_IMAGE=opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/picoclaw:2026.6.8 \
 #     -t picoclaw-manager:local .
 
+# Default upstream picoclaw base image (single source of truth for local make / CI builds).
 ARG PICOCLAW_IMAGE=opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/picoclaw:2026.6.8
 
 FROM ${PICOCLAW_IMAGE}
diff --git a/internal/templates/embed/picoclaw-worker/Dockerfile b/internal/templates/embed/picoclaw-worker/Dockerfile
index 3631bc9c..da409c6c 100644
--- a/internal/templates/embed/picoclaw-worker/Dockerfile
+++ b/internal/templates/embed/picoclaw-worker/Dockerfile
@@ -11,6 +11,7 @@
 #     --build-arg PICOCLAW_IMAGE=opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/picoclaw:2026.6.8 \
 #     -t picoclaw-worker:local .
 
+# Default upstream picoclaw base image (keep in sync with picoclaw-manager/Dockerfile).
 ARG PICOCLAW_IMAGE=opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/picoclaw:2026.6.8
 
 FROM ${PICOCLAW_IMAGE}
diff --git a/scripts/build-docker-embed-images.sh b/scripts/build-docker-embed-images.sh
index 78823eb9..85e912f8 100755
--- a/scripts/build-docker-embed-images.sh
+++ b/scripts/build-docker-embed-images.sh
@@ -11,7 +11,6 @@ LIST_SCRIPT="${ROOT}/scripts/list-docker-embed-templates.sh"
 . "${COMMON}"
 
 : "${ACR_REGISTRY:?ACR_REGISTRY must be set}"
-: "${PICOCLAW_BASE_IMAGE:?PICOCLAW_BASE_IMAGE must be set}"
 
 image_tag_for_template() {
   local name="$1"
@@ -36,9 +35,17 @@ build_one() {
 
   tag="$(image_tag_for_template "${name}")"
   image="${ACR_REGISTRY}/opencsghq/${name}:${tag}"
-  echo "docker build ${name} -> ${image}"
+  if [ -n "${PICOCLAW_BASE_IMAGE:-}" ]; then
+    echo "docker build ${name} -> ${image} (PICOCLAW_IMAGE override: ${PICOCLAW_BASE_IMAGE})"
+    docker build -f "${ROOT}/internal/templates/embed/${name}/Dockerfile" \
+      --build-arg "PICOCLAW_IMAGE=${PICOCLAW_BASE_IMAGE}" \
+      -t "${image}" \
+      "${ROOT}"
+    return
+  fi
+
+  echo "docker build ${name} -> ${image} (PICOCLAW_IMAGE from Dockerfile default)"
   docker build -f "${ROOT}/internal/templates/embed/${name}/Dockerfile" \
-    --build-arg PICOCLAW_IMAGE="${PICOCLAW_BASE_IMAGE}" \
     -t "${image}" \
     "${ROOT}"
 }
diff --git a/scripts/read-picoclaw-base-image.sh b/scripts/read-picoclaw-base-image.sh
new file mode 100755
index 00000000..de5628db
--- /dev/null
+++ b/scripts/read-picoclaw-base-image.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+# Print upstream picoclaw base image ref from embed Dockerfile ARG default.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DOCKERFILE="${ROOT}/internal/templates/embed/picoclaw-manager/Dockerfile"
+
+if [ ! -f "${DOCKERFILE}" ]; then
+  echo "missing Dockerfile: ${DOCKERFILE}" >&2
+  exit 1
+fi
+
+ref="$(grep '^ARG PICOCLAW_IMAGE=' "${DOCKERFILE}" | head -1 | sed 's/^ARG PICOCLAW_IMAGE=//' | tr -d ' \r')"
+if [ -z "${ref}" ]; then
+  echo "missing ARG PICOCLAW_IMAGE in ${DOCKERFILE}" >&2
+  exit 1
+fi
+
+printf '%s' "${ref}"