@aifabrix/builder 2.44.6 → 2.45.0

package/lib/utils/paths.js

@@ -44,13 +44,15 @@ function getConfigDirForPaths() {
 }
 
 /**
- * User-owned `secrets.local.yaml` under {@link getAifabrixHome} (same rule as `aifabrix-home` in
- * `config.yaml`, else `~/.aifabrix`). Keeps `secret set` / merge loaders aligned with declared home.
+ * User-owned `secrets.local.yaml` beside `config.yaml` (same directory as {@link getConfigDirForPaths}).
+ * When `aifabrix-home` is the POSIX home (e.g. `/home/user`), secrets stay under `~/.aifabrix/`, not
+ * in the home root. {@link getAifabrixHome} remains for applications base, builder parent, and
+ * legacy secrets migration reads in {@link module:lib/utils/secrets-utils}.
  *
  * @returns {string} Absolute path to secrets.local.yaml
  */
 function getPrimaryUserSecretsLocalPath() {
-  return path.join(getAifabrixHome(), 'secrets.local.yaml');
+  return path.join(getConfigDirForPaths(), 'secrets.local.yaml');
 }
 
 /**
@@ -315,7 +317,8 @@ function getDevDirectory(appName, developerId) {
 
 /**
  * Gets the application path (builder or integration folder).
- * Matches getBuilderPath / getIntegrationPath: respects AIFABRIX_BUILDER_DIR and project-root vs cwd base.
+ * Matches {@link getBuilderPath} / {@link getIntegrationPath} (cwd `integration/` / `builder/`, then
+ * material `(aifabrix-work | aifabrix-home)` trees).
  * @param {string} appName - Application name
  * @param {string} [appType] - Application type ('external' or other)
  * @returns {string} Absolute path to application directory
@@ -325,65 +328,99 @@ function getAppPath(appName, appType) {
     throw new Error('App name is required and must be a string');
   }
   if (appType === 'external') {
-    return getIntegrationPath(appName);
+    return module.exports.getIntegrationPath(appName);
   }
-  return getBuilderPath(appName);
+  return module.exports.getBuilderPath(appName);
 }
 
 /**
- * Base directory for integration/builder: project root when cwd is inside project, else cwd.
- * When `aifabrix-work` / `AIFABRIX_WORK` points at a repo that contains `integration/`, use that
- * root even if cwd is elsewhere (e.g. global CLI install + cwd under `integration/<app>/`).
- * @returns {string} Directory to resolve integration/ and builder/ from
+ * Apps materialization / default repo root: **`aifabrix-work`** (or `AIFABRIX_WORK`) when set, else
+ * {@link getAifabrixHome}. Used for `integration/` and `builder/` under that parent (not the CLI
+ * install tree). Aligns with setup / `up-platform` / `up-miso` / `up-dataplane` template targets.
+ *
+ * @returns {string} Absolute directory (no trailing `integration/` or `builder/`)
  */
-function getIntegrationBuilderBaseDir() {
+function getAppsMaterializationParent() {
   const work = getAifabrixWork();
   if (work) {
-    const workNorm = path.resolve(work);
-    const integrationUnderWork = path.join(workNorm, 'integration');
-    try {
-      if (nodeFs().existsSync(integrationUnderWork)) {
-        return workNorm;
-      }
-    } catch {
-      // ignore fs errors
-    }
+    return path.resolve(work);
   }
-  const root = getProjectRoot();
-  const cwd = path.resolve(process.cwd());
-  const rootNorm = path.resolve(root);
-  if (cwd === rootNorm || cwd.startsWith(rootNorm + path.sep)) {
-    return rootNorm;
-  }
-  return cwd;
+  return path.resolve(getAifabrixHome());
+}
+
+/**
+ * Base directory for legacy callers that meant “non-cwd app tree”: same as {@link getAppsMaterializationParent}.
+ *
+ * @returns {string}
+ */
+function getIntegrationBuilderBaseDir() {
+  return getAppsMaterializationParent();
 }
 
 /**
- * Returns the integration root directory (used for listing apps).
+ * Returns the default integration root under {@link getAppsMaterializationParent} (listing may also
+ * scan {@link getCwdIntegrationRoot}; see {@link listIntegrationAppNames}).
+ *
  * @returns {string} Absolute path to integration/ directory
  */
 function getIntegrationRoot() {
-  return path.join(getIntegrationBuilderBaseDir(), 'integration');
+  return path.join(getAppsMaterializationParent(), 'integration');
 }
 
 /**
- * Returns the builder root directory. Uses AIFABRIX_BUILDER_DIR when set, else project/cwd + builder.
+ * Absolute `integration/` next to {@link process.cwd} when that directory exists.
+ *
+ * @returns {string|null}
+ */
+function getCwdIntegrationRoot() {
+  const p = path.join(path.resolve(process.cwd()), 'integration');
+  try {
+    if (nodeFs().existsSync(p)) {
+      const st = nodeFs().statSync(p);
+      if (st && typeof st.isDirectory === 'function' && st.isDirectory()) {
+        return p;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+/**
+ * Absolute `builder/` next to {@link process.cwd} when that directory exists.
+ *
+ * @returns {string|null}
+ */
+function getCwdBuilderRoot() {
+  const p = path.join(path.resolve(process.cwd()), 'builder');
+  try {
+    if (nodeFs().existsSync(p)) {
+      const st = nodeFs().statSync(p);
+      if (st && typeof st.isDirectory === 'function' && st.isDirectory()) {
+        return p;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+/**
+ * Returns the material `builder/` root: {@link getAppsMaterializationParent}`/builder`
+ * (same as {@link getSystemBuilderRoot}). Does not use `AIFABRIX_BUILDER_DIR` — app paths follow
+ * cwd + `integration/` / `builder/` or this root only.
+ *
  * @returns {string} Absolute path to builder/ directory
  */
 function getBuilderRoot() {
-  const envDir = process.env.AIFABRIX_BUILDER_DIR && typeof process.env.AIFABRIX_BUILDER_DIR === 'string'
-    ? process.env.AIFABRIX_BUILDER_DIR.trim()
-    : null;
-  if (envDir) {
-    return path.resolve(envDir);
-  }
-  return path.join(getIntegrationBuilderBaseDir(), 'builder');
+  return path.join(getAppsMaterializationParent(), 'builder');
 }
 
 /**
- * Platform system apps: project `builder/<app>` when present; else `builder/<app>` under the
- * resolved system-builder parent (config dir, or `aifabrix-home` when outside config — see
- * {@link getSystemBuilderRoot}).
+ * Platform system apps (`up-platform` / `up-miso` / `up-dataplane` / `setup`): materialize under
+ * {@link getSystemBuilderRoot} (= {@link getAppsMaterializationParent}`/builder`), never the global CLI package tree.
  * @readonly
  */
 const SYSTEM_BUILDER_APP_KEYS = Object.freeze(['keycloak', 'miso-controller', 'dataplane']);
@@ -398,7 +435,8 @@ function isSystemBuilderAppName(appName) {
 }
 
 /**
- * Project/cwd `builder/<appName>` (no existence check).
+ * `builder/<appName>` under {@link getAppsMaterializationParent} (same tree as {@link getSystemBuilderRoot}).
+ *
  * @param {string} appName
  * @returns {string}
  */
@@ -407,20 +445,30 @@ function getProjectBuilderAppPath(appName) {
 }
 
 /**
- * Directory containing default materialization for platform apps: `<parent>/builder/<app>`.
- * Parent is {@link getAifabrixSystemDir} when that path lies under {@link getAifabrixHome};
- * otherwise {@link getAifabrixHome} (honours `aifabrix-home` / `AIFABRIX_HOME` vs config location).
+ * Same parent as {@link getAppsMaterializationParent} (exported for diagnostics / allowlist checks).
+ *
+ * @returns {string} Absolute path (no trailing `builder/`)
+ */
+function getSystemPlatformMaterializationParent() {
+  return getAppsMaterializationParent();
+}
+
+/**
+ * Default `builder/` root for materialized platform apps and Tier‑2 manifest discovery:
+ * {@link getAppsMaterializationParent}`/builder`.
  *
  * @returns {string}
  */
 function getSystemBuilderRoot() {
-  return path.join(
-    resolveSystemBuilderParentDir(getAifabrixSystemDir(), getAifabrixHome()),
-    'builder'
-  );
+  return path.join(getAppsMaterializationParent(), 'builder');
 }
 
 /**
+ * True when `projectAppPath` is a directory that contains a resolvable application config
+ * (`application.yaml` / `.json` / legacy `variables.yaml`). Empty `builder/<platformApp>`
+ * stubs must not win over {@link getSystemBuilderRoot} or secrets/run would read the wrong tree
+ * (missing `env.template` → skipped ensure → "Missing secrets" on first platform boot).
+ *
  * @param {string} projectAppPath - Absolute `.../builder/<app>`
  * @returns {boolean}
  */
@@ -428,7 +476,10 @@ function isProjectBuilderAppDirectory(projectAppPath) {
   try {
     if (!projectAppPath || !nodeFs().existsSync(projectAppPath)) return false;
     const st = nodeFs().statSync(projectAppPath);
-    return Boolean(st && typeof st.isDirectory === 'function' && st.isDirectory());
+    if (!st || typeof st.isDirectory !== 'function' || !st.isDirectory()) return false;
+    const { resolveApplicationConfigPath } = require('./app-config-resolver');
+    resolveApplicationConfigPath(projectAppPath);
+    return true;
   } catch {
     return false;
   }
@@ -458,21 +509,14 @@ function isAppSubdirSync(root, name) {
  */
 function listIntegrationAppNames() {
   const disk = nodeFs();
-  const root = getIntegrationRoot();
-  if (!disk.existsSync(root)) {
-    return [];
-  }
-  let rootStat;
-  try {
-    rootStat = disk.statSync(root);
-  } catch {
-    return [];
-  }
-  if (!rootStat || typeof rootStat.isDirectory !== 'function' || !rootStat.isDirectory()) {
-    return [];
+  const names = new Set();
+  const cwdRoot = getCwdIntegrationRoot();
+  if (cwdRoot) {
+    addBuilderSubdirNamesToSet(disk, cwdRoot, names, null);
   }
-  const entries = disk.readdirSync(root);
-  return entries.filter((name) => isAppSubdirSync(root, name)).sort();
+  const matInt = getIntegrationRoot();
+  addBuilderSubdirNamesToSet(disk, matInt, names, null);
+  return [...names].sort();
 }
 
 /**
@@ -503,21 +547,29 @@ function addBuilderSubdirNamesToSet(disk, builderRootDir, names, nameFilter) {
 }
 
 /**
- * Lists app names (directories) under builder root. Excludes dot-prefixed entries.
- * Merges project `builder/` with system builder root (platform keys only under the latter).
+ * Lists app names (directories) under builder roots. Excludes dot-prefixed entries.
+ * Merges `cwd/builder` and material `(aifabrix-work | aifabrix-home)/builder` (deduped).
  * @returns {string[]} Sorted list of app directory names
  */
 function listBuilderAppNames() {
   const disk = nodeFs();
   const names = new Set();
-  const projectBuilder = path.join(getIntegrationBuilderBaseDir(), 'builder');
-  addBuilderSubdirNamesToSet(disk, projectBuilder, names, null);
-  addBuilderSubdirNamesToSet(disk, getSystemBuilderRoot(), names, isSystemBuilderAppName);
+  const roots = new Set();
+  const cwdRoot = getCwdBuilderRoot();
+  if (cwdRoot) {
+    roots.add(path.resolve(cwdRoot));
+  }
+  roots.add(path.resolve(getSystemBuilderRoot()));
+  for (const r of roots) {
+    addBuilderSubdirNamesToSet(disk, r, names, null);
+  }
   return [...names].sort();
 }
 
 /**
- * Gets the integration folder path for external systems.
+ * Gets the integration folder path: **`cwd/integration/<appName>`** when that directory exists, else
+ * **`aifabrix-work` or `aifabrix-home` + `/integration/<appName>`**.
+ *
  * @param {string} appName - Application name
  * @returns {string} Absolute path to integration directory
  */
@@ -525,8 +577,18 @@ function getIntegrationPath(appName) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
-  const base = getIntegrationBuilderBaseDir();
-  return path.join(base, 'integration', appName);
+  const cwdInt = path.join(path.resolve(process.cwd()), 'integration', appName);
+  try {
+    if (nodeFs().existsSync(cwdInt)) {
+      const st = nodeFs().statSync(cwdInt);
+      if (st && typeof st.isDirectory === 'function' && st.isDirectory()) {
+        return cwdInt;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return path.join(getAppsMaterializationParent(), 'integration', appName);
 }
 
 /**
@@ -544,7 +606,39 @@ function resolveBuildContext(configDir, buildContext) {
 }
 
 /**
- * Gets the builder folder path. Uses AIFABRIX_BUILDER_DIR when set, else project root.
+ * `cwd/builder/<appName>` when present as a directory and allowed (platform empty stubs skipped).
+ *
+ * @param {string} appName
+ * @returns {string|null}
+ */
+function tryCwdBuilderPathOrNull(appName) {
+  const cwdApp = path.join(path.resolve(process.cwd()), 'builder', appName);
+  try {
+    if (!nodeFs().existsSync(cwdApp)) {
+      return null;
+    }
+    const st = nodeFs().statSync(cwdApp);
+    if (!st || typeof st.isDirectory !== 'function' || !st.isDirectory()) {
+      return null;
+    }
+    if (isSystemBuilderAppName(appName) && !isProjectBuilderAppDirectory(cwdApp)) {
+      return null;
+    }
+    return cwdApp;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Gets the builder folder path:
+ * 1. Plan 141 Tier‑1: `cwd/builder/<app>` or `cwd/integration/<app>` when a resolvable application manifest exists.
+ * 2. Else **`cwd/builder/<app>`** when that directory exists. For **platform** apps (`keycloak`,
+ *    `miso-controller`, `dataplane`), an **empty** cwd stub is ignored so materialization under
+ *    `(work|home)/builder` still wins.
+ * 3. Else **`(aifabrix-work or aifabrix-home)/builder/<appName>`** — used by setup / `up-platform` /
+ *    `up-miso` / `up-dataplane` for template materialization.
+ *
  * @param {string} appName - Application name
  * @returns {string} Absolute path to builder directory
  */
@@ -552,21 +646,20 @@ function getBuilderPath(appName) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
-  const envBuilderRoot = process.env.AIFABRIX_BUILDER_DIR && typeof process.env.AIFABRIX_BUILDER_DIR === 'string'
-    ? process.env.AIFABRIX_BUILDER_DIR.trim()
-    : null;
-  if (envBuilderRoot) {
-    return path.join(path.resolve(envBuilderRoot), appName);
+  const { resolveApplicationManifestPathSync } = require('./manifest-location');
+  const manifestHit = resolveApplicationManifestPathSync({
+    targetKey: appName,
+    mode: 'auto',
+    cwd: process.cwd()
+  });
+  if (manifestHit && (manifestHit.tier === 'cwd-builder' || manifestHit.tier === 'cwd-integration')) {
+    return manifestHit.absolutePath;
   }
-  if (isSystemBuilderAppName(appName)) {
-    const projectAppPath = getProjectBuilderAppPath(appName);
-    if (isProjectBuilderAppDirectory(projectAppPath)) {
-      return projectAppPath;
-    }
-    return path.join(getSystemBuilderRoot(), appName);
+  const cwdHit = tryCwdBuilderPathOrNull(appName);
+  if (cwdHit) {
+    return cwdHit;
   }
-  const base = getIntegrationBuilderBaseDir();
-  return path.join(base, 'builder', appName);
+  return path.join(getAppsMaterializationParent(), 'builder', appName);
 }
 
 /**
@@ -717,16 +810,66 @@ async function getResolveAppPath(appName) {
       return { appPath: integrationPath, envOnly: true };
     }
   }
+  const { resolveApplicationManifestPathSync } = require('./manifest-location');
+  const manifestHit = resolveApplicationManifestPathSync({
+    targetKey: appName,
+    mode: 'auto',
+    cwd: process.cwd()
+  });
+  if (manifestHit) {
+    return { appPath: manifestHit.absolutePath, envOnly: false };
+  }
   const result = await detectAppType(appName);
   return { appPath: result.appPath, envOnly: false };
 }
 
-/** Resolve app folder name when cwd is inside integration/<systemKey>/. */
+/**
+ * @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');
+  try {
+    if (!disk.existsSync(integrationDir)) {
+      return null;
+    }
+    const intNorm = path.resolve(integrationDir);
+    if (cwd !== intNorm && !cwd.startsWith(intNorm + path.sep)) {
+      return null;
+    }
+    const rel = path.relative(intNorm, cwd);
+    if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) {
+      return null;
+    }
+    return rel.split(path.sep)[0] || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve app folder name when cwd is under some ancestor's `integration/<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.
+ */
 function resolveIntegrationAppKeyFromCwd() {
-  const integrationNorm = path.resolve(path.join(getIntegrationBuilderBaseDir(), 'integration'));
   const cwd = path.resolve(process.cwd());
-  if (cwd !== integrationNorm && !cwd.startsWith(integrationNorm + path.sep)) return null;
-  return path.relative(integrationNorm, cwd).split(path.sep)[0] || null;
+  const disk = nodeFs();
+  let p = cwd;
+  for (let i = 0; i < 64; i += 1) {
+    const key = tryIntegrationAppKeyAtWalkStep(p, cwd, disk);
+    if (key) {
+      return key;
+    }
+    const parent = path.dirname(p);
+    if (parent === p) {
+      break;
+    }
+    p = parent;
+  }
+  return null;
 }
 
 module.exports = {
@@ -738,14 +881,20 @@ module.exports = {
   getApplicationsBaseDir,
   getDevDirectory,
   getAppPath,
+  getAppsMaterializationParent,
+  getCwdIntegrationRoot,
+  getCwdBuilderRoot,
   getProjectRoot,
+  findProjectRootFromCwd,
   getIntegrationPath,
   getBuilderPath,
   getIntegrationRoot,
   getBuilderRoot,
+  getIntegrationBuilderBaseDir,
   SYSTEM_BUILDER_APP_KEYS,
   isSystemBuilderAppName,
   getProjectBuilderAppPath,
+  getSystemPlatformMaterializationParent,
   getSystemBuilderRoot,
   resolveSystemBuilderParentDir,
   listIntegrationAppNames,

package/lib/utils/remote-secrets-loader.js

@@ -54,14 +54,20 @@ async function loadRemoteSharedSecrets() {
  * Merges remote shared secrets with user secrets. User wins on same key.
  * @param {Object} userSecrets - User secrets object
  * @param {Object} remoteSecrets - Remote API secrets (key-value)
+ * @param {Record<string, string>} [keySources] - Mutated: winning file/API label per key (decrypt hints)
+ * @param {string} [remoteSourceLabel] - Human-readable source for keys taken from remote
  * @returns {Object} Merged object
  */
-function mergeUserWithRemoteSecrets(userSecrets, remoteSecrets) {
+function mergeUserWithRemoteSecrets(userSecrets, remoteSecrets, keySources, remoteSourceLabel) {
   const merged = { ...userSecrets };
   if (!remoteSecrets || typeof remoteSecrets !== 'object') return merged;
+  const label = remoteSourceLabel || 'shared secrets API';
   for (const key of Object.keys(remoteSecrets)) {
     if (!(key in merged) || merged[key] === undefined || merged[key] === null || merged[key] === '') {
       merged[key] = remoteSecrets[key];
+      if (keySources) {
+        keySources[key] = label;
+      }
     }
   }
   return merged;

package/lib/utils/run-cli-flags.js

@@ -0,0 +1,29 @@
+/**
+ * Normalize Commander flags for `aifabrix run`.
+ *
+ * @fileoverview Commander v11 pairs `--no-proxy` with a default-true `--proxy` flag as `options.proxy === false`.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * True when the user disabled proxy hints: explicit `--no-proxy` or `proxy === false` when supported.
+ *
+ * @param {Object} [options] - Commander action options
+ * @returns {boolean}
+ */
+function isRunCliNoProxy(options) {
+  if (!options || typeof options !== 'object') {
+    return false;
+  }
+  if (options.proxy === false) {
+    return true;
+  }
+  return options.noProxy === true;
+}
+
+module.exports = {
+  isRunCliNoProxy
+};

package/lib/utils/secrets-canonical.js

@@ -31,11 +31,14 @@ function readYamlAtPath(filePath) {
  * @param {string} key - Secret key
  * @param {*} canonicalValue - Value from canonical secrets
  */
-function mergeSecretValue(result, key, canonicalValue) {
+function mergeSecretValue(result, key, canonicalValue, keySources, canonicalSourcePath) {
   const currentValue = result[key];
   // Fill missing, empty, or undefined values
   if (!(key in result) || currentValue === undefined || currentValue === null || currentValue === '') {
     result[key] = canonicalValue;
+    if (keySources && canonicalSourcePath) {
+      keySources[key] = canonicalSourcePath;
+    }
     return;
   }
   // Only replace values that are encrypted (have secure:// prefix)
@@ -43,6 +46,9 @@ function mergeSecretValue(result, key, canonicalValue) {
   if (typeof currentValue === 'string' && typeof canonicalValue === 'string') {
     if (currentValue.startsWith('secure://')) {
       result[key] = canonicalValue;
+      if (keySources && canonicalSourcePath) {
+        keySources[key] = canonicalSourcePath;
+      }
     }
   }
 }
@@ -52,9 +58,10 @@ function mergeSecretValue(result, key, canonicalValue) {
  * @async
  * @function applyCanonicalSecretsOverride
  * @param {Object} currentSecrets - Current secrets map
+ * @param {Record<string, string>} [keySources] - Mutated: per-key source path when a value is taken from canonical YAML
  * @returns {Promise<Object>} Possibly overridden secrets
  */
-async function applyCanonicalSecretsOverride(currentSecrets) {
+async function applyCanonicalSecretsOverride(currentSecrets, keySources) {
   let mergedSecrets = currentSecrets || {};
   try {
     const canonicalPath = await config.getSecretsPath();
@@ -78,7 +85,7 @@ async function applyCanonicalSecretsOverride(currentSecrets) {
     // - Replace encrypted values (secure://) with canonical plaintext
     const result = { ...mergedSecrets };
     for (const [key, canonicalValue] of Object.entries(configSecrets)) {
-      mergeSecretValue(result, key, canonicalValue);
+      mergeSecretValue(result, key, canonicalValue, keySources, resolvedCanonical);
     }
     mergedSecrets = result;
   } catch {

package/lib/utils/secrets-path.js

@@ -41,9 +41,8 @@ function resolveSecretsPath(secretsPath) {
 }
 
 /**
- * Determines the actual secrets file paths that loadSecrets would use
- * Mirrors the cascading lookup logic from loadSecrets
- * Uses config.yaml for default secrets path as fallback
+ * Determines paths used for default `loadSecrets()` (no explicit path): primary user secrets file
+ * and configured `aifabrix-secrets` (shared YAML file path or remote API URL).
  *
  * @async
  * @function getActualSecretsPath
@@ -65,7 +64,7 @@ async function getActualSecretsPath(secretsPath, _appName) {
     };
   }
 
-  // Cascading lookup: user's file first (same path as `secret set`: getPrimaryUserSecretsLocalPath)
+  // Default lookup: primary user file plus aifabrix-secrets (file or https URL)
   const userSecretsPath = paths.getPrimaryUserSecretsLocalPath();
 
   let buildSecretsPath = null;

package/lib/utils/secrets-utils.js

@@ -58,18 +58,14 @@ async function loadSecretsFromFile(filePath) {
 }
 
 /**
- * Loads user secrets from getPrimaryUserSecretsLocalPath() (under {@link module:lib/utils/paths.getAifabrixHome}).
- * Used as the master source when merging with project/public secrets: user values win,
- * missing keys are filled from the public (aifabrix-secrets) file.
+ * Loads user secrets from {@link pathsUtil.getPrimaryUserSecretsLocalPath} (beside `config.yaml`).
+ * If that file is missing, reads a legacy file at `getAifabrixHome()/secrets.local.yaml` when paths
+ * differ (older CLI when `aifabrix-home` was POSIX home).
  *
  * @function loadPrimaryUserSecrets
  * @returns {Object} Loaded secrets object or empty object
  */
-function loadPrimaryUserSecrets() {
-  const userSecretsPath = pathsUtil.getPrimaryUserSecretsLocalPath();
-  if (!fs.existsSync(userSecretsPath)) {
-    return {};
-  }
+function readPrimaryUserSecretsAtPath(userSecretsPath) {
   ensureSecureFilePermissions(userSecretsPath);
 
   try {
@@ -84,8 +80,22 @@ function loadPrimaryUserSecrets() {
       throw error;
     }
     logger.warn(`Warning: Could not read secrets file ${userSecretsPath}: ${error.message}`);
-    return {};
+    return null;
+  }
+}
+
+function loadPrimaryUserSecrets() {
+  const primaryPath = pathsUtil.getPrimaryUserSecretsLocalPath();
+  if (fs.existsSync(primaryPath)) {
+    const fromPrimary = readPrimaryUserSecretsAtPath(primaryPath);
+    return fromPrimary !== null ? fromPrimary : {};
+  }
+  const legacyPath = path.join(pathsUtil.getAifabrixHome(), 'secrets.local.yaml');
+  if (path.resolve(legacyPath) !== path.resolve(primaryPath) && fs.existsSync(legacyPath)) {
+    const fromLegacy = readPrimaryUserSecretsAtPath(legacyPath);
+    return fromLegacy !== null ? fromLegacy : {};
   }
+  return {};
 }
 
 /**
@@ -128,7 +138,7 @@ function loadDefaultSecrets() {
 
 /**
  * Creates the primary user secrets file if missing (empty map) for first-run installs.
- * Uses the same directory as {@link loadPrimaryUserSecrets} (resolved AI Fabrix home).
+ * Uses the same directory as {@link loadPrimaryUserSecrets} (beside `config.yaml`).
  *
  * @function ensurePrimaryUserSecretsFileExists
  */