@aifabrix/builder 2.52.0 → 2.53.0

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/deploy-config.js

@@ -78,9 +78,10 @@ async function extractDeploymentConfig(options, _variables) {
     // Used by guided installers which already show a top-level spinner.
     silentPoll: options.silentPoll === true,
     repositoryUrl: options.repositoryUrl,
-    // Omit default here so deployer can resolve 2s vs 5s from controller deploymentType (GET /api/v1/health)
+    // Omit default here so deployer can resolve 1s vs 5s from controller deploymentType (GET /api/v1/health)
     pollInterval: Number.isFinite(pollIntervalExplicit) ? pollIntervalExplicit : undefined,
-    pollMaxAttempts: options.pollMaxAttempts || 60,
+    // Default 300 attempts: ~5 min at 1s (local) / ~25 min at 5s (azure) — deploy may run tests/gates
+    pollMaxAttempts: options.pollMaxAttempts || 300,
     deploymentAuth: options.deploymentAuth
   };
 }

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

@@ -8,11 +8,17 @@
 
 'use strict';
 
+const path = require('path');
 const { getChannelTarget, getDefaultChannelDescription } = require('./channel-targets');
 const { resolveAppDescription } = require('./channel-description');
 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,
@@ -37,11 +43,14 @@ const {
   normalizeBaseChannelName,
   resolveChannelDisplayName
 } = require('./channel-display-name');
+const { displayChannelInstallResult } = require('./channel-status-display');
+const { ensureChannelReadyForAdd } = require('./channel-add-ensure');
+const { showExistingChannelStatus } = require('./channel-add-existing');
 const {
-  displayExistingChannelStatus,
-  displayChannelInstallResult,
-  displayChannelError
-} = require('./channel-status-display');
+  assertMicrosoftCopilotOauthReference,
+  assertMicrosoftCopilotOauthReferenceBeforeForce,
+  loadMicrosoftCopilotEntraContext
+} = require('./microsoft-copilot-channel-add');
 
 /**
  * @param {typeof import('./channel-targets').CHANNEL_TARGETS[string]} target
@@ -73,41 +82,6 @@ function toValidationDisplay(validation) {
   };
 }
 
-/**
- * @param {Object} params
- * @returns {Object|null}
- */
-function showExistingChannelStatus(params) {
-  const { existing, options, channelTarget, name, baseName, ctx } = params;
-  if (!existing || options.force || options.dryRun) return null;
-  const sameInstall =
-    (existing.baseName && existing.baseName === baseName) ||
-    (!existing.baseName && existing.name === name);
-  if (!sameInstall) {
-    throw new Error(
-      `Channel already configured as "${existing.name}". ` +
-        `Use --force to replace with "${name}".`
-    );
-  }
-  const projectRoot = options.projectRoot || process.cwd();
-  const approvalGuide =
-    existing.status === 'approvalRequired'
-      ? buildChannelApprovalGuide(channelTarget, {
-        projectRoot,
-        name: existing.name || name,
-        baseName,
-        dataplaneBaseUrl: ctx?.dataplaneUrl
-      })
-      : null;
-  displayExistingChannelStatus({
-    channelTarget,
-    name: existing.name || name,
-    channelExt: existing,
-    approvalGuide
-  });
-  return { skipped: true, channelExt: existing };
-}
-
 /**
  * @param {string} channelTarget
  * @param {Object} artifactParams
@@ -234,7 +208,8 @@ async function completeLiveInstall(params) {
         name,
         baseName,
         artifactPath: artifact.outputPath,
-        dataplaneBaseUrl: ctx.dataplaneUrl
+        dataplaneBaseUrl: ctx.dataplaneUrl,
+        environment: ctx.environment || options.environment || 'dev'
       })
       : null;
   if (approvalGuide?.portalUrl) {
@@ -252,6 +227,15 @@ async function completeLiveInstall(params) {
     capabilities: target.capabilities,
     artifactPath: artifact.outputPath,
     installGuidePath: artifact.installPath,
+    zipPath: artifact.zipPath,
+    installReady: artifact.installReady,
+    blocker: artifact.blocker,
+    packageReady: artifact.packageReady,
+    packageBlocker: artifact.packageBlocker,
+    microsoftPublicationPending:
+      artifact.microsoftPublicationPending !== undefined
+        ? artifact.microsoftPublicationPending
+        : status === 'approvalRequired',
     validation: toValidationDisplay(validation),
     approvalGuide
   });
@@ -272,7 +256,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 +268,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 +349,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 +373,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 +415,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 +428,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 +449,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)`

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

@@ -71,6 +71,9 @@ function buildChannelApprovalGuide(channelTarget, context = {}) {
     : null;
   const baseCtx = {
     channelTarget,
+    name,
+    baseName: context.baseName || name,
+    environment: context.environment || 'dev',
     artifactPath,
     resumeCommand,
     credentialKey: target.credentialKey,