@aifabrix/builder 2.51.0 → 2.52.0

package/lib/cli/infra-guided.js

@@ -8,8 +8,6 @@ const chalk = require('chalk');
 const logger = require('../utils/logger');
 const config = require('../core/config');
 const devConfig = require('../utils/dev-config');
-const pathsUtil = require('../utils/paths');
-const { loadConfigFile } = require('../utils/config-format');
 const { withMutedLogger } = require('../utils/with-muted-logger');
 const infra = require('../infrastructure');
 const { execWithDockerEnv } = require('../utils/docker-exec');
@@ -41,12 +39,72 @@ const {
   logUpPlatformForceCleanSummary,
   logStoppedServices
 } = require('./infra-guided-footers');
-const healthCheck = require('../utils/health-check');
 const { prepareUrlsLocalRegistryForUpPlatform } = require('../commands/up-common');
 const { assertDevInfraUp } = require('../commands/dev-infra-gate');
 const {
   emitSystemBuilderAppManifestLineIfTTY
 } = require('../utils/manifest-source-emit');
+const { flushDeferredPublicUrlWarnings } = require('./infra-guided-public-url-warn');
+
+/**
+ * Guided Keycloak → Miso Controller start with one spinner per app (no second health wait).
+ * @param {Object} options
+ * @param {Function} handleUpMiso
+ * @returns {Promise<string[]>} Deferred public-URL warning messages
+ */
+async function runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso) {
+  const deferredWarnings = [];
+  const misoSpinnerRef = { current: null };
+  emitSystemBuilderAppManifestLineIfTTY(logger, 'keycloak');
+  const kcSpin = startSpinner('Starting Keycloak...');
+  // Fully mute inner run logs — any newline (✔ / Manifest / blank) splits the ora line.
+  await withMutedLogger(
+    () =>
+      handleUpMiso({
+        ...options,
+        platformInstall: true,
+        onAfterKeycloak: () => {
+          stopSpinnerSuccess(kcSpin, 'Keycloak ready');
+          logger.log('');
+          emitSystemBuilderAppManifestLineIfTTY(logger, 'miso-controller');
+          misoSpinnerRef.current = startSpinner('Starting Miso Controller...');
+        },
+        onMisoPollText: (text) => {
+          const spin = misoSpinnerRef.current;
+          if (spin) {
+            // Keep app name; append health progress so the spinner does not look like a new step.
+            spin.text = `Starting Miso Controller… ${stripHealthPrefix(text)}`;
+            return;
+          }
+          logger.log(text);
+        },
+        onDeferredPublicUrlWarning: (message) => deferredWarnings.push(message)
+      }),
+    { allow: () => false }
+  );
+  if (misoSpinnerRef.current) {
+    stopSpinnerSuccess(misoSpinnerRef.current, 'Miso Controller ready');
+  } else {
+    stopSpinnerSuccess(kcSpin, 'Keycloak ready');
+  }
+  flushDeferredPublicUrlWarnings(deferredWarnings);
+  logger.log('');
+  return deferredWarnings;
+}
+
+/** ESC + CSI SGR — built without a control-char regex literal (no-control-regex). */
+const ANSI_SGR_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+
+/**
+ * Turn "Waiting for health check… (4/45)" into "(4/45)" for nested spinner text.
+ * @param {string} text
+ * @returns {string}
+ */
+function stripHealthPrefix(text) {
+  const raw = String(text || '');
+  const match = raw.match(/\((\d+\/\d+)\)/);
+  return match ? `(${match[1]})` : raw.replace(ANSI_SGR_RE, '').trim();
+}
 
 async function getRunningContainerNameForApp(appName) {
   const apps = await infra.getAppStatus();
@@ -86,31 +144,6 @@ async function validateAppErrorLogs(appNames) {
   logger.log('');
 }
 
-async function waitForAppReady(appName, opts = {}) {
-  const timeoutSeconds = Number.isFinite(opts.timeoutSeconds) ? opts.timeoutSeconds : 90;
-  const builderPath = pathsUtil.getBuilderPath(appName);
-  const configPath = pathsUtil.resolveApplicationConfigPath(builderPath);
-  const appConfig = loadConfigFile(configPath) || {};
-
-  const apps = await infra.getAppStatus();
-  const hit = (apps || []).find(a => a && a.name === appName && typeof a.url === 'string');
-  const portMatch = hit && hit.url ? hit.url.match(/:(\d+)$/) : null;
-  const hostPort = portMatch ? parseInt(portMatch[1], 10) : null;
-  if (!hostPort) {
-    throw new Error(`Could not determine host port for ${appName}`);
-  }
-
-  const userCfg = await config.getConfig();
-  const healthRunOpts = { profile: 'docker' };
-  if (userCfg && userCfg.traefik === true) {
-    healthRunOpts.traefikEnabled = true;
-  }
-  if (typeof opts.onPollText === 'function') {
-    healthRunOpts.onPollText = opts.onPollText;
-  }
-  await healthCheck.waitForHealthCheck(appName, timeoutSeconds, hostPort, appConfig, false, healthRunOpts);
-}
-
 function resolveInfraHost(remoteServer) {
   const raw = String(remoteServer || '').trim().replace(/\/+$/, '');
   if (!raw) return 'localhost';
@@ -179,16 +212,7 @@ async function runGuidedUpMiso(options, handleUpMiso) {
   logger.log('');
   logPlatformSetupDurationHint('platform');
   logger.log('');
-  const kcSpin = startSpinner('Starting Keycloak...');
-  await withMutedLogger(() => handleUpMiso({ ...options, platformInstall: true }));
-  stopSpinnerSuccess(kcSpin, 'Keycloak ready');
-  logger.log('');
-  const mcSpin = startSpinner('Starting Miso Controller...');
-  await waitForAppReady('miso-controller', {
-    timeoutSeconds: 120,
-    onPollText: createSpinnerTextUpdater(mcSpin)
-  });
-  stopSpinnerSuccess(mcSpin, 'Miso Controller ready');
+  await runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso);
   await logMisoReadyFooter();
   await validateAppErrorLogs(['miso-controller']);
 }
@@ -241,22 +265,6 @@ async function refreshDataplaneVersionAfterPlatformInstall() {
   }
 }
 
-async function runGuidedKeycloakAndMisoControllerPhase(options, handleUpMiso) {
-  emitSystemBuilderAppManifestLineIfTTY(logger, 'keycloak');
-  const kcSpin = startSpinner('Starting Keycloak...');
-  await withMutedLogger(() => handleUpMiso({ ...options, platformInstall: true }));
-  stopSpinnerSuccess(kcSpin, 'Keycloak ready');
-  logger.log('');
-  emitSystemBuilderAppManifestLineIfTTY(logger, 'miso-controller');
-  const mcSpin = startSpinner('Starting Miso Controller...');
-  await waitForAppReady('miso-controller', {
-    timeoutSeconds: 120,
-    onPollText: createSpinnerTextUpdater(mcSpin)
-  });
-  stopSpinnerSuccess(mcSpin, 'Miso Controller ready');
-  logger.log('');
-}
-
 async function runGuidedDataplaneInstallPhase(options, handleUpDataplane, handleLoginFn, controllerUrl) {
   logger.log('');
   emitSystemBuilderAppManifestLineIfTTY(logger, 'dataplane');
@@ -310,7 +318,7 @@ async function runGuidedUpPlatform(options, handleUpMiso, handleUpDataplane, han
   await runGuidedAuthStep(handleLogin, authOpts, { startSpinner, stopSpinnerSuccess });
   const controllerUrl = await resolveGuidedAuthControllerUrl(authOpts);
   await runGuidedDataplaneInstallPhase(options, handleUpDataplane, handleLogin, controllerUrl);
-  const baSpin = startSpinner('Starting builder-api...');
+  const baSpin = startSpinner('Starting Builder API...');
   await withMutedLogger(() => handleUpBuilderApi({ ...options, platformInstall: true }));
   stopSpinnerSuccess(baSpin, 'Builder API ready');
   await validateAppErrorLogs(['miso-controller', 'dataplane', 'builder-api']);
@@ -353,5 +361,6 @@ module.exports = {
   runGuidedUpMiso,
   runGuidedUpDataplane,
   runGuidedUpPlatform,
-  runGuidedDownInfra
+  runGuidedDownInfra,
+  stripHealthPrefix
 };

package/lib/cli/setup-app.help.js

@@ -11,6 +11,10 @@ Examples:
   $ aifabrix test hubspot -v
   $ aifabrix test hubspot -d
 
+  # Role Assistant (role-assistant/ra-<roleKey>/) — lifecycle checks
+  $ aifabrix test ra-business-transformation
+  $ aifabrix role-assistant test business-transformation
+
   # Builder app (builder/<app>/) — runs in container
   $ aifabrix test myapp -e dev
   $ aifabrix test myapp -e tst

package/lib/cli/setup-app.js

@@ -56,12 +56,16 @@ Examples:
   $ aifabrix validate hubspot-demo
   $ aifabrix upload hubspot-demo --probe
   $ aifabrix deploy hubspot-demo --probe -v
+  # Prove pillars in tst/CI, then promote (plain deploy seals cert on published Deploy)
   $ aifabrix deploy ek-sales --gate full --subject-email ops@example.com
+  $ aifabrix deploy ek-sales
 
 Notes:
   - Login or set MISO_CONTROLLER_URL + environment (aifabrix login / aifabrix auth).
   - CI: register once (aifabrix app register <appKey>), store DEV_MISO_CLIENTID and DEV_MISO_CLIENTSECRET in pipeline secrets.
   - upload = dataplane publish for dev iteration; deploy = controller validate + deploy (Azure or local Docker).
+  - Prove (tst/CI): use --gate full (optional --subject-email) before promote; plain deploy promotes without live E2E gates.
+  - After a successful published Deploy, the platform seals the integration certificate (no separate certificates issue step).
   - Default output is a compact status card; use -v for expanded preflight and readiness detail.
   - Controller deploy always polls to a terminal status (no --poll / --no-poll on this command).
   - --repository-url overrides repo URL for pipeline validate (default: application.yaml repository.repositoryUrl).

package/lib/cli/setup-app.test-commands.js

@@ -12,9 +12,56 @@ const {
   TEST_E2E_HELP_AFTER
 } = require('./setup-app.help');
 
+/** External packages that use local unit validation (not builder container tests). */
+function isExternalUnitTestWorkspace(baseDir) {
+  return baseDir === 'integration' || baseDir === 'enterprise-knowledge';
+}
+
+/**
+ * Dispatch aifabrix test by detected workspace (builder / integration / role-assistant).
+ * @param {string} appName
+ * @param {Object} options
+ * @param {Object} cmd
+ * @returns {Promise<void>}
+ */
+async function runTestCommandAction(appName, options, cmd) {
+  const rawArgs = Array.isArray(cmd?.rawArgs) ? cmd.rawArgs : [];
+  const envExplicit = rawArgs.includes('-e') || rawArgs.includes('--env');
+  const pathsUtil = require('../utils/paths');
+  const appType = await pathsUtil.detectAppType(appName).catch(() => null);
+  if (options.sync === true) {
+    throw new Error(
+      'Option --sync is not supported for aifabrix test (local or container runs do not publish to the dataplane). ' +
+        'Use: aifabrix upload <systemKey>, then aifabrix test-integration <systemKey> --sync or aifabrix datasource test-integration <datasourceKey> --sync.'
+    );
+  }
+  if (appType && appType.baseDir === 'role-assistant') {
+    const { runRoleAssistantTestAction } = require('../commands/role-assistant');
+    await runRoleAssistantTestAction(appName, options, cmd);
+    return;
+  }
+  if (appType && isExternalUnitTestWorkspace(appType.baseDir)) {
+    const test = require('../external-system/test');
+    const externalOpts = {
+      ...options,
+      // Keep help default but don't override auth/env behavior unless user explicitly set it.
+      env: envExplicit ? options.env : undefined
+    };
+    const results = await test.testExternalSystem(appName, externalOpts);
+    test.displayTestResults(results, options.verbose, appName);
+    if (!results.valid) process.exit(1);
+    return;
+  }
+  const { runAppTest } = require('../commands/app-test');
+  await runAppTest(appName, { env: options.env });
+}
+
 function setupTestCommand(program) {
   program.command('test <appKey|systemKey>')
-    .description('Tests: builder appKey in container; external systemKey = local validation')
+    .description(
+      'Tests: builder appKey in container; integration/EK = local validation; ' +
+        'role-assistant = lifecycle (same as role-assistant test)'
+    )
     .option('-e, --env <env>', 'For builder app: dev (running container) or tst (ephemeral)', 'dev')
     .option('-v, --verbose', 'Verbose output')
     .option('-d, --debug', 'Certification debug + log to integration/<systemKey>/logs/ (external only)')
@@ -25,30 +72,7 @@ function setupTestCommand(program) {
     .addHelpText('after', TEST_HELP_AFTER)
     .action(async(appName, options, cmd) => {
       try {
-        const rawArgs = Array.isArray(cmd?.rawArgs) ? cmd.rawArgs : [];
-        const envExplicit = rawArgs.includes('-e') || rawArgs.includes('--env');
-        const pathsUtil = require('../utils/paths');
-        const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-        if (options.sync === true) {
-          throw new Error(
-            'Option --sync is not supported for aifabrix test (local or container runs do not publish to the dataplane). ' +
-              'Use: aifabrix upload <systemKey>, then aifabrix test-integration <systemKey> --sync or aifabrix datasource test-integration <datasourceKey> --sync.'
-          );
-        }
-        if (appType && appType.baseDir === 'integration') {
-          const test = require('../external-system/test');
-          const externalOpts = {
-            ...options,
-            // Keep help default but don't override auth/env behavior unless user explicitly set it.
-            env: envExplicit ? options.env : undefined
-          };
-          const results = await test.testExternalSystem(appName, externalOpts);
-          test.displayTestResults(results, options.verbose, appName);
-          if (!results.valid) process.exit(1);
-          return;
-        }
-        const { runAppTest } = require('../commands/app-test');
-        await runAppTest(appName, { env: options.env });
+        await runTestCommandAction(appName, options, cmd);
       } catch (error) {
         handleCommandError(error, 'test');
         process.exit(1);
@@ -106,7 +130,14 @@ async function runTestE2ECommand(appName, options, cmd) {
         'Remove --no-publish for builder app E2E.'
     );
   }
-  if (appType && appType.baseDir === 'integration') {
+  if (appType && appType.baseDir === 'role-assistant') {
+    throw new Error(
+      `'${appName}' is a Role Assistant under role-assistant/. ` +
+        'Datasource E2E does not apply. Use: aifabrix role-assistant test <roleKey> ' +
+        '(or: aifabrix test <roleKey>).'
+    );
+  }
+  if (appType && isExternalUnitTestWorkspace(appType.baseDir)) {
     await runExternalIntegrationE2EAndExit(appName, options, cmd);
     return;
   }
@@ -122,7 +153,7 @@ function setupInstallCommand(program) {
       try {
         const pathsUtil = require('../utils/paths');
         const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-        if (appType && appType.baseDir === 'integration') {
+        if (appType && (isExternalUnitTestWorkspace(appType.baseDir) || appType.baseDir === 'role-assistant')) {
           logger.log(
             chalk.gray('Install is for builder appKey only. Use aifabrix shell <appKey> for builder apps or External Systems commands for integrations.')
           );
@@ -186,7 +217,7 @@ function setupLintCommand(program) {
       try {
         const pathsUtil = require('../utils/paths');
         const appType = await pathsUtil.detectAppType(appName).catch(() => null);
-        if (appType && appType.baseDir === 'integration') {
+        if (appType && (isExternalUnitTestWorkspace(appType.baseDir) || appType.baseDir === 'role-assistant')) {
           logger.log(chalk.gray('lint is for builder appKey only. Use aifabrix shell <appKey> then make lint or pnpm lint.'));
           return;
         }

package/lib/cli/setup-external-system-help.js

@@ -10,6 +10,7 @@ Examples:
   $ aifabrix upload hubspot-demo
   $ aifabrix upload hubspot-demo -v
   $ aifabrix upload hubspot-demo --probe
+  $ aifabrix upload hubspot-demo --timeout 600000
 
   # Build and validate payload only (no API calls)
   $ aifabrix upload hubspot-demo --dry-run
@@ -18,11 +19,16 @@ Examples:
   $ aifabrix upload .protection
   $ aifabrix upload .protection --warnings-as-errors
 
+  # Role Assistant package (settings section + Evidence sidecars)
+  $ aifabrix upload sales-representative --env dev
+
 Notes:
   - Requires login (aifabrix auth status).
-  - Reads files under integration/<systemKey>/ (system JSON, datasources, credentials).
+  - Reads files under integration/<systemKey>/ or role-assistant/<roleKey>/ for digital workers.
   - Default output is a compact readiness summary; use -v for expanded detail and server-side validate warnings.
-  - --probe runs dataplane runtime checks after publish (slower; common in Session 1).
+  - --probe runs dataplane runtime checks after publish (slower).
+  - --timeout sets publish budget in ms (HTTP client and dataplane); default 300000.
+  - --env selects role-assistant.yaml section (dev|tst|pro) for digital workers; default dev.
   - test-e2e and test-integration publish local files first by default; use --no-publish on those commands to skip.
   - After dimension/FK edits on active datasources, use --force (or test-e2e / test-integration / datasource test-* with --sync --force).
   - For one datasource only: aifabrix datasource upload <datasourceKey>

package/lib/cli/setup-external-system.js

@@ -45,13 +45,16 @@ async function handleUploadCommandAction(systemKey, options) {
     return;
   }
   const upload = require('../commands/upload');
+  const { resolvePipelineUploadTimeoutMs } = require('../api/pipeline.api');
   const probeTimeout =
     options.probeTimeout === undefined || options.probeTimeout === null
       ? 120000
       : Number(options.probeTimeout);
+  const timeoutMs = resolvePipelineUploadTimeoutMs(options.timeout);
   await upload.uploadExternalSystem(systemKey, {
     ...options,
     probeTimeout: Number.isFinite(probeTimeout) ? probeTimeout : 120000,
+    timeoutMs,
     pathOptions: {}
   });
 }
@@ -98,10 +101,19 @@ function setupUploadCommand(program) {
     .option('-v, --verbose', 'Expanded upload summary and server-side pipeline validate warnings before publish')
     .option('--probe', 'After publish, run dataplane runtime checks (validation/run); slower')
     .option('--probe-timeout <ms>', 'Timeout for --probe (default: 120000)', '120000')
+    .option(
+      '--timeout <ms>',
+      'Publish timeout in ms for HTTP and dataplane budget (default: 300000; min 5000, max 2700000)'
+    )
     .option(
       '--force',
       'Bypass schema guards on active datasources during publish (dangerous; shows a warning)'
     )
+    .option(
+      '-e, --env <env>',
+      'Role Assistant settings environment section: dev, tst, or pro (default: dev)',
+      'dev'
+    )
     .action(async(systemKey, options) => {
       try {
         await handleUploadCommandAction(systemKey, options);
@@ -147,10 +159,44 @@ function setupDeleteCommand(program) {
  * @param {Object} options - CLI options
  * @returns {Promise<boolean>} True if builder test was run, false otherwise
  */
-async function tryBuilderTestIntegration(appName, options) {
+/**
+ * @param {string} appName
+ * @param {Object} options
+ * @returns {Promise<boolean>} True if a builder-app integration test was started
+ */
+async function tryRunBuilderAppIntegration(appName, options) {
   const fsSync = require('fs');
+  const { getBuilderPath } = require('../utils/paths');
+  const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
+  const builderPath = getBuilderPath(appName);
+  if (!fsSync.existsSync(builderPath)) {
+    return false;
+  }
+  let builderConfigPath;
+  try {
+    builderConfigPath = resolveApplicationConfigPath(builderPath);
+  } catch {
+    return false;
+  }
+  if (!fsSync.existsSync(builderConfigPath)) {
+    return false;
+  }
+  const { runAppTestIntegration } = require('../commands/app-test');
+  await runAppTestIntegration(appName, {
+    env: options.env || options.environment || 'dev'
+  });
+  return true;
+}
+
+/**
+ * Prefer builder-app container tests when no externalIntegration folder exists.
+ * @param {string} appName - App or system key
+ * @param {Object} options - CLI options
+ * @returns {Promise<boolean>} True if builder test was run, false otherwise
+ */
+async function tryBuilderTestIntegration(appName, options) {
   const pathsUtil = require('../utils/paths');
-  const { getIntegrationPath, getBuilderPath } = pathsUtil;
+  const { getIntegrationPath } = pathsUtil;
   const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
   const { loadConfigFile } = require('../utils/config-format');
   const integrationPath = getIntegrationPath(appName);
@@ -161,17 +207,10 @@ async function tryBuilderTestIntegration(appName, options) {
   } catch {
     // integration path or config missing
   }
-  if (!hasExternalIntegration) {
-    const builderPath = getBuilderPath(appName);
-    const builderConfigPath = resolveApplicationConfigPath(builderPath);
-    if (fsSync.existsSync(builderPath) && fsSync.existsSync(builderConfigPath)) {
-      const { runAppTestIntegration } = require('../commands/app-test');
-      const opts = { env: options.env || options.environment || 'dev' };
-      await runAppTestIntegration(appName, opts);
-      return true;
-    }
+  if (hasExternalIntegration) {
+    return false;
   }
-  return false;
+  return tryRunBuilderAppIntegration(appName, options);
 }
 
 /**
@@ -221,6 +260,17 @@ async function runTestIntegrationCommand(appName, options) {
     await runAppTestIntegration(appName, opts);
     return;
   }
+  // Role Assistant / EK / integration packages must use the dataplane path — do not
+  // probe builder/<app> (resolveApplicationConfigPath throws when the folder is absent).
+  if (
+    appType &&
+    (appType.baseDir === 'role-assistant' ||
+      appType.baseDir === 'enterprise-knowledge' ||
+      appType.baseDir === 'integration')
+  ) {
+    await runExternalSystemTestIntegration(appName, options);
+    return;
+  }
   const ranBuilder = await tryBuilderTestIntegration(appName, options);
   if (ranBuilder) {
     if (options.sync === true) {

package/lib/commands/app-test.js

@@ -166,20 +166,8 @@ async function runDockerExec(containerName, testCmd, envFilePath = null) {
  * @returns {Promise<number>} Exit code
  */
 async function runDockerRunEphemeral(fullImage, testCmd, envFilePath = null) {
-  const { getDockerExecEnv } = require('../utils/remote-docker-env');
-  const dockerEnv = await getDockerExecEnv();
-  return new Promise((resolve) => {
-    const args = ['run', '--rm'];
-    if (envFilePath) args.push('--env-file', envFilePath);
-    args.push(fullImage, 'sh', '-c', testCmd);
-    const proc = spawn('docker', args, {
-      stdio: 'inherit',
-      shell: false,
-      env: dockerEnv
-    });
-    proc.on('close', code => resolve(code !== null ? code : 1));
-    proc.on('error', () => resolve(1));
-  });
+  const { runDockerRunEphemeral: runEphemeral } = require('../utils/docker-run-ephemeral');
+  return runEphemeral(fullImage, testCmd, envFilePath);
 }
 
 /**

package/lib/commands/channel-add-setup.js

@@ -9,15 +9,21 @@
 const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { formatBlockingError } = require('../utils/cli-test-layout-chalk');
-const { isChannelTargetKey } = require('../channels/channel-targets');
+const {
+  formatSupportedChannelTargetsHelp,
+  isChannelTargetKey
+} = require('../channels/channel-targets');
 const { addChannelCommand } = require('../channels/add-channel');
 
 const CHANNEL_ADD_HELP_AFTER = `
+${formatSupportedChannelTargetsHelp()}
 
 Examples:
   # After upload/deploy of the communication external system
   $ aifabrix channel add slack --name "Elsa"
   $ aifabrix channel add teams-bot --name "Elsa" --description "Enterprise AI assistant for employees"
+  $ aifabrix channel add chatgpt --name "Your Assistant"
+  $ aifabrix channel add microsoft-copilot --name "Your Assistant"
 
   # Slack slash-command prefix (registers /{prefix}-help in manifest)
   $ aifabrix channel add slack --name "Elsa" --command-prefix af
@@ -49,7 +55,7 @@ async function runChannelAddAction(channelTarget, options, meta = {}) {
   }
   if (!isChannelTargetKey(channelTarget)) {
     throw new Error(
-      `Unknown channel target "${channelTarget}". Use teams-bot, slack, microsoft-copilot, or chatgpt.`
+      `Unknown channel target "${channelTarget}". ${formatSupportedChannelTargetsHelp()}`
     );
   }
   await addChannelCommand(channelTarget, {

package/lib/commands/channel.js

@@ -16,7 +16,10 @@ const {
   sectionTitle,
   metadata
 } = require('../utils/cli-test-layout-chalk');
-const { CHANNEL_TARGET_KEYS, isChannelTargetKey } = require('../channels/channel-targets');
+const {
+  formatSupportedChannelTargetsHelp,
+  isChannelTargetKey
+} = require('../channels/channel-targets');
 const { scaffoldChannelIntegration } = require('../channels/channel-integration-generator');
 const { registerChannelAddCommand } = require('./channel-add-setup');
 
@@ -25,9 +28,7 @@ Subcommands:
   scaffold <target>   Create integration/<target>/ files locally (step 1)
   add <target>        Channel install guide + manifest/credential patch (step 3)
 
-Targets:
-  teams-bot, slack, microsoft-copilot, chatgpt
-  web-embed (experimental — scaffold with --allow-experimental)
+${formatSupportedChannelTargetsHelp()}
 
 Typical flow (channels are connected systems, not controller apps):
   aifabrix channel scaffold slack
@@ -39,6 +40,15 @@ Controller pipeline apps only: aifabrix app register · aifabrix app list
 Requires: aifabrix login (for add)
 `;
 
+const CHANNEL_SCAFFOLD_HELP_AFTER = `
+${formatSupportedChannelTargetsHelp()}
+
+Typical flow:
+  aifabrix channel scaffold slack
+  aifabrix upload slack --force
+  aifabrix channel add slack --name "Your Assistant" --probe
+`;
+
 /**
  * @param {import('commander').Command} program
  */
@@ -57,11 +67,12 @@ function setupChannelCommands(program) {
     )
     .option('--force', 'Overwrite generated scaffold files when folder exists')
     .option('--allow-experimental', 'Allow web-embed scaffold')
+    .addHelpText('after', CHANNEL_SCAFFOLD_HELP_AFTER)
     .action(async(channelTarget, options) => {
       try {
         if (!isChannelTargetKey(channelTarget)) {
           throw new Error(
-            `Unknown channel target "${channelTarget}". Expected: ${CHANNEL_TARGET_KEYS.join(', ')}`
+            `Unknown channel target "${channelTarget}". ${formatSupportedChannelTargetsHelp()}`
           );
         }
         const result = await scaffoldChannelIntegration(channelTarget, {

package/lib/commands/datasource-load-export-cli.js

@@ -76,7 +76,8 @@ async function datasourceLoadAction(datasourceKey, options) {
       dryRun: options.dryRun,
       batchSize: options.batchSize,
       syncType: options.syncType,
-      format: options.format
+      format: options.format,
+      timeoutMs: options.timeout
     });
 
     if (options.json) {
@@ -141,6 +142,10 @@ function setupDatasourceLoadExportCommands(datasource) {
       'Dataplane syncType',
       'incremental'
     )
+    .option(
+      '--timeout <ms>',
+      'Per-batch HTTP timeout for records/bulk (default 120000)'
+    )
     .option('--dry-run', 'Parse and validate only; no upload')
     .option('-v, --verbose', 'Per-batch progress')
     .option('--json', 'Machine-readable result JSON')

package/lib/commands/deploy-gate-failure-details.js

@@ -113,6 +113,24 @@ function formatOperationsGateFailure(result) {
   return 'E2E validation did not succeed for one or more datasources';
 }
 
+/**
+ * @param {Object} row
+ * @returns {string|null}
+ */
+function formatFailedDatasourceRowHint(row) {
+  if (!row || row.success !== false) {
+    return null;
+  }
+  const key = row.key || row.datasourceKey || 'datasource';
+  const issues = row.datasourceTestRun?.validation?.issues;
+  if (Array.isArray(issues) && issues.length > 0) {
+    const first = issues[0];
+    const code = first.code ? `${first.code}: ` : '';
+    return `${key}: ${code}${first.message || 'validation failed'}`;
+  }
+  return row.error ? `${key}: ${row.error}` : null;
+}
+
 /**
  * @param {Object} result
  * @returns {string}
@@ -125,23 +143,7 @@ function formatIntegrationGateFailure(result) {
     return String(result.message);
   }
   const rows = Array.isArray(result?.datasourceResults) ? result.datasourceResults : [];
-  const hints = [];
-  for (const row of rows) {
-    if (!row || row.success !== false) {
-      continue;
-    }
-    const key = row.key || row.datasourceKey || 'datasource';
-    const issues = row.datasourceTestRun?.validation?.issues;
-    if (Array.isArray(issues) && issues.length > 0) {
-      const first = issues[0];
-      const code = first.code ? `${first.code}: ` : '';
-      hints.push(`${key}: ${code}${first.message || 'validation failed'}`);
-      continue;
-    }
-    if (row.error) {
-      hints.push(`${key}: ${row.error}`);
-    }
-  }
+  const hints = rows.map(formatFailedDatasourceRowHint).filter(Boolean);
   if (hints.length > 0) {
     return hints.slice(0, 3).join('; ');
   }

package/lib/commands/deploy-gate-orchestrator.js

@@ -142,7 +142,6 @@ async function runDeployBaselineSteps(systemKey, options) {
       uploadStatus: 'published',
       minimal: true,
       suppressSummary: true,
-      suppressPipelineSpinner: true,
       uploadContext: 'deploy-preflight'
     });
     stepOptions = mergeUploadAuthOptions({ ...options, uploadStatus: 'published' }, uploadCtx);
@@ -322,7 +321,9 @@ function inferGatePillarFromLabel(label) {
  * @returns {Promise<{ baseline: { unitPassed: boolean, integrationPassed: boolean }, gates: Object[] }>}
  */
 async function runDeployGateOrchestrator(systemKey, options = {}) {
-  const quiet = options.quietDeployUi === true || options.verbose !== true;
+  // Default: show unit/integration/publish progress (parity with upload).
+  // Only hush when caller opts in (json / explicit quietDeployUi).
+  const quiet = options.quietDeployUi === true;
   if (!quiet) {
     logger.log('');
     logger.log(sectionTitle('Deploy preflight'));