@aifabrix/builder 2.51.1 → 2.52.0

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

@@ -2,63 +2,101 @@
 
 {{appDescription}}
 
-Environment: **{{environment}}** · Credential key: `{{credentialKey}}`
-
-This output is connection and administration material (`channel-chatgpt.json` + `INSTALL.md`), not a plugin archive.
-
-## Workspace admin setup (manual)
-
-1. Sign in to your ChatGPT workspace as an admin and enable **Developer mode / custom MCP apps** if required by workspace policy.
-2. Create a custom MCP app and use the generated artifact from `dist/channels/chatgpt/channel-chatgpt.json` as the connection reference.
-3. Configure the remote MCP URL and transport from **Runtime connection** below.
-4. Complete authentication setup for your workspace policy. Store credential references in AI Fabrix: [Authentication settings]({{credentialPortalUrl}})
-5. Refresh tools in ChatGPT after configuration changes so ChatGPT reads the latest Runtime tool list.
-6. Publish the app to the workspace and configure workspace access controls (RBAC or equivalent).
+**Environment:** {{environment}}  
+**AI Fabrix credential reference:** `{{credentialKey}}`
+
+> 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.
+
+## ChatGPT workspace setup
+
+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.
 
 ## Runtime connection
 
-Configure these values in the ChatGPT custom MCP app. Do not place secrets in generated files.
+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}}
-- **Remote MCP URL:** {{mcpUrl}}
+- **Remote MCP URL:** `{{{mcpUrl}}}`
 {{/if}}
-- **Runtime system key:** {{runtimeSystemKey}}
-- **Transport:** {{runtimeTransport}}
-- **Auth mode:** {{runtimeAuthMode}}
-- **Expected Layer B tools:**
+- **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}}})
+
+The `{{credentialKey}}` value is an AI Fabrix credential reference. It is not a secret to paste into ChatGPT.
+
+## OAuth requirements
+
+Before ChatGPT can connect successfully, the MCP deployment must meet all of these requirements:
+
+- 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.
+
+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}}`
+- `{{this}}`
 {{/each}}
 
-AI Fabrix `--probe` validates Runtime through the first-party MCP gateway
-(`/api/v1/mcp/servers/tools` and MCP docs for `{{runtimeSystemKey}}`), including
-Layer B discovery and BTA Evidence authoring reachability. ChatGPT workspace apps still
-require a working streamable-http Remote MCP URL and admin publication.
-
-## Runtime and Role Assistant boundary checks
+The live server response is authoritative. This list is an expected deployment contract, not a substitute for MCP tool discovery.
 
-- Runtime should resolve assistants dynamically per user from:
+## Runtime and Role Assistant boundaries
 
-{{assistantCatalogUrl}}
+- 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.
 
-- The ChatGPT top-level tool surface should stay at Runtime Layer B tools.
-- Evidence authoring remains an internal Business Transformation Assistant capability path, not top-level ChatGPT tools.
+## BTA evidence-authoring proof scenario
 
-## BTA Evidence-authoring proof scenario
+Use this scenario to verify the ChatGPT → Runtime → BTA path without exposing Evidence commands as top-level ChatGPT tools:
 
-Use this scenario to verify 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.
 
-1. Ask ChatGPT to improve an existing Role Assistant from process documentation.
-2. Confirm ChatGPT starts or continues Business Transformation Assistant work through Runtime.
-3. Confirm BTA performs evidence metadata/download/upload reasoning and presents certified proposals.
-4. Approve selected proposals and confirm activation remains an explicit human action.
+## AI Fabrix validation
 
-## AI Fabrix validation commands
+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.
 
-After workspace publication and authentication setup:
+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

@@ -10,5 +10,6 @@ aifabrix channel add chatgpt --name "Your Assistant" --probe
 ```
 
 The `channel add` step generates `dist/channels/chatgpt/channel-chatgpt.json` and
-`INSTALL.md` for ChatGPT workspace admins to connect a custom MCP app to the
-runtime-orchestration server.
+`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/manifest.template.json.hbs

@@ -6,9 +6,9 @@
   "environment": "{{environment}}",
   "runtime": {
     "runtimeSystemKey": "{{runtimeSystemKey}}",
-    "remoteMcpUrl": "{{mcpUrl}}",
+    "remoteMcpUrl": "{{{mcpUrl}}}",
     "transport": "{{runtimeTransport}}",
-    "assistantCatalogUrl": "{{assistantCatalogUrl}}",
+    "assistantCatalogUrl": "{{{assistantCatalogUrl}}}",
     "roleAssistantResolution": "dynamic-runtime",
     "layerBToolNames": [
 {{#each layerBToolNames}}
@@ -19,7 +19,7 @@
   "authentication": {
     "mode": "{{runtimeAuthMode}}",
     "credentialKey": "{{credentialKey}}",
-    "credentialPortalUrl": "{{credentialPortalUrl}}",
+    "credentialPortalUrl": "{{{credentialPortalUrl}}}",
     "scopes": {{{scopesJson}}}
   },
   "boundaries": {

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

@@ -17,7 +17,7 @@ One Slack app delivers **Role Assistant** chat, **Work hub** shortcuts, and **do
 5. Confirm **App Home → Messages tab** is **ON** in the manifest (required for bot DMs and proactive notifications; slash commands work without it).
 6. Click **Create**, then open **Install App** → **Install to Workspace** and approve.
 7. Copy **Bot User OAuth Token** and **Signing Secret** from the Slack app settings.
-8. Save **Bot User OAuth Token** and **Signing Secret** in AI Fabrix: [Authentication settings]({{credentialPortalUrl}})
+8. Save **Bot User OAuth Token** and **Signing Secret** in AI Fabrix: [Authentication settings]({{{credentialPortalUrl}}})
 
 ## Platform callback URLs
 
@@ -32,6 +32,11 @@ Configure these in your Slack app if you edit settings manually. Do not embed se
 {{#if commandUrl}}
 - **Slash commands:** {{commandUrl}}
 {{/if}}
+{{#if oauthCallbackUrl}}
+- **OAuth Redirect URL:** {{oauthCallbackUrl}}
+{{/if}}
+
+Paste the **OAuth Redirect URL** into Slack app settings → **OAuth & Permissions** → **Redirect URLs** (required for Add to Slack / OAuth).
 
 Register these **V1** slash commands in the manifest (all use the same request URL):
 

package/templates/python/docker-compose.hbs

@@ -53,6 +53,10 @@ services:
     {{/if}}
     env_file:
       - {{envFile}}
+    {{#if devMountPath}}
+    # Bind-mount replaces /app and hides image ENTRYPOINT scripts (e.g. docker-entrypoint.sh).
+    entrypoint: []
+    {{/if}}
     {{#if reloadStartCommand}}
     command: ["sh", "-c", "cd /app && {{{reloadStartCommand}}}"]
     {{/if}}
@@ -111,6 +115,9 @@ services:
       - LOCAL_MODE=false
     env_file:
       - {{envFile}}
+    {{#if devMountPath}}
+    entrypoint: []
+    {{/if}}
     command: ["sh", "-c", "cd /app && {{{workerSidecars.worker.command}}}"]
     networks:
       - {{networkName}}
@@ -136,6 +143,9 @@ services:
       - LOCAL_MODE=false
     env_file:
       - {{envFile}}
+    {{#if devMountPath}}
+    entrypoint: []
+    {{/if}}
     command: ["sh", "-c", "cd /app && {{{workerSidecars.beat.command}}}"]
     networks:
       - {{networkName}}

package/templates/typescript/docker-compose.hbs

@@ -53,6 +53,10 @@ services:
     {{/if}}
     env_file:
       - {{envFile}}
+    {{#if devMountPath}}
+    # Bind-mount replaces /app and hides image ENTRYPOINT scripts (e.g. docker-entrypoint.sh).
+    entrypoint: []
+    {{/if}}
     {{#if reloadStartCommand}}
     command: ["sh", "-c", "cd /app && {{reloadStartCommand}}"]
     {{/if}}
@@ -111,6 +115,9 @@ services:
       - LOCAL_MODE=false
     env_file:
       - {{envFile}}
+    {{#if devMountPath}}
+    entrypoint: []
+    {{/if}}
     command: ["sh", "-c", "cd /app && {{{workerSidecars.worker.command}}}"]
     networks:
       - {{networkName}}
@@ -134,6 +141,9 @@ services:
       - LOCAL_MODE=false
     env_file:
       - {{envFile}}
+    {{#if devMountPath}}
+    entrypoint: []
+    {{/if}}
     command: ["sh", "-c", "cd /app && {{{workerSidecars.beat.command}}}"]
     networks:
       - {{networkName}}