@aifabrix/builder 2.52.1 → 2.53.1

package/lib/external-system/deploy.js

@@ -131,19 +131,6 @@ async function fetchDataplaneDeployReadiness(controllerUrl, environment, authCon
   }
 }
 
-/**
- * Deploys via controller and prints readiness summary (config / deployment / runtime layers).
- * @async
- * @param {Object} manifest - Controller manifest
- * @param {string} controllerUrl - Controller base URL
- * @param {string} environment - Environment key
- * @param {Object} authConfig - Authentication configuration
- * @param {Object} options - Deployment options (poll, probe, probeTimeout)
- * @returns {Promise<Object>} Deployment result
- */
-/**
- * @param {Object} deploymentOutcome - from parseControllerDeploymentOutcome
- */
 /**
  * Optional dataplane validation/run after external deploy (--probe).
  * @async
@@ -202,12 +189,21 @@ function logImmediateControllerDeploymentOutcome(deploymentOutcome) {
   logger.log(chalk.gray('   Check the controller deployment job or logs for details.'));
 }
 
+/** External deploy waits on controller → dataplane publish job (may run prove gates / tests). */
+const EXTERNAL_DEPLOY_POLL_INTERVAL_MS = 2000;
+/** 300 × 2s ≈ 10 minutes — must cover controller publish-job max wait with gates. */
+const EXTERNAL_DEPLOY_POLL_MAX_ATTEMPTS = 300;
+
 function buildExternalDeployPollOpts(options) {
   return {
     ...options,
     poll: true,
-    pollInterval: options.pollInterval !== undefined ? options.pollInterval : 500,
-    pollMaxAttempts: options.pollMaxAttempts !== undefined ? options.pollMaxAttempts : 22,
+    pollInterval:
+      options.pollInterval !== undefined ? options.pollInterval : EXTERNAL_DEPLOY_POLL_INTERVAL_MS,
+    pollMaxAttempts:
+      options.pollMaxAttempts !== undefined
+        ? options.pollMaxAttempts
+        : EXTERNAL_DEPLOY_POLL_MAX_ATTEMPTS,
     silentPoll: options.silentPoll === true
   };
 }
@@ -381,12 +377,6 @@ function wrapDeployExternalSystemError(error, appName) {
   return new Error(message);
 }
 
-/**
- * @async
- * @param {string} appName
- * @param {Object} options
- * @returns {Promise<Object>}
- */
 /**
  * @param {string} appName
  * @param {Object} options

package/lib/integration-definition/apply.js

@@ -5,9 +5,8 @@
 
 'use strict';
 
-const fs = require('../internal/fs-real-sync');
-const fsp = require('fs').promises;
 const path = require('path');
+const fsReal = require('../internal/fs-real-sync');
 const { getIntegrationPath } = require('../utils/paths');
 const { validateIntegrationDefinition } = require('./validate');
 
@@ -20,7 +19,7 @@ const STAMP_FILE = '.aifabrix-integration-definition.json';
 async function readStamp(dir) {
   const stampPath = path.join(dir, STAMP_FILE);
   try {
-    const raw = await fsp.readFile(stampPath, 'utf8');
+    const raw = fsReal.readFileSync(stampPath, 'utf8');
     return JSON.parse(raw);
   } catch (err) {
     if (err && err.code === 'ENOENT') {
@@ -339,22 +338,22 @@ function buildPackageArtifacts(bid, systemKey, enrichOptions = {}) {
  * @returns {Promise<void>}
  */
 async function writePackageArtifacts(outDir, artifacts) {
-  await fsp.mkdir(outDir, { recursive: true });
-  await fsp.writeFile(
+  fsReal.mkdirSync(outDir, { recursive: true });
+  fsReal.writeFileSync(
     path.join(outDir, 'application.json'),
     JSON.stringify(artifacts.application, null, 2),
     'utf8'
   );
-  await fsp.writeFile(
+  fsReal.writeFileSync(
     path.join(outDir, artifacts.systemFile),
     JSON.stringify(artifacts.system, null, 2),
     'utf8'
   );
   for (const file of artifacts.dsFiles) {
-    await fsp.writeFile(path.join(outDir, file.name), JSON.stringify(file.body, null, 2), 'utf8');
+    fsReal.writeFileSync(path.join(outDir, file.name), JSON.stringify(file.body, null, 2), 'utf8');
   }
-  await fsp.writeFile(path.join(outDir, 'env.template'), artifacts.envTemplate, 'utf8');
-  await fsp.writeFile(
+  fsReal.writeFileSync(path.join(outDir, 'env.template'), artifacts.envTemplate, 'utf8');
+  fsReal.writeFileSync(
     path.join(outDir, STAMP_FILE),
     JSON.stringify(artifacts.nextStamp, null, 2),
     'utf8'
@@ -390,7 +389,7 @@ function idempotentResult(stamp, bid, outDir, systemKey) {
       stamp &&
       stamp.definitionId === bid.definitionId &&
       stamp.definitionHash === bid.definitionHash &&
-      fs.existsSync(path.join(outDir, 'application.json'))
+      fsReal.existsSync(path.join(outDir, 'application.json'))
     )
   ) {
     return null;
@@ -434,11 +433,10 @@ async function applyIntegrationDefinition(bidInput, options = {}) {
     return early;
   }
   assertApplyAllowed(bid, stamp);
-  // Prefer explicit openapiBaseDir; else ship-local enrichment specs (not caller cwd).
-  // Suite/builder-api apply runs with workspace cwd and must still resolve openapiSourceRef.
-  const defaultOpenapiBaseDir = path.join(__dirname, 'openapi-enrichment');
+  // Prefer explicit openapiBaseDir (workspace integration/<systemKey>/openapi
+  // from 517.2 persist). Do not default product apply to ship-local enrichment.
   const artifacts = buildPackageArtifacts(bid, systemKey, {
-    baseDir: options.openapiBaseDir || options.baseDir || defaultOpenapiBaseDir
+    baseDir: options.openapiBaseDir || options.baseDir
   });
   const fileList = [
     'application.json',

package/lib/integration-definition/enrich-openapi-operations.js

@@ -5,8 +5,8 @@
 
 'use strict';
 
-const fs = require('../internal/fs-real-sync');
 const path = require('path');
+const fsReal = require('../internal/fs-real-sync');
 const {
   maybeEnrichCrmStyleFieldMappings
 } = require('./enrich-crm-field-mappings');
@@ -26,22 +26,21 @@ function resolveOpenApiRefPath(ref, baseDir) {
   if (path.isAbsolute(trimmed)) {
     return trimmed;
   }
-  const moduleEnrichmentDir = path.join(__dirname, 'openapi-enrichment');
-  // Prefer caller baseDir, then bundled openapi-enrichment, then cwd.
-  // Cwd last avoids false misses when Jest mocks fs.existsSync but readFileSync
-  // remains real (fallback would otherwise point at <cwd>/<ref>).
+  // Product resolve root is workspace openapi/ (517.2) via explicit baseDir.
+  // No ship-local vendor enrichment packs under lib/.
   const candidates = [
     baseDir ? path.resolve(baseDir, trimmed) : null,
-    path.join(moduleEnrichmentDir, trimmed),
-    path.join(moduleEnrichmentDir, path.basename(trimmed)),
+    baseDir ? path.resolve(baseDir, path.basename(trimmed)) : null,
     path.resolve(process.cwd(), trimmed)
   ].filter(Boolean);
   for (const candidate of candidates) {
-    if (fs.existsSync(candidate)) {
+    if (fsReal.existsSync(candidate)) {
       return candidate;
     }
   }
-  return candidates[0];
+  throw new Error(
+    `OpenAPI enrichment document not found for ref "${trimmed}". Tried: ${candidates.join(', ')}`
+  );
 }
 
 /**
@@ -51,7 +50,7 @@ function resolveOpenApiRefPath(ref, baseDir) {
  */
 function loadOpenApiDocument(ref, baseDir) {
   const abs = resolveOpenApiRefPath(ref, baseDir);
-  const raw = fs.readFileSync(abs, 'utf8');
+  const raw = fsReal.readFileSync(abs, 'utf8');
   const doc = JSON.parse(raw);
   if (!doc || typeof doc !== 'object' || !doc.paths || typeof doc.paths !== 'object') {
     throw new Error(`OpenAPI document missing paths: ${abs}`);

package/lib/lab/package-parity-score.js

@@ -0,0 +1,417 @@
+/**
+ * Package-level parity score between a reference integration dir and a candidate.
+ * Lab/DoD aid only — reference packages are score baselines, never generation input.
+ *
+ * @fileoverview Structured parity facets for two integration package directories
+ */
+
+'use strict';
+
+const fs = require('../internal/fs-real-sync');
+const path = require('path');
+const { loadConfigFile } = require('../utils/config-format');
+
+const DATASOURCE_FILE_RE = /datasource/i;
+
+/**
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function listJsonFiles(dir) {
+  if (!dir || !fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+    return [];
+  }
+  return fs
+    .readdirSync(dir)
+    .filter((name) => name.endsWith('.json') || name.endsWith('.yaml') || name.endsWith('.yml'))
+    .map((name) => path.join(dir, name))
+    .sort();
+}
+
+/**
+ * @param {string} dir
+ * @returns {Object[]}
+ */
+function loadDatasourceManifests(dir) {
+  const out = [];
+  for (const filePath of listJsonFiles(dir)) {
+    const base = path.basename(filePath);
+    if (!DATASOURCE_FILE_RE.test(base)) {
+      continue;
+    }
+    try {
+      const parsed = loadConfigFile(filePath);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        out.push({ filePath, base, manifest: parsed });
+      }
+    } catch (_err) {
+      // Skip unreadable files; facet will report incomplete package
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {Object} manifest
+ * @returns {string}
+ */
+function datasourceKey(manifest) {
+  return String(manifest.key || '').trim();
+}
+
+/**
+ * @param {Object} manifest
+ * @returns {string[]}
+ */
+function capabilityKeys(manifest) {
+  const caps = manifest.capabilities;
+  if (!Array.isArray(caps)) {
+    return [];
+  }
+  return caps
+    .map((row) => (row && typeof row === 'object' ? String(row.key || '').trim() : ''))
+    .filter(Boolean)
+    .sort();
+}
+
+/**
+ * @param {string} dir
+ * @returns {string[]}
+ */
+function openapiBasenames(dir) {
+  const openapiDir = path.join(dir, 'openapi');
+  if (!fs.existsSync(openapiDir) || !fs.statSync(openapiDir).isDirectory()) {
+    return [];
+  }
+  return fs
+    .readdirSync(openapiDir)
+    .filter((name) => /\.(json|yaml|yml)$/i.test(name))
+    .map((name) => name.toLowerCase())
+    .sort();
+}
+
+/**
+ * @param {Object} manifest
+ * @returns {{ metadataSchema: boolean, fieldMappings: boolean, foreignKeys: boolean, exposed: boolean, cip: boolean }}
+ */
+function contractSurfaceFlags(manifest) {
+  const execution = manifest.execution && typeof manifest.execution === 'object' ? manifest.execution : {};
+  const cip = execution.cip && typeof execution.cip === 'object' ? execution.cip : null;
+  return {
+    metadataSchema: Boolean(manifest.metadataSchema),
+    fieldMappings: Boolean(manifest.fieldMappings),
+    foreignKeys: Boolean(manifest.foreignKeys),
+    exposed: Boolean(manifest.exposed),
+    cip: Boolean(cip && cip.operations)
+  };
+}
+
+/**
+ * @param {boolean} ok
+ * @param {string} id
+ * @param {string} detail
+ * @param {Object} [extra]
+ * @returns {Object}
+ */
+function facet(ok, id, detail, extra = {}) {
+  return { id, ok: Boolean(ok), detail, ...extra };
+}
+
+/**
+ * @param {string} absDir
+ * @returns {boolean}
+ */
+function isPackageDir(absDir) {
+  return fs.existsSync(absDir) && fs.statSync(absDir).isDirectory();
+}
+
+/**
+ * @param {Object[]} rows
+ * @returns {Map<string, Object>}
+ */
+function indexDatasourcesByKey(rows) {
+  const byKey = new Map();
+  for (const row of rows) {
+    const key = datasourceKey(row.manifest);
+    if (key) {
+      byKey.set(key, row);
+    }
+  }
+  return byKey;
+}
+
+/**
+ * @param {string} refAbs
+ * @param {string} candAbs
+ * @param {Object[]} facets
+ */
+function pushPresenceFacets(refAbs, candAbs, facets) {
+  const refExists = isPackageDir(refAbs);
+  const candExists = isPackageDir(candAbs);
+  facets.push(
+    facet(refExists, 'referencePackagePresent', refExists ? 'Reference package directory found' : 'Reference package directory missing')
+  );
+  facets.push(
+    facet(candExists, 'candidatePackagePresent', candExists ? 'Candidate package directory found' : 'Candidate package directory missing')
+  );
+  return { refExists, candExists };
+}
+
+/**
+ * @param {string} refAbs
+ * @param {string} candAbs
+ * @param {Object[]} facets
+ */
+function pushSystemManifestFacet(refAbs, candAbs, facets) {
+  const refHasSystem = listJsonFiles(refAbs).some((f) => /system/i.test(path.basename(f)));
+  const candHasSystem = listJsonFiles(candAbs).some((f) => /system/i.test(path.basename(f)));
+  facets.push(
+    facet(
+      !refHasSystem || candHasSystem,
+      'systemManifest',
+      candHasSystem ? 'Candidate has a system manifest file' : 'Candidate missing system manifest while reference has one'
+    )
+  );
+}
+
+/**
+ * @param {Map<string, Object>} refByKey
+ * @param {Map<string, Object>} candByKey
+ * @param {Object[]} facets
+ * @returns {string[]}
+ */
+function pushDatasourceCoverageFacet(refByKey, candByKey, facets) {
+  const missingDatasourceKeys = [...refByKey.keys()].filter((key) => !candByKey.has(key)).sort();
+  facets.push(
+    facet(
+      missingDatasourceKeys.length === 0 && refByKey.size > 0,
+      'datasourceKeyCoverage',
+      missingDatasourceKeys.length === 0
+        ? `Candidate covers ${refByKey.size} reference datasource key(s)`
+        : `Missing datasource keys: ${missingDatasourceKeys.join(', ')}`,
+      { missingDatasourceKeys, referenceCount: refByKey.size, candidateCount: candByKey.size }
+    )
+  );
+  return missingDatasourceKeys;
+}
+
+/**
+ * @param {string} refAbs
+ * @param {string} candAbs
+ * @param {Object[]} facets
+ */
+function pushOpenapiFacet(refAbs, candAbs, facets) {
+  const refOpenapi = openapiBasenames(refAbs);
+  const candOpenapi = new Set(openapiBasenames(candAbs));
+  const missingOpenapi = refOpenapi.filter((name) => !candOpenapi.has(name));
+  facets.push(
+    facet(
+      refOpenapi.length === 0 || missingOpenapi.length === 0,
+      'openapiDir',
+      refOpenapi.length === 0
+        ? 'Reference has no openapi/ files — facet skipped'
+        : missingOpenapi.length === 0
+          ? `Candidate has ${refOpenapi.length} matching openapi basename(s)`
+          : `Missing openapi files: ${missingOpenapi.join(', ')}`,
+      { missingOpenapi }
+    )
+  );
+}
+
+/**
+ * @param {string} key
+ * @param {Object} refManifest
+ * @param {Object} candManifest
+ * @param {Object[]} capabilityGaps
+ * @returns {boolean}
+ */
+function collectCapabilityGaps(key, refManifest, candManifest, capabilityGaps) {
+  const refCaps = new Set(capabilityKeys(refManifest));
+  const candCaps = new Set(capabilityKeys(candManifest));
+  const missingCaps = [...refCaps].filter((c) => !candCaps.has(c)).sort();
+  if (!missingCaps.length) {
+    return true;
+  }
+  capabilityGaps.push({ datasourceKey: key, missingCapabilityKeys: missingCaps });
+  return false;
+}
+
+/**
+ * @param {string} key
+ * @param {Object} refManifest
+ * @param {Object} candManifest
+ * @param {Object[]} resourceTypeGaps
+ * @returns {boolean}
+ */
+function collectResourceTypeGaps(key, refManifest, candManifest, resourceTypeGaps) {
+  const refRt = String(refManifest.resourceType || '').trim();
+  const candRt = String(candManifest.resourceType || '').trim();
+  if (!(refRt && candRt && refRt !== candRt)) {
+    return true;
+  }
+  resourceTypeGaps.push({ datasourceKey: key, reference: refRt, candidate: candRt });
+  return false;
+}
+
+/**
+ * @param {string} key
+ * @param {Object} refManifest
+ * @param {Object} candManifest
+ * @param {Object[]} surfaceGaps
+ * @returns {boolean}
+ */
+function collectSurfaceGaps(key, refManifest, candManifest, surfaceGaps) {
+  const refFlags = contractSurfaceFlags(refManifest);
+  const candFlags = contractSurfaceFlags(candManifest);
+  let ok = true;
+  for (const [surface, needed] of Object.entries(refFlags)) {
+    if (needed && !candFlags[surface]) {
+      ok = false;
+      surfaceGaps.push({ datasourceKey: key, surface });
+    }
+  }
+  return ok;
+}
+
+/**
+ * @param {Map<string, Object>} refByKey
+ * @param {Map<string, Object>} candByKey
+ * @returns {{ capabilityOk: boolean, capabilityGaps: Object[], resourceTypeOk: boolean, resourceTypeGaps: Object[], surfacesOk: boolean, surfaceGaps: Object[] }}
+ */
+function compareSharedDatasources(refByKey, candByKey) {
+  const capabilityGaps = [];
+  const resourceTypeGaps = [];
+  const surfaceGaps = [];
+  let capabilityOk = true;
+  let resourceTypeOk = true;
+  let surfacesOk = true;
+
+  for (const [key, refRow] of refByKey.entries()) {
+    const candRow = candByKey.get(key);
+    if (!candRow) {
+      continue;
+    }
+    if (!collectCapabilityGaps(key, refRow.manifest, candRow.manifest, capabilityGaps)) {
+      capabilityOk = false;
+    }
+    if (!collectResourceTypeGaps(key, refRow.manifest, candRow.manifest, resourceTypeGaps)) {
+      resourceTypeOk = false;
+    }
+    if (!collectSurfaceGaps(key, refRow.manifest, candRow.manifest, surfaceGaps)) {
+      surfacesOk = false;
+    }
+  }
+
+  return { capabilityOk, capabilityGaps, resourceTypeOk, resourceTypeGaps, surfacesOk, surfaceGaps };
+}
+
+/**
+ * @param {ReturnType<typeof compareSharedDatasources>} compared
+ * @param {Object[]} facets
+ */
+function pushSharedDatasourceFacets(compared, facets) {
+  facets.push(
+    facet(
+      compared.capabilityOk,
+      'capabilityKeys',
+      compared.capabilityOk ? 'Capability keys cover reference on shared datasources' : 'Missing capability keys on shared datasources',
+      { gaps: compared.capabilityGaps }
+    )
+  );
+  facets.push(
+    facet(
+      compared.resourceTypeOk,
+      'resourceTypes',
+      compared.resourceTypeOk ? 'resourceType matches on shared datasources' : 'resourceType mismatches on shared datasources',
+      { gaps: compared.resourceTypeGaps }
+    )
+  );
+  facets.push(
+    facet(
+      compared.surfacesOk,
+      'contractSurfaces',
+      compared.surfacesOk ? 'Contract surfaces present where reference declares them' : 'Missing contract surfaces vs reference',
+      { gaps: compared.surfaceGaps }
+    )
+  );
+}
+
+/**
+ * @param {Object[]} facets
+ * @param {string[]} missingDatasourceKeys
+ * @param {string} refAbs
+ * @param {string} candAbs
+ * @returns {Object}
+ */
+function buildParityReport(facets, missingDatasourceKeys, refAbs, candAbs) {
+  const scored = facets.filter((f) => f.id !== 'referencePackagePresent');
+  const passed = scored.filter((f) => f.ok).length;
+  const score = scored.length === 0 ? 0 : Math.round((passed / scored.length) * 100);
+  const identical = facets.every((f) => f.ok) && missingDatasourceKeys.length === 0;
+  return {
+    score,
+    maxScore: 100,
+    identical,
+    referenceDir: refAbs,
+    candidateDir: candAbs,
+    goldIsScoreOnly: true,
+    facets,
+    missingDatasourceKeys,
+    summary: identical
+      ? 'Candidate matches reference facets (score baseline only — not generation input)'
+      : `Parity score ${score}/100 — reference is score-only, never generation input`
+  };
+}
+
+/**
+ * Score candidate integration package directory against a reference package directory.
+ *
+ * @param {string} referenceDir Absolute or relative path to reference package (score baseline only)
+ * @param {string} candidateDir Absolute or relative path to candidate package
+ * @returns {{
+ *   score: number,
+ *   maxScore: number,
+ *   identical: boolean,
+ *   referenceDir: string,
+ *   candidateDir: string,
+ *   goldIsScoreOnly: true,
+ *   facets: Object[],
+ *   missingDatasourceKeys: string[],
+ *   summary: string
+ * }}
+ */
+function scorePackageParity(referenceDir, candidateDir) {
+  const refAbs = path.resolve(referenceDir);
+  const candAbs = path.resolve(candidateDir);
+  const facets = [];
+  const { refExists, candExists } = pushPresenceFacets(refAbs, candAbs, facets);
+
+  if (!refExists || !candExists) {
+    return {
+      score: 0,
+      maxScore: 100,
+      identical: false,
+      referenceDir: refAbs,
+      candidateDir: candAbs,
+      goldIsScoreOnly: true,
+      facets,
+      missingDatasourceKeys: [],
+      summary: 'Package directories incomplete — score 0 (no silent 100%)'
+    };
+  }
+
+  pushSystemManifestFacet(refAbs, candAbs, facets);
+  const refByKey = indexDatasourcesByKey(loadDatasourceManifests(refAbs));
+  const candByKey = indexDatasourcesByKey(loadDatasourceManifests(candAbs));
+  const missingDatasourceKeys = pushDatasourceCoverageFacet(refByKey, candByKey, facets);
+  pushOpenapiFacet(refAbs, candAbs, facets);
+  pushSharedDatasourceFacets(compareSharedDatasources(refByKey, candByKey), facets);
+  return buildParityReport(facets, missingDatasourceKeys, refAbs, candAbs);
+}
+
+module.exports = {
+  scorePackageParity,
+  loadDatasourceManifests,
+  openapiBasenames,
+  contractSurfaceFlags
+};

package/lib/programmatic/capability-registry.js

@@ -12,6 +12,7 @@
 const CAPABILITIES = Object.freeze([
   { method: 'GET', route: '/workspaces/me/systems', handlerId: 'listSystems', operationType: 'workspace.read', mutating: false },
   { method: 'POST', route: '/workspaces/me/systems', handlerId: 'createSystem', operationType: 'workspace.write', mutating: true },
+  { method: 'POST', route: '/systems/:systemKey/openapi/persist-supplied', handlerId: 'persistSuppliedOpenApi', operationType: 'workspace.write', mutating: true },
   { method: 'GET', route: '/workspaces/me/systems/:systemKey', handlerId: 'getSystemManifest', operationType: 'workspace.read', mutating: false },
   { method: 'DELETE', route: '/workspaces/me/systems/:systemKey', handlerId: 'deleteSystem', operationType: 'workspace.write', mutating: true },
   { method: 'POST', route: '/systems/:systemKey/wizard', handlerId: 'runWizard', operationType: 'plan', mutating: true },

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

@@ -0,0 +1,35 @@
+# Channel onboarding from your work list
+
+Onboard an assistant channel after your external system is published from a Builder workspace.
+
+## Work list
+
+Call GET workspaces/me/systems to list integration keys in your authenticated workspace. Each entry is a draft or published external system you are building.
+
+## Publish before channel
+
+Complete validate and upload for the target systemKey so the dataplane exposes MCP tools and connected-system UI. Use repair with bearer-forward auth for facade APIs. Apply platform RBAC when the integration is a platform orchestration API.
+
+## Choose a channel target
+
+| Target | Use when |
+| --- | --- |
+| teams-bot | Microsoft Teams employee assistant |
+| slack | Slack workspace assistant |
+| microsoft-copilot | Microsoft Copilot package (runtime-orchestration MCP) |
+| chatgpt | ChatGPT custom MCP app (runtime-orchestration) |
+| web-embed | Experimental embedded web assistant |
+
+Each target requires credentials and deploy approval. Read topic connectedSystemUi after upload for dataplane handoff paths.
+
+## Recommended sequence
+
+1. GET help topic overview and platformRoles when scoping RBAC.
+2. GET workspaces/me/systems — pick or create systemKey.
+3. Run wizard, repair, validate, upload via Builder API.
+4. Scaffold channel integration with the CLI channel scaffold command for the chosen target.
+5. Register the channel on the deployed application with channel add.
+
+## Governance before go-live
+
+Confirm resourceType catalog keys match business entities. Add dimensions on record and document datasources before protection. Scope system.subscriptions to business resource types, not generic placeholders.

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

@@ -0,0 +1,27 @@
+# CIP execution overview
+
+Composable Integration Pipeline is the declarative execution engine for datasource operations. Most external datasources use engine cip under the datasource.execution section.
+
+## Structure
+
+Each operation under execution.cip.operations is a named map entry such as list, get, create, update, or delete. Custom operation names are allowed when they match capability keys.
+
+Every operation contains an ordered steps array. Each step is a single keyed object: fetch, paginate, map, filter, output, or pythonInline.
+
+## 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.
+
+Paginate handles cursor, page, or offset strategies for list operations. Python inline runs sandboxed transforms when declarative steps are insufficient.
+
+## Quality practices
+
+Choose entityType and resourceType before authoring execution steps. Align openapi.operations keys with capabilities and fetch openapiRef values.
+
+After changing metadata or capabilities, run repair hooks for fieldMappings, expose, and rbac before validate and test.
+
+Use validate responses as the authoritative guide when step properties fail schema checks. Request topic schemaCatalog for property indexes, then topic section for governed fragments.
+
+## Related sections
+
+datasource.execution, datasource.capabilities, datasource.fieldMappings, datasource.openapiOperations, datasource.metadata