@aifabrix/builder 2.51.0 → 2.52.0

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

@@ -72,7 +72,7 @@
             "date": "2026-06-15T00:00:00Z",
             "changes": [
                "Added systemKind digitalWorker to x-systemKindCatalog (enterpriseContext group).",
-               "Extended subscriptionFilter with roleKeys, includeSystemKinds, and excludeSystemKinds for Digital Worker generation inputs."
+               "Extended subscriptionFilter with roleKeys, includeSystemKinds, and excludeSystemKinds for Role Assistant generation inputs."
             ],
             "breaking": false
          },
@@ -184,7 +184,7 @@
    "$defs": {
       "subscriptionFilter": {
          "type": "object",
-         "description": "Shared filter engine shape for subscription triggers and Digital Worker generation inputs.",
+         "description": "Shared filter engine shape for subscription triggers and Role Assistant generation inputs.",
          "properties": {
             "resourceTypes": {
                "type": "array",
@@ -217,7 +217,7 @@
                   "minLength": 1
                },
                "minItems": 1,
-               "description": "Role keys that scope Digital Worker or subscription generation."
+               "description": "Role keys that scope Role Assistant or subscription generation."
             },
             "includeSystemKinds": {
                "type": "array",
@@ -978,7 +978,7 @@
          },
          {
             "key": "digitalWorker",
-            "displayName": "Digital Worker",
+            "displayName": "Role Assistant",
             "group": "enterpriseContext"
          },
          {

package/lib/schema/role-assistant-settings.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "aifabrix://schema/role-assistant-settings",
+  "title": "Role Assistant Settings",
+  "description": "Schema for role-assistant.yaml used by digitalWorker packages.",
+  "type": "object",
+  "required": [
+    "apiVersion",
+    "version",
+    "kind",
+    "roleKey"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "apiVersion": {
+      "type": "string",
+      "const": "aifabrix.ai/v1"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "kind": {
+      "type": "string",
+      "const": "RoleAssistantSettings"
+    },
+    "roleKey": {
+      "type": "string",
+      "pattern": "^[a-z0-9-_]+$"
+    },
+    "dev": {
+      "$ref": "#/$defs/environmentSettings"
+    },
+    "tst": {
+      "$ref": "#/$defs/environmentSettings"
+    },
+    "pro": {
+      "$ref": "#/$defs/environmentSettings"
+    }
+  },
+  "$defs": {
+    "environmentSettings": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "runtime": {
+          "$ref": "#/$defs/runtime"
+        },
+        "debug": {
+          "$ref": "#/$defs/debug"
+        },
+        "knowledge": {
+          "$ref": "#/$defs/knowledge"
+        }
+      }
+    },
+    "runtime": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "provider": {
+          "type": "string"
+        },
+        "model": {
+          "type": "string"
+        },
+        "temperature": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2
+        },
+        "maxLoops": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000
+        }
+      }
+    },
+    "debug": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "includeRuntimeLog": {
+          "type": "boolean"
+        },
+        "includePromptTrace": {
+          "type": "boolean"
+        },
+        "includeCapabilityTrace": {
+          "type": "boolean"
+        }
+      }
+    },
+    "knowledge": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "documentStorageKey": {
+          "type": "string",
+          "pattern": "^[a-z0-9-_]+$"
+        }
+      }
+    }
+  }
+}

package/lib/utils/api.js

@@ -381,12 +381,11 @@ function extractControllerUrl(url) {
     return match ? match[1] : url;
   }
 }
-
 /**
- * Set auth header on headers object: Bearer for user token, x-client-token for application token.
+ * Set auth header on headers object: Bearer for user token, x-client-token for app token.
  * @param {Object} headers - Headers object to mutate
  * @param {string} token - Token value
- * @param {string} authType - 'bearer' or 'client-token'
+ * @param {string} authType - 'bearer' | 'client-token'
  */
 function setAuthHeader(headers, token, authType) {
   if (!token) return;
@@ -396,7 +395,6 @@ function setAuthHeader(headers, token, authType) {
     headers['Authorization'] = `Bearer ${token}`;
   }
 }
-
 /**
  * Make an authenticated API call with user token (Bearer) or application token (x-client-token).
  * Automatically refreshes device token on 401 when user Bearer was used.
@@ -408,7 +406,48 @@ function setAuthHeader(headers, token, authType) {
  * @param {string} [tokenOrAuthConfig.controller] - Controller URL for token refresh (if object)
  * @returns {Promise<Object>} Response object
  */
-// eslint-disable-next-line max-statements
+/**
+ * Retry once after device-token refresh on 401 (Bearer only; never for client-token/preserveBearer).
+ * @param {Object} response
+ * @param {string} url
+ * @param {Object} options
+ * @param {Object} headers
+ * @param {string|null} authControllerUrl
+ * @returns {Promise<Object>}
+ */
+async function retryApiCallAfterDeviceTokenRefresh(
+  response,
+  url,
+  options,
+  headers,
+  authControllerUrl
+) {
+  try {
+    const { forceRefreshDeviceToken } = require('./token-manager');
+    const refreshedToken = await forceRefreshDeviceToken(
+      authControllerUrl || extractControllerUrl(url)
+    );
+    if (refreshedToken?.token) {
+      headers.Authorization = `Bearer ${refreshedToken.token}`;
+      return await makeApiCall(url, { ...options, headers });
+    }
+    const authError =
+      'Authentication failed: Token expired and refresh failed. Please login again using: aifabrix login';
+    return { ...response, error: authError, formattedError: authError };
+  } catch (refreshError) {
+    const authError = `Authentication failed: ${refreshError.message || String(refreshError)}. Please login again using: aifabrix login`;
+    return { ...response, error: authError, formattedError: authError };
+  }
+}
+function shouldRefreshBearerOn401(response, authType, tokenOrAuthConfig) {
+  return (
+    !response.success &&
+    response.status === 401 &&
+    authType !== 'client-token' &&
+    !(typeof tokenOrAuthConfig === 'object' && tokenOrAuthConfig?.preserveBearer)
+  );
+}
+
 async function authenticatedApiCall(url, options = {}, tokenOrAuthConfig) {
   const isStringToken = typeof tokenOrAuthConfig === 'string';
   const token = isStringToken ? tokenOrAuthConfig : tokenOrAuthConfig?.token;
@@ -426,32 +465,18 @@ async function authenticatedApiCall(url, options = {}, tokenOrAuthConfig) {
     headers
   });
 
-  // Only attempt device token refresh on 401 when user Bearer token was used (not for client-token).
-  // Token-forward (builder-api): never refresh from mount device store — keep the caller JWT.
-  if (
-    !response.success &&
-    response.status === 401 &&
-    authType !== 'client-token' &&
-    !(typeof tokenOrAuthConfig === 'object' && tokenOrAuthConfig?.preserveBearer)
-  ) {
-    try {
-      const { forceRefreshDeviceToken } = require('./token-manager');
-      const refreshedToken = await forceRefreshDeviceToken(authControllerUrl || extractControllerUrl(url));
-      if (refreshedToken?.token) {
-        headers['Authorization'] = `Bearer ${refreshedToken.token}`;
-        return await makeApiCall(url, { ...options, headers });
-      }
-      const authError = 'Authentication failed: Token expired and refresh failed. Please login again using: aifabrix login';
-      return { ...response, error: authError, formattedError: authError };
-    } catch (refreshError) {
-      const authError = `Authentication failed: ${refreshError.message || String(refreshError)}. Please login again using: aifabrix login`;
-      return { ...response, error: authError, formattedError: authError };
-    }
+  if (shouldRefreshBearerOn401(response, authType, tokenOrAuthConfig)) {
+    return retryApiCallAfterDeviceTokenRefresh(
+      response,
+      url,
+      options,
+      headers,
+      authControllerUrl
+    );
   }
 
   return response;
 }
-
 const {
   initiateDeviceCodeFlow,
   pollDeviceCodeToken,

package/lib/utils/app-path-resolve.js

@@ -15,6 +15,11 @@ const {
   SYSTEM_KIND_ENTERPRISE_KNOWLEDGE,
   getEnterpriseKnowledgePath
 } = require('./enterprise-knowledge-paths');
+const {
+  WORKSPACE_ROLE_ASSISTANT,
+  SYSTEM_KIND_DIGITAL_WORKER,
+  getRoleAssistantPath
+} = require('./role-assistant-paths');
 
 const WORKSPACE_INTEGRATION = 'integration';
 
@@ -62,10 +67,14 @@ function normalizeWorkspaceOverride(raw) {
     return null;
   }
   const v = String(raw).trim().toLowerCase();
-  if (v === WORKSPACE_INTEGRATION || v === WORKSPACE_ENTERPRISE_KNOWLEDGE) {
+  if (
+    v === WORKSPACE_INTEGRATION ||
+    v === WORKSPACE_ENTERPRISE_KNOWLEDGE ||
+    v === WORKSPACE_ROLE_ASSISTANT
+  ) {
     return v;
   }
-  throw new Error(`Unknown workspace "${raw}". Use integration or enterprise-knowledge.`);
+  throw new Error(`Unknown workspace "${raw}". Use integration, enterprise-knowledge, or role-assistant.`);
 }
 
 function workspacePair(appPath, baseDir) {
@@ -76,47 +85,84 @@ function resolveFromWorkspaceOverride(workspaceOverride, appName, getIntegration
   if (workspaceOverride === WORKSPACE_ENTERPRISE_KNOWLEDGE) {
     return workspacePair(getEnterpriseKnowledgePath(appName), WORKSPACE_ENTERPRISE_KNOWLEDGE);
   }
+  if (workspaceOverride === WORKSPACE_ROLE_ASSISTANT) {
+    return workspacePair(getRoleAssistantPath(appName), WORKSPACE_ROLE_ASSISTANT);
+  }
   if (workspaceOverride === WORKSPACE_INTEGRATION) {
     return workspacePair(getIntegrationPath(appName), WORKSPACE_INTEGRATION);
   }
   return null;
 }
 
-function resolveAmbiguousWorkspace(ekPath, intPath, explicitKind, appName) {
-  const kind =
-    explicitKind ||
-    readSystemKindFromAppDir(ekPath, appName) ||
-    readSystemKindFromAppDir(intPath, appName);
+function resolveWorkspaceFromSystemKind(kind, ekPath, intPath, roleAssistantPath) {
   if (kind === SYSTEM_KIND_ENTERPRISE_KNOWLEDGE) {
     return workspacePair(ekPath, WORKSPACE_ENTERPRISE_KNOWLEDGE);
   }
+  if (kind === SYSTEM_KIND_DIGITAL_WORKER) {
+    return workspacePair(roleAssistantPath, WORKSPACE_ROLE_ASSISTANT);
+  }
   return workspacePair(intPath, WORKSPACE_INTEGRATION);
 }
 
-function resolveFromExistingPaths(ekPath, intPath, ekExists, intExists, explicitKind, appName) {
-  if (ekExists && !intExists) {
-    return workspacePair(ekPath, WORKSPACE_ENTERPRISE_KNOWLEDGE);
-  }
-  if (intExists && !ekExists) {
+function resolveAmbiguousWorkspace(ekPath, intPath, roleAssistantPath, explicitKind, appName) {
+  const kind =
+    explicitKind ||
+    readSystemKindFromAppDir(roleAssistantPath, appName) ||
+    readSystemKindFromAppDir(ekPath, appName) ||
+    readSystemKindFromAppDir(intPath, appName);
+  return resolveWorkspaceFromSystemKind(kind, ekPath, intPath, roleAssistantPath);
+}
+
+function resolveFromExistingPaths(paths, existence, explicitKind, appName) {
+  const { ekPath, intPath, roleAssistantPath } = paths;
+  const { ekExists, intExists, roleAssistantExists } = existence;
+  const existingCount = [ekExists, intExists, roleAssistantExists].filter(Boolean).length;
+  if (existingCount === 1) {
+    if (ekExists) {
+      return workspacePair(ekPath, WORKSPACE_ENTERPRISE_KNOWLEDGE);
+    }
+    if (roleAssistantExists) {
+      return workspacePair(roleAssistantPath, WORKSPACE_ROLE_ASSISTANT);
+    }
     return workspacePair(intPath, WORKSPACE_INTEGRATION);
   }
-  if (ekExists && intExists) {
-    return resolveAmbiguousWorkspace(ekPath, intPath, explicitKind, appName);
+  if (existingCount > 1) {
+    return resolveAmbiguousWorkspace(ekPath, intPath, roleAssistantPath, explicitKind, appName);
   }
-  const kind = explicitKind || readSystemKindFromAppDir(intPath, appName);
-  if (kind === SYSTEM_KIND_ENTERPRISE_KNOWLEDGE) {
-    return workspacePair(ekPath, WORKSPACE_ENTERPRISE_KNOWLEDGE);
-  }
-  return workspacePair(intPath, WORKSPACE_INTEGRATION);
+  const kind =
+    explicitKind ||
+    readSystemKindFromAppDir(roleAssistantPath, appName) ||
+    readSystemKindFromAppDir(ekPath, appName) ||
+    readSystemKindFromAppDir(intPath, appName);
+  return resolveWorkspaceFromSystemKind(kind, ekPath, intPath, roleAssistantPath);
+}
+
+function resolveFromExistingPathsBackwardCompatible(
+  ekPath,
+  intPath,
+  roleAssistantPath,
+  explicitKind,
+  appName
+) {
+  return resolveFromExistingPaths(
+    { ekPath, intPath, roleAssistantPath },
+    {
+      ekExists: isExistingDirectory(ekPath),
+      intExists: isExistingDirectory(intPath),
+      roleAssistantExists: isExistingDirectory(roleAssistantPath)
+    },
+    explicitKind,
+    appName
+  );
 }
 
 /**
  * Resolves authoring tree for an external system or Enterprise Knowledge anchor.
  * @param {string} appName - App or anchor key
  * @param {Object} [options]
- * @param {string} [options.workspace] - integration | enterprise-knowledge
+ * @param {string} [options.workspace] - integration | enterprise-knowledge | role-assistant
  * @param {string} [options.systemKind] - Explicit systemKind override
- * @returns {{ appPath: string, baseDir: 'integration' | 'enterprise-knowledge' }}
+ * @returns {{ appPath: string, baseDir: 'integration' | 'enterprise-knowledge' | 'role-assistant' }}
  */
 function resolveAppWorkspace(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
@@ -137,11 +183,11 @@ function resolveAppWorkspace(appName, options = {}) {
 
   const ekPath = getEnterpriseKnowledgePath(appName);
   const intPath = getIntegrationPath(appName);
-  return resolveFromExistingPaths(
+  const roleAssistantPath = getRoleAssistantPath(appName);
+  return resolveFromExistingPathsBackwardCompatible(
     ekPath,
     intPath,
-    isExistingDirectory(ekPath),
-    isExistingDirectory(intPath),
+    roleAssistantPath,
     explicitKind,
     appName
   );
@@ -160,7 +206,9 @@ function resolveExternalSystemPath(appName, options = {}) {
 module.exports = {
   WORKSPACE_INTEGRATION,
   WORKSPACE_ENTERPRISE_KNOWLEDGE,
+  WORKSPACE_ROLE_ASSISTANT,
   SYSTEM_KIND_ENTERPRISE_KNOWLEDGE,
+  SYSTEM_KIND_DIGITAL_WORKER,
   readSystemKindFromAppDir,
   normalizeWorkspaceOverride,
   resolveAppWorkspace,

package/lib/utils/authentication-shape.js

@@ -64,7 +64,9 @@ function buildFlatCredentialTemplate(systemKey, authType) {
       security: { clientId: kvPath('clientId'), clientSecret: kvPath('clientSecret') }
     },
     apikey: {
-      variables: { baseUrl: base, headerName: 'X-API-Key' },
+      // Match credential-field-registry placeholders (Authorization + Bearer).
+      // Integrations that need a literal custom header set headerName after repair.
+      variables: { baseUrl: base, headerName: 'Authorization', prefix: 'Bearer' },
       security: { apiKey: kvPath('apiKey') }
     },
     bearerToken: {

package/lib/utils/certify-external-workspace.js

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Workspace roots allowed for external certify / verify CLI commands.
+ */
+
+'use strict';
+
+const CERTIFY_EXTERNAL_BASE_DIRS = new Set([
+  'integration',
+  'role-assistant',
+  'enterprise-knowledge'
+]);
+
+/**
+ * @param {string|null|undefined} baseDir
+ * @returns {boolean}
+ */
+function isCertifyExternalWorkspace(baseDir) {
+  return CERTIFY_EXTERNAL_BASE_DIRS.has(baseDir);
+}
+
+/**
+ * @param {string|null|undefined} baseDir
+ * @param {string} commandLabel - e.g. verify-operations
+ * @returns {void}
+ * @throws {Error}
+ */
+function assertCertifyExternalWorkspace(baseDir, commandLabel) {
+  if (!isCertifyExternalWorkspace(baseDir)) {
+    throw new Error(
+      `${commandLabel} applies to external authoring folders only ` +
+        '(integration/<systemKey>/, role-assistant/<roleKey>/, or enterprise-knowledge/<key>/).'
+    );
+  }
+}
+
+module.exports = {
+  CERTIFY_EXTERNAL_BASE_DIRS,
+  isCertifyExternalWorkspace,
+  assertCertifyExternalWorkspace
+};

package/lib/utils/deployment-validation.js

@@ -8,6 +8,27 @@
  * @version 2.0.0
  */
 
+/**
+ * True when URL is http to a Docker Compose service DNS name (single hostname label).
+ * Example: http://miso-controller:3000/miso — used by builder-api in compose, not public HTTP.
+ *
+ * @param {string} url
+ * @returns {boolean}
+ */
+function isDockerComposeServiceHttpUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'http:') {
+      return false;
+    }
+    const host = parsed.hostname || '';
+    // Compose DNS: one label, no dots (miso-controller, dataplane, …)
+    return Boolean(host) && !host.includes('.') && host !== 'localhost';
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Validates and sanitizes controller URL
  * Enforces HTTPS-only communication for security
@@ -20,9 +41,13 @@ function validateControllerUrl(url) {
     throw new Error('Controller URL is required and must be a string');
   }
 
-  // Must use HTTPS for security (allow http://localhost for local development)
-  if (!url.startsWith('https://') && !url.startsWith('http://localhost')) {
-    throw new Error('Controller URL must use HTTPS (https://) or http://localhost');
+  // HTTPS required in public networks; allow localhost and compose-service HTTP for local Docker
+  const allowedHttp =
+    url.startsWith('http://localhost') || isDockerComposeServiceHttpUrl(url);
+  if (!url.startsWith('https://') && !allowedHttp) {
+    throw new Error(
+      'Controller URL must use HTTPS (https://), http://localhost, or a Docker Compose service HTTP URL'
+    );
   }
 
   // Basic URL format validation

package/lib/utils/docker-run-ephemeral.js

@@ -0,0 +1,115 @@
+/**
+ * Ephemeral docker run (--rm) for one-shot commands (test, install, deployJob).
+ *
+ * @fileoverview Shared docker run --rm helper
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+const { spawn } = require('child_process');
+const { getDockerExecEnv } = require('./remote-docker-env');
+
+/**
+ * Run a shell command in an ephemeral container; optional --env-file / --network / bind mounts.
+ * Attach to the developer infra bridge when the command needs compose DNS
+ * (e.g. hostname `postgres` in DATABASE_URL).
+ * @param {string} fullImage - Image:tag
+ * @param {string} cmd - Shell command (passed to sh -c)
+ * @param {string|null} [envFilePath] - Path for docker run --env-file
+ * @param {{
+ *   network?: string|null,
+ *   volumeMounts?: Array<{ host: string, container: string }>,
+ *   quiet?: boolean
+ * }} [options] - quiet=true pipes stdio (installer-friendly; dump on failure)
+ * @returns {Promise<number|{ code: number, output: string }>} Exit code, or code+output when quiet
+ */
+async function runDockerRunEphemeral(fullImage, cmd, envFilePath = null, options = {}) {
+  const dockerEnv = await getDockerExecEnv();
+  const network =
+    options && typeof options.network === 'string' && options.network.trim()
+      ? options.network.trim()
+      : null;
+  const volumeMounts = Array.isArray(options?.volumeMounts) ? options.volumeMounts : [];
+  const quiet = options?.quiet === true;
+  const args = _buildDockerRunArgs(fullImage, cmd, envFilePath, network, volumeMounts);
+  if (quiet) {
+    return _spawnDockerQuiet(args, dockerEnv);
+  }
+  return _spawnDockerInherit(args, dockerEnv);
+}
+
+/**
+ * @param {string} fullImage
+ * @param {string} cmd
+ * @param {string|null} envFilePath
+ * @param {string|null} network
+ * @param {Array<{ host: string, container: string }>} volumeMounts
+ * @returns {string[]}
+ */
+function _buildDockerRunArgs(fullImage, cmd, envFilePath, network, volumeMounts) {
+  const args = ['run', '--rm'];
+  if (network) {
+    args.push('--network', network);
+  }
+  if (envFilePath) {
+    args.push('--env-file', envFilePath);
+  }
+  for (const mount of volumeMounts) {
+    const host = typeof mount?.host === 'string' ? mount.host.trim() : '';
+    const container = typeof mount?.container === 'string' ? mount.container.trim() : '';
+    if (host && container) {
+      args.push('-v', `${host}:${container}`);
+    }
+  }
+  args.push(fullImage, 'sh', '-c', cmd);
+  return args;
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ProcessEnv} dockerEnv
+ * @returns {Promise<number>}
+ */
+function _spawnDockerInherit(args, dockerEnv) {
+  return new Promise((resolve) => {
+    const proc = spawn('docker', args, {
+      stdio: 'inherit',
+      shell: false,
+      env: dockerEnv
+    });
+    proc.on('close', (code) => resolve(code !== null ? code : 1));
+    proc.on('error', () => resolve(1));
+  });
+}
+
+/**
+ * @param {string[]} args
+ * @param {NodeJS.ProcessEnv} dockerEnv
+ * @returns {Promise<{ code: number, output: string }>}
+ */
+function _spawnDockerQuiet(args, dockerEnv) {
+  return new Promise((resolve) => {
+    const proc = spawn('docker', args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: false,
+      env: dockerEnv
+    });
+    const chunks = [];
+    const push = (buf) => {
+      if (buf && buf.length) {
+        chunks.push(buf);
+      }
+    };
+    proc.stdout.on('data', push);
+    proc.stderr.on('data', push);
+    proc.on('close', (code) => {
+      resolve({
+        code: code !== null ? code : 1,
+        output: Buffer.concat(chunks).toString('utf8')
+      });
+    });
+    proc.on('error', () => resolve({ code: 1, output: '' }));
+  });
+}
+
+module.exports = { runDockerRunEphemeral };

package/lib/utils/enterprise-knowledge-paths.js

@@ -62,8 +62,22 @@ function getEnterpriseKnowledgeRoot() {
   return path.join(getMaterializationParent(), WORKSPACE_ENTERPRISE_KNOWLEDGE);
 }
 
+function isExistingDirectory(disk, dirPath) {
+  try {
+    if (!dirPath || !disk.existsSync(dirPath)) {
+      return false;
+    }
+    const st = disk.statSync(dirPath);
+    return Boolean(st && typeof st.isDirectory === 'function' && st.isDirectory());
+  } catch {
+    return false;
+  }
+}
+
 /**
- * Resolves enterprise-knowledge/<anchorKey> (cwd-first, then materialization parent).
+ * Resolves enterprise-knowledge/<anchorKey>.
+ * Prefer an existing cwd or materialization folder; when `cwd/enterprise-knowledge/` exists and
+ * neither copy exists yet, return the cwd path (download/create target).
  * @param {string} anchorKey - Enterprise Knowledge anchor key
  * @returns {string}
  */
@@ -71,19 +85,22 @@ function getEnterpriseKnowledgePath(anchorKey) {
   if (!anchorKey || typeof anchorKey !== 'string') {
     throw new Error('Anchor key is required and must be a string');
   }
-  const cwdHit = path.join(path.resolve(process.cwd()), WORKSPACE_ENTERPRISE_KNOWLEDGE, anchorKey);
-  try {
-    const disk = nodeFs();
-    if (disk.existsSync(cwdHit)) {
-      const st = disk.statSync(cwdHit);
-      if (st && typeof st.isDirectory === 'function' && st.isDirectory()) {
-        return cwdHit;
-      }
+  const disk = nodeFs();
+  const cwdRoot = getCwdEnterpriseKnowledgeRoot();
+  const matApp = path.join(getMaterializationParent(), WORKSPACE_ENTERPRISE_KNOWLEDGE, anchorKey);
+  if (cwdRoot) {
+    const cwdApp = path.join(cwdRoot, anchorKey);
+    if (isExistingDirectory(disk, cwdApp)) {
+      return cwdApp;
     }
-  } catch {
-    // ignore
   }
-  return path.join(getMaterializationParent(), WORKSPACE_ENTERPRISE_KNOWLEDGE, anchorKey);
+  if (isExistingDirectory(disk, matApp)) {
+    return matApp;
+  }
+  if (cwdRoot) {
+    return path.join(cwdRoot, anchorKey);
+  }
+  return matApp;
 }
 
 function isEnterpriseKnowledgeDirectory(disk, fullPath) {