@antomanc/aginit 0.4.0 → 0.5.0

package/src/cli/main.ts

@@ -3,12 +3,15 @@ import { readFileSync } from 'node:fs';
 import { createProject } from './new.js';
 import { initCurrentDirectory } from './init.js';
 import { runDoctor } from './doctor.js';
-import { claudeCodeEnabled, ensureClaudeSkillLinks, updateSkills } from '../adapters/skills.js';
-import { setupClaudeMarkdown } from '../adapters/agents-md.js';
+import { ensureClaudeSkillLinks, updateSkills } from '../adapters/skills.js';
+import { ignoreVendoredSkills } from '../adapters/tool-ignores.js';
 import { buildGraft } from '../adapters/graft.js';
 import { readProjectConfig } from '../config/validation.js';
 import { logger } from '../utils/logger.js';
 import { PresetType, WebFramework, PackageManager } from '../config/schema.js';
+import { Platform, ProfileFlags, TestingChoice } from '../registry/index.js';
+import { changeCapabilities, listCapabilities } from './capabilities.js';
+import { syncAgentDocs } from './new.js';
 import {
   isInteractive,
   promptNewProject,
@@ -29,25 +32,85 @@ function readVersion(): string {
   }
 }
 
+const list = (value: string, previous: string[] = []) => [
+  ...previous,
+  ...value
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean)
+];
+
+/** v2 profile options shared by the root command, `new` and `init`. */
+function withProfileOptions(command: Command): Command {
+  return command
+    .option('--platform <platform>', 'Platform: auto | web | mobile-native | mobile-rn | backend | cli')
+    .option('--methodology <preset>', 'Workflow skills: pocock | superpowers | minimal')
+    .option('--design <design>', 'Design system: impeccable | none')
+    .option('--testing <engine>', 'Testing: e2e | playwright | vitest | native')
+    .option('--ui-driver <driver>', 'UI driver: auto | agent-browser | agent-device | none')
+    .option('--addons <ids>', 'Add-ons: context-mode, worktrunk, chrome-devtools-mcp, browserskill', list)
+    .option('--add-skill <owner/repo>', 'Add a skill repository as a custom capability (repeatable)', list)
+    .option('--without <id>', 'Disable a capability, e.g. graft or humanizer (repeatable)', list);
+}
+
+function profileFlags(options: any): ProfileFlags {
+  return {
+    platform: options.platform === 'auto' ? undefined : (options.platform as Platform | undefined),
+    methodology: options.methodology,
+    design: options.design,
+    testing: options.testing as TestingChoice | undefined,
+    uiDriver: options.uiDriver,
+    addons: options.addons,
+    addSkills: options.addSkill,
+    without: options.without
+  };
+}
+
 export function createCliProgram(): Command {
   const program = new Command();
 
   program
     .name('aginit')
     .description('Set up a new or existing project for AI coding agents')
-    .version(readVersion());
-
-  // Root action: interactive wizard when in TTY, else display help
-  program.action(async () => {
-    if (isInteractive()) {
-      await runInteractiveWizard();
-    } else {
-      program.outputHelp();
+    .version(readVersion())
+    .enablePositionalOptions()
+    .option('-p, --preset <preset>', 'Project preset: web | cli | generic')
+    .option('-f, --framework <framework>', 'Web framework: none | vite | next | existing')
+    .option('-m, --package-manager <pm>', 'Package manager: pnpm | npm | yarn | bun')
+    .option('--no-skills', 'Skip installing AI skills')
+    .option('--no-graft', 'Skip codebase graph (Graft) setup')
+    .option('--no-git', 'Skip git repository initialization')
+    .option('--dry-run', 'Simulate setup without writing changes to disk')
+    .option('-y, --yes', 'Initialize the current directory without prompts (saved or detected settings)');
+  withProfileOptions(program);
+
+  // Root action: `aginit [options]` initializes the current directory. Bare
+  // `aginit` opens the wizard in a TTY and prints help otherwise, so a stray
+  // invocation in CI never rewrites a project.
+  program.action(async (options: any, command: Command) => {
+    const explicit = command.options.some(
+      (option) => command.getOptionValueSource(option.attributeName()) === 'cli'
+    );
+    if (!explicit) {
+      if (isInteractive()) await runInteractiveWizard();
+      else program.outputHelp();
+      return;
     }
+    const complete = await initCurrentDirectory({
+      preset: options.preset as PresetType | undefined,
+      framework: options.framework as WebFramework | undefined,
+      packageManager: options.packageManager as PackageManager | undefined,
+      skills: options.skills,
+      graft: options.graft,
+      git: options.git,
+      dryRun: options.dryRun,
+      profile: profileFlags(options)
+    });
+    if (!complete && !options.dryRun) process.exitCode = 1;
   });
 
   // Command: new
-  program
+  const newCommand = program
     .command('new [projectName]')
     .description('Create a brand new AI-first project')
     .option('-p, --preset <preset>', 'Project preset: web | cli | generic', 'generic')
@@ -56,12 +119,14 @@ export function createCliProgram(): Command {
     .option('--no-skills', 'Skip installing AI skills')
     .option('--no-graft', 'Skip codebase graph (Graft) setup')
     .option('--no-git', 'Skip git repository initialization')
-    .option('--dry-run', 'Simulate creation without writing changes to disk')
+    .option('--dry-run', 'Simulate creation without writing changes to disk');
+  withProfileOptions(newCommand)
     .action(async (projectName: string | undefined, options: any, command: Command) => {
       let finalName = projectName;
       let finalPreset = options.preset;
       let finalFramework = options.framework;
       let finalPackageManager = options.packageManager;
+      let finalProfile = profileFlags(options);
 
       if (!finalName) {
         if (!isInteractive()) {
@@ -79,12 +144,14 @@ export function createCliProgram(): Command {
           packageManager:
             command.getOptionValueSource('packageManager') === 'cli'
               ? (options.packageManager as PackageManager)
-              : undefined
+              : undefined,
+          profile: finalProfile
         });
         finalName = answers.projectName;
         finalPreset = answers.preset;
         finalFramework = answers.framework;
         finalPackageManager = answers.packageManager;
+        finalProfile = answers.profile;
       }
 
       const complete = await createProject(finalName, {
@@ -94,13 +161,14 @@ export function createCliProgram(): Command {
         skills: options.skills,
         graft: options.graft,
         git: options.git,
-        dryRun: options.dryRun
+        dryRun: options.dryRun,
+        profile: finalProfile
       });
       if (!complete && !options.dryRun) process.exitCode = 1;
     });
 
   // Command: init
-  program
+  const initCommand = program
     .command('init')
     .description('Initialize or update AI-first capabilities in the current directory')
     .option('-p, --preset <preset>', 'Project preset: web | cli | generic')
@@ -110,25 +178,30 @@ export function createCliProgram(): Command {
     .option('--no-graft', 'Skip codebase graph (Graft) setup')
     .option('--no-git', 'Skip git repository initialization')
     .option('--dry-run', 'Simulate setup without writing changes to disk')
+    .option('-y, --yes', 'Skip the prompts and use saved or detected settings');
+  withProfileOptions(initCommand)
     .action(async (options: any, command: Command) => {
       let finalPreset = options.preset;
       let finalFramework = options.framework;
       let finalPackageManager = options.packageManager;
+      let finalProfile = profileFlags(options);
 
       const isPresetExplicit = command.getOptionValueSource('preset') === 'cli';
       const isFrameworkExplicit = command.getOptionValueSource('framework') === 'cli';
       const isPmExplicit = command.getOptionValueSource('packageManager') === 'cli';
 
       const savedConfig = readProjectConfig(process.cwd());
-      if (isInteractive() && !isPresetExplicit && !options.dryRun && !savedConfig) {
+      if (isInteractive() && !isPresetExplicit && !options.dryRun && !options.yes && !savedConfig) {
         const answers = await promptInitProject({
           preset: isPresetExplicit ? (options.preset as PresetType) : undefined,
           framework: isFrameworkExplicit ? (options.framework as WebFramework) : undefined,
-          packageManager: isPmExplicit ? (options.packageManager as PackageManager) : undefined
+          packageManager: isPmExplicit ? (options.packageManager as PackageManager) : undefined,
+          profile: finalProfile
         });
         finalPreset = answers.preset;
         finalFramework = answers.framework;
         finalPackageManager = answers.packageManager;
+        finalProfile = answers.profile;
       }
 
       const complete = await initCurrentDirectory({
@@ -138,11 +211,45 @@ export function createCliProgram(): Command {
         skills: options.skills,
         graft: options.graft,
         git: options.git,
-        dryRun: options.dryRun
+        dryRun: options.dryRun,
+        profile: finalProfile
       });
       if (!complete && !options.dryRun) process.exitCode = 1;
     });
 
+  // Command: list
+  program
+    .command('list')
+    .description('List every capability in the registry and which ones this project enables')
+    .option('-d, --dir <path>', 'Project directory', process.cwd())
+    .action((options: any) => listCapabilities(options.dir));
+
+  // Command: add
+  program
+    .command('add <capabilities...>')
+    .description('Enable capabilities (registry ids or owner/repo skill repositories)')
+    .option('--dry-run', 'Simulate the change')
+    .action(async (ids: string[], options: any) => {
+      const ok = await changeCapabilities(process.cwd(), { add: ids.flatMap((id) => list(id)) }, {
+        dryRun: options.dryRun
+      });
+      if (!ok && !options.dryRun) process.exitCode = 1;
+    });
+
+  // Command: remove
+  program
+    .command('remove <capabilities...>')
+    .description('Disable capabilities and remove the skills they installed')
+    .option('--dry-run', 'Simulate the change')
+    .action(async (ids: string[], options: any) => {
+      const ok = await changeCapabilities(
+        process.cwd(),
+        { remove: ids.flatMap((id) => list(id)) },
+        { dryRun: options.dryRun }
+      );
+      if (!ok && !options.dryRun) process.exitCode = 1;
+    });
+
   // Command: doctor
   program
     .command('doctor')
@@ -166,8 +273,11 @@ export function createCliProgram(): Command {
           ? true
           : await updateSkills(targetDir, { dryRun: options.dryRun })) &&
         (config ? await ensureClaudeSkillLinks(targetDir, config, { dryRun: options.dryRun }) : true);
-      if (config && claudeCodeEnabled(config))
-        setupClaudeMarkdown(targetDir, { dryRun: options.dryRun });
+      if (config) syncAgentDocs(targetDir, config, { dryRun: options.dryRun });
+      if (config?.skills.sources.length !== 0) {
+        const advice = ignoreVendoredSkills(targetDir, { dryRun: options.dryRun, silent: true });
+        for (const line of advice) logger.warn(line);
+      }
       const graftOk =
         config?.codebase.graft === false
           ? true

package/src/cli/new.ts

@@ -1,7 +1,8 @@
 import path from 'node:path';
 import pc from 'picocolors';
-import { getDefaultConfig, upgradeLegacySkillConfig } from '../config/defaults.js';
+import { getDefaultConfig, presetPlatform, upgradeLegacySkillConfig } from '../config/defaults.js';
 import {
+  AginitConfig,
   AGINIT_CONFIG_FILENAME,
   PresetType,
   WebFramework,
@@ -11,13 +12,28 @@ import { getPreset } from '../presets/registry.js';
 import { setupGit } from '../adapters/git.js';
 import { setupAgentsMarkdown, setupClaudeMarkdown } from '../adapters/agents-md.js';
 import { claudeCodeEnabled, installAllSkills, skillAgents } from '../adapters/skills.js';
-import { initGraft } from '../adapters/graft.js';
+import { ignoreVendoredSkills } from '../adapters/tool-ignores.js';
+import { agentBrowserStubInstalled } from '../adapters/agent-browser.js';
+import { microDocPath, projectProfile, resolvePlatformStack, setupMicroDocs } from '../adapters/agent-docs.js';
+import { detectProject } from '../detect/index.js';
 import {
-  agentBrowserConfigured,
-  agentBrowserStubInstalled,
-  setupAgentBrowser
-} from '../adapters/agent-browser.js';
-import { ensureDir, writeJsonFile } from '../utils/fs.js';
+  activeCapabilities,
+  applyResolvedProfile,
+  CapabilityDescriptor,
+  e2eDirFor,
+  hasProfileFlags,
+  inferCapabilities,
+  isNodeStack,
+  MicroDoc,
+  Platform,
+  PLATFORMS,
+  ProfileFlags,
+  resolveCapabilities,
+  Stack
+} from '../registry/index.js';
+import { SETUP_LABELS, SETUPS } from '../registry/setup.js';
+import { commandExists } from '../utils/shell.js';
+import { ensureDir, fileExists, writeJsonFile } from '../utils/fs.js';
 import {
   readProjectConfig,
   readPackageManifest,
@@ -39,6 +55,103 @@ export interface NewProjectOptions {
   dryRun?: boolean;
   targetDir?: string;
   silent?: boolean;
+  /** v2 profile flags: --platform, --methodology, --design, --testing, --ui-driver, ... */
+  profile?: ProfileFlags;
+}
+
+/**
+ * Work out the config to save. A saved config is reused as written, so plain
+ * reruns are deterministic; profile flags (and --preset/--framework for the
+ * browser switches) are applied on top of it.
+ */
+function resolveConfig(
+  projectName: string,
+  targetDir: string,
+  options: NewProjectOptions,
+  existingConfig: AginitConfig | null,
+  manifest: Record<string, any> | null
+): AginitConfig {
+  const flags = options.profile ?? {};
+  const detected = detectProject(targetDir);
+  const saved = existingConfig ? resolvePlatformStack(existingConfig, targetDir) : null;
+  const presetHint = options.preset ?? existingConfig?.preset;
+  const platform: Platform =
+    flags.platform ??
+    existingConfig?.platform ??
+    (options.preset && options.preset !== 'generic'
+      ? presetPlatform(options.preset)
+      : (saved?.platform ?? detected.platform ?? presetPlatform(presetHint ?? 'generic')));
+  const stack: Stack =
+    existingConfig?.stack ??
+    (detected.stack !== 'unknown'
+      ? detected.stack
+      : platform === 'mobile-native'
+        ? 'unknown'
+        : 'node');
+  const presetName = options.preset ?? existingConfig?.preset ?? 'generic';
+  const framework =
+    options.framework ?? (presetName === 'web' ? existingConfig?.framework : undefined);
+  if (presetName !== 'web' && framework && framework !== 'none' && framework !== 'existing')
+    throw new Error('A web framework requires --preset web.');
+  if (presetName === 'web' && framework === 'existing' && !manifest)
+    throw new Error(
+      'An existing web framework requires an existing package.json. Use --framework none for a new baseline.'
+    );
+  if (!isNodeStack(stack) && options.preset && options.preset !== 'generic')
+    throw new Error(
+      `--preset ${options.preset} scaffolds a Node.js project, but this is a ${stack} project. ` +
+        'Use --preset generic (the default) to keep the project root free of package.json.'
+    );
+  const packageManager = options.packageManager ?? existingConfig?.packageManager ?? 'pnpm';
+  const defaults = getDefaultConfig(projectName, presetName, {
+    framework,
+    packageManager,
+    platform,
+    stack,
+    flags,
+    skills: options.skills !== false,
+    // A generic preset leaves an existing package.json (and its test runner) alone.
+    harness: !(presetName === 'generic' && manifest !== null)
+  });
+  if (!existingConfig) return validateConfig(defaults);
+
+  let config: AginitConfig = {
+    ...existingConfig,
+    name: projectName,
+    preset: presetName,
+    ...(isNodeStack(stack) || existingConfig.packageManager !== undefined ? { packageManager } : {}),
+    ...(presetName === 'web' ? { framework: framework ?? 'none' } : {}),
+    browser:
+      options.framework !== undefined || options.preset !== undefined
+        ? { ...existingConfig.browser, ...defaults.browser }
+        : existingConfig.browser,
+    skills: upgradeLegacySkillConfig(existingConfig.skills)
+  };
+  if (hasProfileFlags(flags)) {
+    const base = existingConfig.capabilities ?? inferCapabilities(existingConfig);
+    const profile = resolveCapabilities(
+      {
+        platform,
+        stack,
+        framework,
+        base,
+        basePlatform: saved!.platform,
+        flags,
+        custom: existingConfig.customCapabilities
+      },
+      existingConfig.disabledCapabilities
+    );
+    config = applyResolvedProfile({ ...config, platform, stack }, profile, {
+      skills: true,
+      previous: [...base, ...(existingConfig.customCapabilities ?? []).map((c) => c.id)]
+    });
+  } else if (config.capabilities && config.browser.playwright !== existingConfig.browser.playwright) {
+    // --framework turned the Playwright switch; keep the capability list in step.
+    config.capabilities = config.browser.playwright
+      ? [...config.capabilities, 'playwright']
+      : config.capabilities.filter((id) => id !== 'playwright');
+  }
+  return validateConfig(config);
 }
 
 export async function createProject(
@@ -55,6 +168,8 @@ export async function createProject(
     !SUPPORTED_PACKAGE_MANAGERS.includes(options.packageManager)
   )
     throw new Error('Invalid package manager.');
+  if (options.profile?.platform !== undefined && !PLATFORMS.includes(options.profile.platform))
+    throw new Error(`Invalid platform. Valid platforms are: ${PLATFORMS.join(', ')}`);
   const defaultDir =
     projectName.startsWith('@') && projectName.includes('/')
       ? projectName.split('/').pop()!
@@ -62,54 +177,35 @@ export async function createProject(
   const targetDir = path.resolve(options.targetDir || path.join(process.cwd(), defaultDir));
   const existingConfig = readProjectConfig(targetDir);
   const manifest = readPackageManifest(targetDir); // Validate before creating or modifying anything.
-  const presetName = options.preset ?? existingConfig?.preset ?? 'generic';
-  const framework =
-    options.framework ?? (presetName === 'web' ? existingConfig?.framework : undefined);
-  if (presetName !== 'web' && framework && framework !== 'none' && framework !== 'existing')
-    throw new Error('A web framework requires --preset web.');
-  if (presetName === 'web' && framework === 'existing' && !manifest)
-    throw new Error(
-      'An existing web framework requires an existing package.json. Use --framework none for a new baseline.'
-    );
-  const packageManager = options.packageManager ?? existingConfig?.packageManager ?? 'pnpm';
+  const config = resolveConfig(projectName, targetDir, options, existingConfig, manifest);
+  if (config.preset !== 'web') delete config.framework;
+  if (options.graft === false) config.codebase = { ...config.codebase, graft: false };
+  if (options.skills === false && !existingConfig) config.skills.sources = [];
+  const presetName = config.preset;
+  const packageManager = config.packageManager ?? 'pnpm';
+  const { platform, stack } = resolvePlatformStack(config, targetDir);
   const dryRun = !!options.dryRun;
   const silent = !!options.silent;
   const presetHandler = getPreset(presetName);
-  const defaults = getDefaultConfig(projectName, presetName, {
-    framework,
-    packageManager
-  });
-  const config = validateConfig(
-    existingConfig
-      ? {
-          ...existingConfig,
-          name: projectName,
-          preset: presetName,
-          packageManager,
-          ...(presetName === 'web' ? { framework: framework ?? 'none' } : {}),
-          browser:
-            options.framework !== undefined || options.preset !== undefined
-              ? { ...existingConfig.browser, ...defaults.browser }
-              : existingConfig.browser,
-          skills: upgradeLegacySkillConfig(existingConfig.skills)
-        }
-      : defaults
-  );
-  if (presetName !== 'web') delete config.framework;
-  if (options.graft === false) config.codebase = { ...config.codebase, graft: false };
-  if (options.skills === false && !existingConfig) config.skills.sources = [];
+  const active = activeCapabilities(config);
   if (!silent)
     logger.banner(
       `Aginit — ${projectName}`,
-      `Preset: ${presetName} | PM: ${packageManager} | Target: ${targetDir}${dryRun ? ' (DRY RUN)' : ''}`
+      `Preset: ${presetName} | Platform: ${platform} (${stack})${isNodeStack(stack) ? ` | PM: ${packageManager}` : ''} | Target: ${targetDir}${dryRun ? ' (DRY RUN)' : ''}`
     );
+  if (!silent) logger.dim(`Capabilities: ${active.map((c) => c.id).join(', ') || 'none'}`);
   let complete = true;
 
-  // The agent-browser skill stub is inert without its CLI and browser
-  // binaries, so provisioning them gets its own step when the skill applies.
-  const agentBrowserWanted =
-    agentBrowserConfigured(config.skills.sources) || agentBrowserStubInstalled(targetDir);
-  const totalSteps = agentBrowserWanted ? 7 : 6;
+  const installSkills = options.skills !== false && config.skills.sources.length > 0;
+  // Upstream setups (agent-browser runtime, e2e, Graft) in registry order, Graft last
+  // so its first index sees every generated file.
+  const setups = active
+    .flatMap((capability) =>
+      capability.install.flatMap((step) => (step.kind === 'setup' ? [step.setup] : []))
+    )
+    .filter((setup) => !(setup === 'graft' && options.graft === false))
+    .sort((a, b) => Number(a === 'graft') - Number(b === 'graft'));
+  const totalSteps = 6 + setups.length;
   let currentStep = 1;
 
   // Scaffold into the clean directory before Git adds files that upstream tools reject.
@@ -134,15 +230,14 @@ export async function createProject(
   });
   if (!silent) logger.success(`Wrote ${AGINIT_CONFIG_FILENAME}`);
 
-  // Step 4: Write or update AGENTS.md intake contract
-  if (!silent) logger.step(currentStep++, totalSteps, 'Generating AGENTS.md intake guidance');
-  setupAgentsMarkdown(targetDir, config, { dryRun, silent });
-  if (claudeCodeEnabled(config)) setupClaudeMarkdown(targetDir, { dryRun, silent });
-  if (!silent) logger.success('Configured AGENTS.md');
+  // Step 4: AGENTS.md (task routing) and the docs/agents/ micro-docs it routes to
+  if (!silent) logger.step(currentStep++, totalSteps, 'Generating AGENTS.md and docs/agents/');
+  const docs = syncAgentDocs(targetDir, config, { dryRun, silent });
+  if (!silent) logger.success(`Configured AGENTS.md${docs.length ? ` and ${docs.map(microDocPath).join(', ')}` : ''}`);
 
   // Step 5: Install skills via skills.sh engine
   if (!silent) logger.step(currentStep++, totalSteps, 'Installing upstream skills via skills.sh');
-  if (options.skills !== false && config.skills.sources.length > 0) {
+  if (installSkills) {
     const { installed, failed } = await installAllSkills(targetDir, config.skills.sources, {
       agents: skillAgents(config),
       dryRun,
@@ -160,29 +255,28 @@ export async function createProject(
   } else if (!silent) {
     logger.dim('Skills installation skipped (--no-skills or empty configuration)');
   }
+  const agentBrowserStub = agentBrowserStubInstalled(targetDir);
+  if (installSkills || agentBrowserStub) {
+    const advice = ignoreVendoredSkills(targetDir, { dryRun, silent: true });
+    if (!silent) for (const line of advice) logger.warn(line);
+  }
+  // A stub installed earlier still needs its runtime, even when skills are skipped now.
+  if (agentBrowserStub && !setups.includes('agent-browser')) setups.unshift('agent-browser');
 
-  // Provision the agent-browser runtime the skill stub drives
-  if (agentBrowserWanted) {
-    if (!silent) logger.step(currentStep++, totalSteps, 'Provisioning agent-browser runtime');
-    const abOk = await setupAgentBrowser({ dryRun, silent, cwd: targetDir });
-    complete &&= abOk;
-    if (!silent && abOk) logger.success('agent-browser runtime ready (CLI + browser)');
+  for (const setup of setups) {
+    if (!silent) logger.step(currentStep++, totalSteps, SETUP_LABELS[setup]);
+    const ok = await SETUPS[setup]({ targetDir, config, platform, stack, dryRun, silent });
+    complete &&= ok;
+    if (ok && !silent) logger.success(`${setup} ready`);
   }
 
-  // Codebase intelligence (Graft)
-  if (!silent) logger.step(currentStep++, totalSteps, 'Configuring codebase intelligence');
-  if (config.codebase.graft && options.graft !== false) {
-    const graftOk = await initGraft(targetDir, {
-      dryRun,
-      silent,
-      claude: claudeCodeEnabled(config)
-    });
-    complete &&= graftOk;
-    if (graftOk && !silent) {
-      logger.success('Graft context graph initialized');
-    }
-  } else if (!silent) {
-    logger.dim('Graft setup skipped (--no-graft or codebase.graft: false)');
+  // CLIs aginit does not install: report the missing ones with their install command.
+  if (!silent) logger.step(currentStep++, totalSteps, 'Checking capability CLIs');
+  const missing = await missingBinaries(active, setups);
+  if (!silent) {
+    if (missing.length === 0) logger.success('Every capability CLI is available');
+    for (const { name, bin, install } of missing)
+      logger.warn(`${name} needs the \`${bin}\` CLI: ${install}`);
   }
 
   if (!silent) {
@@ -196,7 +290,10 @@ export async function createProject(
     console.log('Next steps:');
     const relativeTarget = path.relative(process.cwd(), targetDir);
     if (relativeTarget) console.log(pc.cyan(`  cd ${relativeTarget}`));
-    console.log(pc.cyan(`  ${packageManager} install`));
+    if (isNodeStack(stack) && (manifest || fileExists(path.join(targetDir, 'package.json')) || dryRun))
+      console.log(pc.cyan(`  ${packageManager} install`));
+    if (active.some((c) => c.id === 'e2e') && e2eDirFor(stack))
+      console.log(pc.cyan(`  (cd ${e2eDirFor(stack)} && npm install)`));
     console.log(pc.cyan('  Open the repository in your AI coding agent'));
     console.log(pc.dim('  Prompt the agent: ') + pc.bold(pc.green('"bootstrap this project"')));
     console.log();
@@ -204,3 +301,32 @@ export async function createProject(
 
   return complete;
 }
+
+/** Binaries of active capabilities that are not on PATH (setups report their own). */
+export async function missingBinaries(
+  active: CapabilityDescriptor[],
+  setups: string[]
+): Promise<Array<{ name: string; bin: string; install: string }>> {
+  const missing: Array<{ name: string; bin: string; install: string }> = [];
+  for (const capability of active) {
+    if (capability.install.some((step) => step.kind === 'setup' && setups.includes(step.setup)))
+      continue;
+    for (const step of capability.install)
+      if (step.kind === 'binary' && !(await commandExists(step.bin)))
+        missing.push({ name: capability.name, bin: step.bin, install: step.install });
+  }
+  return missing;
+}
+
+/** Refresh AGENTS.md, CLAUDE.md and docs/agents/ from the config. */
+export function syncAgentDocs(
+  targetDir: string,
+  config: AginitConfig,
+  options: { dryRun?: boolean; silent?: boolean } = {}
+): MicroDoc[] {
+  const scripts = readPackageManifest(targetDir)?.scripts;
+  const docs = setupMicroDocs(targetDir, projectProfile(config, { targetDir, scripts }), options);
+  setupAgentsMarkdown(targetDir, config, { ...options, docs });
+  if (claudeCodeEnabled(config)) setupClaudeMarkdown(targetDir, options);
+  return docs;
+}