aeon-ui-engine 1.3.5 → 1.5.1

package/packages/cli/dist/chunk-JMNRJCWF.js

@@ -0,0 +1,301 @@
+// src/init.ts
+import { mkdirSync, writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import {
+  CURSOR_RULES_SNIPPET,
+  AEON_SYSTEM_PROMPT,
+  catalog,
+  componentSchemas
+} from "@aeon-ui/schemas";
+var STARTER = `/**
+ * Aeon UI starter \u2014 generated by \`npx aeon-ui init\`
+ * Headless: @aeon-ui/react \xB7 Styled: @aeon-ui/ui \xB7 Schemas: @aeon-ui/schemas
+ */
+import { Button, Field } from '@aeon-ui/ui'
+
+export function AeonStarter() {
+  return (
+    <div>
+      <Field.Root>
+        <Field.Label>Email</Field.Label>
+        <Field.Control type="email" placeholder="you@example.com" />
+        <Field.Message />
+      </Field.Root>
+      <Button.Root status="idle">Continue</Button.Root>
+    </div>
+  )
+}
+`;
+function initAeon(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const force = options.force ?? false;
+  const written = [];
+  const write = (rel, body) => {
+    const path = join(cwd, rel);
+    if (existsSync(path) && !force) {
+      written.push(`skip ${rel} (exists)`);
+      return;
+    }
+    mkdirSync(join(path, ".."), { recursive: true });
+    writeFileSync(path, body.endsWith("\n") ? body : `${body}
+`);
+    written.push(`write ${rel}`);
+  };
+  write(".cursor/rules/aeon-ui.mdc", `---
+description: Aeon UI \u2014 statechart-driven components for AI agents
+globs: **/*.{tsx,ts,jsx,js}
+alwaysApply: true
+---
+
+${CURSOR_RULES_SNIPPET.trim()}
+`);
+  write("aeon.cursorrules.md", `${CURSOR_RULES_SNIPPET.trim()}
+`);
+  write("aeon.system-prompt.md", `${AEON_SYSTEM_PROMPT.trim()}
+`);
+  write(
+    "aeon.schemas/catalog.json",
+    `${JSON.stringify(
+      {
+        $id: catalog.$id,
+        title: catalog.title,
+        description: catalog.description,
+        version: catalog.version,
+        principle: catalog.principle,
+        attributes: catalog.attributes,
+        components: catalog.components,
+        note: "Full schemas live under aeon.schemas/components/*.json"
+      },
+      null,
+      2
+    )}
+`
+  );
+  for (const [id, schema] of Object.entries(componentSchemas)) {
+    write(`aeon.schemas/components/${id}.json`, `${JSON.stringify(schema, null, 2)}
+`);
+  }
+  write("src/components/AeonStarter.tsx", STARTER);
+  write(
+    "AEON_AI.md",
+    `# Aeon UI \u2014 AI agent setup
+
+Generated by \`npx aeon-ui init\`.
+
+## Next steps
+
+1. Install: \`npm install aeon-ui-engine react react-dom xstate @xstate/react\`
+   - Postinstall links \`@aeon-ui/*\` into \`node_modules\` (re-run with \`npx aeon-ui link\` if needed).
+2. CSS: \`import 'aeon-ui-engine/aeon.css'\` (e.g. root layout).
+3. **Next.js:** add \`transpilePackages\` for \`@aeon-ui/ui\`, \`@aeon-ui/react\`, \`@aeon-ui/core\`, \`@aeon-ui/primitives\`, \`@aeon-ui/panda\`. Use \`"use client"\` for interactive components. No webpack aliases required.
+4. **Vite (optional):** \`aeonUiVitePlugin()\` from \`aeon-ui-engine/vite\` still helps with optimizeDeps; scoped imports resolve via the link step alone.
+5. Paste \`aeon.cursorrules.md\` into Cursor rules / system prompt (already mirrored to \`.cursor/rules/aeon-ui.mdc\`)
+6. Constrain generation with JSON under \`aeon.schemas/\`
+
+## Frameworks
+
+Aeon is **React-first** (full catalog + styled layer). Next.js is supported. Vue / Solid / Svelte adapters exist but are thin \u2014 not the main product.
+
+## Principle
+
+**UI = f(state)** \u2014 never invent boolean combinations for states the schema does not list.
+`
+  );
+  return { cwd, written };
+}
+
+// src/link.ts
+import { spawnSync } from "child_process";
+import { createRequire } from "module";
+import { existsSync as existsSync2 } from "fs";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+function resolveLinkScript() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const fromMonorepo = join2(here, "../../../scripts/link-scoped-packages.mjs");
+  if (existsSync2(fromMonorepo)) return fromMonorepo;
+  try {
+    const require2 = createRequire(import.meta.url);
+    const engineRoot = dirname(require2.resolve("aeon-ui-engine/package.json"));
+    return join2(engineRoot, "scripts/link-scoped-packages.mjs");
+  } catch {
+    throw new Error(
+      "Could not find scripts/link-scoped-packages.mjs (aeon-ui-engine not installed?)"
+    );
+  }
+}
+function linkAeon(options = {}) {
+  const script = resolveLinkScript();
+  const args = [script];
+  if (options.cwd) {
+    args.push("--cwd", options.cwd);
+  }
+  if (options.quiet) {
+    args.push("--quiet");
+  }
+  if (options.force) {
+    args.push("--force");
+  }
+  const result = spawnSync(process.execPath, args, {
+    stdio: options.quiet ? "pipe" : "inherit",
+    env: process.env,
+    cwd: options.cwd ?? process.cwd()
+  });
+  if (result.status !== 0 && result.status !== null) {
+    const err = result.stderr?.toString() || `link exited with code ${result.status}`;
+    throw new Error(err);
+  }
+  return {
+    cwd: options.cwd ?? process.cwd(),
+    status: result.status ?? 0
+  };
+}
+
+// src/migrate.ts
+import { existsSync as existsSync3, readFileSync, writeFileSync as writeFileSync2 } from "fs";
+import { join as join3 } from "path";
+var FINDINGS = [
+  {
+    id: "preview-window-machine",
+    severity: "replace",
+    patterns: ["preview-window-machine", "previewWindowMachine"],
+    advice: "Replace with RangeSlider from @aeon-ui/react or @aeon-ui/ui (rangeSliderMachine)."
+  },
+  {
+    id: "file-dropzone",
+    severity: "replace",
+    patterns: ["file-dropzone-machine", "fileDropzoneMachine", "FileDropzone"],
+    advice: "Replace with FileUpload compound (fileUploadMachine) \u2014 idle | dragging | rejected."
+  },
+  {
+    id: "sonner-bridge",
+    severity: "replace",
+    patterns: ["from 'sonner'", 'from "sonner"', "components/ui/sonner"],
+    advice: "Use Toast.Provider + useToast().publish / dismiss (aeon-ui-engine \u2265 1.2)."
+  },
+  {
+    id: "manual-link-button",
+    severity: "optional",
+    patterns: ['data-aeon-scope="button"', "buttonVariants("],
+    advice: "Prefer <Button.Root asChild><Link \u2026 /></Button.Root> instead of hand-rolled data-aeon-* on anchors."
+  },
+  {
+    id: "chakra",
+    severity: "info",
+    patterns: ["@chakra-ui/react", "@ark-ui/react"],
+    advice: "Migrate leaf \u2192 forms \u2192 overlays per docs/MIGRATION_FROM_ARK.md; see docs/MIGRATION.md for greenfield checklist."
+  },
+  {
+    id: "alert-dialog-local",
+    severity: "optional",
+    patterns: ["alertDialogMachine", 'role="alertdialog"'],
+    advice: "Prefer Dialog/Prompt with dismissible=false for destructive confirms until AlertDialog ships."
+  }
+];
+var CANDIDATES = [
+  "package.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "lib/preview-window-machine.ts",
+  "lib/file-dropzone-machine.ts",
+  "components/file-dropzone.tsx",
+  "components/ui/sonner.tsx",
+  "components/ui/alert-dialog.tsx",
+  "components/ui/slider.tsx",
+  "components/ui/button.tsx",
+  "components/dual-login-buttons.tsx"
+];
+function walkHints(cwd) {
+  const hits = [];
+  let corpus = "";
+  for (const rel of CANDIDATES) {
+    const abs = join3(cwd, rel);
+    if (!existsSync3(abs)) continue;
+    try {
+      corpus += `
+${rel}
+${readFileSync(abs, "utf8")}`;
+    } catch {
+    }
+  }
+  for (const rule of FINDINGS) {
+    const matched = rule.patterns.find((p) => corpus.includes(p));
+    if (matched) {
+      hits.push({
+        id: rule.id,
+        severity: rule.severity,
+        pattern: matched,
+        advice: rule.advice
+      });
+    }
+  }
+  return hits;
+}
+var CHECKLIST = `# Aeon migration checklist
+
+Generated by \`npx aeon-ui migrate\`.
+
+## Install
+
+\`\`\`bash
+npm install aeon-ui-engine@^1.4.0 react react-dom xstate @xstate/react
+\`\`\`
+
+\`\`\`ts
+import 'aeon-ui-engine/aeon.css'
+\`\`\`
+
+## Agent setup
+
+\`\`\`bash
+npx aeon-ui init
+\`\`\`
+
+Paste \`aeon.cursorrules.md\` into Cursor rules. Keep domain machines in the app; use Aeon for chrome + interactive primitives.
+
+## Statechart-first rule
+
+1. Model interaction with an XState machine (or reuse Aeon machines).
+2. Project \`snapshot\` \u2192 \`data-aeon-state\` / compound parts.
+3. Do not invent parallel booleans for chart-owned concerns.
+
+## New primitives (1.4+)
+
+| Need | Use |
+|------|-----|
+| Two-thumb range | \`RangeSlider\` + \`rangeSliderMachine\` |
+| Link styled as button | \`<Button.Root asChild><Link/></Button.Root>\` |
+| Drag-drop file surface | \`FileUpload\` + \`fileUploadMachine\` |
+| Toast | \`Toast.Provider\` + \`useToast()\` |
+| Confirm sheet | \`Prompt\` / \`Dialog\` |
+
+## Docs
+
+- docs/MIGRATION.md (in aeon-ui-engine / AeonUI repo)
+- docs/MIGRATION_FROM_ARK.md
+- AGENTS.md
+`;
+function migrateAeon(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const write = options.write ?? true;
+  const findings = walkHints(cwd);
+  const written = [];
+  if (write) {
+    const path = join3(cwd, "AEON_MIGRATION_CHECKLIST.md");
+    const findingsBlock = findings.length === 0 ? "\n## Scan results\n\nNo known local workarounds detected in the quick scan.\n" : `
+## Scan results
+
+${findings.map((f) => `- **${f.severity}** \`${f.id}\` (matched \`${f.pattern}\`): ${f.advice}`).join("\n")}
+`;
+    writeFileSync2(path, `${CHECKLIST.trim()}
+${findingsBlock}`);
+    written.push("write AEON_MIGRATION_CHECKLIST.md");
+  }
+  return { cwd, written, findings };
+}
+
+export {
+  initAeon,
+  linkAeon,
+  migrateAeon
+};

package/packages/cli/dist/index.d.ts

@@ -7,4 +7,34 @@ declare function initAeon(options?: InitOptions): {
     written: string[];
 };
 
-export { type InitOptions, initAeon };
+type LinkOptions = {
+    cwd?: string;
+    quiet?: boolean;
+    force?: boolean;
+};
+/**
+ * Symlink `node_modules/@aeon-ui/*` → `aeon-ui-engine/packages/*`.
+ * Prefer the postinstall hook; this command re-runs linking manually.
+ */
+declare function linkAeon(options?: LinkOptions): {
+    cwd: string;
+    status: number;
+};
+
+type MigrateOptions = {
+    cwd?: string;
+    write?: boolean;
+};
+type Finding = {
+    id: string;
+    severity: 'replace' | 'optional' | 'info';
+    pattern: string;
+    advice: string;
+};
+declare function migrateAeon(options?: MigrateOptions): {
+    cwd: string;
+    written: string[];
+    findings: Finding[];
+};
+
+export { type InitOptions, type LinkOptions, type MigrateOptions, initAeon, linkAeon, migrateAeon };

package/packages/cli/dist/index.js

@@ -1,6 +1,10 @@
 import {
-  initAeon
-} from "./chunk-IW5NT2Z2.js";
+  initAeon,
+  linkAeon,
+  migrateAeon
+} from "./chunk-JMNRJCWF.js";
 export {
-  initAeon
+  initAeon,
+  linkAeon,
+  migrateAeon
 };

package/packages/cli/src/bin.ts

@@ -1,31 +1,77 @@
 #!/usr/bin/env node
 import { initAeon } from './init.js'
+import { linkAeon } from './link.js'
+import { migrateAeon } from './migrate.js'
 
 const args = process.argv.slice(2)
 const cmd = args[0] ?? 'help'
 const force = args.includes('--force') || args.includes('-f')
+const checkOnly = args.includes('--check')
+const quiet = args.includes('--quiet') || args.includes('-q')
+
+function argValue(flag: string): string | undefined {
+  const i = args.indexOf(flag)
+  if (i >= 0 && args[i + 1] && !args[i + 1].startsWith('-')) return args[i + 1]
+  return undefined
+}
+
+const cwdArg = argValue('--cwd')
 
 function help() {
   console.log(`aeon-ui — AI-optimized CLI for Aeon UI
 
 Usage:
   npx aeon-ui init [--force]
+  npx aeon-ui link [--quiet] [--force] [--cwd <dir>]
+  npx aeon-ui migrate [--check]
 
 Commands:
-  init    Inject Cursor rules, JSON schemas, system prompt, and a starter component
-  help    Show this message
+  init       Inject Cursor rules, JSON schemas, system prompt, and a starter component
+  link       Symlink node_modules/@aeon-ui/* → aeon-ui-engine/packages/* (also runs on postinstall)
+  migrate    Scan for known workarounds and write AEON_MIGRATION_CHECKLIST.md
+  help       Show this message
 
 Options:
-  --force, -f   Overwrite existing generated files
+  --force, -f   Overwrite existing generated files (init); replace existing @aeon-ui links (link)
+  --check       Report findings only; do not write checklist (migrate)
+  --quiet, -q   Suppress link output (link)
+  --cwd <dir>   Project root for link (defaults to process.cwd())
 `)
 }
 
 if (cmd === 'init') {
-  const result = initAeon({ force })
+  const result = initAeon({ force, cwd: cwdArg })
   console.log(`Aeon UI init → ${result.cwd}`)
   for (const line of result.written) console.log(`  ${line}`)
+  try {
+    linkAeon({ cwd: result.cwd, quiet: true })
+    console.log('  link @aeon-ui/* (scoped packages)')
+  } catch {
+    console.log('  link skipped (install aeon-ui-engine first, then: npx aeon-ui link)')
+  }
   console.log('\nNext: npm install aeon-ui-engine react react-dom xstate @xstate/react')
   console.log('Docs: AEON_AI.md · paste aeon.cursorrules.md into your agent system prompt')
+} else if (cmd === 'link') {
+  try {
+    const result = linkAeon({ quiet, force, cwd: cwdArg })
+    if (quiet) console.log(`Aeon UI link → ${result.cwd}`)
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : err)
+    process.exitCode = 1
+  }
+} else if (cmd === 'migrate') {
+  const result = migrateAeon({ write: !checkOnly })
+  console.log(`Aeon UI migrate → ${result.cwd}`)
+  for (const line of result.written) console.log(`  ${line}`)
+  if (result.findings.length === 0) {
+    console.log('  (no known workarounds matched in quick scan)')
+  } else {
+    for (const f of result.findings) {
+      console.log(`  [${f.severity}] ${f.id}: ${f.advice}`)
+    }
+  }
+  console.log('\nInstall: npm install aeon-ui-engine@^1.4.0 xstate @xstate/react')
+  console.log('Docs: https://aeon-ui.com · repo docs/MIGRATION.md')
 } else {
   help()
   if (cmd !== 'help' && cmd !== '--help' && cmd !== '-h') {

package/packages/cli/src/index.ts

@@ -1 +1,3 @@
 export { initAeon, type InitOptions } from './init.js'
+export { linkAeon, type LinkOptions } from './link.js'
+export { migrateAeon, type MigrateOptions } from './migrate.js'

package/packages/cli/src/init.ts

@@ -92,10 +92,16 @@ Generated by \`npx aeon-ui init\`.
 ## Next steps
 
 1. Install: \`npm install aeon-ui-engine react react-dom xstate @xstate/react\`
-2. CSS: \`import 'aeon-ui-engine/aeon.css'\`
-3. Vite: add \`aeonUiVitePlugin()\` from \`aeon-ui-engine/vite\`
-4. Paste \`aeon.cursorrules.md\` into Cursor rules / system prompt (already mirrored to \`.cursor/rules/aeon-ui.mdc\`)
-5. Constrain generation with JSON under \`aeon.schemas/\`
+   - Postinstall links \`@aeon-ui/*\` into \`node_modules\` (re-run with \`npx aeon-ui link\` if needed).
+2. CSS: \`import 'aeon-ui-engine/aeon.css'\` (e.g. root layout).
+3. **Next.js:** add \`transpilePackages\` for \`@aeon-ui/ui\`, \`@aeon-ui/react\`, \`@aeon-ui/core\`, \`@aeon-ui/primitives\`, \`@aeon-ui/panda\`. Use \`"use client"\` for interactive components. No webpack aliases required.
+4. **Vite (optional):** \`aeonUiVitePlugin()\` from \`aeon-ui-engine/vite\` still helps with optimizeDeps; scoped imports resolve via the link step alone.
+5. Paste \`aeon.cursorrules.md\` into Cursor rules / system prompt (already mirrored to \`.cursor/rules/aeon-ui.mdc\`)
+6. Constrain generation with JSON under \`aeon.schemas/\`
+
+## Frameworks
+
+Aeon is **React-first** (full catalog + styled layer). Next.js is supported. Vue / Solid / Svelte adapters exist but are thin — not the main product.
 
 ## Principle
 

package/packages/cli/src/link.ts

@@ -0,0 +1,61 @@
+import { spawnSync } from 'node:child_process'
+import { createRequire } from 'node:module'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export type LinkOptions = {
+  cwd?: string
+  quiet?: boolean
+  force?: boolean
+}
+
+function resolveLinkScript(): string {
+  const here = dirname(fileURLToPath(import.meta.url))
+  const fromMonorepo = join(here, '../../../scripts/link-scoped-packages.mjs')
+  if (existsSync(fromMonorepo)) return fromMonorepo
+
+  try {
+    const require = createRequire(import.meta.url)
+    const engineRoot = dirname(require.resolve('aeon-ui-engine/package.json'))
+    return join(engineRoot, 'scripts/link-scoped-packages.mjs')
+  } catch {
+    throw new Error(
+      'Could not find scripts/link-scoped-packages.mjs (aeon-ui-engine not installed?)',
+    )
+  }
+}
+
+/**
+ * Symlink `node_modules/@aeon-ui/*` → `aeon-ui-engine/packages/*`.
+ * Prefer the postinstall hook; this command re-runs linking manually.
+ */
+export function linkAeon(options: LinkOptions = {}) {
+  const script = resolveLinkScript()
+  const args = [script]
+  if (options.cwd) {
+    args.push('--cwd', options.cwd)
+  }
+  if (options.quiet) {
+    args.push('--quiet')
+  }
+  if (options.force) {
+    args.push('--force')
+  }
+
+  const result = spawnSync(process.execPath, args, {
+    stdio: options.quiet ? 'pipe' : 'inherit',
+    env: process.env,
+    cwd: options.cwd ?? process.cwd(),
+  })
+
+  if (result.status !== 0 && result.status !== null) {
+    const err = result.stderr?.toString() || `link exited with code ${result.status}`
+    throw new Error(err)
+  }
+
+  return {
+    cwd: options.cwd ?? process.cwd(),
+    status: result.status ?? 0,
+  }
+}

package/packages/cli/src/migrate.ts

@@ -0,0 +1,170 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+export type MigrateOptions = {
+  cwd?: string
+  write?: boolean
+}
+
+type Finding = {
+  id: string
+  severity: 'replace' | 'optional' | 'info'
+  pattern: string
+  advice: string
+}
+
+const FINDINGS: Array<{
+  id: string
+  severity: Finding['severity']
+  patterns: string[]
+  advice: string
+}> = [
+  {
+    id: 'preview-window-machine',
+    severity: 'replace',
+    patterns: ['preview-window-machine', 'previewWindowMachine'],
+    advice: 'Replace with RangeSlider from @aeon-ui/react or @aeon-ui/ui (rangeSliderMachine).',
+  },
+  {
+    id: 'file-dropzone',
+    severity: 'replace',
+    patterns: ['file-dropzone-machine', 'fileDropzoneMachine', 'FileDropzone'],
+    advice: 'Replace with FileUpload compound (fileUploadMachine) — idle | dragging | rejected.',
+  },
+  {
+    id: 'sonner-bridge',
+    severity: 'replace',
+    patterns: ["from 'sonner'", 'from "sonner"', 'components/ui/sonner'],
+    advice: 'Use Toast.Provider + useToast().publish / dismiss (aeon-ui-engine ≥ 1.2).',
+  },
+  {
+    id: 'manual-link-button',
+    severity: 'optional',
+    patterns: ['data-aeon-scope="button"', 'buttonVariants('],
+    advice:
+      'Prefer <Button.Root asChild><Link … /></Button.Root> instead of hand-rolled data-aeon-* on anchors.',
+  },
+  {
+    id: 'chakra',
+    severity: 'info',
+    patterns: ['@chakra-ui/react', '@ark-ui/react'],
+    advice:
+      'Migrate leaf → forms → overlays per docs/MIGRATION_FROM_ARK.md; see docs/MIGRATION.md for greenfield checklist.',
+  },
+  {
+    id: 'alert-dialog-local',
+    severity: 'optional',
+    patterns: ['alertDialogMachine', 'role="alertdialog"'],
+    advice:
+      'Prefer Dialog/Prompt with dismissible=false for destructive confirms until AlertDialog ships.',
+  },
+]
+
+const CANDIDATES = [
+  'package.json',
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'lib/preview-window-machine.ts',
+  'lib/file-dropzone-machine.ts',
+  'components/file-dropzone.tsx',
+  'components/ui/sonner.tsx',
+  'components/ui/alert-dialog.tsx',
+  'components/ui/slider.tsx',
+  'components/ui/button.tsx',
+  'components/dual-login-buttons.tsx',
+]
+
+function walkHints(cwd: string): Finding[] {
+  const hits: Finding[] = []
+  let corpus = ''
+
+  for (const rel of CANDIDATES) {
+    const abs = join(cwd, rel)
+    if (!existsSync(abs)) continue
+    try {
+      corpus += `\n${rel}\n${readFileSync(abs, 'utf8')}`
+    } catch {
+      /* ignore unreadable */
+    }
+  }
+
+  for (const rule of FINDINGS) {
+    const matched = rule.patterns.find((p) => corpus.includes(p))
+    if (matched) {
+      hits.push({
+        id: rule.id,
+        severity: rule.severity,
+        pattern: matched,
+        advice: rule.advice,
+      })
+    }
+  }
+
+  return hits
+}
+
+const CHECKLIST = `# Aeon migration checklist
+
+Generated by \`npx aeon-ui migrate\`.
+
+## Install
+
+\`\`\`bash
+npm install aeon-ui-engine@^1.4.0 react react-dom xstate @xstate/react
+\`\`\`
+
+\`\`\`ts
+import 'aeon-ui-engine/aeon.css'
+\`\`\`
+
+## Agent setup
+
+\`\`\`bash
+npx aeon-ui init
+\`\`\`
+
+Paste \`aeon.cursorrules.md\` into Cursor rules. Keep domain machines in the app; use Aeon for chrome + interactive primitives.
+
+## Statechart-first rule
+
+1. Model interaction with an XState machine (or reuse Aeon machines).
+2. Project \`snapshot\` → \`data-aeon-state\` / compound parts.
+3. Do not invent parallel booleans for chart-owned concerns.
+
+## New primitives (1.4+)
+
+| Need | Use |
+|------|-----|
+| Two-thumb range | \`RangeSlider\` + \`rangeSliderMachine\` |
+| Link styled as button | \`<Button.Root asChild><Link/></Button.Root>\` |
+| Drag-drop file surface | \`FileUpload\` + \`fileUploadMachine\` |
+| Toast | \`Toast.Provider\` + \`useToast()\` |
+| Confirm sheet | \`Prompt\` / \`Dialog\` |
+
+## Docs
+
+- docs/MIGRATION.md (in aeon-ui-engine / AeonUI repo)
+- docs/MIGRATION_FROM_ARK.md
+- AGENTS.md
+`
+
+export function migrateAeon(options: MigrateOptions = {}) {
+  const cwd = options.cwd ?? process.cwd()
+  const write = options.write ?? true
+  const findings = walkHints(cwd)
+  const written: string[] = []
+
+  if (write) {
+    const path = join(cwd, 'AEON_MIGRATION_CHECKLIST.md')
+    const findingsBlock =
+      findings.length === 0
+        ? '\n## Scan results\n\nNo known local workarounds detected in the quick scan.\n'
+        : `\n## Scan results\n\n${findings
+            .map((f) => `- **${f.severity}** \`${f.id}\` (matched \`${f.pattern}\`): ${f.advice}`)
+            .join('\n')}\n`
+    writeFileSync(path, `${CHECKLIST.trim()}\n${findingsBlock}`)
+    written.push('write AEON_MIGRATION_CHECKLIST.md')
+  }
+
+  return { cwd, written, findings }
+}