@inspecto-dev/cli 0.3.3 → 0.3.5

package/dist/{chunk-LJOKPCPD.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,11 +880,39 @@ 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);
 }
 
 // src/onboarding/apply.ts
+function normalizeSupportedIde(ide) {
+  if (!ide) return void 0;
+  return ide.toLowerCase() === "vscode" ? "vscode" : ide.toLowerCase();
+}
+async function readInheritedSettingsDefaults(repoRoot, projectRoot, settingsFileName) {
+  if (path6.resolve(repoRoot) === path6.resolve(projectRoot)) {
+    return {};
+  }
+  const inheritedSettingsPath = path6.join(repoRoot, ".inspecto", settingsFileName);
+  if (!await exists(inheritedSettingsPath)) {
+    return {};
+  }
+  const inheritedSettings = await readJSON(inheritedSettingsPath);
+  if (!inheritedSettings || typeof inheritedSettings !== "object") {
+    return {};
+  }
+  const inheritedDefaults = {};
+  if (typeof inheritedSettings.ide === "string") {
+    const normalizedIde = normalizeSupportedIde(inheritedSettings.ide);
+    if (normalizedIde) {
+      inheritedDefaults.ide = normalizedIde;
+    }
+  }
+  if (typeof inheritedSettings["provider.default"] === "string") {
+    inheritedDefaults.providerDefault = inheritedSettings["provider.default"];
+  }
+  return inheritedDefaults;
+}
 function shellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -892,11 +936,120 @@ function resolveRuntimePackages() {
 function resultStatus(nextSteps) {
   return nextSteps.length > 0 ? "warning" : "ok";
 }
-function manualPlanSteps(plan2) {
-  return [
-    ...plan2.blockers.map((blocker) => blocker.message),
-    ...plan2.actions.filter((action) => action.type === "manual_step").map((action) => action.description)
-  ];
+function manualPlanSteps(plan2, includeBlockers = true) {
+  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);
@@ -960,6 +1113,7 @@ function createSpinner(text, quiet = false) {
 }
 async function applyOnboardingPlanInternal(input) {
   const reporter = createReporter(input.options.quiet);
+  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,
@@ -968,7 +1122,7 @@ async function applyOnboardingPlanInternal(input) {
         installFailed: false,
         injectionFailed: false,
         manualExtensionInstallNeeded: false,
-        nextSteps: manualPlanSteps(input.plan)
+        nextSteps: manualPlanSteps(input.plan, true)
       }
     };
   }
@@ -978,6 +1132,11 @@ async function applyOnboardingPlanInternal(input) {
   const promptsFileName = input.options.shared ? "prompts.json" : "prompts.local.json";
   const settingsPath = path6.join(settingsDir, settingsFileName);
   const promptsPath = path6.join(settingsDir, promptsFileName);
+  const inheritedDefaults = await readInheritedSettingsDefaults(
+    input.repoRoot,
+    input.projectRoot,
+    settingsFileName
+  );
   const runtimePackages = resolveRuntimePackages();
   const installCmd = getInstallCommand(input.packageManager, runtimePackages.installSpec);
   const nextSteps = [];
@@ -1003,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."
@@ -1010,19 +1174,24 @@ async function applyOnboardingPlanInternal(input) {
     }
   }
   let injectionFailed = Boolean(input.injectionSkippedRequiresManualConfig);
-  for (const target of input.supportedBuildTargets) {
-    const result = await injectPlugin(
-      input.repoRoot,
-      target,
-      input.options.dryRun,
-      input.options.quiet ?? false
-    );
-    if (result.success) {
-      mutations.push(...result.mutations);
-    } else {
-      injectionFailed = true;
+  if (!additiveManualPlan) {
+    for (const target of input.supportedBuildTargets) {
+      const result = await injectPlugin(
+        input.repoRoot,
+        target,
+        input.options.dryRun,
+        input.options.quiet ?? false
+      );
+      if (result.success) {
+        mutations.push(...result.mutations);
+      } else {
+        injectionFailed = true;
+      }
     }
   }
+  if (additiveManualPlan) {
+    nextSteps.push(...await applyGuidedPlanPatches(input, mutations, reporter));
+  }
   if (await exists(settingsPath)) {
     const existingSettings = await readJSON(settingsPath);
     if (existingSettings === null) {
@@ -1030,15 +1199,43 @@ async function applyOnboardingPlanInternal(input) {
       reporter.hint("Please fix the syntax errors manually, or delete it and re-run init");
       nextSteps.push(`Fix .inspecto/${settingsFileName} or delete it and rerun Inspecto setup.`);
     } else {
-      reporter.success(`.inspecto/${settingsFileName} already exists (skipped)`);
+      const mergedSettings = existingSettings && typeof existingSettings === "object" ? { ...existingSettings } : {};
+      let settingsChanged = false;
+      const desiredIde = inheritedDefaults.ide ?? (input.selectedIDE?.supported ? normalizeSupportedIde(input.selectedIDE.ide) : void 0);
+      if (desiredIde && !mergedSettings.ide) {
+        mergedSettings.ide = desiredIde;
+        settingsChanged = true;
+      }
+      const desiredProviderDefault = inheritedDefaults.providerDefault ?? input.providerDefault;
+      if (desiredProviderDefault && !mergedSettings["provider.default"]) {
+        mergedSettings["provider.default"] = desiredProviderDefault;
+        settingsChanged = true;
+      }
+      if (settingsChanged) {
+        if (input.options.dryRun) {
+          reporter.dryRun(`Would update .inspecto/${settingsFileName}`);
+        } else {
+          await writeJSON(settingsPath, mergedSettings);
+          reporter.success(`Updated .inspecto/${settingsFileName} with missing defaults`);
+          mutations.push({
+            type: "file_modified",
+            path: `.inspecto/${settingsFileName}`,
+            description: "Merged missing Inspecto defaults into existing settings"
+          });
+        }
+      } else {
+        reporter.success(`.inspecto/${settingsFileName} already exists (skipped)`);
+      }
     }
   } else {
     const defaultSettings = {};
-    if (input.selectedIDE?.supported) {
-      defaultSettings.ide = input.selectedIDE.ide.toLowerCase() === "vscode" ? "vscode" : input.selectedIDE.ide.toLowerCase();
+    const desiredIde = inheritedDefaults.ide ?? (input.selectedIDE?.supported ? normalizeSupportedIde(input.selectedIDE.ide) : void 0);
+    const desiredProviderDefault = inheritedDefaults.providerDefault ?? input.providerDefault;
+    if (desiredIde) {
+      defaultSettings.ide = desiredIde;
     }
-    if (input.providerDefault) {
-      defaultSettings["provider.default"] = input.providerDefault;
+    if (desiredProviderDefault) {
+      defaultSettings["provider.default"] = desiredProviderDefault;
     }
     if (input.options.dryRun) {
       reporter.dryRun(`Would create .inspecto/${settingsFileName}`);
@@ -1117,6 +1314,9 @@ async function applyOnboardingPlanInternal(input) {
     if (manualExtensionInstallNeeded) {
       nextSteps.push("Install the Inspecto IDE extension manually");
     }
+    if (additiveManualPlan && input.plan) {
+      nextSteps.push(...manualPlanSteps(input.plan, false));
+    }
     if (input.manualConfigRequiredFor === "Nuxt") {
       nextSteps.push(
         "Nuxt detected\u2014please follow the Nuxt instructions printed above to finish setup."
@@ -1167,6 +1367,28 @@ async function getResolvedPackageVersion(pkgName, root) {
     return null;
   }
 }
+function parseFirstSemver(version) {
+  if (!version) return null;
+  const match = version.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) {
+    return null;
+  }
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3])
+  };
+}
+function isLegacyRspackVersion(version) {
+  const parsed = parseFirstSemver(version);
+  if (!parsed) return false;
+  return parsed.major === 0 && parsed.minor < 4;
+}
+function isLegacyWebpackVersion(version) {
+  const parsed = parseFirstSemver(version);
+  if (!parsed) return false;
+  return parsed.major === 4;
+}
 var SUPPORTED_PATTERNS = [
   {
     tool: "vite",
@@ -1192,7 +1414,22 @@ var SUPPORTED_PATTERNS = [
   },
   {
     tool: "webpack",
-    files: ["webpack.config.js", "webpack.config.ts", "webpack.config.mjs", "webpack.config.cjs"],
+    files: [
+      "webpack.config.js",
+      "webpack.config.ts",
+      "webpack.config.mjs",
+      "webpack.config.cjs",
+      "webpack.config.common.js",
+      "webpack.config.common.ts",
+      "webpack.config.dev.js",
+      "webpack.config.dev.ts",
+      "webpack.config.prod.js",
+      "webpack.config.prod.ts",
+      "webpack.config.esbuild.js",
+      "webpack.config.esbuild.ts",
+      "webpack.config.build-pre.js",
+      "webpack.config.build-pre.ts"
+    ],
     label: "Webpack"
   },
   {
@@ -1207,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"] },
@@ -1320,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;
@@ -1337,6 +1580,89 @@ async function detectBuildTools(root, packagePaths) {
   }
   return { supported, unsupported: Array.from(unsupported) };
 }
+function rankScriptCommand(name, command) {
+  const haystack = `${name} ${command}`.toLowerCase();
+  let score = 0;
+  if (/(^|[\s:_-])(start|dev|serve|watch)([\s:_-]|$)/.test(haystack)) score += 8;
+  if (/(^|[\s:_-])(prod|build|release|stats)([\s:_-]|$)/.test(haystack)) score -= 3;
+  if (/(^|[\s:_-])(dll|vendor)([\s:_-]|$)/.test(haystack)) score -= 6;
+  if (haystack.includes("webpack-dev-server")) score += 3;
+  if (haystack.includes("webpack")) score += 1;
+  if (haystack.includes("rspack")) score += 1;
+  return score;
+}
+function extractConfigArgs(scriptContent) {
+  return Array.from(scriptContent.matchAll(/(?:-c|--config)\s+([^\s'"`;]+)/g)).map((match) => match[1]).filter((value) => Boolean(value));
+}
+async function resolveScriptRelativeCandidate(targetRoot, scriptPath, candidate) {
+  const normalizedCandidate = candidate.replace(/^['"`]|['"`]$/g, "");
+  const normalizedRelativeCandidate = path7.normalize(normalizedCandidate);
+  const possiblePaths = [];
+  if (normalizedRelativeCandidate.startsWith("..")) {
+    possiblePaths.push(
+      path7.normalize(path7.join(path7.dirname(scriptPath), normalizedRelativeCandidate))
+    );
+  } else {
+    possiblePaths.push(normalizedRelativeCandidate);
+    possiblePaths.push(
+      path7.normalize(path7.join(path7.dirname(scriptPath), normalizedRelativeCandidate))
+    );
+  }
+  for (const possiblePath of possiblePaths) {
+    if (await exists(path7.join(targetRoot, possiblePath))) {
+      return possiblePath.split(path7.sep).join("/");
+    }
+  }
+  return null;
+}
+async function resolveRspackConfigFromScript(targetRoot, scriptPath) {
+  const scriptContent = await readFile(path7.join(targetRoot, scriptPath));
+  if (!scriptContent) {
+    return null;
+  }
+  for (const candidate of extractConfigArgs(scriptContent)) {
+    const resolved = await resolveScriptRelativeCandidate(targetRoot, scriptPath, candidate);
+    if (resolved) {
+      return resolved;
+    }
+  }
+  const matches = scriptContent.matchAll(
+    /['"`]([^'"`\n]*rspack[^'"`\n]*config[^'"`\n]*\.(?:js|ts|mjs|cjs))['"`]/g
+  );
+  for (const match of matches) {
+    const candidate = match[1];
+    if (!candidate) continue;
+    const resolved = await resolveScriptRelativeCandidate(targetRoot, scriptPath, candidate);
+    if (resolved) {
+      return resolved;
+    }
+  }
+  return null;
+}
+async function resolveWebpackBaseConfigFromFile(targetRoot, configPath) {
+  const configContent = await readFile(path7.join(targetRoot, configPath));
+  if (!configContent) {
+    return null;
+  }
+  for (const candidate of extractConfigArgs(configContent)) {
+    const resolved = await resolveScriptRelativeCandidate(targetRoot, configPath, candidate);
+    if (resolved) {
+      return resolved;
+    }
+  }
+  const matches = configContent.matchAll(
+    /(?:configPath\s*=\s*|require\()\s*['"`]([^'"`\n]*webpack[^'"`\n]*config[^'"`\n]*\.(?:js|ts|mjs|cjs))['"`]/g
+  );
+  for (const match of matches) {
+    const candidate = match[1];
+    if (!candidate) continue;
+    const resolved = await resolveScriptRelativeCandidate(targetRoot, configPath, candidate);
+    if (resolved) {
+      return resolved;
+    }
+  }
+  return null;
+}
 async function detectPattern({
   pattern,
   workspaceRoot,
@@ -1361,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);
   }
@@ -1376,13 +1704,38 @@ async function detectPattern({
     }
   }
   if (hasDep && !detectedFile && (pattern.tool === "esbuild" || pattern.tool === "rollup" || pattern.tool === "webpack" || pattern.tool === "rspack" || pattern.tool === "rsbuild")) {
-    for (const cmd of Object.values(scripts)) {
+    const rankedScripts = Object.entries(scripts).sort(
+      ([leftName, leftCommand], [rightName, rightCommand]) => rankScriptCommand(rightName, rightCommand) - rankScriptCommand(leftName, leftCommand)
+    );
+    for (const [, cmd] of rankedScripts) {
+      if (pattern.tool === "webpack" || pattern.tool === "rspack") {
+        for (const configArg of extractConfigArgs(cmd)) {
+          const resolvedConfig = await resolveScriptRelativeCandidate(targetRoot, "", configArg);
+          if (resolvedConfig && (cmd.includes(pattern.tool) || cmd.includes(`${pattern.tool}-`))) {
+            if (pattern.tool === "webpack") {
+              detectedFile = await resolveWebpackBaseConfigFromFile(targetRoot, resolvedConfig) ?? resolvedConfig;
+            } else {
+              detectedFile = await resolveRspackConfigFromScript(targetRoot, resolvedConfig) ?? resolvedConfig;
+            }
+            break;
+          }
+        }
+        if (detectedFile) {
+          break;
+        }
+      }
       if (cmd.includes("node ")) {
         const match = cmd.match(/node\s+([^\s]+\.(js|mjs|cjs|ts))/);
         if (match && match[1]) {
           if (await exists(path7.join(targetRoot, match[1]))) {
             if (cmd.includes(pattern.tool) || match[1].includes(pattern.tool)) {
-              detectedFile = match[1];
+              if (pattern.tool === "rspack") {
+                detectedFile = await resolveRspackConfigFromScript(targetRoot, match[1]) ?? match[1];
+              } else if (pattern.tool === "webpack") {
+                detectedFile = await resolveWebpackBaseConfigFromFile(targetRoot, match[1]) ?? match[1];
+              } else {
+                detectedFile = match[1];
+              }
               break;
             }
           }
@@ -1411,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;
@@ -1419,13 +1772,11 @@ async function detectPattern({
   let isLegacyRspack = false;
   let isLegacyWebpack = false;
   if (pattern.tool === "rspack") {
-    const version = resolvedVersion;
-    if (version && (version.includes("0.3.") || version.includes("0.2.") || version.includes("0.1."))) {
+    if (isLegacyRspackVersion(resolvedVersion)) {
       isLegacyRspack = true;
     }
   } else if (pattern.tool === "webpack") {
-    const version = resolvedVersion;
-    if (version && version.includes("^4") || version?.startsWith("4.")) {
+    if (isLegacyWebpackVersion(resolvedVersion)) {
       isLegacyWebpack = true;
     }
   }
@@ -1435,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) {
@@ -1467,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 {
@@ -1685,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 };
@@ -1711,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(
@@ -1737,6 +2509,28 @@ function buildToolBlockers(context) {
   }
   return [message("missing-build-tool", "No supported build tool detected")];
 }
+function buildToolWarnings(context) {
+  const warnings = [];
+  if (context.buildTools.supported.length === 1) {
+    const buildTool = context.buildTools.supported[0];
+    if (buildTool.tool === "rspack" && buildTool.isLegacyRspack) {
+      warnings.push(
+        message(
+          "legacy-rspack-requires-manual-config",
+          `Legacy Rspack detected at ${buildTool.configPath}. Inspecto must use the legacy Rspack plugin entry and manual config steps.`
+        )
+      );
+    } else if (buildTool.tool === "webpack" && buildTool.isLegacyWebpack) {
+      warnings.push(
+        message(
+          "legacy-webpack4-requires-manual-config",
+          `Webpack 4 detected at ${buildTool.configPath}. Inspecto must use the legacy Webpack 4 plugin entry and manual config steps.`
+        )
+      );
+    }
+  }
+  return warnings;
+}
 function frameworkBlockers(context) {
   if (context.frameworks.supported.length > 0) {
     return [];
@@ -1798,6 +2592,35 @@ function manualBuildToolActions(context) {
       }
     ];
   }
+  const buildTool = context.buildTools.supported[0];
+  if (buildTool?.tool === "rspack" && buildTool.isLegacyRspack) {
+    return [
+      {
+        type: "install_dependency",
+        target: "@inspecto-dev/plugin @inspecto-dev/core",
+        description: `Install the Inspecto runtime packages with ${context.packageManager}.`
+      },
+      {
+        type: "manual_step",
+        target: buildTool.configPath,
+        description: `Update ${buildTool.configPath} to import \`rspackPlugin\` from \`@inspecto-dev/plugin/legacy/rspack\` and add it to the Rspack plugins array.`
+      }
+    ];
+  }
+  if (buildTool?.tool === "webpack" && buildTool.isLegacyWebpack) {
+    return [
+      {
+        type: "install_dependency",
+        target: "@inspecto-dev/plugin @inspecto-dev/core",
+        description: `Install the Inspecto runtime packages with ${context.packageManager}.`
+      },
+      {
+        type: "manual_step",
+        target: buildTool.configPath,
+        description: `Update ${buildTool.configPath} to import \`webpackPlugin\` from \`@inspecto-dev/plugin/legacy/webpack4\` and add it to the Webpack plugins array.`
+      }
+    ];
+  }
   return [
     {
       type: "manual_step",
@@ -1806,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 [
@@ -1826,7 +2689,10 @@ function manualFrameworkActions(context) {
 }
 async function createDetectionResult(root) {
   const context = await buildOnboardingContext(root);
-  const warnings = uniqueMessages([...unsupportedEnvironmentWarnings(context)]);
+  const warnings = uniqueMessages([
+    ...unsupportedEnvironmentWarnings(context),
+    ...buildToolWarnings(context)
+  ]);
   const buildToolResult = buildToolBlockers(context);
   const frameworkResult = frameworkBlockers(context);
   const blockers = uniqueMessages([...buildToolResult, ...frameworkResult]);
@@ -1849,13 +2715,169 @@ async function createDetectionResult(root) {
   };
 }
 function createPlanResult(context) {
-  const warnings = uniqueMessages(unsupportedEnvironmentWarnings(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)
+  ]);
   const blockers = uniqueMessages([...buildToolBlockers(context), ...frameworkBlockers(context)]);
   const actions = [];
   let strategy = "supported";
-  if (blockers.length > 0) {
+  const hasLegacyRspackManualPlan = context.buildTools.supported.length === 1 && context.buildTools.supported[0]?.tool === "rspack" && context.buildTools.supported[0]?.isLegacyRspack;
+  const hasLegacyWebpackManualPlan = context.buildTools.supported.length === 1 && context.buildTools.supported[0]?.tool === "webpack" && context.buildTools.supported[0]?.isLegacyWebpack;
+  if (blockers.length > 0 || hasLegacyRspackManualPlan || hasLegacyWebpackManualPlan) {
     strategy = "manual";
-    if (context.buildTools.unsupported.length > 0 || context.buildTools.supported.length === 0 || context.buildTools.supported.length > 1) {
+    if (context.buildTools.unsupported.length > 0 || context.buildTools.supported.length === 0 || context.buildTools.supported.length > 1 || context.buildTools.supported.some(
+      (buildTool) => buildTool.tool === "rspack" && buildTool.isLegacyRspack
+    ) || context.buildTools.supported.some(
+      (buildTool) => buildTool.tool === "webpack" && buildTool.isLegacyWebpack
+    )) {
       actions.push(...manualBuildToolActions(context));
     }
     if (frameworkBlockers(context).length > 0) {
@@ -1875,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;
   }
@@ -1905,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
@@ -2036,14 +3062,107 @@ 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) {
+  return [candidate.packagePath || ".", candidate.buildTool, candidate.configPath].join(":");
+}
 function normalizePackagePath(packagePath) {
   if (!packagePath || packagePath === ".") return "";
   return packagePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
 }
+function normalizeTargetValue(target) {
+  if (!target) return "";
+  return target.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+}
+function buildSelectionPurpose() {
+  return "Choose the build target that runs your local development build so Inspecto can attach the right plugin and settings.";
+}
+function buildSelectionInstructions(hasCandidates) {
+  if (!hasCandidates) {
+    return "If auto-detection missed your build entrypoint, rerun with --target <configPath> using the config file or wrapper script your dev command actually starts.";
+  }
+  return "Rerun with --target <candidateId> using one returned candidateId. The CLI also accepts an exact configPath from the candidate list as a compatibility fallback.";
+}
 function looksLikeAppPackage(packagePath) {
   if (!packagePath) return true;
   return /(^|\/)(app|apps|web|client|frontend|site)(\/|$)/i.test(packagePath);
@@ -2054,13 +3173,19 @@ function looksLikeAuxiliaryPackage(packagePath) {
 function buildCandidates(input) {
   return input.buildTools.map((buildTool) => {
     const packagePath = normalizePackagePath(buildTool.packagePath);
-    return {
+    const candidate = {
       packagePath,
       configPath: buildTool.configPath,
+      label: buildTool.label,
       buildTool: buildTool.tool,
+      ...buildTool.isLegacyRspack ? { isLegacyRspack: true } : {},
+      ...buildTool.isLegacyWebpack ? { isLegacyWebpack: true } : {},
       frameworks: input.frameworkSupportByPackage[packagePath] ?? [],
       automaticInjection: true
     };
+    candidate.id = buildCandidateId(candidate);
+    candidate.candidateId = candidate.id;
+    return candidate;
   });
 }
 function rankCandidate(candidate) {
@@ -2083,18 +3208,52 @@ function resolveOnboardingTarget(input) {
     return {
       status: "needs_selection",
       candidates,
-      reason: "No supported targets were detected."
+      reason: "No supported targets were detected.",
+      selectionPurpose: buildSelectionPurpose(),
+      selectionInstructions: buildSelectionInstructions(false)
     };
   }
   const explicitlySelected = normalizePackagePath(input.selectedPackagePath);
+  const explicitlySelectedValue = normalizeTargetValue(input.selectedPackagePath);
   if (input.selectedPackagePath !== void 0) {
-    const selected = candidates.find((candidate) => candidate.packagePath === explicitlySelected);
+    const selectedById = candidates.find(
+      (candidate) => candidate.id === input.selectedPackagePath || candidate.candidateId === input.selectedPackagePath
+    );
+    if (selectedById) {
+      return {
+        status: "resolved",
+        selected: selectedById,
+        candidates,
+        reason: `Using the explicitly selected target: ${selectedById.configPath}.`,
+        selectionPurpose: buildSelectionPurpose(),
+        selectionInstructions: buildSelectionInstructions(true)
+      };
+    }
+    const selectedByConfigPath = candidates.find(
+      (candidate) => normalizeTargetValue(candidate.configPath) === explicitlySelectedValue
+    );
+    if (selectedByConfigPath) {
+      return {
+        status: "resolved",
+        selected: selectedByConfigPath,
+        candidates,
+        reason: `Using the explicitly selected config path: ${selectedByConfigPath.configPath}.`,
+        selectionPurpose: buildSelectionPurpose(),
+        selectionInstructions: buildSelectionInstructions(true)
+      };
+    }
+    const matchingPackageCandidates = candidates.filter(
+      (candidate) => candidate.packagePath === explicitlySelected
+    );
+    const selected = matchingPackageCandidates.length === 1 ? matchingPackageCandidates[0] : void 0;
     if (selected) {
       return {
         status: "resolved",
         selected,
         candidates,
-        reason: `Using the explicitly selected target: ${selected.packagePath || "."}.`
+        reason: `Using the explicitly selected target: ${selected.packagePath || "."}.`,
+        selectionPurpose: buildSelectionPurpose(),
+        selectionInstructions: buildSelectionInstructions(true)
       };
     }
   }
@@ -2103,7 +3262,9 @@ function resolveOnboardingTarget(input) {
       status: "resolved",
       selected: candidates[0],
       candidates,
-      reason: "Only one supported target was detected."
+      reason: "Only one supported target was detected.",
+      selectionPurpose: buildSelectionPurpose(),
+      selectionInstructions: buildSelectionInstructions(true)
     };
   }
   const ranked = rankCandidates(candidates);
@@ -2111,14 +3272,18 @@ function resolveOnboardingTarget(input) {
     return {
       status: "needs_selection",
       candidates,
-      reason: "Multiple supported targets look equally plausible."
+      reason: "Multiple supported targets look equally plausible.",
+      selectionPurpose: buildSelectionPurpose(),
+      selectionInstructions: buildSelectionInstructions(true)
     };
   }
   return {
     status: "resolved",
     selected: ranked[0].candidate,
     candidates,
-    reason: `Preselected ${ranked[0].candidate.packagePath || "."} because it has the strongest supported app signal.`
+    reason: `Preselected ${ranked[0].candidate.packagePath || "."} because it has the strongest supported app signal.`,
+    selectionPurpose: buildSelectionPurpose(),
+    selectionInstructions: buildSelectionInstructions(true)
   };
 }
 
@@ -2236,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'",
@@ -2247,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) {",
@@ -2257,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'",
@@ -2269,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",
@@ -2279,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'",
@@ -2298,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
@@ -2313,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 {
@@ -2326,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;
@@ -2361,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.");
@@ -2426,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");
@@ -2585,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;
     })
   );
@@ -2593,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,
@@ -2608,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) {
@@ -2637,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"
     ]);
@@ -2659,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 {
@@ -2731,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`, [], {
@@ -2750,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}`, [], {
@@ -2773,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")
@@ -2809,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) {
@@ -2819,6 +4134,25 @@ async function collectDoctorResult(root = process.cwd()) {
     const settings = await readJSON(targetPath);
     if (settings) {
       checks.push(createDiagnostic("settings-valid", "ok", `.inspecto/${fileName} valid`));
+      const configuredIde = typeof settings.ide === "string" ? settings.ide : void 0;
+      const detectedIdeCandidates = ideProbe.detected.map((item) => item.ide);
+      if (configuredIde && detectedIdeCandidates.length > 0 && !detectedIdeCandidates.includes(configuredIde)) {
+        checks.push(
+          createDiagnostic(
+            "settings-ide-mismatch",
+            "warning",
+            `.inspecto/${fileName} sets ide=${configuredIde}, but the current environment looks like ${detectedIdeCandidates.join(", ")}. Inspecto will use the configured IDE from ${fileName}.`,
+            [
+              `Update .inspecto/${fileName} if you want Inspecto to target the currently detected IDE instead.`
+            ],
+            {
+              configuredIde,
+              detectedIdeCandidates,
+              precedence: `configured ide from ${fileName}`
+            }
+          )
+        );
+      }
     } else {
       checks.push(
         createDiagnostic(
@@ -2844,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) {
@@ -2882,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(/\/$/, "");
@@ -2906,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 {
@@ -2917,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 {
@@ -2934,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"
   };
 }
@@ -2947,15 +4298,16 @@ 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;
     })
   );
   return supportByPackage;
 }
-async function buildTargetedContext(rootContext, packagePath) {
-  const projectRoot = packagePath ? path13.join(rootContext.root, packagePath) : rootContext.root;
+async function buildTargetedContext(rootContext, target) {
+  const packagePath = normalizePackagePath2(target.packagePath);
+  const projectRoot = packagePath ? path17.join(rootContext.root, packagePath) : rootContext.root;
   const [frameworks, ides, providers] = await Promise.all([
     detectFrameworks(projectRoot),
     detectIDE(projectRoot),
@@ -2966,7 +4318,11 @@ async function buildTargetedContext(rootContext, packagePath) {
     packageManager: rootContext.packageManager,
     buildTools: {
       supported: rootContext.buildTools.supported.filter((item) => {
-        return normalizePackagePath2(item.packagePath) === packagePath;
+        const itemPackagePath = normalizePackagePath2(item.packagePath);
+        if (target.id) {
+          return `${itemPackagePath || "."}:${item.tool}:${item.configPath}` === target.id;
+        }
+        return itemPackagePath === packagePath;
       }),
       unsupported: []
     },
@@ -2984,7 +4340,11 @@ async function buildTargetedContext(rootContext, packagePath) {
   };
 }
 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}.`;
@@ -3028,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) {
@@ -3050,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
   };
 }
@@ -3084,25 +4453,41 @@ 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") {
     const plan3 = createPlanResult(rootContext);
     const summary2 = {
-      headline: "Inspecto found multiple plausible app targets and needs one selection.",
+      headline: "Inspecto needs one build target selection before setup so it knows which local dev build should receive the plugin and settings.",
       changes: [],
       risks: [],
       manualFollowUp: []
@@ -3118,8 +4503,7 @@ async function resolveOnboardingSession(root, options = {}) {
       projectRoot: root
     };
   }
-  const packagePath = normalizePackagePath2(target.selected?.packagePath);
-  const context = await buildTargetedContext(rootContext, packagePath);
+  const context = await buildTargetedContext(rootContext, target.selected);
   const verification = await buildVerification(context.root, context.packageManager);
   const plan2 = createPlanResult(context);
   const summary = buildOnboardingSummary(plan2, context.root);
@@ -3143,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,
@@ -3153,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 = {}) {
@@ -3172,23 +4567,33 @@ async function applyResolvedOnboardingSession(session, options = {}) {
     },
     selectedIDE: session.selectedIDE,
     providerDefault: session.providerDefault,
-    plan: session.plan
+    plan: session.plan,
+    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) {
@@ -3211,23 +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);
-  for (const change of result.summary.changes) {
+  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 normalized.target.candidates) {
+      const identifier = candidate.candidateId ?? candidate.id ?? candidate.configPath;
+      const label = candidate.label ?? candidate.configPath;
+      log.hint(`${identifier}: ${label}`);
+    }
+    if (normalized.target.selectionInstructions) {
+      log.hint(normalized.target.selectionInstructions);
+    }
+  }
+  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 = {}) {
@@ -3235,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);
 }
 
@@ -3278,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.");
@@ -3295,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);
@@ -3345,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();
@@ -3354,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 {
@@ -3397,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,
@@ -3423,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);
@@ -3464,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();
@@ -3507,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);
@@ -3546,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: {
@@ -3889,6 +5346,10 @@ function getDispatchModeLabel(assistant, ide, mode) {
 }
 
 // src/commands/integration-install.ts
+import {
+  DEFAULT_PROVIDER_MODE,
+  VALID_MODES
+} from "@inspecto-dev/types";
 var REPO_RAW_BASE = "https://raw.githubusercontent.com/inspecto-dev/inspecto/main";
 var TOTAL_STEPS2 = 6;
 var INTEGRATION_MANIFESTS = [
@@ -3937,7 +5398,7 @@ var INTEGRATION_MANIFESTS = [
   {
     assistant: "coco",
     type: "native-skill",
-    installTarget: ".traecli/skills/inspecto-onboarding/",
+    installTarget: ".trae/skills/inspecto-onboarding/",
     preferredInstall: "npx @inspecto-dev/cli integrations install coco --host-ide <vscode|cursor|trae|trae-cn>",
     cliSupported: true
   }
@@ -3955,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.`);
@@ -3992,10 +5453,13 @@ ${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);
       }
     }
   }
+  if (shouldPersistProjectOnboardingDefaults(options)) {
+    await persistProjectOnboardingDefaults(assistant, options);
+  }
   const stepOneMessage = options.preview ? formatIntegrationStep2(1, `Previewing ${getAssistantLabel2(assistant)} integration assets`) : formatIntegrationStep2(1, `Installed ${getAssistantLabel2(assistant)} integration assets`);
   if (!silent) {
     if (options.preview) {
@@ -4041,7 +5505,7 @@ ${content}`;
   }
   const automationResult = await runIntegrationAutomation(
     assistant,
-    { ...options, silent },
+    { ...options, silent, ignoreProjectArtifacts: true },
     process.cwd()
   );
   const result = {
@@ -4081,6 +5545,46 @@ ${content}`;
   }
   return result;
 }
+function shouldPersistProjectOnboardingDefaults(options) {
+  return !options.preview && !shouldSkipAutomationForInstall(options) && isSupportedHostIde(options.ide);
+}
+function isProviderAssistant(value) {
+  return Object.prototype.hasOwnProperty.call(VALID_MODES, value);
+}
+async function resolveProviderDefaultForAssistant(assistant, ide) {
+  if (!isProviderAssistant(assistant)) {
+    return void 0;
+  }
+  let mode;
+  if (assistant === "codex" || assistant === "claude-code" || assistant === "gemini") {
+    const dispatchMode = await resolveIntegrationDispatchMode({ assistant, hostIde: ide });
+    mode = dispatchMode.mode ?? DEFAULT_PROVIDER_MODE[assistant];
+  } else {
+    mode = DEFAULT_PROVIDER_MODE[assistant];
+  }
+  if (!mode || !VALID_MODES[assistant].includes(mode)) {
+    return void 0;
+  }
+  return `${assistant}.${mode}`;
+}
+async function persistProjectOnboardingDefaults(assistant, options) {
+  const settingsPath = path21.join(process.cwd(), ".inspecto", "settings.local.json");
+  const existingSettings = await readJSON(settingsPath);
+  const resolvedHostIde = await resolveIntegrationHostIde({
+    explicitIde: options.ide,
+    cwd: process.cwd()
+  });
+  const providerDefault = resolvedHostIde.ide && resolvedHostIde.confidence !== "low" ? await resolveProviderDefaultForAssistant(assistant, resolvedHostIde.ide) : void 0;
+  const mergedSettings = existingSettings && typeof existingSettings === "object" ? {
+    ...existingSettings,
+    ide: options.ide,
+    ...providerDefault ? { "provider.default": providerDefault } : {}
+  } : {
+    ide: options.ide,
+    ...providerDefault ? { "provider.default": providerDefault } : {}
+  };
+  await writeJSON(settingsPath, mergedSettings);
+}
 function shouldSkipAutomationForInstall(options) {
   return options.scope === "user" && !options.preview;
 }
@@ -4143,6 +5647,12 @@ function resolveInstallPlan(assistant, options) {
             source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-trae/SKILL.md`,
             target: ".trae/skills/inspecto-onboarding/SKILL.md",
             localSource: "skills/inspecto-onboarding-trae/SKILL.md"
+          },
+          {
+            source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-trae/scripts/run-inspecto.sh`,
+            target: ".trae/skills/inspecto-onboarding/scripts/run-inspecto.sh",
+            localSource: "skills/inspecto-onboarding-trae/scripts/run-inspecto.sh",
+            executable: true
           }
         ],
         successMessage: "Installed Trae skill to .trae/skills/inspecto-onboarding/SKILL.md",
@@ -4153,11 +5663,17 @@ function resolveInstallPlan(assistant, options) {
         assets: [
           {
             source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-trae/SKILL.md`,
-            target: ".traecli/skills/inspecto-onboarding/SKILL.md",
+            target: ".trae/skills/inspecto-onboarding/SKILL.md",
             localSource: "skills/inspecto-onboarding-trae/SKILL.md"
+          },
+          {
+            source: `${REPO_RAW_BASE}/skills/inspecto-onboarding-trae/scripts/run-inspecto.sh`,
+            target: ".trae/skills/inspecto-onboarding/scripts/run-inspecto.sh",
+            localSource: "skills/inspecto-onboarding-trae/scripts/run-inspecto.sh",
+            executable: true
           }
         ],
-        successMessage: "Installed Coco skill to .traecli/skills/inspecto-onboarding/SKILL.md",
+        successMessage: "Installed Coco skill to .trae/skills/inspecto-onboarding/SKILL.md",
         nextStep: "Start a new Coco session."
       };
     default:
@@ -4198,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"
       }
@@ -4233,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"
       }
@@ -4313,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;
   }
@@ -4434,6 +5950,9 @@ export {
   reportCommandError,
   apply,
   detect,
+  devLink,
+  devStatus,
+  devUnlink,
   init,
   collectDoctorResult,
   doctor,