@aifabrix/builder 2.53.1 → 2.54.1

package/lib/programmatic/builder-api-server.js

@@ -1,5 +1,5 @@
 /**
- * Builder API HTTP server (plan 154.0 — pre-Nest unified router).
+ * Builder API HTTP server (pre-Nest unified router).
  *
  * @fileoverview Full V1 route set via capability registry
  * @author AI Fabrix Team
@@ -18,6 +18,8 @@ const { writeAccessLog } = require('./access-log');
 const { dispatchCapabilityRoute } = require('./builder-api-route-dispatch');
 const { renderBuilderApiRedocHtml, resolvePublicBaseUrl } = require('./openapi-docs-serving');
 const { buildProblemDetails, writeProblemDetails } = require('./http-problem-details');
+const { sendRaw } = require('./http-raw-response');
+const { handleCorsPreflight } = require('./builder-api-cors');
 
 /**
  * @param {import('http').ServerResponse} res
@@ -171,6 +173,10 @@ async function handleRequest(req, res) {
   const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`);
   const pathname = url.pathname;
 
+  if (handleCorsPreflight(req, res, requestId, pathname, logRequestOutcome)) {
+    return;
+  }
+
   if (isRedocHtmlPath(pathname) || isOpenApiJsonPath(pathname)) {
     handleOpenApiDocs(req, res, pathname, requestId);
     logRequestOutcome({
@@ -196,6 +202,7 @@ async function handleRequest(req, res) {
     res,
     sendJson,
     sendProblem,
+    sendRaw,
     readJsonBody,
     resolved,
     query,

package/lib/programmatic/capability-registry.js

@@ -76,8 +76,62 @@ const CAPABILITIES = Object.freeze([
   { method: 'GET', route: '/systems/:systemKey/channels/package/zip', handlerId: 'getChannelPackageZip', operationType: 'channel.read', mutating: false },
   { method: 'GET', route: '/systems/:systemKey/channels/branding', handlerId: 'getChannelBranding', operationType: 'channel.read', mutating: false },
   { method: 'PATCH', route: '/systems/:systemKey/channels/branding', handlerId: 'patchChannelBranding', operationType: 'channel', mutating: true },
+  { method: 'GET', route: '/channels', handlerId: 'listChannelTargets', operationType: 'channel.read', mutating: false },
+  { method: 'GET', route: '/channels/:definitionKey', handlerId: 'getChannelDefinitionDetail', operationType: 'channel.read', mutating: false },
+  {
+    method: 'GET',
+    route: '/channels/:definitionKey/installations/:systemKey',
+    handlerId: 'getChannelInstallation',
+    operationType: 'channel.read',
+    mutating: false
+  },
+  { method: 'POST', route: '/systems/:systemKey/channels/install', handlerId: 'runChannelInstall', operationType: 'channel', mutating: true },
+  { method: 'GET', route: '/systems/:systemKey/channels/install', handlerId: 'getChannelInstall', operationType: 'channel.read', mutating: false },
+  {
+    method: 'GET',
+    route: '/systems/:systemKey/channels/install/help.md',
+    handlerId: 'getChannelInstallHelp',
+    operationType: 'channel.read',
+    mutating: false
+  },
+  {
+    method: 'POST',
+    route: '/systems/:systemKey/channels/install/continue',
+    handlerId: 'continueChannelInstall',
+    operationType: 'channel',
+    mutating: true
+  },
+  { method: 'GET', route: '/systems/:systemKey/channels/artifacts', handlerId: 'listChannelArtifacts', operationType: 'channel.read', mutating: false },
+  {
+    method: 'GET',
+    route: '/systems/:systemKey/channels/artifacts/:artifactId',
+    handlerId: 'getChannelArtifact',
+    operationType: 'channel.read',
+    mutating: false
+  },
+  {
+    method: 'GET',
+    route: '/systems/:systemKey/channels/callbacks/:provider',
+    handlerId: 'getChannelCallback',
+    operationType: 'channel',
+    mutating: true
+  },
+  {
+    method: 'POST',
+    route: '/systems/:systemKey/channels/callbacks/:provider',
+    handlerId: 'postChannelCallback',
+    operationType: 'channel',
+    mutating: true
+  },
   { method: 'GET', route: '/health', handlerId: 'health', operationType: 'infra', mutating: false },
   { method: 'GET', route: '/health/ready', handlerId: 'ready', operationType: 'infra', mutating: false },
+  {
+    method: 'GET',
+    route: '/auth/permissions',
+    handlerId: 'getAuthPermissions',
+    operationType: 'infra',
+    mutating: false
+  },
   {
     method: 'GET',
     route: '/help',

package/lib/programmatic/channel-install-help-resolve.js

@@ -0,0 +1,359 @@
+/**
+ * Resolve channel install help for a definition or instance key.
+ *
+ * @fileoverview POST identity + per-instance GET (session or synthesized)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { toChannelInstallEnvelope } = require('../channels/channel-install-envelope');
+const { toChannelInstallHttpPayload } = require('../channels/channel-install-http-payload');
+const { resolveChannelRuntimeValues } = require('../channels/channel-runtime-resolver');
+const { vendorFacingUrlsFromCtx } = require('../channels/vendor-dataplane-url');
+const {
+  getChannelDefinition,
+  listChannelDefinitionKeys
+} = require('../channels/channel-definition-registry');
+const {
+  readChannelInstallSession,
+  writeChannelInstallSession,
+  httpError
+} = require('./channel-install-session');
+const { peekPortalMicrosoftLogin } = require('../channels/microsoft-provisioning/login-portal');
+
+/**
+ * @param {Object} payload
+ * @param {string} definitionKey
+ * @param {string} installationKey
+ * @returns {Object}
+ */
+function attachInstallIdentity(payload, definitionKey, installationKey) {
+  return {
+    ...payload,
+    definitionKey,
+    installationKey,
+    systemKey: installationKey
+  };
+}
+
+/**
+ * @param {Object[]} [actions]
+ * @param {string} id
+ * @returns {string}
+ */
+function copyActionValue(actions, id) {
+  const row = (actions || []).find((action) => action && action.id === id);
+  return row && typeof row.value === 'string' ? row.value.trim() : '';
+}
+
+/**
+ * @param {Object} session
+ * @returns {Object}
+ */
+function runtimeValuesFromStoredEnvelope(session) {
+  const envelope = session.envelope || {};
+  const use = envelope.useValues || {};
+  const actions = envelope.userActions || [];
+  return {
+    appName:
+      use.Name ||
+      copyActionValue(actions, 'copy-name') ||
+      session.displayName ||
+      session.name ||
+      '',
+    appDescription: use.Description || copyActionValue(actions, 'copy-description') || '',
+    mcpUrl: use['Server URL'] || copyActionValue(actions, 'copy-server-url') || ''
+  };
+}
+
+/**
+ * @param {Object} session
+ * @returns {Object}
+ */
+function copilotRuntimeFromSession(session) {
+  const peek = peekPortalMicrosoftLogin(session.installationKey) || {};
+  return {
+    appName: session.displayName || session.name,
+    oauthPluginVaultReferenceId: session.oauthPluginVaultReferenceId,
+    packageAppId: session.packageAppId,
+    microsoftLoginUrl: peek.loginUrl || session.microsoftLoginUrl,
+    microsoftLoginUserCode: peek.userCode || session.microsoftLoginUserCode,
+    microsoftAuthConfigFallback: session.microsoftAuthConfigFallback === true
+  };
+}
+
+/**
+ * @param {Object} session
+ * @returns {Object}
+ */
+function refreshCopilotEnvelope(session, ctx) {
+  const definitionKey = session.definitionKey || session.channelTarget;
+  if (definitionKey !== 'microsoft-copilot') {
+    return session.envelope;
+  }
+  return toChannelInstallEnvelope({
+    channelTarget: definitionKey,
+    displayName: session.displayName || session.name || 'Microsoft Copilot',
+    ctx: {
+      instanceSystemKey: session.installationKey,
+      projectRoot: ctx && typeof ctx.getUserRoot === 'function' ? ctx.getUserRoot() : undefined
+    },
+    runtimeValues: copilotRuntimeFromSession(session),
+    verdicts: (session.envelope && session.envelope.verdicts) || {
+      runtime: { ok: true, label: 'Deployed' }
+    }
+  });
+}
+
+/**
+ * Rebuild ChatGPT help so Open ChatGPT Apps uses the current drafts URL.
+ * @param {Object} session
+ * @returns {Object}
+ */
+function refreshChatGptEnvelope(session) {
+  const definitionKey = session.definitionKey || session.channelTarget;
+  if (definitionKey !== 'chatgpt') {
+    return session.envelope;
+  }
+  return toChannelInstallEnvelope({
+    channelTarget: definitionKey,
+    displayName: session.displayName || session.name || 'ChatGPT',
+    ctx: {},
+    runtimeValues: runtimeValuesFromStoredEnvelope(session),
+    verdicts: (session.envelope && session.envelope.verdicts) || {
+      runtime: { ok: true, label: 'Deployed' }
+    }
+  });
+}
+
+/**
+ * Rebuild Claude help so connectors URL and Name/Server URL stay current.
+ * @param {Object} session
+ * @returns {Object}
+ */
+function refreshClaudeEnvelope(session) {
+  const definitionKey = session.definitionKey || session.channelTarget;
+  if (definitionKey !== 'claude') {
+    return session.envelope;
+  }
+  return toChannelInstallEnvelope({
+    channelTarget: definitionKey,
+    displayName: session.displayName || session.name || 'Claude',
+    ctx: {},
+    runtimeValues: runtimeValuesFromStoredEnvelope(session),
+    verdicts: (session.envelope && session.envelope.verdicts) || {
+      runtime: { ok: true, label: 'Deployed' }
+    }
+  });
+}
+
+/**
+ * @param {Object} session
+ * @returns {Object}
+ */
+function refreshStoredEnvelope(session, ctx) {
+  const definitionKey = session.definitionKey || session.channelTarget;
+  if (definitionKey === 'microsoft-copilot') {
+    return refreshCopilotEnvelope(session, ctx);
+  }
+  if (definitionKey === 'chatgpt') {
+    return refreshChatGptEnvelope(session);
+  }
+  if (definitionKey === 'claude') {
+    return refreshClaudeEnvelope(session);
+  }
+  return session.envelope;
+}
+
+function helpPayloadFromSession(session, ctx) {
+  const envelope = refreshStoredEnvelope(session, ctx) || session.envelope;
+  if (envelope && typeof envelope === 'object') {
+    const payload = toChannelInstallHttpPayload(envelope);
+    const definitionKey = session.definitionKey || session.channelTarget;
+    const installationKey = session.installationKey;
+    if (!definitionKey || !installationKey) {
+      return payload;
+    }
+    return attachInstallIdentity(payload, definitionKey, installationKey);
+  }
+  const payload = {
+    helpMarkdown: session.helpMarkdown,
+    helpMarkdownContentType: 'text/markdown'
+  };
+  if (session.phase === 'waitingForUser') {
+    payload.refreshHintSeconds = 15;
+  }
+  const definitionKey = session.definitionKey || session.channelTarget;
+  const installationKey = session.installationKey;
+  if (!definitionKey || !installationKey) {
+    return payload;
+  }
+  return attachInstallIdentity(payload, definitionKey, installationKey);
+}
+
+/**
+ * @param {string} instanceKey
+ * @returns {string|null}
+ */
+function definitionKeyFromInstanceKey(instanceKey) {
+  const keys = listChannelDefinitionKeys().sort((left, right) => right.length - left.length);
+  for (const key of keys) {
+    if (instanceKey === key || instanceKey.startsWith(`${key}-`)) {
+      return key;
+    }
+  }
+  return null;
+}
+
+/**
+ * Catalog key for install/continue. Path may be the definition or the instance.
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {string}
+ */
+function resolveInstallDefinitionKey(ctx) {
+  if (getChannelDefinition(ctx.systemKey)) {
+    return ctx.systemKey;
+  }
+  const session = readChannelInstallSession(ctx);
+  const fromSession = session && (session.definitionKey || session.channelTarget);
+  if (typeof fromSession === 'string' && getChannelDefinition(fromSession)) {
+    return fromSession;
+  }
+  const fromInstance = definitionKeyFromInstanceKey(ctx.systemKey);
+  if (fromInstance && getChannelDefinition(fromInstance)) {
+    return fromInstance;
+  }
+  return ctx.systemKey;
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {Object|null}
+ */
+function readInstanceSystemDoc(ctx) {
+  const filePath = path.join(ctx.getIntegrationPath(), `${ctx.systemKey}-system.json`);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {Object} doc
+ * @param {string} instanceKey
+ * @returns {string|null}
+ */
+function definitionKeyFromDoc(doc, instanceKey) {
+  const stamped = doc && doc.channel && doc.channel.definitionKey;
+  if (typeof stamped === 'string' && stamped.trim()) {
+    return stamped.trim();
+  }
+  return definitionKeyFromInstanceKey(instanceKey);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {string} definitionKey
+ * @param {string} displayName
+ * @param {string} [description]
+ * @returns {Object}
+ */
+function runtimeValuesForHelp(ctx, definitionKey, displayName, description) {
+  const vendor = vendorFacingUrlsFromCtx(ctx);
+  return resolveChannelRuntimeValues({
+    dataplaneBaseUrl: vendor.dataplaneBaseUrl,
+    controllerUrl: vendor.controllerUrl,
+    channelTarget: definitionKey,
+    appName: displayName,
+    instanceSystemKey: ctx.systemKey,
+    environment: ctx.environment,
+    appDescription: description || ''
+  });
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} doc
+ * @returns {{ payload: Object, envelope: Object }|null}
+ */
+function synthesizeInstallHelp(ctx, doc) {
+  const installationKey = ctx.systemKey;
+  const definitionKey = definitionKeyFromDoc(doc, installationKey);
+  if (!definitionKey || !getChannelDefinition(definitionKey)) {
+    return null;
+  }
+  const displayName =
+    (typeof doc.displayName === 'string' && doc.displayName.trim()) || installationKey;
+  const envelope = toChannelInstallEnvelope({
+    channelTarget: definitionKey,
+    displayName,
+    ctx: {
+      dataplaneUrl: ctx.dataplaneUrl,
+      environment: ctx.environment,
+      projectRoot: ctx.getUserRoot()
+    },
+    runtimeValues: runtimeValuesForHelp(ctx, definitionKey, displayName, doc.description),
+    verdicts: { runtime: { ok: true, label: 'Deployed' } }
+  });
+  const payload = attachInstallIdentity(
+    toChannelInstallHttpPayload(envelope),
+    definitionKey,
+    installationKey
+  );
+  writeChannelInstallSession(ctx, {
+    name: displayName,
+    displayName,
+    phase: envelope.phase,
+    envelope,
+    definitionKey,
+    installationKey
+  });
+  return { payload, envelope };
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} [query]
+ * @returns {Object}
+ */
+function resolveChannelInstallHelp(ctx, query = {}) {
+  const session = readChannelInstallSession(ctx);
+  if (session) {
+    if (query.verbose === 'true' || query.verbose === true) {
+      return refreshStoredEnvelope(session, ctx) || session.envelope;
+    }
+    return helpPayloadFromSession(session, ctx);
+  }
+  if (getChannelDefinition(ctx.systemKey)) {
+    throw httpError('Channel install session not found. POST install first.', 404);
+  }
+  const doc = readInstanceSystemDoc(ctx);
+  if (!doc) {
+    throw httpError('Channel install session not found. POST install first.', 404);
+  }
+  const synthesized = synthesizeInstallHelp(ctx, doc);
+  if (!synthesized) {
+    throw httpError('Channel install session not found. POST install first.', 404);
+  }
+  if (query.verbose === 'true' || query.verbose === true) {
+    return synthesized.envelope;
+  }
+  return synthesized.payload;
+}
+
+module.exports = {
+  attachInstallIdentity,
+  helpPayloadFromSession,
+  definitionKeyFromInstanceKey,
+  resolveInstallDefinitionKey,
+  resolveChannelInstallHelp
+};

package/lib/programmatic/channel-install-session.js

@@ -0,0 +1,218 @@
+/**
+ * Non-secret channel install session under the workspace integration folder.
+ *
+ * @fileoverview Persist help markdown + envelope for GET continue
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('../internal/fs-real-sync');
+const { ensureIntegrationDirectory } = require('./workspace-context');
+
+const SESSION_FILE = '.channel-install.json';
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {string}
+ */
+function sessionPath(ctx) {
+  return path.join(ctx.getIntegrationPath(), SESSION_FILE);
+}
+
+/**
+ * @param {string} filePath
+ * @param {Object} stored
+ */
+function writeSessionFile(filePath, stored) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(stored, null, 2)}\n`, 'utf8');
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {string|null}
+ */
+function instanceSessionPath(ctx) {
+  const instanceKey = typeof ctx.instanceSystemKey === 'string' ? ctx.instanceSystemKey.trim() : '';
+  if (!instanceKey || instanceKey === ctx.systemKey) {
+    return null;
+  }
+  return path.join(ctx.getIntegrationRoot(), instanceKey, SESSION_FILE);
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {Object|null}
+ */
+function readChannelInstallSession(ctx) {
+  const filePath = sessionPath(ctx);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {Object} session
+ * @returns {Object}
+ */
+function writeChannelInstallSession(ctx, session) {
+  ensureIntegrationDirectory(ctx);
+  const installationKey = ctx.instanceSystemKey || session.installationKey || ctx.systemKey;
+  const definitionKey = session.definitionKey || ctx.systemKey;
+  const stored = {
+    channelTarget: definitionKey,
+    definitionKey,
+    installationKey,
+    name: session.name,
+    displayName: session.displayName,
+    profile: session.profile || null,
+    allowExperimental: session.allowExperimental === true,
+    phase: session.phase,
+    helpMarkdown: session.helpMarkdown,
+    envelope: session.envelope,
+    slackAuthTicket: typeof session.slackAuthTicket === 'string' ? session.slackAuthTicket : undefined,
+    commandPrefix: trimSessionString(session.commandPrefix),
+    packageVersion: trimSessionString(session.packageVersion),
+    packageAppId: trimSessionString(session.packageAppId),
+    oauthPluginVaultReferenceId: trimSessionString(session.oauthPluginVaultReferenceId),
+    microsoftLoginUrl: trimSessionString(session.microsoftLoginUrl),
+    microsoftLoginUserCode: trimSessionString(session.microsoftLoginUserCode),
+    microsoftAuthConfigFallback: session.microsoftAuthConfigFallback === true ? true : undefined,
+    updatedAt: new Date().toISOString()
+  };
+  writeSessionFile(sessionPath(ctx), stored);
+  const extra = instanceSessionPath(ctx);
+  if (extra) {
+    writeSessionFile(extra, stored);
+  }
+  return stored;
+}
+
+/**
+ * @param {string} message
+ * @param {number} statusCode
+ * @returns {Error}
+ */
+function httpError(message, statusCode) {
+  const err = new Error(message);
+  err.statusCode = statusCode;
+  return err;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string|undefined}
+ */
+function trimSessionString(value) {
+  if (typeof value !== 'string' || !value.trim()) {
+    return undefined;
+  }
+  return value.trim();
+}
+
+/**
+ * @param {string} integrationRoot
+ * @param {string} folderName
+ * @returns {Object|null}
+ */
+function readNamedSession(integrationRoot, folderName) {
+  const filePath = path.join(integrationRoot, folderName, SESSION_FILE);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {Object|null} session
+ * @param {string} definitionKey
+ * @returns {boolean}
+ */
+function sessionMatchesDefinition(session, definitionKey) {
+  if (!session) {
+    return false;
+  }
+  const key = session.definitionKey || session.channelTarget;
+  return key === definitionKey;
+}
+
+/**
+ * Catalog GET uses the definition key; the session lives on the instance folder.
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @param {string} definitionKey
+ * @returns {Object|null}
+ */
+function readChannelInstallSessionForDefinition(ctx, definitionKey) {
+  const direct = readChannelInstallSession(ctx);
+  if (sessionMatchesDefinition(direct, definitionKey)) {
+    return direct;
+  }
+  const root = typeof ctx.getIntegrationRoot === 'function' ? ctx.getIntegrationRoot() : '';
+  if (!root || !fs.existsSync(root)) {
+    return direct;
+  }
+  return newestMatchingSession(root, definitionKey, direct);
+}
+
+/**
+ * @param {string} root
+ * @param {string} definitionKey
+ * @param {Object|null} seed
+ * @returns {Object|null}
+ */
+function newestMatchingSession(root, definitionKey, seed) {
+  let best = seed;
+  let bestAt = (seed && seed.updatedAt) || '';
+  for (const name of fs.readdirSync(root)) {
+    if (name !== definitionKey && !String(name).startsWith(`${definitionKey}-`)) {
+      continue;
+    }
+    const session = readNamedSession(root, name);
+    if (!sessionMatchesDefinition(session, definitionKey)) {
+      continue;
+    }
+    const updated = session.updatedAt || '';
+    if (!best || updated >= bestAt) {
+      best = session;
+      bestAt = updated;
+    }
+  }
+  return best;
+}
+
+/**
+ * @param {import('./workspace-context').WorkspaceContext} ctx
+ * @returns {Object}
+ */
+function requireChannelInstallSession(ctx) {
+  const session = readChannelInstallSession(ctx);
+  if (!session) {
+    throw httpError('Channel install session not found. POST install first.', 404);
+  }
+  return session;
+}
+
+module.exports = {
+  SESSION_FILE,
+  sessionPath,
+  readChannelInstallSession,
+  readChannelInstallSessionForDefinition,
+  writeChannelInstallSession,
+  requireChannelInstallSession,
+  httpError
+};

package/lib/programmatic/help-content/channel-onboarding.md

@@ -18,6 +18,8 @@ Complete validate and upload for the target systemKey so the dataplane exposes M
 | slack | Slack workspace assistant |
 | microsoft-copilot | Microsoft Copilot package (runtime-orchestration MCP) |
 | chatgpt | ChatGPT custom MCP app (runtime-orchestration) |
+| claude | Claude custom connector (runtime-orchestration) |
+| mcp-client | Developer MCP client (Cursor, VS Code, Copilot IDE profile) |
 | web-embed | Experimental embedded web assistant |
 
 Each target requires credentials and deploy approval. Read topic connectedSystemUi after upload for dataplane handoff paths.

package/lib/programmatic/help-content/cip-overview.md

@@ -10,7 +10,9 @@ Every operation contains an ordered steps array. Each step is a single keyed obj
 
 ## Common step patterns
 
-Fetch resolves data from OpenAPI references, raw HTTP, or another datasource. Map applies fieldMappings to normalize vendor payloads. Filter applies optional ABAC or JMESPath expressions. Output emits records for sync and storage.
+Fetch resolves data from OpenAPI references, raw HTTP, another datasource, a viewpoint SQL query, or local record storage. Map applies fieldMappings to normalize vendor payloads. Filter applies optional ABAC or JMESPath expressions. Output emits records for sync and storage.
+
+`fetch.source` is a closed enum: `openapi`, `http`, `datasource`, `viewpoint`, `record`. The fetch token `record` is singular; `output.mode` stays plural `records`. Persist vs read on `record` follows operation `shape` (`create` or `update`), not the capability key. CIP `fetch.source` compiles to COM `source`.
 
 Paginate handles cursor, page, or offset strategies for list operations. Python inline runs sandboxed transforms when declarative steps are insufficient.