@aifabrix/builder 2.53.1 → 2.54.1

package/lib/programmatic/http-raw-response.js

@@ -0,0 +1,62 @@
+/**
+ * Raw HTTP outcomes for builder-api (markdown / ZIP bytes).
+ *
+ * @fileoverview Bypass JSON envelope for help.md and artifact downloads
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+/**
+ * @param {Object} params
+ * @param {string} params.contentType
+ * @param {string|Buffer} params.body
+ * @param {string} [params.fileName]
+ * @returns {{ __httpRaw: true, contentType: string, body: string|Buffer, fileName?: string }}
+ */
+function createHttpRawResult(params) {
+  const result = {
+    __httpRaw: true,
+    contentType: params.contentType,
+    body: params.body
+  };
+  if (params.fileName) {
+    result.fileName = params.fileName;
+  }
+  return result;
+}
+
+/**
+ * @param {unknown} result
+ * @returns {boolean}
+ */
+function isHttpRawResult(result) {
+  return Boolean(result && typeof result === 'object' && result.__httpRaw === true);
+}
+
+/**
+ * @param {import('http').ServerResponse} res
+ * @param {Object} raw
+ * @param {string} [requestId]
+ * @returns {void}
+ */
+function sendRaw(res, raw, requestId) {
+  const headers = {
+    'Content-Type': raw.contentType || 'application/octet-stream'
+  };
+  if (requestId) {
+    headers['X-Request-Id'] = requestId;
+  }
+  if (raw.fileName) {
+    headers['Content-Disposition'] = `attachment; filename="${raw.fileName}"`;
+  }
+  res.writeHead(200, headers);
+  res.end(raw.body);
+}
+
+module.exports = {
+  createHttpRawResult,
+  isHttpRawResult,
+  sendRaw
+};

package/lib/programmatic/openapi-channel-install-bindings.js

@@ -0,0 +1,179 @@
+/**
+ * OpenAPI operation bindings for generic channel install routes.
+ *
+ * @fileoverview Keep openapi-operation-bindings.js under the line limit
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const SYSTEM_KEY_PARAM = {
+  name: 'systemKey',
+  in: 'path',
+  required: true,
+  schema: { $ref: '#/components/schemas/SystemKey' },
+  description: 'Channel target key (slack, chatgpt, claude, microsoft-copilot, teams-bot, web-embed, mcp-client).'
+};
+
+const ARTIFACT_ID_PARAM = {
+  name: 'artifactId',
+  in: 'path',
+  required: true,
+  schema: { type: 'string' },
+  description: 'Artifact id from the help document download link (for example appPackage).'
+};
+
+const PROVIDER_PARAM = {
+  name: 'provider',
+  in: 'path',
+  required: true,
+  schema: { type: 'string' },
+  description: 'Vendor callback provider key (opaque; used only to resume install).'
+};
+
+/**
+ * @param {string} schemaName
+ * @param {boolean} [required]
+ * @returns {Object}
+ */
+function jsonRequestBody(schemaName, required = false) {
+  return {
+    required,
+    content: {
+      'application/json': {
+        schema: { $ref: `#/components/schemas/${schemaName}` }
+      }
+    }
+  };
+}
+
+/** @type {Record<string, Object>} */
+const CHANNEL_INSTALL_BINDINGS = {
+  listChannelTargets: {
+    queryParameters: [
+      {
+        name: 'allowExperimental',
+        in: 'query',
+        required: false,
+        schema: { type: 'boolean' },
+        description: 'When true, include experimental channel targets such as web-embed.'
+      }
+    ],
+    successResponse: 'ListChannelTargetsResponse'
+  },
+  getChannelDefinitionDetail: {
+    parameters: [
+      {
+        name: 'definitionKey',
+        in: 'path',
+        required: true,
+        schema: { $ref: '#/components/schemas/SystemKey' },
+        description: 'Channel definition key (catalog identity, not the Connected System instance key).'
+      }
+    ],
+    successResponse: 'ChannelDefinitionDetailResponse'
+  },
+  getChannelInstallation: {
+    parameters: [
+      {
+        name: 'definitionKey',
+        in: 'path',
+        required: true,
+        schema: { $ref: '#/components/schemas/SystemKey' },
+        description: 'Channel definition key.'
+      },
+      {
+        name: 'systemKey',
+        in: 'path',
+        required: true,
+        schema: { $ref: '#/components/schemas/SystemKey' },
+        description: 'Connected System instance key for this installation.'
+      }
+    ],
+    successResponse: 'ChannelInstallationDetailResponse'
+  },
+  runChannelInstall: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('ChannelInstallRequest', true),
+    successResponse: 'ChannelInstallHelpResponse'
+  },
+  getChannelInstall: {
+    parameters: [SYSTEM_KEY_PARAM],
+    queryParameters: [
+      {
+        name: 'verbose',
+        in: 'query',
+        required: false,
+        schema: { type: 'boolean' },
+        description: 'When true, return the full machine envelope (remainingSteps, useValues). Default JSON already includes phase and userActions.'
+      }
+    ],
+    successResponse: 'ChannelInstallHelpResponse'
+  },
+  getChannelInstallHelp: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'ChannelInstallHelpResponse',
+    extraSuccessContent: {
+      'text/markdown': {
+        schema: { type: 'string', description: 'Help document body (same remaining steps as INSTALL.md).' }
+      }
+    }
+  },
+  continueChannelInstall: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('ChannelInstallContinueRequest'),
+    successResponse: 'ChannelInstallHelpResponse'
+  },
+  listChannelArtifacts: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'ListChannelArtifactsResponse'
+  },
+  getChannelArtifact: {
+    parameters: [SYSTEM_KEY_PARAM, ARTIFACT_ID_PARAM],
+    successResponse: 'ChannelArtifactBytesResponse',
+    extraSuccessContent: {
+      'application/zip': {
+        schema: { type: 'string', format: 'binary', description: 'Package ZIP bytes.' }
+      }
+    }
+  },
+  getChannelCallback: {
+    parameters: [SYSTEM_KEY_PARAM, PROVIDER_PARAM],
+    successResponse: 'ChannelInstallHelpResponse'
+  },
+  postChannelCallback: {
+    parameters: [SYSTEM_KEY_PARAM, PROVIDER_PARAM],
+    requestBody: jsonRequestBody('EmptyRequestBody'),
+    successResponse: 'ChannelInstallHelpResponse'
+  },
+  buildChannelPackage: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('ChannelPackageRequest'),
+    successResponse: 'ChannelPackageResponse'
+  },
+  getChannelPackageSummary: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'ChannelPackageSummaryResponse'
+  },
+  getChannelPackageZip: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'ChannelPackageZipResponse'
+  },
+  getChannelBranding: {
+    parameters: [SYSTEM_KEY_PARAM],
+    successResponse: 'ChannelBrandingResponse'
+  },
+  patchChannelBranding: {
+    parameters: [SYSTEM_KEY_PARAM],
+    requestBody: jsonRequestBody('ChannelBrandingPatchRequest'),
+    successResponse: 'ChannelBrandingResponse'
+  },
+  getAuthPermissions: {
+    successResponse: 'AuthPermissionsResponse'
+  }
+};
+
+module.exports = {
+  CHANNEL_INSTALL_BINDINGS
+};

package/lib/programmatic/openapi-channel-install-schemas.js

@@ -0,0 +1,286 @@
+/**
+ * OpenAPI request/result schemas for generic channel install.
+ *
+ * @fileoverview Default HTTP is help markdown plus phase and userActions
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { frozenObject, schemaRef } = require('./openapi-schema-helpers');
+
+/** @type {Record<string, Object>} */
+const OPENAPI_CHANNEL_INSTALL_REQUEST_SCHEMAS = {
+  ChannelInstallRequest: frozenObject(
+    {
+      name: { type: 'string', minLength: 1 },
+      systemKey: { type: 'string' },
+      configuration: { type: 'object', additionalProperties: { type: 'string' } },
+      runtimeSystemKey: { type: 'string' },
+      force: { type: 'boolean' },
+      probe: { type: 'boolean' },
+      dryRun: { type: 'boolean' },
+      allowExperimental: { type: 'boolean' },
+      onboardUsers: { type: 'boolean' },
+      profile: { type: 'string' },
+      token: { type: 'string', minLength: 1 }
+    },
+    ['name']
+  ),
+  ChannelInstallContinueRequest: frozenObject({
+    token: { type: 'string', minLength: 1 },
+    retryLogin: { type: 'string' }
+  }),
+  ChannelPackageRequest: frozenObject({
+    name: { type: 'string' },
+    description: { type: 'string' },
+    baseName: { type: 'string' },
+    environment: { type: 'string' },
+    dataplaneUrl: { type: 'string', format: 'uri' },
+    dryRun: { type: 'boolean' },
+    branding: schemaRef('ChannelBrandingFields')
+  }),
+  ChannelBrandingPatchRequest: frozenObject({
+    displayName: { type: 'string' },
+    description: { type: 'string' },
+    iconColorPath: { type: 'string' },
+    iconOutlinePath: { type: 'string' }
+  })
+};
+
+/** @type {Record<string, Object>} */
+const OPENAPI_CHANNEL_INSTALL_RESULT_SCHEMAS = {
+  ChannelProvisioning: frozenObject(
+    {
+      mode: { type: 'string', enum: ['automatic', 'guided', 'cli'] }
+    },
+    ['mode']
+  ),
+  ChannelRuntimeTarget: frozenObject(
+    {
+      defaultSystemKey: { type: 'string' },
+      configurable: { type: 'boolean' },
+      systemKey: { type: 'string' }
+    },
+    ['defaultSystemKey']
+  ),
+  ChannelInstallationSummary: frozenObject(
+    {
+      count: { type: 'integer', minimum: 0 },
+      statusRollup: { type: 'string' }
+    },
+    ['count']
+  ),
+  ChannelInstallationRow: frozenObject(
+    {
+      key: { type: 'string' },
+      displayName: { type: 'string' },
+      version: { type: ['string', 'null'] },
+      lifecycle: { type: ['string', 'null'] },
+      availability: { type: ['string', 'null'] },
+      authenticationStatus: { type: ['string', 'null'] },
+      connectedSystemKey: { type: 'string' },
+      runtimeTarget: { type: 'object', additionalProperties: { type: 'string' } }
+    },
+    ['key', 'connectedSystemKey']
+  ),
+  ChannelDefinitionChannel: frozenObject({
+    definitionKey: { type: 'string' },
+    provisioning: schemaRef('ChannelProvisioning'),
+    runtimeTarget: schemaRef('ChannelRuntimeTarget'),
+    experimental: { type: 'boolean' },
+    maxInstances: { type: 'integer', minimum: 1 },
+    profiles: { type: 'array', items: schemaRef('ChannelTargetProfile') }
+  }),
+  ChannelDefinitionDetailData: frozenObject(
+    {
+      key: { type: 'string' },
+      displayName: { type: 'string' },
+      description: { type: 'string' },
+      type: { type: 'string' },
+      systemKind: { type: 'string' },
+      configuration: { type: 'array', items: { type: 'object' } },
+      channel: schemaRef('ChannelDefinitionChannel'),
+      cliInstructions: { type: 'string' },
+      iconHref: { type: 'string' },
+      installations: { type: 'array', items: schemaRef('ChannelInstallationRow') },
+      maxInstances: { type: 'integer', minimum: 1 },
+      installationCount: { type: 'integer', minimum: 0 },
+      canInstall: { type: 'boolean' },
+      blockedReason: { type: 'string' }
+    },
+    ['key', 'displayName', 'channel', 'installations']
+  ),
+  ChannelInstallationDetailData: frozenObject(
+    {
+      definition: {
+        type: 'object',
+        properties: {
+          key: { type: 'string' },
+          displayName: { type: 'string' },
+          provisioning: schemaRef('ChannelProvisioning')
+        },
+        additionalProperties: false
+      },
+      installation: schemaRef('ChannelInstallationRow')
+    },
+    ['definition', 'installation']
+  ),
+  ChannelTargetProfile: frozenObject(
+    {
+      key: { type: 'string' },
+      displayLabel: { type: 'string' }
+    },
+    ['key', 'displayLabel']
+  ),
+  ChannelTargetRow: frozenObject(
+    {
+      key: { type: 'string' },
+      displayLabel: { type: 'string' },
+      description: { type: 'string' },
+      experimental: { type: 'boolean' },
+      provisioning: schemaRef('ChannelProvisioning'),
+      runtimeTarget: schemaRef('ChannelRuntimeTarget'),
+      installationSummary: schemaRef('ChannelInstallationSummary'),
+      installations: { type: 'array', items: schemaRef('ChannelInstallationRow') },
+      profiles: { type: 'array', items: schemaRef('ChannelTargetProfile') },
+      configuration: { type: 'array', items: { type: 'object' } },
+      cliInstructions: { type: 'string' },
+      iconHref: { type: 'string' },
+      maxInstances: { type: 'integer', minimum: 1 },
+      installationCount: { type: 'integer', minimum: 0 },
+      canInstall: { type: 'boolean' },
+      blockedReason: { type: 'string' }
+    },
+    ['key', 'displayLabel', 'description', 'experimental']
+  ),
+  ListChannelTargetsData: frozenObject(
+    {
+      channels: { type: 'array', items: schemaRef('ChannelTargetRow') }
+    },
+    ['channels']
+  ),
+  ChannelUserAction: frozenObject(
+    {
+      id: { type: 'string' },
+      kind: { type: 'string' },
+      label: { type: 'string' },
+      required: { type: 'boolean' },
+      resume: { type: 'string' },
+      href: { type: 'string' },
+      field: { type: 'string' },
+      artifactId: { type: 'string' },
+      command: { type: 'string' },
+      value: { type: 'string' },
+      text: { type: 'string' }
+    },
+    ['id', 'kind', 'label']
+  ),
+  ChannelInstallVerdict: frozenObject(
+    {
+      ok: { type: 'boolean' },
+      label: { type: 'string' }
+    },
+    ['ok']
+  ),
+  ChannelInstallVerdicts: frozenObject({
+    runtime: schemaRef('ChannelInstallVerdict'),
+    oauth: schemaRef('ChannelInstallVerdict'),
+    vendorSession: schemaRef('ChannelInstallVerdict')
+  }),
+  ChannelInstallHelpData: frozenObject(
+    {
+      helpMarkdown: { type: 'string' },
+      helpMarkdownContentType: { type: 'string', enum: ['text/markdown'] },
+      refreshHintSeconds: { type: 'integer', minimum: 1 },
+      phase: { type: 'string' },
+      userActions: { type: 'array', items: schemaRef('ChannelUserAction') },
+      verdicts: schemaRef('ChannelInstallVerdicts'),
+      definitionKey: { type: 'string' },
+      installationKey: { type: 'string' },
+      systemKey: { type: 'string' }
+    },
+    ['helpMarkdown', 'helpMarkdownContentType', 'phase']
+  ),
+  AuthPermissionsData: frozenObject(
+    {
+      permissions: { type: 'array', items: { type: 'string' } }
+    },
+    ['permissions']
+  ),
+  ChannelArtifactRow: frozenObject(
+    {
+      id: { type: 'string' },
+      kind: { type: 'string' },
+      fileName: { type: 'string' },
+      contentType: { type: 'string' },
+      href: { type: 'string' }
+    },
+    ['id', 'href']
+  ),
+  ListChannelArtifactsData: frozenObject(
+    {
+      artifacts: { type: 'array', items: schemaRef('ChannelArtifactRow') }
+    },
+    ['artifacts']
+  ),
+  ChannelArtifactBytesData: frozenObject(
+    {
+      fileName: { type: 'string' },
+      contentType: { type: 'string' },
+      byteLength: { type: 'integer', minimum: 0 }
+    },
+    ['fileName', 'contentType', 'byteLength']
+  ),
+  ChannelPackageLinks: frozenObject({
+    readme: { type: 'string' },
+    zip: { type: ['string', 'null'] }
+  }),
+  ChannelPackageData: frozenObject(
+    {
+      channelTarget: { type: 'string' },
+      installReady: { type: 'boolean' },
+      blocker: { type: ['string', 'null'] },
+      artifactHash: { type: 'string' },
+      links: schemaRef('ChannelPackageLinks')
+    },
+    ['channelTarget', 'installReady']
+  ),
+  ChannelPackageSummaryData: frozenObject(
+    {
+      channelTarget: { type: 'string' },
+      installReady: { type: 'boolean' },
+      blocker: { type: ['string', 'null'] },
+      links: schemaRef('ChannelPackageLinks')
+    },
+    ['channelTarget', 'installReady']
+  ),
+  ChannelPackageZipData: frozenObject(
+    {
+      fileName: { type: 'string' },
+      contentType: { type: 'string' },
+      byteLength: { type: 'integer', minimum: 0 },
+      zipBase64: { type: 'string' }
+    },
+    ['fileName', 'contentType', 'byteLength', 'zipBase64']
+  ),
+  ChannelBrandingFields: frozenObject({
+    displayName: { type: 'string' },
+    description: { type: 'string' },
+    iconColorPath: { type: 'string' },
+    iconOutlinePath: { type: 'string' }
+  }),
+  ChannelBrandingData: frozenObject(
+    {
+      systemKey: { type: 'string' },
+      branding: schemaRef('ChannelBrandingFields')
+    },
+    ['systemKey', 'branding']
+  )
+};
+
+module.exports = {
+  OPENAPI_CHANNEL_INSTALL_REQUEST_SCHEMAS,
+  OPENAPI_CHANNEL_INSTALL_RESULT_SCHEMAS
+};

package/lib/programmatic/openapi-component-schemas.js

@@ -22,6 +22,10 @@ const {
   OPENAPI_EVIDENCE_RESULT_SCHEMAS
 } = require('./openapi-evidence-schemas');
 const { OPENAPI_HELP_RESULT_SCHEMAS } = require('./openapi-help-schemas');
+const {
+  OPENAPI_CHANNEL_INSTALL_REQUEST_SCHEMAS,
+  OPENAPI_CHANNEL_INSTALL_RESULT_SCHEMAS
+} = require('./openapi-channel-install-schemas');
 
 const RESPONSE_ENVELOPES = [
   ['ListSystemsResponse', 'ListSystemsData'],
@@ -55,7 +59,18 @@ const RESPONSE_ENVELOPES = [
   ['EvidenceDownloadResponse', 'EvidenceDownloadData'],
   ['EvidenceUploadResponse', 'EvidenceUploadData'],
   ['EvidenceActivateResponse', 'EvidenceActivateData'],
-  ['BuilderHelpResponse', 'BuilderHelpData']
+  ['BuilderHelpResponse', 'BuilderHelpData'],
+  ['ListChannelTargetsResponse', 'ListChannelTargetsData'],
+  ['ChannelDefinitionDetailResponse', 'ChannelDefinitionDetailData'],
+  ['ChannelInstallationDetailResponse', 'ChannelInstallationDetailData'],
+  ['ChannelInstallHelpResponse', 'ChannelInstallHelpData'],
+  ['ListChannelArtifactsResponse', 'ListChannelArtifactsData'],
+  ['ChannelArtifactBytesResponse', 'ChannelArtifactBytesData'],
+  ['ChannelPackageResponse', 'ChannelPackageData'],
+  ['ChannelPackageSummaryResponse', 'ChannelPackageSummaryData'],
+  ['ChannelPackageZipResponse', 'ChannelPackageZipData'],
+  ['ChannelBrandingResponse', 'ChannelBrandingData'],
+  ['AuthPermissionsResponse', 'AuthPermissionsData']
 ];
 
 /**
@@ -70,11 +85,13 @@ function buildOpenApiComponentSchemas() {
     ...OPENAPI_REQUEST_SCHEMAS,
     ...OPENAPI_MANIFEST_REQUEST_SCHEMAS,
     ...OPENAPI_EVIDENCE_REQUEST_SCHEMAS,
+    ...OPENAPI_CHANNEL_INSTALL_REQUEST_SCHEMAS,
     ...OPENAPI_RESULT_SCHEMAS,
     ...OPENAPI_APPLY_RESULT_SCHEMAS,
     ...OPENAPI_MANIFEST_RESULT_SCHEMAS,
     ...OPENAPI_EVIDENCE_RESULT_SCHEMAS,
     ...OPENAPI_HELP_RESULT_SCHEMAS,
+    ...OPENAPI_CHANNEL_INSTALL_RESULT_SCHEMAS,
     EmptyResultData: { type: 'object', properties: {}, additionalProperties: false },
     ...envelopes
   });

package/lib/programmatic/openapi-description-enricher.js

@@ -15,6 +15,7 @@ const { MANIFEST_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-
 const { MCP_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-mcp');
 const { HELP_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-help');
 const { EVIDENCE_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-evidence');
+const { CHANNEL_INSTALL_SCHEMA_DESCRIPTIONS } = require('./openapi-schema-descriptions-channel');
 
 /** @type {Record<string, Object>} */
 const MERGED_SCHEMA_DESCRIPTIONS = {
@@ -24,7 +25,8 @@ const MERGED_SCHEMA_DESCRIPTIONS = {
   ...MANIFEST_SCHEMA_DESCRIPTIONS,
   ...MCP_SCHEMA_DESCRIPTIONS,
   ...HELP_SCHEMA_DESCRIPTIONS,
-  ...EVIDENCE_SCHEMA_DESCRIPTIONS
+  ...EVIDENCE_SCHEMA_DESCRIPTIONS,
+  ...CHANNEL_INSTALL_SCHEMA_DESCRIPTIONS
 };
 
 /**

package/lib/programmatic/openapi-descriptions.js

@@ -198,7 +198,8 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
   },
   health: {
     summary: 'Liveness probe',
-    description: 'Returns ok when the builder-api process is running. No authentication.',
+    description:
+      'Returns ok when the builder-api process is running. Portal availability probe. Empty channel catalog is not a down signal. No authentication.',
     tags: ['infra']
   },
   ready: {
@@ -239,12 +240,13 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
   buildChannelPackage: {
     summary: 'Build channel package',
     description:
-      'Build vendor channel package from External AI Discovery plus optional workspace branding. Returns summary, README/ZIP links, and installReady. Mutating.',
+      'Build vendor channel package from External AI Discovery plus optional workspace branding. Returns summary, README/ZIP links, and installReady (package-import readiness, not channel-installed). Mutating.',
     tags: ['channel']
   },
   getChannelPackageSummary: {
     summary: 'Get channel package summary',
-    description: 'Return last built channel package summary and README/ZIP links. Read-only.',
+    description:
+      'Return last built channel package summary and README/ZIP links. installReady is package-import readiness, not channel-installed. Read-only.',
     tags: ['channel']
   },
   getChannelPackageZip: {
@@ -263,6 +265,75 @@ const OPERATION_DESCRIPTIONS = Object.freeze({
     description:
       'Update optional package branding overrides stored in the Builder API workspace. Mutating.',
     tags: ['channel']
+  },
+  listChannelTargets: {
+    summary: 'List live channel definitions',
+    description:
+      'List live Channel Definitions. Each row has key, displayLabel, description, experimental, provisioning, runtimeTarget, installationSummary, installationCount, and canInstall. Optional maxInstances and blockedReason when capped. Catalog is information-only; publishing uses POST install. Read-only.',
+    tags: ['infra']
+  },
+  getChannelDefinitionDetail: {
+    summary: 'Get a Channel Definition',
+    description:
+      'Return a safe Channel Definition (identity, configuration, provisioning, runtimeTarget, profiles, optional maxInstances) plus installations projected from Dataplane Connected Systems. Includes canInstall. Unknown definition keys return 404. Known definitions with no instances return installations []. Read-only.',
+    tags: ['infra']
+  },
+  getChannelInstallation: {
+    summary: 'Get a Channel installation',
+    description:
+      'Return one Channel installation projected from a Dataplane Connected System. 404 only when that instance does not exist for the definition. Read-only.',
+    tags: ['infra']
+  },
+  runChannelInstall: {
+    summary: 'Install a channel',
+    description:
+      'Scaffold, upload, and configure a channel from a Channel Definition. Path systemKey is the definition key. Body name is required; optional systemKey is the Connected System instance key; configuration is a generic propertyKey map. Returns help markdown plus phase, safe userActions, definitionKey, installationKey, and systemKey (the instance). Mutating.',
+    tags: ['infra']
+  },
+  getChannelInstall: {
+    summary: 'Get channel install help',
+    description:
+      'Return install help markdown plus phase and safe userActions for this path systemKey. Help is generated from the current envelope on each GET. The definition key returns the last install session (continue). An instance key returns that installation’s help, from its session or generated from the instance package. verbose=true returns the full machine envelope. Read-only.',
+    tags: ['infra']
+  },
+  getChannelInstallHelp: {
+    summary: 'Download channel install help.md',
+    description: 'Return the current install help document as text/markdown. Human-only; no userActions. Read-only.',
+    tags: ['infra']
+  },
+  continueChannelInstall: {
+    summary: 'Continue channel install',
+    description:
+      'Resume install after the human follows the help document. Path systemKey may be the catalog definition key or the Connected System instance key. Empty body is valid and continues Microsoft device-code login without issuing a new code. Optional token is used once and not stored. retryLogin=true restarts vendor login and issues a new handshake. Returns the same default HTTP as POST install (help markdown, phase, safe userActions). Mutating.',
+    tags: ['infra']
+  },
+  listChannelArtifacts: {
+    summary: 'List channel install artifacts',
+    description: 'List downloadable files linked from the install help document. Read-only.',
+    tags: ['infra']
+  },
+  getChannelArtifact: {
+    summary: 'Download a channel install artifact',
+    description: 'Return artifact bytes (ZIP as application/zip). Read-only.',
+    tags: ['infra']
+  },
+  getChannelCallback: {
+    summary: 'Resume channel install from vendor redirect',
+    description:
+      'Vendor callback (GET). Stores access through existing credentials. Never echoes tokens. Mutating.',
+    tags: ['infra']
+  },
+  postChannelCallback: {
+    summary: 'Resume channel install from vendor POST',
+    description:
+      'Vendor callback (POST). Stores access through existing credentials. Never echoes tokens. Mutating.',
+    tags: ['infra']
+  },
+  getAuthPermissions: {
+    summary: 'Read current-user permissions',
+    description:
+      'Thin forward of the controller current-user permissions list. Used to preflight Integration Client installs. Read-only.',
+    tags: ['infra']
   }
 });