@aifabrix/builder 2.57.0 → 2.59.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/index.js

@@ -41,6 +41,8 @@ const { setupChannelCommands } = require('../commands/channel');
 const { setupManifestCommands } = require('../commands/manifest');
 const { setupNpmCommands } = require('./setup-npm');
 const { setupListCommand } = require('./setup-list');
+const { setupHelpCommand } = require('./setup-help');
+const { setupOnboardingCommand } = require('./setup-onboarding');
 
 /**
  * Dev, secrets, parameters, and platform commands (keeps setupCommands under statement limit).
@@ -101,6 +103,8 @@ function setupExtendedCliCommands(program) {
  * @param {Command} program - Commander program instance
  */
 function setupCommands(program) {
+  setupHelpCommand(program);
+  setupOnboardingCommand(program);
   setupCoreCliCommands(program);
   setupExtendedCliCommands(program);
   setupDevAndPlatformCommands(program);

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
@@ -133,6 +134,10 @@ function addPrintHomeWorkCommands(dev) {
       }
     });
 
+  addShellEnvCommand(dev);
+}
+
+function addShellEnvCommand(dev) {
   dev
     .command('shell-env')
     .description(
@@ -178,8 +183,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 +240,7 @@ function setupDevPathAndFormatCommands(dev, handleSetFormat) {
   addSetWorkCommand(dev);
   addPrintHomeWorkCommands(dev);
   addSetFormatCommand(dev, handleSetFormat);
+  addRegistryCommands(dev);
 }
 
 module.exports = { setupDevPathAndFormatCommands };

package/lib/cli/setup-dev.js

@@ -44,8 +44,11 @@ const DEV_ADD_HELP_AFTER = `
 Examples:
   $ aifabrix dev add --developer-id 02 --name "Jane Doe" --email jane@example.com
   $ aifabrix dev add --developer-id 03 --name "Build admin" --email admin@example.com --groups admin,developer
-  $ aifabrix dev add --developer-id 04 --name "CI user" --email ci@example.com --groups secret-manager,developer
-  $ aifabrix dev add --developer-id 05 --name "Integrator" --email integrator@example.com --groups developer,secret-reader
+  $ aifabrix dev add --developer-id 04 --name "Docker developer" --email docker-dev@example.com --groups developer,docker
+  $ aifabrix dev add --developer-id 05 --name "Integrator" --email integrator@example.com --groups integrator
+
+Groups: integrator is for SSH onboarding without Docker. Use developer,docker for host Docker access (root-equivalent; grant sparingly).
+When --groups is supplied, it replaces the default developer group; developer is not added automatically.
 
 Requires a configured remote Builder Server and an admin client certificate (same machine setup as dev list / dev pin). After add, run dev pin <id> once to create a PIN for aifabrix dev init.
 `;
@@ -318,7 +321,7 @@ function setupDevListAddCommands(dev) {
     .requiredOption('--developer-id <id>', 'Unique id, digits only (e.g. 02); used with dev init --developer-id')
     .requiredOption('--name <name>', 'Display name')
     .requiredOption('--email <email>', 'Email address')
-    .option('--groups <items>', 'Comma-separated roles: admin, secret-manager, secret-reader, developer, docker', 'developer')
+    .option('--groups <items>', 'Comma-separated roles: admin, secret-manager, secret-reader, developer, docker, integrator', 'developer')
     .option('--no-provision', 'Create user in database only (skip host provision job)')
     .option('--builder-version <ver>', 'Builder CLI version for provision job')
     .option('--admin-email <email>', 'Platform admin email for provision job')
@@ -373,7 +376,7 @@ function setupDevUpdatePinDeleteCommands(dev) {
     .option('--developer-id <id>', 'Developer ID (same as dev add)')
     .option('--name <name>', 'Display name')
     .option('--email <email>', 'Email address')
-    .option('--groups <items>', 'Comma-separated groups (admin, secret-manager, secret-reader, developer, docker)')
+    .option('--groups <items>', 'Comma-separated groups (admin, secret-manager, secret-reader, developer, docker, integrator)')
     .addHelpText('after', DEV_UPDATE_HELP_AFTER)
     .action(async(developerId, options) => {
       try {

package/lib/cli/setup-environment.js

@@ -21,14 +21,21 @@ function addMarketplaceOptions(command) {
     .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 URL override for dev, tst or pro (deprecated platform stage also uses it)')
+    .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')
-    .option('--location <region>', 'Deprecated explicit mode: Azure region when not set in the parameter file');
+    .option('--install-id <id>', 'Deprecated explicit mode: installation ID and resume-journal key');
 }
 
 async function runLegacyMarketplace(envKey, options) {
@@ -78,6 +85,8 @@ Installation workspace (<env> is the resource group; files under infrastructure/
   $ 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
@@ -86,7 +95,11 @@ 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 (controller permission controller:deploy); infra also needs az login.
+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.`;

package/lib/cli/setup-help.js

@@ -0,0 +1,86 @@
+/** Read-only onboarding guide; command reference remains available through --help. */
+'use strict';
+
+const ONBOARDING_GUIDE = `Welcome to AI Fabrix
+
+On a managed workspace host with provisioned config, run:
+
+  af onboarding
+  af onboarding --coding claude
+  af onboarding --coding codex
+  af onboarding --coding cursor
+  af onboarding --coding claude --name sales-workspace
+  af onboarding --coding claude --name finance-workspace
+  af onboarding --repo example-org/example-workspace
+  af onboarding --repo my-org/new-repo
+
+This prepares the coding platform selected by your organisation, or the one
+you pass for this run. Claude starts in a detached tmux session; Codex and
+Cursor use their own SSH clients. It does not install the local AI Fabrix platform.
+Use --name <folder> for separate workspaces; each Claude workspace has its own
+tmux session. Use --repo owner/name to clone an accessible GitHub repository
+or create a new private one. agent-kit remote create creates a new GitHub
+repository for the current local workspace; --name sets that remote name.
+
+Start your integration workspace with Codex:
+
+  aifabrix agent-kit setup <controller-url>
+
+Ask your administrator for the Controller URL.
+Setup guides you through sign-in, installs the Agent Kit,
+and starts your coding agent.
+
+Run setup in a Linux/macOS terminal with Builder, Git and tmux installed.
+On Windows, connect to your organisation's Builder Server first.
+Your files stay under the AI Fabrix work directory on the machine running setup.
+No GitHub account or Docker is required for the default local workspace.
+
+Optional:
+  Use GitHub (requires gh):
+    aifabrix agent-kit setup <controller-url> --repo owner/project
+
+  Use Claude:
+    aifabrix agent-kit setup <controller-url> --code claude
+
+Already have a project?
+  Open its Git repository folder and install the Agent Kit:
+    aifabrix agent-kit install --host codex
+
+Using your organisation's Builder Server?
+  On your own computer, use the onboarding command your administrator gives you:
+    aifabrix dev init --developer-id <id> --server <builder-server-url> --pin <pin>
+
+  Use the SSH command printed after successful onboarding to connect.
+  Once connected to a managed workspace, run af onboarding.
+  For a portable server without managed config, use agent-kit setup above.
+  Integrator accounts use the integrator group; Docker is not needed.
+
+Controller URL: connects your workspace to AI Fabrix.
+Builder Server URL: connects your computer to the remote workspace host.
+These are different services; ask your administrator for the correct URLs.
+
+Explore:
+  aifabrix --help
+  aifabrix agent-kit --help
+  aifabrix <command> --help
+
+This guide does not sign you in, install software, or change configuration.
+`;
+
+function setupHelpCommand(program) {
+  program.addHelpCommand(false);
+  program.command('help [command]')
+    .description('Show the onboarding guide, or help for a command')
+    .addHelpText('after', '\nExamples:\n  $ aifabrix help\n  $ aifabrix help agent-kit\n')
+    .action((name, options, command) => {
+      if (!name) {
+        command.configureOutput().writeOut(ONBOARDING_GUIDE);
+        return;
+      }
+      const target = program.commands.find(item => item.name() === name || item.aliases().includes(name));
+      if (!target) command.error(`Unknown command '${name}'. Run aifabrix --help to list commands.`);
+      target.outputHelp();
+    });
+}
+
+module.exports = { setupHelpCommand, ONBOARDING_GUIDE };

package/lib/cli/setup-onboarding.js

@@ -0,0 +1,37 @@
+/** Top-level managed Agent Kit onboarding command. */
+'use strict';
+
+const logger = require('../utils/logger');
+const { formatBlockingError } = require('../utils/cli-layout-chalk');
+const { maskSensitiveData } = require('../utils/log-redaction');
+const { runManagedOnboarding } = require('../agent-kit/setup');
+
+function setupOnboardingCommand(program) {
+  program.command('onboarding')
+    .description('Prepare your provisioned Agent Kit workspace for the selected coding platform')
+    .option('--coding <platform>', 'Use claude, codex, or cursor for this run')
+    .option('--name <folder>', 'Create or reuse this workspace folder under the managed work root')
+    .option('--repo <owner/name>', 'Reuse or clone this GitHub repository, or create it privately')
+    .addHelpText('after', '\nRun on your managed workspace host after connecting by SSH.\n' +
+      'Reads ~/.aifabrix/config.yaml; --coding overrides its codingPlatform for this run only.\n' +
+      'For portable onboarding use aifabrix agent-kit setup <controllerUrl>.\n\n' +
+      'Examples:\n' +
+      '  $ af onboarding\n' +
+      '  $ af onboarding --coding claude\n' +
+      '  $ af onboarding --coding claude --name sales-workspace\n' +
+      '  $ af onboarding --coding claude --name finance-workspace\n' +
+      '  $ af onboarding --repo example-org/example-workspace\n' +
+      '  $ af onboarding --repo my-org/new-repo\n' +
+      '  $ af onboarding --coding codex\n' +
+      '  $ af onboarding --coding cursor\n')
+    .action(async(options) => {
+      try {
+        await runManagedOnboarding(options);
+      } catch (error) {
+        logger.error(formatBlockingError(maskSensitiveData(error.message)));
+        process.exitCode = 1;
+      }
+    });
+}
+
+module.exports = { setupOnboardingCommand };

package/lib/cli/setup-utility-repair.js

@@ -99,7 +99,9 @@ function logRepairDryRunOutcome(options, result, changedFiles) {
  */
 function logRepairSuccessOutcome(result, changedFiles) {
   if (result.updated) {
-    logger.log(formatSuccessParagraph('Repaired external integration config.'));
+    logger.log(formatSuccessParagraph(result.applicationReadme
+      ? 'Regenerated README.md from application configuration.'
+      : 'Repaired external integration config.'));
     logRepairChangedFiles(changedFiles, false);
     logRepairNextActions(changedFiles, result.warnings);
     return;
@@ -166,7 +168,7 @@ async function handleRepairCommand(appName, options) {
  */
 function setupRepairCommand(program) {
   program.command('repair <systemKey>')
-    .description('Fix external integration drift (files, RBAC, manifest, …)')
+    .description('Fix external integration drift or regenerate application documentation (--doc)')
     .option('--all', 'Run all repair actions (api, doc, expose, rbac, sync, test)')
     .option(
       '--api',
@@ -176,10 +178,10 @@ function setupRepairCommand(program) {
       '--auth <method>',
       'Set authentication method (oauth2, aad, apikey, bearerToken, basic, queryParam, oidc, hmac, none); updates system file and env.template'
     )
-    .option('--doc', 'Regenerate README.md from deployment manifest')
+    .option('--doc', 'Regenerate README.md from application config or external integration deployment manifest')
     .option('--expose', 'Set exposed.schema on each datasource from all fieldMappings.attributes keys (metadata.<key>); removes deprecated exposed.attributes if present')
     .option('--rbac', 'Ensure RBAC permissions per datasource and add default Admin/Reader roles if none exist; warns when capabilities lack openapi.operations (auto-syncs operations)')
-    .option('--sync', 'Add default sync section to datasources that lack it')
+    .option('--sync', 'Add enabled monthly UTC sync defaults when the sync section is absent')
     .option(
       '--auth-webhook',
       'Ensure authentications[] slot usage=webhookInbound (454 webhook inbound auth)'
@@ -197,7 +199,7 @@ function setupRepairCommand(program) {
       '--rbac-preset <preset>',
       'RBAC preset for facade APIs (e.g. platform — dataplane role catalog)'
     )
-    .option('--no-backup', 'Skip timestamped copies under integration/<systemKey>/backup/')
+    .option('--no-backup', 'Skip timestamped copies under the application folder backup/')
     .option('--dry-run', 'Report changes only; do not write')
     .addHelpText('after', REPAIR_HELP_AFTER)
     .action(async(appName, options) => {