@mono-agent/agent-app 0.5.1 → 0.6.1

package/dist/cli.js

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
-import { createInterface } from "node:readline/promises";
 import { stat } from "node:fs/promises";
 import { createRequire } from "node:module";
 import { basename, resolve } from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
-import { buildMonoAgentConfigView, findJsonSecretConfigWarnings, findRemovedConfigWarnings, readMonoAgentConfigJson, redactMonoAgentConfig, } from "@mono-agent/config";
+import { buildMonoAgentConfigView, EFFORT_LEVELS, findJsonSecretConfigWarnings, findRemovedConfigWarnings, readMonoAgentConfigJson, redactMonoAgentConfig, } from "@mono-agent/config";
 import { listRecordedRuns } from "@mono-agent/observability";
 import { describeSandboxEffectiveState, sandboxEffectiveStateWarning, } from "@mono-agent/runtime-adapter";
 import { startMonoAgentApp } from "./app.js";
@@ -18,13 +17,16 @@ import { formatChannelFactValue } from "./channel-fact-format.js";
 import { resolveChannelDrivers } from "./channels.js";
 import { findUnknownAppConfigWarnings } from "./config-reference.js";
 import { validateMonoAgentFolder } from "./doctor.js";
-import { initMonoAgentFolder, isWithChannel } from "./init.js";
+import { initMonoAgentFolder } from "./init.js";
 import { installComposerSkill } from "./install-skill.js";
 import { runMetrics } from "./metrics.js";
-import { findRecipe, RECIPE_CATALOG, recipeIds, resolveRecipeInputs } from "./recipes/index.js";
 import { buildRunsHealthDisplay, RUNS_HEALTH_MAX_RUNS } from "./runs-health.js";
 import { purgeSessions } from "./sessions.js";
-import { collectSetupOptions } from "./setup.js";
+import { composeWizardPlan } from "./wizard/answers.js";
+import { answersFromCli, isWithChannel } from "./wizard/from-flags.js";
+import { findPreset, PRESET_CATALOG, presetAnswers, presetIds, RECIPE_TO_PRESET } from "./wizard/presets.js";
+import { runInitWizard } from "./wizard/run.js";
+import { executeProviderSetupPlan, planProviderSetup, providerSetupActionCommandLine } from "./provider-setup.js";
 import * as ui from "./ui.js";
 const DEFAULT_LOG_LINES = 200;
 // Node's maximum setInterval/setTimeout delay (2^31 - 1 ms, ~24.8 days). A
@@ -32,7 +34,7 @@ const DEFAULT_LOG_LINES = 200;
 // busy-waiting; larger values silently overflow to a 1ms delay.
 const KEEP_ALIVE_INTERVAL_MS = 2_147_483_647;
 const BACKGROUND_COMMANDS = ["start", "restart", "stop", "status", "logs"];
-const KNOWN_COMMANDS = ["init", "setup", "validate", "doctor", "config", "recipes", "start", "restart", "stop", "status", "logs", "tui", "web", "install-skill", "backfill", "audit-runs", "metrics", "memory"];
+const KNOWN_COMMANDS = ["init", "setup", "validate", "doctor", "config", "recipes", "presets", "start", "restart", "stop", "status", "logs", "tui", "web", "install-skill", "backfill", "audit-runs", "metrics", "memory"];
 export function parseCliArgs(argv) {
     const [command, ...rest] = argv;
     if (command === undefined || command === "help" || command === "--help" || command === "-h") {
@@ -44,16 +46,27 @@ export function parseCliArgs(argv) {
     if (!KNOWN_COMMANDS.includes(command)) {
         throw new Error(`Unknown command \`${command}\`. Expected ${KNOWN_COMMANDS.join(", ")}.`);
     }
-    // `doctor` is an alias of `validate`; normalize here so every downstream
-    // validate path (env-file resolution, --consumer, routing) applies unchanged.
-    const cmd = (command === "doctor" ? "validate" : command);
+    // `doctor`/`setup`/`recipes` are aliases; normalize here so every downstream
+    // path (routing, env-file resolution, --consumer) applies unchanged. `doctor`
+    // → `validate`, `setup` → `init`, `recipes` → `presets`.
+    const cmd = (command === "doctor"
+        ? "validate"
+        : command === "setup"
+            ? "init"
+            : command === "recipes"
+                ? "presets"
+                : command);
     const isLogs = cmd === "logs";
     let configPath;
     let model;
     let fallbackModels;
+    let effort;
     let memory;
+    let preset;
     let recipe;
     let withChannels;
+    let yes = false;
+    let auth = false;
     const positionals = [];
     let envFile;
     let target;
@@ -184,6 +197,14 @@ export function parseCliArgs(argv) {
                     .map((entry) => entry.trim())
                     .filter((entry) => entry.length > 0);
                 break;
+            case "--effort": {
+                const raw = requireValue(rest, ++i, flag);
+                if (!EFFORT_LEVELS.includes(raw)) {
+                    throw new Error(`--effort must be ${EFFORT_LEVELS.join(", ")}.`);
+                }
+                effort = raw;
+                break;
+            }
             case "--memory": {
                 const raw = requireValue(rest, ++i, flag);
                 if (raw !== "lite" && raw !== "journal" && raw !== "bujo") {
@@ -192,9 +213,18 @@ export function parseCliArgs(argv) {
                 memory = raw;
                 break;
             }
+            case "--preset":
+                preset = requireValue(rest, ++i, flag);
+                break;
             case "--recipe":
                 recipe = requireValue(rest, ++i, flag);
                 break;
+            case "--yes":
+                yes = true;
+                break;
+            case "--auth":
+                auth = true;
+                break;
             case "--with":
                 withChannels = requireValue(rest, ++i, flag)
                     .split(",")
@@ -264,14 +294,21 @@ export function parseCliArgs(argv) {
     if (limit !== undefined && cmd !== "memory") {
         throw new Error("--limit is only supported for `mono-agent memory`.");
     }
+    if (auth && cmd !== "init") {
+        throw new Error("--auth is only supported for `mono-agent init`.");
+    }
     return {
         command: cmd,
         ...(configPath === undefined ? {} : { configPath }),
         ...(model === undefined ? {} : { model }),
         ...(fallbackModels === undefined ? {} : { fallbackModels }),
+        ...(effort === undefined ? {} : { effort }),
         ...(memory === undefined ? {} : { memory }),
+        ...(preset === undefined ? {} : { preset }),
         ...(recipe === undefined ? {} : { recipe }),
         ...(withChannels === undefined ? {} : { withChannels }),
+        ...(yes ? { yes } : {}),
+        ...(auth ? { auth } : {}),
         positionals,
         ...(envFile === undefined ? {} : { envFile }),
         ...(target === undefined ? {} : { target }),
@@ -332,36 +369,34 @@ function requireValue(args, index, flag) {
 }
 const HELP_COMMANDS = [
     {
-        signature: "mono-agent init [--recipe <id>] [--with <csv>] [--dry-run]\n" +
-            "                [--model <ref>] [--fallback-models <csv>] [--memory lite|journal|bujo]",
+        signature: "mono-agent init [--preset <id>] [--with <csv>] [--yes] [--auth] [--dry-run]\n" +
+            "                [--model <ref>] [--fallback-models <csv>] [--effort <level>]\n" +
+            "                [--memory lite|journal|bujo]",
         lines: [
-            "Scaffold mono-agent.config.json, IDENTITY.md, and .mono-agent/ in the",
-            "current folder. With --recipe, build from a blueprint (+ .env.example);",
-            "--with adds channels, --dry-run previews. Existing files are never overwritten.",
+            "Scaffold a mono-agent in the current folder. On a TTY with no flags, launches",
+            "the step-by-step wizard; with --yes or any flag, writes the default/preset",
+            "scaffold non-interactively. --preset seeds a blueprint, --with adds channels,",
+            "--effort writes runtime.effort, --auth runs supported provider auth/preflight",
+            "commands before writing, and --dry-run previews only. Existing files are never overwritten.",
         ],
     },
     {
-        signature: "mono-agent setup [--recipe <id>] [--with <csv>] [--dry-run]\n" +
-            "                 [--model <ref>] [--fallback-models <csv>] [--memory lite|journal|bujo]",
-        lines: [
-            "Guided setup when attached to a TTY: choose a recipe, answer non-secret",
-            "inputs, select channel add-ons, scaffold, validate, and print the secrets",
-            "checklist. In non-TTY contexts it falls back to init-style flags.",
-        ],
+        signature: "mono-agent setup",
+        lines: ["Alias of `init`."],
     },
     {
-        signature: "mono-agent recipes list | show <id>",
+        signature: "mono-agent presets list | show <id>",
         lines: [
-            "List the executable config blueprints, or show one's generated config,",
+            "List the built-in setup presets, or show one's generated config,",
             ".env.example, and follow-up checklist.",
         ],
     },
     {
-        signature: "mono-agent validate [--recipe <id>] [--consumer <path>] [--config <path>] [--env-file <path>]",
+        signature: "mono-agent validate [--preset <id>] [--consumer <path>] [--config <path>] [--env-file <path>]",
         lines: [
             "Load every config section and report what would run, wait, or fail.",
             "--consumer validates another agent folder read-only, including its .env.",
-            "With --recipe, also report whether the recipe's capabilities are live.",
+            "With --preset, also report whether the preset's capabilities are live.",
             "`mono-agent doctor` is an alias for this command.",
         ],
     },
@@ -473,8 +508,12 @@ const HELP_NOTES = `Background mode runs the agent under launchd, keeping it ali
 .env file in the working directory, the same as foreground mode. The background
 commands require macOS; elsewhere use start --foreground.
 
-Model references look like claude:claude-sonnet-4-6, codex:gpt-5.5, or
-pi:<provider>:<model> (e.g. pi:ollama:gemma4:31b).
+Init model references look like claude:claude-sonnet-4-6, codex:gpt-5.5,
+or pi:<provider>:<model> (e.g. pi:openai-codex:gpt-5.5,
+pi:opencode-go:kimi-k2.6, or pi:ollama:gemma4:31b). The init wizard prefers
+Pi OpenAI-Codex when that auth is configured, while direct codex:gpt-5.5
+remains selectable as a Codex CLI fallback path. Direct opencode:<provider>:<model>
+refs are for hand-authored runtime backend config.
 
 A .env file in the current folder is loaded automatically when present;
 already-exported shell variables take precedence.
@@ -536,14 +575,12 @@ export async function runCli(argv) {
             return 0;
         case "init":
             return await runInit(args);
-        case "setup":
-            return await runSetup(args);
         case "validate":
             return await runValidate(args);
         case "config":
             return await runConfig(args);
-        case "recipes":
-            return runRecipes(args);
+        case "presets":
+            return runPresets(args);
         case "start":
             return await runStart(args);
         case "restart":
@@ -623,93 +660,146 @@ export async function runCli(argv) {
     }
 }
 async function runInit(args) {
-    const recipe = resolveRecipeArg(args);
-    if (recipe === "unknown") {
+    // On an interactive TTY with no overriding flags, walk the step-by-step wizard;
+    // any flag (or a piped/non-TTY invocation) takes the silent default/preset path.
+    const wantsWizard = process.stdin.isTTY === true && process.stdout.isTTY === true
+        && args.yes !== true && args.preset === undefined && args.recipe === undefined
+        && args.model === undefined && args.fallbackModels === undefined
+        && args.effort === undefined && args.memory === undefined && args.withChannels === undefined && args.dryRun !== true;
+    if (wantsWizard) {
+        // Existing-config pre-check — don't walk the wizard into a guaranteed no-op.
+        if (await pathExists(resolve(process.cwd(), "mono-agent.config.json"))) {
+            process.stdout.write(ui.hint("Found an existing mono-agent.config.json — `mono-agent init` never overwrites. Run `mono-agent validate`, or start in an empty folder.\n"));
+            return 0;
+        }
+        const outcome = await runInitWizard({ cwd: process.cwd() });
+        if (outcome.status === "cancelled") {
+            return 1;
+        }
+        if (outcome.runProviderSetup) {
+            const previewPlan = composeWizardPlan(outcome.answers, {
+                dirBasename: basename(process.cwd()),
+                skillsRootExists: await pathExists(resolve(process.cwd(), "skills")),
+            });
+            const setup = await runProviderSetupBeforeInit({
+                modelRefs: [outcome.answers.model, ...outcome.answers.fallbackModels],
+                cwd: process.cwd(),
+                auth: true,
+                dryRun: false,
+                ...(typeof previewPlan.configJson.providers?.piAuthPath === "string" ? { piAuthPath: previewPlan.configJson.providers.piAuthPath } : {}),
+            });
+            if (setup === "failed") {
+                return 1;
+            }
+        }
+        const result = await initMonoAgentFolder({ dir: process.cwd(), answers: outcome.answers });
+        printInitResult(result);
+        const report = await validateMonoAgentFolder({ env: process.env, cwd: process.cwd(), configPath: result.configPath });
+        process.stdout.write("\n" + ui.heading("Validation"));
+        for (const section of report.sections) {
+            process.stdout.write(formatSection(section));
+        }
+        process.stdout.write(renderPlanCompleteness(result.plan.validateExpectations, "Selected capabilities", report));
+        printSecretsChecklist(result.plan.secrets);
+        printNextSteps(result.configPath);
+        return report.ok ? 0 : 1;
+    }
+    const presetId = resolveInitPresetId(args);
+    if (presetId === "unknown") {
         return 1;
     }
     const withChannels = resolveWithChannels(args);
     if (withChannels === "invalid") {
         return 1;
     }
-    const result = await initMonoAgentFolder({
-        dir: process.cwd(),
+    const answers = answersFromCli({
         ...(args.model === undefined ? {} : { model: args.model }),
         ...(args.fallbackModels === undefined ? {} : { fallbackModels: args.fallbackModels }),
+        ...(args.effort === undefined ? {} : { effort: args.effort }),
         ...(args.memory === undefined ? {} : { memory: args.memory }),
-        ...(recipe === undefined ? {} : { recipe }),
         ...(withChannels === undefined ? {} : { withChannels }),
-        dryRun: args.dryRun,
+        ...(presetId === undefined ? {} : { presetId }),
     });
-    printInitResult(result, recipe);
-    printNextSteps(result.configPath, recipe);
-    return 0;
-}
-async function runSetup(args) {
-    if (process.stdin.isTTY !== true) {
-        return await runInit(args);
-    }
-    const recipeArg = resolveRecipeArg(args);
-    if (recipeArg === "unknown") {
-        return 1;
-    }
-    const withChannelsArg = resolveWithChannels(args);
-    if (withChannelsArg === "invalid") {
-        return 1;
-    }
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    let collected;
-    try {
-        collected = await collectSetupOptions({
-            prompt: { question: (prompt) => rl.question(prompt) },
-            ...(recipeArg === undefined ? {} : { recipe: recipeArg }),
-            ...(args.model === undefined ? {} : { model: args.model }),
-            ...(args.fallbackModels === undefined ? {} : { fallbackModels: args.fallbackModels }),
-            ...(withChannelsArg === undefined ? {} : { withChannels: withChannelsArg }),
-        });
-    }
-    finally {
-        rl.close();
-    }
-    const result = await initMonoAgentFolder({
-        dir: process.cwd(),
-        ...(collected.fallbackModels.length === 0 ? {} : { fallbackModels: collected.fallbackModels }),
-        ...(args.memory === undefined ? {} : { memory: args.memory }),
-        recipe: collected.recipe,
-        recipeInputs: collected.recipeInputs,
-        withChannels: collected.withChannels,
+    const previewPlan = composeWizardPlan(answers, {
+        dirBasename: basename(process.cwd()),
+        skillsRootExists: await pathExists(resolve(process.cwd(), "skills")),
+    });
+    const setup = await runProviderSetupBeforeInit({
+        modelRefs: [answers.model, ...answers.fallbackModels],
+        cwd: process.cwd(),
+        auth: args.auth === true,
         dryRun: args.dryRun,
+        ...(typeof previewPlan.configJson.providers?.piAuthPath === "string" ? { piAuthPath: previewPlan.configJson.providers.piAuthPath } : {}),
     });
-    printInitResult(result, collected.recipe);
-    if (!result.dryRun) {
-        const report = await validateMonoAgentFolder({
-            env: process.env,
-            cwd: process.cwd(),
-            configPath: result.configPath,
-        });
-        process.stdout.write("\n" + ui.heading("Validation"));
-        for (const section of report.sections) {
-            process.stdout.write(formatSection(section));
-        }
-        process.stdout.write(renderRecipeCompleteness(collected.recipe, report));
-        printSecretsChecklist(collected.secrets);
-        printNextSteps(result.configPath, collected.recipe);
-        return report.ok ? 0 : 1;
+    if (setup === "failed") {
+        return 1;
     }
-    printSecretsChecklist(collected.secrets);
-    printNextSteps(result.configPath, collected.recipe);
+    const result = await initMonoAgentFolder({ dir: process.cwd(), answers, dryRun: args.dryRun });
+    printInitResult(result);
+    printSecretsChecklist(result.plan.secrets);
+    printNextSteps(result.configPath);
     return 0;
 }
-function resolveRecipeArg(args) {
-    if (args.recipe === undefined) {
-        return undefined;
+export async function runProviderSetupBeforeInit(options) {
+    const plan = planProviderSetup(options);
+    if (plan.actions.length === 0) {
+        return "skipped";
+    }
+    if (options.dryRun) {
+        process.stdout.write("\n" + ui.heading("Provider setup"));
+        process.stdout.write(ui.style.dim("Dry run - provider auth/preflight commands were not launched.\n"));
+        printProviderSetupPlan(plan);
+        return "skipped";
+    }
+    if (!options.auth) {
+        return "skipped";
+    }
+    process.stdout.write("\n" + ui.heading("Provider setup"));
+    printProviderSetupPlan(plan);
+    const results = await (options.execute ?? executeProviderSetupPlan)(plan);
+    for (const result of results) {
+        const badge = result.status === "ok" ? ui.badge("ok") : ui.badge("error");
+        process.stdout.write(`${badge}${result.action.label}: ${result.detail}\n`);
+    }
+    if (results.some((result) => result.status === "failed")) {
+        process.stderr.write(ui.errorLine("Provider setup failed; init stopped before writing files."));
+        return "failed";
+    }
+    return "ok";
+}
+function printProviderSetupPlan(plan) {
+    for (const action of plan.actions) {
+        process.stdout.write(`  ${action.label}: ${providerSetupActionCommandLine(action)} ${ui.style.dim(`(cwd: ${action.cwd})`)}\n`);
     }
-    const recipe = findRecipe(args.recipe);
-    if (recipe === undefined) {
-        process.stderr.write(ui.errorLine(`Unknown recipe \`${args.recipe}\`.`));
-        process.stderr.write(ui.hint("Run `mono-agent recipes list` to see available recipes."));
-        return "unknown";
+}
+/**
+ * Resolve the preset id for `init`: `--preset` wins, `--recipe` is a deprecated
+ * alias mapped to the preset that replaced it. Returns the preset id to compose
+ * from, `undefined` for the default scaffold, or `"unknown"` after emitting the
+ * error/hint (an unknown preset, or a retired recipe with no replacement).
+ */
+function resolveInitPresetId(args) {
+    if (args.preset !== undefined) {
+        const preset = findPreset(args.preset);
+        if (preset === undefined) {
+            process.stderr.write(ui.errorLine(`Unknown preset \`${args.preset}\`.`));
+            process.stderr.write(ui.hint(`Available presets: ${presetIds().join(", ")}. Run \`mono-agent presets list\`.`));
+            return "unknown";
+        }
+        return preset.id;
     }
-    return recipe;
+    if (args.recipe !== undefined) {
+        const preset = RECIPE_TO_PRESET.get(args.recipe);
+        if (preset === undefined) {
+            process.stderr.write(ui.errorLine(`Recipe \`${args.recipe}\` was retired; the wizard composes capabilities directly.`));
+            process.stderr.write(ui.hint(`Use \`mono-agent init --preset <id>\` (${presetIds().join(", ")}), or \`mono-agent init\` for the step-by-step wizard.`));
+            process.stderr.write(ui.hint("See the mono-agent-composer skill and docs/playbooks for capability recipes."));
+            return "unknown";
+        }
+        process.stderr.write(ui.hint(`--recipe is deprecated; using preset ${preset.id}. See \`mono-agent presets list\`.`));
+        return preset.id;
+    }
+    return undefined;
 }
 function resolveWithChannels(args) {
     if (args.withChannels === undefined) {
@@ -723,7 +813,7 @@ function resolveWithChannels(args) {
     }
     return args.withChannels.filter(isWithChannel);
 }
-function printInitResult(result, recipe) {
+function printInitResult(result) {
     if (result.dryRun) {
         process.stdout.write(ui.style.dim("Dry run — nothing was written.\n"));
     }
@@ -737,31 +827,35 @@ function printInitResult(result, recipe) {
     if (result.knowledgeFiles.length > 0) {
         process.stdout.write(`\nIdentity references existing knowledge: ${ui.style.cyan(result.knowledgeFiles.join(", "))}\n`);
     }
-    if (recipe !== undefined) {
-        process.stdout.write(`\n${ui.style.bold("Recipe:")} ${ui.style.cyan(recipe.id)} ${ui.style.dim(`(risk: ${recipe.riskLevel})`)}\n`);
-        if (recipe.envExample !== undefined) {
-            process.stdout.write(ui.style.dim("Fill the secret placeholders in .env.example, then copy it to .env.\n"));
+    // Internal `provider:*` modules are auto-added for local models; they are an
+    // implementation detail, not a user-facing capability, so exclude them here.
+    const capabilities = result.plan.selectedModules.filter((module) => module.kind !== "provider");
+    if (capabilities.length > 0) {
+        process.stdout.write("\n" + ui.heading("Capabilities"));
+        for (const module of capabilities) {
+            process.stdout.write(`  ${ui.style.cyan(module.title)} ${ui.style.dim(`(risk: ${riskColor(module.riskLevel)})`)}\n`);
         }
     }
+    if (result.plan.envExample !== undefined) {
+        process.stdout.write("\n" + ui.style.dim("Fill the secret placeholders in .env.example, then copy it to .env.\n"));
+    }
 }
 function printSecretsChecklist(secrets) {
     process.stdout.write("\n" + ui.heading("Secrets checklist"));
     if (secrets.length === 0) {
-        process.stdout.write(ui.style.dim("No secret recipe inputs were prompted. Review .env.example if the recipe created one.\n"));
+        process.stdout.write(ui.style.dim("No secrets required by the selected capabilities.\n"));
         return;
     }
-    process.stdout.write(ui.style.dim("Copy .env.example to .env, then fill these variables. Secret values were not prompted or written to JSON.\n"));
+    process.stdout.write(ui.style.dim("Copy .env.example to .env, then fill these variables. Secret values are never written to JSON.\n"));
     for (const secret of secrets) {
-        const key = secret.envVar ?? secret.id;
-        process.stdout.write(`  ${ui.style.bold(key)} ${ui.style.dim(`- ${secret.label}: ${secret.description}`)}\n`);
+        process.stdout.write(`  ${ui.style.bold(secret.envVar)} ${ui.style.dim(`- ${secret.label}: ${secret.description}`)}\n`);
     }
 }
-function printNextSteps(configPath, recipe) {
-    const validateCmd = recipe === undefined ? "mono-agent validate" : `mono-agent validate --recipe ${recipe.id}`;
+function printNextSteps(configPath) {
     process.stdout.write("\n" +
         ui.heading("Next steps") +
         `  ${ui.style.bold("1.")} Edit ${configPath} ${ui.style.dim("(model, channels, skills, memory, sandbox)")}\n` +
-        `  ${ui.style.bold("2.")} ${validateCmd}\n` +
+        `  ${ui.style.bold("2.")} mono-agent validate\n` +
         `  ${ui.style.bold("3.")} mono-agent start\n`);
 }
 async function runInstallSkill(args) {
@@ -792,14 +886,16 @@ async function runValidate(args) {
     for (const section of report.sections) {
         process.stdout.write(formatSection(section));
     }
-    if (args.recipe !== undefined) {
-        const recipe = findRecipe(args.recipe);
-        if (recipe === undefined) {
-            process.stderr.write(ui.errorLine(`Unknown recipe \`${args.recipe}\`.`));
-            process.stderr.write(ui.hint("Run `mono-agent recipes list` to see available recipes."));
-            return 1;
-        }
-        process.stdout.write(renderRecipeCompleteness(recipe, report));
+    const preset = resolveValidatePreset(args);
+    if (preset === "unknown") {
+        return 1;
+    }
+    if (preset !== undefined) {
+        const plan = composeWizardPlan(presetAnswers(preset), {
+            dirBasename: basename(context.cwd),
+            skillsRootExists: false,
+        });
+        process.stdout.write(renderPlanCompleteness(plan.validateExpectations, `Preset: ${preset.id}`, report));
     }
     process.stdout.write(report.ok
         ? `\n${ui.style.green("✓ Config is ready to start.")}\n${ui.style.dim("Run `mono-agent config` for the full field-by-field view.")}\n`
@@ -808,15 +904,42 @@ async function runValidate(args) {
     return report.ok ? 0 : 1;
 }
 /**
- * Capability-aware recipe check: for each capability the recipe promises, report
- * whether the matching doctor section has reached the expected status. `waiting`
- * stays non-fatal (it never changes the validate exit code) but is surfaced as
- * "selected recipe incomplete" so the operator knows what is left to wire up.
+ * Resolve the preset to check `validate` against: `--preset` wins, `--recipe` is a
+ * deprecated alias. Returns the preset, `undefined` (no capability check), or
+ * `"unknown"` after emitting the error/hint.
+ */
+function resolveValidatePreset(args) {
+    if (args.preset !== undefined) {
+        const preset = findPreset(args.preset);
+        if (preset === undefined) {
+            process.stderr.write(ui.errorLine(`Unknown preset \`${args.preset}\`.`));
+            process.stderr.write(ui.hint(`Available presets: ${presetIds().join(", ")}. Run \`mono-agent presets list\`.`));
+            return "unknown";
+        }
+        return preset;
+    }
+    if (args.recipe !== undefined) {
+        const preset = RECIPE_TO_PRESET.get(args.recipe);
+        if (preset === undefined) {
+            process.stderr.write(ui.errorLine(`Recipe \`${args.recipe}\` was retired; validate against a preset instead.`));
+            process.stderr.write(ui.hint(`Available presets: ${presetIds().join(", ")}. Run \`mono-agent presets list\`.`));
+            return "unknown";
+        }
+        process.stderr.write(ui.hint(`--recipe is deprecated; using preset ${preset.id}. See \`mono-agent presets list\`.`));
+        return preset;
+    }
+    return undefined;
+}
+/**
+ * Capability-aware completeness check: for each capability a preset (or module
+ * set) promises, report whether the matching doctor section reached the expected
+ * status. `waiting` stays non-fatal (it never changes the validate exit code) but
+ * is surfaced as "incomplete" so the operator knows what is left to wire up.
  */
-function renderRecipeCompleteness(recipe, report) {
-    let out = "\n" + ui.heading(`Recipe: ${recipe.id}`);
+function renderPlanCompleteness(expectations, label, report) {
+    let out = "\n" + ui.heading(label);
     let incomplete = 0;
-    for (const expectation of recipe.validateExpectations) {
+    for (const expectation of expectations) {
         const section = report.sections.find((entry) => entry.id === expectation.sectionId);
         const status = section?.status ?? "missing";
         const met = status === expectation.mustBe;
@@ -830,8 +953,8 @@ function renderRecipeCompleteness(recipe, report) {
         }
     }
     out += incomplete === 0
-        ? `${ui.style.green(`✓ Recipe ${recipe.id} is fully configured.`)}\n`
-        : ui.style.yellow(`⚠ Selected recipe incomplete: ${incomplete} capability(ies) not yet live.\n`);
+        ? `${ui.style.green(`✓ ${label} is fully configured.`)}\n`
+        : ui.style.yellow(`⚠ ${label} incomplete: ${incomplete} capability(ies) not yet live.\n`);
     return out;
 }
 function riskColor(risk) {
@@ -843,72 +966,72 @@ function riskColor(risk) {
     }
     return ui.style.green(risk);
 }
-/** `mono-agent recipes list` — one line per recipe. */
-export function renderRecipeList() {
-    let out = ui.banner("mono-agent", "recipes") + "\n";
-    for (const recipe of RECIPE_CATALOG) {
-        out += `${ui.style.bold(ui.style.cyan(recipe.id))} ${ui.style.dim(`[${riskColor(recipe.riskLevel)}]`)}\n`;
-        out += `    ${recipe.title}\n`;
-        out += `    ${ui.style.dim(recipe.tags.join(", "))}\n`;
-    }
-    out += "\n" + ui.style.dim("Scaffold one with: mono-agent init --recipe <id> [--dry-run] [--with slack,cron]\n");
+/** `mono-agent presets list` — one block per preset. */
+export function renderPresetList() {
+    let out = ui.banner("mono-agent", "presets") + "\n";
+    for (const preset of PRESET_CATALOG) {
+        out += `${ui.style.bold(ui.style.cyan(preset.id))} ${ui.style.dim(`[${riskColor(preset.riskLevel)}]`)}\n`;
+        out += `    ${preset.title}\n`;
+        out += `    ${ui.style.dim(preset.description)}\n`;
+    }
+    out += "\n" + ui.style.dim("Scaffold one with: mono-agent init --preset <id>\n");
+    out += ui.style.dim("Build interactively with: mono-agent init\n");
     return out;
 }
-/** `mono-agent recipes show <id>` — description, generated JSON, env example, checklist. */
-export function renderRecipeShow(recipe) {
-    const inputs = resolveRecipeInputs(recipe);
-    let out = ui.banner("mono-agent", `recipe: ${recipe.id}`) + "\n";
-    out += `${ui.style.bold(recipe.title)} ${ui.style.dim(`(risk: ${riskColor(recipe.riskLevel)})`)}\n`;
-    out += `${recipe.description}\n`;
-    if (recipe.playbook !== undefined) {
-        out += ui.style.dim(`Playbook: docs/playbooks/${recipe.playbook}\n`);
+/** `mono-agent presets show <id>` — description, composed JSON, env example, checklist. */
+export function renderPresetShow(preset) {
+    const plan = composeWizardPlan(presetAnswers(preset), { dirBasename: "your-agent", skillsRootExists: false });
+    let out = ui.banner("mono-agent", `preset: ${preset.id}`) + "\n";
+    out += `${ui.style.bold(preset.title)} ${ui.style.dim(`(risk: ${riskColor(preset.riskLevel)})`)}\n`;
+    out += `${preset.description}\n`;
+    if (preset.playbook !== undefined) {
+        out += ui.style.dim(`Playbook: docs/playbooks/${preset.playbook}\n`);
     }
     out += "\n" + ui.heading("Generated mono-agent.config.json");
-    out += JSON.stringify(recipe.config(inputs), null, 2) + "\n";
-    const envExample = recipe.envExample?.(inputs);
+    out += JSON.stringify(plan.configJson, null, 2) + "\n";
+    const envExample = plan.envExample;
     if (envExample !== undefined && envExample.trim().length > 0) {
         out += "\n" + ui.heading(".env.example");
         out += envExample.endsWith("\n") ? envExample : envExample + "\n";
     }
-    const files = recipe.files?.(inputs) ?? [];
-    if (files.length > 0) {
+    if (plan.files.length > 0) {
         out += "\n" + ui.heading("Scaffolded files");
-        for (const file of files) {
+        for (const file of plan.files) {
             out += `  ${ui.style.cyan(file.path)}\n`;
         }
     }
-    if (recipe.validateExpectations.length > 0) {
+    if (plan.validateExpectations.length > 0) {
         out += "\n" + ui.heading("Follow-up checklist");
-        for (const expectation of recipe.validateExpectations) {
+        for (const expectation of plan.validateExpectations) {
             const note = expectation.note === undefined ? "" : ` — ${expectation.note}`;
             out += `  ${ui.style.gray("•")} ${expectation.sectionId} ${ui.style.dim(`must be ${expectation.mustBe}`)}${ui.style.dim(note)}\n`;
         }
     }
     return out;
 }
-/** Dispatch `mono-agent recipes list|show <id>`. */
-function runRecipes(args) {
+/** Dispatch `mono-agent presets list|show <id>`. */
+function runPresets(args) {
     const [sub, id] = args.positionals;
     if (sub === undefined || sub === "list") {
-        process.stdout.write(renderRecipeList());
+        process.stdout.write(renderPresetList());
         return 0;
     }
     if (sub === "show") {
         if (id === undefined) {
-            process.stderr.write(ui.errorLine("Usage: mono-agent recipes show <id>."));
-            process.stderr.write(ui.hint(`Available: ${recipeIds().join(", ")}.`));
+            process.stderr.write(ui.errorLine("Usage: mono-agent presets show <id>."));
+            process.stderr.write(ui.hint(`Available: ${presetIds().join(", ")}.`));
             return 2;
         }
-        const recipe = findRecipe(id);
-        if (recipe === undefined) {
-            process.stderr.write(ui.errorLine(`Unknown recipe \`${id}\`.`));
-            process.stderr.write(ui.hint("Run `mono-agent recipes list` to see available recipes."));
+        const preset = findPreset(id);
+        if (preset === undefined) {
+            process.stderr.write(ui.errorLine(`Unknown preset \`${id}\`.`));
+            process.stderr.write(ui.hint(`Available: ${presetIds().join(", ")}. Run \`mono-agent presets list\`.`));
             return 1;
         }
-        process.stdout.write(renderRecipeShow(recipe));
+        process.stdout.write(renderPresetShow(preset));
         return 0;
     }
-    process.stderr.write(ui.errorLine(`Unknown recipes subcommand \`${sub}\`. Expected list or show.`));
+    process.stderr.write(ui.errorLine(`Unknown presets subcommand \`${sub}\`. Expected list or show.`));
     return 2;
 }
 const SOURCE_TAG = {