@aifabrix/builder 2.42.0 → 2.42.1

package/README.md

@@ -82,7 +82,7 @@ Create and deploy an external system (e.g. HubSpot): wizard or manual setup, the
 
 **Example: HubSpot**
 
-- Create: `aifabrix create hubspot-test --type external` (or `aifabrix wizard` for guided setup).
+- Create: `aifabrix create hubspot` (external is the default; or `aifabrix wizard` for guided setup). For a web app use `aifabrix create my-app --type webapp`.
 - Configure auth and datasources under `integration/hubspot-test/`.
 - Validate: `aifabrix validate hubspot-test`
 - Deploy: `aifabrix deploy hubspot-test`

package/integration/hubspot/README.md

@@ -26,9 +26,11 @@ Optional: `rbac.yaml` – Roles and permissions merged into the system when pres
 ### 1. Create External System
 
 ```bash
-aifabrix create hubspot --type external
+aifabrix create hubspot
 ```
 
+(External is the default type. Use `aifabrix create <name> --type webapp` for a builder app.)
+
 Or use the interactive wizard:
 
 ```bash

package/lib/api/wizard.api.js

@@ -219,8 +219,9 @@ async function getPlatformConfig(dataplaneUrl, authConfig, platformKey, config)
  * @param {string} config.detectedType - Detected API type (required, e.g., 'record-based')
  * @param {string} config.intent - User intent (required, any descriptive text)
  * @param {string} config.mode - Wizard mode (required, 'create-system' | 'add-datasource')
- * @param {string} [config.systemIdOrKey] - Existing system ID/key (required for add-datasource)
+ * @param {string} [config.systemIdOrKey] - Existing system ID/key (required for add-datasource; must be application/system key, not entity/datasource key)
  * @param {string} [config.credentialIdOrKey] - Credential ID or key
+ * @param {string|null} [config.systemDisplayName] - System-level display name for credential (e.g. 'Hubspot Demo'); when OpenAPI title is entity-specific, pass system name here
  * @param {string} [config.fieldOnboardingLevel] - Field onboarding level ('full' | 'standard' | 'minimal')
  * @param {boolean} [config.enableOpenAPIGeneration] - Enable OpenAPI operation generation
  * @param {Object} [config.userPreferences] - User preferences

package/lib/app/index.js

@@ -68,7 +68,7 @@ function validateAppNameAndSetup(appName, options) {
     throw new Error('Application name is required');
   }
 
-  const initialType = options.type || 'webapp';
+  const initialType = options.type || 'external';
   const baseDir = getBaseDirForAppType(initialType);
   const appPath = getAppPath(appName, initialType);
 
@@ -179,7 +179,7 @@ async function logApplicationCreation(appName, config, options) {
 async function createApp(appName, options = {}) {
   try {
     const { appPath } = validateAppNameAndSetup(appName, options);
-    await validateAppCreation(appName, options, appPath, getBaseDirForAppType(options.type || 'webapp'));
+    await validateAppCreation(appName, options, appPath, getBaseDirForAppType(options.type || 'external'));
 
     const mergedOptions = await handleTemplateSetup(options);
     const config = await promptForOptions(appName, mergedOptions);

package/lib/app/prompts.js

@@ -426,8 +426,8 @@ function mergePromptAnswers(appName, options, answers) {
  * @returns {Promise<Object>} Complete configuration
  */
 async function promptForOptions(appName, options) {
-  // Get app type from options (default to webapp)
-  const appType = options.type || 'webapp';
+  // Get app type from options (default to external)
+  const appType = options.type || 'external';
 
   // Build questions based on app type
   let questions = [];

package/lib/app/readme.js

@@ -150,6 +150,7 @@ function generateReadmeMd(appName, config) {
     const datasources = Array.isArray(config.datasources) && config.datasources.length > 0
       ? config.datasources
       : buildExternalDatasourcePlaceholders(systemKey, config.datasourceCount, fileExt);
+    const authType = config.authentication?.type || config.authentication?.method || config.authType;
     return generateExternalReadmeContent({
       appName,
       systemKey,
@@ -157,7 +158,8 @@ function generateReadmeMd(appName, config) {
       displayName: config.systemDisplayName,
       description: config.systemDescription,
       fileExt: config.fileExt,
-      datasources
+      datasources,
+      authType
     });
   }
   const context = buildReadmeContext(appName, config);

package/lib/cli/setup-app.js

@@ -84,14 +84,14 @@ async function handleCreateCommand(appName, options) {
   const wizardOptions = { app: appName, ...options };
   const normalizedOptions = normalizeExternalOptions(options);
 
-  const isExternalType = options.type === 'external';
+  const isExternalType = options.type === 'external' || !options.type;
   const isNonInteractive = process.stdin && process.stdin.isTTY === false;
 
   if (isExternalType && !options.wizard && isNonInteractive) {
     validateNonInteractiveExternalOptions(normalizedOptions);
   }
 
-  const shouldUseWizard = options.wizard && (options.type === 'external' || (!options.type && validTypes.includes('external')));
+  const shouldUseWizard = options.wizard && (options.type === 'external' || !options.type);
   if (shouldUseWizard) {
     const { handleWizard } = require('../commands/wizard');
     await handleWizard(wizardOptions);
@@ -110,7 +110,7 @@ function setupCreateCommand(program) {
     .option('-a, --authentication', 'Requires authentication/RBAC')
     .option('-l, --language <lang>', 'Runtime language (typescript/python)')
     .option('-t, --template <name>', 'Template to use (e.g., miso-controller, keycloak)')
-    .option('--type <type>', 'Application type (webapp, api, service, functionapp, external)', 'webapp')
+    .option('--type <type>', 'Application type (webapp, api, service, functionapp, external)', 'external')
     .option('--app', 'Generate minimal application files (package.json, index.ts or requirements.txt, main.py)')
     .option('-g, --github', 'Generate GitHub Actions workflows')
     .option('--github-steps <steps>', 'Extra GitHub workflow steps (comma-separated, e.g., npm,test)')

package/lib/commands/auth-config.js

@@ -19,34 +19,44 @@ const {
   validateEnvironment,
   checkUserLoggedIn
 } = require('../utils/auth-config-validator');
+const { getControllerUrlFromLoggedInUser } = require('../utils/controller-url');
 const logger = require('../utils/logger');
 
 /**
  * Handle set-controller command
+ * Allows setting the default controller when no credentials are stored, or when already logged in to that controller.
+ * If credentials exist for a different controller, throws with a clear message.
+ *
  * @async
  * @function handleSetController
  * @param {string} url - Controller URL to set
  * @returns {Promise<void>}
- * @throws {Error} If validation fails
+ * @throws {Error} If validation fails or credentials exist for another controller
  */
 async function handleSetController(url) {
   try {
-    // Validate URL format
     validateControllerUrl(url);
+    const normalizedUrl = url.trim().replace(/\/+$/, '');
 
-    // Check if user is logged in to that controller
-    const isLoggedIn = await checkUserLoggedIn(url);
-    if (!isLoggedIn) {
-      throw new Error(
-        `You are not logged in to controller ${url}.\n` +
-        'Please run "aifabrix login" first to authenticate with this controller.'
-      );
+    const loggedInControllerUrl = await getControllerUrlFromLoggedInUser();
+    if (!loggedInControllerUrl) {
+      // No stored credentials: allow setting controller so "aifabrix login" opens the right place
+      await setControllerUrl(url);
+      logger.log(chalk.green(`✓ Controller URL set to: ${url}`));
+      return;
     }
 
-    // Save controller URL
-    await setControllerUrl(url);
+    const normalizedLoggedIn = loggedInControllerUrl.trim().replace(/\/+$/, '');
+    if (normalizedLoggedIn === normalizedUrl) {
+      await setControllerUrl(url);
+      logger.log(chalk.green(`✓ Controller URL set to: ${url}`));
+      return;
+    }
 
-    logger.log(chalk.green(`✓ Controller URL set to: ${url}`));
+    throw new Error(
+      `You have credentials for another controller (${loggedInControllerUrl}).\n` +
+      `To use ${url} either run "aifabrix login" with that controller, or run "aifabrix logout" first to clear credentials, then set the new controller with --set-controller.`
+    );
   } catch (error) {
     logger.error(chalk.red(`✗ Failed to set controller URL: ${error.message}`));
     throw error;

package/lib/commands/repair.js

@@ -351,6 +351,7 @@ function persistChangesAndRegenerate(configPath, variables, appName, appPath, ch
 
 /**
  * Apply --auth: replace system file authentication with canonical block for the given method.
+ * Preserves existing authentication.variables (e.g. baseUrl, tokenUrl) from the current system file.
  * @param {Object} ctx - Context with systemParsed, systemKey, auth, dryRun, changes
  * @returns {boolean} True if auth was replaced
  */
@@ -362,8 +363,18 @@ function applyAuthMethod(ctx) {
       `Invalid --auth "${ctx.auth}". Allowed methods: ${ALLOWED_AUTH.join(', ')}`
     );
   }
+  const existingAuth = ctx.systemParsed.authentication || ctx.systemParsed.auth || {};
   const { buildAuthenticationFromMethod } = require('../external-system/generator');
-  ctx.systemParsed.authentication = buildAuthenticationFromMethod(ctx.systemKey, method);
+  const newAuth = buildAuthenticationFromMethod(ctx.systemKey, method);
+  const existingVars = existingAuth.variables && typeof existingAuth.variables === 'object' ? existingAuth.variables : {};
+  const mergedVariables = { ...newAuth.variables, ...existingVars };
+  ctx.systemParsed.authentication = {
+    ...newAuth,
+    variables: Object.keys(mergedVariables).length ? mergedVariables : newAuth.variables
+  };
+  if (existingAuth.displayName !== undefined) {
+    ctx.systemParsed.authentication.displayName = existingAuth.displayName;
+  }
   ctx.changes.push(`Set authentication method to ${method}`);
   return true;
 }

package/lib/commands/secrets-set.js

@@ -60,6 +60,12 @@ async function handleSecretsSet(key, value, options) {
     throw new Error('Secret key is required and must be a string');
   }
 
+  if (key.startsWith('kv://')) {
+    throw new Error(
+      'Secret key must not start with kv://. Use the key path without the prefix (e.g. my-app/clientSecret or hubspot/apiKey).'
+    );
+  }
+
   if (value === undefined || value === null || value === '') {
     throw new Error('Secret value is required');
   }

package/lib/commands/up-dataplane.js

@@ -11,6 +11,7 @@
  * @version 2.0.0
  */
 
+const readline = require('readline');
 const chalk = require('chalk');
 const pathsUtil = require('../utils/paths');
 const { loadConfigFile } = require('../utils/config-format');
@@ -18,13 +19,87 @@ const logger = require('../utils/logger');
 const config = require('../core/config');
 const { checkAuthentication } = require('../utils/app-register-auth');
 const { resolveControllerUrl } = require('../utils/controller-url');
-const { resolveEnvironment } = require('../core/config');
+const { resolveEnvironment, setControllerUrl } = require('../core/config');
 const { registerApplication } = require('../app/register');
 const { rotateSecret } = require('../app/rotate-secret');
 const { checkApplicationExists } = require('../utils/app-existence');
+const { checkHealthEndpoint } = require('../utils/health-check');
+const { validateControllerUrl } = require('../utils/auth-config-validator');
 const app = require('../app');
 const { ensureAppFromTemplate, validateEnvOutputPathFolderOrNull } = require('./up-common');
 
+const CONTROLLER_HEALTH_PATH = '/health';
+
+/**
+ * Check if controller is reachable (health endpoint).
+ * @param {string} baseUrl - Controller base URL (no trailing slash)
+ * @returns {Promise<boolean>} True if healthy
+ */
+async function isControllerHealthy(baseUrl) {
+  const healthUrl = `${baseUrl.replace(/\/+$/, '')}${CONTROLLER_HEALTH_PATH}`;
+  try {
+    return await checkHealthEndpoint(healthUrl, false);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Prompt user for controller URL when current controller is not available.
+ * @param {string} currentUrl - Current controller URL that failed health check
+ * @returns {Promise<string|null>} New URL or null if user aborted (empty input)
+ */
+function promptForControllerUrl(currentUrl) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(
+      chalk.yellow(`Controller at ${currentUrl} is not available. Enter controller URL (or press Enter to abort): `),
+      (answer) => {
+        rl.close();
+        const trimmed = (answer || '').trim();
+        resolve(trimmed === '' ? null : trimmed);
+      }
+    );
+  });
+}
+
+/**
+ * Resolve controller URL and ensure it is healthy; if not, prompt once for new URL.
+ * @returns {Promise<string>} Controller URL to use
+ * @throws {Error} If controller unavailable and user aborts or new URL still unhealthy
+ */
+async function resolveControllerUrlWithHealthCheck() {
+  let controllerUrl = await resolveControllerUrl();
+  controllerUrl = controllerUrl.replace(/\/+$/, '');
+
+  let healthy = await isControllerHealthy(controllerUrl);
+  if (healthy) {
+    return controllerUrl;
+  }
+
+  logger.log(chalk.yellow(`\nController at ${controllerUrl} is not responding (health check failed).\n`));
+  const newUrl = await promptForControllerUrl(controllerUrl);
+  if (!newUrl) {
+    throw new Error('Controller URL is required. Run "aifabrix up-dataplane" again and enter a valid controller URL, or set it with: aifabrix auth config --set-controller <url>');
+  }
+
+  try {
+    validateControllerUrl(newUrl);
+  } catch (err) {
+    throw new Error(`Invalid controller URL: ${err.message}`);
+  }
+
+  await setControllerUrl(newUrl);
+  const normalizedNew = newUrl.trim().replace(/\/+$/, '');
+  healthy = await isControllerHealthy(normalizedNew);
+  if (!healthy) {
+    throw new Error(`Controller at ${normalizedNew} is not responding. Ensure the controller is running and reachable, then run "aifabrix up-dataplane" again.`);
+  }
+
+  logger.log(chalk.green(`✓ Using controller: ${normalizedNew}`));
+  return normalizedNew;
+}
+
 /**
  * Register or rotate dataplane: if app exists in controller, rotate secret; otherwise register.
  * @async
@@ -45,6 +120,17 @@ async function registerOrRotateDataplane(options, controllerUrl, environmentKey,
   }
 }
 
+/**
+ * Deploy dataplane app (send manifest to controller).
+ * @param {Object} options - Commander options (registry, registryMode, image)
+ * @returns {Promise<void>}
+ */
+async function deployDataplaneToController(options) {
+  const imageOverride = options.image || (options.registry ? buildDataplaneImageRef(options.registry) : undefined);
+  const deployOpts = { imageOverride, image: imageOverride, registryMode: options.registryMode };
+  await app.deployApp('dataplane', deployOpts);
+}
+
 /**
  * Build full image ref from registry and dataplane config (registry/name:tag)
  * @param {string} registry - Registry URL
@@ -85,7 +171,8 @@ async function handleUpDataplane(options = {}) {
   }
   logger.log(chalk.blue('Starting up-dataplane (register/rotate, deploy, then run dataplane locally)...\n'));
 
-  const [controllerUrl, environmentKey] = await Promise.all([resolveControllerUrl(), resolveEnvironment()]);
+  const controllerUrl = await resolveControllerUrlWithHealthCheck();
+  const environmentKey = await resolveEnvironment();
   const authConfig = await checkAuthentication(controllerUrl, environmentKey, { throwOnFailure: true });
 
   const cfg = await config.getConfig();
@@ -103,10 +190,7 @@ async function handleUpDataplane(options = {}) {
 
   await registerOrRotateDataplane(options, controllerUrl, environmentKey, authConfig);
 
-  const imageOverride = options.image || (options.registry ? buildDataplaneImageRef(options.registry) : undefined);
-  const deployOpts = { imageOverride, image: imageOverride, registryMode: options.registryMode };
-
-  await app.deployApp('dataplane', deployOpts);
+  await deployDataplaneToController(options);
   logger.log('');
   await app.runApp('dataplane', { skipEnvOutputPath: true });
 

package/lib/commands/wizard-core-helpers.js

@@ -3,6 +3,7 @@
  * @author AI Fabrix Team
  * @version 2.0.0
  */
+/* eslint-disable max-lines -- 502 lines; wizard payload and helpers */
 
 const chalk = require('chalk');
 const ora = require('ora');
@@ -181,11 +182,12 @@ function buildConfigPreferences(configPrefs) {
  * @param {string} params.mode - Selected mode
  * @param {Object} params.prefs - Configuration preferences
  * @param {string} [params.credentialIdOrKey] - Credential ID or key
- * @param {string} [params.systemIdOrKey] - System ID or key
+ * @param {string} [params.systemIdOrKey] - System ID or key (application/system key, not datasource/entity key)
  * @param {string} [params.entityName] - Entity name for multi-entity OpenAPI (from discover-entities)
+ * @param {string|null} [params.systemDisplayName] - System-level display name for credential (e.g. 'Hubspot Demo')
  * @returns {Object} Configuration payload
  */
-function buildConfigPayload({ openapiSpec, detectedType, mode, prefs, credentialIdOrKey, systemIdOrKey, entityName }) {
+function buildConfigPayload({ openapiSpec, detectedType, mode, prefs, credentialIdOrKey, systemIdOrKey, entityName, systemDisplayName }) {
   const detectedTypeValue = detectedType?.recommendedType || detectedType?.apiType || detectedType?.selectedType || 'record-based';
   const payload = {
     openapiSpec,
@@ -199,6 +201,7 @@ function buildConfigPayload({ openapiSpec, detectedType, mode, prefs, credential
   if (credentialIdOrKey) payload.credentialIdOrKey = credentialIdOrKey;
   if (systemIdOrKey) payload.systemIdOrKey = systemIdOrKey;
   if (entityName) payload.entityName = entityName;
+  if (systemDisplayName) payload.systemDisplayName = systemDisplayName;
   if (prefs.debug) payload.debug = true;
   return payload;
 }

package/lib/commands/wizard-core.js

@@ -298,7 +298,8 @@ async function callGenerateApi(dataplaneUrl, authConfig, options, prefs) {
     prefs,
     credentialIdOrKey: options.credentialIdOrKey,
     systemIdOrKey: options.systemIdOrKey,
-    entityName: options.entityName
+    entityName: options.entityName,
+    systemDisplayName: options.systemDisplayName
   });
   return await generateConfig(dataplaneUrl, authConfig, configPayload);
 }

package/lib/commands/wizard-headless.js

@@ -24,6 +24,7 @@ const {
 } = require('./wizard-core');
 const { discoverEntities } = require('../api/wizard.api');
 const { validateEntityNameForOpenApi } = require('../validation/wizard-datasource-validation');
+const { humanizeAppKey } = require('../generator/wizard-prompts-secondary');
 
 /**
  * Validate entityName for headless config (throws if invalid)
@@ -80,6 +81,9 @@ async function executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig, o
 
   await validateHeadlessEntityName(source?.entityName, openapiSpec, sourceType, dataplaneUrl, authConfig);
 
+  const systemDisplayName = wizardConfig.systemDisplayName ||
+    (mode === 'create-system' ? humanizeAppKey(appName) : undefined);
+
   // Step 5: Generate Configuration
   const { systemConfig, datasourceConfigs, systemKey } = await handleConfigurationGeneration(dataplaneUrl, authConfig, {
     mode,
@@ -93,7 +97,8 @@ async function executeWizardFromConfig(wizardConfig, dataplaneUrl, authConfig, o
     datasourceKeys: source?.datasourceKeys,
     configurationValues: source?.configurationValues,
     entityName: source?.entityName,
-    appName
+    appName,
+    systemDisplayName
   });
 
   // Step 6: Validate Configuration

package/lib/commands/wizard.js

@@ -48,6 +48,7 @@ const {
   showWizardConfigSummary,
   ensureIntegrationDir
 } = require('./wizard-helpers');
+const { humanizeAppKey } = require('../generator/wizard-prompts-secondary');
 
 /**
  * Create wizard session with given mode and optional systemIdOrKey (no prompts)
@@ -150,7 +151,8 @@ async function handleInteractiveConfigGeneration(options) {
     sourceType: options.sourceType,
     platformKey: options.sourceType === 'known-platform' ? options.sourceData : undefined,
     entityName: options.entityName,
-    appName: options.appName
+    appName: options.appName,
+    systemDisplayName: options.systemDisplayName
   });
 
   return {
@@ -190,7 +192,7 @@ async function handleConfigurationReview(dataplaneUrl, authConfig, sessionId, sy
     logger.warn('Preview unavailable, showing full configuration.');
   }
 
-  const reviewResult = await promptForConfigReview({ preview, systemConfig, datasourceConfigs });
+  const reviewResult = await promptForConfigReview({ preview, systemConfig, datasourceConfigs, appKey: opts.appKey });
 
   if (reviewResult.action === 'cancel') {
     logger.log(chalk.yellow('Wizard cancelled.'));
@@ -251,7 +253,8 @@ async function doWizardSteps(appKey, dataplaneUrl, authConfig, sessionId, flowOp
     sourceData,
     entityName: entityName || undefined,
     appName: appKey,
-    debug
+    debug,
+    systemDisplayName: flowOpts.systemDisplayName
   });
   const { systemConfig, datasourceConfigs, systemKey, preferences: savedPrefs } = genResult;
   state.preferences = savedPrefs || {};
@@ -314,7 +317,7 @@ 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, debug } = flowOpts;
+  const { mode, systemIdOrKey, configPath, debug, systemDisplayName } = flowOpts;
 
   if (debug) {
     logger.log(chalk.gray(`[DEBUG] Wizard debug mode enabled for app: ${appKey}`));
@@ -329,7 +332,8 @@ async function executeWizardFlow(appKey, dataplaneUrl, authConfig, flowOpts = {}
     systemIdOrKey,
     platforms,
     configPath,
-    debug: flowOpts.debug
+    debug: flowOpts.debug,
+    systemDisplayName
   });
   if (!state) return;
 
@@ -474,12 +478,15 @@ async function handleWizardInteractive(options) {
   if (!resolved) return;
   const { appKey, configPath, dataplaneUrl, authConfig } = resolved;
   const systemIdOrKey = mode === 'add-datasource' ? resolved.systemIdOrKey : undefined;
+  const systemDisplayName = options.systemDisplayName || options.displayName ||
+    (mode === 'create-system' ? humanizeAppKey(appKey) : undefined);
   try {
     await executeWizardFlow(appKey, dataplaneUrl, authConfig, {
       mode,
       systemIdOrKey,
       configPath,
-      debug: options.debug
+      debug: options.debug,
+      systemDisplayName
     });
     logger.log(chalk.gray(`To change settings, edit integration/${appKey}/wizard.yaml and run: aifabrix wizard ${appKey}`));
   } catch (error) {

package/lib/external-system/download-helpers.js

@@ -77,13 +77,15 @@ function generateReadme(systemKey, application, dataSources) {
     };
   });
 
+  const authType = application.authentication?.type || application.authentication?.method;
   return generateExternalReadmeContent({
     appName: systemKey,
     systemKey,
     systemType: application.type,
     displayName: application.displayName,
     description: application.description,
-    datasources
+    datasources,
+    authType
   });
 }
 

package/lib/generator/external-schema-utils.js

@@ -196,13 +196,15 @@ async function writeSplitExternalSchemaFiles({ outputDir, systemKey, application
     await writeYamlFile(rbacPath, rbac, { indent: 2, lineWidth: -1 });
   }
 
+  const authType = application.authentication?.type || application.authentication?.method;
   const readmeContent = generateExternalReadmeContent({
     appName: systemKey,
     systemKey,
     systemType: application.type,
     displayName: application.displayName,
     description: application.description,
-    datasources: dataSources
+    datasources: dataSources,
+    authType
   });
   const readmePath = path.join(outputDir, 'README.md');
   await fs.promises.writeFile(readmePath, readmeContent, 'utf8');

package/lib/generator/wizard-prompts-secondary.js

@@ -107,6 +107,16 @@ async function promptForEntitySelection(entities = []) {
 /** @param {*} o - Value to stringify */
 const _s = (o) => (o === null || o === undefined || o === '' ? '—' : String(o));
 
+/**
+ * Humanize app key for display name (must stay in sync with prepareWizardContext in lib/generator/wizard.js).
+ * @param {string} appKey - Application key (e.g. hubspot-demo)
+ * @returns {string} Display name (e.g. Hubspot Demo)
+ */
+function humanizeAppKey(appKey) {
+  if (!appKey || typeof appKey !== 'string') return appKey || '';
+  return appKey.replace(/-/g, ' ').replace(/\b\w/g, l => l.toUpperCase());
+}
+
 /** @param {Object} sys - systemSummary */
 function _formatSystem(sys) {
   return [
@@ -149,8 +159,11 @@ function _formatFieldMappings(fm) {
 /**
  * Derive a preview summary from systemConfig and datasourceConfigs when the dataplane
  * preview API does not return summaries. Ensures a compact summary is always shown.
+ * When appKey is provided, system key/displayName and datasource keys are overridden
+ * to match what prepareWizardContext will write (so the preview matches saved files).
  * @param {Object} systemConfig - System configuration
  * @param {Object[]} datasourceConfigs - Array of datasource configurations
+ * @param {string} [appKey] - Optional app key; when set, overrides system key/displayName and rewrites datasource keys
  * @returns {Object} Preview object compatible with formatPreviewSummary
  */
 function _buildDatasourceSummary(ds) {
@@ -171,8 +184,9 @@ function _buildDatasourceSummary(ds) {
 }
 
 function _buildSystemSummary(sys) {
-  const baseUrl = sys.openapi?.servers?.[0]?.url ?? sys.baseUrl ?? sys.openapi?.baseUrl ?? null;
-  const authType = sys.authentication?.type ?? sys.authenticationType ?? null;
+  const baseUrl = sys.openapi?.servers?.[0]?.url ?? sys.baseUrl ?? sys.openapi?.baseUrl ??
+    sys.authentication?.variables?.baseUrl ?? null;
+  const authType = sys.authentication?.type ?? sys.authentication?.method ?? sys.authenticationType ?? null;
   const endpointCount = sys.openapi?.endpoints?.length ??
     (sys.openapi?.operations ? Object.keys(sys.openapi.operations || {}).length : null);
   return {
@@ -191,7 +205,7 @@ function _buildFieldMappingsSummary(ds0) {
   return mappedFields.length > 0 ? { mappingCount: mappedFields.length, mappedFields, unmappedFields: [] } : null;
 }
 
-function derivePreviewFromConfig(systemConfig, datasourceConfigs) {
+function derivePreviewFromConfig(systemConfig, datasourceConfigs, appKey) {
   const sys = systemConfig || {};
   const dsList = Array.isArray(datasourceConfigs) ? datasourceConfigs : (datasourceConfigs ? [datasourceConfigs] : []);
 
@@ -199,7 +213,23 @@ function derivePreviewFromConfig(systemConfig, datasourceConfigs) {
     systemSummary: _buildSystemSummary(sys),
     fieldMappingsSummary: _buildFieldMappingsSummary(dsList[0] || {})
   };
-  const datasourceSummaries = dsList.map(_buildDatasourceSummary);
+  let datasourceSummaries = dsList.map(_buildDatasourceSummary);
+
+  if (appKey && typeof appKey === 'string') {
+    result.systemSummary.key = appKey;
+    result.systemSummary.displayName = humanizeAppKey(appKey);
+    const originalSystemKey = sys.key || appKey;
+    const originalPrefix = `${originalSystemKey}-`;
+    datasourceSummaries = datasourceSummaries.map((summary, i) => {
+      const ds = dsList[i] || {};
+      const dsKey = ds.key || '';
+      const newKey = dsKey && dsKey.startsWith(originalPrefix)
+        ? `${appKey}-${dsKey.substring(originalPrefix.length)}`
+        : `${appKey}-${ds.entityType || ds.entityKey || (dsKey && dsKey.split('-').pop()) || 'default'}`;
+      return { ...summary, key: newKey };
+    });
+  }
+
   if (datasourceSummaries.length === 1) {
     result.datasourceSummary = datasourceSummaries[0];
   } else if (datasourceSummaries.length > 1) {
@@ -247,11 +277,12 @@ function formatPreviewSummary(preview) {
  * @param {Object|null} [opts.preview] - Preview data from getPreview (null = fallback to YAML)
  * @param {Object} opts.systemConfig - System configuration
  * @param {Object[]} opts.datasourceConfigs - Array of datasource configurations
+ * @param {string} [opts.appKey] - App key; when set and using fallback preview, overrides system key/displayName and datasource keys
  * @returns {Promise<Object>} Object with action ('accept'|'cancel') and optionally edited configs
  */
-async function promptForConfigReview({ preview, systemConfig, datasourceConfigs }) {
+async function promptForConfigReview({ preview, systemConfig, datasourceConfigs, appKey }) {
   const hasSummary = preview && (preview.systemSummary || preview.datasourceSummary || (preview.datasourceSummaries && preview.datasourceSummaries.length > 0));
-  const summaryToShow = hasSummary ? preview : derivePreviewFromConfig(systemConfig, datasourceConfigs);
+  const summaryToShow = hasSummary ? preview : derivePreviewFromConfig(systemConfig, datasourceConfigs, appKey);
   const canShowSummary = summaryToShow.systemSummary || summaryToShow.datasourceSummary ||
     (summaryToShow.datasourceSummaries && summaryToShow.datasourceSummaries.length > 0);
 
@@ -290,5 +321,6 @@ module.exports = {
   promptForEntitySelection,
   promptForConfigReview,
   derivePreviewFromConfig,
-  formatPreviewSummary
+  formatPreviewSummary,
+  humanizeAppKey
 };

package/lib/generator/wizard-readme.js

@@ -68,6 +68,8 @@ async function generateReadme(options) {
       };
     });
 
+    const auth = systemConfig.authentication || systemConfig.auth || {};
+    const authType = auth.type || auth.method || auth.authType;
     const readmeContent = generateExternalReadmeContent({
       appName,
       systemKey,
@@ -75,7 +77,8 @@ async function generateReadme(options) {
       displayName: systemConfig.displayName,
       description: systemConfig.description,
       fileExt: ext,
-      datasources
+      datasources,
+      authType
     });
 
     await fs.writeFile(readmePath, readmeContent, 'utf8');

package/lib/generator/wizard.js

@@ -15,7 +15,7 @@ const chalk = require('chalk');
 const logger = require('../utils/logger');
 const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { loadConfigFile, writeConfigFile } = require('../utils/config-format');
-const { systemKeyToKvPrefix } = require('../utils/credential-secrets-env');
+const { systemKeyToKvPrefix, securityKeyToVar, isValidKvPath } = require('../utils/credential-secrets-env');
 const { generateReadme } = require('./wizard-readme');
 
 /**
@@ -297,72 +297,84 @@ async function generateOrUpdateVariablesYaml(params) {
   }
 }
 
-/**
- * Adds API key authentication lines with KV_* convention
- * @param {Array<string>} lines - Lines array to append to
- * @param {string} prefix - KV prefix (e.g. HUBSPOT)
- */
-function addApiKeyAuthLines(lines, prefix) {
-  lines.push('# API Key Authentication');
-  lines.push(`KV_${prefix}_APIKEY=`);
-  lines.push('');
+/** Path-style kv value: kv://systemKey/key (camelCase key). */
+function toPathStyleKv(systemKey, key) {
+  return `kv://${systemKey}/${key}`;
 }
 
 /**
- * Adds OAuth2 authentication lines with KV_* convention
+ * Adds env.template lines from authentication.security (path-style kv:// values).
  * @param {Array<string>} lines - Lines array to append to
- * @param {Object} auth - Authentication configuration
- * @param {string} prefix - KV prefix
+ * @param {Object} security - authentication.security object
+ * @param {string} systemKey - System key for path namespace
+ * @param {string} prefix - KV prefix (e.g. HUBSPOT)
  */
-function addOAuth2AuthLines(lines, auth, prefix) {
-  lines.push('# OAuth2 Authentication');
-  lines.push(`KV_${prefix}_CLIENTID=`);
-  lines.push(`KV_${prefix}_CLIENTSECRET=`);
-  if (auth.scope) lines.push(`SCOPE=${auth.scope}`);
-  lines.push('');
+function addLinesFromSecurity(lines, security, systemKey, prefix) {
+  if (!security || typeof security !== 'object') return;
+  for (const key of Object.keys(security)) {
+    const envName = `KV_${prefix}_${securityKeyToVar(key)}`;
+    let value = security[key];
+    if (typeof value === 'string' && value.trim().startsWith('kv://') && isValidKvPath(value.trim())) {
+      value = value.trim();
+    } else {
+      value = toPathStyleKv(systemKey, key);
+    }
+    lines.push(`${envName}=${value}`);
+  }
+  if (Object.keys(security).length > 0) lines.push('');
 }
 
-/**
- * Adds bearer token authentication lines with KV_* convention
- * @param {Array<string>} lines - Lines array to append to
- * @param {string} prefix - KV prefix
- */
-function addBearerTokenAuthLines(lines, prefix) {
-  lines.push('# Bearer Token Authentication');
-  lines.push(`KV_${prefix}_BEARERTOKEN=`);
-  lines.push('');
-}
+/** Fallback security keys by auth method (camelCase) for path-style kv://. */
+const FALLBACK_SECURITY_BY_AUTH = {
+  oauth2: ['clientId', 'clientSecret'],
+  oauth: ['clientId', 'clientSecret'],
+  aad: ['clientId', 'clientSecret'],
+  apikey: ['apiKey'],
+  apiKey: ['apiKey'],
+  basic: ['username', 'password'],
+  queryParam: ['paramValue'],
+  oidc: [],
+  hmac: ['signingSecret'],
+  bearer: ['bearerToken'],
+  token: ['bearerToken'],
+  none: []
+};
 
 /**
- * Adds basic authentication lines with KV_* convention
+ * Adds auth lines by type with path-style kv:// values (fallback when security is absent).
  * @param {Array<string>} lines - Lines array to append to
+ * @param {string} authType - Authentication type
+ * @param {string} systemKey - System key
  * @param {string} prefix - KV prefix
  */
-function addBasicAuthLines(lines, prefix) {
-  lines.push('# Basic Authentication');
-  lines.push(`KV_${prefix}_USERNAME=`);
-  lines.push(`KV_${prefix}_PASSWORD=`);
+function addFallbackAuthLines(lines, authType, systemKey, prefix) {
+  const keys = FALLBACK_SECURITY_BY_AUTH[authType] || FALLBACK_SECURITY_BY_AUTH.apikey;
+  if (keys.length === 0) return;
+  const labels = { oauth2: 'OAuth2', aad: 'Azure AD', apikey: 'API Key', basic: 'Basic', queryParam: 'Query Param', hmac: 'HMAC', bearer: 'Bearer Token' };
+  const label = labels[authType] || authType;
+  lines.push(`# ${label} Authentication`);
+  for (const key of keys) {
+    lines.push(`KV_${prefix}_${securityKeyToVar(key)}=${toPathStyleKv(systemKey, key)}`);
+  }
   lines.push('');
 }
 
 /**
- * Adds authentication lines based on auth type. Uses KV_<APPKEY>_<VAR> convention.
+ * Adds authentication lines: from authentication.security when present, else by auth type with path-style kv://.
  * @param {Array<string>} lines - Lines array to append to
- * @param {Object} auth - Authentication configuration
- * @param {string} authType - Authentication type
- * @param {string} systemKey - System key (e.g. hubspot) for KV_ prefix
+ * @param {Object} auth - Authentication configuration (may have security, type/method)
+ * @param {string} authType - Normalized auth type
+ * @param {string} systemKey - System key for KV path namespace
  */
 function addAuthenticationLines(lines, auth, authType, systemKey) {
   const prefix = systemKeyToKvPrefix(systemKey);
   if (!prefix) return;
-  if (authType === 'apikey' || authType === 'apiKey') {
-    addApiKeyAuthLines(lines, prefix);
-  } else if (authType === 'oauth2' || authType === 'oauth') {
-    addOAuth2AuthLines(lines, auth || {}, prefix);
-  } else if (authType === 'bearer' || authType === 'token') {
-    addBearerTokenAuthLines(lines, prefix);
-  } else if (authType === 'basic') {
-    addBasicAuthLines(lines, prefix);
+  const security = auth?.security;
+  if (security && typeof security === 'object' && Object.keys(security).length > 0) {
+    lines.push('# Authentication (from security)');
+    addLinesFromSecurity(lines, security, systemKey, prefix);
+  } else {
+    addFallbackAuthLines(lines, authType, systemKey, prefix);
   }
 }
 
@@ -396,7 +408,7 @@ async function generateEnvTemplate(appPath, systemConfig, finalSystemKey) {
     const lines = ['# Environment variables for external system integration', '# Use KV_* for credential push (aifabrix credential push)', ''];
 
     const auth = systemConfig?.authentication || systemConfig?.auth || {};
-    const authType = auth.type || auth.authType || 'apikey';
+    const authType = (auth.type || auth.method || auth.authType || 'apikey').toLowerCase();
 
     addAuthenticationLines(lines, auth, authType, systemKey);
     addBaseUrlLines(lines, systemConfig);

package/lib/schema/wizard-config.schema.json

@@ -20,11 +20,17 @@
     },
     "systemIdOrKey": {
       "type": "string",
-      "description": "Existing system ID or key (required when mode='add-datasource')",
+      "description": "Application/system key (e.g. hubspot-demo), not a datasource or entity key. Required when mode='add-datasource'. Must be the system key from the dataplane, not an entity key (e.g. 'companies').",
       "pattern": "^[a-z0-9-]+$",
       "minLength": 1,
       "maxLength": 50
     },
+    "systemDisplayName": {
+      "type": ["string", "null"],
+      "title": "Systemdisplayname",
+      "description": "System-level display name for the credential (e.g. 'Hubspot Demo'). When the OpenAPI title is entity-specific (e.g. 'Companies'), pass the system name here so authentication.displayName is system-level.",
+      "maxLength": 200
+    },
     "source": {
       "type": "object",
       "description": "Source configuration for the wizard",

package/lib/utils/external-readme.js

@@ -91,6 +91,33 @@ function normalizeDatasources(datasources, systemKey, fileExt = '.json') {
   );
 }
 
+/**
+ * Builds secret path entries for README "Secrets" section per auth type.
+ * Path is the key for `aifabrix secret set <key> <value>` (no kv:// prefix; key format systemKey/secretKey in camelCase).
+ * @param {string} systemKey - System key
+ * @param {string} [authType] - Authentication type (oauth2, aad, apikey, basic, queryParam, hmac, bearer, token, none)
+ * @returns {Array<{path: string, description: string}>} secretPaths for template (path = key for secret set, no kv://)
+ */
+function buildSecretPaths(systemKey, authType) {
+  if (!systemKey || typeof systemKey !== 'string') return [];
+  const t = (authType && typeof authType === 'string') ? authType.toLowerCase() : 'apikey';
+  const map = {
+    oauth2: [{ path: `${systemKey}/clientId`, description: 'Client ID' }, { path: `${systemKey}/clientSecret`, description: 'Client Secret' }],
+    oauth: [{ path: `${systemKey}/clientId`, description: 'Client ID' }, { path: `${systemKey}/clientSecret`, description: 'Client Secret' }],
+    aad: [{ path: `${systemKey}/clientId`, description: 'Client ID' }, { path: `${systemKey}/clientSecret`, description: 'Client Secret' }],
+    apikey: [{ path: `${systemKey}/apiKey`, description: 'API Key' }],
+    apiKey: [{ path: `${systemKey}/apiKey`, description: 'API Key' }],
+    basic: [{ path: `${systemKey}/username`, description: 'Username' }, { path: `${systemKey}/password`, description: 'Password' }],
+    queryparam: [{ path: `${systemKey}/paramValue`, description: 'Query parameter value' }],
+    hmac: [{ path: `${systemKey}/signingSecret`, description: 'Signing secret' }],
+    bearer: [{ path: `${systemKey}/bearerToken`, description: 'Bearer token' }],
+    token: [{ path: `${systemKey}/bearerToken`, description: 'Bearer token' }],
+    oidc: [],
+    none: []
+  };
+  return map[t] || map.apikey;
+}
+
 /**
  * Builds the external system README template context
  * @function buildExternalReadmeContext
@@ -102,6 +129,8 @@ function normalizeDatasources(datasources, systemKey, fileExt = '.json') {
  * @param {string} [params.description] - Description
  * @param {Array} [params.datasources] - Datasource objects
  * @param {string} [params.fileExt] - File extension for config files (e.g. '.json', '.yaml'); default '.json'
+ * @param {string} [params.authType] - Authentication type for Secrets section (oauth2, aad, apikey, basic, etc.)
+ * @param {Object} [params.authentication] - Full authentication object (authType used if authType not set)
  * @returns {Object} Template context
  */
 function buildExternalReadmeContext(params = {}) {
@@ -112,6 +141,8 @@ function buildExternalReadmeContext(params = {}) {
   const systemType = params.systemType || 'openapi';
   const fileExt = params.fileExt !== undefined ? params.fileExt : '.json';
   const datasources = normalizeDatasources(params.datasources, systemKey, fileExt);
+  const authType = params.authType || params.authentication?.type || params.authentication?.method || params.authentication?.authType;
+  const secretPaths = buildSecretPaths(systemKey, authType);
 
   return {
     appName,
@@ -122,7 +153,8 @@ function buildExternalReadmeContext(params = {}) {
     fileExt: fileExt && fileExt.startsWith('.') ? fileExt : `.${fileExt || 'json'}`,
     datasourceCount: datasources.length,
     hasDatasources: datasources.length > 0,
-    datasources
+    datasources,
+    secretPaths
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.42.0",
+  "version": "2.42.1",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {
@@ -10,7 +10,7 @@
   "scripts": {
     "test": "node tests/scripts/test-wrapper.js",
     "test:ci": "bash tests/scripts/ci-simulate.sh",
-    "test:same-as-github": "cross-env CI=true npm run lint && cross-env CI=true node tests/scripts/test-wrapper.js",
+    "test:same-as-github": "npm run build:ci",
     "test:coverage": "cross-env RUN_COVERAGE=1 node tests/scripts/test-wrapper.js",
     "test:coverage:nyc": "nyc --reporter=text --reporter=lcov --reporter=html jest --config jest.config.coverage.js --runInBand",
     "test:watch": "jest --watch",

package/templates/external-system/README.md.hbs

@@ -46,6 +46,18 @@ Edit files in `integration/{{appName}}/`:
 - **Field mappings**: `{{systemKey}}-datasource-*-datasource{{fileExt}}` (dimensions, attributes, operations)
 - **Credential and configuration**: `env.template` (security settings and configuration variables)
 
+{{#if secretPaths}}{{#if secretPaths.length}}
+### Secrets
+
+Secrets are resolved from `.aifabrix` or key vault. Set them with:
+
+```bash
+{{#each secretPaths}}
+aifabrix secret set {{path}} <your value>   # {{description}}
+{{/each}}
+```
+{{/if}}{{/if}}
+
 ### 3. Validate Configuration
 
 ```bash
@@ -61,11 +73,12 @@ aifabrix repair {{appName}}
 ```
 
 Options:
-  --dry-run   Report changes only; do not write
-  --rbac      Ensure RBAC permissions per datasource and add default Admin/Reader roles if none exist
-  --expose    Set exposed.attributes on each datasource to all fieldMappings.attributes keys
-  --sync      Add default sync section to datasources that lack it
-  --test      Generate testPayload.payloadTemplate and testPayload.expectedResult from attributes
+  --auth <method>  Set authentication method (oauth2, aad, apikey, basic, queryParam, oidc, hmac, none); updates system file and env.template
+  --dry-run        Report changes only; do not write
+  --rbac           Ensure RBAC permissions per datasource and add default Admin/Reader roles if none exist
+  --expose         Set exposed.attributes on each datasource to all fieldMappings.attributes keys
+  --sync           Add default sync section to datasources that lack it
+  --test           Generate testPayload.payloadTemplate and testPayload.expectedResult from attributes
 
 ### 5. Upload to dataplane