@decocms/start 2.21.0 → 2.23.0

package/MIGRATION_TOOLING_PLAN.md

@@ -239,6 +239,88 @@ Each item carries a status: ⬜ pending, 🟡 in progress, ✅ done, 🚫 blocke
 
 > Append-only. Each entry: date, what we found, where it impacts the plan.
 
+### 2026-05-01 — Wave 15-A double-check exposed a self-perpetuating template→audit loop
+
+- **Q1 (sites→packages promotion completeness):** Two subagents
+  swept `casaevideo-storefront` + `baggagio-tanstack`. The big
+  A-list icebergs are caught — but **5 cross-site duplications
+  satisfying D4** slipped through (`useSuggestions`, `useOffer`
+  forks, `useVariantPossibilities` forks, site-local copies of
+  framework `clx` / `useSendEvent`, three competing `Picture`
+  APIs). Plus 4 migration debts where the framework already has
+  the answer (`useCart` factory not adopted in casaevideo,
+  `runtime.ts` inline proxy still scaffolded, location matcher
+  duplication, inline cookie helpers).
+- **Q2 (script/skill coverage of what we shipped):** Worse. The
+  migration script's templates were **scaffolding code that the
+  audit's `--fix` then removed** — the textbook
+  self-perpetuating loop. `templates/vite-config.ts` was emitting
+  `site-manual-chunks` + `deco-stub-meta-gen` (both already
+  inside `decoVitePlugin()`). `templates/server-entry.ts` was
+  emitting a 47-line `createNestedInvokeProxy` body (already in
+  `@decocms/start/sdk`). The factories shipped in W12 (`createUseUser`
+  / `createUseWishlist`) had **zero skill mentions** — the
+  pre-W12 manual approach was still the canonical doc. Cookie
+  passthrough helpers in `cookiePassthrough.ts` were **half-shipped**:
+  the deco-start side compiled, the apps-start providers it
+  references in its own docstring don't exist, and the migration
+  script never wired either.
+- **Decided: ship Wave 15-A as a single PR.** Drop the obsolete
+  emissions (G1/G2/G4/G5), expand `dead-runtime-shim` to catch
+  both the legacy inline shape (with `Runtime` export) and the
+  Wave-15-A canonical re-export shape (skip — desired form),
+  publish a `platform-hooks-factories.md` skill that supersedes
+  the stale README, and update plan + journal.
+- **Defer to Wave 15-B / 16:** (G3) promotion of the
+  `invoke.gen.ts` 170-LOC server-fn block to apps-start needs
+  research on TanStack Start's compiler scanning behaviour
+  (whether `createServerFn` can be transformed when it lives in
+  a node_module). (H1) full cookie-passthrough provider wiring
+  (`setRequestCookieProvider` / `setResponseCookieForwarder` in
+  apps-start, auto-wire in `setup.ts`) needs design. The 5
+  cross-site convergence promotions (`useSuggestions`,
+  `useOffer` factory, `Picture` unification, `clx`/`useSendEvent`
+  redirects, `relative()` extension) are now in the priority-2
+  backlog, sequenced after Wave 15-A merges.
+- **The double-check itself is a useful primitive.** "Did we
+  ship script/skill/audit coverage for everything we built?" run
+  against the framework + apps inventory consistently surfaces
+  these loops. Codify it: when promoting a new factory or
+  helper, the PR checklist must include "matching template
+  emit", "matching audit-rule expansion", "matching skill doc
+  entry". This is the kind of self-check that prevents the next
+  16-month-old stale skill.
+
+### 2026-05-01 — Wave 14-A rescoped from three codemods to one based on real als data
+
+- **Pre-data plan vs post-data plan.** The plan called for three
+  htmx codemods (`event-handler`, `form-swap`, `click-swap`).
+  After running `deco-htmx-analyze` against als-storefront's
+  actual code (210 occurrences across 133 files), only the
+  `event-handler` bucket (88 occurrences, 42 %) genuinely admits
+  a mechanical rewrite — the other buckets need per-call-site
+  product decisions a codemod cannot encode. **Decided: ship
+  one codemod (W14-A: `htmx-on-event-rename`), defer the other
+  two to W15+.** Rationale captured in the Wave 14 — discoveries
+  block.
+- **Codemod shape generalises:** rename + preserve body +
+  conditional file-level TODO. Three outputs, one mechanical,
+  one verbatim, one conditional on body-content heuristics. This
+  is the shape any future per-pattern codemod should target.
+- **Smoke against the real source tree validated the design in
+  five minutes.** 754 files scanned, 71 changed, 98 renames, 67
+  TODO injections (94 % of changed files). Without that smoke
+  step we'd have shipped blind on edge cases like multi-line
+  values, mixed standard + lifecycle hooks on the same element,
+  and the colon-vs-dash variants both showing up in the same
+  file.
+- **The codemod + audit pair closes another loop.** Same shape
+  as W12 (D3 throwing stubs + audit `--fix` for swap-able
+  stubs). The codemod removes the mechanical half of the htmx
+  surface; the `htmx-residue` audit catches the surviving half
+  in CI. Engineers can never silently ship a half-rewritten
+  file.
+
 ### 2026-05-01 — als-storefront surfaces the htmx track + policy reset
 
 - **als-storefront is the third migration target and the first
@@ -834,12 +916,217 @@ analysis, rewrite recipes, and a "rewrite-complete" gate.
   rule means changing one file, getting `--strict` and `--json`
   for free.
 
-### Wave 14 (htmx codemods + first als migration on 2.14+) — planned
-
-- **W14-A** deco-start: codemod `transforms/htmx-form-post-swap.ts` — `<form hx-post={url} hx-target hx-swap>` → `useMutation` + state setter
-- **W14-B** deco-start: codemod `transforms/htmx-click-fetch-swap.ts` — `<button hx-get={url}>` → onClick + invoke + state
-- **W14-C** deco-start: codemod `transforms/htmx-on-click-script.ts` — `hx-on:click={useScript(...)}` → `onClick` handler
-- **W14-D** als: rm -rf old als-tanstack, fresh `deco-migrate` run on 2.14+ with new htmx codemods. Per D5 (no --restart), this is the only restart UX.
+### Wave 14 (htmx codemod — Priority 2 part 2) — ✅ **PARTIAL / RESCOPED**
+
+After shipping the W13 htmx foundations and gathering real data
+from als-storefront with `deco-htmx-analyze`, the planned three-codemod
+scope was reduced to **one codemod** + **one inventory artefact**.
+The other two codemods (form-swap, click-swap) were deferred to W15+,
+to be designed *after* als migration data exposes which exact
+attribute clusters dominate. **Rationale logged in W14 discoveries.**
+
+**Shipped:**
+
+- **W14-A** [`deco-start#132`](https://github.com/decocms/deco-start/pull/132) — `feat(migrate): htmx-on-event-rename codemod` ✅ **MERGED**, released as `@decocms/start@2.22.0`.
+  Adds `scripts/migrate/transforms/htmx-on-events.ts` to the migrate
+  `transforms/` pipeline. Mechanically rewrites `hx-on:event=` and
+  `hx-on-event=` (colon + dash variants) to the React equivalent
+  for every standard DOM event in `STANDARD_EVENT_MAP` (40 entries:
+  click, submit, change, input, key*, mouse*, focus*, drag*, touch*,
+  paste/copy/cut, scroll, wheel, load, contextmenu). Handler bodies
+  are preserved verbatim. **Idempotent** — running twice is a no-op.
+  Two safety hatches: htmx lifecycle events (`hx-on:htmx-*`) and
+  unknown custom events left alone (the `htmx-residue` audit catches
+  them); a single top-of-file MIGRATION TODO comment is injected
+  when the body references Fresh-only globals (`useScript(…)`,
+  `globalThis.window.STOREFRONT`, `STOREFRONT.…`) so engineers
+  don't ship a syntactically-clean file with broken runtime calls.
+  29 unit tests + als-shaped fixtures (AddToBagButton, SearchInput,
+  RecoveryPassword form, Footer.tsx). 339/339 pass; typecheck clean.
+  htmx-rewrite skill § Pattern 1 cross-references the codemod.
+- **W14-B** [`deco-start#132`](https://github.com/decocms/deco-start/pull/132) — captured the **als-storefront htmx inventory** in this plan (this section) as a fixture for future W15+ codemod design.
+
+**Deferred (intentionally) — see Wave 14 discoveries:**
+
+- ~~**W14-C** codemod `transforms/htmx-form-post-swap.ts`~~ — moved to W15+. The form-swap rewrite is genuinely non-mechanical (per-call-site decisions about optimistic vs pessimistic UI, where to surface loading state, which response handler shape). A speculative codemod would produce React skeletons that still need ~80 % manual work.
+- ~~**W14-D** codemod `transforms/htmx-click-fetch-swap.ts`~~ — moved to W15+. Same logic; on top of that, choosing between local state machine vs sub-route is a routing-architecture decision that varies per page.
+
+#### W14-A smoke + als inventory (captured 2026-05-01)
+
+The W13-A `deco-htmx-analyze` CLI run against als-storefront's
+production Fresh tree:
+
+| Category | Count | % | Notes |
+|---|---:|---:|---|
+| `event-handler` | 88 | 42 % | **Codemoded by W14-A** — mechanical rename |
+| `click-swap` | 64 | 30 % | Manual (W15+) — needs state vs sub-route decision |
+| `form-swap` | 20 | 10 % | Manual (W15+) — needs `useMutation` shape decision |
+| `auto-fetch` | 9 | 4 % | Manual — debounced state + `useQuery` |
+| `oob-swap` | 8 | 4 % | Manual — no 1:1 React equivalent |
+| `unmatched` | 21 | 10 % | Mostly typed-generic noise (`<string>` from `Map<string,X>`) |
+| **Total** | **210** | | across 133 files |
+
+W14-A codemod sweep against the same tree (754 ts/tsx files):
+
+| Metric | Value |
+|---|---:|
+| Files scanned | 754 |
+| Files changed | 71 |
+| Total `hx-on:*` attributes renamed | 98 |
+| Files getting the MIGRATION TODO | 67 (94 % of changed) |
+
+The 98 vs 88 discrepancy is expected: the analyzer counts attribute
+*clusters* per element (an `<input hx-post hx-target hx-on:change>`
+classifies as one `auto-fetch`); the codemod counts individual
+`hx-on:*` attribute renames (the same element gets one rename
+plus the `auto-fetch` cluster left intact for the engineer to
+finish). Net effect: ~98 mechanical wins, leaving ~112 cluster
+rewrites (click-swap + form-swap + auto-fetch + oob-swap +
+unmatched) for the engineer — matching the manual rewrite
+recipes in `references/htmx-rewrite.md`.
+
+### Wave 14 — discoveries
+
+- **Speculative codemods are over-engineering; data-driven scope
+  is better.** The pre-data plan said three codemods (event-handler,
+  form-swap, click-swap). After running `deco-htmx-analyze` against
+  als-storefront's actual code, only the event-handler bucket
+  (88 occurrences, 42 % of the surface) genuinely admits a
+  mechanical rewrite. The other two buckets need per-call-site
+  product decisions (state machine vs sub-route, optimistic vs
+  pessimistic UI, response-handler shape) that a codemod cannot
+  encode without producing React skeletons that still need ~80 %
+  manual work — net negative versus the recipe in
+  `references/htmx-rewrite.md`. **New rule: codemods come *after*
+  the analyzer data, not before.**
+- **The smoke-against-real-site step is the design feedback loop.**
+  Running the codemod against als's full 754-file tree (98
+  renames, 71 files changed, 67 with TODO injection) validated
+  three things in five minutes: (a) the rename surface matches
+  the inventory (98 vs 88 ratio explained), (b) the TODO
+  injection rate is high (94 %) — the marker is essential, not
+  defensive, (c) the codemod is idempotent at scale (re-running
+  produces zero diffs). Without this step we'd ship blind.
+- **The three-output codemod shape (rename + preserve body +
+  conditional TODO) generalises.** Same shape any future
+  per-pattern codemod should target: do the mechanical part,
+  preserve the human-decision-required part, leave a single
+  file-level marker the engineer can grep for. Over-eager
+  body rewriting is what produces the ~80 % manual cleanup load
+  that justifies leaving form-swap / click-swap codemods out for
+  now.
+- **`htmx-residue` audit + W14-A codemod close another loop.**
+  Same pattern as W12 (D3 throwing stubs + audit `--fix` for
+  swap-able stubs). The codemod removes the easy half of the
+  htmx surface; the audit catches the surviving half. Engineers
+  can never accidentally ship a half-rewritten file: the
+  attribute is either gone (codemod ran, body might still need
+  work — TODO), or it's still there (audit fires in CI).
+- **als-storefront's profile probably generalises to other htmx
+  sites.** 42 % event-handler is a strong skew toward
+  trivially-mechanical rewrites; even if other sites differ,
+  this codemod alone removes the largest single bucket. If a
+  future site shows 80 % click-swap, *that* would be the cue to
+  build the click-swap codemod — not pre-emptively now.
+- **Pipeline order matters.** Codemod runs after `transformJsx`
+  (which renames `class` → `className` and `onInput` → `onChange`)
+  and before `transformFreshApis` (which removes `useScript`
+  imports). If `transformFreshApis` ran first, the codemod's
+  TODO marker would still fire (we look for `useScript(` calls,
+  not the import), but the import-removal would create dead
+  references. Order is correct.
+
+### Wave 15-A (close template→audit loops + factories skill — Priority 2 follow-on) — 🟡 **IN FLIGHT**
+
+Triggered by the double-check audit on 2026-05-01: subagent sweeps over
+casaevideo-storefront + baggagio-tanstack revealed (a) the migration
+template was scaffolding code that the audit's `--fix` then removed,
+and (b) the W12 factory hooks (`createUseUser`, `createUseWishlist`)
+had no skill coverage. Wave 15-A closes both loops in one PR.
+
+**Shipped (one PR against `decocms/deco-start`):**
+
+37. `feat(migrate): close template→audit loops for vite plugins, runtime, cookies, branding + factories skill` 🟡 **WAITING ON CI**.
+    - **`templates/vite-config.ts`** — drop `site-manual-chunks` and
+      `deco-stub-meta-gen` plugin emissions. Both already live in
+      `decoVitePlugin()` (`src/vite/plugin.js`). The audit's
+      `obsolete-vite-plugins --fix` was undoing the template's own
+      output; now the template emits clean, the audit catches
+      regressions in legacy sites.
+    - **`templates/server-entry.ts` `generateRuntime()`** — replace
+      the 47-line inline `createNestedInvokeProxy` body with a 6-line
+      re-export from `@decocms/start/sdk`. Sites keep
+      `import { invoke } from "~/runtime"` and `Runtime.invoke`
+      shapes. A2 of the original investigation finally lands at the
+      template layer (was previously only patched post-migration by
+      the audit).
+    - **`templates/server-entry.ts` `generateInvoke()` (VTEX path)**
+      — replace inline `mergeSetCookies` helper with
+      `forwardResponseCookies` from
+      `@decocms/start/sdk/cookiePassthrough`. The framework helper
+      already shipped with try/catch for build-time safety.
+      `getVtexCookies` stays inline (it's auth-specific filtering, not
+      generic passthrough — see Wave 15-B/16 for full provider wiring
+      under H1).
+    - **`templates/routes.ts` + `templates/commerce-loaders.ts`** —
+      replace casaevideo-specific branding leaks ("Tudo para sua
+      casa…" tagline, "O melhor site de compras online…"
+      `productListPageCollection` SEO description) with
+      `${siteTitle}`-derived defaults plus `MIGRATION TODO` markers
+      pointing at the per-site customization spot. CMS `Site.seo`
+      overrides the defaults at runtime so leaving them visible in
+      pre-resolution states is the safe behaviour.
+    - **Audit rule expansion: `dead-runtime-shim`** — previously only
+      flagged when exports were exactly `{ invoke }` or
+      `{ invoke, createNestedInvokeProxy }`. Updated to detect (a)
+      inline `createNestedInvokeProxy` body via regex (catches the
+      legacy 47-line shape **with** `Runtime` export — which the old
+      heuristic missed entirely; this is the shape every existing
+      VTEX site has) and (b) skip the new Wave-15-A canonical
+      re-export shape (where `import invoke from
+      @decocms/start/sdk` is present and no inline proxy body
+      exists). Auto-fix is gated by `safeToAutoFix` metadata: legacy
+      shim shapes get the rewrite + delete; sites that mix the proxy
+      with custom helpers get a warning only. Three new tests.
+      **Verified against casaevideo-storefront**: now flags
+      `[invoke, Runtime] inline createNestedInvokeProxy body` (was
+      missed entirely before).
+    - **Skill: `references/platform-hooks-factories.md`** — new
+      canonical doc covering `createUseCart` / `createUseUser` /
+      `createUseWishlist`. Replaces the pre-W12 manual approach of
+      hand-rolling 200+ LOC of `createServerFn` wrappers per site.
+      Documents the 5-line shim shape, why factories instead of
+      direct hook imports (state isolation per site), non-VTEX
+      stubs using `@decocms/start/sdk/signal`, and the migration
+      path off the manual approach.
+    - **Skill update: `references/platform-hooks/README.md`** —
+      retained as legacy reference but now opens with a
+      "deprecated, see canonical" header pointing at the new doc.
+      The pre-W12 `createServerFn` examples are kept for sites that
+      haven't migrated to factories yet.
+    - **`SKILL.md` index update** — Phase 5 entry now points to the
+      factories doc; reference table lists both new + legacy paths.
+    - 342 → 345 tests pass, typecheck clean, smoke against casaevideo
+      + baggagio confirms expanded rule fires correctly on legacy
+      shapes and stays silent on baggagio (no `runtime.ts` file there).
+
+**Deferred to Wave 15-B / 16 (intentionally — see discoveries journal):**
+
+- **G3** — promote the 170-LOC `invoke.gen.ts` VTEX `createServerFn`
+  wrappers into `@decocms/apps/vtex/server-fns`. Needs research on
+  whether TanStack Start's compiler can transform `createServerFn`
+  call sites that live inside a node_module. Not safe to ship blind.
+- **H1** — full cookie-passthrough provider wiring
+  (`setRequestCookieProvider` / `setResponseCookieForwarder` in
+  apps-start, auto-wire in `templates/setup.ts`). The
+  `cookiePassthrough.ts` docstring already references this design but
+  the apps-start side doesn't exist. Needs a design pass to scope
+  what calls inside `vtex/utils/fetch.ts` need the provider hook
+  (currently each call site forwards cookies manually).
+- **Cross-site convergence promotions** (5 items) — `useSuggestions`,
+  `useOffer` factory, `Picture` API unification, redirect
+  `useSendEvent`/`clx`/location-matcher imports, `relative()`
+  SKU-stripping extension. Sequenced after 15-A merges.
 
 ### Wave 15+ (htmx cleanup PRs on als + propagation to other sites) — Priority 3 / 4
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.21.0",
+  "version": "2.23.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/migrate/phase-transform.ts

@@ -9,6 +9,7 @@ import { transformFreshApis } from "./transforms/fresh-apis";
 import { transformDenoIsms } from "./transforms/deno-isms";
 import { transformTailwind } from "./transforms/tailwind";
 import { transformDeadCode } from "./transforms/dead-code";
+import { transformHtmxOnEvents } from "./transforms/htmx-on-events";
 import { createSectionConventionsTransform } from "./transforms/section-conventions";
 
 /** Map of section path → metadata, populated per-run */
@@ -54,10 +55,15 @@ function applyTransforms(content: string, filePath: string, ctx?: MigrationConte
     return { content, changed: false, notes: [] };
   }
 
-  // Pipeline: imports → jsx → fresh-apis → dead-code → deno-isms → tailwind
+  // Pipeline: imports → jsx → htmx-on-events → fresh-apis → dead-code → deno-isms → tailwind
+  // htmx-on-events runs after jsx (which renames class/onChange) and
+  // before fresh-apis (which removes useScript imports the htmx
+  // codemod's TODO might still reference). The codemod is a no-op on
+  // files without hx-on, so it never adds latency to non-htmx sites.
   const pipeline: Array<{ name: string; fn: (content: string) => TransformResult }> = [
     { name: "imports", fn: (c) => transformImports(c, ctx?.islandWrapperTargets) },
     { name: "jsx", fn: transformJsx },
+    { name: "htmx-on-events", fn: transformHtmxOnEvents },
     { name: "fresh-apis", fn: transformFreshApis },
     { name: "dead-code", fn: (c) => transformDeadCode(c, ctx?.platform) },
     { name: "deno-isms", fn: transformDenoIsms },

package/scripts/migrate/post-cleanup/rules.ts

@@ -462,6 +462,31 @@ function findAttachedLeadingComments(content: string, openIdx: number): number {
 /* Rule 3 — dead `src/runtime.ts` invoke shim                          */
 /* ------------------------------------------------------------------ */
 
+/**
+ * Detection covers two shapes of `src/runtime.ts`:
+ *
+ * 1. Legacy inline proxy (pre-Wave 15-A migration template) — defines
+ *    `createNestedInvokeProxy` plus `invoke` and `Runtime` constants.
+ *    The whole 40-50 LOC body duplicates `@decocms/start/sdk`'s `invoke`.
+ *
+ * 2. Simple re-export shim — the file only re-exports `invoke` /
+ *    `createNestedInvokeProxy` (no inline proxy body, but also not yet
+ *    pointing at `@decocms/start/sdk`).
+ *
+ * Both should be replaced with `import { invoke } from "@decocms/start/sdk"`
+ * at every callsite, and the file deleted. The Wave 15-A migration template
+ * scaffolds a thin re-export form that's also acceptable (re-exports
+ * `invoke` from `@decocms/start/sdk` and rebuilds `Runtime = { invoke }`);
+ * we explicitly skip it via the "imports invoke from @decocms/start/sdk
+ * AND no inline proxy" check below.
+ */
+const INLINE_PROXY_RE =
+  /(?:function|const)\s+createNestedInvokeProxy\b|new\s+Proxy\s*\(\s*Object\.assign\s*\(\s*async\s*\(\s*props/;
+const FRAMEWORK_INVOKE_IMPORT_RE =
+  /import\s+\{[^}]*\binvoke\b[^}]*\}\s+from\s+['"]@decocms\/start(?:\/sdk)?['"]/;
+
+const ALLOWED_RUNTIME_EXPORTS = new Set(["invoke", "createNestedInvokeProxy", "Runtime"]);
+
 const ruleDeadRuntimeShim: Rule = {
   id: "dead-runtime-shim",
   title: "Dead src/runtime.ts invoke shim",
@@ -469,24 +494,54 @@ const ruleDeadRuntimeShim: Rule = {
     const abs = `${siteDir}/src/runtime.ts`;
     if (!fs.exists(abs)) return [];
     const content = fs.readText(abs);
-    // Heuristic: if the file's only meaningful exports are `invoke` /
-    // `createNestedInvokeProxy`, it's purely a shim.
+
+    const hasInlineProxy = INLINE_PROXY_RE.test(content);
+    const reExportsFromFramework = FRAMEWORK_INVOKE_IMPORT_RE.test(content);
     const exports = extractExports(content);
-    const onlyInvokeShim =
-      exports.length > 0 && exports.every((e) => ["invoke", "createNestedInvokeProxy"].includes(e));
-    if (!onlyInvokeShim) return [];
+    const onlyKnownInvokeExports =
+      exports.length > 0 && exports.every((e) => ALLOWED_RUNTIME_EXPORTS.has(e));
+
+    // Wave 15-A canonical template: re-exports invoke from @decocms/start/sdk
+    // and exposes `Runtime = { invoke }` for legacy callers. No inline proxy
+    // body. This is the desired shape — skip.
+    if (reExportsFromFramework && !hasInlineProxy) return [];
+
+    // Site-specific helpers alongside invoke: don't flag — the file has its
+    // own purpose beyond shimming. (Old behavior preserved.)
+    if (!hasInlineProxy && !onlyKnownInvokeExports) return [];
+
+    const exportSummary = exports.length > 0 ? exports.join(", ") : "(re-exports only)";
+    const flavor = hasInlineProxy ? "inline createNestedInvokeProxy body" : "shim re-exports";
+    // Only safe to auto-delete when exports are pure invoke surface; if a
+    // legacy file mixes the inline proxy with custom helpers, we still flag
+    // it but skip the destructive fix.
+    const safeToAutoFix = onlyKnownInvokeExports;
+
     return [
       {
         rule: "dead-runtime-shim",
         severity: "info",
         file: "src/runtime.ts",
-        message: `Only re-exports invoke (${exports.join(", ")}) — replace with @decocms/start/sdk`,
-        fix: 'rg -l "from \\"~/runtime\\"" src/ | xargs sed -i \'\' \'s|from "~/runtime"|from "@decocms/start/sdk"|g\' && rm src/runtime.ts',
+        message: safeToAutoFix
+          ? `${flavor} [${exportSummary}] — replace with @decocms/start/sdk`
+          : `${flavor} [${exportSummary}] — manual review: file mixes the runtime proxy with site-specific exports`,
+        fix: safeToAutoFix
+          ? 'rg -l "from \\"~/runtime\\"" src/ | xargs sed -i \'\' \'s|from "~/runtime"|from "@decocms/start/sdk"|g\' && rm src/runtime.ts'
+          : "Move the inline `createNestedInvokeProxy` body to call @decocms/start/sdk's `invoke`; relocate site-specific helpers to a dedicated module before deleting src/runtime.ts",
+        meta: {
+          hasInlineProxy,
+          exports,
+          safeToAutoFix,
+        },
       },
     ];
   },
   applyFix(ctx, findings, writer): FixAction[] {
     if (findings.length === 0) return [];
+    // Honor the per-finding safety gate emitted by run() — never auto-delete
+    // a runtime.ts that mixes the proxy with site-specific helpers.
+    const safe = findings.every((f) => f.meta?.safeToAutoFix !== false);
+    if (!safe) return [];
     const updated = rewriteImportSpec(ctx, writer, "~/runtime", "@decocms/start/sdk");
     writer.deleteFile(`${ctx.siteDir}/src/runtime.ts`);
     return [

package/scripts/migrate/post-cleanup/runner.test.ts

@@ -227,9 +227,11 @@ describe("rule: dead-runtime-shim", () => {
     const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
     expect(r.findings).toHaveLength(1);
     expect(r.findings[0].file).toBe("src/runtime.ts");
+    expect(r.findings[0].meta?.safeToAutoFix).toBe(true);
+    expect(r.findings[0].meta?.hasInlineProxy).toBe(true);
   });
 
-  it("does not flag a runtime.ts that exports site-specific helpers", () => {
+  it("does not flag a runtime.ts that exports site-specific helpers (no inline proxy)", () => {
     const fs = makeFs({
       "/site/src/runtime.ts": "export const invoke = {};\nexport const customHelper = () => 1;\n",
     });
@@ -237,6 +239,80 @@ describe("rule: dead-runtime-shim", () => {
     const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
     expect(r.findings).toEqual([]);
   });
+
+  it("does NOT flag the Wave 15-A canonical re-export shape", () => {
+    // The migration template now scaffolds a thin re-export from
+    // @decocms/start/sdk plus a Runtime alias. No inline proxy body.
+    const fs = makeFs({
+      "/site/src/runtime.ts":
+        'import { invoke } from "@decocms/start/sdk";\nexport { invoke };\nexport const Runtime = { invoke };\n',
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("flags the legacy 47-line inline createNestedInvokeProxy body (with Runtime export)", () => {
+    // The pre-Wave-15-A migration template emitted a full Proxy body
+    // alongside `Runtime = { invoke }`. The earlier rule heuristic
+    // missed this shape because `Runtime` was not in its allowlist.
+    const fs = makeFs({
+      "/site/src/runtime.ts": `
+function createNestedInvokeProxy(path: string[] = []): any {
+  return new Proxy(
+    Object.assign(async (props: any) => {
+      const key = path.join("/");
+      const response = await fetch(\`/deco/invoke/\${key}\`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(props ?? {}),
+      });
+      return response.json();
+    }, {}),
+    {
+      get(_target: any, prop: string) {
+        if (prop === "then") return undefined;
+        return createNestedInvokeProxy([...path, prop]);
+      },
+    },
+  );
+}
+
+export const invoke = createNestedInvokeProxy() as any;
+export const Runtime = { invoke };
+`,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.hasInlineProxy).toBe(true);
+    expect(r.findings[0].meta?.safeToAutoFix).toBe(true);
+    expect(r.findings[0].message).toContain("inline createNestedInvokeProxy body");
+  });
+
+  it("flags but does NOT auto-fix when inline proxy coexists with site-specific helpers", () => {
+    // Defensive: if a site has hand-tuned the runtime file with extra
+    // exports beyond invoke/Runtime, deletion would lose data. Surface
+    // the issue but skip the destructive fix.
+    const fs = makeFs({
+      "/site/src/runtime.ts": `
+function createNestedInvokeProxy(path: string[] = []): any {
+  return new Proxy(Object.assign(async (props: any) => {}, {}), {});
+}
+export const invoke = createNestedInvokeProxy();
+export const trackPageView = () => console.log("custom tracker");
+`,
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "dead-runtime-shim")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.hasInlineProxy).toBe(true);
+    expect(r.findings[0].meta?.safeToAutoFix).toBe(false);
+    expect(r.findings[0].message).toContain("manual review");
+    // applyFix should be a no-op when safeToAutoFix is false — verified
+    // implicitly by the runner test for --fix below; here we only
+    // assert the metadata gate.
+  });
 });
 
 describe("rule: site-local-with-globals", () => {

package/scripts/migrate/templates/commerce-loaders.ts

@@ -204,7 +204,8 @@ export function generateCommerceLoaders(ctx: MigrationContext): string {
       lines.push(`      breadcrumb: createBreadcrumbFromPath(url.pathname, url, collection.name) ?? {},`);
       lines.push(`      seo: {`);
       lines.push(`        title: collection.name,`);
-      lines.push(`        description: "O melhor site de compras online para sua casa: compre itens de cozinha, móveis para sala e escritório, acessórios de tecnologia e mais. Clique já!",`);
+      lines.push(`        // MIGRATION TODO: replace with site-specific category description`);
+      lines.push(`        description: collection.name,`);
       lines.push(`        noIndexing: false,`);
       lines.push(`        canonical: url.toString(),`);
       lines.push(`      },`);

package/scripts/migrate/templates/routes.ts

@@ -67,8 +67,10 @@ import { DecoRootLayout } from "@decocms/start/hooks";
 // @ts-ignore Vite ?url import
 import appCss from "../styles/app.css?url";
 
-const DEFAULT_DESCRIPTION =
-  "${siteTitle} - Tudo para sua casa com os melhores preços.";
+// MIGRATION TODO: customize description, OG image, and locale for ${siteTitle}.
+// The migration scaffold leaves a generic default so it never falls through;
+// CMS \`Site.seo\` overrides this once block resolution kicks in.
+const DEFAULT_DESCRIPTION = "${siteTitle}";
 
 export const Route = createRootRoute({
   head: () => ({
@@ -108,11 +110,14 @@ function generateIndex(ctx: MigrationContext, siteTitle: string): string {
 import { cmsHomeRouteConfig, deferredSectionLoader } from "@decocms/start/routes";
 import { DecoPageRenderer } from "@decocms/start/hooks";
 
+// MIGRATION TODO: customize defaultTitle / defaultDescription / fallback
+// copy below for ${siteTitle}. CMS \`Site.seo\` overrides these once block
+// resolution kicks in, so leaving the migration scaffold defaults is safe
+// but visible in pre-block-resolution states.
 export const Route = createFileRoute("/")({
   ...cmsHomeRouteConfig({
-    defaultTitle: "${siteTitle} - Tudo para sua casa",
-    defaultDescription:
-      "${siteTitle} - Tudo para sua casa com os melhores preços.",
+    defaultTitle: "${siteTitle}",
+    defaultDescription: "${siteTitle}",
     siteName: "${siteTitle}",
   }),
   component: HomePage,
@@ -126,8 +131,7 @@ function HomePage() {
       <div className="min-h-screen flex items-center justify-center">
         <div className="text-center">
           <h1 className="text-4xl font-bold mb-4">${siteTitle}</h1>
-          <p className="text-lg text-base-content/60">Tudo para sua casa</p>
-          <p className="text-sm text-base-content/40 mt-2">Nenhuma página CMS encontrada para /</p>
+          <p className="text-sm text-base-content/40 mt-2">No CMS page registered for /</p>
         </div>
       </div>
     );
@@ -152,11 +156,12 @@ function generateCatchAll(ctx: MigrationContext, siteTitle: string): string {
 import { cmsRouteConfig, deferredSectionLoader } from "@decocms/start/routes";
 import { DecoPageRenderer } from "@decocms/start/hooks";
 
+// MIGRATION TODO: customize defaultTitle / defaultDescription for ${siteTitle}
+// (CMS \`Site.seo\` overrides these per-page once block resolution kicks in).
 const routeConfig = cmsRouteConfig({
   siteName: "${siteTitle}",
-  defaultTitle: "${siteTitle} - Tudo para sua casa",
-  defaultDescription:
-    "${siteTitle} - Tudo para sua casa com os melhores preços.",
+  defaultTitle: "${siteTitle}",
+  defaultDescription: "${siteTitle}",
   ignoreSearchParams: ["skuId"],
 });