ci: align Gitea CI/CD + Docker with the notify-bridge template

Adopt the proven notify-bridge pipeline pattern and fix deployment bugs.

Workflows:
- build.yml: split into parallel frontend / backend / build-image jobs.
  Run svelte-check + vitest + `go vet ./...` + `go test ./internal/...`
  (tests were never executed in CI). Use buildx with GHA layer cache and
  pin Go to 1.25. Quote the `if:` skip-guard so it is valid YAML.
- release.yml: gate the release on a passing test job, then build & push
  the image, then create the Gitea release LAST so a failed image build
  can no longer leave an orphan release. Use buildx + registry buildcache,
  a hard registry login (a push failure now fails the release), and
  auto-generate a changelog between tags.

Docker:
- Dockerfile: pin golang to 1.25 (matches go.mod's `go 1.25.0`), add
  BuildKit cache mounts for the module + build caches, an OCI source
  label, VOLUME /app/data, and a HEALTHCHECK on /readyz.
- docker-compose.yml: fix the healthcheck — it targeted POST-only
  /api/auth/login (405 -> always unhealthy); now /readyz. Point the image
  name at the Gitea registry tag with build-from-source as the default.
- .dockerignore: exclude ~95 MB of stray binaries, logs, env, and CI/doc
  files from the build context.

.dockerignore

@@ -1,9 +1,47 @@
+# VCS / tooling
 .git
-node_modules
-web/node_modules
-web/build
-data
-*.md
-plans/
-.claude/
+.gitignore
 .dockerignore
+.gitea/
+.github/
+.claude/
+.code-review-graph/
+.vex.toml
+.facts-sync.json
+.facts-suggestions.md
+
+# Node / frontend build artifacts (frontend stage rebuilds web/build)
+node_modules/
+web/node_modules/
+web/build/
+web/.svelte-kit/
+
+# Runtime / local data
+data/
+.env
+.env.*
+*.log
+
+# Compiled binaries (rebuilt inside the image)
+tinyforge
+tinyforge.exe
+tinyforge-server.exe
+server.exe
+docker-watcher
+docker-watcher.exe
+docker-watcher.exe~
+/cli
+/cli.exe
+
+# Build/orchestration files not needed inside the image
+Dockerfile
+docker-compose.yml
+Makefile
+*.example.yaml
+
+# Docs / planning / design (not needed at runtime)
+*.md
+docs/
+plans/
+design-mockups/
+test-data/

.gitea/workflows/build.yml

@@ -5,34 +5,70 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+  workflow_dispatch:
 
 jobs:
-  build:
+  frontend:
+    # Skip the build on release-bump commits — the tag push runs release.yml.
+    if: "${{ !startsWith(gitea.event.head_commit.message, 'chore: release v') }}"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install frontend dependencies
+        working-directory: web
+        run: npm ci --no-audit
+
+      - name: Svelte check
+        working-directory: web
+        run: npm run check
+
+      - name: Unit tests (vitest)
+        working-directory: web
+        run: npm run test
+
+      - name: Build frontend
+        working-directory: web
+        run: npm run build
+
+  backend:
+    if: "${{ !startsWith(gitea.event.head_commit.message, 'chore: release v') }}"
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
       - uses: actions/setup-go@v5
         with:
-          go-version: '1.24'
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-
-      - name: Install frontend dependencies
-        working-directory: web
-        run: npm ci --no-audit
-
-      - name: Build frontend
-        working-directory: web
-        run: npm run build
+          go-version: '1.25'
+          cache-dependency-path: go.sum
 
       - name: Vet Go code
         run: go vet ./...
 
-      - name: Build Go binary
-        run: CGO_ENABLED=0 go build -ldflags="-s -w" -o tinyforge ./cmd/server
+      - name: Run Go tests
+        run: go test ./internal/... -count=1
 
-      - name: Build Docker image
-        run: docker build -t tinyforge:dev .
+  build-image:
+    if: "${{ !startsWith(gitea.event.head_commit.message, 'chore: release v') }}"
+    needs: [frontend, backend]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build Docker image (no push)
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: false
+          tags: tinyforge:ci-${{ gitea.sha }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.gitea/workflows/release.yml

@@ -10,19 +10,109 @@ env:
   REGISTRY: git.dolgolyov-family.by/alexei.dolgolyov/tiny-forge
 
 jobs:
-  create-release:
+  # ───────────────────────────────────────────────────────────────────────
+  # Gate the release on a passing test suite. A tagged release must never
+  # ship code that fails `go vet` / `go test`.
+  # ───────────────────────────────────────────────────────────────────────
+  test:
     runs-on: ubuntu-latest
-    outputs:
-      release_id: ${{ steps.create.outputs.release_id }}
     steps:
-      - name: Fetch RELEASE_NOTES.md only
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+          cache-dependency-path: go.sum
+
+      - name: Vet Go code
+        run: go vet ./...
+
+      - name: Run Go tests
+        run: go test ./internal/... -count=1
+
+  # ───────────────────────────────────────────────────────────────────────
+  # Build + push the image FIRST. If this fails, no release is created
+  # (create-release depends on it) — so we never leave an orphan release
+  # pointing at a tag with no published image.
+  # ───────────────────────────────────────────────────────────────────────
+  build-docker:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Compute tags
+        id: meta
+        run: |
+          TAG="${{ gitea.ref_name }}"
+          VERSION="${TAG#v}"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          # Detect pre-release (alpha/beta/rc) — these do NOT get :latest.
+          if echo "$TAG" | grep -qE '(alpha|beta|rc)'; then
+            echo "is_pre=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_pre=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Gitea Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.SERVER_HOST }}
+          username: ${{ gitea.actor }}
+          password: ${{ secrets.DEPLOY_TOKEN }}
+
+      - name: Build and push image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: |
+            ${{ env.REGISTRY }}:${{ steps.meta.outputs.tag }}
+            ${{ env.REGISTRY }}:${{ steps.meta.outputs.version }}
+            ${{ env.REGISTRY }}:sha-${{ gitea.sha }}
+            ${{ steps.meta.outputs.is_pre == 'false' && format('{0}:latest', env.REGISTRY) || '' }}
+          cache-from: type=registry,ref=${{ env.REGISTRY }}:buildcache
+          cache-to: type=registry,ref=${{ env.REGISTRY }}:buildcache,mode=max
+
+      - name: Trigger redeploy webhook
+        if: steps.meta.outputs.is_pre == 'false'
+        continue-on-error: true
+        run: |
+          if [ -n "${{ secrets.DOCKER_REDEPLOY_WEBHOOK_URL }}" ]; then
+            echo "Triggering redeploy webhook..."
+            curl -sf -X POST "${{ secrets.DOCKER_REDEPLOY_WEBHOOK_URL }}" \
+              --max-time 30 || echo "::warning::Redeploy webhook failed"
+          else
+            echo "DOCKER_REDEPLOY_WEBHOOK_URL not set — skipping auto-deploy"
+          fi
+
+  # ───────────────────────────────────────────────────────────────────────
+  # Create the Gitea release LAST — body = RELEASE_NOTES.md + auto-changelog.
+  # ───────────────────────────────────────────────────────────────────────
+  create-release:
+    needs: build-docker
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (full history for changelog)
         uses: actions/checkout@v4
         with:
-          sparse-checkout: RELEASE_NOTES.md
-          sparse-checkout-cone-mode: false
+          fetch-depth: 0
+
+      - name: Generate changelog
+        id: changelog
+        run: |
+          PREV_TAG=$(git tag --sort=-v:refname | head -2 | tail -1)
+          if [ -z "$PREV_TAG" ] || [ "$PREV_TAG" = "${{ gitea.ref_name }}" ]; then
+            git log --oneline --no-decorate -n 20 > /tmp/changelog.txt
+          else
+            git log --oneline --no-decorate "${PREV_TAG}..HEAD" > /tmp/changelog.txt
+          fi
 
       - name: Create Gitea release
-        id: create
         env:
           DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}
         run: |
@@ -42,74 +132,49 @@ jobs:
             echo "Found RELEASE_NOTES.md"
           else
             export RELEASE_NOTES=""
-            echo "No RELEASE_NOTES.md found — release will have no body"
+            echo "No RELEASE_NOTES.md found — release body = changelog only"
           fi
 
-          BODY_JSON=$(python3 -c "
+          # Build release body (notes + changelog) via Python to avoid shell
+          # escaping and CLI length limits.
+          export TAG VERSION IS_PRE
+          python3 <<'PY'
           import json, os
-          notes = os.environ.get('RELEASE_NOTES', '')
-          print(json.dumps(notes.strip()))
-          ")
 
-          # Create release via Gitea API
-          RELEASE=$(curl -s -X POST "$BASE_URL/releases" \
+          notes = os.environ.get('RELEASE_NOTES', '')
+          changelog = open('/tmp/changelog.txt').read().strip()
+
+          sections = []
+          if notes.strip():
+              sections.append(notes.strip())
+          if changelog:
+              sections.append('## Changelog\n\n' + changelog)
+
+          payload = {
+              'tag_name': os.environ['TAG'],
+              'name': os.environ['VERSION'],
+              'body': '\n\n'.join(sections),
+              'draft': False,
+              'prerelease': os.environ['IS_PRE'] == 'true',
+          }
+          with open('/tmp/release-payload.json', 'w') as f:
+              json.dump(payload, f)
+          PY
+
+          HTTP=$(curl -s -o /tmp/release-resp.json -w "%{http_code}" \
+            -X POST "$BASE_URL/releases" \
             -H "Authorization: token $DEPLOY_TOKEN" \
             -H "Content-Type: application/json" \
-            -d "{
-              \"tag_name\": \"$TAG\",
-              \"name\": \"$VERSION\",
-              \"body\": $BODY_JSON,
-              \"draft\": false,
-              \"prerelease\": $IS_PRE
-            }")
+            --data-binary @/tmp/release-payload.json)
 
-          # Fallback: if release already exists for this tag, reuse it
-          RELEASE_ID=$(echo "$RELEASE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])" 2>/dev/null)
-          if [ -z "$RELEASE_ID" ]; then
-            echo "::warning::Release already exists for tag $TAG — reusing existing release"
-            RELEASE=$(curl -s "$BASE_URL/releases/tags/$TAG" \
-              -H "Authorization: token $DEPLOY_TOKEN")
-            RELEASE_ID=$(echo "$RELEASE" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
-          fi
-          echo "release_id=$RELEASE_ID" >> "$GITHUB_OUTPUT"
-          echo "Created release $RELEASE_ID for $TAG"
-
-  build-docker:
-    needs: create-release
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Login to Gitea Container Registry
-        id: docker-login
-        continue-on-error: true
-        run: |
-          echo "${{ secrets.DEPLOY_TOKEN }}" | docker login \
-            "$SERVER_HOST" -u "${{ gitea.actor }}" --password-stdin
-
-      - name: Build and tag
-        if: steps.docker-login.outcome == 'success'
-        run: |
-          TAG="${{ gitea.ref_name }}"
-          VERSION="${TAG#v}"
-          docker build -t "$REGISTRY:$TAG" -t "$REGISTRY:$VERSION" .
-          # Tag as 'latest' only for stable releases
-          if ! echo "$TAG" | grep -qE '(alpha|beta|rc)'; then
-            docker tag "$REGISTRY:$TAG" "$REGISTRY:latest"
-          fi
-
-      - name: Push
-        if: steps.docker-login.outcome == 'success'
-        run: docker push "$REGISTRY" --all-tags
-
-      - name: Trigger Portainer redeploy
-        if: steps.docker-login.outcome == 'success'
-        continue-on-error: true
-        run: |
-          if [ -n "${{ secrets.DOCKER_REDEPLOY_WEBHOOK_URL }}" ]; then
-            echo "Triggering Portainer redeploy..."
-            curl -sf -X POST "${{ secrets.DOCKER_REDEPLOY_WEBHOOK_URL }}" \
-              --max-time 30 || echo "::warning::Portainer webhook failed"
+          echo "POST /releases → HTTP $HTTP"
+          if [ "$HTTP" = "201" ]; then
+            RELEASE_ID=$(python3 -c "import json; print(json.load(open('/tmp/release-resp.json'))['id'])")
+            echo "Created release $RELEASE_ID for $TAG"
+          elif [ "$HTTP" = "409" ] || grep -q "already exists" /tmp/release-resp.json; then
+            echo "::warning::Release already exists for tag $TAG — reusing"
           else
-            echo "DOCKER_REDEPLOY_WEBHOOK_URL not set — skipping auto-deploy"
+            echo "::error::Failed to create release for $TAG (HTTP $HTTP)"
+            head -c 2000 /tmp/release-resp.json; echo
+            exit 1
           fi

Dockerfile

@@ -1,3 +1,4 @@
+# syntax=docker/dockerfile:1.7
 # Stage 1: Build frontend
 FROM node:20-alpine AS frontend-builder
 
@@ -9,25 +10,33 @@ COPY web/ ./
 RUN npm run build
 
 # Stage 2: Build Go binary
-FROM golang:1.24-alpine AS backend-builder
+FROM golang:1.25-alpine AS backend-builder
 
 RUN apk add --no-cache git ca-certificates
 
 WORKDIR /build
 COPY go.mod go.sum ./
 ENV GOTOOLCHAIN=auto
-RUN go mod download
+# Cache mounts persist the module + build caches across rebuilds (BuildKit).
+RUN --mount=type=cache,target=/go/pkg/mod \
+    go mod download
 
 COPY . .
 # Copy built frontend into the expected embed location.
 COPY --from=frontend-builder /build/web/build ./web/build
 
-RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /tinyforge ./cmd/server
+RUN --mount=type=cache,target=/go/pkg/mod \
+    --mount=type=cache,target=/root/.cache/go-build \
+    CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /tinyforge ./cmd/server
 
 # Stage 3: Minimal runtime image
 FROM alpine:3.19
 
-RUN apk add --no-cache ca-certificates tzdata
+LABEL org.opencontainers.image.source="https://git.dolgolyov-family.by/alexei.dolgolyov/tiny-forge"
+LABEL org.opencontainers.image.title="Tinyforge"
+LABEL org.opencontainers.image.description="Self-hosted Docker deployment + mini-CI platform"
+
+RUN apk add --no-cache ca-certificates tzdata wget
 
 # Create non-root user.
 RUN addgroup -g 1000 -S app && adduser -u 1000 -S app -G app
@@ -46,4 +55,10 @@ EXPOSE 8080
 ENV DATA_DIR=/app/data
 ENV LISTEN_ADDR=:8080
 
+VOLUME /app/data
+
+# /readyz is the public readiness probe (pings the DB); /livez is liveness.
+HEALTHCHECK --interval=30s --timeout=5s --retries=3 --start-period=10s \
+    CMD wget --no-verbose --tries=1 --spider http://localhost:8080/readyz || exit 1
+
 ENTRYPOINT ["/app/tinyforge"]

docker-compose.yml

@@ -1,7 +1,13 @@
 services:
   tinyforge:
+    # Default: build from source so a fresh clone works out of the box.
     build: .
-    image: tinyforge:latest
+    # Image name doubles as the Gitea registry tag. To DEPLOY the pre-built
+    # image instead of building (e.g. Portainer pulling on a webhook), comment
+    # out `build:` above — compose will then pull this tag. `:latest` is pushed
+    # only for stable (non pre-release) releases, and the registry may require
+    # `docker login git.dolgolyov-family.by` first if the package is private.
+    image: git.dolgolyov-family.by/alexei.dolgolyov/tiny-forge:latest
     container_name: tinyforge
     restart: unless-stopped
     ports:
@@ -31,7 +37,10 @@ services:
     networks:
       - staging-net
     healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/api/auth/login"]
+      # /readyz is the public readiness probe (pings the DB, rate-limited).
+      # The previous target (/api/auth/login) is POST-only, so a GET/spider
+      # request returned 405 and the container was always reported unhealthy.
+      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:8080/readyz"]
       interval: 30s
       timeout: 5s
       retries: 3

internal/deployer/deployer.go

@@ -100,20 +100,34 @@ func (d *Deployer) SetPreDeployBackuper(b PreDeployBackuper) {
 	d.backuper = b
 }
 
-// MaybeBackupBeforeDeploy creates a "pre-deploy" Tinyforge DB snapshot when
-// the setting is enabled. Failures are logged but do not abort the deploy:
-// missing a backup is preferable to refusing to ship a fix. Exposed so
-// Source plugins can opt into the same behaviour.
-func (d *Deployer) MaybeBackupBeforeDeploy(deployID string, settings store.Settings) {
-	if !settings.AutoBackupBeforeDeploy || d.backuper == nil {
+// maybeBackupBeforeDeploy takes a "pre-deploy" Tinyforge DB snapshot before a
+// deploy when the operator enabled auto_backup_before_deploy. It is called on
+// the unified deploy path (DispatchPlugin) so the setting actually fires — its
+// predecessor was orphaned when the legacy executeDeploy pipeline (its only
+// caller) was removed in the workload-first cutover, silently disabling the
+// setting.
+//
+// Fail-open: a nil backuper, a settings-load error, or a backup failure all
+// skip the snapshot without blocking the deploy — missing a backup is
+// preferable to refusing to ship a fix.
+func (d *Deployer) maybeBackupBeforeDeploy(workloadID string) {
+	if d.backuper == nil {
+		return
+	}
+	settings, err := d.store.GetSettings()
+	if err != nil {
+		slog.Warn("pre-deploy backup: load settings", "workload", workloadID, "error", err)
+		return
+	}
+	if !settings.AutoBackupBeforeDeploy {
 		return
 	}
 	backup, err := d.backuper.CreateBackup("pre-deploy")
 	if err != nil {
-		slog.Warn("pre-deploy backup failed", "deploy_id", deployID, "error", err)
+		slog.Warn("pre-deploy backup failed", "workload", workloadID, "error", err)
 		return
 	}
-	slog.Info("pre-deploy backup created", "deploy_id", deployID, "backup_id", backup.ID, "filename", backup.Filename)
+	slog.Info("pre-deploy backup created", "workload", workloadID, "backup_id", backup.ID, "filename", backup.Filename)
 }
 
 // SetDNSProvider sets the DNS provider for managing DNS records during deployments.

internal/deployer/dispatch.go

@@ -9,11 +9,10 @@ import (
 )
 
 // DispatchPlugin routes a DeploymentIntent for w to the matching Source
-// plugin. This is the new unified deploy path; the legacy executeDeploy
-// remains in place until Phase 6 ports image-deploy logic into
-// source/image. While both exist, callers must pick: webhook/registry
-// triggers + image deploys still go through the legacy path, while
-// /api/hooks/generic + the unified webhook ingress go through here.
+// plugin. This is the unified deploy path for every source kind (the legacy
+// executeDeploy pipeline was removed in the workload-first cutover). When the
+// operator enables auto_backup_before_deploy, a pre-deploy Tinyforge DB
+// snapshot is taken here, after the source resolves and before it runs.
 func (d *Deployer) DispatchPlugin(ctx context.Context, w plugin.Workload, intent plugin.DeploymentIntent) error {
 	if err := d.beginDispatch(); err != nil {
 		metrics.DeploysTotal.Inc(w.SourceKind, "rejected_draining")
@@ -29,6 +28,11 @@ func (d *Deployer) DispatchPlugin(ctx context.Context, w plugin.Workload, intent
 		metrics.DeploysTotal.Inc("unknown", "unknown_source")
 		return fmt.Errorf("dispatch %s: %w", w.Name, err)
 	}
+	// Optional operator-enabled pre-deploy DB snapshot. Fail-open: never
+	// blocks shipping a deploy. Runs before any source-internal idempotency
+	// check (e.g. the image source's same-tag short-circuit), so a same-tag
+	// redeploy still snapshots — "backup before every deploy attempt".
+	d.maybeBackupBeforeDeploy(w.ID)
 	err = src.Deploy(ctx, d.PluginDeps(), w, intent)
 	outcome := "success"
 	if err != nil {

internal/deployer/dispatch_test.go

@@ -21,9 +21,9 @@ import (
 type fakeSource struct {
 	kind string
 
-	mu          sync.Mutex
-	deployErr   error
-	teardownErr error
+	mu           sync.Mutex
+	deployErr    error
+	teardownErr  error
 	reconcileErr error
 
 	deployCount    atomic.Int32
@@ -34,8 +34,8 @@ type fakeSource struct {
 	lastDeps   plugin.Deps
 }
 
-func (f *fakeSource) Kind() string                 { return f.kind }
-func (f *fakeSource) SchemaSample() any            { return struct{}{} }
+func (f *fakeSource) Kind() string                   { return f.kind }
+func (f *fakeSource) SchemaSample() any              { return struct{}{} }
 func (f *fakeSource) Validate(json.RawMessage) error { return nil }
 
 func (f *fakeSource) Deploy(_ context.Context, deps plugin.Deps, _ plugin.Workload, intent plugin.DeploymentIntent) error {

internal/deployer/predeploy_backup_test.go

@@ -0,0 +1,107 @@
+package deployer
+
+import (
+	"context"
+	"errors"
+	"sync/atomic"
+	"testing"
+
+	"github.com/alexei/tinyforge/internal/store"
+	"github.com/alexei/tinyforge/internal/workload/plugin"
+)
+
+// fakeBackuper records pre-deploy backup calls so the dispatch wiring can be
+// asserted. err (when set) simulates a backup failure.
+type fakeBackuper struct {
+	count    atomic.Int32
+	lastType atomic.Value // string
+	err      error
+}
+
+func (f *fakeBackuper) CreateBackup(backupType string) (store.Backup, error) {
+	f.count.Add(1)
+	f.lastType.Store(backupType)
+	if f.err != nil {
+		return store.Backup{}, f.err
+	}
+	return store.Backup{ID: "b1", Filename: "tinyforge-pre-deploy.db"}, nil
+}
+
+func setAutoBackup(t *testing.T, d *Deployer, enabled bool) {
+	t.Helper()
+	s, err := d.store.GetSettings()
+	if err != nil {
+		t.Fatalf("get settings: %v", err)
+	}
+	s.AutoBackupBeforeDeploy = enabled
+	if err := d.store.UpdateSettings(s); err != nil {
+		t.Fatalf("update settings: %v", err)
+	}
+}
+
+// Regression: the pre-deploy backup hook was orphaned after the cutover (no
+// caller on DispatchPlugin), making auto_backup_before_deploy a silent no-op.
+func TestDispatchPlugin_PreDeployBackup_FiresWhenEnabled(t *testing.T) {
+	resetFake(t)
+	d := newTestDeployer(t)
+	b := &fakeBackuper{}
+	d.SetPreDeployBackuper(b)
+	setAutoBackup(t, d, true)
+
+	if err := d.DispatchPlugin(context.Background(), sampleWorkload(), plugin.DeploymentIntent{}); err != nil {
+		t.Fatalf("dispatch: %v", err)
+	}
+	if got := b.count.Load(); got != 1 {
+		t.Fatalf("CreateBackup called %d times, want 1", got)
+	}
+	if bt, _ := b.lastType.Load().(string); bt != "pre-deploy" {
+		t.Fatalf("backup type = %q, want pre-deploy", bt)
+	}
+	if got := dispatchTestSource.deployCount.Load(); got != 1 {
+		t.Fatalf("Deploy ran %d times, want 1", got)
+	}
+}
+
+func TestDispatchPlugin_PreDeployBackup_SkippedWhenDisabled(t *testing.T) {
+	resetFake(t)
+	d := newTestDeployer(t)
+	b := &fakeBackuper{}
+	d.SetPreDeployBackuper(b)
+	setAutoBackup(t, d, false)
+
+	if err := d.DispatchPlugin(context.Background(), sampleWorkload(), plugin.DeploymentIntent{}); err != nil {
+		t.Fatalf("dispatch: %v", err)
+	}
+	if got := b.count.Load(); got != 0 {
+		t.Fatalf("CreateBackup called %d times, want 0 (setting off)", got)
+	}
+}
+
+func TestDispatchPlugin_PreDeployBackup_NilBackuperNoPanic(t *testing.T) {
+	resetFake(t)
+	d := newTestDeployer(t)
+	setAutoBackup(t, d, true) // enabled, but no backuper wired
+
+	if err := d.DispatchPlugin(context.Background(), sampleWorkload(), plugin.DeploymentIntent{}); err != nil {
+		t.Fatalf("dispatch must not panic/fail with a nil backuper: %v", err)
+	}
+	if got := dispatchTestSource.deployCount.Load(); got != 1 {
+		t.Fatalf("Deploy ran %d times, want 1", got)
+	}
+}
+
+func TestDispatchPlugin_PreDeployBackup_FailOpen(t *testing.T) {
+	resetFake(t)
+	d := newTestDeployer(t)
+	b := &fakeBackuper{err: errors.New("disk full")}
+	d.SetPreDeployBackuper(b)
+	setAutoBackup(t, d, true)
+
+	// A failed backup is logged but must NOT block the deploy.
+	if err := d.DispatchPlugin(context.Background(), sampleWorkload(), plugin.DeploymentIntent{}); err != nil {
+		t.Fatalf("deploy must succeed when backup fails (fail-open): %v", err)
+	}
+	if got := dispatchTestSource.deployCount.Load(); got != 1 {
+		t.Fatalf("Deploy ran %d times, want 1 (despite backup failure)", got)
+	}
+}

web/src/lib/components/workload/ImageSourceForm.svelte

@@ -219,18 +219,34 @@
 			>{$t('apps.new.imageRefLabel')}<span class="req-star" aria-label={$t('apps.new.fieldRequired')}>*</span></span
 		>
 		<div class="input-with-button">
-			<input
-				id="app-image-ref"
-				type="text"
-				class="input mono"
-				bind:value={form.ref}
-				oninput={onImageRefInput}
-				onblur={onImageRefBlur}
-				placeholder={$t('apps.new.imageRefPlaceholder')}
-				autocomplete="off"
-				spellcheck="false"
-				required
-			/>
+			<div class="input-wrap">
+				<input
+					id="app-image-ref"
+					type="text"
+					class="input mono"
+					bind:value={form.ref}
+					oninput={onImageRefInput}
+					onblur={onImageRefBlur}
+					placeholder={$t('apps.new.imageRefPlaceholder')}
+					autocomplete="off"
+					spellcheck="false"
+					required
+				/>
+				<!--
+					Conflict-lookup affordance lives INSIDE the field as an
+					absolutely-positioned overlay, so a blur → check → clear
+					cycle never reflows the rows below it. (The old inline hint
+					sat in normal flow and flashed in/out, shifting the whole
+					form.) A left fade masks ref text behind it; the aria-live
+					region still announces the lookup to assistive tech.
+				-->
+				{#if enableConflicts && conflictLoading}
+					<span class="conflict-checking" role="status" aria-live="polite">
+						<IconLoader size={12} />
+						<span>{$t('apps.new.imageConflictChecking')}</span>
+					</span>
+				{/if}
+			</div>
 			<button
 				type="button"
 				class="discover-btn"
@@ -265,18 +281,6 @@
 		{:else if inspectStatus === 'error'}
 			<span class="discover-pill discover-pill-bad inline">{$t('apps.new.errors.inspectFailed')}</span>
 		{/if}
-		<!--
-			Conflict-checking indicator. Reserves no layout when idle and is a
-			quiet inline hint (not the full panel) while a lookup is in flight,
-			so a no-conflict blur no longer flashes the warning panel in then
-			out. The panel itself renders only for REAL conflicts below.
-		-->
-		{#if enableConflicts && conflictLoading}
-			<span class="conflict-checking" role="status" aria-live="polite">
-				<IconLoader size={12} />
-				<span>{$t('apps.new.imageConflictChecking')}</span>
-			</span>
-		{/if}
 	</label>
 	{#if enableConflicts && conflicts.length > 0}
 		<div class="conflict-panel" role="status" aria-live="polite">
@@ -551,7 +555,18 @@
 		align-items: stretch;
 		gap: 0.4rem;
 	}
-	.input-with-button > .input {
+	.input-with-button > .input-wrap {
+		flex: 1;
+		min-width: 0;
+	}
+	/* Wrapper exists only to anchor the absolute conflict-checking overlay to
+	   the field's box (inputs can't host positioned children themselves). */
+	.input-wrap {
+		position: relative;
+		display: flex;
+		min-width: 0;
+	}
+	.input-wrap > .input {
 		flex: 1;
 		min-width: 0;
 	}
@@ -649,20 +664,32 @@
 		border-radius: var(--radius-sm);
 		line-height: 1;
 	}
-	/* Quiet inline "checking…" hint shown near the image-ref input while a
-	   conflict lookup is in flight. Deliberately NOT the full panel, so a
-	   no-conflict blur doesn't flash a panel in and out. Self-aligned so it
-	   sits with the inspect status pills without shifting form layout. */
+	/* Quiet "checking…" affordance shown while a conflict lookup is in flight.
+	   Pinned as an absolute overlay inside the image-ref field's right edge so
+	   it sits ENTIRELY out of document flow — toggling it on a blur → check →
+	   clear cycle can no longer reflow the form rows beneath it (the old
+	   in-flow hint flashed in/out and shifted the whole form). The left fade
+	   lets a long ref scroll cleanly under the pill instead of hard-cutting,
+	   and pointer-events:none keeps the field fully clickable underneath. */
 	.conflict-checking {
+		position: absolute;
+		top: 50%;
+		right: 0.5rem;
+		transform: translateY(-50%);
 		display: inline-flex;
 		align-items: center;
 		gap: 0.35rem;
-		align-self: flex-start;
+		padding: 0.28rem 0.55rem 0.28rem 1.6rem;
+		border-radius: var(--radius-md);
+		background: linear-gradient(90deg, transparent, var(--surface-input) 1.1rem);
 		font-family: var(--forge-mono);
 		font-size: 0.62rem;
 		font-weight: 600;
 		letter-spacing: 0.06em;
 		color: var(--text-tertiary);
+		white-space: nowrap;
+		pointer-events: none;
+		animation: cc-fade-in 140ms ease-out;
 	}
 	.conflict-checking :global(svg) {
 		animation: spin 0.9s linear infinite;
@@ -672,6 +699,21 @@
 			transform: rotate(360deg);
 		}
 	}
+	@keyframes cc-fade-in {
+		from {
+			opacity: 0;
+		}
+		to {
+			opacity: 1;
+		}
+	}
+	/* Respect users who opt out of motion: no spin, no fade. */
+	@media (prefers-reduced-motion: reduce) {
+		.conflict-checking,
+		.conflict-checking :global(svg) {
+			animation: none;
+		}
+	}
 	.conflict-heading {
 		margin: 0;
 		font-size: 0.84rem;