@aifabrix/builder 2.53.0 → 2.54.1

package/lib/channels/approval-guides/index.js

@@ -15,7 +15,10 @@ const { buildSlackApprovalGuide } = require('./slack');
 const { buildTeamsBotApprovalGuide } = require('./teams-bot');
 const { buildMicrosoftCopilotApprovalGuide } = require('./microsoft-copilot');
 const { buildChatGptApprovalGuide } = require('./chatgpt');
+const { buildClaudeApprovalGuide } = require('./claude');
 const { buildWebEmbedInstallGuide } = require('./web-embed');
+const { buildMcpClientInstallGuide } = require('./mcp-client');
+const { vendorFacingUrlsFromCtx } = require('../vendor-dataplane-url');
 const { buildCredentialPortalUrl } = require('./credential-portal');
 
 /** @type {Record<string, (ctx: Object) => { portalUrl: string|null, steps: string[] }>} */
@@ -24,6 +27,8 @@ const GUIDE_BUILDERS = {
   'teams-bot': buildTeamsBotApprovalGuide,
   'microsoft-copilot': buildMicrosoftCopilotApprovalGuide,
   chatgpt: buildChatGptApprovalGuide,
+  claude: buildClaudeApprovalGuide,
+  'mcp-client': buildMcpClientInstallGuide,
   'web-embed': buildWebEmbedInstallGuide
 };
 
@@ -51,50 +56,110 @@ function buildResumeCommand(channelTarget, name) {
 
 /**
  * @param {string} channelTarget
- * @param {Object} [context]
+ * @param {Object} context
+ * @param {Object} target
  * @returns {Object}
  */
-function buildChannelApprovalGuide(channelTarget, context = {}) {
-  const target = getChannelTarget(channelTarget);
-  const builder = GUIDE_BUILDERS[channelTarget];
-  if (!builder) {
-    throw new Error(`No approval guide for channel target "${channelTarget}"`);
-  }
-
+function approvalGuideContext(channelTarget, context, target) {
   const projectRoot = context.projectRoot || process.cwd();
   const name = context.name || '';
+  const baseName = context.baseName || name;
   const artifactPath = resolveArtifactPath(projectRoot, channelTarget, context.artifactPath);
-  const installGuidePath = path.join(path.dirname(artifactPath), 'INSTALL.md');
-  const resumeCommand = buildResumeCommand(channelTarget, name);
-  const credentialPortalUrl = context.dataplaneBaseUrl
-    ? buildCredentialPortalUrl(context.dataplaneBaseUrl, channelTarget)
-    : null;
-  const baseCtx = {
+  const resumeName = channelTarget === 'chatgpt' || channelTarget === 'claude' ? baseName : name;
+  return {
     channelTarget,
     name,
-    baseName: context.baseName || name,
+    baseName,
     environment: context.environment || 'dev',
     artifactPath,
-    resumeCommand,
+    installGuidePath: path.join(path.dirname(artifactPath), 'INSTALL.md'),
+    resumeCommand: buildResumeCommand(channelTarget, resumeName),
     credentialKey: target.credentialKey,
-    credentialPortalUrl
+    credentialPortalUrl: context.dataplaneBaseUrl
+      ? buildCredentialPortalUrl(context.dataplaneBaseUrl, channelTarget)
+      : null,
+    controllerUrl: context.controllerUrl,
+    oauth2ProfileUrl: context.oauth2ProfileUrl,
+    mcpUrl: context.mcpUrl,
+    appName: context.appName || name,
+    description: context.description,
+    authorizationUrl: context.authorizationUrl,
+    tokenUrl: context.tokenUrl,
+    clientId: context.clientId
   };
+}
 
-  const guide = builder(baseCtx);
+/**
+ * @param {Object} context
+ * @param {Object} guide
+ * @param {string} channelTarget
+ * @returns {string|null}
+ */
+function approvalGuideCredentialUrl(channelTarget, context, guide) {
+  if (guide.credentialPortalUrl !== undefined) {
+    return guide.credentialPortalUrl;
+  }
+  if (!context.dataplaneBaseUrl) {
+    return null;
+  }
+  return buildCredentialPortalUrl(context.dataplaneBaseUrl, channelTarget);
+}
 
+/**
+ * @param {string} channelTarget
+ * @param {Object} [context]
+ * @returns {Object}
+ */
+function buildChannelApprovalGuide(channelTarget, context = {}) {
+  const target = getChannelTarget(channelTarget);
+  const builder = GUIDE_BUILDERS[channelTarget];
+  if (!builder) {
+    throw new Error(`No approval guide for channel target "${channelTarget}"`);
+  }
+  const baseCtx = approvalGuideContext(channelTarget, context, target);
+  const guide = builder(baseCtx);
   return {
     channelTarget,
+    heading: guide.heading,
     portalUrl: guide.portalUrl,
-    artifactPath,
-    installGuidePath,
-    resumeCommand,
+    artifactPath: baseCtx.artifactPath,
+    installGuidePath: baseCtx.installGuidePath,
+    resumeCommand: baseCtx.resumeCommand,
     credentialKey: target.credentialKey,
-    credentialPortalUrl,
+    credentialPortalUrl: approvalGuideCredentialUrl(channelTarget, context, guide),
     steps: guide.steps,
     approvalRequired: target.approvalRequired === true
   };
 }
 
+/**
+ * @param {Object} params
+ * @returns {Object|null}
+ */
+function buildLiveInstallApprovalGuide(params) {
+  const { channelTarget, status, artifact, name, baseName, ctx, options } = params;
+  if (status !== 'approvalRequired') {
+    return null;
+  }
+  const runtimeValues = params.runtimeValues || {};
+  const asMetadata = params.preflight && params.preflight.asMetadata;
+  const vendor = vendorFacingUrlsFromCtx(ctx);
+  return buildChannelApprovalGuide(channelTarget, {
+    projectRoot: options.projectRoot || process.cwd(),
+    name,
+    baseName,
+    artifactPath: artifact.outputPath,
+    dataplaneBaseUrl: vendor.dataplaneBaseUrl,
+    controllerUrl: vendor.controllerUrl,
+    environment: ctx.environment || options.environment || 'dev',
+    oauth2ProfileUrl: runtimeValues.oauth2ProfileUrl,
+    mcpUrl: runtimeValues.mcpUrl,
+    description: runtimeValues.appDescription,
+    authorizationUrl: asMetadata && asMetadata.authorization_endpoint,
+    tokenUrl: asMetadata && asMetadata.token_endpoint
+  });
+}
+
 /**
  * @param {string} channelTarget
  * @param {Object} [context]
@@ -107,6 +172,7 @@ function resolveApprovalPortalUrl(channelTarget, context = {}) {
 module.exports = {
   GUIDE_BUILDERS,
   buildChannelApprovalGuide,
+  buildLiveInstallApprovalGuide,
   resolveApprovalPortalUrl,
   resolveArtifactPath,
   buildResumeCommand

package/lib/channels/approval-guides/mcp-client.js

@@ -0,0 +1,27 @@
+/**
+ * Developer MCP client go-live steps — reload the editor after mcp.json merge.
+ *
+ * @fileoverview Remaining operator step for mcp-client
+ */
+
+'use strict';
+
+/**
+ * @param {Object} ctx
+ * @returns {{ heading: string, portalUrl: null, steps: string[], credentialPortalUrl: null }}
+ */
+function buildMcpClientInstallGuide(ctx) {
+  const profile = ctx.mcpClientProfileKey || '<profile>';
+  return {
+    heading: 'Reload the editor',
+    portalUrl: null,
+    credentialPortalUrl: null,
+    steps: [
+      'Reload the editor so it reads the merged MCP client config.',
+      'Sign in with your user account when the editor starts OAuth.',
+      `Re-run: aifabrix channel add mcp-client --target ${profile} --name "${ctx.name || ''}"`
+    ]
+  };
+}
+
+module.exports = { buildMcpClientInstallGuide };

package/lib/channels/approval-guides/microsoft-copilot.js

@@ -8,8 +8,53 @@
 
 'use strict';
 
+const fs = require('../../internal/fs-real-sync');
+const path = require('path');
+
 const DEVELOPER_PORTAL_URL = 'https://dev.teams.microsoft.com/';
+const DEVELOPER_PORTAL_APPS_URL = 'https://dev.teams.microsoft.com/apps';
 const TEAMS_ADMIN_APPS_URL = 'https://admin.teams.microsoft.com/policies/manage-apps';
+const TEAMS_APP_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Developer Portal publish-to-org page for a packaged Teams app id.
+ * @param {string} [appId]
+ * @returns {string}
+ */
+function developerPortalPublishOrgUrl(appId) {
+  const id = typeof appId === 'string' ? appId.trim() : '';
+  if (!TEAMS_APP_ID.test(id)) {
+    return DEVELOPER_PORTAL_APPS_URL;
+  }
+  return `${DEVELOPER_PORTAL_APPS_URL}/${id}/publish-org`;
+}
+
+/**
+ * Packaged Teams app / manifest id from runtime values or the built source manifest.
+ * @param {Object|null} ctx
+ * @param {Object|null} runtimeValues
+ * @returns {string}
+ */
+function copilotPackageAppId(ctx, runtimeValues) {
+  const fromRuntime =
+    runtimeValues && typeof runtimeValues.packageAppId === 'string'
+      ? runtimeValues.packageAppId.trim()
+      : '';
+  if (fromRuntime) {
+    return fromRuntime;
+  }
+  const root = ctx && typeof ctx.projectRoot === 'string' ? ctx.projectRoot.trim() : '';
+  if (!root) {
+    return '';
+  }
+  try {
+    const manifestPath = path.join(root, 'dist', 'channels', 'microsoft-copilot', 'source', 'manifest.json');
+    const parsed = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    return typeof parsed.id === 'string' ? parsed.id.trim() : '';
+  } catch {
+    return '';
+  }
+}
 
 /**
  * @param {Object} ctx
@@ -25,14 +70,15 @@ function buildMicrosoftCopilotApprovalGuide(ctx) {
     (typeof ctx.baseName === 'string' && ctx.baseName.trim()) ||
     'your app';
   return {
-    portalUrl: DEVELOPER_PORTAL_URL,
+    portalUrl: DEVELOPER_PORTAL_APPS_URL,
+    heading: 'Organisation publish / Teams admin approval required',
     steps: [
-      `Open Teams Developer Portal (${DEVELOPER_PORTAL_URL}).`,
+      `Open Teams Developer Portal (${DEVELOPER_PORTAL_APPS_URL}).`,
       `Click Import an app → import ${zipName}. Preserve the generated stable manifest.json.id. Do not create an unrelated new Teams app.`,
       'Developer Portal → selected app → Publish to your org → Distribute / submit.',
       `Teams admin approves in ${TEAMS_ADMIN_APPS_URL} (Manage apps → search → allow). Expect Published / Unblocked per organisation policy. Allow several minutes for propagation.`,
       `Open Teams → Apps (Built for your org), click "${appName}", Add the application, then choose Open with Copilot.`,
-      'In Copilot, click "Show my role assistants" and run the command.',
+      'In Copilot, click a conversation starter titled like "vX.Y.Z — Role Assistants" and run it.',
       'Confirm Runtime MCP and governed tools using INSTALL.md, then re-run with --probe after organisation publish.',
       `After the app is available under Built for your org, re-run: ${ctx.resumeCommand}`
     ]
@@ -41,6 +87,9 @@ function buildMicrosoftCopilotApprovalGuide(ctx) {
 
 module.exports = {
   buildMicrosoftCopilotApprovalGuide,
+  copilotPackageAppId,
+  developerPortalPublishOrgUrl,
   DEVELOPER_PORTAL_URL,
+  DEVELOPER_PORTAL_APPS_URL,
   TEAMS_ADMIN_APPS_URL
 };

package/lib/channels/approval-guides/slack.js

@@ -1,9 +1,9 @@
 /**
- * Slack channel admin approval steps (plan 152).
+ * Slack channel admin approval steps (plan 152 / 176).
  *
- * @fileoverview Slack app manifest install guide
+ * @fileoverview Automated Slack CLI path first; manifest paste is recovery
  * @author AI Fabrix Team
- * @version 1.0.0
+ * @version 1.1.0
  */
 
 'use strict';
@@ -17,14 +17,14 @@ const { formatCredentialPortalStep } = require('./credential-portal');
 function buildSlackApprovalGuide(ctx) {
   return {
     portalUrl: 'https://api.slack.com/apps',
+    heading: 'Slack workspace approval',
     steps: [
-      'Open https://api.slack.com/apps and sign in as a Slack workspace admin.',
-      'Click Create New App → From an app manifest.',
-      'Select your workspace, then paste or upload the Slack app manifest (path shown below).',
-      'Review callback URLs and OAuth scopes (pre-filled from AI Fabrix), then create the app.',
-      'Open Install App → Install to Workspace and approve the installation.',
-      'Copy the Bot User OAuth Token and Signing Secret from the Slack app settings.',
-      formatCredentialPortalStep(ctx, 'the Bot User OAuth Token and Signing Secret'),
+      'Open https://api.slack.com/apps only if channel add could not create the app (recovery).',
+      'Preferred: paste the slash command from Next actions in Slack, then paste the challenge code and continue.',
+      'Approve the Slack workspace install if Slack prompts.',
+      'Recovery: Create New App → From an app manifest, then paste or upload the generated Slack app manifest (path shown below).',
+      'Recovery only: copy the Bot User OAuth Token and Signing Secret from Slack app settings.',
+      formatCredentialPortalStep(ctx, 'the Bot User OAuth Token and Signing Secret (recovery only)'),
       `When Slack shows the app as installed, re-run: ${ctx.resumeCommand}`,
       'Optional: add --probe to verify callbacks and the assistant catalog.'
     ]

package/lib/channels/approval-guides/teams-bot.js

@@ -1,14 +1,14 @@
 /**
- * Microsoft Teams bot channel admin approval steps (plan 152).
+ * Microsoft Teams bot channel admin approval steps.
  *
- * @fileoverview Teams Developer Portal + Azure Bot registration guide
+ * @fileoverview Tenant policy / org publish after Azure-managed bot provision
  * @author AI Fabrix Team
  * @version 1.0.0
  */
 
 'use strict';
 
-const { formatCredentialPortalStep } = require('./credential-portal');
+const { TEAMS_ADMIN_APPS_URL, TEAMS_OPEN_URL, TEAMS_POLICY_REMAINING } = require('../microsoft-provisioning/constants');
 
 /**
  * @param {Object} ctx
@@ -16,16 +16,12 @@ const { formatCredentialPortalStep } = require('./credential-portal');
  */
 function buildTeamsBotApprovalGuide(ctx) {
   return {
-    portalUrl: 'https://dev.teams.microsoft.com/',
+    portalUrl: TEAMS_OPEN_URL,
+    heading: 'Tenant policy / org publish may still be required',
     steps: [
-      'Open the Teams Developer Portal (https://dev.teams.microsoft.com/) as a Teams tenant admin.',
-      'Create a new app or import the Bot Framework manifest JSON (path shown below).',
-      'Set the bot messaging endpoint to the Bot messages URL in INSTALL.md (your dataplane /messages route).',
-      'In Azure Portal, register or link the Azure Bot resource and copy the Microsoft App ID.',
-      'Create a client secret (or upload certificate) for the bot app registration in Microsoft Entra.',
-      'Enable the Microsoft Teams channel on the Azure Bot resource.',
-      formatCredentialPortalStep(ctx, 'the Microsoft App ID and client secret'),
-      'Publish the app to your org (or sideload for lab) and complete tenant admin approval if prompted.',
+      `Open Teams (${TEAMS_OPEN_URL}) and install the generated package if sideloading is allowed.`,
+      TEAMS_POLICY_REMAINING,
+      `If custom app upload is restricted, approve in Teams admin centre: ${TEAMS_ADMIN_APPS_URL}`,
       `After the bot is live in Teams, re-run: ${ctx.resumeCommand}`,
       'Optional: add --probe to verify inbound JWT validation and the assistant catalog.'
     ]

package/lib/channels/channel-add-continuations.js

@@ -0,0 +1,91 @@
+/**
+ * Vendor preflight and continuation dispatch for channel add.
+ *
+ * @fileoverview Keep add-channel.js under the file-size limit
+ */
+
+'use strict';
+
+const {
+  maybeAssertChatGptPreflight,
+  maybeRunChatGptContinuation
+} = require('./chatgpt-channel-add');
+const {
+  maybeAssertMcpClientPreflight,
+  maybeRunMcpClientContinuation
+} = require('./mcp-client-channel-add');
+const {
+  maybeAssertClaudePreflight,
+  maybeRunClaudeContinuation
+} = require('./claude-channel-add');
+const { assertIntegrationClientPermissions } = require('./channel-oauth-preflight');
+
+/**
+ * @param {Object} params
+ * @returns {Promise<void>}
+ */
+async function maybeAssertIntegrationClientPermissions(params) {
+  const ctx = params.ctx;
+  if (!ctx || (params.options && params.options.dryRun === true)) {
+    return;
+  }
+  const token = (ctx.authConfig && ctx.authConfig.token) || ctx.bearerToken;
+  if (!token || !ctx.controllerUrl) {
+    return;
+  }
+  await assertIntegrationClientPermissions(
+    {
+      controllerUrl: ctx.controllerUrl,
+      environment: ctx.environment,
+      bearerToken: token
+    },
+    params.channelTarget,
+    params.deps || {}
+  );
+}
+
+/**
+ * @param {Object} params
+ * @returns {Promise<void>}
+ */
+async function runChannelAddPreflights(params) {
+  await maybeAssertIntegrationClientPermissions(params);
+  await maybeAssertChatGptPreflight(params);
+  await maybeAssertMcpClientPreflight(params);
+  await maybeAssertClaudePreflight(params);
+}
+
+/**
+ * @param {Object} params
+ * @returns {Promise<void>}
+ */
+async function runChannelAddContinuations(params) {
+  await maybeRunChatGptContinuation(params);
+  await maybeRunMcpClientContinuation(params);
+  await maybeRunClaudeContinuation(params);
+}
+
+/**
+ * Re-run remaining TTY for ChatGPT/Claude without regenerating artifacts.
+ * @param {Object} params
+ * @returns {Promise<boolean>}
+ */
+async function runSkippedRemoteMcpTty(params) {
+  if (params.channelTarget === 'chatgpt') {
+    await maybeAssertChatGptPreflight(params);
+    await maybeRunChatGptContinuation(params);
+    return true;
+  }
+  if (params.channelTarget === 'claude') {
+    await maybeAssertClaudePreflight(params);
+    await maybeRunClaudeContinuation(params);
+    return true;
+  }
+  return false;
+}
+
+module.exports = {
+  runChannelAddPreflights,
+  runChannelAddContinuations,
+  runSkippedRemoteMcpTty
+};

package/lib/channels/channel-add-ensure.js

@@ -8,28 +8,87 @@
 
 'use strict';
 
-const fs = require('fs');
 const path = require('path');
+const fs = require('fs');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
-const { formatSuccessLine, metadata } = require('../utils/cli-test-layout-chalk');
+const { printScaffolded, printUploaded, isChannelAddVerbose } = require('./channel-add-tty');
 const { getIntegrationPath } = require('../utils/paths');
 const { getExternalSystem } = require('../api/external-systems.api');
 const { unwrapApiData } = require('../utils/external-system-readiness-core');
-const { scaffoldChannelIntegration } = require('./channel-integration-generator');
+const {
+  scaffoldChannelIntegration,
+  hasChannelIntegrationFiles
+} = require('./channel-integration-generator');
 const { resolveChannelAuthContext } = require('./channel-auth-context');
 const { uploadExternalSystem } = require('../commands/upload');
+const { materializeChannelInstanceSystem } = require('./channel-instance-materialize');
+const { resolveChannelInstanceKey } = require('./channel-instance-key');
+const { isNotFoundError } = require('./channel-instance-collision');
+
+/**
+ * Default channel-add TTY: Publishing spinner, then one Uploaded line.
+ * Compact UPLOAD card and dataplane URL resolve stay on -v.
+ * @param {Object} options
+ * @param {Object} ctx
+ * @returns {Object}
+ */
+function buildChannelAddUploadOptions(options, ctx) {
+  const verbose = isChannelAddVerbose(options);
+  const shared = {
+    force: true,
+    authConfig: ctx.authConfig,
+    dataplaneUrl: ctx.dataplaneUrl,
+    environment: ctx.environment
+  };
+  if (verbose) {
+    return { ...shared, minimal: false, verbose: true };
+  }
+  return {
+    ...shared,
+    minimal: true,
+    verbose: false,
+    silentResolve: true,
+    suppressSummary: true,
+    suppressPipelineSpinner: options.quiet === true
+  };
+}
+
+function resolveInstanceKey(channelTarget, options = {}) {
+  return resolveChannelInstanceKey(channelTarget, options);
+}
+
+/**
+ * HTTP install already has the caller JWT on options.authContext.
+ * Re-resolving via getDeploymentAuth(definitionKey) looks up
+ * `{key}-client-idKeyVault` inside builder-api and 500s.
+ *
+ * @param {string} channelTarget
+ * @param {Object} options
+ * @returns {Promise<Object>}
+ */
+async function resolveEnsureAuthContext(channelTarget, options) {
+  if (options.authContext && typeof options.authContext === 'object') {
+    return options.authContext;
+  }
+  const verbose = isChannelAddVerbose(options);
+  return resolveChannelAuthContext(channelTarget, {
+    silent: options.quiet === true || !verbose
+  });
+}
 
 /**
  * @param {string} channelTarget
  * @param {string} [projectRoot]
+ * @param {string} [instanceKey]
  * @returns {string}
  */
-function resolveIntegrationDir(channelTarget, projectRoot) {
+function resolveIntegrationDir(channelTarget, projectRoot, instanceKey) {
+  const folderKey = instanceKey || channelTarget;
   if (projectRoot) {
-    return path.join(path.resolve(projectRoot), 'integration', channelTarget);
+    return path.join(path.resolve(projectRoot), 'integration', folderKey);
   }
-  return getIntegrationPath(channelTarget);
+  return getIntegrationPath(folderKey);
 }
 
 /**
@@ -38,31 +97,65 @@ function resolveIntegrationDir(channelTarget, projectRoot) {
  * @returns {Promise<boolean>}
  */
 async function isCommunicationSystemUploaded(ctx, channelTarget) {
-  const res = await getExternalSystem(ctx.dataplaneUrl, channelTarget, ctx.authConfig);
-  const system = unwrapApiData(res);
-  return !!(system && typeof system === 'object');
+  try {
+    const res = await getExternalSystem(ctx.dataplaneUrl, channelTarget, ctx.authConfig);
+    const system = unwrapApiData(res);
+    return !!(system && typeof system === 'object');
+  } catch (err) {
+    if (isNotFoundError(err)) {
+      return false;
+    }
+    throw err;
+  }
+}
+
+async function maybeRegenerateInstanceDeployJson(integrationDir, instanceKey) {
+  const appPath = path.join(integrationDir, 'application.json');
+  if (!fs.existsSync(appPath)) {
+    return;
+  }
+  const { generateDeployJson } = require('../generator');
+  await generateDeployJson(instanceKey, { appPath: integrationDir });
+}
+
+async function finishInstanceScaffold(integrationDir, definitionKey, instanceKey) {
+  materializeChannelInstanceSystem(integrationDir, definitionKey, instanceKey);
+  await maybeRegenerateInstanceDeployJson(integrationDir, instanceKey);
 }
 
 /**
- * Scaffold integration/<target>/ when missing (does not overwrite).
+ * Scaffold integration/<target>/ when missing or incomplete.
+ * With --force, refresh files from the channel template (same as channel scaffold --force).
  *
  * @param {string} channelTarget
  * @param {Object} options
  * @returns {Promise<{ scaffolded: boolean, integrationDir: string }>}
  */
 async function ensureChannelScaffold(channelTarget, options = {}) {
-  const integrationDir = resolveIntegrationDir(channelTarget, options.projectRoot);
-  if (fs.existsSync(integrationDir)) {
+  const instanceKey = resolveInstanceKey(channelTarget, options);
+  const integrationDir = resolveIntegrationDir(
+    channelTarget,
+    options.projectRoot,
+    instanceKey
+  );
+  const force = options.force === true;
+  if (hasChannelIntegrationFiles(integrationDir, instanceKey) && !force) {
+    await finishInstanceScaffold(integrationDir, channelTarget, instanceKey);
     return { scaffolded: false, integrationDir };
   }
   const result = await scaffoldChannelIntegration(channelTarget, {
     projectRoot: options.projectRoot,
-    allowExperimental: options.allowExperimental === true
+    integrationDir,
+    allowExperimental: options.allowExperimental === true,
+    force
   });
+  await finishInstanceScaffold(result.integrationDir, channelTarget, instanceKey);
   if (options.quiet !== true) {
-    logger.log(formatSuccessLine(`Scaffolded integration at ${result.integrationDir}`));
-    for (const file of result.files) {
-      logger.log(metadata(file));
+    printScaffolded(result.integrationDir);
+    if (isChannelAddVerbose(options) && Array.isArray(result.files)) {
+      for (const file of result.files) {
+        logger.log(chalk.gray(file));
+      }
     }
   }
   return { scaffolded: true, integrationDir: result.integrationDir };
@@ -79,25 +172,28 @@ async function ensureChannelUploaded(channelTarget, options = {}) {
   if (options.dryRun === true) {
     return { uploaded: false, skipped: true, ctx: null };
   }
-  const ctx = await resolveChannelAuthContext(channelTarget, { silent: options.quiet === true });
+  const instanceKey = resolveInstanceKey(channelTarget, options);
+  const verbose = isChannelAddVerbose(options);
+  const ctx = await resolveEnsureAuthContext(channelTarget, options);
   const force = options.force === true;
-  const alreadyUploaded = force ? false : await isCommunicationSystemUploaded(ctx, channelTarget);
+  const alreadyUploaded = force ? false : await isCommunicationSystemUploaded(ctx, instanceKey);
   if (alreadyUploaded) {
-    if (options.quiet !== true) {
-      logger.log(chalk.gray(`  Communication system "${channelTarget}" already on dataplane`));
+    if (verbose && options.quiet !== true) {
+      logger.log(chalk.gray(`  Communication system "${instanceKey}" already on dataplane`));
     }
     return { uploaded: false, skipped: true, ctx };
   }
-  if (options.quiet !== true) {
+  if (verbose && options.quiet !== true) {
     const reason = force ? 'force upload' : 'not found on dataplane';
-    logger.log(chalk.white(`Uploading ${channelTarget} (${reason})…`));
+    logger.log(chalk.white(`Uploading ${instanceKey} (${reason})…`));
   }
-  await uploadExternalSystem(channelTarget, {
-    force: true,
-    minimal: options.quiet === true || options.minimal !== false
+  const integrationDir = resolveIntegrationDir(channelTarget, options.projectRoot, instanceKey);
+  await uploadExternalSystem(instanceKey, {
+    ...buildChannelAddUploadOptions(options, ctx),
+    pathOptions: { appPath: integrationDir }
   });
-  if (options.quiet !== true) {
-    logger.log(formatSuccessLine(`Uploaded ${channelTarget}`));
+  if (options.quiet !== true && options.suppressUploadedLine !== true) {
+    printUploaded(instanceKey);
   }
   return { uploaded: true, skipped: false, ctx };
 }
@@ -122,6 +218,7 @@ async function ensureChannelReadyForAdd(channelTarget, options = {}) {
 module.exports = {
   resolveIntegrationDir,
   isCommunicationSystemUploaded,
+  buildChannelAddUploadOptions,
   ensureChannelScaffold,
   ensureChannelUploaded,
   ensureChannelReadyForAdd