@inspecto-dev/cli 0.3.3 → 0.3.5

package/src/onboarding/session.ts

@@ -2,6 +2,11 @@ import path from 'node:path'
 import { detectFrameworks } from '../detect/framework.js'
 import { detectIDE } from '../detect/ide.js'
 import { detectProviders } from '../detect/provider.js'
+import {
+  getHostIdeBinaryName,
+  isSupportedHostIde,
+  type SupportedHostIde,
+} from '../integrations/capabilities.js'
 import { applyOnboardingPlan, type ApplyOnboardingResult } from './apply.js'
 import { buildOnboardingContext } from './context.js'
 import { createPlanResult, planManualFollowUp } from './planner.js'
@@ -61,9 +66,10 @@ async function buildVerification(
   projectRoot: string,
   packageManager: OnboardingContext['packageManager'],
 ): Promise<OnboardingVerification> {
-  const packageJson = await readJSON<{ scripts?: Record<string, string> }>(
-    path.join(projectRoot, 'package.json'),
-  )
+  const packageJson = await readJSON<{
+    scripts?: Record<string, string>
+    dependencies?: Record<string, string>
+  }>(path.join(projectRoot, 'package.json'))
 
   if (packageJson?.scripts?.dev) {
     const devCommand = getVerificationCommand(packageManager)
@@ -74,13 +80,34 @@ async function buildVerification(
     }
   }
 
+  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?: string): string {
+  if (ide && isSupportedHostIde(ide)) {
+    const binaryName = getHostIdeBinaryName(ide as SupportedHostIde)
+    if (binaryName) {
+      return `${binaryName} --install-extension inspecto.inspecto`
+    }
+  }
+
+  return 'code --install-extension inspecto.inspecto'
+}
+
 function buildIdeExtensionStatus(input: {
+  ide?: string
   required: boolean
   installed: boolean
   manualRequired: boolean
@@ -97,8 +124,12 @@ 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',
   }
 }
@@ -126,8 +157,9 @@ async function detectFrameworkSupportByPackage(
 
 async function buildTargetedContext(
   rootContext: OnboardingContext,
-  packagePath: string,
+  target: { id?: string; packagePath: string },
 ): Promise<OnboardingContext> {
+  const packagePath = normalizePackagePath(target.packagePath)
   const projectRoot = packagePath ? path.join(rootContext.root, packagePath) : rootContext.root
   const [frameworks, ides, providers] = await Promise.all([
     detectFrameworks(projectRoot),
@@ -140,7 +172,11 @@ async function buildTargetedContext(
     packageManager: rootContext.packageManager,
     buildTools: {
       supported: rootContext.buildTools.supported.filter(item => {
-        return normalizePackagePath(item.packagePath) === packagePath
+        const itemPackagePath = normalizePackagePath(item.packagePath)
+        if (target.id) {
+          return `${itemPackagePath || '.'}:${item.tool}:${item.configPath}` === target.id
+        }
+        return itemPackagePath === packagePath
       }),
       unsupported: [],
     },
@@ -160,7 +196,12 @@ async function buildTargetedContext(
 
 function buildOnboardingSummary(plan: PlanResult, projectRoot: string): OnboardingSummary {
   const changes = plan.actions
-    .filter(action => action.type !== 'manual_step')
+    .filter(
+      action =>
+        !['manual_step', 'generate_patch_plan', 'generate_file', 'manual_confirmation'].includes(
+          action.type,
+        ),
+    )
     .map(action => action.description)
   const risks = [...plan.warnings.map(item => item.message)]
   const manualFollowUp = planManualFollowUp(plan)
@@ -230,18 +271,28 @@ function buildPreApplyResult(
         }
       : undefined
 
+  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 } : {}),
   }
 }
 
@@ -258,8 +309,8 @@ function buildExecutionResult(
     installedDependencies: applyResult.mutations
       .map(item => item.name)
       .filter((value): value is string => !!value),
-    selectedProviderDefault: session.providerDefault,
-    selectedIDE: session.selectedIDE?.ide,
+    ...(session.providerDefault ? { selectedProviderDefault: session.providerDefault } : {}),
+    ...(session.selectedIDE?.ide ? { selectedIDE: session.selectedIDE.ide } : {}),
     mutations: applyResult.mutations,
   }
 }
@@ -307,27 +358,48 @@ export async function resolveOnboardingSession(
     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 plan = createPlanResult(rootContext)
+    const guidedStatus = plan.strategy === 'guided' ? 'partial_success' : 'error'
+    const resolvedTarget =
+      plan.strategy === 'guided'
+        ? {
+            status: 'guided' as const,
+            candidates: [],
+            reason: `Guided onboarding is available for ${plan.metaFramework ?? 'this project'}.`,
+          }
+        : target
     return {
-      status: 'error',
-      target,
+      status: guidedStatus,
+      target: resolvedTarget,
       summary: buildOnboardingSummary(plan, root),
       confirmation: { required: false },
       verification: rootVerification,
       context: rootContext,
       plan,
       projectRoot: root,
+      ...(plan.framework ? { framework: plan.framework } : {}),
+      ...(plan.metaFramework ? { metaFramework: plan.metaFramework } : {}),
+      ...(plan.routerMode ? { routerMode: plan.routerMode } : {}),
+      ...(plan.autoApplied ? { autoApplied: plan.autoApplied } : {}),
+      ...(plan.pendingSteps ? { pendingSteps: plan.pendingSteps } : {}),
+      ...(plan.assistantPrompt ? { assistantPrompt: plan.assistantPrompt } : {}),
+      ...(plan.patches ? { patches: plan.patches } : {}),
     }
   }
 
   if (target.status === 'needs_selection') {
     const plan = createPlanResult(rootContext)
     const summary: OnboardingSummary = {
-      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: [],
@@ -344,8 +416,7 @@ export async function resolveOnboardingSession(
     }
   }
 
-  const packagePath = normalizePackagePath(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 plan = createPlanResult(context)
   const summary = buildOnboardingSummary(plan, context.root)
@@ -375,6 +446,11 @@ export async function resolveOnboardingSession(
     status = 'partial_success'
   }
 
+  const providerDefault = getProviderDefault(
+    plan.defaults.provider,
+    selectedProvider?.preferredMode,
+  )
+
   return {
     status,
     target,
@@ -385,7 +461,14 @@ export async function resolveOnboardingSession(
     plan,
     projectRoot: context.root,
     selectedIDE,
-    providerDefault: getProviderDefault(plan.defaults.provider, selectedProvider?.preferredMode),
+    ...(providerDefault ? { providerDefault } : {}),
+    ...(plan.framework ? { framework: plan.framework } : {}),
+    ...(plan.metaFramework ? { metaFramework: plan.metaFramework } : {}),
+    ...(plan.routerMode ? { routerMode: plan.routerMode } : {}),
+    ...(plan.autoApplied ? { autoApplied: plan.autoApplied } : {}),
+    ...(plan.pendingSteps ? { pendingSteps: plan.pendingSteps } : {}),
+    ...(plan.assistantPrompt ? { assistantPrompt: plan.assistantPrompt } : {}),
+    ...(plan.patches ? { patches: plan.patches } : {}),
   }
 }
 
@@ -409,6 +492,9 @@ export async function applyResolvedOnboardingSession(
     selectedIDE: session.selectedIDE,
     providerDefault: session.providerDefault,
     plan: session.plan,
+    allowManualPlanApply:
+      (session.plan.strategy === 'manual' || session.plan.strategy === 'guided') &&
+      session.plan.blockers.length === 0,
   })
 
   const diagnostics = buildExecutionDiagnostics(session, applyResult)
@@ -419,20 +505,30 @@ export async function applyResolvedOnboardingSession(
         ? '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 } : {}),
   }
 }
 

package/src/onboarding/target-resolution.ts

@@ -16,11 +16,36 @@ interface RankedCandidate {
   score: number
 }
 
+function buildCandidateId(candidate: {
+  packagePath: string
+  buildTool: string
+  configPath: string
+}): string {
+  return [candidate.packagePath || '.', candidate.buildTool, candidate.configPath].join(':')
+}
+
 function normalizePackagePath(packagePath?: string): string {
   if (!packagePath || packagePath === '.') return ''
   return packagePath.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '')
 }
 
+function normalizeTargetValue(target?: string): string {
+  if (!target) return ''
+  return target.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/$/, '')
+}
+
+function buildSelectionPurpose(): string {
+  return 'Choose the build target that runs your local development build so Inspecto can attach the right plugin and settings.'
+}
+
+function buildSelectionInstructions(hasCandidates: boolean): string {
+  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: string): boolean {
   if (!packagePath) return true
   return /(^|\/)(app|apps|web|client|frontend|site)(\/|$)/i.test(packagePath)
@@ -33,13 +58,19 @@ function looksLikeAuxiliaryPackage(packagePath: string): boolean {
 function buildCandidates(input: ResolveOnboardingTargetInput): OnboardingTargetCandidate[] {
   return input.buildTools.map(buildTool => {
     const packagePath = normalizePackagePath(buildTool.packagePath)
-    return {
+    const candidate: OnboardingTargetCandidate = {
       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
   })
 }
 
@@ -73,18 +104,57 @@ export function resolveOnboardingTarget(
       status: 'needs_selection',
       candidates,
       reason: 'No supported targets were detected.',
+      selectionPurpose: buildSelectionPurpose(),
+      selectionInstructions: buildSelectionInstructions(false),
     }
   }
 
   const explicitlySelected = normalizePackagePath(input.selectedPackagePath)
+  const explicitlySelectedValue = normalizeTargetValue(input.selectedPackagePath)
   if (input.selectedPackagePath !== undefined) {
-    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] : undefined
     if (selected) {
       return {
         status: 'resolved',
         selected,
         candidates,
         reason: `Using the explicitly selected target: ${selected.packagePath || '.'}.`,
+        selectionPurpose: buildSelectionPurpose(),
+        selectionInstructions: buildSelectionInstructions(true),
       }
     }
   }
@@ -92,9 +162,11 @@ export function resolveOnboardingTarget(
   if (candidates.length === 1) {
     return {
       status: 'resolved',
-      selected: candidates[0],
+      selected: candidates[0]!,
       candidates,
       reason: 'Only one supported target was detected.',
+      selectionPurpose: buildSelectionPurpose(),
+      selectionInstructions: buildSelectionInstructions(true),
     }
   }
 
@@ -104,6 +176,8 @@ export function resolveOnboardingTarget(
       status: 'needs_selection',
       candidates,
       reason: 'Multiple supported targets look equally plausible.',
+      selectionPurpose: buildSelectionPurpose(),
+      selectionInstructions: buildSelectionInstructions(true),
     }
   }
 
@@ -112,5 +186,7 @@ export function resolveOnboardingTarget(
     selected: ranked[0]!.candidate,
     candidates,
     reason: `Preselected ${ranked[0]!.candidate.packagePath || '.'} because it has the strongest supported app signal.`,
+    selectionPurpose: buildSelectionPurpose(),
+    selectionInstructions: buildSelectionInstructions(true),
   }
 }

package/src/onboarding/umi-guidance.ts

@@ -0,0 +1,139 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import type { OnboardingPatchPlan } from '../types.js'
+
+export interface UmiGuidance {
+  framework: 'react'
+  metaFramework: 'Umi'
+  autoApplied: string[]
+  pendingSteps: string[]
+  assistantPrompt: string
+  patches: OnboardingPatchPlan[]
+}
+
+const UMI_CONFIG_CANDIDATES = [
+  '.umirc.ts',
+  '.umirc.js',
+  'config/config.ts',
+  'config/config.js',
+] as const
+
+function findFirstExisting(root: string, candidates: readonly string[]): string | undefined {
+  for (const candidate of candidates) {
+    if (fs.existsSync(path.join(root, candidate))) {
+      return candidate
+    }
+  }
+
+  return undefined
+}
+
+function readConfig(root: string, relativePath?: string): string {
+  if (!relativePath) return ''
+  const filePath = path.join(root, relativePath)
+  if (!fs.existsSync(filePath)) return ''
+  return fs.readFileSync(filePath, 'utf8')
+}
+
+function detectPatchShape(source: string): {
+  status: OnboardingPatchPlan['status']
+  reason: OnboardingPatchPlan['reason']
+  confidence: OnboardingPatchPlan['confidence']
+} {
+  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(): string {
+  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(): string {
+  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')
+}
+
+export function createUmiGuidance(root: string): UmiGuidance {
+  const configPath = findFirstExisting(root, UMI_CONFIG_CANDIDATES) ?? '.umirc.ts'
+  const configSource = readConfig(root, findFirstExisting(root, UMI_CONFIG_CANDIDATES))
+  const patchShape = detectPatchShape(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(),
+      },
+    ],
+  }
+}

package/src/types.ts

@@ -63,18 +63,25 @@ export interface OnboardingContext {
 }
 
 export interface OnboardingTargetCandidate {
+  id?: string
+  candidateId?: string
   packagePath: string
   configPath: string
+  label?: string
   buildTool: BuildTool
+  isLegacyRspack?: boolean
+  isLegacyWebpack?: boolean
   frameworks: string[]
   automaticInjection: boolean
 }
 
 export interface OnboardingTargetResolution {
-  status: 'resolved' | 'needs_selection'
+  status: 'resolved' | 'needs_selection' | 'guided'
   selected?: OnboardingTargetCandidate
   candidates: OnboardingTargetCandidate[]
   reason: string
+  selectionPurpose?: string
+  selectionInstructions?: string
 }
 
 export interface OnboardingSummary {
@@ -84,6 +91,14 @@ export interface OnboardingSummary {
   manualFollowUp: string[]
 }
 
+export interface OnboardingPatchPlan {
+  path: string
+  status: 'planned' | 'manual_patch_required'
+  reason: string
+  snippet: string
+  confidence: 'high' | 'medium' | 'low'
+}
+
 export interface OnboardingConfirmation {
   required: boolean
   reason?: string
@@ -119,6 +134,16 @@ export interface OnboardingVerification {
   message: string
 }
 
+export interface OnboardingAssistantHandoff {
+  framework?: string
+  metaFramework?: string
+  routerMode?: 'app' | 'pages' | 'mixed' | 'unknown'
+  autoApplied?: string[]
+  pendingSteps?: string[]
+  assistantPrompt?: string
+  patches?: OnboardingPatchPlan[]
+}
+
 export interface ResolvedOnboardingSession {
   status: OnboardStatus
   target: OnboardingTargetResolution
@@ -130,6 +155,14 @@ export interface ResolvedOnboardingSession {
   projectRoot: string
   selectedIDE?: { ide: string; supported: boolean } | null
   providerDefault?: string
+  framework?: string
+  metaFramework?: string
+  routerMode?: 'app' | 'pages' | 'mixed' | 'unknown'
+  autoApplied?: string[]
+  pendingSteps?: string[]
+  assistantPrompt?: string
+  patches?: OnboardingPatchPlan[]
+  handoff?: OnboardingAssistantHandoff
 }
 
 export interface OnboardCommandResult {
@@ -141,6 +174,14 @@ export interface OnboardCommandResult {
   verification?: OnboardingVerification
   result?: OnboardingExecutionResult
   diagnostics?: OnboardingDiagnostics
+  framework?: string
+  metaFramework?: string
+  routerMode?: 'app' | 'pages' | 'mixed' | 'unknown'
+  autoApplied?: string[]
+  pendingSteps?: string[]
+  assistantPrompt?: string
+  patches?: OnboardingPatchPlan[]
+  handoff?: OnboardingAssistantHandoff
 }
 
 /** Machine-readable detection output for skill-first onboarding */
@@ -167,9 +208,16 @@ export interface PlanResult {
   status: CommandStatus
   warnings: CommandMessage[]
   blockers: CommandMessage[]
-  strategy: 'supported' | 'manual' | 'unsupported'
+  strategy: 'supported' | 'guided' | 'manual' | 'unsupported'
   actions: Array<{
-    type: 'install_dependency' | 'modify_file' | 'install_extension' | 'manual_step'
+    type:
+      | 'install_dependency'
+      | 'modify_file'
+      | 'install_extension'
+      | 'manual_step'
+      | 'generate_patch_plan'
+      | 'generate_file'
+      | 'manual_confirmation'
     target: string
     description: string
   }>
@@ -179,6 +227,13 @@ export interface PlanResult {
     shared: boolean
     extension: boolean
   }
+  framework?: string
+  metaFramework?: string
+  routerMode?: 'app' | 'pages' | 'mixed' | 'unknown'
+  autoApplied?: string[]
+  pendingSteps?: string[]
+  assistantPrompt?: string
+  patches?: OnboardingPatchPlan[]
 }
 
 /** A single doctor diagnostic check/result */