@inspecto-dev/cli 0.3.4 → 0.3.5

package/dist/{chunk-2MOEVONN.js → chunk-7ABJRH3F.js}

@@ -118,6 +118,12 @@ async function writeFile(filePath, content) {
   await fs.mkdir(path.dirname(filePath), { recursive: true });
   await fs.writeFile(filePath, content, "utf-8");
 }
+async function removeFile(filePath) {
+  try {
+    await fs.unlink(filePath);
+  } catch {
+  }
+}
 async function removeDir(dirPath) {
   try {
     await fs.rm(dirPath, { recursive: true, force: true });
@@ -144,8 +150,8 @@ async function detectPackageManager(root) {
     ["bun.lockb", "bun"],
     ["bun.lock", "bun"],
     ["pnpm-lock.yaml", "pnpm"],
-    ["yarn.lock", "yarn"],
-    ["package-lock.json", "npm"]
+    ["package-lock.json", "npm"],
+    ["yarn.lock", "yarn"]
   ];
   const results = await Promise.all(
     checks.map(async ([file, pm]) => {
@@ -826,8 +832,18 @@ async function isExtensionInstalled() {
 
 // src/inject/gitignore.ts
 import path5 from "path";
-var DEFAULT_RULES = [".inspecto/install.lock", ".inspecto/cache.json", ".inspecto/*.local.json"];
-var SHARED_RULES = [".inspecto/install.lock", ".inspecto/cache.json", ".inspecto/*.local.json"];
+var DEFAULT_RULES = [
+  ".inspecto/install.lock",
+  ".inspecto/cache.json",
+  ".inspecto/*.local.json",
+  ".inspecto/dev.json"
+];
+var SHARED_RULES = [
+  ".inspecto/install.lock",
+  ".inspecto/cache.json",
+  ".inspecto/*.local.json",
+  ".inspecto/dev.json"
+];
 async function updateGitignore(root, shared, dryRun, quiet = false) {
   const gitignorePath = path5.join(root, ".gitignore");
   let content = await readFile(gitignorePath) ?? "";
@@ -864,7 +880,7 @@ async function cleanGitignore(root) {
   const gitignorePath = path5.join(root, ".gitignore");
   const content = await readFile(gitignorePath);
   if (!content) return;
-  const cleaned = content.replace(/^# Inspecto\s*$/m, "").replace(/^\.inspecto\/?\s*$/gm, "").replace(/^\.inspecto\/install\.lock\s*$/gm, "").replace(/^\.inspecto\/cache\.json\s*$/gm, "").replace(/^\.inspecto\/\*\.local\.json\s*$/gm, "").replace(/\n{3,}/g, "\n\n");
+  const cleaned = content.replace(/^# Inspecto\s*$/m, "").replace(/^\.inspecto\/?\s*$/gm, "").replace(/^\.inspecto\/install\.lock\s*$/gm, "").replace(/^\.inspecto\/cache\.json\s*$/gm, "").replace(/^\.inspecto\/\*\.local\.json\s*$/gm, "").replace(/^\.inspecto\/dev\.json\s*$/gm, "").replace(/\n{3,}/g, "\n\n");
   await writeFile(gitignorePath, cleaned);
 }
 
@@ -921,12 +937,120 @@ function resultStatus(nextSteps) {
   return nextSteps.length > 0 ? "warning" : "ok";
 }
 function manualPlanSteps(plan2, includeBlockers = true) {
-  const steps = plan2.actions.filter((action) => action.type === "manual_step").map((action) => action.description);
+  const steps = plan2.actions.filter(
+    (action) => ["manual_step", "generate_patch_plan", "generate_file", "manual_confirmation"].includes(
+      action.type
+    )
+  ).map((action) => action.description);
   if (!includeBlockers) {
     return steps;
   }
   return [...plan2.blockers.map((blocker) => blocker.message), ...steps];
 }
+function applyGuidedPatchContent(source, snippet) {
+  if (source.includes("import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'")) {
+    return source;
+  }
+  if (source.includes("import { vitePlugin as inspecto } from '@inspecto-dev/plugin'")) {
+    return source;
+  }
+  const trimmedSource = source.trimEnd();
+  if (/export\s+default\s*\{/m.test(source)) {
+    const nextSource = trimmedSource.replace(
+      /export\s+default\s*\{/m,
+      "import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'\n\nexport default {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },"
+    );
+    return `${nextSource}
+`;
+  }
+  if (/module\.exports\s*=\s*\{/m.test(source)) {
+    const nextSource = trimmedSource.replace(
+      /module\.exports\s*=\s*\{/m,
+      "const { webpackPlugin: inspecto } = require('@inspecto-dev/plugin')\n\nmodule.exports = {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },"
+    );
+    return `${nextSource}
+`;
+  }
+  const objectExportVariableMatch = source.match(
+    /(const\s+([A-Za-z0-9_$]+)\s*(?::[^=]+)?=\s*\{[\s\S]*?\}\s*;?\s*)export\s+default\s+\2\s*;?/m
+  );
+  const variableDeclaration = objectExportVariableMatch?.[1];
+  const variableName = objectExportVariableMatch?.[2];
+  if (variableDeclaration && variableName) {
+    const nextDeclaration = variableDeclaration.replace(
+      /=\s*\{/m,
+      "= {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },"
+    );
+    const nextSource = source.replace(
+      objectExportVariableMatch[0],
+      `import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'
+
+${nextDeclaration}export default ${variableName}`
+    );
+    return `${nextSource.trimEnd()}
+`;
+  }
+  if (/defineNuxtConfig\s*\(\s*\{/m.test(source)) {
+    const trimmedSource2 = source.trimEnd();
+    const nextSource = trimmedSource2.replace(
+      /defineNuxtConfig\s*\(\s*\{/m,
+      "defineNuxtConfig({\n  vite: {\n    plugins: [inspecto()],\n  },"
+    );
+    return `import { vitePlugin as inspecto } from '@inspecto-dev/plugin'
+
+${nextSource}
+`;
+  }
+  const jsdocMatch = source.match(
+    /\/\*\*[\s\S]*?@type\s*\{import\('next'\)\.NextConfig\}[\s\S]*?\*\/[\s\S]*?(export\s+default|module\.exports)\s*=?\s*\{/m
+  );
+  if (jsdocMatch) {
+    const isEsm = jsdocMatch[1] === "export default";
+    const importStatement = isEsm ? "import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'\n\n" : "const { webpackPlugin: inspecto } = require('@inspecto-dev/plugin')\n\n";
+    const replacementPattern = isEsm ? /export\s+default\s*\{/m : /module\.exports\s*=\s*\{/m;
+    const injectConfig = isEsm ? "export default {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  }," : "module.exports = {\n  webpack(config, { dev, isServer }) {\n    if (dev) {\n      config.plugins.push(inspecto())\n    }\n    return config\n  },";
+    const nextSource = source.replace(replacementPattern, injectConfig);
+    return `${importStatement}${nextSource.trimEnd()}
+`;
+  }
+  return `${trimmedSource}
+
+${snippet}
+`;
+}
+async function applyGuidedPlanPatches(input, mutations, reporter) {
+  const nextSteps = [];
+  if (!input.plan || input.plan.strategy !== "guided" || !input.plan.patches?.length) {
+    return nextSteps;
+  }
+  for (const patch of input.plan.patches) {
+    if (patch.status !== "planned" || !patch.reason.startsWith("next_config_") && !patch.reason.startsWith("nuxt_config_")) {
+      continue;
+    }
+    const patchPath = path6.join(input.projectRoot, patch.path);
+    const existingContent = await readFile(patchPath);
+    if (existingContent === null) {
+      nextSteps.push(`Could not auto-apply the guided patch for ${patch.path}.`);
+      continue;
+    }
+    const nextContent = applyGuidedPatchContent(existingContent, patch.snippet);
+    if (nextContent === existingContent) {
+      continue;
+    }
+    if (input.options.dryRun) {
+      reporter.dryRun(`Would apply guided patch to ${patch.path}`);
+      continue;
+    }
+    await writeFile(patchPath, nextContent);
+    mutations.push({
+      type: "file_modified",
+      path: patch.path,
+      description: "Automatically configured Inspecto guided Next.js patch"
+    });
+    reporter.success(`Applied guided patch to ${patch.path}`);
+  }
+  return nextSteps;
+}
 async function applyOnboardingPlan(input) {
   return applyOnboardingPlanInternal(input);
 }
@@ -989,7 +1113,7 @@ function createSpinner(text, quiet = false) {
 }
 async function applyOnboardingPlanInternal(input) {
   const reporter = createReporter(input.options.quiet);
-  const additiveManualPlan = input.plan?.strategy === "manual" && input.allowManualPlanApply && input.plan.blockers.length === 0;
+  const additiveManualPlan = (input.plan?.strategy === "manual" || input.plan?.strategy === "guided") && input.allowManualPlanApply && input.plan.blockers.length === 0;
   if (input.plan && input.plan.strategy !== "supported" && !input.allowManualPlanApply) {
     return {
       status: input.plan.status,
@@ -1038,6 +1162,11 @@ async function applyOnboardingPlanInternal(input) {
       spinner.fail("Dependency installation failed");
       installFailed = true;
       reporter.error(`Failed to install dependency: ${error?.message || "Unknown error"}`);
+      if (error?.stderr) {
+        reporter.error(`Details: ${error.stderr}`);
+      } else if (error?.stdout) {
+        reporter.error(`Details: ${error.stdout}`);
+      }
       reporter.hint(`Run manually in ${input.projectRoot}: ${installCmd}`);
       reporter.hint(
         "Setup will continue without dependencies, but Inspecto may not run until installation succeeds."
@@ -1060,6 +1189,9 @@ async function applyOnboardingPlanInternal(input) {
       }
     }
   }
+  if (additiveManualPlan) {
+    nextSteps.push(...await applyGuidedPlanPatches(input, mutations, reporter));
+  }
   if (await exists(settingsPath)) {
     const existingSettings = await readJSON(settingsPath);
     if (existingSettings === null) {
@@ -1312,6 +1444,11 @@ var SUPPORTED_PATTERNS = [
   }
 ];
 var UNSUPPORTED_META = [
+  {
+    name: "Umi",
+    dep: "umi",
+    files: [".umirc.ts", ".umirc.js", "config/config.ts", "config/config.js"]
+  },
   { name: "Next.js", dep: "next", files: ["next.config.mjs", "next.config.js", "next.config.ts"] },
   { name: "Nuxt", dep: "nuxt", files: ["nuxt.config.ts", "nuxt.config.js"] },
   { name: "Remix", dep: "@remix-run/dev", files: ["remix.config.js", "remix.config.ts"] },
@@ -1425,7 +1562,8 @@ async function detectBuildTools(root, packagePaths) {
       }
     }
     const unsupportedChecks = UNSUPPORTED_META.map(async (meta) => {
-      if (!(meta.dep in allDeps)) return null;
+      const hasDep = meta.dep in allDeps || Object.keys(allDeps).some((dep) => dep.includes(meta.dep));
+      if (!hasDep) return null;
       for (const file of meta.files) {
         if (await exists(path7.join(target.absolutePath, file))) {
           return meta.name;
@@ -1549,6 +1687,8 @@ async function detectPattern({
     }
   } else if (pattern.tool === "rsbuild") {
     hasDep = !!allDeps["@rsbuild/core"] || isPackageResolvable("@rsbuild/core", targetRoot);
+  } else if (pattern.tool === "vite") {
+    hasDep = !!allDeps["vite"] || isPackageResolvable("vite", targetRoot);
   } else {
     hasDep = !!allDeps[pattern.tool] || isPackageResolvable(pattern.tool, targetRoot);
   }
@@ -1624,7 +1764,7 @@ async function detectPattern({
         tool: pattern.tool,
         configPath: "package.json (dependency)",
         label: `${pattern.label} (detected via dependency)`,
-        packagePath: packagePath || void 0
+        ...packagePath ? { packagePath } : {}
       };
     }
     return null;
@@ -1646,9 +1786,9 @@ async function detectPattern({
     tool: pattern.tool,
     configPath: relativeConfig,
     label: `${pattern.label} (${relativeConfig})${isLegacyRspack ? " [Legacy]" : ""}${isLegacyWebpack ? " [Webpack 4]" : ""}${inferredFromScripts ? " [Scripts Detected]" : ""}`,
-    isLegacyRspack,
-    isLegacyWebpack,
-    packagePath: packagePath || void 0
+    ...isLegacyRspack ? { isLegacyRspack: true } : {},
+    ...isLegacyWebpack ? { isLegacyWebpack: true } : {},
+    ...packagePath ? { packagePath } : {}
   };
 }
 function resolveInjectionTarget(detections) {
@@ -1678,9 +1818,12 @@ var SUPPORTED_FRAMEWORKS = [
 var UNSUPPORTED_FRAMEWORKS = [
   { name: "Solid", dep: "solid-js" },
   { name: "Svelte", dep: "svelte" },
+  { name: "SvelteKit", dep: "@sveltejs/kit" },
   { name: "Angular", dep: "@angular/core" },
   { name: "Preact", dep: "preact" },
-  { name: "Lit", dep: "lit" }
+  { name: "Lit", dep: "lit" },
+  { name: "Qwik", dep: "qwik" },
+  { name: "Alpine", dep: "lit-html" }
 ];
 function isPackageResolvable2(pkgName, root) {
   try {
@@ -1896,6 +2039,418 @@ async function buildOnboardingContext(root) {
   };
 }
 
+// src/onboarding/nextjs-guidance.ts
+import fs3 from "fs";
+import path11 from "path";
+var NEXT_CONFIG_CANDIDATES = ["next.config.ts", "next.config.mjs", "next.config.js"];
+var APP_ROUTER_LAYOUTS = [
+  "app/layout.tsx",
+  "app/layout.jsx",
+  "src/app/layout.tsx",
+  "src/app/layout.jsx"
+];
+var PAGES_ROUTER_APPS = [
+  "pages/_app.tsx",
+  "pages/_app.jsx",
+  "src/pages/_app.tsx",
+  "src/pages/_app.jsx"
+];
+var PACKAGE_JSON_PATH = "package.json";
+function findFirstExisting(root, candidates) {
+  for (const candidate of candidates) {
+    if (fs3.existsSync(path11.join(root, candidate))) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function detectRouterMode(root) {
+  const hasAppRouter = Boolean(findFirstExisting(root, APP_ROUTER_LAYOUTS));
+  const hasPagesRouter = Boolean(findFirstExisting(root, PAGES_ROUTER_APPS));
+  if (hasAppRouter && hasPagesRouter) return "mixed";
+  if (hasAppRouter) return "app";
+  if (hasPagesRouter) return "pages";
+  return "unknown";
+}
+function detectNextConfigPath(root) {
+  return findFirstExisting(root, NEXT_CONFIG_CANDIDATES);
+}
+function readConfig(root, relativePath) {
+  if (!relativePath) return "";
+  const filePath = path11.join(root, relativePath);
+  if (!fs3.existsSync(filePath)) return "";
+  return fs3.readFileSync(filePath, "utf8");
+}
+function detectPatchShape(source) {
+  if (/export\s+default\s*\{[\s\S]*\}/m.test(source) || /module\.exports\s*=\s*\{[\s\S]*\}/m.test(source) || /const\s+[A-Za-z0-9_$]+\s*(?::[^=]+)?=\s*\{[\s\S]*\}\s*;?\s*export\s+default\s+[A-Za-z0-9_$]+\s*;?/m.test(
+    source
+  ) || /\/\*\*[\s\S]*?@type\s*\{import\('next'\)\.NextConfig\}[\s\S]*?\*\/[\s\S]*?(export\s+default|module\.exports)\s*=?\s*\{[\s\S]*\}/m.test(
+    source
+  )) {
+    return {
+      status: "planned",
+      reason: "next_config_object_export",
+      confidence: "high"
+    };
+  }
+  if (/module\.exports\s*=\s*[A-Za-z0-9_$]+\s*\(/m.test(source) || /export\s+default\s+[A-Za-z0-9_$]+\s*\(/m.test(source)) {
+    return {
+      status: "manual_patch_required",
+      reason: "next_config_wrapped_export",
+      confidence: "medium"
+    };
+  }
+  if (source.trim().length === 0) {
+    return {
+      status: "manual_patch_required",
+      reason: "next_config_missing",
+      confidence: "low"
+    };
+  }
+  return {
+    status: "manual_patch_required",
+    reason: "next_config_complex_shape",
+    confidence: "medium"
+  };
+}
+function buildPatchSnippet() {
+  return [
+    "import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'",
+    "",
+    "webpack(config, { dev, isServer }) {",
+    "  if (dev) {",
+    "    config.plugins.push(inspecto())",
+    "  }",
+    "  return config",
+    "}"
+  ].join("\n");
+}
+function buildAppRouterMountSnippet() {
+  return [
+    "import { useEffect } from 'react'",
+    "",
+    "function InspectoProvider() {",
+    "  useEffect(() => {",
+    "    if (process.env.NODE_ENV !== 'production') {",
+    "      import('@inspecto-dev/core').then(({ mountInspector }) => {",
+    "        mountInspector()",
+    "      })",
+    "    }",
+    "  }, [])",
+    "",
+    "  return null",
+    "}",
+    "",
+    "Render <InspectoProvider /> from app/layout.tsx inside the <body> tree."
+  ].join("\n");
+}
+function buildPagesRouterMountSnippet() {
+  return [
+    "import { useEffect } from 'react'",
+    "",
+    "useEffect(() => {",
+    "  if (process.env.NODE_ENV !== 'production') {",
+    "    import('@inspecto-dev/core').then(({ mountInspector }) => {",
+    "      mountInspector()",
+    "    })",
+    "  }",
+    "}, [])",
+    "",
+    "Add this effect to pages/_app.tsx without changing the existing app wrapper behavior."
+  ].join("\n");
+}
+function detectWebpackDevScriptPatch(root) {
+  const packageJsonSource = readConfig(root, PACKAGE_JSON_PATH);
+  if (!packageJsonSource) {
+    return void 0;
+  }
+  try {
+    const packageJson = JSON.parse(packageJsonSource);
+    const devScript = packageJson.scripts?.dev;
+    if (!devScript || !/\bnext\s+dev\b/.test(devScript) || /--webpack\b/.test(devScript)) {
+      return void 0;
+    }
+    return {
+      path: PACKAGE_JSON_PATH,
+      status: "manual_patch_required",
+      reason: "next_dev_script_requires_webpack",
+      confidence: "medium",
+      snippet: '"dev": "next dev --webpack"'
+    };
+  } catch {
+    return void 0;
+  }
+}
+function buildPendingSteps(routerMode, configPath, needsWebpackDevScript) {
+  const routerHint = routerMode === "app" ? "Complete the remaining client-side mount step for your App Router entry." : routerMode === "pages" ? "Complete the remaining client-side mount step for your Pages Router entry." : routerMode === "mixed" ? "Complete the remaining client-side mount step for the router entry your team actually uses in development." : "Complete the remaining client-side mount step in the appropriate Next.js entry file.";
+  return [
+    `Review the generated Next.js patch plan for ${configPath}.`,
+    ...needsWebpackDevScript ? ["Update the Next.js dev script to use webpack mode for Inspecto validation."] : [],
+    "Keep the Inspecto webpack plugin enabled for both server and client development compilers in App Router projects.",
+    routerHint
+  ];
+}
+function createNextJsGuidance(root) {
+  const configPath = detectNextConfigPath(root) ?? "next.config.js";
+  const configSource = readConfig(root, detectNextConfigPath(root));
+  const patchShape = detectPatchShape(configSource);
+  const routerMode = detectRouterMode(root);
+  const webpackDevScriptPatch = detectWebpackDevScriptPatch(root);
+  return {
+    framework: "react",
+    metaFramework: "Next.js",
+    routerMode,
+    autoApplied: ["dependencies", "inspecto_settings"],
+    pendingSteps: buildPendingSteps(routerMode, configPath, Boolean(webpackDevScriptPatch)),
+    assistantPrompt: "Complete the remaining Inspecto onboarding for this Next.js project. Use the generated patches directly, keep existing app behavior unchanged, avoid unrelated documentation searches unless a patch is insufficient, and finish the client-side mount step safely.",
+    patches: [
+      {
+        path: configPath,
+        status: patchShape.status,
+        reason: patchShape.reason,
+        confidence: patchShape.confidence,
+        snippet: buildPatchSnippet()
+      },
+      ...routerMode === "app" || routerMode === "mixed" ? [
+        {
+          path: findFirstExisting(root, APP_ROUTER_LAYOUTS) ?? "app/layout.tsx",
+          status: "manual_patch_required",
+          reason: "next_app_router_mount",
+          confidence: "medium",
+          snippet: buildAppRouterMountSnippet()
+        }
+      ] : [],
+      ...routerMode === "pages" || routerMode === "mixed" ? [
+        {
+          path: findFirstExisting(root, PAGES_ROUTER_APPS) ?? "pages/_app.tsx",
+          status: "manual_patch_required",
+          reason: "next_pages_router_mount",
+          confidence: "medium",
+          snippet: buildPagesRouterMountSnippet()
+        }
+      ] : [],
+      ...webpackDevScriptPatch ? [webpackDevScriptPatch] : []
+    ]
+  };
+}
+
+// src/onboarding/nuxt-guidance.ts
+import fs4 from "fs";
+import path12 from "path";
+var NUXT_CONFIG_CANDIDATES = ["nuxt.config.ts", "nuxt.config.js"];
+function findFirstExisting2(root, candidates) {
+  for (const candidate of candidates) {
+    if (fs4.existsSync(path12.join(root, candidate))) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function readConfig2(root, relativePath) {
+  if (!relativePath) return "";
+  const filePath = path12.join(root, relativePath);
+  if (!fs4.existsSync(filePath)) return "";
+  return fs4.readFileSync(filePath, "utf8");
+}
+function detectPatchShape2(source) {
+  if (/with[A-Za-z0-9_$]*\s*\(\s*defineNuxtConfig/m.test(source)) {
+    return {
+      status: "manual_patch_required",
+      reason: "nuxt_config_wrapped_export",
+      confidence: "medium"
+    };
+  }
+  if (/defineNuxtConfig\s*\(\s*\{[\s\S]*\}\s*\)/m.test(source)) {
+    return {
+      status: "planned",
+      reason: "nuxt_config_object_export",
+      confidence: "high"
+    };
+  }
+  if (source.trim().length === 0) {
+    return {
+      status: "manual_patch_required",
+      reason: "nuxt_config_missing",
+      confidence: "low"
+    };
+  }
+  return {
+    status: "manual_patch_required",
+    reason: "nuxt_config_complex_shape",
+    confidence: "medium"
+  };
+}
+function buildNuxtConfigSnippet() {
+  return [
+    "import { vitePlugin as inspecto } from '@inspecto-dev/plugin'",
+    "",
+    "export default defineNuxtConfig({",
+    "  vite: {",
+    "    plugins: [inspecto()],",
+    "  },",
+    "})"
+  ].join("\n");
+}
+function buildNuxtPluginSnippet() {
+  return [
+    "export default defineNuxtPlugin(() => {",
+    "  if (import.meta.dev) {",
+    "    import('@inspecto-dev/core').then(({ mountInspector }) => {",
+    "      mountInspector()",
+    "    })",
+    "  }",
+    "})"
+  ].join("\n");
+}
+function createNuxtGuidance(root) {
+  const configPath = findFirstExisting2(root, NUXT_CONFIG_CANDIDATES) ?? "nuxt.config.ts";
+  const configSource = readConfig2(root, findFirstExisting2(root, NUXT_CONFIG_CANDIDATES));
+  const patchShape = detectPatchShape2(configSource);
+  const hasSrcDir = fs4.existsSync(path12.join(root, "src")) && fs4.statSync(path12.join(root, "src")).isDirectory();
+  const pluginPath = hasSrcDir ? "src/plugins/inspecto.client.ts" : "plugins/inspecto.client.ts";
+  return {
+    framework: "vue",
+    metaFramework: "Nuxt",
+    autoApplied: ["dependencies", "inspecto_settings"],
+    pendingSteps: [
+      `Review the generated Nuxt patch plan for ${configPath}.`,
+      `Complete the remaining Nuxt client plugin mount step in ${pluginPath}.`
+    ],
+    assistantPrompt: "Complete the remaining Inspecto onboarding for this Nuxt project. Review the generated patch plan, keep existing app behavior unchanged, and finish the client plugin mount step safely.",
+    patches: [
+      {
+        path: configPath,
+        status: patchShape.status,
+        reason: patchShape.reason,
+        confidence: patchShape.confidence,
+        snippet: buildNuxtConfigSnippet()
+      },
+      {
+        path: pluginPath,
+        status: "manual_patch_required",
+        reason: "nuxt_client_plugin_mount",
+        confidence: "medium",
+        snippet: buildNuxtPluginSnippet()
+      }
+    ]
+  };
+}
+
+// src/onboarding/umi-guidance.ts
+import fs5 from "fs";
+import path13 from "path";
+var UMI_CONFIG_CANDIDATES = [
+  ".umirc.ts",
+  ".umirc.js",
+  "config/config.ts",
+  "config/config.js"
+];
+function findFirstExisting3(root, candidates) {
+  for (const candidate of candidates) {
+    if (fs5.existsSync(path13.join(root, candidate))) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function readConfig3(root, relativePath) {
+  if (!relativePath) return "";
+  const filePath = path13.join(root, relativePath);
+  if (!fs5.existsSync(filePath)) return "";
+  return fs5.readFileSync(filePath, "utf8");
+}
+function detectPatchShape3(source) {
+  if (/defineConfig\s*\(\s*\{[\s\S]*\}\s*\)/m.test(source)) {
+    return {
+      status: "planned",
+      reason: "umi_config_object_export",
+      confidence: "high"
+    };
+  }
+  if (source.trim().length === 0) {
+    return {
+      status: "manual_patch_required",
+      reason: "umi_config_missing",
+      confidence: "low"
+    };
+  }
+  return {
+    status: "manual_patch_required",
+    reason: "umi_config_complex_shape",
+    confidence: "medium"
+  };
+}
+function buildUmiConfigSnippet() {
+  return [
+    "import { defineConfig } from 'umi'",
+    "import { webpack4Plugin } from '@inspecto-dev/plugin/legacy/webpack4'",
+    "",
+    "export default defineConfig({",
+    "  chainWebpack(memo) {",
+    "    if (process.env.NODE_ENV === 'development') {",
+    "      memo.plugin('inspecto').use(webpack4Plugin())",
+    "    }",
+    "  },",
+    "})"
+  ].join("\n");
+}
+function buildUmiMountSnippet() {
+  return [
+    "import { useEffect } from 'react'",
+    "",
+    "export function rootContainer(container: React.ReactNode) {",
+    "  return (",
+    "    <InspectoWrapper>{container}</InspectoWrapper>",
+    "  )",
+    "}",
+    "",
+    "function InspectoWrapper({ children }: { children: React.ReactNode }) {",
+    "  useEffect(() => {",
+    "    if (process.env.NODE_ENV !== 'production') {",
+    "      import('@inspecto-dev/core').then(({ mountInspector }) => {",
+    "        mountInspector({",
+    "          serverUrl: 'http://127.0.0.1:' + ((window as any).__AI_INSPECTOR_PORT__ || 5678),",
+    "        })",
+    "      })",
+    "    }",
+    "  }, [])",
+    "",
+    "  return <>{children}</>",
+    "}"
+  ].join("\n");
+}
+function createUmiGuidance(root) {
+  const configPath = findFirstExisting3(root, UMI_CONFIG_CANDIDATES) ?? ".umirc.ts";
+  const configSource = readConfig3(root, findFirstExisting3(root, UMI_CONFIG_CANDIDATES));
+  const patchShape = detectPatchShape3(configSource);
+  return {
+    framework: "react",
+    metaFramework: "Umi",
+    autoApplied: ["dependencies", "inspecto_settings"],
+    pendingSteps: [
+      `Review the generated Umi patch plan for ${configPath}.`,
+      "Complete the remaining client-side mount step in src/app.tsx."
+    ],
+    assistantPrompt: "Complete the remaining Inspecto onboarding for this Umi project. Review the generated patch plan, keep existing app behavior unchanged, and finish the client-side mount step safely.",
+    patches: [
+      {
+        path: configPath,
+        status: patchShape.status,
+        reason: patchShape.reason,
+        confidence: patchShape.confidence,
+        snippet: buildUmiConfigSnippet()
+      },
+      {
+        path: "src/app.tsx",
+        status: "manual_patch_required",
+        reason: "umi_app_mount",
+        confidence: "medium",
+        snippet: buildUmiMountSnippet()
+      }
+    ]
+  };
+}
+
 // src/onboarding/planner.ts
 function message(code, message2) {
   return { code, message: message2 };
@@ -1922,10 +2477,16 @@ function planStatus(warnings, blockers) {
 function supportedIde(context) {
   return context.ides.find((ide) => ide.supported)?.ide;
 }
+function shouldInstallInspectoExtension(ide) {
+  return Boolean(ide && isSupportedHostIde(ide));
+}
 function supportedProvider(context) {
   return context.providers.find((provider) => provider.supported)?.id;
 }
 function buildToolBlockers(context) {
+  if (isGuidedMetaFrameworkScenario(context)) {
+    return [];
+  }
   if (context.buildTools.unsupported.length > 0) {
     return [
       message(
@@ -2068,6 +2629,46 @@ function manualBuildToolActions(context) {
     }
   ];
 }
+function hasUnsupportedBuildTool(context, buildTool) {
+  return context.buildTools.unsupported.includes(buildTool);
+}
+function isGuidedNextJsScenario(context) {
+  return context.buildTools.supported.length === 0 && hasUnsupportedBuildTool(context, "Next.js") && context.frameworks.supported.includes("react");
+}
+function isGuidedNuxtScenario(context) {
+  return context.buildTools.supported.length === 0 && hasUnsupportedBuildTool(context, "Nuxt") && context.frameworks.supported.includes("vue");
+}
+function isGuidedUmiScenario(context) {
+  return hasUnsupportedBuildTool(context, "Umi") && context.frameworks.supported.includes("react");
+}
+function isGuidedMetaFrameworkScenario(context) {
+  return isGuidedNextJsScenario(context) || isGuidedNuxtScenario(context) || isGuidedUmiScenario(context);
+}
+function guidedBuildToolWarnings(context, guidedBuildTool) {
+  return context.buildTools.unsupported.filter((buildTool) => buildTool !== guidedBuildTool).map(
+    (buildTool) => message(
+      "additional-unsupported-build-tool",
+      `Additional unsupported build tool also detected: ${buildTool}`
+    )
+  );
+}
+function guidedFrameworkWarnings(context, framework) {
+  return context.frameworks.unsupported.filter((item) => item !== framework).map(
+    (item) => message(
+      "additional-unsupported-framework",
+      `Additional unsupported framework also detected: ${item}`
+    )
+  );
+}
+function buildGuidedWarnings(context, guidedBuildTool, guidedFramework) {
+  return uniqueMessages([
+    ...guidedBuildToolWarnings(context, guidedBuildTool),
+    ...guidedFrameworkWarnings(context, guidedFramework),
+    ...unsupportedEnvironmentWarnings(context)
+  ]).filter(
+    (warning) => warning.message !== `Unsupported framework(s) also detected: ${context.frameworks.unsupported.join(", ")}`
+  );
+}
 function manualFrameworkActions(context) {
   if (context.frameworks.unsupported.length > 0) {
     return [
@@ -2114,6 +2715,153 @@ async function createDetectionResult(root) {
   };
 }
 function createPlanResult(context) {
+  if (isGuidedNextJsScenario(context)) {
+    const ide2 = supportedIde(context);
+    const provider2 = supportedProvider(context);
+    const guidance = createNextJsGuidance(context.root);
+    const actions2 = [
+      {
+        type: "install_dependency",
+        target: "@inspecto-dev/plugin @inspecto-dev/core",
+        description: `Install the Inspecto runtime packages with ${context.packageManager}.`
+      }
+    ];
+    if (shouldInstallInspectoExtension(ide2) && ide2) {
+      actions2.push({
+        type: "install_extension",
+        target: ide2,
+        description: `Install the Inspecto ${getHostIdeLabel(ide2)} extension.`
+      });
+    }
+    actions2.push(
+      {
+        type: "generate_patch_plan",
+        target: "next.config",
+        description: "Generate a guided patch plan for the Next.js Inspecto webpack integration."
+      },
+      {
+        type: "manual_confirmation",
+        target: context.root,
+        description: "Complete the remaining client-side Inspecto mount step in your assistant or editor."
+      }
+    );
+    const defaults2 = {
+      shared: false,
+      extension: shouldInstallInspectoExtension(ide2),
+      ...provider2 ? { provider: provider2 } : {},
+      ...ide2 ? { ide: ide2 } : {}
+    };
+    return {
+      status: "warning",
+      warnings: buildGuidedWarnings(context, "Next.js", "react"),
+      blockers: [],
+      strategy: "guided",
+      actions: actions2,
+      defaults: defaults2,
+      framework: guidance.framework,
+      metaFramework: guidance.metaFramework,
+      routerMode: guidance.routerMode,
+      autoApplied: guidance.autoApplied,
+      pendingSteps: guidance.pendingSteps,
+      assistantPrompt: guidance.assistantPrompt,
+      patches: guidance.patches
+    };
+  }
+  if (isGuidedNuxtScenario(context)) {
+    const ide2 = supportedIde(context);
+    const provider2 = supportedProvider(context);
+    const guidance = createNuxtGuidance(context.root);
+    const actions2 = [
+      {
+        type: "install_dependency",
+        target: "@inspecto-dev/plugin @inspecto-dev/core",
+        description: `Install the Inspecto runtime packages with ${context.packageManager}.`
+      }
+    ];
+    if (shouldInstallInspectoExtension(ide2) && ide2) {
+      actions2.push({
+        type: "install_extension",
+        target: ide2,
+        description: `Install the Inspecto ${getHostIdeLabel(ide2)} extension.`
+      });
+    }
+    actions2.push(
+      {
+        type: "generate_patch_plan",
+        target: "nuxt.config",
+        description: "Generate a guided patch plan for the Nuxt Inspecto Vite integration."
+      },
+      {
+        type: "manual_confirmation",
+        target: context.root,
+        description: "Complete the remaining Nuxt client plugin mount step in your assistant or editor."
+      }
+    );
+    const defaults2 = {
+      shared: false,
+      extension: shouldInstallInspectoExtension(ide2),
+      ...provider2 ? { provider: provider2 } : {},
+      ...ide2 ? { ide: ide2 } : {}
+    };
+    return {
+      status: "warning",
+      warnings: buildGuidedWarnings(context, "Nuxt", "vue"),
+      blockers: [],
+      strategy: "guided",
+      actions: actions2,
+      defaults: defaults2,
+      framework: guidance.framework,
+      metaFramework: guidance.metaFramework,
+      autoApplied: guidance.autoApplied,
+      pendingSteps: guidance.pendingSteps,
+      assistantPrompt: guidance.assistantPrompt,
+      patches: guidance.patches
+    };
+  }
+  if (isGuidedUmiScenario(context)) {
+    const ide2 = supportedIde(context);
+    const provider2 = supportedProvider(context);
+    const guidance = createUmiGuidance(context.root);
+    const actions2 = [
+      {
+        type: "install_dependency",
+        target: "@inspecto-dev/plugin @inspecto-dev/core",
+        description: `Install the Inspecto runtime packages with ${context.packageManager}.`
+      }
+    ];
+    if (shouldInstallInspectoExtension(ide2) && ide2) {
+      actions2.push({
+        type: "install_extension",
+        target: ide2,
+        description: `Install the Inspecto ${getHostIdeLabel(ide2)} extension.`
+      });
+    }
+    actions2.push({
+      type: "generate_patch_plan",
+      target: "umi.config",
+      description: "Generate a guided patch plan for the Umi Inspecto webpack integration."
+    });
+    const defaults2 = {
+      shared: false,
+      extension: shouldInstallInspectoExtension(ide2),
+      ...provider2 ? { provider: provider2 } : {},
+      ...ide2 ? { ide: ide2 } : {}
+    };
+    return {
+      status: "warning",
+      warnings: buildGuidedWarnings(context, "Umi", "react"),
+      blockers: [],
+      strategy: "guided",
+      actions: actions2,
+      defaults: defaults2,
+      framework: guidance.framework,
+      metaFramework: guidance.metaFramework,
+      autoApplied: guidance.autoApplied,
+      pendingSteps: guidance.pendingSteps,
+      assistantPrompt: guidance.assistantPrompt,
+      patches: guidance.patches
+    };
+  }
   const warnings = uniqueMessages([
     ...unsupportedEnvironmentWarnings(context),
     ...buildToolWarnings(context)
@@ -2149,23 +2897,23 @@ function createPlanResult(context) {
       });
     }
     const ide2 = supportedIde(context);
-    if (ide2 === "vscode") {
+    if (shouldInstallInspectoExtension(ide2) && ide2) {
       actions.push({
         type: "install_extension",
-        target: "vscode",
-        description: "Install the Inspecto VS Code extension."
+        target: ide2,
+        description: `Install the Inspecto ${getHostIdeLabel(ide2)} extension.`
       });
     }
   }
+  const ide = supportedIde(context);
   const defaults = {
     shared: false,
-    extension: supportedIde(context) === "vscode"
+    extension: shouldInstallInspectoExtension(ide)
   };
   const provider = supportedProvider(context);
   if (provider) {
     defaults.provider = provider;
   }
-  const ide = supportedIde(context);
   if (ide) {
     defaults.ide = ide;
   }
@@ -2179,7 +2927,11 @@ function createPlanResult(context) {
   };
 }
 function planManualFollowUp(result) {
-  return result.actions.filter((action) => action.type === "manual_step").map((action) => action.description);
+  return result.actions.filter(
+    (action) => ["manual_step", "generate_patch_plan", "generate_file", "manual_confirmation"].includes(
+      action.type
+    )
+  ).map((action) => action.description);
 }
 
 // src/commands/apply.ts
@@ -2310,8 +3062,85 @@ async function detect(json = false) {
   return writeCommandOutput(result, json, printDetectionResult);
 }
 
+// src/commands/dev-config.ts
+import path14 from "path";
+var DEV_CONFIG_PATH = path14.join(".inspecto", "dev.json");
+function absoluteDevConfigPath(root) {
+  return path14.join(root, DEV_CONFIG_PATH);
+}
+function printDevConfigResult(result) {
+  log.header("Inspecto Dev");
+  log.info(`Config: ${result.configPath}`);
+  if (result.config.cliBin) {
+    log.hint(`cliBin: ${result.config.cliBin}`);
+  }
+  if (result.config.devRepo) {
+    log.hint(`devRepo: ${result.config.devRepo}`);
+  }
+  if (!result.config.cliBin && !result.config.devRepo) {
+    log.hint("No local dev overrides are configured.");
+  }
+}
+async function readExistingConfig(root) {
+  const configPath = absoluteDevConfigPath(root);
+  const config = await readJSON(configPath);
+  if (!config || typeof config !== "object") {
+    return {};
+  }
+  return config;
+}
+async function devLink(options) {
+  const root = process.cwd();
+  const configPath = absoluteDevConfigPath(root);
+  const existing = await readExistingConfig(root);
+  const nextConfig = {
+    ...existing,
+    ...options.cliBin ? { cliBin: options.cliBin } : {},
+    ...options.devRepo ? { devRepo: options.devRepo } : {}
+  };
+  await writeJSON(configPath, nextConfig);
+  await updateGitignore(root, false, false, true);
+  return writeCommandOutput(
+    {
+      status: "ok",
+      configPath,
+      config: nextConfig
+    },
+    options.json ?? false,
+    printDevConfigResult
+  );
+}
+async function devStatus(json = false) {
+  const root = process.cwd();
+  const configPath = absoluteDevConfigPath(root);
+  const config = await readExistingConfig(root);
+  return writeCommandOutput(
+    {
+      status: "ok",
+      configPath,
+      config
+    },
+    json,
+    printDevConfigResult
+  );
+}
+async function devUnlink(json = false) {
+  const root = process.cwd();
+  const configPath = absoluteDevConfigPath(root);
+  await removeFile(configPath);
+  return writeCommandOutput(
+    {
+      status: "ok",
+      configPath,
+      config: {}
+    },
+    json,
+    printDevConfigResult
+  );
+}
+
 // src/commands/init.ts
-import path11 from "path";
+import path15 from "path";
 
 // src/onboarding/target-resolution.ts
 function buildCandidateId(candidate) {
@@ -2349,8 +3178,8 @@ function buildCandidates(input) {
       configPath: buildTool.configPath,
       label: buildTool.label,
       buildTool: buildTool.tool,
-      isLegacyRspack: buildTool.isLegacyRspack,
-      isLegacyWebpack: buildTool.isLegacyWebpack,
+      ...buildTool.isLegacyRspack ? { isLegacyRspack: true } : {},
+      ...buildTool.isLegacyWebpack ? { isLegacyWebpack: true } : {},
       frameworks: input.frameworkSupportByPackage[packagePath] ?? [],
       automaticInjection: true
     };
@@ -2572,7 +3401,9 @@ async function promptUnsupportedFrameworkContinue() {
 // src/instructions.ts
 function printNuxtManualInstructions() {
   log.blank();
-  log.hint("Nuxt requires manual setup in the current version.");
+  log.hint(
+    "Nuxt supports guided setup in the current version. Inspecto can prepare the config patch, but the client plugin mount step still needs review."
+  );
   log.hint("1. Update `nuxt.config.ts` to register the Inspecto Vite plugin:");
   log.copyableCodeBlock([
     "import { vitePlugin as inspecto } from '@inspecto-dev/plugin'",
@@ -2583,7 +3414,7 @@ function printNuxtManualInstructions() {
     "  },",
     "})"
   ]);
-  log.hint("2. Create `plugins/inspecto.client.ts` to mount `@inspecto-dev/core` in development:");
+  log.hint("2. Complete the remaining client plugin mount step in `plugins/inspecto.client.ts`:");
   log.copyableCodeBlock([
     "export default defineNuxtPlugin(() => {",
     "  if (import.meta.dev) {",
@@ -2593,11 +3424,31 @@ function printNuxtManualInstructions() {
     "  }",
     "})"
   ]);
-  log.hint("3. Restart your Nuxt dev server after updating the config.");
+  log.hint("3. Restart your Nuxt dev server after applying the guided patches.");
+}
+function printUmiManualInstructions() {
+  log.blank();
+  log.hint("Umi supports guided setup in the current version.");
+  log.hint("1. Update `config/config.ts` or `.umirc.ts` to register the Inspecto webpack plugin:");
+  log.copyableCodeBlock([
+    "import { defineConfig } from 'umi'",
+    "import { webpack4Plugin } from '@inspecto-dev/plugin/legacy/webpack4'",
+    "",
+    "export default defineConfig({",
+    "  chainWebpack(memo) {",
+    "    if (process.env.NODE_ENV === 'development') {",
+    "      memo.plugin('inspecto').use(webpack4Plugin())",
+    "    }",
+    "  },",
+    "})"
+  ]);
+  log.hint("2. Restart your Umi dev server after applying the guided patches.");
 }
 function printNextJsManualInstructions() {
   log.blank();
-  log.hint("Next.js requires manual setup in the current version.");
+  log.hint(
+    "Next.js supports guided setup in the current version. Inspecto can prepare the config patch, but the client-side mount step still needs review."
+  );
   log.hint("1. Update `next.config.mjs` to register the Inspecto webpack plugin:");
   log.copyableCodeBlock([
     "import { webpackPlugin as inspecto } from '@inspecto-dev/plugin'",
@@ -2605,7 +3456,7 @@ function printNextJsManualInstructions() {
     "/** @type {import('next').NextConfig} */",
     "const nextConfig = {",
     "  webpack: (config, { dev, isServer }) => {",
-    "    if (dev && !isServer) {",
+    "    if (dev) {",
     "      config.plugins.push(inspecto())",
     "    }",
     "    return config",
@@ -2615,7 +3466,10 @@ function printNextJsManualInstructions() {
     "export default nextConfig"
   ]);
   log.hint(
-    "2. Initialize `@inspecto-dev/core` from a client component such as `app/layout.tsx` or `pages/_app.tsx`:"
+    "Keep the plugin enabled for both server and client development compilers so App Router server components also receive Inspecto transforms."
+  );
+  log.hint(
+    "2. Complete the remaining client-side mount step in `app/layout.tsx` or `pages/_app.tsx`:"
   );
   log.copyableCodeBlock([
     "'use client'",
@@ -2634,7 +3488,7 @@ function printNextJsManualInstructions() {
     "  return <html><body>{children}</body></html>",
     "}"
   ]);
-  log.hint("3. Restart your Next.js dev server after updating the config.");
+  log.hint("3. Restart your Next.js dev server after applying the guided patches.");
 }
 
 // src/commands/init.ts
@@ -2649,7 +3503,7 @@ async function init(options) {
       verifiedPackages.push(pkg);
       continue;
     }
-    const absolutePath = path11.join(repoRoot, pkg);
+    const absolutePath = path15.join(repoRoot, pkg);
     if (await exists(absolutePath)) {
       verifiedPackages.push(pkg);
     } else {
@@ -2662,7 +3516,7 @@ async function init(options) {
     return;
   }
   log.header("Inspecto Setup");
-  if (!await exists(path11.join(repoRoot, "package.json"))) {
+  if (!await exists(path15.join(repoRoot, "package.json"))) {
     log.error("No package.json found in current directory");
     log.hint("Run this command from your project root");
     return;
@@ -2697,12 +3551,12 @@ async function init(options) {
           log.hint("Run `inspecto init` inside the target app, or pass --packages <app-path>.");
           return;
         }
-        projectRoot = path11.join(repoRoot, selectedPackage);
+        projectRoot = path15.join(repoRoot, selectedPackage);
         buildResult = await detectBuildTools(repoRoot, [selectedPackage]);
         log.info(`Continuing initialization in ${selectedPackage}`);
       } else if (targetResolution.selected?.packagePath) {
         const selectedPackage = targetResolution.selected.packagePath;
-        projectRoot = path11.join(repoRoot, selectedPackage);
+        projectRoot = path15.join(repoRoot, selectedPackage);
         buildResult = await detectBuildTools(repoRoot, [selectedPackage]);
         log.warn(`Monorepo root detected. Using the only candidate app: ${selectedPackage}`);
         log.hint("Run `inspecto init` inside that app next time to skip this prompt.");
@@ -2762,14 +3616,17 @@ async function init(options) {
   if (buildResult.unsupported.length > 0) {
     const names = buildResult.unsupported.join(", ");
     manualConfigRequiredFor = buildResult.unsupported[0] || "";
-    log.warn(`Detected ${names} \u2014 automatic plugin injection is not supported in current version`);
-    log.hint("You can still manually configure it by modifying your configuration file");
+    log.warn(`Detected ${names} \u2014 guided onboarding is available in the current version`);
+    log.hint("Inspecto can prepare the remaining patch plan and assistant handoff for this stack.");
     if (buildResult.unsupported.includes("Next.js")) {
       printNextJsManualInstructions();
     }
     if (buildResult.unsupported.includes("Nuxt")) {
       printNuxtManualInstructions();
     }
+    if (buildResult.unsupported.includes("Umi")) {
+      printUmiManualInstructions();
+    }
   }
   if (buildResult.supported.length === 0 && buildResult.unsupported.length === 0) {
     log.warn("No recognized build tool detected");
@@ -2921,7 +3778,7 @@ async function detectFrameworkSupportByPackage(repoRoot, buildTools) {
   const supportByPackage = {};
   await Promise.all(
     packagePaths.map(async (packagePath) => {
-      const result = await detectFrameworks(path11.join(repoRoot, packagePath));
+      const result = await detectFrameworks(path15.join(repoRoot, packagePath));
       supportByPackage[packagePath] = result.supported;
     })
   );
@@ -2929,7 +3786,7 @@ async function detectFrameworkSupportByPackage(repoRoot, buildTools) {
 }
 
 // src/commands/doctor.ts
-import path12 from "path";
+import path16 from "path";
 function createDiagnostic(code, status, message2, hints = [], details) {
   return {
     code,
@@ -2944,6 +3801,94 @@ function doctorStatus(errors, warnings) {
   if (warnings > 0) return "warning";
   return "ok";
 }
+function isGuidedMetaFramework(buildTool) {
+  return buildTool === "Next.js" || buildTool === "Nuxt";
+}
+function buildDoctorOnboardingContext(input) {
+  return {
+    root: input.root,
+    packageManager: input.packageManager,
+    buildTools: input.buildTools,
+    frameworks: {
+      supported: input.frameworks.supported,
+      unsupported: input.frameworks.unsupported.map((item) => item.name)
+    },
+    ides: input.ides.detected.map(({ ide, supported }) => ({ ide, supported })),
+    providers: input.providers.detected.map(({ id, label, supported, preferredMode }) => ({
+      id,
+      label,
+      supported,
+      preferredMode
+    }))
+  };
+}
+function isConfigPatchReason(reason) {
+  return reason.startsWith("next_config_") || reason.startsWith("nuxt_config_");
+}
+function isNextWebpackDevPatchReason(reason) {
+  return reason === "next_dev_script_requires_webpack";
+}
+async function collectGuidedPatchDiagnostics(root, plan2) {
+  if (plan2.strategy !== "guided" || !plan2.patches?.length) {
+    return [];
+  }
+  const diagnostics = [];
+  for (const patch of plan2.patches) {
+    if (isConfigPatchReason(patch.reason)) {
+      const content = await readFile(path16.join(root, patch.path));
+      if (content?.includes("@inspecto-dev/plugin")) {
+        diagnostics.push(
+          createDiagnostic(
+            "guided-config-patch-detected",
+            "ok",
+            `Guided config patch appears to be applied in ${patch.path}`,
+            [],
+            { path: patch.path, reason: patch.reason }
+          )
+        );
+      } else {
+        diagnostics.push(
+          createDiagnostic(
+            "guided-config-patch-pending",
+            "warning",
+            `Guided config patch still needs review in ${patch.path}`,
+            ["Run `inspecto onboard --json` to review the generated patch details."],
+            { path: patch.path, reason: patch.reason }
+          )
+        );
+      }
+      continue;
+    }
+    if (isNextWebpackDevPatchReason(patch.reason)) {
+      const packageJson = await readJSON(
+        path16.join(root, "package.json")
+      );
+      const devScript = packageJson?.scripts?.dev ?? "";
+      if (/next\s+dev\b/.test(devScript) && /--webpack\b/.test(devScript)) {
+        diagnostics.push(
+          createDiagnostic(
+            "guided-dev-script-configured",
+            "ok",
+            "Next.js dev script is configured for webpack mode",
+            [],
+            { script: devScript }
+          )
+        );
+      } else {
+        diagnostics.push(
+          createDiagnostic(
+            "guided-dev-script-pending",
+            "warning",
+            "Next.js dev script still needs webpack mode for Inspecto validation",
+            ["Update the `dev` script to `next dev --webpack` before browser validation."],
+            { script: devScript }
+          )
+        );
+      }
+    }
+  }
+  return diagnostics;
+}
 function printDoctorResult(result) {
   log.header("Inspecto Doctor");
   for (const check of result.checks) {
@@ -2973,7 +3918,7 @@ function printDoctorResult(result) {
 }
 async function collectDoctorResult(root = process.cwd()) {
   const checks = [];
-  if (!await exists(path12.join(root, "package.json"))) {
+  if (!await exists(path16.join(root, "package.json"))) {
     const diagnostic = createDiagnostic("missing-package-json", "error", "No package.json found", [
       "Run this command from your project root"
     ]);
@@ -2995,6 +3940,15 @@ async function collectDoctorResult(root = process.cwd()) {
     detectBuildTools(root),
     isExtensionInstalled()
   ]);
+  const onboardingContext = buildDoctorOnboardingContext({
+    root,
+    packageManager: pm,
+    buildTools: buildResult,
+    frameworks: frameworkResult,
+    ides: ideProbe,
+    providers: providerProbe
+  });
+  const onboardingPlan = createPlanResult(onboardingContext);
   if (ideProbe.detected.length === 0) {
     checks.push(createDiagnostic("ide-not-detected", "warning", "IDE: not detected"));
   } else {
@@ -3067,9 +4021,9 @@ async function collectDoctorResult(root = process.cwd()) {
     }).join(", ");
     checks.push(createDiagnostic("provider-detected", "ok", `Provider: ${aiNames}`));
   }
-  const pluginPath = path12.join(root, "node_modules", "@inspecto-dev", "plugin");
+  const pluginPath = path16.join(root, "node_modules", "@inspecto-dev", "plugin");
   if (await exists(pluginPath)) {
-    const pkgJson = await readJSON(path12.join(pluginPath, "package.json"));
+    const pkgJson = await readJSON(path16.join(pluginPath, "package.json"));
     const version = pkgJson?.version ?? "unknown";
     checks.push(
       createDiagnostic("plugin-installed", "ok", `@inspecto-dev/plugin@${version} installed`, [], {
@@ -3086,7 +4040,7 @@ async function collectDoctorResult(root = process.cwd()) {
   if (buildResult.supported.length > 0) {
     let injected = false;
     for (const bt of buildResult.supported) {
-      const content = await readFile(path12.join(root, bt.configPath));
+      const content = await readFile(path16.join(root, bt.configPath));
       if (content && content.includes("@inspecto-dev/plugin")) {
         checks.push(
           createDiagnostic("plugin-configured", "ok", `Plugin configured in ${bt.configPath}`, [], {
@@ -3109,15 +4063,40 @@ async function collectDoctorResult(root = process.cwd()) {
       );
     }
   } else if (buildResult.unsupported.length > 0) {
-    const names = buildResult.unsupported.join(", ");
-    checks.push(
-      createDiagnostic(
-        `build-tool-unsupported`,
-        "warning",
-        `Build tool: ${names} (not supported in v1)`,
-        ["current version supports: Vite, Webpack, Rspack, esbuild, Rollup"]
-      )
+    const guidedBuildTools = buildResult.unsupported.filter(isGuidedMetaFramework);
+    const trulyUnsupportedBuildTools = buildResult.unsupported.filter(
+      (buildTool) => !isGuidedMetaFramework(buildTool)
     );
+    if (guidedBuildTools.length > 0) {
+      checks.push(
+        createDiagnostic(
+          "build-tool-guided",
+          "warning",
+          `Build tool: ${guidedBuildTools.join(", ")} (guided onboarding available)`,
+          [
+            "Run `inspecto onboard --json` to generate the remaining patch plan and assistant handoff.",
+            ...onboardingPlan.pendingSteps ?? []
+          ],
+          {
+            metaFrameworks: guidedBuildTools,
+            ...onboardingPlan.pendingSteps ? { pendingSteps: onboardingPlan.pendingSteps } : {},
+            ...onboardingPlan.assistantPrompt ? { assistantPrompt: onboardingPlan.assistantPrompt } : {},
+            ...onboardingPlan.patches ? { patchCount: onboardingPlan.patches.length } : {}
+          }
+        )
+      );
+    }
+    checks.push(...await collectGuidedPatchDiagnostics(root, onboardingPlan));
+    if (trulyUnsupportedBuildTools.length > 0) {
+      checks.push(
+        createDiagnostic(
+          "build-tool-unsupported",
+          "warning",
+          `Build tool: ${trulyUnsupportedBuildTools.join(", ")} (not supported in v1)`,
+          ["current version supports: Vite, Webpack, Rspack, esbuild, Rollup"]
+        )
+      );
+    }
   } else {
     checks.push(
       createDiagnostic("build-tool-missing", "warning", "No recognized build config found")
@@ -3145,8 +4124,8 @@ async function collectDoctorResult(root = process.cwd()) {
       );
     }
   }
-  const settingsJsonPath = path12.join(root, ".inspecto", "settings.json");
-  const settingsLocalPath = path12.join(root, ".inspecto", "settings.local.json");
+  const settingsJsonPath = path16.join(root, ".inspecto", "settings.json");
+  const settingsLocalPath = path16.join(root, ".inspecto", "settings.local.json");
   const hasSettingsJson = await exists(settingsJsonPath);
   const hasSettingsLocal = await exists(settingsLocalPath);
   if (hasSettingsJson || hasSettingsLocal) {
@@ -3199,7 +4178,7 @@ async function collectDoctorResult(root = process.cwd()) {
       )
     );
   }
-  const gitignoreContent = await readFile(path12.join(root, ".gitignore"));
+  const gitignoreContent = await readFile(path16.join(root, ".gitignore"));
   if (gitignoreContent) {
     const hasLockIgnore = gitignoreContent.includes(".inspecto/install.lock") || gitignoreContent.includes(".inspecto/");
     if (!hasLockIgnore) {
@@ -3237,7 +4216,7 @@ async function doctor(options = {}) {
 }
 
 // src/onboarding/session.ts
-import path13 from "path";
+import path17 from "path";
 function normalizePackagePath2(packagePath) {
   if (!packagePath || packagePath === ".") return "";
   return packagePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
@@ -3261,9 +4240,7 @@ function getVerificationCommand(packageManager) {
   }
 }
 async function buildVerification(projectRoot, packageManager) {
-  const packageJson = await readJSON(
-    path13.join(projectRoot, "package.json")
-  );
+  const packageJson = await readJSON(path17.join(projectRoot, "package.json"));
   if (packageJson?.scripts?.dev) {
     const devCommand = getVerificationCommand(packageManager);
     return {
@@ -3272,11 +4249,28 @@ async function buildVerification(projectRoot, packageManager) {
       message: `Start the local dev server with \`${devCommand}\` to verify Inspecto in the browser.`
     };
   }
+  if (packageJson?.scripts?.start && packageJson?.dependencies?.next) {
+    const devCommand = packageManager === "bun" ? "bunx next dev" : "npx next dev";
+    return {
+      available: true,
+      devCommand,
+      message: `Start the local dev server with \`${devCommand}\` to verify Inspecto in the browser.`
+    };
+  }
   return {
     available: false,
     message: "Start your normal local dev server command to verify Inspecto in the browser."
   };
 }
+function buildExtensionInstallCommand(ide) {
+  if (ide && isSupportedHostIde(ide)) {
+    const binaryName = getHostIdeBinaryName(ide);
+    if (binaryName) {
+      return `${binaryName} --install-extension inspecto.inspecto`;
+    }
+  }
+  return "code --install-extension inspecto.inspecto";
+}
 function buildIdeExtensionStatus(input) {
   if (!input.required) {
     return {
@@ -3289,8 +4283,10 @@ function buildIdeExtensionStatus(input) {
     required: true,
     installed: input.installed,
     manualRequired: input.manualRequired,
-    installCommand: "code --install-extension inspecto.inspecto",
-    marketplaceUrl: "https://marketplace.visualstudio.com/items?itemName=inspecto.inspecto",
+    installCommand: buildExtensionInstallCommand(input.ide),
+    ...input.ide === "vscode" ? {
+      marketplaceUrl: "https://marketplace.visualstudio.com/items?itemName=inspecto.inspecto"
+    } : {},
     openVsxUrl: "https://open-vsx.org/extension/inspecto/inspecto"
   };
 }
@@ -3302,7 +4298,7 @@ async function detectFrameworkSupportByPackage2(repoRoot, context) {
   await Promise.all(
     Array.from(packagePaths).map(async (packagePath) => {
       const frameworkResult = await detectFrameworks(
-        packagePath ? path13.join(repoRoot, packagePath) : repoRoot
+        packagePath ? path17.join(repoRoot, packagePath) : repoRoot
       );
       supportByPackage[packagePath] = frameworkResult.supported;
     })
@@ -3311,7 +4307,7 @@ async function detectFrameworkSupportByPackage2(repoRoot, context) {
 }
 async function buildTargetedContext(rootContext, target) {
   const packagePath = normalizePackagePath2(target.packagePath);
-  const projectRoot = packagePath ? path13.join(rootContext.root, packagePath) : rootContext.root;
+  const projectRoot = packagePath ? path17.join(rootContext.root, packagePath) : rootContext.root;
   const [frameworks, ides, providers] = await Promise.all([
     detectFrameworks(projectRoot),
     detectIDE(projectRoot),
@@ -3344,7 +4340,11 @@ async function buildTargetedContext(rootContext, target) {
   };
 }
 function buildOnboardingSummary(plan2, projectRoot) {
-  const changes = plan2.actions.filter((action) => action.type !== "manual_step").map((action) => action.description);
+  const changes = plan2.actions.filter(
+    (action) => !["manual_step", "generate_patch_plan", "generate_file", "manual_confirmation"].includes(
+      action.type
+    )
+  ).map((action) => action.description);
   const risks = [...plan2.warnings.map((item) => item.message)];
   const manualFollowUp = planManualFollowUp(plan2);
   let headline = `Inspecto is ready to onboard ${projectRoot}.`;
@@ -3388,18 +4388,27 @@ function buildPreApplyResult(status, session) {
     errors: session.plan.blockers.map((item) => item.message),
     nextSteps: session.summary.manualFollowUp
   } : void 0;
+  const ideExtension = buildIdeExtensionStatus({
+    ...session.selectedIDE?.ide ? { ide: session.selectedIDE.ide } : {},
+    required: session.plan.defaults.extension,
+    installed: false,
+    manualRequired: session.plan.defaults.extension
+  });
   return {
     status,
     target: session.target,
     summary: session.summary,
     confirmation: session.confirmation,
-    ideExtension: buildIdeExtensionStatus({
-      required: session.plan.defaults.extension,
-      installed: false,
-      manualRequired: session.plan.defaults.extension
-    }),
+    ideExtension,
     verification: session.verification,
-    diagnostics
+    ...session.framework ? { framework: session.framework } : {},
+    ...session.metaFramework ? { metaFramework: session.metaFramework } : {},
+    ...session.routerMode ? { routerMode: session.routerMode } : {},
+    ...session.autoApplied ? { autoApplied: session.autoApplied } : {},
+    ...session.pendingSteps ? { pendingSteps: session.pendingSteps } : {},
+    ...session.assistantPrompt ? { assistantPrompt: session.assistantPrompt } : {},
+    ...session.patches ? { patches: session.patches } : {},
+    ...diagnostics ? { diagnostics } : {}
   };
 }
 function buildExecutionResult(session, applyResult) {
@@ -3410,8 +4419,8 @@ function buildExecutionResult(session, applyResult) {
       )
     ),
     installedDependencies: applyResult.mutations.map((item) => item.name).filter((value) => !!value),
-    selectedProviderDefault: session.providerDefault,
-    selectedIDE: session.selectedIDE?.ide,
+    ...session.providerDefault ? { selectedProviderDefault: session.providerDefault } : {},
+    ...session.selectedIDE?.ide ? { selectedIDE: session.selectedIDE.ide } : {},
     mutations: applyResult.mutations
   };
 }
@@ -3444,19 +4453,35 @@ async function resolveOnboardingSession(root, options = {}) {
     repoRoot: root,
     buildTools: rootContext.buildTools.supported,
     frameworkSupportByPackage,
-    selectedPackagePath: options.target
+    ...options.target ? { selectedPackagePath: options.target } : {}
   });
-  if (target.candidates.length === 0) {
+  const isGuided = rootContext.buildTools.unsupported.some(
+    (t) => ["Next.js", "Nuxt", "Umi"].includes(t)
+  );
+  if (target.candidates.length === 0 || isGuided) {
     const plan3 = createPlanResult(rootContext);
+    const guidedStatus = plan3.strategy === "guided" ? "partial_success" : "error";
+    const resolvedTarget = plan3.strategy === "guided" ? {
+      status: "guided",
+      candidates: [],
+      reason: `Guided onboarding is available for ${plan3.metaFramework ?? "this project"}.`
+    } : target;
     return {
-      status: "error",
-      target,
+      status: guidedStatus,
+      target: resolvedTarget,
       summary: buildOnboardingSummary(plan3, root),
       confirmation: { required: false },
       verification: rootVerification,
       context: rootContext,
       plan: plan3,
-      projectRoot: root
+      projectRoot: root,
+      ...plan3.framework ? { framework: plan3.framework } : {},
+      ...plan3.metaFramework ? { metaFramework: plan3.metaFramework } : {},
+      ...plan3.routerMode ? { routerMode: plan3.routerMode } : {},
+      ...plan3.autoApplied ? { autoApplied: plan3.autoApplied } : {},
+      ...plan3.pendingSteps ? { pendingSteps: plan3.pendingSteps } : {},
+      ...plan3.assistantPrompt ? { assistantPrompt: plan3.assistantPrompt } : {},
+      ...plan3.patches ? { patches: plan3.patches } : {}
     };
   }
   if (target.status === "needs_selection") {
@@ -3502,6 +4527,10 @@ async function resolveOnboardingSession(root, options = {}) {
   } else if (summary.manualFollowUp.length > 0 || plan2.warnings.length > 0) {
     status = "partial_success";
   }
+  const providerDefault = getProviderDefault2(
+    plan2.defaults.provider,
+    selectedProvider?.preferredMode
+  );
   return {
     status,
     target,
@@ -3512,7 +4541,14 @@ async function resolveOnboardingSession(root, options = {}) {
     plan: plan2,
     projectRoot: context.root,
     selectedIDE,
-    providerDefault: getProviderDefault2(plan2.defaults.provider, selectedProvider?.preferredMode)
+    ...providerDefault ? { providerDefault } : {},
+    ...plan2.framework ? { framework: plan2.framework } : {},
+    ...plan2.metaFramework ? { metaFramework: plan2.metaFramework } : {},
+    ...plan2.routerMode ? { routerMode: plan2.routerMode } : {},
+    ...plan2.autoApplied ? { autoApplied: plan2.autoApplied } : {},
+    ...plan2.pendingSteps ? { pendingSteps: plan2.pendingSteps } : {},
+    ...plan2.assistantPrompt ? { assistantPrompt: plan2.assistantPrompt } : {},
+    ...plan2.patches ? { patches: plan2.patches } : {}
   };
 }
 async function applyResolvedOnboardingSession(session, options = {}) {
@@ -3532,23 +4568,32 @@ async function applyResolvedOnboardingSession(session, options = {}) {
     selectedIDE: session.selectedIDE,
     providerDefault: session.providerDefault,
     plan: session.plan,
-    allowManualPlanApply: session.plan.strategy === "manual" && session.plan.blockers.length === 0
+    allowManualPlanApply: (session.plan.strategy === "manual" || session.plan.strategy === "guided") && session.plan.blockers.length === 0
   });
   const diagnostics = buildExecutionDiagnostics(session, applyResult);
   const status = applyResult.postInstall.installFailed && session.context.buildTools.supported.length === 0 ? "error" : diagnostics?.nextSteps.length || diagnostics?.errors.length || diagnostics?.warnings.length ? "partial_success" : "success";
+  const ideExtension = buildIdeExtensionStatus({
+    ...session.selectedIDE?.ide ? { ide: session.selectedIDE.ide } : {},
+    required: session.plan.defaults.extension,
+    installed: session.plan.defaults.extension && !applyResult.postInstall.manualExtensionInstallNeeded,
+    manualRequired: applyResult.postInstall.manualExtensionInstallNeeded
+  });
   return {
     status,
     target: session.target,
     summary: session.summary,
     confirmation: session.confirmation,
-    ideExtension: buildIdeExtensionStatus({
-      required: session.plan.defaults.extension,
-      installed: session.plan.defaults.extension && !applyResult.postInstall.manualExtensionInstallNeeded,
-      manualRequired: applyResult.postInstall.manualExtensionInstallNeeded
-    }),
+    ideExtension,
     verification,
     result: buildExecutionResult(session, applyResult),
-    diagnostics
+    ...session.framework ? { framework: session.framework } : {},
+    ...session.metaFramework ? { metaFramework: session.metaFramework } : {},
+    ...session.routerMode ? { routerMode: session.routerMode } : {},
+    ...session.autoApplied ? { autoApplied: session.autoApplied } : {},
+    ...session.pendingSteps ? { pendingSteps: session.pendingSteps } : {},
+    ...session.assistantPrompt ? { assistantPrompt: session.assistantPrompt } : {},
+    ...session.patches ? { patches: session.patches } : {},
+    ...diagnostics ? { diagnostics } : {}
   };
 }
 function buildDeferredOnboardResult(session) {
@@ -3571,36 +4616,72 @@ function printManualExtensionGuidance(result) {
     log.hint(result.ideExtension.openVsxUrl);
   }
 }
+function buildAssistantHandoff(result) {
+  if (!result.framework && !result.metaFramework && !result.routerMode && !result.autoApplied && !result.pendingSteps && !result.assistantPrompt && !result.patches) {
+    return result.handoff;
+  }
+  return {
+    ...result.framework ? { framework: result.framework } : {},
+    ...result.metaFramework ? { metaFramework: result.metaFramework } : {},
+    ...result.routerMode ? { routerMode: result.routerMode } : {},
+    ...result.autoApplied ? { autoApplied: result.autoApplied } : {},
+    ...result.pendingSteps ? { pendingSteps: result.pendingSteps } : {},
+    ...result.assistantPrompt ? { assistantPrompt: result.assistantPrompt } : {},
+    ...result.patches ? { patches: result.patches } : {}
+  };
+}
+function normalizeOnboardResult(result) {
+  const handoff = buildAssistantHandoff(result);
+  if (!handoff) {
+    return result;
+  }
+  return {
+    ...result,
+    handoff
+  };
+}
+function collectDisplayNextSteps(result) {
+  return Array.from(
+    /* @__PURE__ */ new Set([...result.diagnostics?.nextSteps ?? [], ...result.handoff?.pendingSteps ?? []])
+  );
+}
 function printOnboardResult(result) {
+  const normalized = normalizeOnboardResult(result);
   log.header("Inspecto Onboard");
-  log.info(`Status: ${result.status}`);
-  log.info(result.summary.headline);
-  if (result.status === "needs_target_selection") {
-    if (result.target.selectionPurpose) {
-      log.warn(result.target.selectionPurpose);
+  log.info(`Status: ${normalized.status}`);
+  log.info(normalized.summary.headline);
+  if (normalized.status === "needs_target_selection") {
+    if (normalized.target.selectionPurpose) {
+      log.warn(normalized.target.selectionPurpose);
     }
-    for (const candidate of result.target.candidates) {
+    for (const candidate of normalized.target.candidates) {
       const identifier = candidate.candidateId ?? candidate.id ?? candidate.configPath;
       const label = candidate.label ?? candidate.configPath;
       log.hint(`${identifier}: ${label}`);
     }
-    if (result.target.selectionInstructions) {
-      log.hint(result.target.selectionInstructions);
+    if (normalized.target.selectionInstructions) {
+      log.hint(normalized.target.selectionInstructions);
     }
   }
-  for (const change of result.summary.changes) {
+  for (const change of normalized.summary.changes) {
     log.hint(change);
   }
-  for (const step of result.diagnostics?.nextSteps ?? []) {
+  for (const step of collectDisplayNextSteps(normalized)) {
     log.warn(step);
   }
-  if (result.confirmation.required && result.confirmation.question) {
-    log.warn(result.confirmation.question);
+  for (const patch of normalized.handoff?.patches ?? []) {
+    log.hint(`Patch target: ${patch.path} (${patch.reason})`);
+  }
+  if (normalized.handoff?.assistantPrompt) {
+    log.hint(normalized.handoff.assistantPrompt);
   }
-  printManualExtensionGuidance(result);
-  const extensionReady = !result.ideExtension?.required || result.ideExtension.installed && !result.ideExtension.manualRequired;
-  if (extensionReady && (result.status === "success" || result.status === "partial_success") && result.verification?.message) {
-    log.info(result.verification.message);
+  if (normalized.confirmation.required && normalized.confirmation.question) {
+    log.warn(normalized.confirmation.question);
+  }
+  printManualExtensionGuidance(normalized);
+  const extensionReady = !normalized.ideExtension?.required || normalized.ideExtension.installed && !normalized.ideExtension.manualRequired;
+  if (extensionReady && (normalized.status === "success" || normalized.status === "partial_success") && normalized.verification?.message) {
+    log.info(normalized.verification.message);
   }
 }
 async function onboard(options = {}) {
@@ -3608,12 +4689,12 @@ async function onboard(options = {}) {
   const session = await resolveOnboardingSession(root, options);
   if (session.status === "error" || session.status === "needs_target_selection" || session.status === "needs_confirmation") {
     return writeCommandOutput(
-      buildDeferredOnboardResult(session),
+      normalizeOnboardResult(buildDeferredOnboardResult(session)),
       options.json ?? false,
       printOnboardResult
     );
   }
-  const result = await applyResolvedOnboardingSession(session, options);
+  const result = normalizeOnboardResult(await applyResolvedOnboardingSession(session, options));
   return writeCommandOutput(result, options.json ?? false, printOnboardResult);
 }
 
@@ -3651,11 +4732,11 @@ async function plan(json = false) {
 }
 
 // src/commands/teardown.ts
-import path14 from "path";
+import path18 from "path";
 async function teardown() {
   const root = process.cwd();
   log.header("Inspecto Teardown");
-  const lockPath = path14.join(root, ".inspecto", "install.lock");
+  const lockPath = path18.join(root, ".inspecto", "install.lock");
   const lock = await readJSON(lockPath);
   if (!lock) {
     log.warn("No .inspecto/install.lock found. Running in best-effort mode.");
@@ -3668,8 +4749,8 @@ async function teardown() {
     } catch {
       log.warn("Could not remove @inspecto-dev/plugin (may not be installed)");
     }
-    if (await exists(path14.join(root, ".inspecto"))) {
-      await removeDir(path14.join(root, ".inspecto"));
+    if (await exists(path18.join(root, ".inspecto"))) {
+      await removeDir(path18.join(root, ".inspecto"));
       log.success("Deleted .inspecto/ directory");
     }
     await cleanGitignore(root);
@@ -3718,7 +4799,7 @@ async function teardown() {
       }
     }
   }
-  await removeDir(path14.join(root, ".inspecto"));
+  await removeDir(path18.join(root, ".inspecto"));
   log.success("Deleted .inspecto/ directory");
   await cleanGitignore(root);
   log.blank();
@@ -3727,13 +4808,13 @@ async function teardown() {
 }
 
 // src/commands/integration-install.ts
-import fs3 from "fs/promises";
+import fs6 from "fs/promises";
 import { homedir as homedir2 } from "os";
-import path17 from "path";
+import path21 from "path";
 import { fileURLToPath } from "url";
 
 // src/commands/integration-host-ide.ts
-import path15 from "path";
+import path19 from "path";
 async function resolveIntegrationHostIde(options = {}) {
   if (isSupportedHostIde(options.explicitIde)) {
     return {
@@ -3770,22 +4851,24 @@ async function resolveIntegrationHostIde(options = {}) {
       candidates: envCandidates
     };
   }
-  const artifactCandidates = await detectArtifactHostIdes(cwd);
-  if (artifactCandidates.length === 1) {
-    return {
-      ide: artifactCandidates[0],
-      confidence: "medium",
-      source: "artifact",
-      candidates: artifactCandidates
-    };
-  }
-  if (artifactCandidates.length > 1) {
-    return {
-      ide: null,
-      confidence: "low",
-      source: "ambiguous",
-      candidates: artifactCandidates
-    };
+  if (!options.ignoreProjectArtifacts) {
+    const artifactCandidates = await detectArtifactHostIdes(cwd);
+    if (artifactCandidates.length === 1) {
+      return {
+        ide: artifactCandidates[0],
+        confidence: "medium",
+        source: "artifact",
+        candidates: artifactCandidates
+      };
+    }
+    if (artifactCandidates.length > 1) {
+      return {
+        ide: null,
+        confidence: "low",
+        source: "ambiguous",
+        candidates: artifactCandidates
+      };
+    }
   }
   return {
     ide: null,
@@ -3796,8 +4879,8 @@ async function resolveIntegrationHostIde(options = {}) {
 }
 async function resolveConfiguredIde(cwd) {
   const settingsPaths = [
-    path15.join(cwd, ".inspecto", "settings.local.json"),
-    path15.join(cwd, ".inspecto", "settings.json")
+    path19.join(cwd, ".inspecto", "settings.local.json"),
+    path19.join(cwd, ".inspecto", "settings.json")
   ];
   for (const settingsPath of settingsPaths) {
     const settings = await readJSON(settingsPath);
@@ -3837,7 +4920,7 @@ async function detectArtifactHostIdes(cwd) {
 
 // src/commands/integration-dispatch-mode.ts
 import { homedir } from "os";
-import path16 from "path";
+import path20 from "path";
 async function resolveIntegrationDispatchMode(options) {
   const assistantRule = getDualModeAssistantCapability(options.assistant);
   const home = options.homeDir ?? homedir();
@@ -3880,7 +4963,7 @@ async function isIdeExtensionInstalled(extensionId, extensionsDir) {
   } catch {
     return false;
   }
-  const obsoletePath = path16.join(extensionsDir, ".obsolete");
+  const obsoletePath = path20.join(extensionsDir, ".obsolete");
   let obsoleteFolders = /* @__PURE__ */ new Set();
   if (await exists(obsoletePath)) {
     const obsolete = await readJSON(obsoletePath);
@@ -3919,7 +5002,8 @@ async function runIntegrationAutomation(assistant, options = {}, cwd) {
   const silent = options.silent ?? false;
   const resolvedHostIde = await resolveIntegrationHostIde({
     ...options.ide ? { explicitIde: options.ide } : {},
-    ...cwd ? { cwd } : {}
+    ...cwd ? { cwd } : {},
+    ...options.ignoreProjectArtifacts ? { ignoreProjectArtifacts: true } : {}
   });
   const details = {
     hostIde: {
@@ -4332,7 +5416,7 @@ async function installIntegration(assistant, options = {}) {
       if (await exists(asset.target)) {
         if (options.force) {
         } else if (manifest.type === "context-template") {
-          const originalContent = await fs3.readFile(asset.target, "utf-8");
+          const originalContent = await fs6.readFile(asset.target, "utf-8");
           existingFiles.set(asset.target, originalContent);
           if (!silent) {
             log.info(`File ${asset.target} already exists. Content will be appended safely.`);
@@ -4369,7 +5453,7 @@ ${content}`;
     for (const { asset, content } of downloadedAssets) {
       await writeFile(asset.target, content);
       if (asset.executable) {
-        await fs3.chmod(asset.target, 493);
+        await fs6.chmod(asset.target, 493);
       }
     }
   }
@@ -4421,7 +5505,7 @@ ${content}`;
   }
   const automationResult = await runIntegrationAutomation(
     assistant,
-    { ...options, silent },
+    { ...options, silent, ignoreProjectArtifacts: true },
     process.cwd()
   );
   const result = {
@@ -4484,7 +5568,7 @@ async function resolveProviderDefaultForAssistant(assistant, ide) {
   return `${assistant}.${mode}`;
 }
 async function persistProjectOnboardingDefaults(assistant, options) {
-  const settingsPath = path17.join(process.cwd(), ".inspecto", "settings.local.json");
+  const settingsPath = path21.join(process.cwd(), ".inspecto", "settings.local.json");
   const existingSettings = await readJSON(settingsPath);
   const resolvedHostIde = await resolveIntegrationHostIde({
     explicitIde: options.ide,
@@ -4630,22 +5714,22 @@ function resolveCodexPlan(options) {
   if (options.mode !== void 0) {
     throw new Error("`--mode` is not supported for codex.");
   }
-  const baseDir = scope === "user" ? path17.join(homedir2(), ".agents/skills/inspecto-onboarding-codex") : ".agents/skills/inspecto-onboarding-codex";
+  const baseDir = scope === "user" ? path21.join(homedir2(), ".agents/skills/inspecto-onboarding-codex") : ".agents/skills/inspecto-onboarding-codex";
   return {
     assets: [
       {
         source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-codex/SKILL.md`,
-        target: path17.join(baseDir, "SKILL.md"),
+        target: path21.join(baseDir, "SKILL.md"),
         localSource: "skills/inspecto-onboarding-codex/SKILL.md"
       },
       {
         source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-codex/agents/openai.yaml`,
-        target: path17.join(baseDir, "agents/openai.yaml"),
+        target: path21.join(baseDir, "agents/openai.yaml"),
         localSource: "skills/inspecto-onboarding-codex/agents/openai.yaml"
       },
       {
         source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-codex/scripts/run-inspecto.sh`,
-        target: path17.join(baseDir, "scripts/run-inspecto.sh"),
+        target: path21.join(baseDir, "scripts/run-inspecto.sh"),
         executable: true,
         localSource: "skills/inspecto-onboarding-codex/scripts/run-inspecto.sh"
       }
@@ -4665,22 +5749,22 @@ function resolveClaudeCodePlan(options) {
   if (scope !== "project" && scope !== "user") {
     throw new Error(`Unknown Claude Code scope: ${scope}`);
   }
-  const baseDir = scope === "user" ? path17.join(homedir2(), ".claude/skills/inspecto-onboarding-claude-code") : ".claude/skills/inspecto-onboarding-claude-code";
+  const baseDir = scope === "user" ? path21.join(homedir2(), ".claude/skills/inspecto-onboarding-claude-code") : ".claude/skills/inspecto-onboarding-claude-code";
   return {
     assets: [
       {
         source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-claude-code/SKILL.md`,
-        target: path17.join(baseDir, "SKILL.md"),
+        target: path21.join(baseDir, "SKILL.md"),
         localSource: "skills/inspecto-onboarding-claude-code/SKILL.md"
       },
       {
         source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-claude-code/agents/openai.yaml`,
-        target: path17.join(baseDir, "agents/openai.yaml"),
+        target: path21.join(baseDir, "agents/openai.yaml"),
         localSource: "skills/inspecto-onboarding-claude-code/agents/openai.yaml"
       },
       {
         source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-claude-code/scripts/run-inspecto.sh`,
-        target: path17.join(baseDir, "scripts/run-inspecto.sh"),
+        target: path21.join(baseDir, "scripts/run-inspecto.sh"),
         executable: true,
         localSource: "skills/inspecto-onboarding-claude-code/scripts/run-inspecto.sh"
       }
@@ -4745,20 +5829,20 @@ async function loadAsset(asset) {
   if (asset.localSource) {
     const localPath = await resolveBundledAssetPath(asset.localSource);
     if (localPath) {
-      return await fs3.readFile(localPath, "utf-8");
+      return await fs6.readFile(localPath, "utf-8");
     }
   }
   return await downloadAsset(asset.source);
 }
 async function resolveBundledAssetPath(relativePath) {
-  const startDir = path17.dirname(fileURLToPath(import.meta.url));
+  const startDir = path21.dirname(fileURLToPath(import.meta.url));
   let currentDir = startDir;
   for (let depth = 0; depth < 8; depth += 1) {
-    const candidate = path17.join(currentDir, relativePath);
+    const candidate = path21.join(currentDir, relativePath);
     if (await exists(candidate)) {
       return candidate;
     }
-    const parent = path17.dirname(currentDir);
+    const parent = path21.dirname(currentDir);
     if (parent === currentDir) break;
     currentDir = parent;
   }
@@ -4866,6 +5950,9 @@ export {
   reportCommandError,
   apply,
   detect,
+  devLink,
+  devStatus,
+  devUnlink,
   init,
   collectDoctorResult,
   doctor,