@aifabrix/builder 2.39.3 → 2.40.2

package/lib/utils/secrets-utils.js

@@ -119,7 +119,7 @@ function buildHostnameToServiceMap(dockerHosts) {
 }
 
 /**
- * Resolves port for a single URL by looking up service's variables.yaml
+ * Resolves port for a single URL by looking up service's application config
  * @function resolveUrlPort
  * @param {string} protocol - URL protocol (http:// or https://)
  * @param {string} hostname - Service hostname
@@ -135,24 +135,22 @@ function resolveUrlPort(protocol, hostname, port, urlPath, hostnameToService) {
     return `${protocol}${hostname}:${port}${urlPath}`;
   }
 
-  // Try to load service's variables.yaml
-  const serviceVariablesPath = path.join(process.cwd(), 'builder', serviceName, 'variables.yaml');
-  if (!fs.existsSync(serviceVariablesPath)) {
-    // Service variables.yaml not found, keep original port
+  const { resolveApplicationConfigPath } = require('./app-config-resolver');
+  const { loadConfigFile } = require('./config-format');
+  const builderPath = path.join(process.cwd(), 'builder', serviceName);
+  let serviceVariablesPath;
+  try {
+    serviceVariablesPath = resolveApplicationConfigPath(builderPath);
+  } catch {
     return `${protocol}${hostname}:${port}${urlPath}`;
   }
 
   try {
-    const variablesContent = fs.readFileSync(serviceVariablesPath, 'utf8');
-    const variables = yaml.load(variablesContent);
-
+    const variables = loadConfigFile(serviceVariablesPath);
     const containerPort = getContainerPort(variables, port);
-
-    // Replace port in URL
     return `${protocol}${hostname}:${containerPort}${urlPath}`;
   } catch (error) {
-    // Error loading variables.yaml, keep original port
-    logger.warn(`Warning: Could not load variables.yaml for service ${serviceName}: ${error.message}`);
+    logger.warn(`Warning: Could not load application config for service ${serviceName}: ${error.message}`);
     return `${protocol}${hostname}:${port}${urlPath}`;
   }
 }

package/lib/utils/template-helpers.js

@@ -14,7 +14,7 @@ const chalk = require('chalk');
 const logger = require('./logger');
 
 /**
- * Loads template variables from template's variables.yaml file
+ * Loads template variables from template's application.yaml file
  * @async
  * @function loadTemplateVariables
  * @param {string} templateName - Template name
@@ -27,15 +27,15 @@ async function loadTemplateVariables(templateName) {
 
   const yaml = require('js-yaml');
   const templatePath = path.join(__dirname, '..', '..', 'templates', 'applications', templateName);
-  const templateVariablesPath = path.join(templatePath, 'variables.yaml');
+  const templateVariablesPath = path.join(templatePath, 'application.yaml');
 
   try {
     const templateContent = await fs.readFile(templateVariablesPath, 'utf8');
     return yaml.load(templateContent);
   } catch (error) {
-    // Template variables.yaml not found or invalid, continue without it
+    // Template application.yaml not found or invalid, continue without it
     if (error.code !== 'ENOENT') {
-      logger.warn(chalk.yellow(`⚠️  Warning: Could not load template variables.yaml: ${error.message}`));
+      logger.warn(chalk.yellow(`⚠️  Warning: Could not load template application.yaml: ${error.message}`));
     }
     return null;
   }
@@ -101,7 +101,7 @@ function updateDatabaseConfig(variables, options, appName) {
 }
 
 /**
- * Updates variables.yaml file after copying from template
+ * Updates application config file after copying from template
  * Updates app.key, displayName, and port with actual values
  * @async
  * @function updateTemplateVariables
@@ -111,21 +111,21 @@ function updateDatabaseConfig(variables, options, appName) {
  * @param {Object} config - Final configuration
  */
 async function updateTemplateVariables(appPath, appName, options, config) {
-  const variablesPath = path.join(appPath, 'variables.yaml');
+  const { resolveApplicationConfigPath } = require('./app-config-resolver');
+  const { loadConfigFile, writeConfigFile } = require('./config-format');
   try {
-    const yaml = require('js-yaml');
-    const variablesContent = await fs.readFile(variablesPath, 'utf8');
-    const variables = yaml.load(variablesContent);
+    const variablesPath = resolveApplicationConfigPath(appPath);
+    const variables = loadConfigFile(variablesPath) || {};
 
     updateAppMetadata(variables, appName);
     updatePort(variables, options, config);
     updateBuildConfig(variables);
     updateDatabaseConfig(variables, options, appName);
 
-    await fs.writeFile(variablesPath, yaml.dump(variables, { indent: 2, lineWidth: 120, noRefs: true }));
+    writeConfigFile(variablesPath, variables);
   } catch (error) {
-    if (error.code !== 'ENOENT') {
-      logger.warn(chalk.yellow(`⚠️  Warning: Could not update variables.yaml: ${error.message}`));
+    if (error.message && !error.message.includes('not found')) {
+      logger.warn(chalk.yellow(`⚠️  Warning: Could not update application config: ${error.message}`));
     }
   }
 }
@@ -197,7 +197,7 @@ function mergeAuthentication(merged, templateVariables) {
  * Merges template variables into options
  * @function mergeTemplateVariables
  * @param {Object} options - User-provided options
- * @param {Object} templateVariables - Template variables from variables.yaml
+ * @param {Object} templateVariables - Template variables from application.yaml
  * @returns {Object} Merged options object
  */
 function mergeTemplateVariables(options, templateVariables) {

package/lib/utils/token-manager.js

@@ -427,6 +427,24 @@ async function getDeviceOnlyAuth(controllerUrl) {
   throw new Error('Device token authentication required. Run "aifabrix login" to authenticate.');
 }
 
+/**
+ * Ensures auth config has a Bearer token for Dataplane pipeline endpoints.
+ * Dataplane pipeline (upload, validate, publish, test) accepts OAuth2 (Bearer) or API_KEY only;
+ * client id/secret are rejected. Call this before invoking pipeline API functions.
+ * @param {Object} authConfig - Authentication configuration (may have token, clientId, clientSecret)
+ * @throws {Error} If authConfig has only client id/secret (no token)
+ */
+function requireBearerForDataplanePipeline(authConfig) {
+  if (authConfig.token) {
+    return;
+  }
+  if (authConfig.clientId || authConfig.clientSecret) {
+    throw new Error(
+      'Dataplane pipeline endpoints require OAuth2 (Bearer token). Client id/secret are not accepted. Run "aifabrix login" to authenticate, then retry.'
+    );
+  }
+}
+
 module.exports = {
   getDeviceToken,
   getClientToken,
@@ -440,6 +458,6 @@ module.exports = {
   forceRefreshDeviceToken,
   getDeploymentAuth,
   getDeviceOnlyAuth,
-  extractClientCredentials
+  extractClientCredentials,
+  requireBearerForDataplanePipeline
 };
-

package/lib/utils/variable-transformer.js

@@ -1,7 +1,7 @@
 /**
  * Variable Transformation Utilities
  *
- * Transforms nested variables.yaml structure to flat schema format
+ * Transforms nested application config structure to flat schema format
  * Converts app.*, image.*, requires.* to schema-compatible structure
  *
  * @fileoverview Variable transformation utilities for AI Fabrix Builder
@@ -309,7 +309,7 @@ function transformOptionalFields(variables, transformed) {
 }
 
 /**
- * Transforms nested variables.yaml structure to flat schema format
+ * Transforms nested application config structure to flat schema format
  * Converts app.*, image.*, requires.* to schema-compatible structure
  * Handles both flat and nested structures
  *

package/lib/validation/validate-display.js

@@ -8,9 +8,9 @@
  * @version 2.0.0
  */
 
-const fs = require('fs');
 const chalk = require('chalk');
 const logger = require('../utils/logger');
+const { loadConfigFile } = require('../utils/config-format');
 
 /**
  * Displays application validation results
@@ -44,12 +44,11 @@ function displayApplicationValidation(application) {
  * Extracts dimensions from a datasource file
  * @function extractDimensionsFromDatasource
  * @param {string} filePath - Path to datasource file
- * @returns {Object} Dimensions info { dimensions: Object, hasDimensions: boolean }
+ * @returns {Object} Dimensions info { dimensions: Object, dimensionKeys: string[], hasDimensions: boolean }
  */
 function extractDimensionsFromDatasource(filePath) {
   try {
-    const content = fs.readFileSync(filePath, 'utf8');
-    const parsed = JSON.parse(content);
+    const parsed = loadConfigFile(filePath);
 
     // Check fieldMappings.dimensions (primary location)
     const dimensions = parsed.fieldMappings?.dimensions || {};

package/lib/validation/validate.js

@@ -10,12 +10,14 @@
  */
 
 const fs = require('fs');
-const path = require('path');
+const yaml = require('js-yaml');
 const validator = require('./validator');
 const { resolveExternalFiles } = require('../utils/schema-resolver');
 const { loadExternalSystemSchema, loadExternalDataSourceSchema, detectSchemaType } = require('../utils/schema-loader');
 const { formatValidationErrors } = require('../utils/error-formatter');
 const { detectAppType } = require('../utils/paths');
+const { logOfflinePathWhenType } = require('../utils/cli-utils');
+const { resolveApplicationConfigPath } = require('../utils/app-config-resolver');
 const { displayValidationResults } = require('./validate-display');
 const { generateControllerManifest } = require('../generator/external-controller-manifest');
 const { validateControllerManifest } = require('./external-manifest-validator');
@@ -43,8 +45,8 @@ async function validateFilePath(filePath) {
  * @param {string} appName - Application name
  * @returns {Promise<Array>} Array of validation results
  */
-async function validateExternalFilesForApp(appName) {
-  const files = await resolveExternalFiles(appName);
+async function validateExternalFilesForApp(appName, options = {}) {
+  const files = await resolveExternalFiles(appName, options);
   const validations = [];
 
   for (const file of files) {
@@ -105,21 +107,23 @@ function aggregateValidationResults(appValidation, externalValidations, rbacVali
  * @returns {Promise<Object>} Validation result
  */
 /**
- * Parses JSON file content
+ * Parses external system/datasource file content (JSON or YAML).
  * @function parseJsonFileContent
- * @param {string} filePath - File path
+ * @param {string} filePath - File path (.json, .yaml, or .yml)
  * @returns {Object} Parse result with parsed object or error
  */
 function parseJsonFileContent(filePath) {
   const content = fs.readFileSync(filePath, 'utf8');
+  const isYaml = /\.(yaml|yml)$/i.test(filePath);
   try {
-    return { parsed: JSON.parse(content), error: null };
+    const parsed = isYaml ? yaml.load(content) : JSON.parse(content);
+    return { parsed: parsed || {}, error: null };
   } catch (error) {
     return {
       parsed: null,
       error: {
         valid: false,
-        errors: [`Invalid JSON syntax: ${error.message}`],
+        errors: [isYaml ? `Invalid YAML syntax: ${error.message}` : `Invalid JSON syntax: ${error.message}`],
         warnings: []
       }
     };
@@ -206,7 +210,7 @@ async function validateExternalFile(filePath, type) {
  * @function validateAppOrFile
  * @param {string} appOrFile - Application name or file path
  * @param {Object} [options] - Validation options
- * @param {string} [options.type] - Forced application type (external)
+ *
  * @returns {Promise<Object>} Validation result with aggregated results
  * @throws {Error} If validation fails
  *
@@ -239,9 +243,9 @@ async function validateRbacForExternalSystem(isExternal, appName) {
 }
 
 /**
- * Loads and checks variables.yaml for externalIntegration
+ * Loads and checks application config for externalIntegration
  * @function loadVariablesAndCheckExternalIntegration
- * @param {string} variablesPath - Path to variables.yaml
+ * @param {string} variablesPath - Path to application config
  * @param {Object} appValidation - Application validation result
  * @returns {Object|null} Variables object or null if no externalIntegration
  */
@@ -265,7 +269,7 @@ function loadVariablesAndCheckExternalIntegration(variablesPath, appValidation)
       valid: appValidation.valid,
       application: appValidation,
       externalFiles: [],
-      warnings: [`Could not parse variables.yaml to check externalIntegration: ${error.message}`]
+      warnings: [`Could not parse application config to check externalIntegration: ${error.message}`]
     };
   }
 
@@ -287,9 +291,9 @@ function loadVariablesAndCheckExternalIntegration(variablesPath, appValidation)
  * @param {string} appName - Application name
  * @returns {Promise<Object>} Application validation result
  */
-async function validateApplicationStep(appName) {
+async function validateApplicationStep(appName, options = {}) {
   try {
-    const appValidation = await validator.validateApplication(appName);
+    const appValidation = await validator.validateApplication(appName, options);
     return {
       valid: appValidation.valid,
       errors: appValidation.errors || [],
@@ -311,9 +315,9 @@ async function validateApplicationStep(appName) {
  * @param {string} appName - Application name
  * @returns {Promise<Object>} Components validation result
  */
-async function validateComponentsStep(appName) {
+async function validateComponentsStep(appName, options = {}) {
   try {
-    const externalValidations = await validateExternalFilesForApp(appName);
+    const externalValidations = await validateExternalFilesForApp(appName, options);
     const componentErrors = [];
     const componentWarnings = [];
     const componentFiles = [];
@@ -357,9 +361,9 @@ async function validateComponentsStep(appName) {
  * @param {string} appName - Application name
  * @returns {Promise<Object>} Manifest validation result
  */
-async function validateManifestStep(appName) {
+async function validateManifestStep(appName, options = {}) {
   try {
-    const manifest = await generateControllerManifest(appName);
+    const manifest = await generateControllerManifest(appName, options);
     const manifestValidation = await validateControllerManifest(manifest);
     return {
       valid: manifestValidation.valid,
@@ -389,7 +393,7 @@ async function validateManifestStep(appName) {
  * const result = await validateExternalSystemComplete('my-hubspot');
  * // Returns: { valid: true, errors: [], warnings: [], steps: {...} }
  */
-async function validateExternalSystemComplete(appName) {
+async function validateExternalSystemComplete(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
@@ -400,11 +404,13 @@ async function validateExternalSystemComplete(appName) {
     manifest: { valid: false, errors: [], warnings: [] }
   };
 
+  const externalOptions = { ...options };
+
   // Step 1: Validate Application Config
-  steps.application = await validateApplicationStep(appName);
+  steps.application = await validateApplicationStep(appName, externalOptions);
 
   // Step 2: Validate Individual Components
-  steps.components = await validateComponentsStep(appName);
+  steps.components = await validateComponentsStep(appName, externalOptions);
 
   // If components have errors, return early (don't validate manifest)
   if (!steps.components.valid) {
@@ -417,7 +423,7 @@ async function validateExternalSystemComplete(appName) {
   }
 
   // Step 3 & 4: Generate and Validate Full Manifest (only if Step 2 passes)
-  steps.manifest = await validateManifestStep(appName);
+  steps.manifest = await validateManifestStep(appName, externalOptions);
 
   // Aggregate Results
   const allErrors = [...steps.application.errors, ...steps.components.errors, ...steps.manifest.errors];
@@ -442,23 +448,23 @@ async function validateAppOrFile(appOrFile, options = {}) {
   }
 
   const appName = appOrFile;
-  const { appPath, isExternal } = await detectAppType(appName, options);
+  const { appPath, isExternal } = await detectAppType(appName);
+  logOfflinePathWhenType(appPath);
 
-  // For external systems with --type external flag, use new unified validation
-  if (isExternal && options.type === 'external') {
-    return await validateExternalSystemComplete(appName);
+  if (isExternal) {
+    return await validateExternalSystemComplete(appName, options);
   }
 
-  const appValidation = await validator.validateApplication(appName);
+  const appValidation = await validator.validateApplication(appName, options);
   const rbacValidation = await validateRbacForExternalSystem(isExternal, appName);
 
-  const variablesPath = path.join(appPath, 'variables.yaml');
+  const variablesPath = resolveApplicationConfigPath(appPath);
   const earlyReturn = loadVariablesAndCheckExternalIntegration(variablesPath, appValidation);
   if (earlyReturn) {
     return earlyReturn;
   }
 
-  const externalValidations = await validateExternalFilesForApp(appName);
+  const externalValidations = await validateExternalFilesForApp(appName, options);
   return aggregateValidationResults(appValidation, externalValidations, rbacValidation);
 }
 

package/lib/validation/validator.js

@@ -2,7 +2,7 @@
  * AI Fabrix Builder Schema Validation
  *
  * This module provides schema validation with developer-friendly error messages.
- * Validates variables.yaml, rbac.yaml, and env.template files.
+ * Validates application.yaml, rbac.yaml, and env.template files.
  *
  * @fileoverview Schema validation with friendly error messages for AI Fabrix Builder
  * @author AI Fabrix Team
@@ -19,10 +19,11 @@ const externalDataSourceSchema = require('../schema/external-datasource.schema.j
 const { transformVariablesForValidation } = require('../utils/variable-transformer');
 const { checkEnvironment } = require('../utils/environment-checker');
 const { formatValidationErrors } = require('../utils/error-formatter');
-const { detectAppType } = require('../utils/paths');
+const { detectAppType, resolveApplicationConfigPath } = require('../utils/paths');
+const { loadConfigFile } = require('../utils/config-format');
 
 /**
- * Validates variables.yaml file against application schema
+ * Validates application config file against application schema
  * Provides detailed error messages for configuration issues
  *
  * @async
@@ -36,27 +37,17 @@ const { detectAppType } = require('../utils/paths');
  * // Returns: { valid: true, errors: [], warnings: [] }
  */
 /**
- * Loads and parses variables.yaml
+ * Loads and parses application config (application.yaml or application.json) via resolver + converter.
  * @async
  * @function loadVariablesYaml
  * @param {string} appName - Application name
  * @returns {Promise<Object>} Variables object
  * @throws {Error} If file not found or invalid
  */
-async function loadVariablesYaml(appName) {
-  const { appPath } = await detectAppType(appName);
-  const variablesPath = path.join(appPath, 'variables.yaml');
-
-  if (!fs.existsSync(variablesPath)) {
-    throw new Error(`variables.yaml not found: ${variablesPath}`);
-  }
-
-  const content = fs.readFileSync(variablesPath, 'utf8');
-  try {
-    return yaml.load(content);
-  } catch (error) {
-    throw new Error(`Invalid YAML syntax in variables.yaml: ${error.message}`);
-  }
+async function loadVariablesYaml(appName, options = {}) {
+  const { appPath } = await detectAppType(appName, options);
+  const configPath = resolveApplicationConfigPath(appPath);
+  return loadConfigFile(configPath);
 }
 
 /**
@@ -119,12 +110,12 @@ function validateFrontDoorRouting(variables, errors) {
   }
 }
 
-async function validateVariables(appName) {
+async function validateVariables(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
 
-  const variables = await loadVariablesYaml(appName);
+  const variables = await loadVariablesYaml(appName, options);
   const transformed = transformVariablesForValidation(variables, appName);
   const validate = setupAjvValidator();
   const valid = validate(transformed);
@@ -203,16 +194,18 @@ function validatePermissions(permissions) {
   return errors;
 }
 
-async function validateRbac(appName) {
+async function validateRbac(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
 
   // Support both builder/ and integration/ directories using detectAppType
-  const { appPath } = await detectAppType(appName);
-  const rbacPath = path.join(appPath, 'rbac.yaml');
+  const { appPath } = await detectAppType(appName, options);
+  const rbacYaml = path.join(appPath, 'rbac.yaml');
+  const rbacYml = path.join(appPath, 'rbac.yml');
+  const rbacPath = fs.existsSync(rbacYaml) ? rbacYaml : (fs.existsSync(rbacYml) ? rbacYml : null);
 
-  if (!fs.existsSync(rbacPath)) {
+  if (!rbacPath) {
     return { valid: true, errors: [], warnings: ['rbac.yaml not found - authentication disabled'] };
   }
 
@@ -251,13 +244,13 @@ async function validateRbac(appName) {
  * const result = await validateEnvTemplate('myapp');
  * // Returns: { valid: true, errors: [], warnings: [] }
  */
-async function validateEnvTemplate(appName) {
+async function validateEnvTemplate(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
 
   // Support both builder/ and integration/ directories using detectAppType
-  const { appPath } = await detectAppType(appName);
+  const { appPath } = await detectAppType(appName, options);
   const templatePath = path.join(appPath, 'env.template');
 
   if (!fs.existsSync(templatePath)) {
@@ -305,6 +298,32 @@ async function validateEnvTemplate(appName) {
   };
 }
 
+/**
+ * Validates a single object against the application schema (no app-name resolution).
+ * Supports both flat root (key, displayName, ...) and nested shape (app: {...}).
+ * Used by diff and other callers that have already parsed the config.
+ *
+ * @function validateObjectAgainstApplicationSchema
+ * @param {Object} obj - Parsed config object (root or { app, deployment })
+ * @returns {{ valid: boolean, errors: string[] }} Validation result
+ *
+ * @example
+ * const result = validateObjectAgainstApplicationSchema(parsed);
+ * if (!result.valid) throw new Error(result.errors.join('; '));
+ */
+function validateObjectAgainstApplicationSchema(obj) {
+  if (!obj || typeof obj !== 'object') {
+    return { valid: false, errors: ['Config must be an object'] };
+  }
+  const toValidate = obj.app && typeof obj.app === 'object' && !obj.key ? obj.app : obj;
+  const validate = setupAjvValidator();
+  const valid = validate(toValidate);
+  return {
+    valid: !!valid,
+    errors: valid ? [] : formatValidationErrors(validate.errors)
+  };
+}
+
 /**
  * Validates deployment JSON against application schema
  * Ensures generated <app-name>-deploy.json matches the schema structure
@@ -360,14 +379,14 @@ function validateDeploymentJson(deployment) {
  * const result = await validateApplication('myapp');
  * // Returns: { valid: true, variables: {...}, rbac: {...}, env: {...} }
  */
-async function validateApplication(appName) {
+async function validateApplication(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
 
-  const variables = await validateVariables(appName);
-  const rbac = await validateRbac(appName);
-  const env = await validateEnvTemplate(appName);
+  const variables = await validateVariables(appName, options);
+  const rbac = await validateRbac(appName, options);
+  const env = await validateEnvTemplate(appName, options);
 
   const valid = variables.valid && rbac.valid && env.valid;
   const errors = [...(variables.errors || []), ...(rbac.errors || []), ...(env.errors || [])];
@@ -392,6 +411,7 @@ module.exports = {
   validateRbac,
   validateEnvTemplate,
   validateDeploymentJson,
+  validateObjectAgainstApplicationSchema,
   checkEnvironment,
   formatValidationErrors,
   validateApplication

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.39.3",
+  "version": "2.40.2",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {
@@ -16,11 +16,13 @@
     "test:integration": "jest --config jest.config.integration.js --runInBand",
     "test:integration:python": "cross-env TEST_LANGUAGE=python jest --config jest.config.integration.js --runInBand",
     "test:integration:typescript": "cross-env TEST_LANGUAGE=typescript jest --config jest.config.integration.js --runInBand",
+    "test:manual": "jest --config jest.config.manual.js --runInBand",
     "lint": "eslint . --ext .js",
     "lint:fix": "eslint . --ext .js --fix",
     "lint:ci": "eslint . --ext .js --format json --output-file eslint-report.json",
     "dev": "node bin/aifabrix.js",
     "build": "npm run lint && npm run test",
+    "build:ci": "npm run lint && npm run test:ci",
     "pack": "npm run build && npm pack",
     "validate": "npm run build",
     "prepublishOnly": "npm run validate",
@@ -78,6 +80,7 @@
     "ora": "^5.4.1"
   },
   "devDependencies": {
+    "@babel/preset-env": "^7.29.0",
     "@bcoe/v8-coverage": "^1.0.2",
     "@types/node": "^20.10.0",
     "cross-env": "^10.1.0",

package/templates/README.md

@@ -106,7 +106,7 @@ Create your own step templates in `templates/github/steps/{your-step}.hbs` and r
 
 ### Language and Infrastructure Templates
 
-These templates are processed automatically by the AI Fabrix Builder SDK based on the application schema defined in `variables.yaml`. The generated files will be valid Docker files after template processing.
+These templates are processed automatically by the AI Fabrix Builder SDK based on the application schema defined in `application.yaml`. The generated files will be valid Docker files after template processing.
 
 ## VS Code Configuration
 

package/templates/applications/README.md.hbs

@@ -61,7 +61,7 @@ aifabrix build {{appName}} --tag v1.0.0
 aifabrix push {{appName}} --registry {{registry}} --tag "v1.0.0,latest"
 
 # Deploy (controller and environment from config; set via aifabrix login or aifabrix auth config)
-aifabrix deploy {{appName}} --deployment local
+aifabrix deploy {{appName}} --local
 ```
 
 ---
@@ -132,7 +132,7 @@ aifabrix push {{appName}} --registry {{registry}} --tag "v1.0.0,latest,stable"
 ### Deploy Options
 
 ```bash
-aifabrix deploy {{appName}} --deployment local    # Uses controller and environment from config
+aifabrix deploy {{appName}} --local    # Uses controller and environment from config
 aifabrix deploy {{appName}} --no-poll             # Deploy without polling for status
 ```
 
@@ -166,7 +166,7 @@ Controller URL and environment (for `deploy`, `app register`, etc.) are set via
 
 - **"Docker not running"** → Start Docker Desktop
 - **"Not logged in"** → Run `aifabrix login` first
-- **"Port already in use"** → Use `aifabrix run {{appName}} --port <port>` or set `build.localPort` in `variables.yaml` (default: {{localPort}})
+- **"Port already in use"** → Use `aifabrix run {{appName}} --port <port>` or set `build.localPort` in `application.yaml` (default: {{localPort}})
 - **"Authentication failed"** → Run `aifabrix login` again
 - **"Build fails"** → Check Docker is running and `aifabrix-secrets` in `config.yaml` is configured correctly
 - **"Can't connect"** → Verify infrastructure is running{{#if hasDatabase}} and PostgreSQL is accessible{{/if}}

package/templates/applications/miso-controller/env.template

@@ -105,7 +105,9 @@ REDIS_PERMISSIONS_TTL=900
 # (KeycloakConfiguration + Application url/internalUrl). Sync env->DB at startup via
 # sync-application-urls-from-env.service.
 #
-# NOTE: Do NOT onboard Azure Entra SSO in Keycloak during onboarding (skipAzureEntraSso=true).
+# Azure Entra SSO during onboarding: true = skip (default), false = onboard Azure Entra SSO client in Keycloak
+# (onboarding Azure SSO requires Entra admin consent and Azure app credentials).
+KEYCLOAK_SKIP_AZURE_ENTRA_SSO=false
 
 KEYCLOAK_REALM=aifabrix
 KEYCLOAK_SERVER_URL=kv://keycloak-server-urlKeyVault

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

@@ -10,8 +10,8 @@
 
 ## Files
 
-- `variables.yaml` – Application configuration with `app` and `externalIntegration` blocks
-- `{{systemKey}}-system.json` – External system definition (authentication, OpenAPI/MCP, RBAC)
+- `application.yaml` – Application configuration with `app` and `externalIntegration` blocks
+- `{{systemKey}}-system.yaml` – External system definition (authentication, OpenAPI/MCP, RBAC)
 {{#each datasources}}
 - `{{fileName}}` – Datasource: {{displayName}}
 {{/each}}
@@ -38,8 +38,8 @@ aifabrix wizard --app {{appName}}
 
 Edit files in `integration/{{appName}}/`:
 
-- **Authentication**: `{{systemKey}}-system.json` (auth type, credentials placeholders)
-- **Field mappings**: `{{systemKey}}-datasource-*.json` (dimensions, attributes, operations)
+- **Authentication**: `{{systemKey}}-system.yaml` (auth type, credentials placeholders)
+- **Field mappings**: `{{systemKey}}-datasource-*.yaml` (dimensions, attributes, operations)
 
 ### 3. Validate Configuration