@aifabrix/builder 2.40.2 → 2.42.0

package/lib/commands/wizard-core.js

@@ -3,19 +3,21 @@
  * @author AI Fabrix Team
  * @version 2.0.0
  */
+/* eslint-disable max-lines */
 
 const chalk = require('chalk');
 const ora = require('ora');
 const path = require('path');
 const fs = require('fs').promises;
 const logger = require('../utils/logger');
-const { getDeploymentAuth } = require('../utils/token-manager');
+const { getDeploymentAuth, requireBearerForDataplanePipeline } = require('../utils/token-manager');
 const { resolveControllerUrl } = require('../utils/controller-url');
 const { normalizeWizardConfigs } = require('./wizard-config-normalizer');
 const {
   createWizardSession,
   updateWizardSession,
   detectType,
+  getPlatformConfig,
   generateConfig,
   validateWizardConfig,
   getDeploymentDocs,
@@ -29,9 +31,17 @@ const {
   runCredentialSelectionLoop,
   buildConfigPreferences,
   buildConfigPayload,
+  buildPlatformConfigPayload,
   extractConfigurationFromResponse,
-  throwConfigGenerationError
+  writeDebugLog,
+  saveDebugManifestOnErrorAndThrow,
+  throwValidationFailureWithDebug,
+  resolveCredentialConfig,
+  fetchSystemsListForAddDatasource,
+  resolveExternalSystemForAddDatasource
 } = require('./wizard-core-helpers');
+const { validateDatasourceKeysBeforePlatformConfig } = require('../validation/validate-datasource-keys-api');
+const { handleEntitySelection } = require('./wizard-entity-selection');
 
 /**
  * Validate app name and check if directory exists
@@ -263,35 +273,56 @@ async function handleTypeDetection(dataplaneUrl, authConfig, openapiSpec) {
  * @param {Object} [options.configPrefs] - Preferences from wizard.yaml
  * @param {string} [options.credentialIdOrKey] - Credential ID or key (optional)
  * @param {string} [options.systemIdOrKey] - System ID or key (optional)
+ * @param {string} [options.sourceType] - Source type (use 'known-platform' to call platforms config endpoint)
+ * @param {string} [options.platformKey] - Platform key for known-platform (e.g. 'hubspot')
+ * @param {string} [options.appName] - App name for writing debug.log when debug=true
  * @returns {Promise<Object>} Generated configuration
  */
+async function callGenerateApi(dataplaneUrl, authConfig, options, prefs) {
+  if (options.sourceType === 'known-platform' && options.platformKey) {
+    await validateDatasourceKeysBeforePlatformConfig(
+      dataplaneUrl, authConfig, options.platformKey, options.datasourceKeys
+    );
+    const platformPayload = buildPlatformConfigPayload({
+      credentialIdOrKey: options.credentialIdOrKey,
+      datasourceKeys: options.datasourceKeys,
+      configurationValues: options.configurationValues,
+      debug: prefs.debug
+    });
+    return await getPlatformConfig(dataplaneUrl, authConfig, options.platformKey, platformPayload);
+  }
+  const configPayload = buildConfigPayload({
+    openapiSpec: options.openapiSpec,
+    detectedType: options.detectedType,
+    mode: options.mode,
+    prefs,
+    credentialIdOrKey: options.credentialIdOrKey,
+    systemIdOrKey: options.systemIdOrKey,
+    entityName: options.entityName
+  });
+  return await generateConfig(dataplaneUrl, authConfig, configPayload);
+}
 
 async function handleConfigurationGeneration(dataplaneUrl, authConfig, options) {
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 5: Generate Configuration'));
   const prefs = buildConfigPreferences(options.configPrefs);
   const spinner = ora('Generating configuration via AI (10-30 seconds)...').start();
   try {
-    const configPayload = buildConfigPayload({
-      openapiSpec: options.openapiSpec,
-      detectedType: options.detectedType,
-      mode: options.mode,
-      prefs,
-      credentialIdOrKey: options.credentialIdOrKey,
-      systemIdOrKey: options.systemIdOrKey
-    });
-    const generateResponse = await generateConfig(dataplaneUrl, authConfig, configPayload);
+    const generateResponse = await callGenerateApi(dataplaneUrl, authConfig, options, prefs);
     spinner.stop();
     if (!generateResponse.success) {
-      throwConfigGenerationError(generateResponse);
+      await saveDebugManifestOnErrorAndThrow(generateResponse, { enableDebug: prefs.debug, appName: options.appName });
     }
     const result = extractConfigurationFromResponse(generateResponse);
     const normalized = normalizeWizardConfigs(result.systemConfig, result.datasourceConfigs);
+    if (prefs.debug && options.appName) {
+      const debugLog = generateResponse.data?.debugLog;
+      if (debugLog && typeof debugLog === 'string') {
+        await writeDebugLog(options.appName, debugLog);
+      }
+    }
     logger.log(chalk.green('\u2713 Configuration generated successfully'));
-    return {
-      systemConfig: normalized.systemConfig,
-      datasourceConfigs: normalized.datasourceConfigs,
-      systemKey: result.systemKey
-    };
+    return { systemConfig: normalized.systemConfig, datasourceConfigs: normalized.datasourceConfigs, systemKey: result.systemKey };
   } catch (error) {
     spinner.stop();
     throw error;
@@ -306,9 +337,11 @@ async function handleConfigurationGeneration(dataplaneUrl, authConfig, options)
  * @param {Object} authConfig - Authentication configuration
  * @param {Object} systemConfig - System configuration
  * @param {Object[]} datasourceConfigs - Datasource configurations
+ * @param {Object} [options] - Optional options
+ * @param {boolean} [options.debug] - When true, save debug manifest on validation failure
+ * @param {string} [options.appName] - App name for writing debug files
  */
-// eslint-disable-next-line max-statements
-async function validateWizardConfiguration(dataplaneUrl, authConfig, systemConfig, datasourceConfigs) {
+async function validateWizardConfiguration(dataplaneUrl, authConfig, systemConfig, datasourceConfigs, options = {}) {
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 6: Validate Configuration'));
   const spinner = ora('Validating configuration...').start();
   try {
@@ -322,16 +355,13 @@ async function validateWizardConfiguration(dataplaneUrl, authConfig, systemConfi
         const errorDetail = validateResponse.errorData?.detail || validateResponse.errorData?.message;
         const errorMsg = errors.length > 0 ? errors.map(e => e.message || e).join(', ') : errorDetail || validateResponse.error || 'Validation failed';
         spinner.stop();
-        throw new Error(`Configuration validation failed: ${errorMsg}`);
+        await throwValidationFailureWithDebug(validateResponse, systemConfig, configs, errorMsg, options);
       }
       if (validateResponse.data?.warnings?.length > 0) warnings.push(...validateResponse.data.warnings);
     }
     spinner.stop();
     logger.log(chalk.green('\u2713 Configuration validated successfully'));
-    if (warnings.length > 0) {
-      logger.log(chalk.yellow('\n\u26A0 Warnings:'));
-      warnings.forEach(w => logger.log(chalk.yellow(`  - ${w.message || w}`)));
-    }
+    if (warnings.length > 0) logger.log(chalk.yellow('\n\u26A0 Warnings:\n' + warnings.map(w => `  - ${w.message || w}`).join('\n')));
   } catch (error) {
     spinner.stop();
     throw error;
@@ -370,7 +400,9 @@ async function tryUpdateReadmeFromDeploymentDocs(appPath, appName, dataplaneUrl,
     ? await postDeploymentDocs(dataplaneUrl, authConfig, systemKey, body)
     : await getDeploymentDocs(dataplaneUrl, authConfig, systemKey);
   const content = docsResponse?.data?.content ?? docsResponse?.content;
-  if (content && typeof content === 'string') {
+  // Only overwrite README when the API returns substantial content; otherwise keep the template README
+  const MIN_README_LENGTH = 400;
+  if (content && typeof content === 'string' && content.trim().length >= MIN_README_LENGTH) {
     const readmePath = path.join(appPath, 'README.md');
     await fs.writeFile(readmePath, content, 'utf8');
     logger.log(chalk.gray('  Updated README.md from deployment-docs API (application config + deploy JSON).'));
@@ -393,7 +425,9 @@ async function handleFileSaving(appName, systemConfig, datasourceConfigs, system
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 7: Save Files'));
   const spinner = ora('Saving files...').start();
   try {
-    const generatedFiles = await generateWizardFiles(appName, systemConfig, datasourceConfigs, systemKey, { aiGeneratedReadme: null });
+    const config = require('../core/config');
+    const format = (await config.getFormat()) || 'yaml';
+    const generatedFiles = await generateWizardFiles(appName, systemConfig, datasourceConfigs, systemKey, { aiGeneratedReadme: null, format });
     if (systemKey && dataplaneUrl && authConfig && generatedFiles.appPath) {
       try {
         await tryUpdateReadmeFromDeploymentDocs(generatedFiles.appPath, appName, dataplaneUrl, authConfig, systemKey);
@@ -427,14 +461,14 @@ async function setupDataplaneAndAuth(options, appName) {
   const { resolveEnvironment } = require('../core/config');
   const environment = await resolveEnvironment();
   const controllerUrl = await resolveControllerUrl();
-  // Prefer device token; use client token or client credentials when available.
-  // Some dataplanes accept only client credentials; getDeploymentAuth tries all.
+  // getDeploymentAuth returns token-based auth only (Bearer); never client-credentials for app endpoints.
   let authConfig;
   try {
     authConfig = await getDeploymentAuth(controllerUrl, environment, appName);
   } catch (error) {
     throw new Error(`Authentication failed: ${error.message}`);
   }
+  requireBearerForDataplanePipeline(authConfig);
   const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
   let dataplaneUrl;
   try {
@@ -459,8 +493,12 @@ module.exports = {
   handleOpenApiParsing,
   handleCredentialSelection,
   handleTypeDetection,
+  handleEntitySelection,
   handleConfigurationGeneration,
   validateWizardConfiguration,
   handleFileSaving,
-  setupDataplaneAndAuth
+  setupDataplaneAndAuth,
+  resolveCredentialConfig,
+  fetchSystemsListForAddDatasource,
+  resolveExternalSystemForAddDatasource
 };

package/lib/commands/wizard-dataplane.js

@@ -59,7 +59,7 @@ function isNotFoundError(error) {
 function createDataplaneNotFoundError() {
   return new Error(
     'Could not discover dataplane URL from controller. No dataplane service application found in this environment. ' +
-    'Please provide the dataplane URL using --dataplane <url> flag.'
+    'Ensure the dataplane service is registered in the controller.'
   );
 }
 

package/lib/commands/wizard-entity-selection.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Entity selection step for OpenAPI multi-entity wizard flow
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const chalk = require('chalk');
+const logger = require('../utils/logger');
+const { discoverEntities } = require('../api/wizard.api');
+const { validateEntityNameForOpenApi } = require('../validation/wizard-datasource-validation');
+const { promptForEntitySelection } = require('../generator/wizard-prompts');
+
+/**
+ * Handle entity selection step (OpenAPI multi-entity).
+ * Calls discover-entities; if entities found, prompts user to select one.
+ * @async
+ * @param {string} dataplaneUrl - Dataplane URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} openapiSpec - OpenAPI specification
+ * @returns {Promise<string|null>} Selected entity name or null (skip)
+ */
+async function handleEntitySelection(dataplaneUrl, authConfig, openapiSpec) {
+  if (!openapiSpec || typeof openapiSpec !== 'object') return null;
+  try {
+    const response = await discoverEntities(dataplaneUrl, authConfig, openapiSpec);
+    const entities = response?.data?.entities;
+    if (!Array.isArray(entities) || entities.length === 0) return null;
+
+    logger.log(chalk.blue('\n\uD83D\uDCCB Step 4.5: Select Entity'));
+    const entityName = await promptForEntitySelection(entities);
+    const validation = validateEntityNameForOpenApi(entityName, entities);
+    if (!validation.valid) {
+      throw new Error(`Invalid entity '${entityName}'. Available: ${entities.map(e => e.name).join(', ')}`);
+    }
+    logger.log(chalk.green(`\u2713 Selected entity: ${entityName}`));
+    return entityName;
+  } catch (error) {
+    logger.log(chalk.yellow(`Warning: Entity discovery failed, using default: ${error.message}`));
+    return null;
+  }
+}
+
+module.exports = { handleEntitySelection };

package/lib/commands/wizard-headless.js

@@ -22,6 +22,29 @@ const {
   handleFileSaving,
   setupDataplaneAndAuth
 } = require('./wizard-core');
+const { discoverEntities } = require('../api/wizard.api');
+const { validateEntityNameForOpenApi } = require('../validation/wizard-datasource-validation');
+
+/**
+ * Validate entityName for headless config (throws if invalid)
+ * @async
+ * @param {string} entityName - Entity from source
+ * @param {Object} openapiSpec - OpenAPI spec
+ * @param {string} sourceType - Source type
+ * @param {string} dataplaneUrl - Dataplane URL
+ * @param {Object} authConfig - Auth config
+ * @throws {Error} If entityName invalid
+ */
+async function validateHeadlessEntityName(entityName, openapiSpec, sourceType, dataplaneUrl, authConfig) {
+  if (!entityName || !openapiSpec || sourceType === 'known-platform') return;
+  const discoverResponse = await discoverEntities(dataplaneUrl, authConfig, openapiSpec);
+  const entities = discoverResponse?.data?.entities || [];
+  const validation = validateEntityNameForOpenApi(entityName, entities);
+  if (!validation.valid) {
+    const available = entities.map(e => e.name).join(', ');
+    throw new Error(`Invalid entityName '${entityName}'. Available from discover-entities: ${available || 'none'}`);
+  }
+}
 
 /**
  * Execute wizard flow from config file (headless mode)
@@ -30,11 +53,15 @@ const {
  * @param {Object} wizardConfig - Validated wizard configuration
  * @param {string} dataplaneUrl - Dataplane URL
  * @param {Object} authConfig - Authentication configuration
+ * @param {Object} [opts] - Optional overrides
+ * @param {boolean} [opts.debug] - Enable debug (CLI --debug); overrides wizard.yaml preferences.debug
  * @returns {Promise<void>} Resolves when wizard flow completes
  * @throws {Error} If wizard flow fails
  */
-async function executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig) {
+async function executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig, opts = {}) {
   const { appName, mode, systemIdOrKey, source, credential, preferences } = wizardConfig;
+  const configPrefs = { ...preferences };
+  if (opts.debug === true) configPrefs.debug = true;
 
   // Step 1: Create Session
   const { sessionId } = await handleModeSelection(dataplaneUrl, authConfig, mode, systemIdOrKey);
@@ -51,18 +78,27 @@ async function executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig) {
   // Step 4: Detect Type
   const detectedType = await handleTypeDetection(dataplaneUrl, authConfig, openapiSpec);
 
+  await validateHeadlessEntityName(source?.entityName, openapiSpec, sourceType, dataplaneUrl, authConfig);
+
   // Step 5: Generate Configuration
   const { systemConfig, datasourceConfigs, systemKey } = await handleConfigurationGeneration(dataplaneUrl, authConfig, {
     mode,
     openapiSpec,
     detectedType,
-    configPrefs: preferences,
+    configPrefs,
     credentialIdOrKey,
-    systemIdOrKey
+    systemIdOrKey,
+    sourceType,
+    platformKey: sourceType === 'known-platform' ? sourceData : undefined,
+    datasourceKeys: source?.datasourceKeys,
+    configurationValues: source?.configurationValues,
+    entityName: source?.entityName,
+    appName
   });
 
   // Step 6: Validate Configuration
-  await validateWizardConfiguration(dataplaneUrl, authConfig, systemConfig, datasourceConfigs);
+  const debugOpts = opts.debug ? { debug: true, appName } : {};
+  await validateWizardConfiguration(dataplaneUrl, authConfig, systemConfig, datasourceConfigs, debugOpts);
 
   // Step 7: Save Files
   await handleFileSaving(
@@ -87,6 +123,9 @@ async function executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig) {
 async function handleWizardHeadless(options) {
   logger.log(chalk.blue('\n\uD83E\uDDD9 AI Fabrix External System Wizard (Headless Mode)\n'));
   logger.log(chalk.gray(`Reading configuration from: ${options.config}`));
+  if (options.debug) {
+    logger.log(chalk.gray('[DEBUG] Wizard debug mode enabled'));
+  }
 
   // Validate wizard config file
   const validationResult = await validateWizardConfigFile(options.config);
@@ -109,7 +148,7 @@ async function handleWizardHeadless(options) {
   const { dataplaneUrl, authConfig } = await setupDataplaneAndAuth(options, appName);
 
   // Execute wizard flow from config
-  await executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig);
+  await executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig, { debug: options.debug });
 }
 
 module.exports = { handleWizardHeadless, executeWizardFromConfig };

package/lib/commands/wizard-helpers.js

@@ -10,15 +10,17 @@ const chalk = require('chalk');
 const logger = require('../utils/logger');
 
 /**
- * Build preferences object for wizard.yaml (schema shape: intent, fieldOnboardingLevel, enableOpenAPIGeneration, enableMCP, enableABAC, enableRBAC)
+ * Build preferences object for wizard.yaml (schema shape: intent, fieldOnboardingLevel, enableOpenAPIGeneration, enableMCP, enableABAC, enableRBAC, debug)
  * @param {string} intent - User intent
  * @param {Object} preferences - From promptForUserPreferences (fieldOnboardingLevel, mcp, abac, rbac)
+ * @param {Object} [opts] - Optional overrides
+ * @param {boolean} [opts.debug] - Enable debug (CLI --debug); saved to wizard.yaml for headless runs
  * @returns {Object} Preferences for wizard-config schema
  */
-function buildPreferencesForSave(intent, preferences) {
+function buildPreferencesForSave(intent, preferences, opts = {}) {
   const level = preferences?.fieldOnboardingLevel;
   const validLevel = level === 'standard' || level === 'minimal' ? level : 'full';
-  return {
+  const result = {
     intent: intent || 'general integration',
     fieldOnboardingLevel: validLevel,
     enableOpenAPIGeneration: true,
@@ -26,6 +28,8 @@ function buildPreferencesForSave(intent, preferences) {
     enableABAC: Boolean(preferences?.abac),
     enableRBAC: Boolean(preferences?.rbac)
   };
+  if (opts.debug === true || preferences?.debug === true) result.debug = true;
+  return result;
 }
 
 /**

package/lib/commands/wizard.js

@@ -3,12 +3,13 @@
  * @author AI Fabrix Team
  * @version 2.0.0
  */
+/* eslint-disable max-lines */
 
 const chalk = require('chalk');
 const logger = require('../utils/logger');
 const {
   promptForMode,
-  promptForSystemIdOrKey,
+  promptForExistingSystem,
   promptForSourceType,
   promptForOpenApiFile,
   promptForOpenApiUrl,
@@ -24,46 +25,30 @@ const {
 const {
   validateAndCheckAppDirectory,
   formatDataplaneRejectedTokenMessage,
+  extractSessionId,
   handleOpenApiParsing,
   handleCredentialSelection,
   handleTypeDetection,
+  handleEntitySelection,
   handleConfigurationGeneration,
   validateWizardConfiguration,
   handleFileSaving,
-  setupDataplaneAndAuth
+  setupDataplaneAndAuth,
+  resolveCredentialConfig,
+  fetchSystemsListForAddDatasource,
+  resolveExternalSystemForAddDatasource
 } = require('./wizard-core');
 const { handleWizardHeadless } = require('./wizard-headless');
-const { createWizardSession, updateWizardSession, getWizardPlatforms } = require('../api/wizard.api');
-const { getExternalSystem } = require('../api/external-systems.api');
+const { createWizardSession, updateWizardSession, getWizardPlatforms, getPreview } = require('../api/wizard.api');
 const { writeWizardConfig, wizardConfigExists, validateWizardConfig } = require('../validation/wizard-config-validator');
 const { appendWizardError } = require('../utils/cli-utils');
 const {
   buildPreferencesForSave,
   buildWizardStateForSave,
   showWizardConfigSummary,
-  ensureIntegrationDir,
-  isExternalSystemForAddDatasource
+  ensureIntegrationDir
 } = require('./wizard-helpers');
 
-/**
- * Extract session ID from response data
- * @function extractSessionId
- * @param {Object} responseData - Response data from API
- * @returns {string} Session ID
- * @throws {Error} If session ID not found or invalid
- */
-function extractSessionId(responseData) {
-  let sessionId = responseData?.data?.sessionId || responseData?.sessionId ||
-                  responseData?.data?.session_id || responseData?.session_id;
-  if (sessionId && typeof sessionId === 'object') {
-    sessionId = sessionId.id || sessionId.sessionId || sessionId.session_id;
-  }
-  if (!sessionId || typeof sessionId !== 'string') {
-    throw new Error(`Session ID not found: ${JSON.stringify(responseData, null, 2)}`);
-  }
-  return sessionId;
-}
-
 /**
  * Create wizard session with given mode and optional systemIdOrKey (no prompts)
  * @async
@@ -151,7 +136,8 @@ async function handleInteractiveConfigGeneration(options) {
     fieldOnboardingLevel: preferences.fieldOnboardingLevel || 'full',
     enableMCP: preferences.mcp,
     enableABAC: preferences.abac,
-    enableRBAC: preferences.rbac
+    enableRBAC: preferences.rbac,
+    debug: options.debug === true
   };
 
   const result = await handleConfigurationGeneration(options.dataplaneUrl, options.authConfig, {
@@ -160,28 +146,51 @@ async function handleInteractiveConfigGeneration(options) {
     detectedType: options.detectedType,
     configPrefs,
     credentialIdOrKey: options.credentialIdOrKey,
-    systemIdOrKey: options.systemIdOrKey
+    systemIdOrKey: options.systemIdOrKey,
+    sourceType: options.sourceType,
+    platformKey: options.sourceType === 'known-platform' ? options.sourceData : undefined,
+    entityName: options.entityName,
+    appName: options.appName
   });
 
   return {
     ...result,
-    preferences: buildPreferencesForSave(userIntent, preferences)
+    preferences: buildPreferencesForSave(userIntent, preferences, { debug: options.debug })
   };
 }
 
 /**
  * Handle configuration review and validation step (interactive mode only)
+ * Fetches preview summary from dataplane; falls back to YAML dump if preview unavailable.
  * @async
  * @function handleConfigurationReview
  * @param {string} dataplaneUrl - Dataplane URL
  * @param {Object} authConfig - Authentication configuration
+ * @param {string} sessionId - Wizard session ID
  * @param {Object} systemConfig - System configuration
  * @param {Object[]} datasourceConfigs - Datasource configurations
- * @returns {Promise<Object>} Final configurations
+ * @param {Object} [opts] - Optional options
+ * @param {string} [opts.appKey] - App key for debug manifest path
+ * @param {boolean} [opts.debug] - When true, save debug manifest on validation failure
+ * @returns {Promise<Object|null>} Final configurations or null if cancelled
  */
-async function handleConfigurationReview(dataplaneUrl, authConfig, systemConfig, datasourceConfigs) {
+async function handleConfigurationReview(dataplaneUrl, authConfig, sessionId, systemConfig, datasourceConfigs, opts = {}) {
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 6-7: Review & Validate'));
-  const reviewResult = await promptForConfigReview(systemConfig, datasourceConfigs);
+
+  let preview = null;
+  try {
+    const previewResponse = await getPreview(dataplaneUrl, sessionId, authConfig);
+    if (previewResponse?.success && previewResponse?.data) {
+      preview = previewResponse.data;
+    }
+  } catch {
+    // Fall back to YAML display
+  }
+  if (!preview) {
+    logger.warn('Preview unavailable, showing full configuration.');
+  }
+
+  const reviewResult = await promptForConfigReview({ preview, systemConfig, datasourceConfigs });
 
   if (reviewResult.action === 'cancel') {
     logger.log(chalk.yellow('Wizard cancelled.'));
@@ -191,7 +200,10 @@ async function handleConfigurationReview(dataplaneUrl, authConfig, systemConfig,
   const finalSystemConfig = reviewResult.systemConfig || systemConfig;
   const finalDatasourceConfigs = reviewResult.datasourceConfigs || datasourceConfigs;
 
-  await validateWizardConfiguration(dataplaneUrl, authConfig, finalSystemConfig, finalDatasourceConfigs);
+  await validateWizardConfiguration(dataplaneUrl, authConfig, finalSystemConfig, finalDatasourceConfigs, {
+    debug: opts.debug,
+    appName: opts.appKey
+  });
 
   return { systemConfig: finalSystemConfig, datasourceConfigs: finalDatasourceConfigs };
 }
@@ -208,7 +220,7 @@ async function handleConfigurationReview(dataplaneUrl, authConfig, systemConfig,
  * @returns {Promise<Object>} Collected state (source, credential, preferences) for wizard.yaml save
  */
 async function doWizardSteps(appKey, dataplaneUrl, authConfig, sessionId, flowOpts, state) {
-  const { mode, systemIdOrKey, platforms } = flowOpts;
+  const { mode, systemIdOrKey, platforms, debug } = flowOpts;
   const { sourceType, sourceData } = await handleInteractiveSourceSelection(
     dataplaneUrl, sessionId, authConfig, platforms
   );
@@ -220,13 +232,13 @@ async function doWizardSteps(appKey, dataplaneUrl, authConfig, sessionId, flowOp
 
   const openapiSpec = await handleOpenApiParsing(dataplaneUrl, authConfig, sourceType, sourceData);
   const credentialAction = await promptForCredentialAction();
-  const configCredential = credentialAction.action === 'skip'
-    ? { action: 'skip' }
-    : { action: credentialAction.action, credentialIdOrKey: credentialAction.credentialIdOrKey };
+  const configCredential = await resolveCredentialConfig(dataplaneUrl, authConfig, credentialAction);
   state.credential = configCredential;
   const credentialIdOrKey = await handleCredentialSelection(dataplaneUrl, authConfig, configCredential);
 
   const detectedType = await handleTypeDetection(dataplaneUrl, authConfig, openapiSpec);
+  const entityName = openapiSpec && sourceType !== 'known-platform'
+    ? await handleEntitySelection(dataplaneUrl, authConfig, openapiSpec) : null;
   const genResult = await handleInteractiveConfigGeneration({
     dataplaneUrl,
     authConfig,
@@ -234,12 +246,24 @@ async function doWizardSteps(appKey, dataplaneUrl, authConfig, sessionId, flowOp
     openapiSpec,
     detectedType,
     credentialIdOrKey,
-    systemIdOrKey
+    systemIdOrKey,
+    sourceType,
+    sourceData,
+    entityName: entityName || undefined,
+    appName: appKey,
+    debug
   });
   const { systemConfig, datasourceConfigs, systemKey, preferences: savedPrefs } = genResult;
   state.preferences = savedPrefs || {};
 
-  const finalConfigs = await handleConfigurationReview(dataplaneUrl, authConfig, systemConfig, datasourceConfigs);
+  const finalConfigs = await handleConfigurationReview(
+    dataplaneUrl,
+    authConfig,
+    sessionId,
+    systemConfig,
+    datasourceConfigs,
+    { appKey, debug }
+  );
   if (!finalConfigs) return null;
 
   await handleFileSaving(
@@ -290,18 +314,22 @@ async function runWizardStepsAfterSession(appKey, dataplaneUrl, authConfig, sess
  * @returns {Promise<void>} Resolves when wizard flow completes
  */
 async function executeWizardFlow(appKey, dataplaneUrl, authConfig, flowOpts = {}) {
-  const { mode, systemIdOrKey, configPath } = flowOpts;
+  const { mode, systemIdOrKey, configPath, debug } = flowOpts;
 
+  if (debug) {
+    logger.log(chalk.gray(`[DEBUG] Wizard debug mode enabled for app: ${appKey}`));
+  }
   logger.log(chalk.blue('\n\uD83D\uDCCB Step 1: Create Session'));
   const sessionId = await createSessionFromParams(dataplaneUrl, authConfig, mode, systemIdOrKey, appKey);
   logger.log(chalk.green('\u2713 Session created'));
 
-  const platforms = await getWizardPlatforms(dataplaneUrl, authConfig);
+  const platforms = mode === 'add-datasource' ? [] : await getWizardPlatforms(dataplaneUrl, authConfig);
   const state = await runWizardStepsAfterSession(appKey, dataplaneUrl, authConfig, sessionId, {
     mode,
     systemIdOrKey,
     platforms,
-    configPath
+    configPath,
+    debug: flowOpts.debug
   });
   if (!state) return;
 
@@ -362,26 +390,15 @@ async function resolveCreateNewPath(options, loadedConfig) {
  * @returns {Promise<Object>} { appKey, configPath, dataplaneUrl, authConfig, systemIdOrKey }
  */
 async function resolveAddDatasourcePath(options, loadedConfig) {
-  let systemIdOrKey = loadedConfig?.systemIdOrKey || (await promptForSystemIdOrKey(loadedConfig?.systemIdOrKey));
-  const { dataplaneUrl, authConfig } = await setupDataplaneAndAuth(options, systemIdOrKey || 'wizard');
-  let systemResponse;
-  for (;;) {
-    try {
-      systemResponse = await getExternalSystem(dataplaneUrl, systemIdOrKey, authConfig);
-      const sys = systemResponse?.data || systemResponse;
-      if (sys && (systemResponse?.data || systemResponse?.success)) {
-        if (!isExternalSystemForAddDatasource(sys)) {
-          logger.log(chalk.red('Cannot add datasource to a webapp. Please enter an external system ID or key.'));
-          systemIdOrKey = await promptForSystemIdOrKey(systemIdOrKey);
-          continue;
-        }
-        break;
-      }
-    } catch (err) {
-      logger.log(chalk.red(`System not found or error: ${err.message}`));
-    }
-    systemIdOrKey = await promptForSystemIdOrKey(systemIdOrKey);
-  }
+  const { dataplaneUrl, authConfig } = await setupDataplaneAndAuth(
+    options,
+    loadedConfig?.systemIdOrKey || loadedConfig?.appKey || 'wizard'
+  );
+  const systemsList = await fetchSystemsListForAddDatasource(dataplaneUrl, authConfig);
+  const initialSystemIdOrKey = loadedConfig?.systemIdOrKey || (await promptForExistingSystem(systemsList, loadedConfig?.systemIdOrKey));
+  const { systemResponse, systemIdOrKey } = await resolveExternalSystemForAddDatasource(
+    dataplaneUrl, authConfig, systemsList, initialSystemIdOrKey
+  );
   const sys = systemResponse?.data || systemResponse;
   const appKey = sys?.key || sys?.systemKey || systemIdOrKey;
   const configPath = await ensureIntegrationDir(appKey);
@@ -449,7 +466,8 @@ async function handleWizardWithSavedConfig(options, loadedConfig, displayPath) {
 }
 
 async function handleWizardInteractive(options) {
-  const mode = await promptForMode();
+  const allowAddDatasource = !options.app;
+  const mode = allowAddDatasource ? await promptForMode(undefined, true) : 'create-system';
   const resolved = mode === 'create-system'
     ? await resolveCreateNewPath(options, null)
     : await resolveAddDatasourcePath(options, null);
@@ -457,7 +475,12 @@ async function handleWizardInteractive(options) {
   const { appKey, configPath, dataplaneUrl, authConfig } = resolved;
   const systemIdOrKey = mode === 'add-datasource' ? resolved.systemIdOrKey : undefined;
   try {
-    await executeWizardFlow(appKey, dataplaneUrl, authConfig, { mode, systemIdOrKey, configPath });
+    await executeWizardFlow(appKey, dataplaneUrl, authConfig, {
+      mode,
+      systemIdOrKey,
+      configPath,
+      debug: options.debug
+    });
     logger.log(chalk.gray(`To change settings, edit integration/${appKey}/wizard.yaml and run: aifabrix wizard ${appKey}`));
   } catch (error) {
     await handleWizardError(appKey, configPath, mode, systemIdOrKey, error);
@@ -480,5 +503,4 @@ async function handleWizard(options = {}) {
   }
   return await handleWizardInteractive(options);
 }
-
 module.exports = { handleWizard, handleWizardHeadless };