@decocms/start 2.17.0 → 2.19.0

package/package.json

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

package/scripts/migrate/phase-scaffold.ts

@@ -18,6 +18,7 @@ import { generateCommerceLoaders } from "./templates/commerce-loaders";
 import { generateSectionLoaders } from "./templates/section-loaders";
 import { generateCacheConfig } from "./templates/cache-config";
 import { generateSdkFiles } from "./templates/sdk-gen";
+import { generateMigrationPolicyPointerRule } from "./templates/cursor-rules";
 // `lib-utils` is imported lazily — see end of phase-cleanup. Eager
 // generation of all 11 shims left every site with dead code that had
 // to be cleaned up by hand.
@@ -139,6 +140,17 @@ export function scaffold(ctx: MigrationContext): void {
     writeFile(ctx, "src/components/ui/Theme.tsx", generateSiteThemeComponent());
   }
 
+  // Migration tooling policy pointer rule (D1–D5 + priorities).
+  // The canonical rule lives in decocms/deco-start; this is a tiny
+  // pointer that loads on every Cursor session in the migrated site
+  // so agents working on the site know where the policy is and what
+  // it means here. See MIGRATION_TOOLING_PLAN.md (Wave 12-H).
+  writeFile(
+    ctx,
+    ".cursor/rules/migration-tooling-policy.mdc",
+    generateMigrationPolicyPointerRule(ctx.siteName),
+  );
+
   // Create public/ directory
   if (!ctx.dryRun) {
     fs.mkdirSync(path.join(ctx.sourceDir, "public"), { recursive: true });

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

@@ -156,8 +156,307 @@ const ruleObsoleteVitePlugins: Rule = {
     }
     return findings;
   },
+  applyFix({ siteDir, fs }, findings, writer): FixAction[] {
+    // Group findings by file so we rewrite each vite.config in one pass.
+    const byFile = new Map<string, string[]>();
+    for (const f of findings) {
+      const plugin = (f.meta?.plugin as string | undefined) ?? "";
+      if (!plugin) continue;
+      const arr = byFile.get(f.file) ?? [];
+      arr.push(plugin);
+      byFile.set(f.file, arr);
+    }
+    const actions: FixAction[] = [];
+    for (const [rel, pluginNames] of byFile) {
+      const abs = `${siteDir}/${rel}`;
+      if (!fs.exists(abs)) continue;
+      const before = fs.readText(abs);
+      const removed: string[] = [];
+      let next = before;
+      // Process plugins right-to-left in document order so each removal
+      // does not invalidate the indices of the next one.
+      const ordered = pluginNames
+        .map((name) => ({ name, span: findInlineVitePluginSpan(next, name) }))
+        .filter((p): p is { name: string; span: PluginSpan } => p.span !== null)
+        .sort((a, b) => b.span.startIdx - a.span.startIdx);
+      for (const p of ordered) {
+        next = next.slice(0, p.span.startIdx) + next.slice(p.span.endIdx);
+        removed.push(p.name);
+      }
+      if (next !== before) {
+        writer.writeText(abs, next);
+        actions.push({
+          file: rel,
+          kind: "rewrite-vite-config",
+          detail: `removed obsolete plugin(s): ${removed
+            .reverse()
+            .join(", ")}`,
+        });
+      }
+    }
+    return actions;
+  },
 };
 
+/**
+ * Span of an inline plugin object literal inside vite.config.ts that
+ * the auto-fixer should strip. Includes:
+ *
+ * - `startIdx`: position of the first attached `// ...` line above the
+ *   `{`, or the `{` itself if no leading comment is attached. Leading
+ *   indentation is included.
+ * - `endIdx`: exclusive — points just past the trailing `,\n` (or `\n`
+ *   if there's no comma). The next character is the start of the next
+ *   plugin (or the closing `]`).
+ *
+ * Removing `[startIdx, endIdx)` produces a clean diff: comment + literal
+ * gone, no orphan separator, surrounding plugins still paired with their
+ * own commas / comments.
+ */
+type PluginSpan = { startIdx: number; endIdx: number };
+
+/**
+ * Brace-balanced search for an inline `{ name: "<plugin>", ... }`
+ * object literal inside a vite config. Properly skips over strings,
+ * template literals, line comments and block comments so it doesn't
+ * miscount braces inside e.g. a `config()` body that contains
+ * `{ build: { rollupOptions: ... } }` or template-string interpolation.
+ *
+ * Returns null when the plugin name isn't present, or when we can't
+ * walk the braces unambiguously (defensive — the rule's `run()` will
+ * still flag the finding for a manual fix).
+ */
+export function findInlineVitePluginSpan(
+  content: string,
+  pluginName: string,
+): PluginSpan | null {
+  const re = new RegExp(`name:\\s*(['"\`])${escapeRegex(pluginName)}\\1`);
+  const m = re.exec(content);
+  if (!m) return null;
+  const namePropIdx = m.index;
+
+  // Walk backwards from the name property to find the enclosing `{`.
+  // Track string / comment state so we don't false-match on `{` inside
+  // a string literal somewhere earlier in the file.
+  const openIdx = findEnclosingObjectOpen(content, namePropIdx);
+  if (openIdx < 0) return null;
+
+  // Walk forward from the open brace counting matching braces, again
+  // skipping strings / comments. Returns the index of the matching `}`.
+  const closeIdx = findMatchingClose(content, openIdx);
+  if (closeIdx < 0) return null;
+
+  // Compute trailingEnd: consume `,` (optional) then whitespace up to
+  // and including the first `\n` after the closing brace. If we never
+  // hit `\n`, just stop at the comma / next non-whitespace.
+  let trailingEnd = closeIdx + 1;
+  while (
+    trailingEnd < content.length &&
+    (content[trailingEnd] === " " || content[trailingEnd] === "\t")
+  ) {
+    trailingEnd++;
+  }
+  if (content[trailingEnd] === ",") trailingEnd++;
+  while (
+    trailingEnd < content.length &&
+    (content[trailingEnd] === " " || content[trailingEnd] === "\t")
+  ) {
+    trailingEnd++;
+  }
+  if (content[trailingEnd] === "\n") trailingEnd++;
+
+  // Compute leadingStart: walk backwards over consecutive `//`-only
+  // lines that are immediately attached to the `{` (no blank line
+  // between them and the literal). Block comments are left alone.
+  const leadingStart = findAttachedLeadingComments(content, openIdx);
+
+  return { startIdx: leadingStart, endIdx: trailingEnd };
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Walk backwards from `fromIdx` to find the index of the `{` that
+ * opens the object literal currently containing `fromIdx`. Returns
+ * -1 if no such `{` is found before the start of the file or if
+ * the walk is too ambiguous (mismatched balance).
+ *
+ * Skips over string, template-literal and comment regions so braces
+ * inside those don't affect the count.
+ */
+function findEnclosingObjectOpen(content: string, fromIdx: number): number {
+  // Strategy: scan the file from the start to fromIdx, maintaining a
+  // stack of open `{` positions, skipping inside strings/comments.
+  // The top of the stack at fromIdx is our enclosing open.
+  const stack: number[] = [];
+  let i = 0;
+  const n = Math.min(content.length, fromIdx);
+  while (i < n) {
+    const ch = content[i];
+    const next = content[i + 1];
+    if (ch === "/" && next === "/") {
+      i += 2;
+      while (i < n && content[i] !== "\n") i++;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < n && !(content[i] === "*" && content[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      const quote = ch;
+      i++;
+      while (i < n && content[i] !== quote) {
+        if (content[i] === "\\") i++;
+        i++;
+      }
+      i++;
+      continue;
+    }
+    if (ch === "`") {
+      i++;
+      while (i < n && content[i] !== "`") {
+        if (content[i] === "\\") {
+          i += 2;
+          continue;
+        }
+        if (content[i] === "$" && content[i + 1] === "{") {
+          i += 2;
+          // Recursively skip until matching `}` of the interpolation.
+          let depth = 1;
+          while (i < n && depth > 0) {
+            if (content[i] === "{") depth++;
+            else if (content[i] === "}") depth--;
+            if (depth === 0) break;
+            i++;
+          }
+        }
+        i++;
+      }
+      i++;
+      continue;
+    }
+    if (ch === "{") {
+      stack.push(i);
+      i++;
+      continue;
+    }
+    if (ch === "}") {
+      stack.pop();
+      i++;
+      continue;
+    }
+    i++;
+  }
+  return stack.length > 0 ? stack[stack.length - 1] : -1;
+}
+
+/**
+ * From the `{` at `openIdx`, walk forward to find the matching `}`.
+ * Skips strings / template literals / comments.
+ */
+function findMatchingClose(content: string, openIdx: number): number {
+  let i = openIdx + 1;
+  let depth = 1;
+  const n = content.length;
+  while (i < n) {
+    const ch = content[i];
+    const next = content[i + 1];
+    if (ch === "/" && next === "/") {
+      i += 2;
+      while (i < n && content[i] !== "\n") i++;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      i += 2;
+      while (i < n && !(content[i] === "*" && content[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      const quote = ch;
+      i++;
+      while (i < n && content[i] !== quote) {
+        if (content[i] === "\\") i++;
+        i++;
+      }
+      i++;
+      continue;
+    }
+    if (ch === "`") {
+      i++;
+      while (i < n && content[i] !== "`") {
+        if (content[i] === "\\") {
+          i += 2;
+          continue;
+        }
+        if (content[i] === "$" && content[i + 1] === "{") {
+          i += 2;
+          let d = 1;
+          while (i < n && d > 0) {
+            if (content[i] === "{") d++;
+            else if (content[i] === "}") d--;
+            if (d === 0) break;
+            i++;
+          }
+        }
+        i++;
+      }
+      i++;
+      continue;
+    }
+    if (ch === "{") {
+      depth++;
+      i++;
+      continue;
+    }
+    if (ch === "}") {
+      depth--;
+      if (depth === 0) return i;
+      i++;
+      continue;
+    }
+    i++;
+  }
+  return -1;
+}
+
+/**
+ * Walk backwards from `openIdx` consuming the contiguous block of
+ * `//`-only lines immediately preceding the `{`. Stops at the first
+ * blank line, the first non-comment line, or block-comment territory.
+ * Returns the absolute index where the leading comment block (plus
+ * its indentation) starts — equal to `openIdx` minus its own line's
+ * indentation when no comment is attached.
+ */
+function findAttachedLeadingComments(content: string, openIdx: number): number {
+  // Walk back to start of the line containing `{`.
+  let lineStart = openIdx;
+  while (lineStart > 0 && content[lineStart - 1] !== "\n") lineStart--;
+  // Now climb up: each iteration considers the line ending at
+  // `lineStart - 1`. If it is a `//`-only line, include it; else stop.
+  let cursor = lineStart;
+  while (cursor > 0) {
+    const prevLineEnd = cursor - 1; // index of the `\n` separating
+    if (prevLineEnd <= 0) break;
+    let prevLineStart = prevLineEnd;
+    while (prevLineStart > 0 && content[prevLineStart - 1] !== "\n") {
+      prevLineStart--;
+    }
+    const line = content.slice(prevLineStart, prevLineEnd);
+    if (/^\s*\/\/.*$/.test(line)) {
+      cursor = prevLineStart;
+      continue;
+    }
+    break;
+  }
+  return cursor;
+}
+
 /* ------------------------------------------------------------------ */
 /* Rule 3 — dead `src/runtime.ts` invoke shim                          */
 /* ------------------------------------------------------------------ */

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

@@ -591,6 +591,7 @@ describe("runAudit — totals", () => {
         "dead-lib-shims",
         "dead-runtime-shim",
         "local-widgets-types",
+        "obsolete-vite-plugins",
         "vtex-shim-regression",
       ].sort(),
     );
@@ -804,3 +805,184 @@ describe("runAudit — fix mode — vtex-shim-regression swap cases", () => {
     );
   });
 });
+
+/* ------------------------------------------------------------------ */
+/* W12-F — obsolete-vite-plugins --fix                                 */
+/* ------------------------------------------------------------------ */
+
+describe("runAudit — fix mode — obsolete-vite-plugins", () => {
+  it("removes a single inline obsolete plugin literal cleanly", () => {
+    const before = `import { defineConfig } from "vite";
+export default defineConfig({
+  plugins: [
+    react(),
+    {
+      name: "site-manual-chunks",
+      config(_cfg, { command }) {
+        if (command !== "build") return;
+        return { build: { rollupOptions: { output: { manualChunks(_id: string) {} } } } };
+      },
+    },
+    tailwindcss(),
+  ],
+});
+`;
+    const { fs, writer, store } = makeMutableFs({
+      "/site/vite.config.ts": before,
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "obsolete-vite-plugins")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.fixes).toHaveLength(1);
+    expect(r.fixes![0].kind).toBe("rewrite-vite-config");
+    expect(r.fixes![0].detail).toContain("site-manual-chunks");
+    const after = store["/site/vite.config.ts"];
+    // Plugin literal is gone; siblings remain intact.
+    expect(after).not.toContain('name: "site-manual-chunks"');
+    expect(after).toContain("react()");
+    expect(after).toContain("tailwindcss()");
+    // The literal's body has been fully unindented out — no dangling braces.
+    expect(after).not.toContain("manualChunks(_id");
+  });
+
+  it("removes the leading `//` comment block attached to the plugin literal", () => {
+    const before = `export default defineConfig({
+  plugins: [
+    decoVitePlugin(),
+    // Override decoVitePlugin's default manualChunks — circular deps
+    // would crash if split.
+    // (mirrors the framework's improved splitting)
+    {
+      name: "site-manual-chunks",
+      config() { return {}; },
+    },
+    tailwindcss(),
+  ],
+});
+`;
+    const { fs, writer, store } = makeMutableFs({
+      "/site/vite.config.ts": before,
+    });
+    runAudit(SITE, fs, { writer });
+    const after = store["/site/vite.config.ts"];
+    expect(after).not.toContain("Override decoVitePlugin");
+    expect(after).not.toContain("circular deps");
+    expect(after).not.toContain("framework's improved splitting");
+    expect(after).not.toContain("site-manual-chunks");
+    // decoVitePlugin call still there, no orphan separator left behind.
+    expect(after).toContain("decoVitePlugin(),");
+    expect(after).toContain("tailwindcss()");
+    expect(after).not.toMatch(/,\s*,/);
+  });
+
+  it("removes BOTH obsolete plugins in one pass without disturbing each other", () => {
+    const before = `export default defineConfig({
+  plugins: [
+    decoVitePlugin(),
+    // chunks override
+    {
+      name: "site-manual-chunks",
+      config() { return {}; },
+    },
+    // meta.gen client stub
+    {
+      name: "deco-stub-meta-gen",
+      enforce: "pre" as const,
+      load(id: string) { if (id === "x") return "export default {}"; },
+    },
+    tailwindcss(),
+  ],
+});
+`;
+    const { fs, writer, store } = makeMutableFs({
+      "/site/vite.config.ts": before,
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "obsolete-vite-plugins")!;
+    expect(r.findings).toHaveLength(2);
+    expect(r.fixes).toHaveLength(1);
+    expect(r.fixes![0].detail).toContain("site-manual-chunks");
+    expect(r.fixes![0].detail).toContain("deco-stub-meta-gen");
+    const after = store["/site/vite.config.ts"];
+    expect(after).not.toContain("site-manual-chunks");
+    expect(after).not.toContain("deco-stub-meta-gen");
+    expect(after).not.toContain("chunks override");
+    expect(after).not.toContain("meta.gen client stub");
+    expect(after).toContain("decoVitePlugin(),");
+    expect(after).toContain("tailwindcss()");
+  });
+
+  it("does not miscount braces inside template literals or strings inside the plugin body", () => {
+    // Template literal containing `${'}'}` and string with `}` must not
+    // throw off the brace walker.
+    const before = `export default defineConfig({
+  plugins: [
+    {
+      name: "site-manual-chunks",
+      load(id: string) {
+        const a = \`a\${'}'}b\`;
+        const b = "}";
+        return id + a + b;
+      },
+    },
+    tailwindcss(),
+  ],
+});
+`;
+    const { fs, writer, store } = makeMutableFs({
+      "/site/vite.config.ts": before,
+    });
+    runAudit(SITE, fs, { writer });
+    const after = store["/site/vite.config.ts"];
+    expect(after).not.toContain("site-manual-chunks");
+    expect(after).toContain("tailwindcss()");
+    // Sanity: closing brackets of defineConfig + plugins array preserved.
+    expect(after).toContain("],");
+    expect(after.trim().endsWith("});")).toBe(true);
+  });
+
+  it("is a no-op (no fixes) when no obsolete plugins are present", () => {
+    const before = `export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+`;
+    const { fs, writer, store } = makeMutableFs({
+      "/site/vite.config.ts": before,
+    });
+    const report = runAudit(SITE, fs, { writer });
+    const r = report.rules.find((r) => r.rule === "obsolete-vite-plugins")!;
+    expect(r.findings).toEqual([]);
+    expect(r.fixes).toBeUndefined();
+    expect(store["/site/vite.config.ts"]).toBe(before);
+  });
+
+  it("is idempotent — running --fix twice is a no-op the second time", () => {
+    const before = `export default defineConfig({
+  plugins: [
+    decoVitePlugin(),
+    {
+      name: "deco-stub-meta-gen",
+      load() { return "export default {};"; },
+    },
+    tailwindcss(),
+  ],
+});
+`;
+    const { fs, writer, store } = makeMutableFs({
+      "/site/vite.config.ts": before,
+    });
+    runAudit(SITE, fs, { writer });
+    const afterFirst = store["/site/vite.config.ts"];
+    runAudit(SITE, fs, { writer });
+    expect(store["/site/vite.config.ts"]).toBe(afterFirst);
+  });
+
+  it("includes obsolete-vite-plugins in supportsAutoFix", () => {
+    const fs = makeFs({});
+    const report = runAudit(SITE, fs);
+    const supported = report.rules
+      .filter((r) => r.supportsAutoFix)
+      .map((r) => r.rule);
+    expect(supported).toContain("obsolete-vite-plugins");
+  });
+});

package/scripts/migrate/templates/cursor-rules.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { generateMigrationPolicyPointerRule } from "./cursor-rules";
+
+describe("generateMigrationPolicyPointerRule", () => {
+	const body = generateMigrationPolicyPointerRule("acme");
+
+	it("emits a Cursor MDC rule with alwaysApply: true frontmatter", () => {
+		expect(body.startsWith("---\n")).toBe(true);
+		expect(body).toContain("alwaysApply: true");
+		expect(body).toContain("description:");
+	});
+
+	it("interpolates the site name into the body", () => {
+		expect(body).toContain("`acme`");
+	});
+
+	it("links to the canonical rule and plan in decocms/deco-start", () => {
+		expect(body).toContain(
+			"https://github.com/decocms/deco-start/blob/main/.cursor/rules/migration-tooling-policy.mdc",
+		);
+		expect(body).toContain(
+			"https://github.com/decocms/deco-start/blob/main/MIGRATION_TOOLING_PLAN.md",
+		);
+	});
+
+	it("documents D1–D5 by ID, not just by name", () => {
+		expect(body).toContain("**D1**");
+		expect(body).toContain("**D2**");
+		expect(body).toContain("**D3**");
+		expect(body).toContain("**D4**");
+		expect(body).toContain("**D5**");
+	});
+
+	it("points at the post-cleanup --fix command rather than restating policy", () => {
+		expect(body).toContain("deco-post-cleanup --fix");
+		expect(body).toContain("deco-post-cleanup --strict");
+	});
+
+	it("does NOT restate the canonical rule body verbatim (pointer, not a copy)", () => {
+		// Length budget: pointer must stay short to discourage drift.
+		// The canonical rule in decocms/deco-start is ~110 lines / 4–5 KB;
+		// the pointer must be substantially smaller than a copy.
+		expect(body.length).toBeLessThan(3000);
+	});
+
+	it("is deterministic — same site name, same output", () => {
+		const a = generateMigrationPolicyPointerRule("foo");
+		const b = generateMigrationPolicyPointerRule("foo");
+		expect(a).toBe(b);
+	});
+
+	it("escapes nothing weird from siteName — siteName is used as a label only", () => {
+		// We don't sanitise; we trust the migration script to pass a real
+		// package name. But verify nothing surprising happens with hyphens
+		// (a common shape, e.g. "casaevideo-storefront").
+		const out = generateMigrationPolicyPointerRule("casaevideo-storefront");
+		expect(out).toContain("`casaevideo-storefront`");
+	});
+});

package/scripts/migrate/templates/cursor-rules.ts

@@ -0,0 +1,70 @@
+/**
+ * Cursor rule scaffolding for migrated sites.
+ *
+ * The canonical migration tooling policy (D1–D5, priorities, process)
+ * lives in `decocms/deco-start`. We don't duplicate it into every site
+ * — that would drift the moment the canonical changes. Instead the
+ * migration scaffolds a tiny pointer rule, marked `alwaysApply: true`,
+ * that loads on every agent session inside the migrated site and tells
+ * the agent where the real policy lives.
+ *
+ * Closes Wave 12-H from MIGRATION_TOOLING_PLAN.md.
+ */
+
+/**
+ * Generate the contents of `.cursor/rules/migration-tooling-policy.mdc`
+ * for a freshly migrated site. Pure function: `siteName` is the only
+ * input that influences the body, and only as a friendly mention.
+ */
+export function generateMigrationPolicyPointerRule(
+	siteName: string,
+): string {
+	return `---
+description: Pointer to the canonical migration tooling policy (D1–D5, PR-only, etc.). Always loaded.
+alwaysApply: true
+---
+
+# Migration Tooling Policy — Pointer
+
+> This site (\`${siteName}\`) was generated by the \`@decocms/start\`
+> migration script. The canonical policy that governs how the migration
+> tooling, framework (\`@decocms/start\`), and commerce layer
+> (\`@decocms/apps\`) evolve lives **upstream**, not in this repo.
+
+## Where to read
+
+- **Rule (always-applied) — full text:**
+  https://github.com/decocms/deco-start/blob/main/.cursor/rules/migration-tooling-policy.mdc
+- **Plan (living tracker, decisions + waves):**
+  https://github.com/decocms/deco-start/blob/main/MIGRATION_TOOLING_PLAN.md
+- **Migration skill (phase playbook):**
+  \`@decocms/start/.agents/skills/deco-to-tanstack-migration\`
+
+## What you need to know in this site
+
+| ID | Decision | What it means here |
+|----|----------|--------------------|
+| **D1** | Force convergence — no fork runtime support | Site customisations live in \`src/apps/local/\` or open a PR to \`@decocms/apps\`. Don't wrap framework/commerce code in soft adapters. |
+| **D2** | Rewrite HTMX on migration | If you find HTMX residue, rewrite to React. Don't bring back \`hx-*\` runtime. |
+| **D3** | Generated stubs throw at runtime | If a \`~/lib/vtex-*\` import comes from a stub that returns \`null\` / \`{}\` / identity-cast, replace it. \`npx -p @decocms/start deco-post-cleanup --fix\` does the safe swaps automatically. |
+| **D4** | Site-local apps by default, promote at 3+ sites | Don't try to upstream a pattern that has only shipped here. Build it twice in different sites first, then PR it to \`@decocms/apps\`. |
+| **D5** | Failed migrations: \`rm -rf\` and re-run | No restart-mode magic. If the migration goes sideways, blow away the working tree and run again. |
+
+## How to find issues this rule wants you to fix
+
+\`\`\`bash
+npx -p @decocms/start deco-post-cleanup           # audit only
+npx -p @decocms/start deco-post-cleanup --fix     # auto-fix the safe rules
+npx -p @decocms/start deco-post-cleanup --strict  # exit 1 on any finding (CI)
+\`\`\`
+
+## Process
+
+- **PR-only.** No direct pushes to \`main\`. Self-merge after green CI is fine.
+- **Conventional commits** (\`feat\`, \`fix\`, \`chore\`, \`docs\`, \`refactor\`, \`test\`, \`perf\`).
+- **CI must be green before merge.**
+- When the canonical rule changes upstream, update this pointer if any
+  link or table heading goes stale. Keep it short — body content lives
+  upstream.
+`;
+}