@agent-native/core 0.112.0 → 0.114.0

package/src/cli/migrate.ts

@@ -0,0 +1,1813 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+import {
+  appendCodeAgentTranscriptEvent,
+  codeAgentRunArtifactsDir,
+  createCodeAgentRunRecord,
+  getLastCodeAgentRunRecord,
+  listCodeAgentRunRecords,
+  writeCodeAgentRunRecord,
+  type CodeAgentRunRecord,
+} from "./code-agent-runs.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const DEFAULT_APP_NAME = "migration";
+const DEFAULT_OUTPUT = "../migrated-app";
+const DEFAULT_TARGET = "agent-native";
+const DEFAULT_DOSSIER_DIR = "agent-native-migration-dossier";
+const MIGRATION_DEV_PORT = 8101;
+const MIGRATE_SUBCOMMANDS = new Set(["resume", "status", "stop", "ui"]);
+const MIGRATION_SESSION_COMMAND = "agent-native code /migrate";
+const MODEL_CREDENTIAL_ENV_NAMES = [
+  "ANTHROPIC_API_KEY",
+  "OPENAI_API_KEY",
+  "GOOGLE_GENERATIVE_AI_API_KEY",
+  "GROQ_API_KEY",
+  "MISTRAL_API_KEY",
+  "COHERE_API_KEY",
+  "BUILDER_PRIVATE_KEY",
+];
+
+type MigrateSubcommand = "resume" | "status" | "stop" | "ui";
+type SourceKind = "path" | "url" | "description";
+
+export interface MigrateCliOptions {
+  subcommand?: MigrateSubcommand;
+  source?: string;
+  sourcePath?: string;
+  sourceUrl?: string;
+  sourceDescription?: string;
+  workbench?: string;
+  output?: string;
+  appName?: string;
+  target?: string;
+  planOnly?: boolean;
+  planFile?: string;
+  emit?: boolean;
+  emitDir?: string;
+  appSurface?: boolean;
+  last?: boolean;
+  help?: boolean;
+}
+
+export interface SourceSpec {
+  kind: SourceKind;
+  value: string;
+  sourceRoot?: string;
+  description?: string;
+}
+
+export interface EmitDossierResult {
+  dossierRoot: string;
+  files: string[];
+  source: SourceSpec;
+  usedMigrateHelpers: boolean;
+}
+
+interface ProjectIRLike {
+  site: {
+    framework: "nextjs" | "react" | "aem" | "unknown";
+    sourceRoot: string;
+    routes: Array<{
+      id: string;
+      path: string;
+      filePath: string;
+      router: "next-pages" | "next-app" | "unknown";
+      kind: "marketing" | "docs" | "landing" | "app" | "api" | "unknown";
+      dynamic: boolean;
+      public: boolean;
+      notes?: string[];
+    }>;
+    redirects: Array<Record<string, unknown>>;
+    metadata: Record<string, unknown>;
+  };
+  components: {
+    components: Array<{
+      id: string;
+      name: string;
+      filePath: string;
+      usedByRoutes: string[];
+      notes?: string[];
+    }>;
+    designTokens: Record<string, unknown>;
+  };
+  content: {
+    models: Array<Record<string, unknown>>;
+    assets: Array<{
+      id: string;
+      path: string;
+      type: string;
+      metadata?: Record<string, unknown>;
+    }>;
+  };
+  behavior: {
+    apiEndpoints: Array<{
+      id: string;
+      path: string;
+      method: string;
+      filePath: string;
+      recommendedRecipe: string;
+    }>;
+    dataStores: Array<{
+      id: string;
+      name: string;
+      filePath: string;
+      kind: "database" | "api" | "local-state" | "unknown";
+    }>;
+    llmCalls: Array<{ id: string; filePath: string; provider: string }>;
+    clientState: Array<{ id: string; filePath: string; reason: string }>;
+    auth: Array<{ id: string; filePath: string; provider: string }>;
+    jobs: Array<{ id: string; filePath: string; kind: string }>;
+  };
+}
+
+export function parseMigrateArgs(argv: string[]): MigrateCliOptions {
+  const opts: MigrateCliOptions = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (i === 0 && MIGRATE_SUBCOMMANDS.has(arg)) {
+      opts.subcommand = arg as MigrateSubcommand;
+      continue;
+    }
+
+    if (arg === "--help" || arg === "-h") {
+      opts.help = true;
+    } else if (arg === "--out" && argv[i + 1]) {
+      opts.output = argv[++i];
+    } else if (arg.startsWith("--out=")) {
+      opts.output = arg.slice("--out=".length);
+    } else if (arg === "--name" && argv[i + 1]) {
+      opts.appName = argv[++i];
+    } else if (arg.startsWith("--name=")) {
+      opts.appName = arg.slice("--name=".length);
+    } else if (arg === "--target" && argv[i + 1]) {
+      opts.target = argv[++i];
+    } else if (arg.startsWith("--target=")) {
+      opts.target = arg.slice("--target=".length);
+    } else if (arg === "--source" && argv[i + 1]) {
+      setSourceOption(opts, argv[++i]);
+    } else if (arg.startsWith("--source=")) {
+      setSourceOption(opts, arg.slice("--source=".length));
+    } else if (arg === "--path" && argv[i + 1]) {
+      opts.sourcePath = argv[++i];
+    } else if (arg.startsWith("--path=")) {
+      opts.sourcePath = arg.slice("--path=".length);
+    } else if (arg === "--url" && argv[i + 1]) {
+      opts.sourceUrl = argv[++i];
+    } else if (arg.startsWith("--url=")) {
+      opts.sourceUrl = arg.slice("--url=".length);
+    } else if (
+      (arg === "--description" || arg === "--describe") &&
+      argv[i + 1]
+    ) {
+      opts.sourceDescription = argv[++i];
+    } else if (arg.startsWith("--description=")) {
+      opts.sourceDescription = arg.slice("--description=".length);
+    } else if (arg.startsWith("--describe=")) {
+      opts.sourceDescription = arg.slice("--describe=".length);
+    } else if (arg === "--emit") {
+      opts.emit = true;
+      if (argv[i + 1] && !argv[i + 1].startsWith("-")) {
+        opts.emitDir = argv[++i];
+      }
+    } else if (arg.startsWith("--emit=")) {
+      opts.emit = true;
+      opts.emitDir = arg.slice("--emit=".length);
+    } else if (arg === "--emit-dir" && argv[i + 1]) {
+      opts.emit = true;
+      opts.emitDir = argv[++i];
+    } else if (arg.startsWith("--emit-dir=")) {
+      opts.emit = true;
+      opts.emitDir = arg.slice("--emit-dir=".length);
+    } else if (arg === "--app-surface" || arg === "--workbench") {
+      opts.appSurface = true;
+    } else if (arg === "--plan-only") {
+      opts.planOnly = true;
+    } else if (arg === "--plan-file" && argv[i + 1]) {
+      opts.planFile = argv[++i];
+    } else if (arg.startsWith("--plan-file=")) {
+      opts.planFile = arg.slice("--plan-file=".length);
+    } else if (arg === "--last") {
+      opts.last = true;
+    } else if (!arg.startsWith("-")) {
+      if (
+        opts.subcommand &&
+        ["status", "stop", "ui"].includes(opts.subcommand) &&
+        !opts.workbench
+      ) {
+        opts.workbench = arg;
+      } else if (!opts.source) {
+        opts.source = arg;
+      } else if (!opts.workbench) {
+        opts.workbench = arg;
+      }
+    }
+  }
+  return opts;
+}
+
+export async function runMigrate(argv: string[]): Promise<void> {
+  const opts = parseMigrateArgs(argv);
+  if (opts.help) {
+    console.log(migrateUsage());
+    return;
+  }
+
+  if (opts.subcommand === "status") {
+    printMigrationStatus(opts);
+    return;
+  }
+  if (opts.subcommand === "stop") {
+    printMigrationStop(opts);
+    return;
+  }
+  if (opts.subcommand === "ui") {
+    printMigrationUi(opts);
+    return;
+  }
+  if (opts.emit) {
+    try {
+      const result = await emitOwnAgentDossier(opts);
+      console.log(renderEmitResult(result));
+    } catch (error) {
+      if (isExpectedMigrationCliError(error)) {
+        console.error(`\n${migrationCliErrorMessage(error)}\n`);
+        process.exit(1);
+      }
+      throw error;
+    }
+    return;
+  }
+  if (opts.subcommand === "resume" && !hasAnySource(opts)) {
+    printMigrationResume(opts);
+    return;
+  }
+
+  if (opts.appSurface) {
+    await scaffoldOrResumeWorkbench();
+    return;
+  }
+
+  try {
+    await createMigrationCodeAgentSession(opts);
+  } catch (error) {
+    if (isExpectedMigrationCliError(error)) {
+      console.error(`\n${migrationCliErrorMessage(error)}\n`);
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+
+export async function emitOwnAgentDossier(
+  opts: MigrateCliOptions,
+  cwd = process.cwd(),
+): Promise<EmitDossierResult> {
+  const source = resolveSourceSpec(opts, cwd);
+  if (!source) {
+    throw new Error(
+      "Usage: agent-native migrate <source-path-or-url> --emit [dossier-dir]",
+    );
+  }
+
+  let dossierRoot = resolveDossierRoot(opts, source, cwd);
+  const explicitEmitDir = Boolean(opts.emitDir);
+  if (source.sourceRoot && isInsideOrSame(source.sourceRoot, dossierRoot)) {
+    if (explicitEmitDir) {
+      throw new Error(
+        `Refusing to emit dossier inside sourceRoot (${source.sourceRoot}). Choose an --emit path outside the source project.`,
+      );
+    }
+    dossierRoot = defaultDossierRoot(source, cwd);
+  }
+  if (source.sourceRoot) {
+    assertOutsideSourceRoot(source.sourceRoot, dossierRoot, "dossier");
+  }
+
+  fs.mkdirSync(dossierRoot, { recursive: true });
+  const planInputs = await readMigrationPlanInputs(opts, cwd);
+  const written = new Set<string>();
+  const write = (relativePath: string, content: string) => {
+    const filePath = path.join(dossierRoot, relativePath);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(
+      filePath,
+      content.endsWith("\n") ? content : `${content}\n`,
+    );
+    written.add(relativePath);
+  };
+
+  const templateDir = findMigrationTemplateDir();
+  const templateAgents = readTextIfExists(
+    templateDir ? path.join(templateDir, "AGENTS.md") : undefined,
+  );
+  write("AGENTS.md", renderDossierAgentsMd(source, templateAgents, planInputs));
+
+  for (const copied of copyMigrationSkills(templateDir, dossierRoot)) {
+    written.add(copied);
+  }
+
+  const helperResult = await writeAssessmentWithMigrateHelpers({
+    source,
+    dossierRoot,
+    target: opts.target ?? DEFAULT_TARGET,
+    write,
+  });
+  const usedMigrateHelpers = helperResult;
+  if (!helperResult) {
+    const fallback = buildFallbackAssessment(source);
+    write("01-assessment.md", fallback.assessment);
+    if (fallback.ir) {
+      write("ir.json", `${JSON.stringify(fallback.ir, null, 2)}\n`);
+    }
+  }
+
+  if (planInputs) {
+    write("02-plan-inputs.json", `${JSON.stringify(planInputs, null, 2)}\n`);
+  }
+
+  write("MIGRATION_PLAYBOOK.md", renderMigrationPlaybook(source, planInputs));
+  write(
+    "source.json",
+    `${JSON.stringify(
+      {
+        source,
+        target: opts.target ?? DEFAULT_TARGET,
+        planInputs,
+        createdAt: new Date().toISOString(),
+        usedMigrateHelpers,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+
+  return {
+    dossierRoot,
+    files: [...written].sort(),
+    source,
+    usedMigrateHelpers,
+  };
+}
+
+export function isExpectedMigrationCliError(error: unknown): boolean {
+  const message = migrationCliErrorMessage(error);
+  return (
+    message.startsWith("Usage: agent-native migrate") ||
+    message.startsWith("Refusing to emit dossier inside sourceRoot") ||
+    message.startsWith("Refusing to write ") ||
+    message.startsWith("Could not read migration plan file ")
+  );
+}
+
+function migrationCliErrorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+async function scaffoldOrResumeWorkbench(): Promise<void> {
+  console.error(
+    [
+      "",
+      "The legacy migration app surface has been removed.",
+      "Use `agent-native code /migrate <source>` for the supported migration workflow.",
+      "Use `--emit [dir]` when you want a portable dossier for another coding agent.",
+      "",
+    ].join("\n"),
+  );
+  process.exit(1);
+}
+
+async function createMigrationCodeAgentSession(
+  opts: MigrateCliOptions,
+): Promise<void> {
+  const cwd = process.cwd();
+  const source = resolveSourceSpec(opts, cwd);
+  if (!source) {
+    console.error(migrateUsage());
+    process.exit(1);
+  }
+
+  const outputRoot = path.resolve(cwd, opts.output ?? DEFAULT_OUTPUT);
+  const planInputs = await readMigrationPlanInputs(opts, cwd);
+  if (source.sourceRoot) {
+    assertOutsideSourceRoot(source.sourceRoot, outputRoot, "outputRoot");
+  }
+
+  const run = createCodeAgentRunRecord({
+    goalId: "migrate",
+    title: defaultRunName(source),
+    subtitle: formatSourceForDisplay(source),
+    status: "needs-approval",
+    phase: "intake",
+    needsApproval: true,
+    progress: {
+      label: "Intake",
+      completed: 0,
+      total: 1,
+      percent: 0,
+    },
+    cwd,
+    metadata: {
+      source,
+      sourceRoot: source.sourceRoot,
+      outputRoot,
+      target: opts.target ?? DEFAULT_TARGET,
+      planInputs,
+    },
+  });
+  appendCodeAgentTranscriptEvent({
+    runId: run.id,
+    kind: "user",
+    message: `Migrate ${formatSourceForDisplay(source)} to ${opts.target ?? DEFAULT_TARGET}.`,
+    metadata: {
+      source,
+      outputRoot,
+      target: opts.target ?? DEFAULT_TARGET,
+      planInputs,
+    },
+  });
+  appendCodeAgentTranscriptEvent({
+    runId: run.id,
+    kind: "status",
+    message: "Preparing migration dossier.",
+    metadata: { status: "needs-approval", phase: "intake" },
+  });
+  const artifactRoot = codeAgentRunArtifactsDir(run.id);
+  const dossierRoot = path.join(artifactRoot, "migration-dossier");
+  const dossier = await emitOwnAgentDossier(
+    {
+      ...opts,
+      emit: true,
+      emitDir: dossierRoot,
+      target: opts.target ?? DEFAULT_TARGET,
+    },
+    cwd,
+  );
+
+  const updated: CodeAgentRunRecord = {
+    ...run,
+    progress: {
+      label: "Dossier ready; waiting for approval",
+      completed: 1,
+      total: 2,
+      percent: 50,
+    },
+    artifactRoot,
+    details: [
+      { label: "Source", value: formatSourceForDisplay(source) },
+      { label: "Output", value: outputRoot },
+      { label: "Dossier", value: dossierRoot },
+      { label: "Resume", value: "agent-native code resume --last" },
+      { label: "Attach", value: "agent-native code attach --last" },
+    ],
+    metadata: {
+      ...(run.metadata ?? {}),
+      dossierRoot,
+      dossierFiles: dossier.files,
+      artifactFiles: dossier.files.map((file) => path.join(dossierRoot, file)),
+      planInputs,
+      usedMigrateHelpers: dossier.usedMigrateHelpers,
+      resumeCommand: "agent-native code resume --last",
+      attachCommand: "agent-native code attach --last",
+      statusCommand: "agent-native code status --last",
+      preferredCommand: MIGRATION_SESSION_COMMAND,
+    },
+    updatedAt: new Date().toISOString(),
+  };
+  writeCodeAgentRunRecord(updated);
+  appendCodeAgentTranscriptEvent({
+    runId: run.id,
+    kind: "artifact",
+    message: "Migration dossier created.",
+    metadata: {
+      path: dossierRoot,
+      files: dossier.files,
+      usedMigrateHelpers: dossier.usedMigrateHelpers,
+    },
+  });
+  appendCodeAgentTranscriptEvent({
+    runId: run.id,
+    kind: "note",
+    message:
+      "Use the dossier with Codex, Claude Code, Cursor, or another coding agent; no migration agent process has been started by the CLI.",
+    metadata: { source: "migration-dossier" },
+  });
+  appendCodeAgentTranscriptEvent({
+    runId: run.id,
+    kind: "status",
+    message:
+      "Migration dossier is ready. Resume the /migrate session from Agent-Native Code when you are ready to approve or continue.",
+    metadata: { status: "needs-approval", phase: "intake" },
+  });
+
+  console.log(renderCodeAgentMigrationSession(updated, dossier));
+}
+
+function printMigrationStatus(opts: MigrateCliOptions): void {
+  const last = getLastCodeAgentRunRecord("migrate");
+  const runs = listCodeAgentRunRecords("migrate");
+  if (last || !opts.appSurface) {
+    console.log(renderCodeAgentMigrationStatus(runs));
+    return;
+  }
+
+  const appDir = resolveWorkbenchDir(opts);
+  const seedPath = path.join(appDir, "data", "migration-source.json");
+  const seed = readJsonIfExists(seedPath) as {
+    sourceKind?: string;
+    sourceRoot?: string;
+    sourceUrl?: string;
+    sourceDescription?: string;
+    outputRoot?: string;
+    target?: string;
+  } | null;
+  const artifactRuns = readArtifactRuns(appDir);
+
+  if (!fs.existsSync(appDir)) {
+    console.error(`No Migration Workbench found at ${appDir}.`);
+    console.error(
+      `Create one with: npx @agent-native/core@latest code /migrate <source>`,
+    );
+    console.error(
+      `The direct migrate command is a shortcut into that same Agent-Native Code slash command.`,
+    );
+    process.exit(1);
+  }
+
+  console.log(
+    [
+      "",
+      "Migration Workbench status",
+      "",
+      `  App:        ${appDir}`,
+      `  Seed:       ${fs.existsSync(seedPath) ? seedPath : "not found"}`,
+      `  Source:     ${formatSeedSource(seed)}`,
+      `  Output:     ${seed?.outputRoot ?? "not set"}`,
+      `  Target:     ${seed?.target ?? DEFAULT_TARGET}`,
+      `  Artifacts:  ${artifactRuns.length} run${artifactRuns.length === 1 ? "" : "s"}`,
+      ...artifactRuns
+        .slice(0, 5)
+        .map((run) => `    - ${run.id} (${run.phase})`),
+      artifactRuns.length > 5 ? `    - ${artifactRuns.length - 5} more...` : "",
+      "",
+      ...credentialStatusLines(),
+    ]
+      .filter(Boolean)
+      .join("\n"),
+  );
+}
+
+function printMigrationStop(_opts: MigrateCliOptions): void {
+  console.log(
+    [
+      "",
+      "Agent-Native Code /migrate stop",
+      "",
+      "The migrate CLI creates resumable session records and artifacts; it does not daemonize a background process yet.",
+      "Stop the terminal, Desktop run, or external coding agent that is actively working on the session.",
+    ].join("\n"),
+  );
+}
+
+function printMigrationUi(opts: MigrateCliOptions): void {
+  const last = getLastCodeAgentRunRecord("migrate");
+  if (last && !opts.appSurface) {
+    console.log(renderCodeAgentMigrationUi(last));
+    return;
+  }
+
+  const appDir = resolveWorkbenchDir(opts);
+  console.log(
+    [
+      "",
+      "Migration Workbench UI",
+      "",
+      `  App: ${appDir}`,
+      `  URL: http://localhost:${MIGRATION_DEV_PORT}/`,
+      "",
+      "Start it with:",
+      `  cd ${shellQuote(path.relative(process.cwd(), appDir) || ".")}`,
+      "  pnpm install",
+      "  pnpm dev",
+      "",
+      "Deep-link shape:",
+      `  http://localhost:${MIGRATION_DEV_PORT}/`,
+      "  Pick a run in the Workbench, or ask the app agent to navigate by run ID.",
+    ].join("\n"),
+  );
+}
+
+function printMigrationResume(opts: MigrateCliOptions): void {
+  const last = getLastCodeAgentRunRecord("migrate");
+  if (last && !opts.appSurface) {
+    console.log(renderCodeAgentMigrationResume(last));
+    return;
+  }
+
+  const appDir = resolveWorkbenchDir(opts);
+  const seedPath = path.join(appDir, "data", "migration-source.json");
+  const seed = readJsonIfExists(seedPath);
+  if (!fs.existsSync(appDir) || !seed) {
+    console.error(
+      "No resumable Migration Workbench seed found. Run `npx @agent-native/core@latest code /migrate <source>` first.",
+    );
+    process.exit(1);
+  }
+  console.log(
+    [
+      "",
+      "Migration Workbench resume",
+      "",
+      `  App:  ${appDir}`,
+      `  Seed: ${seedPath}`,
+      "",
+      "Continue with:",
+      `  cd ${shellQuote(path.relative(process.cwd(), appDir) || ".")}`,
+      "  pnpm dev",
+      "",
+      `Workbench URL: http://localhost:${MIGRATION_DEV_PORT}/`,
+    ].join("\n"),
+  );
+}
+
+function renderWorkbenchReady(args: {
+  appDir: string;
+  existing: boolean;
+  outputRoot: string;
+  source: SourceSpec;
+}): string {
+  const rel = path.relative(process.cwd(), args.appDir) || ".";
+  const sourceCommand = formatSourceForCommand(args.source);
+  return [
+    "",
+    args.existing
+      ? "Migration Workbench is ready (reused existing app)."
+      : "Migration Workbench is ready.",
+    "",
+    `  Source: ${formatSourceForDisplay(args.source)}`,
+    `  Output: ${args.outputRoot}`,
+    `  App:    ${args.appDir}`,
+    "",
+    "Run it:",
+    `  cd ${shellQuote(rel)}`,
+    "  pnpm install",
+    "  pnpm dev",
+    "",
+    "npx-friendly commands:",
+    `  npx @agent-native/core@latest code /migrate ${sourceCommand} --out ${shellQuote(path.relative(process.cwd(), args.outputRoot) || ".")}`,
+    `  npx @agent-native/core@latest code /migrate ${sourceCommand} --emit ${shellQuote(defaultDossierDirForDisplay(args.source))}`,
+    "",
+    "Workbench URL:",
+    `  http://localhost:${MIGRATION_DEV_PORT}/`,
+    "  If Vite chooses another port, use the URL printed by `pnpm dev`.",
+    "",
+    "Deep-link shape:",
+    `  http://localhost:${MIGRATION_DEV_PORT}/`,
+    "  Select the run inside the Workbench, or ask the app agent to open a run by ID.",
+    "",
+    ...credentialStatusLines(),
+    "",
+    "The Workbench seed is written to data/migration-source.json. It stores paths and source metadata only, never secret values.",
+  ].join("\n");
+}
+
+function renderCodeAgentMigrationSession(
+  run: CodeAgentRunRecord,
+  dossier: EmitDossierResult,
+): string {
+  return [
+    "",
+    "Agent-Native Code /migrate session created.",
+    "",
+    `  Run:     ${run.id}`,
+    "  Goal:    /migrate",
+    `  Source:  ${run.subtitle ?? "not set"}`,
+    `  Output:  ${stringMetadata(run, "outputRoot") ?? "not set"}`,
+    `  Dossier: ${stringMetadata(run, "dossierRoot") ?? dossier.dossierRoot}`,
+    `  Engine:  ${dossier.usedMigrateHelpers ? "@agent-native/migrate helpers" : "safe local fallback"}`,
+    "",
+    "Artifacts:",
+    ...dossier.files
+      .filter((file) =>
+        [
+          "AGENTS.md",
+          "MIGRATION_PLAYBOOK.md",
+          "01-assessment.md",
+          "ir.json",
+          "source.json",
+        ].includes(file),
+      )
+      .map((file) => `  - ${path.join(dossier.dossierRoot, file)}`),
+    "",
+    "Continue:",
+    "  agent-native code attach --last",
+    "  agent-native code resume --last",
+    "  agent-native code logs --last",
+    "  agent-native code status --last",
+    "",
+    "Desktop:",
+    "  Open Agent-Native Code in the left sidebar. This run appears as a /migrate session.",
+    "",
+    "Use another agent:",
+    `  Point Codex, Claude Code, Cursor, or another coding agent at ${shellQuote(dossier.dossierRoot)} and ask it to follow AGENTS.md plus MIGRATION_PLAYBOOK.md.`,
+    "",
+    "Default surface:",
+    "  Migration stays in Agent-Native Code. No hidden app/template was scaffolded.",
+    "  The legacy --app-surface detail app has been removed.",
+  ].join("\n");
+}
+
+function renderCodeAgentMigrationStatus(runs: CodeAgentRunRecord[]): string {
+  return [
+    "",
+    "Agent-Native Code /migrate status",
+    "",
+    runs.length === 0
+      ? "  No /migrate sessions found. Start one with `agent-native code /migrate <source>`."
+      : `  ${runs.length} session${runs.length === 1 ? "" : "s"} found.`,
+    ...runs.slice(0, 8).map((run) => {
+      const output = stringMetadata(run, "outputRoot");
+      const dossier = stringMetadata(run, "dossierRoot");
+      const progress = run.progress?.label
+        ? `    Progress: ${run.progress.label} (${run.progress.completed}/${run.progress.total})`
+        : "";
+      return [
+        `  - ${run.id}`,
+        `    Status:  ${run.status}${run.phase ? ` (${run.phase})` : ""}`,
+        progress,
+        `    Source:  ${run.subtitle ?? "not set"}`,
+        output ? `    Output:  ${output}` : "",
+        dossier ? `    Dossier: ${dossier}` : "",
+        `    Resume:  agent-native code resume ${run.id}`,
+      ]
+        .filter(Boolean)
+        .join("\n");
+    }),
+    runs.length > 8 ? `  - ${runs.length - 8} more...` : "",
+    "",
+    "Shortcuts:",
+    "  agent-native migrate status --last shows the same Agent-Native Code sessions.",
+    "  The legacy --app-surface detail app has been removed.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function renderCodeAgentMigrationResume(run: CodeAgentRunRecord): string {
+  const dossier = stringMetadata(run, "dossierRoot");
+  return [
+    "",
+    "Agent-Native Code /migrate resume",
+    "",
+    `  Run:     ${run.id}`,
+    `  Status:  ${run.status}${run.phase ? ` (${run.phase})` : ""}`,
+    `  Source:  ${run.subtitle ?? "not set"}`,
+    dossier ? `  Dossier: ${dossier}` : "",
+    "",
+    "Continue in the interactive shell:",
+    "  agent-native code",
+    "",
+    "Resume this run directly:",
+    `  agent-native code resume ${run.id}`,
+    "  agent-native code attach --last",
+    "",
+    dossier
+      ? `Or hand off to another agent by pointing it at ${shellQuote(dossier)}.`
+      : "No dossier path is recorded on this run.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+function renderCodeAgentMigrationUi(run: CodeAgentRunRecord): string {
+  return [
+    "",
+    "Agent-Native Code /migrate UI",
+    "",
+    `  Run: ${run.id}`,
+    "",
+    "Open Agent-Native Desktop and choose Agent-Native Code from the left sidebar.",
+    "The legacy migration detail app is no longer scaffolded.",
+  ].join("\n");
+}
+
+function renderEmitResult(result: EmitDossierResult): string {
+  return [
+    "",
+    "Migration agent dossier emitted.",
+    "",
+    `  Source:  ${formatSourceForDisplay(result.source)}`,
+    `  Dossier: ${result.dossierRoot}`,
+    `  IR:      ${result.files.includes("ir.json") ? "included" : "not available from this input"}`,
+    `  Engine:  ${result.usedMigrateHelpers ? "@agent-native/migrate helpers" : "safe local fallback"}`,
+    "",
+    "Files:",
+    ...result.files.map((file) => `  - ${file}`),
+    "",
+    "Use with Agent-Native Code/Desktop:",
+    `  Point the agent at ${shellQuote(result.dossierRoot)} and ask it to follow AGENTS.md plus MIGRATION_PLAYBOOK.md.`,
+    "",
+    "Safety:",
+    "  The dossier was written outside sourceRoot and contains no secret values.",
+  ].join("\n");
+}
+
+function migrateUsage(): string {
+  return [
+    "Usage:",
+    "  agent-native code /migrate <source-path-or-url> [--out ../migrated-app]   (preferred)",
+    "  agent-native migrate <source-path-or-url> [--out ../migrated-app]         (shortcut)",
+    "  agent-native migrate <source> --emit [dossier-dir]",
+    '  agent-native migrate --describe "legacy app described in prose" --emit',
+    "  agent-native migrate resume --last",
+    "  agent-native migrate status --last",
+    "  agent-native migrate ui --last",
+    "  agent-native migrate stop --last",
+    "",
+    "Examples:",
+    "  npx @agent-native/core@latest code /migrate ./my-next-app --out ../migrated-app",
+    "  npx @agent-native/core@latest migrate ./my-next-app --out ../migrated-app",
+    '  npx @agent-native/core@latest code /migrate https://example.com --describe "marketing site" --emit ../migration-dossier',
+    '  npx @agent-native/core@latest code /migrate --describe "A Rails admin app with reporting dashboards" --emit',
+    "",
+    "Default:",
+    "  Migration is an Agent-Native Code slash command. The legacy hidden migration app has been removed.",
+    "",
+    "Options:",
+    "  --source, --path <path>       Local source path",
+    "  --url <url>                  Source URL",
+    "  --description, --describe    Source description for any-input migrations",
+    "  --emit [dir]                 Emit an own-agent dossier without recording a session",
+    "  --out <path>                 Generated output path for the migration session",
+    "  --plan-file <path>           Custom migration profile JSON or notes",
+    "  --app-surface, --workbench   Removed legacy detail-app flag; prints migration guidance",
+    "  --name <name>                Legacy app-surface name (ignored for supported flows)",
+    "  --target <name>              Migration target (default: agent-native)",
+    "  --plan-only                  Legacy app-surface plan-only seed (ignored for supported flows)",
+  ].join("\n");
+}
+
+function setSourceOption(opts: MigrateCliOptions, value: string): void {
+  opts.source = value;
+  if (isProbablyUrl(value)) {
+    opts.sourceUrl = value;
+  } else {
+    opts.sourcePath = value;
+  }
+}
+
+function hasAnySource(opts: MigrateCliOptions): boolean {
+  return Boolean(
+    opts.source || opts.sourcePath || opts.sourceUrl || opts.sourceDescription,
+  );
+}
+
+function resolveSourceSpec(
+  opts: MigrateCliOptions,
+  cwd = process.cwd(),
+): SourceSpec | null {
+  if (opts.sourceUrl) {
+    return {
+      kind: "url",
+      value: opts.sourceUrl,
+      description: opts.sourceDescription,
+    };
+  }
+  if (opts.sourcePath) {
+    return {
+      kind: "path",
+      value: opts.sourcePath,
+      sourceRoot: path.resolve(cwd, opts.sourcePath),
+      description: opts.sourceDescription,
+    };
+  }
+  if (opts.source) {
+    if (isProbablyUrl(opts.source)) {
+      return {
+        kind: "url",
+        value: opts.source,
+        description: opts.sourceDescription,
+      };
+    }
+    return {
+      kind: "path",
+      value: opts.source,
+      sourceRoot: path.resolve(cwd, opts.source),
+      description: opts.sourceDescription,
+    };
+  }
+  if (opts.sourceDescription) {
+    return {
+      kind: "description",
+      value: opts.sourceDescription,
+      description: opts.sourceDescription,
+    };
+  }
+  return null;
+}
+
+function resolveDossierRoot(
+  opts: MigrateCliOptions,
+  source: SourceSpec,
+  cwd: string,
+): string {
+  if (opts.emitDir) return path.resolve(cwd, opts.emitDir);
+  return defaultDossierRoot(source, cwd);
+}
+
+async function readMigrationPlanInputs(
+  opts: MigrateCliOptions,
+  cwd: string,
+): Promise<unknown | null> {
+  if (!opts.planFile) return null;
+  const filePath = path.resolve(cwd, opts.planFile);
+  let text = "";
+  try {
+    text = fs.readFileSync(filePath, "utf-8");
+  } catch (error) {
+    throw new Error(
+      `Could not read migration plan file ${filePath}: ${migrationCliErrorMessage(error)}`,
+    );
+  }
+
+  try {
+    const migratePackage = "@agent-native/migrate";
+    const migrate = (await import(migratePackage)) as {
+      parseMigrationPlanInputsText?: (
+        text: string,
+        sourceLabel?: string,
+      ) => unknown;
+    };
+    const parsed = migrate.parseMigrationPlanInputsText?.(
+      text,
+      path.basename(filePath),
+    );
+    if (migrate.parseMigrationPlanInputsText) return parsed ?? null;
+  } catch {
+    // The dossier writer can run without the migrate package being bundled.
+  }
+
+  try {
+    const parsed = JSON.parse(text);
+    return isRecognizedPlanInputJson(parsed) ? parsed : null;
+  } catch {
+    return inferMigrationPlanInputsFromText(text, path.basename(filePath));
+  }
+}
+
+function isRecognizedPlanInputJson(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  return [
+    "summary",
+    "notes",
+    "aem",
+    "builder",
+    "headless",
+    "jquery",
+    "verification",
+  ].some((key) => Object.prototype.hasOwnProperty.call(value, key));
+}
+
+function inferMigrationPlanInputsFromText(
+  text: string,
+  sourceLabel: string,
+): Record<string, unknown> {
+  const lower = text.toLowerCase();
+  const planInputs: Record<string, unknown> = {
+    summary: firstMeaningfulLine(text) ?? sourceLabel,
+    notes: text.trim(),
+  };
+  const mentionsAem =
+    /\baem\b|adobe experience manager|content fragment|experience fragment|sling|htl|jcr|vault|dam/.test(
+      lower,
+    );
+  const mentionsBuilder = /\bbuilder\b|fusion|publish|visual editor/.test(
+    lower,
+  );
+  const mentionsHeadless = /akeneo|akineo|headless|dynamic pages?/.test(lower);
+  const mentionsJQuery = /\bjquery\b|\$\(|clientlib/.test(lower);
+
+  if (mentionsAem) {
+    planInputs.aem = {
+      modes: ["enterprise"],
+      contentFragmentPolicy: mentionsHeadless ? "headless" : "manual",
+      experienceFragmentPolicy: mentionsBuilder
+        ? "builder-section"
+        : "react-component",
+      componentPolicy: mentionsBuilder
+        ? "builder-registered-component"
+        : "react-component",
+    };
+  }
+  if (mentionsBuilder) {
+    planInputs.builder = {
+      enabled: true,
+      componentRegistration: "register",
+      routeOwnership: [
+        {
+          pattern: "static/low-change pages",
+          owner: "builder-page",
+          notes:
+            "Use Builder for static or low-change public pages that benefit from visual management.",
+        },
+      ],
+    };
+  }
+  if (mentionsHeadless) {
+    planInputs.headless = {
+      provider:
+        lower.includes("akeneo") || lower.includes("akineo")
+          ? "Akeneo"
+          : "headless",
+      routePatterns: ["dynamic pages"],
+    };
+    const builder = planInputs.builder as
+      | { routeOwnership?: Array<Record<string, string>> }
+      | undefined;
+    if (builder) {
+      builder.routeOwnership = [
+        ...(builder.routeOwnership ?? []),
+        {
+          pattern: "dynamic pages",
+          owner: "headless",
+          notes:
+            "Route dynamic pages through the approved headless source instead of treating Builder as a content dump.",
+        },
+      ];
+    }
+  }
+  if (mentionsJQuery) {
+    planInputs.jquery = { policy: "rewrite" };
+  }
+  return planInputs;
+}
+
+function firstMeaningfulLine(text: string): string | undefined {
+  return text
+    .split(/\r?\n/)
+    .map((line) => line.replace(/^#+\s*/, "").trim())
+    .find(Boolean)
+    ?.slice(0, 140);
+}
+
+function defaultDossierRoot(source: SourceSpec, cwd: string): string {
+  if (source.sourceRoot) {
+    return path.resolve(
+      path.dirname(source.sourceRoot),
+      `${path.basename(source.sourceRoot)}-migration-dossier`,
+    );
+  }
+  return path.resolve(cwd, DEFAULT_DOSSIER_DIR);
+}
+
+function defaultDossierDirForDisplay(source: SourceSpec): string {
+  if (source.sourceRoot) {
+    return `../${path.basename(source.sourceRoot)}-migration-dossier`;
+  }
+  return DEFAULT_DOSSIER_DIR;
+}
+
+function assertOutsideSourceRoot(
+  sourceRoot: string,
+  targetPath: string,
+  label: string,
+): void {
+  if (isInsideOrSame(sourceRoot, targetPath)) {
+    throw new Error(
+      `Refusing to write ${label} inside sourceRoot (${sourceRoot}). Choose a path outside the source project.`,
+    );
+  }
+}
+
+function isInsideOrSame(root: string, candidate: string): boolean {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+}
+
+async function writeAssessmentWithMigrateHelpers(args: {
+  source: SourceSpec;
+  dossierRoot: string;
+  target: string;
+  write(relativePath: string, content: string): void;
+}): Promise<boolean> {
+  try {
+    const migratePackage = "@agent-native/migrate";
+    const migrate = (await import(migratePackage)) as any;
+    const adapter = migrate.nextjsSourceAdapter;
+
+    if (
+      args.source.sourceRoot &&
+      fs.existsSync(args.source.sourceRoot) &&
+      adapter?.introspect &&
+      migrate.createMigrationRun &&
+      migrate.discoverMigration &&
+      migrate.artifactPaths
+    ) {
+      if (adapter.detect) {
+        const detected = await adapter.detect(args.source.sourceRoot);
+        if (!detected) return false;
+      }
+
+      const artifactRoot = path.join(args.dossierRoot, ".migrate-artifacts");
+      const outputRoot = path.join(args.dossierRoot, "generated-output");
+      assertOutsideSourceRoot(
+        args.source.sourceRoot,
+        artifactRoot,
+        "artifacts",
+      );
+      assertOutsideSourceRoot(args.source.sourceRoot, outputRoot, "outputRoot");
+
+      const run = await migrate.createMigrationRun({
+        sourceRoot: args.source.sourceRoot,
+        outputRoot,
+        artifactRoot,
+        target: args.target,
+        id: "dossier",
+      });
+      const result = await migrate.discoverMigration(run, adapter);
+      const artifacts = migrate.artifactPaths(result.run);
+      args.write(
+        "01-assessment.md",
+        fs.readFileSync(result.assessmentPath, "utf-8"),
+      );
+      if (fs.existsSync(artifacts.irPath)) {
+        args.write("ir.json", fs.readFileSync(artifacts.irPath, "utf-8"));
+      }
+      return true;
+    }
+
+    if (!args.source.sourceRoot && migrate.createSkeletonProjectIR) {
+      const ir = migrate.createSkeletonProjectIR({
+        sourceRoot: args.source.value,
+        inputKind: args.source.kind,
+        inputDescription: args.source.description ?? args.source.value,
+      }) as ProjectIRLike;
+      args.write("01-assessment.md", renderLocalAssessment(args.source, ir));
+      args.write("ir.json", `${JSON.stringify(ir, null, 2)}\n`);
+      return true;
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+function buildFallbackAssessment(source: SourceSpec): {
+  assessment: string;
+  ir?: ProjectIRLike;
+} {
+  if (source.sourceRoot && fs.existsSync(source.sourceRoot)) {
+    const ir = createLocalProjectIr(source.sourceRoot);
+    return { assessment: renderLocalAssessment(source, ir), ir };
+  }
+  return { assessment: renderNonPathAssessment(source) };
+}
+
+function createLocalProjectIr(sourceRoot: string): ProjectIRLike {
+  const files = walkSourceFiles(sourceRoot);
+  const packageJson = readJsonIfExists(
+    path.join(sourceRoot, "package.json"),
+  ) as {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+  } | null;
+  const deps = {
+    ...(packageJson?.dependencies ?? {}),
+    ...(packageJson?.devDependencies ?? {}),
+  };
+  const framework =
+    deps.next ||
+    hasAnyFile(sourceRoot, [
+      "next.config.js",
+      "next.config.mjs",
+      "next.config.ts",
+    ])
+      ? "nextjs"
+      : deps.react
+        ? "react"
+        : "unknown";
+  const routes = files
+    .map((file) => routeFromFile(file))
+    .filter((route): route is ProjectIRLike["site"]["routes"][number] =>
+      Boolean(route),
+    )
+    .sort((a, b) => a.path.localeCompare(b.path));
+  const codeFiles = files.filter((file) => /\.(ts|tsx|js|jsx)$/.test(file));
+  const behavior: ProjectIRLike["behavior"] = {
+    apiEndpoints: [],
+    dataStores: [],
+    llmCalls: [],
+    clientState: [],
+    auth: [],
+    jobs: [],
+  };
+
+  for (const file of codeFiles) {
+    const text = readSmallText(path.join(sourceRoot, file));
+    if (!text) continue;
+    if (
+      file.startsWith("pages/api/") ||
+      /(^|\/)api\/.*\/route\.[tj]sx?$/.test(file)
+    ) {
+      behavior.apiEndpoints.push({
+        id: stableId(file),
+        path: apiPathFromFile(file),
+        method: inferHttpMethod(text),
+        filePath: file,
+        recommendedRecipe: "api-routes-to-actions",
+      });
+    }
+    if (/\b(useState|useReducer|localStorage|sessionStorage)\b/.test(text)) {
+      behavior.clientState.push({
+        id: stableId(`${file}:state`),
+        filePath: file,
+        reason:
+          "Review for important UI state that should move into application_state.",
+      });
+    }
+    if (
+      /\b(openai|anthropic|generateText|streamText|chat\.completions|messages\.create)\b/i.test(
+        text,
+      )
+    ) {
+      behavior.llmCalls.push({
+        id: stableId(`${file}:llm`),
+        filePath: file,
+        provider: inferLlmProvider(text),
+      });
+    }
+    if (
+      /\b(drizzle|prisma|postgres|supabase|mysql|sqlite|mongoose)\b/i.test(text)
+    ) {
+      behavior.dataStores.push({
+        id: stableId(`${file}:data`),
+        name: path.basename(file),
+        filePath: file,
+        kind: "database",
+      });
+    }
+    if (/\b(next-auth|better-auth|auth0|clerk|supabase\.auth)\b/i.test(text)) {
+      behavior.auth.push({
+        id: stableId(`${file}:auth`),
+        filePath: file,
+        provider: inferAuthProvider(text),
+      });
+    }
+    if (
+      /\b(cron|schedule|queue|inngest|trigger\.dev|setInterval)\b/i.test(text)
+    ) {
+      behavior.jobs.push({
+        id: stableId(`${file}:job`),
+        filePath: file,
+        kind: "scheduled-or-queued",
+      });
+    }
+  }
+
+  return {
+    site: {
+      framework,
+      sourceRoot,
+      routes,
+      redirects: [],
+      metadata: {
+        routeCount: routes.length,
+        fileCount: files.length,
+        packageManager: detectPackageManager(sourceRoot),
+      },
+    },
+    components: {
+      components: files
+        .filter(
+          (file) =>
+            /(^|\/)(components|ui)\//.test(file) &&
+            /\.(ts|tsx|js|jsx)$/.test(file),
+        )
+        .sort()
+        .map((file) => ({
+          id: stableId(file),
+          name: componentName(file),
+          filePath: file,
+          usedByRoutes: [],
+        })),
+      designTokens: {},
+    },
+    content: {
+      models: [],
+      assets: files
+        .filter((file) =>
+          /\.(png|jpe?g|webp|gif|svg|avif|pdf|mp4|webm)$/i.test(file),
+        )
+        .sort()
+        .map((file) => ({
+          id: stableId(file),
+          path: file,
+          type: path.extname(file).slice(1).toLowerCase() || "unknown",
+        })),
+    },
+    behavior,
+  };
+}
+
+function renderLocalAssessment(source: SourceSpec, ir: ProjectIRLike): string {
+  return `# Migration Assessment
+
+Source type: \`${source.kind}\`
+Source: \`${formatSourceForDisplay(source)}\`
+${source.description ? `Description: ${source.description}\n` : ""}
+Target: \`${DEFAULT_TARGET}\`
+
+## Inventory
+
+- Framework: ${ir.site.framework}
+- Routes: ${ir.site.routes.length}
+- Components: ${ir.components.components.length}
+- API endpoints: ${ir.behavior.apiEndpoints.length}
+- Data stores: ${ir.behavior.dataStores.length}
+- LLM calls: ${ir.behavior.llmCalls.length}
+- Client state hotspots: ${ir.behavior.clientState.length}
+- Auth hotspots: ${ir.behavior.auth.length}
+- Jobs: ${ir.behavior.jobs.length}
+- Assets: ${ir.content.assets.length}
+
+## Routes
+
+${ir.site.routes.map((route) => `- \`${route.path}\` (${route.kind}) from \`${route.filePath}\``).join("\n") || "- No routes detected."}
+
+## Agent-Native Focus Areas
+
+- Convert API routes and server mutations into actions unless they are uploads, webhooks, OAuth callbacks, or streams.
+- Move app-owned state into SQL with Drizzle and expose reads/writes through actions.
+- Delegate all AI work to the agent chat instead of calling model APIs directly from UI code.
+- Expose important navigation and selection state through application_state.
+- Keep public pages server-rendered and logged-in workflows inside the persistent app shell.
+`;
+}
+
+function renderNonPathAssessment(source: SourceSpec): string {
+  return `# Migration Assessment
+
+Source type: \`${source.kind}\`
+Source: ${source.kind === "url" ? source.value : "provided description"}
+${source.description && source.kind !== "description" ? `Description: ${source.description}\n` : ""}
+${source.kind === "description" ? `Description: ${source.value}\n` : ""}
+Target: \`${DEFAULT_TARGET}\`
+
+## Inventory
+
+No local source path was provided, so this dossier does not include file-level IR. Use the URL or description as the intake brief, then let an Agent-Native Code or Desktop session inspect the real source before writing output.
+
+## Agent-Native Focus Areas
+
+- Identify public pages, logged-in workflows, API endpoints, data ownership, auth, jobs, and direct LLM calls.
+- Convert operations into actions and keep application data in SQL.
+- Generate output outside the original source tree.
+- Verify claims with deterministic checks or explicit human review notes.
+`;
+}
+
+function renderDossierAgentsMd(
+  source: SourceSpec,
+  templateAgents: string | null,
+  planInputs: unknown | null,
+): string {
+  return `# Migration Dossier Agent Instructions
+
+You are migrating an existing application to agent-native.
+
+## Source
+
+- Type: ${source.kind}
+- Value: ${formatSourceForDisplay(source)}
+${source.description ? `- Description: ${source.description}\n` : ""}
+## Hard Rules
+
+- Never write generated files inside the sourceRoot.
+- Treat source as read-only unless the user explicitly asks for source edits.
+- Put generated output in a separate directory.
+- Keep app-owned data in SQL, expose operations as actions, and route AI work through the agent chat.
+- Use 01-assessment.md and ir.json when present. If they are incomplete, update the assessment before implementation.
+- Record manual gaps and verification evidence. Do not present a migration as complete without checks.
+${planInputs ? "- Treat `02-plan-inputs.json` as binding planning input. Do not approve output writes until the generated task list covers it.\n" : ""}
+
+## Files In This Dossier
+
+- \`MIGRATION_PLAYBOOK.md\` - ordered workflow for Agent-Native Code/Desktop.
+- \`01-assessment.md\` - initial source assessment.
+- \`02-plan-inputs.json\` - custom route ownership, AEM, Builder, jQuery, or verification profile when present.
+- \`ir.json\` - source inventory when available.
+- \`.agents/skills/migration*/SKILL.md\` - extra instruction packs when available from the migration goal surface.
+
+${templateAgents ? `## Migration Goal Surface Instructions\n\n${templateAgents.trim()}\n` : ""}
+`;
+}
+
+function renderMigrationPlaybook(
+  source: SourceSpec,
+  planInputs: unknown | null,
+): string {
+  return `# Migration Playbook
+
+## 1. Intake Any Input
+
+Start from the available input: a local source path, a URL, or a prose description. If this dossier has \`ir.json\`, use it as a first inventory. If not, inspect the real source before planning implementation.
+
+Source: ${formatSourceForDisplay(source)}
+
+## 2. Build The Migration Map
+
+Classify routes, public pages, logged-in app surfaces, API endpoints, data stores, auth, jobs, client state, assets, and direct LLM calls. Update \`01-assessment.md\` when you learn more.
+
+${planInputs ? "Use `02-plan-inputs.json` as the customer-specific migration profile. Apply its route ownership, AEM evidence, Builder registration, headless, jQuery, and verification constraints before approving output writes.\n" : ""}
+
+## 3. Apply Agent-Native Rules
+
+- Actions are the single source of truth for operations.
+- Data lives in SQL through Drizzle.
+- AI work goes through the agent chat.
+- Important UI state is mirrored through \`application_state\`.
+- Public/SEO pages server-render; logged-in workflows use the persistent app shell.
+- Ownable resources use sharing and access helpers.
+
+## 4. Work In Samples
+
+Migrate one representative route or workflow first. Verify it, tune the pattern, then sweep similar surfaces. Keep generated output outside the original source tree.
+
+## 5. Verify
+
+Run typecheck/build plus route, action, and data checks that fit the migrated app. Capture unresolved gaps in a report before handing off.
+
+## 6. Use With Agent-Native Code Or Desktop
+
+Point Codex, Claude Code, another code agent, or Agent-Native Desktop at this dossier directory. Ask it to follow \`AGENTS.md\`, then implement the plan in a separate output project.
+`;
+}
+
+function copyMigrationSkills(
+  templateDir: string | undefined,
+  dossierRoot: string,
+): string[] {
+  if (!templateDir) return [];
+  const skillsRoot = path.join(templateDir, ".agents", "skills");
+  if (!fs.existsSync(skillsRoot)) return [];
+  const copied: string[] = [];
+  for (const entry of fs.readdirSync(skillsRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !entry.name.startsWith("migration")) continue;
+    const src = path.join(skillsRoot, entry.name, "SKILL.md");
+    if (!fs.existsSync(src)) continue;
+    const relative = path.join(".agents", "skills", entry.name, "SKILL.md");
+    const dest = path.join(dossierRoot, relative);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    copied.push(relative);
+  }
+  return copied;
+}
+
+function findMigrationTemplateDir(): string | undefined {
+  const starts = [__dirname, process.cwd()];
+  for (const start of starts) {
+    let dir = path.resolve(start);
+    for (let i = 0; i < 12; i++) {
+      for (const candidate of [
+        path.join(dir, "templates", "migration"),
+        path.join(dir, "src", "templates", "migration"),
+      ]) {
+        if (fs.existsSync(path.join(candidate, "AGENTS.md"))) {
+          return candidate;
+        }
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+  }
+  return undefined;
+}
+
+function resolveWorkbenchDir(opts: MigrateCliOptions): string {
+  if (opts.workbench) return path.resolve(process.cwd(), opts.workbench);
+  return resolveScaffoldedAppDir(
+    process.cwd(),
+    opts.appName ?? DEFAULT_APP_NAME,
+  );
+}
+
+function resolveScaffoldedAppDir(cwd: string, appName: string): string {
+  const workspaceAppDir = path.join(cwd, "apps", appName);
+  if (fs.existsSync(workspaceAppDir)) return workspaceAppDir;
+  return path.join(cwd, appName);
+}
+
+function sourceSeedPayload(source: SourceSpec): Record<string, string> {
+  return {
+    kind: source.kind,
+    value: source.value,
+    ...(source.sourceRoot ? { sourceRoot: source.sourceRoot } : {}),
+    ...(source.description ? { description: source.description } : {}),
+  };
+}
+
+function defaultRunName(source: SourceSpec): string {
+  if (source.sourceRoot) {
+    return `Migration from ${path.basename(source.sourceRoot)}`;
+  }
+  if (source.kind === "url") {
+    return `Migration from ${source.value}`;
+  }
+  return "Migration from described source";
+}
+
+function stringMetadata(
+  run: CodeAgentRunRecord,
+  key: string,
+): string | undefined {
+  const value = run.metadata?.[key];
+  return typeof value === "string" ? value : undefined;
+}
+
+function formatSeedSource(
+  seed: {
+    sourceKind?: string;
+    sourceRoot?: string;
+    sourceUrl?: string;
+    sourceDescription?: string;
+  } | null,
+): string {
+  if (!seed) return "not set";
+  if (seed.sourceRoot) return seed.sourceRoot;
+  if (seed.sourceUrl) return seed.sourceUrl;
+  if (seed.sourceDescription) return seed.sourceDescription;
+  return seed.sourceKind ?? "not set";
+}
+
+function readArtifactRuns(
+  appDir: string,
+): Array<{ id: string; phase: string }> {
+  const runsRoot = path.join(appDir, "data", "migration-runs");
+  if (!fs.existsSync(runsRoot)) return [];
+  return fs
+    .readdirSync(runsRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      const run = readJsonIfExists(
+        path.join(runsRoot, entry.name, "run.json"),
+      ) as { id?: string; phase?: string; updatedAt?: string } | null;
+      return {
+        id: run?.id ?? entry.name,
+        phase: run?.phase ?? "unknown",
+        updatedAt: run?.updatedAt ?? "",
+      };
+    })
+    .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+function credentialStatusLines(): string[] {
+  const configured = MODEL_CREDENTIAL_ENV_NAMES.filter((key) =>
+    Boolean(process.env[key]),
+  );
+  if (configured.length > 0) {
+    return [
+      `Headless credentials: detected ${configured.join(", ")} in this shell.`,
+      "Secret values were not read or stored.",
+    ];
+  }
+  return [
+    `Headless credentials: none of ${MODEL_CREDENTIAL_ENV_NAMES.join(", ")} are set in this shell.`,
+    "Set credentials in the Workbench app env or use Desktop/Agent-Native Code credentials; the migrate CLI will not store them.",
+  ];
+}
+
+function walkSourceFiles(root: string): string[] {
+  const out: string[] = [];
+  const ignored = new Set([
+    ".git",
+    ".next",
+    ".turbo",
+    "node_modules",
+    "dist",
+    "build",
+    ".output",
+    "coverage",
+  ]);
+  const visit = (dir: string) => {
+    if (out.length > 5000) return;
+    let entries: fs.Dirent[];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (ignored.has(entry.name)) continue;
+      const absolute = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        visit(absolute);
+      } else if (entry.isFile()) {
+        out.push(toPosix(path.relative(root, absolute)));
+      }
+    }
+  };
+  visit(root);
+  return out.sort();
+}
+
+function routeFromFile(
+  relativePath: string,
+): ProjectIRLike["site"]["routes"][number] | null {
+  const normalized = toPosix(relativePath);
+  const router = normalized.startsWith("app/") ? "next-app" : "next-pages";
+  const isPageRoute =
+    normalized.startsWith("pages/") &&
+    /\.(ts|tsx|js|jsx|md|mdx)$/.test(normalized) &&
+    !normalized.startsWith("pages/_app.") &&
+    !normalized.startsWith("pages/_document.");
+  const isAppRoute =
+    normalized.startsWith("app/") &&
+    /\/(page|route)\.(ts|tsx|js|jsx|md|mdx)$/.test(normalized);
+  if (!isPageRoute && !isAppRoute) return null;
+
+  const isApi =
+    normalized.startsWith("pages/api/") ||
+    /(^|\/)api\/.*\/route\.[tj]sx?$/.test(normalized) ||
+    normalized.endsWith("/route.ts") ||
+    normalized.endsWith("/route.tsx") ||
+    normalized.endsWith("/route.js") ||
+    normalized.endsWith("/route.jsx");
+
+  let routePath = normalized;
+  if (router === "next-app") {
+    routePath = routePath
+      .replace(/^app\//, "")
+      .replace(/(^|\/)(page|route)\.(ts|tsx|js|jsx|md|mdx)$/, "");
+  } else {
+    routePath = routePath
+      .replace(/^pages\//, "")
+      .replace(/\.(ts|tsx|js|jsx|md|mdx)$/, "");
+  }
+
+  routePath = routePath
+    .replace(/\/index$/, "")
+    .replace(/^index$/, "")
+    .replace(/^\(.*?\)\//, "")
+    .replace(/\[(\.\.\.)?([^\]]+)\]/g, (_, dots: string, name: string) =>
+      dots ? `*${name}` : `:${name}`,
+    );
+  const publicPath = routePath ? `/${routePath}` : "/";
+  const pathValue = publicPath === "/api" && isApi ? "/api/*" : publicPath;
+  const kind = isApi
+    ? "api"
+    : pathValue === "/"
+      ? "landing"
+      : pathValue.includes("docs")
+        ? "docs"
+        : pathValue.includes("pricing") || pathValue.includes("blog")
+          ? "marketing"
+          : "app";
+  return {
+    id: stableId(normalized),
+    path: pathValue,
+    filePath: normalized,
+    router,
+    kind,
+    dynamic: pathValue.includes(":") || pathValue.includes("*"),
+    public: kind !== "app" && kind !== "api",
+    notes: isApi
+      ? [
+          "Convert to an action unless it uploads, streams, handles OAuth, or receives webhooks.",
+        ]
+      : [],
+  };
+}
+
+function apiPathFromFile(file: string): string {
+  let value = file
+    .replace(/^pages\/api\//, "/api/")
+    .replace(/^app\//, "/")
+    .replace(/\/route\.[tj]sx?$/, "")
+    .replace(/\.[tj]sx?$/, "");
+  value = value
+    .replace(/\/index$/, "")
+    .replace(/\[(\.\.\.)?([^\]]+)\]/g, (_, dots: string, name: string) =>
+      dots ? `*${name}` : `:${name}`,
+    );
+  return value || "/api";
+}
+
+function inferHttpMethod(text: string): string {
+  const exported = text.match(
+    /export\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE)/,
+  );
+  if (exported) return exported[1];
+  const method = text.match(
+    /method\s*[:=]\s*["'](GET|POST|PUT|PATCH|DELETE)["']/i,
+  );
+  return method?.[1]?.toUpperCase() ?? "GET";
+}
+
+function inferLlmProvider(text: string): string {
+  if (/anthropic/i.test(text)) return "anthropic";
+  if (/openai/i.test(text)) return "openai";
+  return "unknown";
+}
+
+function inferAuthProvider(text: string): string {
+  if (/better-auth/i.test(text)) return "better-auth";
+  if (/next-auth/i.test(text)) return "next-auth";
+  if (/clerk/i.test(text)) return "clerk";
+  if (/auth0/i.test(text)) return "auth0";
+  if (/supabase\.auth/i.test(text)) return "supabase";
+  return "unknown";
+}
+
+function componentName(file: string): string {
+  const base = path.basename(file).replace(/\.(ts|tsx|js|jsx)$/, "");
+  return base
+    .split(/[-_]/g)
+    .filter(Boolean)
+    .map((part) => part[0]?.toUpperCase() + part.slice(1))
+    .join("");
+}
+
+function detectPackageManager(sourceRoot: string): string {
+  if (fs.existsSync(path.join(sourceRoot, "pnpm-lock.yaml"))) return "pnpm";
+  if (fs.existsSync(path.join(sourceRoot, "yarn.lock"))) return "yarn";
+  if (fs.existsSync(path.join(sourceRoot, "package-lock.json"))) return "npm";
+  return "unknown";
+}
+
+function readSmallText(filePath: string): string | null {
+  try {
+    const stat = fs.statSync(filePath);
+    if (stat.size > 256_000) return null;
+    return fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function readJsonIfExists(filePath: string): unknown | null {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function readTextIfExists(filePath: string | undefined): string | null {
+  if (!filePath) return null;
+  try {
+    return fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+function hasAnyFile(root: string, files: string[]): boolean {
+  return files.some((file) => fs.existsSync(path.join(root, file)));
+}
+
+function stableId(value: string): string {
+  return crypto.createHash("sha1").update(value).digest("hex").slice(0, 12);
+}
+
+function isProbablyUrl(value: string): boolean {
+  return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+}
+
+function formatSourceForDisplay(source: SourceSpec): string {
+  if (source.sourceRoot) return source.sourceRoot;
+  return source.value;
+}
+
+function formatSourceForCommand(source: SourceSpec): string {
+  if (source.kind === "description") {
+    return `--describe ${shellQuote(source.value)}`;
+  }
+  const base = shellQuote(source.value);
+  if (source.description) {
+    return `${base} --describe ${shellQuote(source.description)}`;
+  }
+  return base;
+}
+
+function shellQuote(value: string): string {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) return value;
+  return JSON.stringify(value);
+}
+
+function toPosix(value: string): string {
+  return value.split(path.sep).join("/");
+}