From 532a413ab9fb2a97e2cfca5cae215a4d87d849d2 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Mon, 14 Sep 2026 20:13:38 +0200
Subject: [PATCH 01/31] nav: size the sidebar group headers as headers, and
 indent their items

The group name rendered at caption size, the same weight as the pages under
it, so the grouping had to be read rather than seen. It now takes body size
and the links sit indented from it.

Shared component, so this applies to the handbook and the guides too.
---
 nuxt/components/SidebarNav.vue | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/nuxt/components/SidebarNav.vue b/nuxt/components/SidebarNav.vue
index 4dd32dfe6c..26f5ee5bc9 100644
--- a/nuxt/components/SidebarNav.vue
+++ b/nuxt/components/SidebarNav.vue
@@ -68,3 +68,19 @@ watch(() => route.path, () => { open.value = false })
     </div>
   </div>
 </template>
+
+<style scoped>
+/* Group headers ("Get FlowFuse running") read as headers: body text size rather
+   than the caption size Nuxt UI defaults labels to. */
+:deep([data-slot="label"]) {
+    font-size: 0.875rem;
+    line-height: 1.5rem;
+}
+
+/* The pages under a header sit indented from it, so the grouping is visible
+   without reading the words. Applied to every link so the existing nesting
+   keeps its relative steps. */
+:deep([data-slot="link"]) {
+    padding-left: 1.125rem;
+}
+</style>

From 9b4db8c97e09abf4740ab3434a3e3293daf17db0 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Mon, 14 Sep 2026 20:16:58 +0200
Subject: [PATCH 02/31] docs nav: align the sidebar with the content column,
 indent items, drop the lone crumb

The sidebar started 1.5rem above the page body, so nothing lined up across
the top. Its items sit indented further from their group header.

A breadcrumb trail of one item names the page you are already on. It now
renders only when there is somewhere to go back to.
---
 nuxt/components/DocsLeftNav.vue | 8 +++++++-
 nuxt/components/SidebarNav.vue  | 2 +-
 nuxt/pages/docs/[...slug].vue   | 2 +-
 3 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/nuxt/components/DocsLeftNav.vue b/nuxt/components/DocsLeftNav.vue
index 111f65f44f..e1c697fcea 100644
--- a/nuxt/components/DocsLeftNav.vue
+++ b/nuxt/components/DocsLeftNav.vue
@@ -17,5 +17,11 @@ const items = computed((): NavigationMenuItem[] => [
 </script>
 
 <template>
-  <SidebarNav :items="items" label="Documentation" />
+  <!-- pt matches the content column's pt-8 so the first nav item lines up
+       with the top of the page body rather than sitting above it. Below lg the
+       wrapper gets out of the way (display: contents) so SidebarNav's own root is
+       the grid/flex item its sticky and order rules address. -->
+  <div class="pt-6 max-lg:contents">
+    <SidebarNav :items="items" label="Documentation" />
+  </div>
 </template>
diff --git a/nuxt/components/SidebarNav.vue b/nuxt/components/SidebarNav.vue
index 26f5ee5bc9..aa7621b46b 100644
--- a/nuxt/components/SidebarNav.vue
+++ b/nuxt/components/SidebarNav.vue
@@ -81,6 +81,6 @@ watch(() => route.path, () => { open.value = false })
    without reading the words. Applied to every link so the existing nesting
    keeps its relative steps. */
 :deep([data-slot="link"]) {
-    padding-left: 1.125rem;
+    padding-left: 1.75rem;
 }
 </style>
diff --git a/nuxt/pages/docs/[...slug].vue b/nuxt/pages/docs/[...slug].vue
index 635cbb20f7..5cc7956495 100644
--- a/nuxt/pages/docs/[...slug].vue
+++ b/nuxt/pages/docs/[...slug].vue
@@ -120,7 +120,7 @@ const surround = computed(() => {
           <!-- Breadcrumbs + Search bar -->
           <div class="font-medium pb-1 flex flex-col gap-1">
             <div class="md:flex-1">
-              <Breadcrumbs :items="breadcrumbItems" />
+              <Breadcrumbs v-if="breadcrumbItems.length > 1" :items="breadcrumbItems" />
             </div>
             <div class="w-full mb-1">
               <AlgoliaSearch index-filter="category:docs" placeholder="Search in Docs..." source-id="docs" />

From 5fd2eef2f005b1613b8b78f59939006a7ca7f57e Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 13:42:49 +0200
Subject: [PATCH 03/31] docs: bring the FlowFuse Expert question box to Nuxt
 pages

FfExpertAsk carries the markup of the old /ai/ page's chat interface and modal and
runs the same src/js/ai-expert-modal.js. The script now starts through a named init
that runs whether or not DOMContentLoaded has fired, can run again after client-side
navigation, and replaces its page-wide click listeners instead of stacking them.

Answers come from the Expert service for the hosted site; in a local preview the
request fails, as the script itself notes.
---
 nuxt/components/content/FfExpertAsk.vue | 137 ++++++++++++++++++++++++
 1 file changed, 137 insertions(+)
 create mode 100644 nuxt/components/content/FfExpertAsk.vue

diff --git a/nuxt/components/content/FfExpertAsk.vue b/nuxt/components/content/FfExpertAsk.vue
new file mode 100644
index 0000000000..97fb37f2ce
--- /dev/null
+++ b/nuxt/components/content/FfExpertAsk.vue
@@ -0,0 +1,137 @@
+<script setup lang="ts">
+// FlowFuse Expert, embedded: a question box that opens the Expert conversation in a modal.
+//
+// The conversation itself is src/js/ai-expert-modal.js, the same script the old /ai/ page
+// used (via src/_includes/components/ai-chat-interface.njk and ai-expert-modal.njk). This
+// component carries that markup for Nuxt pages. The element ids and the classes the script
+// selects on are load-bearing: keep them as they are.
+//
+// Usage from markdown:
+//   ::ff-expert-ask
+//   ::
+withDefaults(defineProps<{
+    placeholder?: string
+    button?: string
+    position?: string
+}>(), {
+    placeholder: 'Ask FlowFuse Expert anything about FlowFuse or Node-RED',
+    button: 'Ask',
+    position: 'docs-home',
+})
+
+function loadScript (src: string) {
+    return new Promise<void>((resolve, reject) => {
+        const el = document.createElement('script')
+        el.src = src
+        el.onload = () => resolve()
+        el.onerror = () => reject(new Error(`failed to load ${src}`))
+        document.body.appendChild(el)
+    })
+}
+
+onMounted(async () => {
+    const w = window as any
+    // The script sanitises every answer with DOMPurify before rendering it.
+    if (!w.DOMPurify) await loadScript('https://cdn.jsdelivr.net/npm/dompurify@3.3.0/dist/purify.min.js')
+    // First visit: loading the script runs it. A later client-side visit mounts fresh
+    // elements, so the already-loaded script is asked to bind to them.
+    if (w.ffExpertInit) w.ffExpertInit()
+    else await loadScript('/js/ai-expert-modal.js')
+})
+
+function track (position: string) {
+    const capture = (window as any).capture
+    if (typeof capture === 'function') capture('cta-ai-get-started', { position })
+}
+</script>
+
+<template>
+  <div class="ff-expert-ask not-prose">
+    <div class="ai-chat-container mt-6 max-w-4xl">
+      <div class="ai-chat-box">
+        <div class="textarea-wrapper relative mb-4 h-32 p-4 pb-12 rounded-lg overflow-hidden">
+          <textarea
+            data-ff-expert-input
+            :placeholder="placeholder"
+            class="w-full h-full bg-transparent border-0 focus:outline-none text-gray-600 placeholder-gray-400 resize-none"
+            aria-label="Ask FlowFuse Expert"
+          />
+          <div class="absolute bottom-3 left-4 text-[10px] font-light text-gray-500 pr-36 line-clamp-2">
+            AI uses FlowFuse's knowledge base
+          </div>
+          <button
+            id="tell-me-how-btn"
+            type="button"
+            class="absolute bottom-3 right-4 ff-btn ff-btn--highlight uppercase whitespace-nowrap px-6 py-3"
+            @click="track(position)"
+          >
+            {{ button }}
+          </button>
+        </div>
+      </div>
+
+      <div class="ai-prompts mt-4">
+        <div class="wrapper flex flex-wrap gap-2 mb-3" />
+      </div>
+    </div>
+
+    <div id="ai-expert-modal" class="fixed inset-0 bg-black/50 hidden items-center justify-center p-0 md:p-4 md:px-8 md:py-8 z-[9999]" role="dialog" aria-modal="true" aria-labelledby="ai-expert-modal-title">
+      <div class="bg-white rounded-none md:rounded-lg shadow-xl w-full max-w-4xl h-full md:h-full flex flex-col relative">
+        <div class="ai-chat-box">
+          <div class="textarea-wrapper modal-header flex items-center justify-between px-4 py-3 rounded-t-none md:rounded-t-lg h-auto rounded-b-none mb-0">
+            <div class="flex items-center gap-1">
+              <div class="w-24 h-6">
+                <FlowFuseWordmark uid="expert-modal" />
+              </div>
+              <h2 id="ai-expert-modal-title" class="text-base font-semibold text-gray-700 -mb-1">Expert</h2>
+            </div>
+            <button id="close-modal" type="button" class="text-gray-500 hover:text-gray-600" aria-label="Close dialog">
+              <svg width="24" height="24" viewBox="0 0 24 24" fill="none">
+                <path d="M18 6L6 18" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+                <path d="M6 6l12 12" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+              </svg>
+            </button>
+          </div>
+        </div>
+
+        <div class="flex-1 p-4 overflow-y-auto">
+          <div class="bg-indigo-100 rounded-lg mb-6 py-3 px-4">
+            <p class="text-indigo-700 text-sm m-0">
+              AI agent has access to all of FlowFuse's
+              <a href="/docs" class="underline">documentation and knowledge</a>,
+              <a href="/blog" class="underline">blogposts</a>, and more.
+            </p>
+          </div>
+          <div id="chat-messages" class="space-y-4 overflow-auto" />
+        </div>
+
+        <div class="p-4 bg-white rounded-b-none md:rounded-b-lg border-t border-gray-200">
+          <div id="action-buttons-container" class="pb-4 flex justify-between">
+            <button id="clear-conversation" type="button" class="bg-white border border-indigo-300 rounded-full text-sm py-2 px-3 disabled:opacity-50 disabled:cursor-not-allowed" disabled>
+              Start over
+            </button>
+            <div id="right-buttons" class="flex gap-2">
+              <button id="continue-to-app" type="button" class="textarea-wrapper bg-white rounded-full text-sm py-2 px-3 disabled:opacity-50 disabled:cursor-not-allowed transition-colors hidden inline-flex items-center gap-1">
+                Continue chat in <img :src="'/images/ff-minimal-red.svg'" alt="FlowFuse" class="w-5 h-5 inline-block">
+              </button>
+              <button id="stop-generation" type="button" class="bg-white border border-indigo-300 rounded-full text-sm flex items-center gap-2 py-2 px-3 hidden">
+                <div class="w-3 h-3 bg-gray-800 rounded-sm" />
+                Stop
+              </button>
+              <button id="send-message" type="button" class="bg-indigo-600 text-white border border-indigo-600 rounded-full text-sm py-2 px-3 disabled:opacity-50 disabled:cursor-not-allowed hover:bg-indigo-700 transition-colors" disabled>
+                Send
+              </button>
+            </div>
+          </div>
+          <div class="relative">
+            <textarea
+              id="modal-input"
+              placeholder="Give more details in regards to your intended workflow to tailor it to your use case"
+              class="w-full p-4 border-2 border-gray-300 rounded-lg resize-none focus:outline-none focus:border-indigo-500 text-gray-900 h-24 text-sm disabled:cursor-not-allowed disabled:bg-gray-50 disabled:text-gray-500"
+            />
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+</template>

From 61588ab59ab0c4376fbc982db6aafadfd6da7a65 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 14:16:27 +0200
Subject: [PATCH 04/31] docs: FlowFuse Expert on every docs page, and support
 prompts on the home box

The Expert conversation modal now lives once in the layout for all docs pages. The
home page box carries the FlowFuse Expert branding above the text box, an Ask Docs
button and support questions instead of workflow ideas. Elsewhere, and on the home
page once that box scrolls away, an Ask FlowFuse Expert button at the top of the
right-hand column opens the same conversation.

ai-expert-modal.js: the entry button is handled by delegation so a box mounted after
start-up works, the morph from the box only runs when the box opened the modal, a page
can set the greeting, and window.ffExpertOpen() opens it from any button.
---
 nuxt/components/DocsExpertButton.vue    | 138 ++++++++++++++++++
 nuxt/components/DocsExpertHost.vue      |  76 ++++++++++
 nuxt/components/content/FfExpertAsk.vue | 177 +++++++++++-------------
 nuxt/composables/useDocsExpert.ts       |  47 +++++++
 nuxt/layouts/default.vue                |   7 +
 nuxt/pages/docs/[...slug].vue           |  11 +-
 6 files changed, 359 insertions(+), 97 deletions(-)
 create mode 100644 nuxt/components/DocsExpertButton.vue
 create mode 100644 nuxt/components/DocsExpertHost.vue
 create mode 100644 nuxt/composables/useDocsExpert.ts

diff --git a/nuxt/components/DocsExpertButton.vue b/nuxt/components/DocsExpertButton.vue
new file mode 100644
index 0000000000..06145ce909
--- /dev/null
+++ b/nuxt/components/DocsExpertButton.vue
@@ -0,0 +1,138 @@
+<script setup lang="ts">
+// Opens the FlowFuse Expert conversation from anywhere on a docs page.
+//
+// `toc` is the branded call to action in the right-hand column. `compact` matches the
+// Expert button in the FlowFuse app header (the FlowFuse mark and "Expert" inside a
+// slowly turning gradient border), for the site header on narrow screens.
+const props = withDefaults(defineProps<{
+    variant?: 'toc' | 'compact'
+    position?: string
+    /** Compact only: the FlowFuse mark alone, for a header that is short of room. */
+    iconOnly?: boolean
+}>(), {
+    variant: 'toc',
+    position: 'docs-toc',
+    iconOnly: false,
+})
+
+function open () {
+    const capture = (window as any).capture
+    if (typeof capture === 'function') capture('cta-ai-get-started', { position: props.position })
+    openDocsExpert()
+}
+</script>
+
+<template>
+  <button
+    type="button"
+    class="ff-expert-btn"
+    :class="[`ff-expert-btn--${variant}`, { 'ff-expert-btn--icon': iconOnly }]"
+    :aria-label="variant === 'compact' ? 'Ask FlowFuse Expert' : undefined"
+    @click="open"
+  >
+    <template v-if="variant === 'toc'">
+      <span>Ask</span>
+      <span class="ff-expert-btn__wordmark" aria-label="FlowFuse" role="img">
+        <FlowFuseWordmark uid="expert-toc" />
+      </span>
+      <span>Expert</span>
+    </template>
+    <template v-else>
+      <img :src="'/images/ff-minimal-red.svg'" alt="" class="ff-expert-btn__mark">
+      <span class="ff-expert-btn__label">Expert</span>
+    </template>
+  </button>
+</template>
+
+<style scoped>
+@property --ff-expert-border-angle {
+    syntax: '<angle>';
+    inherits: false;
+    initial-value: 135deg;
+}
+
+.ff-expert-btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.375rem;
+    font-weight: 700;
+    color: #1f2937;
+    white-space: nowrap;
+    cursor: pointer;
+    border: 1px solid transparent;
+    border-radius: 6px;
+    background:
+        linear-gradient(#fff, #fff) padding-box,
+        conic-gradient(from var(--ff-expert-border-angle), #BC3838, #9333EA, #4F46E5, #9333EA, #BC3838) border-box;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+    .ff-expert-btn {
+        animation: ff-expert-swirl 9s linear infinite;
+    }
+}
+
+.ff-expert-btn:hover {
+    background:
+        linear-gradient(#f5f5ff, #f5f5ff) padding-box,
+        conic-gradient(from var(--ff-expert-border-angle), #BC3838, #9333EA, #4F46E5, #9333EA, #BC3838) border-box;
+}
+
+.ff-expert-btn:focus-visible {
+    outline: 2px solid #4F46E5;
+    outline-offset: 2px;
+}
+
+.ff-expert-btn--compact {
+    padding: 6px 9px;
+    font-size: 0.85rem;
+    line-height: 20px;
+}
+
+.ff-expert-btn__mark {
+    width: 1.25rem;
+    height: 1.25rem;
+    margin-left: -0.25rem;
+    flex-shrink: 0;
+}
+
+/* On a phone the header also carries search, Book a demo and the menu, so the pill shows
+   the FlowFuse mark only. */
+@media (max-width: 599px) {
+    .ff-expert-btn--compact .ff-expert-btn__label {
+        display: none;
+    }
+
+    .ff-expert-btn--compact .ff-expert-btn__mark {
+        margin-left: 0;
+    }
+}
+
+.ff-expert-btn--icon .ff-expert-btn__label {
+    display: none;
+}
+
+.ff-expert-btn--icon .ff-expert-btn__mark {
+    margin-left: 0;
+}
+
+.ff-expert-btn--toc {
+    width: 100%;
+    justify-content: center;
+    padding: 0.625rem 0.75rem;
+    font-size: 0.95rem;
+    line-height: 1.25rem;
+}
+
+.ff-expert-btn__wordmark {
+    display: inline-block;
+    width: 5.5rem;
+    height: 1rem;
+    line-height: 0;
+}
+
+@keyframes ff-expert-swirl {
+    from { --ff-expert-border-angle: 135deg; }
+    to { --ff-expert-border-angle: 495deg; }
+}
+</style>
diff --git a/nuxt/components/DocsExpertHost.vue b/nuxt/components/DocsExpertHost.vue
new file mode 100644
index 0000000000..057d3bb96d
--- /dev/null
+++ b/nuxt/components/DocsExpertHost.vue
@@ -0,0 +1,76 @@
+<script setup lang="ts">
+// The FlowFuse Expert conversation modal, rendered once for every docs page by the layout.
+// src/js/ai-expert-modal.js drives it (see nuxt/composables/useDocsExpert.ts). The element ids
+// and the classes that script selects on are load-bearing: keep them as they are.
+onMounted(() => {
+    mountDocsExpert().catch(() => {})
+})
+</script>
+
+<template>
+  <div
+    id="ai-expert-modal"
+    class="fixed inset-0 bg-black/50 hidden items-center justify-center p-0 md:p-4 md:px-8 md:py-8 z-[9999]"
+    role="dialog"
+    aria-modal="true"
+    aria-labelledby="ai-expert-modal-title"
+    data-welcome="Hello! Ask me anything about FlowFuse or Node-RED, and I will answer from the documentation."
+  >
+    <div class="bg-white rounded-none md:rounded-lg shadow-xl w-full max-w-4xl h-full md:h-full flex flex-col relative">
+      <div class="ai-chat-box">
+        <div class="textarea-wrapper modal-header flex items-center justify-between px-4 py-3 rounded-t-none md:rounded-t-lg h-auto rounded-b-none mb-0">
+          <div class="flex items-center gap-1">
+            <div class="w-24 h-6">
+              <FlowFuseWordmark uid="expert-modal" />
+            </div>
+            <h2 id="ai-expert-modal-title" class="text-base font-semibold text-gray-700 -mb-1">Expert</h2>
+          </div>
+          <button id="close-modal" type="button" class="text-gray-500 hover:text-gray-600" aria-label="Close dialog">
+            <svg width="24" height="24" viewBox="0 0 24 24" fill="none">
+              <path d="M18 6L6 18" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+              <path d="M6 6l12 12" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+            </svg>
+          </button>
+        </div>
+      </div>
+
+      <div class="flex-1 p-4 overflow-y-auto">
+        <div class="bg-indigo-100 rounded-lg mb-6 py-3 px-4">
+          <p class="text-indigo-700 text-sm m-0">
+            AI agent has access to all of FlowFuse's
+            <a href="/docs" class="underline">documentation and knowledge</a>,
+            <a href="/blog" class="underline">blogposts</a>, and more.
+          </p>
+        </div>
+        <div id="chat-messages" class="space-y-4 overflow-auto" />
+      </div>
+
+      <div class="p-4 bg-white rounded-b-none md:rounded-b-lg border-t border-gray-200">
+        <div id="action-buttons-container" class="pb-4 flex justify-between">
+          <button id="clear-conversation" type="button" class="bg-white border border-indigo-300 rounded-full text-sm py-2 px-3 disabled:opacity-50 disabled:cursor-not-allowed" disabled>
+            Start over
+          </button>
+          <div id="right-buttons" class="flex gap-2">
+            <button id="continue-to-app" type="button" class="textarea-wrapper bg-white rounded-full text-sm py-2 px-3 disabled:opacity-50 disabled:cursor-not-allowed transition-colors hidden inline-flex items-center gap-1">
+              Continue chat in <img :src="'/images/ff-minimal-red.svg'" alt="FlowFuse" class="w-5 h-5 inline-block">
+            </button>
+            <button id="stop-generation" type="button" class="bg-white border border-indigo-300 rounded-full text-sm flex items-center gap-2 py-2 px-3 hidden">
+              <div class="w-3 h-3 bg-gray-800 rounded-sm" />
+              Stop
+            </button>
+            <button id="send-message" type="button" class="bg-indigo-600 text-white border border-indigo-600 rounded-full text-sm py-2 px-3 disabled:opacity-50 disabled:cursor-not-allowed hover:bg-indigo-700 transition-colors" disabled>
+              Send
+            </button>
+          </div>
+        </div>
+        <div class="relative">
+          <textarea
+            id="modal-input"
+            placeholder="Ask a question, or give more detail about what you are trying to do"
+            class="w-full p-4 border-2 border-gray-300 rounded-lg resize-none focus:outline-none focus:border-indigo-500 text-gray-900 h-24 text-sm disabled:cursor-not-allowed disabled:bg-gray-50 disabled:text-gray-500"
+          />
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/nuxt/components/content/FfExpertAsk.vue b/nuxt/components/content/FfExpertAsk.vue
index 97fb37f2ce..1f7d65ce09 100644
--- a/nuxt/components/content/FfExpertAsk.vue
+++ b/nuxt/components/content/FfExpertAsk.vue
@@ -1,55 +1,68 @@
 <script setup lang="ts">
-// FlowFuse Expert, embedded: a question box that opens the Expert conversation in a modal.
+// FlowFuse Expert, embedded in a page: a question box that opens the Expert conversation.
 //
-// The conversation itself is src/js/ai-expert-modal.js, the same script the old /ai/ page
-// used (via src/_includes/components/ai-chat-interface.njk and ai-expert-modal.njk). This
-// component carries that markup for Nuxt pages. The element ids and the classes the script
-// selects on are load-bearing: keep them as they are.
+// The conversation itself is src/js/ai-expert-modal.js, the script the old /ai/ page used,
+// driving the modal that DocsExpertHost renders in the layout. The script listens for the
+// #tell-me-how-btn button and for .prompt-pill clicks, and morphs this card (the
+// .textarea-wrapper holding the data-ff-expert-input textarea) into the modal. Keep those
+// hooks as they are.
 //
 // Usage from markdown:
 //   ::ff-expert-ask
 //   ::
-withDefaults(defineProps<{
+const props = withDefaults(defineProps<{
     placeholder?: string
     button?: string
     position?: string
 }>(), {
-    placeholder: 'Ask FlowFuse Expert anything about FlowFuse or Node-RED',
-    button: 'Ask',
+    placeholder: 'Ask a question about FlowFuse or Node-RED',
+    button: 'Ask Docs',
     position: 'docs-home',
 })
 
-function loadScript (src: string) {
-    return new Promise<void>((resolve, reject) => {
-        const el = document.createElement('script')
-        el.src = src
-        el.onload = () => resolve()
-        el.onerror = () => reject(new Error(`failed to load ${src}`))
-        document.body.appendChild(el)
+// Support questions, the kind a reader brings to the documentation.
+const prompts = [
+    { title: 'My instance will not start', prompt: 'My FlowFuse instance will not start, or keeps crashing. How do I find out why, and how do I recover it?' },
+    { title: 'Connect a remote instance', prompt: 'How do I install the FlowFuse Device Agent and connect a remote instance to my team?' },
+    { title: 'Remote instance shows offline', prompt: 'My Device Agent is installed, but the remote instance shows as offline in FlowFuse. How do I troubleshoot it?' },
+    { title: 'Move flows to production', prompt: 'How do I promote flows from a development instance to production with snapshots and a DevOps pipeline?' },
+    { title: 'Roll back to a snapshot', prompt: 'How do I roll an instance back to an earlier snapshot?' },
+    { title: 'Set environment variables', prompt: 'How do I set environment variables on an instance, and how do my flows read them?' },
+]
+
+const root = ref<HTMLElement>()
+const inlineVisible = useExpertInlineVisible()
+let observer: IntersectionObserver | undefined
+
+onMounted(() => {
+    observer = new IntersectionObserver(([entry]) => {
+        inlineVisible.value = entry.isIntersecting
     })
-}
+    if (root.value) observer.observe(root.value)
+})
 
-onMounted(async () => {
-    const w = window as any
-    // The script sanitises every answer with DOMPurify before rendering it.
-    if (!w.DOMPurify) await loadScript('https://cdn.jsdelivr.net/npm/dompurify@3.3.0/dist/purify.min.js')
-    // First visit: loading the script runs it. A later client-side visit mounts fresh
-    // elements, so the already-loaded script is asked to bind to them.
-    if (w.ffExpertInit) w.ffExpertInit()
-    else await loadScript('/js/ai-expert-modal.js')
+onBeforeUnmount(() => {
+    observer?.disconnect()
+    inlineVisible.value = false
 })
 
-function track (position: string) {
+function track () {
     const capture = (window as any).capture
-    if (typeof capture === 'function') capture('cta-ai-get-started', { position })
+    if (typeof capture === 'function') capture('cta-ai-get-started', { position: props.position })
 }
 </script>
 
 <template>
-  <div class="ff-expert-ask not-prose">
-    <div class="ai-chat-container mt-6 max-w-4xl">
-      <div class="ai-chat-box">
-        <div class="textarea-wrapper relative mb-4 h-32 p-4 pb-12 rounded-lg overflow-hidden">
+  <div ref="root" class="ff-expert-ask not-prose mt-6 max-w-4xl">
+    <div class="ai-chat-box">
+      <div class="textarea-wrapper ff-expert-ask__card relative mb-4 rounded-lg overflow-hidden">
+        <div class="ff-expert-ask__brand">
+          <span class="ff-expert-ask__wordmark" role="img" aria-label="FlowFuse">
+            <FlowFuseWordmark uid="expert-ask" />
+          </span>
+          <span class="ff-expert-ask__product">Expert</span>
+        </div>
+        <div class="relative h-32 p-4 pb-12">
           <textarea
             data-ff-expert-input
             :placeholder="placeholder"
@@ -62,76 +75,54 @@ function track (position: string) {
           <button
             id="tell-me-how-btn"
             type="button"
-            class="absolute bottom-3 right-4 ff-btn ff-btn--highlight uppercase whitespace-nowrap px-6 py-3"
-            @click="track(position)"
+            class="absolute bottom-3 right-4 ff-btn ff-btn--highlight whitespace-nowrap px-6 py-3"
+            @click="track"
           >
             {{ button }}
           </button>
         </div>
       </div>
-
-      <div class="ai-prompts mt-4">
-        <div class="wrapper flex flex-wrap gap-2 mb-3" />
-      </div>
     </div>
 
-    <div id="ai-expert-modal" class="fixed inset-0 bg-black/50 hidden items-center justify-center p-0 md:p-4 md:px-8 md:py-8 z-[9999]" role="dialog" aria-modal="true" aria-labelledby="ai-expert-modal-title">
-      <div class="bg-white rounded-none md:rounded-lg shadow-xl w-full max-w-4xl h-full md:h-full flex flex-col relative">
-        <div class="ai-chat-box">
-          <div class="textarea-wrapper modal-header flex items-center justify-between px-4 py-3 rounded-t-none md:rounded-t-lg h-auto rounded-b-none mb-0">
-            <div class="flex items-center gap-1">
-              <div class="w-24 h-6">
-                <FlowFuseWordmark uid="expert-modal" />
-              </div>
-              <h2 id="ai-expert-modal-title" class="text-base font-semibold text-gray-700 -mb-1">Expert</h2>
-            </div>
-            <button id="close-modal" type="button" class="text-gray-500 hover:text-gray-600" aria-label="Close dialog">
-              <svg width="24" height="24" viewBox="0 0 24 24" fill="none">
-                <path d="M18 6L6 18" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
-                <path d="M6 6l12 12" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
-              </svg>
-            </button>
-          </div>
-        </div>
-
-        <div class="flex-1 p-4 overflow-y-auto">
-          <div class="bg-indigo-100 rounded-lg mb-6 py-3 px-4">
-            <p class="text-indigo-700 text-sm m-0">
-              AI agent has access to all of FlowFuse's
-              <a href="/docs" class="underline">documentation and knowledge</a>,
-              <a href="/blog" class="underline">blogposts</a>, and more.
-            </p>
-          </div>
-          <div id="chat-messages" class="space-y-4 overflow-auto" />
-        </div>
-
-        <div class="p-4 bg-white rounded-b-none md:rounded-b-lg border-t border-gray-200">
-          <div id="action-buttons-container" class="pb-4 flex justify-between">
-            <button id="clear-conversation" type="button" class="bg-white border border-indigo-300 rounded-full text-sm py-2 px-3 disabled:opacity-50 disabled:cursor-not-allowed" disabled>
-              Start over
-            </button>
-            <div id="right-buttons" class="flex gap-2">
-              <button id="continue-to-app" type="button" class="textarea-wrapper bg-white rounded-full text-sm py-2 px-3 disabled:opacity-50 disabled:cursor-not-allowed transition-colors hidden inline-flex items-center gap-1">
-                Continue chat in <img :src="'/images/ff-minimal-red.svg'" alt="FlowFuse" class="w-5 h-5 inline-block">
-              </button>
-              <button id="stop-generation" type="button" class="bg-white border border-indigo-300 rounded-full text-sm flex items-center gap-2 py-2 px-3 hidden">
-                <div class="w-3 h-3 bg-gray-800 rounded-sm" />
-                Stop
-              </button>
-              <button id="send-message" type="button" class="bg-indigo-600 text-white border border-indigo-600 rounded-full text-sm py-2 px-3 disabled:opacity-50 disabled:cursor-not-allowed hover:bg-indigo-700 transition-colors" disabled>
-                Send
-              </button>
-            </div>
-          </div>
-          <div class="relative">
-            <textarea
-              id="modal-input"
-              placeholder="Give more details in regards to your intended workflow to tailor it to your use case"
-              class="w-full p-4 border-2 border-gray-300 rounded-lg resize-none focus:outline-none focus:border-indigo-500 text-gray-900 h-24 text-sm disabled:cursor-not-allowed disabled:bg-gray-50 disabled:text-gray-500"
-            />
-          </div>
-        </div>
-      </div>
+    <div class="flex flex-wrap gap-2 mb-3">
+      <button
+        v-for="p in prompts"
+        :key="p.title"
+        type="button"
+        class="prompt-pill text-left px-4 py-2 bg-white rounded-full text-sm text-gray-500 hover:shadow-sm transition-all border hover:border-indigo-600 border-indigo-200 whitespace-nowrap overflow-hidden text-ellipsis max-w-full"
+        :data-prompt="p.prompt"
+        :title="p.prompt"
+      >
+        {{ p.title }}
+      </button>
     </div>
   </div>
 </template>
+
+<style scoped>
+.ff-expert-ask__brand {
+    display: flex;
+    align-items: center;
+    gap: 0.375rem;
+    padding: 0.75rem 1rem;
+    border-bottom: 1px solid transparent;
+    background:
+        linear-gradient(#fff, #fff) padding-box,
+        linear-gradient(90deg, #f87171, #f472b6, #a78bfa) border-box;
+}
+
+.ff-expert-ask__wordmark {
+    display: inline-block;
+    width: 7rem;
+    height: 1.25rem;
+    line-height: 0;
+}
+
+.ff-expert-ask__product {
+    font-size: 1.125rem;
+    line-height: 1;
+    font-weight: 600;
+    color: #374151;
+    margin-top: 0.125rem;
+}
+</style>
diff --git a/nuxt/composables/useDocsExpert.ts b/nuxt/composables/useDocsExpert.ts
new file mode 100644
index 0000000000..38e063af64
--- /dev/null
+++ b/nuxt/composables/useDocsExpert.ts
@@ -0,0 +1,47 @@
+// FlowFuse Expert on the docs pages.
+//
+// The conversation is src/js/ai-expert-modal.js, shared with the Eleventy site. It binds to
+// the modal that DocsExpertHost renders once in the layout, and exposes window.ffExpertOpen
+// so any button on the page can open it. The embedded question box (FfExpertAsk) needs no
+// call from here: the script listens for its button and prompt pills itself.
+
+const DOMPURIFY = 'https://cdn.jsdelivr.net/npm/dompurify@3.3.0/dist/purify.min.js'
+const SCRIPT = '/js/ai-expert-modal.js'
+
+let ready: Promise<void> | null = null
+
+function loadScript (src: string) {
+    return new Promise<void>((resolve, reject) => {
+        const el = document.createElement('script')
+        el.src = src
+        el.onload = () => resolve()
+        el.onerror = () => reject(new Error(`failed to load ${src}`))
+        document.body.appendChild(el)
+    })
+}
+
+/** Called by DocsExpertHost once its modal is in the DOM. */
+export function mountDocsExpert (): Promise<void> {
+    ready = (async () => {
+        const w = window as any
+        // The script sanitises every answer with DOMPurify before rendering it.
+        if (!w.DOMPurify) await loadScript(DOMPURIFY)
+        // Loading the script runs it. If it is already loaded (the host mounted again after
+        // leaving the docs and coming back), ask it to bind to the new modal instead.
+        if (w.ffExpertInit) w.ffExpertInit()
+        else await loadScript(SCRIPT)
+    })()
+    return ready
+}
+
+/** Open the Expert conversation, optionally starting it with a question. */
+export function openDocsExpert (text = '') {
+    const open = () => (window as any).ffExpertOpen?.(text)
+    if (ready) ready.then(open).catch(() => {})
+    else open()
+}
+
+/** Whether the embedded question box is on screen, so other entry points can step aside. */
+export function useExpertInlineVisible () {
+    return useState<boolean>('ff-expert-inline-visible', () => false)
+}
diff --git a/nuxt/layouts/default.vue b/nuxt/layouts/default.vue
index 0a2dd11857..4998dee667 100644
--- a/nuxt/layouts/default.vue
+++ b/nuxt/layouts/default.vue
@@ -1,3 +1,8 @@
+<script setup lang="ts">
+const route = useRoute()
+const isDocs = computed(() => route.path === '/docs' || route.path.startsWith('/docs/'))
+</script>
+
 <template>
   <div class="font-sans ff-website leading-normal tracking-normal gradient text-gray-500 min-h-screen flex flex-col">
     <a href="#main-content" class="skip-to-main">Skip to main content</a>
@@ -14,5 +19,7 @@
       </div>
     </div>
     <AppFooter />
+    <!-- FlowFuse Expert's conversation, opened from the docs pages' question box, sidebar and header. -->
+    <DocsExpertHost v-if="isDocs" />
   </div>
 </template>
diff --git a/nuxt/pages/docs/[...slug].vue b/nuxt/pages/docs/[...slug].vue
index 5cc7956495..9e286d4e24 100644
--- a/nuxt/pages/docs/[...slug].vue
+++ b/nuxt/pages/docs/[...slug].vue
@@ -81,6 +81,8 @@ defineOgImage('Default', seo.value.ogImage)
 // Same key+handler DocsLeftNav uses, so useAsyncData dedupes into one fetch per request.
 const { data: navGroups } = await useDocsNavTree()
 
+const expertInlineVisible = useExpertInlineVisible()
+
 const breadcrumbItems = computed(() => {
     const crumbs = findDocsBreadcrumb(navGroups.value ?? [], route.path)
     const withRoot = [{ title: 'Docs', path: '/docs' }, ...crumbs]
@@ -117,14 +119,11 @@ const surround = computed(() => {
       <!-- Main content area -->
       <div class="px-10 pt-8">
         <div class="w-full">
-          <!-- Breadcrumbs + Search bar -->
+          <!-- Breadcrumbs -->
           <div class="font-medium pb-1 flex flex-col gap-1">
             <div class="md:flex-1">
               <Breadcrumbs v-if="breadcrumbItems.length > 1" :items="breadcrumbItems" />
             </div>
-            <div class="w-full mb-1">
-              <AlgoliaSearch index-filter="category:docs" placeholder="Search in Docs..." source-id="docs" />
-            </div>
           </div>
         </div>
 
@@ -143,6 +142,10 @@ const surround = computed(() => {
       <!-- Right sidebar: TOC -->
       <div class="lg right-nav">
         <div class="sticky top-20 w-full mt-4 md:mt-6 px-8">
+          <!-- Hidden while the page's own Expert question box is on screen. -->
+          <div v-if="!expertInlineVisible" class="max-lg:hidden mb-6">
+            <DocsExpertButton variant="toc" position="docs-toc" />
+          </div>
           <HandbookToc :links="page?.body?.toc?.links" />
           <div v-if="page?.updated" class="text-xs pb-1 text-right mt-4 text-gray-500 max-lg:hidden">
             Updated: <RelativeTime :value="page.updated" />

From 5fefab4b06541670eb3cbef92be1d21dd15c14a9 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 14:16:27 +0200
Subject: [PATCH 05/31] docs search: a dialog opened from the sidebar or with
 Cmd+K

The docs search moves from above the article to the top of the sidebar, where the
Documentation link was, and opens its results in a centred dialog (full screen on a
phone). Cmd+K or Ctrl+K opens it from anywhere on a docs page. AlgoliaSearch gains
opt-in detached and shortcut props, so the blog, changelog, handbook and support
searches are unchanged, and results without an image no longer show a broken one.
---
 nuxt/components/AlgoliaSearch.vue | 90 +++++++++++++++++++++++++++++--
 nuxt/components/DocsLeftNav.vue   |  8 ++-
 2 files changed, 94 insertions(+), 4 deletions(-)

diff --git a/nuxt/components/AlgoliaSearch.vue b/nuxt/components/AlgoliaSearch.vue
index 7cfab36266..d6d34df988 100644
--- a/nuxt/components/AlgoliaSearch.vue
+++ b/nuxt/components/AlgoliaSearch.vue
@@ -7,9 +7,33 @@ const props = withDefaults(defineProps<{
     indexFilter?: string
     placeholder?: string
     sourceId?: string
+    /** Render a search button that opens the results in a dialog, at every screen width. */
+    detached?: boolean
+    /** Open it with Cmd+K / Ctrl+K and from a `ff-docs-search:open` window event. Needs `detached`. */
+    shortcut?: boolean
 }>(), {
     placeholder: 'Search...',
     sourceId: 'content',
+    detached: false,
+    shortcut: false,
+})
+
+const isMac = ref(true)
+
+function openDialog () {
+    searchContainer.value?.querySelector<HTMLElement>('.aa-DetachedSearchButton')?.click()
+}
+
+function onKeydown (e: KeyboardEvent) {
+    if ((e.metaKey || e.ctrlKey) && !e.altKey && !e.shiftKey && e.key.toLowerCase() === 'k') {
+        e.preventDefault()
+        openDialog()
+    }
+}
+
+onBeforeUnmount(() => {
+    window.removeEventListener('keydown', onKeydown)
+    window.removeEventListener('ff-docs-search:open', openDialog)
 })
 
 const searchContainer = ref<HTMLElement>()
@@ -56,6 +80,10 @@ onMounted(async () => {
     autocomplete({
         container: searchContainer.value!,
         placeholder: props.placeholder,
+        // An empty media query matches every width, so the input is always a button that
+        // opens the dialog: centred on wide screens, full screen on narrow ones (the theme's
+        // --aa-detached-modal-media-query decides which).
+        ...(props.detached ? { detachedMediaQuery: '' } : {}),
         getSources ({ query }: { query: string }) {
             if (query !== prevQuery) {
                 prevQuery = query
@@ -81,9 +109,9 @@ onMounted(async () => {
                         return html`
                             <a href="#" data-href="${item.url}" class="aa-ItemWrapper">
                                 <div class="aa-ItemContent">
-                                    <div class="aa-ItemIcon aa-ItemIcon--alignTop">
+                                    ${item.image ? html`<div class="aa-ItemIcon aa-ItemIcon--alignTop">
                                         <img src="#" data-src="${item.image}" alt="${item.name}" width="40" height="40" />
-                                    </div>
+                                    </div>` : ''}
                                     <div class="aa-ItemContentBody">
                                         <div class="aa-ItemContentTitle">
                                             ${components.Highlight({ hit: item, attribute: ['hierarchy', 'lvl0'] })}
@@ -125,9 +153,65 @@ onMounted(async () => {
             }
         }
     })
+
+    if (props.detached && props.shortcut) {
+        isMac.value = /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent)
+        window.addEventListener('keydown', onKeydown)
+        window.addEventListener('ff-docs-search:open', openDialog)
+    }
 })
 </script>
 
 <template>
-  <div ref="searchContainer" id="algolia-search" class="border border-gray-200 rounded"></div>
+  <div class="ff-algolia" :class="{ 'ff-algolia--detached': detached }">
+    <div ref="searchContainer" id="algolia-search" :class="detached ? '' : 'border border-gray-200 rounded'"></div>
+    <kbd v-if="detached && shortcut" class="ff-algolia__kbd" aria-hidden="true">{{ isMac ? '⌘' : 'Ctrl' }} K</kbd>
+  </div>
 </template>
+
+<style scoped>
+.ff-algolia--detached {
+    position: relative;
+}
+
+/* The search button reads as a search field, with the shortcut shown at its right edge. */
+.ff-algolia--detached :deep(.aa-DetachedSearchButton) {
+    width: 100%;
+    height: 2.5rem;
+    padding-right: 4rem;
+    border: 1px solid #d1d5db;
+    border-radius: 6px;
+    background: #fff;
+    font-size: 0.875rem;
+    color: #6b7280;
+    cursor: pointer;
+}
+
+.ff-algolia--detached :deep(.aa-DetachedSearchButton:hover) {
+    border-color: #a5b4fc;
+}
+
+.ff-algolia__kbd {
+    position: absolute;
+    top: 50%;
+    right: 0.625rem;
+    transform: translateY(-50%);
+    pointer-events: none;
+    font-family: inherit;
+    font-size: 0.7rem;
+    line-height: 1;
+    color: #6b7280;
+    padding: 0.25rem 0.375rem;
+    border: 1px solid #e5e7eb;
+    border-radius: 4px;
+    background: #f9fafb;
+}
+</style>
+
+<style>
+/* The dialog is appended to <body>, outside this component, so this is not scoped. It only
+   exists for a detached search, which only the docs use. */
+.aa-DetachedContainer--modal {
+    top: 12vh;
+}
+</style>
diff --git a/nuxt/components/DocsLeftNav.vue b/nuxt/components/DocsLeftNav.vue
index e1c697fcea..30a787d02e 100644
--- a/nuxt/components/DocsLeftNav.vue
+++ b/nuxt/components/DocsLeftNav.vue
@@ -7,8 +7,9 @@ const route = useRoute()
 
 const { data: navGroups } = await useDocsNavTree()
 
+// No "Documentation" entry on top: the search button sits there, and the breadcrumb and
+// the site header both lead back to /docs.
 const items = computed((): NavigationMenuItem[] => [
-    { label: 'Documentation', to: '/docs/' },
     ...(navGroups.value ?? []).flatMap(group => [
         { type: 'label', label: group.name } satisfies NavigationMenuItem,
         ...buildNavigationMenuItems(group.children, route.path),
@@ -22,6 +23,11 @@ const items = computed((): NavigationMenuItem[] => [
        wrapper gets out of the way (display: contents) so SidebarNav's own root is
        the grid/flex item its sticky and order rules address. -->
   <div class="pt-6 max-lg:contents">
+    <!-- Below lg the header carries a search button instead. This stays mounted there, hidden,
+         because that button opens this component's dialog. -->
+    <div class="max-lg:hidden mb-4 pr-2">
+      <AlgoliaSearch index-filter="category:docs" placeholder="Search in Docs..." source-id="docs" detached shortcut />
+    </div>
     <SidebarNav :items="items" label="Documentation" />
   </div>
 </template>

From 7de5b73a7f7dd5a02c5360ea9e4bdabc3798cb76 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 14:16:28 +0200
Subject: [PATCH 06/31] header: docs search and Expert beside the menu on
 phones and tablets

Below lg the docs sidebar and right-hand column are folded away, so docs pages get a
search button and the FlowFuse Expert button in the header, styled like the Expert
button in the FlowFuse app. To keep Book a demo on one line, the Expert button shows
the FlowFuse mark alone below 600px and on tablets, and the square logo holds until
520px on docs pages. Measured from 360 to 1000px: no overflow beyond what the header
already allows.
---
 nuxt/components/AppHeader.vue         | 28 ++++++++++++--
 nuxt/components/DocsHeaderActions.vue | 53 +++++++++++++++++++++++++++
 2 files changed, 77 insertions(+), 4 deletions(-)
 create mode 100644 nuxt/components/DocsHeaderActions.vue

diff --git a/nuxt/components/AppHeader.vue b/nuxt/components/AppHeader.vue
index d9b297485f..e4135d7ce6 100644
--- a/nuxt/components/AppHeader.vue
+++ b/nuxt/components/AppHeader.vue
@@ -11,6 +11,9 @@ const hl = (key) => {
 
 const resolveHref = useResolveHref()
 
+const route = useRoute()
+const isDocs = computed(() => route.path === '/docs' || route.path.startsWith('/docs/'))
+
 onMounted(() => {
     const navToggle = document.getElementById('nav-toggle')
     if (navToggle) {
@@ -119,17 +122,17 @@ onMounted(() => {
 </script>
 
 <template>
-  <header id="ff-header" class="ff-header" data-nav-zone="header">
+  <header id="ff-header" class="ff-header" :class="{ 'ff-header--docs': isDocs }" data-nav-zone="header">
     <nav class="relative w-full flex items-center justify-between xl:grid xl:grid-cols-header mx-auto max-screen-none lg:max-w-screen-xl 2xl:max-w-[1920px]">
 
       <!-- Wordmark: visible from 420px up on mobile and on desktop, hidden on tablet -->
-      <a class="ff-logo-link hidden min-[420px]:flex md:hidden lg:flex no-underline hover:no-underline font-bold h-8 w-40 flex-row" href="/" aria-label="FlowFuse Home" style="font-family:'Baloo 2', sans-serif">
+      <a class="ff-logo-link ff-logo-link--wordmark hidden min-[420px]:flex md:hidden lg:flex no-underline hover:no-underline font-bold h-8 w-40 flex-row" href="/" aria-label="FlowFuse Home" style="font-family:'Baloo 2', sans-serif">
         <!-- Five stops feed the staggered hover wave in style.css (ff-logo-wave). -->
         <FlowFuseWordmark uid="header" color="#DA3D0B" />
       </a>
 
       <!-- Square icon: visible below 420px and on tablet -->
-      <a class="ff-logo-link w-8 h-8 block min-[420px]:hidden md:block lg:hidden shrink-0" href="/" aria-label="FlowFuse Home">
+      <a class="ff-logo-link ff-logo-link--square w-8 h-8 block min-[420px]:hidden md:block lg:hidden shrink-0" href="/" aria-label="FlowFuse Home">
         <svg class="ff-wave-square" enable-background="new 0 0 79.4 79.4" viewBox="0 0 79.4 79.4" xmlns="http://www.w3.org/2000/svg">
           <!-- Rests on #ED4E4E, so ff-wave-square rebases the wave in style.css. -->
           <defs>
@@ -148,7 +151,8 @@ onMounted(() => {
 
       <!-- Mobile hamburger -->
       <div class="flex items-center gap-2 md:hidden relative z-20">
-        <CtaBookDemo variant="primary" position="header-mobile" />
+        <DocsHeaderActions />
+        <CtaBookDemo variant="primary" position="header-mobile" class="whitespace-nowrap" />
         <button id="nav-toggle" class="text-gray-700 flex items-center text-red-hero">
           <svg class="burger fill-current h-4 w-4" viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg"><title>Menu</title><path d="M0 3h20v2H0V3zm0 6h20v2H0V9zm0 6h20v2H0v-2z"/></svg>
           <svg class="close fill-current h-6 w-6" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12" /></svg>
@@ -184,6 +188,8 @@ onMounted(() => {
 
       <!-- Desktop CTAs -->
       <ul class="cta hidden md:flex flex-row items-center justify-end font-medium text no-underline z-10 bg-transparent w-auto">
+        <!-- Docs search and Expert, on tablets, where the docs sidebar is folded away. -->
+        <li v-if="isDocs" class="lg:hidden mr-1"><DocsHeaderActions icon-only /></li>
         <li class="hidden md:flex"><CtaSignUp variant="nav-text" position="main-nav" padded class="ff-nav-freetrial text-base" /></li>
         <li class="flex">
           <CtaBookDemo variant="primary" position="main-nav" class="ml-2" />
@@ -201,3 +207,17 @@ onMounted(() => {
     </div>
   </header>
 </template>
+
+<style scoped>
+/* Docs pages add search and Expert to the phone header, so the square logo holds on a
+   little longer before the wordmark takes its place. */
+@media (min-width: 420px) and (max-width: 519px) {
+    .ff-header--docs .ff-logo-link--wordmark {
+        display: none;
+    }
+
+    .ff-header--docs .ff-logo-link--square {
+        display: block;
+    }
+}
+</style>
diff --git a/nuxt/components/DocsHeaderActions.vue b/nuxt/components/DocsHeaderActions.vue
new file mode 100644
index 0000000000..03fbdfe0c9
--- /dev/null
+++ b/nuxt/components/DocsHeaderActions.vue
@@ -0,0 +1,53 @@
+<script setup lang="ts">
+// Docs search and FlowFuse Expert for the site header, where the docs sidebar and the
+// right-hand column are not on screen. AppHeader shows it below lg, on docs pages only.
+defineProps<{
+    /** Show Expert as the FlowFuse mark alone. */
+    iconOnly?: boolean
+}>()
+
+const route = useRoute()
+const isDocs = computed(() => route.path === '/docs' || route.path.startsWith('/docs/'))
+
+function openSearch () {
+    // AlgoliaSearch in the docs sidebar listens for this and opens its search dialog.
+    window.dispatchEvent(new CustomEvent('ff-docs-search:open'))
+}
+</script>
+
+<template>
+  <div v-if="isDocs" class="ff-docs-header-actions flex items-center gap-2">
+    <button
+      type="button"
+      class="ff-docs-header-actions__search"
+      aria-label="Search the documentation"
+      @click="openSearch"
+    >
+      <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="w-5 h-5" aria-hidden="true">
+        <path stroke-linecap="round" stroke-linejoin="round" d="m21 21-5.197-5.197m0 0A7.5 7.5 0 1 0 5.196 5.196a7.5 7.5 0 0 0 10.607 10.607Z" />
+      </svg>
+    </button>
+    <DocsExpertButton variant="compact" position="docs-header" :icon-only="iconOnly" />
+  </div>
+</template>
+
+<style scoped>
+.ff-docs-header-actions__search {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 2.25rem;
+    height: 2.25rem;
+    color: #374151;
+    border-radius: 6px;
+}
+
+.ff-docs-header-actions__search:hover {
+    background: #f3f4f6;
+}
+
+.ff-docs-header-actions__search:focus-visible {
+    outline: 2px solid #4F46E5;
+    outline-offset: 2px;
+}
+</style>

From 67472fc49f5f49a16641674399dc4a8671f3150c Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 14:43:43 +0200
Subject: [PATCH 07/31] docs search: an X to close the dialog, no ring round
 the input, border back on the button

The dialog header now reads like a plain search bar: the input sits flat above the
header's divider with no box or focus ring, the search icon is grey, and Cancel is an X
(still named Close for screen readers). The input's own clear button is hidden so the X
is the only one. The dialog carries an ff-search-dialog class, so the blog, changelog and
handbook phone dialogs are unchanged. The sidebar button lost its border to
algolia-theme.css, whose #algolia-search rule outranked the component's classes; the
component's rule now includes the id.
---
 nuxt/components/AlgoliaSearch.vue | 72 +++++++++++++++++++++++++++----
 1 file changed, 64 insertions(+), 8 deletions(-)

diff --git a/nuxt/components/AlgoliaSearch.vue b/nuxt/components/AlgoliaSearch.vue
index d6d34df988..3a3d0d7f40 100644
--- a/nuxt/components/AlgoliaSearch.vue
+++ b/nuxt/components/AlgoliaSearch.vue
@@ -83,7 +83,13 @@ onMounted(async () => {
         // An empty media query matches every width, so the input is always a button that
         // opens the dialog: centred on wide screens, full screen on narrow ones (the theme's
         // --aa-detached-modal-media-query decides which).
-        ...(props.detached ? { detachedMediaQuery: '' } : {}),
+        // The dialog carries its own class, so its styles below leave the other searches'
+        // phone dialogs alone. Its close button reads "Close" to a screen reader and shows an X.
+        ...(props.detached ? {
+            detachedMediaQuery: '',
+            classNames: { detachedContainer: 'ff-search-dialog' },
+            translations: { detachedCancelButtonText: 'Close' },
+        } : {}),
         getSources ({ query }: { query: string }) {
             if (query !== prevQuery) {
                 prevQuery = query
@@ -174,11 +180,13 @@ onMounted(async () => {
     position: relative;
 }
 
-/* The search button reads as a search field, with the shortcut shown at its right edge. */
-.ff-algolia--detached :deep(.aa-DetachedSearchButton) {
+/* The search button reads as a search field, with the shortcut shown at its right edge.
+   The id is in the selector because src/css/algolia-theme.css strips the border and padding
+   from `#algolia-search .aa-DetachedSearchButton`, and an id outranks the classes alone. */
+.ff-algolia--detached :deep(#algolia-search .aa-DetachedSearchButton) {
     width: 100%;
     height: 2.5rem;
-    padding-right: 4rem;
+    padding: 0 4rem 0 0.5rem;
     border: 1px solid #d1d5db;
     border-radius: 6px;
     background: #fff;
@@ -187,7 +195,7 @@ onMounted(async () => {
     cursor: pointer;
 }
 
-.ff-algolia--detached :deep(.aa-DetachedSearchButton:hover) {
+.ff-algolia--detached :deep(#algolia-search .aa-DetachedSearchButton:hover) {
     border-color: #a5b4fc;
 }
 
@@ -209,9 +217,57 @@ onMounted(async () => {
 </style>
 
 <style>
-/* The dialog is appended to <body>, outside this component, so this is not scoped. It only
-   exists for a detached search, which only the docs use. */
-.aa-DetachedContainer--modal {
+/* The dialog is appended to <body>, outside this component, so this is not scoped. */
+.ff-search-dialog.aa-DetachedContainer--modal {
     top: 12vh;
 }
+
+/* The input sits flat in the dialog header, above the header's own divider: no box and no
+   focus ring around it, since the caret already shows where typing goes. */
+.ff-search-dialog .aa-Form,
+.ff-search-dialog .aa-Form:focus-within {
+    border: 0;
+    box-shadow: none;
+}
+
+.ff-search-dialog .aa-SubmitIcon {
+    color: #6b7280;
+}
+
+/* The close X is the only X in the header, so the input's own clear button stays out. */
+.ff-search-dialog .aa-ClearButton {
+    display: none;
+}
+
+.ff-search-dialog .aa-DetachedCancelButton {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    flex-shrink: 0;
+    width: 2.5rem;
+    height: 2.5rem;
+    margin: auto 0 auto 0.25rem;
+    padding: 0;
+    border-radius: 6px;
+    color: #374151;
+    /* The word stays for screen readers; the X below is what shows. */
+    font-size: 0;
+}
+
+.ff-search-dialog .aa-DetachedCancelButton::before {
+    content: '';
+    width: 1.25rem;
+    height: 1.25rem;
+    background: currentColor;
+    mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round'%3E%3Cpath d='M18 6 6 18M6 6l12 12'/%3E%3C/svg%3E") center / contain no-repeat;
+}
+
+.ff-search-dialog .aa-DetachedCancelButton:hover {
+    background: #f3f4f6;
+}
+
+.ff-search-dialog .aa-DetachedCancelButton:focus-visible {
+    outline: 2px solid #4f46e5;
+    outline-offset: 2px;
+}
 </style>

From d869fb659a414effed34cd0b1f88ececeefb09fc Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 14:43:43 +0200
Subject: [PATCH 08/31] docs: breadcrumb on the docs home, Ask Expert under the
 table of contents

/docs now shows its single Docs crumb, so every docs page opens the same way. The
right-hand Expert button moves below the table of contents and reads Ask Expert with the
FlowFuse mark, like the compact header button, instead of the FlowFuse wordmark. On wide
screens the column is capped to the window and a long table of contents scrolls inside
itself, so the button under it stays in view.
---
 nuxt/components/DocsExpertButton.vue | 30 ++++++++++------------------
 nuxt/pages/docs/[...slug].vue        | 15 ++++++++------
 2 files changed, 19 insertions(+), 26 deletions(-)

diff --git a/nuxt/components/DocsExpertButton.vue b/nuxt/components/DocsExpertButton.vue
index 06145ce909..a44b58dafb 100644
--- a/nuxt/components/DocsExpertButton.vue
+++ b/nuxt/components/DocsExpertButton.vue
@@ -1,9 +1,10 @@
 <script setup lang="ts">
 // Opens the FlowFuse Expert conversation from anywhere on a docs page.
 //
-// `toc` is the branded call to action in the right-hand column. `compact` matches the
-// Expert button in the FlowFuse app header (the FlowFuse mark and "Expert" inside a
-// slowly turning gradient border), for the site header on narrow screens.
+// Both variants follow the Expert button in the FlowFuse app header: the FlowFuse mark and
+// a label inside a slowly turning gradient border. `toc` is the full-width "Ask Expert"
+// under the table of contents; `compact` is the smaller "Expert" for the site header on
+// narrow screens.
 const props = withDefaults(defineProps<{
     variant?: 'toc' | 'compact'
     position?: string
@@ -27,20 +28,11 @@ function open () {
     type="button"
     class="ff-expert-btn"
     :class="[`ff-expert-btn--${variant}`, { 'ff-expert-btn--icon': iconOnly }]"
-    :aria-label="variant === 'compact' ? 'Ask FlowFuse Expert' : undefined"
+    aria-label="Ask FlowFuse Expert"
     @click="open"
   >
-    <template v-if="variant === 'toc'">
-      <span>Ask</span>
-      <span class="ff-expert-btn__wordmark" aria-label="FlowFuse" role="img">
-        <FlowFuseWordmark uid="expert-toc" />
-      </span>
-      <span>Expert</span>
-    </template>
-    <template v-else>
-      <img :src="'/images/ff-minimal-red.svg'" alt="" class="ff-expert-btn__mark">
-      <span class="ff-expert-btn__label">Expert</span>
-    </template>
+    <img :src="'/images/ff-minimal-red.svg'" alt="" class="ff-expert-btn__mark">
+    <span class="ff-expert-btn__label">{{ variant === 'toc' ? 'Ask Expert' : 'Expert' }}</span>
   </button>
 </template>
 
@@ -119,16 +111,14 @@ function open () {
 .ff-expert-btn--toc {
     width: 100%;
     justify-content: center;
+    gap: 0.5rem;
     padding: 0.625rem 0.75rem;
     font-size: 0.95rem;
     line-height: 1.25rem;
 }
 
-.ff-expert-btn__wordmark {
-    display: inline-block;
-    width: 5.5rem;
-    height: 1rem;
-    line-height: 0;
+.ff-expert-btn--toc .ff-expert-btn__mark {
+    margin-left: 0;
 }
 
 @keyframes ff-expert-swirl {
diff --git a/nuxt/pages/docs/[...slug].vue b/nuxt/pages/docs/[...slug].vue
index 9e286d4e24..ec060f51c5 100644
--- a/nuxt/pages/docs/[...slug].vue
+++ b/nuxt/pages/docs/[...slug].vue
@@ -122,7 +122,8 @@ const surround = computed(() => {
           <!-- Breadcrumbs -->
           <div class="font-medium pb-1 flex flex-col gap-1">
             <div class="md:flex-1">
-              <Breadcrumbs v-if="breadcrumbItems.length > 1" :items="breadcrumbItems" />
+              <!-- On /docs itself this is the one unlinked "Docs" crumb, so every page opens the same way. -->
+              <Breadcrumbs :items="breadcrumbItems" />
             </div>
           </div>
         </div>
@@ -141,17 +142,19 @@ const surround = computed(() => {
 
       <!-- Right sidebar: TOC -->
       <div class="lg right-nav">
-        <div class="sticky top-20 w-full mt-4 md:mt-6 px-8">
+        <!-- On wide screens the column never runs past the bottom of the window: a long table
+             of contents scrolls inside itself, so the Expert button under it stays in view. -->
+        <div class="sticky top-20 w-full mt-4 md:mt-6 px-8 lg:flex lg:flex-col lg:max-h-[calc(100vh-7.5rem)]">
+          <HandbookToc :links="page?.body?.toc?.links" :ui="{ root: 'lg:min-h-0' }" />
           <!-- Hidden while the page's own Expert question box is on screen. -->
-          <div v-if="!expertInlineVisible" class="max-lg:hidden mb-6">
+          <div v-if="!expertInlineVisible" class="max-lg:hidden mt-2 shrink-0">
             <DocsExpertButton variant="toc" position="docs-toc" />
           </div>
-          <HandbookToc :links="page?.body?.toc?.links" />
-          <div v-if="page?.updated" class="text-xs pb-1 text-right mt-4 text-gray-500 max-lg:hidden">
+          <div v-if="page?.updated" class="text-xs pb-1 text-right mt-4 text-gray-500 max-lg:hidden shrink-0">
             Updated: <RelativeTime :value="page.updated" />
           </div>
           <ClientOnly>
-            <div v-if="editHref" class="text-xs pb-1 text-right italic max-lg:hidden">
+            <div v-if="editHref" class="text-xs pb-1 text-right italic max-lg:hidden shrink-0">
               <a :href="editHref" target="_blank" rel="noopener">Edit this page</a>
             </div>
           </ClientOnly>

From fac5747137b5e9aca35d137c292216c3f749b114 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 14:43:44 +0200
Subject: [PATCH 09/31] docs: the Expert box's brand flies into the modal
 header

The question box and the conversation modal now render FlowFuse Expert from one
DocsExpertBrand component at the modal's size; the box's was larger. When the box morphs
into the modal, its brand gets its own view transition and moves up into the modal
header while the rest of the box morphs into the input area as before, and back again on
close. Pages without a branded box (the Eleventy /ai/ page) are unaffected.
---
 nuxt/components/DocsExpertBrand.vue     | 55 +++++++++++++++++++++++++
 nuxt/components/DocsExpertHost.vue      |  7 +---
 nuxt/components/content/FfExpertAsk.vue | 24 +----------
 3 files changed, 58 insertions(+), 28 deletions(-)
 create mode 100644 nuxt/components/DocsExpertBrand.vue

diff --git a/nuxt/components/DocsExpertBrand.vue b/nuxt/components/DocsExpertBrand.vue
new file mode 100644
index 0000000000..aebe60ba3c
--- /dev/null
+++ b/nuxt/components/DocsExpertBrand.vue
@@ -0,0 +1,55 @@
+<script setup lang="ts">
+// "FlowFuse Expert", the same in the page's question box (FfExpertAsk) and in the header of
+// the conversation modal (DocsExpertHost). When the box morphs into the modal,
+// src/js/ai-expert-modal.js finds both by data-ff-expert-brand and flies the box's one up
+// into the modal header, so the two have to stay the same size.
+defineProps<{
+    uid: string
+    /** Render "Expert" as the dialog's heading, with this id for its aria-labelledby. */
+    headingId?: string
+}>()
+</script>
+
+<template>
+  <div class="ff-expert-brand" data-ff-expert-brand>
+    <span class="ff-expert-brand__wordmark" role="img" aria-label="FlowFuse">
+      <FlowFuseWordmark :uid="uid" />
+    </span>
+    <h2 v-if="headingId" :id="headingId" class="ff-expert-brand__product">Expert</h2>
+    <span v-else class="ff-expert-brand__product">Expert</span>
+  </div>
+</template>
+
+<style scoped>
+/* Only as wide as its content, in the box as in the modal, so the flight between them moves
+   it without stretching it. */
+.ff-expert-brand {
+    display: flex;
+    align-items: center;
+    gap: 0.25rem;
+    width: fit-content;
+}
+
+.ff-expert-brand__wordmark {
+    display: inline-block;
+    width: 6rem;
+    height: 1.5rem;
+    line-height: 0;
+}
+
+.ff-expert-brand__product {
+    margin: 0 0 -0.25rem;
+    font-size: 1rem;
+    line-height: 1.5rem;
+    font-weight: 600;
+    color: #374151;
+}
+</style>
+
+<style>
+/* Same pace as the box morphing into the input area (src/css/style.css, morphing-content). */
+::view-transition-group(ff-expert-brand) {
+    animation-duration: 0.5s;
+    animation-timing-function: cubic-bezier(0.4, 0.0, 0.2, 1);
+}
+</style>
diff --git a/nuxt/components/DocsExpertHost.vue b/nuxt/components/DocsExpertHost.vue
index 057d3bb96d..dcdae19734 100644
--- a/nuxt/components/DocsExpertHost.vue
+++ b/nuxt/components/DocsExpertHost.vue
@@ -19,12 +19,7 @@ onMounted(() => {
     <div class="bg-white rounded-none md:rounded-lg shadow-xl w-full max-w-4xl h-full md:h-full flex flex-col relative">
       <div class="ai-chat-box">
         <div class="textarea-wrapper modal-header flex items-center justify-between px-4 py-3 rounded-t-none md:rounded-t-lg h-auto rounded-b-none mb-0">
-          <div class="flex items-center gap-1">
-            <div class="w-24 h-6">
-              <FlowFuseWordmark uid="expert-modal" />
-            </div>
-            <h2 id="ai-expert-modal-title" class="text-base font-semibold text-gray-700 -mb-1">Expert</h2>
-          </div>
+          <DocsExpertBrand uid="expert-modal" heading-id="ai-expert-modal-title" />
           <button id="close-modal" type="button" class="text-gray-500 hover:text-gray-600" aria-label="Close dialog">
             <svg width="24" height="24" viewBox="0 0 24 24" fill="none">
               <path d="M18 6L6 18" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
diff --git a/nuxt/components/content/FfExpertAsk.vue b/nuxt/components/content/FfExpertAsk.vue
index 1f7d65ce09..6c08eb5692 100644
--- a/nuxt/components/content/FfExpertAsk.vue
+++ b/nuxt/components/content/FfExpertAsk.vue
@@ -57,10 +57,7 @@ function track () {
     <div class="ai-chat-box">
       <div class="textarea-wrapper ff-expert-ask__card relative mb-4 rounded-lg overflow-hidden">
         <div class="ff-expert-ask__brand">
-          <span class="ff-expert-ask__wordmark" role="img" aria-label="FlowFuse">
-            <FlowFuseWordmark uid="expert-ask" />
-          </span>
-          <span class="ff-expert-ask__product">Expert</span>
+          <DocsExpertBrand uid="expert-ask" />
         </div>
         <div class="relative h-32 p-4 pb-12">
           <textarea
@@ -100,29 +97,12 @@ function track () {
 </template>
 
 <style scoped>
+/* Same padding as the modal header, so the brand flies between matching spots. */
 .ff-expert-ask__brand {
-    display: flex;
-    align-items: center;
-    gap: 0.375rem;
     padding: 0.75rem 1rem;
     border-bottom: 1px solid transparent;
     background:
         linear-gradient(#fff, #fff) padding-box,
         linear-gradient(90deg, #f87171, #f472b6, #a78bfa) border-box;
 }
-
-.ff-expert-ask__wordmark {
-    display: inline-block;
-    width: 7rem;
-    height: 1.25rem;
-    line-height: 0;
-}
-
-.ff-expert-ask__product {
-    font-size: 1.125rem;
-    line-height: 1;
-    font-weight: 600;
-    color: #374151;
-    margin-top: 0.125rem;
-}
 </style>

From 82a4143d25ef2451f816d6c9d242578c298c5222 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 15:01:42 +0200
Subject: [PATCH 10/31] docs: Ask Docs, a floating button for FlowFuse Expert
 on every docs page

FlowFuse Expert now has one entry point on docs pages: a round Ask Docs button in the
bottom-right corner at every screen width, which steps aside while a page's own question
box is on screen. The Expert buttons in the right-hand column and in the phone and tablet
header are gone, so the header keeps only the docs search there. DocsExpertButton is
removed with them.
---
 nuxt/components/AppHeader.vue         |   9 +-
 nuxt/components/DocsAskFab.vue        |  84 +++++++++++++++++
 nuxt/components/DocsExpertButton.vue  | 128 --------------------------
 nuxt/components/DocsHeaderActions.vue |  10 +-
 nuxt/layouts/default.vue              |   3 +-
 5 files changed, 93 insertions(+), 141 deletions(-)
 create mode 100644 nuxt/components/DocsAskFab.vue
 delete mode 100644 nuxt/components/DocsExpertButton.vue

diff --git a/nuxt/components/AppHeader.vue b/nuxt/components/AppHeader.vue
index e4135d7ce6..92bd904866 100644
--- a/nuxt/components/AppHeader.vue
+++ b/nuxt/components/AppHeader.vue
@@ -188,8 +188,8 @@ onMounted(() => {
 
       <!-- Desktop CTAs -->
       <ul class="cta hidden md:flex flex-row items-center justify-end font-medium text no-underline z-10 bg-transparent w-auto">
-        <!-- Docs search and Expert, on tablets, where the docs sidebar is folded away. -->
-        <li v-if="isDocs" class="lg:hidden mr-1"><DocsHeaderActions icon-only /></li>
+        <!-- Docs search, on tablets, where the docs sidebar is folded away. -->
+        <li v-if="isDocs" class="lg:hidden mr-1"><DocsHeaderActions /></li>
         <li class="hidden md:flex"><CtaSignUp variant="nav-text" position="main-nav" padded class="ff-nav-freetrial text-base" /></li>
         <li class="flex">
           <CtaBookDemo variant="primary" position="main-nav" class="ml-2" />
@@ -209,8 +209,9 @@ onMounted(() => {
 </template>
 
 <style scoped>
-/* Docs pages add search and Expert to the phone header, so the square logo holds on a
-   little longer before the wordmark takes its place. */
+/* Docs pages add search to the phone header, so the square logo holds on a little longer
+   before the wordmark takes its place (without this the wordmark touches the search button
+   at 420 to 440px). */
 @media (min-width: 420px) and (max-width: 519px) {
     .ff-header--docs .ff-logo-link--wordmark {
         display: none;
diff --git a/nuxt/components/DocsAskFab.vue b/nuxt/components/DocsAskFab.vue
new file mode 100644
index 0000000000..08a376f027
--- /dev/null
+++ b/nuxt/components/DocsAskFab.vue
@@ -0,0 +1,84 @@
+<script setup lang="ts">
+// "Ask Docs": the one entry point to FlowFuse Expert on every docs page, floating in the
+// bottom-right corner at every screen width. It steps aside while a page's own question
+// box (FfExpertAsk) is on screen, since that box opens the same conversation.
+const inlineVisible = useExpertInlineVisible()
+
+function open () {
+    const capture = (window as any).capture
+    if (typeof capture === 'function') capture('cta-ai-get-started', { position: 'docs-fab' })
+    openDocsExpert()
+}
+</script>
+
+<template>
+  <Transition name="ff-ask-fab">
+    <button
+      v-show="!inlineVisible"
+      type="button"
+      class="ff-ask-fab"
+      title="Ask FlowFuse Expert about the docs"
+      @click="open"
+    >
+      <span>Ask Docs</span>
+      <UIcon name="i-lucide-book-open" class="ff-ask-fab__icon" aria-hidden="true" />
+    </button>
+  </Transition>
+</template>
+
+<style scoped>
+.ff-ask-fab {
+    position: fixed;
+    right: 1.5rem;
+    bottom: 1.5rem;
+    z-index: 60;
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    height: 2.5rem;
+    padding: 0 1rem 0 1.125rem;
+    border-radius: 9999px;
+    background: #111827;
+    color: #fff;
+    font-size: 0.9375rem;
+    font-weight: 500;
+    line-height: 1;
+    white-space: nowrap;
+    cursor: pointer;
+    box-shadow: 0 4px 8px rgb(17 24 39 / 0.08), 0 12px 28px -2px rgb(17 24 39 / 0.18);
+    transition: background-color 0.15s ease, transform 0.15s ease;
+}
+
+.ff-ask-fab:hover {
+    background: #1f2937;
+    transform: translateY(-1px);
+}
+
+.ff-ask-fab:focus-visible {
+    outline: 2px solid #4F46E5;
+    outline-offset: 3px;
+}
+
+.ff-ask-fab__icon {
+    width: 1.125rem;
+    height: 1.125rem;
+}
+
+@media (max-width: 639px) {
+    .ff-ask-fab {
+        right: 1rem;
+        bottom: 1rem;
+    }
+}
+
+.ff-ask-fab-enter-active,
+.ff-ask-fab-leave-active {
+    transition: opacity 0.2s ease, transform 0.2s ease;
+}
+
+.ff-ask-fab-enter-from,
+.ff-ask-fab-leave-to {
+    opacity: 0;
+    transform: translateY(0.5rem);
+}
+</style>
diff --git a/nuxt/components/DocsExpertButton.vue b/nuxt/components/DocsExpertButton.vue
deleted file mode 100644
index a44b58dafb..0000000000
--- a/nuxt/components/DocsExpertButton.vue
+++ /dev/null
@@ -1,128 +0,0 @@
-<script setup lang="ts">
-// Opens the FlowFuse Expert conversation from anywhere on a docs page.
-//
-// Both variants follow the Expert button in the FlowFuse app header: the FlowFuse mark and
-// a label inside a slowly turning gradient border. `toc` is the full-width "Ask Expert"
-// under the table of contents; `compact` is the smaller "Expert" for the site header on
-// narrow screens.
-const props = withDefaults(defineProps<{
-    variant?: 'toc' | 'compact'
-    position?: string
-    /** Compact only: the FlowFuse mark alone, for a header that is short of room. */
-    iconOnly?: boolean
-}>(), {
-    variant: 'toc',
-    position: 'docs-toc',
-    iconOnly: false,
-})
-
-function open () {
-    const capture = (window as any).capture
-    if (typeof capture === 'function') capture('cta-ai-get-started', { position: props.position })
-    openDocsExpert()
-}
-</script>
-
-<template>
-  <button
-    type="button"
-    class="ff-expert-btn"
-    :class="[`ff-expert-btn--${variant}`, { 'ff-expert-btn--icon': iconOnly }]"
-    aria-label="Ask FlowFuse Expert"
-    @click="open"
-  >
-    <img :src="'/images/ff-minimal-red.svg'" alt="" class="ff-expert-btn__mark">
-    <span class="ff-expert-btn__label">{{ variant === 'toc' ? 'Ask Expert' : 'Expert' }}</span>
-  </button>
-</template>
-
-<style scoped>
-@property --ff-expert-border-angle {
-    syntax: '<angle>';
-    inherits: false;
-    initial-value: 135deg;
-}
-
-.ff-expert-btn {
-    display: inline-flex;
-    align-items: center;
-    gap: 0.375rem;
-    font-weight: 700;
-    color: #1f2937;
-    white-space: nowrap;
-    cursor: pointer;
-    border: 1px solid transparent;
-    border-radius: 6px;
-    background:
-        linear-gradient(#fff, #fff) padding-box,
-        conic-gradient(from var(--ff-expert-border-angle), #BC3838, #9333EA, #4F46E5, #9333EA, #BC3838) border-box;
-}
-
-@media (prefers-reduced-motion: no-preference) {
-    .ff-expert-btn {
-        animation: ff-expert-swirl 9s linear infinite;
-    }
-}
-
-.ff-expert-btn:hover {
-    background:
-        linear-gradient(#f5f5ff, #f5f5ff) padding-box,
-        conic-gradient(from var(--ff-expert-border-angle), #BC3838, #9333EA, #4F46E5, #9333EA, #BC3838) border-box;
-}
-
-.ff-expert-btn:focus-visible {
-    outline: 2px solid #4F46E5;
-    outline-offset: 2px;
-}
-
-.ff-expert-btn--compact {
-    padding: 6px 9px;
-    font-size: 0.85rem;
-    line-height: 20px;
-}
-
-.ff-expert-btn__mark {
-    width: 1.25rem;
-    height: 1.25rem;
-    margin-left: -0.25rem;
-    flex-shrink: 0;
-}
-
-/* On a phone the header also carries search, Book a demo and the menu, so the pill shows
-   the FlowFuse mark only. */
-@media (max-width: 599px) {
-    .ff-expert-btn--compact .ff-expert-btn__label {
-        display: none;
-    }
-
-    .ff-expert-btn--compact .ff-expert-btn__mark {
-        margin-left: 0;
-    }
-}
-
-.ff-expert-btn--icon .ff-expert-btn__label {
-    display: none;
-}
-
-.ff-expert-btn--icon .ff-expert-btn__mark {
-    margin-left: 0;
-}
-
-.ff-expert-btn--toc {
-    width: 100%;
-    justify-content: center;
-    gap: 0.5rem;
-    padding: 0.625rem 0.75rem;
-    font-size: 0.95rem;
-    line-height: 1.25rem;
-}
-
-.ff-expert-btn--toc .ff-expert-btn__mark {
-    margin-left: 0;
-}
-
-@keyframes ff-expert-swirl {
-    from { --ff-expert-border-angle: 135deg; }
-    to { --ff-expert-border-angle: 495deg; }
-}
-</style>
diff --git a/nuxt/components/DocsHeaderActions.vue b/nuxt/components/DocsHeaderActions.vue
index 03fbdfe0c9..845129922f 100644
--- a/nuxt/components/DocsHeaderActions.vue
+++ b/nuxt/components/DocsHeaderActions.vue
@@ -1,11 +1,6 @@
 <script setup lang="ts">
-// Docs search and FlowFuse Expert for the site header, where the docs sidebar and the
-// right-hand column are not on screen. AppHeader shows it below lg, on docs pages only.
-defineProps<{
-    /** Show Expert as the FlowFuse mark alone. */
-    iconOnly?: boolean
-}>()
-
+// Docs search for the site header, where the docs sidebar is not on screen. AppHeader shows
+// it below lg, on docs pages only. FlowFuse Expert is the Ask Docs button (DocsAskFab).
 const route = useRoute()
 const isDocs = computed(() => route.path === '/docs' || route.path.startsWith('/docs/'))
 
@@ -27,7 +22,6 @@ function openSearch () {
         <path stroke-linecap="round" stroke-linejoin="round" d="m21 21-5.197-5.197m0 0A7.5 7.5 0 1 0 5.196 5.196a7.5 7.5 0 0 0 10.607 10.607Z" />
       </svg>
     </button>
-    <DocsExpertButton variant="compact" position="docs-header" :icon-only="iconOnly" />
   </div>
 </template>
 
diff --git a/nuxt/layouts/default.vue b/nuxt/layouts/default.vue
index 4998dee667..e0dd47141c 100644
--- a/nuxt/layouts/default.vue
+++ b/nuxt/layouts/default.vue
@@ -19,7 +19,8 @@ const isDocs = computed(() => route.path === '/docs' || route.path.startsWith('/
       </div>
     </div>
     <AppFooter />
-    <!-- FlowFuse Expert's conversation, opened from the docs pages' question box, sidebar and header. -->
+    <!-- FlowFuse Expert's conversation, opened from Ask Docs and from a page's own question box. -->
     <DocsExpertHost v-if="isDocs" />
+    <DocsAskFab v-if="isDocs" />
   </div>
 </template>

From d71915c0775096e4ccb2bd5abfa5ffa3e62e337d Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 15:01:42 +0200
Subject: [PATCH 11/31] docs: On this page lines up with the sidebar search and
 the breadcrumb

The right-hand column started 22px lower than the other two because the table of contents
pads its own container. It now starts where the sidebar's search field does and centres
its first line the same way, so the three columns share one top line. The column also no
longer reserves room for the Expert button that moved to Ask Docs.
---
 nuxt/pages/docs/[...slug].vue | 13 +++++--------
 1 file changed, 5 insertions(+), 8 deletions(-)

diff --git a/nuxt/pages/docs/[...slug].vue b/nuxt/pages/docs/[...slug].vue
index ec060f51c5..516318c4a4 100644
--- a/nuxt/pages/docs/[...slug].vue
+++ b/nuxt/pages/docs/[...slug].vue
@@ -81,8 +81,6 @@ defineOgImage('Default', seo.value.ogImage)
 // Same key+handler DocsLeftNav uses, so useAsyncData dedupes into one fetch per request.
 const { data: navGroups } = await useDocsNavTree()
 
-const expertInlineVisible = useExpertInlineVisible()
-
 const breadcrumbItems = computed(() => {
     const crumbs = findDocsBreadcrumb(navGroups.value ?? [], route.path)
     const withRoot = [{ title: 'Docs', path: '/docs' }, ...crumbs]
@@ -143,13 +141,12 @@ const surround = computed(() => {
       <!-- Right sidebar: TOC -->
       <div class="lg right-nav">
         <!-- On wide screens the column never runs past the bottom of the window: a long table
-             of contents scrolls inside itself, so the Expert button under it stays in view. -->
+             of contents scrolls inside itself, so the lines under it stay in view.
+             "On this page" lines up with the sidebar's search text and the breadcrumb: the
+             column starts where the search field does (mt-6), and pt-2.5 is half of the
+             field's 40px less one 20px line. -->
         <div class="sticky top-20 w-full mt-4 md:mt-6 px-8 lg:flex lg:flex-col lg:max-h-[calc(100vh-7.5rem)]">
-          <HandbookToc :links="page?.body?.toc?.links" :ui="{ root: 'lg:min-h-0' }" />
-          <!-- Hidden while the page's own Expert question box is on screen. -->
-          <div v-if="!expertInlineVisible" class="max-lg:hidden mt-2 shrink-0">
-            <DocsExpertButton variant="toc" position="docs-toc" />
-          </div>
+          <HandbookToc :links="page?.body?.toc?.links" :ui="{ root: 'lg:min-h-0', container: 'lg:pt-2.5' }" />
           <div v-if="page?.updated" class="text-xs pb-1 text-right mt-4 text-gray-500 max-lg:hidden shrink-0">
             Updated: <RelativeTime :value="page.updated" />
           </div>

From 408ea31d9aafcc9b106add5d93c8fa11a692c69a Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 15:01:42 +0200
Subject: [PATCH 12/31] header: a subtle grey line under the site header

A 1px gray-200 line separates the sticky header from the page on every page, Nuxt and
Eleventy alike, since both link this stylesheet. It is a shadow rather than a border, so
the header height that --ff-header-height tracks does not change.
---
 nuxt/assets/css/style.css | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/nuxt/assets/css/style.css b/nuxt/assets/css/style.css
index 79076bf728..91920a56de 100644
--- a/nuxt/assets/css/style.css
+++ b/nuxt/assets/css/style.css
@@ -999,8 +999,11 @@ h4:hover .header-anchor::before {
         font-weight: 400;
     }
 
+    /* The grey line under the header is a shadow, not a border, so it adds nothing to the
+       height that --ff-header-height below has to match. */
     .ff-website .ff-header {
         @apply bg-white w-full px-6 py-4 sm:py-6 md:py-0 top-0 z-50 sticky;
+        box-shadow: 0 1px 0 var(--color-gray-200);
     }
 
     /* The header pins itself to the top of the viewport, so anything else that wants to

From 8befa145cdb7efbe589549a87e053eab8d4a0733 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 15:14:31 +0200
Subject: [PATCH 13/31] docs: Ask Docs wears FlowFuse Expert's colours

The floating button is now white with the FlowFuse mark and a slowly turning brand-red to
indigo border, as the Expert button in the FlowFuse app is. Its box matches the header's
Book a demo button (40px tall, 16px text, the same padding), keeping the pill shape.
---
 nuxt/components/DocsAskFab.vue | 53 ++++++++++++++++++++++++++--------
 1 file changed, 41 insertions(+), 12 deletions(-)

diff --git a/nuxt/components/DocsAskFab.vue b/nuxt/components/DocsAskFab.vue
index 08a376f027..19fa8e5ab7 100644
--- a/nuxt/components/DocsAskFab.vue
+++ b/nuxt/components/DocsAskFab.vue
@@ -2,6 +2,11 @@
 // "Ask Docs": the one entry point to FlowFuse Expert on every docs page, floating in the
 // bottom-right corner at every screen width. It steps aside while a page's own question
 // box (FfExpertAsk) is on screen, since that box opens the same conversation.
+//
+// It wears FlowFuse Expert's colours, as the Expert button in the FlowFuse app does: the
+// FlowFuse mark, and a slowly turning brand-red to indigo border. Its box matches the
+// header's Book a demo button (40px tall, 16px text, 8px 16px padding), so the two calls
+// to action read as one family; the pill shape marks this one as floating.
 const inlineVisible = useExpertInlineVisible()
 
 function open () {
@@ -20,13 +25,19 @@ function open () {
       title="Ask FlowFuse Expert about the docs"
       @click="open"
     >
+      <img :src="'/images/ff-minimal-red.svg'" alt="" class="ff-ask-fab__mark">
       <span>Ask Docs</span>
-      <UIcon name="i-lucide-book-open" class="ff-ask-fab__icon" aria-hidden="true" />
     </button>
   </Transition>
 </template>
 
 <style scoped>
+@property --ff-ask-fab-angle {
+    syntax: '<angle>';
+    inherits: false;
+    initial-value: 135deg;
+}
+
 .ff-ask-fab {
     position: fixed;
     right: 1.5rem;
@@ -36,22 +47,34 @@ function open () {
     align-items: center;
     gap: 0.5rem;
     height: 2.5rem;
-    padding: 0 1rem 0 1.125rem;
+    padding: 8px 18px 8px 14px;
+    border: 1.5px solid transparent;
     border-radius: 9999px;
-    background: #111827;
-    color: #fff;
-    font-size: 0.9375rem;
-    font-weight: 500;
+    background:
+        linear-gradient(#fff, #fff) padding-box,
+        conic-gradient(from var(--ff-ask-fab-angle), #DA3D0B, #9333EA, #4F46E5, #9333EA, #DA3D0B) border-box;
+    color: #111827;
+    font-size: 1rem;
+    font-weight: 600;
     line-height: 1;
     white-space: nowrap;
     cursor: pointer;
-    box-shadow: 0 4px 8px rgb(17 24 39 / 0.08), 0 12px 28px -2px rgb(17 24 39 / 0.18);
-    transition: background-color 0.15s ease, transform 0.15s ease;
+    box-shadow: 0 4px 8px rgb(17 24 39 / 0.08), 0 12px 28px -2px rgb(79 70 229 / 0.22);
+    transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+    .ff-ask-fab {
+        animation: ff-ask-fab-swirl 9s linear infinite;
+    }
 }
 
 .ff-ask-fab:hover {
-    background: #1f2937;
+    background:
+        linear-gradient(#f5f5ff, #f5f5ff) padding-box,
+        conic-gradient(from var(--ff-ask-fab-angle), #DA3D0B, #9333EA, #4F46E5, #9333EA, #DA3D0B) border-box;
     transform: translateY(-1px);
+    box-shadow: 0 6px 12px rgb(17 24 39 / 0.1), 0 16px 32px -4px rgb(79 70 229 / 0.3);
 }
 
 .ff-ask-fab:focus-visible {
@@ -59,9 +82,10 @@ function open () {
     outline-offset: 3px;
 }
 
-.ff-ask-fab__icon {
-    width: 1.125rem;
-    height: 1.125rem;
+.ff-ask-fab__mark {
+    width: 1.25rem;
+    height: 1.25rem;
+    flex-shrink: 0;
 }
 
 @media (max-width: 639px) {
@@ -71,6 +95,11 @@ function open () {
     }
 }
 
+@keyframes ff-ask-fab-swirl {
+    from { --ff-ask-fab-angle: 135deg; }
+    to { --ff-ask-fab-angle: 495deg; }
+}
+
 .ff-ask-fab-enter-active,
 .ff-ask-fab-leave-active {
     transition: opacity 0.2s ease, transform 0.2s ease;

From 9303ebc729511d622662c873ba9126a9df25f7a4 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 15:14:31 +0200
Subject: [PATCH 14/31] docs: a landing layout and the blocks a docs contents
 page is built from

A docs page whose frontmatter sets landing: true gets the full page width: no sidebar, no
table of contents, no previous and next cards, and its body is not wrapped in .prose,
because every block on it styles itself. The breadcrumb stays. Three content components
build such a page from markdown, next to Nuxt UI's own cards, tabs and steps:

- docs-hero: heading and line, the docs search (the page's Cmd+K search, since there is
  no sidebar), a row of buttons from a markdown list, and an aside slot beside them.
- docs-section: eyebrow, heading and one line, then the section's cards or tiles.
- docs-tiles: a markdown list of links as a grid of tiles, each clickable across its
  whole area; the links stay plain markdown so the flowfuse link check still sees them.

AlgoliaSearch gains a taller lg size for the hero. The copy-command block no longer
picks up the site-wide code box inside itself on pages outside .nohero.
---
 nuxt/assets/css/style.css               |   5 +
 nuxt/components/AlgoliaSearch.vue       |  12 +-
 nuxt/components/content/DocsHero.vue    | 220 ++++++++++++++++++++++++
 nuxt/components/content/DocsSection.vue | 158 +++++++++++++++++
 nuxt/components/content/DocsTiles.vue   | 101 +++++++++++
 nuxt/content.config.ts                  |   3 +
 nuxt/pages/docs/[...slug].vue           |  13 +-
 7 files changed, 510 insertions(+), 2 deletions(-)
 create mode 100644 nuxt/components/content/DocsHero.vue
 create mode 100644 nuxt/components/content/DocsSection.vue
 create mode 100644 nuxt/components/content/DocsTiles.vue

diff --git a/nuxt/assets/css/style.css b/nuxt/assets/css/style.css
index 91920a56de..03276abfb0 100644
--- a/nuxt/assets/css/style.css
+++ b/nuxt/assets/css/style.css
@@ -478,8 +478,13 @@ dl.message-properties > dd {
     @apply flex items-start justify-between gap-4 rounded-lg p-4 text-left;
 }
 
+/* The site-wide `code` rule draws a bordered, padded box, which inside the dark block reads
+   as a second box. Pages that sit in .nohero reset it already; docs pages do not. */
 .ff-command__text {
     @apply text-sm text-gray-100 whitespace-pre-wrap break-all;
+    border: 0;
+    border-radius: 0;
+    padding: 0;
 }
 
 .ff-command__copy {
diff --git a/nuxt/components/AlgoliaSearch.vue b/nuxt/components/AlgoliaSearch.vue
index 3a3d0d7f40..c4e4358ade 100644
--- a/nuxt/components/AlgoliaSearch.vue
+++ b/nuxt/components/AlgoliaSearch.vue
@@ -11,11 +11,14 @@ const props = withDefaults(defineProps<{
     detached?: boolean
     /** Open it with Cmd+K / Ctrl+K and from a `ff-docs-search:open` window event. Needs `detached`. */
     shortcut?: boolean
+    /** `lg` is the taller search field of a landing page's hero. Needs `detached`. */
+    size?: 'md' | 'lg'
 }>(), {
     placeholder: 'Search...',
     sourceId: 'content',
     detached: false,
     shortcut: false,
+    size: 'md',
 })
 
 const isMac = ref(true)
@@ -169,7 +172,7 @@ onMounted(async () => {
 </script>
 
 <template>
-  <div class="ff-algolia" :class="{ 'ff-algolia--detached': detached }">
+  <div class="ff-algolia" :class="{ 'ff-algolia--detached': detached, 'ff-algolia--lg': detached && size === 'lg' }">
     <div ref="searchContainer" id="algolia-search" :class="detached ? '' : 'border border-gray-200 rounded'"></div>
     <kbd v-if="detached && shortcut" class="ff-algolia__kbd" aria-hidden="true">{{ isMac ? '⌘' : 'Ctrl' }} K</kbd>
   </div>
@@ -199,6 +202,13 @@ onMounted(async () => {
     border-color: #a5b4fc;
 }
 
+.ff-algolia--lg :deep(#algolia-search .aa-DetachedSearchButton) {
+    height: 3rem;
+    padding-left: 0.75rem;
+    border-radius: 8px;
+    font-size: 1rem;
+}
+
 .ff-algolia__kbd {
     position: absolute;
     top: 50%;
diff --git a/nuxt/components/content/DocsHero.vue b/nuxt/components/content/DocsHero.vue
new file mode 100644
index 0000000000..0ac8754d69
--- /dev/null
+++ b/nuxt/components/content/DocsHero.vue
@@ -0,0 +1,220 @@
+<script setup lang="ts">
+// The opening of a docs landing page: a heading and a line from the default slot, the docs
+// search, a row of buttons from the `actions` slot (a markdown list of links) and, beside
+// them on wide screens, whatever the `aside` slot holds (the docs home puts its quick-start
+// tabs there).
+//
+//   ::docs-hero{eyebrow="FlowFuse Docs"}
+//   # Start building with FlowFuse
+//   One line.
+//
+//   #actions
+//   - [:icon{name="i-lucide-play"} A tutorial](/docs/tutorials/...)
+//
+//   #aside
+//   ...
+//   ::
+//
+// The search here is the page's only one with the Cmd+K shortcut: a landing page has no
+// sidebar, whose search would otherwise take it.
+defineProps<{
+    eyebrow?: string
+}>()
+</script>
+
+<template>
+  <section class="ff-docs-hero not-prose">
+    <div class="ff-docs-hero__main">
+      <p v-if="eyebrow" class="ff-docs-hero__eyebrow">{{ eyebrow }}</p>
+      <div class="ff-docs-hero__intro">
+        <slot />
+      </div>
+      <AlgoliaSearch
+        class="ff-docs-hero__search"
+        index-filter="category:docs"
+        placeholder="Search the docs"
+        source-id="docs"
+        size="lg"
+        detached
+        shortcut
+      />
+      <div v-if="$slots.actions" class="ff-docs-hero__actions">
+        <slot name="actions" />
+      </div>
+    </div>
+    <div v-if="$slots.aside" class="ff-docs-hero__aside">
+      <slot name="aside" />
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.ff-docs-hero {
+    display: grid;
+    gap: 2.5rem;
+    margin-top: 2.5rem;
+}
+
+@media (min-width: 1024px) {
+    .ff-docs-hero {
+        grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+        gap: 4rem;
+        align-items: center;
+    }
+}
+
+.ff-docs-hero__eyebrow {
+    margin: 0 0 1rem;
+    font-size: 0.875rem;
+    color: #6b7280;
+}
+
+.ff-docs-hero__intro :deep(h1) {
+    margin: 0;
+    font-size: 2.5rem;
+    line-height: 1.1;
+    font-weight: 400;
+    color: #111827;
+    letter-spacing: -0.01em;
+}
+
+@media (min-width: 640px) {
+    .ff-docs-hero__intro :deep(h1) {
+        font-size: 3.25rem;
+    }
+}
+
+/* The heading's own anchor link would underline it on hover; the title is not a link. */
+.ff-docs-hero__intro :deep(h1 a) {
+    color: inherit;
+    border: 0;
+    pointer-events: none;
+}
+
+.ff-docs-hero__intro :deep(p) {
+    margin: 1.5rem 0 0;
+    max-width: 32rem;
+    font-size: 1.125rem;
+    line-height: 1.6;
+    color: #4b5563;
+}
+
+.ff-docs-hero__search {
+    margin-top: 2rem;
+    max-width: 30rem;
+}
+
+.ff-docs-hero__actions {
+    margin-top: 1.25rem;
+}
+
+.ff-docs-hero__actions :deep(ul) {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.625rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.ff-docs-hero__actions :deep(li) {
+    margin: 0;
+    padding: 0;
+}
+
+.ff-docs-hero__actions :deep(a) {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    height: 2.5rem;
+    padding: 0 1rem;
+    border: 1px solid #d1d5db;
+    border-radius: 6px;
+    background: #fff;
+    color: #1f2937;
+    font-size: 0.9375rem;
+    font-weight: 500;
+    text-decoration: none;
+    transition: border-color 0.15s ease, background-color 0.15s ease;
+}
+
+.ff-docs-hero__actions :deep(a:hover) {
+    border-color: #a5b4fc;
+    background: #f5f7ff;
+}
+
+.ff-docs-hero__actions :deep(a:focus-visible) {
+    outline: 2px solid #4f46e5;
+    outline-offset: 2px;
+}
+
+.ff-docs-hero__actions :deep(a .iconify) {
+    width: 1.125rem;
+    height: 1.125rem;
+    color: #4b5563;
+}
+
+.ff-docs-hero__aside {
+    min-width: 0;
+    padding: 0.5rem 1.5rem 1.5rem;
+    border: 1px solid #e5e7eb;
+    border-radius: 12px;
+    background: #fff;
+    box-shadow: 0 1px 2px rgb(17 24 39 / 0.04), 0 8px 24px -8px rgb(17 24 39 / 0.08);
+}
+
+.ff-docs-hero__aside > :deep(:first-child) {
+    margin-top: 0;
+}
+
+/* Tabs as wide as their labels, never cut short: Nuxt UI's tabs share the row out equally
+   and truncate, which in a phone-width card leaves "Devic..." */
+.ff-docs-hero__aside :deep([role="tab"]) {
+    flex: 0 0 auto;
+}
+
+.ff-docs-hero__aside :deep([role="tab"] span) {
+    overflow: visible;
+    text-overflow: clip;
+}
+
+@media (max-width: 639px) {
+    .ff-docs-hero__aside {
+        padding: 0.25rem 1rem 1.25rem;
+    }
+
+    .ff-docs-hero__aside :deep([role="tab"]) {
+        padding-inline: 0.5rem;
+    }
+}
+
+/* Quick-start steps: a heading and a line each, close together. Nuxt UI wraps each step
+   heading's text in an anchor link, which the site's link colour would turn blue. */
+.ff-docs-hero__aside :deep(h4) {
+    margin: 1.5rem 0 0.25rem;
+    font-size: 1rem;
+    line-height: 1.75rem;
+    font-weight: 500;
+    color: #111827;
+}
+
+.ff-docs-hero__aside :deep(h4:first-child) {
+    margin-top: 0.5rem;
+}
+
+.ff-docs-hero__aside :deep(h4 > a) {
+    color: inherit;
+    text-decoration: none;
+}
+
+.ff-docs-hero__aside :deep(p) {
+    margin: 0.25rem 0 0.5rem;
+    font-size: 0.9375rem;
+    line-height: 1.55;
+    color: #4b5563;
+}
+
+.ff-docs-hero__aside :deep(.ff-command) {
+    margin: 0.75rem 0;
+}
+</style>
diff --git a/nuxt/components/content/DocsSection.vue b/nuxt/components/content/DocsSection.vue
new file mode 100644
index 0000000000..e84ad00c18
--- /dev/null
+++ b/nuxt/components/content/DocsSection.vue
@@ -0,0 +1,158 @@
+<script setup lang="ts">
+// One section of a docs landing page: a small eyebrow, a heading, a line saying what the
+// section is for (the first paragraph of the slot), then its cards or tiles. A contents
+// page reads as an overview this way rather than as a bare list of links.
+//
+//   ::docs-section{eyebrow="Platform" title="Choose how you run FlowFuse" cols="2"}
+//   One line.
+//
+//   :::card-group
+//   ...
+//   :::
+//   ::
+//
+// `cols` sets how many cards a card-group in the section shows side by side on wide
+// screens (2 by default). Links listed inside a card read as plain rows, not bullets.
+const props = withDefaults(defineProps<{
+    title: string
+    eyebrow?: string
+    id?: string
+    cols?: string | number
+}>(), {
+    cols: 2,
+})
+
+const anchor = computed(() => props.id || props.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, ''))
+</script>
+
+<template>
+  <section class="ff-docs-section not-prose">
+    <p v-if="eyebrow" class="ff-docs-section__eyebrow">{{ eyebrow }}</p>
+    <h2 :id="anchor" class="ff-docs-section__title">{{ title }}</h2>
+    <div class="ff-docs-section__body" :class="`ff-docs-section__body--cols-${cols}`">
+      <slot />
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.ff-docs-section {
+    margin-top: 5.5rem;
+}
+
+.ff-docs-section__eyebrow {
+    margin: 0 0 0.5rem;
+    font-size: 0.875rem;
+    color: #6b7280;
+}
+
+.ff-docs-section__title {
+    margin: 0;
+    font-size: 1.875rem;
+    line-height: 1.2;
+    font-weight: 400;
+    color: #111827;
+    scroll-margin-top: calc(var(--ff-header-height, 56px) + 1.5rem);
+}
+
+.ff-docs-section__body > :deep(p:first-child) {
+    margin: 0.625rem 0 2rem;
+    max-width: 42rem;
+    font-size: 1.0625rem;
+    line-height: 1.6;
+    color: #4b5563;
+}
+
+.ff-docs-section__body > :deep(.grid) {
+    margin: 0;
+    gap: 1rem;
+}
+
+/* Without a lead line the cards would sit right under the heading. */
+.ff-docs-section__body > :deep(.grid:first-child) {
+    margin-top: 2rem;
+}
+
+/* Cards hold a line or two, not an article: tighter than Nuxt UI's default card. */
+.ff-docs-section__body > :deep(.grid > div) {
+    padding: 1.25rem;
+}
+
+.ff-docs-section__body > :deep(.grid > div p) {
+    margin: 0;
+    font-size: 0.9375rem;
+    line-height: 1.5;
+}
+
+/* The numbered stages of a ::steps journey. Nuxt UI wraps each step heading's text in an
+   anchor link, which the site's link colour would turn blue. */
+.ff-docs-section__body :deep(h3) {
+    margin: 2.75rem 0 0.25rem;
+    font-size: 1.25rem;
+    line-height: 1.75rem;
+    font-weight: 500;
+    color: #111827;
+}
+
+.ff-docs-section__body :deep(h3:first-child) {
+    margin-top: 0;
+}
+
+.ff-docs-section__body :deep(h3 > a) {
+    color: inherit;
+    text-decoration: none;
+}
+
+.ff-docs-section__body :deep(h3 + p) {
+    margin: 0.25rem 0 1rem;
+    color: #4b5563;
+}
+
+@media (min-width: 1024px) {
+    .ff-docs-section__body--cols-3 > :deep(.grid) {
+        grid-template-columns: repeat(3, minmax(0, 1fr));
+    }
+
+    .ff-docs-section__body--cols-4 > :deep(.grid) {
+        grid-template-columns: repeat(4, minmax(0, 1fr));
+    }
+}
+
+/* A card's list of links: plain rows with their icons, the way Claude's platform cards
+   list Quickstart / API reference / SDKs. */
+.ff-docs-section__body :deep(.grid ul) {
+    margin: 1rem 0 0;
+    padding: 0;
+    list-style: none;
+}
+
+.ff-docs-section__body :deep(.grid li) {
+    margin: 0;
+    padding: 0.3rem 0;
+}
+
+.ff-docs-section__body :deep(.grid li a) {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    color: #1f2937;
+    font-weight: 500;
+    border: 0;
+    text-decoration: none;
+}
+
+.ff-docs-section__body :deep(.grid li a:hover) {
+    color: #4f46e5;
+}
+
+.ff-docs-section__body :deep(.grid li a .iconify) {
+    width: 1rem;
+    height: 1rem;
+    color: #6b7280;
+}
+
+/* Anything that follows the card-group, such as a row of tiles, keeps its distance. */
+.ff-docs-section__body > :deep(.grid + *) {
+    margin-top: 1rem;
+}
+</style>
diff --git a/nuxt/components/content/DocsTiles.vue b/nuxt/components/content/DocsTiles.vue
new file mode 100644
index 0000000000..69fe4f70ed
--- /dev/null
+++ b/nuxt/components/content/DocsTiles.vue
@@ -0,0 +1,101 @@
+<script setup lang="ts">
+// A markdown list of links shown as a grid of tiles, each one clickable across its whole
+// area. Start a link's text with an icon to give its tile one:
+//
+//   ::docs-tiles{cols="3"}
+//   - [:icon{name="i-lucide-history"} Snapshots](/docs/user/snapshots/)
+//   - [:icon{name="i-lucide-git-branch"} DevOps pipelines](/docs/user/devops-pipelines/)
+//   ::
+//
+// The links stay ordinary markdown links, so the flowfuse docs link check still covers them.
+withDefaults(defineProps<{
+    cols?: string | number
+}>(), {
+    cols: 3,
+})
+</script>
+
+<template>
+  <div class="ff-docs-tiles not-prose" :class="`ff-docs-tiles--cols-${cols}`">
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+.ff-docs-tiles :deep(ul) {
+    display: grid;
+    grid-template-columns: minmax(0, 1fr);
+    gap: 0.75rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+@media (min-width: 640px) {
+    .ff-docs-tiles :deep(ul) {
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+    }
+}
+
+@media (min-width: 1024px) {
+    .ff-docs-tiles--cols-3 :deep(ul) {
+        grid-template-columns: repeat(3, minmax(0, 1fr));
+    }
+
+    .ff-docs-tiles--cols-4 :deep(ul) {
+        grid-template-columns: repeat(4, minmax(0, 1fr));
+    }
+}
+
+.ff-docs-tiles :deep(li) {
+    position: relative;
+    margin: 0;
+    padding: 0;
+    border: 1px solid #e5e7eb;
+    border-radius: 10px;
+    background: #fff;
+    transition: border-color 0.15s ease, background-color 0.15s ease;
+}
+
+.ff-docs-tiles :deep(li:hover) {
+    border-color: #a5b4fc;
+    background: #f5f7ff;
+}
+
+.ff-docs-tiles :deep(li:has(a:focus-visible)) {
+    outline: 2px solid #4f46e5;
+    outline-offset: 2px;
+}
+
+.ff-docs-tiles :deep(li a) {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding: 0.875rem 1rem;
+    color: #1f2937;
+    font-size: 0.9375rem;
+    font-weight: 500;
+    line-height: 1.35;
+    border: 0;
+    text-decoration: none;
+}
+
+.ff-docs-tiles :deep(li a:focus-visible) {
+    outline: none;
+}
+
+/* The link covers its whole tile. */
+.ff-docs-tiles :deep(li a::after) {
+    content: '';
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+}
+
+.ff-docs-tiles :deep(li a .iconify) {
+    width: 1.125rem;
+    height: 1.125rem;
+    flex-shrink: 0;
+    color: #6b7280;
+}
+</style>
diff --git a/nuxt/content.config.ts b/nuxt/content.config.ts
index d4475e9036..28afc5488c 100644
--- a/nuxt/content.config.ts
+++ b/nuxt/content.config.ts
@@ -57,6 +57,9 @@ export default defineContentConfig({
                 structuredData: z.object({
                     description: z.string().optional(),
                 }).optional(),
+                // A contents page that lays itself out (the docs home): no sidebar, no
+                // table of contents, the full page width. Read by pages/docs/[...slug].vue.
+                landing: z.boolean().optional(),
                 // No `sitemap` schema field here on purpose - @nuxtjs/sitemap's own
                 // @nuxt/content integration only accepts *plain* onUrl/filter functions
                 // (it re-splices their source text into a generated file with no closure
diff --git a/nuxt/pages/docs/[...slug].vue b/nuxt/pages/docs/[...slug].vue
index 516318c4a4..8a1d167ef8 100644
--- a/nuxt/pages/docs/[...slug].vue
+++ b/nuxt/pages/docs/[...slug].vue
@@ -29,6 +29,10 @@ if (!page.value) {
 // Empty on most docs pages: only the ones a catalog feature names as its docsLink get badges.
 const plans = useDocsPlans(contentPath)
 
+// A contents page such as the docs home lays itself out from its own components, so it
+// gets the full width: no sidebar, no table of contents, no previous and next cards.
+const isLanding = computed(() => (page.value as { landing?: boolean } | null)?.landing === true)
+
 // /docs is assembled from two repos, so "Edit this page" has to point at whichever one
 // owns the page. Guides overlaid from this repo carry a ready-made `editUrl` (stamped by
 // nuxt/lib/guides-sync.mjs); everything else came from FlowFuse/flowfuse and is addressed
@@ -108,7 +112,14 @@ const surround = computed(() => {
 </script>
 
 <template>
-  <div class="w-full pl-6">
+  <!-- Not wrapped in .prose: every block on a landing page is a component that styles
+       itself, and Tailwind Typography's unlayered rules would fight them. -->
+  <div v-if="isLanding" class="ff-docs-landing w-full max-w-6xl mx-auto px-6 lg:px-10 pt-8 pb-24 text-left">
+    <Breadcrumbs :items="breadcrumbItems" />
+    <ContentRenderer v-if="page" :value="page" />
+  </div>
+
+  <div v-else class="w-full pl-6">
     <div class="handbook ff-prose text-left pb-24 m-auto">
 
       <!-- Left navigation -->

From d5efdec136e59e44f88ff618db0f1e360abd63e7 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 15:18:37 +0200
Subject: [PATCH 15/31] docs: choices that explain each way in, and a
 two-column block

docs-choices and docs-choice list the ways into FlowFuse, one open at a time: each opens
to a line or two on what the option is, then its next step as a button and a guide as a
link. They route to the pages that already walk through setup (the Device Agent install,
the AI agent picker) rather than repeating them. Each choice is a native details element
sharing one name, so the browser keeps a single one open with no script.

docs-columns sets two blocks side by side, two thirds and one third, stacked on phones.
---
 nuxt/components/content/DocsChoice.vue  | 144 ++++++++++++++++++++++++
 nuxt/components/content/DocsChoices.vue |  45 ++++++++
 nuxt/components/content/DocsColumns.vue |  39 +++++++
 3 files changed, 228 insertions(+)
 create mode 100644 nuxt/components/content/DocsChoice.vue
 create mode 100644 nuxt/components/content/DocsChoices.vue
 create mode 100644 nuxt/components/content/DocsColumns.vue

diff --git a/nuxt/components/content/DocsChoice.vue b/nuxt/components/content/DocsChoice.vue
new file mode 100644
index 0000000000..1a308d7e64
--- /dev/null
+++ b/nuxt/components/content/DocsChoice.vue
@@ -0,0 +1,144 @@
+<script setup lang="ts">
+// One option in a ::docs-choices list: a row that opens to a short explanation, then its
+// links. The first link is the option's next step and reads as a button; any after it
+// read as plain links.
+defineProps<{
+    label: string
+    icon?: string
+    open?: boolean
+}>()
+
+const name = inject<string>('ff-docs-choices-name', 'ff-docs-choices')
+</script>
+
+<template>
+  <details class="ff-docs-choice" :name="name" :open="open || undefined">
+    <summary class="ff-docs-choice__summary">
+      <UIcon v-if="icon" :name="icon" class="ff-docs-choice__icon" aria-hidden="true" />
+      <span class="ff-docs-choice__label">{{ label }}</span>
+      <UIcon name="i-lucide-chevron-down" class="ff-docs-choice__chevron" aria-hidden="true" />
+    </summary>
+    <div class="ff-docs-choice__body">
+      <slot />
+    </div>
+  </details>
+</template>
+
+<style scoped>
+.ff-docs-choice {
+    border-bottom: 1px solid #e5e7eb;
+}
+
+.ff-docs-choice__summary {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding: 0.875rem 0.25rem;
+    list-style: none;
+    cursor: pointer;
+    color: #1f2937;
+    font-weight: 500;
+}
+
+.ff-docs-choice__summary::-webkit-details-marker {
+    display: none;
+}
+
+.ff-docs-choice__summary:hover .ff-docs-choice__label {
+    color: #4f46e5;
+}
+
+.ff-docs-choice__summary:focus-visible {
+    outline: 2px solid #4f46e5;
+    outline-offset: 2px;
+    border-radius: 6px;
+}
+
+.ff-docs-choice[open] .ff-docs-choice__summary {
+    color: #111827;
+}
+
+.ff-docs-choice__icon {
+    width: 1.25rem;
+    height: 1.25rem;
+    flex-shrink: 0;
+    color: #4f46e5;
+}
+
+.ff-docs-choice__label {
+    flex: 1;
+    min-width: 0;
+}
+
+.ff-docs-choice__chevron {
+    width: 1rem;
+    height: 1rem;
+    flex-shrink: 0;
+    color: #9ca3af;
+    transition: transform 0.2s ease;
+}
+
+.ff-docs-choice[open] .ff-docs-choice__chevron {
+    transform: rotate(180deg);
+}
+
+.ff-docs-choice__body {
+    padding: 0 0.25rem 1.125rem 2.25rem;
+}
+
+.ff-docs-choice__body :deep(p) {
+    margin: 0 0 0.875rem;
+    font-size: 0.9375rem;
+    line-height: 1.55;
+    color: #4b5563;
+}
+
+.ff-docs-choice__body :deep(ul) {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.5rem 1.25rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+}
+
+.ff-docs-choice__body :deep(li) {
+    margin: 0;
+    padding: 0;
+}
+
+.ff-docs-choice__body :deep(li a) {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.375rem;
+    font-size: 0.9375rem;
+    font-weight: 500;
+    color: #4f46e5;
+    border: 0;
+    text-decoration: none;
+}
+
+.ff-docs-choice__body :deep(li a:hover) {
+    text-decoration: underline;
+}
+
+/* The option's next step. */
+.ff-docs-choice__body :deep(li:first-child a) {
+    height: 2.25rem;
+    padding: 0 0.875rem;
+    border-radius: 6px;
+    background: #4f46e5;
+    color: #fff;
+}
+
+.ff-docs-choice__body :deep(li:first-child a:hover) {
+    background: #4338ca;
+    text-decoration: none;
+}
+
+.ff-docs-choice__body :deep(li a:focus-visible) {
+    outline: 2px solid #4f46e5;
+    outline-offset: 2px;
+}
+</style>
diff --git a/nuxt/components/content/DocsChoices.vue b/nuxt/components/content/DocsChoices.vue
new file mode 100644
index 0000000000..56c72c98dc
--- /dev/null
+++ b/nuxt/components/content/DocsChoices.vue
@@ -0,0 +1,45 @@
+<script setup lang="ts">
+// A short list of ways in, one open at a time: each ::docs-choice explains one option in a
+// sentence or two and links onward. It explains and routes rather than walking through
+// setup, because the pages it links to (the Device Agent install, the AI agent picker)
+// already do that better.
+//
+//   ::docs-choices{title="Where do you want to start?"}
+//   :::docs-choice{label="FlowFuse Cloud" icon="i-lucide-cloud" open}
+//   What it is, in a line or two.
+//
+//   - [The first thing to do](https://...)
+//   - [The guide](/docs/...)
+//   :::
+//   ::
+//
+// Each choice is a native <details>; sharing one name makes the browser keep a single one
+// open, with no script involved.
+defineProps<{
+    title?: string
+}>()
+
+provide('ff-docs-choices-name', useId())
+</script>
+
+<template>
+  <div class="ff-docs-choices not-prose">
+    <p v-if="title" class="ff-docs-choices__title">{{ title }}</p>
+    <div class="ff-docs-choices__list">
+      <slot />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.ff-docs-choices__title {
+    margin: 0 0 0.75rem;
+    font-size: 1rem;
+    font-weight: 500;
+    color: #111827;
+}
+
+.ff-docs-choices__list {
+    border-top: 1px solid #e5e7eb;
+}
+</style>
diff --git a/nuxt/components/content/DocsColumns.vue b/nuxt/components/content/DocsColumns.vue
new file mode 100644
index 0000000000..9d9edf18b8
--- /dev/null
+++ b/nuxt/components/content/DocsColumns.vue
@@ -0,0 +1,39 @@
+<script setup lang="ts">
+// Two blocks side by side on wide screens, the first twice as wide as the second, stacked
+// on narrow ones. The docs home uses it to put the Expert question box next to the card
+// that leads to human support, so the section spans the page.
+//
+//   ::docs-columns
+//   :::ff-expert-ask
+//   :::
+//
+//   :::card{title="..." to="..."}
+//   ...
+//   :::
+//   ::
+</script>
+
+<template>
+  <div class="ff-docs-columns not-prose">
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+.ff-docs-columns {
+    display: grid;
+    gap: 1.5rem;
+}
+
+@media (min-width: 1024px) {
+    .ff-docs-columns {
+        grid-template-columns: minmax(0, 2fr) minmax(0, 1fr);
+        align-items: start;
+    }
+}
+
+.ff-docs-columns > :deep(*) {
+    margin-top: 0;
+    margin-bottom: 0;
+}
+</style>

From 3e5587a7e56dbdcda125f218547567a6ae52045d Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 15:31:07 +0200
Subject: [PATCH 16/31] docs: a card leads somewhere through a plain markdown
 link

A card on a landing page that opens with a paragraph holding only a link takes that link
as its title, and the link covers the whole card with a hover state. This replaces Nuxt
UI's to attribute, whose URL the flowfuse docs link check misreads (it autolinks the text
and keeps the closing quote and brace), and which left internal card links unchecked.
A #title slot cannot stand in for it: inside these wrapper components MDC attaches a
nested card's #title to the wrapper and swallows the card's closing fence.
---
 nuxt/components/content/DocsSection.vue | 57 +++++++++++++++++++++++++
 1 file changed, 57 insertions(+)

diff --git a/nuxt/components/content/DocsSection.vue b/nuxt/components/content/DocsSection.vue
index e84ad00c18..8d034fac38 100644
--- a/nuxt/components/content/DocsSection.vue
+++ b/nuxt/components/content/DocsSection.vue
@@ -84,6 +84,63 @@ const anchor = computed(() => props.id || props.title.toLowerCase().replace(/[^a
     line-height: 1.5;
 }
 
+/* A card that leads somewhere opens with a paragraph holding only a link: that link is the
+   card's title and covers the whole card.
+
+     ::::card{icon="i-lucide-life-buoy"}
+     [Troubleshooting](/docs/troubleshooting/)
+
+     Every troubleshooting guide in one place.
+     ::::
+
+   Not Nuxt UI's `to` attribute, because the flowfuse docs link check reads markdown links
+   only and misreads a URL inside an attribute. Not a #title slot either: inside these
+   wrapper components MDC attaches a nested card's #title to the wrapper instead. */
+.ff-docs-section__body :deep(.group:has(> div > p:first-child > a:only-child)) {
+    transition: border-color 0.15s ease, background-color 0.15s ease;
+}
+
+.ff-docs-section__body :deep(.group:has(> div > p:first-child > a:only-child):hover) {
+    border-color: #a5b4fc;
+    background: #f5f7ff;
+}
+
+.ff-docs-section__body :deep(.group:has(> div > p:first-child > a:only-child:focus-visible)) {
+    outline: 2px solid #4f46e5;
+    outline-offset: 2px;
+}
+
+.ff-docs-section__body :deep(.group > div > p:first-child:has(> a:only-child)) {
+    margin: 0 0 0.25rem;
+}
+
+.ff-docs-section__body :deep(.group > div > p:first-child > a:only-child) {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.375rem;
+    color: #111827;
+    font-size: 1rem;
+    font-weight: 600;
+    border: 0;
+    text-decoration: none;
+}
+
+.ff-docs-section__body :deep(.group > div > p:first-child > a:only-child:focus-visible) {
+    outline: none;
+}
+
+.ff-docs-section__body :deep(.group > div > p:first-child > a:only-child::after) {
+    content: '';
+    position: absolute;
+    inset: 0;
+}
+
+.ff-docs-section__body :deep(.group > div > p:first-child > a:only-child .iconify) {
+    width: 0.875rem;
+    height: 0.875rem;
+    color: #9ca3af;
+}
+
 /* The numbered stages of a ::steps journey. Nuxt UI wraps each step heading's text in an
    anchor link, which the site's link colour would turn blue. */
 .ff-docs-section__body :deep(h3) {

From 6b53ee24bb76f04d6b14efea350c8f6e9bbf5b61 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 15:54:56 +0200
Subject: [PATCH 17/31] docs: the Expert box and the card beside it are the
 same height

FfExpertAsk lays out its box and its prompts as a two-row grid, and the box fills the
height its row gives it. DocsColumns hands its first block both rows through subgrid, so
that block's box shares the top row with the second column and the two stretch to one
height, with the prompts below. The row gaps match; a subgrid with a different gap spreads
the difference into its rows and left the box 4px taller.
---
 nuxt/components/content/DocsColumns.vue | 17 ++++++++++-
 nuxt/components/content/FfExpertAsk.vue | 40 +++++++++++++++++++++----
 2 files changed, 51 insertions(+), 6 deletions(-)

diff --git a/nuxt/components/content/DocsColumns.vue b/nuxt/components/content/DocsColumns.vue
index 9d9edf18b8..56fefc018a 100644
--- a/nuxt/components/content/DocsColumns.vue
+++ b/nuxt/components/content/DocsColumns.vue
@@ -26,9 +26,24 @@
 }
 
 @media (min-width: 1024px) {
+    /* The row gap matches FfExpertAsk's own: a subgrid with a different gap spreads the
+       difference into its rows, and the box would stand 4px taller than the card. */
     .ff-docs-columns {
         grid-template-columns: minmax(0, 2fr) minmax(0, 1fr);
-        align-items: start;
+        grid-template-rows: auto auto;
+        gap: 1rem 1.5rem;
+    }
+
+    /* The first block spans both rows and hands them to its own children (subgrid): its
+       first child shares the top row with the second column, so the two boxes are the same
+       height, and whatever follows it (the Expert box's prompts) sits in the row below. */
+    .ff-docs-columns > :deep(:first-child) {
+        grid-row: 1 / span 2;
+        grid-template-rows: subgrid;
+    }
+
+    .ff-docs-columns > :deep(:not(:first-child)) {
+        grid-row: 1;
     }
 }
 
diff --git a/nuxt/components/content/FfExpertAsk.vue b/nuxt/components/content/FfExpertAsk.vue
index 6c08eb5692..b8646a9867 100644
--- a/nuxt/components/content/FfExpertAsk.vue
+++ b/nuxt/components/content/FfExpertAsk.vue
@@ -54,16 +54,16 @@ function track () {
 
 <template>
   <div ref="root" class="ff-expert-ask not-prose mt-6 max-w-4xl">
-    <div class="ai-chat-box">
-      <div class="textarea-wrapper ff-expert-ask__card relative mb-4 rounded-lg overflow-hidden">
+    <div class="ai-chat-box ff-expert-ask__box">
+      <div class="textarea-wrapper ff-expert-ask__card relative rounded-lg overflow-hidden">
         <div class="ff-expert-ask__brand">
           <DocsExpertBrand uid="expert-ask" />
         </div>
-        <div class="relative h-32 p-4 pb-12">
+        <div class="ff-expert-ask__input relative p-4 pb-12">
           <textarea
             data-ff-expert-input
             :placeholder="placeholder"
-            class="w-full h-full bg-transparent border-0 focus:outline-none text-gray-600 placeholder-gray-400 resize-none"
+            class="w-full bg-transparent border-0 focus:outline-none text-gray-600 placeholder-gray-400 resize-none"
             aria-label="Ask FlowFuse Expert"
           />
           <div class="absolute bottom-3 left-4 text-[10px] font-light text-gray-500 pr-36 line-clamp-2">
@@ -81,7 +81,7 @@ function track () {
       </div>
     </div>
 
-    <div class="flex flex-wrap gap-2 mb-3">
+    <div class="flex flex-wrap gap-2">
       <button
         v-for="p in prompts"
         :key="p.title"
@@ -97,6 +97,36 @@ function track () {
 </template>
 
 <style scoped>
+/* Two rows, the box and its prompts. A grid rather than margins so a parent can share the
+   rows through subgrid (DocsColumns does, to line the box up with the card beside it), and
+   the box fills whatever height its row gives it. */
+.ff-expert-ask {
+    display: grid;
+    grid-template-rows: auto auto;
+    row-gap: 1rem;
+}
+
+.ff-expert-ask__box {
+    display: flex;
+}
+
+.ff-expert-ask__card {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+}
+
+.ff-expert-ask__input {
+    flex: 1;
+    display: flex;
+    flex-direction: column;
+    min-height: 8rem;
+}
+
+.ff-expert-ask__input textarea {
+    flex: 1;
+}
+
 /* Same padding as the modal header, so the brand flies between matching spots. */
 .ff-expert-ask__brand {
     padding: 0.75rem 1rem;

From fde86ed2bc57a4bca2ca6e5863c14858cf0281ec Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 16:16:31 +0200
Subject: [PATCH 18/31] docs: no breadcrumb on the docs home

The trail on /docs would be the single word Docs, so the home page leaves it out; every
other docs page, landing or not, keeps its breadcrumb.
---
 nuxt/pages/docs/[...slug].vue | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/nuxt/pages/docs/[...slug].vue b/nuxt/pages/docs/[...slug].vue
index 8a1d167ef8..9627f6e168 100644
--- a/nuxt/pages/docs/[...slug].vue
+++ b/nuxt/pages/docs/[...slug].vue
@@ -115,7 +115,8 @@ const surround = computed(() => {
   <!-- Not wrapped in .prose: every block on a landing page is a component that styles
        itself, and Tailwind Typography's unlayered rules would fight them. -->
   <div v-if="isLanding" class="ff-docs-landing w-full max-w-6xl mx-auto px-6 lg:px-10 pt-8 pb-24 text-left">
-    <Breadcrumbs :items="breadcrumbItems" />
+    <!-- The docs home has no trail to show: it would be the single word Docs. -->
+    <Breadcrumbs v-if="slugParts.length" :items="breadcrumbItems" />
     <ContentRenderer v-if="page" :value="page" />
   </div>
 
@@ -131,7 +132,6 @@ const surround = computed(() => {
           <!-- Breadcrumbs -->
           <div class="font-medium pb-1 flex flex-col gap-1">
             <div class="md:flex-1">
-              <!-- On /docs itself this is the one unlinked "Docs" crumb, so every page opens the same way. -->
               <Breadcrumbs :items="breadcrumbItems" />
             </div>
           </div>

From 69ffd954c075c4104fade91add615ff27a2c8a2f Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 16:16:36 +0200
Subject: [PATCH 19/31] docs search: the field is there from the first paint

Autocomplete loads from a CDN after the page renders, so a detached search showed nothing
but its Cmd+K hint until then; on the docs home, where the field leads the hero, that read
as a missing search. A stand-in button of the same size now renders with the page and
gives way once autocomplete mounts, with no layout shift. A click or Cmd+K before then
opens the dialog as soon as it can; the shortcut listeners are set up right away.
---
 nuxt/components/AlgoliaSearch.vue | 67 +++++++++++++++++++++++++++++--
 1 file changed, 63 insertions(+), 4 deletions(-)

diff --git a/nuxt/components/AlgoliaSearch.vue b/nuxt/components/AlgoliaSearch.vue
index c4e4358ade..53198724c4 100644
--- a/nuxt/components/AlgoliaSearch.vue
+++ b/nuxt/components/AlgoliaSearch.vue
@@ -23,7 +23,18 @@ const props = withDefaults(defineProps<{
 
 const isMac = ref(true)
 
+// Autocomplete arrives from a CDN after the page has rendered. Until it has mounted, a
+// detached search shows a stand-in button of the same size, so the field is there from the
+// first paint instead of popping in; a click or Cmd+K before then opens the dialog as soon
+// as it can.
+const ready = ref(false)
+let openWhenReady = false
+
 function openDialog () {
+    if (!ready.value) {
+        openWhenReady = true
+        return
+    }
     searchContainer.value?.querySelector<HTMLElement>('.aa-DetachedSearchButton')?.click()
 }
 
@@ -42,6 +53,12 @@ onBeforeUnmount(() => {
 const searchContainer = ref<HTMLElement>()
 
 onMounted(async () => {
+    if (props.detached && props.shortcut) {
+        isMac.value = /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent)
+        window.addEventListener('keydown', onKeydown)
+        window.addEventListener('ff-docs-search:open', openDialog)
+    }
+
     const loadScript = (src: string, integrity?: string): Promise<void> =>
         new Promise((resolve, reject) => {
             if (document.querySelector(`script[src="${src}"]`)) { resolve(); return }
@@ -163,10 +180,14 @@ onMounted(async () => {
         }
     })
 
-    if (props.detached && props.shortcut) {
-        isMac.value = /Mac|iPhone|iPad/.test(navigator.platform || navigator.userAgent)
-        window.addEventListener('keydown', onKeydown)
-        window.addEventListener('ff-docs-search:open', openDialog)
+    ready.value = true
+    if (openWhenReady) {
+        openWhenReady = false
+        // Autocomplete renders its button a frame or two after it is set up.
+        for (let i = 0; i < 30 && !searchContainer.value?.querySelector('.aa-DetachedSearchButton'); i++) {
+            await new Promise(resolve => requestAnimationFrame(resolve))
+        }
+        openDialog()
     }
 })
 </script>
@@ -174,6 +195,12 @@ onMounted(async () => {
 <template>
   <div class="ff-algolia" :class="{ 'ff-algolia--detached': detached, 'ff-algolia--lg': detached && size === 'lg' }">
     <div ref="searchContainer" id="algolia-search" :class="detached ? '' : 'border border-gray-200 rounded'"></div>
+    <button v-if="detached && !ready" type="button" class="ff-algolia__standin" @click="openDialog">
+      <svg class="ff-algolia__standin-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true">
+        <circle cx="11" cy="11" r="7" /><path d="m20 20-3.5-3.5" />
+      </svg>
+      <span>{{ placeholder }}</span>
+    </button>
     <kbd v-if="detached && shortcut" class="ff-algolia__kbd" aria-hidden="true">{{ isMac ? '⌘' : 'Ctrl' }} K</kbd>
   </div>
 </template>
@@ -202,6 +229,38 @@ onMounted(async () => {
     border-color: #a5b4fc;
 }
 
+/* Stands in for the search button until autocomplete has mounted (see `ready`). */
+.ff-algolia__standin {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    width: 100%;
+    height: 2.5rem;
+    padding: 0 4rem 0 0.75rem;
+    border: 1px solid #d1d5db;
+    border-radius: 6px;
+    background: #fff;
+    font-size: 0.875rem;
+    color: #6b7280;
+    text-align: left;
+    cursor: pointer;
+}
+
+.ff-algolia__standin-icon {
+    width: 1rem;
+    height: 1rem;
+    color: #777;
+    flex-shrink: 0;
+}
+
+.ff-algolia--lg .ff-algolia__standin {
+    height: 3rem;
+    padding-left: 1.25rem;
+    gap: 0.75rem;
+    border-radius: 8px;
+    font-size: 1rem;
+}
+
 .ff-algolia--lg :deep(#algolia-search .aa-DetachedSearchButton) {
     height: 3rem;
     padding-left: 0.75rem;

From 4512174a6e28f2a9fd748b55b614197ab2c3ddbc Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 16:47:33 +0200
Subject: [PATCH 20/31] docs: the Expert box without prompt pills, and one card
 style throughout

FfExpertAsk drops its six prompt pills, so it is the question box alone and simply fills
the height it is given; DocsColumns no longer needs a subgrid to line it up with the card
beside it, plain grid stretching does. A card beside the Expert box now gets the same
compact padding and type as cards in a card-group, and cards that follow the two-column
block keep their distance. docs-choice states the rule for its links: one main call to
action and at most one secondary action.
---
 nuxt/components/content/DocsChoice.vue  |  5 ++--
 nuxt/components/content/DocsColumns.vue | 18 ++----------
 nuxt/components/content/DocsSection.vue | 15 ++++++++--
 nuxt/components/content/FfExpertAsk.vue | 37 ++++---------------------
 4 files changed, 22 insertions(+), 53 deletions(-)

diff --git a/nuxt/components/content/DocsChoice.vue b/nuxt/components/content/DocsChoice.vue
index 1a308d7e64..51126ababf 100644
--- a/nuxt/components/content/DocsChoice.vue
+++ b/nuxt/components/content/DocsChoice.vue
@@ -1,7 +1,8 @@
 <script setup lang="ts">
 // One option in a ::docs-choices list: a row that opens to a short explanation, then its
-// links. The first link is the option's next step and reads as a button; any after it
-// read as plain links.
+// links. Two at most: the first is the option's main call to action and reads as a button,
+// the second a secondary action that reads as a plain link. A third choice would make the
+// reader weigh options inside an option.
 defineProps<{
     label: string
     icon?: string
diff --git a/nuxt/components/content/DocsColumns.vue b/nuxt/components/content/DocsColumns.vue
index 56fefc018a..24035a6a35 100644
--- a/nuxt/components/content/DocsColumns.vue
+++ b/nuxt/components/content/DocsColumns.vue
@@ -25,25 +25,11 @@
     gap: 1.5rem;
 }
 
+/* The two blocks stretch to one height (grid items do by default), so a box beside a
+   taller card grows to match it. */
 @media (min-width: 1024px) {
-    /* The row gap matches FfExpertAsk's own: a subgrid with a different gap spreads the
-       difference into its rows, and the box would stand 4px taller than the card. */
     .ff-docs-columns {
         grid-template-columns: minmax(0, 2fr) minmax(0, 1fr);
-        grid-template-rows: auto auto;
-        gap: 1rem 1.5rem;
-    }
-
-    /* The first block spans both rows and hands them to its own children (subgrid): its
-       first child shares the top row with the second column, so the two boxes are the same
-       height, and whatever follows it (the Expert box's prompts) sits in the row below. */
-    .ff-docs-columns > :deep(:first-child) {
-        grid-row: 1 / span 2;
-        grid-template-rows: subgrid;
-    }
-
-    .ff-docs-columns > :deep(:not(:first-child)) {
-        grid-row: 1;
     }
 }
 
diff --git a/nuxt/components/content/DocsSection.vue b/nuxt/components/content/DocsSection.vue
index 8d034fac38..2160970f58 100644
--- a/nuxt/components/content/DocsSection.vue
+++ b/nuxt/components/content/DocsSection.vue
@@ -68,17 +68,26 @@ const anchor = computed(() => props.id || props.title.toLowerCase().replace(/[^a
     gap: 1rem;
 }
 
+/* Cards that follow a two-column block (the Expert box and its neighbour) keep their
+   distance from it. */
+.ff-docs-section__body > :deep(.ff-docs-columns + .grid) {
+    margin-top: 1.5rem;
+}
+
 /* Without a lead line the cards would sit right under the heading. */
 .ff-docs-section__body > :deep(.grid:first-child) {
     margin-top: 2rem;
 }
 
-/* Cards hold a line or two, not an article: tighter than Nuxt UI's default card. */
-.ff-docs-section__body > :deep(.grid > div) {
+/* Cards hold a line or two, not an article: tighter than Nuxt UI's default card. The same
+   for a card in a card-group and one beside the Expert box in docs-columns. */
+.ff-docs-section__body > :deep(.grid > div),
+.ff-docs-section__body > :deep(.ff-docs-columns > .group) {
     padding: 1.25rem;
 }
 
-.ff-docs-section__body > :deep(.grid > div p) {
+.ff-docs-section__body > :deep(.grid > div p),
+.ff-docs-section__body > :deep(.ff-docs-columns > .group p) {
     margin: 0;
     font-size: 0.9375rem;
     line-height: 1.5;
diff --git a/nuxt/components/content/FfExpertAsk.vue b/nuxt/components/content/FfExpertAsk.vue
index b8646a9867..4b38666d3c 100644
--- a/nuxt/components/content/FfExpertAsk.vue
+++ b/nuxt/components/content/FfExpertAsk.vue
@@ -3,9 +3,8 @@
 //
 // The conversation itself is src/js/ai-expert-modal.js, the script the old /ai/ page used,
 // driving the modal that DocsExpertHost renders in the layout. The script listens for the
-// #tell-me-how-btn button and for .prompt-pill clicks, and morphs this card (the
-// .textarea-wrapper holding the data-ff-expert-input textarea) into the modal. Keep those
-// hooks as they are.
+// #tell-me-how-btn button and morphs this card (the .textarea-wrapper holding the
+// data-ff-expert-input textarea) into the modal. Keep those hooks as they are.
 //
 // Usage from markdown:
 //   ::ff-expert-ask
@@ -20,16 +19,6 @@ const props = withDefaults(defineProps<{
     position: 'docs-home',
 })
 
-// Support questions, the kind a reader brings to the documentation.
-const prompts = [
-    { title: 'My instance will not start', prompt: 'My FlowFuse instance will not start, or keeps crashing. How do I find out why, and how do I recover it?' },
-    { title: 'Connect a remote instance', prompt: 'How do I install the FlowFuse Device Agent and connect a remote instance to my team?' },
-    { title: 'Remote instance shows offline', prompt: 'My Device Agent is installed, but the remote instance shows as offline in FlowFuse. How do I troubleshoot it?' },
-    { title: 'Move flows to production', prompt: 'How do I promote flows from a development instance to production with snapshots and a DevOps pipeline?' },
-    { title: 'Roll back to a snapshot', prompt: 'How do I roll an instance back to an earlier snapshot?' },
-    { title: 'Set environment variables', prompt: 'How do I set environment variables on an instance, and how do my flows read them?' },
-]
-
 const root = ref<HTMLElement>()
 const inlineVisible = useExpertInlineVisible()
 let observer: IntersectionObserver | undefined
@@ -80,30 +69,14 @@ function track () {
         </div>
       </div>
     </div>
-
-    <div class="flex flex-wrap gap-2">
-      <button
-        v-for="p in prompts"
-        :key="p.title"
-        type="button"
-        class="prompt-pill text-left px-4 py-2 bg-white rounded-full text-sm text-gray-500 hover:shadow-sm transition-all border hover:border-indigo-600 border-indigo-200 whitespace-nowrap overflow-hidden text-ellipsis max-w-full"
-        :data-prompt="p.prompt"
-        :title="p.prompt"
-      >
-        {{ p.title }}
-      </button>
-    </div>
   </div>
 </template>
 
 <style scoped>
-/* Two rows, the box and its prompts. A grid rather than margins so a parent can share the
-   rows through subgrid (DocsColumns does, to line the box up with the card beside it), and
-   the box fills whatever height its row gives it. */
+/* The box fills whatever height it is given, so beside a taller card (DocsColumns) the two
+   stand the same height. */
 .ff-expert-ask {
-    display: grid;
-    grid-template-rows: auto auto;
-    row-gap: 1rem;
+    display: flex;
 }
 
 .ff-expert-ask__box {

From 899ded5e5d864ec82409e763465afff43fc5f23b Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 16:47:33 +0200
Subject: [PATCH 21/31] header: FlowFuse Docs on docs pages

Docs pages show Docs beside the logo, linking to the docs home while the logo still goes
to the site. On wide screens it pairs with the wordmark as one lockup: capitals as tall as
the wordmark's (28px) on the same baseline, lighter and grey so the brand leads. Below
1024px it pairs with the square mark. On tablets the row had no other room (the menus
cannot fold into More), so on docs pages Free Trial gives way there and Book a demo keeps
its margin; it stays from 1024px up and on every other page.
---
 nuxt/components/AppHeader.vue | 52 +++++++++++++++++++++++++++++++----
 1 file changed, 47 insertions(+), 5 deletions(-)

diff --git a/nuxt/components/AppHeader.vue b/nuxt/components/AppHeader.vue
index 92bd904866..7d28a6d23b 100644
--- a/nuxt/components/AppHeader.vue
+++ b/nuxt/components/AppHeader.vue
@@ -125,6 +125,9 @@ onMounted(() => {
   <header id="ff-header" class="ff-header" :class="{ 'ff-header--docs': isDocs }" data-nav-zone="header">
     <nav class="relative w-full flex items-center justify-between xl:grid xl:grid-cols-header mx-auto max-screen-none lg:max-w-screen-xl 2xl:max-w-[1920px]">
 
+      <!-- One cell for the brand, so the xl grid (1fr auto 1fr) keeps three columns when
+           docs pages add their Docs label beside the logo. -->
+      <div class="ff-brand flex items-center shrink-0">
       <!-- Wordmark: visible from 420px up on mobile and on desktop, hidden on tablet -->
       <a class="ff-logo-link ff-logo-link--wordmark hidden min-[420px]:flex md:hidden lg:flex no-underline hover:no-underline font-bold h-8 w-40 flex-row" href="/" aria-label="FlowFuse Home" style="font-family:'Baloo 2', sans-serif">
         <!-- Five stops feed the staggered hover wave in style.css (ff-logo-wave). -->
@@ -149,6 +152,11 @@ onMounted(() => {
         </svg>
       </a>
 
+      <!-- On docs pages the logo reads "FlowFuse Docs": the logo still goes to the site,
+           "Docs" goes to the docs home. -->
+      <a v-if="isDocs" href="/docs/" class="ff-docs-brand-label">Docs</a>
+      </div>
+
       <!-- Mobile hamburger -->
       <div class="flex items-center gap-2 md:hidden relative z-20">
         <DocsHeaderActions />
@@ -190,7 +198,9 @@ onMounted(() => {
       <ul class="cta hidden md:flex flex-row items-center justify-end font-medium text no-underline z-10 bg-transparent w-auto">
         <!-- Docs search, on tablets, where the docs sidebar is folded away. -->
         <li v-if="isDocs" class="lg:hidden mr-1"><DocsHeaderActions /></li>
-        <li class="hidden md:flex"><CtaSignUp variant="nav-text" position="main-nav" padded class="ff-nav-freetrial text-base" /></li>
+        <!-- On docs pages Free Trial gives way to the search and the "Docs" label on tablets,
+             where the row has no other room: the menus cannot fold into More. -->
+        <li class="hidden md:flex" :class="{ 'md:hidden lg:flex': isDocs }"><CtaSignUp variant="nav-text" position="main-nav" padded class="ff-nav-freetrial text-base" /></li>
         <li class="flex">
           <CtaBookDemo variant="primary" position="main-nav" class="ml-2" />
         </li>
@@ -209,10 +219,10 @@ onMounted(() => {
 </template>
 
 <style scoped>
-/* Docs pages add search to the phone header, so the square logo holds on a little longer
-   before the wordmark takes its place (without this the wordmark touches the search button
-   at 420 to 440px). */
-@media (min-width: 420px) and (max-width: 519px) {
+/* Docs pages show "Docs" beside the logo. Below lg that pair is the square mark and
+   "Docs", on phones and tablets alike; the wordmark and "Docs" would crowd out the search
+   and Book a demo buttons. */
+@media (max-width: 1023px) {
     .ff-header--docs .ff-logo-link--wordmark {
         display: none;
     }
@@ -221,4 +231,36 @@ onMounted(() => {
         display: block;
     }
 }
+
+/* Beside the wordmark, "Docs" reads as one lockup with it: its capitals are as tall as the
+   wordmark's (20px, and Heebo's cap height is 0.711em, so 28px) and it sits on the same
+   baseline. With line-height 1 and centred on the 32px logo box, a 28px line puts its
+   baseline 1px above the wordmark's, hence the nudge. Lighter and grey, so the brand still
+   leads. */
+.ff-docs-brand-label {
+    position: relative;
+    top: 1px;
+    margin-left: 0.625rem;
+    font-size: 1.75rem;
+    line-height: 1;
+    font-weight: 400;
+    color: #374151;
+    white-space: nowrap;
+    text-decoration: none;
+}
+
+.ff-docs-brand-label:hover {
+    color: #4f46e5;
+}
+
+/* Beside the square mark the label is a size down. The tablet header is the tightest (the
+   nav, docs search, Free Trial and Book a demo share one row), and at 768px the larger label
+   pushed Book a demo past the edge. */
+@media (max-width: 1023px) {
+    .ff-docs-brand-label {
+        top: 0;
+        margin-left: 0.5rem;
+        font-size: 1.25rem;
+    }
+}
 </style>

From af1d4201d430d5f68152a56f8b755d644f617489 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 16:47:33 +0200
Subject: [PATCH 22/31] docs: the sidebar's first heading starts level with the
 page title

The gap between the sidebar search and the first group heading was Nuxt UI's label
padding, meant to separate a group from the one above, plus the nav's own top padding.
The first heading has no group above, so both go, and the space under the search is set
so the heading's capitals start on the same line as the page title's.
---
 nuxt/components/DocsLeftNav.vue | 24 ++++++++++++++++++++++--
 1 file changed, 22 insertions(+), 2 deletions(-)

diff --git a/nuxt/components/DocsLeftNav.vue b/nuxt/components/DocsLeftNav.vue
index 30a787d02e..0d59030fa3 100644
--- a/nuxt/components/DocsLeftNav.vue
+++ b/nuxt/components/DocsLeftNav.vue
@@ -25,9 +25,29 @@ const items = computed((): NavigationMenuItem[] => [
   <div class="pt-6 max-lg:contents">
     <!-- Below lg the header carries a search button instead. This stays mounted there, hidden,
          because that button opens this component's dialog. -->
-    <div class="max-lg:hidden mb-4 pr-2">
+    <div class="ff-docs-left-nav__search max-lg:hidden pr-2">
       <AlgoliaSearch index-filter="category:docs" placeholder="Search in Docs..." source-id="docs" detached shortcut />
     </div>
-    <SidebarNav :items="items" label="Documentation" />
+    <SidebarNav :items="items" label="Documentation" class="ff-docs-left-nav__nav" />
   </div>
 </template>
+
+<style scoped>
+/* The first group heading sits under the search field level with the page title: its
+   capitals start where the title's do (the 36px h1's cap top is 23px lower than this
+   label's would be straight under the field). Nuxt UI pads every label to separate it from
+   the group above; the first has no group above, so it loses that padding. */
+@media (min-width: 1024px) {
+    .ff-docs-left-nav__search {
+        margin-bottom: 23px;
+    }
+
+    .ff-docs-left-nav__nav {
+        padding-top: 0;
+    }
+
+    .ff-docs-left-nav__nav :deep(nav > ul > li:first-child > [data-slot="label"]) {
+        padding-top: 0;
+    }
+}
+</style>

From cfa92d886930c3e25896d625cf328a11a4a63cd4 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 16:51:59 +0200
Subject: [PATCH 23/31] header: the Docs lockup matched at 4x zoom, square mark
 until xl

Docs beside the wordmark is now Heebo 700, whose stems (4px) match the wordmark's (3.9px),
at 29px, which splits Heebo's proportions against the wordmark's (capitals 0.6px taller,
lowercase 0.4px shorter), on the same baseline. On docs pages the wordmark now waits for
xl: between 1024 and 1280px it brought the menus within 16px of Docs, while the square mark
keeps at least 45px there, 70px or more from 1100px.
---
 nuxt/components/AppHeader.vue | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/nuxt/components/AppHeader.vue b/nuxt/components/AppHeader.vue
index 7d28a6d23b..6e3aa49d68 100644
--- a/nuxt/components/AppHeader.vue
+++ b/nuxt/components/AppHeader.vue
@@ -219,10 +219,11 @@ onMounted(() => {
 </template>
 
 <style scoped>
-/* Docs pages show "Docs" beside the logo. Below lg that pair is the square mark and
-   "Docs", on phones and tablets alike; the wordmark and "Docs" would crowd out the search
-   and Book a demo buttons. */
-@media (max-width: 1023px) {
+/* Docs pages show "Docs" beside the logo. Below xl that pair is the square mark and
+   "Docs": with the wordmark, the menus came within 16px of "Docs" at 1100px, and the
+   square keeps at least 70px between them from there up. From xl, where the header
+   centres its menus, the wordmark has room (about 100px). */
+@media (max-width: 1279px) {
     .ff-header--docs .ff-logo-link--wordmark {
         display: none;
     }
@@ -232,18 +233,20 @@ onMounted(() => {
     }
 }
 
-/* Beside the wordmark, "Docs" reads as one lockup with it: its capitals are as tall as the
-   wordmark's (20px, and Heebo's cap height is 0.711em, so 28px) and it sits on the same
-   baseline. With line-height 1 and centred on the 32px logo box, a 28px line puts its
-   baseline 1px above the wordmark's, hence the nudge. Lighter and grey, so the brand still
-   leads. */
+/* Beside the wordmark, "Docs" reads as one lockup with it, measured at 4x zoom:
+   - weight 700, whose stems (4px at this size) match the wordmark's (3.9px);
+   - 29px, which splits Heebo's proportions against the wordmark's: capitals 0.6px taller
+     (20.6 against 20) and lowercase 0.4px shorter (15.6 against 16);
+   - the same baseline: with line-height 1, centred on the 32px logo box, the line sits 1px
+     high, hence the nudge.
+   Grey, so the brand colour still leads. */
 .ff-docs-brand-label {
     position: relative;
     top: 1px;
     margin-left: 0.625rem;
-    font-size: 1.75rem;
+    font-size: 29px;
     line-height: 1;
-    font-weight: 400;
+    font-weight: 700;
     color: #374151;
     white-space: nowrap;
     text-decoration: none;
@@ -254,9 +257,9 @@ onMounted(() => {
 }
 
 /* Beside the square mark the label is a size down. The tablet header is the tightest (the
-   nav, docs search, Free Trial and Book a demo share one row), and at 768px the larger label
+   nav, docs search, Free Trial and Book a demo share one row), and at 768px a larger label
    pushed Book a demo past the edge. */
-@media (max-width: 1023px) {
+@media (max-width: 1279px) {
     .ff-docs-brand-label {
         top: 0;
         margin-left: 0.5rem;

From f1e93def1e33810d7d969184194fb237d5d01015 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 16:52:00 +0200
Subject: [PATCH 24/31] docs: sidebar, logo and banner share one left edge at
 every width

Between 1280 and 1536px the docs page and the header stop at the same max width but were
padded differently (the page on the left only), so the sidebar search sat 12px right of
the logo. The page now mirrors the header's padding from lg up. Group headings also drop
Nuxt UI's label inset, which put them 10px right of the search field: they are headings
over indented links, not link text.
---
 nuxt/components/DocsLeftNav.vue | 7 +++++++
 nuxt/pages/docs/[...slug].vue   | 5 ++++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/nuxt/components/DocsLeftNav.vue b/nuxt/components/DocsLeftNav.vue
index 0d59030fa3..2655aafc9c 100644
--- a/nuxt/components/DocsLeftNav.vue
+++ b/nuxt/components/DocsLeftNav.vue
@@ -50,4 +50,11 @@ const items = computed((): NavigationMenuItem[] => [
         padding-top: 0;
     }
 }
+
+/* Group headings start on the same left edge as the search field and the logo above it;
+   Nuxt UI insets labels to line up with link text, but ours are headings over indented
+   links. */
+.ff-docs-left-nav__nav :deep([data-slot="label"]) {
+    padding-left: 0;
+}
 </style>
diff --git a/nuxt/pages/docs/[...slug].vue b/nuxt/pages/docs/[...slug].vue
index 9627f6e168..518ea3abaf 100644
--- a/nuxt/pages/docs/[...slug].vue
+++ b/nuxt/pages/docs/[...slug].vue
@@ -120,7 +120,10 @@ const surround = computed(() => {
     <ContentRenderer v-if="page" :value="page" />
   </div>
 
-  <div v-else class="w-full pl-6">
+  <!-- lg:pr-6 mirrors the header's own padding, so the two centre alike and the sidebar
+       search lines up under the logo at every width (with pl-6 alone they parted by 12px
+       between 1280 and 1536, where both stop at the same max width). -->
+  <div v-else class="w-full pl-6 lg:pr-6">
     <div class="handbook ff-prose text-left pb-24 m-auto">
 
       <!-- Left navigation -->

From 6b294d99df6e0f26b41b33dcf3d364956c33e94b Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 16:57:50 +0200
Subject: [PATCH 25/31] header: one logo at every width, Docs one size and a
 step lighter

Below xl the docs header no longer swaps in the separate square logo, which is drawn larger
and in a lighter red: it shows the wordmark itself cropped to its mark, so the logo keeps
one shape, colour and size and only its lettering comes and goes. Docs stays 29px at every
width, now weight 600: its stems sit just under the wordmark's, 700 read too heavy. On
phones below 390px the row cannot hold the mark, Docs, search, Book a demo and the menu,
so there Book a demo gives way; from 390px it fits.
---
 nuxt/components/AppHeader.vue | 51 ++++++++++++++++++++++-------------
 1 file changed, 32 insertions(+), 19 deletions(-)

diff --git a/nuxt/components/AppHeader.vue b/nuxt/components/AppHeader.vue
index 6e3aa49d68..405a200e9c 100644
--- a/nuxt/components/AppHeader.vue
+++ b/nuxt/components/AppHeader.vue
@@ -160,7 +160,7 @@ onMounted(() => {
       <!-- Mobile hamburger -->
       <div class="flex items-center gap-2 md:hidden relative z-20">
         <DocsHeaderActions />
-        <CtaBookDemo variant="primary" position="header-mobile" class="whitespace-nowrap" />
+        <CtaBookDemo variant="primary" position="header-mobile" class="ff-header-demo-mobile whitespace-nowrap" />
         <button id="nav-toggle" class="text-gray-700 flex items-center text-red-hero">
           <svg class="burger fill-current h-4 w-4" viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg"><title>Menu</title><path d="M0 3h20v2H0V3zm0 6h20v2H0V9zm0 6h20v2H0v-2z"/></svg>
           <svg class="close fill-current h-6 w-6" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor"><path stroke-linecap="round" stroke-linejoin="round" d="M6 18L18 6M6 6l12 12" /></svg>
@@ -219,34 +219,49 @@ onMounted(() => {
 </template>
 
 <style scoped>
-/* Docs pages show "Docs" beside the logo. Below xl that pair is the square mark and
-   "Docs": with the wordmark, the menus came within 16px of "Docs" at 1100px, and the
-   square keeps at least 70px between them from there up. From xl, where the header
-   centres its menus, the wordmark has room (about 100px). */
+/* Docs pages show "Docs" beside the logo. Below xl that pair is the mark alone and
+   "Docs": with the whole wordmark, the menus came within 16px of "Docs" at 1100px. The
+   mark is the wordmark itself, cropped to its first 28px, rather than the separate square
+   logo, which is drawn larger and in a lighter red: the logo keeps one shape, colour and
+   size at every width, and only its lettering comes and goes. */
+.ff-header--docs .ff-logo-link--square {
+    display: none;
+}
+
+.ff-header--docs .ff-logo-link--wordmark {
+    display: flex;
+}
+
 @media (max-width: 1279px) {
     .ff-header--docs .ff-logo-link--wordmark {
-        display: none;
+        width: 28px;
+        overflow: hidden;
     }
 
-    .ff-header--docs .ff-logo-link--square {
-        display: block;
+    .ff-header--docs .ff-logo-link--wordmark svg {
+        width: 160px;
+        max-width: none;
+        flex-shrink: 0;
     }
 }
 
 /* Beside the wordmark, "Docs" reads as one lockup with it, measured at 4x zoom:
-   - weight 700, whose stems (4px at this size) match the wordmark's (3.9px);
+   - weight 600: its stems (3.5px at this size) sit just under the wordmark's (3.9px), close
+     enough to belong to it, a step lighter so it does not compete (700 matched the stems
+     but read too heavy, 400 too thin);
    - 29px, which splits Heebo's proportions against the wordmark's: capitals 0.6px taller
      (20.6 against 20) and lowercase 0.4px shorter (15.6 against 16);
    - the same baseline: with line-height 1, centred on the 32px logo box, the line sits 1px
      high, hence the nudge.
-   Grey, so the brand colour still leads. */
+   Grey, so the brand colour still leads. The same size at every width, beside the mark
+   alone as beside the whole wordmark. */
 .ff-docs-brand-label {
     position: relative;
     top: 1px;
     margin-left: 0.625rem;
     font-size: 29px;
     line-height: 1;
-    font-weight: 700;
+    font-weight: 600;
     color: #374151;
     white-space: nowrap;
     text-decoration: none;
@@ -256,14 +271,12 @@ onMounted(() => {
     color: #4f46e5;
 }
 
-/* Beside the square mark the label is a size down. The tablet header is the tightest (the
-   nav, docs search, Free Trial and Book a demo share one row), and at 768px a larger label
-   pushed Book a demo past the edge. */
-@media (max-width: 1279px) {
-    .ff-docs-brand-label {
-        top: 0;
-        margin-left: 0.5rem;
-        font-size: 1.25rem;
+/* On a phone narrower than 390px the docs header has no room for the mark, "Docs", search,
+   Book a demo and the menu at once ("Docs" touched the search at 360 and 375px, and the row
+   overflowed at 320px), so Book a demo gives way there. From 390px it fits. */
+@media (max-width: 389px) {
+    .ff-header--docs .ff-header-demo-mobile {
+        display: none;
     }
 }
 </style>

From 3a62fd4df7bff86b1c992ad6868e827fc6e2ae97 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 17:03:18 +0200
Subject: [PATCH 26/31] docs: the Expert box spans its column again

Without the prompt pills the box sat in a flex row that sized it to its content, so it
shrank to a narrow strip and clipped its footnote. It now grows to the column's width as
well as its height.
---
 nuxt/components/content/FfExpertAsk.vue | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/nuxt/components/content/FfExpertAsk.vue b/nuxt/components/content/FfExpertAsk.vue
index 4b38666d3c..12812860f0 100644
--- a/nuxt/components/content/FfExpertAsk.vue
+++ b/nuxt/components/content/FfExpertAsk.vue
@@ -73,14 +73,16 @@ function track () {
 </template>
 
 <style scoped>
-/* The box fills whatever height it is given, so beside a taller card (DocsColumns) the two
-   stand the same height. */
+/* The box fills whatever width and height it is given, so beside a taller card
+   (DocsColumns) the two stand the same height and the box spans its column. */
 .ff-expert-ask {
     display: flex;
 }
 
 .ff-expert-ask__box {
     display: flex;
+    flex: 1;
+    min-width: 0;
 }
 
 .ff-expert-ask__card {

From 49dbebb92d3428bb5d9d342ee3fd506988650abe Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 17:54:58 +0200
Subject: [PATCH 27/31] docs: the docs home is this repo's page, not the
 flowfuse README

/docs spans more than the FlowFuse/flowfuse docs: the guides and the Node-RED library come
from this repo. Its home therefore lives here, as nuxt/content-guides/README.md, which
guides-sync overlays as the docs index. docs-sync stops copying the README at the root of
the flowfuse docs tree, which stays that repository's own readme for its docs folder;
syncing it neither writes nor removes the home page. Tests cover both the dev watcher's
single-file sync and a full sync.

The page is the landing page built from the docs-* components, with links to other pages
of this site written relative so they resolve on any host, deploy previews included.
---
 nuxt/content-guides/README.md | 253 ++++++++++++++++++++++++++++++++++
 nuxt/lib/docs-sync.mjs        |  12 ++
 nuxt/lib/docs-sync.test.mjs   |  36 ++++-
 3 files changed, 300 insertions(+), 1 deletion(-)
 create mode 100644 nuxt/content-guides/README.md

diff --git a/nuxt/content-guides/README.md b/nuxt/content-guides/README.md
new file mode 100644
index 0000000000..3e266b4db6
--- /dev/null
+++ b/nuxt/content-guides/README.md
@@ -0,0 +1,253 @@
+---
+navTitle: Documentation
+metaTitle: Documentation
+landing: true
+meta:
+   description: FlowFuse documentation. Get started on FlowFuse Cloud, on your own hardware or with your AI agent, then build, deploy and run industrial applications.
+---
+
+::docs-hero
+# Start building with FlowFuse
+
+Build industrial applications, then deploy and run them from cloud to edge.
+
+#actions
+- [:icon{name="i-lucide-play"} Getting started](/docs/user/introduction/)
+- [:icon{name="i-lucide-book-open"} API reference](/docs/api/)
+
+#aside
+:::docs-choices{title="Where do you want to start?"}
+::::docs-choice{label="FlowFuse Cloud" icon="i-lucide-cloud"}
+FlowFuse runs the platform for you. Sign up, then build your applications and deploy them from your browser, with nothing to install. The quickest way to try FlowFuse.
+
+- [Get started on FlowFuse Cloud](/docs/user/introduction/)
+- [Sign up](https://app.flowfuse.com/account/create)
+::::
+
+::::docs-choice{label="Your own edge hardware, with the Device Agent" icon="i-lucide-cpu"}
+Run your applications on your own machines at the edge, from an industrial PC to a Raspberry Pi, and manage them all from FlowFuse. The Device Agent connects each machine as a remote instance, to FlowFuse Cloud or to a self-hosted platform.
+
+- [Connect your first machine](/docs/device-agent/quickstart/)
+- [Other ways to install](/docs/device-agent/install/overview/)
+::::
+
+::::docs-choice{label="FlowFuse Self-Hosted" icon="i-lucide-server"}
+Run the whole platform, and the applications on it, on your own infrastructure: on premises or in your own cloud, with Docker or Kubernetes. Talk to our sales team first: they help you choose the right licence and plan the installation with you.
+
+- [Contact sales](/contact-us/)
+- [Choose how to install](/docs/install/introduction/)
+::::
+
+::::docs-choice{label="Your AI agent" icon="i-lucide-bot"}
+Connect Claude, ChatGPT, Copilot or another agent to FlowFuse over MCP. It can manage your teams and applications, and build and edit their flows, within the access you grant it.
+
+- [Connect your agent](/docs/user/expert/third-party-agents/)
+::::
+
+::::docs-choice{label="Not sure yet? Talk to us" icon="i-lucide-messages-square" open}
+Tell us about the applications you want to build, and the sites and machines they run on. We work out with you which setup fits, then help you get it running. To understand the platform first, the Application Guide explains how FlowFuse applications are shaped.
+
+- [Book a call](/book-demo/)
+- [Read the Application Guide](/docs/application-guide/)
+::::
+:::
+::
+
+::docs-section{eyebrow="Platform" title="Choose how you run FlowFuse"}
+Where FlowFuse runs is the one choice that changes your first steps. After that, the documentation is the same.
+
+:::card-group
+::::card{title="FlowFuse Cloud" icon="i-lucide-cloud"}
+Hosted by FlowFuse. Nothing to install: sign up and build in the browser.
+
+- [:icon{name="i-lucide-info"} About FlowFuse Cloud](/docs/cloud/introduction/)
+- [:icon{name="i-lucide-play"} Get started on FlowFuse Cloud](/docs/user/introduction/)
+- [:icon{name="i-lucide-receipt"} Billing](/docs/cloud/billing/)
+::::
+
+::::card{title="Self-hosted" icon="i-lucide-server"}
+The platform on your own infrastructure, with Docker, Kubernetes or a single machine. Start by talking to our sales team.
+
+- [:icon{name="i-lucide-messages-square"} Contact sales](/contact-us/)
+- [:icon{name="i-lucide-signpost"} Choosing how to install](/docs/install/introduction/)
+- [:icon{name="i-lucide-container"} Docker](/docs/install/docker/)
+- [:icon{name="i-lucide-ship-wheel"} Kubernetes](/docs/install/kubernetes/)
+- [:icon{name="i-lucide-settings"} Configuring FlowFuse](/docs/install/configuration/)
+::::
+:::
+
+:::docs-tiles
+- [:icon{name="i-lucide-cpu"} Remote instances with the Device Agent](/docs/device-agent/)
+- [:icon{name="i-lucide-arrow-right-left"} Moving from plain Node-RED](/docs/migration/)
+- [:icon{name="i-lucide-hard-drive"} Hardware guides](/docs/hardware/introduction/)
+:::
+::
+
+::docs-section{eyebrow="Documentation" title="Find what you need" cols="4"}
+Four kinds of page, for four different moments.
+
+:::card-group
+::::card{title="Learn by building" icon="i-lucide-graduation-cap"}
+Lessons that take you from nothing to something working.
+
+- [Build a weather dashboard](/blog/2025/12/getting-weather-data-in-node-red/)
+- [Build a machine downtime tracker](/blog/2026/07/build-downtime-logger/)
+- [Build a defect tracking dashboard](/blog/2026/07/defect-and-quality-monitoring/)
+::::
+
+::::card{title="Get something done" icon="i-lucide-list-checks"}
+Task guides, for when you know what you want.
+
+- [Working in FlowFuse](/docs/user/)
+- [Working in Node-RED](/docs/node-red/)
+- [MCP in your flows](/docs/flowfuse-nodes/mcp/)
+- [Administering FlowFuse](/docs/admin/)
+::::
+
+::::card{title="Look something up" icon="i-lucide-book-open"}
+Details you come back for rather than read once.
+
+- [Instance states](/docs/user/instance-states/)
+- [FlowFuse nodes](/docs/flowfuse-nodes/)
+- [Node-RED core nodes](/docs/node-red/core-nodes/)
+- [API](/docs/api/)
+::::
+
+::::card{title="Understand FlowFuse" icon="i-lucide-lightbulb"}
+What FlowFuse is, and how to shape an application on it.
+
+- [FlowFuse concepts](/docs/user/concepts/)
+- [Application Guide](/docs/application-guide/)
+- [Node-RED Guide](/docs/node-red-guide/)
+::::
+:::
+::
+
+::docs-section{eyebrow="Journey" title="From first flow to production"}
+Follow the lifecycle, or jump to what you need.
+
+:::steps{level="3"}
+### Get started
+Your first application and its first flow, and the people you build it with.
+
+::::docs-tiles
+- [:icon{name="i-lucide-play"} Getting started](/docs/user/introduction/)
+- [:icon{name="i-lucide-layout-dashboard"} Your first dashboard](/blog/2025/12/getting-weather-data-in-node-red/)
+- [:icon{name="i-lucide-shapes"} FlowFuse concepts](/docs/user/concepts/)
+- [:icon{name="i-lucide-users"} Teams](/docs/user/team/)
+- [:icon{name="i-lucide-arrow-right-left"} Move from Node-RED](/docs/migration/)
+::::
+
+### Build
+The flows, dashboards and data your application runs on.
+
+::::docs-tiles
+- [:icon{name="i-lucide-gauge"} Dashboards](/docs/user/dashboards/)
+- [:icon{name="i-lucide-sparkles"} FlowFuse Expert](/docs/user/expert/)
+- [:icon{name="i-lucide-bot"} Connect your own agent](/docs/user/expert/third-party-agents/)
+- [:icon{name="i-lucide-table"} FlowFuse Tables](/docs/user/ff-tables/)
+- [:icon{name="i-lucide-radio-tower"} Team Broker](/docs/user/teambroker/)
+- [:icon{name="i-lucide-variable"} Environment variables](/docs/user/envvar/)
+- [:icon{name="i-lucide-library"} Shared team library](/docs/user/shared-library/)
+::::
+
+### Deploy
+Promote tested work to production, in the cloud and at the edge.
+
+::::docs-tiles
+- [:icon{name="i-lucide-history"} Snapshots](/docs/user/snapshots/)
+- [:icon{name="i-lucide-git-branch"} DevOps pipelines](/docs/user/devops-pipelines/)
+- [:icon{name="i-lucide-cpu"} Deploy to remote instances](/docs/device-agent/deploy/)
+- [:icon{name="i-lucide-boxes"} Remote instance groups](/docs/user/device-groups/)
+- [:icon{name="i-lucide-copy"} High availability](/docs/user/high-availability/)
+- [:icon{name="i-lucide-globe"} Custom hostnames](/docs/user/custom-hostnames/)
+::::
+
+### Operate
+Access, visibility and cost, once it runs.
+
+::::docs-tiles
+- [:icon{name="i-lucide-shield"} Roles and permissions](/docs/user/role-based-access-control/)
+- [:icon{name="i-lucide-key-round"} Single sign-on](/docs/admin/sso/)
+- [:icon{name="i-lucide-scroll-text"} Logging](/docs/user/logs/)
+- [:icon{name="i-lucide-activity"} Monitoring](/docs/admin/monitoring/)
+- [:icon{name="i-lucide-settings"} Instance settings](/docs/user/instance-settings/)
+- [:icon{name="i-lucide-receipt"} Billing](/docs/cloud/billing/)
+::::
+:::
+::
+
+::docs-section{eyebrow="Resources" title="Keep learning" cols="3"}
+:::card-group
+::::card{icon="i-lucide-newspaper"}
+[Blog :icon{name="i-lucide-arrow-up-right"}](/blog/)
+
+Articles, how-tos and product news.
+::::
+
+::::card{icon="i-lucide-layout-template"}
+[Blueprint library :icon{name="i-lucide-arrow-up-right"}](/blueprints/)
+
+Ready-made flows to start an application from.
+::::
+
+::::card{icon="i-lucide-star"}
+[What's new :icon{name="i-lucide-arrow-up-right"}](/changelog/)
+
+Every release, feature by feature.
+::::
+
+::::card{icon="i-lucide-presentation"}
+[Webinars :icon{name="i-lucide-arrow-up-right"}](/webinars/)
+
+Live and recorded sessions with the team.
+::::
+
+::::card{icon="i-lucide-plug"}
+[Integrations :icon{name="i-lucide-arrow-up-right"}](/integrations/)
+
+Certified nodes for the systems you connect to.
+::::
+
+::::card{icon="i-lucide-youtube"}
+[YouTube :icon{name="i-lucide-arrow-up-right"}](https://www.youtube.com/channel/UCbBzP8NZbv3WDtlt4UouA-g)
+
+Walkthroughs and recorded talks.
+::::
+:::
+::
+
+::docs-section{eyebrow="Help" title="Ask a question" cols="3"}
+Ask FlowFuse Expert, which answers from these docs, the blog and more. Or put your question to our support team, the community, or the troubleshooting guides.
+
+:::docs-columns
+::::ff-expert-ask
+::::
+
+::::card{icon="i-lucide-headset"}
+[Talk to our support team :icon{name="i-lucide-arrow-up-right"}](/support/)
+
+Search the Help Center or submit a ticket. For Cloud and Enterprise customers.
+::::
+:::
+
+:::card-group
+::::card{icon="i-lucide-bug"}
+[Debugging Node-RED](/docs/debugging/)
+
+Find out why a flow or an instance is not behaving.
+::::
+
+::::card{icon="i-lucide-messages-square"}
+[Community forum](/docs/community-support/)
+
+Ask the FlowFuse and Node-RED community.
+::::
+
+::::card{icon="i-lucide-activity"}
+[Platform status :icon{name="i-lucide-arrow-up-right"}](https://status.flowfuse.com/)
+
+FlowFuse Cloud availability.
+::::
+:::
+::
diff --git a/nuxt/lib/docs-sync.mjs b/nuxt/lib/docs-sync.mjs
index 766eceb612..aa3c0e8e87 100644
--- a/nuxt/lib/docs-sync.mjs
+++ b/nuxt/lib/docs-sync.mjs
@@ -96,6 +96,15 @@ function gitOutput (cwd, args) {
     }
 }
 
+/**
+ * The README at the root of the flowfuse docs tree is that repository's own readme for its
+ * docs folder, not the portal's home page. /docs spans more than the flowfuse docs (the
+ * guides and the Node-RED library come from this repo), so its home is this repo's
+ * nuxt/content-guides/README.md, which guides-sync overlays as index.md. This file is
+ * therefore never copied, and syncing it neither writes nor removes the home page.
+ */
+export const FLOWFUSE_DOCS_README = 'README.md'
+
 /**
  * Where one source file lands: markdown becomes a page under content/, a README becomes
  * its section index, and anything else is an asset served from public/.
@@ -141,6 +150,7 @@ function copyDocsDir ({ docsDir, sourceRoot, contentDocsDir, publicDocsDir, vers
         if (entry.name.startsWith('.')) continue
 
         const relPath = join(relDir, entry.name)
+        if (relPath === FLOWFUSE_DOCS_README) continue
         const args = { docsDir, sourceRoot, contentDocsDir, publicDocsDir, version }
 
         if (entry.isDirectory()) {
@@ -172,6 +182,8 @@ export function syncDocsPath ({ docsDir, nuxtRoot, relPath }) {
     const contentDocsDir = join(nuxtRoot, 'content', 'docs')
     const publicDocsDir = join(nuxtRoot, 'public', 'docs')
 
+    if (relPath === FLOWFUSE_DOCS_README) return
+
     if (!existsSync(join(docsDir, relPath))) {
         rmSync(destinationFor(relPath, contentDocsDir, publicDocsDir), { force: true })
         return
diff --git a/nuxt/lib/docs-sync.test.mjs b/nuxt/lib/docs-sync.test.mjs
index 014c7692bb..072c6f9ea0 100644
--- a/nuxt/lib/docs-sync.test.mjs
+++ b/nuxt/lib/docs-sync.test.mjs
@@ -4,7 +4,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
-import { resolveSource, syncDocsPath } from './docs-sync.mjs'
+import { resolveSource, syncDocs, syncDocsPath } from './docs-sync.mjs'
 
 const repoRoot = '/repo/website'
 
@@ -100,6 +100,40 @@ test('a README becomes the index page of its section', (t) => {
     assert.ok(!existsSync(fx.content('cloud', 'README.md')))
 })
 
+// The portal home is this repo's page (nuxt/content-guides/README.md); the README at the
+// root of the flowfuse docs tree is only that repo's own readme.
+test('the root README of the flowfuse docs is not written as the portal home', (t) => {
+    const fx = fixture(t)
+    writeFileSync(join(fx.docsDir, 'README.md'), '# FlowFuse docs\n')
+
+    syncDocsPath({ docsDir: fx.docsDir, nuxtRoot: fx.nuxtRoot, relPath: 'README.md' })
+
+    assert.ok(!existsSync(fx.content('index.md')))
+})
+
+test('syncing the root README leaves the portal home in place', (t) => {
+    const fx = fixture(t)
+    writeFileSync(fx.content('index.md'), 'the website home\n')
+
+    syncDocsPath({ docsDir: fx.docsDir, nuxtRoot: fx.nuxtRoot, relPath: 'README.md' })
+
+    assert.equal(readFileSync(fx.content('index.md'), 'utf8'), 'the website home\n')
+})
+
+test('a full sync copies every page but the root README', async (t) => {
+    const fx = fixture(t)
+    writeFileSync(join(fx.docsDir, 'README.md'), '# FlowFuse docs\n')
+    writeFileSync(join(fx.docsDir, 'cloud', 'README.md'), '# Cloud\n')
+    writeFileSync(join(fx.docsDir, 'cloud', 'billing.md'), '# Billing\n')
+    const silent = { info () {}, warn () {} }
+
+    await syncDocs({ repoRoot: join(fx.nuxtRoot, '..'), nuxtRoot: fx.nuxtRoot, env: { FLOWFUSE_DOCS_LOCAL: fx.docsDir }, logger: silent })
+
+    assert.ok(!existsSync(fx.content('index.md')))
+    assert.ok(existsSync(fx.content('cloud', 'index.md')))
+    assert.ok(existsSync(fx.content('cloud', 'billing.md')))
+})
+
 test('a non-markdown file is copied to the public tree unchanged', (t) => {
     const fx = fixture(t)
     writeFileSync(join(fx.docsDir, 'cloud', 'diagram.svg'), '<svg/>')

From e950295c5afb23bbe5bbb6c0176f3ec730655b72 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 18:19:25 +0200
Subject: [PATCH 28/31] docs: each way in pairs its first step with a page
 about it

In the docs home's list of ways in, the second link of every option now leads to the page
that explains the option: about FlowFuse Cloud, the Device Agent, self-hosting, FlowFuse MCP
and FlowFuse applications. The first stays the step that starts it. The AI agent option,
which had only its first step, gains its about link too.
---
 nuxt/components/content/DocsChoice.vue | 5 +++--
 nuxt/content-guides/README.md          | 9 +++++----
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/nuxt/components/content/DocsChoice.vue b/nuxt/components/content/DocsChoice.vue
index 51126ababf..69251d88ac 100644
--- a/nuxt/components/content/DocsChoice.vue
+++ b/nuxt/components/content/DocsChoice.vue
@@ -1,8 +1,9 @@
 <script setup lang="ts">
 // One option in a ::docs-choices list: a row that opens to a short explanation, then its
 // links. Two at most: the first is the option's main call to action and reads as a button,
-// the second a secondary action that reads as a plain link. A third choice would make the
-// reader weigh options inside an option.
+// the second reads as a plain link and leads to the page that explains the option, for the
+// reader who wants to learn more before starting. A third choice would make the reader
+// weigh options inside an option.
 defineProps<{
     label: string
     icon?: string
diff --git a/nuxt/content-guides/README.md b/nuxt/content-guides/README.md
index 3e266b4db6..fb44b053eb 100644
--- a/nuxt/content-guides/README.md
+++ b/nuxt/content-guides/README.md
@@ -21,34 +21,35 @@ Build industrial applications, then deploy and run them from cloud to edge.
 FlowFuse runs the platform for you. Sign up, then build your applications and deploy them from your browser, with nothing to install. The quickest way to try FlowFuse.
 
 - [Get started on FlowFuse Cloud](/docs/user/introduction/)
-- [Sign up](https://app.flowfuse.com/account/create)
+- [About FlowFuse Cloud](/docs/cloud/introduction/)
 ::::
 
 ::::docs-choice{label="Your own edge hardware, with the Device Agent" icon="i-lucide-cpu"}
 Run your applications on your own machines at the edge, from an industrial PC to a Raspberry Pi, and manage them all from FlowFuse. The Device Agent connects each machine as a remote instance, to FlowFuse Cloud or to a self-hosted platform.
 
 - [Connect your first machine](/docs/device-agent/quickstart/)
-- [Other ways to install](/docs/device-agent/install/overview/)
+- [About the Device Agent](/docs/device-agent/introduction/)
 ::::
 
 ::::docs-choice{label="FlowFuse Self-Hosted" icon="i-lucide-server"}
 Run the whole platform, and the applications on it, on your own infrastructure: on premises or in your own cloud, with Docker or Kubernetes. Talk to our sales team first: they help you choose the right licence and plan the installation with you.
 
 - [Contact sales](/contact-us/)
-- [Choose how to install](/docs/install/introduction/)
+- [About self-hosting](/docs/install/introduction/)
 ::::
 
 ::::docs-choice{label="Your AI agent" icon="i-lucide-bot"}
 Connect Claude, ChatGPT, Copilot or another agent to FlowFuse over MCP. It can manage your teams and applications, and build and edit their flows, within the access you grant it.
 
 - [Connect your agent](/docs/user/expert/third-party-agents/)
+- [About FlowFuse MCP](/docs/user/mcp/)
 ::::
 
 ::::docs-choice{label="Not sure yet? Talk to us" icon="i-lucide-messages-square" open}
 Tell us about the applications you want to build, and the sites and machines they run on. We work out with you which setup fits, then help you get it running. To understand the platform first, the Application Guide explains how FlowFuse applications are shaped.
 
 - [Book a call](/book-demo/)
-- [Read the Application Guide](/docs/application-guide/)
+- [About FlowFuse applications](/docs/application-guide/)
 ::::
 :::
 ::

From cd58eff454f36b209a8ec492e7e05e72cb53b26b Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Fri, 25 Sep 2026 18:51:41 +0200
Subject: [PATCH 29/31] docs: the ways-in list opens smoothly and moves nothing
 around it

Opening another option no longer moves the home page heading or the sections below. The
hero aligns its columns to the top instead of centring the heading on the list, and the
list keeps the height of its tallest open option, measured once mounted and again when its
width changes (each option opened in turn with transitions off, in one synchronous pass).
Opening and closing an option now animate its height with a short fade, using
::details-content and interpolate-size; a browser without them opens the option
immediately, and reduced motion turns the animation off.
---
 nuxt/components/content/DocsChoice.vue  | 27 +++++++++++++
 nuxt/components/content/DocsChoices.vue | 54 ++++++++++++++++++++++++-
 nuxt/components/content/DocsHero.vue    |  4 +-
 3 files changed, 83 insertions(+), 2 deletions(-)

diff --git a/nuxt/components/content/DocsChoice.vue b/nuxt/components/content/DocsChoice.vue
index 69251d88ac..fd98faea09 100644
--- a/nuxt/components/content/DocsChoice.vue
+++ b/nuxt/components/content/DocsChoice.vue
@@ -84,8 +84,35 @@ const name = inject<string>('ff-docs-choices-name', 'ff-docs-choices')
     transform: rotate(180deg);
 }
 
+/* Opening and closing animate the content's height (to its natural size, which
+   interpolate-size on DocsChoices allows) with a short fade. A browser without
+   ::details-content drops these rules and simply opens the option. */
+.ff-docs-choice::details-content {
+    block-size: 0;
+    overflow: hidden;
+    transition: block-size 0.25s ease, content-visibility 0.25s allow-discrete;
+}
+
+.ff-docs-choice[open]::details-content {
+    block-size: auto;
+}
+
 .ff-docs-choice__body {
     padding: 0 0.25rem 1.125rem 2.25rem;
+    opacity: 0;
+    transition: opacity 0.2s ease;
+}
+
+.ff-docs-choice[open] .ff-docs-choice__body {
+    opacity: 1;
+}
+
+@media (prefers-reduced-motion: reduce) {
+    .ff-docs-choice::details-content,
+    .ff-docs-choice__body,
+    .ff-docs-choice__chevron {
+        transition: none;
+    }
 }
 
 .ff-docs-choice__body :deep(p) {
diff --git a/nuxt/components/content/DocsChoices.vue b/nuxt/components/content/DocsChoices.vue
index 56c72c98dc..66178b665c 100644
--- a/nuxt/components/content/DocsChoices.vue
+++ b/nuxt/components/content/DocsChoices.vue
@@ -15,17 +15,61 @@
 //
 // Each choice is a native <details>; sharing one name makes the browser keep a single one
 // open, with no script involved.
+//
+// The list keeps the height of its tallest open option, whichever is open, so opening
+// another option never moves what sits below or beside it. That height is measured once
+// mounted and again when the width changes: every option is opened in turn with the
+// transition off, inside one synchronous pass, so nothing is painted in between.
 defineProps<{
     title?: string
 }>()
 
 provide('ff-docs-choices-name', useId())
+
+const list = ref<HTMLElement>()
+let resizeObserver: ResizeObserver | undefined
+let lastWidth = 0
+
+function reserveHeight () {
+    const el = list.value
+    if (!el) return
+    const items = Array.from(el.querySelectorAll<HTMLDetailsElement>(':scope > .ff-docs-choice'))
+    if (!items.length) return
+
+    const wasOpen = items.find(item => item.open)
+    el.classList.add('ff-docs-choices__list--measuring')
+    el.style.minHeight = ''
+
+    let tallest = 0
+    for (const item of items) {
+        item.open = true
+        tallest = Math.max(tallest, el.offsetHeight)
+    }
+    for (const item of items) item.open = item === wasOpen
+
+    el.style.minHeight = `${tallest}px`
+    void el.offsetHeight // settle layout before transitions come back
+    el.classList.remove('ff-docs-choices__list--measuring')
+}
+
+onMounted(() => {
+    reserveHeight()
+    resizeObserver = new ResizeObserver(([entry]) => {
+        const width = Math.round(entry.contentRect.width)
+        if (width === lastWidth) return
+        lastWidth = width
+        reserveHeight()
+    })
+    if (list.value) resizeObserver.observe(list.value)
+})
+
+onBeforeUnmount(() => resizeObserver?.disconnect())
 </script>
 
 <template>
   <div class="ff-docs-choices not-prose">
     <p v-if="title" class="ff-docs-choices__title">{{ title }}</p>
-    <div class="ff-docs-choices__list">
+    <div ref="list" class="ff-docs-choices__list">
       <slot />
     </div>
   </div>
@@ -41,5 +85,13 @@ provide('ff-docs-choices-name', useId())
 
 .ff-docs-choices__list {
     border-top: 1px solid #e5e7eb;
+    /* Lets an option's content animate to its natural height (see DocsChoice). */
+    interpolate-size: allow-keywords;
+}
+
+/* While measuring, options open and close instantly. */
+.ff-docs-choices__list--measuring :deep(.ff-docs-choice::details-content),
+.ff-docs-choices__list--measuring :deep(.ff-docs-choice__chevron) {
+    transition: none !important;
 }
 </style>
diff --git a/nuxt/components/content/DocsHero.vue b/nuxt/components/content/DocsHero.vue
index 0ac8754d69..d37596bbb4 100644
--- a/nuxt/components/content/DocsHero.vue
+++ b/nuxt/components/content/DocsHero.vue
@@ -55,11 +55,13 @@ defineProps<{
     margin-top: 2.5rem;
 }
 
+/* Top-aligned, not centred: the aside can change height (the ways-in list opens and closes),
+   and a centred heading would move with it. */
 @media (min-width: 1024px) {
     .ff-docs-hero {
         grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
         gap: 4rem;
-        align-items: center;
+        align-items: start;
     }
 }
 

From 4d882f288579c8e70015a6c01f076197037f24bb Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Tue, 29 Sep 2026 14:10:51 +0200
Subject: [PATCH 30/31] docs: Ask Docs moves to its own PR

FlowFuse Expert on the docs (the Ask Docs button, the question box on the
docs home and the conversation modal) ran on src/js/ai-expert-modal.js,
which the Eleventy retirement removed from main, and the endpoint that
script calls no longer answers without sign-in. This PR keeps the docs
home, the header and the search dialog, and Ask Docs follows separately.

Removed: DocsAskFab, DocsExpertHost, DocsExpertBrand, FfExpertAsk,
useDocsExpert, and DocsColumns, which only held the question box. The
layout goes back to main's. The Help section on the docs home keeps its
wording without the Expert sentence, and the support card joins the
other three cards in a two-column group.
---
 nuxt/components/DocsAskFab.vue          | 113 ------------------------
 nuxt/components/DocsExpertBrand.vue     |  55 ------------
 nuxt/components/DocsExpertHost.vue      |  71 ---------------
 nuxt/components/DocsHeaderActions.vue   |   2 +-
 nuxt/components/content/DocsColumns.vue |  40 ---------
 nuxt/components/content/DocsSection.vue |  15 +---
 nuxt/components/content/FfExpertAsk.vue | 113 ------------------------
 nuxt/composables/useDocsExpert.ts       |  47 ----------
 nuxt/content-guides/README.md           |  11 +--
 nuxt/layouts/default.vue                |   8 --
 10 files changed, 7 insertions(+), 468 deletions(-)
 delete mode 100644 nuxt/components/DocsAskFab.vue
 delete mode 100644 nuxt/components/DocsExpertBrand.vue
 delete mode 100644 nuxt/components/DocsExpertHost.vue
 delete mode 100644 nuxt/components/content/DocsColumns.vue
 delete mode 100644 nuxt/components/content/FfExpertAsk.vue
 delete mode 100644 nuxt/composables/useDocsExpert.ts

diff --git a/nuxt/components/DocsAskFab.vue b/nuxt/components/DocsAskFab.vue
deleted file mode 100644
index 19fa8e5ab7..0000000000
--- a/nuxt/components/DocsAskFab.vue
+++ /dev/null
@@ -1,113 +0,0 @@
-<script setup lang="ts">
-// "Ask Docs": the one entry point to FlowFuse Expert on every docs page, floating in the
-// bottom-right corner at every screen width. It steps aside while a page's own question
-// box (FfExpertAsk) is on screen, since that box opens the same conversation.
-//
-// It wears FlowFuse Expert's colours, as the Expert button in the FlowFuse app does: the
-// FlowFuse mark, and a slowly turning brand-red to indigo border. Its box matches the
-// header's Book a demo button (40px tall, 16px text, 8px 16px padding), so the two calls
-// to action read as one family; the pill shape marks this one as floating.
-const inlineVisible = useExpertInlineVisible()
-
-function open () {
-    const capture = (window as any).capture
-    if (typeof capture === 'function') capture('cta-ai-get-started', { position: 'docs-fab' })
-    openDocsExpert()
-}
-</script>
-
-<template>
-  <Transition name="ff-ask-fab">
-    <button
-      v-show="!inlineVisible"
-      type="button"
-      class="ff-ask-fab"
-      title="Ask FlowFuse Expert about the docs"
-      @click="open"
-    >
-      <img :src="'/images/ff-minimal-red.svg'" alt="" class="ff-ask-fab__mark">
-      <span>Ask Docs</span>
-    </button>
-  </Transition>
-</template>
-
-<style scoped>
-@property --ff-ask-fab-angle {
-    syntax: '<angle>';
-    inherits: false;
-    initial-value: 135deg;
-}
-
-.ff-ask-fab {
-    position: fixed;
-    right: 1.5rem;
-    bottom: 1.5rem;
-    z-index: 60;
-    display: inline-flex;
-    align-items: center;
-    gap: 0.5rem;
-    height: 2.5rem;
-    padding: 8px 18px 8px 14px;
-    border: 1.5px solid transparent;
-    border-radius: 9999px;
-    background:
-        linear-gradient(#fff, #fff) padding-box,
-        conic-gradient(from var(--ff-ask-fab-angle), #DA3D0B, #9333EA, #4F46E5, #9333EA, #DA3D0B) border-box;
-    color: #111827;
-    font-size: 1rem;
-    font-weight: 600;
-    line-height: 1;
-    white-space: nowrap;
-    cursor: pointer;
-    box-shadow: 0 4px 8px rgb(17 24 39 / 0.08), 0 12px 28px -2px rgb(79 70 229 / 0.22);
-    transition: transform 0.15s ease, box-shadow 0.15s ease;
-}
-
-@media (prefers-reduced-motion: no-preference) {
-    .ff-ask-fab {
-        animation: ff-ask-fab-swirl 9s linear infinite;
-    }
-}
-
-.ff-ask-fab:hover {
-    background:
-        linear-gradient(#f5f5ff, #f5f5ff) padding-box,
-        conic-gradient(from var(--ff-ask-fab-angle), #DA3D0B, #9333EA, #4F46E5, #9333EA, #DA3D0B) border-box;
-    transform: translateY(-1px);
-    box-shadow: 0 6px 12px rgb(17 24 39 / 0.1), 0 16px 32px -4px rgb(79 70 229 / 0.3);
-}
-
-.ff-ask-fab:focus-visible {
-    outline: 2px solid #4F46E5;
-    outline-offset: 3px;
-}
-
-.ff-ask-fab__mark {
-    width: 1.25rem;
-    height: 1.25rem;
-    flex-shrink: 0;
-}
-
-@media (max-width: 639px) {
-    .ff-ask-fab {
-        right: 1rem;
-        bottom: 1rem;
-    }
-}
-
-@keyframes ff-ask-fab-swirl {
-    from { --ff-ask-fab-angle: 135deg; }
-    to { --ff-ask-fab-angle: 495deg; }
-}
-
-.ff-ask-fab-enter-active,
-.ff-ask-fab-leave-active {
-    transition: opacity 0.2s ease, transform 0.2s ease;
-}
-
-.ff-ask-fab-enter-from,
-.ff-ask-fab-leave-to {
-    opacity: 0;
-    transform: translateY(0.5rem);
-}
-</style>
diff --git a/nuxt/components/DocsExpertBrand.vue b/nuxt/components/DocsExpertBrand.vue
deleted file mode 100644
index aebe60ba3c..0000000000
--- a/nuxt/components/DocsExpertBrand.vue
+++ /dev/null
@@ -1,55 +0,0 @@
-<script setup lang="ts">
-// "FlowFuse Expert", the same in the page's question box (FfExpertAsk) and in the header of
-// the conversation modal (DocsExpertHost). When the box morphs into the modal,
-// src/js/ai-expert-modal.js finds both by data-ff-expert-brand and flies the box's one up
-// into the modal header, so the two have to stay the same size.
-defineProps<{
-    uid: string
-    /** Render "Expert" as the dialog's heading, with this id for its aria-labelledby. */
-    headingId?: string
-}>()
-</script>
-
-<template>
-  <div class="ff-expert-brand" data-ff-expert-brand>
-    <span class="ff-expert-brand__wordmark" role="img" aria-label="FlowFuse">
-      <FlowFuseWordmark :uid="uid" />
-    </span>
-    <h2 v-if="headingId" :id="headingId" class="ff-expert-brand__product">Expert</h2>
-    <span v-else class="ff-expert-brand__product">Expert</span>
-  </div>
-</template>
-
-<style scoped>
-/* Only as wide as its content, in the box as in the modal, so the flight between them moves
-   it without stretching it. */
-.ff-expert-brand {
-    display: flex;
-    align-items: center;
-    gap: 0.25rem;
-    width: fit-content;
-}
-
-.ff-expert-brand__wordmark {
-    display: inline-block;
-    width: 6rem;
-    height: 1.5rem;
-    line-height: 0;
-}
-
-.ff-expert-brand__product {
-    margin: 0 0 -0.25rem;
-    font-size: 1rem;
-    line-height: 1.5rem;
-    font-weight: 600;
-    color: #374151;
-}
-</style>
-
-<style>
-/* Same pace as the box morphing into the input area (src/css/style.css, morphing-content). */
-::view-transition-group(ff-expert-brand) {
-    animation-duration: 0.5s;
-    animation-timing-function: cubic-bezier(0.4, 0.0, 0.2, 1);
-}
-</style>
diff --git a/nuxt/components/DocsExpertHost.vue b/nuxt/components/DocsExpertHost.vue
deleted file mode 100644
index dcdae19734..0000000000
--- a/nuxt/components/DocsExpertHost.vue
+++ /dev/null
@@ -1,71 +0,0 @@
-<script setup lang="ts">
-// The FlowFuse Expert conversation modal, rendered once for every docs page by the layout.
-// src/js/ai-expert-modal.js drives it (see nuxt/composables/useDocsExpert.ts). The element ids
-// and the classes that script selects on are load-bearing: keep them as they are.
-onMounted(() => {
-    mountDocsExpert().catch(() => {})
-})
-</script>
-
-<template>
-  <div
-    id="ai-expert-modal"
-    class="fixed inset-0 bg-black/50 hidden items-center justify-center p-0 md:p-4 md:px-8 md:py-8 z-[9999]"
-    role="dialog"
-    aria-modal="true"
-    aria-labelledby="ai-expert-modal-title"
-    data-welcome="Hello! Ask me anything about FlowFuse or Node-RED, and I will answer from the documentation."
-  >
-    <div class="bg-white rounded-none md:rounded-lg shadow-xl w-full max-w-4xl h-full md:h-full flex flex-col relative">
-      <div class="ai-chat-box">
-        <div class="textarea-wrapper modal-header flex items-center justify-between px-4 py-3 rounded-t-none md:rounded-t-lg h-auto rounded-b-none mb-0">
-          <DocsExpertBrand uid="expert-modal" heading-id="ai-expert-modal-title" />
-          <button id="close-modal" type="button" class="text-gray-500 hover:text-gray-600" aria-label="Close dialog">
-            <svg width="24" height="24" viewBox="0 0 24 24" fill="none">
-              <path d="M18 6L6 18" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
-              <path d="M6 6l12 12" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
-            </svg>
-          </button>
-        </div>
-      </div>
-
-      <div class="flex-1 p-4 overflow-y-auto">
-        <div class="bg-indigo-100 rounded-lg mb-6 py-3 px-4">
-          <p class="text-indigo-700 text-sm m-0">
-            AI agent has access to all of FlowFuse's
-            <a href="/docs" class="underline">documentation and knowledge</a>,
-            <a href="/blog" class="underline">blogposts</a>, and more.
-          </p>
-        </div>
-        <div id="chat-messages" class="space-y-4 overflow-auto" />
-      </div>
-
-      <div class="p-4 bg-white rounded-b-none md:rounded-b-lg border-t border-gray-200">
-        <div id="action-buttons-container" class="pb-4 flex justify-between">
-          <button id="clear-conversation" type="button" class="bg-white border border-indigo-300 rounded-full text-sm py-2 px-3 disabled:opacity-50 disabled:cursor-not-allowed" disabled>
-            Start over
-          </button>
-          <div id="right-buttons" class="flex gap-2">
-            <button id="continue-to-app" type="button" class="textarea-wrapper bg-white rounded-full text-sm py-2 px-3 disabled:opacity-50 disabled:cursor-not-allowed transition-colors hidden inline-flex items-center gap-1">
-              Continue chat in <img :src="'/images/ff-minimal-red.svg'" alt="FlowFuse" class="w-5 h-5 inline-block">
-            </button>
-            <button id="stop-generation" type="button" class="bg-white border border-indigo-300 rounded-full text-sm flex items-center gap-2 py-2 px-3 hidden">
-              <div class="w-3 h-3 bg-gray-800 rounded-sm" />
-              Stop
-            </button>
-            <button id="send-message" type="button" class="bg-indigo-600 text-white border border-indigo-600 rounded-full text-sm py-2 px-3 disabled:opacity-50 disabled:cursor-not-allowed hover:bg-indigo-700 transition-colors" disabled>
-              Send
-            </button>
-          </div>
-        </div>
-        <div class="relative">
-          <textarea
-            id="modal-input"
-            placeholder="Ask a question, or give more detail about what you are trying to do"
-            class="w-full p-4 border-2 border-gray-300 rounded-lg resize-none focus:outline-none focus:border-indigo-500 text-gray-900 h-24 text-sm disabled:cursor-not-allowed disabled:bg-gray-50 disabled:text-gray-500"
-          />
-        </div>
-      </div>
-    </div>
-  </div>
-</template>
diff --git a/nuxt/components/DocsHeaderActions.vue b/nuxt/components/DocsHeaderActions.vue
index 845129922f..bfb6875ce3 100644
--- a/nuxt/components/DocsHeaderActions.vue
+++ b/nuxt/components/DocsHeaderActions.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 // Docs search for the site header, where the docs sidebar is not on screen. AppHeader shows
-// it below lg, on docs pages only. FlowFuse Expert is the Ask Docs button (DocsAskFab).
+// it below lg, on docs pages only.
 const route = useRoute()
 const isDocs = computed(() => route.path === '/docs' || route.path.startsWith('/docs/'))
 
diff --git a/nuxt/components/content/DocsColumns.vue b/nuxt/components/content/DocsColumns.vue
deleted file mode 100644
index 24035a6a35..0000000000
--- a/nuxt/components/content/DocsColumns.vue
+++ /dev/null
@@ -1,40 +0,0 @@
-<script setup lang="ts">
-// Two blocks side by side on wide screens, the first twice as wide as the second, stacked
-// on narrow ones. The docs home uses it to put the Expert question box next to the card
-// that leads to human support, so the section spans the page.
-//
-//   ::docs-columns
-//   :::ff-expert-ask
-//   :::
-//
-//   :::card{title="..." to="..."}
-//   ...
-//   :::
-//   ::
-</script>
-
-<template>
-  <div class="ff-docs-columns not-prose">
-    <slot />
-  </div>
-</template>
-
-<style scoped>
-.ff-docs-columns {
-    display: grid;
-    gap: 1.5rem;
-}
-
-/* The two blocks stretch to one height (grid items do by default), so a box beside a
-   taller card grows to match it. */
-@media (min-width: 1024px) {
-    .ff-docs-columns {
-        grid-template-columns: minmax(0, 2fr) minmax(0, 1fr);
-    }
-}
-
-.ff-docs-columns > :deep(*) {
-    margin-top: 0;
-    margin-bottom: 0;
-}
-</style>
diff --git a/nuxt/components/content/DocsSection.vue b/nuxt/components/content/DocsSection.vue
index 2160970f58..8d034fac38 100644
--- a/nuxt/components/content/DocsSection.vue
+++ b/nuxt/components/content/DocsSection.vue
@@ -68,26 +68,17 @@ const anchor = computed(() => props.id || props.title.toLowerCase().replace(/[^a
     gap: 1rem;
 }
 
-/* Cards that follow a two-column block (the Expert box and its neighbour) keep their
-   distance from it. */
-.ff-docs-section__body > :deep(.ff-docs-columns + .grid) {
-    margin-top: 1.5rem;
-}
-
 /* Without a lead line the cards would sit right under the heading. */
 .ff-docs-section__body > :deep(.grid:first-child) {
     margin-top: 2rem;
 }
 
-/* Cards hold a line or two, not an article: tighter than Nuxt UI's default card. The same
-   for a card in a card-group and one beside the Expert box in docs-columns. */
-.ff-docs-section__body > :deep(.grid > div),
-.ff-docs-section__body > :deep(.ff-docs-columns > .group) {
+/* Cards hold a line or two, not an article: tighter than Nuxt UI's default card. */
+.ff-docs-section__body > :deep(.grid > div) {
     padding: 1.25rem;
 }
 
-.ff-docs-section__body > :deep(.grid > div p),
-.ff-docs-section__body > :deep(.ff-docs-columns > .group p) {
+.ff-docs-section__body > :deep(.grid > div p) {
     margin: 0;
     font-size: 0.9375rem;
     line-height: 1.5;
diff --git a/nuxt/components/content/FfExpertAsk.vue b/nuxt/components/content/FfExpertAsk.vue
deleted file mode 100644
index 12812860f0..0000000000
--- a/nuxt/components/content/FfExpertAsk.vue
+++ /dev/null
@@ -1,113 +0,0 @@
-<script setup lang="ts">
-// FlowFuse Expert, embedded in a page: a question box that opens the Expert conversation.
-//
-// The conversation itself is src/js/ai-expert-modal.js, the script the old /ai/ page used,
-// driving the modal that DocsExpertHost renders in the layout. The script listens for the
-// #tell-me-how-btn button and morphs this card (the .textarea-wrapper holding the
-// data-ff-expert-input textarea) into the modal. Keep those hooks as they are.
-//
-// Usage from markdown:
-//   ::ff-expert-ask
-//   ::
-const props = withDefaults(defineProps<{
-    placeholder?: string
-    button?: string
-    position?: string
-}>(), {
-    placeholder: 'Ask a question about FlowFuse or Node-RED',
-    button: 'Ask Docs',
-    position: 'docs-home',
-})
-
-const root = ref<HTMLElement>()
-const inlineVisible = useExpertInlineVisible()
-let observer: IntersectionObserver | undefined
-
-onMounted(() => {
-    observer = new IntersectionObserver(([entry]) => {
-        inlineVisible.value = entry.isIntersecting
-    })
-    if (root.value) observer.observe(root.value)
-})
-
-onBeforeUnmount(() => {
-    observer?.disconnect()
-    inlineVisible.value = false
-})
-
-function track () {
-    const capture = (window as any).capture
-    if (typeof capture === 'function') capture('cta-ai-get-started', { position: props.position })
-}
-</script>
-
-<template>
-  <div ref="root" class="ff-expert-ask not-prose mt-6 max-w-4xl">
-    <div class="ai-chat-box ff-expert-ask__box">
-      <div class="textarea-wrapper ff-expert-ask__card relative rounded-lg overflow-hidden">
-        <div class="ff-expert-ask__brand">
-          <DocsExpertBrand uid="expert-ask" />
-        </div>
-        <div class="ff-expert-ask__input relative p-4 pb-12">
-          <textarea
-            data-ff-expert-input
-            :placeholder="placeholder"
-            class="w-full bg-transparent border-0 focus:outline-none text-gray-600 placeholder-gray-400 resize-none"
-            aria-label="Ask FlowFuse Expert"
-          />
-          <div class="absolute bottom-3 left-4 text-[10px] font-light text-gray-500 pr-36 line-clamp-2">
-            AI uses FlowFuse's knowledge base
-          </div>
-          <button
-            id="tell-me-how-btn"
-            type="button"
-            class="absolute bottom-3 right-4 ff-btn ff-btn--highlight whitespace-nowrap px-6 py-3"
-            @click="track"
-          >
-            {{ button }}
-          </button>
-        </div>
-      </div>
-    </div>
-  </div>
-</template>
-
-<style scoped>
-/* The box fills whatever width and height it is given, so beside a taller card
-   (DocsColumns) the two stand the same height and the box spans its column. */
-.ff-expert-ask {
-    display: flex;
-}
-
-.ff-expert-ask__box {
-    display: flex;
-    flex: 1;
-    min-width: 0;
-}
-
-.ff-expert-ask__card {
-    flex: 1;
-    display: flex;
-    flex-direction: column;
-}
-
-.ff-expert-ask__input {
-    flex: 1;
-    display: flex;
-    flex-direction: column;
-    min-height: 8rem;
-}
-
-.ff-expert-ask__input textarea {
-    flex: 1;
-}
-
-/* Same padding as the modal header, so the brand flies between matching spots. */
-.ff-expert-ask__brand {
-    padding: 0.75rem 1rem;
-    border-bottom: 1px solid transparent;
-    background:
-        linear-gradient(#fff, #fff) padding-box,
-        linear-gradient(90deg, #f87171, #f472b6, #a78bfa) border-box;
-}
-</style>
diff --git a/nuxt/composables/useDocsExpert.ts b/nuxt/composables/useDocsExpert.ts
deleted file mode 100644
index 38e063af64..0000000000
--- a/nuxt/composables/useDocsExpert.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-// FlowFuse Expert on the docs pages.
-//
-// The conversation is src/js/ai-expert-modal.js, shared with the Eleventy site. It binds to
-// the modal that DocsExpertHost renders once in the layout, and exposes window.ffExpertOpen
-// so any button on the page can open it. The embedded question box (FfExpertAsk) needs no
-// call from here: the script listens for its button and prompt pills itself.
-
-const DOMPURIFY = 'https://cdn.jsdelivr.net/npm/dompurify@3.3.0/dist/purify.min.js'
-const SCRIPT = '/js/ai-expert-modal.js'
-
-let ready: Promise<void> | null = null
-
-function loadScript (src: string) {
-    return new Promise<void>((resolve, reject) => {
-        const el = document.createElement('script')
-        el.src = src
-        el.onload = () => resolve()
-        el.onerror = () => reject(new Error(`failed to load ${src}`))
-        document.body.appendChild(el)
-    })
-}
-
-/** Called by DocsExpertHost once its modal is in the DOM. */
-export function mountDocsExpert (): Promise<void> {
-    ready = (async () => {
-        const w = window as any
-        // The script sanitises every answer with DOMPurify before rendering it.
-        if (!w.DOMPurify) await loadScript(DOMPURIFY)
-        // Loading the script runs it. If it is already loaded (the host mounted again after
-        // leaving the docs and coming back), ask it to bind to the new modal instead.
-        if (w.ffExpertInit) w.ffExpertInit()
-        else await loadScript(SCRIPT)
-    })()
-    return ready
-}
-
-/** Open the Expert conversation, optionally starting it with a question. */
-export function openDocsExpert (text = '') {
-    const open = () => (window as any).ffExpertOpen?.(text)
-    if (ready) ready.then(open).catch(() => {})
-    else open()
-}
-
-/** Whether the embedded question box is on screen, so other entry points can step aside. */
-export function useExpertInlineVisible () {
-    return useState<boolean>('ff-expert-inline-visible', () => false)
-}
diff --git a/nuxt/content-guides/README.md b/nuxt/content-guides/README.md
index fb44b053eb..699909d3d1 100644
--- a/nuxt/content-guides/README.md
+++ b/nuxt/content-guides/README.md
@@ -218,21 +218,16 @@ Walkthroughs and recorded talks.
 :::
 ::
 
-::docs-section{eyebrow="Help" title="Ask a question" cols="3"}
-Ask FlowFuse Expert, which answers from these docs, the blog and more. Or put your question to our support team, the community, or the troubleshooting guides.
-
-:::docs-columns
-::::ff-expert-ask
-::::
+::docs-section{eyebrow="Help" title="Ask a question" cols="2"}
+Put your question to our support team, the community, or the troubleshooting guides.
 
+:::card-group
 ::::card{icon="i-lucide-headset"}
 [Talk to our support team :icon{name="i-lucide-arrow-up-right"}](/support/)
 
 Search the Help Center or submit a ticket. For Cloud and Enterprise customers.
 ::::
-:::
 
-:::card-group
 ::::card{icon="i-lucide-bug"}
 [Debugging Node-RED](/docs/debugging/)
 
diff --git a/nuxt/layouts/default.vue b/nuxt/layouts/default.vue
index e0dd47141c..0a2dd11857 100644
--- a/nuxt/layouts/default.vue
+++ b/nuxt/layouts/default.vue
@@ -1,8 +1,3 @@
-<script setup lang="ts">
-const route = useRoute()
-const isDocs = computed(() => route.path === '/docs' || route.path.startsWith('/docs/'))
-</script>
-
 <template>
   <div class="font-sans ff-website leading-normal tracking-normal gradient text-gray-500 min-h-screen flex flex-col">
     <a href="#main-content" class="skip-to-main">Skip to main content</a>
@@ -19,8 +14,5 @@ const isDocs = computed(() => route.path === '/docs' || route.path.startsWith('/
       </div>
     </div>
     <AppFooter />
-    <!-- FlowFuse Expert's conversation, opened from Ask Docs and from a page's own question box. -->
-    <DocsExpertHost v-if="isDocs" />
-    <DocsAskFab v-if="isDocs" />
   </div>
 </template>

From 9f91b7d2cb3202466974721d153a15a761bf79b3 Mon Sep 17 00:00:00 2001
From: Dimitrie Hoekstra <hi@dimitr.ie>
Date: Tue, 29 Sep 2026 14:20:54 +0200
Subject: [PATCH 31/31] header: "Docs" beside the logo as a small superscript

At the wordmark's own size (29px, weight 600) the label read as a second
logo on every docs page. It is now 13px, grey, set high beside the logo
with its capital level with the wordmark's, like a superscript: it still
says this is the docs, without competing with the brand.

The smaller label frees room on phones, so Book a demo now gives way only
below 360px instead of below 390px (at 360px the row has 20px to spare).
The mark-only logo below xl stays: with the whole wordmark the menus
would come within about 28px of "Docs" at 1100px.
---
 nuxt/components/AppHeader.vue | 36 ++++++++++++++++-------------------
 1 file changed, 16 insertions(+), 20 deletions(-)

diff --git a/nuxt/components/AppHeader.vue b/nuxt/components/AppHeader.vue
index 405a200e9c..bf8fac8ce1 100644
--- a/nuxt/components/AppHeader.vue
+++ b/nuxt/components/AppHeader.vue
@@ -220,7 +220,7 @@ onMounted(() => {
 
 <style scoped>
 /* Docs pages show "Docs" beside the logo. Below xl that pair is the mark alone and
-   "Docs": with the whole wordmark, the menus came within 16px of "Docs" at 1100px. The
+   "Docs": with the whole wordmark, the menus come within about 28px of "Docs" at 1100px. The
    mark is the wordmark itself, cropped to its first 28px, rather than the separate square
    logo, which is drawn larger and in a lighter red: the logo keeps one shape, colour and
    size at every width, and only its lettering comes and goes. */
@@ -245,24 +245,20 @@ onMounted(() => {
     }
 }
 
-/* Beside the wordmark, "Docs" reads as one lockup with it, measured at 4x zoom:
-   - weight 600: its stems (3.5px at this size) sit just under the wordmark's (3.9px), close
-     enough to belong to it, a step lighter so it does not compete (700 matched the stems
-     but read too heavy, 400 too thin);
-   - 29px, which splits Heebo's proportions against the wordmark's: capitals 0.6px taller
-     (20.6 against 20) and lowercase 0.4px shorter (15.6 against 16);
-   - the same baseline: with line-height 1, centred on the 32px logo box, the line sits 1px
-     high, hence the nudge.
-   Grey, so the brand colour still leads. The same size at every width, beside the mark
-   alone as beside the whole wordmark. */
+/* "Docs" sits high beside the logo, small, like a superscript. At the wordmark's own size
+   it read as a second logo on every docs page; this says where you are without competing
+   with it. The 4px drop puts the top of its capital level with the wordmark's (measured at
+   4x zoom), rather than floating above it. Grey, so the brand colour still leads, and the
+   same size at every width. */
 .ff-docs-brand-label {
-    position: relative;
-    top: 1px;
-    margin-left: 0.625rem;
-    font-size: 29px;
+    align-self: flex-start;
+    margin-top: 4px;
+    margin-left: 0.25rem;
+    font-size: 0.8125rem;
     line-height: 1;
     font-weight: 600;
-    color: #374151;
+    letter-spacing: 0.02em;
+    color: #6b7280;
     white-space: nowrap;
     text-decoration: none;
 }
@@ -271,10 +267,10 @@ onMounted(() => {
     color: #4f46e5;
 }
 
-/* On a phone narrower than 390px the docs header has no room for the mark, "Docs", search,
-   Book a demo and the menu at once ("Docs" touched the search at 360 and 375px, and the row
-   overflowed at 320px), so Book a demo gives way there. From 390px it fits. */
-@media (max-width: 389px) {
+/* On a phone narrower than 360px the docs header has no room for the mark, "Docs", search,
+   Book a demo and the menu at once ("Docs" touches the search at 320px), so Book a demo
+   gives way there. From 360px it fits, with 20px to spare. */
+@media (max-width: 359px) {
     .ff-header--docs .ff-header-demo-mobile {
         display: none;
     }