From 5fe5c9ff6b162aee19568fc8d4ef412e7554068d Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Thu, 27 Aug 2026 16:15:49 +0200
Subject: [PATCH 1/9] ai: extract the agent picker into a shared content
 component

The tabs and their three setup steps were inline in the /ai page. They are now
AgentSetupTabs in nuxt/components/content/, so markdown can use them too, and
the changelog entry does instead of listing the agents as links.

excludeExpert drops the FlowFuse Expert tab on surfaces that are specifically
about connecting your own agent. surface prefixes the PostHog positions
everywhere except /ai, whose existing positions are left alone.
---
 nuxt/components/content/AgentSetupTabs.vue    | 189 ++++++++++++++++++
 nuxt/pages/ai/index.vue                       | 156 +--------------
 .../2026/08/connect-your-own-ai-agent.md      |   7 +-
 3 files changed, 199 insertions(+), 153 deletions(-)
 create mode 100644 nuxt/components/content/AgentSetupTabs.vue

diff --git a/nuxt/components/content/AgentSetupTabs.vue b/nuxt/components/content/AgentSetupTabs.vue
new file mode 100644
index 0000000000..bd5df9ae3b
--- /dev/null
+++ b/nuxt/components/content/AgentSetupTabs.vue
@@ -0,0 +1,189 @@
+<script setup lang="ts">
+// The agent picker: a tab per agent, and the three setup steps that apply to the
+// one selected. Lives in components/content/ so markdown can use it as
+// ::agent-setup-tabs as well as pages using it directly, which is the point: the
+// changelog entry and the third-party-agents docs page need the same steps /ai has,
+// and hand-copying them into each surface is how they drift apart.
+//
+// Styling comes from .ff-agent-tabs / .ff-agent-tab / .ff-agent-panel in
+// src/css/style.css, which nuxt.config.ts links on every Nuxt page.
+const props = withDefaults(defineProps<{
+    // Drops the FlowFuse Expert tab. For surfaces that are specifically about
+    // connecting your own agent, where Expert is not one of the options.
+    excludeExpert?: boolean
+    // Whether step 03 ends on a sign-up CTA. Off for documentation, where the
+    // reader already has an account.
+    signup?: boolean
+    // Distinguishes this instance in PostHog. 'ai' keeps the positions the /ai
+    // page already reports, so its existing numbers stay comparable.
+    surface?: string
+}>(), { excludeExpert: false, signup: true, surface: 'ai' })
+
+const capture = useCapture()
+
+const ENDPOINT = 'https://app.flowfuse.com/mcp'
+
+const STEP1 = {
+    title: 'Copy the FlowFuse connector URL',
+    description: 'You will paste this into your agent in the next step.',
+}
+const STEP3 = {
+    title: 'Sign in and choose what it reaches',
+    description: 'Which teams the agent may act on, and whether it has editing rights or read access only.',
+}
+
+// A client renders `logo` as a brand mark when set, `icon` as our own glyph when not.
+// A brand mark keeps its own colours so it stays an <img>; the glyph inherits
+// currentColor and turns white with the label when its tab is active.
+const CLIENTS = [
+    {
+        id: 'expert',
+        logo: '/images/ai/agents/flowfuse-expert.svg',
+        name: 'FlowFuse Expert',
+        builtIn: true,
+        step1Title: 'Sign in to FlowFuse',
+        step1Body: 'A new account puts you in a hosted instance with Expert already in the editor. Nothing to add, no connector, no token.',
+        step2Title: 'Or start with the Device Agent',
+        step2Body: 'Already running Node-RED on your own hardware? Connect it as a remote instance and Expert works there in the same way.',
+        step2Label: 'Install the Device Agent',
+        step2Url: '/docs/device-agent/quickstart/',
+        step3Title: 'Ask for what you need',
+        step3Body: 'Build a flow, explain one you inherited, write the Function node, or ask what is running on the floor. Every write waits for you to approve, edit or reject.',
+        noStep3Cta: true,
+    },
+    {
+        id: 'copilot',
+        logo: '/images/ai/agents/microsoft-copilot.svg',
+        name: 'Microsoft Copilot',
+        step2Title: 'Copilot Studio, Tools, Add a tool',
+        step2Body: 'Choose Model Context Protocol and paste the URL. Describe what it is for: the orchestrator reads that to decide when to call it.',
+        step2Label: 'Open Copilot Studio',
+        step2Url: 'https://copilotstudio.microsoft.com/',
+    },
+    {
+        id: 'chatgpt',
+        logo: '/images/ai/agents/chatgpt.svg',
+        name: 'ChatGPT',
+        step2Title: 'Settings, Connectors',
+        step2Body: 'An administrator enables custom connectors first, under Permissions and Roles.',
+        step2Label: 'Open ChatGPT',
+        step2Url: 'https://chatgpt.com/',
+    },
+    {
+        id: 'claude',
+        logo: '/images/ai/agents/claude.svg',
+        name: 'Claude',
+        step2Title: 'Settings, Customize, Connectors',
+        step2Body: 'Add a custom connector and paste the URL. On Team and Enterprise an owner adds it once for everyone.',
+        step2Label: 'Open Claude connectors',
+        step2Url: 'https://claude.ai/settings/connectors',
+    },
+    {
+        id: 'gemini',
+        logo: '/images/ai/agents/gemini.svg',
+        name: 'Gemini',
+        step2Title: 'Settings, Manage team, Connected apps',
+        step2Body: 'Add the FlowFuse URL as an MCP server.',
+        step2Label: 'Open Gemini',
+        step2Url: 'https://gemini.google.com/',
+    },
+    {
+        id: 'local',
+        icon: 'i-lucide-server',
+        name: 'Local and Custom Agents',
+        step2Title: "Your MCP client's config",
+        step2Body: 'Any MCP-capable client works, pointed at your own model, so nothing has to leave your network.',
+        step2Label: 'See the documentation',
+        step2Url: '/docs/user/expert/',
+    },
+]
+
+const clients = computed(() => props.excludeExpert ? CLIENTS.filter(client => !client.builtIn) : CLIENTS)
+
+// Prefix only off the /ai page, so the positions that page already reports to
+// PostHog keep their current values and its existing insights stay valid.
+function pos (id: string) {
+    return props.surface === 'ai' ? id : `${props.surface}-${id}`
+}
+
+const activeClient = ref(clients.value[0].id)
+
+// A surface can switch excludeExpert at runtime in dev; keep the selection valid.
+watch(clients, (list) => {
+    if (!list.some(client => client.id === activeClient.value)) activeClient.value = list[0].id
+})
+
+function selectClient (id: string) {
+    activeClient.value = id
+    capture('cta-ai-agent-tab', { position: pos(id) })
+}
+</script>
+
+<template>
+  <div class="mt-12 overflow-hidden rounded-xl border border-indigo-100 bg-white shadow-sm">
+    <div class="ff-agent-tabs flex flex-nowrap gap-1 overflow-x-auto border-b border-indigo-100 bg-indigo-50/60 p-2" role="tablist" aria-label="Choose your AI agent">
+      <button
+        v-for="client in clients"
+        :id="`ff-tab-${client.id}`"
+        :key="client.id"
+        type="button"
+        role="tab"
+        :aria-controls="`ff-panel-${client.id}`"
+        :aria-selected="activeClient === client.id"
+        class="ff-agent-tab flex flex-none items-center gap-2 whitespace-nowrap rounded-lg px-3 py-2 text-sm font-medium transition"
+        :class="activeClient === client.id ? 'bg-indigo-600 text-white shadow-sm' : 'text-gray-600 hover:bg-white hover:text-gray-900'"
+        @click="selectClient(client.id)"
+      >
+        <UIcon v-if="client.icon" :name="client.icon" class="flex-none size-4" aria-hidden="true" />
+        <img v-else-if="client.logo" :src="client.logo" alt="" class="h-4 w-auto flex-none" aria-hidden="true">
+        <span>{{ client.name }}</span>
+      </button>
+    </div>
+
+    <div
+      v-for="client in clients"
+      v-show="activeClient === client.id"
+      :id="`ff-panel-${client.id}`"
+      :key="`panel-${client.id}`"
+      role="tabpanel"
+      :aria-labelledby="`ff-tab-${client.id}`"
+      class="ff-agent-panel grid grid-cols-1 gap-8 p-6 md:grid-cols-3 md:gap-10 md:p-8"
+    >
+      <div class="flex flex-col">
+        <p class="font-mono text-xs font-semibold text-indigo-600 m-0">01</p>
+        <p class="text-lg font-medium text-gray-900 mt-2 mb-0">{{ client.builtIn ? client.step1Title : STEP1.title }}</p>
+        <p class="text-gray-600 font-light text-sm mt-2 mb-0">{{ client.builtIn ? client.step1Body : STEP1.description }}</p>
+        <div v-if="client.builtIn" class="mt-auto pt-5">
+          <CtaSignUp variant="primary" :position="`${surface}-tab-expert`" class="w-full" />
+        </div>
+        <div v-else class="mt-auto pt-5">
+          <FfCommand :command="ENDPOINT" event="cta-copy-mcp-endpoint" :position="pos(client.id)" stacked />
+        </div>
+      </div>
+
+      <div class="flex flex-col">
+        <p class="font-mono text-xs font-semibold text-indigo-600 m-0">02</p>
+        <p class="text-lg font-medium text-gray-900 mt-2 mb-0">{{ client.step2Title }}</p>
+        <p class="text-gray-600 font-light text-sm mt-2 mb-0">{{ client.step2Body }}</p>
+        <div class="mt-auto pt-5">
+          <a
+            :href="client.step2Url"
+            class="ff-btn ff-btn--primary-outlined flex w-full"
+            :target="client.step2Url.startsWith('http') ? '_blank' : undefined"
+            :rel="client.step2Url.startsWith('http') ? 'noopener' : undefined"
+            @click="capture('cta-ai-open-client', { position: pos(client.id) })"
+          >{{ client.step2Label }}</a>
+        </div>
+      </div>
+
+      <div class="flex flex-col">
+        <p class="font-mono text-xs font-semibold text-indigo-600 m-0">03</p>
+        <p class="text-lg font-medium text-gray-900 mt-2 mb-0">{{ client.step3Title || STEP3.title }}</p>
+        <p class="text-gray-600 font-light text-sm mt-2 mb-0">{{ client.step3Body || STEP3.description }}</p>
+        <div v-if="signup && !client.noStep3Cta" class="mt-auto pt-5">
+          <CtaSignUp variant="primary" :position="`${surface}-connect-step3`" class="w-full" />
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/nuxt/pages/ai/index.vue b/nuxt/pages/ai/index.vue
index abcbddd699..ed3ea81a3d 100644
--- a/nuxt/pages/ai/index.vue
+++ b/nuxt/pages/ai/index.vue
@@ -6,8 +6,9 @@ import { getAllBlogPosts } from '~/utils/sharedContent'
 // What the port changes on purpose:
 //  - The two hand-rolled DOM scripts (agent tabs, showcase rotation) become
 //    reactive state. That was ~120 lines of querySelectorAll in the .njk.
-//  - The copy button becomes <FfCommand>, shared with the changelog and any other
-//    markdown page, instead of markup plus a copy helper pasted per page.
+//  - The copy button becomes <FfCommand>, and the whole agent picker becomes
+//    <AgentSetupTabs>, both shared with the changelog and the docs page instead
+//    of markup plus a copy helper pasted per page.
 //  - jsonld.njk's meta.faq becomes useSchemaOrg, which escapes properly. The 11ty
 //    partial interpolated answers straight into a JSON string.
 //  - Sign-up buttons become <CtaSignUp>, so the copy is the site's fixed "Try it
@@ -52,92 +53,8 @@ useSchemaOrg([
     ...FAQ.map(item => defineQuestion({ question: item.question, answer: item.answer })),
 ])
 
-const ENDPOINT = 'https://app.flowfuse.com/mcp'
-
-const STEP1 = {
-    title: 'Copy the FlowFuse connector URL',
-    description: 'You will paste this into your agent in the next step.',
-}
-const STEP3 = {
-    title: 'Sign in and choose what it reaches',
-    description: 'Which teams the agent may act on, and whether it has editing rights or read access only.',
-}
-
-// A client renders `logo` as a brand mark when set, `icon` as our own glyph when not.
-// A brand mark keeps its own colours so it stays an <img>; the glyph inherits
-// currentColor and turns white with the label when its tab is active.
-const CLIENTS = [
-    {
-        id: 'expert',
-        logo: '/images/ai/agents/flowfuse-expert.svg',
-        name: 'FlowFuse Expert',
-        builtIn: true,
-        step1Title: 'Sign in to FlowFuse',
-        step1Body: 'A new account puts you in a hosted instance with Expert already in the editor. Nothing to add, no connector, no token.',
-        step2Title: 'Or start with the Device Agent',
-        step2Body: 'Already running Node-RED on your own hardware? Connect it as a remote instance and Expert works there in the same way.',
-        step2Label: 'Install the Device Agent',
-        step2Url: '/docs/device-agent/quickstart/',
-        step3Title: 'Ask for what you need',
-        step3Body: 'Build a flow, explain one you inherited, write the Function node, or ask what is running on the floor. Every write waits for you to approve, edit or reject.',
-        noStep3Cta: true,
-    },
-    {
-        id: 'copilot',
-        logo: '/images/ai/agents/microsoft-copilot.svg',
-        name: 'Microsoft Copilot',
-        step2Title: 'Copilot Studio, Tools, Add a tool',
-        step2Body: 'Choose Model Context Protocol and paste the URL. Describe what it is for: the orchestrator reads that to decide when to call it.',
-        step2Label: 'Open Copilot Studio',
-        step2Url: 'https://copilotstudio.microsoft.com/',
-    },
-    {
-        id: 'chatgpt',
-        logo: '/images/ai/agents/chatgpt.svg',
-        name: 'ChatGPT',
-        step2Title: 'Settings, Connectors',
-        step2Body: 'An administrator enables custom connectors first, under Permissions and Roles.',
-        step2Label: 'Open ChatGPT',
-        step2Url: 'https://chatgpt.com/',
-    },
-    {
-        id: 'claude',
-        logo: '/images/ai/agents/claude.svg',
-        name: 'Claude',
-        step2Title: 'Settings, Customize, Connectors',
-        step2Body: 'Add a custom connector and paste the URL. On Team and Enterprise an owner adds it once for everyone.',
-        step2Label: 'Open Claude connectors',
-        step2Url: 'https://claude.ai/settings/connectors',
-    },
-    {
-        id: 'gemini',
-        logo: '/images/ai/agents/gemini.svg',
-        name: 'Gemini',
-        step2Title: 'Settings, Manage team, Connected apps',
-        step2Body: 'Add the FlowFuse URL as an MCP server.',
-        step2Label: 'Open Gemini',
-        step2Url: 'https://gemini.google.com/',
-    },
-    {
-        id: 'local',
-        icon: 'i-lucide-server',
-        name: 'Local and Custom Agents',
-        step2Title: "Your MCP client's config",
-        step2Body: 'Any MCP-capable client works, pointed at your own model, so nothing has to leave your network.',
-        step2Label: 'See the documentation',
-        step2Url: '/docs/user/expert/',
-    },
-]
-
 const CODING_NOTE = 'Command-line and editor agents such as Claude Code, Cursor, Visual Studio Code and Gemini CLI connect to the same URL.'
 
-const activeClient = ref(CLIENTS[0].id)
-
-function selectClient (id: string) {
-    activeClient.value = id
-    capture('cta-ai-agent-tab', { position: id })
-}
-
 const GOVERNANCE = {
     title: 'AI Governance you can <span class="text-indigo-600">prove</span>',
     subtitle: 'The control plane every AI action runs through, the same one that governs your teams.',
@@ -289,72 +206,7 @@ onUnmounted(() => {
 
             <!-- CONNECTOR: pick your agent, then three steps specific to it, so the
                  reader only sees the instructions that apply to them. -->
-            <div class="mt-12 overflow-hidden rounded-xl border border-indigo-100 bg-white shadow-sm">
-              <div class="ff-agent-tabs flex flex-nowrap gap-1 overflow-x-auto border-b border-indigo-100 bg-indigo-50/60 p-2" role="tablist" aria-label="Choose your AI agent">
-                <button
-                  v-for="client in CLIENTS"
-                  :id="`ff-tab-${client.id}`"
-                  :key="client.id"
-                  type="button"
-                  role="tab"
-                  :aria-controls="`ff-panel-${client.id}`"
-                  :aria-selected="activeClient === client.id"
-                  class="ff-agent-tab flex flex-none items-center gap-2 whitespace-nowrap rounded-lg px-3 py-2 text-sm font-medium transition"
-                  :class="activeClient === client.id ? 'bg-indigo-600 text-white shadow-sm' : 'text-gray-600 hover:bg-white hover:text-gray-900'"
-                  @click="selectClient(client.id)"
-                >
-                  <UIcon v-if="client.icon" :name="client.icon" class="flex-none size-4" aria-hidden="true" />
-                  <img v-else-if="client.logo" :src="client.logo" alt="" class="h-4 w-auto flex-none" aria-hidden="true">
-                  <span>{{ client.name }}</span>
-                </button>
-              </div>
-
-              <div
-                v-for="client in CLIENTS"
-                v-show="activeClient === client.id"
-                :id="`ff-panel-${client.id}`"
-                :key="`panel-${client.id}`"
-                role="tabpanel"
-                :aria-labelledby="`ff-tab-${client.id}`"
-                class="ff-agent-panel grid grid-cols-1 gap-8 p-6 md:grid-cols-3 md:gap-10 md:p-8"
-              >
-                <div class="flex flex-col">
-                  <p class="font-mono text-xs font-semibold text-indigo-600 m-0">01</p>
-                  <p class="text-lg font-medium text-gray-900 mt-2 mb-0">{{ client.builtIn ? client.step1Title : STEP1.title }}</p>
-                  <p class="text-gray-600 font-light text-sm mt-2 mb-0">{{ client.builtIn ? client.step1Body : STEP1.description }}</p>
-                  <div v-if="client.builtIn" class="mt-auto pt-5">
-                    <CtaSignUp variant="primary" position="ai-tab-expert" class="w-full" />
-                  </div>
-                  <div v-else class="mt-auto pt-5">
-                    <FfCommand :command="ENDPOINT" event="cta-copy-mcp-endpoint" :position="client.id" stacked />
-                  </div>
-                </div>
-
-                <div class="flex flex-col">
-                  <p class="font-mono text-xs font-semibold text-indigo-600 m-0">02</p>
-                  <p class="text-lg font-medium text-gray-900 mt-2 mb-0">{{ client.step2Title }}</p>
-                  <p class="text-gray-600 font-light text-sm mt-2 mb-0">{{ client.step2Body }}</p>
-                  <div class="mt-auto pt-5">
-                    <a
-                      :href="client.step2Url"
-                      class="ff-btn ff-btn--primary-outlined flex w-full"
-                      :target="client.step2Url.startsWith('http') ? '_blank' : undefined"
-                      :rel="client.step2Url.startsWith('http') ? 'noopener' : undefined"
-                      @click="capture('cta-ai-open-client', { position: client.id })"
-                    >{{ client.step2Label }}</a>
-                  </div>
-                </div>
-
-                <div class="flex flex-col">
-                  <p class="font-mono text-xs font-semibold text-indigo-600 m-0">03</p>
-                  <p class="text-lg font-medium text-gray-900 mt-2 mb-0">{{ client.step3Title || STEP3.title }}</p>
-                  <p class="text-gray-600 font-light text-sm mt-2 mb-0">{{ client.step3Body || STEP3.description }}</p>
-                  <div v-if="!client.noStep3Cta" class="mt-auto pt-5">
-                    <CtaSignUp variant="primary" position="ai-connect-step3" class="w-full" />
-                  </div>
-                </div>
-              </div>
-            </div>
+            <AgentSetupTabs />
             <!-- Docs pointer, not a step. Carded in the same tinted, hover-lifting
                  treatment the platform page uses for its How-it-works blocks, so it
                  reads as somewhere to go rather than as fine print under step 03.
diff --git a/src/changelog/2026/08/connect-your-own-ai-agent.md b/src/changelog/2026/08/connect-your-own-ai-agent.md
index cd6ba26ab8..40ca12308c 100644
--- a/src/changelog/2026/08/connect-your-own-ai-agent.md
+++ b/src/changelog/2026/08/connect-your-own-ai-agent.md
@@ -14,7 +14,12 @@ You can now connect your own AI agent to FlowFuse. Your company-approved AI can
 
 Add the FlowFuse address to connect, then decide which teams the agent reaches and whether it can make changes.
 
-The address is `https://app.flowfuse.com/mcp`. [Pick your agent on the AI page](/ai/) for the exact steps in [Microsoft Copilot](https://copilotstudio.microsoft.com/), [ChatGPT](https://chatgpt.com/), [Claude](https://claude.ai/settings/connectors) or [Gemini](https://gemini.google.com/). Any MCP client that supports the HTTP transport works too, including command-line and editor agents and local models. Sign-in uses OAuth where the client supports it, with a token fallback where it does not.
+Pick your agent, and follow the three steps:
+
+::agent-setup-tabs{:exclude-expert="true" surface="changelog"}
+::
+
+Any MCP client that supports the HTTP transport works, including command-line and editor agents and local models. Sign-in uses OAuth where the client supports it, with a token fallback where it does not.
 
 Your own agent gets the full, growing set of FlowFuse platform automation and flow-building tools to run. That matters most where company policy only permits an approved AI agent, so FlowFuse Expert wasn't an option.
 

From 43af411beadda599597c40e1ec41c666c6036265 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Thu, 27 Aug 2026 16:24:04 +0200
Subject: [PATCH 2/9] ai: move the agent picker's look into unlayered CSS so it
 survives prose

---
 nuxt/components/content/AgentSetupTabs.vue |  54 +++++----
 src/css/style.css                          | 131 ++++++++++++++++++---
 2 files changed, 141 insertions(+), 44 deletions(-)

diff --git a/nuxt/components/content/AgentSetupTabs.vue b/nuxt/components/content/AgentSetupTabs.vue
index bd5df9ae3b..8a5b91134b 100644
--- a/nuxt/components/content/AgentSetupTabs.vue
+++ b/nuxt/components/content/AgentSetupTabs.vue
@@ -5,8 +5,12 @@
 // changelog entry and the third-party-agents docs page need the same steps /ai has,
 // and hand-copying them into each surface is how they drift apart.
 //
-// Styling comes from .ff-agent-tabs / .ff-agent-tab / .ff-agent-panel in
-// src/css/style.css, which nuxt.config.ts links on every Nuxt page.
+// Styling comes from the .ff-agent-* rules in src/css/style.css, which nuxt.config.ts
+// links on every Nuxt page, rather than from utility classes on the elements. That is
+// forced: this renders inside .prose on the changelog and docs pages, and the site's
+// prose rules sit in @layer overrides, which outranks Tailwind's @layer utilities
+// whatever the specificity. As utilities, `h-4` on a tab logo lost to .prose img's
+// width:100% and the marks blew up to full column width.
 const props = withDefaults(defineProps<{
     // Drops the FlowFuse Expert tab. For surfaces that are specifically about
     // connecting your own agent, where Expert is not one of the options.
@@ -120,22 +124,22 @@ function selectClient (id: string) {
 </script>
 
 <template>
-  <div class="mt-12 overflow-hidden rounded-xl border border-indigo-100 bg-white shadow-sm">
-    <div class="ff-agent-tabs flex flex-nowrap gap-1 overflow-x-auto border-b border-indigo-100 bg-indigo-50/60 p-2" role="tablist" aria-label="Choose your AI agent">
+  <div class="ff-agent-card overflow-hidden rounded-xl border border-indigo-100 bg-white shadow-sm">
+    <div class="ff-agent-tabs border-b border-indigo-100 bg-indigo-50/60" role="tablist" aria-label="Choose your AI agent">
       <button
         v-for="client in clients"
         :id="`ff-tab-${client.id}`"
         :key="client.id"
         type="button"
         role="tab"
+        class="ff-agent-tab"
+        :class="{ 'ff-agent-tab--active': activeClient === client.id }"
         :aria-controls="`ff-panel-${client.id}`"
         :aria-selected="activeClient === client.id"
-        class="ff-agent-tab flex flex-none items-center gap-2 whitespace-nowrap rounded-lg px-3 py-2 text-sm font-medium transition"
-        :class="activeClient === client.id ? 'bg-indigo-600 text-white shadow-sm' : 'text-gray-600 hover:bg-white hover:text-gray-900'"
         @click="selectClient(client.id)"
       >
-        <UIcon v-if="client.icon" :name="client.icon" class="flex-none size-4" aria-hidden="true" />
-        <img v-else-if="client.logo" :src="client.logo" alt="" class="h-4 w-auto flex-none" aria-hidden="true">
+        <UIcon v-if="client.icon" :name="client.icon" class="ff-agent-tab__glyph" aria-hidden="true" />
+        <img v-else-if="client.logo" :src="client.logo" alt="" aria-hidden="true">
         <span>{{ client.name }}</span>
       </button>
     </div>
@@ -147,25 +151,25 @@ function selectClient (id: string) {
       :key="`panel-${client.id}`"
       role="tabpanel"
       :aria-labelledby="`ff-tab-${client.id}`"
-      class="ff-agent-panel grid grid-cols-1 gap-8 p-6 md:grid-cols-3 md:gap-10 md:p-8"
+      class="ff-agent-panel"
     >
-      <div class="flex flex-col">
-        <p class="font-mono text-xs font-semibold text-indigo-600 m-0">01</p>
-        <p class="text-lg font-medium text-gray-900 mt-2 mb-0">{{ client.builtIn ? client.step1Title : STEP1.title }}</p>
-        <p class="text-gray-600 font-light text-sm mt-2 mb-0">{{ client.builtIn ? client.step1Body : STEP1.description }}</p>
-        <div v-if="client.builtIn" class="mt-auto pt-5">
+      <div class="ff-agent-step">
+        <p class="ff-agent-step__num">01</p>
+        <p class="ff-agent-step__title">{{ client.builtIn ? client.step1Title : STEP1.title }}</p>
+        <p class="ff-agent-step__body">{{ client.builtIn ? client.step1Body : STEP1.description }}</p>
+        <div v-if="client.builtIn" class="ff-agent-step__cta">
           <CtaSignUp variant="primary" :position="`${surface}-tab-expert`" class="w-full" />
         </div>
-        <div v-else class="mt-auto pt-5">
+        <div v-else class="ff-agent-step__cta">
           <FfCommand :command="ENDPOINT" event="cta-copy-mcp-endpoint" :position="pos(client.id)" stacked />
         </div>
       </div>
 
-      <div class="flex flex-col">
-        <p class="font-mono text-xs font-semibold text-indigo-600 m-0">02</p>
-        <p class="text-lg font-medium text-gray-900 mt-2 mb-0">{{ client.step2Title }}</p>
-        <p class="text-gray-600 font-light text-sm mt-2 mb-0">{{ client.step2Body }}</p>
-        <div class="mt-auto pt-5">
+      <div class="ff-agent-step">
+        <p class="ff-agent-step__num">02</p>
+        <p class="ff-agent-step__title">{{ client.step2Title }}</p>
+        <p class="ff-agent-step__body">{{ client.step2Body }}</p>
+        <div class="ff-agent-step__cta">
           <a
             :href="client.step2Url"
             class="ff-btn ff-btn--primary-outlined flex w-full"
@@ -176,11 +180,11 @@ function selectClient (id: string) {
         </div>
       </div>
 
-      <div class="flex flex-col">
-        <p class="font-mono text-xs font-semibold text-indigo-600 m-0">03</p>
-        <p class="text-lg font-medium text-gray-900 mt-2 mb-0">{{ client.step3Title || STEP3.title }}</p>
-        <p class="text-gray-600 font-light text-sm mt-2 mb-0">{{ client.step3Body || STEP3.description }}</p>
-        <div v-if="signup && !client.noStep3Cta" class="mt-auto pt-5">
+      <div class="ff-agent-step">
+        <p class="ff-agent-step__num">03</p>
+        <p class="ff-agent-step__title">{{ client.step3Title || STEP3.title }}</p>
+        <p class="ff-agent-step__body">{{ client.step3Body || STEP3.description }}</p>
+        <div v-if="signup && !client.noStep3Cta" class="ff-agent-step__cta">
           <CtaSignUp variant="primary" :position="`${surface}-connect-step3`" class="w-full" />
         </div>
       </div>
diff --git a/src/css/style.css b/src/css/style.css
index 819311f998..6203aa990f 100644
--- a/src/css/style.css
+++ b/src/css/style.css
@@ -3271,14 +3271,62 @@ lite-youtube::before {
     border-left: 2px solid var(--color-indigo-200);
 }
 
+/* AgentSetupTabs: the agent picker and its three setup steps. Unlayered on purpose.
+   The component renders inside .prose on the changelog entry and the third-party-agents
+   docs page as well as standalone on /ai, and the site's prose rules live in
+   @layer overrides, which outranks Tailwind's @layer utilities however specific the
+   utility is. So the component's look cannot live in utility classes on the elements:
+   .prose img's width:100% beat `h-4` and blew the tab marks up to full column width,
+   and .prose p forced the step text to 12px. Unlayered outranks every layer, so these
+   rules hold in prose and out of it. Keep visual values here, not in the template.
+
+   Sizing is driven by the component's own width via @container, not by the viewport.
+   A viewport md: breakpoint gave three 186px columns inside a 704px prose column,
+   because the viewport was wide while the column was not. */
+.ff-agent-card {
+    container-type: inline-size;
+    margin-top: 2rem;
+}
+
 /* Agent tab: a segmented control on the tinted rail, not a row of CTA buttons.
-   The brand's solid indigo marks the active one; the rest stay quiet until hovered.
-   Sizing and colour are utility classes on the element - only the focus ring lives
-   here, because the ring has to clear the pill on all four sides inside a scroller
-   that would otherwise clip it. */
+   The brand's solid indigo marks the active one; the rest stay quiet until hovered. */
+.ff-agent-tabs {
+    display: flex;
+    gap: 0.25rem;
+    padding: 0.5rem;
+    /* Wraps rather than scrolling. In a prose column the strip is too narrow to show
+       five agents on one line, and a sideways scroller hides the last of them off the
+       edge with nothing to say so. */
+    flex-wrap: wrap;
+}
+.ff-agent-tab {
+    display: flex;
+    flex: none;
+    align-items: center;
+    gap: 0.5rem;
+    white-space: nowrap;
+    border-radius: 0.5rem;
+    padding: 0.5rem 0.75rem;
+    font-size: 0.875rem;
+    font-weight: 500;
+    line-height: 1.25rem;
+    color: var(--color-gray-600);
+    transition: background-color 0.15s, color 0.15s;
+}
+.ff-agent-tab:hover {
+    background-color: #fff;
+    color: var(--color-gray-900);
+}
+.ff-agent-tab--active,
+.ff-agent-tab--active:hover {
+    background-color: var(--color-indigo-600);
+    color: #fff;
+    box-shadow: var(--shadow-sm);
+}
 .ff-agent-tab:focus {
     outline: none;
 }
+/* The ring has to clear the pill on all four sides. */
 .ff-agent-tab:focus-visible {
     outline: 2px solid var(--color-indigo-600);
     outline-offset: 2px;
@@ -3286,7 +3334,67 @@ lite-youtube::before {
 /* The brand marks are <img>, so they keep their own colours; our own glyphs are
    masked spans that inherit currentColor and turn white with the label. */
 .ff-agent-tab img {
+    height: 1rem;
+    width: auto;
     flex: none;
+    margin: 0;
+    border-radius: 0;
+}
+.ff-agent-tab__glyph {
+    height: 1rem;
+    width: 1rem;
+    flex: none;
+}
+
+.ff-agent-panel {
+    display: grid;
+    grid-template-columns: 1fr;
+    gap: 2rem;
+    padding: 1.5rem;
+}
+.ff-agent-step {
+    display: flex;
+    flex-direction: column;
+}
+.ff-agent-step__num {
+    margin: 0;
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    font-weight: 600;
+    line-height: 1rem;
+    color: var(--color-indigo-600);
+}
+.ff-agent-step__title {
+    margin: 0.5rem 0 0;
+    font-size: 1.125rem;
+    font-weight: 500;
+    line-height: 1.75rem;
+    color: var(--color-gray-900);
+}
+.ff-agent-step__body {
+    margin: 0.5rem 0 0;
+    font-size: 0.875rem;
+    font-weight: 300;
+    line-height: 1.5rem;
+    color: var(--color-gray-600);
+}
+/* mt-auto: pins every CTA to the bottom so the three line up however unevenly the
+   bodies above them wrap. */
+.ff-agent-step__cta {
+    margin-top: auto;
+    padding-top: 1.25rem;
+}
+.ff-agent-step__cta a {
+    text-decoration: none;
+}
+
+/* Three across only once the component itself is wide enough for it. */
+@container (min-width: 44rem) {
+    .ff-agent-panel {
+        grid-template-columns: repeat(3, minmax(0, 1fr));
+        gap: 2.5rem;
+        padding: 2rem;
+    }
 }
 
 /* The three step CTAs are three different elements - CtaSignUp's UButton, an
@@ -3307,21 +3415,6 @@ lite-youtube::before {
     padding-bottom: 0;
 }
 
-/* Agent tab strip: scrolls sideways rather than wrapping, so the row stays one line at
-   any width. Thin scrollbar so it reads as a control, not a scroll container. */
-.ff-agent-tabs {
-    scrollbar-width: thin;
-    -webkit-overflow-scrolling: touch;
-    overscroll-behavior-x: contain;
-}
-.ff-agent-tabs::-webkit-scrollbar {
-    height: 6px;
-}
-.ff-agent-tabs::-webkit-scrollbar-thumb {
-    background-color: var(--color-gray-300);
-    border-radius: 3px;
-}
-
 /* Media well: the frame around each capability's schematic. */
 .ff-cap-well {
     /* Matches the diagram's 720x150 viewBox, so the frame hugs the drawing instead

From 9c669f19672c44f8a6c306ef8b49237a0ef465d5 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Thu, 27 Aug 2026 16:27:49 +0200
Subject: [PATCH 3/9] ai: size the agent panel by its own width, not the
 viewport

---
 src/css/style.css | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/css/style.css b/src/css/style.css
index 5ad5684004..4374235157 100644
--- a/src/css/style.css
+++ b/src/css/style.css
@@ -3431,8 +3431,13 @@ lite-youtube::before {
     text-decoration: none;
 }
 
-/* Three across only once the component itself is wide enough for it. */
-@container (min-width: 44rem) {
+/* Three across only once the component itself is wide enough for it. 60rem is set by
+   the widest thing a column has to hold without clipping: the connector URL in the
+   copy block, ~270px of mono text plus its padding, times three, plus the gaps and
+   the panel padding. Below that the steps stack, which is what the changelog entry
+   and the docs page get in their ~700px prose column. At 44rem the docs page took
+   three 190px columns and cut the URL off mid-domain. */
+@container (min-width: 60rem) {
     .ff-agent-panel {
         grid-template-columns: repeat(3, minmax(0, 1fr));
         gap: 2.5rem;

From 9e8802eb7f08d3e4921ece97a0453faa15dfc2d7 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Thu, 27 Aug 2026 16:32:15 +0200
Subject: [PATCH 4/9] ai: shrink the step CTAs to their labels when the steps
 stack

---
 src/css/style.css | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/src/css/style.css b/src/css/style.css
index 4374235157..22ec3fe630 100644
--- a/src/css/style.css
+++ b/src/css/style.css
@@ -3426,6 +3426,16 @@ lite-youtube::before {
 .ff-agent-step__cta {
     margin-top: auto;
     padding-top: 1.25rem;
+    /* Stacked, a step is as wide as the whole prose column, and a control stretched
+       across that reads as a banner rather than something to click. Shrink to the
+       label and sit left. The w-full utilities on the three CTAs are overridden here
+       rather than removed from the template, because they are still what makes the
+       three fill their columns in the wide layout below. */
+    align-self: flex-start;
+    max-width: 100%;
+}
+.ff-agent-step__cta > * {
+    width: auto;
 }
 .ff-agent-step__cta a {
     text-decoration: none;
@@ -3443,6 +3453,14 @@ lite-youtube::before {
         gap: 2.5rem;
         padding: 2rem;
     }
+    /* Three across, the columns are narrow enough that filling them is right: the row
+       then reads as one control repeated rather than three different-width buttons. */
+    .ff-agent-step__cta {
+        align-self: stretch;
+    }
+    .ff-agent-step__cta > * {
+        width: 100%;
+    }
 }
 
 /* The three step CTAs are three different elements - CtaSignUp's UButton, an

From c685e6fc361a6a8ac0cb5c4fee5d63d2b7b4dfd6 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Thu, 27 Aug 2026 16:36:13 +0200
Subject: [PATCH 5/9] ai: give the card room in prose, and one width for the
 stacked CTAs

---
 nuxt/pages/ai/index.vue |  2 +-
 src/css/style.css       | 24 ++++++++++++++----------
 2 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/nuxt/pages/ai/index.vue b/nuxt/pages/ai/index.vue
index ed3ea81a3d..e9a031295f 100644
--- a/nuxt/pages/ai/index.vue
+++ b/nuxt/pages/ai/index.vue
@@ -206,7 +206,7 @@ onUnmounted(() => {
 
             <!-- CONNECTOR: pick your agent, then three steps specific to it, so the
                  reader only sees the instructions that apply to them. -->
-            <AgentSetupTabs />
+            <AgentSetupTabs class="mt-12" />
             <!-- Docs pointer, not a step. Carded in the same tinted, hover-lifting
                  treatment the platform page uses for its How-it-works blocks, so it
                  reads as somewhere to go rather than as fine print under step 03.
diff --git a/src/css/style.css b/src/css/style.css
index 22ec3fe630..4202f232ed 100644
--- a/src/css/style.css
+++ b/src/css/style.css
@@ -3328,7 +3328,13 @@ lite-youtube::before {
    because the viewport was wide while the column was not. */
 .ff-agent-card {
     container-type: inline-size;
+}
+/* In prose the card is a block between paragraphs and needs air on both sides. Left
+   off the base rule so /ai keeps setting its own top margin, where the card is
+   followed by the docs-pointer card rather than by body copy. */
+.prose .ff-agent-card {
     margin-top: 2rem;
+    margin-bottom: 2rem;
 }
 
 /* Agent tab: a segmented control on the tinted rail, not a row of CTA buttons.
@@ -3427,15 +3433,16 @@ lite-youtube::before {
     margin-top: auto;
     padding-top: 1.25rem;
     /* Stacked, a step is as wide as the whole prose column, and a control stretched
-       across that reads as a banner rather than something to click. Shrink to the
-       label and sit left. The w-full utilities on the three CTAs are overridden here
-       rather than removed from the template, because they are still what makes the
-       three fill their columns in the wide layout below. */
+       across that reads as a banner rather than something to click. So the CTAs get a
+       fixed width and sit left: still one width for all three, so the column reads as
+       one control repeated, but nothing like the full measure. 18rem is set by the
+       widest thing one has to hold, the connector URL in the copy block at ~274px. */
     align-self: flex-start;
+    width: 18rem;
     max-width: 100%;
 }
 .ff-agent-step__cta > * {
-    width: auto;
+    width: 100%;
 }
 .ff-agent-step__cta a {
     text-decoration: none;
@@ -3453,13 +3460,10 @@ lite-youtube::before {
         gap: 2.5rem;
         padding: 2rem;
     }
-    /* Three across, the columns are narrow enough that filling them is right: the row
-       then reads as one control repeated rather than three different-width buttons. */
+    /* Three across, the columns are narrow enough that filling them is right. */
     .ff-agent-step__cta {
         align-self: stretch;
-    }
-    .ff-agent-step__cta > * {
-        width: 100%;
+        width: auto;
     }
 }
 

From df86891b1ab45c0e0775397774f4a29b05141218 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Thu, 27 Aug 2026 18:26:08 +0200
Subject: [PATCH 6/9] ai: keep the changelog entry out of this branch, it lands
 separately

---
 src/changelog/2026/08/connect-your-own-ai-agent.md | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/src/changelog/2026/08/connect-your-own-ai-agent.md b/src/changelog/2026/08/connect-your-own-ai-agent.md
index 40ca12308c..cd6ba26ab8 100644
--- a/src/changelog/2026/08/connect-your-own-ai-agent.md
+++ b/src/changelog/2026/08/connect-your-own-ai-agent.md
@@ -14,12 +14,7 @@ You can now connect your own AI agent to FlowFuse. Your company-approved AI can
 
 Add the FlowFuse address to connect, then decide which teams the agent reaches and whether it can make changes.
 
-Pick your agent, and follow the three steps:
-
-::agent-setup-tabs{:exclude-expert="true" surface="changelog"}
-::
-
-Any MCP client that supports the HTTP transport works, including command-line and editor agents and local models. Sign-in uses OAuth where the client supports it, with a token fallback where it does not.
+The address is `https://app.flowfuse.com/mcp`. [Pick your agent on the AI page](/ai/) for the exact steps in [Microsoft Copilot](https://copilotstudio.microsoft.com/), [ChatGPT](https://chatgpt.com/), [Claude](https://claude.ai/settings/connectors) or [Gemini](https://gemini.google.com/). Any MCP client that supports the HTTP transport works too, including command-line and editor agents and local models. Sign-in uses OAuth where the client supports it, with a token fallback where it does not.
 
 Your own agent gets the full, growing set of FlowFuse platform automation and flow-building tools to run. That matters most where company policy only permits an approved AI agent, so FlowFuse Expert wasn't an option.
 

From 03629311941722a579a2a172697211b8fabdff57 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Thu, 27 Aug 2026 18:26:11 +0200
Subject: [PATCH 7/9] changelog: use the shared agent picker instead of listing
 the agents

---
 src/changelog/2026/08/connect-your-own-ai-agent.md | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/changelog/2026/08/connect-your-own-ai-agent.md b/src/changelog/2026/08/connect-your-own-ai-agent.md
index cd6ba26ab8..40ca12308c 100644
--- a/src/changelog/2026/08/connect-your-own-ai-agent.md
+++ b/src/changelog/2026/08/connect-your-own-ai-agent.md
@@ -14,7 +14,12 @@ You can now connect your own AI agent to FlowFuse. Your company-approved AI can
 
 Add the FlowFuse address to connect, then decide which teams the agent reaches and whether it can make changes.
 
-The address is `https://app.flowfuse.com/mcp`. [Pick your agent on the AI page](/ai/) for the exact steps in [Microsoft Copilot](https://copilotstudio.microsoft.com/), [ChatGPT](https://chatgpt.com/), [Claude](https://claude.ai/settings/connectors) or [Gemini](https://gemini.google.com/). Any MCP client that supports the HTTP transport works too, including command-line and editor agents and local models. Sign-in uses OAuth where the client supports it, with a token fallback where it does not.
+Pick your agent, and follow the three steps:
+
+::agent-setup-tabs{:exclude-expert="true" surface="changelog"}
+::
+
+Any MCP client that supports the HTTP transport works, including command-line and editor agents and local models. Sign-in uses OAuth where the client supports it, with a token fallback where it does not.
 
 Your own agent gets the full, growing set of FlowFuse platform automation and flow-building tools to run. That matters most where company policy only permits an approved AI agent, so FlowFuse Expert wasn't an option.
 

From d6e113ac95edced546704bf47cebbaf9b65d8325 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 28 Aug 2026 16:08:33 +0200
Subject: [PATCH 8/9] ai: correct the ChatGPT route to developer mode

Settings, Apps and Connectors, Advanced settings, then add by URL. The earlier
wording sent people to a prompt dashboard and to a workspace administrator,
neither of which is where developer mode lives. Developer mode also needs a
paid plan.
---
 nuxt/components/content/AgentSetupTabs.vue | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/nuxt/components/content/AgentSetupTabs.vue b/nuxt/components/content/AgentSetupTabs.vue
index 057e128e16..65e6174938 100644
--- a/nuxt/components/content/AgentSetupTabs.vue
+++ b/nuxt/components/content/AgentSetupTabs.vue
@@ -71,8 +71,8 @@ const CLIENTS = [
         id: 'chatgpt',
         logo: '/images/ai/agents/chatgpt.svg',
         name: 'ChatGPT',
-        step2Title: 'Enable developer mode, then add a connector',
-        step2Body: 'Custom connectors sit behind developer mode, which a workspace administrator turns on. The connector itself is added from the prompt dashboard.',
+        step2Title: 'Settings, Apps and Connectors, Advanced settings',
+        step2Body: 'Turn on developer mode there, then add FlowFuse by URL. Developer mode needs a paid plan, so it is not on the free tier.',
         step2Label: 'Open ChatGPT',
         step2Url: 'https://chatgpt.com/',
     },

From de9094ad2a1e9a0001f3e5aebcb1d2d607a74e92 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 28 Aug 2026 16:42:00 +0200
Subject: [PATCH 9/9] ai: spell the ChatGPT menu label as it appears on screen

---
 nuxt/components/content/AgentSetupTabs.vue | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/nuxt/components/content/AgentSetupTabs.vue b/nuxt/components/content/AgentSetupTabs.vue
index 65e6174938..b11f4ed52f 100644
--- a/nuxt/components/content/AgentSetupTabs.vue
+++ b/nuxt/components/content/AgentSetupTabs.vue
@@ -71,7 +71,7 @@ const CLIENTS = [
         id: 'chatgpt',
         logo: '/images/ai/agents/chatgpt.svg',
         name: 'ChatGPT',
-        step2Title: 'Settings, Apps and Connectors, Advanced settings',
+        step2Title: 'Settings, Apps & Connectors, Advanced settings',
         step2Body: 'Turn on developer mode there, then add FlowFuse by URL. Developer mode needs a paid plan, so it is not on the free tier.',
         step2Label: 'Open ChatGPT',
         step2Url: 'https://chatgpt.com/',