@aifabrix/builder 2.46.0 → 2.47.0

package/lib/channels/channel-probe.js

@@ -0,0 +1,89 @@
+/**
+ * Channel install probe checks (plan 152).
+ *
+ * @fileoverview Callback, assistant catalog, and inbound verification probes
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('../api/index');
+const { fetchDataplaneGeneralHealth } = require('../api/dataplane-health.api');
+
+/**
+ * @async
+ * @param {string} url
+ * @returns {Promise<boolean>}
+ */
+async function isUrlReachable(url) {
+  if (!url) return false;
+  const client = new ApiClient(url.split('/api/')[0] || url);
+  try {
+    const pathPart = url.includes('/api/') ? url.substring(url.indexOf('/api/')) : '/health';
+    const res = await client.get(pathPart, { timeoutMs: 8000 });
+    return res && res.success !== false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @async
+ * @param {string} dataplaneUrl
+ * @param {Object} authConfig
+ * @returns {Promise<boolean>}
+ */
+async function isAssistantCatalogReachable(dataplaneUrl, authConfig) {
+  const client = require('../api/index').createDataplaneApiClient(dataplaneUrl, authConfig);
+  try {
+    const res = await client.get('/api/v1/workers/available', { timeoutMs: 10000 });
+    return res && res.success !== false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {Object|null} channelExt
+ * @returns {Object}
+ */
+function evaluateInboundVerification(channelExt) {
+  const credentialKey = channelExt?.credentialKey || '';
+  return {
+    slackSigningSecretConfigured: credentialKey.includes('slack'),
+    teamsBotOidcValidationConfigured: credentialKey.includes('teams-bot'),
+    issuerAudienceConfigured: Boolean(channelExt?.type),
+    replayProtectionConfigured: Boolean(channelExt?.status === 'installed' || channelExt?.status === 'validated')
+  };
+}
+
+/**
+ * @async
+ * @param {Object} ctx
+ * @param {Object|null} channelExt
+ * @returns {Promise<Object>}
+ */
+async function runChannelProbe(ctx, channelExt) {
+  const health = await fetchDataplaneGeneralHealth(ctx.dataplaneUrl, { timeoutMs: 8000 });
+  const catalogOk = await isAssistantCatalogReachable(ctx.dataplaneUrl, ctx.authConfig);
+  const callbackOk = health?.status === 'healthy' || health?.status === 'ok';
+
+  const inbound = evaluateInboundVerification(channelExt);
+
+  return {
+    dataplaneHealth: health?.status || 'unknown',
+    callbackReachable: callbackOk,
+    assistantCatalogReachable: catalogOk,
+    credentialValid: Boolean(channelExt?.credentialKey),
+    inboundVerification: inbound,
+    passed: callbackOk && catalogOk && Boolean(channelExt?.credentialKey)
+  };
+}
+
+module.exports = {
+  isUrlReachable,
+  isAssistantCatalogReachable,
+  evaluateInboundVerification,
+  runChannelProbe
+};

package/lib/channels/channel-runtime-resolver.js

@@ -0,0 +1,152 @@
+/**
+ * Resolve runtime URLs for channel templates (no hardcoded env URLs).
+ *
+ * @fileoverview Channel runtime value resolution (plan 152)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { getChannelTarget } = require('./channel-targets');
+
+/**
+ * Normalize dataplane base URL (no trailing slash).
+ * @param {string} dataplaneBaseUrl
+ * @returns {string}
+ */
+function normalizeBaseUrl(dataplaneBaseUrl) {
+  if (!dataplaneBaseUrl || typeof dataplaneBaseUrl !== 'string') {
+    throw new Error('dataplaneBaseUrl is required');
+  }
+  return dataplaneBaseUrl.trim().replace(/\/+$/, '');
+}
+
+/**
+ * @param {string} base
+ * @param {string} path
+ * @returns {string}
+ */
+function joinUrl(base, path) {
+  return `${normalizeBaseUrl(base)}${path.startsWith('/') ? path : `/${path}`}`;
+}
+
+/**
+ * Dataplane external-system route prefix for webhook URLs.
+ * @param {string} routeSystemKey
+ * @returns {string}
+ */
+function externalSystemsPrefix(routeSystemKey) {
+  return `/api/v1/external/systems/${routeSystemKey}`;
+}
+
+/**
+ * Relative endpoint paths per channel target (under external/systems/{routeSystemKey}).
+ * @param {string} channelTarget
+ * @returns {Record<string, string>}
+ */
+function getEndpointPathSuffixes(channelTarget) {
+  const maps = {
+    slack: {
+      eventsUrl: '/events',
+      interactionUrl: '/interactive',
+      oauthCallbackUrl: '/oauth/callback',
+      commandUrl: '/commands'
+    },
+    'teams-bot': {
+      messagesUrl: '/messages',
+      notificationsUrl: '/notifications',
+      botConfigUrl: '/bot-config'
+    },
+    'microsoft-copilot': {
+      openapiUrl: '/openapi.yaml',
+      actionsBaseUrl: '/actions'
+    },
+    chatgpt: {
+      openapiUrl: '/openapi.yaml',
+      mcpUrl: '/mcp',
+      actionsBaseUrl: '/actions'
+    },
+    'web-embed': {
+      configUrl: '/config'
+    }
+  };
+  return maps[channelTarget] || {};
+}
+
+/**
+ * Legacy / non-external-system paths (Copilot/ChatGPT until dataplane routes exist).
+ * @param {string} channelTarget
+ * @returns {Record<string, string>}
+ */
+function getLegacyApiPaths(channelTarget) {
+  const legacy = {
+    'microsoft-copilot': {
+      openapiUrl: '/api/v1/copilot/openapi.yaml',
+      actionsBaseUrl: '/api/v1/copilot/actions'
+    },
+    chatgpt: {
+      openapiUrl: '/api/v1/chatgpt/openapi.yaml',
+      mcpUrl: '/api/v1/chatgpt/mcp',
+      actionsBaseUrl: '/api/v1/chatgpt/actions'
+    },
+    'web-embed': {
+      configUrl: '/api/v1/web-embed/config'
+    }
+  };
+  return legacy[channelTarget] || {};
+}
+
+/**
+ * @param {Object} params
+ * @param {string} params.dataplaneBaseUrl
+ * @param {string} params.channelTarget
+ * @param {string} params.appName
+ * @param {string} [params.baseName]
+ * @param {string} [params.environment]
+ * @param {string} params.appDescription
+ * @param {string} [params.icon]
+ * @returns {Object}
+ */
+function resolveChannelRuntimeValues(params) {
+  const target = getChannelTarget(params.channelTarget);
+  const base = normalizeBaseUrl(params.dataplaneBaseUrl);
+  const routeKey = target.routeSystemKey || target.key;
+  const systemPrefix = externalSystemsPrefix(routeKey);
+  const suffixes = getEndpointPathSuffixes(params.channelTarget);
+  const legacy = getLegacyApiPaths(params.channelTarget);
+
+  const resolved = {
+    dataplaneBaseUrl: base,
+    channelTarget: params.channelTarget,
+    routeSystemKey: routeKey,
+    appName: params.appName,
+    baseName: params.baseName || params.appName,
+    environment: params.environment || 'dev',
+    appDescription: params.appDescription,
+    icon: params.icon || '',
+    credentialKey: target.credentialKey,
+    assistantCatalogUrl: joinUrl(base, '/api/v1/workers/available'),
+    scopes: []
+  };
+
+  for (const [key, suffix] of Object.entries(suffixes)) {
+    resolved[key] = joinUrl(base, `${systemPrefix}${suffix}`);
+  }
+
+  for (const [key, legacyPath] of Object.entries(legacy)) {
+    if (!resolved[key]) {
+      resolved[key] = joinUrl(base, legacyPath);
+    }
+  }
+
+  return resolved;
+}
+
+module.exports = {
+  normalizeBaseUrl,
+  joinUrl,
+  externalSystemsPrefix,
+  getEndpointPathSuffixes,
+  resolveChannelRuntimeValues
+};

package/lib/channels/channel-status-display.js

@@ -0,0 +1,141 @@
+/**
+ * TTY output for app add-channel (plan 152).
+ *
+ * @fileoverview Channel install status display — customer language: Assistant
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const {
+  formatSuccessLine,
+  formatWarningLine,
+  formatBlockingError,
+  sectionTitle,
+  metadata
+} = require('../utils/cli-test-layout-chalk');
+
+/** @returns {string} */
+function separatorLine() {
+  const gray = chalk.gray;
+  return typeof gray === 'function'
+    ? gray('────────────────────────────────────────')
+    : '────────────────────────────────────────';
+}
+
+/**
+ * @param {Object} params
+ * @param {string} params.channelTarget
+ * @param {string} params.name
+ * @param {Object|null} params.channelExt
+ * @param {string} [params.approvalUrl]
+ */
+function displayExistingChannelStatus(params) {
+  logger.log(sectionTitle(`${params.channelTarget} channel: ${params.name}`));
+  logger.log('');
+  logger.log(metadata(`Status: ${params.channelExt?.status || 'unknown'}`));
+  if (params.channelExt?.baseName && params.channelExt.baseName !== params.name) {
+    logger.log(metadata(`Base name: ${params.channelExt.baseName}`));
+  }
+  logger.log(metadata(`External System: ${params.channelTarget}`));
+  logger.log(metadata(`Credential: ${params.channelExt?.credentialKey || '—'}`));
+  if (params.channelExt?.capabilities?.length) {
+    logger.log(metadata('Capabilities:'));
+    for (const cap of params.channelExt.capabilities) {
+      logger.log(`  - ${cap}`);
+    }
+  }
+  logger.log('');
+  logger.log(formatWarningLine('Channel install already configured. Use --force to regenerate artifacts.'));
+  if (params.approvalUrl) {
+    logger.log(metadata(`Approval URL: ${params.approvalUrl}`));
+  }
+  logger.log(separatorLine());
+}
+
+/**
+ * @param {Object} result
+ */
+function displayChannelCoreFields(result) {
+  logger.log(sectionTitle(`${result.channelTarget} channel: ${result.name}`));
+  logger.log('');
+  logger.log(metadata(`Status: ${result.statusLabel}`));
+  if (result.baseName && result.baseName !== result.name) {
+    logger.log(metadata(`Base name: ${result.baseName}`));
+  }
+  logger.log(metadata(`External System: ${result.channelTarget}`));
+  logger.log(metadata(`Credential: ${result.credentialKey}`));
+  if (result.capabilities?.length) {
+    logger.log(metadata('Capabilities:'));
+    for (const cap of result.capabilities) {
+      logger.log(`  - ${cap}`);
+    }
+  }
+  if (result.artifactPath) {
+    logger.log(metadata(`Artifact: ${result.artifactPath}`));
+  }
+  if (result.installGuidePath) {
+    logger.log(metadata(`Install guide: ${result.installGuidePath}`));
+  }
+}
+
+/**
+ * @param {Object|null} validation
+ */
+function displayValidationSection(validation) {
+  if (!validation) return;
+  logger.log('');
+  logger.log(metadata('Validation:'));
+  if (validation.callbackReachable) {
+    logger.log(formatSuccessLine('Callback reachable'));
+  }
+  if (validation.credentialValid) {
+    logger.log(formatSuccessLine('Credential valid'));
+  }
+  if (validation.assistantCatalogReachable) {
+    logger.log(formatSuccessLine('Assistant catalog reachable'));
+  }
+  if (validation.inboundVerification) {
+    logger.log(formatSuccessLine('Inbound verification configured'));
+  }
+}
+
+/**
+ * @param {Object} result
+ */
+function displayApprovalSection(result) {
+  if (!result.approvalUrl) return;
+  logger.log('');
+  logger.log(formatWarningLine('Approval required'));
+  logger.log(metadata('Open this URL as platform admin:'));
+  logger.log(chalk.cyan(result.approvalUrl));
+  logger.log('');
+  logger.log(metadata('After approval, run:'));
+  logger.log(chalk.white(`  aifabrix app add-channel ${result.channelTarget} --name "${result.name}"`));
+}
+
+/**
+ * @param {Object} result
+ */
+function displayChannelInstallResult(result) {
+  displayChannelCoreFields(result);
+  displayValidationSection(result.validation);
+  displayApprovalSection(result);
+  logger.log(separatorLine());
+}
+
+/**
+ * @param {string} message
+ */
+function displayChannelError(message) {
+  logger.error(formatBlockingError(message));
+}
+
+module.exports = {
+  displayExistingChannelStatus,
+  displayChannelInstallResult,
+  displayChannelError
+};

package/lib/channels/channel-targets.js

@@ -0,0 +1,115 @@
+/**
+ * Channel target registry for assistant communication channels (plan 152).
+ *
+ * @fileoverview Channel install targets — templates, capabilities, approval semantics
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/** @typedef {'teams-bot'|'slack'|'microsoft-copilot'|'chatgpt'|'web-embed'} ChannelTargetKey */
+
+const DEFAULT_CAPABILITIES = ['chat', 'notify'];
+
+const CHANNEL_TARGETS = {
+  'teams-bot': {
+    key: 'teams-bot',
+    channelType: 'teamsBot',
+    templateDir: 'teams-bot',
+    artifactFileName: 'channel-teams-bot.json',
+    artifactFormat: 'json',
+    credentialKey: 'teams-bot',
+    routeSystemKey: 'teams',
+    capabilities: DEFAULT_CAPABILITIES,
+    approvalRequired: true,
+    experimental: false
+  },
+  slack: {
+    key: 'slack',
+    channelType: 'slack',
+    templateDir: 'slack',
+    artifactFileName: 'channel-slack.json',
+    artifactFormat: 'json',
+    credentialKey: 'slack-app',
+    routeSystemKey: 'slack',
+    capabilities: DEFAULT_CAPABILITIES,
+    approvalRequired: true,
+    experimental: false
+  },
+  'microsoft-copilot': {
+    key: 'microsoft-copilot',
+    channelType: 'microsoftCopilot',
+    templateDir: 'microsoft-copilot',
+    artifactFileName: 'channel-microsoft-copilot.json',
+    artifactFormat: 'json',
+    credentialKey: 'microsoft-copilot-channel',
+    capabilities: [...DEFAULT_CAPABILITIES, 'enterpriseActions'],
+    approvalRequired: true,
+    experimental: false
+  },
+  chatgpt: {
+    key: 'chatgpt',
+    channelType: 'chatgpt',
+    templateDir: 'chatgpt',
+    artifactFileName: 'channel-chatgpt.json',
+    artifactFormat: 'json',
+    credentialKey: 'chatgpt-channel',
+    capabilities: ['chat', 'enterpriseActions'],
+    approvalRequired: true,
+    experimental: false
+  },
+  'web-embed': {
+    key: 'web-embed',
+    channelType: 'webEmbed',
+    templateDir: 'web-embed',
+    artifactFileName: 'channel-web-embed.json',
+    artifactFormat: 'json',
+    credentialKey: 'web-embed-channel',
+    capabilities: DEFAULT_CAPABILITIES,
+    approvalRequired: false,
+    experimental: true
+  }
+};
+
+const CHANNEL_TARGET_KEYS = Object.keys(CHANNEL_TARGETS);
+
+/**
+ * @param {string} channelTarget
+ * @returns {boolean}
+ */
+function isChannelTargetKey(channelTarget) {
+  return typeof channelTarget === 'string' && CHANNEL_TARGET_KEYS.includes(channelTarget);
+}
+
+/**
+ * @param {string} channelTarget
+ * @returns {typeof CHANNEL_TARGETS[string]}
+ */
+function getChannelTarget(channelTarget) {
+  if (!isChannelTargetKey(channelTarget)) {
+    throw new Error(
+      `Unknown channel target "${channelTarget}". Expected one of: ${CHANNEL_TARGET_KEYS.join(', ')}`
+    );
+  }
+  return CHANNEL_TARGETS[channelTarget];
+}
+
+/**
+ * Default customer-facing description when --description is omitted.
+ * @returns {string}
+ */
+function getDefaultChannelDescription() {
+  return (
+    'Enterprise AI assistant for employees. Provides access to approved assistants, ' +
+    'enterprise knowledge, business workflows, and governed actions through AI Fabrix.'
+  );
+}
+
+module.exports = {
+  CHANNEL_TARGETS,
+  CHANNEL_TARGET_KEYS,
+  isChannelTargetKey,
+  getChannelTarget,
+  getDefaultChannelDescription
+};

package/lib/cli/index.js

@@ -22,6 +22,7 @@ const { setupExternalSystemCommands } = require('./setup-external-system');
 const { setupAppCommands: setupAppManagementCommands } = require('../commands/app');
 const { setupDatasourceCommands } = require('../commands/datasource');
 const { setupDimensionCommands } = require('../commands/dimension');
+const { setupResourceTypeCommands } = require('../commands/resource-type');
 const { setupIdentityCommands } = require('../commands/identity');
 const { setupProtectionCommands } = require('../commands/protection');
 const { setupCredentialDeploymentCommands } = require('./setup-credential-deployment');
@@ -29,6 +30,18 @@ const { setupIntegrationClientCommands } = require('./setup-integration-client')
 const { setupPlatformCommands } = require('./setup-platform');
 const { setupCertificationCommands } = require('./setup-certification-commands');
 const { setupGovernanceCommands } = require('../commands/governance');
+const { setupChannelCommands } = require('../commands/channel');
+
+/**
+ * Dev, secrets, parameters, and platform commands (keeps setupCommands under statement limit).
+ * @param {import('commander').Command} program
+ */
+function setupDevAndPlatformCommands(program) {
+  setupDevCommands(program);
+  setupSecretsCommands(program);
+  setupParametersCommands(program);
+  setupPlatformCommands(program);
+}
 
 /**
  * Sets up all CLI commands on the Commander program instance
@@ -42,18 +55,17 @@ function setupCommands(program) {
   setupGovernanceCommands(program);
   setupEnvironmentCommands(program);
   setupAppManagementCommands(program);
+  setupChannelCommands(program);
   setupDatasourceCommands(program);
   setupDimensionCommands(program);
+  setupResourceTypeCommands(program);
   setupIdentityCommands(program);
   setupProtectionCommands(program);
   setupUtilityCommands(program);
   setupCredentialDeploymentCommands(program);
   setupIntegrationClientCommands(program);
   setupExternalSystemCommands(program);
-  setupDevCommands(program);
-  setupSecretsCommands(program);
-  setupParametersCommands(program);
-  setupPlatformCommands(program);
+  setupDevAndPlatformCommands(program);
 }
 
 module.exports = {

package/lib/cli/setup-app.js

@@ -112,6 +112,49 @@ function normalizeExternalOptions(options) {
   return normalized;
 }
 
+/**
+ * Whether normalized options include all external CLI fields for headless create.
+ * @param {Object} normalized - Normalized external create options
+ * @returns {boolean}
+ */
+function hasFullExternalCliOptions(normalized) {
+  return Boolean(
+    normalized.systemKey &&
+    normalized.systemDisplayName &&
+    normalized.systemDescription &&
+    normalized.systemType &&
+    normalized.authType &&
+    normalized.entityType &&
+    normalized.datasourceCount
+  );
+}
+
+/**
+ * Map positional systemKey and apply headless defaults for external create.
+ * @param {string} appName - Positional appKey or systemKey from CLI
+ * @param {Object} options - Raw CLI options
+ * @returns {Object} Normalized options ready for createApp
+ */
+function prepareExternalCreateOptions(appName, options) {
+  const normalized = normalizeExternalOptions(options);
+  const isExternalType = options.type === 'external' || !options.type;
+
+  if (isExternalType && appName) {
+    normalized.systemKey = appName;
+  }
+
+  if (isExternalType && hasFullExternalCliOptions(normalized)) {
+    if (!Object.prototype.hasOwnProperty.call(normalized, 'github')) {
+      normalized.github = false;
+    }
+    if (!Object.prototype.hasOwnProperty.call(normalized, 'controller')) {
+      normalized.controller = false;
+    }
+  }
+
+  return normalized;
+}
+
 /**
  * Validate required options for non-interactive external creation
  * @param {Object} normalizedOptions - Normalized options
@@ -149,7 +192,7 @@ async function handleCreateCommand(appName, options) {
   }
 
   const wizardOptions = { app: appName, ...options };
-  const normalizedOptions = normalizeExternalOptions(options);
+  const normalizedOptions = prepareExternalCreateOptions(appName, options);
 
   const isExternalType = options.type === 'external' || !options.type;
   const isNonInteractive = process.stdin && process.stdin.isTTY === false;
@@ -279,7 +322,10 @@ function setupBuildRunLogsDownCommands(program) {
     .option('-f, --force-template', 'Force rebuild from template')
     .option('--no-cache', 'Full Docker rebuild (disable layer cache); use after Dockerfile or context fixes')
     .option('-t, --tag <tag>', 'Image tag (default: latest). Set image.tag in application.yaml to match for deploy.')
-    .option('--base', 'Also tag the manifest base image name (after developer-scoped build when developer id > 0)')
+    .option(
+      '--base',
+      'When manifest omits image: also tag the base repository after a developer-scoped build (ignored when application.yaml defines image)'
+    )
     .action(async(appName, options) => {
       try {
         const imageTag = await app.buildApp(appName, options);
@@ -437,4 +483,9 @@ function setupAppCommands(program) {
   setupPushDeployDockerfileCommands(program);
 }
 
-module.exports = { setupAppCommands };
+module.exports = {
+  setupAppCommands,
+  normalizeExternalOptions,
+  prepareExternalCreateOptions,
+  validateNonInteractiveExternalOptions
+};

package/lib/cli/setup-infra-up-dataplane-action.js

@@ -15,7 +15,7 @@ const { handleCommandError, isAuthenticationError } = require('../utils/cli-util
 const { resolveControllerUrl } = require('../utils/controller-url');
 const { handleLogin } = require('../commands/login');
 const { handleUpDataplane } = require('../commands/up-dataplane');
-const { cleanBuilderAppDirs } = require('../commands/up-common');
+const { cleanBuilderAppDirs, DATAPLANE_BUILDER_APP_KEYS } = require('../commands/up-common');
 const { runGuidedUpDataplane } = require('./infra-guided');
 const { recordInfraInstallationCommand } = require('./installation-log-command');
 
@@ -26,7 +26,7 @@ const { recordInfraInstallationCommand } = require('./installation-log-command')
 async function runUpDataplaneWork(options) {
   let cleanedAppKeys = [];
   if (options.force) {
-    const c = await cleanBuilderAppDirs(['dataplane']);
+    const c = await cleanBuilderAppDirs([...DATAPLANE_BUILDER_APP_KEYS]);
     cleanedAppKeys = Array.isArray(c) ? c : [];
   }
   if (!options.verbose) {

package/lib/cli/setup-infra-up-platform-action.js

@@ -19,6 +19,7 @@ const { handleUpDataplane } = require('../commands/up-dataplane');
 const {
   applyUpPlatformForceConfig,
   cleanBuilderAppDirs,
+  PLATFORM_BUILDER_CLEAN_APP_KEYS,
   prepareUrlsLocalRegistryForUpPlatform
 } = require('../commands/up-common');
 const { runGuidedUpPlatform } = require('./infra-guided');
@@ -35,7 +36,7 @@ async function runUpPlatformWork(options) {
   let platformForceCleanSummary = null;
   if (options.force) {
     const forceSummary = await applyUpPlatformForceConfig({ silent: !options.verbose });
-    const cleanedApps = await cleanBuilderAppDirs(PLATFORM_APPS, {
+    const cleanedApps = await cleanBuilderAppDirs(PLATFORM_BUILDER_CLEAN_APP_KEYS, {
       silent: !options.verbose
     });
     cleanedAppKeys = Array.isArray(cleanedApps) ? cleanedApps : [];

package/lib/cli/setup-platform.js

@@ -54,7 +54,7 @@ function registerSetup(program) {
     .command('setup')
     .description('Install or refresh the full AI Fabrix platform (infra + miso + dataplane)')
     .option('-d, --developer <id>', 'Pin developer ID before fresh install (fresh path only; ignored when infra is already up)')
-    .option('--platform <mode>', 'Platform mode: single (direct ports) or full (Traefik front door + multi-env)')
+    .option('--platform <mode>', 'Platform mode: single, single-traefik (Traefik + TLS), or full (multi-env; advanced)')
     .option('--installation <profile>', 'Installation profile: dev (one password) or pro (autogen/manual)')
     .option('--pro-password-mode <mode>', 'Pro profile only: autogen or manual')
     .option('--admin-email <email>', 'Admin email (non-interactive fresh install)')

package/lib/cli/setup-utility-help-after.js

@@ -46,8 +46,11 @@ Examples:
   $ aifabrix resolve hubspot-demo
     External integration: resolves integration/<systemKey>/env.template to .env using local host ports (no Docker rewrite).
 
+  $ aifabrix resolve dataplane --force
+    Seed missing secret keys and replace the full .env from env.template (no merge with an existing file).
+
   $ aifabrix resolve dataplane --fresh
-    Regenerate the full .env from env.template (no merge with an existing file). Use after adding many new variables or when a normal resolve did not pick up new template lines.
+    Replace the full .env only (no merge; does not seed missing secret keys). Same .env output as --force when secrets are already set.
 
   $ aifabrix secret set hubspot-demo/token "<your-token>"
     Store a secret when resolve reports a missing kv:// reference.