@aifabrix/builder 2.51.0 → 2.52.0

package/lib/validation/validate.js

@@ -22,6 +22,7 @@ const { generateControllerManifest } = require('../generator/external-controller
 const { validateControllerManifest } = require('./external-manifest-validator');
 const { runExternalValidateWithOptionalCertSync } = require('./validate-external-cert-sync');
 const { validateExternalFile } = require('./validate-external-file');
+const { reservedSystemKeyError } = require('./reserved-system-key-prefixes');
 
 /**
  * Validates a file path (detects type and validates)
@@ -276,6 +277,52 @@ async function validateManifestStep(appName, options = {}) {
   }
 }
 
+/**
+ * Early-fail payload when system key uses a reserved prefix.
+ * @param {string} reservedError
+ * @param {string} appPath
+ * @returns {Object}
+ */
+function reservedSystemKeyValidationResult(reservedError, appPath) {
+  return {
+    valid: false,
+    errors: [reservedError],
+    warnings: [],
+    steps: {
+      application: { valid: false, errors: [reservedError], warnings: [] },
+      components: { valid: true, errors: [], warnings: [], files: [], skipped: true },
+      manifest: { valid: true, errors: [], warnings: [], skipped: true }
+    },
+    appPath
+  };
+}
+
+/**
+ * Aggregate step results into the complete validation response.
+ * @param {Object} steps
+ * @param {string} appPath
+ * @returns {Object}
+ */
+function aggregateExternalValidationSteps(steps, appPath) {
+  const allErrors = [
+    ...steps.application.errors,
+    ...steps.components.errors,
+    ...steps.manifest.errors
+  ];
+  const allWarnings = [
+    ...steps.application.warnings,
+    ...steps.components.warnings,
+    ...steps.manifest.warnings
+  ];
+  return {
+    valid: allErrors.length === 0,
+    errors: allErrors,
+    warnings: allWarnings,
+    steps,
+    appPath
+  };
+}
+
 /**
  * Validates external system completely (components + full manifest)
  * Performs step-by-step validation: application config → components → full manifest
@@ -295,7 +342,12 @@ async function validateExternalSystemComplete(appName, options = {}) {
     throw new Error('App name is required and must be a string');
   }
 
-  const { appPath } = await detectAppType(appName, options);
+  const { appPath, baseDir } = await detectAppType(appName, options);
+  const reservedError = reservedSystemKeyError(appName, baseDir);
+  if (reservedError) {
+    return reservedSystemKeyValidationResult(reservedError, appPath);
+  }
+
   const steps = {
     application: { valid: false, errors: [], warnings: [] },
     components: { valid: false, errors: [], warnings: [], files: [] },
@@ -303,14 +355,9 @@ async function validateExternalSystemComplete(appName, options = {}) {
   };
 
   const externalOptions = { ...options };
-
-  // Step 1: Validate Application Config
   steps.application = await validateApplicationStep(appName, externalOptions);
-
-  // Step 2: Validate Individual Components
   steps.components = await validateComponentsStep(appName, externalOptions);
 
-  // If components have errors, return early (don't validate manifest)
   if (!steps.components.valid) {
     steps.manifest = { valid: true, errors: [], warnings: [], skipped: true };
     return {
@@ -322,20 +369,8 @@ async function validateExternalSystemComplete(appName, options = {}) {
     };
   }
 
-  // Step 3 & 4: Generate and Validate Full Manifest (only if Step 2 passes)
   steps.manifest = await validateManifestStep(appName, { ...externalOptions, appPath });
-
-  // Aggregate Results
-  const allErrors = [...steps.application.errors, ...steps.components.errors, ...steps.manifest.errors];
-  const allWarnings = [...steps.application.warnings, ...steps.components.warnings, ...steps.manifest.warnings];
-
-  return {
-    valid: allErrors.length === 0,
-    errors: allErrors,
-    warnings: allWarnings,
-    steps,
-    appPath
-  };
+  return aggregateExternalValidationSteps(steps, appPath);
 }
 
 async function validateAppOrFile(appOrFile, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.51.0",
+  "version": "2.52.0",
   "description": "AI Fabrix Builder — CLI and developer scripts (pnpm + af)",
   "main": "lib/index.js",
   "bin": {
@@ -114,6 +114,7 @@
   },
   "dependencies": {
     "@aifabrix/miso-client": "^4.19.0",
+    "adm-zip": "^0.6.0",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "axios": "^1.18.1",

package/scripts/export-builder-api-evidence.js

@@ -238,7 +238,7 @@ function rowsFromManifestGuides() {
       title: 'Section quality and missing inputs',
       when: 'GET manifest section returns quality.missingInputs',
       expectedBehavior:
-        'Collect required missing inputs from the user before PATCH. Do not guess values. Include sectionReadToken from GET in PATCH body.',
+        'Collect required missing inputs from the user before PATCH. Do not guess values. sectionReadToken from GET is optional on PATCH (server re-reads when omitted; stale token returns 409). Prefer GET when you need quality or missingInputs.',
       order: 17
     })
   ];

package/templates/applications/builder-api/application.yaml

@@ -2,7 +2,7 @@
 app:
   key: builder-api
   displayName: 'AI Fabrix Builder API'
-  description: 'Stateless HTTP orchestration for external-system workspace lifecycle. Provider-neutral integration flows via Dataplane Enterprise MCP and governance APIs (154.0 / 154.1).'
+  description: 'Business Transformation services — HTTP orchestration for connected-system workspace lifecycle via Dataplane Enterprise MCP and governance APIs.'
   type: webapp
   language: typescript
   version: 1.0.0
@@ -11,8 +11,8 @@ app:
 image:
   name: aifabrix/builder-api
   tag: latest
-  registry: aifabrixdevacr.azurecr.io
-  registryMode: acr
+  registry: aifabrixacr.azurecr.io
+  registryMode: external
 
 # Port Configuration (container port; host port = port + developer_id * 100)
 port: 3005

package/templates/applications/dataplane/application.yaml

@@ -4,16 +4,16 @@ app:
   displayName: "AI Fabrix Dataplane"
   description: "AI Fabrix Dataplane is a secure, in-tenant integration and automation layer that supplies governed, normalized, and explainable enterprise data to AI agents. Using CIP as a declarative standard, it enforces RBAC and ABAC, executes integrations, and exposes trusted data via MCP and OpenAPI."
   type: webapp
-  language: python  # Explicitly specify Python language
-  version: 2.0.10
+  language: python # Explicitly specify Python language
+  version: 2.0.20
 # Image Configuration
-# Set tag to match your build (e.g. aifabrix build dataplane -t 1.0.0 then tag: 1.0.0)
-# Registry is required so the controller can pull the image (avoids "docker: not found" on the controller host).
+# Set tag to match your build (example: aifabrix build dataplane -t 1.0.0).
+# Registry is required so the controller can pull the image (avoids docker-not-found on the controller host).
 image:
   name: aifabrix/dataplane
   tag: latest
-  registry: aifabrixdevacr.azurecr.io
-  registryMode: acr
+  registry: aifabrixacr.azurecr.io
+  registryMode: external
 
 # Port Configuration
 port: 3001
@@ -34,10 +34,10 @@ frontDoorRouting:
 requires:
   database: true
   databases:
-    - name: dataplane          # Main database - configuration only
-    - name: dataplane-vector   # Vector and document store: chunks, embeddings, vector indexes (pgvector)
-    - name: dataplane-logs     # Logs database - execution, audit, ABAC traces
-    - name: dataplane-records  # Records database - external records storage
+    - name: dataplane # Main database - configuration only
+    - name: dataplane-vector # Vector and document store: chunks, embeddings, vector indexes (pgvector)
+    - name: dataplane-logs # Logs database - execution, audit, ABAC traces
+    - name: dataplane-records # Records database - external records storage
   redis: true
   storage: true
 
@@ -59,10 +59,10 @@ authentication:
 # Build Configuration
 # Dataplane builds from published image; context is project root (like miso-controller)
 build:
-  context: ../..                  # Docker build context (relative to builder/dataplane/)
-  dockerfile: builder/dataplane/Dockerfile  # Dockerfile path (relative to project root)
-  envOutputPath: ../../.env       # Copy to repo root for local dev
-  language: python                # Runtime language for template selection (typescript or python)
+  context: ../.. # Docker build context (relative to builder/dataplane/)
+  dockerfile: builder/dataplane/Dockerfile # Dockerfile path (relative to project root)
+  envOutputPath: ../../.env # Copy to repo root for local dev
+  language: python # Runtime language for template selection (typescript or python)
   # Dev reload: polling + watch /app/app only (avoids EMFILE on full repo bind-mount). See run_local.py, make af-reload.
   reloadStart: WATCHFILES_FORCE_POLLING=1 uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-3001} --reload --reload-dir /app/app
   # Pulled-image local compose (no bind-mount): drives `command` in generated docker-compose. Override for non-standard images (e.g. stub ACR tags).
@@ -72,6 +72,10 @@ build:
   worker: true
   imageRunWorker: exec python -m app.core.celery_worker_main
   imageRunBeat: exec python -m app.core.celery_beat_main
+  # Optional one-shot before ANY long-running role (api/worker/beat). Run exactly once per
+  # aifabrix run / Deployment — never once-per-container. Schema: application-schema build.deployJob.
+  # Local: aifabrix run; remote: miso Deployment via miso-azure (not Docker on controller).
+  deployJob: python -m app.db.migrate upgrade
 
 # =============================================================================
 # Portal Input Configuration (Deployment Wizard)
@@ -81,7 +85,7 @@ build:
 #
 # NOT included (auto-configured):
 # - Database URLs, Redis → auto-generated during Azure install
-# - MISO_*, KEYCLOAK_* → auto-generated during Azure install  
+# - MISO_*, KEYCLOAK_* → auto-generated during Azure install
 # - AI params / provider secrets → LLM external systems + secret store
 #   (never product OPENAI_* / AZURE_OPENAI_*). ≥2 providers →
 #   ENTERPRISE_LLM_DEFAULT_SELECTOR (portal LLM category).
@@ -135,8 +139,9 @@ configuration:
     category: Trust
     portalInput:
       field: select
-      label: "Enforce trust gate on datasource publish"
+      label: "Enforce trust gate on datasource publish (empty=ENVIRONMENT default)"
       options:
+        - ""
         - "false"
         - "true"
 
@@ -144,8 +149,9 @@ configuration:
     category: Trust
     portalInput:
       field: select
-      label: "Enforce trust gate on external system publish (promote scope)"
+      label: "Enforce trust gate on Deploy / system publish (empty=ENVIRONMENT default)"
       options:
+        - ""
         - "false"
         - "true"
 
@@ -225,3 +231,4 @@ configuration:
       field: text
       label: "Default LLM provider (system key when two or more providers)"
       placeholder: "openai"
+

package/templates/applications/dataplane/env.template

@@ -44,7 +44,7 @@ API_KEY_BYPASS_ROLES=full-access
 
 # API Configuration
 API_V1_STR=/api/v1
-VERSION=2.0.10
+VERSION=2.0.20
 # Minimum supported aifabrix-builder CLI semver (advertised on /health and /api/v1/health; empty = no gate)
 # MIN_BUILDER_CLI_VERSION=2.45.0
 MIN_BUILDER_CLI_VERSION=2.45.5
@@ -284,7 +284,7 @@ VALIDATION_AUTO_ISSUE_INTEGRATION_CERTIFICATE=true
 CIP_EXECUTION_MAX_RESPONSE_SIZE_MB=100.0
 CIP_EXECUTION_MAX_RECORDS=100000
 CIP_EXECUTION_OPERATION_TIMEOUT=300.0
-CIP_EXECUTION_HTTP_TIMEOUT=30.0
+CIP_EXECUTION_HTTP_TIMEOUT=120.0
 CIP_EXECUTION_MAX_RETRIES=3
 CIP_EXECUTION_RETRY_BACKOFF_FACTOR=2.0
 CIP_EXECUTION_RETRY_INITIAL_DELAY=1.0

package/templates/applications/dataplane/rbac.yaml

@@ -5,47 +5,47 @@
 # MisoClient validates environment access automatically based on user/application permissions.
 
 roles:
-  - name: "AI Fabrix Platform Admin"
+  - name: "Platform Admin"
     value: "aifabrix-platform-admin"
     description: "Full platform infrastructure management and enterprise controller access"
     groups: ["AI-Fabrix-Platform-Admins"]
 
-  - name: "AI Fabrix Security Admin"
+  - name: "Security Admin"
     value: "aifabrix-security-admin"
     description: "Security and compliance management for enterprise controller"
     groups: ["AI-Fabrix-Security-Admins"]
 
-  - name: "AI Fabrix Deployment Admin"
+  - name: "Deployment Admin"
     value: "aifabrix-deployment-admin"
     description: "Application deployment orchestration and environment management"
     groups: ["AI-Fabrix-Deployment-Admins"]
 
-  - name: "AI Fabrix Compliance Admin"
+  - name: "Compliance Admin"
     value: "aifabrix-compliance-admin"
     description: "ISO 27001 compliance monitoring and audit management"
     groups: ["AI-Fabrix-Compliance-Admins"]
 
-  - name: "AI Fabrix Developer"
+  - name: "Developer"
     value: "aifabrix-developer"
     description: "Developer access to deploy applications via CI pipelines"
     groups: ["AI-Fabrix-Developers"]
 
-  - name: "AI Fabrix Business Transformation"
-    value: "aifabrix-business-transformation"
+  - name: "Business Transformation"
+    value: "business-transformation"
     description: "Built-in assistant: business intention → governed Connected Systems via Runtime and builder-api"
     groups: ["AI-Fabrix-Business-Transformation"]
 
-  - name: "AI Fabrix Observer"
+  - name: "Observer"
     value: "aifabrix-observer"
     description: "Read-only access to monitoring, logs, and compliance reports"
     groups: ["AI-Fabrix-Observers"]
 
-  - name: "AI Fabrix AI Trust Operator"
+  - name: "AI Trust Operator"
     value: "aifabrix-ai-trust-operator"
     description: "Run AI Trust access evaluation and explain visibility for governed users"
     groups: ["AI-Fabrix-AI-Trust-Operators"]
 
-  - name: "AI Fabrix External System Discoverer"
+  - name: "External System Discoverer"
     value: "aifabrix-external-system-discoverer"
     description: "Discover business context for external systems via REST and MCP"
     groups: ["AI-Fabrix-External-System-Discoverers"]
@@ -143,6 +143,20 @@ permissions:
   - name: "integration-template:delete"
     roles: ["aifabrix-platform-admin", "aifabrix-developer"]
     description: "Delete integration templates"
+
+  # Resource type catalog (public read; Miso owns writes via controller sync)
+  - name: "resource-type:read"
+    roles:
+      [
+        "aifabrix-platform-admin",
+        "aifabrix-security-admin",
+        "aifabrix-deployment-admin",
+        "aifabrix-compliance-admin",
+        "aifabrix-developer",
+        "aifabrix-observer",
+        "aifabrix-ai-trust-operator",
+      ]
+    description: "Read the global Resource Type catalog (list/get)"
   
   # Generic dataplane operations
   - name: "dataplane:read"

package/templates/applications/keycloak/application.yaml

@@ -10,8 +10,8 @@ app:
 image:
   name: aifabrix/keycloak
   tag: 'latest'
-  registry: aifabrixdevacr.azurecr.io
-  registryMode: acr
+  registry: aifabrixacr.azurecr.io
+  registryMode: external
 
 # Port Configuration (base for host; host port = 8082 + developer_id*100 from ~/.aifabrix/config.yaml)
 port: 8082

package/templates/applications/keycloak/env.template

@@ -9,11 +9,14 @@
 KC_BOOTSTRAP_ADMIN_USERNAME=admin
 KC_BOOTSTRAP_ADMIN_PASSWORD=kv://keycloak-admin-passwordKeyVault
 KC_HOSTNAME_STRICT=false
-KC_HTTP_ENABLED=${HTTP_ENABLED}
+# Follows tlsEnabled in ~/.aifabrix/config.yaml (same as ${TLS_ENABLED}).
+# Traefik/edge HTTPS on → true (proxy forwards HTTP to Keycloak :8080).
+# Single container without HTTPS (tlsEnabled false) → false.
+KC_HTTP_ENABLED=${TLS_ENABLED}
 # When Traefik + frontDoorRouting.enabled are on, same vdir as url://public. If the front door is off, env generation
 # rewrites url://vdir-public to "/" before expansion (empty path is invalid — Keycloak 26 SRCFG00040).
 # Docker-only templates may use url://vdir-internal instead.
-KC_HTTP_RELATIVE_PATH=url://vdir-public
+KC_HTTP_RELATIVE_PATH=/auth
 
 # =============================================================================
 # HOSTNAME / ISSUER (Docker vs localhost)

package/templates/applications/miso-controller/application.yaml

@@ -4,7 +4,7 @@ app:
   displayName: 'Miso Controller'
   description: 'Miso is the AI Fabrix in-tenant controller and portal layer for securely operating enterprise AI apps inside a customer’s Azure tenant. It provides Entra ID SSO, RBAC, audit logs, environment/app configuration via schemas, and safe secret handling via Key Vault references—ensuring governance, traceability, and predictable UX across portal, SDK, and CLI.'
   type: webapp
-  version: '2.0.8'
+  version: '2.0.20'
 
 # Image Configuration
 # Set tag to match your build (e.g. aifabrix build miso-controller -t 1.0.0 then tag: 1.0.0)
@@ -12,8 +12,8 @@ app:
 image:
   name: aifabrix/miso-controller
   tag: latest
-  registry: aifabrixdevacr.azurecr.io
-  registryMode: acr
+  registry: aifabrixacr.azurecr.io
+  registryMode: external
 
 # Port Configuration (container port; host port = 3000 + developer_id*100 from ~/.aifabrix/config.yaml)
 port: 3000

package/templates/applications/miso-controller/env.template

@@ -49,6 +49,10 @@ ONBOARDING_ADMIN_EMAIL=kv://miso-controller-admin-emailKeyVault
 # When true, supersedes ONBOARDING_CREATE_DEV_ENV for which extra environments are created
 ONBOARDING_FULL_PLATFORM=false
 
+# When true, run Azure env deploy for onboarding envs (SDK modules). Default false —
+# Marketplace already provisions infra; TA owns customer env deploy.
+ONBOARDING_CREATE_MISO_ENV=false
+
 # Set to true to create both miso and dev environments during onboarding
 # When false (default), only the miso environment is created (ignored when ONBOARDING_FULL_PLATFORM=true)
 ONBOARDING_CREATE_DEV_ENV=true
@@ -236,6 +240,14 @@ SKIP_DB_REDEPLOY=true
 # Bootstrap (SKIP_FIRST_TIME_SETUP=false) is separate from the activation wizard.
 DEPLOYMENT=database
 
+# Dev/test: open /tenant-activation on Platform Apps (last step). Default false.
+# Does not skip server-side TA — use only when env is already activated/deployed.
+TA_SKIP_TO_APP_DEPLOY=false
+
+# Dev/test: show TA Entra "Completing setup" countdown (120s cap). Default false.
+# Exposed to UI via GET /api/v1/tenant/status → showTaCountdown (restart controller after change).
+SHOW_TA_COUNT_DOWN=false
+
 # =============================================================================
 # SECURITY & ENCRYPTION
 # =============================================================================
@@ -287,8 +299,11 @@ ENTRA_GRAPH_DELEGATED_REDIRECT_URI=https://aifabrix-pro-mori-web-we.azurewebsite
 # =============================================================================
 # MORI SERVICE CONFIGURATION
 # =============================================================================
-
-MORI_BASE_URL=url://mori-controller-public
+# Shared Mori (handoff poll + Entra callback). Local `url://mori-controller-public`
+# only works when a local Mori app is registered and running for this developer.
+# MORI_CALLBACK_API_KEY must be the same secret as Mori MORI_CONTROLLER_CALLBACK_API_KEY
+# (both resolve from kv://mori-callback-api-keyKeyVault — do not generate separate values).
+MORI_BASE_URL=https://aifabrix-pro-mori-web-we.azurewebsites.net
 MORI_AUTH_METHOD=kv://mori-controller-auth-methodKeyVault
 MORI_CALLBACK_API_KEY=kv://mori-callback-api-keyKeyVault
 MORI_API_KEY=kv://mori-controller-api-keyKeyVault

package/templates/channels/chatgpt/install.template.md.hbs

@@ -1,46 +1,102 @@
-# {{appName}} — ChatGPT assistant channel install
+# {{appName}} — ChatGPT custom MCP app setup
 
 {{appDescription}}
 
-Environment: **{{environment}}** · Credential key: `{{credentialKey}}`
+**Environment:** {{environment}}  
+**AI Fabrix credential reference:** `{{credentialKey}}`
 
-## Connect ChatGPT workspace (admin)
+> This document and `dist/channels/chatgpt/channel-chatgpt.json` are deployment references for administrators. ChatGPT does not install the JSON file as a plugin archive. ChatGPT connects directly to the remote MCP endpoint and discovers the tools exposed by that server.
 
-1. Sign in to [OpenAI Platform](https://platform.openai.com/) or your **ChatGPT Enterprise** workspace admin console.
-2. Create a custom GPT, workspace connector, or MCP integration using the generated manifest from `dist/channels/chatgpt/channel-chatgpt.json`.
-3. Configure the **OpenAPI specification URL** and **MCP endpoint** from **Platform endpoints** below.
-4. Complete OAuth or API key setup as required by your ChatGPT deployment model.
-5. Save the **API key** or **OAuth client credentials** in AI Fabrix: [Authentication settings]({{credentialPortalUrl}})
-6. Publish the connector to your workspace and complete admin approval if your organization requires it.
+## ChatGPT workspace setup
 
-## Platform endpoints
+1. Sign in to the ChatGPT web app as a workspace admin or owner.
+2. Enable Developer mode for custom MCP apps:
+   - **Business:** **Workspace settings → Apps → Create**, or **Settings → Apps → Advanced settings**.
+   - **Enterprise/Edu:** grant the appropriate Developer mode permission under **Workspace settings → Permissions & roles → Connected data**, then enable it under **Settings → Apps → Advanced settings**.
+3. Open **Settings → Apps → Create** (or the equivalent **Workspace settings → Apps → Create** entry).
+4. Enter the app name `{{appName}}` and the remote MCP URL shown under **Runtime connection** below.
+5. Select **OAuth** as the authentication mechanism. Do not configure a custom API key in ChatGPT; custom API-key authentication is not supported for a remote custom MCP app.
+6. Select **Scan tools**. If prompted, complete the OAuth authorization flow and wait for ChatGPT to finish scanning the Runtime tool list.
+7. Review the discovered tools and create the app as a draft.
+8. Test representative read and write workflows. Confirm that user authorization and action confirmations behave as expected.
+9. Publish the app to the workspace and configure its access and action controls. Only workspace admins or owners can publish it.
+10. After MCP tool names, schemas, annotations, or authentication metadata change, use **Refresh** in the app's action controls and review the changes before enabling them.
 
-Configure these on the ChatGPT connector / custom GPT. Do not embed secrets in generated files — use AI Fabrix credential storage only.
+## Runtime connection
 
-{{#if openapiUrl}}
-- **OpenAPI spec:** {{openapiUrl}}
-{{/if}}
+Configure the following values in the ChatGPT custom MCP app. Never place access tokens, client secrets, or API keys in generated files.
+
+- **App name:** `{{appName}}`
 {{#if mcpUrl}}
-- **MCP:** {{mcpUrl}}
-{{/if}}
-{{#if actionsBaseUrl}}
-- **Actions base:** {{actionsBaseUrl}}
+- **Remote MCP URL:** `{{{mcpUrl}}}`
 {{/if}}
+- **Runtime system key:** `{{runtimeSystemKey}}`
+- **Transport:** Streamable HTTP
+- **Authentication:** OAuth 2.1 authorization-code flow with PKCE (`S256`)
+- **AI Fabrix credential reference:** `{{credentialKey}}`
+- **AI Fabrix authentication settings:** [Open authentication settings]({{{credentialPortalUrl}}})
 
-## Assistant catalog
+The `{{credentialKey}}` value is an AI Fabrix credential reference. It is not a secret to paste into ChatGPT.
 
-Runtime lists **assistants** available to each user from:
+## OAuth requirements
 
-{{assistantCatalogUrl}}
+Before ChatGPT can connect successfully, the MCP deployment must meet all of these requirements:
 
-## After workspace approval
+- The MCP endpoint is reachable over public HTTPS with a publicly trusted TLS certificate chain.
+- The MCP server publishes OAuth protected-resource metadata, normally at `/.well-known/oauth-protected-resource`, or points to it in the `WWW-Authenticate` header returned with a `401 Unauthorized` response.
+- The protected-resource document identifies the canonical resource URL, authorization server, and supported scopes.
+- The authorization server publishes OAuth or OpenID Connect discovery metadata.
+- The authorization server supports the authorization-code flow and PKCE with `S256`.
+- The OAuth flow preserves the MCP `resource` parameter, and issued access tokens contain the expected audience and scopes.
+- The redirect URI shown by ChatGPT when the app is created is allowlisted in the authorization server.
+- The MCP server validates every access token's signature, issuer, audience, expiry, and scopes.
+- Each authenticated MCP tool declares an `oauth2` security scheme with the scopes it needs.
 
-```bash
-aifabrix channel add {{channelTarget}} --name "{{baseName}}"
-```
+If this development endpoint is deliberately anonymous, select **No authentication** instead and declare `noauth` on the applicable tools. Do not describe the app as “OAuth or API key”; the selected mechanism must match the behavior advertised by the MCP server.
+
+## Expected Runtime Layer B tools
+
+ChatGPT should discover the following tools from the live MCP server during **Scan tools**:
+
+{{#each layerBToolNames}}
+- `{{this}}`
+{{/each}}
+
+The live server response is authoritative. This list is an expected deployment contract, not a substitute for MCP tool discovery.
+
+## Runtime and Role Assistant boundaries
 
-Optional validation:
+- Runtime resolves assistants dynamically for the current user from `{{{assistantCatalogUrl}}}`.
+- ChatGPT's top-level tool surface remains limited to the Runtime Layer B tools listed above.
+- Evidence authoring remains an internal Business Transformation Assistant capability. It is reached through `ChatGPT → runtime-orchestration → Business Transformation Assistant → internal evidence capabilities` and is not exposed as a top-level ChatGPT tool.
+- One authenticated Runtime connection can support multiple Role Assistants, subject to the current user's authorization.
+
+## BTA evidence-authoring proof scenario
+
+Use this scenario to verify the ChatGPT → Runtime → BTA path without exposing Evidence commands as top-level ChatGPT tools:
+
+1. Ask {{baseName}} to improve an existing Role Assistant from process documentation.
+2. Confirm that {{baseName}} starts or continues Business Transformation Assistant work through Runtime.
+3. Confirm that BTA performs evidence metadata, download, upload, and reasoning operations internally and presents certified proposals.
+4. Approve selected proposals and confirm that activation remains an explicit human action.
+
+## AI Fabrix validation
+
+Before workspace publication, validate the live Streamable HTTP endpoint with MCP Inspector and confirm that initialization, tool discovery, representative calls, invalid inputs, OAuth challenges, and authorization checks all work.
+
+Then run the AI Fabrix probe:
 
 ```bash
 aifabrix channel add {{channelTarget}} --name "{{baseName}}" --probe
 ```
+
+The probe should validate Runtime through the first-party MCP gateway, including Layer B discovery and BTA Evidence-authoring reachability. A successful AI Fabrix probe does not replace ChatGPT's own **Scan tools**, OAuth, and workspace publication checks.
+
+Use `--force` only to regenerate artifacts and patch channel metadata. It does not rotate credentials.
+
+## Current validation status
+
+- Local artifact validation: complete
+- Live Runtime validation: pending
+- ChatGPT workspace tool scan: pending
+- ChatGPT workspace publication: requires a workspace admin or owner

package/templates/channels/chatgpt/integration/README.md

@@ -1,11 +1,15 @@
-# ChatGPT assistant channel (lab fixture)
+# ChatGPT custom MCP app channel
 
-SSOT for `aifabrix channel scaffold chatgpt` templates (`make sync-json` → builder).
+Generated by `aifabrix channel scaffold chatgpt`.
+
+Recommended flow:
 
 ```bash
-cd aifabrix-dataplane
-aifabrix validate chatgpt
-aifabrix upload chatgpt --probe
-aifabrix deploy chatgpt
-aifabrix app add-channel chatgpt --name "Your Assistant"
+aifabrix upload chatgpt --force
+aifabrix channel add chatgpt --name "Your Assistant" --probe
 ```
+
+The `channel add` step generates `dist/channels/chatgpt/channel-chatgpt.json` and
+`INSTALL.md`. Those files are deployment references for workspace admins: ChatGPT
+connects to the remote Runtime MCP URL (OAuth) and discovers tools; it does not
+install the JSON as a plugin archive.

package/templates/channels/chatgpt/integration/application.json

@@ -1,8 +1,8 @@
 {
   "app": {
     "key": "chatgpt",
-    "displayName": "ChatGPT assistant channel",
-    "description": "Assistant communication channel — deploy then app add-channel",
+    "displayName": "ChatGPT custom MCP app channel",
+    "description": "Assistant communication channel — deploy then channel add",
     "type": "external"
   },
   "externalIntegration": {

package/templates/channels/chatgpt/integration/chatgpt-system.json

@@ -1,7 +1,7 @@
 {
   "key": "chatgpt",
-  "displayName": "ChatGPT assistant channel",
-  "description": "Communication external system for ChatGPT assistant channel install",
+  "displayName": "ChatGPT custom MCP app channel",
+  "description": "Communication external system for ChatGPT custom MCP app onboarding",
   "type": "custom",
   "systemKind": "communication",
   "enabled": true,
@@ -9,7 +9,7 @@
     "authType": "credential",
     "credential": {
       "credentialKey": "chatgpt-channel",
-      "displayName": "ChatGPT assistant channel",
+      "displayName": "ChatGPT custom MCP app channel",
       "method": "apikey",
       "writeOnce": true,
       "variables": {

package/templates/channels/chatgpt/integration/env.template

@@ -1,4 +1,4 @@
-# ChatGPT assistant channel — lab fixture secrets
+# ChatGPT custom MCP app channel credential reference
 # aifabrix secret set chatgpt/apiKey "<value>" --shared
 
 KV_CHATGPT_APIKEY=kv://chatgpt/apiKey