@aifabrix/builder 2.51.1 → 2.52.0

package/lib/utils/paths.js

@@ -1022,23 +1022,17 @@ async function getResolveAppPath(appName, options = {}) {
   return { appPath: result.appPath, envOnly: false };
 }
 
-/**
- * @param {string} walkDir - Candidate workspace root (walk upward from cwd)
- * @param {string} cwd - Resolved process.cwd()
- * @param {ReturnType<typeof nodeFs>} disk
- * @returns {string|null}
- */
-function tryIntegrationAppKeyAtWalkStep(walkDir, cwd, disk) {
-  const integrationDir = path.join(walkDir, 'integration');
+function tryAuthoringAppKeyAtWalkStep(walkDir, cwd, disk, folderName) {
+  const authoringDir = path.join(walkDir, folderName);
   try {
-    if (!disk.existsSync(integrationDir)) {
+    if (!disk.existsSync(authoringDir)) {
       return null;
     }
-    const intNorm = path.resolve(integrationDir);
-    if (cwd !== intNorm && !cwd.startsWith(intNorm + path.sep)) {
+    const rootNorm = path.resolve(authoringDir);
+    if (cwd !== rootNorm && !cwd.startsWith(rootNorm + path.sep)) {
       return null;
     }
-    const rel = path.relative(intNorm, cwd);
+    const rel = path.relative(rootNorm, cwd);
     if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) {
       return null;
     }
@@ -1049,16 +1043,20 @@ function tryIntegrationAppKeyAtWalkStep(walkDir, cwd, disk) {
 }
 
 /**
- * Resolve app folder name when cwd is under some ancestor's `integration/<systemKey>/`.
+ * Resolve app folder name when cwd is under integration/, role-assistant/, or
+ * enterprise-knowledge/<systemKey>/.
  * Walks up from cwd (does not use {@link getIntegrationBuilderBaseDir}) so detection still works
- * when the canonical base is config/home but the shell is inside a checkout's integration tree.
+ * when the canonical base is config/home but the shell is inside a checkout's tree.
  */
 function resolveIntegrationAppKeyFromCwd() {
   const cwd = path.resolve(process.cwd());
   const disk = nodeFs();
   let p = cwd;
   for (let i = 0; i < 64; i += 1) {
-    const key = tryIntegrationAppKeyAtWalkStep(p, cwd, disk);
+    const key =
+      tryAuthoringAppKeyAtWalkStep(p, cwd, disk, 'integration') ||
+      tryAuthoringAppKeyAtWalkStep(p, cwd, disk, 'role-assistant') ||
+      tryAuthoringAppKeyAtWalkStep(p, cwd, disk, 'enterprise-knowledge');
     if (key) {
       return key;
     }

package/lib/utils/role-assistant-paths.js

@@ -3,7 +3,7 @@
  *
  * @fileoverview Paths under role-assistant/ for Role Assistant packages
  * @author AI Fabrix Team
- * @version 1.0.0
+ * @version 1.1.0
  */
 
 'use strict';
@@ -14,6 +14,7 @@ const { nodeFs } = require('../internal/node-fs');
 
 const WORKSPACE_ROLE_ASSISTANT = 'role-assistant';
 const SYSTEM_KIND_DIGITAL_WORKER = 'digitalWorker';
+const ROLE_ASSISTANT_SYSTEM_PREFIX = 'ra-';
 
 function getMaterializationParent() {
   const work = process.env.AIFABRIX_WORK;
@@ -63,7 +64,64 @@ function isExistingDirectory(disk, dirPath) {
 }
 
 /**
- * Resolves role-assistant/<roleKey> with cwd-first behavior.
+ * Bare business roleKey (strips leading ra- if present).
+ * @param {string} roleKeyOrSystemKey
+ * @returns {string}
+ */
+function bareRoleKey(roleKeyOrSystemKey) {
+  const raw = String(roleKeyOrSystemKey || '').trim();
+  if (raw.toLowerCase().startsWith(ROLE_ASSISTANT_SYSTEM_PREFIX)) {
+    return raw.slice(ROLE_ASSISTANT_SYSTEM_PREFIX.length);
+  }
+  return raw;
+}
+
+/**
+ * Folder / ExternalSystem key for a Role Assistant: ra-{roleKey}.
+ * @param {string} roleKeyOrSystemKey
+ * @returns {string}
+ */
+function roleAssistantSystemKey(roleKeyOrSystemKey) {
+  const bare = bareRoleKey(roleKeyOrSystemKey);
+  if (!bare) {
+    return '';
+  }
+  return `${ROLE_ASSISTANT_SYSTEM_PREFIX}${bare}`;
+}
+
+/**
+ * Candidate folder names under role-assistant/ (prefer ra-, then legacy bare).
+ * @param {string} roleKeyOrSystemKey
+ * @returns {string[]}
+ */
+function roleAssistantFolderCandidates(roleKeyOrSystemKey) {
+  const withRa = roleAssistantSystemKey(roleKeyOrSystemKey);
+  const bare = bareRoleKey(roleKeyOrSystemKey);
+  const out = [];
+  if (withRa) {
+    out.push(withRa);
+  }
+  if (bare && bare !== withRa) {
+    out.push(bare);
+  }
+  return out;
+}
+
+function firstExistingUnderRoot(disk, root, folderNames) {
+  if (!root) {
+    return null;
+  }
+  for (const name of folderNames) {
+    const candidate = path.join(root, name);
+    if (isExistingDirectory(disk, candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolves role-assistant/ra-{roleKey} (preferred) or legacy bare folder.
  * @param {string} roleKey
  * @returns {string}
  */
@@ -72,27 +130,31 @@ function getRoleAssistantPath(roleKey) {
     throw new Error('Role key is required and must be a string');
   }
   const disk = nodeFs();
+  const folders = roleAssistantFolderCandidates(roleKey);
+  const preferred = roleAssistantSystemKey(roleKey);
   const cwdRoot = getCwdRoleAssistantRoot();
-  const matPath = path.join(getMaterializationParent(), WORKSPACE_ROLE_ASSISTANT, roleKey);
-  if (cwdRoot) {
-    const cwdPath = path.join(cwdRoot, roleKey);
-    if (isExistingDirectory(disk, cwdPath)) {
-      return cwdPath;
-    }
-  }
-  if (isExistingDirectory(disk, matPath)) {
-    return matPath;
+  const matRoot = path.join(getMaterializationParent(), WORKSPACE_ROLE_ASSISTANT);
+
+  const existing =
+    firstExistingUnderRoot(disk, cwdRoot, folders) ||
+    firstExistingUnderRoot(disk, matRoot, folders);
+  if (existing) {
+    return existing;
   }
   if (cwdRoot) {
-    return path.join(cwdRoot, roleKey);
+    return path.join(cwdRoot, preferred);
   }
-  return matPath;
+  return path.join(matRoot, preferred);
 }
 
 module.exports = {
   WORKSPACE_ROLE_ASSISTANT,
   SYSTEM_KIND_DIGITAL_WORKER,
+  ROLE_ASSISTANT_SYSTEM_PREFIX,
   getCwdRoleAssistantRoot,
   getRoleAssistantRoot,
-  getRoleAssistantPath
+  getRoleAssistantPath,
+  bareRoleKey,
+  roleAssistantSystemKey,
+  roleAssistantFolderCandidates
 };

package/lib/utils/upload-sync-options.js

@@ -10,7 +10,7 @@
 
 /**
  * @param {Object} [options] - CLI options from test / sync callers
- * @returns {{ minimal: true, verbose: boolean, silentResolve: true, syncMode: true, force?: true, authConfig?: Object, dataplaneUrl?: string, environment?: string }}
+ * @returns {{ minimal: true, verbose: boolean, silentResolve: boolean, syncMode: boolean, force?: true, authConfig?: Object, dataplaneUrl?: string, environment?: string }}
  */
 function buildMinimalUploadSyncOptions(options = {}) {
   const deployPreflight = options.uploadContext === 'deploy-preflight';
@@ -18,11 +18,14 @@ function buildMinimalUploadSyncOptions(options = {}) {
     minimal: true,
     // CLI -v on verify-* / test-* is for run output, not preflight upload banners.
     verbose: false,
-    silentResolve: true,
-    syncMode: true,
+    // Deploy preflight should match `af upload` progress (URL + Publishing spinner).
+    // Verify/test --sync stays silent so parent command owns the progress line.
+    silentResolve: !deployPreflight,
+    syncMode: !deployPreflight,
     skipDataSync: true,
+    // Explicit suppress wins; deploy-preflight never suppresses the Publishing spinner.
     suppressPipelineSpinner:
-      options.suppressPipelineSpinner === true || deployPreflight === true
+      options.suppressPipelineSpinner === true && !deployPreflight
   };
   if (options.force === true) {
     out.force = true;

package/lib/validation/reserved-system-key-prefixes.js

@@ -0,0 +1,56 @@
+/**
+ * Frozen ExternalSystem key prefixes (Role Assistant / Enterprise Knowledge).
+ *
+ * @fileoverview Reject hand-authored ra-/ek- keys under integration/
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const RESERVED_SYSTEM_KEY_PREFIXES = ['ra-', 'ek-'];
+
+/**
+ * @param {string|null|undefined} systemKey
+ * @returns {boolean}
+ */
+function hasReservedPlatformSystemKeyPrefix(systemKey) {
+  const normalized = String(systemKey || '')
+    .trim()
+    .toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+  return RESERVED_SYSTEM_KEY_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+
+/**
+ * Connected Systems under integration/ must not use reserved prefixes.
+ * Role Assistant packages live under role-assistant/ra-*.
+ *
+ * @param {string|null|undefined} systemKey
+ * @param {string|null|undefined} workspaceBaseDir - integration | role-assistant | …
+ * @returns {string|null} Error message or null when allowed
+ */
+function reservedSystemKeyError(systemKey, workspaceBaseDir) {
+  if (!hasReservedPlatformSystemKeyPrefix(systemKey)) {
+    return null;
+  }
+  const workspace = String(workspaceBaseDir || '')
+    .trim()
+    .toLowerCase();
+  if (workspace === 'role-assistant' || workspace === 'enterprise-knowledge') {
+    return null;
+  }
+  return (
+    `System key '${systemKey}' uses a reserved prefix (ra- or ek-). ` +
+    'Role Assistant packages use role-assistant/ra-{roleKey}/; ' +
+    'Enterprise Knowledge uses ek- keys from platform generators only.'
+  );
+}
+
+module.exports = {
+  RESERVED_SYSTEM_KEY_PREFIXES,
+  hasReservedPlatformSystemKeyPrefix,
+  reservedSystemKeyError
+};

package/lib/validation/validate.js

@@ -22,6 +22,7 @@ const { generateControllerManifest } = require('../generator/external-controller
 const { validateControllerManifest } = require('./external-manifest-validator');
 const { runExternalValidateWithOptionalCertSync } = require('./validate-external-cert-sync');
 const { validateExternalFile } = require('./validate-external-file');
+const { reservedSystemKeyError } = require('./reserved-system-key-prefixes');
 
 /**
  * Validates a file path (detects type and validates)
@@ -276,6 +277,52 @@ async function validateManifestStep(appName, options = {}) {
   }
 }
 
+/**
+ * Early-fail payload when system key uses a reserved prefix.
+ * @param {string} reservedError
+ * @param {string} appPath
+ * @returns {Object}
+ */
+function reservedSystemKeyValidationResult(reservedError, appPath) {
+  return {
+    valid: false,
+    errors: [reservedError],
+    warnings: [],
+    steps: {
+      application: { valid: false, errors: [reservedError], warnings: [] },
+      components: { valid: true, errors: [], warnings: [], files: [], skipped: true },
+      manifest: { valid: true, errors: [], warnings: [], skipped: true }
+    },
+    appPath
+  };
+}
+
+/**
+ * Aggregate step results into the complete validation response.
+ * @param {Object} steps
+ * @param {string} appPath
+ * @returns {Object}
+ */
+function aggregateExternalValidationSteps(steps, appPath) {
+  const allErrors = [
+    ...steps.application.errors,
+    ...steps.components.errors,
+    ...steps.manifest.errors
+  ];
+  const allWarnings = [
+    ...steps.application.warnings,
+    ...steps.components.warnings,
+    ...steps.manifest.warnings
+  ];
+  return {
+    valid: allErrors.length === 0,
+    errors: allErrors,
+    warnings: allWarnings,
+    steps,
+    appPath
+  };
+}
+
 /**
  * Validates external system completely (components + full manifest)
  * Performs step-by-step validation: application config → components → full manifest
@@ -295,7 +342,12 @@ async function validateExternalSystemComplete(appName, options = {}) {
     throw new Error('App name is required and must be a string');
   }
 
-  const { appPath } = await detectAppType(appName, options);
+  const { appPath, baseDir } = await detectAppType(appName, options);
+  const reservedError = reservedSystemKeyError(appName, baseDir);
+  if (reservedError) {
+    return reservedSystemKeyValidationResult(reservedError, appPath);
+  }
+
   const steps = {
     application: { valid: false, errors: [], warnings: [] },
     components: { valid: false, errors: [], warnings: [], files: [] },
@@ -303,14 +355,9 @@ async function validateExternalSystemComplete(appName, options = {}) {
   };
 
   const externalOptions = { ...options };
-
-  // Step 1: Validate Application Config
   steps.application = await validateApplicationStep(appName, externalOptions);
-
-  // Step 2: Validate Individual Components
   steps.components = await validateComponentsStep(appName, externalOptions);
 
-  // If components have errors, return early (don't validate manifest)
   if (!steps.components.valid) {
     steps.manifest = { valid: true, errors: [], warnings: [], skipped: true };
     return {
@@ -322,20 +369,8 @@ async function validateExternalSystemComplete(appName, options = {}) {
     };
   }
 
-  // Step 3 & 4: Generate and Validate Full Manifest (only if Step 2 passes)
   steps.manifest = await validateManifestStep(appName, { ...externalOptions, appPath });
-
-  // Aggregate Results
-  const allErrors = [...steps.application.errors, ...steps.components.errors, ...steps.manifest.errors];
-  const allWarnings = [...steps.application.warnings, ...steps.components.warnings, ...steps.manifest.warnings];
-
-  return {
-    valid: allErrors.length === 0,
-    errors: allErrors,
-    warnings: allWarnings,
-    steps,
-    appPath
-  };
+  return aggregateExternalValidationSteps(steps, appPath);
 }
 
 async function validateAppOrFile(appOrFile, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.51.1",
+  "version": "2.52.0",
   "description": "AI Fabrix Builder — CLI and developer scripts (pnpm + af)",
   "main": "lib/index.js",
   "bin": {

package/templates/applications/builder-api/application.yaml

@@ -2,7 +2,7 @@
 app:
   key: builder-api
   displayName: 'AI Fabrix Builder API'
-  description: 'Stateless HTTP orchestration for external-system workspace lifecycle. Provider-neutral integration flows via Dataplane Enterprise MCP and governance APIs (154.0 / 154.1).'
+  description: 'Business Transformation services — HTTP orchestration for connected-system workspace lifecycle via Dataplane Enterprise MCP and governance APIs.'
   type: webapp
   language: typescript
   version: 1.0.0
@@ -11,8 +11,8 @@ app:
 image:
   name: aifabrix/builder-api
   tag: latest
-  registry: aifabrixdevacr.azurecr.io
-  registryMode: acr
+  registry: aifabrixacr.azurecr.io
+  registryMode: external
 
 # Port Configuration (container port; host port = port + developer_id * 100)
 port: 3005

package/templates/applications/dataplane/application.yaml

@@ -5,16 +5,15 @@ app:
   description: "AI Fabrix Dataplane is a secure, in-tenant integration and automation layer that supplies governed, normalized, and explainable enterprise data to AI agents. Using CIP as a declarative standard, it enforces RBAC and ABAC, executes integrations, and exposes trusted data via MCP and OpenAPI."
   type: webapp
   language: python # Explicitly specify Python language
-  version: 2.0.15
-
+  version: 2.0.20
 # Image Configuration
 # Set tag to match your build (example: aifabrix build dataplane -t 1.0.0).
 # Registry is required so the controller can pull the image (avoids docker-not-found on the controller host).
 image:
   name: aifabrix/dataplane
   tag: latest
-  registry: aifabrixdevacr.azurecr.io
-  registryMode: acr
+  registry: aifabrixacr.azurecr.io
+  registryMode: external
 
 # Port Configuration
 port: 3001

package/templates/applications/dataplane/env.template

@@ -44,7 +44,7 @@ API_KEY_BYPASS_ROLES=full-access
 
 # API Configuration
 API_V1_STR=/api/v1
-VERSION=2.0.15
+VERSION=2.0.20
 # Minimum supported aifabrix-builder CLI semver (advertised on /health and /api/v1/health; empty = no gate)
 # MIN_BUILDER_CLI_VERSION=2.45.0
 MIN_BUILDER_CLI_VERSION=2.45.5
@@ -284,7 +284,7 @@ VALIDATION_AUTO_ISSUE_INTEGRATION_CERTIFICATE=true
 CIP_EXECUTION_MAX_RESPONSE_SIZE_MB=100.0
 CIP_EXECUTION_MAX_RECORDS=100000
 CIP_EXECUTION_OPERATION_TIMEOUT=300.0
-CIP_EXECUTION_HTTP_TIMEOUT=30.0
+CIP_EXECUTION_HTTP_TIMEOUT=120.0
 CIP_EXECUTION_MAX_RETRIES=3
 CIP_EXECUTION_RETRY_BACKOFF_FACTOR=2.0
 CIP_EXECUTION_RETRY_INITIAL_DELAY=1.0

package/templates/applications/dataplane/rbac.yaml

@@ -5,47 +5,47 @@
 # MisoClient validates environment access automatically based on user/application permissions.
 
 roles:
-  - name: "AI Fabrix Platform Admin"
+  - name: "Platform Admin"
     value: "aifabrix-platform-admin"
     description: "Full platform infrastructure management and enterprise controller access"
     groups: ["AI-Fabrix-Platform-Admins"]
 
-  - name: "AI Fabrix Security Admin"
+  - name: "Security Admin"
     value: "aifabrix-security-admin"
     description: "Security and compliance management for enterprise controller"
     groups: ["AI-Fabrix-Security-Admins"]
 
-  - name: "AI Fabrix Deployment Admin"
+  - name: "Deployment Admin"
     value: "aifabrix-deployment-admin"
     description: "Application deployment orchestration and environment management"
     groups: ["AI-Fabrix-Deployment-Admins"]
 
-  - name: "AI Fabrix Compliance Admin"
+  - name: "Compliance Admin"
     value: "aifabrix-compliance-admin"
     description: "ISO 27001 compliance monitoring and audit management"
     groups: ["AI-Fabrix-Compliance-Admins"]
 
-  - name: "AI Fabrix Developer"
+  - name: "Developer"
     value: "aifabrix-developer"
     description: "Developer access to deploy applications via CI pipelines"
     groups: ["AI-Fabrix-Developers"]
 
-  - name: "AI Fabrix Business Transformation"
-    value: "aifabrix-business-transformation"
+  - name: "Business Transformation"
+    value: "business-transformation"
     description: "Built-in assistant: business intention → governed Connected Systems via Runtime and builder-api"
     groups: ["AI-Fabrix-Business-Transformation"]
 
-  - name: "AI Fabrix Observer"
+  - name: "Observer"
     value: "aifabrix-observer"
     description: "Read-only access to monitoring, logs, and compliance reports"
     groups: ["AI-Fabrix-Observers"]
 
-  - name: "AI Fabrix AI Trust Operator"
+  - name: "AI Trust Operator"
     value: "aifabrix-ai-trust-operator"
     description: "Run AI Trust access evaluation and explain visibility for governed users"
     groups: ["AI-Fabrix-AI-Trust-Operators"]
 
-  - name: "AI Fabrix External System Discoverer"
+  - name: "External System Discoverer"
     value: "aifabrix-external-system-discoverer"
     description: "Discover business context for external systems via REST and MCP"
     groups: ["AI-Fabrix-External-System-Discoverers"]

package/templates/applications/keycloak/application.yaml

@@ -10,8 +10,8 @@ app:
 image:
   name: aifabrix/keycloak
   tag: 'latest'
-  registry: aifabrixdevacr.azurecr.io
-  registryMode: acr
+  registry: aifabrixacr.azurecr.io
+  registryMode: external
 
 # Port Configuration (base for host; host port = 8082 + developer_id*100 from ~/.aifabrix/config.yaml)
 port: 8082

package/templates/applications/keycloak/env.template

@@ -9,11 +9,14 @@
 KC_BOOTSTRAP_ADMIN_USERNAME=admin
 KC_BOOTSTRAP_ADMIN_PASSWORD=kv://keycloak-admin-passwordKeyVault
 KC_HOSTNAME_STRICT=false
-KC_HTTP_ENABLED=${HTTP_ENABLED}
+# Follows tlsEnabled in ~/.aifabrix/config.yaml (same as ${TLS_ENABLED}).
+# Traefik/edge HTTPS on → true (proxy forwards HTTP to Keycloak :8080).
+# Single container without HTTPS (tlsEnabled false) → false.
+KC_HTTP_ENABLED=${TLS_ENABLED}
 # When Traefik + frontDoorRouting.enabled are on, same vdir as url://public. If the front door is off, env generation
 # rewrites url://vdir-public to "/" before expansion (empty path is invalid — Keycloak 26 SRCFG00040).
 # Docker-only templates may use url://vdir-internal instead.
-KC_HTTP_RELATIVE_PATH=url://vdir-public
+KC_HTTP_RELATIVE_PATH=/auth
 
 # =============================================================================
 # HOSTNAME / ISSUER (Docker vs localhost)

package/templates/applications/miso-controller/application.yaml

@@ -4,7 +4,7 @@ app:
   displayName: 'Miso Controller'
   description: 'Miso is the AI Fabrix in-tenant controller and portal layer for securely operating enterprise AI apps inside a customer’s Azure tenant. It provides Entra ID SSO, RBAC, audit logs, environment/app configuration via schemas, and safe secret handling via Key Vault references—ensuring governance, traceability, and predictable UX across portal, SDK, and CLI.'
   type: webapp
-  version: '2.0.10'
+  version: '2.0.20'
 
 # Image Configuration
 # Set tag to match your build (e.g. aifabrix build miso-controller -t 1.0.0 then tag: 1.0.0)
@@ -12,8 +12,8 @@ app:
 image:
   name: aifabrix/miso-controller
   tag: latest
-  registry: aifabrixdevacr.azurecr.io
-  registryMode: acr
+  registry: aifabrixacr.azurecr.io
+  registryMode: external
 
 # Port Configuration (container port; host port = 3000 + developer_id*100 from ~/.aifabrix/config.yaml)
 port: 3000

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

@@ -49,6 +49,10 @@ ONBOARDING_ADMIN_EMAIL=kv://miso-controller-admin-emailKeyVault
 # When true, supersedes ONBOARDING_CREATE_DEV_ENV for which extra environments are created
 ONBOARDING_FULL_PLATFORM=false
 
+# When true, run Azure env deploy for onboarding envs (SDK modules). Default false —
+# Marketplace already provisions infra; TA owns customer env deploy.
+ONBOARDING_CREATE_MISO_ENV=false
+
 # Set to true to create both miso and dev environments during onboarding
 # When false (default), only the miso environment is created (ignored when ONBOARDING_FULL_PLATFORM=true)
 ONBOARDING_CREATE_DEV_ENV=true
@@ -236,6 +240,14 @@ SKIP_DB_REDEPLOY=true
 # Bootstrap (SKIP_FIRST_TIME_SETUP=false) is separate from the activation wizard.
 DEPLOYMENT=database
 
+# Dev/test: open /tenant-activation on Platform Apps (last step). Default false.
+# Does not skip server-side TA — use only when env is already activated/deployed.
+TA_SKIP_TO_APP_DEPLOY=false
+
+# Dev/test: show TA Entra "Completing setup" countdown (120s cap). Default false.
+# Exposed to UI via GET /api/v1/tenant/status → showTaCountdown (restart controller after change).
+SHOW_TA_COUNT_DOWN=false
+
 # =============================================================================
 # SECURITY & ENCRYPTION
 # =============================================================================
@@ -287,9 +299,10 @@ ENTRA_GRAPH_DELEGATED_REDIRECT_URI=https://aifabrix-pro-mori-web-we.azurewebsite
 # =============================================================================
 # MORI SERVICE CONFIGURATION
 # =============================================================================
-
-# Shared pro Mori (Entra handoff + Graph callback). Prefer this over url://mori-controller-public
-# unless a local Mori app is registered and running for the developer.
+# Shared Mori (handoff poll + Entra callback). Local `url://mori-controller-public`
+# only works when a local Mori app is registered and running for this developer.
+# MORI_CALLBACK_API_KEY must be the same secret as Mori MORI_CONTROLLER_CALLBACK_API_KEY
+# (both resolve from kv://mori-callback-api-keyKeyVault — do not generate separate values).
 MORI_BASE_URL=https://aifabrix-pro-mori-web-we.azurewebsites.net
 MORI_AUTH_METHOD=kv://mori-controller-auth-methodKeyVault
 MORI_CALLBACK_API_KEY=kv://mori-callback-api-keyKeyVault