@msn-control/liftoff 0.4.0 → 0.4.1

package/dist/commands.js

@@ -4,28 +4,38 @@ import { existsSync } from 'node:fs';
 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, formatGeneralHelp, readBooleanFlag, readListFlag, readStringFlag } from './args.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 { confirmDependencyInstallation, confirmFileReplacements, confirmPlan, confirmToolInstallation, promptForInitOptions } from './interactive.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, partitionGeneratedArtifacts } from './templates.js';
-import { TerminalRenderer } from './terminal.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) {
@@ -33,156 +43,191 @@ 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 'init':
-                return await initCommand(parsed, context);
+                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 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 needsPrompts = !initial.yes && hasMissingInitInputs(initial);
-    const options = needsPrompts ? await promptForInitOptions(initial) : initial;
-    const plan = buildProjectPlan(options, { requireProjectName: true });
-    const confirmed = await confirmPlan(plan, options.yes);
-    if (!confirmed) {
-        context.stdout.write('Initialization cancelled.\n');
-        return 0;
-    }
-    const target = resolveInitTargetFromDiscovery(git, plan.safeProjectName);
-    await assertSafeInitTarget(target, target.mode === 'named-child' ? git.canonicalCwd : undefined);
-    const renderer = new TerminalRenderer({ stream: context.stdout });
-    renderer.write(renderer.banner('Initialize the project and prepare its workstation'));
-    const readiness = await ensureWorkstationReady(plan, options, context, runner, renderer);
-    if (!readiness.ready) {
-        return 1;
-    }
-    const staged = await withStagingArea(async (area) => {
-        const partition = partitionGeneratedArtifacts(buildArtifacts(plan));
-        await writeStagedArtifacts(area, partition.durable, 'liftoff');
-        await initializeFramework(area, plan, runner, { stdout: context.stdout, stderr: context.stderr });
-        await writeStagedArtifacts(area, partition.seed, 'seed');
-        await writeStagedArtifacts(area, [partition.manifest], 'liftoff');
-        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 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;
         }
-        const preflight = await buildMergePreflight(area, target.root);
-        const interactive = options.yes !== true;
-        const authorized = await authorizeMergePreflight(preflight, options.force === true, interactive ? confirmFileReplacements : undefined);
-        if (!authorized) {
-            return {
-                status: interactive ? 'declined' : 'authorization-required'
-            };
+        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;
         }
-        return { status: 'applied', merge: await applyMergePreflight(authorized) };
-    });
-    if (staged.status === 'declined') {
-        context.stdout.write('Initialization cancelled; no destination files were changed.\n');
+        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;
     }
-    if (staged.status === 'authorization-required') {
-        context.stderr.write('Existing regular-file conflicts require --force in non-interactive mode.\n');
-        return 1;
-    }
-    const issues = await validateGeneratedProject(target.root);
-    if (issues.length > 0) {
-        context.stderr.write(`Initialized project validation failed:\n${issues.join('\n')}\n`);
-        return 1;
-    }
-    const dependencyPhase = await handleProjectDependencies(plan, target.root, options, readiness.probes, context, runner, renderer);
-    if (!dependencyPhase.success) {
-        return 1;
-    }
-    renderer.write(renderer.status('success', `Initialized ${plan.projectName}`, target.root));
-    renderer.write(renderer.panel('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) {
-        renderer.write(renderer.panel('Deferred advisory checks', readiness.deferred));
-    }
-    if (dependencyPhase.deferred.length > 0) {
-        renderer.write(renderer.panel('Deferred project dependencies', dependencyPhase.deferred));
+    finally {
+        prompter?.close();
     }
-    renderer.write(renderer.command(`liftoff validate ${JSON.stringify(target.root)}`));
-    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`);
-    }
-    context.stdout.write('\nWorkstation requirements:\n');
-    for (const requirement of selectWorkstationRequirements(plan)) {
-        const version = requirement.exactVersion
+    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';
-        context.stdout.write(`- ${requirement.definition.label}: ${version} [${requirement.severity}]\n`);
+                : '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;
 }
-async function ensureWorkstationReady(plan, options, context, runner, renderer, resumeInvocation = 'liftoff init', commandCwd) {
+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 });
-    renderer.write(renderer.heading('Workstation readiness'));
-    renderer.write(renderer.table(['Requirement', 'Level', 'State', 'Detail'], probes.map((probe) => [
+    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) => {
@@ -213,17 +258,16 @@ async function ensureWorkstationReady(plan, options, context, runner, renderer,
                 : probe.requirement.minimumVersion
                     ? `required ${probe.requirement.minimumVersion} or newer`
                     : 'required to be available';
-            const action = automatic
-                ? `Command: ${formatCommand(recipe.command)}`
-                : `Manual remedy: ${installInstruction(probe)}`;
-            const detail = [
-                `${probe.requirement.definition.label} [${probe.requirement.severity}]`,
-                `Purpose: ${probe.requirement.reasons.join('; ')}`,
-                `Requirement: ${constraint}`,
-                `Observed: ${probe.state} - ${probe.detail}`,
-                action
-            ].map((line) => `  ${line}`).join('\n');
-            if (await confirmToolInstallation(detail)) {
+            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);
             }
         }
@@ -234,12 +278,17 @@ async function ensureWorkstationReady(plan, options, context, runner, renderer,
             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: { stdout: context.stdout, stderr: context.stderr }
+                streamOptions: presentation.childStreams()
             });
             updates.set(probe.requirement.id, installation.probe);
             const kind = installation.state === 'installed'
@@ -247,9 +296,9 @@ async function ensureWorkstationReady(plan, options, context, runner, renderer,
                 : probe.requirement.severity === 'blocking'
                     ? 'error'
                     : 'warning';
-            renderer.write(renderer.status(kind, probe.requirement.definition.label, installation.detail));
+            presentation.status(kind, probe.requirement.definition.label, installation.detail);
             if (installation.remedy) {
-                renderer.write(renderer.command(installation.remedy));
+                presentation.command(installation.remedy);
             }
         }
         probes = probes.map((probe) => updates.get(probe.requirement.id) ?? probe);
@@ -257,12 +306,11 @@ async function ensureWorkstationReady(plan, options, context, runner, renderer,
     const blockers = blockingReadinessFailures(probes);
     if (blockers.length > 0) {
         for (const blocker of blockers) {
-            context.stderr.write(`${blocker.requirement.definition.label}: ${blocker.detail}` +
-                `\nRemedy: ${installInstruction(blocker)}\n`);
+            presentation.error(`${blocker.requirement.definition.label}: ${blocker.detail}`, installInstruction(blocker));
         }
-        context.stderr.write(options.installTools
-            ? `Open a new terminal if PATH changed, then rerun \`${resumeInvocation}\` with the same project options.\n`
-            : `Resume with \`${resumeInvocation} --install-tools\` plus the same project options after reviewing the commands.\n`);
+        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 = [
@@ -275,13 +323,13 @@ async function ensureWorkstationReady(plan, options, context, runner, renderer,
     ];
     return { ready: true, deferred, probes };
 }
-async function handleProjectDependencies(plan, projectRoot, options, probes, context, runner, renderer) {
+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 confirmDependencyInstallation(dependencyPlan.commands);
+        installDependencies = await prompter.confirmDependencyInstallation(dependencyPlan.commands);
     }
     if (!installDependencies) {
         return {
@@ -289,62 +337,66 @@ async function handleProjectDependencies(plan, projectRoot, options, probes, con
             deferred: dependencyPlan.commands.map((command) => `${command.label}: ${command.cwd} -> ${formatCommand(command.command)}`)
         };
     }
+    presentation.stage('Install project dependencies');
     const result = await runDependencySetup(dependencyPlan, projectRoot, runner, {
-        stdout: context.stdout,
-        stderr: context.stderr
+        ...presentation.childStreams(),
+        onCommand: (command) => {
+            presentation.status('pending', command.label, command.cwd);
+            presentation.command(formatCommand(command.command));
+        }
     });
     if (!result.success) {
-        renderer.write(renderer.status('error', 'Project dependencies failed', `${result.failed?.label ?? 'dependency command'}: ${result.detail ?? 'unknown failure'}`));
-        renderer.write(renderer.status('info', 'Scaffold preserved', projectRoot));
+        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) {
-            renderer.write(renderer.warning(`Restored protected files: ${result.restoredMutations.join(', ')}`));
+            presentation.warning(`Restored protected files: ${result.restoredMutations.join(', ')}`);
         }
         if (result.resumeCommand) {
-            renderer.write(renderer.command(result.resumeCommand));
+            presentation.command(result.resumeCommand);
         }
         return { success: false, deferred: [] };
     }
-    renderer.write(renderer.status('success', 'Project dependencies', `${result.completed.length} command${result.completed.length === 1 ? '' : 's'} completed`));
+    presentation.status('success', 'Project dependencies', `${result.completed.length} command${result.completed.length === 1 ? '' : 's'} completed`);
     return { success: true, deferred: [] };
 }
 function patternsCommand(context) {
-    context.stdout.write('Patterns:\n');
-    for (const pattern of patterns) {
-        context.stdout.write(`- ${pattern.id}: ${pattern.label} [${pattern.scaffoldStatus}]\n`);
-    }
+    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']);
@@ -454,13 +506,16 @@ function migrationPlanArtifacts(plan, inventory) {
     };
 }
 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) {
@@ -479,97 +534,125 @@ async function executeMigration(parsed, context, sourceRoot) {
     if (flagOptions.projectType === 'genai' && flagOptions.apiStack === undefined) {
         initial.apiStack = undefined;
     }
-    const needsPrompts = !initial.yes && hasMissingInitInputs(initial);
-    const options = needsPrompts ? await promptForInitOptions(initial) : initial;
-    const plan = buildProjectPlan(options, { requireProjectName: true });
-    const confirmed = await confirmPlan(plan, options.yes);
-    if (!confirmed) {
-        context.stdout.write('Migration cancelled.\n');
-        return 0;
-    }
-    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();
-    const renderer = new TerminalRenderer({ stream: context.stdout });
-    renderer.write(renderer.banner('Migrate into a fresh Liftoff project'));
-    const readinessRoot = await mkdtemp(path.join(os.tmpdir(), 'liftoff-migrate-readiness-'));
-    const readiness = await (async () => {
-        try {
-            return await ensureWorkstationReady(plan, options, context, runner, renderer, `liftoff migrate ${JSON.stringify(sourceRoot)}`, readinessRoot);
+    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');
         }
-        finally {
-            await rm(readinessRoot, { recursive: true, force: true });
+        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;
         }
-    })();
-    if (!readiness.ready) {
-        return 1;
-    }
-    const migrationPlan = migrationPlanArtifacts(plan, inventory);
-    await withStagingArea(async (area) => {
-        const partition = partitionGeneratedArtifacts(buildArtifacts(plan));
-        await writeStagedArtifacts(area, partition.durable, 'liftoff');
-        await initializeFramework(area, plan, runner, {
-            stdout: context.stdout,
-            stderr: context.stderr
+        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 });
         });
-        await writeStagedArtifacts(area, partition.seed, 'seed');
-        await stageMigrationSource(area, sourceRoot);
-        await writeStagedArtifacts(area, migrationPlan.artifacts, 'seed');
-        await writeStagedArtifacts(area, [partition.manifest], 'liftoff');
-        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 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;
         }
-        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'));
+        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);
         }
-        const authorized = await authorizeMergePreflight(preflight, false);
-        if (!authorized) {
-            throw new Error('Migration target authorization failed.');
+        if (dependencyPhase.deferred.length > 0) {
+            presentation.bullets('Deferred project dependencies', dependencyPhase.deferred);
         }
-        await applyMergePreflight(authorized, { requireEmptyTarget: true });
-    });
-    const issues = await validateGeneratedProject(targetRoot);
-    if (issues.length > 0) {
-        context.stderr.write(`Migrated project validation failed:\n${issues.join('\n')}\n`);
-        return 1;
-    }
-    const dependencyPhase = await handleProjectDependencies(plan, targetRoot, options, readiness.probes, context, runner, renderer);
-    if (!dependencyPhase.success) {
-        return 1;
-    }
-    renderer.write(renderer.status('success', `Migrated ${plan.projectName}`, targetRoot));
-    renderer.write(renderer.panel('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) {
-        renderer.write(renderer.panel('Deferred advisory checks', readiness.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;
     }
-    if (dependencyPhase.deferred.length > 0) {
-        renderer.write(renderer.panel('Deferred project dependencies', dependencyPhase.deferred));
+    finally {
+        prompter?.close();
     }
-    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: ${migrationPlan.location}\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;
 }
 async function migrateCommand(parsed, context) {
     const sourceArg = parsed.positional[0];
     if (!sourceArg) {
-        context.stderr.write('Usage: liftoff migrate <path-to-existing-project>\n');
+        context.presentation.error('Usage: liftoff migrate <path-to-existing-project>', 'Run `liftoff migrate --help` for accepted migration options.');
         return 1;
     }
     const sourceRoot = path.resolve(context.cwd, sourceArg);
@@ -578,17 +661,18 @@ async function migrateCommand(parsed, context) {
         sourceDetails = await stat(sourceRoot);
     }
     catch {
-        context.stderr.write(`Source project not found: ${sourceRoot}\n`);
+        context.presentation.error(`Source project not found: ${sourceRoot}`);
         return 1;
     }
     if (!sourceDetails.isDirectory()) {
-        context.stderr.write(`Source path is not a directory: ${sourceRoot}\n`);
+        context.presentation.error(`Source path is not a directory: ${sourceRoot}`);
         return 1;
     }
     if (existsSync(path.join(sourceRoot, 'liftoff.manifest.json'))) {
-        context.stderr.write(`${sourceRoot} is already a Liftoff project. Use liftoff update instead.\n`);
+        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) {
@@ -659,47 +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) {
-        context.stderr.write(`Spec workflow changes (${manifest.project.specWorkflow} -> ${plan.specWorkflow.id}) require official framework initialization and are not supported by liftoff update.\n`);
+        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)) {
-        context.stderr.write('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.\n');
+        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);
@@ -709,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,
@@ -725,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 = [];
@@ -813,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,
@@ -824,18 +917,17 @@ 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 versionedBinaryCheck(label, command, args, minimum, remedy) {
@@ -1022,11 +1114,11 @@ function binaryPresent(command) {
     const probe = process.platform === 'win32' ? 'where' : 'which';
     return spawnSync(probe, [command], { encoding: 'utf8' }).status === 0;
 }
-function azureCloudChecks() {
-    if (!binaryPresent('az')) {
+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' }];
     }
@@ -1036,9 +1128,9 @@ function azureCloudChecks() {
 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 };
 }
@@ -1141,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'))) {
@@ -1161,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' });
         }
@@ -1176,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) {
@@ -1198,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;
@@ -1227,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')
@@ -1240,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) {
@@ -1327,10 +1424,34 @@ function hasMissingInitInputs(options) {
         missingDefaultAgent ||
         !options.environments;
 }
-function printHelp(stream) {
-    const renderer = new TerminalRenderer({ stream });
-    renderer.write(renderer.banner('Project workstation and scaffold initializer'));
-    stream.write(formatGeneralHelp(liftoffVersion));
+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-'));