diff --git a/nuxt/assets/css/style.css b/nuxt/assets/css/style.css
index 79076bf728..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 {
@@ -999,8 +1004,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
diff --git a/nuxt/components/AlgoliaSearch.vue b/nuxt/components/AlgoliaSearch.vue
index 7cfab36266..53198724c4 100644
--- a/nuxt/components/AlgoliaSearch.vue
+++ b/nuxt/components/AlgoliaSearch.vue
@@ -7,14 +7,58 @@ 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
+    /** `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)
+
+// 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()
+}
+
+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>()
 
 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 }
@@ -56,6 +100,16 @@ 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).
+        // 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
@@ -81,9 +135,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 +179,164 @@ onMounted(async () => {
             }
         }
     })
+
+    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>
 
 <template>
-  <div ref="searchContainer" id="algolia-search" class="border border-gray-200 rounded"></div>
+  <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>
+
+<style scoped>
+.ff-algolia--detached {
+    position: relative;
+}
+
+/* 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: 0 4rem 0 0.5rem;
+    border: 1px solid #d1d5db;
+    border-radius: 6px;
+    background: #fff;
+    font-size: 0.875rem;
+    color: #6b7280;
+    cursor: pointer;
+}
+
+.ff-algolia--detached :deep(#algolia-search .aa-DetachedSearchButton:hover) {
+    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;
+    border-radius: 8px;
+    font-size: 1rem;
+}
+
+.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. */
+.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>
diff --git a/nuxt/components/AppHeader.vue b/nuxt/components/AppHeader.vue
index d9b297485f..bf8fac8ce1 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,20 @@ 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]">
 
+      <!-- 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 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>
@@ -146,9 +152,15 @@ 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">
-        <CtaBookDemo variant="primary" position="header-mobile" />
+        <DocsHeaderActions />
+        <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>
@@ -184,7 +196,11 @@ 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">
-        <li class="hidden md:flex"><CtaSignUp variant="nav-text" position="main-nav" padded class="ff-nav-freetrial text-base" /></li>
+        <!-- Docs search, on tablets, where the docs sidebar is folded away. -->
+        <li v-if="isDocs" class="lg:hidden mr-1"><DocsHeaderActions /></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>
@@ -201,3 +217,62 @@ onMounted(() => {
     </div>
   </header>
 </template>
+
+<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 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. */
+.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 {
+        width: 28px;
+        overflow: hidden;
+    }
+
+    .ff-header--docs .ff-logo-link--wordmark svg {
+        width: 160px;
+        max-width: none;
+        flex-shrink: 0;
+    }
+}
+
+/* "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 {
+    align-self: flex-start;
+    margin-top: 4px;
+    margin-left: 0.25rem;
+    font-size: 0.8125rem;
+    line-height: 1;
+    font-weight: 600;
+    letter-spacing: 0.02em;
+    color: #6b7280;
+    white-space: nowrap;
+    text-decoration: none;
+}
+
+.ff-docs-brand-label:hover {
+    color: #4f46e5;
+}
+
+/* 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;
+    }
+}
+</style>
diff --git a/nuxt/components/DocsHeaderActions.vue b/nuxt/components/DocsHeaderActions.vue
new file mode 100644
index 0000000000..bfb6875ce3
--- /dev/null
+++ b/nuxt/components/DocsHeaderActions.vue
@@ -0,0 +1,47 @@
+<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.
+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>
+  </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>
diff --git a/nuxt/components/DocsLeftNav.vue b/nuxt/components/DocsLeftNav.vue
index 111f65f44f..2655aafc9c 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),
@@ -17,5 +18,43 @@ 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">
+    <!-- Below lg the header carries a search button instead. This stays mounted there, hidden,
+         because that button opens this component's dialog. -->
+    <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" 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;
+    }
+}
+
+/* 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/components/SidebarNav.vue b/nuxt/components/SidebarNav.vue
index 4dd32dfe6c..aa7621b46b 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.75rem;
+}
+</style>
diff --git a/nuxt/components/content/DocsChoice.vue b/nuxt/components/content/DocsChoice.vue
new file mode 100644
index 0000000000..fd98faea09
--- /dev/null
+++ b/nuxt/components/content/DocsChoice.vue
@@ -0,0 +1,173 @@
+<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 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
+    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);
+}
+
+/* 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) {
+    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..66178b665c
--- /dev/null
+++ b/nuxt/components/content/DocsChoices.vue
@@ -0,0 +1,97 @@
+<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.
+//
+// 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 ref="list" 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;
+    /* 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
new file mode 100644
index 0000000000..d37596bbb4
--- /dev/null
+++ b/nuxt/components/content/DocsHero.vue
@@ -0,0 +1,222 @@
+<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;
+}
+
+/* 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: start;
+    }
+}
+
+.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..8d034fac38
--- /dev/null
+++ b/nuxt/components/content/DocsSection.vue
@@ -0,0 +1,215 @@
+<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;
+}
+
+/* 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) {
+    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-guides/README.md b/nuxt/content-guides/README.md
new file mode 100644
index 0000000000..699909d3d1
--- /dev/null
+++ b/nuxt/content-guides/README.md
@@ -0,0 +1,249 @@
+---
+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/)
+- [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/)
+- [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/)
+- [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/)
+- [About FlowFuse applications](/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="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{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/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/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/>')
diff --git a/nuxt/pages/docs/[...slug].vue b/nuxt/pages/docs/[...slug].vue
index 635cbb20f7..518ea3abaf 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,18 @@ 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">
+    <!-- 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>
+
+  <!-- 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 -->
@@ -117,14 +132,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 :items="breadcrumbItems" />
             </div>
-            <div class="w-full mb-1">
-              <AlgoliaSearch index-filter="category:docs" placeholder="Search in Docs..." source-id="docs" />
-            </div>
           </div>
         </div>
 
@@ -142,13 +154,18 @@ 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">
-          <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">
+        <!-- On wide screens the column never runs past the bottom of the window: a long table
+             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', 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>
           <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>