@aifabrix/builder 2.52.0 → 2.53.0

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/builder-api-request.js

@@ -19,7 +19,11 @@ const { withRequestTimeout } = require('./request-timeout');
  * @returns {boolean}
  */
 function requiresAuth(capability) {
-  return capability.handlerId !== 'health' && capability.handlerId !== 'ready';
+  return (
+    capability.handlerId !== 'health' &&
+    capability.handlerId !== 'ready' &&
+    capability.handlerId !== 'getBuilderHelp'
+  );
 }
 
 /**

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

@@ -8,7 +8,7 @@
 
 'use strict';
 
-const fs = require('fs');
+const fs = require('../internal/fs-real-sync');
 const path = require('path');
 const { buildHelpEnvelope } = require('./builder-help-envelope');
 const { listPlatformRoles } = require('./platform-rbac-catalog');
@@ -168,5 +168,6 @@ module.exports = {
   buildPlatformRolesTopic,
   buildResourceTypeCatalogTopic,
   buildDimensionsGuideTopic,
-  buildChannelOnboardingTopic
+  buildChannelOnboardingTopic,
+  loadResourceTypeCatalog
 };

package/lib/programmatic/capability-registry.js

@@ -12,9 +12,17 @@
 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 },
+  {
+    method: 'POST',
+    route: '/systems/:systemKey/integration-definition/apply',
+    handlerId: 'applyIntegrationDefinition',
+    operationType: 'plan',
+    mutating: true
+  },
   { method: 'POST', route: '/systems/:systemKey/repair', handlerId: 'runRepair', operationType: 'plan', mutating: true },
   { method: 'GET', route: '/systems/:systemKey/manifest/sections', handlerId: 'listManifestSections', operationType: 'workspace.read', mutating: false },
   { method: 'GET', route: '/systems/:systemKey/manifest/section/:sectionKey', handlerId: 'getManifestSection', operationType: 'workspace.read', mutating: false },
@@ -63,8 +71,20 @@ const CAPABILITIES = Object.freeze([
   { method: 'POST', route: '/systems/:systemKey/repository/create-review', handlerId: 'runRepositoryCreateReview', operationType: 'repository', mutating: true },
   { method: 'GET', route: '/systems/:systemKey/repository/status', handlerId: 'getRepositoryStatus', operationType: 'repository.read', mutating: false },
   { method: 'POST', route: '/systems/:systemKey/repository/dispatch-pipeline', handlerId: 'runRepositoryDispatchPipeline', operationType: 'repository', mutating: true },
+  { method: 'POST', route: '/systems/:systemKey/channels/package', handlerId: 'buildChannelPackage', operationType: 'channel', mutating: true },
+  { method: 'GET', route: '/systems/:systemKey/channels/package', handlerId: 'getChannelPackageSummary', operationType: 'channel.read', mutating: false },
+  { 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: '/health', handlerId: 'health', operationType: 'infra', mutating: false },
   { method: 'GET', route: '/health/ready', handlerId: 'ready', operationType: 'infra', mutating: false },
+  {
+    method: 'GET',
+    route: '/help',
+    handlerId: 'getBuilderHelp',
+    operationType: 'help.read',
+    mutating: false
+  },
   { method: 'GET', route: '/evidence/:roleKey/metadata', handlerId: 'getEvidenceMetadata', operationType: 'evidence.read', mutating: false },
   { method: 'GET', route: '/evidence/:roleKey/download', handlerId: 'downloadEvidence', operationType: 'evidence.read', mutating: false },
   { method: 'POST', route: '/evidence/:roleKey/upload', handlerId: 'uploadEvidenceCandidates', operationType: 'evidence.write', 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

package/lib/programmatic/help-content/connected-system-ui.md

@@ -0,0 +1,70 @@
+# Connected Systems UI navigation
+
+Use this topic after validate, test, test-integration, and upload succeed without resolved integration secrets in Builder API scope.
+
+## Post-upload authentication handoff
+
+Upload publishes the external system manifest. The user adds **live secrets only** in the dataplane Connected Systems Authentication tab — not by pasting tokens into Builder API or workspace files.
+
+Authentication is declared on the **external system** manifest (`authentications[]` with usage slots, or legacy `authentication` normalized by repair), not on individual datasource manifests. Datasources inherit linked system credentials at sync and CIP runtime.
+
+### Variables vs secrets (manifest split)
+
+| Manifest path | When to set | After upload |
+| --- | --- | --- |
+| `authentication.credential.variables` | During manifest editing (Builder API) | Published and **pre-filled** in Authentication UI — user does not re-enter |
+| `authentication.credential.security` | kv:// placeholders in manifest only | User adds **live secret values** in Authentication UI (for example token, apiKey, clientSecret) |
+
+**Enterprise-ready pattern:** put baseUrl, headerName, tokenUrl, prefix, testEndpoint, and similar non-secrets in `variables` before upload. After upload, the user opens Authentication and adds only the token or other required secret.
+
+Before prompting the user:
+
+1. Read `authentications[]` usage slots from the published system manifest (prefer over legacy `authentication`).
+2. For each slot, read `authType` and `credential.method` when applicable.
+3. Confirm `variables` are already complete in the manifest — do not ask the user to supply them again.
+4. Tell the user which **secret keys only** they must add in the UI (`requiredSecretKeys`).
+5. When webhook or syncBridge is enabled, also hand off to datasource **Sync** tab (`tab=sync`) for activation guide URLs.
+
+## Authentication modes (authType)
+
+| authType | Where in manifest | User action in UI |
+| --- | --- | --- |
+| `credential` | `authentication.credential` | Add secret values only; variables already pre-filled |
+| `apiProvider` | `authentication.apiProvider.apiProviderKey` | Link the Miso API Provider — no local vendor secrets |
+| `none` | `authentication.authType` only | No credential handoff unless live tests fail for other reasons |
+
+## Credential methods (when authType is credential)
+
+Methods come from `external-system.schema.json` (`authentication.credential.method`). User adds **secrets only** after upload:
+
+| method | User adds in UI (secrets only) | Already in manifest variables |
+| --- | --- | --- |
+| `oauth2` | clientSecret (clientId if empty) | baseUrl, tokenUrl, grantType, scope |
+| `aad` | clientSecret (clientId if empty) | baseUrl, tokenUrl, tenantId, grantType |
+| `apikey` | apiKey (token) | baseUrl, headerName, prefix, testEndpoint |
+| `bearerToken` | token | baseUrl, headerName, prefix, testEndpoint |
+| `basic` | username, password | baseUrl, testEndpoint |
+| `queryParam` | paramValue | baseUrl, paramName, testEndpoint |
+| `oidc` | any remaining OIDC secrets shown | openIdConfigUrl, clientId |
+| `hmac` | signingSecret | algorithm, signature headers |
+| `none` | none | — |
+
+Use optional query params `authType` and `credentialMethod` on this topic to get `manifestHandoff.promptHints` tailored to the manifest.
+
+## URL structure
+
+Combine `{dataplanePublicBase}` with a relative path:
+
+- System: `/connected-systems/{systemKey}?tab=authentication`
+- Datasource: `/connected-systems/{systemKey}/datasources/{datasourceKey}?tab={tab}`
+
+Omit `?tab=` for the default Overview tab on each level. Tab values are case-insensitive; aliases are listed in the structured `systemTabs` and `datasourceTabs` arrays on this topic.
+
+## Typical tabs after publish
+
+| Goal | System tab value |
+| --- | --- |
+| Add token / secrets | `authentication` |
+| Review datasources | `datasources` or `business-entities` |
+| Sync / webhook activation | Open datasource path with `tab=sync` |
+| Execution logs | Open datasource path with `tab=logs` |

package/lib/programmatic/help-content/dimensions-guide.md

@@ -0,0 +1,23 @@
+# Dimensions and ABAC grounding
+
+Dimensions are governance attributes on datasource manifests. They map normalized metadata paths to ABAC policies, protection rules, and subscription filters.
+
+## When dimensions apply
+
+Use dimensions on recordStorage, documentStorage, and serviceContract datasources. entityType none orchestration datasources must not declare fieldMappings.dimensions.
+
+## Authoring rules
+
+Declare dimensions at fieldMappings.dimensions with values pointing to metadata paths, such as metadata.country or metadata.owner. Match metadataSchema properties so protection and sync can evaluate grants.
+
+Ask the user for business context before patching datasource.dimensions. Common dimensions include country, region, department, owner, sensitivity, siteId, and lifecycleStage.
+
+## Challenge patterns
+
+If a datasource uses resourceType customer but has no country or region dimension, ask whether geographic protection is required. If document libraries lack owner or sensitivity, ask before enabling protection.
+
+When foreignKeys link a child datasource to a parent, confirm whether dimensions should inherit from the parent record metadata.
+
+## Related sections
+
+datasource.dimensions, datasource.metadata, datasource.foreignKeys, datasource.governance, system.subscriptions