@aifabrix/builder 2.38.0 → 2.39.0

package/lib/commands/up-miso.js

@@ -1,7 +1,7 @@
 /**
  * AI Fabrix Builder - Up Miso Command
  *
- * Installs keycloak, miso-controller, and dataplane from images (no build).
+ * Installs keycloak and miso-controller from images (no build). For dataplane, use up-dataplane.
  * Assumes infra is up; sets dev secrets and resolves (no force; existing .env values preserved).
  *
  * @fileoverview up-miso command implementation
@@ -19,19 +19,16 @@ const secrets = require('../core/secrets');
 const infra = require('../infrastructure');
 const app = require('../app');
 const { saveLocalSecret } = require('../utils/local-secrets');
-const { ensureAppFromTemplate, patchEnvOutputPathForDeployOnly } = require('./up-common');
+const { ensureAppFromTemplate, patchEnvOutputPathForDeployOnly, validateEnvOutputPathFolderOrNull } = require('./up-common');
 
 /** Keycloak base port (from templates/applications/keycloak/variables.yaml) */
 const KEYCLOAK_BASE_PORT = 8082;
 /** Miso controller base port (dev-config app base) */
 const MISO_BASE_PORT = 3000;
-/** Dataplane base port (from templates/applications/dataplane/variables.yaml) */
-const _DATAPLANE_BASE_PORT = 3001;
-
 /**
- * Parse --image options array into map { keycloak?: string, 'miso-controller'?: string, dataplane?: string }
- * @param {string[]|string} imageOpts - Option value(s) e.g. ['keycloak=reg/k:v1', 'miso-controller=reg/m:v1', 'dataplane=reg/d:v1']
- * @returns {{ keycloak?: string, 'miso-controller'?: string, dataplane?: string }}
+ * Parse --image options array into map { keycloak?: string, 'miso-controller'?: string }
+ * @param {string[]|string} imageOpts - Option value(s) e.g. ['keycloak=reg/k:v1', 'miso-controller=reg/m:v1']
+ * @returns {{ keycloak?: string, 'miso-controller'?: string }}
  */
 function parseImageOptions(imageOpts) {
   const map = {};
@@ -50,7 +47,7 @@ function parseImageOptions(imageOpts) {
 
 /**
  * Build full image ref from registry and app variables (registry/name:tag)
- * @param {string} appName - keycloak, miso-controller, or dataplane
+ * @param {string} appName - keycloak or miso-controller
  * @param {string} registry - Registry URL
  * @returns {string} Full image reference
  */
@@ -67,7 +64,7 @@ function buildImageRefFromRegistry(appName, registry) {
 }
 
 /**
- * Set URL secrets and resolve keycloak + miso-controller + dataplane (no force; existing .env preserved)
+ * Set URL secrets and resolve keycloak + miso-controller (no force; existing .env preserved)
  * @async
  * @param {number} devIdNum - Developer ID number
  */
@@ -79,12 +76,11 @@ async function setMisoSecretsAndResolve(devIdNum) {
   logger.log(chalk.green('✓ Set keycloak and miso-controller URL secrets'));
   await secrets.generateEnvFile('keycloak', undefined, 'docker', false, true);
   await secrets.generateEnvFile('miso-controller', undefined, 'docker', false, true);
-  await secrets.generateEnvFile('dataplane', undefined, 'docker', false, true);
-  logger.log(chalk.green('✓ Resolved keycloak, miso-controller, and dataplane'));
+  logger.log(chalk.green('✓ Resolved keycloak and miso-controller'));
 }
 
 /**
- * Build run options and run keycloak, miso-controller, then dataplane
+ * Build run options and run keycloak, then miso-controller
  * @async
  * @param {Object} options - Commander options (image, registry, registryMode)
  */
@@ -92,27 +88,23 @@ async function runMisoApps(options) {
   const imageMap = parseImageOptions(options.image);
   const keycloakImage = imageMap.keycloak || (options.registry ? buildImageRefFromRegistry('keycloak', options.registry) : undefined);
   const misoImage = imageMap['miso-controller'] || (options.registry ? buildImageRefFromRegistry('miso-controller', options.registry) : undefined);
-  const dataplaneImage = imageMap.dataplane || (options.registry ? buildImageRefFromRegistry('dataplane', options.registry) : undefined);
   const keycloakRunOpts = { image: keycloakImage, registry: options.registry, registryMode: options.registryMode, skipEnvOutputPath: true, skipInfraCheck: true };
   const misoRunOpts = { image: misoImage, registry: options.registry, registryMode: options.registryMode, skipEnvOutputPath: true, skipInfraCheck: true };
-  const dataplaneRunOpts = { image: dataplaneImage, registry: options.registry, registryMode: options.registryMode, skipEnvOutputPath: true, skipInfraCheck: true };
   logger.log(chalk.blue('Starting keycloak...'));
   await app.runApp('keycloak', keycloakRunOpts);
   logger.log(chalk.blue('Starting miso-controller...'));
   await app.runApp('miso-controller', misoRunOpts);
-  logger.log(chalk.blue('Starting dataplane...'));
-  await app.runApp('dataplane', dataplaneRunOpts);
 }
 
 /**
- * Handle up-miso command: ensure infra, ensure app dirs, set secrets, resolve (preserve existing .env), run keycloak, miso-controller, then dataplane.
+ * Handle up-miso command: ensure infra, ensure app dirs, set secrets, resolve (preserve existing .env), run keycloak and miso-controller.
  *
  * @async
  * @function handleUpMiso
  * @param {Object} options - Commander options
  * @param {string} [options.registry] - Override registry for all apps
  * @param {string} [options.registryMode] - Override registry mode (acr|external)
- * @param {string[]|string} [options.image] - Override images e.g. keycloak=reg/k:v1, miso-controller=reg/m:v1, dataplane=reg/d:v1
+ * @param {string[]|string} [options.image] - Override images e.g. keycloak=reg/k:v1, miso-controller=reg/m:v1
  * @returns {Promise<void>}
  * @throws {Error} If infra not up or any step fails
  */
@@ -121,7 +113,7 @@ async function handleUpMiso(options = {}) {
   if (builderDir) {
     process.env.AIFABRIX_BUILDER_DIR = builderDir;
   }
-  logger.log(chalk.blue('Starting up-miso (keycloak + miso-controller + dataplane from images)...\n'));
+  logger.log(chalk.blue('Starting up-miso (keycloak + miso-controller from images)...\n'));
   // Strict: only this developer's infra (same as status), so up-miso and status agree
   const health = await infra.checkInfraHealth(undefined, { strict: true });
   const allHealthy = Object.values(health).every(status => status === 'healthy');
@@ -131,17 +123,18 @@ async function handleUpMiso(options = {}) {
   logger.log(chalk.green('✓ Infrastructure is up'));
   await ensureAppFromTemplate('keycloak');
   await ensureAppFromTemplate('miso-controller');
-  await ensureAppFromTemplate('dataplane');
+  // If envOutputPath target folder does not exist, set envOutputPath to null
+  validateEnvOutputPathFolderOrNull('keycloak');
+  validateEnvOutputPathFolderOrNull('miso-controller');
   // Deploy-only: do not copy .env to repo paths; patch variables so envOutputPath is null
   patchEnvOutputPathForDeployOnly('keycloak');
   patchEnvOutputPathForDeployOnly('miso-controller');
-  patchEnvOutputPathForDeployOnly('dataplane');
   const developerId = await config.getDeveloperId();
   const devIdNum = typeof developerId === 'string' ? parseInt(developerId, 10) : developerId;
   await setMisoSecretsAndResolve(devIdNum);
   await runMisoApps(options);
-  logger.log(chalk.green('\n✓ up-miso complete. Keycloak, miso-controller, and dataplane are running.') +
-    chalk.gray('\n  Run onboarding and register Keycloak from the miso-controller repo if needed.'));
+  logger.log(chalk.green('\n✓ up-miso complete. Keycloak and miso-controller are running.') +
+    chalk.gray('\n  Run onboarding and register Keycloak from the miso-controller repo if needed. Use \'aifabrix up-dataplane\' for dataplane.'));
 }
 
 module.exports = { handleUpMiso, parseImageOptions };

package/lib/core/templates.js

@@ -35,7 +35,6 @@ function generateExternalSystemVariables(appName, displayName, config) {
       type: 'external'
     },
     deployment: {
-      controllerUrl: '',
       environment: 'dev'
     },
     externalIntegration: {

package/lib/external-system/deploy.js

@@ -13,10 +13,87 @@ const chalk = require('chalk');
 const { getDeploymentAuth } = require('../utils/token-manager');
 const logger = require('../utils/logger');
 const { resolveControllerUrl } = require('../utils/controller-url');
+const { resolveDataplaneUrl } = require('../utils/dataplane-resolver');
+const { getExternalSystem } = require('../api/external-systems.api');
 const { generateControllerManifest } = require('../generator/external-controller-manifest');
 const { validateExternalSystemComplete } = require('../validation/validate');
 const { displayValidationResults } = require('../validation/validate-display');
 
+/**
+ * Displays API and MCP documentation URLs from dataplane when available
+ * @async
+ * @function displayDeploymentDocs
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} environment - Environment key
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} systemKey - External system key
+ */
+async function displayDeploymentDocs(controllerUrl, environment, authConfig, systemKey) {
+  try {
+    const dataplaneUrl = await resolveDataplaneUrl(controllerUrl, environment, authConfig);
+    const res = await getExternalSystem(dataplaneUrl, systemKey, authConfig);
+    const sys = res?.data || res;
+    if (!sys) return;
+
+    const apiDocumentUrl = sys.apiDocumentUrl;
+    const mcpServerUrl = sys.mcpServerUrl;
+    const openApiDocsPageUrl = sys.openApiDocsPageUrl;
+
+    const urls = [];
+    if (apiDocumentUrl && typeof apiDocumentUrl === 'string') {
+      urls.push({ label: 'API Docs', url: apiDocumentUrl });
+    }
+    if (mcpServerUrl && typeof mcpServerUrl === 'string') {
+      urls.push({ label: 'MCP Server', url: mcpServerUrl });
+    }
+    if (openApiDocsPageUrl && typeof openApiDocsPageUrl === 'string') {
+      urls.push({ label: 'OpenAPI Docs Page', url: openApiDocsPageUrl });
+    }
+
+    if (urls.length > 0) {
+      logger.log(chalk.blue('\nDocumentation:'));
+      urls.forEach(({ label, url }) => {
+        logger.log(chalk.blue(`   ${label}: ${url}`));
+      });
+    }
+  } catch (_err) {
+    // Silently ignore: dataplane may be unreachable or docs not configured
+  }
+}
+
+/**
+ * Deploys via controller and displays success summary with docs
+ * @async
+ * @function executeDeployAndDisplay
+ * @param {Object} manifest - Controller manifest
+ * @param {string} controllerUrl - Controller base URL
+ * @param {string} environment - Environment key
+ * @param {Object} authConfig - Authentication configuration
+ * @param {Object} options - Deployment options
+ * @returns {Promise<Object>} Deployment result
+ */
+async function executeDeployAndDisplay(manifest, controllerUrl, environment, authConfig, options) {
+  const deployer = require('../deployment/deployer');
+  const pollOpts = {
+    poll: options.poll,
+    pollInterval: options.pollInterval !== undefined ? options.pollInterval : 500,
+    pollMaxAttempts: options.pollMaxAttempts,
+    ...options
+  };
+  const result = await deployer.deployToController(
+    manifest,
+    controllerUrl,
+    environment,
+    authConfig,
+    pollOpts
+  );
+  logger.log(chalk.green('\n✅ External system deployed successfully!'));
+  logger.log(chalk.blue(`System: ${manifest.key}`));
+  logger.log(chalk.blue(`Datasources: ${manifest.dataSources.length}`));
+  await displayDeploymentDocs(controllerUrl, environment, authConfig, manifest.key);
+  return result;
+}
+
 /**
  * Prepares deployment configuration (auth, controller URL, environment)
  * @async
@@ -75,26 +152,13 @@ async function deployExternalSystem(appName, options = {}) {
     const { environment, controllerUrl, authConfig } = await prepareDeploymentConfig(appName, options);
 
     // Step 3: Deploy via controller pipeline (same as regular apps)
-    // Use 500ms polling for external systems (faster than web apps which use 5000ms)
-    const deployer = require('../deployment/deployer');
-    const result = await deployer.deployToController(
+    const result = await executeDeployAndDisplay(
       manifest,
       controllerUrl,
       environment,
       authConfig,
-      {
-        poll: options.poll,
-        pollInterval: options.pollInterval !== undefined ? options.pollInterval : 500,
-        pollMaxAttempts: options.pollMaxAttempts,
-        ...options
-      }
+      options
     );
-
-    // Display success summary
-    logger.log(chalk.green('\n✅ External system deployed successfully!'));
-    logger.log(chalk.blue(`System: ${manifest.key}`));
-    logger.log(chalk.blue(`Datasources: ${manifest.dataSources.length}`));
-
     return result;
   } catch (error) {
     let message = `Failed to deploy external system: ${error.message}`;

package/lib/generator/builders.js

@@ -262,25 +262,6 @@ function validateBuildFields(build) {
   return Object.keys(buildConfig).length > 0 ? buildConfig : null;
 }
 
-/**
- * Validates and transforms deployment fields
- * @function validateDeploymentFields
- * @param {Object} deployment - Deployment configuration
- * @returns {Object|null} Validated deployment config or null
- */
-function validateDeploymentFields(deployment) {
-  if (!deployment) {
-    return null;
-  }
-
-  const deploymentConfig = {};
-  if (deployment.controllerUrl && deployment.controllerUrl.trim() && deployment.controllerUrl.startsWith('https://')) {
-    deploymentConfig.controllerUrl = deployment.controllerUrl;
-  }
-
-  return Object.keys(deploymentConfig).length > 0 ? deploymentConfig : null;
-}
-
 /**
  * Adds optional fields to deployment manifest
  * @function buildOptionalFields
@@ -339,11 +320,6 @@ function addValidatedConfigSections(deployment, variables) {
   if (build) {
     deployment.build = build;
   }
-
-  const deploymentConfig = validateDeploymentFields(variables.deployment);
-  if (deploymentConfig) {
-    deployment.deployment = deploymentConfig;
-  }
 }
 
 /**

package/lib/schema/application-schema.json

@@ -772,18 +772,6 @@
       },
       "additionalProperties": false
     },
-    "deployment": {
-      "type": "object",
-      "description": "Deployment configuration for pipeline API",
-      "properties": {
-        "controllerUrl": {
-          "type": "string",
-          "description": "Controller API URL for deployment",
-          "pattern": "^https://.*$"
-        }
-      },
-      "additionalProperties": false
-    },
     "system": {
       "type": "object",
       "description": "Optional: Inline external system configuration for atomic deployment. Uses external-system.schema.json structure via $ref. Alternative to externalIntegration.systems file-based approach.",

package/lib/schema/external-system.schema.json

@@ -102,22 +102,6 @@
       "type": "boolean",
       "default": true
     },
-    "environment": {
-      "type": "object",
-      "description": "Environment-level configuration values used by dataplane and external data sources.",
-      "properties": {
-        "baseUrl": {
-          "type": "string",
-          "description": "Base API URL or MCP server URL",
-          "pattern": "^(http|https)://.*$"
-        },
-        "region": {
-          "type": "string",
-          "description": "Optional region setting for API routing"
-        }
-      },
-      "additionalProperties": true
-    },
     "authentication": {
       "type": "object",
       "description": "Authentication configuration for external system",

package/lib/utils/app-register-config.js

@@ -112,19 +112,14 @@ function resolveSystemFilePath(appPath, schemaBasePath, systemFileName) {
 }
 
 /**
- * Extracts URL from system JSON
+ * Base URL is no longer read from manifest; Controller resolves from configuration at deploy time.
  * @function extractUrlFromSystemJson
- * @param {Object} systemJson - System JSON object
- * @param {string} systemFileName - System file name
- * @returns {string} Base URL
- * @throws {Error} If URL is missing
+ * @param {Object} _systemJson - System JSON object (unused; kept for call-site compatibility)
+ * @param {string} _systemFileName - System file name (unused)
+ * @returns {undefined} URL is not supplied from manifest
  */
-function extractUrlFromSystemJson(systemJson, systemFileName) {
-  const url = systemJson.environment?.baseUrl;
-  if (!url) {
-    throw new Error(`Missing environment.baseUrl in ${systemFileName}`);
-  }
-  return url;
+function extractUrlFromSystemJson(_systemJson, _systemFileName) {
+  return undefined;
 }
 
 /**
@@ -209,7 +204,10 @@ async function extractExternalIntegrationUrl(appKey, externalIntegration) {
  */
 async function extractExternalAppConfiguration(appKey, variables, appKeyFromFile, displayName, description) {
   const { url, apiKey } = await extractExternalIntegrationUrl(appKey, variables.externalIntegration);
-  const externalIntegration = { url };
+  const externalIntegration = {};
+  if (url !== undefined && url !== null) {
+    externalIntegration.url = url;
+  }
   if (apiKey) {
     externalIntegration.apiKey = apiKey;
   }

package/lib/utils/deployment-errors.js

@@ -206,6 +206,16 @@ async function handleDeploymentErrors(error, appName, url, alreadyLogged = false
   // Extract error message
   const errorMessage = extractErrorMessage(error);
 
+  // Deployment failed/cancelled (from deploy.js): show message as-is, do not treat as HTTP error
+  if (errorMessage.startsWith('Deployment failed:') || errorMessage.startsWith('Deployment cancelled:')) {
+    if (!alreadyLogged) {
+      await logDeploymentFailure(appName, url, error);
+    }
+    const err = new Error(errorMessage);
+    err.formatted = (error.formatted || errorMessage).trim();
+    throw err;
+  }
+
   // For validation errors (like URL validation), just re-throw them directly
   if (isValidationError(errorMessage)) {
     throwValidationError(error, errorMessage);

package/lib/utils/environment-checker.js

@@ -13,6 +13,8 @@ const fs = require('fs');
 const path = require('path');
 const dockerUtils = require('./docker');
 const { getActualSecretsPath } = require('./secrets-path');
+const config = require('../core/config');
+const devConfig = require('./dev-config');
 
 /**
  * Checks if Docker is installed and available
@@ -33,17 +35,28 @@ async function checkDocker() {
 
 /**
  * Checks if required ports are available
+ * Uses developer-specific ports when developer-id greater than 0 (basePort + developerId * 100)
  *
  * @async
  * @function checkPorts
+ * @param {number[]} [requiredPorts] - Ports to check. If omitted, uses ports from config developer-id
  * @returns {Promise<string>} 'ok' if all ports are available, 'warning' otherwise
  */
-async function checkPorts() {
-  const requiredPorts = [5432, 6379, 5050, 8081];
+async function checkPorts(requiredPorts) {
   const netstat = require('net');
+  let portsToCheck = requiredPorts;
+
+  if (!portsToCheck || portsToCheck.length === 0) {
+    const devId = await config.getDeveloperId();
+    const idNum = typeof devId === 'string' ? parseInt(devId, 10) : devId;
+    const id = Number.isNaN(idNum) || idNum < 0 ? 0 : idNum;
+    const ports = devConfig.getDevPorts(id);
+    portsToCheck = [ports.postgres, ports.redis, ports.pgadmin, ports.redisCommander];
+  }
+
   let portIssues = 0;
 
-  for (const port of requiredPorts) {
+  for (const port of portsToCheck) {
     try {
       await new Promise((resolve, reject) => {
         const server = netstat.createServer();
@@ -128,10 +141,16 @@ async function checkEnvironment() {
     result.recommendations.push('Install Docker and Docker Compose');
   }
 
-  // Check ports
-  result.ports = await checkPorts();
+  // Check ports (developer-specific: dev 0 = base ports, dev N = base + N*100)
+  const devId = await config.getDeveloperId();
+  const idNum = typeof devId === 'string' ? parseInt(devId, 10) : devId;
+  const id = Number.isNaN(idNum) || idNum < 0 ? 0 : idNum;
+  const ports = devConfig.getDevPorts(id);
+  const requiredPorts = [ports.postgres, ports.redis, ports.pgadmin, ports.redisCommander];
+
+  result.ports = await checkPorts(requiredPorts);
   if (result.ports === 'warning') {
-    result.recommendations.push('Some required ports (5432, 6379, 5050, 8081) are in use');
+    result.recommendations.push(`Some required ports (${requiredPorts.join(', ')}) are in use`);
   }
 
   // Check secrets

package/lib/utils/variable-transformer.js

@@ -198,22 +198,14 @@ function validateBuildConfig(build) {
 }
 
 /**
- * Validates and transforms deployment configuration
+ * Validates and transforms deployment configuration.
+ * Manifest is generic: deployment URL/env are resolved outside the manifest (user/config).
  * @function validateDeploymentConfig
- * @param {Object} deployment - Deployment configuration
- * @returns {Object|null} Validated deployment config or null
+ * @param {Object} _deployment - Deployment configuration (unused; manifest is generic)
+ * @returns {null} No deployment block emitted from variables
  */
-function validateDeploymentConfig(deployment) {
-  if (!deployment) {
-    return null;
-  }
-
-  const deploymentConfig = {};
-  if (deployment.controllerUrl && deployment.controllerUrl.trim() !== '' && /^https:\/\/.*$/.test(deployment.controllerUrl)) {
-    deploymentConfig.controllerUrl = deployment.controllerUrl;
-  }
-
-  return Object.keys(deploymentConfig).length > 0 ? deploymentConfig : null;
+function validateDeploymentConfig(_deployment) {
+  return null;
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.38.0",
+  "version": "2.39.0",
   "description": "AI Fabrix Local Fabric & Deployment SDK",
   "main": "lib/index.js",
   "bin": {

package/templates/applications/dataplane/README.md

@@ -18,17 +18,27 @@ npm install -g @aifabrix/builder
 # Check your environment
 aifabrix doctor
 
-# Login to controller (change your own port)
-aifabrix login --method device --environment dev --controller http://localhost:3100
+# Login to controller (debug mode -c http://localhost:3010 - change your own port)
+aifabrix login 
 
 # Register your application (gets you credentials automatically)
 aifabrix app register dataplane
+
+# Rotate credentials if needed:
+aifabrix app rotate-secret dataplane
+
+# Run locally
+aifabrix run dataplane
+
+# Deploy to miso-controller
+aifabrix deploy dataplane
+
 ```
 
 ### 3. Build & Run Locally
 
 ```bash
-# Build the Docker image
+# Build the Docker image (latest)
 aifabrix build dataplane
 
 # Run locally
@@ -41,7 +51,7 @@ aifabrix run dataplane
 
 ## Testing dataplane (use DATAPLANE_TEST_GUIDE)
 
-**Use the builder's Dataplane Test Guide** for auth, health, wizard, external systems, and pipeline checks:
+**Use the builder’s Dataplane Test Guide** for auth, health, wizard, external systems, and pipeline checks:
 
 - **In aifabrix-builder:** `integration/hubspot/DATAPLANE_TEST_GUIDE.md`
 - **Dataplane base URL:** `http://localhost:3111`
@@ -53,13 +63,13 @@ Keep `build.localPort` in `variables.yaml` at **3111** so it matches that guide.
 **View logs:**
 
 ```bash
-docker logs aifabrix-dataplane -f
+docker logs aifabrix-dev06-dataplane -f
 ```
 
 **Stop:**
 
 ```bash
-docker stop aifabrix-dataplane
+docker stop aifabrix-dev06-dataplane
 ```
 
 ### 4. Deploy to Azure
@@ -73,6 +83,7 @@ aifabrix push dataplane --registry myacr.azurecr.io --tag "v1.0.0,latest"
 
 # Deploy to miso-controller
 aifabrix deploy dataplane
+
 ```
 
 ---
@@ -103,7 +114,8 @@ aifabrix dockerfile dataplane --force           # Generate Dockerfile
 aifabrix resolve dataplane                      # Generate .env file
 
 # Deployment
-aifabrix json dataplane                         # Generate deployment manifest
+aifabrix json dataplane                         # Preview deployment JSON
+aifabrix genkey dataplane                       # Generate deployment key
 aifabrix push dataplane --registry myacr.azurecr.io # Push to ACR
 aifabrix deploy dataplane --controller <url>    # Deploy to Azure
 
@@ -167,6 +179,8 @@ export AIFABRIX_HOME=/custom/path
 export AIFABRIX_SECRETS=/path/to/secrets.yaml
 ```
 
+**Default OAuth callback URL:** Set `DATAPLANE_WEB_SERVER_URL` (e.g. in `env.template` as `http://localhost:${PORT}`) so the dataplane can build the default OAuth2 callback URL when `redirectUri` is omitted. The callback URL is `{DATAPLANE_WEB_SERVER_URL}/auth/callback`. When you change the domain (e.g. from localhost to a production URL), update this single variable and register the same callback URL in your OAuth app (e.g. HubSpot).
+
 ---
 
 ## Troubleshooting
@@ -177,12 +191,14 @@ export AIFABRIX_SECRETS=/path/to/secrets.yaml
 - **"Authentication failed"** → Run `aifabrix login` again
 - **"Build fails"** → Check Docker is running and `variables.yaml` → `build.secrets` path is correct
 - **"Can't connect"** → Verify infrastructure is running and PostgreSQL is accessible
+- **Wizard / API 401 after `rotate-secret`** → The wizard may write `.env` to a different path (e.g. `../../.env`). Ensure the **project root** `.env` has the new `MISO_CLIENTID` and `MISO_CLIENTSECRET` (copy from the rotate-secret output or run `make resolve`), then **restart the backend** (`make dev` or restart the process) so it loads the new credentials.
 
 **Regenerate files:**
 
 ```bash
 aifabrix resolve dataplane --force
 aifabrix json dataplane
+aifabrix genkey dataplane
 ```
 
 ---