@aifabrix/builder 2.49.2 → 2.51.0

package/lib/programmatic/builder-help-authentication-catalog.js

@@ -0,0 +1,282 @@
+/**
+ * Authentication catalog for builder-api LLM help (external-system.schema.json).
+ *
+ * @fileoverview authType modes and credential.method templates for UI handoff guidance
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_DIR = path.join(__dirname, '..', 'schema');
+const SYSTEM_SCHEMA_PATH = path.join(SCHEMA_DIR, 'external-system.schema.json');
+const CREDENTIAL_REGISTRY_PATH = path.join(SCHEMA_DIR, 'type', 'credential-field-registry.json');
+
+/** @type {Object|null} */
+let cachedCatalog = null;
+
+/** @type {Readonly<Record<string, string>>} */
+const METHOD_UI_LABELS = Object.freeze({
+  oauth2: 'OAuth 2.0',
+  aad: 'Azure AD (aad)',
+  apikey: 'API Key',
+  bearerToken: 'Bearer token',
+  basic: 'Basic Auth',
+  queryParam: 'Query parameter',
+  oidc: 'OpenID Connect (OIDC)',
+  hmac: 'HMAC',
+  none: 'None'
+});
+
+/** @type {Readonly<Record<string, string>>} */
+const METHOD_REGISTRY_KEY = Object.freeze({
+  oauth2: 'oauth2',
+  aad: 'oauth2',
+  apikey: 'apiKey',
+  bearerToken: 'bearerToken',
+  basic: 'basicAuth',
+  queryParam: 'queryParam',
+  oidc: 'oidc',
+  hmac: 'hmac',
+  none: 'none'
+});
+
+/** @type {Readonly<Object>} */
+const MANIFEST_AUTH_SPLIT = Object.freeze({
+  variables: {
+    manifestPath: 'authentication.credential.variables',
+    purpose:
+      'Non-secret configuration (baseUrl, tokenUrl, headerName, prefix, testEndpoint, and similar). Set in the manifest authentication section before upload.',
+    publishedBehavior:
+      'Upload publishes variables to dataplane. They appear pre-filled in Connected Systems Authentication — the user does not re-enter them.',
+    agentRule:
+      'Ensure variables are complete in the manifest during editing. After upload, do not ask the user to supply non-secret variable values again.'
+  },
+  security: {
+    manifestPath: 'authentication.credential.security',
+    purpose:
+      'Secret placeholders only. Manifest values must be kv:// references (unresolved in Builder API scope).',
+    publishedBehavior:
+      'Upload creates the credential template. The user adds live secret values in Authentication UI — typically only the token or apiKey.',
+    agentRule:
+      'After upload, ask the user only for requiredSecretKeys. This is the minimum post-upload handoff.'
+  }
+});
+
+/** @type {Readonly<Record<string, string>>} */
+const METHOD_USER_HANDOFF = Object.freeze({
+  oauth2:
+    'User adds clientSecret (and clientId if empty). baseUrl, tokenUrl, grantType, and scope are already published from manifest variables.',
+  aad:
+    'User adds clientSecret (and clientId if empty). baseUrl, tokenUrl, tenantId, and grantType are already published from manifest variables.',
+  apikey:
+    'User adds only the API key token. baseUrl, headerName, prefix, and testEndpoint are already published from manifest variables.',
+  bearerToken:
+    'User adds only the bearer token. baseUrl, headerName, prefix, and testEndpoint are already published from manifest variables.',
+  basic:
+    'User adds username and password. baseUrl and testEndpoint are already published from manifest variables.',
+  queryParam:
+    'User adds only the paramValue secret. baseUrl, paramName, and testEndpoint are already published from manifest variables.',
+  oidc:
+    'openIdConfigUrl and clientId are already published from manifest variables. User confirms or completes any remaining OIDC fields shown in UI.',
+  hmac:
+    'User adds signingSecret. Algorithm and signature header settings are already published from manifest variables.',
+  none: 'No credential secrets required for this method.'
+});
+
+/** @type {ReadonlyArray<Object>} */
+const AUTH_TYPES = Object.freeze([
+  {
+    authType: 'credential',
+    manifestPath: 'authentication.credential',
+    uiTab: 'authentication',
+    description:
+      'Local credential template from external-system.schema.json. Non-secret variables are published on upload; user adds live secrets in Authentication UI only.',
+    userAction:
+      'Open Authentication tab. Non-secret fields are already pre-filled from manifest variables. User adds only the required secret values (for example apiKey token, clientSecret).',
+    builderApiScope:
+      'Set authentication.credential.variables in the manifest before upload. Keep kv:// placeholders in security; upload does not resolve secrets. User replaces placeholders with live values in the UI.'
+  },
+  {
+    authType: 'apiProvider',
+    manifestPath: 'authentication.apiProvider.apiProviderKey',
+    uiTab: 'authentication',
+    description:
+      'Delegated authentication via a Miso API Provider — no dataplane-local vendor secrets.',
+    userAction:
+      'Open Authentication tab and link or select the API Provider referenced by apiProviderKey in the manifest.',
+    builderApiScope:
+      'Upload publishes the apiProviderKey reference only. User completes provider binding in the UI.'
+  },
+  {
+    authType: 'none',
+    manifestPath: 'authentication.authType',
+    uiTab: null,
+    description: 'No authentication block secrets. System does not use a local credential template.',
+    userAction:
+      'Skip credential entry unless the integration still needs network-level auth configured elsewhere.',
+    builderApiScope: 'No post-upload secret handoff for authType none unless live tests fail for other reasons.'
+  }
+]);
+
+/**
+ * @returns {Object}
+ */
+function loadSystemSchema() {
+  return JSON.parse(fs.readFileSync(SYSTEM_SCHEMA_PATH, 'utf8'));
+}
+
+/**
+ * @returns {Object}
+ */
+function loadCredentialRegistry() {
+  return JSON.parse(fs.readFileSync(CREDENTIAL_REGISTRY_PATH, 'utf8'));
+}
+
+/**
+ * @param {string|null|undefined} text
+ * @returns {string|null}
+ */
+function sanitizeHelpText(text) {
+  if (!text) {
+    return null;
+  }
+  const cleaned = String(text)
+    .replace(/https?:\/\/[^\s)]+/gi, '')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+  return cleaned || null;
+}
+
+/**
+ * @param {string} method
+ * @param {Object} registry
+ * @returns {string}
+ */
+function resolveUiLabel(method, registry) {
+  if (METHOD_UI_LABELS[method]) {
+    return METHOD_UI_LABELS[method];
+  }
+  const registryKey = METHOD_REGISTRY_KEY[method];
+  const entry = registryKey ? registry.credentialTypes?.[registryKey] : null;
+  if (entry?.display?.label) {
+    return entry.display.label;
+  }
+  return method;
+}
+
+/**
+ * @param {string} method
+ * @param {Object} methodDef
+ * @returns {Object}
+ */
+function summarizeMethodFields(method, methodDef) {
+  const variables = (methodDef.variables || []).map((item) => ({
+    key: item.key,
+    required: item.required === true,
+    description: sanitizeHelpText(item.description)
+  }));
+  const security = (methodDef.security || []).map((item) => ({
+    key: item.key,
+    required: item.required === true,
+    encrypted: true
+  }));
+  return {
+    method,
+    uiLabel: METHOD_UI_LABELS[method] || method,
+    variableKeys: variables.map((item) => item.key),
+    requiredVariableKeys: variables.filter((item) => item.required).map((item) => item.key),
+    secretKeys: security.map((item) => item.key),
+    requiredSecretKeys: security.filter((item) => item.required).map((item) => item.key),
+    variables,
+    security,
+    userHandoff: METHOD_USER_HANDOFF[method] || 'User completes secret fields shown for this method in Authentication.',
+    manifestPath: 'authentication.credential.method',
+    schemaDefKey: 'authenticationVariablesByMethod'
+  };
+}
+
+/**
+ * @returns {Object}
+ */
+function buildAuthenticationCatalog() {
+  if (cachedCatalog) {
+    return cachedCatalog;
+  }
+  const schema = loadSystemSchema();
+  const registry = loadCredentialRegistry();
+  const methodsByDef = schema.$defs?.authenticationVariablesByMethod || {};
+  const methodEnum =
+    schema.$defs?.credentialTemplate?.properties?.method?.enum ||
+    Object.keys(methodsByDef).sort();
+
+  const credentialMethods = methodEnum
+    .filter((method) => methodsByDef[method])
+    .map((method) => {
+      const summary = summarizeMethodFields(method, methodsByDef[method]);
+      summary.uiLabel = resolveUiLabel(method, registry);
+      return summary;
+    });
+
+  cachedCatalog = {
+    schemaSource: 'external-system.schema.json',
+    manifestSectionKey: 'system.authentication',
+    datasourceNote:
+      'Authentication is declared on the external system manifest (system.authentication), not on individual datasource manifests. Datasources inherit the linked system credential during sync and CIP execution.',
+    manifestAuthSplit: MANIFEST_AUTH_SPLIT,
+    authTypes: AUTH_TYPES,
+    credentialMethods,
+    agentHandoffSteps: [
+      'Read workspace section system.authentication (or the published system manifest) before prompting the user.',
+      'Identify authentication.authType: credential, apiProvider, or none.',
+      'When authType is credential, ensure authentication.credential.variables holds all non-secret config before upload (baseUrl, headerName, tokenUrl, and similar).',
+      'Upload publishes variables pre-filled in Authentication UI. Ask the user only for requiredSecretKeys — not for variables already in the manifest.',
+      'When authType is apiProvider, direct the user to link apiProviderKey in Authentication — do not ask for vendor API keys in Builder API scope.',
+      'When authType is none, skip secret handoff unless E2E still fails for unrelated configuration.',
+      'Provide the Connected Systems Authentication URL using connectedSystemUi urlTemplates plus the published systemKey.'
+    ]
+  };
+  return cachedCatalog;
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object|null}
+ */
+function buildAuthenticationHandoffForManifest(query) {
+  const authType = query.authType ? String(query.authType) : null;
+  const method = query.credentialMethod ? String(query.credentialMethod) : null;
+  if (!authType && !method) {
+    return null;
+  }
+  const catalog = buildAuthenticationCatalog();
+  const authTypeEntry = authType ? catalog.authTypes.find((entry) => entry.authType === authType) : null;
+  const methodEntry = method
+    ? catalog.credentialMethods.find((entry) => entry.method === method)
+    : null;
+  if (!authTypeEntry && !methodEntry) {
+    return null;
+  }
+  return {
+    authType: authTypeEntry || null,
+    credentialMethod: methodEntry || null,
+    promptHints: [
+      authTypeEntry ? authTypeEntry.userAction : null,
+      'Non-secret authentication.credential.variables are already published and pre-filled in the UI.',
+      methodEntry ? methodEntry.userHandoff : null,
+      methodEntry && methodEntry.requiredSecretKeys.length
+        ? `User adds only these secret fields: ${methodEntry.requiredSecretKeys.join(', ')}`
+        : null
+    ].filter(Boolean)
+  };
+}
+
+module.exports = {
+  AUTH_TYPES,
+  METHOD_UI_LABELS,
+  buildAuthenticationCatalog,
+  buildAuthenticationHandoffForManifest
+};

package/lib/programmatic/builder-help-connected-system-ui.js

@@ -0,0 +1,266 @@
+/**
+ * Connected Systems UI URL catalog for builder-api LLM help (plan 154.6).
+ *
+ * @fileoverview Structured paths and tab aliases for post-upload authentication handoff
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { buildHelpEnvelope } = require('./builder-help-envelope');
+const {
+  buildAuthenticationCatalog,
+  buildAuthenticationHandoffForManifest
+} = require('./builder-help-authentication-catalog');
+
+/** @type {ReadonlyArray<Object>} */
+const SYSTEM_TABS = Object.freeze([
+  { uiLabel: 'Overview', urlTab: null, aliases: ['overview'], omitTabParam: true },
+  { uiLabel: 'Technical readiness', urlTab: 'technical-readiness', aliases: [] },
+  { uiLabel: 'Business Entities', urlTab: 'datasources', aliases: ['business-entities'] },
+  { uiLabel: 'Business Policies', urlTab: 'rules', aliases: ['business-policies'] },
+  { uiLabel: 'Authentication', urlTab: 'authentication', aliases: ['Authentication'] },
+  { uiLabel: 'Configuration', urlTab: 'configuration', aliases: [] },
+  { uiLabel: 'AI Interfaces', urlTab: 'openapi', aliases: ['ai-interfaces'] },
+  { uiLabel: 'Policies & Security', urlTab: 'policies', aliases: [], note: 'When policy management is enabled in dataplane.' },
+  { uiLabel: 'Audit & History', urlTab: 'audit', aliases: ['audit-history'] }
+]);
+
+/** @type {ReadonlyArray<Object>} */
+const DATASOURCE_TABS = Object.freeze([
+  {
+    uiLabel: 'Overview',
+    urlTab: 'business-context',
+    aliases: ['business-overview'],
+    omitTabParam: true,
+    note: 'First tab id is business-context. URL value overview opens Technical readiness.'
+  },
+  { uiLabel: 'Technical readiness', urlTab: 'overview', aliases: ['technical-readiness'] },
+  { uiLabel: 'Data Flow', urlTab: 'cip', aliases: ['data-flow', 'Data Flow'] },
+  { uiLabel: 'Business Vocabulary', urlTab: 'mappings', aliases: ['business-vocabulary'] },
+  { uiLabel: 'AI Contract', urlTab: 'exposure', aliases: ['ai-contract'] },
+  { uiLabel: 'Business Policies', urlTab: 'abac', aliases: ['business-policies'] },
+  { uiLabel: 'Quality', urlTab: 'quality', aliases: [] },
+  { uiLabel: 'Sync', urlTab: 'sync', aliases: [] },
+  { uiLabel: 'Doc Processing', urlTab: 'document-processing', aliases: ['doc-processing'] },
+  { uiLabel: 'Operations', urlTab: 'openapi', aliases: ['operations'] },
+  { uiLabel: 'Configuration', urlTab: 'configuration', aliases: [] },
+  { uiLabel: 'YAML', urlTab: 'yaml', aliases: [] },
+  { uiLabel: 'Logs', urlTab: 'logs', aliases: ['audit-logs', 'execution-logs'] }
+]);
+
+/** @type {Readonly<Object>} */
+const URL_TEMPLATES = Object.freeze({
+  dataplanePublicBasePlaceholder: '{dataplanePublicBase}',
+  systemPath: '/connected-systems/{systemKey}',
+  systemPathWithTab: '/connected-systems/{systemKey}?tab={tab}',
+  datasourcePath: '/connected-systems/{systemKey}/datasources/{datasourceKey}',
+  datasourcePathWithTab: '/connected-systems/{systemKey}/datasources/{datasourceKey}?tab={tab}',
+  composedSystemUrl: '{dataplanePublicBase}/connected-systems/{systemKey}?tab={tab}',
+  composedDatasourceUrl:
+    '{dataplanePublicBase}/connected-systems/{systemKey}/datasources/{datasourceKey}?tab={tab}',
+  routeHelper:
+    'Dataplane UI route helper: CONNECTED_SYSTEM_ROUTES.DATASOURCE_TAB(systemKey, datasourceKey, tab).'
+});
+
+/** @type {ReadonlyArray<string>} */
+const AGENT_RULES = Object.freeze([
+  'Run validate, test, test-integration, and upload without requiring resolved integration secrets in Builder API scope.',
+  'Upload publishes manifest authentication.credential.variables (non-secrets) pre-filled in the UI; kv:// security placeholders stay unresolved until the user adds live secrets.',
+  'Before post-upload handoff, read system.authentications[] (or legacy authentication) and identify authType, usage (api, webhookInbound, syncExecution), and credential.method when applicable.',
+  'Set all non-secret auth config in credential.variables during manifest editing — do not ask the user to re-enter baseUrl, headerName, tokenUrl, or similar after upload.',
+  'After upload succeeds, ask the user to open Connected Systems Authentication and add only requiredSecretKeys (for example apiKey token, webhookInbound signingSecret) — not variables already published.',
+  'When webhook.enabled or syncBridge is active, direct the user to datasource Sync tab (tab=sync) for webhook activation markdown and syncBridge read-only status.',
+  'Combine the user dataplane public base (origin including /data) with paths from urlTemplates.',
+  'Do not ask the user to paste vendor tokens into Builder API requests or workspace files when UI authentication is the intended path.',
+  'Tab query values are case-insensitive; aliases in systemTabs and datasourceTabs are accepted on load.'
+]);
+
+/** @type {ReadonlyArray<Object>} */
+const POST_UPLOAD_AUTH_WORKFLOW = Object.freeze([
+  { order: 1, capability: 'validate', goal: 'Confirm workspace manifest structure before publish.' },
+  { order: 2, capability: 'test', goal: 'Run local manifest tests without live vendor credentials.' },
+  {
+    order: 3,
+    capability: 'test-integration',
+    goal: 'Exercise pipeline integration tests; credential gaps may remain until UI auth is set.'
+  },
+  {
+    order: 4,
+    capability: 'upload',
+    goal: 'Publish external system draft without embedding resolved secrets in the workspace.'
+  },
+  {
+    order: 5,
+    capability: 'ui-authentication-handoff',
+    goal:
+      'Read authentications[] usage slots and credential.method from manifest; provide Authentication URL and method-specific secret field guidance from authentication catalog. Include webhookInbound and syncExecution when configured.'
+  },
+  {
+    order: 6,
+    capability: 'ui-sync-fabrix-handoff',
+    goal:
+      'When webhook or syncBridge is enabled, provide datasource Sync tab URL (tab=sync) for activation guide and read-only fabrix status.'
+  },
+  { order: 7, capability: 'test-e2e', goal: 'After UI auth is configured, user or agent re-runs E2E against live vendor APIs.' }
+]);
+
+/**
+ * @param {string} input
+ * @param {ReadonlyArray<Object>} catalog
+ * @returns {string|null}
+ */
+function resolveTabFromCatalog(input, catalog) {
+  if (!input) {
+    return null;
+  }
+  const normalized = String(input).toLowerCase();
+  for (const entry of catalog) {
+    if (entry.urlTab && entry.urlTab.toLowerCase() === normalized) {
+      return entry.urlTab;
+    }
+    for (const alias of entry.aliases || []) {
+      if (String(alias).toLowerCase() === normalized) {
+        return entry.urlTab;
+      }
+    }
+    if (entry.omitTabParam && normalized === 'overview') {
+      return null;
+    }
+  }
+  return String(input);
+}
+
+/**
+ * @param {string} systemKey
+ * @param {string|null|undefined} tabInput
+ * @returns {string}
+ */
+function buildSystemRelativePath(systemKey, tabInput) {
+  const encodedKey = encodeURIComponent(systemKey);
+  const tab = resolveTabFromCatalog(tabInput, SYSTEM_TABS);
+  const base = `/connected-systems/${encodedKey}`;
+  if (!tab) {
+    return base;
+  }
+  return `${base}?tab=${encodeURIComponent(tab)}`;
+}
+
+/**
+ * @param {string} systemKey
+ * @param {string} datasourceKey
+ * @param {string|null|undefined} tabInput
+ * @returns {string}
+ */
+function buildDatasourceRelativePath(systemKey, datasourceKey, tabInput) {
+  const tab = resolveTabFromCatalog(tabInput, DATASOURCE_TABS);
+  const base = `/connected-systems/${encodeURIComponent(systemKey)}/datasources/${encodeURIComponent(datasourceKey)}`;
+  if (!tab) {
+    return base;
+  }
+  return `${base}?tab=${encodeURIComponent(tab)}`;
+}
+
+/**
+ * @param {string} publicBase
+ * @param {string} relativePath
+ * @returns {string}
+ */
+function composePublicUrl(publicBase, relativePath) {
+  const trimmedBase = String(publicBase).replace(/\/$/, '');
+  const trimmedPath = relativePath.startsWith('/') ? relativePath : `/${relativePath}`;
+  return `${trimmedBase}${trimmedPath}`;
+}
+
+/**
+ * @param {Object} data
+ * @param {Object} params
+ * @returns {void}
+ */
+function attachConnectedSystemResolvedPaths(data, params) {
+  const { systemKey, tab, datasourceKey, datasourceTab, publicBase } = params;
+  const authenticationPath = buildSystemRelativePath(systemKey, 'authentication');
+  const requestedSystemPath = buildSystemRelativePath(systemKey, tab);
+  data.resolved = {
+    systemKey,
+    authenticationPath,
+    requestedSystemPath
+  };
+  if (publicBase) {
+    data.resolved.authenticationUrl = composePublicUrl(publicBase, authenticationPath);
+    data.resolved.requestedSystemUrl = composePublicUrl(publicBase, requestedSystemPath);
+  }
+  if (datasourceKey) {
+    const datasourcePath = buildDatasourceRelativePath(systemKey, datasourceKey, datasourceTab);
+    data.resolved.datasourceKey = datasourceKey;
+    data.resolved.datasourcePath = datasourcePath;
+    if (publicBase) {
+      data.resolved.datasourceUrl = composePublicUrl(publicBase, datasourcePath);
+    }
+  }
+}
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildConnectedSystemUiTopic(query) {
+  const systemKey = query.systemKey ? String(query.systemKey) : null;
+  const datasourceKey = query.datasourceKey ? String(query.datasourceKey) : null;
+  const tab = query.tab || 'authentication';
+  const datasourceTab = query.datasourceTab || null;
+  const publicBase = query.dataplanePublicBase ? String(query.dataplanePublicBase) : null;
+
+  /** @type {Object} */
+  const data = {
+    urlTemplates: URL_TEMPLATES,
+    systemTabs: SYSTEM_TABS,
+    datasourceTabs: DATASOURCE_TABS,
+    authentication: buildAuthenticationCatalog(),
+    agentRules: AGENT_RULES,
+    postUploadAuthWorkflow: POST_UPLOAD_AUTH_WORKFLOW,
+    behavior: {
+      tabQuerySelectsTabOnLoad: true,
+      tabSwitchUpdatesUrl: true,
+      navigationClearsStaleTabState: true,
+      staticUiRebuildNote: 'Rebuild dataplane static UI after UI route changes when using Docker dev-reload (make ui-build).'
+    }
+  };
+
+  const manifestHandoff = buildAuthenticationHandoffForManifest(query);
+  if (manifestHandoff) {
+    data.manifestHandoff = manifestHandoff;
+  }
+
+  if (systemKey) {
+    attachConnectedSystemResolvedPaths(data, {
+      systemKey,
+      tab,
+      datasourceKey,
+      datasourceTab,
+      publicBase
+    });
+  }
+
+  return buildHelpEnvelope({
+    topic: 'connectedSystemUi',
+    key: systemKey || 'connectedSystemUi',
+    title: 'Connected Systems UI navigation',
+    summary:
+      'Shareable dataplane UI paths, tab aliases, and external-system authentication catalog for post-upload handoff without Builder API secrets.',
+    data,
+    related: ['workflow', 'subscriptionGuide', 'evidencePatterns'],
+    recommendedNext: ['workflow', 'evidencePatterns']
+  });
+}
+
+module.exports = {
+  SYSTEM_TABS,
+  DATASOURCE_TABS,
+  URL_TEMPLATES,
+  buildSystemRelativePath,
+  buildDatasourceRelativePath,
+  composePublicUrl,
+  buildConnectedSystemUiTopic
+};

package/lib/programmatic/builder-help-enterprise-sync-fabrix.js

@@ -0,0 +1,60 @@
+/**
+ * Enterprise Synchronization Fabrix help topic (webhooks + syncBridge).
+ *
+ * @fileoverview Builder-api LLM help for webhook activation and syncBridge
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { buildHelpEnvelope } = require('./builder-help-envelope');
+
+const HELP_MD_DIR = path.join(__dirname, 'help-content');
+
+/** @type {ReadonlyArray<string>} */
+const REPAIR_COMMANDS = Object.freeze([
+  'aifabrix repair <systemKey>',
+  'aifabrix repair <systemKey> --auth <method>',
+  'aifabrix repair <systemKey> --auth-webhook',
+  'aifabrix repair <systemKey> --auth-sync',
+  'aifabrix validate <app>',
+  'aifabrix upload <app>'
+]);
+
+/**
+ * @param {Object} query
+ * @returns {Object}
+ */
+function buildEnterpriseSyncFabrixTopic(query) {
+  const raw = fs.readFileSync(
+    path.join(HELP_MD_DIR, 'enterprise-sync-fabrix.md'),
+    'utf8'
+  );
+  const systemKey = query.systemKey ? String(query.systemKey) : '';
+  return buildHelpEnvelope({
+    topic: 'enterpriseSyncFabrix',
+    key: systemKey || 'enterpriseSyncFabrix',
+    title: 'Enterprise Synchronization Fabrix',
+    summary:
+      'Webhook change signals, syncBridge propagation, authentications[] usage slots, and activation workflow.',
+    data: {
+      authenticationsUsageSlots: ['api', 'webhookInbound', 'syncExecution'],
+      syncBridgeModes: ['disabled', 'master', 'bidirectional'],
+      webhookEndpointModes: ['system', 'datasource', 'event'],
+      repairCommands: [...REPAIR_COMMANDS],
+      postUploadTabs: {
+        systemAuthentication: 'authentication',
+        datasourceSync: 'sync',
+        datasourceLogs: 'logs'
+      },
+      bodyText: raw.replace(/\s{2,}/g, ' ').trim()
+    },
+    related: ['connectedSystemUi', 'workflow', 'schemaCatalog'],
+    recommendedNext: ['connectedSystemUi', 'workflow']
+  });
+}
+
+module.exports = {
+  buildEnterpriseSyncFabrixTopic
+};

package/lib/programmatic/builder-help-envelope.js

@@ -0,0 +1,36 @@
+/**
+ * Help response envelope builder (plan 154.5).
+ *
+ * @fileoverview Shared constants and envelope shape for builder-api help
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const HELP_CONTENT_VERSION = '154.7';
+const HELP_SCHEMA_VERSION = '1.0.0';
+
+/**
+ * @param {Object} input
+ * @returns {Object}
+ */
+function buildHelpEnvelope(input) {
+  return {
+    version: HELP_CONTENT_VERSION,
+    schemaVersion: HELP_SCHEMA_VERSION,
+    topic: input.topic,
+    key: input.key,
+    title: input.title,
+    summary: input.summary,
+    data: input.data || {},
+    related: input.related || [],
+    recommendedNext: input.recommendedNext || []
+  };
+}
+
+module.exports = {
+  HELP_CONTENT_VERSION,
+  HELP_SCHEMA_VERSION,
+  buildHelpEnvelope
+};