@decocms/start 2.28.2 → 2.30.0

package/.agents/skills/deco-to-tanstack-migration/SKILL.md

@@ -315,7 +315,7 @@ See: `references/search.md`
 5. **`tsconfig.json` mirrors `vite.config.ts`** -- only `"~/*": ["./src/*"]` in paths
 6. **Signals don't auto-subscribe in React** -- reading `signal.value` in render creates NO subscription; use `useStore(signal.store)` from `@tanstack/react-store`
 7. **Commerce loaders need request context** -- `resolve.ts` must pass URL/path to PLP/PDP loaders
-8. **`wrangler.jsonc` main must be a custom worker-entry** -- TanStack Start ignores `export default` in `server.ts`
+8. **`wrangler.jsonc` main must be a custom worker-entry** -- TanStack Start ignores `export default` in `server.ts`. The `main` field lives in the **central** `decocms/deco-start/deploy/wrangler-template.jsonc` (D6); site repos do not commit `wrangler.jsonc`.
 9. **Copy components faithfully, never rewrite** -- `cp` the original, then only change mechanical things (class→className, imports). NEVER regenerate or "improve" — AI-rewritten components are the #1 source of visual regressions
 10. **Tailwind v4 logical property hazard** -- mixed `px-*` + `pl-*/pr-*` on the same element breaks the cascade
 11. **oklch CSS variables need triplets, not hex** -- `oklch(var(--x))` must store variables as oklch triplets

package/.agents/skills/deco-to-tanstack-migration/references/vtex-commerce.md

@@ -36,7 +36,11 @@ This lets the core component render while gracefully degrading features that dep
 
 ## 7. VTEX API Auth on Cloudflare Workers
 
-Env vars must be set via `wrangler secret put` or `.dev.vars`, not `.env`.
+Env vars are stored as `SECRET_*` GitHub repo secrets (e.g. `SECRET_VTEX_APP_KEY`)
+and pushed to the worker via the centralized `Sync worker secrets` workflow
+(D6). Locally, use `.dev.vars` (gitignored) for development. Do not run
+`npx wrangler secret put` per-site — the central workflow keeps GitHub and
+Cloudflare in sync.
 
 
 ## 8. Cookie Handling

package/.agents/skills/deco-to-tanstack-migration/references/worker-cloudflare.md

@@ -37,7 +37,7 @@ TanStack Start's Cloudflare adapter **completely ignores** the `export default`
 
 **Diagnosis**: Search the built `dist/server/worker-entry-*.js` bundle for your custom code (e.g., `X-Cache`, `caches.open`, `_cache/purge`). If absent, TanStack stripped it.
 
-**Fix**: Create a **separate** `src/worker-entry.ts` file that wraps TanStack Start's built handler. Point `wrangler.jsonc` to this file instead of `@tanstack/react-start/server-entry`.
+**Fix**: Create a **separate** `src/worker-entry.ts` file that wraps TanStack Start's built handler. Wrangler is told to use this file via `main: "./src/worker-entry.ts"` in the **canonical wrangler template** at `decocms/deco-start/deploy/wrangler-template.jsonc` (D6) — sites do not configure this themselves.
 
 ```typescript
 // src/worker-entry.ts
@@ -57,13 +57,10 @@ export default createDecoWorkerEntry(serverEntry, {
 });
 ```
 
-```jsonc
-// wrangler.jsonc -- MUST point to custom entry, NOT the default
-{
-  "main": "./src/worker-entry.ts",
-  // NOT: "main": "@tanstack/react-start/server-entry"
-}
-```
+The `main` field is set centrally so a future migration of the entry path
+applies to every site at once (single PR to the template). If you ever need to
+override `main` for a single site, add it under `deploy/sites/<repo>.jsonc` —
+never to a per-site `wrangler.jsonc` (sites don't commit one; see D6).
 
 This ensures admin route interception AND edge caching survive the build because they're in the Worker's own fetch handler, outside of TanStack's build pipeline.
 
@@ -136,9 +133,14 @@ Imports like `import Color from "npm:colorjs.io"` use the Deno-specific `npm:` p
 After deploying a new build to Cloudflare Workers, the edge cache may still serve old HTML that references previous JS bundle hashes. This causes module import failures.
 
 **Fix**: After every deploy, purge the cache:
-1. Set a `PURGE_TOKEN` secret: `npx wrangler secret put PURGE_TOKEN`
+1. Set a `PURGE_TOKEN` secret. Add `SECRET_PURGE_TOKEN` to the site repo's
+   GitHub Secrets, then trigger the centralized `Sync worker secrets`
+   workflow (`workflow_dispatch` → `apply`). This pushes it to the Cloudflare
+   worker via `wrangler secret put PURGE_TOKEN`. **Do not** run
+   `npx wrangler secret put` manually per-site — the central workflow keeps
+   GitHub and Cloudflare in sync.
 2. Call the purge endpoint: `POST /_cache/purge` with `Authorization: Bearer <token>` and body `{"paths":["/"]}`
-3. Automate this in CI/CD (see the deploy.yml workflow)
+3. The right place to automate this is the **central** `deco-start/.github/workflows/deploy.yml` (D6) so every site picks it up at once. Do not add site-local deploy.yml steps; site repos hold only ~5-line caller workflows.
 
 
 ## 44. Runtime Module Import Kills Lazy-Loaded Sections
@@ -207,3 +209,98 @@ Or in project `.npmrc` with an env var (for CI):
 ```
 
 **Tradeoff with `github:` syntax**: No semver resolution — `npm update` is meaningless. Pin to a tag for stability: `github:decocms/deco-start#v0.14.2`. Without a tag, you get HEAD of the default branch.
+
+
+## 46. Central Deploy / Wrangler Config (D6)
+
+**Severity**: HIGH — site repos must NOT commit `wrangler.jsonc` or per-site deploy logic. Doing so reintroduces drift.
+
+Per [D6](../../../../.cursor/rules/migration-tooling-policy.mdc), all
+storefronts deploy via reusable workflows shipped from
+`decocms/deco-start/.github/workflows/{deploy,preview,sync-secrets,regen-blocks}.yml@v2`.
+The canonical `wrangler.jsonc` lives at
+`decocms/deco-start/deploy/wrangler-template.jsonc`; per-site overrides live at
+`decocms/deco-start/deploy/sites/<repo-name>.jsonc`. The two are deep-merged at
+deploy time and written to a generated `wrangler.jsonc` in the runner; site
+repos gitignore the file.
+
+### What goes in the site repo
+
+Four ~5-line caller workflow stubs and nothing else:
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: write
+jobs:
+  deploy:
+    uses: decocms/deco-start/.github/workflows/deploy.yml@v2
+    secrets: inherit
+```
+
+(Plus equivalent `preview.yml`, `regen-blocks.yml`, `sync-secrets.yml` —
+see `scripts/migrate/templates/github-workflows.ts` for the canonical text.)
+The migration script generates these for new sites; the same stubs are
+hand-applied to existing sites.
+
+### What goes in `decocms/deco-start/deploy/sites/<repo>.jsonc`
+
+The minimum:
+
+```jsonc
+{
+  "worker_name": "<repo-name>"
+}
+```
+
+Plus optional `routes`, `kv_namespaces`, `analytics_engine_datasets`,
+`version_metadata` for the few sites that need them. Adding a new site is a
+PR to deco-start, not a change to the site repo.
+
+### Local dev
+
+Site repos add three package.json hooks so vite picks up the generated
+`wrangler.jsonc`:
+
+```jsonc
+"scripts": {
+  "gen:wrangler": "deco-wrangler gen",
+  "predev": "deco-wrangler gen",
+  "prebuild": "deco-wrangler gen",
+  "types": "deco-wrangler types",
+  "deploy": "echo 'Production deploys are managed by .github/workflows/deploy.yml on push to main. For an emergency manual deploy run: npx deco-wrangler deploy'; exit 1"
+}
+```
+
+`deco-wrangler` is a `bin` shipped from `@decocms/start` that materializes the
+canonical config from the central registry, then either exits (`gen` mode) or
+execs the real `wrangler` with that config in cwd.
+
+### Trust model
+
+- The central workflow ignores all caller `inputs:` for site identity.
+- Site name is derived from `${{ github.repository }}` (set by GitHub,
+  untamperable by user code) and looked up in `deploy/sites/<repo>.jsonc`.
+- A customer cannot misroute their deploy onto another site's worker
+  because they can't write to `decocms/deco-start` (CODEOWNERS-protected).
+
+### Common mistakes (do not do these)
+
+- **Committing `wrangler.jsonc` to a site repo.** Generated only;
+  always gitignored. If you see it tracked, the site missed migration.
+- **Adding a site-local `deploy.yml` step** (e.g. cache purge after deploy).
+  Add it to `deco-start/.github/workflows/deploy.yml` instead so every site
+  picks it up at once.
+- **Hard-coding `account_id` in a site's wrangler config.** It comes from
+  `CLOUDFLARE_ACCOUNT_ID` (org-level GitHub secret in CI; `wrangler login`
+  locally). Removing it from JSON is the one-way protection against
+  accidentally deploying to the wrong account.
+- **Setting `worker_name` to anything other than the repo name** without
+  a strong reason. The 1:1 binding makes audit (and incident response)
+  trivial. Exceptions today: `casaevideo-storefront` -> `casaevideo-tanstack`
+  and `miess-01-tanstack` -> `miess-tanstack` (both for historical
+  Cloudflare worker names that predate the repo).

package/.agents/skills/deco-to-tanstack-migration/templates/package-json.md

@@ -12,7 +12,11 @@
     "generate:blocks": "tsx node_modules/@decocms/start/scripts/generate-blocks.ts",
     "generate:invoke": "tsx node_modules/@decocms/start/scripts/generate-invoke.ts",
     "generate:schema": "tsx node_modules/@decocms/start/scripts/generate-schema.ts --site storefront",
-    "deploy": "wrangler deploy"
+    "gen:wrangler": "deco-wrangler gen",
+    "predev": "deco-wrangler gen",
+    "prebuild": "deco-wrangler gen",
+    "types": "deco-wrangler types",
+    "deploy": "echo 'Production deploys are managed by .github/workflows/deploy.yml on push to main. See D6.'; exit 1"
   },
   "dependencies": {
     "@decocms/apps": "^0.20.1",

package/.cursor/rules/migration-tooling-policy.mdc

@@ -1,5 +1,5 @@
 ---
-description: Constitutional decisions for the deco-start migration-tooling effort (D1–D5, priorities, process). Always loaded.
+description: Constitutional decisions for the deco-start migration-tooling effort (D1–D6, priorities, process). Always loaded.
 alwaysApply: true
 ---
 
@@ -14,7 +14,7 @@ summary; always defer to the plan when they conflict.
 1. **Design for 100 sites, not 3.** When the surface of an abstraction is
    well-understood, ship it. Don't defer waiting for "more signal" — design
    for the projection. When the surface is *not* understood, *decide*
-   explicitly (write a D-record like D1–D5), don't ship fast.
+   explicitly (write a D-record like D1–D6), don't ship fast.
 2. **Strict over flexible.** No support layers, no soft drift, no
    fork-runtime adapters. Every fork divergence becomes either a PR back to
    canonical or visible local debt.
@@ -76,6 +76,25 @@ Failure modes get documented in skills, not encoded as escape hatches.
 **Agent behavior**: when a migration goes sideways, propose deletion +
 re-run, not in-place repair. Add the failure mode to the skill.
 
+### D6 — Deploy / preview / secrets pipelines: centralize in `deco-start` (signed off 2026-05-07)
+All storefronts deploy via reusable workflows under
+`decocms/deco-start/.github/workflows/{deploy,preview,sync-secrets,regen-blocks}.yml@v2`.
+Per-site overrides live in [`deploy/sites/<repo>.jsonc`](../../deploy/) and
+are deep-merged on top of [`deploy/wrangler-template.jsonc`](../../deploy/wrangler-template.jsonc)
+at deploy time. **Customer repos do not commit `wrangler.jsonc`** — it is
+generated locally by `deco-wrangler gen` (a `bin` shipped from
+`@decocms/start`) and gitignored. The repo→worker binding is the trust
+boundary: the central workflow ignores caller `inputs:` for identity and
+derives the site name from `${{ github.repository }}`. `deploy/**` is
+CODEOWNERS-protected.
+
+**Agent behavior**: when adding or migrating a site, do **not** generate a
+per-site `wrangler.jsonc` or per-site `deploy.yml` / `preview.yml` /
+`sync-secrets.yml` / `regen-blocks.yml`. The site repo gets the four
+~5-line caller stubs only. Per-site config goes in a PR to
+`decocms/deco-start` adding `deploy/sites/<repo>.jsonc`. Do not commit
+`wrangler.jsonc` or any wrangler config to a site repo.
+
 ## Priority order
 
 Work proceeds in this order. Higher priorities don't block on lower ones,
@@ -109,3 +128,4 @@ order — but only if explicitly identified as urgent.
 - When reading a section of the plan or a skill, prefer the plan or skill
   over your memory of past conversations.
 - Do not run `deco-deploy` or any deploy command from agent flows.
+- Do not commit `wrangler.jsonc` to a site repo. See **D6** above.

package/.github/workflows/deploy.yml

@@ -0,0 +1,115 @@
+name: deploy (central)
+
+# Reusable workflow that drives `wrangler deploy` for any storefront repo
+# registered under `deploy/sites/<repo-name>.jsonc`.
+#
+# Site identity (worker name, KV bindings, routes, ...) is derived ONLY from
+# `${{ github.repository }}` and the registry checked in to deco-start. The
+# caller cannot pass an `inputs:` block to override the worker name -- this is
+# the trust boundary that prevents one site's commits from deploying on top of
+# another site's worker.
+#
+# Caller usage (in customer repo, `.github/workflows/deploy.yml`):
+#
+#   on:
+#     push:
+#       branches: [main]
+#   permissions:
+#     contents: write
+#   jobs:
+#     deploy:
+#       uses: decocms/deco-start/.github/workflows/deploy.yml@v2
+#       secrets: inherit
+
+on:
+  workflow_call:
+    secrets:
+      CLOUDFLARE_API_TOKEN:
+        required: true
+      CLOUDFLARE_ACCOUNT_ID:
+        required: true
+
+permissions:
+  contents: write
+
+concurrency:
+  group: deploy-${{ github.repository }}
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout caller repo
+        uses: actions/checkout@v4
+
+      - name: Resolve deco-start ref + site identity
+        id: meta
+        run: |
+          # github.workflow_ref looks like
+          #   decocms/deco-start/.github/workflows/deploy.yml@refs/tags/v1
+          # or
+          #   decocms/deco-start/.github/workflows/deploy.yml@refs/heads/main
+          WF_REF="${{ github.workflow_ref }}"
+          REF="${WF_REF##*@}"
+          REF="${REF#refs/tags/}"
+          REF="${REF#refs/heads/}"
+          echo "deco_start_ref=$REF" >> "$GITHUB_OUTPUT"
+          echo "site_name=${GITHUB_REPOSITORY#*/}" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout deco-start registry at the same ref
+        uses: actions/checkout@v4
+        with:
+          repository: decocms/deco-start
+          ref: ${{ steps.meta.outputs.deco_start_ref }}
+          path: .deco-start
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Generate lockfile if missing
+        if: hashFiles('package-lock.json') == ''
+        run: npm install --package-lock-only
+
+      - name: Restore npm cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          key: npm-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
+          restore-keys: npm-${{ runner.os }}-
+
+      - name: Sync lockfile and install
+        run: |
+          npm install --package-lock-only
+          if ! git diff --quiet package-lock.json 2>/dev/null; then
+            git config user.name "github-actions[bot]"
+            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+            git add package-lock.json
+            git commit -m "chore: sync package-lock.json"
+            git push || echo "Lockfile push failed (remote ahead); proceeding with deploy"
+          fi
+          npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Resolve site manifest
+        id: site
+        run: node .deco-start/scripts/deploy/resolve-site.mjs
+        env:
+          DECO_START_PATH: .deco-start
+          SITE_NAME: ${{ steps.meta.outputs.site_name }}
+
+      - name: Generate wrangler.jsonc
+        run: node .deco-start/scripts/deploy/build-wrangler-config.mjs
+        env:
+          DECO_START_PATH: .deco-start
+          SITE_NAME: ${{ steps.meta.outputs.site_name }}
+          OUTPUT_PATH: ./wrangler.jsonc
+
+      - name: Deploy to Cloudflare Workers
+        run: npx wrangler deploy --var BUILD_HASH:$(git rev-parse --short HEAD)
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

package/.github/workflows/preview.yml

@@ -0,0 +1,143 @@
+name: preview (central)
+
+# Reusable workflow that uploads a preview version (alias) for any storefront
+# repo registered under `deploy/sites/<repo-name>.jsonc`.
+#
+# Caller usage (in customer repo, `.github/workflows/preview.yml`):
+#
+#   on:
+#     repository_dispatch:
+#       types: [preview-deploy]
+#     pull_request:
+#       types: [opened, synchronize, reopened]
+#     push:
+#       branches: ['env/**']
+#   permissions:
+#     contents: read
+#     pull-requests: write
+#     statuses: write
+#   jobs:
+#     preview:
+#       uses: decocms/deco-start/.github/workflows/preview.yml@v2
+#       secrets: inherit
+
+on:
+  workflow_call:
+    secrets:
+      CLOUDFLARE_API_TOKEN:
+        required: true
+      CLOUDFLARE_ACCOUNT_ID:
+        required: true
+
+permissions:
+  contents: read
+  pull-requests: write
+  statuses: write
+
+concurrency:
+  group: preview-${{ github.repository }}-${{ github.event.client_payload.ref || github.head_ref || github.ref_name }}
+  cancel-in-progress: true
+
+jobs:
+  preview:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Resolve ref
+        id: resolve
+        run: |
+          if [ "${{ github.event_name }}" = "repository_dispatch" ]; then
+            echo "ref=${{ github.event.client_payload.ref }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=${{ github.head_ref || github.ref_name }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.resolve.outputs.ref }}
+
+      - name: Resolve deco-start ref + site identity
+        id: meta
+        run: |
+          WF_REF="${{ github.workflow_ref }}"
+          REF="${WF_REF##*@}"
+          REF="${REF#refs/tags/}"
+          REF="${REF#refs/heads/}"
+          echo "deco_start_ref=$REF" >> "$GITHUB_OUTPUT"
+          echo "site_name=${GITHUB_REPOSITORY#*/}" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout deco-start registry at the same ref
+        uses: actions/checkout@v4
+        with:
+          repository: decocms/deco-start
+          ref: ${{ steps.meta.outputs.deco_start_ref }}
+          path: .deco-start
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Compute preview alias
+        id: alias
+        run: |
+          REF="${{ steps.resolve.outputs.ref }}"
+          if echo "$REF" | grep -q '^env/'; then
+            ALIAS=$(echo "$REF" | sed 's|^env/||')
+          elif [ "${{ github.event_name }}" = "pull_request" ]; then
+            ALIAS="pr-${{ github.event.pull_request.number }}"
+          else
+            ALIAS=$(echo "$REF" | sed 's|[^a-z0-9-]|-|g')
+          fi
+          echo "alias=$ALIAS" >> "$GITHUB_OUTPUT"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+      - name: Resolve site manifest
+        id: site
+        run: node .deco-start/scripts/deploy/resolve-site.mjs
+        env:
+          DECO_START_PATH: .deco-start
+          SITE_NAME: ${{ steps.meta.outputs.site_name }}
+
+      - name: Generate wrangler.jsonc
+        run: node .deco-start/scripts/deploy/build-wrangler-config.mjs
+        env:
+          DECO_START_PATH: .deco-start
+          SITE_NAME: ${{ steps.meta.outputs.site_name }}
+          OUTPUT_PATH: ./wrangler.jsonc
+
+      - name: Upload preview version
+        id: deploy
+        run: |
+          set +e
+          OUTPUT=$(npx wrangler versions upload --preview-alias ${{ steps.alias.outputs.alias }} 2>&1)
+          EXIT_CODE=$?
+          set -e
+          echo "$OUTPUT"
+          if [ $EXIT_CODE -ne 0 ]; then
+            echo "::error::wrangler versions upload failed with exit code $EXIT_CODE"
+            exit $EXIT_CODE
+          fi
+          PREVIEW_URL=$(echo "$OUTPUT" | grep 'Version Preview URL:' | sed 's/.*Version Preview URL: //')
+          ALIAS_URL=$(echo "$OUTPUT" | grep 'Version Preview Alias URL:' | sed 's/.*Version Preview Alias URL: //')
+          echo "preview_url=${PREVIEW_URL}" >> "$GITHUB_OUTPUT"
+          echo "alias_url=${ALIAS_URL}" >> "$GITHUB_OUTPUT"
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+
+      - name: Comment preview URL on PR
+        if: github.event_name == 'pull_request'
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: preview-url
+          message: |
+            ### Preview deployed
+
+            | | URL |
+            |---|---|
+            | **Version** | ${{ steps.deploy.outputs.preview_url }} |
+            | **Alias** | ${{ steps.deploy.outputs.alias_url }} |

package/.github/workflows/regen-blocks.yml

@@ -0,0 +1,56 @@
+name: regen-blocks (central)
+
+# Reusable workflow. Regenerates `src/server/cms/blocks.gen.json` and commits
+# the result back to the caller branch. Runs in the caller's runner context;
+# uses bun because that's what the existing `generate:blocks` script expects.
+#
+# Caller usage (in customer repo, `.github/workflows/regen-blocks.yml`):
+#
+#   on:
+#     push:
+#       branches: [main]
+#       paths: [".deco/blocks/**"]
+#   permissions:
+#     contents: write
+#   jobs:
+#     regen:
+#       uses: decocms/deco-start/.github/workflows/regen-blocks.yml@v2
+#       secrets: inherit
+
+on:
+  workflow_call: {}
+
+permissions:
+  contents: write
+
+concurrency:
+  group: regen-blocks-${{ github.repository }}
+  cancel-in-progress: false
+
+jobs:
+  regen:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install deps
+        run: bun install --frozen-lockfile
+
+      - name: Regenerate blocks.gen.json
+        run: bun run generate:blocks
+
+      - name: Commit and push if changed
+        run: |
+          if git diff --quiet src/server/cms/blocks.gen.json; then
+            echo "blocks.gen.json already up to date — nothing to commit."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add src/server/cms/blocks.gen.json
+          git commit -m "chore: regenerate blocks.gen.json after .deco sync"
+          git push

package/.github/workflows/release.yml

@@ -29,3 +29,29 @@ jobs:
         run: npx semantic-release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      # Caller workflows in storefront repos pin to a moveable major tag (`@v2`),
+      # GitHub Actions convention. After every release we fast-forward that major
+      # tag to the latest exact tag in the same series. Idempotent: if no new
+      # release happened, this just re-points to the existing latest, which is a
+      # no-op force-push.
+      #
+      # Why not a separate workflow on `push: tags`? GitHub suppresses workflow
+      # triggers caused by the auto-issued `GITHUB_TOKEN` (anti-recursion guard),
+      # and `@semantic-release/git` pushes tags using exactly that token, so a
+      # listener would never fire. Inlining keeps the lifecycle visible in one
+      # job log.
+      - name: Advance moveable major tag
+        run: |
+          git fetch --tags --force
+          LATEST=$(git tag -l 'v*.*.*' --sort=-v:refname | head -n 1)
+          if [ -z "$LATEST" ]; then
+            echo "::notice::no v*.*.* tags yet; nothing to advance"
+            exit 0
+          fi
+          MAJOR=$(echo "$LATEST" | sed -E 's/^(v[0-9]+).*/\1/')
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag -f "$MAJOR" "$LATEST"
+          git push origin "$MAJOR" --force
+          echo "::notice::Moved $MAJOR -> $LATEST"