@aifabrix/builder 2.51.1 → 2.52.1

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']);
@@ -323,23 +331,30 @@ async function runGuidedDownInfra(appName, options, infraMod, appLib) {
   logger.log(SEPARATOR);
   logger.log('');
 
+  const targetDeveloperId = options && options.developerId;
   const spin = startSpinner('Stopping infrastructure...');
   await withMutedLogger(async() => {
     if (typeof appName === 'string' && appName.trim().length > 0) {
-      await appLib.downApp(appName, { volumes: !!options.volumes });
+      await appLib.downApp(appName, {
+        volumes: !!options.volumes,
+        developerId: targetDeveloperId
+      });
       return;
     }
-    if (options.volumes) await infraMod.stopInfraWithVolumes();
-    else await infraMod.stopInfra();
+    if (options.volumes) await infraMod.stopInfraWithVolumes(targetDeveloperId);
+    else await infraMod.stopInfra(targetDeveloperId);
   });
   stopSpinnerSuccess(spin, 'Infrastructure stopped');
 
-  const developerId = await config.getDeveloperId();
-  const idNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
+  const developerId = String(
+    targetDeveloperId !== undefined && targetDeveloperId !== null && targetDeveloperId !== ''
+      ? targetDeveloperId
+      : await config.getDeveloperId()
+  );
   const cfg = await config.getConfig();
 
   logFooterStart('Stopped');
-  logSection('Developer', `dev${String(idNum).padStart(2, '0')} (id: ${idNum})`);
+  logSection('Developer', `dev${developerId.padStart(2, '0')} (id: ${developerId})`);
   logStoppedServices(cfg);
   if (options.volumes) {
     logger.log(chalk.yellow('⚠ Volumes removed: all local data deleted'));
@@ -353,5 +368,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.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.js

@@ -159,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);
@@ -173,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);
 }
 
 /**
@@ -233,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/cli/setup-infra.js

@@ -31,6 +31,9 @@ const {
   getRestartableInfraServiceNames,
   buildRestartInfraHelpLines
 } = require('../constants/infra-compose-service-names');
+const {
+  resolveTransientDeveloperIdFromOptions
+} = require('../utils/transient-developer-id');
 
 const {
   computeEffectiveInfraOptionalFlags,
@@ -97,6 +100,18 @@ async function applyDeveloperIdFromUpInfra(options) {
   return id;
 }
 
+const DOWN_INFRA_HELP_AFTER = `
+Examples:
+  $ aifabrix down-infra
+  $ aifabrix down-infra --volumes
+  $ aifabrix down-infra --developer-id 02
+  $ aifabrix down-infra -d 02 --volumes
+  $ aifabrix down-infra myapp --developer-id 02
+
+--developer-id / -d target another developer's stack for this command only.
+They do not change developer-id in config.
+`;
+
 /**
  * @param {Object} options
  * @param {Object} cfg - Mutable config from getConfig()
@@ -302,20 +317,32 @@ function setupUpBuilderApiCommand(program) {
 function setupDownInfraCommand(program) {
   program.command('down-infra [service|app]')
     .description('Stop all infra, or stop one app; use -v to remove volumes')
+    .addHelpText('after', DOWN_INFRA_HELP_AFTER)
     .option('-v, --volumes', 'Remove volumes (deletes all data)')
     .option('--verbose', 'Show full orchestration output (default is guided summary)')
+    .option(
+      '-d, --developer <id>',
+      'Target developer ID for this stop only (does not change config)'
+    )
+    .option(
+      '--developer-id <id>',
+      'Same as --developer; target another developer without changing config'
+    )
     .action(async(appName, options) => {
       try {
+        const developerId = resolveTransientDeveloperIdFromOptions(options);
+        const opts = { ...options, developerId };
         if (!options.verbose) {
-          await runGuidedDownInfra(appName, options, infra, appLib);
+          await runGuidedDownInfra(appName, opts, infra, appLib);
           return;
         }
 
         if (typeof appName === 'string' && appName.trim().length > 0) {
-          await appLib.downApp(appName, { volumes: !!options.volumes });
+          await appLib.downApp(appName, { volumes: !!options.volumes, developerId });
+        } else if (options.volumes) {
+          await infra.stopInfraWithVolumes(developerId);
         } else {
-          if (options.volumes) await infra.stopInfraWithVolumes();
-          else await infra.stopInfra();
+          await infra.stopInfra(developerId);
         }
       } catch (error) {
         handleCommandError(error, 'down-infra');

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

@@ -9,29 +9,45 @@
 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()}
+
+One command covers scaffold → upload → install:
+  $ aifabrix channel add slack --name "Elsa" --probe
 
 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" \\
+      --oauth-plugin-vault-reference-id "<Teams-Entra-SSO-auth-config-id>"
 
   # Slack slash-command prefix (registers /{prefix}-help in manifest)
   $ aifabrix channel add slack --name "Elsa" --command-prefix af
 
-  # Generate artifacts only; no dataplane patch
+  # Generate artifacts only; no dataplane patch / upload
   $ aifabrix channel add slack --name "Elsa" --dry-run
 
-  # Regenerate artifacts and patch config (does not rotate secrets)
+  # Re-upload communication system + regenerate channel config (does not rotate secrets)
   $ aifabrix channel add slack --name "Elsa" --force
 
   # Validate callbacks and assistant catalog after install
   $ aifabrix channel add slack --name "Elsa" --probe
 
-Prerequisites: aifabrix upload <target> (or deploy) and aifabrix login
+Behavior:
+  - Scaffolds integration/<target>/ when missing (does not overwrite existing files)
+  - Uploads when the system is not on the dataplane; with --force uploads every time
+  - Then configures the channel install (artifacts, credentials, admin guide)
+  - microsoft-copilot uses Entra SSO (trustedIssuer); pass --oauth-plugin-vault-reference-id
+    from Teams Developer Portal. Does not create Fabrix oauth2 channel credentials.
+
+Requires: aifabrix login
 `;
 
 /**
@@ -49,7 +65,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, {
@@ -58,6 +74,7 @@ async function runChannelAddAction(channelTarget, options, meta = {}) {
     icon: options.icon,
     template: options.template,
     commandPrefix: options.commandPrefix,
+    oauthPluginVaultReferenceId: options.oauthPluginVaultReferenceId,
     dryRun: options.dryRun === true,
     force: options.force === true,
     probe: options.probe === true
@@ -71,7 +88,7 @@ async function runChannelAddAction(channelTarget, options, meta = {}) {
  */
 function registerChannelAddCommand(parent, meta = {}) {
   const description =
-    'Configure channel install (manifest, credentials, admin guide) after upload/deploy';
+    'Scaffold (if needed), upload (if needed/--force), then configure channel install';
   const commandName = meta.commandName || 'add <channelTarget>';
   const cmd = meta.hidden
     ? parent.command(commandName, { hidden: true })
@@ -82,12 +99,19 @@ function registerChannelAddCommand(parent, meta = {}) {
     .option('-d, --description <text>', 'Channel description (default generated)')
     .option('--icon <path>', 'Path to channel icon asset')
     .option('--template <name>', 'Template override (default from channel target)')
-    .option('--dry-run', 'Generate artifacts only; do not patch external system or credentials')
-    .option('--force', 'Regenerate artifacts and patch config (does not rotate secrets)')
+    .option('--dry-run', 'Generate artifacts only; do not upload, patch, or set credentials')
+    .option(
+      '--force',
+      'Re-upload communication system and regenerate channel config (does not rotate secrets)'
+    )
     .option(
       '--command-prefix <key>',
       'Slack slash alias prefix (default af) — registers /{prefix}-help etc. in manifest'
     )
+    .option(
+      '--oauth-plugin-vault-reference-id <id>',
+      'Teams Developer Portal Entra SSO OAuth auth-config id (microsoft-copilot)'
+    )
     .option('--probe', 'After install, validate callbacks and assistant catalog')
     .addHelpText('after', CHANNEL_ADD_HELP_AFTER)
     .action(async(channelTarget, options) => {
@@ -95,7 +119,8 @@ function registerChannelAddCommand(parent, meta = {}) {
         await runChannelAddAction(channelTarget, options, meta);
       } catch (error) {
         if (!error.message?.includes('Authentication required')) {
-          logger.error(formatBlockingError('Channel install failed:'), error.message);
+          const detail = error.message || String(error);
+          logger.error(formatBlockingError(`Channel install failed:\n${detail}`));
         }
         process.exit(1);
       }