@decocms/start 2.28.2 → 2.30.0

package/.github/workflows/sync-secrets.yml

@@ -0,0 +1,173 @@
+name: sync-secrets (central)
+
+# Reusable workflow. Reconciles the caller's `SECRET_*` GitHub repo secrets
+# with the Cloudflare Worker's runtime secrets (with the prefix stripped).
+#
+# Examples:
+#   SECRET_STRIPE_KEY in GitHub  ->  STRIPE_KEY on the worker
+#
+# Defaults to dry-run; the caller must pass `mode: apply` to actually write.
+# Orphans on the worker (present on worker but not in GitHub as SECRET_*) are
+# warned about, never deleted.
+#
+# Caller usage (in customer repo, `.github/workflows/sync-secrets.yml`):
+#
+#   on:
+#     workflow_dispatch:
+#       inputs:
+#         mode:
+#           description: "dry-run | apply"
+#           required: true
+#           default: "dry-run"
+#           type: choice
+#           options: [dry-run, apply]
+#   jobs:
+#     sync:
+#       uses: decocms/deco-start/.github/workflows/sync-secrets.yml@v2
+#       with:
+#         mode: ${{ inputs.mode }}
+#       secrets: inherit
+
+on:
+  workflow_call:
+    inputs:
+      mode:
+        description: "dry-run = print diff only | apply = set secrets on worker"
+        required: false
+        type: string
+        default: "dry-run"
+    secrets:
+      CLOUDFLARE_API_TOKEN:
+        required: true
+      CLOUDFLARE_ACCOUNT_ID:
+        required: true
+
+permissions:
+  contents: read
+
+concurrency:
+  group: sync-secrets-${{ github.repository }}
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - 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: 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: Install wrangler
+        run: npm install --no-save wrangler@4
+
+      - name: Plan and (optionally) apply
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          ALL_SECRETS: ${{ toJSON(secrets) }}
+          MODE: ${{ inputs.mode }}
+        run: |
+          set -euo pipefail
+
+          # Build desired-state map from SECRET_* entries.
+          desired_json=$(printf '%s' "$ALL_SECRETS" | jq '
+            to_entries
+            | map(select(.key | startswith("SECRET_")))
+            | map({ key: (.key | sub("^SECRET_"; "")), value: .value })
+            | from_entries
+          ')
+
+          desired_names=$(printf '%s' "$desired_json" | jq -r 'keys[]' | sort)
+
+          # Validate names before any side effect.
+          while IFS= read -r name; do
+            [ -z "$name" ] && continue
+            if ! [[ "$name" =~ ^[A-Z][A-Z0-9_]{0,63}$ ]]; then
+              echo "::error::Invalid worker secret name derived from SECRET_${name}: must match ^[A-Z][A-Z0-9_]{0,63}$"
+              exit 1
+            fi
+          done <<< "$desired_names"
+
+          # Snapshot what's currently on the worker.
+          existing=$(npx wrangler secret list --format=json | jq -r '.[].name' | sort)
+
+          # Diff
+          to_set="$desired_names"
+          orphans=$(comm -23 <(printf '%s\n' "$existing") <(printf '%s\n' "$desired_names") || true)
+
+          {
+            echo "## Diff"
+            echo ""
+            echo "### Will set (from SECRET_* in GitHub):"
+            if [ -z "$to_set" ]; then
+              echo "  (none)"
+            else
+              echo "$to_set" | sed 's/^/  + /'
+            fi
+            echo ""
+            echo "### Orphans (on worker, not in GitHub as SECRET_*):"
+            if [ -z "$orphans" ]; then
+              echo "  (none)"
+            else
+              echo "$orphans" | sed 's/^/  ! /'
+              echo ""
+              echo "  These will NOT be deleted automatically. To remove manually:"
+              echo "$orphans" | sed 's|^|    npx wrangler secret delete "|; s|$|" --force|'
+            fi
+          } | tee -a "$GITHUB_STEP_SUMMARY"
+
+          if [ -n "$orphans" ]; then
+            echo "::warning::${orphans//$'\n'/, } exist on the worker but not in GitHub as SECRET_*. Not deleting."
+          fi
+
+          if [ "$MODE" = "dry-run" ]; then
+            echo "::notice::dry-run mode -- no changes applied"
+            exit 0
+          fi
+
+          # Apply
+          if [ -z "$to_set" ]; then
+            echo "Nothing to apply."
+            exit 0
+          fi
+
+          printf '%s' "$desired_json" | jq -r 'to_entries[] | "\(.key)\t\(.value)"' \
+            | while IFS=$'\t' read -r name value; do
+                echo "Setting $name..."
+                printf '%s' "$value" | npx wrangler secret put "$name"
+              done
+
+          echo "::notice::Applied $(echo "$to_set" | wc -l | tr -d ' ') secrets."

package/CODEOWNERS

@@ -0,0 +1,16 @@
+# CODEOWNERS for decocms/deco-start
+#
+# `deploy/` is the trust boundary for the central deploy pipeline. The files
+# under `deploy/sites/` immutably bind a customer repo to a Cloudflare worker;
+# `deploy/wrangler-template.jsonc` is the canonical wrangler config every site
+# inherits. A bad PR here can misroute a deploy or change every site's runtime
+# configuration in one shot. Only the platform team approves changes.
+#
+# The central reusable workflows are in the same trust boundary: they decide
+# how every site is built and deployed.
+deploy/                       @vibe-dex
+.github/workflows/deploy.yml         @vibe-dex
+.github/workflows/preview.yml        @vibe-dex
+.github/workflows/sync-secrets.yml   @vibe-dex
+.github/workflows/regen-blocks.yml   @vibe-dex
+scripts/deploy/                      @vibe-dex

package/MIGRATION_TOOLING_PLAN.md

@@ -117,6 +117,7 @@ this plan.
 | 2026-05-01 | **D3 — Stub generation: throw at runtime (Option C)** | Migration-time stubs throw with a clear pointer to the canonical replacement instead of silently identity-casting. Forces audit `--fix` to cover swap cases (no permanent detect-only state) and skills to keep up with stub generation. |
 | 2026-05-01 | **D4 — Site-local apps: local by default, promote at 3** | Site-specific apps live in `src/apps/local/` until ≥3 sites use them, then promote to `@decocms/apps`. |
 | 2026-05-01 | **D5 — Failed migrations: rm -rf and re-run** | No `--restart` mode. Half-migrated sites are throwaways. Failure modes get documented in skills, not encoded as escape hatches. |
+| 2026-05-07 | **D6 — Deploy / preview / secrets pipelines: centralize in `deco-start`** | At 6 sites the "1-minute copy" of `deploy.yml` / `preview.yml` / `wrangler.jsonc` had already produced unintended drift (lebiscuit missing 2 workflows, miess missing `account_id`, casaevideo's `loadtest:tail` worker name out of sync with its wrangler config). All sites now consume reusable workflows from `decocms/deco-start@v2` and a per-site registry under [`deploy/sites/<repo>.jsonc`](./deploy/) deep-merged on top of [`deploy/wrangler-template.jsonc`](./deploy/wrangler-template.jsonc) at deploy time. Customer repos hold only ~5-line caller workflows; `wrangler.jsonc` is generated and gitignored. The repo→worker binding is the trust boundary that prevents one site's commits from misrouting onto another site's worker (the central workflow ignores caller `inputs:` for identity and derives the site name from `${{ github.repository }}`). See [`deploy/README.md`](./deploy/README.md) for the contract. |
 
 The full text of the constitutional rule (loaded into every agent
 session for this repo) lives at
@@ -1669,10 +1670,21 @@ props. One broken section never takes the page down.
   release picks up the framework export — TODO is checked into
   `src/lib/http-utils.ts`.
 - **CI/CD porting from casaevideo to a new TanStack site is a 1-minute
-  copy.** `deploy.yml`, `preview.yml`, `regen-blocks.yml`, plus
-  `wrangler.jsonc` worker `name` rename, plus `account_id` paste from
-  another site. No template needed yet — three sites is too few. Will
-  template if a fourth migration needs it.
+  copy** (when this note was written, at 3 sites). By 6 sites
+  the copy-paste had drifted: lebiscuit was missing
+  `regen-blocks.yml` and `sync-secrets.yml`, miess was missing
+  `regen-blocks.yml` and its `wrangler.jsonc` lacked `account_id`,
+  lebiscuit's preview workflow swallowed `wrangler` exit codes, and
+  casaevideo's `loadtest:tail` referenced a worker name that didn't
+  match its `wrangler.jsonc`. **Resolved 2026-05-07 via D6:** all
+  workflows + wrangler config are centralized in
+  [`deco-start/.github/workflows/`](./.github/workflows/) and
+  [`deco-start/deploy/`](./deploy/). New-site onboarding is now: open a
+  PR adding `deploy/sites/<repo>.jsonc` to deco-start, then drop the
+  ~5-line caller workflows into the new site's repo. No `wrangler.jsonc`
+  is committed to the site repo — `deco-wrangler gen`
+  (a `bin` shipped from `@decocms/start`) materializes it from the
+  central registry on demand for local dev and CI alike.
 
 #### Counter-evidence the user-rule asks for
 

package/README.md

@@ -1,124 +1,219 @@
-# @decocms/start 
+# @decocms/start
 
 [![npm version](https://img.shields.io/npm/v/@decocms/start.svg)](https://www.npmjs.com/package/@decocms/start)
 [![license](https://img.shields.io/npm/l/@decocms/start.svg)](https://github.com/decocms/deco-start/blob/main/LICENSE)
 
-Framework layer for [Deco](https://deco.cx) storefronts built on **TanStack Start + React 19 + Cloudflare Workers**.
+Framework layer for [deco.cx](https://deco.cx) storefronts on **TanStack Start + React 19 + Cloudflare Workers**.
 
-Provides CMS block resolution, admin protocol handlers, section rendering, schema generation, edge caching, and SDK utilities. This is **not** a storefront — it's the npm package that storefronts depend on.
+`@decocms/start` is the npm package that storefronts depend on. It provides the CMS bridge, admin protocol, section registry, schema generation, edge caching, the Vite plugin, and a small SDK. It is **not** itself a storefront — it is what storefronts build on top of.
 
-## Install
+📖 **[Read the full documentation →](https://docs.deco.cx/v2/en/getting-started/overview)**
+
+---
+
+## What's in the box
 
-```bash
-npm install @decocms/start
+```
+┌─────────────────────────────────────────────────┐
+│   Site repo (your storefront)                    │  ← Components, sections, routes
+├─────────────────────────────────────────────────┤
+│   @decocms/apps  (commerce integrations)         │  ← VTEX, Shopify, Resend
+├─────────────────────────────────────────────────┤
+│   @decocms/start  (framework — this package)     │  ← CMS bridge, admin, caching
+└─────────────────────────────────────────────────┘
+              ↓ runs on ↓
+   TanStack Start  +  React 19  +  Cloudflare Workers
 ```
 
-## Architecture
+`@decocms/start` exports cover four surfaces:
+
+- **Worker entry** — `createDecoWorkerEntry` wraps your Cloudflare Worker with admin routes, edge cache, and asset bypass.
+- **CMS bridge** — `loadCmsPage`, `resolveDecoPage`, `registerSectionLoaders`, `registerLayoutSections`.
+- **Admin protocol** — `handleMeta`, `handleDecofile`, `handleRender`, `handleInvoke`.
+- **SDK** — `createCachedLoader`, `createInstrumentedFetch`, `createInvoke`, `decoVitePlugin`, plus utilities (cookies, redirects, sitemap, A/B testing).
+
+Full export reference: [docs.deco.cx/v2/en/reference/package-exports](https://docs.deco.cx/v2/en/reference/package-exports).
+
+---
+
+## Hello, World
+
+A minimal v2 storefront has six files. Here they are.
+
+### `package.json`
+
+```jsonc
+{
+  "name": "my-store",
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "deploy": "wrangler deploy"
+  },
+  "dependencies": {
+    "@decocms/start": "^2.28.0",
+    "@decocms/apps": "^1.11.0",
+    "@tanstack/react-start": "^1.166.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "vite": "^6.0.0",
+    "wrangler": "^4.72.0"
+  }
+}
+```
 
+### `vite.config.ts`
+
+```ts
+import { defineConfig } from "vite";
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import react from "@vitejs/plugin-react";
+import decoVitePlugin from "@decocms/start/vite";
+
+export default defineConfig({
+  plugins: [
+    cloudflare({ viteEnvironment: { name: "ssr" } }),
+    tanstackStart({ server: { entry: "server" } }),
+    react({ babel: { plugins: ["babel-plugin-react-compiler"] } }),
+    decoVitePlugin(),
+  ],
+  resolve: {
+    alias: { "~": "/src" },
+    deduplicate: ["react", "react-dom", "@decocms/start", "@decocms/apps"],
+  },
+});
 ```
-@decocms/start        ← Framework (this package)
-  └─ @decocms/apps    ← Commerce integrations (VTEX, Shopify)
-       └─ site repo   ← UI components, routes, styles
+
+### `wrangler.jsonc`
+
+```jsonc
+{
+  "name": "my-store",
+  "main": "./src/worker-entry.ts",
+  "compatibility_date": "2026-02-14",
+  "compatibility_flags": [
+    "nodejs_compat",
+    "no_handle_cross_request_promise_resolution"
+  ],
+  "assets": { "directory": "./dist/client" }
+}
+```
+
+### `src/setup.ts`
+
+```ts
+import { createSiteSetup } from "@decocms/start/setup";
+import { applySectionConventions } from "@decocms/start/cms";
+
+import blocks from "./server/cms/blocks.gen";
+import sectionsGen from "./server/cms/sections.gen";
+import meta from "./server/cms/meta.gen.json";
+
+createSiteSetup({
+  sections: import.meta.glob("./sections/**/*.tsx", { eager: true }),
+  blocks,
+  meta: () => meta,
+  productionOrigins: ["https://my-store.com"],
+});
+
+applySectionConventions(sectionsGen);
 ```
 
-### Package Exports
-
-| Import | Purpose |
-|--------|---------|
-| `@decocms/start` | Barrel export |
-| `@decocms/start/cms` | Block loading, page resolution, section registry |
-| `@decocms/start/admin` | Admin protocol (meta, decofile, invoke, render, schema) |
-| `@decocms/start/hooks` | DecoPageRenderer, LiveControls, LazySection |
-| `@decocms/start/routes` | CMS route config, admin routes |
-| `@decocms/start/middleware` | Observability, deco state, liveness probe |
-| `@decocms/start/sdk/workerEntry` | Cloudflare Worker entry with edge caching |
-| `@decocms/start/sdk/cacheHeaders` | URL-to-profile cache detection |
-| `@decocms/start/sdk/cachedLoader` | In-flight dedup for loaders |
-| `@decocms/start/sdk/useScript` | Inline `<script>` with minification |
-| `@decocms/start/sdk/useDevice` | SSR-safe device detection |
-| `@decocms/start/sdk/analytics` | Analytics event types |
-| `@decocms/start/matchers/*` | Feature flag matchers (PostHog, built-ins) |
-| `@decocms/start/types` | Section, App, FnContext type definitions |
-| `@decocms/start/scripts/*` | Code generation (blocks, schema, invoke) |
-
-### Worker Entry Request Flow
+### `src/worker-entry.ts`
+
+```ts
+import "./setup";   // MUST be first
+
+import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";
+import {
+  handleMeta,
+  handleDecofile,
+  handleRender,
+  handleInvoke,
+} from "@decocms/start/admin";
+import serverEntry from "./server";
 
+export default createDecoWorkerEntry(serverEntry, {
+  admin: { handleMeta, handleDecofile, handleRender, handleInvoke },
+});
 ```
-Request → createDecoWorkerEntry()
- ├─ Admin routes (/live/_meta, /.decofile, /deco/render, /deco/invoke)
- ├─ Cache purge check
- ├─ Static asset bypass (/assets/*, favicon)
- ├─ Cloudflare edge cache (profile-based TTLs)
- └─ TanStack Start server entry
+
+### `src/routes/$.tsx`
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { cmsRouteConfig } from "@decocms/start/routes";
+
+export const Route = createFileRoute("/$")(
+  cmsRouteConfig({ siteName: "my-store" }),
+);
 ```
 
-### Edge Cache Profiles
+That is the entire skeleton. `npm install`, `npm run dev`, point `admin.deco.cx` at it, and you have a working CMS-driven site.
 
-| URL Pattern | Profile | Edge TTL |
-|-------------|---------|----------|
-| `/` | static | 1 day |
-| `*/p` | product | 5 min |
-| `/s`, `?q=` | search | 60s |
-| `/cart`, `/checkout` | private | none |
-| Everything else | listing | 2 min |
+For commerce integrations (VTEX, Shopify) see [`@decocms/apps`](https://www.npmjs.com/package/@decocms/apps).
 
-## Migrating from Fresh/Preact/Deno
+---
 
-`@decocms/start` includes an Agent Skill that handles migration for you. It works with Claude Code, Cursor, Codex, and other AI coding tools. Install the skill, open your Fresh storefront, and tell the AI to migrate:
+## Migrating from Fresh / Preact / Deno
+
+`@decocms/start` ships an Agent Skill that handles the migration for you. It works with Claude Code, Cursor, Codex, and any tool that supports skills.
 
 ```bash
 npx skills add decocms/deco-start
 ```
 
-Then open your project in any supported tool and say:
+Then, in your editor, point at your Fresh storefront and prompt:
 
 > migrate this project to TanStack Start
 
-The skill handles compatibility checking, import rewrites, config generation, section registry setup, and worker entry creation. It knows what `@decocms/start` supports and will flag anything that needs manual attention.
+The skill runs the migration script, walks you through `MIGRATION_REPORT.md`, fixes typecheck/build errors interactively, and shows the diff before committing.
 
-### Or run the script manually
+### Or run the script directly
 
 ```bash
-# From your Fresh site directory (nothing to install beforehand):
+# from inside the v1 storefront directory
 npx -p @decocms/start deco-migrate
 ```
 
-**Options:**
+The script runs seven phases (analyze → scaffold → transform → cleanup → report → verify → bootstrap), produces `MIGRATION_REPORT.md` with manual TODOs, and gets you to "compiles clean, builds clean".
+
+Full migration playbook: [docs.deco.cx/v2/en/migration/overview](https://docs.deco.cx/v2/en/migration/overview).
 
-| Flag | Description |
-|------|-------------|
-| `--source <dir>` | Source directory (default: current directory) |
-| `--dry-run` | Preview changes without writing files |
-| `--verbose` | Show detailed output |
-| `--help`, `-h` | Show help message |
+---
 
-The script runs 7 phases automatically:
+## Documentation
 
-1. **Analyze** — scan source, detect Preact/Fresh/Deco patterns
-2. **Scaffold** — generate `vite.config.ts`, `wrangler.jsonc`, routes, `setup.ts`, worker entry
-3. **Transform** — rewrite imports (70+ rules), JSX attrs, Fresh APIs, Deno-isms, Tailwind v3→v4
-4. **Cleanup** — delete `islands/`, old routes, `deno.json`, move `static/` → `public/`
-5. **Report** — generate `MIGRATION_REPORT.md` with manual review items
-6. **Verify** — 18+ smoke tests (zero old imports, scaffolded files exist)
-7. **Bootstrap** — `npm install`, generate CMS blocks, generate routes
+The full v2 docs live at **[docs.deco.cx/v2](https://docs.deco.cx/v2/en/getting-started/overview)**:
 
-Your existing `src/sections/`, `src/components/`, and `.deco/blocks/` work as-is. The script gets you to "builds clean with zero old imports" — manual work starts at platform hooks (`useCart`) and runtime tuning.
+- [Getting started](https://docs.deco.cx/v2/en/getting-started/overview) — install paths, project structure, stack overview.
+- [Concepts](https://docs.deco.cx/v2/en/concepts/sections) — sections, loaders, blocks, routes, deferred rendering.
+- [Framework reference](https://docs.deco.cx/v2/en/framework/overview) — every export of `@decocms/start`, page by page.
+- [Migration](https://docs.deco.cx/v2/en/migration/overview) — v1 → v2 playbook + script + skill.
+- [Case studies](https://docs.deco.cx/v2/en/case-studies/overview) — three production stores end-to-end.
 
-### Agent Skills
+---
 
-Skills live in [`.agents/skills/`](.agents/skills/) and provide deep context to AI coding tools:
+## Peer dependencies
 
-| Skill | What it covers |
-|-------|---------------|
-| `deco-to-tanstack-migration` | Full 12-phase migration playbook with 22 reference docs and 6 templates |
-| `deco-migrate-script` | How the automated `scripts/migrate.ts` works, how to extend it |
+```json
+{
+  "@tanstack/react-start": ">=1.0.0",
+  "@tanstack/store": ">=0.7.0",
+  "@tanstack/react-query": ">=5.0.0",
+  "react": "^19.0.0",
+  "react-dom": "^19.0.0",
+  "vite": ">=6.0.0"
+}
+```
 
-## Peer Dependencies
+OpenTelemetry is optional but recommended: `@microlabs/otel-cf-workers >=1.0.0-rc.0`, `@opentelemetry/api >=1.9.0`.
 
-- `@tanstack/react-start` >= 1.0.0
-- `@tanstack/store` >= 0.7.0
-- `react` ^19.0.0
-- `react-dom` ^19.0.0
+---
 
 ## Development
 
@@ -128,7 +223,11 @@ npm run lint        # biome check
 npm run check       # typecheck + lint + unused exports
 ```
 
-This is a library — no dev server. Consumer sites run their own `vite dev`.
+This is a library — there is no dev server here. Consumer storefronts run their own `vite dev`.
+
+Contributing? See `CLAUDE.md` for the architectural decisions, and `MIGRATION_TOOLING_PLAN.md` for the append-only history of the migration tooling.
+
+---
 
 ## License
 

package/deploy/README.md

@@ -0,0 +1,85 @@
+# `deploy/` — central deploy registry
+
+This directory is the single source of truth for **what gets deployed where**
+across every storefront on the platform. It is consumed by the reusable GitHub
+workflows under [`.github/workflows/`](../.github/workflows/) (`deploy.yml`,
+`preview.yml`, `sync-secrets.yml`) and by the local `deco-wrangler` CLI.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `wrangler-template.jsonc` | Canonical wrangler config that every site inherits. Compatibility flags, worker-entry path, observability — everything that is the same for every site. |
+| `sites/<repo-name>.jsonc` | Per-site overrides. Only the keys that genuinely vary per-site live here (`worker_name` always; `routes`, `kv_namespaces`, `analytics_engine_datasets`, `version_metadata` when used). |
+
+The repository name (the part of `${{ github.repository }}` after the `/`) is
+the lookup key. `als-tanstack` deploys via `sites/als-tanstack.jsonc`. There is
+no other way to identify a site.
+
+## Trust model
+
+- Customer caller workflows pass **no inputs** to the central reusable workflow.
+- The central workflow derives the site name from `${{ github.repository }}`
+  (set by GitHub, untamperable by user code) and looks up
+  `sites/<repo-name>.jsonc` from this registry.
+- A customer cannot misroute a deploy onto another customer's worker because
+  they can't write to `decocms/deco-start`.
+
+`deploy/**` is CODEOWNERS-protected. Only the platform team can change site
+manifests or the template.
+
+## How wrangler.jsonc is generated
+
+At deploy time, the central workflow runs
+[`scripts/deploy/build-wrangler-config.mjs`](../scripts/deploy/build-wrangler-config.mjs),
+which:
+
+1. Loads `deploy/wrangler-template.jsonc` (canonical defaults).
+2. Loads `deploy/sites/<site>.jsonc` (per-site overrides).
+3. Deep-merges: site overrides win. `worker_name` becomes wrangler's `name`.
+   Arrays are replaced, not concatenated.
+4. Writes the result to `./wrangler.jsonc` in the caller checkout.
+
+`account_id` is never written to JSON — wrangler reads it from
+`CLOUDFLARE_ACCOUNT_ID` (env var in CI; `wrangler login` locally).
+
+## Adding a new site
+
+1. Open a PR to this repo adding `deploy/sites/<new-repo>.jsonc`:
+   ```jsonc
+   {
+     "worker_name": "<new-repo>"   // can differ from repo name if needed
+   }
+   ```
+2. After merge, the next `v2.x.y` semantic-release publish auto-moves the
+   `@v2` major tag (the major-tag advance step lives inline in
+   [`.github/workflows/release.yml`](../.github/workflows/release.yml)).
+3. In the new repo, add the four caller workflows from
+   [`.github/workflows/`](../.github/workflows/) and set the org-level
+   `CLOUDFLARE_API_TOKEN` / `CLOUDFLARE_ACCOUNT_ID` GitHub secrets.
+4. Push to `main` and verify the deploy lands on the right worker.
+
+## Per-site override schema
+
+```jsonc
+{
+  "worker_name": "string (required, immutable)",
+  "routes": [                          // optional
+    { "pattern": "www.example.com/*", "zone_name": "decocdn.com" }
+  ],
+  "kv_namespaces": [                   // optional
+    { "binding": "SITES_KV", "id": "<cf-kv-id>" }
+  ],
+  "analytics_engine_datasets": [       // optional
+    { "binding": "DECO_METRICS", "dataset": "deco_metrics_<site>" }
+  ],
+  "version_metadata": {                // optional
+    "binding": "CF_VERSION_METADATA"
+  }
+}
+```
+
+All other wrangler keys (compatibility flags, `main`, observability, etc.) come
+from the template — do not duplicate them per-site. If a per-site override is
+genuinely needed for one of those keys, add it to the schema and document the
+reason here.

package/deploy/sites/als-tanstack.jsonc

@@ -0,0 +1,7 @@
+// Per-site overrides for `als-tanstack` (immutable repo->worker binding).
+// Renaming `worker_name` is a breaking change: it points the next deploy at a
+// different Cloudflare worker. Only the platform team can change this file
+// (CODEOWNERS-protected).
+{
+  "worker_name": "als-tanstack"
+}

package/deploy/sites/americanas-tanstack.jsonc

@@ -0,0 +1,4 @@
+// Per-site overrides for `americanas-tanstack`.
+{
+  "worker_name": "americanas-tanstack"
+}

package/deploy/sites/baggagio-tanstack.jsonc

@@ -0,0 +1,4 @@
+// Per-site overrides for `baggagio-tanstack`.
+{
+  "worker_name": "baggagio-tanstack"
+}

package/deploy/sites/casaevideo-storefront.jsonc

@@ -0,0 +1,11 @@
+// Per-site overrides for `casaevideo-storefront`.
+//
+// NOTE: `kv_namespaces[].id` is shared with `lebiscuit-tanstack`. Verify this
+// is intentional before promoting this registry to v1. R4 in the central-deploy
+// plan adds a CI check that flags shared KV ids as a copy-paste smell.
+{
+  "worker_name": "casaevideo-tanstack",
+  "kv_namespaces": [
+    { "binding": "SITES_KV", "id": "ad0b74fc4d9341c9af9149c4ab85132f" }
+  ]
+}