@aifabrix/builder 2.52.0 → 2.52.1

package/jest.isolated-projects.js

@@ -67,6 +67,11 @@ const ISOLATED_SUITE_ENTRIES = [
   ['role-assistant-knowledge-sync', ['**/tests/lib/role-assistant/knowledge-sync.test.js']],
   ['role-assistant-evidence-sync', ['**/tests/lib/role-assistant/evidence-sync.test.js']],
   ['role-assistant-test-cases', ['**/tests/lib/role-assistant/test-cases.test.js']],
+  ['role-assistant-test-suite', ['**/tests/lib/role-assistant/test-suite.test.js']],
+  [
+    'role-assistant-workhub-answers',
+    ['**/tests/lib/role-assistant/test-runner-workhub-answers.test.js']
+  ],
   ['governance-fixture-subjects', ['**/tests/lib/commands/governance-fixture-subjects.test.js']],
   ['enterprise-knowledge-generate-manifest', ['**/tests/lib/commands/enterprise-knowledge-generate-manifest.test.js']],
   ['plan-prevalidate-gates', ['**/tests/lib/plan-prevalidate-gates.test.js']],
@@ -152,7 +157,19 @@ const ISOLATED_SUITE_ENTRIES = [
     [
       '**/tests/lib/channels/channel-integration-generator.test.js',
       '**/tests/lib/channels/channel-artifact-generator.test.js',
-      '**/tests/lib/channels/channel-integration-template.test.js'
+      '**/tests/lib/channels/channel-integration-template.test.js',
+      '**/tests/lib/channels/add-channel.test.js',
+      '**/tests/lib/channels/microsoft-copilot-package-quality.test.js',
+      '**/tests/lib/channels/channel-branding.test.js'
+    ]
+  ],
+  [
+    'integration-definition-real-fs',
+    [
+      '**/tests/lib/validation/integration-definition-schema.test.js',
+      '**/tests/lib/integration-definition/apply.test.js',
+      '**/tests/lib/integration-definition/from-discovery.test.js',
+      '**/tests/lib/integration-definition/emit-suite-bid.test.js'
     ]
   ],
   [
@@ -175,6 +192,10 @@ const ISOLATED_SUITE_ENTRIES = [
       '**/tests/lib/scripts/sync-builder-api-template.test.js',
       '**/tests/lib/evidence/evidence-service.test.js'
     ]
+  ],
+  [
+    'enrich-openapi-operations',
+    ['**/tests/lib/integration-definition/enrich-openapi-operations.test.js']
   ]
 ];
 
@@ -224,7 +245,9 @@ function buildDefaultTestPathIgnorePatterns(includeLocalTests) {
     '/tests/integration/',
     '\\\\tests\\\\integration\\\\',
     '/tests/manual/',
-    '\\\\tests\\\\manual\\\\'
+    '\\\\tests\\\\manual\\\\',
+    '/builder/',
+    '\\\\builder\\\\'
   ];
   const globs = [
     ...ISOLATED_SUITE_ENTRIES.flatMap((entry) => entry[1]),

package/jest.projects.js

@@ -52,7 +52,10 @@ const defaultProject = {
   ],
   testPathIgnorePatterns: buildDefaultTestPathIgnorePatterns(),
   modulePathIgnorePatterns: [
-    '<rootDir>/docker-builder-api-staging/'
+    '<rootDir>/docker-builder-api-staging/',
+    // Generated app dirs under builder/ (except builder-api) — avoid haste/transform
+    // picking up junk written by generator/cli suites (e.g. builder/testapp).
+    '<rootDir>/builder/(?!builder-api(?:/|$))'
   ],
   setupFiles: ['<rootDir>/tests/capture-real-fs.js'],
   setupFilesAfterEnv: ['<rootDir>/tests/setup.js'],

package/lib/api/datasources-extended.api.js

@@ -69,28 +69,28 @@ async function detachPolicy(dataplaneUrl, sourceIdOrKey, policyIdOrKey, authConf
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/${sourceIdOrKey}/policies/${policyIdOrKey}`);
 }
-/** @requiresPermission {Dataplane} external-system:read (sync) */
+/** @requiresPermission {Dataplane} external-data-source:read (sync under /data-storage) */
 async function listSyncJobs(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
-  return await client.get(`/api/v1/external/${sourceIdOrKey}/sync`, { params: options });
+  return await client.get(`/api/v1/data-storage/${sourceIdOrKey}/sync`, { params: options });
 }
 async function createSyncJob(dataplaneUrl, sourceIdOrKey, authConfig, syncData) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
-  return await client.post(`/api/v1/external/${sourceIdOrKey}/sync`, { body: syncData });
+  return await client.post(`/api/v1/data-storage/${sourceIdOrKey}/sync`, { body: syncData });
 }
-/** @requiresPermission {Dataplane} external-system:read */
+/** @requiresPermission {Dataplane} external-data-source:read */
 async function getSyncJob(dataplaneUrl, sourceIdOrKey, syncJobId, authConfig) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
-  return await client.get(`/api/v1/external/${sourceIdOrKey}/sync/${syncJobId}`);
+  return await client.get(`/api/v1/data-storage/${sourceIdOrKey}/sync/${syncJobId}`);
 }
-/** @requiresPermission {Dataplane} external-system:update */
+/** @requiresPermission {Dataplane} external-data-source:sync */
 async function updateSyncJob(dataplaneUrl, sourceIdOrKey, syncJobId, authConfig, updateData) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
-  return await client.put(`/api/v1/external/${sourceIdOrKey}/sync/${syncJobId}`, { body: updateData });
+  return await client.put(`/api/v1/data-storage/${sourceIdOrKey}/sync/${syncJobId}`, { body: updateData });
 }
 async function executeSyncJob(dataplaneUrl, sourceIdOrKey, syncJobId, authConfig) {
   const client = createDataplaneApiClient(dataplaneUrl, authConfig);
-  return await client.post(`/api/v1/external/${sourceIdOrKey}/sync/${syncJobId}/execute`);
+  return await client.post(`/api/v1/data-storage/${sourceIdOrKey}/sync/${syncJobId}/execute`);
 }
 /** @requiresPermission {Dataplane} external-data-source:sync */
 async function validateDocuments(dataplaneUrl, sourceIdOrKey, authConfig, validateData) {

package/lib/api/keycloak.api.js

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Keycloak status API (Controller) — Entra IdP ids for packaging
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const KEYCLOAK_STATUS_PATH = '/api/v1/keycloak/status';
+
+/**
+ * @param {Object} response
+ * @returns {import('./types/keycloak.types').KeycloakStatus|null}
+ */
+function extractKeycloakStatus(response) {
+  if (!response || typeof response !== 'object' || response.success === false) {
+    return null;
+  }
+  const body = response.data ?? response;
+  const data = body?.data !== undefined ? body.data : body;
+  if (!data || typeof data !== 'object' || Array.isArray(data)) {
+    return null;
+  }
+  return data;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+function trimNonEmptyString(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+
+/**
+ * @param {import('./types/keycloak.types').KeycloakStatus|null} status
+ * @returns {import('./types/keycloak.types').KeycloakEntraIdentityProvider|null}
+ */
+function extractEntraIdentityProvider(status) {
+  const raw = status?.entraIdentityProvider;
+  if (!raw || typeof raw !== 'object') {
+    return null;
+  }
+  const enterpriseAppId = trimNonEmptyString(raw.enterpriseAppId);
+  if (!enterpriseAppId) {
+    return null;
+  }
+  const tenantId = trimNonEmptyString(raw.tenantId);
+  return tenantId ? { enterpriseAppId, tenantId } : { enterpriseAppId };
+}
+
+/**
+ * GET /api/v1/keycloak/status
+ * @requiresPermission {Controller} admin:keycloak
+ * @async
+ * @param {string} controllerUrl - Miso Controller base URL
+ * @param {Object} authConfig - Authentication configuration (device Bearer)
+ * @returns {Promise<import('./types/keycloak.types').KeycloakStatus|null>}
+ */
+async function getKeycloakStatus(controllerUrl, authConfig) {
+  const client = new ApiClient(controllerUrl, authConfig);
+  const response = await client.get(KEYCLOAK_STATUS_PATH);
+  return extractKeycloakStatus(response);
+}
+
+/**
+ * Resolve Entra SSO enterprise app id from Keycloak status, or null when missing.
+ * Does not invent ids.
+ * @requiresPermission {Controller} admin:keycloak
+ * @async
+ * @param {string} controllerUrl - Miso Controller base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Promise<import('./types/keycloak.types').KeycloakEntraIdentityProvider|null>}
+ */
+async function getKeycloakEntraIdentityProvider(controllerUrl, authConfig) {
+  const status = await getKeycloakStatus(controllerUrl, authConfig);
+  return extractEntraIdentityProvider(status);
+}
+
+module.exports = {
+  KEYCLOAK_STATUS_PATH,
+  getKeycloakStatus,
+  getKeycloakEntraIdentityProvider,
+  extractKeycloakStatus,
+  extractEntraIdentityProvider
+};

package/lib/api/token-providers.api.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Admin token providers API (Controller Trust sources)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const ADMIN_BASE = '/api/v1/admin/token-providers';
+const MICROSOFT_ENTRA_ID_KEY = 'microsoft-entra-id';
+
+/**
+ * @param {Object} response
+ * @returns {import('./types/token-providers.types').TokenProvider[]}
+ */
+function extractTokenProviders(response) {
+  const body = response?.data ?? response;
+  const data = body?.data ?? body;
+  if (Array.isArray(data)) {
+    return data;
+  }
+  if (Array.isArray(data?.items)) {
+    return data.items;
+  }
+  return [];
+}
+
+/**
+ * List admin token providers (paginated).
+ * GET /api/v1/admin/token-providers
+ * @requiresPermission {Controller} token-provider:read
+ * @async
+ * @param {string} controllerUrl - Miso Controller base URL
+ * @param {Object} authConfig - Authentication configuration (device Bearer)
+ * @param {import('./types/token-providers.types').ListAdminTokenProvidersOptions} options
+ * @returns {Promise<Object>} Controller list response
+ * @throws {Error} If direction is missing or request fails
+ */
+async function listAdminTokenProviders(controllerUrl, authConfig, options = {}) {
+  const direction = options?.direction;
+  if (direction !== 'inbound' && direction !== 'outbound') {
+    throw new Error('direction is required and must be "inbound" or "outbound"');
+  }
+  const client = new ApiClient(controllerUrl, authConfig);
+  const params = { ...options, direction };
+  return await client.get(ADMIN_BASE, { params });
+}
+
+/**
+ * Resolve inbound Microsoft Entra ID Trust source, or null when missing.
+ * Does not invent issuer, audience, or scopes.
+ * @requiresPermission {Controller} token-provider:read
+ * @async
+ * @param {string} controllerUrl - Miso Controller base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @returns {Promise<import('./types/token-providers.types').TokenProvider|null>}
+ */
+async function getInboundMicrosoftEntraIdProvider(controllerUrl, authConfig) {
+  const response = await listAdminTokenProviders(controllerUrl, authConfig, {
+    direction: 'inbound',
+    search: MICROSOFT_ENTRA_ID_KEY,
+    page: 1,
+    pageSize: 50
+  });
+  const items = extractTokenProviders(response);
+  const exact = items.find((item) => item && item.key === MICROSOFT_ENTRA_ID_KEY);
+  return exact || null;
+}
+
+module.exports = {
+  listAdminTokenProviders,
+  getInboundMicrosoftEntraIdProvider,
+  extractTokenProviders,
+  MICROSOFT_ENTRA_ID_KEY
+};

package/lib/api/types/keycloak.types.js

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview Keycloak status API type definitions (Controller)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * Entra identity provider fragment from Keycloak status.
+ * @typedef {Object} KeycloakEntraIdentityProvider
+ * @property {string} enterpriseAppId - Entra SSO application (client) id
+ * @property {string} [tenantId] - Entra tenant id when known
+ */
+
+/**
+ * Keycloak configuration status payload (`data` of GET /api/v1/keycloak/status).
+ * @typedef {Object} KeycloakStatus
+ * @property {string} [realm]
+ * @property {string} [status]
+ * @property {string} [controllerClientId]
+ * @property {KeycloakEntraIdentityProvider} [entraIdentityProvider]
+ */
+
+module.exports = {};

package/lib/api/types/token-providers.types.js

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Token provider API type definitions (Controller admin Trust sources)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+/**
+ * Token provider direction
+ * @typedef {'inbound'|'outbound'} TokenProviderDirection
+ */
+
+/**
+ * Token provider subject type
+ * @typedef {'user'|'service'|'both'} TokenProviderSubjectType
+ */
+
+/**
+ * Allowed operation on a token provider
+ * @typedef {'mcp.invoke'|'dataplane.read'|'dataplane.write'} TokenProviderAllowedOperation
+ */
+
+/**
+ * Admin token provider list item (Controller TokenProvider schema)
+ * @typedef {Object} TokenProvider
+ * @property {string} id - Unique identifier (cuid)
+ * @property {string} key - Unique slug (e.g. microsoft-entra-id)
+ * @property {string} displayName - Human-readable name
+ * @property {string} issuer - JWT issuer URL (iss claim)
+ * @property {string} jwksUri - JWKS endpoint for key verification
+ * @property {string|null} [audience] - Expected audience claim (may be null)
+ * @property {TokenProviderSubjectType} subjectType - Subject type
+ * @property {TokenProviderDirection} direction - inbound or outbound
+ * @property {string|null} [identityClaim] - Claim used for user identity
+ * @property {string|null} [emailClaim] - Claim used for email
+ * @property {boolean} [autoProvision] - Whether to auto-create users
+ * @property {string|null} [serviceUserKey] - Service user key for service flow
+ * @property {TokenProviderAllowedOperation[]} [allowedOperations] - Allowed operations
+ * @property {string[]} [allowedScopes] - OAuth scopes (may be empty)
+ * @property {boolean} enabled - Whether this provider is enabled
+ * @property {string} [createdAt] - Created at
+ * @property {string} [updatedAt] - Updated at
+ */
+
+/**
+ * List admin token providers query options
+ * @typedef {Object} ListAdminTokenProvidersOptions
+ * @property {TokenProviderDirection} direction - Required by OpenAPI
+ * @property {string} [search] - Search across key, displayName, issuer
+ * @property {number} [page] - Page number
+ * @property {number} [pageSize] - Page size
+ * @property {string} [sort] - Sort expression
+ * @property {string} [filter] - Filter expression
+ * @property {string} [enabled] - 'true' | 'false'
+ * @property {TokenProviderSubjectType} [subjectType] - Subject type filter
+ */
+
+/**
+ * Paginated list response for admin token providers
+ * @typedef {Object} ListAdminTokenProvidersResponse
+ * @property {TokenProvider[]} data - Provider rows
+ * @property {Object} meta - Pagination meta
+ * @property {Object} [links] - Pagination links
+ */
+
+module.exports = {};

package/lib/app/down.js

@@ -111,6 +111,20 @@ async function stopAppContainers(appName, companionKeys, developerId) {
   }
 }
 
+/**
+ * Resolve developer id for downApp (optional override does not change config).
+ * @param {Object} options
+ * @returns {Promise<string>}
+ */
+async function resolveDownAppDeveloperId(options) {
+  const override = options && options.developerId;
+  if (override === undefined || override === null || override === '') {
+    return config.getDeveloperId();
+  }
+  const { validateAndNormalizeDeveloperId } = require('../core/config-normalize');
+  return validateAndNormalizeDeveloperId(override);
+}
+
 /**
  * Stops and removes a specific application's container.
  * If --volumes is passed, attempts to remove the app's named Docker volume.
@@ -122,6 +136,7 @@ async function stopAppContainers(appName, companionKeys, developerId) {
  * @param {string} appName - Application name
  * @param {Object} options - Options
  * @param {boolean} [options.volumes=false] - Remove Docker volume data
+ * @param {string|number} [options.developerId] - Target developer for this stop only
  * @returns {Promise<void>} Resolves when operation completes
  * @throws {Error} If validation fails or Docker operations error (other than missing volume)
  *
@@ -136,7 +151,7 @@ async function downApp(appName, options = {}) {
     validateAppName(appName);
 
     const volumes = !!options.volumes;
-    const developerId = await config.getDeveloperId();
+    const developerId = await resolveDownAppDeveloperId(options);
     const appConfig = loadBuilderApplicationConfig(appName);
     const companionKeys = getCeleryCompanionAppKeys(appName, appConfig);
 

package/lib/channels/add-channel.js

@@ -10,9 +10,15 @@
 
 const { getChannelTarget, getDefaultChannelDescription } = require('./channel-targets');
 const { resolveAppDescription } = require('./channel-description');
+const path = require('path');
 const { resolveChannelRuntimeValues } = require('./channel-runtime-resolver');
 const { generateChannelArtifact } = require('./channel-artifact-generator');
 const { fetchRuntimeLayerBToolNames } = require('./runtime-tool-catalog');
+const { loadChannelPackageContext } = require('./channel-discovery');
+const {
+  readChannelBranding,
+  mergeChannelBranding
+} = require('./channel-branding');
 const {
   getExistingChannelExtension,
   buildChannelExtensionBlock,
@@ -39,9 +45,14 @@ const {
 } = require('./channel-display-name');
 const {
   displayExistingChannelStatus,
-  displayChannelInstallResult,
-  displayChannelError
+  displayChannelInstallResult
 } = require('./channel-status-display');
+const { ensureChannelReadyForAdd } = require('./channel-add-ensure');
+const {
+  assertMicrosoftCopilotOauthReference,
+  assertMicrosoftCopilotOauthReferenceBeforeForce,
+  loadMicrosoftCopilotEntraContext
+} = require('./microsoft-copilot-channel-add');
 
 /**
  * @param {typeof import('./channel-targets').CHANNEL_TARGETS[string]} target
@@ -252,6 +263,9 @@ async function completeLiveInstall(params) {
     capabilities: target.capabilities,
     artifactPath: artifact.outputPath,
     installGuidePath: artifact.installPath,
+    zipPath: artifact.zipPath,
+    installReady: artifact.installReady,
+    blocker: artifact.blocker,
     validation: toValidationDisplay(validation),
     approvalGuide
   });
@@ -272,7 +286,10 @@ function finishDryRunInstall(params) {
     credentialKey: params.target.credentialKey,
     capabilities: params.target.capabilities,
     artifactPath: params.artifact.outputPath,
-    installGuidePath: params.artifact.installPath
+    installGuidePath: params.artifact.installPath,
+    zipPath: params.artifact.zipPath,
+    installReady: params.artifact.installReady,
+    blocker: params.artifact.blocker
   });
   return { dryRun: true, channelBlock: params.channelBlock, artifact: params.artifact };
 }
@@ -281,12 +298,78 @@ function finishDryRunInstall(params) {
  * @param {Object} params
  * @returns {Promise<{ artifact: Object, channelBlock: Object, status: string }>}
  */
+/**
+ * @param {Object|null} packageContext
+ * @param {Object} options
+ * @param {'iconColorPath'|'iconOutlinePath'} key
+ * @returns {string|undefined}
+ */
+function brandingIconOrOption(packageContext, options, key) {
+  if (typeof options[key] === 'string' && options[key].trim()) {
+    return options[key].trim();
+  }
+  if (packageContext && typeof packageContext[key] === 'string' && packageContext[key].trim()) {
+    return packageContext[key].trim();
+  }
+  return undefined;
+}
+
+async function resolvePackageContextForInstall(params) {
+  const { channelTarget, options, name, description, ctx } = params;
+  const packagingTargets = new Set(['chatgpt', 'microsoft-copilot', 'slack', 'teams-bot']);
+  if (!packagingTargets.has(channelTarget)) {
+    return null;
+  }
+  const projectRoot = options.projectRoot || process.cwd();
+  const workspaceDir = path.join(projectRoot, 'integration', channelTarget);
+  const branding = mergeChannelBranding(readChannelBranding(workspaceDir), {
+    displayName: options.overrideDisplayName || undefined,
+    description: options.overrideDescription || undefined,
+    iconColorPath: options.iconColorPath || undefined,
+    iconOutlinePath: options.iconOutlinePath || undefined
+  });
+  let packageContext;
+  try {
+    packageContext = await loadChannelPackageContext({
+      dataplaneBaseUrl: ctx.dataplaneUrl,
+      authConfig: ctx.authConfig,
+      channelTarget,
+      branding
+    });
+  } catch {
+    packageContext = {
+      displayName: name,
+      description,
+      governedToolNames: [],
+      mcpServerUrl: null,
+      installReady: false,
+      blocker: 'discoveryUnavailable',
+      authentication: null,
+      authenticationCapabilities: []
+    };
+  }
+  return {
+    ...packageContext,
+    iconColorPath: branding.iconColorPath,
+    iconOutlinePath: branding.iconOutlinePath
+  };
+}
+
 async function buildInstallArtifacts(params) {
   const { channelTarget, options, target, existing, name, baseName, description, ctx } = params;
-  const runtimeToolNames =
-    channelTarget === 'chatgpt' || channelTarget === 'microsoft-copilot'
-      ? await fetchRuntimeLayerBToolNames(ctx.dataplaneUrl, ctx.authConfig, channelTarget)
-      : [];
+  const packageContext = await resolvePackageContextForInstall(params);
+  let runtimeToolNames = [];
+  if (channelTarget === 'chatgpt' || channelTarget === 'microsoft-copilot') {
+    runtimeToolNames =
+      packageContext?.governedToolNames?.length > 0
+        ? packageContext.governedToolNames
+        : await fetchRuntimeLayerBToolNames(ctx.dataplaneUrl, ctx.authConfig, channelTarget);
+  }
+  let entraProvider = null;
+  let entraIdentityProvider = null;
+  if (channelTarget === 'microsoft-copilot') {
+    ({ entraProvider, entraIdentityProvider } = await loadMicrosoftCopilotEntraContext(ctx));
+  }
   const runtimeValues = resolveChannelRuntimeValues({
     dataplaneBaseUrl: ctx.dataplaneUrl,
     channelTarget,
@@ -296,7 +379,14 @@ async function buildInstallArtifacts(params) {
     appDescription: description,
     icon: options.icon,
     commandPrefix: options.commandPrefix,
-    layerBToolNames: runtimeToolNames
+    layerBToolNames: runtimeToolNames,
+    packageContext,
+    entraProvider,
+    entraIdentityProvider,
+    oauthPluginVaultReferenceId: options.oauthPluginVaultReferenceId,
+    scopes: options.scopes,
+    iconColorPath: brandingIconOrOption(packageContext, options, 'iconColorPath'),
+    iconOutlinePath: brandingIconOrOption(packageContext, options, 'iconOutlinePath')
   });
   const projectRoot = options.projectRoot || process.cwd();
   const artifact = generateArtifactWithAudit(channelTarget, {
@@ -313,17 +403,39 @@ async function buildInstallArtifacts(params) {
   return { artifact, channelBlock, status };
 }
 
+/**
+ * @param {string} channelTarget
+ * @param {Object} options
+ * @returns {Object}
+ */
+function assertChannelAddOptions(channelTarget, options) {
+  const target = getChannelTarget(channelTarget);
+  if (target.experimental) {
+    throw new Error(
+      `Channel target "${channelTarget}" is experimental. Confirm product requirement before use.`
+    );
+  }
+  if (!options.name || typeof options.name !== 'string' || !options.name.trim()) {
+    throw new Error('--name is required for channel add');
+  }
+  return target;
+}
+
 /**
  * @param {string} channelTarget
  * @param {Object} options
  * @returns {Promise<Object>}
  */
 async function runAddChannel(channelTarget, options = {}) {
-  const { target, name, baseName, description, ctx, existing } = await prepareChannelContext(
+  const target = assertChannelAddOptions(channelTarget, options);
+  if (channelTarget === 'microsoft-copilot' && options.force === true) {
+    await assertMicrosoftCopilotOauthReferenceBeforeForce(options);
+  }
+  await ensureChannelReadyForAdd(channelTarget, options);
+  const { name, baseName, description, ctx, existing } = await prepareChannelContext(
     channelTarget,
     options
   );
-
   const skipped = showExistingChannelStatus({
     existing,
     options,
@@ -333,7 +445,9 @@ async function runAddChannel(channelTarget, options = {}) {
     ctx
   });
   if (skipped) return skipped;
-
+  if (channelTarget === 'microsoft-copilot') {
+    await assertMicrosoftCopilotOauthReference({ options, ctx, name, baseName, description });
+  }
   const { artifact, channelBlock, status } = await buildInstallArtifacts({
     channelTarget,
     options,
@@ -344,11 +458,9 @@ async function runAddChannel(channelTarget, options = {}) {
     description,
     ctx
   });
-
   if (options.dryRun) {
     return finishDryRunInstall({ channelTarget, name, baseName, target, artifact, channelBlock });
   }
-
   return completeLiveInstall({
     ctx,
     channelTarget,
@@ -367,12 +479,7 @@ async function runAddChannel(channelTarget, options = {}) {
  * @param {Object} options
  */
 async function addChannelCommand(channelTarget, options = {}) {
-  try {
-    await runAddChannel(channelTarget, options);
-  } catch (err) {
-    displayChannelError(err.message || String(err));
-    throw err;
-  }
+  await runAddChannel(channelTarget, options);
 }
 
 module.exports = {

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

@@ -22,7 +22,7 @@ function buildChatGptApprovalGuide(ctx) {
       'Enable Developer mode for custom MCP apps (Business: Workspace settings → Apps, or Settings → Apps → Advanced settings; Enterprise/Edu: grant Developer mode under Permissions & roles → Connected data first).',
       'Create a custom MCP app with the Remote MCP URL from INSTALL.md (channel-chatgpt.json is a deployment reference, not a plugin archive).',
       'Select OAuth (authorization-code + PKCE S256). Do not configure a custom API key for a remote custom MCP app.',
-      'Scan tools, complete OAuth if prompted, review discovered Runtime Layer B tools, then save the app as a draft.',
+      'Scan tools, complete OAuth if prompted, review discovered governed tools, then save the app as a draft.',
       formatCredentialPortalStep(
         ctx,
         `${ctx.credentialKey || 'channel'} credential references (not secrets to paste into ChatGPT)`