@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/commands/packages.js

@@ -14,10 +14,13 @@ import { cloneRepo } from '../lib/git.js';
 import { discoverCommands, resolveCommandSource, installCommand, installCommandCentrally, } from '../lib/commands.js';
 import { discoverSkillsFromRepo, installSkill, installSkillCentrally, } from '../lib/skills.js';
 import { discoverHooksFromRepo, installHooks, installHooksCentrally, } from '../lib/hooks.js';
-import { listInstalledVersions, resolveInstalledAgentTargets, resolveConfiguredAgentTargets, syncResourcesToVersion, } from '../lib/versions.js';
-import { isInteractiveTerminal, isPromptCancelled, requireDestructiveArg, requireInteractiveSelection, } from './utils.js';
+import { discoverWorkflowsFromRepo, installWorkflowCentrally, } from '../lib/workflows.js';
+import { discoverSubagentsFromRepo, installSubagentCentrally, } from '../lib/subagents.js';
+import { discoverPermissionsFromRepo, installPermissionSet, } from '../lib/permissions.js';
+import { listInstalledVersions, resolveConfiguredAgentTargets, syncResourcesToVersion, } from '../lib/versions.js';
+import { isInteractiveTerminal, isPromptCancelled, parseCommaSeparatedList, requireDestructiveArg, requireInteractiveSelection, resolveInstalledAgentTargetsAutoInstalling, } from './utils.js';
 import { itemPicker } from '../lib/picker.js';
-import { registerMcpCommandToTargets } from '../lib/mcp.js';
+import { registerMcpCommandToTargets, discoverMcpConfigsFromRepo, installMcpConfigCentrally, } from '../lib/mcp.js';
 export function buildMcpPackageCommand(pkg) {
     const packageName = pkg.name || pkg.registry_name;
     if (pkg.runtime === 'node') {
@@ -326,6 +329,9 @@ When to use:
         .command('install <identifier>')
         .description('Install a package by registry name (mcp:notion), GitHub URL (gh:user/repo), or skill identifier')
         .option('-a, --agents <list>', 'Targets: claude, codex@0.116.0, or gemini@default')
+        .option('--types <list>', 'When source is a repo: comma-separated resource types to install (skills,workflows,commands,hooks,permissions,subagents,mcp)')
+        .option('--names <list>', 'When source is a repo: comma-separated resource names within the selected types')
+        .option('-y, --yes', 'Auto-install any missing agent versions without prompting')
         .addHelpText('after', `
 Install resolves the package type (MCP server, skill, command, hook) and installs to the specified agents. Packages can come from registries (mcp:, skill:), GitHub (gh:user/repo), or direct URLs.
 
@@ -339,6 +345,12 @@ Examples:
   # Install using GitHub shorthand
   agents install gh:user/repo --agents claude@2.1.112
 
+  # Install only specific resource types from a multi-resource repo
+  agents install gh:phnx-labs/.agents-system --types skills,workflows --agents claude@all
+
+  # Install specific resources by name
+  agents install gh:phnx-labs/.agents-system --types skills --names animator,composer --agents claude@all
+
   # Install to all installed agents (uses defaults or prompts)
   agents install mcp:postgres
 
@@ -399,9 +411,18 @@ When to use:
                 }
                 const cliStates = await getAllCliStates();
                 const installedAgents = MCP_CAPABLE_AGENTS.filter((id) => cliStates[id]?.installed || listInstalledVersions(id).length > 0);
-                const targets = options.agents
-                    ? resolveInstalledAgentTargets(options.agents, MCP_CAPABLE_AGENTS)
-                    : resolveConfiguredAgentTargets(installedAgents, undefined, MCP_CAPABLE_AGENTS);
+                let targets;
+                if (options.agents) {
+                    const resolved = await resolveInstalledAgentTargetsAutoInstalling(options.agents, MCP_CAPABLE_AGENTS, { yes: options.yes });
+                    if (!resolved) {
+                        console.log(chalk.gray('Cancelled.'));
+                        return;
+                    }
+                    targets = resolved;
+                }
+                else {
+                    targets = resolveConfiguredAgentTargets(installedAgents, undefined, MCP_CAPABLE_AGENTS);
+                }
                 if (targets.selectedAgents.length === 0) {
                     console.log(chalk.yellow('\nNo MCP-capable agents installed.'));
                     process.exit(1);
@@ -420,38 +441,95 @@ When to use:
                 console.log(chalk.green('\nMCP server installed.'));
             }
             else if (resolved.type === 'git' || resolved.type === 'skill') {
-                // Install from git source (skills/commands/hooks)
+                // Install from git source: sniff every resource type the repo
+                // contains. Optional --types narrows which kinds get installed;
+                // --names narrows which specific resources within those kinds.
                 console.log(chalk.bold(`\nInstalling from ${resolved.source}`));
                 const { localPath } = await cloneRepo(resolved.source);
-                // Discover what's in the repo
-                const commands = discoverCommands(localPath);
-                const skills = discoverSkillsFromRepo(localPath);
-                const hooks = discoverHooksFromRepo(localPath);
-                const hasCommands = commands.length > 0;
-                const hasSkills = skills.length > 0;
-                const hasHooks = hooks.length > 0;
-                if (!hasCommands && !hasSkills && !hasHooks) {
+                const requestedTypes = new Set(parseCommaSeparatedList(options.types));
+                const includeType = (type) => requestedTypes.size === 0 || requestedTypes.has(type);
+                const requestedNames = new Set(parseCommaSeparatedList(options.names));
+                const nameFilter = (items) => {
+                    if (requestedNames.size === 0)
+                        return items;
+                    return items.filter((item) => requestedNames.has(item.name));
+                };
+                // Discover everything; filter to requested types up front so the
+                // summary table reflects what will actually be installed.
+                let commands = includeType('commands') ? discoverCommands(localPath) : [];
+                let skills = includeType('skills') ? discoverSkillsFromRepo(localPath) : [];
+                let hooks = includeType('hooks') ? discoverHooksFromRepo(localPath) : [];
+                let workflows = includeType('workflows') ? discoverWorkflowsFromRepo(localPath) : [];
+                let subagents = includeType('subagents') ? discoverSubagentsFromRepo(localPath) : [];
+                let permissions = includeType('permissions') ? discoverPermissionsFromRepo(localPath) : [];
+                let mcpServers = includeType('mcp') ? discoverMcpConfigsFromRepo(localPath) : [];
+                // --names filter applies across every discovered type. If the user
+                // typed a name that matched nothing, fail loud so they can fix the
+                // typo rather than silently install zero items.
+                if (requestedNames.size > 0) {
+                    const allNames = new Set([
+                        ...commands.map((c) => c.name),
+                        ...skills.map((s) => s.name),
+                        ...hooks,
+                        ...workflows.map((w) => w.name),
+                        ...subagents.map((s) => s.name),
+                        ...permissions.map((p) => p.name),
+                        ...mcpServers.map((s) => s.name),
+                    ]);
+                    const missing = [...requestedNames].filter((n) => !allNames.has(n));
+                    if (missing.length > 0) {
+                        console.log(chalk.red(`\nResource(s) not found in repo: ${missing.join(', ')}`));
+                        console.log(chalk.gray(`Available: ${[...allNames].sort().join(', ')}`));
+                        process.exit(1);
+                    }
+                    commands = nameFilter(commands);
+                    skills = nameFilter(skills);
+                    hooks = hooks.filter((h) => requestedNames.has(h));
+                    workflows = nameFilter(workflows);
+                    subagents = nameFilter(subagents);
+                    permissions = nameFilter(permissions);
+                    mcpServers = nameFilter(mcpServers);
+                }
+                const summary = [
+                    { kind: 'commands', count: commands.length },
+                    { kind: 'skills', count: skills.length },
+                    { kind: 'hooks', count: hooks.length },
+                    { kind: 'workflows', count: workflows.length },
+                    { kind: 'subagents', count: subagents.length },
+                    { kind: 'permissions', count: permissions.length },
+                    { kind: 'mcp', count: mcpServers.length },
+                ].filter((s) => s.count > 0);
+                if (summary.length === 0) {
                     console.log(chalk.yellow('No installable content found in repository.'));
+                    if (requestedTypes.size > 0 || requestedNames.size > 0) {
+                        console.log(chalk.gray('Try removing --types/--names to see everything the repo offers.'));
+                    }
                     process.exit(1);
                 }
                 console.log(chalk.bold('\nFound:'));
-                if (hasCommands)
-                    console.log(`  ${commands.length} commands`);
-                if (hasSkills)
-                    console.log(`  ${skills.length} skills`);
-                if (hasHooks)
-                    console.log(`  ${hooks.length} hooks`);
+                for (const { kind, count } of summary) {
+                    console.log(`  ${count} ${kind}`);
+                }
                 const gitCliStates = await getAllCliStates();
                 const installedAgents = ALL_AGENT_IDS.filter((id) => gitCliStates[id]?.installed || listInstalledVersions(id).length > 0);
-                const targets = options.agents
-                    ? resolveInstalledAgentTargets(options.agents, ALL_AGENT_IDS)
-                    : resolveConfiguredAgentTargets(installedAgents, undefined, ALL_AGENT_IDS);
+                let targets;
+                if (options.agents) {
+                    const resolved = await resolveInstalledAgentTargetsAutoInstalling(options.agents, ALL_AGENT_IDS, { yes: options.yes });
+                    if (!resolved) {
+                        console.log(chalk.gray('Cancelled.'));
+                        return;
+                    }
+                    targets = resolved;
+                }
+                else {
+                    targets = resolveConfiguredAgentTargets(installedAgents, undefined, ALL_AGENT_IDS);
+                }
                 if (targets.selectedAgents.length === 0) {
                     console.log(chalk.yellow('\nNo agents selected.'));
                     return;
                 }
                 // Install commands
-                if (hasCommands) {
+                if (commands.length > 0) {
                     console.log(chalk.bold('\nInstalling commands...'));
                     let directInstalled = 0;
                     let syncedVersions = 0;
@@ -495,7 +573,7 @@ When to use:
                     }
                 }
                 // Install skills
-                if (hasSkills) {
+                if (skills.length > 0) {
                     console.log(chalk.bold('\nInstalling skills...'));
                     const directAgents = targets.directAgents.filter((agentId) => AGENTS[agentId].capabilities.skills && gitCliStates[agentId]?.installed);
                     let syncedVersions = 0;
@@ -522,7 +600,7 @@ When to use:
                     console.log(`  Synced skills to ${syncedVersions} managed version(s)`);
                 }
                 // Install hooks
-                if (hasHooks) {
+                if (hooks.length > 0) {
                     console.log(chalk.bold('\nInstalling hooks...'));
                     let syncedVersions = 0;
                     const directHookAgents = targets.directAgents.filter((id) => AGENTS[id].supportsHooks && gitCliStates[id]?.installed);
@@ -543,6 +621,97 @@ When to use:
                     }
                     console.log(`  Synced hooks to ${syncedVersions} managed version(s)`);
                 }
+                // Install workflows
+                if (workflows.length > 0) {
+                    console.log(chalk.bold('\nInstalling workflows...'));
+                    let installed = 0;
+                    for (const w of workflows) {
+                        const result = installWorkflowCentrally(w.path, w.name);
+                        if (result.success) {
+                            installed++;
+                        }
+                        else {
+                            console.log(`  ${chalk.red('x')} ${w.name}: ${result.error}`);
+                        }
+                    }
+                    const workflowNames = workflows.map((w) => w.name);
+                    let syncedVersions = 0;
+                    for (const [agentId, versions] of targets.versionSelections) {
+                        for (const version of versions) {
+                            const result = syncResourcesToVersion(agentId, version, { workflows: workflowNames });
+                            if (result.workflows.length > 0)
+                                syncedVersions++;
+                        }
+                    }
+                    console.log(`  Installed ${installed} workflow(s) to ~/.agents/workflows/`);
+                    console.log(`  Synced workflows to ${syncedVersions} managed version(s)`);
+                }
+                // Install subagents
+                if (subagents.length > 0) {
+                    console.log(chalk.bold('\nInstalling subagents...'));
+                    let installed = 0;
+                    for (const s of subagents) {
+                        const result = installSubagentCentrally(s.path, s.name);
+                        if (result.success) {
+                            installed++;
+                        }
+                        else {
+                            console.log(`  ${chalk.red('x')} ${s.name}: ${result.error}`);
+                        }
+                    }
+                    const subagentNames = subagents.map((s) => s.name);
+                    let syncedVersions = 0;
+                    for (const [agentId, versions] of targets.versionSelections) {
+                        for (const version of versions) {
+                            const result = syncResourcesToVersion(agentId, version, { subagents: subagentNames });
+                            if (result.subagents.length > 0)
+                                syncedVersions++;
+                        }
+                    }
+                    console.log(`  Installed ${installed} subagent(s) to ~/.agents/subagents/`);
+                    console.log(`  Synced subagents to ${syncedVersions} managed version(s)`);
+                }
+                // Install permissions
+                if (permissions.length > 0) {
+                    console.log(chalk.bold('\nInstalling permission sets...'));
+                    let installed = 0;
+                    for (const p of permissions) {
+                        const result = installPermissionSet(p.path, p.name);
+                        if (result.success) {
+                            installed++;
+                        }
+                        else {
+                            console.log(`  ${chalk.red('x')} ${p.name}: ${result.error}`);
+                        }
+                    }
+                    console.log(`  Installed ${installed} permission set(s) to ~/.agents/permissions/`);
+                    console.log(chalk.gray('  Apply with: agents permissions apply <name> --agents <selector>'));
+                }
+                // Install MCP server configs
+                if (mcpServers.length > 0) {
+                    console.log(chalk.bold('\nInstalling MCP server configs...'));
+                    let installed = 0;
+                    for (const s of mcpServers) {
+                        const result = installMcpConfigCentrally(s.path);
+                        if (result.success) {
+                            installed++;
+                        }
+                        else {
+                            console.log(`  ${chalk.red('x')} ${s.name}: ${result.error}`);
+                        }
+                    }
+                    const mcpNames = mcpServers.map((s) => s.name);
+                    let syncedVersions = 0;
+                    for (const [agentId, versions] of targets.versionSelections) {
+                        for (const version of versions) {
+                            const result = syncResourcesToVersion(agentId, version, { mcp: mcpNames });
+                            if (result.mcp.length > 0)
+                                syncedVersions++;
+                        }
+                    }
+                    console.log(`  Installed ${installed} MCP config(s) to ~/.agents/mcp/`);
+                    console.log(`  Synced MCP configs to ${syncedVersions} managed version(s)`);
+                }
                 console.log(chalk.green('\nPackage installed.'));
             }
         }

package/dist/commands/permissions.js

@@ -7,9 +7,9 @@ import { confirm, checkbox } from '@inquirer/prompts';
 import { AGENTS, resolveAgentName, formatAgentError, agentLabel, } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
 import { PERMISSIONS_CAPABLE_AGENTS, listInstalledPermissions, discoverPermissionsFromRepo, installPermissionSet, removePermissionSet, applyPermissionsToVersion, readAgentPermissions, exportPermissionsFromPath, getDefaultPermissionSet, computePermissionsDiff, mergePermissionSets, saveDefaultPermissionSet, containsBroadGrants, } from '../lib/permissions.js';
-import { listInstalledVersions, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, resolveAgentVersionTargets, resolveVersionAlias, } from '../lib/versions.js';
+import { listInstalledVersions, getGlobalDefault, getVersionHomePath, promptAgentVersionSelection, resolveVersionAlias, } from '../lib/versions.js';
 import { recordVersionResources } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, resolveAgentTargetsAutoInstalling, } from './utils.js';
 export function shouldRefuseBroadPermissions(permissions, allowBroadPermissions) {
     return !allowBroadPermissions && permissions.some((perm) => containsBroadGrants(perm.set) !== null);
 }
@@ -279,9 +279,14 @@ Examples:
                 let selectedAgents;
                 let versionSelections;
                 if (options.agents) {
-                    const result = resolveAgentVersionTargets(options.agents, PERMISSIONS_CAPABLE_AGENTS, {
+                    const result = await resolveAgentTargetsAutoInstalling(options.agents, PERMISSIONS_CAPABLE_AGENTS, {
+                        yes: options.yes,
                         allVersions: options.all,
                     });
+                    if (!result) {
+                        console.log(chalk.gray('Cancelled.'));
+                        return;
+                    }
                     selectedAgents = result.selectedAgents;
                     versionSelections = result.versionSelections;
                 }
@@ -296,7 +301,7 @@ Examples:
                     }
                 }
                 else {
-                    const result = await promptAgentVersionSelection(PERMISSIONS_CAPABLE_AGENTS, { skipPrompts });
+                    const result = await promptAgentVersionSelection(PERMISSIONS_CAPABLE_AGENTS, { skipPrompts: options.yes });
                     selectedAgents = result.selectedAgents;
                     versionSelections = result.versionSelections;
                 }
@@ -412,9 +417,14 @@ Examples:
                 let selectedAgents;
                 let versionSelections;
                 if (options.agents) {
-                    const result = resolveAgentVersionTargets(options.agents, PERMISSIONS_CAPABLE_AGENTS, {
+                    const result = await resolveAgentTargetsAutoInstalling(options.agents, PERMISSIONS_CAPABLE_AGENTS, {
+                        yes: options.yes,
                         allVersions: options.all,
                     });
+                    if (!result) {
+                        console.log(chalk.gray('Cancelled.'));
+                        return;
+                    }
                     selectedAgents = result.selectedAgents;
                     versionSelections = result.versionSelections;
                 }
@@ -537,9 +547,14 @@ Examples:
                 let selectedAgents;
                 let versionSelections;
                 if (options.agents) {
-                    const result = resolveAgentVersionTargets(options.agents, PERMISSIONS_CAPABLE_AGENTS, {
+                    const result = await resolveAgentTargetsAutoInstalling(options.agents, PERMISSIONS_CAPABLE_AGENTS, {
+                        yes: options.yes,
                         allVersions: options.all,
                     });
+                    if (!result) {
+                        console.log(chalk.gray('Cancelled.'));
+                        return;
+                    }
                     selectedAgents = result.selectedAgents;
                     versionSelections = result.versionSelections;
                 }

package/dist/commands/plugins.js

@@ -237,6 +237,7 @@ Examples:
     pluginsCmd
         .command('sync <name> [agent]')
         .description('Apply a plugin to the default version of an agent (or all supported agents if none specified)')
+        .option('--allow-exec-surfaces', 'Enable the plugin even when it ships hooks/, .mcp.json, bin/, scripts/, settings.json, or permissions/')
         .addHelpText('after', `
 Examples:
   # Sync a plugin to a specific agent (default version)
@@ -244,8 +245,11 @@ Examples:
 
   # Sync to all supported agents
   agents plugins sync rush-toolkit
+
+  # Re-affirm consent for a hooks-bearing plugin
+  agents plugins sync hivemind claude --allow-exec-surfaces
 `)
-        .action(async (name, agentArg) => {
+        .action(async (name, agentArg, options) => {
         const plugin = getPlugin(name);
         if (!plugin) {
             console.log(chalk.red(`Plugin '${name}' not found`));
@@ -268,6 +272,7 @@ Examples:
         else {
             targetAgents = PLUGINS_CAPABLE_AGENTS.filter(a => pluginSupportsAgent(plugin, a));
         }
+        const allowExec = options.allowExecSurfaces === true;
         for (const agentId of targetAgents) {
             const versions = listInstalledVersions(agentId);
             if (versions.length === 0)
@@ -275,9 +280,11 @@ Examples:
             const defaultVer = getGlobalDefault(agentId);
             const targetVersions = defaultVer ? [defaultVer] : [versions[versions.length - 1]];
             for (const version of targetVersions) {
-                const syncResult = syncResourcesToVersion(agentId, version, { plugins: [name] });
-                if (syncResult.plugins.length > 0) {
-                    console.log(chalk.green(`Synced ${name} to ${agentLabel(agentId)}@${version}`));
+                const didSync = allowExec
+                    ? syncPluginToVersion(plugin, agentId, getVersionHomePath(agentId, version), { allowExecSurfaces: true, version }).success
+                    : syncResourcesToVersion(agentId, version, { plugins: [name] }).plugins.length > 0;
+                if (didSync) {
+                    console.log(chalk.green(`Synced ${name} to ${agentLabel(agentId)}@${version}${allowExec ? ' (exec surfaces enabled)' : ''}`));
                 }
                 else {
                     console.log(chalk.gray(`${name} already synced to ${agentLabel(agentId)}@${version}`));

package/dist/commands/profiles.d.ts

@@ -7,5 +7,13 @@
  * through a standard agent CLI with no local proxy.
  */
 import type { Command } from 'commander';
+import { type Profile } from '../lib/profiles.js';
+import { type Preset } from '../lib/profiles-presets.js';
+/**
+ * Pure helper: builds a Profile from collected wizard inputs. Extracted so the
+ * shape of preset->profile mapping for the `create` wizard is unit-testable
+ * without mocking @inquirer/prompts.
+ */
+export declare function buildProfileFromCollection(name: string, preset: Preset, collected: Record<string, string>, version?: string): Profile;
 /** Register the `agents profiles` command tree. */
 export declare function registerProfilesCommands(program: Command): void;

package/dist/commands/profiles.js

@@ -8,10 +8,30 @@
  */
 import chalk from 'chalk';
 import * as fs from 'fs';
-import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileFromPreset, getPresetForProfile, } from '../lib/profiles.js';
-import { getPreset, listPresets } from '../lib/profiles-presets.js';
+import { spawn } from 'child_process';
+import { listProfiles, readProfile, writeProfile, deleteProfile, profileExists, profileFromPreset, validateProfileName, getPresetForProfile, } from '../lib/profiles.js';
+import { getPreset, listPresets, expandPreset } from '../lib/profiles-presets.js';
 import { hasKeychainToken, keychainItemName, setKeychainToken, deleteKeychainToken, } from '../lib/secrets/profiles.js';
 import { isInteractiveTerminal } from './utils.js';
+/**
+ * Pure helper: builds a Profile from collected wizard inputs. Extracted so the
+ * shape of preset->profile mapping for the `create` wizard is unit-testable
+ * without mocking @inquirer/prompts.
+ */
+export function buildProfileFromCollection(name, preset, collected, version) {
+    return {
+        name,
+        host: { agent: preset.host, version },
+        env: { ...preset.env, ...collected },
+        auth: {
+            envVar: preset.authEnvVar,
+            keychainItem: keychainItemName(preset.provider),
+        },
+        description: preset.description,
+        preset: preset.name,
+        provider: preset.provider,
+    };
+}
 /** Prompt the user for a secret value with masked input. Requires an interactive TTY. */
 async function promptForSecret(message) {
     if (!isInteractiveTerminal()) {
@@ -86,7 +106,8 @@ Built-in presets (via OpenRouter, one shared key):
 Run 'agents profiles presets' for the full list with pricing and context sizes.
 
 Typical flow:
-  agents profiles add kimi             # prompts for OpenRouter key, stored in Keychain
+  agents profiles create               # interactive wizard for any provider
+  agents profiles add kimi             # one-line preset (existing)
   agents run kimi "refactor this"      # Claude Code UI, Kimi model responses
   agents profiles add deepseek         # reuses OpenRouter key, no re-prompt
 
@@ -116,7 +137,7 @@ Examples:
 
   # Add MiniMax for SWE-bench style fixes; reuses the same OpenRouter key
   agents profiles add minimax
-  agents run minimax "investigate EXAMPLE-2317 and patch the off-by-one in pagination"
+  agents run minimax "investigate PROJ-456 and patch the off-by-one in pagination"
 
   # Add DeepSeek for cheap, fast non-reasoning work
   agents profiles add deepseek
@@ -202,6 +223,96 @@ Examples:
             process.exit(1);
         }
     });
+    cmd
+        .command('create')
+        .description('Interactive profile creation wizard (any provider, with prompts for endpoints + keys).')
+        .option('--name <name>', 'Profile name (skips the name prompt)')
+        .option('--provider <provider>', 'Provider preset name (skips the provider prompt)')
+        .option('--no-smoke-test', 'Skip the post-create smoke test prompt')
+        .action(async (opts) => {
+        if (!isInteractiveTerminal()) {
+            console.error(chalk.red('agents profiles create requires an interactive terminal. Use `agents profiles add <preset>` for scriptable creation.'));
+            process.exit(1);
+        }
+        const { input, select, confirm } = await import('@inquirer/prompts');
+        const name = opts.name
+            ? opts.name
+            : await input({
+                message: 'Profile name',
+                validate: (v) => /^[a-z0-9][a-z0-9-_]{0,48}$/i.test(v) || 'lowercase alphanumeric + -_ only, max 48 chars',
+            });
+        validateProfileName(name);
+        if (profileExists(name)) {
+            const overwrite = await confirm({
+                message: `Profile '${name}' already exists. Overwrite?`,
+                default: false,
+            });
+            if (!overwrite) {
+                console.log(chalk.gray('Cancelled.'));
+                return;
+            }
+        }
+        const presets = listPresets();
+        const providerName = opts.provider
+            ? opts.provider
+            : await select({
+                message: 'Provider',
+                choices: presets.map((p) => ({
+                    name: `${p.name.padEnd(18)} ${chalk.gray(p.description.slice(0, 70))}`,
+                    value: p.name,
+                })),
+            });
+        const preset = getPreset(providerName);
+        if (!preset) {
+            console.error(chalk.red(`Unknown provider '${providerName}'. Run 'agents profiles presets' for the list.`));
+            process.exit(1);
+        }
+        const expanded = expandPreset(preset);
+        const collected = {};
+        for (const v of expanded.prompts) {
+            if (v.secret) {
+                collected[v.envVar] = await promptForSecret(v.prompt);
+            }
+            else {
+                const value = await input({
+                    message: v.hint ? `${v.prompt}  ${chalk.gray('(' + v.hint + ')')}` : v.prompt,
+                    default: v.default,
+                    validate: v.pattern
+                        ? (val) => new RegExp(v.pattern).test(val) || `must match ${v.pattern}`
+                        : undefined,
+                });
+                collected[v.envVar] = value;
+            }
+        }
+        if (!preset.authOptional) {
+            await ensureProviderToken(preset.provider, preset.signupUrl);
+        }
+        const profile = buildProfileFromCollection(name, preset, collected);
+        writeProfile(profile);
+        console.log(chalk.green(`Profile '${name}' created.`));
+        if (preset.docPath) {
+            console.log(chalk.gray(`See docs/profiles/${preset.docPath}.md for provider-specific caveats.`));
+        }
+        if (opts.smokeTest !== false) {
+            const run = await confirm({ message: 'Run smoke test now?', default: true });
+            if (run) {
+                console.log(chalk.gray(`Spawning: agents run ${name} "say alive in one word" (60s timeout)`));
+                const child = spawn(process.argv[0], [
+                    process.argv[1],
+                    'run',
+                    name,
+                    'say alive in one word',
+                    '--headless',
+                    '--timeout',
+                    '60s',
+                ], { stdio: 'inherit' });
+                child.on('exit', (code) => process.exit(code ?? 0));
+            }
+            else {
+                console.log(chalk.gray(`Try later: agents run ${name} "hello"`));
+            }
+        }
+    });
     cmd
         .command('add <name>')
         .description('Add a profile. If <name> matches a built-in preset, the preset is applied. Prompts for API key (once per provider).')
@@ -223,7 +334,9 @@ Examples:
                 console.error(chalk.gray('Or pass --preset <name> to pick explicitly.'));
                 process.exit(1);
             }
-            await ensureProviderToken(preset.provider, preset.signupUrl, opts.keyStdin);
+            if (!preset.authOptional) {
+                await ensureProviderToken(preset.provider, preset.signupUrl, opts.keyStdin);
+            }
             const profile = profileFromPreset(name, preset, opts.version);
             writeProfile(profile);
             console.log(chalk.green(`Profile '${name}' added.`));