@decocms/start 2.4.2 → 2.6.0

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

@@ -368,6 +368,7 @@ For sites with 100+ sections:
 | Runtime storefront patterns | `references/storefront-patterns.md` |
 | Admin / CMS integration | `references/admin-cms.md` |
 | Gotchas index | `references/gotchas.md` |
+| Post-migration cleanup checklist | `references/post-migration-cleanup.md` |
 | React hooks patterns | `references/react-hooks-patterns.md` |
 | React signals & state | `references/react-signals-state.md` |
 | JSX migration differences | `references/jsx-migration.md` |

package/.agents/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md

@@ -0,0 +1,163 @@
+# Post-Migration Cleanup
+
+After the migration script runs and the site builds + boots, there's a
+recurring set of dead-code and boilerplate cleanup that every migrated
+site benefits from. Run this checklist before the first PR review, not
+after the site has been shipping for weeks.
+
+## 1. Delete unused `src/lib/*` shims
+
+The migration script's `templates/lib-utils.ts` generates 11 shim files
+under `src/lib/`. Most of them are NO-OP stubs intended as defensive
+bridges for signature mismatches. In practice many sites use zero of them
+because their loaders import directly from `@decocms/apps/vtex/utils/*`.
+
+### How to detect
+
+```bash
+# From repo root.
+for f in src/lib/*.ts; do
+  base=$(basename "$f" .ts)
+  symbols=$(grep -oE "^export (function|const|interface|type|class) [A-Za-z_][A-Za-z0-9_]*" "$f" | awk '{print $NF}')
+  for s in $symbols; do
+    # Search for the symbol anywhere in src/ outside src/lib/
+    hits=$(rg -l "\\b$s\\b" src/ --type ts --type tsx -g '!src/lib/**')
+    if [ -z "$hits" ]; then
+      echo "DEAD: $f exports $s with zero external imports"
+    fi
+  done
+done
+```
+
+If every export in a file is dead, delete the file. If `src/lib/` ends
+up empty, delete the directory too.
+
+### Real-world data
+
+| Site | Files generated | Files used |
+|------|-----------------|-----------|
+| baggagio-tanstack | 11 | 0 (all dead) |
+| casaevideo-storefront | 11 | 1 (wrapped manually) |
+
+The files that tend to be dead in every site:
+
+- `vtex-client.ts` — type-only export, sites usually grab it from `@decocms/apps`
+- `vtex-fetch.ts` — `fetchSafe` wrapper, supplanted by `@decocms/apps/vtex/utils/fetch`
+- `vtex-id.ts` — manual `parseCookie`, usually shadowed by `~/sdk/orderForm`'s real one
+- `vtex-segment.ts` — NO-OP stubs returning empty; never useful
+- `vtex-intelligent-search.ts` — stubs returning `{}`; supplanted by apps
+- `vtex-transform.ts` — re-exports from `@decocms/apps/vtex/utils/transform` directly
+- `vtex-send-event.ts` — claims to mirror an unreleased apps export; almost never imported
+
+The files that occasionally stay used:
+
+- `http-utils.ts` — `createHttpClient` proxy bridge for sites with custom
+  HTTP clients
+- `graphql-utils.ts` — same shape for GraphQL
+- `fetch-utils.ts` — single `STALE` cache header constant (very small)
+- `filter-navigate.ts` — VTEX filter URL string transformer
+
+If `apps/utils/*` imports never appear in your Fresh source, ALL FOUR of
+the latter are also dead.
+
+## 2. Drop inline vite plugins that are now framework-provided
+
+Two plugins that older site templates inline are obsolete on
+`@decocms/start >= 2.5.0`:
+
+```ts
+// site-manual-chunks — overrides framework default chunking
+{ name: "site-manual-chunks", config(_cfg, { command }) { ... ~25 lines ... } }
+
+// deco-stub-meta-gen — stubs admin schema on client
+{ name: "deco-stub-meta-gen", enforce: "pre", resolveId(...), load(...) }
+```
+
+The framework's `decoVitePlugin()` now handles both:
+- `manualChunks` no longer splits `@decocms/start` / `@decocms/apps` (the
+  old split caused circular-dep load-order crashes — every site overrode it)
+- `meta.gen.{json,ts}` is stubbed on the client by default
+
+Delete both inline plugins from the site's `vite.config.ts`. Verify the
+production build still succeeds (`vite build` in the site repo).
+
+## 3. Drop the `runtime.ts` `invoke` shim
+
+Older migrations create `src/runtime.ts` with a manual `createNestedInvokeProxy`
+implementation (~45 lines). The framework's `@decocms/start/sdk` now exports
+both `invoke` (default singleton) and `createAppInvoke` (for typed app-scoped
+proxies). Replace the file with a re-export, or delete it and update import
+sites:
+
+```diff
+- import { invoke } from "~/runtime";
++ import { invoke } from "@decocms/start/sdk";
+```
+
+If `~/runtime` was only used for `invoke`, delete the file entirely. If
+it had additional helpers, keep it but trim it down to those.
+
+## 4. Drop site-local `withSiteGlobals` workaround
+
+If your site's `cmsRouteConfig` has a `cmsRouteWithGlobals` wrapper that
+manually merges `site.global` sections into the page sections list,
+delete it and use `@decocms/start/routes`'s opt-in helper:
+
+```ts
+import { cmsRouteConfig, withSiteGlobals } from "@decocms/start/routes";
+
+export const Route = createFileRoute(...)({
+  ...cmsRouteConfig({
+    ...withSiteGlobals,
+    // your route options
+  }),
+});
+```
+
+The site-side wrapper is typically ~390 LOC; the framework helper is
+opt-in and tested.
+
+## 5. Verify `vtex-* shim regression` is not still happening
+
+Older versions of the migration script's `phase-cleanup` had a bug where
+it actively rewrote valid `@decocms/apps/vtex/utils/*` and
+`@decocms/apps/vtex/client` imports back to the dead `~/lib/vtex-*` shims.
+Confirm your loaders import direct from `@decocms/apps`:
+
+```bash
+rg "from ['\"]~/lib/vtex-" src/
+# Expected: 0 hits (or only site-specific reasons you can articulate)
+```
+
+If you see hits, update the imports to point at `@decocms/apps/vtex/...`
+directly (or the corresponding `commerce/utils/*` if it's a generic
+utility). Your runtime behavior gets MUCH better — segment cookies, IS
+cookies, VTEX session auth all start working again instead of being
+silently stubbed to `{}` / `null`.
+
+## 6. Search for orphan `TODO: move into framework` comments
+
+Real sites accumulate `TODO` comments like `// TODO: move into decoVitePlugin
+in next @decocms/start release`. These are roadmap items the framework
+team should pick up, but they often go stale.
+
+```bash
+rg -n "TODO.*deco|TODO.*framework|TODO.*move into" src/ vite.config.ts
+```
+
+For each hit, decide:
+- Has the framework feature shipped? → migrate to it now and delete the comment
+- Is it deferred indefinitely? → file a tracking issue and link from the comment
+- Is it obsolete? → delete the comment
+
+## Verification checklist
+
+After completing 1-6:
+
+- [ ] `npm run typecheck` baseline matches pre-cleanup count (no new errors)
+- [ ] `npm run dev` starts and `/`, `/some-pdp/p`, `/s?q=foo` all render
+- [ ] `npm run build` succeeds with no chunk-load crashes
+- [ ] Smoke a logged-in PDP to confirm session cookies and segment auth
+      work (this is what the `~/lib/vtex-*` regression silently broke)
+- [ ] `git diff --stat` shows only deletions or framework-helper substitutions
+      — no new site-local logic added

package/.agents/skills/deco-to-tanstack-migration/references/vite-config/README.md

@@ -1,12 +1,18 @@
 # Vite Configuration
 
-## Final Config (Post-Migration)
+For the canonical battle-tested template (with VTEX dev proxy, CSP headers,
+React Compiler, dedupe, framework plugin, and rollup chunk strategy) see
+[`../../templates/vite-config.md`](../../templates/vite-config.md).
 
-After all imports are rewritten, the config should be minimal:
+This page covers the post-migration **minimum viable config** if you've
+stripped everything optional. Real sites should use the full template.
+
+## Minimum Viable Config
 
 ```typescript
 import { cloudflare } from "@cloudflare/vite-plugin";
 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import { decoVitePlugin } from "@decocms/start/vite";
 import react from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "vite";
@@ -24,8 +30,23 @@ export default defineConfig({
       },
     }),
     tailwindcss(),
+    // Required — server-only stubs, blocks.gen.ts fast-path, meta.gen
+    // client stub, daemon/tunnel for dev mode. Without this, client
+    // bundle crashes on node:async_hooks / react-dom/server transitively
+    // imported by @decocms/start.
+    decoVitePlugin(),
   ],
   resolve: {
+    // Required — dedupe React/TanStack/Deco packages so there's only one
+    // instance of each. Without this you get "Invalid hook call" errors.
+    dedupe: [
+      "@decocms/start",
+      "@decocms/apps",
+      "@tanstack/react-start",
+      "@tanstack/react-router",
+      "react",
+      "react-dom",
+    ],
     alias: {
       "~": srcDir,
     },
@@ -35,6 +56,10 @@ export default defineConfig({
 
 **One alias only**: `~` -> `src/`. Nothing else.
 
+The `decoVitePlugin()` call is **mandatory** — the older skill examples
+that omitted it (or inlined the stub logic) reflect the pre-2.x state of
+`@decocms/start` and will produce build/runtime failures on current versions.
+
 ## tsconfig.json
 
 Must mirror the Vite alias:

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

@@ -1,10 +1,13 @@
 # vite.config.ts Template
 
-Battle-tested configuration from espacosmart-storefront.
+Battle-tested configuration. Uses the framework's `decoVitePlugin()` for the
+server-only stub layer (rather than re-implementing it inline like older
+sites did).
 
 ```typescript
 import { cloudflare } from "@cloudflare/vite-plugin";
 import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import { decoVitePlugin } from "@decocms/start/vite";
 import react from "@vitejs/plugin-react";
 import tailwindcss from "@tailwindcss/vite";
 import { defineConfig } from "vite";
@@ -12,90 +15,86 @@ import path from "path";
 
 const srcDir = path.resolve(__dirname, "src");
 
+// VTEX dev proxy — adjust to your account / commerce backend.
+const VTEX_ACCOUNT = process.env.VTEX_ACCOUNT || "mystore";
+const VTEX_ORIGIN = `https://${VTEX_ACCOUNT}.vtexcommercestable.com.br`;
+
 export default defineConfig({
+  server: {
+    port: parseInt(process.env.PORT ?? "5173", 10),
+    // When the deco daemon injects PORT, bind to all interfaces so Deno's
+    // TCP connect (127.0.0.1) can reach Vite regardless of IPv4/IPv6.
+    host: process.env.PORT ? "0.0.0.0" : undefined,
+    headers: {
+      // Allow embedding in iframes from trusted admin origins.
+      "Content-Security-Policy":
+        "frame-ancestors 'self' https://*.deco.studio http://localhost:* https://localhost:* https://admin.deco.cx https://studio.decocms.com",
+    },
+    proxy: {
+      "/api/": {
+        target: VTEX_ORIGIN,
+        changeOrigin: true,
+        cookieDomainRewrite: { "*": "" },
+      },
+      "/checkout": {
+        target: VTEX_ORIGIN,
+        changeOrigin: true,
+        cookieDomainRewrite: { "*": "" },
+      },
+    },
+  },
   plugins: [
     cloudflare({ viteEnvironment: { name: "ssr" } }),
     tanstackStart({ server: { entry: "server" } }),
     react({
       babel: {
-        plugins: [
-          ["babel-plugin-react-compiler", { target: "19" }],
-        ],
+        plugins: [["babel-plugin-react-compiler", { target: "19" }]],
       },
     }),
     tailwindcss(),
-    // CRITICAL: Stubs for client bundles that transitively import server modules.
-    // Without this, client build crashes on node:async_hooks, react-dom/server, etc.
-    {
-      name: "deco-server-only-stubs",
-      enforce: "pre" as const,
-      resolveId(id, _importer, options) {
-        if (options?.ssr) return undefined;
-        const CLIENT_STUBS: Record<string, string> = {
-          "react-dom/server": "\0stub:react-dom-server",
-          "react-dom/server.browser": "\0stub:react-dom-server",
-          "node:stream": "\0stub:node-stream",
-          "node:stream/web": "\0stub:node-stream-web",
-          "node:async_hooks": "\0stub:node-async-hooks",
-          "tanstack-start-injected-head-scripts:v": "\0stub:tanstack-head-scripts",
-        };
-        return CLIENT_STUBS[id];
-      },
-      configEnvironment(name: string, env: any) {
-        if (name === "ssr" || name === "client") {
-          env.optimizeDeps = env.optimizeDeps || {};
-          env.optimizeDeps.esbuildOptions = env.optimizeDeps.esbuildOptions || {};
-          env.optimizeDeps.esbuildOptions.jsx = "automatic";
-          env.optimizeDeps.esbuildOptions.jsxImportSource = "react";
-        }
-      },
-      load(id) {
-        if (id === "\0stub:react-dom-server") {
-          return [
-            "const noop = () => '';",
-            "export const renderToString = noop;",
-            "export const renderToStaticMarkup = noop;",
-            "export const renderToReadableStream = noop;",
-            "export const resume = noop;",
-            "export const version = '19.0.0';",
-            "export default { renderToString: noop, renderToStaticMarkup: noop, renderToReadableStream: noop, resume: noop, version: '19.0.0' };",
-          ].join("\n");
-        }
-        if (id === "\0stub:node-stream") {
-          return "export class PassThrough {}; export class Readable {}; export class Writable {}; export default { PassThrough, Readable, Writable };";
-        }
-        if (id === "\0stub:node-stream-web") {
-          return "export const ReadableStream = globalThis.ReadableStream; export const WritableStream = globalThis.WritableStream; export const TransformStream = globalThis.TransformStream; export default { ReadableStream, WritableStream, TransformStream };";
-        }
-        if (id === "\0stub:node-async-hooks") {
-          return [
-            "class _ALS { getStore() { return undefined; } run(_store, fn, ...args) { return fn(...args); } enterWith() {} disable() {} }",
-            "export const AsyncLocalStorage = _ALS;",
-            "export const AsyncResource = class {};",
-            "export function executionAsyncId() { return 0; }",
-            "export function createHook() { return { enable() {}, disable() {} }; }",
-            "export default { AsyncLocalStorage: _ALS, AsyncResource, executionAsyncId, createHook };",
-          ].join("\n");
-        }
-        if (id === "\0stub:tanstack-head-scripts") {
-          return "export const injectedHeadScripts = undefined;";
+    // Framework plugin — provides server-only stubs (react-dom/server,
+    // node:async_hooks, etc.), blocks.gen.ts JSON-fast-path, meta.gen
+    // client stub, daemon/tunnel for dev mode, and correct manualChunks
+    // (NOT splitting @decocms/start / @decocms/apps which have circular
+    // re-exports). Replaces ~80 lines of boilerplate that older sites
+    // had inline.
+    decoVitePlugin(),
+  ],
+  build: {
+    sourcemap: "hidden",
+    rollupOptions: {
+      onLog(level, log, handler) {
+        // Silence harmless "dynamic import will not move module" warning
+        // emitted when a module is imported both statically and dynamically.
+        if (
+          log.code === "PLUGIN_WARNING" &&
+          log.plugin === "vite:reporter" &&
+          log.message?.includes("dynamic import will not move module")
+        ) {
+          return;
         }
+        handler(level, log);
       },
     },
-  ],
-  // Inject site name at build time (not runtime)
+  },
   define: {
+    // Inject site name at build time, not read at runtime.
     "process.env.DECO_SITE_NAME": JSON.stringify(
-      process.env.DECO_SITE_NAME || "my-store"
+      process.env.DECO_SITE_NAME || "my-store",
     ),
   },
   esbuild: {
     jsx: "automatic",
     jsxImportSource: "react",
+    // Strip console.log in production; keep .warn / .error for debugging.
+    pure: ["console.log"],
   },
   resolve: {
-    // CRITICAL: Without dedupe, multiple React/TanStack instances cause hook errors
+    // CRITICAL: without dedupe, multiple React/TanStack instances cause
+    // "Invalid hook call" errors at runtime.
     dedupe: [
+      "@decocms/start",
+      "@decocms/apps",
       "@tanstack/react-start",
       "@tanstack/react-router",
       "@tanstack/react-start-server",
@@ -115,8 +114,84 @@ export default defineConfig({
 
 ## Key Points
 
-1. **deco-server-only-stubs plugin** — Required. Client bundles transitively import `node:async_hooks`, `react-dom/server`, etc. Without stubs, build crashes.
-2. **resolve.dedupe** — Required. Without it, multiple React instances cause "Invalid hook call" errors.
-3. **process.env.DECO_SITE_NAME via define** — Must be injected at build time, not read at runtime.
-4. **React Compiler** — `babel-plugin-react-compiler` with target 19 for automatic memoization.
-5. **esbuild.jsx** — Must be `"automatic"` with `jsxImportSource: "react"` for proper JSX transform.
+1. **`decoVitePlugin()`** — Required. Replaces ~80 lines of inline boilerplate
+   that older sites had to copy. Provides:
+   - Client stubs for server-only modules (`react-dom/server`,
+     `node:async_hooks`, `node:stream`, etc.)
+   - `blocks.gen.ts` JSON fast-path (10-100x parse speedup for large registries)
+   - `meta.gen.{json,ts}` client stub (cuts admin schema 0.5-5MB out of
+     browser bundle)
+   - Daemon/tunnel for dev mode (when `DECO_SITE_NAME` env is set)
+   - Production `manualChunks` that does NOT split `@decocms/start` or
+     `@decocms/apps` (those have circular re-exports and crash when chunked
+     separately)
+   - `allowedHosts` for tunnel domains (`.deco.host`, `.decocdn.com`,
+     `.deco.studio`)
+   - JSX automatic / react import-source defaults
+
+2. **`resolve.dedupe`** — Required. Without it, multiple React instances
+   cause "Invalid hook call" errors. The list MUST include both
+   `@decocms/start` and `@decocms/apps` because they re-export TanStack
+   types and registry singletons.
+
+3. **`process.env.DECO_SITE_NAME` via `define`** — Must be injected at
+   build time, not read at runtime. Workers don't have a Node-style
+   `process.env` at runtime.
+
+4. **React Compiler** — `babel-plugin-react-compiler` with `target: "19"`
+   for automatic memoization. Requires `@vitejs/plugin-react`, not the
+   default SWC plugin.
+
+5. **`esbuild.jsx: "automatic"` with `jsxImportSource: "react"`** — Without
+   it, JSX falls back to `React.createElement` references that may not
+   resolve.
+
+6. **CSP `frame-ancestors`** — Required for the admin (`*.deco.studio`,
+   `admin.deco.cx`, `studio.decocms.com`) to embed previews in iframes.
+
+7. **VTEX dev proxy** — Local `/api/`, `/checkout` requests proxied to
+   the upstream commerce backend so cookie-based session works in dev
+   without CORS gymnastics.
+
+## What older site templates inline (and why this template doesn't)
+
+Some older guides show two extra inline plugins:
+
+```ts
+// site-manual-chunks — overrides framework default chunking
+{ name: "site-manual-chunks", config(_cfg, { command }) { ... } }
+
+// deco-stub-meta-gen — stubs admin schema on client
+{ name: "deco-stub-meta-gen", enforce: "pre", resolveId(...), load(...) }
+```
+
+Both are obsolete after `@decocms/start` >= 2.5.0:
+- The framework's `manualChunks` no longer splits `@decocms/start` /
+  `@decocms/apps` (the old split caused circular-dep load-order crashes —
+  every site overrode it).
+- The framework now stubs `meta.gen.{json,ts}` on the client by default.
+
+If you're on an older version, keep the inline plugins until you can bump.
+
+## tsconfig.json (matches the Vite alias)
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "moduleResolution": "bundler",
+    "module": "ESNext",
+    "target": "ES2022",
+    "skipLibCheck": true,
+    "strictNullChecks": true,
+    "baseUrl": ".",
+    "paths": {
+      "~/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*", "vite.config.ts"]
+}
+```
+
+No `$store/*`, `site/*`, `apps/*`, `preact`, `@preact/signals`,
+`@deco/deco` paths. Those are all dead.

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

@@ -628,6 +628,7 @@ The conductor approach that worked (836 errors → 0 across 213 files) treated e
 | Admin schema composition | `src/admin/schema.ts` in `@decocms/start` |
 | Server functions (`createServerFn`) | `references/server-functions/` |
 | Common gotchas (45 items) | `references/gotchas.md` |
+| Post-migration cleanup checklist | `references/post-migration-cleanup.md` |
 | setup.ts template | `templates/setup-ts.md` |
 | vite.config.ts template | `templates/vite-config.md` |
 | worker-entry template | `templates/worker-entry.md` |

package/.cursor/skills/deco-to-tanstack-migration/references/post-migration-cleanup.md

@@ -0,0 +1,163 @@
+# Post-Migration Cleanup
+
+After the migration script runs and the site builds + boots, there's a
+recurring set of dead-code and boilerplate cleanup that every migrated
+site benefits from. Run this checklist before the first PR review, not
+after the site has been shipping for weeks.
+
+## 1. Delete unused `src/lib/*` shims
+
+The migration script's `templates/lib-utils.ts` generates 11 shim files
+under `src/lib/`. Most of them are NO-OP stubs intended as defensive
+bridges for signature mismatches. In practice many sites use zero of them
+because their loaders import directly from `@decocms/apps/vtex/utils/*`.
+
+### How to detect
+
+```bash
+# From repo root.
+for f in src/lib/*.ts; do
+  base=$(basename "$f" .ts)
+  symbols=$(grep -oE "^export (function|const|interface|type|class) [A-Za-z_][A-Za-z0-9_]*" "$f" | awk '{print $NF}')
+  for s in $symbols; do
+    # Search for the symbol anywhere in src/ outside src/lib/
+    hits=$(rg -l "\\b$s\\b" src/ --type ts --type tsx -g '!src/lib/**')
+    if [ -z "$hits" ]; then
+      echo "DEAD: $f exports $s with zero external imports"
+    fi
+  done
+done
+```
+
+If every export in a file is dead, delete the file. If `src/lib/` ends
+up empty, delete the directory too.
+
+### Real-world data
+
+| Site | Files generated | Files used |
+|------|-----------------|-----------|
+| baggagio-tanstack | 11 | 0 (all dead) |
+| casaevideo-storefront | 11 | 1 (wrapped manually) |
+
+The files that tend to be dead in every site:
+
+- `vtex-client.ts` — type-only export, sites usually grab it from `@decocms/apps`
+- `vtex-fetch.ts` — `fetchSafe` wrapper, supplanted by `@decocms/apps/vtex/utils/fetch`
+- `vtex-id.ts` — manual `parseCookie`, usually shadowed by `~/sdk/orderForm`'s real one
+- `vtex-segment.ts` — NO-OP stubs returning empty; never useful
+- `vtex-intelligent-search.ts` — stubs returning `{}`; supplanted by apps
+- `vtex-transform.ts` — re-exports from `@decocms/apps/vtex/utils/transform` directly
+- `vtex-send-event.ts` — claims to mirror an unreleased apps export; almost never imported
+
+The files that occasionally stay used:
+
+- `http-utils.ts` — `createHttpClient` proxy bridge for sites with custom
+  HTTP clients
+- `graphql-utils.ts` — same shape for GraphQL
+- `fetch-utils.ts` — single `STALE` cache header constant (very small)
+- `filter-navigate.ts` — VTEX filter URL string transformer
+
+If `apps/utils/*` imports never appear in your Fresh source, ALL FOUR of
+the latter are also dead.
+
+## 2. Drop inline vite plugins that are now framework-provided
+
+Two plugins that older site templates inline are obsolete on
+`@decocms/start >= 2.5.0`:
+
+```ts
+// site-manual-chunks — overrides framework default chunking
+{ name: "site-manual-chunks", config(_cfg, { command }) { ... ~25 lines ... } }
+
+// deco-stub-meta-gen — stubs admin schema on client
+{ name: "deco-stub-meta-gen", enforce: "pre", resolveId(...), load(...) }
+```
+
+The framework's `decoVitePlugin()` now handles both:
+- `manualChunks` no longer splits `@decocms/start` / `@decocms/apps` (the
+  old split caused circular-dep load-order crashes — every site overrode it)
+- `meta.gen.{json,ts}` is stubbed on the client by default
+
+Delete both inline plugins from the site's `vite.config.ts`. Verify the
+production build still succeeds (`vite build` in the site repo).
+
+## 3. Drop the `runtime.ts` `invoke` shim
+
+Older migrations create `src/runtime.ts` with a manual `createNestedInvokeProxy`
+implementation (~45 lines). The framework's `@decocms/start/sdk` now exports
+both `invoke` (default singleton) and `createAppInvoke` (for typed app-scoped
+proxies). Replace the file with a re-export, or delete it and update import
+sites:
+
+```diff
+- import { invoke } from "~/runtime";
++ import { invoke } from "@decocms/start/sdk";
+```
+
+If `~/runtime` was only used for `invoke`, delete the file entirely. If
+it had additional helpers, keep it but trim it down to those.
+
+## 4. Drop site-local `withSiteGlobals` workaround
+
+If your site's `cmsRouteConfig` has a `cmsRouteWithGlobals` wrapper that
+manually merges `site.global` sections into the page sections list,
+delete it and use `@decocms/start/routes`'s opt-in helper:
+
+```ts
+import { cmsRouteConfig, withSiteGlobals } from "@decocms/start/routes";
+
+export const Route = createFileRoute(...)({
+  ...cmsRouteConfig({
+    ...withSiteGlobals,
+    // your route options
+  }),
+});
+```
+
+The site-side wrapper is typically ~390 LOC; the framework helper is
+opt-in and tested.
+
+## 5. Verify `vtex-* shim regression` is not still happening
+
+Older versions of the migration script's `phase-cleanup` had a bug where
+it actively rewrote valid `@decocms/apps/vtex/utils/*` and
+`@decocms/apps/vtex/client` imports back to the dead `~/lib/vtex-*` shims.
+Confirm your loaders import direct from `@decocms/apps`:
+
+```bash
+rg "from ['\"]~/lib/vtex-" src/
+# Expected: 0 hits (or only site-specific reasons you can articulate)
+```
+
+If you see hits, update the imports to point at `@decocms/apps/vtex/...`
+directly (or the corresponding `commerce/utils/*` if it's a generic
+utility). Your runtime behavior gets MUCH better — segment cookies, IS
+cookies, VTEX session auth all start working again instead of being
+silently stubbed to `{}` / `null`.
+
+## 6. Search for orphan `TODO: move into framework` comments
+
+Real sites accumulate `TODO` comments like `// TODO: move into decoVitePlugin
+in next @decocms/start release`. These are roadmap items the framework
+team should pick up, but they often go stale.
+
+```bash
+rg -n "TODO.*deco|TODO.*framework|TODO.*move into" src/ vite.config.ts
+```
+
+For each hit, decide:
+- Has the framework feature shipped? → migrate to it now and delete the comment
+- Is it deferred indefinitely? → file a tracking issue and link from the comment
+- Is it obsolete? → delete the comment
+
+## Verification checklist
+
+After completing 1-6:
+
+- [ ] `npm run typecheck` baseline matches pre-cleanup count (no new errors)
+- [ ] `npm run dev` starts and `/`, `/some-pdp/p`, `/s?q=foo` all render
+- [ ] `npm run build` succeeds with no chunk-load crashes
+- [ ] Smoke a logged-in PDP to confirm session cookies and segment auth
+      work (this is what the `~/lib/vtex-*` regression silently broke)
+- [ ] `git diff --stat` shows only deletions or framework-helper substitutions
+      — no new site-local logic added