/**
 * Cursor rule scaffolding for migrated sites.
 *
 * The canonical migration tooling policy (D1–D5, priorities, process)
 * lives in `decocms/blocks`. 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/blocks-cli\`
> migration script (\`deco-migrate\`). The canonical policy that governs how
> the migration tooling, framework (\`@decocms/blocks\` + \`@decocms/tanstack\`),
> and commerce layer (\`@decocms/apps-*\`) evolve lives **upstream**, not in
> this repo.

## Where to read

- **Rule (always-applied) — full text:**
  https://github.com/decocms/blocks/blob/main/.cursor/rules/migration-tooling-policy.mdc
- **Plan (living tracker, decisions + waves):**
  https://github.com/decocms/blocks/blob/main/MIGRATION_TOOLING_PLAN.md
- **Migration skill (phase playbook):**
  https://github.com/decocms/blocks/blob/main/.agents/skills/deco-to-tanstack-migration/SKILL.md

## 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/blocks-cli 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/blocks-cli deco-post-cleanup           # audit only
npx -p @decocms/blocks-cli deco-post-cleanup --fix     # auto-fix the safe rules
npx -p @decocms/blocks-cli 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.
`;
}