@msn-control/liftoff 0.3.4 → 0.4.1

package/dist/commands.js

@@ -1,23 +1,41 @@
+import { createHash } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { cp, mkdir, mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
+import { cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, stat } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { formatCommandHelp, readBooleanFlag, readListFlag, readStringFlag } from './args.js';
-import { apiStacks, listRegions, patterns, providers, searchRegions } from './catalogs.js';
-import { artifactPath, assertNewOrEmptyDirectory, deleteProjectFile, findProjectRoot, loadManifest, manifestDisplayPath, resolveProjectPath, resolveTargetRoot, validateGeneratedProject, writeArtifacts, writeProjectFile } from './file-system.js';
-import { confirmPlan, promptForCreateOptions } from './interactive.js';
+import { getCommandHelp, getGeneralHelp, readBooleanFlag, readListFlag, readStringFlag } from './args.js';
+import { getCodingAgent, getFrameworkDefinition, getSpecWorkflow, listRegions, patterns, providers, searchRegions } from './catalogs.js';
+import { initializeFramework } from './framework-adapters.js';
+import { validateFrameworkInstallation } from './framework-validation.js';
+import { artifactPath, assertNewOrEmptyDirectory, deleteProjectFile, findProjectRoot, loadManifest, manifestDisplayPath, resolveProjectPath, validateGeneratedProject, writeArtifacts, writeProjectFile } from './file-system.js';
+import { InteractivePrompter } from './interactive.js';
+import { applyMergePreflight, assertSafeInitTarget, authorizeMergePreflight, buildMergePreflight, captureTreeState, discoverGitRoot, resolveInitTargetFromDiscovery, validateStagedTree, withStagingArea, writeStagedArtifacts } from './init-filesystem.js';
 import { renderMigrationChecklist, renderMigrationProposal, renderMigrationTasks, seedMigrationGroups } from './migrate-plan.js';
-import { buildProjectPlan, formatProjectPlan, loadConfigOptions, mergeOptions, PlanValidationError } from './planner.js';
+import { buildProjectPlan, loadConfigOptions, mergeOptions, PlanValidationError, projectPlanEntries } from './planner.js';
+import { buildDependencySetupPlan, runDependencySetup } from './project-dependencies.js';
+import { formatCommand, NodeCommandRunner } from './process-runner.js';
 import { scanDefaults, scanLegacyProject } from './scan.js';
 import { hasDrift, reconcileProject } from './reconcile.js';
 import { compareSemver } from './semver.js';
-import { buildArtifacts, buildManifest } from './templates.js';
+import { buildArtifacts, buildManifest, partitionGeneratedArtifacts } from './templates.js';
+import { PresentationSession } from './terminal.js';
 import { liftoffVersion } from './version.js';
+import { blockingReadinessFailures, detectHostEnvironment, installRequirement, probeWorkstation, selectLiftoffRuntimeRequirements, selectWorkstationRequirements } from './workstation.js';
 export async function runCommand(parsed, context) {
+    const helpRequested = parsed.command !== undefined && readBooleanFlag(parsed.flags, 'help') === true;
+    const jsonMode = !helpRequested && (parsed.command === 'doctor' || parsed.command === 'update') &&
+        readBooleanFlag(parsed.flags, 'json') === true;
+    const presentation = new PresentationSession({
+        stdout: context.stdout,
+        stderr: context.stderr,
+        ...context.terminal,
+        json: jsonMode
+    });
+    const executionContext = { ...context, presentation };
     try {
         if (parsed.command && readBooleanFlag(parsed.flags, 'help')) {
-            context.stdout.write(formatCommandHelp(parsed.command));
+            renderCommandHelp(parsed.command, presentation);
             return 0;
         }
         switch (parsed.command) {
@@ -25,154 +43,479 @@ export async function runCommand(parsed, context) {
             case 'help':
             case '--help':
                 if (parsed.positional[0]) {
-                    context.stdout.write(formatCommandHelp(parsed.positional[0]));
+                    renderCommandHelp(parsed.positional[0], presentation);
                 }
                 else {
-                    printHelp(context.stdout);
+                    renderGeneralHelp(presentation);
                 }
                 return 0;
             case 'version':
-                context.stdout.write(`Liftoff ${liftoffVersion}\n`);
+                presentation.rawStdout(`Liftoff ${liftoffVersion}\n`);
                 return 0;
-            case 'create':
-                return await createCommand(parsed, context);
+            case 'init':
+                return await initCommand(parsed, executionContext);
             case 'plan':
-                return await planCommand(parsed, context);
+                return await planCommand(parsed, executionContext);
             case 'patterns':
-                return patternsCommand(context);
+                return patternsCommand(executionContext);
             case 'providers':
-                return providersCommand(context);
+                return providersCommand(executionContext);
             case 'regions':
-                return regionsCommand(parsed, context);
+                return regionsCommand(parsed, executionContext);
             case 'validate':
-                return await validateCommand(parsed, context);
+                return await validateCommand(parsed, executionContext);
             case 'update':
-                return await updateCommand(parsed, context);
+                return await updateCommand(parsed, executionContext);
             case 'migrate':
-                return await migrateCommand(parsed, context);
+                return await migrateCommand(parsed, executionContext);
             case 'doctor':
-                return await doctorCommand(parsed, context);
+                return await doctorCommand(parsed, executionContext);
             case 'dev':
-                return helperCommand(parsed, context, 'docker compose');
+                return helperCommand(parsed, executionContext, 'docker compose');
             case 'infra':
-                return helperCommand(parsed, context, 'tofu');
+                return helperCommand(parsed, executionContext, 'tofu');
             default:
-                context.stderr.write(`Unknown command: ${parsed.command}\n\n`);
-                printHelp(context.stderr);
+                presentation.error(`Unknown command: ${parsed.command}`, 'Run `liftoff help` to list available commands.');
                 return 1;
         }
     }
     catch (error) {
         if (error instanceof PlanValidationError) {
-            context.stderr.write(`${error.issues.join('\n')}\n`);
+            presentation.error(error.issues.join('\n'), parsed.command ? `Run \`liftoff ${parsed.command} --help\` to review accepted values.` : undefined);
             return 1;
         }
-        context.stderr.write(`${error.message}\n`);
+        presentation.error(error instanceof Error ? error.message : String(error));
         return 1;
     }
 }
-async function createCommand(parsed, context) {
-    const initial = await optionsFromParsedArgs(parsed, context.cwd, true);
-    const needsPrompts = !initial.yes && hasMissingCreateInputs(initial);
-    const options = needsPrompts ? await promptForCreateOptions(initial) : initial;
-    const plan = buildProjectPlan(options, { requireProjectName: true });
-    const confirmed = await confirmPlan(plan, options.yes);
-    if (!confirmed) {
-        context.stdout.write('Generation cancelled.\n');
+async function initCommand(parsed, context) {
+    const { presentation } = context;
+    presentation.identity('Initialize the project and prepare its workstation');
+    const runner = context.runner ?? new NodeCommandRunner();
+    presentation.stage('Discover project context');
+    const git = await discoverGitRoot(context.cwd, runner);
+    let initial = await optionsFromParsedArgs(parsed, context.cwd, true);
+    if (!initial.projectName && git.exact && git.root) {
+        initial = { ...initial, projectName: path.basename(git.root) };
+    }
+    const interactive = initial.yes !== true;
+    const prompter = interactive
+        ? new InteractivePrompter({
+            input: context.stdin,
+            output: context.stdout,
+            presentation
+        })
+        : undefined;
+    try {
+        const needsPrompts = interactive && hasMissingInitInputs(initial);
+        if (needsPrompts) {
+            presentation.stage('Configure project');
+        }
+        const options = needsPrompts ? await prompter.promptForInitOptions(initial) : initial;
+        const plan = buildProjectPlan(options, { requireProjectName: true });
+        presentation.stage('Review resolved plan');
+        const confirmed = options.yes === true
+            ? (presentation.definitions('Resolved project plan', projectPlanEntries(plan)), true)
+            : await prompter.confirmPlan(plan);
+        if (!confirmed) {
+            presentation.cancellation('Initialization stopped; no destination files were changed.');
+            return 0;
+        }
+        presentation.stage('Resolve destination');
+        const target = resolveInitTargetFromDiscovery(git, plan.safeProjectName);
+        await assertSafeInitTarget(target, target.mode === 'named-child' ? git.canonicalCwd : undefined);
+        presentation.stage('Check workstation readiness');
+        const readiness = await ensureWorkstationReady(plan, options, context, runner, presentation, prompter);
+        if (!readiness.ready) {
+            return 1;
+        }
+        presentation.stage('Stage project files');
+        const staged = await withStagingArea(async (area) => {
+            const partition = partitionGeneratedArtifacts(buildArtifacts(plan));
+            await writeStagedArtifacts(area, partition.durable, 'liftoff');
+            presentation.stage('Initialize spec-driven framework', `${plan.specWorkflow.label} ${plan.framework.version}`);
+            await initializeFramework(area, plan, runner, {
+                ...presentation.childStreams(),
+                onCommand: (command) => presentation.command(command)
+            });
+            await writeStagedArtifacts(area, partition.seed, 'seed');
+            await writeStagedArtifacts(area, [partition.manifest], 'liftoff');
+            presentation.stage('Validate staged project');
+            await validateStagedTree(area);
+            const stagedIssues = await validateGeneratedProject(area.root);
+            if (stagedIssues.length > 0) {
+                throw new Error(`Staged project validation failed:\n${stagedIssues.join('\n')}`);
+            }
+            const preflight = await buildMergePreflight(area, target.root);
+            const authorized = await authorizeMergePreflight(preflight, options.force === true, interactive ? (paths) => prompter.confirmFileReplacements(paths) : undefined);
+            if (!authorized) {
+                return {
+                    status: interactive ? 'declined' : 'authorization-required'
+                };
+            }
+            presentation.stage('Merge staged project', target.root);
+            return { status: 'applied', merge: await applyMergePreflight(authorized) };
+        });
+        if (staged.status === 'declined') {
+            presentation.cancellation('No destination files were changed.');
+            return 0;
+        }
+        if (staged.status === 'authorization-required') {
+            presentation.error('Existing regular-file conflicts require --force in non-interactive mode.', 'Review the listed conflicts, then rerun with `--force` only if every replacement is intended.');
+            return 1;
+        }
+        const issues = await validateGeneratedProject(target.root);
+        if (issues.length > 0) {
+            presentation.error(`Initialized project validation failed:\n${issues.join('\n')}`);
+            return 1;
+        }
+        const dependencyPhase = await handleProjectDependencies(plan, target.root, options, readiness.probes, context, runner, presentation, prompter);
+        if (!dependencyPhase.success) {
+            return 1;
+        }
+        presentation.bullets('Configured integrations', [
+            `${plan.specWorkflow.label} ${plan.framework.version}`,
+            ...plan.agents.map((agent) => `${agent.label}${plan.defaultAgent?.id === agent.id ? ' (default)' : ''}`)
+        ]);
+        if (readiness.deferred.length > 0) {
+            presentation.bullets('Deferred advisory checks', readiness.deferred);
+        }
+        if (dependencyPhase.deferred.length > 0) {
+            presentation.bullets('Deferred project dependencies', dependencyPhase.deferred);
+        }
+        presentation.completion(`Initialized ${plan.projectName}`, target.root, [
+            { label: 'Target', value: target.root },
+            { label: 'Spec workflow', value: plan.specWorkflow.label },
+            { label: 'Coding agents', value: plan.agents.map((agent) => agent.label).join(', ') }
+        ], `liftoff validate ${JSON.stringify(target.root)}`);
         return 0;
     }
-    const targetRoot = resolveTargetRoot(context.cwd, plan.safeProjectName);
-    const artifacts = buildArtifacts(plan);
-    await writeArtifacts(targetRoot, artifacts);
-    const issues = await validateGeneratedProject(targetRoot);
-    if (issues.length > 0) {
-        context.stderr.write(`Generated project validation failed:\n${issues.join('\n')}\n`);
-        return 1;
+    finally {
+        prompter?.close();
     }
-    context.stdout.write(`Created ${plan.projectName} at ${targetRoot}\n`);
-    return 0;
 }
 async function planCommand(parsed, context) {
+    const { presentation } = context;
+    presentation.identity('Preview project decisions, artifacts, and workstation requirements');
     const options = await optionsFromParsedArgs(parsed, context.cwd, false);
     const plan = buildProjectPlan(options, { requireProjectName: false });
     const artifacts = buildArtifacts(plan);
-    context.stdout.write(`${formatProjectPlan(plan)}\n\nArtifacts (${artifacts.length}):\n`);
-    for (const artifact of artifacts) {
-        context.stdout.write(`- ${artifact.logicalName}: ${artifact.pathParts.join('/')}\n`);
+    presentation.definitions('Project decisions', projectPlanEntries(plan));
+    presentation.table(`Artifacts (${artifacts.length})`, ['Artifact', 'Path'], artifacts.map((artifact) => [artifact.logicalName, artifact.pathParts.join('/')]));
+    const workstationRows = selectWorkstationRequirements(plan).map((requirement) => [
+        requirement.definition.label,
+        requirement.exactVersion
+            ? `exactly ${requirement.exactVersion}`
+            : requirement.minimumVersion
+                ? `${requirement.minimumVersion}+`
+                : 'available',
+        requirement.severity
+    ]);
+    if (presentation.stdout.layout === 'plain') {
+        presentation.section('Workstation requirements', workstationRows.map(([label, version, severity]) => `${label}: ${version} [${severity}]`));
+    }
+    else {
+        presentation.table('Workstation requirements', ['Requirement', 'Version', 'Level'], workstationRows);
     }
     return 0;
 }
-function patternsCommand(context) {
-    context.stdout.write('Patterns:\n');
-    for (const pattern of patterns) {
-        context.stdout.write(`- ${pattern.id}: ${pattern.label} [${pattern.scaffoldStatus}]\n`);
+async function ensureWorkstationReady(plan, options, context, runner, presentation, prompter, resumeInvocation = 'liftoff init', commandCwd) {
+    const requirements = selectWorkstationRequirements(plan);
+    let probes = await probeWorkstation(requirements, runner, { cwd: commandCwd });
+    presentation.table('Workstation readiness', ['Requirement', 'Level', 'State', 'Detail'], probes.map((probe) => [
+        probe.requirement.definition.label,
+        probe.requirement.severity,
+        probe.state,
+        probe.detail
+    ]));
+    const actionable = probes.filter((probe) => probe.state !== 'ready');
+    const host = await detectHostEnvironment();
+    const installInstruction = (probe) => {
+        const recipe = probe.requirement.definition.install[host.platform];
+        const automatic = recipe && (host.platform !== 'linux' || recipe.manager === 'npm' || recipe.manager === 'uv');
+        if (automatic) {
+            return formatCommand(recipe.command);
+        }
+        if (host.platform === 'linux') {
+            return probe.requirement.definition.linuxRemedies[host.linuxFamily];
+        }
+        return `Install ${probe.requirement.definition.label} manually, then retry.`;
+    };
+    const authorizedInstallations = new Set();
+    if (options.installTools === true) {
+        for (const probe of actionable) {
+            authorizedInstallations.add(probe.requirement.id);
+        }
+    }
+    if (options.installTools === undefined &&
+        options.yes !== true &&
+        actionable.length > 0) {
+        for (const probe of actionable) {
+            const recipe = probe.requirement.definition.install[host.platform];
+            const automatic = recipe && (host.platform !== 'linux' || recipe.manager === 'npm' || recipe.manager === 'uv');
+            const constraint = probe.requirement.exactVersion
+                ? `required exactly ${probe.requirement.exactVersion}`
+                : probe.requirement.minimumVersion
+                    ? `required ${probe.requirement.minimumVersion} or newer`
+                    : 'required to be available';
+            if (await prompter.confirmToolInstallation({
+                label: probe.requirement.definition.label,
+                severity: probe.requirement.severity,
+                purpose: probe.requirement.reasons.join('; '),
+                requirement: constraint,
+                observed: `${probe.state} - ${probe.detail}`,
+                ...(automatic
+                    ? { command: formatCommand(recipe.command) }
+                    : { remedy: installInstruction(probe) })
+            })) {
+                authorizedInstallations.add(probe.requirement.id);
+            }
+        }
+    }
+    if (authorizedInstallations.size > 0) {
+        const updates = new Map();
+        for (const probe of actionable) {
+            if (!authorizedInstallations.has(probe.requirement.id)) {
+                continue;
+            }
+            presentation.stage(`Install ${probe.requirement.definition.label}`, `${probe.state} - ${probe.detail}`);
+            const recipe = probe.requirement.definition.install[host.platform];
+            if (recipe && (host.platform !== 'linux' || recipe.manager === 'npm' || recipe.manager === 'uv')) {
+                presentation.command(formatCommand(recipe.command));
+            }
+            const installation = await installRequirement(probe.requirement, probe, {
+                authorized: true,
+                host,
+                runner,
+                cwd: commandCwd,
+                streamOptions: presentation.childStreams()
+            });
+            updates.set(probe.requirement.id, installation.probe);
+            const kind = installation.state === 'installed'
+                ? 'success'
+                : probe.requirement.severity === 'blocking'
+                    ? 'error'
+                    : 'warning';
+            presentation.status(kind, probe.requirement.definition.label, installation.detail);
+            if (installation.remedy) {
+                presentation.command(installation.remedy);
+            }
+        }
+        probes = probes.map((probe) => updates.get(probe.requirement.id) ?? probe);
+    }
+    const blockers = blockingReadinessFailures(probes);
+    if (blockers.length > 0) {
+        for (const blocker of blockers) {
+            presentation.error(`${blocker.requirement.definition.label}: ${blocker.detail}`, installInstruction(blocker));
+        }
+        presentation.error('Workstation readiness is incomplete.', options.installTools
+            ? `Open a new terminal if PATH changed, then rerun \`${resumeInvocation}\` with the same project options.`
+            : `Resume with \`${resumeInvocation} --install-tools\` plus the same project options after reviewing the commands.`);
+        return { ready: false, deferred: [], probes };
+    }
+    const deferred = [
+        ...probes
+            .filter((probe) => probe.requirement.severity === 'advisory' && probe.state !== 'ready')
+            .map((probe) => `${probe.requirement.definition.label}: ${probe.detail} Remedy: ${installInstruction(probe)}`),
+        ...probes.flatMap((probe) => probe.notices
+            .filter((notice) => notice.state !== 'ready')
+            .map((notice) => `${notice.label}: ${notice.detail}${notice.remedy ? ` Remedy: ${notice.remedy}` : ''}`))
+    ];
+    return { ready: true, deferred, probes };
+}
+async function handleProjectDependencies(plan, projectRoot, options, probes, context, runner, presentation, prompter) {
+    const dependencyPlan = buildDependencySetupPlan(plan, projectRoot, probes);
+    let installDependencies = options.installDependencies === true;
+    if (options.installDependencies === undefined &&
+        options.yes !== true &&
+        dependencyPlan.commands.length > 0) {
+        installDependencies = await prompter.confirmDependencyInstallation(dependencyPlan.commands);
+    }
+    if (!installDependencies) {
+        return {
+            success: true,
+            deferred: dependencyPlan.commands.map((command) => `${command.label}: ${command.cwd} -> ${formatCommand(command.command)}`)
+        };
+    }
+    presentation.stage('Install project dependencies');
+    const result = await runDependencySetup(dependencyPlan, projectRoot, runner, {
+        ...presentation.childStreams(),
+        onCommand: (command) => {
+            presentation.status('pending', command.label, command.cwd);
+            presentation.command(formatCommand(command.command));
+        }
+    });
+    if (!result.success) {
+        presentation.error('Project dependencies failed', `${result.failed?.label ?? 'dependency command'}: ${result.detail ?? 'unknown failure'}`);
+        presentation.status('info', 'Scaffold preserved', projectRoot);
+        if (result.restoredMutations.length > 0) {
+            presentation.warning(`Restored protected files: ${result.restoredMutations.join(', ')}`);
+        }
+        if (result.resumeCommand) {
+            presentation.command(result.resumeCommand);
+        }
+        return { success: false, deferred: [] };
     }
+    presentation.status('success', 'Project dependencies', `${result.completed.length} command${result.completed.length === 1 ? '' : 's'} completed`);
+    return { success: true, deferred: [] };
+}
+function patternsCommand(context) {
+    context.presentation.commandIdentity('patterns', 'Available GenAI application patterns');
+    context.presentation.table('Patterns', ['Identifier', 'Pattern', 'Scaffold'], patterns.map((pattern) => [pattern.id, pattern.label, pattern.scaffoldStatus]));
     return 0;
 }
 function providersCommand(context) {
-    context.stdout.write('Providers:\n');
-    for (const provider of providers) {
-        context.stdout.write(`- ${provider.id}: ${provider.label} [${provider.status}]\n`);
-    }
+    context.presentation.commandIdentity('providers', 'Cloud provider availability');
+    context.presentation.table('Providers', ['Identifier', 'Provider', 'Availability'], providers.map((provider) => [provider.id, provider.label, provider.status]));
     return 0;
 }
 function regionsCommand(parsed, context) {
     const cloud = readStringFlag(parsed.flags, 'cloud') ?? 'azure';
+    context.presentation.commandIdentity('regions', 'Cloud deployment regions');
     if (cloud !== 'azure') {
-        context.stderr.write(`${cloud} regions are not available until the provider adapter is implemented.\n`);
+        context.presentation.error(`${cloud} regions are not available until the provider adapter is implemented.`, 'Run `liftoff providers` to review currently available providers.');
         return 1;
     }
     const query = parsed.positional[0] ?? readStringFlag(parsed.flags, 'region');
     const regions = parsed.subcommand === 'search' && query ? searchRegions('azure', query) : listRegions('azure');
-    for (const region of regions) {
-        context.stdout.write(`${region.slug}\t${region.displayName}\t${region.geography}\n`);
+    if (regions.length === 0) {
+        context.presentation.warning(`No Azure regions matched ${JSON.stringify(query ?? '')}.`);
+        return 0;
     }
+    context.presentation.table(query ? `Azure region matches for ${JSON.stringify(query)}` : 'Azure regions', ['Identifier', 'Region', 'Geography'], regions.map((region) => [region.slug, region.displayName, region.geography]));
     return 0;
 }
 async function validateCommand(parsed, context) {
+    context.presentation.commandIdentity('validate', 'Validate a generated Liftoff project');
     const explicit = parsed.positional[0] ?? readStringFlag(parsed.flags, 'project');
     const projectRoot = explicit
         ? path.resolve(context.cwd, explicit)
         : (await findProjectRoot(context.cwd)) ?? context.cwd;
     const issues = await validateGeneratedProject(projectRoot);
     if (issues.length > 0) {
-        context.stderr.write(`${issues.join('\n')}\n`);
+        context.presentation.error(issues.join('\n'), 'Restore invalid generated files or the manifest from version control, then rerun validation.');
         return 1;
     }
-    context.stdout.write('Generated project manifest is valid.\n');
+    context.presentation.status('success', 'Generated project manifest is valid', projectRoot);
     return 0;
 }
 const STAGING_EXCLUDES = new Set(['.git', 'node_modules', 'vendor', '.venv', 'venv', '__pycache__', 'dist', 'build', '.next']);
-async function migrateCommand(parsed, context) {
-    const sourceArg = parsed.positional[0];
-    if (!sourceArg) {
-        context.stderr.write('Usage: liftoff migrate <path-to-existing-project>\n');
-        return 1;
-    }
-    const sourceRoot = path.resolve(context.cwd, sourceArg);
-    let sourceDetails;
+async function snapshotMigrationSource(sourceRoot) {
+    const snapshot = new Map();
+    const visit = async (pathParts) => {
+        const current = path.join(sourceRoot, ...pathParts);
+        const entries = await readdir(current, { withFileTypes: true });
+        entries.sort((left, right) => left.name.localeCompare(right.name, 'en'));
+        for (const entry of entries) {
+            const childParts = [...pathParts, entry.name];
+            const relativePath = childParts.join('/');
+            const childPath = path.join(sourceRoot, ...childParts);
+            const details = await lstat(childPath);
+            if (details.isSymbolicLink()) {
+                snapshot.set(relativePath, `symlink:${await readlink(childPath)}`);
+            }
+            else if (details.isDirectory()) {
+                snapshot.set(relativePath, 'directory');
+                await visit(childParts);
+            }
+            else if (details.isFile()) {
+                const hash = createHash('sha256').update(await readFile(childPath)).digest('hex');
+                snapshot.set(relativePath, `file:${hash}`);
+            }
+            else {
+                snapshot.set(relativePath, 'other');
+            }
+        }
+    };
+    await visit([]);
+    return snapshot;
+}
+function sourceSnapshotChanges(before, after) {
+    return [...new Set([...before.keys(), ...after.keys()])]
+        .filter((key) => before.get(key) !== after.get(key))
+        .sort();
+}
+async function withUnchangedMigrationSource(sourceRoot, operation) {
+    const before = await snapshotMigrationSource(sourceRoot);
+    const assertUnchanged = async () => {
+        const changes = sourceSnapshotChanges(before, await snapshotMigrationSource(sourceRoot));
+        if (changes.length > 0) {
+            throw new Error(`Migration source changed unexpectedly; refusing to continue:\n${changes.map((entry) => `- ${entry}`).join('\n')}`);
+        }
+    };
+    let result;
     try {
-        sourceDetails = await stat(sourceRoot);
+        result = await operation();
     }
-    catch {
-        context.stderr.write(`Source project not found: ${sourceRoot}\n`);
-        return 1;
+    catch (error) {
+        await assertUnchanged();
+        throw error;
     }
-    if (!sourceDetails.isDirectory()) {
-        context.stderr.write(`Source path is not a directory: ${sourceRoot}\n`);
-        return 1;
+    await assertUnchanged();
+    return result;
+}
+async function stageMigrationSource(area, sourceRoot) {
+    const destination = path.join(area.root, 'migration', 'legacy');
+    await cp(sourceRoot, destination, {
+        recursive: true,
+        filter: (source) => {
+            const relative = path.relative(sourceRoot, source);
+            if (!relative) {
+                return true;
+            }
+            return !relative.split(path.sep).some((part) => STAGING_EXCLUDES.has(part));
+        }
+    });
+    for (const entry of (await captureTreeState(area.root)).values()) {
+        if (entry.pathParts[0] === 'migration' &&
+            entry.pathParts[1] === 'legacy' &&
+            entry.type !== 'directory') {
+            area.origins.set(entry.pathParts.join('/'), 'seed');
+        }
     }
-    if (existsSync(path.join(sourceRoot, 'liftoff.manifest.json'))) {
-        context.stderr.write(`${sourceRoot} is already a Liftoff project. Use liftoff update instead.\n`);
-        return 1;
+}
+function migrationPlanArtifacts(plan, inventory) {
+    const groups = seedMigrationGroups(inventory, plan);
+    if (plan.specWorkflow.id === 'openspec') {
+        return {
+            artifacts: [
+                {
+                    logicalName: 'migration-proposal',
+                    category: 'seed',
+                    pathParts: ['openspec', 'changes', 'migrate-to-liftoff', 'proposal.md'],
+                    content: renderMigrationProposal(plan, inventory)
+                },
+                {
+                    logicalName: 'migration-tasks',
+                    category: 'seed',
+                    pathParts: ['openspec', 'changes', 'migrate-to-liftoff', 'tasks.md'],
+                    content: renderMigrationTasks(groups)
+                }
+            ],
+            location: 'openspec/changes/migrate-to-liftoff/ (run it with your agent workflow, e.g. /opsx:apply migrate-to-liftoff)'
+        };
     }
+    return {
+        artifacts: [{
+                logicalName: 'migration-checklist',
+                category: 'seed',
+                pathParts: ['MIGRATION.md'],
+                content: renderMigrationChecklist(plan, inventory, groups)
+            }],
+        location: 'MIGRATION.md'
+    };
+}
+async function executeMigration(parsed, context, sourceRoot) {
+    const { presentation } = context;
+    presentation.stage('Scan legacy project', sourceRoot);
     const inventory = await scanLegacyProject(sourceRoot);
     const { options: defaults, provenance } = scanDefaults(inventory);
-    context.stdout.write('Scan defaults (override in prompts or with flags):\n');
-    for (const item of provenance) {
-        context.stdout.write(`  - ${item.field}: ${item.value}  (detected: ${item.evidence})\n`);
+    if (presentation.stdout.layout === 'plain') {
+        presentation.section('Scan defaults (override in prompts or with flags)', provenance.map((item) => `${item.field}: ${String(item.value)}  (detected: ${item.evidence})`));
+    }
+    else {
+        presentation.table('Scan defaults (override in prompts or with flags)', ['Decision', 'Detected value', 'Evidence'], provenance.map((item) => [item.field, String(item.value), item.evidence]));
     }
-    context.stdout.write('\n');
     const flagOptions = await optionsFromParsedArgs(parsed, context.cwd, false);
     const initial = mergeOptions(defaults, flagOptions);
     if (flagOptions.pattern && flagOptions.projectType === undefined) {
@@ -191,57 +534,146 @@ async function migrateCommand(parsed, context) {
     if (flagOptions.projectType === 'genai' && flagOptions.apiStack === undefined) {
         initial.apiStack = undefined;
     }
-    const needsPrompts = !initial.yes && hasMissingCreateInputs(initial);
-    const options = needsPrompts ? await promptForCreateOptions(initial) : initial;
-    const plan = buildProjectPlan(options, { requireProjectName: true });
-    const confirmed = await confirmPlan(plan, options.yes);
-    if (!confirmed) {
-        context.stdout.write('Migration cancelled.\n');
+    const interactive = initial.yes !== true;
+    const prompter = interactive
+        ? new InteractivePrompter({
+            input: context.stdin,
+            output: context.stdout,
+            presentation
+        })
+        : undefined;
+    try {
+        const needsPrompts = interactive && hasMissingInitInputs(initial);
+        if (needsPrompts) {
+            presentation.stage('Configure migrated project');
+        }
+        const options = needsPrompts ? await prompter.promptForInitOptions(initial) : initial;
+        const plan = buildProjectPlan(options, { requireProjectName: true });
+        presentation.stage('Review migration plan');
+        const confirmed = options.yes === true
+            ? (presentation.definitions('Resolved migration plan', projectPlanEntries(plan)), true)
+            : await prompter.confirmPlan(plan, undefined, 'Migrate project?');
+        if (!confirmed) {
+            presentation.cancellation('Migration stopped; the source and destination were not modified.');
+            return 0;
+        }
+        presentation.stage('Resolve fresh migration target');
+        const parentDir = path.dirname(sourceRoot);
+        let targetRoot = path.resolve(parentDir, plan.safeProjectName);
+        if (targetRoot === sourceRoot) {
+            targetRoot = path.resolve(parentDir, `${plan.safeProjectName}-liftoff`);
+        }
+        const target = { root: targetRoot, mode: 'named-child' };
+        await assertSafeInitTarget(target, parentDir);
+        await assertNewOrEmptyDirectory(targetRoot);
+        const runner = context.runner ?? new NodeCommandRunner();
+        presentation.stage('Check workstation readiness');
+        const readinessRoot = await mkdtemp(path.join(os.tmpdir(), 'liftoff-migrate-readiness-'));
+        const readiness = await (async () => {
+            try {
+                return await ensureWorkstationReady(plan, options, context, runner, presentation, prompter, `liftoff migrate ${JSON.stringify(sourceRoot)}`, readinessRoot);
+            }
+            finally {
+                await rm(readinessRoot, { recursive: true, force: true });
+            }
+        })();
+        if (!readiness.ready) {
+            return 1;
+        }
+        const migrationPlan = migrationPlanArtifacts(plan, inventory);
+        presentation.stage('Stage fresh migration project');
+        await withStagingArea(async (area) => {
+            const partition = partitionGeneratedArtifacts(buildArtifacts(plan));
+            await writeStagedArtifacts(area, partition.durable, 'liftoff');
+            presentation.stage('Initialize spec-driven framework', `${plan.specWorkflow.label} ${plan.framework.version}`);
+            await initializeFramework(area, plan, runner, {
+                ...presentation.childStreams(),
+                onCommand: (command) => presentation.command(command)
+            });
+            await writeStagedArtifacts(area, partition.seed, 'seed');
+            presentation.stage('Copy filtered legacy source', sourceRoot);
+            await stageMigrationSource(area, sourceRoot);
+            await writeStagedArtifacts(area, migrationPlan.artifacts, 'seed');
+            await writeStagedArtifacts(area, [partition.manifest], 'liftoff');
+            presentation.stage('Validate staged migration');
+            await validateStagedTree(area);
+            const stagedIssues = await validateGeneratedProject(area.root);
+            if (stagedIssues.length > 0) {
+                throw new Error(`Staged migration project validation failed:\n${stagedIssues.join('\n')}`);
+            }
+            const preflight = await buildMergePreflight(area, targetRoot);
+            const existing = preflight.entries.filter((entry) => entry.destination.type !== 'missing');
+            if (existing.length > 0) {
+                throw new Error(`Migration target must remain new or empty; --force cannot replace existing content:\n` +
+                    existing.map((entry) => `- ${entry.relativePath}`).join('\n'));
+            }
+            const authorized = await authorizeMergePreflight(preflight, false);
+            if (!authorized) {
+                throw new Error('Migration target authorization failed.');
+            }
+            presentation.stage('Merge fresh migration target', targetRoot);
+            await applyMergePreflight(authorized, { requireEmptyTarget: true });
+        });
+        const issues = await validateGeneratedProject(targetRoot);
+        if (issues.length > 0) {
+            presentation.error(`Migrated project validation failed:\n${issues.join('\n')}`);
+            return 1;
+        }
+        const dependencyPhase = await handleProjectDependencies(plan, targetRoot, options, readiness.probes, context, runner, presentation, prompter);
+        if (!dependencyPhase.success) {
+            return 1;
+        }
+        presentation.bullets('Configured integrations', [
+            `${plan.specWorkflow.label} ${plan.framework.version}`,
+            ...plan.agents.map((agent) => `${agent.label}${plan.defaultAgent?.id === agent.id ? ' (default)' : ''}`)
+        ]);
+        if (readiness.deferred.length > 0) {
+            presentation.bullets('Deferred advisory checks', readiness.deferred);
+        }
+        if (dependencyPhase.deferred.length > 0) {
+            presentation.bullets('Deferred project dependencies', dependencyPhase.deferred);
+        }
+        presentation.bullets('Next steps', [
+            `Optional - preserve history: copy the .git directory from ${sourceRoot} into ${targetRoot}, then commit the migration on top (git rename detection preserves file history).`,
+            `Execute the migration plan: ${migrationPlan.location}`,
+            'Verify compliance: liftoff validate && liftoff doctor'
+        ]);
+        presentation.completion(`Migrated ${plan.projectName}`, targetRoot, [
+            { label: 'Target', value: targetRoot },
+            { label: 'Source', value: `${sourceRoot} (not modified)` },
+            { label: 'Rollback', value: `Delete ${targetRoot}` }
+        ], 'liftoff validate && liftoff doctor');
         return 0;
     }
-    const parentDir = path.dirname(sourceRoot);
-    let targetRoot = path.resolve(parentDir, plan.safeProjectName);
-    if (targetRoot === sourceRoot) {
-        targetRoot = path.resolve(parentDir, `${plan.safeProjectName}-liftoff`);
+    finally {
+        prompter?.close();
     }
-    const artifacts = buildArtifacts(plan);
-    await writeArtifacts(targetRoot, artifacts);
-    const issues = await validateGeneratedProject(targetRoot);
-    if (issues.length > 0) {
-        context.stderr.write(`Generated scaffold validation failed:\n${issues.join('\n')}\n`);
+}
+async function migrateCommand(parsed, context) {
+    const sourceArg = parsed.positional[0];
+    if (!sourceArg) {
+        context.presentation.error('Usage: liftoff migrate <path-to-existing-project>', 'Run `liftoff migrate --help` for accepted migration options.');
         return 1;
     }
-    const stagingRoot = path.join(targetRoot, 'migration', 'legacy');
-    await cp(sourceRoot, stagingRoot, {
-        recursive: true,
-        filter: (source) => {
-            const relative = path.relative(sourceRoot, source);
-            if (!relative) {
-                return true;
-            }
-            return !relative.split(path.sep).some((part) => STAGING_EXCLUDES.has(part));
-        }
-    });
-    const groups = seedMigrationGroups(inventory, plan);
-    let planLocation;
-    if (plan.specWorkflow.id === 'openspec') {
-        const changeDir = path.join(targetRoot, 'openspec', 'changes', 'migrate-to-liftoff');
-        await mkdir(changeDir, { recursive: true });
-        await writeFile(path.join(changeDir, 'proposal.md'), renderMigrationProposal(plan, inventory), 'utf8');
-        await writeFile(path.join(changeDir, 'tasks.md'), renderMigrationTasks(groups), 'utf8');
-        planLocation = 'openspec/changes/migrate-to-liftoff/ (run it with your agent workflow, e.g. /opsx:apply migrate-to-liftoff)';
+    const sourceRoot = path.resolve(context.cwd, sourceArg);
+    let sourceDetails;
+    try {
+        sourceDetails = await stat(sourceRoot);
     }
-    else {
-        await writeFile(path.join(targetRoot, 'MIGRATION.md'), renderMigrationChecklist(plan, inventory, groups), 'utf8');
-        planLocation = 'MIGRATION.md';
-    }
-    context.stdout.write(`Created ${plan.projectName} at ${targetRoot}\n\n`);
-    context.stdout.write('Next steps:\n');
-    context.stdout.write(`  1. Optional - preserve history: copy the .git directory from ${sourceRoot} into ${targetRoot}, then commit the migration on top (git rename detection preserves file history).\n`);
-    context.stdout.write(`  2. Execute the migration plan: ${planLocation}\n`);
-    context.stdout.write('  3. Verify compliance: liftoff validate && liftoff doctor\n');
-    context.stdout.write(`The source project was not modified. Rolling back is deleting ${targetRoot}.\n`);
-    return 0;
+    catch {
+        context.presentation.error(`Source project not found: ${sourceRoot}`);
+        return 1;
+    }
+    if (!sourceDetails.isDirectory()) {
+        context.presentation.error(`Source path is not a directory: ${sourceRoot}`);
+        return 1;
+    }
+    if (existsSync(path.join(sourceRoot, 'liftoff.manifest.json'))) {
+        context.presentation.error(`${sourceRoot} is already a Liftoff project.`, 'Use `liftoff update` instead.');
+        return 1;
+    }
+    context.presentation.identity('Migrate an existing application into a fresh Liftoff project');
+    return withUnchangedMigrationSource(sourceRoot, () => executeMigration(parsed, context, sourceRoot));
 }
 function summarizeEntries(entries) {
     const summary = { new: 0, missing: 0, upgrade: 0, conflict: 0, moved: 0, orphan: 0, refresh: 0, unchanged: 0 };
@@ -311,36 +743,49 @@ async function preflightUpdate(projectRoot, entries, force) {
     await resolveProjectPath(projectRoot, ['liftoff.manifest.json']);
 }
 async function updateCommand(parsed, context) {
+    const { presentation } = context;
     const apply = readBooleanFlag(parsed.flags, 'apply') ?? false;
     const force = readBooleanFlag(parsed.flags, 'force') ?? false;
     const jsonMode = readBooleanFlag(parsed.flags, 'json') ?? false;
+    presentation.commandIdentity('update', 'Reconcile the project with current Liftoff templates');
     if (force && !apply) {
-        context.stderr.write('--force requires --apply.\n');
+        presentation.error('--force requires --apply.', 'Run `liftoff update --apply --force` only after reviewing the reported conflicts.');
         return 1;
     }
     const explicit = parsed.positional[0] ?? readStringFlag(parsed.flags, 'project');
     const projectRoot = explicit ? path.resolve(context.cwd, explicit) : await findProjectRoot(context.cwd);
     if (!projectRoot) {
-        context.stderr.write(`No liftoff.manifest.json found in ${context.cwd} or any parent directory.\n`);
+        presentation.error(`No liftoff.manifest.json found in ${context.cwd} or any parent directory.`, 'Run this command inside a Liftoff project or provide its path explicitly.');
         return 1;
     }
     const manifest = await loadManifest(projectRoot);
     if (compareSemver(manifest.liftoffVersion, liftoffVersion) > 0) {
-        context.stderr.write(`This project was written by Liftoff ${manifest.liftoffVersion}, which is newer than this CLI (${liftoffVersion}). Upgrade the CLI first.\n`);
+        presentation.error(`This project was written by Liftoff ${manifest.liftoffVersion}, which is newer than this CLI (${liftoffVersion}).`, 'Upgrade the CLI first.');
         return 1;
     }
     const config = await loadConfigOptions('liftoff.config.json', projectRoot);
     const plan = buildProjectPlan(config, { requireProjectName: true });
     if (plan.projectType.id !== manifest.project.projectType) {
-        context.stderr.write(`Project type changes (${manifest.project.projectType} -> ${plan.projectType.id}) are a migration, not an update. Run liftoff migrate instead.\n`);
+        presentation.error(`Project type changes (${manifest.project.projectType} -> ${plan.projectType.id}) are a migration, not an update.`, 'Run `liftoff migrate` instead.');
         return 1;
     }
     if (plan.apiStack.id !== manifest.project.apiStack) {
-        context.stderr.write(`API stack changes (${manifest.project.apiStack} -> ${plan.apiStack.id}) are a migration, not an update. Run liftoff migrate instead.\n`);
+        presentation.error(`API stack changes (${manifest.project.apiStack} -> ${plan.apiStack.id}) are a migration, not an update.`, 'Run `liftoff migrate` instead.');
         return 1;
     }
     if (plan.pattern?.id !== manifest.project.pattern) {
-        context.stderr.write(`Pattern changes (${manifest.project.pattern ?? 'none'} -> ${plan.pattern?.id ?? 'none'}) are a migration, not an update. Run liftoff migrate instead.\n`);
+        presentation.error(`Pattern changes (${manifest.project.pattern ?? 'none'} -> ${plan.pattern?.id ?? 'none'}) are a migration, not an update.`, 'Run `liftoff migrate` instead.');
+        return 1;
+    }
+    if (plan.specWorkflow.id !== manifest.project.specWorkflow) {
+        presentation.error(`Spec workflow changes (${manifest.project.specWorkflow} -> ${plan.specWorkflow.id}) require official framework initialization and are not supported by liftoff update.`, 'Restore the workflow recorded in liftoff.manifest.json or migrate into a fresh project.');
+        return 1;
+    }
+    const configuredAgents = plan.agents.map((agent) => agent.id);
+    if (manifest.framework.state === 'initialized' && (configuredAgents.length !== manifest.project.agents.length ||
+        configuredAgents.some((agent, index) => agent !== manifest.project.agents[index]) ||
+        plan.defaultAgent?.id !== manifest.project.defaultAgent)) {
+        presentation.error('AI agent or default-agent changes require official framework initialization and are not supported by liftoff update.', 'Restore liftoff.config.json to the integrations recorded in liftoff.manifest.json.');
         return 1;
     }
     const render = buildArtifacts(plan);
@@ -350,7 +795,7 @@ async function updateCommand(parsed, context) {
     const visible = entries.filter((entry) => entry.status !== 'unchanged' || entry.refreshHash);
     if (!apply) {
         if (jsonMode) {
-            context.stdout.write(`${JSON.stringify({
+            presentation.rawStdout(`${JSON.stringify({
                 schemaVersion: 1,
                 mode: 'check',
                 cliVersion: liftoffVersion,
@@ -366,22 +811,29 @@ async function updateCommand(parsed, context) {
             }, null, 2)}\n`);
             return drift ? 2 : 0;
         }
-        context.stdout.write(`Liftoff ${liftoffVersion} - project generated by ${manifest.liftoffVersion}\n\n`);
+        presentation.definitions('Project versions', [
+            { label: 'Liftoff CLI', value: liftoffVersion },
+            { label: 'Project generated by', value: manifest.liftoffVersion }
+        ]);
         if (!drift) {
-            context.stdout.write(`No drift: ${summary.unchanged} artifacts match the current templates and configuration.\n`);
+            presentation.status('success', 'No drift', `${summary.unchanged} artifacts match the current templates and configuration`);
             return 0;
         }
-        for (const entry of visible) {
-            context.stdout.write(`  ${entryMarker(entry)} ${entryDisplay(entry)}  ${entry.reason}\n`);
+        if (presentation.stdout.layout === 'plain') {
+            presentation.section('Template drift', visible.map((entry) => `${entryMarker(entry)} ${entryDisplay(entry)}  ${entry.reason}`));
+        }
+        else {
+            presentation.table('Template drift', ['Change', 'Artifact', 'Reason'], visible.map((entry) => [entryMarker(entry), entryDisplay(entry), entry.reason]));
         }
         const toWrite = summary.new + summary.missing + summary.upgrade + summary.moved + summary.refresh;
-        context.stdout.write(`\n  ${toWrite} to write, ${summary.conflict} conflict(s), ${summary.orphan} orphan(s), ${summary.unchanged} unchanged\n`);
-        context.stdout.write('  Run `liftoff update --apply` to apply the safe changes.\n');
+        presentation.status('warning', 'Drift detected', `${toWrite} to write, ${summary.conflict} conflict(s), ${summary.orphan} orphan(s), ${summary.unchanged} unchanged`);
+        presentation.command('liftoff update --apply');
         return 2;
     }
     if (isDirtyGitWorktree(projectRoot)) {
-        context.stdout.write('Hint: the project worktree has uncommitted changes - consider committing before applying.\n');
+        presentation.warning('The project worktree has uncommitted changes; consider committing before applying.');
     }
+    presentation.stage('Apply safe template changes', projectRoot);
     await preflightUpdate(projectRoot, entries, force);
     const written = [];
     const skipped = [];
@@ -423,7 +875,16 @@ async function updateCommand(parsed, context) {
     }
     const oldByName = new Map(manifest.artifacts.map((artifact) => [artifact.logicalName, artifact]));
     const skippedByName = new Map(skipped.map((entry) => [entry.logicalName, entry]));
-    const nextManifest = buildManifest(plan, render.filter((artifact) => artifact.logicalName !== 'manifest'));
+    const nextManifest = buildManifest(plan, render.filter((artifact) => artifact.logicalName !== 'manifest'), { frameworkState: manifest.framework.state });
+    nextManifest.framework = manifest.framework;
+    nextManifest.project.specWorkflow = manifest.project.specWorkflow;
+    nextManifest.project.agents = manifest.project.agents;
+    if (manifest.project.defaultAgent) {
+        nextManifest.project.defaultAgent = manifest.project.defaultAgent;
+    }
+    else {
+        delete nextManifest.project.defaultAgent;
+    }
     nextManifest.artifacts = nextManifest.artifacts.flatMap((artifact) => {
         // config is user-owned after create: carry the recorded entry forward untouched
         if (artifact.logicalName === 'liftoff-config') {
@@ -445,7 +906,7 @@ async function updateCommand(parsed, context) {
     }
     await writeProjectFile(projectRoot, ['liftoff.manifest.json'], `${JSON.stringify(nextManifest, null, 2)}\n`);
     if (jsonMode) {
-        context.stdout.write(`${JSON.stringify({
+        presentation.rawStdout(`${JSON.stringify({
             schemaVersion: 1,
             mode: 'apply',
             cliVersion: liftoffVersion,
@@ -456,27 +917,19 @@ async function updateCommand(parsed, context) {
         }, null, 2)}\n`);
         return 0;
     }
-    for (const entry of written) {
-        context.stdout.write(`  wrote ${entryDisplay(entry)}\n`);
+    if (written.length > 0) {
+        presentation.bullets('Applied changes', written.map((entry) => `wrote ${entryDisplay(entry)}`));
     }
-    for (const entry of skipped) {
-        context.stdout.write(`  skipped ${entryDisplay(entry)}  ${entry.reason}${force ? '' : ' (use --apply --force to overwrite)'}\n`);
+    if (skipped.length > 0) {
+        presentation.bullets('Skipped conflicts', skipped.map((entry) => `skipped ${entryDisplay(entry)}  ${entry.reason}${force ? '' : ' (use --apply --force to overwrite)'}`));
     }
-    for (const entry of entries) {
-        if (entry.status === 'orphan') {
-            context.stdout.write(`  orphan ${entryDisplay(entry)}  ${entry.reason}\n`);
-        }
+    const orphans = entries.filter((entry) => entry.status === 'orphan');
+    if (orphans.length > 0) {
+        presentation.bullets('Orphaned artifacts', orphans.map((entry) => `orphan ${entryDisplay(entry)}  ${entry.reason}`));
     }
-    context.stdout.write(`Updated: ${written.length} written, ${skipped.length} skipped, ${summary.orphan} orphan(s). Manifest recorded at ${liftoffVersion}.\n`);
+    presentation.completion('Updated project', `${written.length} written, ${skipped.length} skipped, ${summary.orphan} orphan(s)`, [{ label: 'Manifest version', value: liftoffVersion }], 'liftoff validate && liftoff doctor');
     return 0;
 }
-function binaryCheck(command, args, remedy, cwd) {
-    const result = spawnSync(command, args, { cwd, encoding: 'utf8' });
-    if (result.status === 0) {
-        return { label: command, severity: 'ok', detail: (result.stdout || result.stderr).split('\n')[0].trim() };
-    }
-    return { label: command, severity: 'fail', detail: 'not found', remedy };
-}
 function versionedBinaryCheck(label, command, args, minimum, remedy) {
     const result = spawnSync(command, args, { encoding: 'utf8' });
     if (result.status !== 0) {
@@ -506,25 +959,121 @@ function pythonRuntime() {
         ];
     return candidates.find((candidate) => versionedBinaryCheck('python', candidate.command, candidate.versionArgs, [3, 12], 'install Python 3.12 or newer').severity === 'ok') ?? candidates.find((candidate) => binaryPresent(candidate.command));
 }
-function environmentLayer(apiStack) {
-    const python = pythonRuntime();
-    const runtimeChecks = apiStack === 'go-huma'
-        ? [versionedBinaryCheck('go', 'go', ['version'], [1, 23], 'install Go 1.23 or newer')]
-        : apiStack === 'node-fastify'
-            ? []
-            : [python
-                    ? versionedBinaryCheck('python', python.command, python.versionArgs, [3, 12], 'install Python 3.12 or newer')
-                    : { label: 'python', severity: 'fail', detail: 'not found', remedy: 'install Python 3.12 or newer' }];
+function doctorCheckFromProbe(probe) {
+    const severity = probe.state === 'ready'
+        ? 'ok'
+        : probe.requirement.severity === 'blocking'
+            ? 'fail'
+            : 'warn';
     return {
-        title: 'Environment',
-        checks: [
-            versionedBinaryCheck('node', 'node', ['--version'], [20, 0], 'install Node.js 20 or newer'),
-            ...runtimeChecks,
-            binaryCheck('docker', ['--version'], 'install Docker'),
-            binaryCheck('tofu', ['--version'], 'install OpenTofu')
-        ]
+        id: probe.requirement.id,
+        label: probe.requirement.id,
+        severity,
+        state: probe.state,
+        requirementSeverity: probe.requirement.severity,
+        detail: probe.detail,
+        ...(probe.remedy ? { remedy: probe.remedy } : {})
     };
 }
+function noticeId(requirementId, label) {
+    const suffix = label.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+    return `${requirementId}:${suffix}`;
+}
+function workstationLayer(probes) {
+    const checks = probes.flatMap((probe) => [
+        doctorCheckFromProbe(probe),
+        ...probe.notices.map((notice) => ({
+            id: noticeId(probe.requirement.id, notice.label),
+            label: notice.label,
+            severity: notice.state === 'ready' ? 'ok' : 'warn',
+            state: notice.state,
+            requirementSeverity: 'advisory',
+            detail: notice.detail,
+            ...(notice.remedy ? { remedy: notice.remedy } : {})
+        }))
+    ]);
+    return { title: 'Environment', checks };
+}
+function workstationSelectionFromManifest(manifest) {
+    const framework = getFrameworkDefinition(manifest.project.specWorkflow);
+    return {
+        apiStack: { id: manifest.project.apiStack },
+        specWorkflow: { id: manifest.project.specWorkflow },
+        framework: { version: framework.version },
+        provider: { id: manifest.project.cloud },
+        agents: manifest.framework.state === 'initialized'
+            ? manifest.project.agents.map((id) => {
+                const agent = getCodingAgent(id);
+                if (!agent) {
+                    throw new Error(`Manifest references unknown coding agent ${id}.`);
+                }
+                return { id: agent.id, label: agent.label };
+            })
+            : []
+    };
+}
+async function frameworkDoctorChecks(projectRoot, manifest) {
+    if (manifest.framework.state === 'legacy') {
+        return [{
+                id: 'framework-legacy-state',
+                label: 'framework state',
+                severity: 'warn',
+                state: 'not-observable',
+                detail: `Legacy v${manifest.artifactVersion} manifest does not prove official ${manifest.framework.adapter} initialization or configured coding agents.`,
+                remedy: 'Reinitialize the framework explicitly before recording a v3 initialized framework contract.'
+            }];
+    }
+    const expected = getFrameworkDefinition(manifest.framework.adapter);
+    const frameworkLabel = getSpecWorkflow(manifest.framework.adapter)?.label ?? manifest.framework.adapter;
+    const contract = manifest.framework.contractVersion === expected.version
+        ? {
+            id: 'framework-contract',
+            label: 'framework contract',
+            severity: 'ok',
+            state: 'ready',
+            detail: `${frameworkLabel} ${expected.version}`
+        }
+        : {
+            id: 'framework-contract',
+            label: 'framework contract',
+            severity: 'fail',
+            state: 'outdated',
+            detail: `Manifest records ${manifest.framework.contractVersion}; this Liftoff version requires ${expected.version}.`,
+            remedy: `Install ${frameworkLabel} ${expected.version} and reinitialize its integrations.`
+        };
+    const markerIssues = await validateFrameworkInstallation(projectRoot, {
+        workflow: manifest.framework.adapter,
+        agents: manifest.project.agents,
+        ...(manifest.project.defaultAgent ? { defaultAgent: manifest.project.defaultAgent } : {})
+    });
+    const markers = markerIssues.length === 0
+        ? {
+            id: 'framework-markers',
+            label: 'framework markers',
+            severity: 'ok',
+            state: 'ready',
+            detail: `${manifest.project.agents.length} selected integration${manifest.project.agents.length === 1 ? '' : 's'} verified`
+        }
+        : {
+            id: 'framework-markers',
+            label: 'framework markers',
+            severity: 'fail',
+            state: 'unhealthy',
+            detail: `${markerIssues.length} issue(s): ${markerIssues[0]}`,
+            remedy: `Run the official ${frameworkLabel} initializer for the selected integrations.`
+        };
+    return [
+        contract,
+        {
+            id: 'selected-agents',
+            label: 'selected agents',
+            severity: 'ok',
+            state: 'ready',
+            detail: manifest.project.agents.join(', ')
+        },
+        markers
+    ];
+}
 function stackProjectCheck(projectRoot, apiStack) {
     let result;
     switch (apiStack) {
@@ -565,23 +1114,23 @@ function binaryPresent(command) {
     const probe = process.platform === 'win32' ? 'where' : 'which';
     return spawnSync(probe, [command], { encoding: 'utf8' }).status === 0;
 }
-function azureCloudChecks() {
-    if (!binaryPresent('az')) {
-        return [{ label: 'az', severity: 'fail', detail: 'Azure CLI not found', remedy: 'install the Azure CLI' }];
+async function azureCloudChecks(runner) {
+    const auth = await runner.run({ executable: 'az', args: ['account', 'show', '-o', 'none', '--only-show-errors'] }, { timeoutMs: 15_000 });
+    if (auth.errorCode === 'ENOENT') {
+        return [{ label: 'az', severity: 'warn', detail: 'Azure CLI not found', remedy: 'install the Azure CLI' }];
     }
-    const auth = spawnSync('az', ['account', 'show', '-o', 'none', '--only-show-errors'], { encoding: 'utf8' });
     if (auth.status === 0) {
         return [{ label: 'azure auth', severity: 'ok', detail: 'authenticated' }];
     }
-    return [{ label: 'azure auth', severity: 'fail', detail: 'not authenticated', remedy: 'run az login' }];
+    return [{ label: 'azure auth', severity: 'warn', detail: 'not authenticated', remedy: 'run az login' }];
 }
 // ponytail: provider-keyed map so aws/gcp checks slot in when their adapters land
 const CLOUD_CHECKS = {
     azure: azureCloudChecks
 };
-function cloudLayer(cloud) {
+async function cloudLayer(cloud, runner) {
     const checks = CLOUD_CHECKS[cloud]
-        ? CLOUD_CHECKS[cloud]()
+        ? await CLOUD_CHECKS[cloud](runner)
         : [{ label: cloud, severity: 'skipped', detail: `${cloud} provider checks are not available yet` }];
     return { title: `Cloud - ${cloud}`, checks };
 }
@@ -654,6 +1203,7 @@ async function projectLayer(projectRoot, manifest) {
     else {
         checks.push({ label: 'version', severity: 'ok', detail: `generated by ${manifest.liftoffVersion}, CLI ${liftoffVersion}` });
     }
+    checks.push(...await frameworkDoctorChecks(projectRoot, manifest));
     checks.push(stackProjectCheck(projectRoot, manifest.project.apiStack));
     try {
         const config = await loadConfigOptions('liftoff.config.json', projectRoot);
@@ -683,7 +1233,7 @@ async function projectLayer(projectRoot, manifest) {
     }
     return { title: 'Project', checks };
 }
-async function runtimeLayer(projectRoot, dockerAvailable) {
+async function runtimeLayer(projectRoot, dockerAvailable, runner) {
     const checks = [];
     if (existsSync(path.join(projectRoot, '.env.example'))) {
         if (existsSync(path.join(projectRoot, '.env'))) {
@@ -703,7 +1253,7 @@ async function runtimeLayer(projectRoot, dockerAvailable) {
         checks.push({ label: 'compose', severity: 'skipped', detail: 'docker is not installed, compose config not checked' });
     }
     else {
-        const result = spawnSync('docker', ['compose', 'config', '-q'], { cwd: projectRoot, encoding: 'utf8' });
+        const result = await runner.run({ executable: 'docker', args: ['compose', 'config', '-q'] }, { cwd: projectRoot, timeoutMs: 15_000 });
         if (result.status === 0) {
             checks.push({ label: 'compose', severity: 'ok', detail: 'docker compose config is valid' });
         }
@@ -718,19 +1268,21 @@ async function runtimeLayer(projectRoot, dockerAvailable) {
     }
     return { title: 'Runtime', checks };
 }
-const severityMarker = {
-    ok: '[ok]',
-    warn: '[warn]',
-    fail: '[fail]',
-    skipped: '[skip]'
-};
-function renderDoctorLayers(layers, stream) {
+function renderDoctorLayers(layers, presentation) {
+    const statusKind = {
+        ok: 'success',
+        warn: 'warning',
+        fail: 'error',
+        skipped: 'pending'
+    };
     for (const layer of layers) {
-        stream.write(`${layer.title}\n`);
-        for (const check of layer.checks) {
+        presentation.section(layer.title, layer.checks.flatMap((check) => {
             const remedy = check.remedy ? ` - ${check.remedy}` : '';
-            stream.write(`  ${severityMarker[check.severity].padEnd(6)} ${check.label}: ${check.detail}${remedy}\n`);
-        }
+            return presentation.stdout
+                .status(statusKind[check.severity], check.label, `${check.detail}${remedy}`)
+                .trimEnd()
+                .split('\n');
+        }));
     }
 }
 export function doctorExitCode(layers) {
@@ -740,6 +1292,7 @@ async function doctorCommand(parsed, context) {
     const jsonMode = readBooleanFlag(parsed.flags, 'json') ?? false;
     const cloudOverride = readStringFlag(parsed.flags, 'cloud');
     const layers = [];
+    context.presentation.commandIdentity('doctor', 'Inspect CLI, workstation, project, runtime, and cloud readiness');
     const projectRoot = await findProjectRoot(context.cwd);
     let manifest;
     let manifestError;
@@ -752,9 +1305,14 @@ async function doctorCommand(parsed, context) {
         }
     }
     layers.push(await cliLayer());
-    const environment = environmentLayer(manifest?.project.apiStack);
+    const runner = context.runner ?? new NodeCommandRunner();
+    const requirements = manifest
+        ? selectWorkstationRequirements(workstationSelectionFromManifest(manifest), { includeFramework: manifest.framework.state === 'initialized' })
+        : selectLiftoffRuntimeRequirements();
+    const probes = await probeWorkstation(requirements, runner);
+    const environment = workstationLayer(probes);
     layers.push(environment);
-    const dockerAvailable = environment.checks.some((check) => check.label === 'docker' && check.severity === 'ok');
+    const dockerAvailable = probes.some((probe) => probe.requirement.id === 'docker' && probe.state === 'ready');
     if (projectRoot) {
         if (manifestError) {
             layers.push({
@@ -764,9 +1322,9 @@ async function doctorCommand(parsed, context) {
         }
         if (manifest) {
             layers.push(await projectLayer(projectRoot, manifest));
-            layers.push(await runtimeLayer(projectRoot, dockerAvailable));
+            layers.push(await runtimeLayer(projectRoot, dockerAvailable, runner));
             const cloud = cloudOverride ?? manifest.project.cloud;
-            const cloudChecks = cloudLayer(cloud);
+            const cloudChecks = await cloudLayer(cloud, runner);
             const pattern = patterns.find((candidate) => candidate.id === manifest.project.pattern);
             if (pattern?.worker && cloud === 'azure') {
                 cloudChecks.checks.push(binaryPresent('func')
@@ -777,22 +1335,24 @@ async function doctorCommand(parsed, context) {
         }
     }
     else if (cloudOverride) {
-        layers.push(cloudLayer(cloudOverride));
+        layers.push(await cloudLayer(cloudOverride, runner));
     }
     const failures = layers.reduce((count, layer) => count + layer.checks.filter((check) => check.severity === 'fail').length, 0);
     const warnings = layers.reduce((count, layer) => count + layer.checks.filter((check) => check.severity === 'warn').length, 0);
     if (jsonMode) {
-        context.stdout.write(`${JSON.stringify({ schemaVersion: 1, layers, summary: { failures, warnings } }, null, 2)}\n`);
+        context.presentation.rawStdout(`${JSON.stringify({ schemaVersion: 1, layers, summary: { failures, warnings } }, null, 2)}\n`);
     }
     else {
-        renderDoctorLayers(layers, context.stdout);
-        context.stdout.write(`${failures} failure(s), ${warnings} warning(s)\n`);
+        renderDoctorLayers(layers, context.presentation);
+        context.presentation.status(failures > 0 ? 'error' : warnings > 0 ? 'warning' : 'success', 'Doctor summary', `${failures} failure(s), ${warnings} warning(s)`);
     }
     return doctorExitCode(layers);
 }
 function helperCommand(parsed, context, tool) {
     const command = parsed.command === 'dev' ? buildDevCommand(parsed) : buildInfraCommand(parsed);
-    context.stdout.write(`${tool} helper command:\n${command}\n`);
+    context.presentation.commandIdentity(parsed.command ?? tool, `${tool} helper command`);
+    context.presentation.section(`${tool} helper command`, []);
+    context.presentation.command(command);
     return 0;
 }
 function buildDevCommand(parsed) {
@@ -839,35 +1399,59 @@ async function optionsFromParsedArgs(parsed, cwd, includeProjectName) {
         includeFrontend: readBooleanFlag(parsed.flags, 'frontend'),
         environments: readListFlag(parsed.flags, 'environments'),
         specWorkflow: readStringFlag(parsed.flags, 'spec'),
+        agents: readListFlag(parsed.flags, 'agents'),
+        defaultAgent: readStringFlag(parsed.flags, 'default-agent'),
         configPath,
-        yes: readBooleanFlag(parsed.flags, 'yes') ?? false
+        yes: readBooleanFlag(parsed.flags, 'yes') ?? false,
+        force: readBooleanFlag(parsed.flags, 'force'),
+        installTools: readBooleanFlag(parsed.flags, 'install-tools'),
+        installDependencies: readBooleanFlag(parsed.flags, 'install-dependencies')
     };
     return mergeOptions(configOptions, flagOptions);
 }
-function hasMissingCreateInputs(options) {
+function hasMissingInitInputs(options) {
     const projectType = options.projectType ?? (options.pattern ? 'genai' : options.apiStack ? 'standard' : undefined);
     const missingTypeSpecific = projectType === 'genai' ? !options.pattern : projectType === 'standard' ? !options.apiStack : true;
-    return !options.projectName || missingTypeSpecific || !options.cloud || options.includeFrontend === undefined || !options.specWorkflow || !options.environments;
-}
-function printHelp(stream) {
-    stream.write(`Mission Control Liftoff ${liftoffVersion}\n\n`);
-    stream.write(`Global options:\n`);
-    stream.write(`  --version   Show the installed Liftoff version\n`);
-    stream.write(`  --help      Show general help\n\n`);
-    stream.write(`Commands:\n`);
-    stream.write(`  create      Generate a new project\n`);
-    stream.write(`  plan        Preview generated artifacts\n`);
-    stream.write(`  patterns    List GenAI patterns\n`);
-    stream.write(`  providers   List cloud providers\n`);
-    stream.write(`  regions     List or search provider regions\n`);
-    stream.write(`  validate    Validate a generated project manifest\n`);
-    stream.write(`  update      Reconcile a project with the current templates (check by default; --apply, --force)\n`);
-    stream.write(`  migrate     Adopt an existing project: fresh scaffold + staged copy + migration plan\n`);
-    stream.write(`  doctor      Check local readiness\n`);
-    stream.write(`  dev         Print Docker Compose helper commands\n`);
-    stream.write(`  infra       Print OpenTofu helper commands\n`);
-    stream.write(`\nProject types: GenAI (Python/FastAPI/PydanticAI) or standard API\n`);
-    stream.write(`Standard API stacks: ${apiStacks.map((stack) => stack.label).join(', ')}\n`);
+    const missingDefaultAgent = options.specWorkflow === 'spec-kit' &&
+        (options.agents?.length ?? 0) > 1 &&
+        !options.defaultAgent;
+    return !options.projectName ||
+        missingTypeSpecific ||
+        !options.cloud ||
+        options.includeFrontend === undefined ||
+        !options.specWorkflow ||
+        !options.agents ||
+        missingDefaultAgent ||
+        !options.environments;
+}
+function renderGeneralHelp(presentation) {
+    const help = getGeneralHelp(liftoffVersion);
+    presentation.identity(`${help.title} - ${help.subtitle}`);
+    presentation.section('Usage', [help.usage]);
+    presentation.table('Global options', ['Option', 'Description'], help.globalOptions.map((option) => [option.syntax, option.description]));
+    for (const group of help.commandGroups) {
+        presentation.table(group.title, ['Command', 'Description'], group.entries.map((entry) => [entry.syntax, entry.description]));
+    }
+    presentation.status('info', 'Tip', help.hint);
+}
+function renderCommandHelp(command, presentation) {
+    const help = getCommandHelp(command);
+    presentation.commandIdentity(help.command, help.description);
+    presentation.section('Usage', [
+        presentation.stdout.layout === 'plain' ? `Usage: ${help.usage}` : help.usage
+    ]);
+    if (help.arguments.length > 0) {
+        presentation.table('Arguments', ['Argument', 'Description'], help.arguments.map((argument) => [argument.syntax, argument.description]));
+    }
+    if (help.subcommands.length > 0) {
+        presentation.bullets('Subcommands', help.subcommands);
+    }
+    for (const group of help.optionGroups) {
+        presentation.table(group.title, ['Option', 'Description'], group.entries.map((entry) => [
+            entry.syntax,
+            `${entry.description}${entry.defaultValue ? ` (default: ${entry.defaultValue})` : ''}`
+        ]));
+    }
 }
 export async function createFixtureProject(options) {
     const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'liftoff-'));
@@ -877,6 +1461,27 @@ export async function createFixtureProject(options) {
     await assertNewOrEmptyDirectory(target);
     await rm(target, { recursive: true, force: true });
     await writeArtifacts(target, buildArtifacts(plan));
+    for (const marker of [
+        ...plan.framework.baseMarkers,
+        ...plan.agents.flatMap((agent) => plan.framework.agentMarkers[agent.id])
+    ]) {
+        let content = 'fixture marker\n';
+        if (marker.join('/') === '.specify/integration.json') {
+            const installed = plan.agents.map((agent) => agent.integrationIds['spec-kit']);
+            const defaultIntegration = plan.defaultAgent?.integrationIds['spec-kit'];
+            content = `${JSON.stringify({
+                integration_state_schema: 1,
+                integration: defaultIntegration,
+                default_integration: defaultIntegration,
+                installed_integrations: installed,
+                integration_settings: {}
+            }, null, 2)}\n`;
+        }
+        else if (marker.join('/') === '.specify/init-options.json') {
+            content = '{}\n';
+        }
+        await writeProjectFile(target, marker, content);
+    }
     return target;
 }
 //# sourceMappingURL=commands.js.map