@aifabrix/builder 2.50.0 → 2.51.1

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

@@ -0,0 +1,98 @@
+/**
+ * Role Assistant workspace path helpers.
+ *
+ * @fileoverview Paths under role-assistant/ for Role Assistant packages
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const os = require('os');
+const { nodeFs } = require('../internal/node-fs');
+
+const WORKSPACE_ROLE_ASSISTANT = 'role-assistant';
+const SYSTEM_KIND_DIGITAL_WORKER = 'digitalWorker';
+
+function getMaterializationParent() {
+  const work = process.env.AIFABRIX_WORK;
+  if (work && typeof work === 'string' && work.trim()) {
+    return path.resolve(work.trim());
+  }
+  if (process.env.AIFABRIX_HOME && typeof process.env.AIFABRIX_HOME === 'string') {
+    return path.resolve(process.env.AIFABRIX_HOME.trim());
+  }
+  return path.join(os.homedir(), '.aifabrix');
+}
+
+function getCwdRoleAssistantRoot() {
+  const p = path.join(path.resolve(process.cwd()), WORKSPACE_ROLE_ASSISTANT);
+  try {
+    const disk = nodeFs();
+    if (disk.existsSync(p)) {
+      const st = disk.statSync(p);
+      if (st && typeof st.isDirectory === 'function' && st.isDirectory()) {
+        return p;
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return null;
+}
+
+function getRoleAssistantRoot() {
+  const cwdRoot = getCwdRoleAssistantRoot();
+  if (cwdRoot) {
+    return cwdRoot;
+  }
+  return path.join(getMaterializationParent(), WORKSPACE_ROLE_ASSISTANT);
+}
+
+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 role-assistant/<roleKey> with cwd-first behavior.
+ * @param {string} roleKey
+ * @returns {string}
+ */
+function getRoleAssistantPath(roleKey) {
+  if (!roleKey || typeof roleKey !== 'string') {
+    throw new Error('Role key is required and must be a string');
+  }
+  const disk = nodeFs();
+  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;
+  }
+  if (cwdRoot) {
+    return path.join(cwdRoot, roleKey);
+  }
+  return matPath;
+}
+
+module.exports = {
+  WORKSPACE_ROLE_ASSISTANT,
+  SYSTEM_KIND_DIGITAL_WORKER,
+  getCwdRoleAssistantRoot,
+  getRoleAssistantRoot,
+  getRoleAssistantPath
+};

package/lib/utils/schema-loader.js

@@ -18,6 +18,7 @@ const addFormats = require('ajv-formats');
 // These are reset when module is reloaded (for testing)
 let externalSystemValidator = null;
 let externalDataSourceValidator = null;
+let roleAssistantSettingsValidator = null;
 
 /**
  * Reset validators cache (for testing)
@@ -26,6 +27,7 @@ let externalDataSourceValidator = null;
 function resetValidators() {
   externalSystemValidator = null;
   externalDataSourceValidator = null;
+  roleAssistantSettingsValidator = null;
 }
 
 /**
@@ -138,6 +140,38 @@ function loadExternalDataSourceSchema() {
   return externalDataSourceValidator;
 }
 
+/**
+ * Loads and compiles role-assistant settings schema.
+ * @function loadRoleAssistantSettingsSchema
+ * @returns {Function}
+ */
+function loadRoleAssistantSettingsSchema() {
+  if (roleAssistantSettingsValidator) {
+    return roleAssistantSettingsValidator;
+  }
+
+  const schemaPath = path.join(__dirname, '..', 'schema', 'role-assistant-settings.schema.json');
+  let schema;
+  try {
+    const schemaContent = fsRealSync.readFileSync(schemaPath, 'utf8');
+    schema = JSON.parse(schemaContent);
+  } catch (error) {
+    try {
+      schema = require('../schema/role-assistant-settings.schema.json');
+    } catch {
+      if (error && error.code === 'ENOENT') {
+        throw new Error(`Role assistant settings schema not found: ${schemaPath}`);
+      }
+      throw new Error(`Invalid JSON in role-assistant-settings.schema.json: ${error.message}`);
+    }
+  }
+
+  const ajv = new Ajv({ allErrors: true, strict: false, strictSchema: false });
+  addFormats(ajv);
+  roleAssistantSettingsValidator = ajv.compile(schema);
+  return roleAssistantSettingsValidator;
+}
+
 /**
  * Detect schema type from $id field
  * @param {Object} parsed - Parsed JSON object
@@ -157,6 +191,9 @@ function detectFromId(parsed) {
   if (parsed.$id.includes('application-schema')) {
     return 'application';
   }
+  if (parsed.$id.includes('role-assistant-settings')) {
+    return 'role-assistant-settings';
+  }
 
   return null;
 }
@@ -239,6 +276,9 @@ function detectFromApplicationFields(parsed) {
  */
 function detectFromFilename(filePath) {
   const fileName = path.basename(filePath).toLowerCase();
+  if (fileName === 'role-assistant.yaml' || fileName === 'role-assistant.yml') {
+    return 'role-assistant-settings';
+  }
   if (fileName.includes('external-system') || fileName.includes('external_system')) {
     return 'external-system';
   }
@@ -347,6 +387,7 @@ function detectSchemaType(filePath, content) {
 module.exports = {
   loadExternalSystemSchema,
   loadExternalDataSourceSchema,
+  loadRoleAssistantSettingsSchema,
   registerExternalDatasourceAjvDependencies,
   detectSchemaType,
   detectSchemaTypeFromParsed,

package/lib/utils/schema-resolver.js

@@ -175,6 +175,18 @@ function resolveDatasourceFiles(schemaBasePath, datasourceFiles) {
   return datasourceFiles.map(fileName => resolveSingleExternalFile(schemaBasePath, fileName, 'datasource'));
 }
 
+function resolveRoleAssistantSettingsFile(appPath) {
+  const yamlPath = path.join(appPath, 'role-assistant.yaml');
+  if (fs.existsSync(yamlPath)) {
+    return resolveSingleExternalFile(appPath, 'role-assistant.yaml', 'role-assistant-settings');
+  }
+  const ymlPath = path.join(appPath, 'role-assistant.yml');
+  if (fs.existsSync(ymlPath)) {
+    return resolveSingleExternalFile(appPath, 'role-assistant.yml', 'role-assistant-settings');
+  }
+  return resolveSingleExternalFile(appPath, 'role-assistant.yaml', 'role-assistant-settings');
+}
+
 /**
  * @param {string} schemaBasePath
  * @param {string[]} systemFileNames
@@ -282,6 +294,21 @@ async function loadAndValidateVariables(appPath) {
   }
 }
 
+function readSystemKindFromFirstSystemFile(schemaBasePath, systemFileNames) {
+  if (!systemFileNames.length) {
+    return '';
+  }
+  try {
+    const firstSystemPath = path.join(schemaBasePath, systemFileNames[0]);
+    const parsedSystem = loadConfigFile(firstSystemPath);
+    return parsedSystem && typeof parsedSystem.systemKind === 'string'
+      ? parsedSystem.systemKind
+      : '';
+  } catch {
+    return '';
+  }
+}
+
 async function resolveExternalFiles(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
@@ -295,15 +322,20 @@ async function resolveExternalFiles(appName, options = {}) {
   }
 
   const schemaBasePath = await resolveSchemaBasePath(appName, options);
-  const systemFiles = resolveSystemFiles(schemaBasePath, variables.externalIntegration.systems);
+  const systemFileNames = variables.externalIntegration.systems || [];
+  const systemFiles = resolveSystemFiles(schemaBasePath, systemFileNames);
+  const systemKind = readSystemKindFromFirstSystemFile(schemaBasePath, systemFileNames);
   const orderedNames = orderDatasourceFileNamesBySystemKeys(
     schemaBasePath,
-    variables.externalIntegration.systems,
+    systemFileNames,
     variables.externalIntegration.dataSources || []
   );
   const datasourceFiles = resolveDatasourceFiles(schemaBasePath, orderedNames);
-
-  return [...systemFiles, ...datasourceFiles];
+  const extraFiles = [];
+  if (String(systemKind).trim() === 'digitalWorker') {
+    extraFiles.push(resolveRoleAssistantSettingsFile(appPath));
+  }
+  return [...systemFiles, ...datasourceFiles, ...extraFiles];
 }
 
 module.exports = {

package/lib/utils/token-manager.js

@@ -408,37 +408,62 @@ function applyLabDataplaneApiKeyBearer(authConfig) {
   return authConfig;
 }
 
+function looksLikeJwtBearer(token) {
+  const existing = token ? String(token) : '';
+  return existing.split('.').length === 3 && existing.length > 80;
+}
+
+function preferClientCredentialsDeploymentAuth() {
+  return String(process.env.AIFABRIX_DEPLOYMENT_AUTH || '').toLowerCase() === 'client-credentials';
+}
+
+/**
+ * @param {Object} authConfig
+ * @returns {boolean} true when a substitution was applied
+ */
+function trySubstituteEnvApiKeyBearer(authConfig) {
+  if (!process.env.API_KEY) {
+    return false;
+  }
+  const apiKey = String(process.env.API_KEY);
+  if (authConfig.type === 'bearer' && authConfig.token !== apiKey) {
+    authConfig.token = apiKey;
+    return true;
+  }
+  if (authConfig.type === 'client-token') {
+    authConfig.type = 'bearer';
+    authConfig.token = apiKey;
+    return true;
+  }
+  if (!authConfig.token) {
+    authConfig.type = 'bearer';
+    authConfig.token = apiKey;
+    return true;
+  }
+  return false;
+}
+
 function requireBearerForDataplanePipeline(authConfig) {
+  if (!authConfig || typeof authConfig !== 'object') {
+    return;
+  }
   if (authConfig.type === 'client-token' && authConfig.token) {
     return;
   }
-
-  const preferAppClientToken =
-    String(process.env.AIFABRIX_DEPLOYMENT_AUTH || '').toLowerCase() === 'client-credentials';
-
-  if (!preferAppClientToken && process.env.API_KEY) {
-    const apiKey = String(process.env.API_KEY);
-    if (authConfig.type === 'bearer' && authConfig.token !== apiKey) {
-      authConfig.token = apiKey;
-      return;
-    }
-    if (authConfig.type === 'client-token') {
-      authConfig.type = 'bearer';
-      authConfig.token = apiKey;
-      return;
-    }
+  // Token-forward (builder-api / bearerForward): never substitute lab API_KEY for the caller JWT.
+  if (authConfig.preserveBearer && authConfig.token) {
+    return;
   }
-
-  if (authConfig.token) {
+  // Enterprise path: keep a real OAuth JWT; do not overwrite with process.env.API_KEY.
+  if (looksLikeJwtBearer(authConfig.token)) {
     return;
   }
-
-  if (!preferAppClientToken && process.env.API_KEY) {
-    authConfig.type = 'bearer';
-    authConfig.token = String(process.env.API_KEY);
+  if (!preferClientCredentialsDeploymentAuth() && trySubstituteEnvApiKeyBearer(authConfig)) {
+    return;
+  }
+  if (authConfig.token) {
     return;
   }
-
   if (authConfig.clientId || authConfig.clientSecret) {
     throw new Error(
       'Dataplane pipeline endpoints require OAuth2 (Bearer token) or x-client-token. ' +

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

@@ -10,9 +10,10 @@
 
 /**
  * @param {Object} [options] - CLI options from test / sync callers
- * @returns {{ minimal: true, verbose: boolean, silentResolve: true, syncMode: true, force?: true }}
+ * @returns {{ minimal: true, verbose: boolean, silentResolve: true, syncMode: true, force?: true, authConfig?: Object, dataplaneUrl?: string, environment?: string }}
  */
 function buildMinimalUploadSyncOptions(options = {}) {
+  const deployPreflight = options.uploadContext === 'deploy-preflight';
   const out = {
     minimal: true,
     // CLI -v on verify-* / test-* is for run output, not preflight upload banners.
@@ -20,14 +21,27 @@ function buildMinimalUploadSyncOptions(options = {}) {
     silentResolve: true,
     syncMode: true,
     skipDataSync: true,
-    suppressPipelineSpinner: options.suppressPipelineSpinner === true
+    suppressPipelineSpinner:
+      options.suppressPipelineSpinner === true || deployPreflight === true
   };
   if (options.force === true) {
     out.force = true;
   }
-  if (options.suppressSummary === true) {
+  if (options.suppressSummary === true || deployPreflight === true) {
     out.suppressSummary = true;
   }
+  if (deployPreflight) {
+    out.uploadContext = 'deploy-preflight';
+  }
+  // Builder-api / programmatic callers: keep request Bearer — do not fall back to
+  // getDeploymentAuth against a stale mount AIFABRIX_CONFIG device token.
+  if (options.authConfig && options.dataplaneUrl) {
+    out.authConfig = options.authConfig;
+    out.dataplaneUrl = options.dataplaneUrl;
+    if (options.environment) {
+      out.environment = options.environment;
+    }
+  }
   return out;
 }
 

package/lib/utils/url-declarative-resolve-load-doc.js

@@ -25,6 +25,42 @@ function tryReadApplicationYamlAt(cfgPath) {
   }
 }
 
+/**
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isPositivePortValue(value) {
+  if (typeof value === 'number' && value > 0) {
+    return true;
+  }
+  return typeof value === 'string' && /^\d+$/.test(String(value).trim());
+}
+
+/**
+ * True when a manifest can authoritatively supply listen/port for url:// expansion.
+ * External-system `application.json` (upload payload) has no HTTP listen port — using it
+ * for `url://builder-api-internal` falls through to {@link DECLARATIVE_URL_INFRA_DEFAULTS}
+ * (3000) and breaks Docker CIP against the real builder-api container (3005).
+ *
+ * @param {object|null|undefined} doc
+ * @returns {boolean}
+ */
+function isDeclarativeUrlPortAuthorityDoc(doc) {
+  if (!doc || typeof doc !== 'object') {
+    return false;
+  }
+  if ((doc.app && doc.app.type) === 'external') {
+    return false;
+  }
+  if (doc.externalIntegration && typeof doc.externalIntegration === 'object') {
+    return false;
+  }
+  return (
+    isPositivePortValue(doc.port) ||
+    isPositivePortValue(doc.build && doc.build.containerPort)
+  );
+}
+
 /**
  * Candidate paths for cross-app url:// resolution (low → high priority).
  * Platform system apps prefer materialized `~/.aifabrix-work|home/builder` over CLI package `builder/` stubs.
@@ -83,7 +119,7 @@ function loadApplicationYamlDocForUrlResolve(appKey, ctx, pathsUtil) {
     if (appKey === current && ctx.variablesPath) {
       const vp = path.resolve(String(ctx.variablesPath));
       const fromVars = tryReadApplicationYamlAt(vp);
-      if (fromVars) {
+      if (isDeclarativeUrlPortAuthorityDoc(fromVars)) {
         return fromVars;
       }
     }
@@ -105,5 +141,6 @@ function loadApplicationYamlDocForUrlResolve(appKey, ctx, pathsUtil) {
 
 module.exports = {
   collectApplicationYamlPathsForUrlResolve,
+  isDeclarativeUrlPortAuthorityDoc,
   loadApplicationYamlDocForUrlResolve
 };

package/lib/validation/external-manifest-validator.js

@@ -217,6 +217,36 @@ function validateDatasourceSystemKeyAlignment(manifest, errors) {
   });
 }
 
+/**
+ * Vendor OpenAPI contract surface is for Connected Systems. Role Assistants
+ * (digitalWorker) promote settings + Evidence — skip blocking OpenAPI vendor checks.
+ * @param {Object} manifest
+ * @param {Object} options
+ * @param {string[]} errors
+ * @param {string[]} warnings
+ */
+function applyExternalContractSurfaceChecks(manifest, options, errors, warnings) {
+  if (manifest.type !== 'external' || !Array.isArray(manifest.dataSources) || !manifest.system?.key) {
+    return;
+  }
+  const appPath = options.appPath;
+  if (typeof appPath !== 'string' || !appPath) {
+    return;
+  }
+  const systemKind =
+    typeof manifest.system.systemKind === 'string' ? manifest.system.systemKind.trim() : '';
+  if (systemKind === 'digitalWorker') {
+    warnings.push(
+      'Role Assistant (digitalWorker): vendor OpenAPI contract checks skipped ' +
+        '(settings + evidence path; run repair --api only when binding vendor OpenAPI).'
+    );
+    return;
+  }
+  const contract = validateAppContractSurface(appPath, manifest.system.key, manifest.dataSources);
+  errors.push(...contract.errors);
+  warnings.push(...contract.warnings);
+}
+
 /**
  * Validates controller deployment manifest for external systems
  * Validates manifest structure and inline system/dataSources against their schemas
@@ -251,14 +281,7 @@ async function validateControllerManifest(manifest, options = {}) {
   validateDatasources(manifest, ajv, externalDatasourceSchema, errors, warnings);
   validateDatasourceSystemKeyAlignment(manifest, errors);
   errors.push(...validateManifestRuntimeConfiguration(manifest));
-  if (manifest.type === 'external' && Array.isArray(manifest.dataSources) && manifest.system?.key) {
-    const appPath = options.appPath;
-    if (typeof appPath === 'string' && appPath) {
-      const contract = validateAppContractSurface(appPath, manifest.system.key, manifest.dataSources);
-      errors.push(...contract.errors);
-      warnings.push(...contract.warnings);
-    }
-  }
+  applyExternalContractSurfaceChecks(manifest, options, errors, warnings);
   validateConditionalRequirements(manifest, errors, warnings);
   validateRequiredFields(manifest, errors);
 

package/lib/validation/openapi-contract-surface-validator.js

@@ -307,6 +307,10 @@ function resolveCachedVendorSpec(documentKey, prefix, appPath, systemKey, vendor
 function validateServiceContractVendorOpenApi(ds, prefix, appPath, systemKey, vendorCache) {
   const errors = [];
   const warnings = [];
+  // Python/CIP handlers without a vendor OpenAPI binding are valid serviceContracts.
+  if (!hasVendorOpenapiOnManifest(ds)) {
+    return { errors, warnings };
+  }
   const documentKey =
     typeof ds.openapi?.documentKey === 'string' ? ds.openapi.documentKey.trim() : '';
   if (!documentKey) {

package/lib/validation/validate-external-file.js

@@ -10,7 +10,11 @@
 
 const fs = require('fs');
 const yaml = require('js-yaml');
-const { loadExternalSystemSchema, loadExternalDataSourceSchema } = require('../utils/schema-loader');
+const {
+  loadExternalSystemSchema,
+  loadExternalDataSourceSchema,
+  loadRoleAssistantSettingsSchema
+} = require('../utils/schema-loader');
 const { formatValidationErrors } = require('../utils/error-formatter');
 const { validateFieldReferences } = require('../datasource/field-reference-validator');
 const { validateAbac } = require('../datasource/abac-validator');
@@ -53,6 +57,9 @@ function getValidatorForType(normalizedType) {
   if (normalizedType === 'datasource') {
     return loadExternalDataSourceSchema();
   }
+  if (normalizedType === 'role-assistant-settings') {
+    return loadRoleAssistantSettingsSchema();
+  }
   throw new Error(`Unknown file type: ${normalizedType}`);
 }
 

package/lib/validation/validator.js

@@ -223,10 +223,11 @@ async function validateRbac(appName, options = {}) {
     throw new Error(`Invalid syntax in ${basename}: ${error.message}`);
   }
 
-  const errors = [
-    ...validateRoles(rbac.roles),
-    ...validatePermissions(rbac.permissions)
-  ];
+  const [roleErrors, permissionErrors] = await Promise.all([
+    Promise.resolve(validateRoles(rbac.roles)),
+    Promise.resolve(validatePermissions(rbac.permissions))
+  ]);
+  const errors = [...roleErrors, ...permissionErrors];
 
   return {
     valid: errors.length === 0,
@@ -275,7 +276,7 @@ async function validateEnvTemplate(appName, options = {}) {
       if (!trimmed.includes('=')) {
         errors.push(`Line ${index + 1}: Invalid environment variable format (missing =)`);
       } else {
-        const [key, _value] = trimmed.split('=', 2);
+        const [key] = trimmed.split('=', 2);
         // Trim key to handle whitespace issues
         // Empty values are allowed (_value can be empty string or undefined)
         const trimmedKey = key ? key.trim() : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.50.0",
+  "version": "2.51.1",
   "description": "AI Fabrix Builder — CLI and developer scripts (pnpm + af)",
   "main": "lib/index.js",
   "bin": {
@@ -85,36 +85,59 @@
     "cache": true,
     "temp-dir": ".nyc_output"
   },
+  "overrides": {
+    "@babel/core": "^7.29.7",
+    "@babel/plugin-transform-modules-systemjs": "^7.29.7",
+    "fast-uri": "^4.1.0",
+    "flatted": "^3.4.2",
+    "follow-redirects": "^1.16.0",
+    "form-data": "^4.0.6",
+    "lodash": "^4.18.1",
+    "minimatch": "^10.2.5",
+    "picomatch": "^4.0.5",
+    "qs": "^6.15.3"
+  },
   "pnpm": {
     "overrides": {
-      "@bcoe/v8-coverage": "^1.0.2"
+      "@bcoe/v8-coverage": "^1.0.2",
+      "@babel/core": "^7.29.7",
+      "@babel/plugin-transform-modules-systemjs": "^7.29.7",
+      "fast-uri": "^4.1.0",
+      "flatted": "^3.4.2",
+      "follow-redirects": "^1.16.0",
+      "form-data": "^4.0.6",
+      "lodash": "^4.18.1",
+      "minimatch": "^10.2.5",
+      "picomatch": "^4.0.5",
+      "qs": "^6.15.3"
     }
   },
   "dependencies": {
     "@aifabrix/miso-client": "^4.19.0",
-    "ajv": "^8.12.0",
+    "adm-zip": "^0.6.0",
+    "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
-    "axios": "^1.6.0",
+    "axios": "^1.18.1",
     "chalk": "^4.1.2",
     "commander": "^11.1.0",
-    "handlebars": "^4.7.8",
+    "handlebars": "^4.7.9",
     "inquirer": "^8.2.5",
     "inquirer-autocomplete-prompt": "^2.0.0",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^4.3.0",
     "ora": "^5.4.1",
-    "yaml": "^2.4.0"
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@babel/plugin-syntax-optional-chaining": "^7.8.3",
-    "@babel/preset-env": "^7.29.0",
+    "@babel/preset-env": "^7.29.7",
     "@bcoe/v8-coverage": "^1.0.2",
-    "@nestjs/common": "^10.4.15",
-    "@nestjs/core": "^10.4.15",
-    "@nestjs/platform-express": "^10.4.15",
+    "@nestjs/common": "^11.1.28",
+    "@nestjs/core": "^11.1.28",
+    "@nestjs/platform-express": "^11.1.28",
     "@types/node": "^20.10.0",
     "cross-env": "^10.1.0",
     "eslint": "^8.55.0",
-    "jest": "^30.2.0",
+    "jest": "^30.4.2",
     "markdownlint-cli": "^0.49.0",
     "nyc": "^18.0.0",
     "reflect-metadata": "^0.2.2",

package/scripts/export-builder-api-evidence.js

@@ -18,8 +18,8 @@ const DEFAULT_OUT = path.join(
   '..',
   'aifabrix-dataplane',
   'integration',
-  'aifabrix-builder-api',
-  'aifabrix-builder-api-evidence.json'
+  'builder-api',
+  'builder-api-evidence.json'
 );
 
 const EVIDENCE_PATTERNS = path.join(REPO_ROOT, 'docs', 'builder-help', 'evidence-patterns.json');
@@ -238,7 +238,7 @@ function rowsFromManifestGuides() {
       title: 'Section quality and missing inputs',
       when: 'GET manifest section returns quality.missingInputs',
       expectedBehavior:
-        'Collect required missing inputs from the user before PATCH. Do not guess values. Include sectionReadToken from GET in PATCH body.',
+        'Collect required missing inputs from the user before PATCH. Do not guess values. sectionReadToken from GET is optional on PATCH (server re-reads when omitted; stale token returns 409). Prefer GET when you need quality or missingInputs.',
       order: 17
     })
   ];

package/scripts/lib/plan-actor.js

@@ -80,9 +80,9 @@ function loadActor() {
 function saveActor(displayName, email) {
   const actorPath = resolveActorPath();
   fs.mkdirSync(path.dirname(actorPath), { recursive: true });
-  const lines = [`displayName: "${displayName.replace(/"/g, '\\"')}"`];
+  const lines = [`displayName: ${JSON.stringify(displayName)}`];
   if (email) {
-    lines.push(`email: "${email.replace(/"/g, '\\"')}"`);
+    lines.push(`email: ${JSON.stringify(email)}`);
   }
   fs.writeFileSync(actorPath, `${lines.join('\n')}\n`, 'utf8');
   return actorPath;

package/scripts/lib/plan-meta.js

@@ -87,7 +87,7 @@ function patchPlanMeta(planPath, key, value) {
     die('Plan has no frontmatter to patch');
   }
   let yaml = match[1];
-  const quoted = `"${String(value).replace(/"/g, '\\"')}"`;
+  const quoted = JSON.stringify(String(value));
   const re = new RegExp(`^${key}:.*$`, 'm');
   if (re.test(yaml)) {
     yaml = yaml.replace(re, `${key}: ${quoted}`);

package/scripts/lib/plan-parse.js

@@ -111,7 +111,7 @@ function loadPlanFile(planPath) {
   if (!match) {
     return null;
   }
-  const meta = parseSimpleYaml(match[1]) || {};
+  const meta = parseSimpleYaml(match[1]);
   if (Array.isArray(meta.todos)) {
     meta.todos = normalizeTodos(meta.todos);
   }