@aifabrix/builder 2.56.0 → 2.58.0

package/lib/app/push.js

@@ -93,23 +93,24 @@ function extractImageName(config, appName) {
  */
 async function loadPushConfig(appName, options) {
   const { loadConfigFile } = require('../utils/config-format');
+  const { resolveEffectiveRegistry, stripRegistryHostFromRepository } = require('../utils/resolve-docker-image-ref');
+  let config;
   try {
     const { appPath } = await paths.detectAppType(appName);
-    const configPath = paths.resolveApplicationConfigPath(appPath);
-    const config = loadConfigFile(configPath);
-    const effective = getEffectiveConfig(config);
-    const registry = options.registry || effective.image?.registry;
-    if (!registry) {
-      throw new Error('Registry URL is required. Provide via --registry flag or configure in application config under image.registry');
-    }
-    const imageName = extractImageName(config, appName);
-    return { registry, imageName };
+    config = loadConfigFile(paths.resolveApplicationConfigPath(appPath));
   } catch (error) {
-    if (error.message.includes('Registry URL')) {
-      throw error;
-    }
     throw new Error(`Failed to load configuration: ${error.message}\nRun 'aifabrix create ${appName}' first`);
   }
+  const effective = getEffectiveConfig(config);
+  const { registry } = resolveEffectiveRegistry(effective, { registry: options.registry });
+  if (!registry) {
+    throw new Error(
+      'Registry URL is required. Provide --registry, run "aifabrix dev set-registry <registry>", ' +
+      'or configure image.registry in the application config'
+    );
+  }
+  const imageName = stripRegistryHostFromRepository(extractImageName(config, appName));
+  return { registry, imageName, appVersion: require('../utils/image-tags').readAppVersion(effective) };
 }
 
 /**
@@ -129,10 +130,43 @@ async function validatePushConfig(registry, imageName, appName) {
     throw new Error(`Invalid registry URL format: ${registry}. Expected format: *.azurecr.io`);
   }
 
-  if (!await pushUtils.checkLocalImageExists(imageName, 'latest')) {
-    throw new Error(`Docker image ${imageName}:latest not found locally.\nRun 'aifabrix build ${appName}' first`);
+  const sourceRef = await resolveLocalSourceRef(registry, imageName);
+  if (!sourceRef) {
+    throw new Error(`Docker image ${registry}/${imageName}:latest or ${imageName}:latest not found locally.\nRun 'aifabrix build ${appName}' first`);
+  }
+
+  const { getRegistryCredentialStatus } = require('../utils/registry-credentials');
+  const credentialStatus = getRegistryCredentialStatus(registry);
+  if (credentialStatus === 'partial') {
+    await require('../utils/registry-credentials').loadRegistryCredentials(registry);
+  }
+  if (credentialStatus === 'complete') {
+    return sourceRef;
+  }
+  await validateAzureCli();
+  return sourceRef;
+}
+
+/**
+ * Local image to push from: the registry-qualified build output first, else the plain repository.
+ * @param {string} registry - Registry host
+ * @param {string} imageName - Repository without host
+ * @returns {Promise<string|null>} `repository:latest` or null
+ */
+async function resolveLocalSourceRef(registry, imageName) {
+  for (const repository of [`${registry}/${imageName}`, imageName]) {
+    if (await pushUtils.checkLocalImageExists(repository, 'latest')) {
+      return `${repository}:latest`;
+    }
   }
+  return null;
+}
 
+/**
+ * Azure CLI prerequisites for the ACR login fallback (no stored registry credentials).
+ * @returns {Promise<void>}
+ */
+async function validateAzureCli() {
   if (!await pushUtils.checkAzureCLIInstalled()) {
     throw new Error('Azure CLI is not installed. Install from: https://docs.microsoft.com/cli/azure/install-azure-cli');
   }
@@ -149,7 +183,7 @@ async function validatePushConfig(registry, imageName, appName) {
  * @async
  * @param {string} registry - Registry URL
  */
-async function authenticateWithRegistry(registry) {
+async function authenticateWithAzureCli(registry) {
   if (await pushUtils.checkACRAuthentication(registry)) {
     logger.log(formatSuccessLine(`Already authenticated with ${registry}`));
   } else {
@@ -157,6 +191,16 @@ async function authenticateWithRegistry(registry) {
   }
 }
 
+/**
+ * Stored host-scoped credentials first (stdin login), else Azure CLI. Once per command.
+ * @param {string} registry - Registry host
+ * @returns {Promise<void>}
+ */
+async function authenticateWithRegistry(registry) {
+  const { ensureRegistryLogin } = require('../utils/registry-credentials');
+  await ensureRegistryLogin(registry, { fallback: authenticateWithAzureCli });
+}
+
 /**
  * Layout-aligned notice when push is skipped for external integrations.
  * @param {string} appName
@@ -191,30 +235,43 @@ function logPushCommandHeader(appName, registry, imageName) {
  * @param {string} registry - Registry URL
  * @param {Array<string>} tags - Image tags
  */
-async function pushImageTags(imageName, registry, tags) {
-  try {
-    await Promise.all(tags.map(async(tag) => {
-      await pushUtils.tagImage(`${imageName}:latest`, `${registry}/${imageName}:${tag}`);
-      await pushUtils.pushImage(`${registry}/${imageName}:${tag}`, registry);
-    }));
-  } catch (error) {
-    // If authentication error, try to re-authenticate and retry once
-    const errorMessage = error.message || String(error);
-    const isAuthError = errorMessage.includes('Authentication required') ||
-                        errorMessage.includes('authentication required') ||
-                        (errorMessage.includes('authentication') && errorMessage.includes('401'));
+function isAuthenticationError(error) {
+  const message = (error && error.message) || String(error);
+  return message.includes('Authentication required') ||
+    message.includes('authentication required') ||
+    (message.includes('authentication') && message.includes('401'));
+}
+
+async function tagAndPushOne(sourceRef, targetRef, registry) {
+  if (sourceRef !== targetRef) {
+    await pushUtils.tagImage(sourceRef, targetRef);
+  }
+  await pushUtils.pushImage(targetRef, registry);
+}
 
-    if (isAuthError) {
-      logger.log(
-        formatWarningLine('Registry authentication expired; re-authenticating, then retrying push.')
-      );
+/**
+ * Tags and pushes every unique target once, re-authenticating once on an auth failure.
+ * @async
+ * @param {string} sourceRef - Local source image
+ * @param {string} imageName - Repository without host
+ * @param {string} registry - Registry host
+ * @param {Array<string>} tags - Resolved tags
+ */
+async function pushImageTags(sourceRef, imageName, registry, tags) {
+  let reauthenticated = false;
+  for (const tag of tags) {
+    const targetRef = `${registry}/${imageName}:${tag}`;
+    try {
+      await tagAndPushOne(sourceRef, targetRef, registry);
+    } catch (error) {
+      if (reauthenticated || !isAuthenticationError(error)) {
+        throw new Error(`Push failed for ${targetRef}: ${error.message}`);
+      }
+      logger.log(formatWarningLine('Registry authentication expired; re-authenticating, then retrying push.'));
+      require('../utils/registry-credentials').resetRegistryLoginCache(registry);
       await authenticateWithRegistry(registry);
-      // Retry push after re-authentication
-      await Promise.all(tags.map(async(tag) => {
-        await pushUtils.pushImage(`${registry}/${imageName}:${tag}`, registry);
-      }));
-    } else {
-      throw error;
+      reauthenticated = true;
+      await tagAndPushOne(sourceRef, targetRef, registry);
     }
   }
 }
@@ -252,12 +309,12 @@ async function pushApp(appName, options = {}) {
   }
   try {
     validateAppName(appName);
-    const { registry, imageName } = await loadPushConfig(appName, options);
-    await validatePushConfig(registry, imageName, appName);
+    const { registry, imageName, appVersion } = await loadPushConfig(appName, options);
+    const tags = require('../utils/image-tags').resolveImageTags(options.tag, appVersion);
+    const sourceRef = await validatePushConfig(registry, imageName, appName);
     logPushCommandHeader(appName, registry, imageName);
     await authenticateWithRegistry(registry);
-    const tags = options.tag ? options.tag.split(',').map(t => t.trim()) : ['latest'];
-    await pushImageTags(imageName, registry, tags);
+    await pushImageTags(sourceRef, imageName, registry, tags);
     displayPushResults(registry, imageName, tags);
   } catch (error) {
     throw new Error(`Failed to push application: ${error.message}`);

package/lib/build/standard-docker-build.js

@@ -80,21 +80,18 @@ async function executeDockerImageBuild(appName, options, buildConfig) {
   );
   await ensureRunSecretsForApp(appName);
   const buildArgs = await resolveDockerBuildArgsForApp(appName, contextPath);
-  const tag = options.tag || 'latest';
-  if (typeof tag === 'string' && tag.includes(',')) {
-    throw new Error('Use a single image tag per build (comma-separated multiple tags are not supported).');
-  }
+  const { primary, aliases, tags } = options.tagPlan;
   await dockerBuild.executeDockerBuildWithTag(
     effectiveImageName,
     imageName,
     dockerfilePath,
     contextPath,
-    tag,
-    { ...options, buildArgs }
+    primary,
+    { ...options, buildArgs, tagAliases: aliases }
   );
   await postBuildTasks(appName, buildConfig);
   logger.log(formatSuccessParagraph('Build completed successfully!'));
-  return `${effectiveImageName}:${tag}`;
+  return tags.map((tag) => `${effectiveImageName}:${tag}`).join(', ');
 }
 
 /**
@@ -104,12 +101,17 @@ async function executeDockerImageBuild(appName, options, buildConfig) {
  * @returns {Promise<string>} Built image ref e.g. name:tag
  */
 async function runStandardDockerBuild(appName, options) {
-  const promotedRef = await tryCompleteDevPromoteBuild(appName, options);
+  const { resolveBuildTagPlan, readAppVersion } = require('../utils/image-tags');
+  const { buildConfig, config: appConfig } = await buildHelpers.loadAndValidateConfig(appName);
+  // Resolve and validate every tag before any Docker build, tag, login or promote.
+  const planned = { ...options, tagPlan: resolveBuildTagPlan(options.tag, readAppVersion(appConfig)) };
+  const promotedRef = await tryCompleteDevPromoteBuild(appName, planned);
   if (promotedRef) {
-    return promotedRef;
+    const { resolvePromoteBaseTags } = require('../utils/promote-dev-docker-image');
+    const baseName = promotedRef.slice(0, promotedRef.lastIndexOf(':'));
+    return resolvePromoteBaseTags(planned).map((tag) => `${baseName}:${tag}`).join(', ');
   }
-  const { buildConfig } = await buildHelpers.loadAndValidateConfig(appName);
-  return executeDockerImageBuild(appName, options, buildConfig);
+  return executeDockerImageBuild(appName, planned, buildConfig);
 }
 
 module.exports = { runStandardDockerBuild };

package/lib/cli/setup-app.js

@@ -208,6 +208,7 @@ Examples:
     .option('-p, --port <port>', 'Override local port')
     .option('-d, --debug', 'Enable debug output with detailed container information')
     .option('-t, --tag <tag>', 'Image tag to run (e.g. v1.0.0); overrides application.yaml image.tag')
+    .option('-r, --registry <registry>', 'Registry host for the image (overrides dev set-registry and application.yaml)')
     .option('-e, --env <env>', 'Environment: dev (default), tst, or pro', 'dev')
     .option('--base', 'Use manifest base image only (skip local developer-scoped tag preference)')
     .option('--reload', 'In dev: mount workspace into container (Mutagen only if docker-endpoint is a remote host)')
@@ -237,7 +238,11 @@ function registerBuildCommand(program) {
     .option('-l, --language <lang>', 'Override language detection')
     .option('-f, --force-template', 'Force rebuild from template')
     .option('--no-cache', 'Full Docker rebuild (disable layer cache); use after Dockerfile or context fixes')
-    .option('-t, --tag <tag>', 'Image tag (default: latest). Set image.tag in application.yaml to match for deploy.')
+    .option(
+      '-t, --tag <tags>',
+      'Image tag or comma-separated tags (default: latest); {version} expands to app.version, e.g. "latest,{version}"'
+    )
+    .option('-r, --registry <registry>', 'Registry host for the image name (overrides dev set-registry and application.yaml)')
     .option(
       '--base',
       'Build/run the manifest base image (no -devN suffix). Default local build uses a developer-scoped repository when developer-id > 0.'
@@ -246,10 +251,16 @@ function registerBuildCommand(program) {
       '--from-dev',
       'With --base: tag the existing developer-scoped image as the base image instead of rebuilding when possible'
     )
+    .addHelpText('after', `
+Examples:
+  $ aifabrix build myapp
+  $ aifabrix build myapp --tag v1.0.0            # also tags latest
+  $ aifabrix build myapp --base --from-dev --tag 'latest,{version}'
+  $ aifabrix build myapp --registry myregistry.azurecr.io`)
     .action(async(appName, options) => {
       try {
-        const imageTag = await app.buildApp(appName, options);
-        logger.log(`✔ Built image: ${imageTag}`);
+        const imageRefs = await app.buildApp(appName, options);
+        logger.log(`✔ Built image: ${imageRefs}`);
       } catch (error) {
         handleCommandError(error, 'build');
         process.exit(1);
@@ -403,8 +414,8 @@ function setupPushDeployDockerfileCommands(program) {
   program.command('push <appKey>')
     .description('Push builder appKey image to Azure Container Registry')
     .addHelpText('after', PUSH_HELP_AFTER)
-    .option('-r, --registry <registry>', 'ACR registry URL (overrides application.yaml)')
-    .option('-t, --tag <tag>', 'Image tag(s) - comma-separated for multiple (default: latest)')
+    .option('-r, --registry <registry>', 'Registry host (overrides dev set-registry and application.yaml)')
+    .option('-t, --tag <tags>', 'Image tag or comma-separated tags (default: latest); {version} expands to app.version')
     .action(async(appName, options) => {
       try {
         await app.pushApp(appName, options);

package/lib/cli/setup-dev-path-commands.js

@@ -1,5 +1,6 @@
 /**
- * Dev subcommands: set-home, set-work, print-home, print-work, shell-env, set-format.
+ * Dev subcommands: set-home, set-work, print-home, print-work, shell-env, set-format,
+ * set-registry, print-registry.
  *
  * @fileoverview Path and format CLI registration for `aifabrix dev`
  * @author AI Fabrix Team
@@ -178,8 +179,53 @@ function addSetFormatCommand(dev, handleSetFormat) {
     });
 }
 
+const SET_REGISTRY_HELP = `
+Examples:
+  $ aifabrix dev set-registry myregistry.azurecr.io
+  $ printf '%s' "$TOKEN" | aifabrix dev set-registry myregistry.azurecr.io --username puller --password-stdin
+  $ aifabrix dev set-registry myregistry.azurecr.io --clear-credentials
+  $ aifabrix dev set-registry --clear
+
+Registry precedence for build, run, push and deploy: --registry, then this value, then the
+application image.registry. Credentials are stored encrypted in your local secrets file as
+<registry>-username and <registry>-password and are used for docker login (password on stdin).`;
+
+function addRegistryCommands(dev) {
+  const { runSetRegistry, runPrintRegistry } = require('../commands/dev-registry');
+  dev
+    .command('set-registry [registry]')
+    .description('Set, clear or add credentials for the default container registry of this CLI installation')
+    .option('--username <username>', 'Registry username (requires a password option)')
+    .option('--password <password>', 'Registry password or token (visible in shell history; prefer --password-stdin)')
+    .option('--password-stdin', 'Read the registry password or token from stdin')
+    .option('--clear', 'Remove the saved default registry (credentials are kept)')
+    .option('--clear-credentials', 'Remove only the stored credentials for <registry>')
+    .addHelpText('after', SET_REGISTRY_HELP)
+    .action(async(registry, cmdOpts) => {
+      try {
+        await runSetRegistry(registry, cmdOpts);
+      } catch (error) {
+        handleCommandError(error, 'dev set-registry');
+        process.exit(1);
+      }
+    });
+
+  dev
+    .command('print-registry')
+    .description('Print the saved default registry or an empty line (stdout only; for scripts)')
+    .addHelpText('after', '\nExamples:\n  $ aifabrix dev print-registry\n')
+    .action(async() => {
+      try {
+        await runPrintRegistry();
+      } catch (error) {
+        handleCommandError(error, 'dev print-registry');
+        process.exit(1);
+      }
+    });
+}
+
 /**
- * Register dev set-home, set-work, print-*, set-format.
+ * Register dev set-home, set-work, print-*, set-format, set-registry, print-registry.
  * @param {import('commander').Command} dev - dev subcommand group
  * @param {function(string): Promise<void>} handleSetFormat - handler that updates format and refreshes display
  * @returns {void}
@@ -190,6 +236,7 @@ function setupDevPathAndFormatCommands(dev, handleSetFormat) {
   addSetWorkCommand(dev);
   addPrintHomeWorkCommands(dev);
   addSetFormatCommand(dev, handleSetFormat);
+  addRegistryCommands(dev);
 }
 
 module.exports = { setupDevPathAndFormatCommands };

package/lib/cli/setup-environment.js

@@ -7,39 +7,108 @@
  */
 
 const { handleCommandError } = require('../utils/cli-utils');
+const { formatWarningLine } = require('../utils/cli-test-layout-chalk');
+const { isWorkspaceMode, isLegacyMarketplaceMode } = require('../deployment/installation/stage-input');
 
 /**
- * Sets up environment deployment commands
- * @param {Command} program - Commander program instance
+ * Adds installation workspace and deprecated explicit Marketplace options.
+ * @param {Command} command - Commander command
+ * @returns {Command} The command
  */
-function setupEnvironmentCommands(program) {
-  const deployEnvHandler = async(envKey, options) => {
-    try {
+function addMarketplaceOptions(command) {
+  return command
+    .option('--stage <stage>', 'Installation workspace stage: register, infra, dev, tst or pro (<env> is then the resource group)')
+    .option('--vendor <vendor>', 'Installation vendor: AZURE (default) or DOCKER (register only)')
+    .option('--allow-my-ip', 'Allow the caller public IPv4 /32 to reach PostgreSQL, Key Vault and Storage (infra only; default off)')
+    .option('--license-edition <edition>', 'License requested at activation: COMMUNITY, STANDARD, ENTERPRISE or a Marketplace subscription ID (infra only; saved in the workspace)')
+    .option('--location <region>', 'Azure region for infra (saved to the workspace; dev, tst and pro inherit it)')
+    .option(
+      '--acr-auth <mode>',
+      'Image pull auth for infra: auto (default: saved dev set-registry pair, else managed identity), mi, or credentials (admin is a deprecated alias)'
+    )
+    .option('--miso-api-key-env <name>', 'Environment variable holding a temporary Miso API key (dev, tst, pro)')
+    .option(
+      '--controller-url <url>',
+      'Controller endpoint override for dev, tst or pro (normally recorded by infra); does not authenticate'
+    )
+    .option('--marketplace-json <file>', 'Deprecated explicit mode: ARM Marketplace infrastructure template')
+    .option('--parameters <file>', 'Deprecated explicit mode: secure ARM deploymentParameters JSON file')
+    .option('--subscription <id>', 'Deprecated explicit mode: Azure subscription ID')
+    .option('--resource-group <name>', 'Deprecated explicit mode: new isolated Azure resource group')
+    .option('--install-id <id>', 'Deprecated explicit mode: installation ID and resume-journal key');
+}
+
+async function runLegacyMarketplace(envKey, options) {
+  process.stderr.write(`${formatWarningLine('Explicit Marketplace flags are deprecated; use af env deploy <resource-group> --stage infra')}\n`);
+  const installer = require('../deployment/marketplace-environment');
+  const result = await installer.deployMarketplaceEnvironment(envKey, options);
+  if (result.platformComplete) {
+    process.stdout.write(`Platform ready: ${result.publicControllerUrl}\n`);
+  } else {
+    process.stdout.write(`Infrastructure deployed: ${result.outputs.webAppUrl} (deployment ${result.deploymentId})\n`);
+    process.stdout.write(`Resume after controller login and wizard activation: af env deploy ${envKey} --install-id ${result.installId} --controller-url https://<ready-public-host>/miso --stage platform\n`);
+  }
+}
+
+async function runInstallationStage(resourceGroup, options) {
+  const { deployInstallationStage } = require('../deployment/installation');
+  const { formatStageResult } = require('../deployment/installation/stage-output');
+  const result = await deployInstallationStage(resourceGroup, options);
+  process.stdout.write(formatStageResult(result, resourceGroup));
+}
+
+async function deployEnvHandler(envKey, options) {
+  try {
+    if (isWorkspaceMode(options)) {
+      await runInstallationStage(envKey, options);
+    } else if (isLegacyMarketplaceMode(options)) {
+      await runLegacyMarketplace(envKey, options);
+    } else {
       const environmentDeploy = require('../deployment/environment');
       await environmentDeploy.deployEnvironment(envKey, options);
-    } catch (error) {
-      handleCommandError(error, 'env deploy');
-      process.exit(1);
     }
-  };
+  } catch (error) {
+    handleCommandError(error, 'env deploy');
+    process.exit(1);
+  }
+}
 
-  const deployExamples = `
+const DEPLOY_EXAMPLES = `
 Examples:
   $ aifabrix env deploy dev
   $ aifabrix env deploy tst
   $ aifabrix env deploy pro --preset m
-  $ aifabrix env deploy dev --preset xl
   $ aifabrix env deploy dev --config ./env-config.json
   $ aifabrix env deploy dev --no-poll
 
-Prerequisites: aifabrix login (device token; controller permission controller:deploy).
+Installation workspace (<env> is the resource group; files under infrastructure/<resource-group>/):
+  $ af env deploy <resource-group> --stage infra
+  $ af env deploy <resource-group> --stage infra --allow-my-ip
+  $ af env deploy <resource-group> --stage infra --license-edition ENTERPRISE
+  $ af env deploy <resource-group> --stage infra --location swedencentral
+  $ af env deploy <resource-group> --stage infra --acr-auth credentials
+  $ af env deploy <resource-group> --stage dev
+  $ af env deploy <resource-group> --stage pro --preset m
+  $ af env deploy <resource-group> --stage register --vendor DOCKER
+
+Vendor/stage matrix:
+  AZURE   infra, dev, tst, pro   (Mori bootstrap runs inside the Marketplace template)
+  DOCKER  register only          (deploy with aifabrix setup)
+
+Prerequisites: aifabrix login or MISO_API_KEY / --miso-api-key-env (controller permission controller:deploy);
+infra also needs az login. --controller-url only selects the endpoint; it never replaces authentication.
+Registry pull auth for infra: save a pair once with aifabrix dev set-registry <acr-login-server> --username <user> --password-stdin.
+Deprecated explicit Marketplace flags: --marketplace-json, --parameters, --subscription, --resource-group, --install-id
+(that route also accepts --location).
 Environment keys: miso, dev, tst, pro. Default size preset: s (use --preset s|m|l|xl).
+Tenant activation after infra is a manual step in the Miso web application.
 Run this before aifabrix deploy <app> — the environment must exist first.`;
 
-  const ENV_GROUP_HELP_AFTER = `
+const ENV_GROUP_HELP_AFTER = `
 Examples:
   $ aifabrix env deploy dev
   $ aifabrix env deploy dev --preset m
+  $ af env deploy <resource-group> --stage infra
   $ aifabrix env deploy dev --help
 
 Typical workflow:
@@ -51,21 +120,22 @@ Subcommands:
   deploy <env>   Provision/update environment in Miso Controller (see env deploy --help)
 `;
 
+function setupEnvironmentCommands(program) {
   const env = program
     .command('env')
     .description('Miso Controller environments (primary: env deploy <env>)')
     .addHelpText('after', ENV_GROUP_HELP_AFTER);
 
-  env
+  addMarketplaceOptions(env
     .command('deploy <env>')
-    .description('Deploy environment infrastructure in Miso Controller (run before deploy <app>)')
+    .description('Deploy environment infrastructure in Miso Controller, or an installation workspace stage with --stage')
     .option('--config <file>', 'Environment configuration file (optional if --preset is used)')
-    .option('--preset <size>', 'Environment size preset: s, m, l, xl (default: s)', 's')
+    .option('--preset <size>', 'Environment size preset: s, m, l, xl (default: s, or the workspace file value)')
     .option('--skip-validation', 'Skip environment validation')
     .option('--poll', 'Poll for deployment status', true)
-    .option('--no-poll', 'Do not poll for status')
-    .addHelpText('after', deployExamples)
+    .option('--no-poll', 'Do not poll for status'))
+    .addHelpText('after', DEPLOY_EXAMPLES)
     .action(deployEnvHandler);
 }
 
-module.exports = { setupEnvironmentCommands };
+module.exports = { setupEnvironmentCommands, deployEnvHandler, addMarketplaceOptions };

package/lib/commands/agent-kit-help.js

@@ -21,9 +21,10 @@ Examples:
   $ aifabrix agent-kit install --host all --approve-all claude --yes
   $ aifabrix agent-kit update --host all --approve-all --yes
   $ aifabrix agent-kit remote create --org my-org --yes
-  $ aifabrix agent-kit start claude --remote-control --approve-all --yes
-  $ aifabrix agent-kit start claude --name aifabrix-docs --remote-control --approve-all --yes
-  $ aifabrix agent-kit start codex --approve-all --yes
+  $ aifabrix agent-kit start claude
+  $ aifabrix agent-kit start codex
+  $ aifabrix agent-kit list
+  $ aifabrix agent-kit kill aifabrix-docs
   $ aifabrix agent-kit status
   $ aifabrix agent-kit validate
 `;
@@ -117,23 +118,37 @@ Interactive (TTY): omit flags to be prompted. Silent: --org <owner> --yes
 const START_HELP = `
 Does not install Agent Kit skills. Starts claude or codex in tmux in this git
 workspace so closing the terminal does not kill the session. Detach: Ctrl-b then
-d. --approve-all writes that app's local permission config only. --name is the
-tmux session (default: last folder, e.g. aifabrix-docs). Claude also gets
---name and --remote-control hostname-user-folder, e.g.
-builder01-dev03-aifabrix-docs. Claude --tmux is for worktrees, not this wrapper.
-That is not Claude --cloud (a separate cloud VM). Codex has no phone/web attach.
+d. The defaults enable that app's Remote Control and workspace auto-approval.
+--name is the tmux session (default: last git-root folder, e.g. aifabrix-docs).
+Claude gets --name and hostname-user-folder Remote Control. Codex uses its native
+remote-control daemon. Use --no-remote-control and/or --skip-approve-all to opt
+out. Claude --tmux is for worktrees, not this wrapper.
 
 Examples:
-  $ aifabrix agent-kit start claude --remote-control --approve-all --yes
-  $ aifabrix agent-kit start claude --name aifabrix-docs --remote-control --approve-all --yes
-  $ aifabrix agent-kit start claude --name aifabrix-miso --remote-control --approve-all --yes
-  $ aifabrix agent-kit start claude --remote-control --detach
   $ aifabrix agent-kit start claude
-  $ aifabrix agent-kit start claude --approve-all --yes
-  $ aifabrix agent-kit start codex --approve-all --yes
+  $ aifabrix agent-kit start codex
+  $ aifabrix agent-kit start claude --name aifabrix-miso
+  $ aifabrix agent-kit start codex --no-remote-control --skip-approve-all
+  $ aifabrix agent-kit start claude --detach
   $ aifabrix agent-kit start claude --dry-run --json
 `;
 
+const LIST_HELP = `
+Lists every active tmux session visible to the current Unix user.
+
+Examples:
+  $ aifabrix agent-kit list
+  $ aifabrix agent-kit list --json
+`;
+
+const KILL_HELP = `
+Stops exactly one tmux session. Use agent-kit list to find its name.
+
+Examples:
+  $ aifabrix agent-kit kill aifabrix-miso
+  $ aifabrix agent-kit kill aifabrix-miso --json
+`;
+
 module.exports = {
   HOST_OPTION_HELP,
   APPROVE_ALL_OPTION_HELP,
@@ -145,5 +160,7 @@ module.exports = {
   INIT_HELP,
   REMOTE_GROUP_HELP,
   REMOTE_HELP,
-  START_HELP
+  START_HELP,
+  LIST_HELP,
+  KILL_HELP
 };