From 2d745edfb429a14f19d83c3a962d609057b98290 Mon Sep 17 00:00:00 2001
From: Saxon Fletcher <saxonafletcher@gmail.com>
Date: Tue, 21 Jul 2026 14:30:36 +1000
Subject: [PATCH 1/7] Landing page agent focus (#47989)

---
 apps/docs/app/page.tsx                        | 105 +++---
 apps/docs/components/DocsCoverLogo.tsx        |   6 +-
 .../components/HomePageCover.constants.ts     |   9 +
 apps/docs/components/HomePageCover.tsx        | 305 +++++++++---------
 apps/docs/features/docs/MdxBase.shared.tsx    |   8 +-
 apps/docs/features/ui/CodeBlock/CodeBlock.tsx |   4 +-
 apps/docs/features/ui/PromptPanel.tsx         | 304 +++++++++++++++++
 .../internals/generate-guides-markdown.ts     |   2 +
 .../markdown-schema/PromptPanel.test.ts       |  72 +++++
 .../internals/markdown-schema/PromptPanel.ts  |  22 ++
 apps/docs/layouts/HomeLayout.tsx              |  19 +-
 packages/config/css/animations.css            |   9 +
 packages/config/css/utilities.css             | 106 ++++++
 13 files changed, 781 insertions(+), 190 deletions(-)
 create mode 100644 apps/docs/components/HomePageCover.constants.ts
 create mode 100644 apps/docs/features/ui/PromptPanel.tsx
 create mode 100644 apps/docs/internals/markdown-schema/PromptPanel.test.ts
 create mode 100644 apps/docs/internals/markdown-schema/PromptPanel.ts

diff --git a/apps/docs/app/page.tsx b/apps/docs/app/page.tsx
index 31eba97aef4e2..031a06a61a47b 100644
--- a/apps/docs/app/page.tsx
+++ b/apps/docs/app/page.tsx
@@ -5,6 +5,7 @@ import { cn } from 'ui'
 import { IconPanel } from 'ui-patterns/IconPanel'
 import { TextLink } from 'ui-patterns/TextLink'
 
+import { FrameworkQuickstarts } from '@/components/HomePageCover'
 import { MIGRATION_PAGES } from '@/components/Navigation/NavigationMenu/NavigationMenu.constants'
 import { GlassPanelWithIconPicker } from '@/features/ui/GlassPanelWithIconPicker'
 import { IconPanelWithIconPicker } from '@/features/ui/IconPanelWithIconPicker'
@@ -45,7 +46,7 @@ const products = [
     href: '/guides/database/overview',
     description:
       'Supabase provides a full Postgres database for every project with Realtime functionality, database backups, extensions, and more.',
-    span: 'col-span-12 md:col-span-6',
+    span: 'col-span-12',
   },
   {
     title: 'Auth',
@@ -226,26 +227,55 @@ const additionalResources = [
 const HomePage = () => (
   <HomeLayout>
     <div className="flex flex-col">
-      <h2 id="products">Products</h2>
-      <ul className="grid grid-cols-12 gap-6 not-prose [&_svg]:text-brand-600">
-        {products.map((product) => {
-          return (
-            <li key={product.title} className={cn(product.span ?? 'col-span-12 md:col-span-4')}>
-              <Link href={product.href} passHref>
-                <GlassPanelWithIconPicker {...product}>
-                  {product.description}
-                </GlassPanelWithIconPicker>
-              </Link>
-            </li>
-          )
-        })}
-      </ul>
+      {isFeatureEnabled('docs:full_getting_started') && (
+        <div className="flex flex-col gap-6 border-b py-12 lg:grid lg:grid-cols-12 lg:gap-x-16">
+          <div className="col-span-4 flex flex-col gap-1 [&_h2]:m-0">
+            <h2 id="connect-a-framework" className="group scroll-mt-24">
+              Connect a framework
+            </h2>
+            <p className="m-0 p-0 text-sm text-foreground-light">
+              Start with a framework quickstart and connect your project in minutes.
+            </p>
+          </div>
+
+          <div className="col-span-8 not-prose">
+            <FrameworkQuickstarts />
+          </div>
+        </div>
+      )}
+      <div className="flex flex-col gap-6 border-b py-12 lg:grid lg:grid-cols-12 lg:gap-x-16">
+        <div className="col-span-4 flex flex-col gap-1 [&_h2]:m-0">
+          <h2 id="products" className="group scroll-mt-24">
+            Build your backend
+          </h2>
+          <p className="m-0 p-0 text-sm text-foreground-light">
+            Build with a complete backend platform, from your database to your application logic.
+          </p>
+        </div>
 
-      <div className="flex flex-col lg:grid grid-cols-12 gap-6 py-12 border-b">
-        <div className="col-span-4">
-          <h2 id="postgres-integrations" className="scroll-mt-24 m-0">
-            Modules
+        <ul className="col-span-8 grid grid-cols-12 gap-6 not-prose [&_svg]:text-brand-600">
+          {products.map((product) => {
+            return (
+              <li key={product.title} className={cn(product.span ?? 'col-span-12 md:col-span-6')}>
+                <Link href={product.href} passHref>
+                  <GlassPanelWithIconPicker {...product}>
+                    {product.description}
+                  </GlassPanelWithIconPicker>
+                </Link>
+              </li>
+            )
+          })}
+        </ul>
+      </div>
+
+      <div className="flex flex-col gap-6 border-b py-12 lg:grid lg:grid-cols-12 lg:gap-x-16">
+        <div className="col-span-4 flex flex-col gap-1 [&_h2]:m-0">
+          <h2 id="postgres-integrations" className="scroll-mt-24">
+            Extend your database
           </h2>
+          <p className="m-0 p-0 text-sm text-foreground-light">
+            Extend your database with built-in tools for AI, APIs, scheduled jobs, and queues.
+          </p>
         </div>
         <div className="grid col-span-8 grid-cols-12 gap-6 not-prose">
           {postgresIntegrations.map((integration) => (
@@ -261,15 +291,14 @@ const HomePage = () => (
         </div>
       </div>
 
-      <div className="flex flex-col lg:grid grid-cols-12 gap-6 py-12 border-b">
+      <div className="flex flex-col gap-6 border-b py-12 lg:grid lg:grid-cols-12 lg:gap-x-16">
         <div className="col-span-4 flex flex-col gap-1 [&_h2]:m-0 [&_h3]:m-0">
-          <div className="md:max-w-xs 2xl:max-w-none">
-            <div className="flex items-center gap-3 mb-3 text-brand-600">
-              <h2 id="client-libraries" className="group scroll-mt-24">
-                Client Libraries
-              </h2>
-            </div>
-          </div>
+          <h2 id="client-libraries" className="group scroll-mt-24">
+            Use a client library
+          </h2>
+          <p className="m-0 p-0 text-sm text-foreground-light">
+            Use Supabase from the language and framework your application is built with.
+          </p>
         </div>
 
         <div className="grid col-span-8 grid-cols-12 gap-6 not-prose">
@@ -291,7 +320,7 @@ const HomePage = () => (
         </div>
       </div>
       {isFeatureEnabled('docs:full_getting_started') && (
-        <div className="flex flex-col lg:grid grid-cols-12 gap-6 py-12 border-b">
+        <div className="flex flex-col gap-6 border-b py-12 lg:grid lg:grid-cols-12 lg:gap-x-16">
           <div className="col-span-4 flex flex-col gap-1 [&_h2]:m-0">
             <h2 id="migrate-to-supabase" className="group scroll-mt-24">
               Migrate to Supabase
@@ -322,20 +351,22 @@ const HomePage = () => (
         </div>
       )}
 
-      <div className="flex flex-col gap-6 py-12 border-b">
-        <div className="col-span-4 flex flex-col gap-1">
-          <h2 id="additional-resources" className="group scroll-mt-24 m-0">
-            Additional resources
+      <div className="flex flex-col gap-6 border-b py-12 lg:grid lg:grid-cols-12 lg:gap-x-16">
+        <div className="col-span-4 flex flex-col gap-1 [&_h2]:m-0">
+          <h2 id="additional-resources" className="group scroll-mt-24">
+            Explore more
           </h2>
+          <p className="m-0 p-0 text-sm text-foreground-light">
+            Explore the tools, integrations, and guides that help you get more from Supabase.
+          </p>
         </div>
 
-        <ul className="grid grid-cols-12 gap-6 not-prose">
+        <ul className="col-span-8 grid grid-cols-12 gap-6 not-prose">
           {additionalResources.map((resource) => {
             return (
-              <li key={resource.title} className="col-span-12 md:col-span-6 lg:col-span-3">
+              <li key={resource.title} className="col-span-12 md:col-span-6">
                 <Link
                   href={resource.href}
-                  className="col-span-12 md:col-span-6 lg:col-span-3"
                   passHref
                   target={resource.external ? '_blank' : undefined}
                 >
@@ -349,12 +380,12 @@ const HomePage = () => (
         </ul>
       </div>
       {isFeatureEnabled('docs:full_getting_started') && (
-        <div className="flex flex-col lg:grid grid-cols-12 gap-6 py-12">
+        <div className="flex flex-col gap-6 py-12 lg:grid lg:grid-cols-12 lg:gap-x-16">
           <div className="col-span-4 flex flex-col gap-1">
             <div className="md:max-w-xs 2xl:max-w-none">
               <div className="flex items-center gap-3 mb-3 text-brand-600">
                 <h2 id="self-hosting" className="group scroll-mt-24 m-0">
-                  Self-Hosting
+                  Self-host Supabase
                 </h2>
               </div>
               <p className="text-foreground-light text-sm m-0 p-0">
diff --git a/apps/docs/components/DocsCoverLogo.tsx b/apps/docs/components/DocsCoverLogo.tsx
index 3b56575513fc5..eebc87c0092b9 100644
--- a/apps/docs/components/DocsCoverLogo.tsx
+++ b/apps/docs/components/DocsCoverLogo.tsx
@@ -1,9 +1,9 @@
 'use client'
 
 import { domAnimation, LazyMotion, m } from 'framer-motion'
-import React, { type PropsWithChildren } from 'react'
+import React, { type ComponentPropsWithoutRef } from 'react'
 
-const DocsCoverLogo = (props: PropsWithChildren) => {
+const DocsCoverLogo = ({ className, ...props }: ComponentPropsWithoutRef<'div'>) => {
   const pathMotionConfig = {
     initial: { pathLength: 0 },
     animate: { pathLength: 1 },
@@ -24,7 +24,7 @@ const DocsCoverLogo = (props: PropsWithChildren) => {
   }
 
   return (
-    <div className="w-[60px] md:w-[150px] [&_svg]" {...props}>
+    <div className={className} {...props}>
       <LazyMotion features={domAnimation}>
         <m.svg
           width="100%"
diff --git a/apps/docs/components/HomePageCover.constants.ts b/apps/docs/components/HomePageCover.constants.ts
new file mode 100644
index 0000000000000..18155403fbf27
--- /dev/null
+++ b/apps/docs/components/HomePageCover.constants.ts
@@ -0,0 +1,9 @@
+export const setupCommand = {
+  installCli: 'npm install -g supabase',
+  installPlugin: 'npx plugins add supabase-community/supabase-plugin',
+  initialize: 'supabase init',
+} as const
+
+export const setupCommands = [setupCommand.installCli, setupCommand.installPlugin].join('\n')
+
+export const setupPrompt = `Help me get set up with Supabase. Do the following: 1. Install the Supabase CLI globally with \`${setupCommand.installCli}\`. 2. Install the Supabase Plugin with \`${setupCommand.installPlugin}\`. 3. Review my project and determine whether Supabase is already initialized. If it is not initialized, run \`${setupCommand.initialize}\`. 4. Suggest the most relevant next steps.`
diff --git a/apps/docs/components/HomePageCover.tsx b/apps/docs/components/HomePageCover.tsx
index f7973dbe089f3..c98b765bc5ba1 100644
--- a/apps/docs/components/HomePageCover.tsx
+++ b/apps/docs/components/HomePageCover.tsx
@@ -1,180 +1,195 @@
 'use client'
 
-// End of third-party imports
+import {
+  Prompt,
+  PromptContent,
+  PromptCopy,
+  PromptPanel,
+  PromptTitle,
+} from '~/features/ui/PromptPanel'
 import { isFeatureEnabled, useBreakpoint } from 'common'
-import { ChevronRight, Sparkles } from 'lucide-react'
+import { Sparkles, Terminal } from 'lucide-react'
 import { useTheme } from 'next-themes'
 import Link from 'next/link'
-import { cn } from 'ui'
+import { useEffect, useState, type ReactNode } from 'react'
 import { IconPanel } from 'ui-patterns/IconPanel'
 
 import { getCustomContent } from '../lib/custom-content/getCustomContent'
 import DocsCoverLogo from './DocsCoverLogo'
+import { setupCommand, setupCommands, setupPrompt } from './HomePageCover.constants'
 
 const {
   sdkDart: sdkDartEnabled,
   sdkKotlin: sdkKotlinEnabled,
   sdkSwift: sdkSwiftEnabled,
 } = isFeatureEnabled(['sdk:dart', 'sdk:kotlin', 'sdk:swift'])
+const fullGettingStartedEnabled = isFeatureEnabled('docs:full_getting_started')
 
-function AiPrompt({ className }: { className?: string }) {
+function SetupPrompt({ cliCode }: { cliCode: ReactNode }) {
   return (
-    <Link
-      className={cn(
-        'group',
-        'w-fit rounded-full border px-3 py-1 flex gap-2 items-center text-foreground-light text-sm',
-        'hover:border-brand hover:text-brand-link focus-visible:text-brand-link',
-        'transition-colors',
-        className
-      )}
-      href="/guides/ai-tools/ai-prompts"
-    >
-      <Sparkles size={14} />
-      Start with Supabase AI prompts
-      <ChevronRight size={14} className="group-hover:translate-x-1 transition-transform" />
-    </Link>
+    <PromptPanel>
+      <Prompt value="prompt" expandable>
+        <PromptTitle icon={<Sparkles />}>AI Prompt</PromptTitle>
+        <PromptCopy>{setupPrompt}</PromptCopy>
+        <PromptContent>
+          Help me get set up with Supabase. Do the following: 1. Install the Supabase CLI globally
+          with{' '}
+          <code className="shimmer-none rounded bg-surface-200 px-1 py-0.5 font-mono text-xs text-foreground">
+            {setupCommand.installCli}
+          </code>
+          . 2. Install the Supabase Plugin with{' '}
+          <code className="shimmer-none rounded bg-surface-200 px-1 py-0.5 font-mono text-xs text-foreground">
+            {setupCommand.installPlugin}
+          </code>
+          . 3. Review my project and determine whether Supabase is already initialized. If it is not
+          initialized, run{' '}
+          <code className="shimmer-none rounded bg-surface-200 px-1 py-0.5 font-mono text-xs text-foreground">
+            {setupCommand.initialize}
+          </code>
+          . 4. Suggest the most relevant next steps.
+        </PromptContent>
+      </Prompt>
+      <Prompt value="cli">
+        <PromptTitle icon={<Terminal />}>CLI</PromptTitle>
+        <PromptCopy>{setupCommands}</PromptCopy>
+        <PromptContent shimmer={false}>{cliCode}</PromptContent>
+      </Prompt>
+    </PromptPanel>
   )
 }
 
-const HomePageCover = (props) => {
+const frameworks = [
+  {
+    tooltip: 'ReactJS',
+    icon: '/docs/img/icons/react-icon',
+    href: '/guides/getting-started/quickstarts/reactjs',
+    hasLightIcon: false,
+  },
+  {
+    tooltip: 'Next.js',
+    icon: '/docs/img/icons/nextjs-icon',
+    href: '/guides/getting-started/quickstarts/nextjs',
+    hasLightIcon: false,
+  },
+  {
+    tooltip: 'TanStack Start',
+    icon: '/docs/img/icons/tanstack-icon',
+    href: '/guides/getting-started/quickstarts/tanstack',
+    hasLightIcon: true,
+  },
+  {
+    tooltip: 'Astro.js',
+    icon: '/docs/img/icons/astro-icon',
+    href: '/guides/getting-started/quickstarts/astrojs',
+    hasLightIcon: true,
+  },
+  {
+    tooltip: 'Vue',
+    icon: '/docs/img/icons/vuejs-icon',
+    href: '/guides/getting-started/quickstarts/vue',
+    hasLightIcon: false,
+  },
+  {
+    tooltip: 'Nuxt',
+    icon: '/docs/img/icons/nuxt-icon',
+    href: '/guides/getting-started/quickstarts/nuxtjs',
+    hasLightIcon: false,
+  },
+  {
+    tooltip: 'iOS Swift',
+    icon: '/docs/img/icons/swift-icon-orange',
+    href: '/guides/getting-started/quickstarts/ios-swiftui',
+    enabled: sdkSwiftEnabled,
+    hasLightIcon: false,
+  },
+  {
+    tooltip: 'Android Kotlin',
+    icon: '/docs/img/icons/kotlin-icon',
+    href: '/guides/getting-started/quickstarts/kotlin',
+    enabled: sdkKotlinEnabled,
+    hasLightIcon: false,
+  },
+  {
+    tooltip: 'Expo React Native',
+    icon: '/docs/img/icons/expo-icon',
+    href: '/guides/getting-started/quickstarts/expo-react-native',
+    hasLightIcon: true,
+  },
+  {
+    tooltip: 'Flutter',
+    icon: '/docs/img/icons/flutter-icon',
+    href: '/guides/getting-started/quickstarts/flutter',
+    enabled: sdkDartEnabled,
+    hasLightIcon: false,
+  },
+  {
+    tooltip: 'Python',
+    icon: '/docs/img/icons/python-icon',
+    href: '/guides/getting-started/quickstarts/flask',
+    hasLightIcon: false,
+  },
+]
+
+export function FrameworkQuickstarts() {
   const isXs = useBreakpoint(639)
   const iconSize = isXs ? 'sm' : 'lg'
-  const { homepageHeading } = getCustomContent(['homepage:heading'])
   const { resolvedTheme } = useTheme()
-  const isLightMode = !resolvedTheme?.includes('dark')
+  const [isMounted, setIsMounted] = useState(false)
+  const isLightMode = isMounted && resolvedTheme === 'light'
 
-  const frameworks = [
-    {
-      tooltip: 'ReactJS',
-      icon: '/docs/img/icons/react-icon',
-      href: '/guides/getting-started/quickstarts/reactjs',
-      hasLightIcon: false,
-    },
-    {
-      tooltip: 'Next.js',
-      icon: '/docs/img/icons/nextjs-icon',
-      href: '/guides/getting-started/quickstarts/nextjs',
-      hasLightIcon: false,
-    },
-    {
-      tooltip: 'TanStack Start',
-      icon: '/docs/img/icons/tanstack-icon',
-      href: '/guides/getting-started/quickstarts/tanstack',
-      hasLightIcon: true,
-    },
-    {
-      tooltip: 'Astro.js',
-      icon: '/docs/img/icons/astro-icon',
-      href: '/guides/getting-started/quickstarts/astrojs',
-      hasLightIcon: true,
-    },
-    {
-      tooltip: 'Vue',
-      icon: '/docs/img/icons/vuejs-icon',
-      href: '/guides/getting-started/quickstarts/vue',
-      hasLightIcon: false,
-    },
-    {
-      tooltip: 'Nuxt',
-      icon: '/docs/img/icons/nuxt-icon',
-      href: '/guides/getting-started/quickstarts/nuxtjs',
-      hasLightIcon: false,
-    },
-    {
-      tooltip: 'iOS Swift',
-      icon: '/docs/img/icons/swift-icon-orange',
-      href: '/guides/getting-started/quickstarts/ios-swiftui',
-      enabled: sdkSwiftEnabled,
-      hasLightIcon: false,
-    },
-    {
-      tooltip: 'Android Kotlin',
-      icon: '/docs/img/icons/kotlin-icon',
-      href: '/guides/getting-started/quickstarts/kotlin',
-      enabled: sdkKotlinEnabled,
-      hasLightIcon: false,
-    },
-    {
-      tooltip: 'Expo React Native',
-      icon: '/docs/img/icons/expo-icon',
-      href: '/guides/getting-started/quickstarts/expo-react-native',
-      hasLightIcon: true,
-    },
-    {
-      tooltip: 'Flutter',
-      icon: '/docs/img/icons/flutter-icon',
-      href: '/guides/getting-started/quickstarts/flutter',
-      enabled: sdkDartEnabled,
-      hasLightIcon: false,
-    },
-    {
-      tooltip: 'Python',
-      icon: '/docs/img/icons/python-icon',
-      href: '/guides/getting-started/quickstarts/flask',
-      hasLightIcon: false,
-    },
-  ]
+  useEffect(() => setIsMounted(true), [])
 
-  const GettingStarted = () => (
-    <div
-      className="
-        border bg-background
-        relative overflow-hidden
-        grid grid-cols-12
-        rounded-lg
-        p-5 md:p-8
-        "
-    >
-      <div className="col-span-full flex flex-col md:flex-row xl:flex-col justify-between gap-3">
-        <div className="md:max-w-xs shrink w-fit xl:max-w-none">
-          <div className="flex flex-col gap-1 mb-3">
-            <h2 className="text-2xl text-foreground">Getting Started</h2>
-            <p className="text-foreground-light text-sm">
-              Set up and connect a database in just a few minutes.
-            </p>
-          </div>
-        </div>
-        <div className="shrink-0">
-          <div className="flex flex-wrap md:grid md:grid-cols-5 gap-2 sm:gap-3">
-            {frameworks
-              .filter((framework) => framework.enabled !== false)
-              .map((framework, i) => {
-                const iconToUse =
-                  framework.hasLightIcon && isLightMode ? `${framework.icon}-light` : framework.icon
+  return (
+    <div className="grid grid-cols-12 gap-6">
+      {frameworks
+        .filter((framework) => framework.enabled !== false)
+        .map((framework) => {
+          const iconToUse =
+            framework.hasLightIcon && isLightMode ? `${framework.icon}-light` : framework.icon
 
-                return (
-                  <Link key={i} href={framework.href} passHref className="no-underline">
-                    <IconPanel iconSize={iconSize} tooltip={framework.tooltip} icon={iconToUse} />
-                  </Link>
-                )
-              })}
-          </div>
-          <AiPrompt className="mt-6" />
-        </div>
-      </div>
+          return (
+            <Link
+              key={framework.tooltip}
+              href={framework.href}
+              passHref
+              className="col-span-6 no-underline md:col-span-4"
+            >
+              <IconPanel
+                iconSize={iconSize}
+                tooltip={framework.tooltip}
+                title={framework.tooltip}
+                icon={iconToUse}
+              />
+            </Link>
+          )
+        })}
     </div>
   )
+}
+
+const HomePageCover = ({ title, cliCode }: { title: string; cliCode: ReactNode }) => {
+  const { homepageHeading } = getCustomContent(['homepage:heading'])
 
   return (
-    <div className="relative z-10 w-full bg-alternative border-b max-w-none mb-16 md:mb-12 xl:mb-0">
-      <div className="max-w-7xl px-5 mx-auto py-8 sm:pb-16 sm:pt-12 xl:pt-16 flex flex-col xl:flex-row justify-between gap-12 xl:gap-12">
-        <div className="flex flex-col sm:flex-row gap-4 sm:gap-8 items-start sm:items-center w-full max-w-xl xl:max-w-132">
-          <DocsCoverLogo aria-hidden="true" />
-          <div className="flex flex-col">
-            <h1 className="m-0 mb-3 text-2xl sm:text-3xl text-foreground">
-              {homepageHeading || props.title}
-            </h1>
-            <p className="m-0 text-foreground-light">
-              Learn how to get up and running with Supabase through tutorials, APIs and platform
-              resources.
-            </p>
+    <div className="w-full border-b bg-muted/10">
+      <div className="mx-auto max-w-7xl px-6 py-16">
+        <div className="flex flex-col items-start gap-10 xl:flex-row xl:items-center xl:gap-16">
+          <div className="flex w-full flex-1 flex-col gap-4 sm:flex-row sm:items-center sm:gap-8">
+            <DocsCoverLogo aria-hidden="true" className="w-[60px] shrink-0 md:w-[100px]" />
+            <div className="flex min-w-0 flex-col">
+              <h1 className="m-0 text-4xl text-foreground">{homepageHeading || title}</h1>
+              <p className="m-0 mt-3 text-xl leading-7 text-foreground-light">
+                Learn how to get up and running with Supabase through tutorials, APIs and platform
+                resources.
+              </p>
+            </div>
           </div>
+          {fullGettingStartedEnabled && (
+            <div className="w-full max-w-xl xl:max-w-[478px] xl:shrink-0">
+              <SetupPrompt cliCode={cliCode} />
+            </div>
+          )}
         </div>
-        {isFeatureEnabled('docs:full_getting_started') && (
-          <div className="w-full xl:max-w-[440px] -mb-40">
-            <GettingStarted />
-          </div>
-        )}
       </div>
     </div>
   )
diff --git a/apps/docs/features/docs/MdxBase.shared.tsx b/apps/docs/features/docs/MdxBase.shared.tsx
index 7bd5a9d1b120e..993891a12ba9b 100644
--- a/apps/docs/features/docs/MdxBase.shared.tsx
+++ b/apps/docs/features/docs/MdxBase.shared.tsx
@@ -5,8 +5,8 @@ import AuthProviders from '~/components/AuthProviders'
 import { AuthSmsProviderConfig } from '~/components/AuthSmsProviderConfig'
 import ButtonCard from '~/components/ButtonCard'
 import { ComputeDiskLimitsTable } from '~/components/ComputeDiskLimitsTable'
-import { CustomContent } from '~/components/CustomContent'
 import { ContentListings } from '~/components/ContentListings'
+import { CustomContent } from '~/components/CustomContent'
 import { Extensions } from '~/components/Extensions'
 import Image, { type ImageProps } from '~/components/Image'
 import { McpCiConfigBlock } from '~/components/McpCiConfigBlock'
@@ -40,6 +40,7 @@ import { Heading } from 'ui/src/components/CustomHTMLElements'
 import { AgentPluginsPanel } from '../ui/AgentPluginsPanel'
 import { ErrorCodes } from '../ui/ErrorCodes'
 import { McpConfigPanel } from '../ui/McpConfigPanel'
+import { Prompt, PromptContent, PromptCopy, PromptPanel, PromptTitle } from '../ui/PromptPanel'
 
 // Wrap Admonition for Docs-specific styling (within MDX prose, requires a margin-bottom)
 const AdmonitionWithMargin = (props: AdmonitionProps) => {
@@ -96,6 +97,11 @@ const components = {
   NamedCodeBlock,
   NavData,
   ProjectConfigVariables,
+  Prompt,
+  PromptContent,
+  PromptCopy,
+  PromptPanel,
+  PromptTitle,
   RealtimeLimitsEstimator,
   RegionsList,
   SmartRegionsList,
diff --git a/apps/docs/features/ui/CodeBlock/CodeBlock.tsx b/apps/docs/features/ui/CodeBlock/CodeBlock.tsx
index 2ba08dbae9aa5..6cfc7f5591d92 100644
--- a/apps/docs/features/ui/CodeBlock/CodeBlock.tsx
+++ b/apps/docs/features/ui/CodeBlock/CodeBlock.tsx
@@ -26,12 +26,14 @@ export async function CodeBlock({
   contents,
   children,
   skipTypeGeneration,
+  hideControls = false,
 }: PropsWithChildren<{
   className?: string
   lang?: string
   lineNumbers?: boolean
   contents?: string
   skipTypeGeneration?: boolean
+  hideControls?: boolean
 }>) {
   let code = (contents || extractCode(children)).trim()
   const lang = tryToBundledLanguage(langSetting || '') || extractLang(children)
@@ -73,7 +75,7 @@ export async function CodeBlock({
       role="group"
       aria-roledescription="code block"
     >
-      <CodeBlockControls content={code.trim()} />
+      {!hideControls && <CodeBlockControls content={code.trim()} />}
       <pre>
         <code className={lineNumbers ? 'grid grid-cols-[auto_1fr]' : ''}>
           {lineNumbers ? (
diff --git a/apps/docs/features/ui/PromptPanel.tsx b/apps/docs/features/ui/PromptPanel.tsx
new file mode 100644
index 0000000000000..2950f255ae86e
--- /dev/null
+++ b/apps/docs/features/ui/PromptPanel.tsx
@@ -0,0 +1,304 @@
+'use client'
+
+import { Check, Copy } from 'lucide-react'
+import {
+  Children,
+  isValidElement,
+  useEffect,
+  useId,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react'
+// shadcn tabs from packages/ui/src/components/shadcn/ui/tabs.tsx
+import { cn, copyToClipboard, Tabs, TabsContent, TabsList, TabsTrigger } from 'ui'
+
+type PromptTitleProps = {
+  children: ReactNode
+  icon?: ReactNode
+}
+
+type PromptCopyProps = {
+  children: string
+}
+
+type PromptContentProps = {
+  children: ReactNode
+  /** Draws attention with a text shimmer. Defaults to true. */
+  shimmer?: boolean
+}
+
+type PromptProps = {
+  children: ReactNode
+  /** Stable tab id. Auto-generated when omitted. */
+  value?: string
+  /** When true, content starts collapsed with a show more / show less control. */
+  expandable?: boolean
+}
+
+type PromptPanelProps = {
+  children: ReactNode
+  className?: string
+}
+
+type CollectedPrompt = {
+  value: string
+  title: ReactNode
+  icon?: ReactNode
+  copyValue: string
+  content: ReactNode
+  expandable: boolean
+  shimmer: boolean
+}
+
+function PromptTitle(_props: PromptTitleProps) {
+  return null
+}
+PromptTitle.displayName = 'PromptTitle'
+
+function PromptCopy(_props: PromptCopyProps) {
+  return null
+}
+PromptCopy.displayName = 'PromptCopy'
+
+function PromptContent(_props: PromptContentProps) {
+  return null
+}
+PromptContent.displayName = 'PromptContent'
+
+function Prompt(_props: PromptProps) {
+  return null
+}
+Prompt.displayName = 'Prompt'
+
+function isElementOfType(child: ReactNode, type: { displayName?: string }) {
+  return (
+    isValidElement(child) &&
+    typeof child.type !== 'string' &&
+    'displayName' in child.type &&
+    child.type.displayName === type.displayName
+  )
+}
+
+function collectPrompt(prompt: ReactElement<PromptProps>, index: number): CollectedPrompt {
+  let title: ReactNode = `Prompt ${index + 1}`
+  let icon: ReactNode | undefined
+  let copyValue = ''
+  let content: ReactNode = null
+  let shimmer = true
+
+  Children.forEach(prompt.props.children, (child) => {
+    if (isElementOfType(child, PromptTitle)) {
+      const props = (child as ReactElement<PromptTitleProps>).props
+      title = props.children
+      icon = props.icon
+    } else if (isElementOfType(child, PromptCopy)) {
+      copyValue = (child as ReactElement<PromptCopyProps>).props.children
+    } else if (isElementOfType(child, PromptContent)) {
+      const props = (child as ReactElement<PromptContentProps>).props
+      content = props.children
+      shimmer = props.shimmer !== false
+    }
+  })
+
+  return {
+    value: prompt.props.value ?? `prompt-${index}`,
+    title,
+    icon,
+    copyValue,
+    content,
+    expandable: Boolean(prompt.props.expandable),
+    shimmer,
+  }
+}
+
+function collectPrompts(children: ReactNode): CollectedPrompt[] {
+  return Children.toArray(children)
+    .filter((child): child is ReactElement<PromptProps> => isElementOfType(child, Prompt))
+    .map((prompt, index) => collectPrompt(prompt, index))
+}
+
+function ExpandableContent({ children }: { children: ReactNode }) {
+  const [isExpanded, setIsExpanded] = useState(false)
+
+  return (
+    <div>
+      <div className="relative">
+        <div className={cn(!isExpanded && 'max-h-30 overflow-hidden')}>{children}</div>
+        {!isExpanded && (
+          <div className="pointer-events-none absolute inset-x-0 bottom-0 h-12 bg-gradient-to-t from-background to-transparent" />
+        )}
+      </div>
+      <button
+        type="button"
+        onClick={() => setIsExpanded((expanded) => !expanded)}
+        className="mt-2 text-sm text-brand-link transition-colors hover:text-brand focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-foreground-muted"
+        aria-expanded={isExpanded}
+      >
+        {isExpanded ? 'Show less' : 'Show more'}
+      </button>
+    </div>
+  )
+}
+
+function PromptBody({
+  prompt,
+  shimmerEnabled,
+}: {
+  prompt: CollectedPrompt
+  shimmerEnabled: boolean
+}) {
+  const [shimmerMounted, setShimmerMounted] = useState(prompt.shimmer)
+
+  const content = (
+    <div
+      className={cn(shimmerMounted && 'shimmer')}
+      data-shimmer-fading={shimmerMounted && !shimmerEnabled ? true : undefined}
+      onTransitionEnd={(event) => {
+        if (event.target !== event.currentTarget) return
+        if (shimmerMounted && !shimmerEnabled) {
+          setShimmerMounted(false)
+        }
+      }}
+    >
+      {prompt.content}
+    </div>
+  )
+
+  return (
+    <div className="px-4 py-3.5 text-sm leading-6 text-foreground-light">
+      {prompt.expandable ? <ExpandableContent>{content}</ExpandableContent> : content}
+    </div>
+  )
+}
+
+function CopyButton({ label, value }: { label: string; value: string }) {
+  const [copied, setCopied] = useState(false)
+
+  useEffect(() => {
+    if (!copied) return
+
+    const timeout = window.setTimeout(() => setCopied(false), 2000)
+    return () => window.clearTimeout(timeout)
+  }, [copied])
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        copyToClipboard(value, () => {
+          setCopied(true)
+        })
+      }}
+      className="rounded-sm p-1.5 text-foreground-muted transition-colors hover:bg-surface-200 hover:text-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-foreground-muted"
+      aria-label={copied ? `${label} copied` : `Copy ${label}`}
+      title={copied ? 'Copied' : 'Copy to clipboard'}
+    >
+      {copied ? <Check size={14} /> : <Copy size={14} />}
+    </button>
+  )
+}
+
+function TabLabel({ icon, children }: { icon?: ReactNode; children: ReactNode }) {
+  return (
+    <span className="inline-flex items-center gap-1.5">
+      {icon && <span className="text-tertiary-foreground [&_svg]:size-3.5">{icon}</span>}
+      {children}
+    </span>
+  )
+}
+
+const tabTriggerClassName = 'h-full px-0 py-0 text-xs shadow-none data-[state=active]:shadow-none'
+
+/**
+ * Copyable prompt card. Compose one or more `<Prompt>` children; multiple
+ * prompts render as tabs. A single prompt still shows the header + copy
+ * button, with the title styled like an inactive tab (no underline).
+ *
+ * @example
+ * ```tsx
+ * <PromptPanel>
+ *   <Prompt value="prompt" expandable>
+ *     <PromptTitle icon={<Sparkles />}>AI Prompt</PromptTitle>
+ *     <PromptCopy>Plain text copied to the clipboard</PromptCopy>
+ *     <PromptContent>Rich content shown in the panel</PromptContent>
+ *   </Prompt>
+ * </PromptPanel>
+ * ```
+ */
+function PromptPanel({ children, className }: PromptPanelProps) {
+  const fallbackId = useId()
+  const prompts = collectPrompts(children)
+  const [activeTab, setActiveTab] = useState(prompts[0]?.value ?? fallbackId)
+  const [shimmerEnabled, setShimmerEnabled] = useState(true)
+
+  if (prompts.length === 0) return null
+
+  const activePrompt = prompts.find((prompt) => prompt.value === activeTab) ?? prompts[0]
+  const hasTabs = prompts.length > 1
+  const dismissShimmer = () => setShimmerEnabled(false)
+
+  const header = (
+    <div className="flex h-11 items-center justify-between border-b bg-surface-75 px-4">
+      {hasTabs ? (
+        <TabsList className="h-full gap-5 border-0">
+          {prompts.map((prompt) => (
+            <TabsTrigger key={prompt.value} value={prompt.value} className={tabTriggerClassName}>
+              <TabLabel icon={prompt.icon}>{prompt.title}</TabLabel>
+            </TabsTrigger>
+          ))}
+        </TabsList>
+      ) : (
+        <span
+          className={cn(
+            'inline-flex items-center justify-center whitespace-nowrap border-b-2 border-transparent text-foreground-lighter',
+            tabTriggerClassName
+          )}
+        >
+          <TabLabel icon={prompts[0].icon}>{prompts[0].title}</TabLabel>
+        </span>
+      )}
+      <CopyButton
+        key={activePrompt.value}
+        label={typeof activePrompt.title === 'string' ? activePrompt.title : 'content'}
+        value={activePrompt.copyValue}
+      />
+    </div>
+  )
+
+  if (!hasTabs) {
+    return (
+      <div
+        onFocusCapture={dismissShimmer}
+        onPointerEnter={dismissShimmer}
+        className={cn(
+          'w-full overflow-hidden rounded-lg border bg-background shadow-sm',
+          className
+        )}
+      >
+        {header}
+        <PromptBody prompt={prompts[0]} shimmerEnabled={shimmerEnabled} />
+      </div>
+    )
+  }
+
+  return (
+    <Tabs
+      value={activeTab}
+      onValueChange={setActiveTab}
+      onFocusCapture={dismissShimmer}
+      onPointerEnter={dismissShimmer}
+      className={cn('w-full overflow-hidden rounded-lg border bg-background shadow-sm', className)}
+    >
+      {header}
+      {prompts.map((prompt) => (
+        <TabsContent key={prompt.value} value={prompt.value} className="m-0">
+          <PromptBody prompt={prompt} shimmerEnabled={shimmerEnabled} />
+        </TabsContent>
+      ))}
+    </Tabs>
+  )
+}
+
+export { Prompt, PromptContent, PromptCopy, PromptPanel, PromptTitle }
+export type { PromptContentProps, PromptCopyProps, PromptPanelProps, PromptProps, PromptTitleProps }
diff --git a/apps/docs/internals/generate-guides-markdown.ts b/apps/docs/internals/generate-guides-markdown.ts
index c0c77c12261c2..94a13b727d7e1 100644
--- a/apps/docs/internals/generate-guides-markdown.ts
+++ b/apps/docs/internals/generate-guides-markdown.ts
@@ -28,6 +28,7 @@ import { MetricsStackCards } from './markdown-schema/MetricsStackCards'
 import { NavData } from './markdown-schema/NavData'
 import { Panel } from './markdown-schema/Panel'
 import { Price } from './markdown-schema/Price'
+import { PromptPanel } from './markdown-schema/PromptPanel'
 import { RealtimeLimitsEstimator } from './markdown-schema/RealtimeLimitsEstimator'
 import { RegionsList, SmartRegionsList } from './markdown-schema/RegionsList'
 import { SharedData } from './markdown-schema/SharedData'
@@ -174,6 +175,7 @@ const SCHEMA: ComponentSchema = {
   McpCiConfigBlock,
   McpConfigPanel,
   Price,
+  ...PromptPanel,
   GlassPanel: Panel,
   IconPanel: Panel,
   RealtimeLimitsEstimator,
diff --git a/apps/docs/internals/markdown-schema/PromptPanel.test.ts b/apps/docs/internals/markdown-schema/PromptPanel.test.ts
new file mode 100644
index 0000000000000..4d1d241c8b74b
--- /dev/null
+++ b/apps/docs/internals/markdown-schema/PromptPanel.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest'
+
+import { PromptPanel } from './PromptPanel'
+
+function serializePrompt({
+  title,
+  copyValue,
+  content,
+}: {
+  title: string
+  copyValue: string
+  content: string
+}) {
+  const children = [
+    PromptPanel.PromptTitle({ children: title }),
+    PromptPanel.PromptCopy({ children: copyValue }),
+    PromptPanel.PromptContent({ children: content }),
+  ]
+    .filter(Boolean)
+    .join('\n\n')
+
+  return PromptPanel.Prompt({ children })
+}
+
+describe('PromptPanel markdown schema', () => {
+  it('flattens prompts in order while preserving visible rich content', () => {
+    const prompt = serializePrompt({
+      title: 'AI Prompt',
+      copyValue: 'clipboard-only prompt payload',
+      content:
+        'Install the CLI with `npm install -g supabase` and read the [CLI guide](/docs/guides/local-development/cli/getting-started).',
+    })
+    const cli = serializePrompt({
+      title: 'CLI',
+      copyValue: 'clipboard-only CLI payload',
+      content: '```bash\nsupabase init\n```',
+    })
+
+    const markdown = PromptPanel.PromptPanel({ children: [prompt, cli].join('\n\n') })
+
+    expect(markdown).toBe(`**AI Prompt**
+
+Install the CLI with \`npm install -g supabase\` and read the [CLI guide](/docs/guides/local-development/cli/getting-started).
+
+**CLI**
+
+\`\`\`bash
+supabase init
+\`\`\``)
+    expect(markdown).not.toContain('clipboard-only')
+  })
+
+  it('omits empty titles without dropping prompt content', () => {
+    const markdown = serializePrompt({
+      title: '  ',
+      copyValue: 'clipboard-only content',
+      content: 'Visible content',
+    })
+
+    expect(markdown).toBe('Visible content')
+  })
+
+  it('registers every PromptPanel marker component', () => {
+    expect(Object.keys(PromptPanel)).toEqual([
+      'PromptPanel',
+      'Prompt',
+      'PromptTitle',
+      'PromptCopy',
+      'PromptContent',
+    ])
+  })
+})
diff --git a/apps/docs/internals/markdown-schema/PromptPanel.ts b/apps/docs/internals/markdown-schema/PromptPanel.ts
new file mode 100644
index 0000000000000..e9123e5e5a3c0
--- /dev/null
+++ b/apps/docs/internals/markdown-schema/PromptPanel.ts
@@ -0,0 +1,22 @@
+type HandlerContext = {
+  children: string
+}
+
+const preserveChildren = ({ children }: HandlerContext): string => children
+
+const PromptTitle = ({ children }: HandlerContext): string => {
+  const title = children.trim()
+  return title ? `**${title}**` : ''
+}
+
+// PromptCopy is clipboard-only metadata. PromptContent is the visible source of
+// truth and is preserved below, so including both would duplicate the prompt.
+const PromptCopy = (_context: HandlerContext): string => ''
+
+export const PromptPanel = {
+  PromptPanel: preserveChildren,
+  Prompt: preserveChildren,
+  PromptTitle,
+  PromptCopy,
+  PromptContent: preserveChildren,
+}
diff --git a/apps/docs/layouts/HomeLayout.tsx b/apps/docs/layouts/HomeLayout.tsx
index ad8def21de742..1eed90bb84ed4 100644
--- a/apps/docs/layouts/HomeLayout.tsx
+++ b/apps/docs/layouts/HomeLayout.tsx
@@ -1,6 +1,8 @@
+import HomePageCover from '~/components/HomePageCover'
+import { setupCommands } from '~/components/HomePageCover.constants'
+import { CodeBlock } from '~/features/ui/CodeBlock/CodeBlock'
 import { type PropsWithChildren } from 'react'
 
-import HomePageCover from '~/components/HomePageCover'
 import { LayoutMainContent } from './DefaultLayout'
 import { SidebarSkeleton } from './MainSkeleton'
 
@@ -8,8 +10,19 @@ const HomeLayout = ({ children }: PropsWithChildren) => {
   return (
     <SidebarSkeleton hideSideNav>
       <article>
-        <HomePageCover title="Supabase Documentation" />
-        <LayoutMainContent>
+        <HomePageCover
+          title="Supabase Documentation"
+          cliCode={
+            <CodeBlock
+              contents={setupCommands}
+              lang="bash"
+              lineNumbers={false}
+              hideControls
+              className="!-mx-4 !-my-3.5 !border-0 !rounded-none !bg-transparent [&_.code-content]:!px-4 [&_.code-content]:!py-3.5"
+            />
+          }
+        />
+        <LayoutMainContent className="max-w-7xl">
           <div className={['relative transition-all ease-out', 'duration-150 '].join(' ')}>
             <div className="prose max-w-none">{children}</div>
           </div>
diff --git a/packages/config/css/animations.css b/packages/config/css/animations.css
index d7ca9759139e6..3e1362a5d4ae4 100644
--- a/packages/config/css/animations.css
+++ b/packages/config/css/animations.css
@@ -296,3 +296,12 @@
     height: 0;
   }
 }
+
+@keyframes tw-shimmer {
+  from {
+    background-position: 100% 0;
+  }
+  to {
+    background-position: 0 0;
+  }
+}
diff --git a/packages/config/css/utilities.css b/packages/config/css/utilities.css
index c792e51209697..7ea8e9d28a1f5 100644
--- a/packages/config/css/utilities.css
+++ b/packages/config/css/utilities.css
@@ -74,3 +74,109 @@
     display: none; /* Chrome, Safari, Opera */
   }
 }
+
+/*
+ * Text shimmer (shadcn shimmer utility, inlined so we don't pull in the full
+ * shadcn CSS package). Apply `shimmer` to text to draw attention.
+ */
+@property --shimmer-angle {
+  syntax: '<angle>';
+  inherits: true;
+  initial-value: 20deg;
+}
+@property --shimmer-image {
+  syntax: '*';
+  inherits: false;
+}
+@property --shimmer-text-fill {
+  syntax: '*';
+  inherits: false;
+}
+
+@utility shimmer {
+  --_spread: var(--shimmer-spread, calc(3ch + 40px));
+  --_base: currentColor;
+  --_highlight: var(--shimmer-color, oklch(from currentColor l c h / calc(alpha* 0.2)));
+
+  background-image: var(
+    --shimmer-image,
+    linear-gradient(
+      calc(90deg + var(--shimmer-angle)),
+      var(--_base) calc(50% - var(--_spread)),
+      color-mix(in oklch, var(--_highlight), var(--_base) 50%) calc(50% - var(--_spread) * 0.5),
+      var(--_highlight) 50%,
+      color-mix(in oklch, var(--_highlight), var(--_base) 50%) calc(50% + var(--_spread) * 0.5),
+      var(--_base) calc(50% + var(--_spread))
+    )
+  );
+  background-repeat: no-repeat;
+  background-size: calc(200% + var(--_spread) * 2) 100%;
+  background-position: 0 0;
+  background-clip: text;
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: var(--shimmer-text-fill, transparent);
+  animation: tw-shimmer var(--shimmer-duration, 2s) linear infinite;
+  transition: -webkit-text-fill-color 0.5s ease;
+
+  /* Fade to solid text on dismiss — keep the gradient until fill is opaque */
+  &[data-shimmer-fading] {
+    -webkit-text-fill-color: currentColor;
+    animation-play-state: paused;
+  }
+
+  @variant dark {
+    --_highlight: var(
+      --shimmer-color,
+      oklch(from currentColor max(0.8, calc(l + 0.4)) c h / calc(alpha + 0.4))
+    );
+  }
+
+  &:where([dir='rtl'], [dir='rtl'] *) {
+    animation-direction: reverse;
+  }
+}
+
+@utility shimmer-once {
+  animation-iteration-count: 1;
+}
+
+@utility shimmer-reverse {
+  animation-direction: reverse;
+}
+
+@utility shimmer-none {
+  --shimmer-image: none;
+  --shimmer-text-fill: currentColor;
+  background-image: none;
+  -webkit-text-fill-color: currentColor;
+}
+
+@utility shimmer-color-* {
+  --shimmer-color: --value(--color-*, [color]);
+  --shimmer-color: color-mix(
+    in oklch,
+    --value(--color-*, [color]) calc(--modifier(integer) * 1%),
+    transparent
+  );
+}
+
+@utility shimmer-duration-* {
+  --shimmer-duration: calc(--value(integer) * 1ms);
+}
+
+@utility shimmer-spread-* {
+  --shimmer-spread: calc(var(--spacing) * --value(integer));
+  --shimmer-spread: --value([length], [percentage]);
+}
+
+@utility shimmer-angle-* {
+  --shimmer-angle: calc(--value(integer) * 1deg);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .shimmer {
+    animation: none;
+    background-image: none;
+    -webkit-text-fill-color: currentColor;
+  }
+}

From 846706bc504d84c0bdae51e6e61d50ccdda86f73 Mon Sep 17 00:00:00 2001
From: Ali Waseem <waseema393@gmail.com>
Date: Tue, 21 Jul 2026 01:22:36 -0600
Subject: [PATCH 2/7] fix(studio): guard panel collapse/resize on narrow
 viewports (#48098)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary

Fixes FE-3955 /
[SUPABASE-APP-K41](https://supabase.sentry.io/issues/7613475596/) — a
crash affecting 101 users (502 occurrences, escalating) since the
"maximise AI assistant" feature (#47954) shipped on 2026-07-15.

`DefaultLayout` calls `panelRef.current.collapse()` / `.resize()` on the
`panel-content` resizable panel whenever the AI assistant sidebar is
maximised. Below the `md` breakpoint, `LayoutSidebar` renders no panel
at all (the sidebar shows as a mobile sheet instead), leaving
`panel-content` as the *only* panel in the `ResizablePanelGroup`.
`react-resizable-panels`' resize algorithm assumes a neighboring panel
exists to pivot against, so with a single panel it computes an invalid
pivot index of `-1` and throws `Panel constraints not found for index
-1`.

This guards the effect with the same `isMobile` breakpoint check
`LayoutSidebar` already uses, so we never call `collapse()`/`resize()`
when there's no sibling panel to resize against.

## Test plan

- [ ] On a narrow viewport (or actual mobile device), open the AI
assistant and toggle maximise — should no longer throw
- [ ] On desktop, confirm maximise/minimise still resizes the content
panel as before

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Fixed a mobile layout issue where the sidebar could collapse or resize
incorrectly, leading to runtime errors.
* Improved the sidebar’s resize/collapse behavior on mobile devices to
keep the layout stable.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 apps/studio/components/layouts/DefaultLayout.tsx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/studio/components/layouts/DefaultLayout.tsx b/apps/studio/components/layouts/DefaultLayout.tsx
index 9b4c23f424aa4..2f29bf4016a80 100644
--- a/apps/studio/components/layouts/DefaultLayout.tsx
+++ b/apps/studio/components/layouts/DefaultLayout.tsx
@@ -72,13 +72,13 @@ export const DefaultLayout = ({
   }, [])
 
   useEffect(() => {
-    if (!isMounted || !panelRef.current || !activeSidebar) return
+    if (!isMounted || !panelRef.current || !activeSidebar || isMobile) return
     if (isMaximised) {
       panelRef.current.collapse()
     } else {
       panelRef.current.resize(`${contentMaxSizePercentage}%`)
     }
-  }, [isMounted, isMaximised, panelRef, activeSidebar])
+  }, [isMounted, isMaximised, panelRef, activeSidebar, isMobile])
 
   // This is required to prevent layout shift when rendering resizable panels (they initially render at 50%, then shift
   // to whatever is specified).

From c7803b8b9b0718595599536e4026ef7772811141 Mon Sep 17 00:00:00 2001
From: Joshen Lim <joshenlimek@gmail.com>
Date: Tue, 21 Jul 2026 16:52:03 +0800
Subject: [PATCH 3/7] Chore/add sessions database connections (#48094)

## Context

Initial work for Top for Postgres - adds a "Sessions" section under a
new Observability segment "Database Connections"
NOTE: All the copywriting and naming might change - not sure what's an
ideal title for this
We'll also be iteratively building on top of this UI, adding more
actionable signals instead of just information
Changes are featured flagged, off for public

- This would essentially replace the "View ongoing queries" in the SQL
Editor by providing a dedicated UI
  - It checks against `pg_stat_activity` as per the ongoing queries UI
- We'll also subsequently deprecate the "Ongoing queries" UI in the SQL
editor
- Defaults into a "live mode" where the data is refreshed every 3
seconds via long-polling
<img width="983" height="474" alt="image"
src="https://github.com/user-attachments/assets/16402fe4-0b53-4f9e-9342-cdda26e3778a"
/>
- Supports filtering by state
<img width="374" height="282" alt="image"
src="https://github.com/user-attachments/assets/562f8fbe-2dc6-48e7-8ec0-de7ffb8348d1"
/>
- Users can also terminate queries through here
<img width="247" height="164" alt="image"
src="https://github.com/user-attachments/assets/23a639dc-8f96-473a-a823-605b0bab02ee"
/>





<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

# Release Notes

* **New Features**
* Added an Observability **Database Connections** page with a live
**Sessions** activity table (state/roles filtering, blocked-by details,
session duration, and per-session termination with confirmation).
* Included a **Live/Pause** toggle to control automatic refresh (~3
seconds).

* **Enhancements**
* Improved Reports selection filtering: supports optional option
quantities, better popover styling, sorted apply behavior, and shows
quantity inline.
* Query performance duration formatting now supports configurable
decimal precision.
  * Tooltips can now render richer content (string or React node).
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 .../DatabaseConnections/Activity.tsx          | 463 ++++++++++++++++++
 .../QueryPerformance.utils.ts                 |   4 +-
 .../QueryPerformance/SqlMonacoBlock.tsx       |   4 +
 .../Reports/v2/ReportsSelectFilter.tsx        |  26 +-
 .../ObservabilityMenu.utils.tsx               |   2 +-
 .../components/ui/DropdownMenuItemTooltip.tsx |   4 +-
 apps/studio/data/database/activity-query.ts   | 119 +++++
 apps/studio/data/database/keys.ts             |   2 +
 .../[ref]/observability/connections.tsx       |  55 +++
 apps/studio/routeTree.gen.ts                  |  23 +
 .../$ref/observability/connections.tsx        |  14 +
 .../src/sql/studio/database/activity.ts       |  23 +
 .../pg-meta/src/sql/studio/database/index.ts  |   1 +
 13 files changed, 725 insertions(+), 15 deletions(-)
 create mode 100644 apps/studio/components/interfaces/Observability/DatabaseConnections/Activity.tsx
 create mode 100644 apps/studio/data/database/activity-query.ts
 create mode 100644 apps/studio/pages/project/[ref]/observability/connections.tsx
 create mode 100644 apps/studio/routes/project/$ref/observability/connections.tsx
 create mode 100644 packages/pg-meta/src/sql/studio/database/activity.ts

diff --git a/apps/studio/components/interfaces/Observability/DatabaseConnections/Activity.tsx b/apps/studio/components/interfaces/Observability/DatabaseConnections/Activity.tsx
new file mode 100644
index 0000000000000..7af3cb57b589b
--- /dev/null
+++ b/apps/studio/components/interfaces/Observability/DatabaseConnections/Activity.tsx
@@ -0,0 +1,463 @@
+import dayjs from 'dayjs'
+import { isEqual } from 'lodash'
+import { Minus, MoreVertical, StopCircle } from 'lucide-react'
+import { parseAsArrayOf, parseAsInteger, parseAsJson, parseAsString, useQueryState } from 'nuqs'
+import { Fragment, useEffect, useState } from 'react'
+import { toast } from 'sonner'
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+  Badge,
+  Button,
+  Card,
+  cn,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuTrigger,
+  HoverCard,
+  HoverCardContent,
+  HoverCardTrigger,
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from 'ui'
+import { CodeBlock } from 'ui-patterns/CodeBlock'
+import { ShimmeringLoader } from 'ui-patterns/ShimmeringLoader'
+
+import { ReportsSelectFilter, selectFilterSchema } from '../../Reports/v2/ReportsSelectFilter'
+import { formatDuration } from '@/components/interfaces/QueryPerformance/QueryPerformance.utils'
+import { DropdownMenuItemTooltip } from '@/components/ui/DropdownMenuItemTooltip'
+import { InlineLinkClassName } from '@/components/ui/InlineLink'
+import { useDatabaseRolesQuery } from '@/data/database-roles/database-roles-query'
+import { useDatabaseActivityQuery, type DatabaseActivity } from '@/data/database/activity-query'
+import { useQueryAbortMutation } from '@/data/sql/abort-query-mutation'
+import { useSelectedProjectQuery } from '@/hooks/misc/useSelectedProject'
+import { formatSql } from '@/lib/formatSql'
+
+const getDuration = (activity: DatabaseActivity) => {
+  const { state } = activity
+  if (state === 'active' && activity.query_start) {
+    return dayjs().utc().diff(dayjs(activity.query_start).utc(), 'second')
+  }
+  if (state === 'idle' && activity.state_change) {
+    return dayjs().utc().diff(dayjs(activity.state_change).utc(), 'second')
+  }
+  if (
+    (state === 'idle in transaction' || state === 'idle in transaction (aborted)') &&
+    activity.transaction_start
+  ) {
+    return dayjs().utc().diff(dayjs(activity.transaction_start).utc(), 'second')
+  }
+  return null
+}
+
+const DEFAULT_ROLES_FILTER = ['anon', 'authenticated', 'postgres']
+
+interface ActivityProps {
+  live?: boolean
+}
+
+export const Activity = ({ live }: ActivityProps) => {
+  const { data: project } = useSelectedProjectQuery()
+
+  const [, setNow] = useState(() => dayjs())
+  const [selectedPid] = useQueryState('pid', parseAsInteger)
+  const [stateFilter, setStateFilter] = useQueryState(
+    'state',
+    parseAsJson(selectFilterSchema.parse).withDefault([])
+  )
+  const [rolesFilter, setRolesFilter] = useQueryState(
+    'roles',
+    parseAsArrayOf(parseAsString, ',').withDefault(DEFAULT_ROLES_FILTER)
+  )
+
+  const hasNoFiltersApplied = stateFilter.length === 0 && isEqual(rolesFilter, DEFAULT_ROLES_FILTER)
+
+  const { data, isPending, isSuccess } = useDatabaseActivityQuery(
+    {
+      projectRef: project?.ref,
+      connectionString: project?.connectionString,
+    },
+    { refetchInterval: live ? 3000 : false }
+  )
+
+  const { data: roles } = useDatabaseRolesQuery({
+    projectRef: project?.ref,
+    connectionString: project?.connectionString,
+  })
+
+  const activities = data?.filter((activity) => {
+    const matchesState =
+      !stateFilter ||
+      stateFilter.length === 0 ||
+      (activity.state !== null && stateFilter.includes(activity.state))
+    const matchesRole = rolesFilter.length === 0 || rolesFilter.includes(activity.role_name)
+    return matchesState && matchesRole
+  })
+
+  const stateOptions = [
+    'Idle',
+    'Active',
+    'Idle in transaction',
+    'Idle in transaction (aborted)',
+    'Fastpath function call',
+    'Disabled',
+  ].map((x) => ({
+    label: x,
+    value: x.toLowerCase(),
+    quantity: data?.filter(
+      (y) =>
+        y.state === x.toLowerCase() &&
+        (rolesFilter.length === 0 || rolesFilter.includes(y.role_name))
+    ).length,
+  }))
+
+  const priorityRoles = ['anon', 'authenticated', 'postgres']
+
+  const roleOptions = (roles ?? [])
+    .map((x) => ({
+      label: x.name,
+      value: x.name,
+      quantity: data?.filter(
+        (y) =>
+          y.role_name === x.name &&
+          (!stateFilter ||
+            stateFilter.length === 0 ||
+            (y.state !== null && stateFilter.includes(y.state)))
+      ).length,
+    }))
+    .sort((a, b) => {
+      const aIndex = priorityRoles.indexOf(a.value)
+      const bIndex = priorityRoles.indexOf(b.value)
+      if (aIndex !== -1 && bIndex !== -1) return aIndex - bIndex
+      if (aIndex !== -1) return -1
+      if (bIndex !== -1) return 1
+      return 0
+    })
+
+  // [Joshen] Just to trigger a UI re-render for the duration to be "live"
+  useEffect(() => {
+    const interval = setInterval(() => setNow(dayjs()), 1000)
+    return () => clearInterval(interval)
+  }, [])
+
+  useEffect(() => {
+    if (selectedPid && isSuccess) {
+      document
+        .getElementById(selectedPid.toString())
+        ?.scrollIntoView({ behavior: 'smooth', block: 'center' })
+    }
+  }, [selectedPid, isSuccess])
+
+  return (
+    <div className="flex flex-col gap-y-4">
+      <div className="flex gap-x-4">
+        <h2>Sessions</h2>
+        <div className="flex gap-x-2">
+          <ReportsSelectFilter
+            showSearch
+            label="Roles"
+            options={roleOptions}
+            value={rolesFilter ?? []}
+            onChange={setRolesFilter}
+            isLoading={isPending}
+            popoverClassName="w-72"
+          />
+          <ReportsSelectFilter
+            label="State"
+            options={stateOptions}
+            value={stateFilter ?? []}
+            onChange={setStateFilter}
+            isLoading={isPending}
+            popoverClassName="w-60"
+          />
+        </div>
+      </div>
+
+      <Card>
+        <Table>
+          <TableHeader>
+            <TableRow>
+              <TableHead className="w-[70px]">State</TableHead>
+              <TableHead className="max-w-[300px]">Query · Session</TableHead>
+              <TableHead>Duration</TableHead>
+              <TableHead>Blocked by</TableHead>
+              <TableHead />
+            </TableRow>
+          </TableHeader>
+
+          <TableBody>
+            {isPending ? (
+              Array.from({ length: 3 }).map((_, i) => (
+                <TableRow key={i}>
+                  <TableCell>
+                    <ShimmeringLoader />
+                  </TableCell>
+                  <TableCell>
+                    <ShimmeringLoader />
+                  </TableCell>
+                  <TableCell>
+                    <ShimmeringLoader />
+                  </TableCell>
+                  <TableCell colSpan={2}>
+                    <ShimmeringLoader />
+                  </TableCell>
+                </TableRow>
+              ))
+            ) : (activities ?? []).length === 0 ? (
+              <TableRow>
+                {hasNoFiltersApplied ? (
+                  <TableCell colSpan={5}>
+                    <p className="text-sm text-foreground">No active sessions</p>
+                    <p className="text-sm text-foreground-lighter mt-1">
+                      There are currently no active database connections for the anon,
+                      authenticated, and postgres roles.
+                    </p>
+                  </TableCell>
+                ) : (
+                  <TableCell colSpan={5}>
+                    <p className="text-sm text-foreground">No results found</p>
+                    <p className="text-sm text-foreground-lighter mt-1">
+                      There are no sessions that match the selected filters. Try adjusting or
+                      clearing them.
+                    </p>
+                    <Button
+                      variant="default"
+                      className="mt-2"
+                      onClick={() => {
+                        setStateFilter([])
+                        setRolesFilter(DEFAULT_ROLES_FILTER)
+                      }}
+                    >
+                      Reset filters
+                    </Button>
+                  </TableCell>
+                )}
+              </TableRow>
+            ) : null}
+
+            {activities?.map((activity) => (
+              <ActivityRow key={activity.pid} activity={activity} />
+            ))}
+          </TableBody>
+        </Table>
+      </Card>
+    </div>
+  )
+}
+
+const ActivityRow = ({ activity }: { activity: DatabaseActivity }) => {
+  const { data: project } = useSelectedProjectQuery()
+  const [showTerminateConfirmDialog, setShowTerminateConfirmDialog] = useState(false)
+  const [selectedPid, setSelectedPid] = useQueryState('pid', parseAsInteger)
+
+  const { data } = useDatabaseActivityQuery({
+    projectRef: project?.ref,
+    connectionString: project?.connectionString,
+  })
+
+  const { data: roles } = useDatabaseRolesQuery({
+    projectRef: project?.ref,
+    connectionString: project?.connectionString,
+  })
+  const superuserRoles = roles?.filter((role) => role.isSuperuser).map((role) => role.name)
+
+  const { mutateAsync: abortQuery } = useQueryAbortMutation({
+    onSuccess: () => {
+      toast.success(`Successfully aborted query (ID: ${activity.pid})`)
+    },
+  })
+
+  const getBadgeVariant = (state: DatabaseActivity['state']) => {
+    if (state === 'active') return 'success'
+    if (state === 'idle in transaction') return 'warning'
+    return 'default'
+  }
+
+  const durationSeconds = getDuration(activity)
+
+  /**
+   * Queries in "active state": 30s threshold is long enough (most CRUD queries should be quick)
+   * Queries in "idle in transaction" state: This actively holds locks and blocks autovacuum while contributing nothing, so important to surface early at 10s threshold
+   */
+  const queryRunningLongWarning =
+    !!durationSeconds &&
+    ((activity.state === 'active' && durationSeconds >= 30) ||
+      (activity.state === 'idle in transaction' && durationSeconds >= 10))
+
+  const onConfirmTerminate = async () => {
+    try {
+      await abortQuery({
+        pid: activity.pid,
+        projectRef: project?.ref,
+        connectionString: project?.connectionString,
+      })
+    } catch (error) {}
+  }
+
+  return (
+    <>
+      <TableRow id={activity.pid.toString()} key={activity.pid}>
+        <TableCell className="relative w-[70px]">
+          {selectedPid === activity.pid && (
+            <div className="absolute h-full bg-brand top-0 left-0 w-1 bg-foreground-lighter"></div>
+          )}
+          <Badge variant={getBadgeVariant(activity.state)}>{activity.state}</Badge>
+        </TableCell>
+        <TableCell className="max-w-[300px]">
+          <HoverCard openDelay={100} closeDelay={100}>
+            <HoverCardTrigger>
+              <p
+                className={cn(
+                  'truncate font-mono tracking-tighter',
+                  activity.query === null && 'text-foreground-lighter'
+                )}
+              >
+                {activity.query ?? 'No query'}
+              </p>
+            </HoverCardTrigger>
+            {activity.query && (
+              <HoverCardContent align="start" className="w-96 p-0">
+                <CodeBlock
+                  hideLineNumbers
+                  className={cn(
+                    'max-w-96 border-none [&>code]:text-xs max-h-64',
+                    '[&>code]:m-0 [&>code>span]:flex [&>code>span]:flex-wrap min-h-11'
+                  )}
+                  wrapperClassName={cn('[&_pre]:px-4 [&_pre]:py-0')}
+                  language="pgsql"
+                  value={formatSql(activity.query)}
+                />
+              </HoverCardContent>
+            )}
+          </HoverCard>
+          <p className="text-xs text-foreground-lighter flex items-center gap-x-1 mt-0.5 truncate">
+            <span>PID: {activity.pid}</span>
+            <span>·</span>
+            <span>{activity.role_name}</span>
+            {activity.application_name && (
+              <>
+                <span>·</span>
+                <span>{activity.application_name}</span>
+              </>
+            )}
+          </p>
+        </TableCell>
+
+        <TableCell>
+          <p
+            className={cn(
+              'tabular-nums truncate',
+              queryRunningLongWarning ? 'text-warning' : undefined
+            )}
+          >
+            {durationSeconds !== null ? (
+              formatDuration(durationSeconds * 1000, 0)
+            ) : (
+              <Minus size={12} className="text-foreground-lighter" />
+            )}
+          </p>
+        </TableCell>
+
+        <TableCell>
+          {activity.blocked_by.length > 0 ? (
+            activity.blocked_by.map((pid, index) => {
+              const blockedProcess = data?.find((x) => x.pid === pid)
+
+              return (
+                <Fragment key={pid}>
+                  {index > 0 && ', '}
+                  <Tooltip>
+                    <TooltipTrigger
+                      className={cn(InlineLinkClassName, 'cursor-pointer')}
+                      onClick={() => setSelectedPid(pid)}
+                    >
+                      {pid}
+                    </TooltipTrigger>
+                    <TooltipContent side="bottom" className="min-w-64 max-w-80">
+                      <p className="truncate">
+                        <code className="tracking-tighter">{blockedProcess?.query}</code>
+                      </p>
+                      <p className="text-xs text-foreground-lighter flex items-center gap-x-0.5 mt-0.5 truncate">
+                        <span>PID: {blockedProcess?.pid}</span>
+                        <span>·</span>
+                        <span>{blockedProcess?.role_name}</span>
+                        {blockedProcess?.application_name && (
+                          <>
+                            <span>·</span>
+                            <span>{blockedProcess?.application_name}</span>
+                          </>
+                        )}
+                      </p>
+                    </TooltipContent>
+                  </Tooltip>
+                </Fragment>
+              )
+            })
+          ) : (
+            <Minus size={12} className="text-foreground-lighter" />
+          )}
+        </TableCell>
+
+        <TableCell className="text-right">
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button
+                aria-label="More actions"
+                variant="text"
+                className="px-1"
+                icon={<MoreVertical />}
+              />
+            </DropdownMenuTrigger>
+            <DropdownMenuContent align="end" className="w-44">
+              <DropdownMenuItemTooltip
+                className="gap-x-2"
+                disabled={superuserRoles?.includes(activity.role_name)}
+                onClick={() => setShowTerminateConfirmDialog(true)}
+                tooltip={{
+                  content: {
+                    side: 'left',
+                    text: 'Unable to terminate queries run by superuser roles',
+                  },
+                }}
+              >
+                <StopCircle size={12} />
+                <span>Terminate</span>
+              </DropdownMenuItemTooltip>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </TableCell>
+      </TableRow>
+
+      <AlertDialog open={showTerminateConfirmDialog} onOpenChange={setShowTerminateConfirmDialog}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Confirm to terminate this process?</AlertDialogTitle>
+            <AlertDialogDescription>
+              This will force the query to stop running.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+
+          <AlertDialogFooter>
+            <AlertDialogCancel>Cancel</AlertDialogCancel>
+            <AlertDialogAction variant="warning" onClick={onConfirmTerminate}>
+              Terminate
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </>
+  )
+}
diff --git a/apps/studio/components/interfaces/QueryPerformance/QueryPerformance.utils.ts b/apps/studio/components/interfaces/QueryPerformance/QueryPerformance.utils.ts
index a8dcebdce4100..3278b4fa426b2 100644
--- a/apps/studio/components/interfaces/QueryPerformance/QueryPerformance.utils.ts
+++ b/apps/studio/components/interfaces/QueryPerformance/QueryPerformance.utils.ts
@@ -6,7 +6,7 @@ import { getErrorMessage } from '@/lib/get-error-message'
 
 dayjs.extend(duration)
 
-export const formatDuration = (milliseconds: number) => {
+export const formatDuration = (milliseconds: number, precision: number = 2) => {
   const duration = dayjs.duration(milliseconds, 'milliseconds')
 
   const days = Math.floor(duration.asDays())
@@ -16,7 +16,7 @@ export const formatDuration = (milliseconds: number) => {
   const totalSeconds = duration.asSeconds()
 
   if (totalSeconds < 60) {
-    return `${totalSeconds.toFixed(2)}s`
+    return `${totalSeconds.toFixed(precision)}s`
   }
 
   const parts = []
diff --git a/apps/studio/components/interfaces/QueryPerformance/SqlMonacoBlock.tsx b/apps/studio/components/interfaces/QueryPerformance/SqlMonacoBlock.tsx
index a2f1fde9b21b1..c53a0a72b1597 100644
--- a/apps/studio/components/interfaces/QueryPerformance/SqlMonacoBlock.tsx
+++ b/apps/studio/components/interfaces/QueryPerformance/SqlMonacoBlock.tsx
@@ -9,6 +9,10 @@ type SqlMonacoBlockProps = {
   wrapperClassName?: string
 }
 
+// [Joshen] This is technically a duplicate of CodeBlock from `ui-patterns`
+// Should decide which is the preferred and consolidate - although rendering CodeEditor
+// is much heavier due to Monaco Editor. I'd rather we use CodeBlock (or improve that)
+// for read-only rendering of code contents
 export const SqlMonacoBlock = ({ value, wrapperClassName }: SqlMonacoBlockProps) => {
   const [copied, setCopied] = useState(false)
 
diff --git a/apps/studio/components/interfaces/Reports/v2/ReportsSelectFilter.tsx b/apps/studio/components/interfaces/Reports/v2/ReportsSelectFilter.tsx
index b7deb03170ef9..4727ce55c6a8d 100644
--- a/apps/studio/components/interfaces/Reports/v2/ReportsSelectFilter.tsx
+++ b/apps/studio/components/interfaces/Reports/v2/ReportsSelectFilter.tsx
@@ -10,6 +10,7 @@ import { z } from 'zod'
 export interface ReportSelectOption {
   label: React.ReactNode
   value: string
+  quantity?: number
   description?: string
 }
 
@@ -23,6 +24,7 @@ interface ReportsSelectFilterProps {
   onChange: (value: SelectFilters) => void
   isLoading?: boolean
   className?: string
+  popoverClassName?: string
   showSearch?: boolean
 }
 
@@ -33,6 +35,7 @@ export const ReportsSelectFilter = ({
   onChange,
   isLoading = false,
   className,
+  popoverClassName,
   showSearch = false,
 }: ReportsSelectFilterProps) => {
   const [open, setOpen] = useState(false)
@@ -47,7 +50,7 @@ export const ReportsSelectFilter = ({
   }, [open, value])
 
   const handleApply = () => {
-    onChange(tempValue)
+    onChange([...tempValue].sort())
     setOpen(false)
   }
 
@@ -80,9 +83,9 @@ export const ReportsSelectFilter = ({
           </span>
         </Button>
       </PopoverTrigger>
-      <PopoverContent align="start" className="p-0 w-72">
+      <PopoverContent align="start" className={cn('p-0 w-72', popoverClassName)}>
         <Command>
-          {showSearch && <CommandInput placeholder="Search..." />}
+          {showSearch && <CommandInput placeholder="Search..." className="text-xs" />}
           <CommandList className="max-h-72">
             <CommandEmpty>No options found.</CommandEmpty>
             <CommandGroup>
@@ -90,9 +93,7 @@ export const ReportsSelectFilter = ({
                 <CommandItem key={option.value}>
                   <Label
                     key={option.value}
-                    className={
-                      'flex items-center overflow-hidden p-1 rounded-xs gap-x-3 w-full h-full'
-                    }
+                    className={'flex items-center overflow-hidden rounded-xs gap-x-3 w-full h-full'}
                   >
                     <Checkbox
                       id={`${label}-${option.value}`}
@@ -106,10 +107,15 @@ export const ReportsSelectFilter = ({
                       }}
                       onKeyDown={handleKeyDown}
                     />
-                    <div className="flex flex-col text-xs">
-                      {option.label}
-                      {option.description && (
-                        <span className="text-foreground-lighter">{option.description}</span>
+                    <div className="flex items-center justify-between w-full">
+                      <div className="flex flex-col text-xs">
+                        <span className="flex items-center gap-x-2">{option.label}</span>
+                        {option.description && (
+                          <span className="text-foreground-lighter">{option.description}</span>
+                        )}
+                      </div>
+                      {!!option.quantity && (
+                        <code className="p-0 px-1 text-code-inline">{option.quantity}</code>
                       )}
                     </div>
                   </Label>
diff --git a/apps/studio/components/layouts/ObservabilityLayout/ObservabilityMenu.utils.tsx b/apps/studio/components/layouts/ObservabilityLayout/ObservabilityMenu.utils.tsx
index ad7bd6d88169d..efd8b8c1b9828 100644
--- a/apps/studio/components/layouts/ObservabilityLayout/ObservabilityMenu.utils.tsx
+++ b/apps/studio/components/layouts/ObservabilityLayout/ObservabilityMenu.utils.tsx
@@ -95,7 +95,7 @@ export const useGenerateObservabilityMenu = () => {
       ? [
           {
             name: 'Database Connections',
-            key: 'database-connections',
+            key: 'connections',
             url: `${baseUrl}/connections`,
             shortcutId: SHORTCUT_IDS.NAV_OBSERVABILITY_API_GATEWAY,
           },
diff --git a/apps/studio/components/ui/DropdownMenuItemTooltip.tsx b/apps/studio/components/ui/DropdownMenuItemTooltip.tsx
index 28cfc1d28a3e8..8cb3e913655e7 100644
--- a/apps/studio/components/ui/DropdownMenuItemTooltip.tsx
+++ b/apps/studio/components/ui/DropdownMenuItemTooltip.tsx
@@ -1,4 +1,4 @@
-import { ComponentProps, ComponentPropsWithoutRef, ElementRef, forwardRef } from 'react'
+import { ComponentProps, ComponentPropsWithoutRef, ElementRef, forwardRef, ReactNode } from 'react'
 import { cn, DropdownMenuItem, Tooltip, TooltipContent, TooltipTrigger } from 'ui'
 
 export const DropdownMenuItemTooltip = forwardRef<
@@ -6,7 +6,7 @@ export const DropdownMenuItemTooltip = forwardRef<
   ComponentPropsWithoutRef<typeof DropdownMenuItem> & {
     tooltip: {
       content: ComponentProps<typeof TooltipContent> & {
-        text?: string
+        text?: string | ReactNode
       }
     }
   }
diff --git a/apps/studio/data/database/activity-query.ts b/apps/studio/data/database/activity-query.ts
new file mode 100644
index 0000000000000..447f0f6265808
--- /dev/null
+++ b/apps/studio/data/database/activity-query.ts
@@ -0,0 +1,119 @@
+import { getPgStatActivitySql } from '@supabase/pg-meta'
+import { useQuery } from '@tanstack/react-query'
+
+import { databaseKeys } from './keys'
+import { executeSql } from '@/data/sql/execute-sql-mutation'
+import { ResponseError, UseCustomQueryOptions } from '@/types'
+
+type LockWaitEvent =
+  | 'relation'
+  | 'extend'
+  | 'page'
+  | 'tuple'
+  | 'transactionid'
+  | 'virtualxid'
+  | 'speculative token'
+  | 'object'
+  | 'userlock'
+  | 'advisory'
+  | 'applytransaction'
+
+type ClientWaitEvent = 'ClientRead' | 'ClientWrite' | 'WalSenderWaitForWAL' | 'WalSenderWriteData'
+
+type TimeoutWaitEvent =
+  | 'BaseBackupThrottle'
+  | 'CheckpointWriteDelay'
+  | 'PgSleep'
+  | 'RecoveryApplyDelay'
+  | 'VacuumDelay'
+  | 'VacuumTruncate'
+
+type ActivityWaitEvent =
+  | 'ArchiverMain'
+  | 'AutoVacuumMain'
+  | 'BgWriterHibernate'
+  | 'BgWriterMain'
+  | 'CheckpointerMain'
+  | 'LogicalApplyMain'
+  | 'LogicalLauncherMain'
+  | 'WalReceiverMain'
+  | 'WalSenderMain'
+  | 'WalWriterMain'
+
+type BufferPinWaitEvent = 'BufferPin'
+type IOWaitEvent = string
+type IPCWaitEvent = string
+type LWLockWaitEvent = string
+
+/**
+ * wait_event_type: What the session is blocked on
+ * wait_event: The specific event within that wait type
+ * */
+type WaitEvent =
+  | { wait_event_type: 'Lock'; wait_event: LockWaitEvent }
+  | { wait_event_type: 'Client'; wait_event: ClientWaitEvent }
+  | { wait_event_type: 'Timeout'; wait_event: TimeoutWaitEvent }
+  | { wait_event_type: 'Activity'; wait_event: ActivityWaitEvent }
+  | { wait_event_type: 'BufferPin'; wait_event: BufferPinWaitEvent }
+  | { wait_event_type: 'Extension'; wait_event: string }
+  | { wait_event_type: 'IO'; wait_event: IOWaitEvent }
+  | { wait_event_type: 'IPC'; wait_event: IPCWaitEvent }
+  | { wait_event_type: 'LWLock'; wait_event: LWLockWaitEvent }
+  | { wait_event_type: null; wait_event: null }
+
+export type DatabaseActivity = {
+  pid: number
+  role_name: string
+  application_name: string
+  blocked_by: number[]
+  query: string | null
+  query_start: string | null
+  transaction_start: string | null
+  state_change: string | null
+  state:
+    | 'idle'
+    | 'active'
+    | 'idle in transaction'
+    | 'idle in transaction (aborted)'
+    | 'fastpath function call'
+    | 'disabled'
+    | null
+} & WaitEvent
+
+export type DatabaseActivityVariables = {
+  projectRef?: string
+  connectionString?: string | null
+}
+
+export async function getDatabaseActivity(
+  { projectRef, connectionString }: DatabaseActivityVariables,
+  signal?: AbortSignal
+) {
+  const sql = getPgStatActivitySql()
+
+  const { result } = await executeSql(
+    { projectRef, connectionString, sql, queryKey: ['activity'] },
+    signal
+  )
+
+  return (result ?? []).filter(
+    (x: DatabaseActivity) => !x.query?.startsWith(sql)
+  ) as DatabaseActivity[]
+}
+
+export type DatabaseActivityData = Awaited<ReturnType<typeof getDatabaseActivity>>
+export type DatabaseActivityError = ResponseError
+
+export const useDatabaseActivityQuery = <TData = DatabaseActivityData>(
+  { projectRef, connectionString }: DatabaseActivityVariables,
+  {
+    enabled = true,
+    ...options
+  }: UseCustomQueryOptions<DatabaseActivityData, DatabaseActivityError, TData> = {}
+) =>
+  useQuery<DatabaseActivityData, DatabaseActivityError, TData>({
+    queryKey: databaseKeys.databaseActivity(projectRef),
+    queryFn: ({ signal }) => getDatabaseActivity({ projectRef, connectionString }, signal),
+    enabled: enabled && typeof projectRef !== 'undefined',
+    ...options,
+  })
diff --git a/apps/studio/data/database/keys.ts b/apps/studio/data/database/keys.ts
index 9a2b67d9aa611..b020ef61788d8 100644
--- a/apps/studio/data/database/keys.ts
+++ b/apps/studio/data/database/keys.ts
@@ -64,6 +64,8 @@ export const databaseKeys = {
   ) => ['projects', projectRef, 'table-index-advisor', schema, table] as const,
   supamonitorEnabled: (projectRef: string | undefined) =>
     ['projects', projectRef, 'supamonitor-enabled'] as const,
+  databaseActivity: (projectRef: string | undefined) =>
+    ['projects', projectRef, 'database-activity'] as const,
 }
 
 export const getLiveTupleEstimateKey = (
diff --git a/apps/studio/pages/project/[ref]/observability/connections.tsx b/apps/studio/pages/project/[ref]/observability/connections.tsx
new file mode 100644
index 0000000000000..96efd9538ca14
--- /dev/null
+++ b/apps/studio/pages/project/[ref]/observability/connections.tsx
@@ -0,0 +1,55 @@
+import { Pause, Play } from 'lucide-react'
+import { useState } from 'react'
+import { Badge, Button, Tooltip, TooltipContent, TooltipTrigger } from 'ui'
+
+import { Activity } from '@/components/interfaces/Observability/DatabaseConnections/Activity'
+import ReportPadding from '@/components/interfaces/Reports/ReportPadding'
+import { DefaultLayout } from '@/components/layouts/DefaultLayout'
+import ObservabilityLayout from '@/components/layouts/ObservabilityLayout/ObservabilityLayout'
+import type { NextPageWithLayout } from '@/types'
+
+export const DatabaseConnections: NextPageWithLayout = () => {
+  const [live, setLive] = useState(true)
+
+  return (
+    <ReportPadding>
+      <div className="flex items-center justify-between">
+        <div className="flex items-center gap-x-2">
+          <h1>Database Connections</h1>
+          {live && (
+            <Tooltip>
+              <TooltipTrigger>
+                <Badge variant="success">
+                  <span className="h-1.5 w-1.5 bg-brand rounded-full animate-pulse" />
+                  <span>Live</span>
+                </Badge>
+              </TooltipTrigger>
+              <TooltipContent side="bottom">
+                Data on this page is refreshed every 3 seconds
+              </TooltipContent>
+            </Tooltip>
+          )}
+        </div>
+        <div className="flex items-center gap-x-2">
+          <Button
+            variant={live ? 'default' : 'primary'}
+            onClick={() => setLive((prev) => !prev)}
+            icon={live ? <Pause /> : <Play />}
+          >
+            {live ? 'Pause' : 'Live'}
+          </Button>
+        </div>
+      </div>
+
+      <Activity live={live} />
+    </ReportPadding>
+  )
+}
+
+DatabaseConnections.getLayout = (page) => (
+  <DefaultLayout>
+    <ObservabilityLayout title="Database Connections">{page}</ObservabilityLayout>
+  </DefaultLayout>
+)
+
+export default DatabaseConnections
diff --git a/apps/studio/routeTree.gen.ts b/apps/studio/routeTree.gen.ts
index 92c65cbe68561..8f8e52c4d4db9 100644
--- a/apps/studio/routeTree.gen.ts
+++ b/apps/studio/routeTree.gen.ts
@@ -118,6 +118,7 @@ import { Route as ProjectRefObservabilityQueryInsightsRouteImport } from './rout
 import { Route as ProjectRefObservabilityPostgrestRouteImport } from './routes/project/$ref/observability/postgrest'
 import { Route as ProjectRefObservabilityEdgeFunctionsRouteImport } from './routes/project/$ref/observability/edge-functions'
 import { Route as ProjectRefObservabilityDatabaseRouteImport } from './routes/project/$ref/observability/database'
+import { Route as ProjectRefObservabilityConnectionsRouteImport } from './routes/project/$ref/observability/connections'
 import { Route as ProjectRefObservabilityAuthRouteImport } from './routes/project/$ref/observability/auth'
 import { Route as ProjectRefObservabilityApiOverviewRouteImport } from './routes/project/$ref/observability/api-overview'
 import { Route as ProjectRefObservabilityIdRouteImport } from './routes/project/$ref/observability/$id'
@@ -890,6 +891,12 @@ const ProjectRefObservabilityDatabaseRoute =
     path: '/database',
     getParentRoute: () => ProjectRefObservabilityRoute,
   } as any)
+const ProjectRefObservabilityConnectionsRoute =
+  ProjectRefObservabilityConnectionsRouteImport.update({
+    id: '/connections',
+    path: '/connections',
+    getParentRoute: () => ProjectRefObservabilityRoute,
+  } as any)
 const ProjectRefObservabilityAuthRoute =
   ProjectRefObservabilityAuthRouteImport.update({
     id: '/auth',
@@ -2178,6 +2185,7 @@ export interface FileRoutesByFullPath {
   '/project/$ref/observability/$id': typeof ProjectRefObservabilityIdRoute
   '/project/$ref/observability/api-overview': typeof ProjectRefObservabilityApiOverviewRoute
   '/project/$ref/observability/auth': typeof ProjectRefObservabilityAuthRoute
+  '/project/$ref/observability/connections': typeof ProjectRefObservabilityConnectionsRoute
   '/project/$ref/observability/database': typeof ProjectRefObservabilityDatabaseRoute
   '/project/$ref/observability/edge-functions': typeof ProjectRefObservabilityEdgeFunctionsRoute
   '/project/$ref/observability/postgrest': typeof ProjectRefObservabilityPostgrestRoute
@@ -2473,6 +2481,7 @@ export interface FileRoutesByTo {
   '/project/$ref/observability/$id': typeof ProjectRefObservabilityIdRoute
   '/project/$ref/observability/api-overview': typeof ProjectRefObservabilityApiOverviewRoute
   '/project/$ref/observability/auth': typeof ProjectRefObservabilityAuthRoute
+  '/project/$ref/observability/connections': typeof ProjectRefObservabilityConnectionsRoute
   '/project/$ref/observability/database': typeof ProjectRefObservabilityDatabaseRoute
   '/project/$ref/observability/edge-functions': typeof ProjectRefObservabilityEdgeFunctionsRoute
   '/project/$ref/observability/postgrest': typeof ProjectRefObservabilityPostgrestRoute
@@ -2781,6 +2790,7 @@ export interface FileRoutesById {
   '/project/$ref/observability/$id': typeof ProjectRefObservabilityIdRoute
   '/project/$ref/observability/api-overview': typeof ProjectRefObservabilityApiOverviewRoute
   '/project/$ref/observability/auth': typeof ProjectRefObservabilityAuthRoute
+  '/project/$ref/observability/connections': typeof ProjectRefObservabilityConnectionsRoute
   '/project/$ref/observability/database': typeof ProjectRefObservabilityDatabaseRoute
   '/project/$ref/observability/edge-functions': typeof ProjectRefObservabilityEdgeFunctionsRoute
   '/project/$ref/observability/postgrest': typeof ProjectRefObservabilityPostgrestRoute
@@ -3089,6 +3099,7 @@ export interface FileRouteTypes {
     | '/project/$ref/observability/$id'
     | '/project/$ref/observability/api-overview'
     | '/project/$ref/observability/auth'
+    | '/project/$ref/observability/connections'
     | '/project/$ref/observability/database'
     | '/project/$ref/observability/edge-functions'
     | '/project/$ref/observability/postgrest'
@@ -3384,6 +3395,7 @@ export interface FileRouteTypes {
     | '/project/$ref/observability/$id'
     | '/project/$ref/observability/api-overview'
     | '/project/$ref/observability/auth'
+    | '/project/$ref/observability/connections'
     | '/project/$ref/observability/database'
     | '/project/$ref/observability/edge-functions'
     | '/project/$ref/observability/postgrest'
@@ -3691,6 +3703,7 @@ export interface FileRouteTypes {
     | '/project/$ref/observability/$id'
     | '/project/$ref/observability/api-overview'
     | '/project/$ref/observability/auth'
+    | '/project/$ref/observability/connections'
     | '/project/$ref/observability/database'
     | '/project/$ref/observability/edge-functions'
     | '/project/$ref/observability/postgrest'
@@ -4735,6 +4748,13 @@ declare module '@tanstack/react-router' {
       preLoaderRoute: typeof ProjectRefObservabilityDatabaseRouteImport
       parentRoute: typeof ProjectRefObservabilityRoute
     }
+    '/project/$ref/observability/connections': {
+      id: '/project/$ref/observability/connections'
+      path: '/connections'
+      fullPath: '/project/$ref/observability/connections'
+      preLoaderRoute: typeof ProjectRefObservabilityConnectionsRouteImport
+      parentRoute: typeof ProjectRefObservabilityRoute
+    }
     '/project/$ref/observability/auth': {
       id: '/project/$ref/observability/auth'
       path: '/auth'
@@ -6557,6 +6577,7 @@ interface ProjectRefObservabilityRouteChildren {
   ProjectRefObservabilityIdRoute: typeof ProjectRefObservabilityIdRoute
   ProjectRefObservabilityApiOverviewRoute: typeof ProjectRefObservabilityApiOverviewRoute
   ProjectRefObservabilityAuthRoute: typeof ProjectRefObservabilityAuthRoute
+  ProjectRefObservabilityConnectionsRoute: typeof ProjectRefObservabilityConnectionsRoute
   ProjectRefObservabilityDatabaseRoute: typeof ProjectRefObservabilityDatabaseRoute
   ProjectRefObservabilityEdgeFunctionsRoute: typeof ProjectRefObservabilityEdgeFunctionsRoute
   ProjectRefObservabilityPostgrestRoute: typeof ProjectRefObservabilityPostgrestRoute
@@ -6573,6 +6594,8 @@ const ProjectRefObservabilityRouteChildren: ProjectRefObservabilityRouteChildren
     ProjectRefObservabilityApiOverviewRoute:
       ProjectRefObservabilityApiOverviewRoute,
     ProjectRefObservabilityAuthRoute: ProjectRefObservabilityAuthRoute,
+    ProjectRefObservabilityConnectionsRoute:
+      ProjectRefObservabilityConnectionsRoute,
     ProjectRefObservabilityDatabaseRoute: ProjectRefObservabilityDatabaseRoute,
     ProjectRefObservabilityEdgeFunctionsRoute:
       ProjectRefObservabilityEdgeFunctionsRoute,
diff --git a/apps/studio/routes/project/$ref/observability/connections.tsx b/apps/studio/routes/project/$ref/observability/connections.tsx
new file mode 100644
index 0000000000000..eebbb30806d30
--- /dev/null
+++ b/apps/studio/routes/project/$ref/observability/connections.tsx
@@ -0,0 +1,14 @@
+import { createFileRoute } from '@tanstack/react-router'
+
+import DatabaseConnections from '@/pages/project/[ref]/observability/connections'
+
+export const Route = createFileRoute('/project/$ref/observability/connections')({
+  component: ObservabilityConnectionsRoute,
+  staticData: {
+    observabilityLayoutTitle: 'API Gateway',
+  },
+})
+
+function ObservabilityConnectionsRoute() {
+  return <DatabaseConnections dehydratedState={undefined} />
+}
diff --git a/packages/pg-meta/src/sql/studio/database/activity.ts b/packages/pg-meta/src/sql/studio/database/activity.ts
new file mode 100644
index 0000000000000..6059b36d377ca
--- /dev/null
+++ b/packages/pg-meta/src/sql/studio/database/activity.ts
@@ -0,0 +1,23 @@
+import { safeSql, type SafeSqlFragment } from '../../../pg-format'
+
+export const getPgStatActivitySql = (): SafeSqlFragment => {
+  return safeSql`
+select
+  a.pid,
+  a.usename as role_name,
+  a.application_name,
+  a.state,
+  a.query,
+  a.wait_event_type,
+  a.wait_event,
+  a.xact_start as transaction_start,
+  a.query_start,
+  a.state_change,
+  pg_blocking_pids(a.pid) as blocked_by
+from pg_stat_activity a
+where a.datname = current_database()
+  and a.pid <> pg_backend_pid()
+  and a.backend_type = 'client backend'
+order by a.query_start asc nulls last;
+`
+}
diff --git a/packages/pg-meta/src/sql/studio/database/index.ts b/packages/pg-meta/src/sql/studio/database/index.ts
index 48e84d36ea345..f323bdcceb070 100644
--- a/packages/pg-meta/src/sql/studio/database/index.ts
+++ b/packages/pg-meta/src/sql/studio/database/index.ts
@@ -19,3 +19,4 @@ export * from './types'
 export * from './vault'
 export * from './views'
 export * from './publications'
+export * from './activity'

From 77818b814e1a89327e1ab3afdd0afb65ce189d8b Mon Sep 17 00:00:00 2001
From: Jeremias Menichelli <jmenichelli@gmail.com>
Date: Tue, 21 Jul 2026 10:54:09 +0200
Subject: [PATCH 4/7] feat: Add terraform federated content and data (#48010)

---
 apps/docs/.gitignore                          |   2 +
 .../deployment/terraform/[[...slug]]/page.tsx | 156 ++----------------
 .../terraform/terraformConstants.ts           |   9 -
 .../TerraformProviderSchema.tsx}              |  93 ++---------
 .../guides/deployment/terraform/reference.mdx |   8 +
 apps/docs/features/docs/MdxBase.shared.tsx    |   2 +
 .../internals/generate-guides-markdown.ts     |   2 +
 .../TerraformProviderSchema.ts                |  40 +++++
 apps/docs/lib/docs.ts                         |   1 +
 .../fetch-federated-content.ts                |  56 +++++--
 .../federated-content/sources/terraform.ts    |  32 ++++
 apps/docs/scripts/federated-content/types.ts  |  21 +++
 12 files changed, 181 insertions(+), 241 deletions(-)
 delete mode 100644 apps/docs/app/guides/deployment/terraform/terraformConstants.ts
 rename apps/docs/{app/guides/deployment/terraform/reference/page.tsx => components/TerraformProviderSchema.tsx} (85%)
 create mode 100644 apps/docs/content/guides/deployment/terraform/reference.mdx
 create mode 100644 apps/docs/internals/markdown-schema/TerraformProviderSchema.ts
 create mode 100644 apps/docs/scripts/federated-content/sources/terraform.ts

diff --git a/apps/docs/.gitignore b/apps/docs/.gitignore
index ca8ec6b88b967..f27e790639814 100644
--- a/apps/docs/.gitignore
+++ b/apps/docs/.gitignore
@@ -44,6 +44,8 @@ public/docs/
 # scripts/federated-content/fetch-federated-content.ts
 /content/guides/graphql/
 /content/guides/graphql.mdx
+/content/guides/deployment/terraform.mdx
+/content/guides/deployment/terraform/tutorial.mdx
 
 # Downloaded TypeDoc dumps under spec/reference/<lib>/<ver>/. Regenerated by
 # `cd apps/docs/spec && make download.tsdoc.v2`. Hand-authored files in the
diff --git a/apps/docs/app/guides/deployment/terraform/[[...slug]]/page.tsx b/apps/docs/app/guides/deployment/terraform/[[...slug]]/page.tsx
index 153c814eff369..d30e3452ce5cf 100644
--- a/apps/docs/app/guides/deployment/terraform/[[...slug]]/page.tsx
+++ b/apps/docs/app/guides/deployment/terraform/[[...slug]]/page.tsx
@@ -1,152 +1,26 @@
-import { GuideTemplate, newEditLink } from '~/features/docs/GuidesMdx.template'
-import { genGuideMeta, removeRedundantH1 } from '~/features/docs/GuidesMdx.utils'
+import { GuideTemplate } from '~/features/docs/GuidesMdx.template'
+import {
+  genGuideMeta,
+  genGuidesStaticParams,
+  getGuidesMarkdown,
+} from '~/features/docs/GuidesMdx.utils'
 import { getEmptyArray } from '~/features/helpers.fn'
 import { IS_DEV } from '~/lib/constants'
-import { isValidGuideFrontmatter } from '~/lib/docs'
-import { linkTransform, UrlTransformFunction } from '~/lib/mdx/plugins/rehypeLinkTransform'
-import remarkMkDocsAdmonition from '~/lib/mdx/plugins/remarkAdmonition'
-import { removeTitle } from '~/lib/mdx/plugins/remarkRemoveTitle'
-import remarkPyMdownTabs from '~/lib/mdx/plugins/remarkTabs'
-import { getGitHubFileContents } from '~/lib/octokit'
-import { SerializeOptions } from '~/types/next-mdx-remote-serialize'
-import matter from 'gray-matter'
-import { notFound } from 'next/navigation'
-import rehypeSlug from 'rehype-slug'
-
-import {
-  terraformDocsBranch,
-  terraformDocsDocsDir,
-  terraformDocsOrg,
-  terraformDocsRepo,
-} from '../terraformConstants'
 
-// Each external docs page is mapped to a local page
-const pageMap = [
-  {
-    remoteFile: 'README.md',
-    meta: {
-      title: 'Terraform Provider',
-    },
-    useRoot: true,
-  },
-  {
-    slug: 'tutorial',
-    remoteFile: 'tutorial.md',
-    meta: {
-      title: 'Using the Supabase Terraform Provider',
-    },
-  },
-]
-
-interface Params {
-  slug?: string[]
-}
+type Params = { slug?: string[] }
 
 const TerraformDocs = async (props: { params: Promise<Params> }) => {
   const params = await props.params
-  const { meta, ...data } = await getContent(params)
-
-  const options = {
-    mdxOptions: {
-      remarkPlugins: [remarkMkDocsAdmonition, remarkPyMdownTabs, [removeTitle, meta.title]],
-      rehypePlugins: [[linkTransform, urlTransform], rehypeSlug],
-    },
-  } as SerializeOptions
-
-  return <GuideTemplate mdxOptions={options} meta={meta} {...data} />
-}
-
-/**
- * The GitHub repo uses relative links, which don't lead to the right locations
- * in docs.
- *
- * @param url The original link, as written in the Markdown file
- * @returns The rewritten link
- */
-const urlTransform: UrlTransformFunction = (url: string) => {
-  try {
-    const placeholderHostname = 'placeholder'
-    const { hostname, pathname, hash } = new URL(url, `http://${placeholderHostname}`)
-
-    // Don't modify a url with a FQDN or a url that's only a hash
-    if (hostname !== placeholderHostname || pathname === '/') {
-      return url
-    }
-
-    const getBasename = (pathname: string) =>
-      pathname.endsWith('.md') ? pathname.replace(/\.md$/, '') : pathname
-    const stripLeadingPrefix = (pathname: string) => pathname.replace(/^\//, '')
-    const stripLeadingDocs = (pathname: string) => pathname.replace(/^docs\//, '')
-
-    const relativePath = stripLeadingPrefix(getBasename(pathname))
-
-    const page = pageMap.find(
-      ({ remoteFile, useRoot }) =>
-        (useRoot && `${relativePath}.md` === remoteFile) ||
-        (!useRoot && `${stripLeadingDocs(relativePath)}.md` === remoteFile)
-    )
-
-    if (page) {
-      return 'terraform' + `/${page.slug}` + hash
-    }
-
-    // If we don't have this page in our docs, link to GitHub repo
-    return `https://github.com/${terraformDocsOrg}/${terraformDocsRepo}/blob/${terraformDocsBranch}${pathname}${hash}`
-  } catch (err) {
-    console.error('Error transforming markdown URL', err)
-    return url
-  }
-}
-
-/**
- * Fetch markdown from external repo
- */
-const getContent = async ({ slug }: Params) => {
-  const [requestedSlug] = slug ?? []
-  const page = pageMap.find((page) => page.slug === requestedSlug)
-
-  if (!page) {
-    notFound()
-  }
-
-  const { meta, remoteFile, useRoot } = page
-
-  const editLink = newEditLink(
-    `${terraformDocsOrg}/${terraformDocsRepo}/blob/${terraformDocsBranch}/${useRoot ? '' : `${terraformDocsDocsDir}/`}${remoteFile}`
-  )
-
-  let rawContent = await getGitHubFileContents({
-    org: terraformDocsOrg,
-    repo: terraformDocsRepo,
-    path: useRoot ? remoteFile : `${terraformDocsDocsDir}/${remoteFile}`,
-    branch: terraformDocsBranch,
-  })
-  // Strip out HTML comments
-  rawContent = rawContent.replace(/<!--.*?-->/, '')
-  let { content, data } = matter(rawContent)
-
-  // Remove the title from the content so it isn't duplicated in the final display
-  content = removeRedundantH1(content)
-
-  Object.assign(meta, data)
-
-  if (!isValidGuideFrontmatter(meta)) {
-    throw Error('Guide frontmatter is invalid.')
-  }
+  const slug = ['deployment', 'terraform', ...(params.slug ?? [])]
+  const data = await getGuidesMarkdown(slug)
 
-  return {
-    pathname:
-      `/guides/deployment/terraform${slug?.length ? `/${slug.join('/')}` : ''}` satisfies `/${string}`,
-    meta,
-    content,
-    editLink,
-  }
+  return <GuideTemplate {...data!} />
 }
 
-const generateStaticParams = !IS_DEV
-  ? async () => pageMap.map(({ slug }) => ({ slug: slug ? [slug] : [] }))
-  : getEmptyArray
-const generateMetadata = genGuideMeta(getContent)
+const generateStaticParams = !IS_DEV ? genGuidesStaticParams('deployment/terraform') : getEmptyArray
+const generateMetadata = genGuideMeta((params: { slug?: string[] }) =>
+  getGuidesMarkdown(['deployment', 'terraform', ...(params.slug ?? [])])
+)
 
 export default TerraformDocs
-export { generateMetadata, generateStaticParams }
+export { generateStaticParams, generateMetadata }
diff --git a/apps/docs/app/guides/deployment/terraform/terraformConstants.ts b/apps/docs/app/guides/deployment/terraform/terraformConstants.ts
deleted file mode 100644
index 0cc7ad3125bb1..0000000000000
--- a/apps/docs/app/guides/deployment/terraform/terraformConstants.ts
+++ /dev/null
@@ -1,9 +0,0 @@
-/**
- * Information on where to fetch docs content
- */
-const terraformDocsOrg = 'supabase'
-const terraformDocsRepo = 'terraform-provider-supabase'
-const terraformDocsBranch = 'v1.1.3'
-const terraformDocsDocsDir = 'docs'
-
-export { terraformDocsOrg, terraformDocsRepo, terraformDocsBranch, terraformDocsDocsDir }
diff --git a/apps/docs/app/guides/deployment/terraform/reference/page.tsx b/apps/docs/components/TerraformProviderSchema.tsx
similarity index 85%
rename from apps/docs/app/guides/deployment/terraform/reference/page.tsx
rename to apps/docs/components/TerraformProviderSchema.tsx
index 8b974373fe417..feb933300937f 100644
--- a/apps/docs/app/guides/deployment/terraform/reference/page.tsx
+++ b/apps/docs/components/TerraformProviderSchema.tsx
@@ -1,31 +1,13 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { TabPanel, Tabs } from '~/features/ui/Tabs'
+import { GENERATED_DIRECTORY } from '~/lib/docs'
 import { codeBlock } from 'common-tags'
 import { Check, PlusCircle } from 'lucide-react'
-import Link from 'next/link'
 import ReactMarkdown from 'react-markdown'
 import { Heading, Popover, PopoverContent, PopoverTrigger } from 'ui'
 import { CodeBlock } from 'ui-patterns/CodeBlock'
 
-import {
-  terraformDocsBranch,
-  terraformDocsDocsDir,
-  terraformDocsOrg,
-  terraformDocsRepo,
-} from '../terraformConstants'
-import { GuideTemplate, newEditLink } from '@/features/docs/GuidesMdx.template'
-import { genGuideMeta } from '@/features/docs/GuidesMdx.utils'
-import { TabPanel, Tabs } from '@/features/ui/Tabs'
-import { getGitHubFileContents } from '@/lib/octokit'
-
-const meta = {
-  title: 'Terraform Provider reference',
-  subtitle: 'Resources and data sources available through the Terraform Provider',
-}
-
-const generateMetadata = genGuideMeta(() => ({
-  pathname: '/guides/deployment/terraform/reference',
-  meta,
-}))
-
 function ProviderSettings({ schema }: { schema: any }) {
   const attributes = schema.block.attributes
 
@@ -346,65 +328,16 @@ function DataSources({ schema }: { schema: any }) {
   )
 }
 
-const TerraformReferencePage = async () => {
-  const { schema } = await getSchema()
-
-  const editLink = newEditLink('supabase/terraform-provider-supabase')
+export async function TerraformProviderSchema() {
+  const raw = await readFile(join(GENERATED_DIRECTORY, 'terraform.schema.json'), 'utf-8')
+  const schema = JSON.parse(raw)
+  const providerSchema = schema.provider_schemas['registry.terraform.io/supabase/supabase']
 
   return (
-    <GuideTemplate
-      meta={meta}
-      editLink={editLink}
-      pathname="/guides/deployment/terraform/reference"
-    >
-      The Terraform Provider provides access to{' '}
-      <Link
-        href="https://developer.hashicorp.com/terraform/language/resources"
-        rel="noopener noreferrer"
-      >
-        resources
-      </Link>{' '}
-      and{' '}
-      <Link
-        href="https://developer.hashicorp.com/terraform/language/data-sources"
-        rel="noreferrer noopener"
-      >
-        data sources
-      </Link>
-      . Resources are infrastructure objects, such as a Supabase project, that you can declaratively
-      configure. Data sources are sources of information about your Supabase instances.
-      <ProviderSettings
-        schema={schema.provider_schemas['registry.terraform.io/supabase/supabase'].provider}
-      />
-      <Resources
-        schema={schema.provider_schemas['registry.terraform.io/supabase/supabase'].resource_schemas}
-      />
-      <DataSources
-        schema={
-          schema.provider_schemas['registry.terraform.io/supabase/supabase'].data_source_schemas
-        }
-      />
-    </GuideTemplate>
+    <>
+      <ProviderSettings schema={providerSchema.provider} />
+      <Resources schema={providerSchema.resource_schemas} />
+      <DataSources schema={providerSchema.data_source_schemas} />
+    </>
   )
 }
-
-/**
- * Fetch JSON schema from external repo
- */
-const getSchema = async () => {
-  const schema = JSON.parse(
-    await getGitHubFileContents({
-      org: terraformDocsOrg,
-      repo: terraformDocsRepo,
-      path: `${terraformDocsDocsDir}/schema.json`,
-      branch: terraformDocsBranch,
-    })
-  )
-
-  return {
-    schema,
-  }
-}
-
-export default TerraformReferencePage
-export { generateMetadata }
diff --git a/apps/docs/content/guides/deployment/terraform/reference.mdx b/apps/docs/content/guides/deployment/terraform/reference.mdx
new file mode 100644
index 0000000000000..da8cd9ce05d06
--- /dev/null
+++ b/apps/docs/content/guides/deployment/terraform/reference.mdx
@@ -0,0 +1,8 @@
+---
+title: Terraform Provider reference
+subtitle: Resources and data sources available through the Terraform Provider
+---
+
+The Terraform Provider provides access to [resources](https://developer.hashicorp.com/terraform/language/resources) and [data sources](https://developer.hashicorp.com/terraform/language/data-sources). Resources are infrastructure objects, such as a Supabase project, that you can declaratively configure. Data sources are sources of information about your Supabase instances.
+
+<TerraformProviderSchema />
diff --git a/apps/docs/features/docs/MdxBase.shared.tsx b/apps/docs/features/docs/MdxBase.shared.tsx
index 993891a12ba9b..70aba0cb37b02 100644
--- a/apps/docs/features/docs/MdxBase.shared.tsx
+++ b/apps/docs/features/docs/MdxBase.shared.tsx
@@ -19,6 +19,7 @@ import { RealtimeLimitsEstimator } from '~/components/RealtimeLimitsEstimator'
 import { RegionsList, SmartRegionsList } from '~/components/RegionsList'
 import { SharedData } from '~/components/SharedData'
 import StepHikeCompact from '~/components/StepHikeCompact'
+import { TerraformProviderSchema } from '~/components/TerraformProviderSchema'
 import { CodeSampleDummy, CodeSampleWrapper } from '~/features/directives/CodeSample.client'
 import { NamedCodeBlock } from '~/features/directives/CodeTabs.components'
 import { MdxAnchor } from '~/features/docs/MdxAnchor'
@@ -111,6 +112,7 @@ const components = {
   StepHikeCompact,
   Tabs,
   TabPanel,
+  TerraformProviderSchema,
   InfoTooltip,
   a: MdxAnchor,
   h2: (props: ComponentPropsWithoutRef<'h2'>) => (
diff --git a/apps/docs/internals/generate-guides-markdown.ts b/apps/docs/internals/generate-guides-markdown.ts
index 94a13b727d7e1..5e19d7fd2fbc8 100644
--- a/apps/docs/internals/generate-guides-markdown.ts
+++ b/apps/docs/internals/generate-guides-markdown.ts
@@ -34,6 +34,7 @@ import { RegionsList, SmartRegionsList } from './markdown-schema/RegionsList'
 import { SharedData } from './markdown-schema/SharedData'
 import { StepHike } from './markdown-schema/StepHike'
 import { TabPanel } from './markdown-schema/TabPanel'
+import { TerraformProviderSchema } from './markdown-schema/TerraformProviderSchema'
 import {
   collectMarkdownSources,
   type FrontmatterFormat,
@@ -187,6 +188,7 @@ const SCHEMA: ComponentSchema = {
   ContentListings,
   NavData,
   SharedData,
+  TerraformProviderSchema,
 }
 
 function parseFrontmatter(raw: string, frontmatter: FrontmatterFormat) {
diff --git a/apps/docs/internals/markdown-schema/TerraformProviderSchema.ts b/apps/docs/internals/markdown-schema/TerraformProviderSchema.ts
new file mode 100644
index 0000000000000..91c31732e28b3
--- /dev/null
+++ b/apps/docs/internals/markdown-schema/TerraformProviderSchema.ts
@@ -0,0 +1,40 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+const SCHEMA_PATH = path.join(process.cwd(), 'features/docs/generated/terraform.schema.json')
+
+function attributesTable(attributes: Record<string, any>, extraColumns: string[]): string {
+  const columns = ['Description', ...extraColumns]
+  const header = `| Attribute | ${columns.join(' | ')} |`
+  const divider = `| --- | ${columns.map(() => '---').join(' | ')} |`
+  const rows = Object.entries(attributes).map(
+    ([name, attribute]) =>
+      `| \`${name}\` | ${columns.map((column) => String(attribute[column.toLowerCase()] ?? '')).join(' | ')} |`
+  )
+  return [header, divider, ...rows].join('\n')
+}
+
+export const TerraformProviderSchema = (): string => {
+  const schema = JSON.parse(readFileSync(SCHEMA_PATH, 'utf-8'))
+  const provider = schema.provider_schemas['registry.terraform.io/supabase/supabase']
+
+  const resources = Object.entries(provider.resource_schemas)
+    .map(
+      ([name, resource]: [string, any]) =>
+        `### ${name}\n\n${attributesTable(resource.block.attributes, ['Type', 'Required', 'Optional'])}`
+    )
+    .join('\n\n')
+
+  const dataSources = Object.entries(provider.data_source_schemas)
+    .map(
+      ([name, dataSource]: [string, any]) =>
+        `### ${name}\n\n${attributesTable(dataSource.block.attributes, ['Type', 'Required', 'Optional'])}`
+    )
+    .join('\n\n')
+
+  return [
+    `## Provider settings\n\n${attributesTable(provider.provider.block.attributes, ['Type', 'Optional', 'Sensitive'])}`,
+    `## Resources\n\n${resources}`,
+    `## Data sources\n\n${dataSources}`,
+  ].join('\n\n')
+}
diff --git a/apps/docs/lib/docs.ts b/apps/docs/lib/docs.ts
index d070cc84c47ab..0d91668ceefa4 100644
--- a/apps/docs/lib/docs.ts
+++ b/apps/docs/lib/docs.ts
@@ -16,6 +16,7 @@ export const CONTENT_DIRECTORY = join(DOCS_DIRECTORY, 'content')
 export const EXAMPLES_DIRECTORY = join(DOCS_DIRECTORY, 'examples')
 export const GUIDES_DIRECTORY = join(CONTENT_DIRECTORY, 'guides')
 export const PARTIALS_DIRECTORY = join(CONTENT_DIRECTORY, '_partials')
+export const GENERATED_DIRECTORY = join(DOCS_DIRECTORY, 'features/docs/generated')
 export const REF_DOCS_DIRECTORY = join(DOCS_DIRECTORY, 'docs/ref')
 export const SPEC_DIRECTORY = join(DOCS_DIRECTORY, 'spec')
 
diff --git a/apps/docs/scripts/federated-content/fetch-federated-content.ts b/apps/docs/scripts/federated-content/fetch-federated-content.ts
index 91b1df9c4e4a7..50b8e10bdd4fc 100644
--- a/apps/docs/scripts/federated-content/fetch-federated-content.ts
+++ b/apps/docs/scripts/federated-content/fetch-federated-content.ts
@@ -4,7 +4,7 @@ import { mkdir, readdir, writeFile } from 'node:fs/promises'
 import { dirname, isAbsolute, join, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { BASE_PATH } from '~/lib/constants'
-import { GUIDES_DIRECTORY } from '~/lib/docs'
+import { GENERATED_DIRECTORY, GUIDES_DIRECTORY } from '~/lib/docs'
 import remarkMkDocsAdmonition from '~/lib/mdx/plugins/remarkAdmonition'
 import { removeTitle } from '~/lib/mdx/plugins/remarkRemoveTitle'
 import remarkPyMdownTabs from '~/lib/mdx/plugins/remarkTabs'
@@ -49,6 +49,13 @@ async function loadSources(): Promise<FederatedContentSource[]> {
   )
 }
 
+/**
+ * Path of a page's remote file, relative to the repo root.
+ */
+function remotePath(source: FederatedContentSource, page: FederatedPage): string {
+  return page.useRoot ? page.remoteFile : `${source.docsDir}/${page.remoteFile}`
+}
+
 /**
  * Rewrites a link URL: pages mapped in `source.pageMap` go to their local
  * `/guides/<section>` route, everything else falls back to `externalSite`.
@@ -70,13 +77,19 @@ function transformUrl(source: FederatedContentSource, url: string): string {
           ? relative(new URL(source.externalSite).pathname, pathname)
           : pathname
     ).replace(/^\//, '')
+    const docsRelative = relativePath.replace(new RegExp(`^${source.docsDir}/`), '')
 
-    const mapped = source.pageMap.find(({ remoteFile }) => `${relativePath}.md` === remoteFile)
+    const mapped = source.pageMap.find(({ remoteFile, useRoot }) =>
+      useRoot ? `${relativePath}.md` === remoteFile : `${docsRelative}.md` === remoteFile
+    )
 
     // If we have a mapping for this page, use the mapped path; otherwise
     // link to the original docs
-    return mapped
-      ? `${BASE_PATH}/guides/${source.section}${mapped.slug ? `/${mapped.slug}` : ''}${hash}`
+    if (mapped) {
+      return `${BASE_PATH}/guides/${source.section}${mapped.slug ? `/${mapped.slug}` : ''}${hash}`
+    }
+    return source.rawFallback
+      ? `${source.externalSite}${pathname}${hash}`
       : `${source.externalSite}/${relativePath}${hash}`
   } catch (err) {
     throw Error('[DOCS] fetch-federated-content: Error transforming markdown URL', { cause: err })
@@ -87,14 +100,19 @@ async function fetchPage(source: FederatedContentSource, page: FederatedPage): P
   const raw = await getGitHubFileContents({
     org: source.org,
     repo: source.repo,
-    path: `${source.docsDir}/${page.remoteFile}`,
+    path: remotePath(source, page),
     branch: source.branch,
   })
 
   const tree = fromMarkdown(raw, PARSE_OPTIONS)
   remarkMkDocsAdmonition()(tree)
   remarkPyMdownTabs()(tree)
-  removeTitle(page.meta.title)(tree)
+  if (page.dropLeadingHeading) {
+    const [firstNode] = tree.children
+    if (firstNode?.type === 'heading' && firstNode.depth === 1) tree.children.splice(0, 1)
+  } else {
+    removeTitle(page.meta.title)(tree)
+  }
   visit(tree, ['link', 'image', 'definition'], (node: any) => {
     node.url = transformUrl(source, node.url)
   })
@@ -104,18 +122,33 @@ async function fetchPage(source: FederatedContentSource, page: FederatedPage): P
     title: page.meta.title,
     // Points the "Edit this page on GitHub" link back at the source repo
     // instead of this generated file.
-    editLink: `${source.org}/${source.repo}/blob/${source.branch}/${source.docsDir}/${page.remoteFile}`,
+    editLink: `${source.org}/${source.repo}/blob/${source.branch}/${remotePath(source, page)}`,
   }
   if (page.meta.subtitle) frontmatter.subtitle = page.meta.subtitle
 
   return matter.stringify(`${content}\n`, frontmatter)
 }
 
+async function fetchRawFile(
+  source: FederatedContentSource,
+  rawFile: NonNullable<FederatedContentSource['rawFiles']>[number]
+): Promise<void> {
+  const content = await getGitHubFileContents({
+    org: source.org,
+    repo: source.repo,
+    path: `${source.docsDir}/${rawFile.remoteFile}`,
+    branch: source.branch,
+  })
+
+  await mkdir(GENERATED_DIRECTORY, { recursive: true })
+  await writeFile(join(GENERATED_DIRECTORY, rawFile.outFile), content)
+}
+
 async function fetchSource(source: FederatedContentSource): Promise<void> {
   await mkdir(join(GUIDES_DIRECTORY, source.section), { recursive: true })
 
-  await Promise.all(
-    source.pageMap.map(async (page) => {
+  await Promise.all([
+    ...source.pageMap.map(async (page) => {
       const output = await fetchPage(source, page)
 
       const outPath = page.slug
@@ -123,8 +156,9 @@ async function fetchSource(source: FederatedContentSource): Promise<void> {
         : join(GUIDES_DIRECTORY, `${source.section}.mdx`)
 
       await writeFile(outPath, output)
-    })
-  )
+    }),
+    ...(source.rawFiles ?? []).map((rawFile) => fetchRawFile(source, rawFile)),
+  ])
 }
 
 async function fetchFederatedContent() {
diff --git a/apps/docs/scripts/federated-content/sources/terraform.ts b/apps/docs/scripts/federated-content/sources/terraform.ts
new file mode 100644
index 0000000000000..1c938d9345162
--- /dev/null
+++ b/apps/docs/scripts/federated-content/sources/terraform.ts
@@ -0,0 +1,32 @@
+import type { FederatedContentSource } from '../types'
+
+// We fetch these docs at build time from an external repo
+const terraform: FederatedContentSource = {
+  section: 'deployment/terraform',
+  org: 'supabase',
+  repo: 'terraform-provider-supabase',
+  branch: 'v1.1.3',
+  docsDir: 'docs',
+  externalSite: 'https://github.com/supabase/terraform-provider-supabase/blob/v1.1.3',
+  rawFallback: true,
+  pageMap: [
+    {
+      meta: {
+        title: 'Terraform Provider',
+      },
+      remoteFile: 'README.md',
+      useRoot: true,
+      dropLeadingHeading: true,
+    },
+    {
+      slug: 'tutorial',
+      meta: {
+        title: 'Using the Supabase Terraform Provider',
+      },
+      remoteFile: 'tutorial.md',
+    },
+  ],
+  rawFiles: [{ remoteFile: 'schema.json', outFile: 'terraform.schema.json' }],
+}
+
+export default terraform
diff --git a/apps/docs/scripts/federated-content/types.ts b/apps/docs/scripts/federated-content/types.ts
index eddd7f9cb2697..d6a2bee2afd7e 100644
--- a/apps/docs/scripts/federated-content/types.ts
+++ b/apps/docs/scripts/federated-content/types.ts
@@ -10,6 +10,14 @@ export interface FederatedPage {
   }
   /** Path of the file in the remote repo, relative to `docsDir`. */
   remoteFile: string
+  /** Fetch `remoteFile` from the repo root instead of `docsDir`. */
+  useRoot?: boolean
+  /**
+   * Unconditionally drop the first heading, regardless of whether its text
+   * matches `meta.title`. Use when the curated title intentionally differs
+   * from the source file's own heading text.
+   */
+  dropLeadingHeading?: boolean
 }
 
 /**
@@ -29,5 +37,18 @@ export interface FederatedContentSource {
   docsDir: string
   /** Public site the remote docs are also published to, used to resolve unmapped links. */
   externalSite: string
+  /**
+   * Unmapped links fall back to `${externalSite}/${relativePath}${hash}`. Set
+   * this when `externalSite` is a source-controlled host (e.g. a GitHub blob
+   * URL) that needs the file extension kept, rather than a docs site that
+   * serves clean, extensionless URLs.
+   */
+  rawFallback?: boolean
   pageMap: FederatedPage[]
+  /**
+   * Non-guide files fetched verbatim (no Markdown transform), e.g. JSON data
+   * consumed by a custom MDX component. Written to
+   * `features/docs/generated/<outFile>`.
+   */
+  rawFiles?: { remoteFile: string; outFile: string }[]
 }

From bc0c1999cac7ac77c482570da8df4183c3df7a4d Mon Sep 17 00:00:00 2001
From: Joshen Lim <joshenlimek@gmail.com>
Date: Tue, 21 Jul 2026 17:13:55 +0800
Subject: [PATCH 5/7] Update dev toolbar to support mocking org restrictions
 (#48136)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Context

Only applies for local development - adds a way to mock org restrictions
with the dev toolbar
<img width="1392" height="484" alt="image"
src="https://github.com/user-attachments/assets/64b8b0c6-c59a-453a-88fa-ffbc2565cd87"
/>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added organization-level warning controls to the development toolbar,
including a new “Organization warnings” section to simulate restriction
status variants (none, grace periods, restricted, and overdue-invoice
scenarios, including an “other org” option).
* Updated the existing project-warning controls’ guidance to reference
the current organization or project.
* **Bug Fixes**
* Improved cleanup so resetting or closing warning overrides reliably
restores the real organization and invoice warning data, including after
navigation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 .../ui/DevToolbar/ResourceWarningsTab.tsx     | 129 ++++++++++++++++--
 1 file changed, 117 insertions(+), 12 deletions(-)

diff --git a/apps/studio/components/ui/DevToolbar/ResourceWarningsTab.tsx b/apps/studio/components/ui/DevToolbar/ResourceWarningsTab.tsx
index 575fa25ffaabb..b7a3f0f1ba116 100644
--- a/apps/studio/components/ui/DevToolbar/ResourceWarningsTab.tsx
+++ b/apps/studio/components/ui/DevToolbar/ResourceWarningsTab.tsx
@@ -2,12 +2,18 @@
 
 import { useQueryClient } from '@tanstack/react-query'
 import { useParams } from 'common'
+import dayjs from 'dayjs'
 import { useEffect, useRef, useState } from 'react'
-import { cn } from 'ui'
+import { cn, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, Separator } from 'ui'
+import { InfoTooltip } from 'ui-patterns/info-tooltip'
 
+import type { OverdueInvoicesResponse } from '@/data/invoices/invoices-overdue-query'
+import { invoicesKeys } from '@/data/invoices/keys'
+import { organizationKeys } from '@/data/organizations/keys'
 import { usageKeys } from '@/data/usage/keys'
 import type { ResourceWarning } from '@/data/usage/resource-warnings-query'
 import { useSelectedOrganizationQuery } from '@/hooks/misc/useSelectedOrganization'
+import type { Organization } from '@/types'
 
 type Severity = 'warning' | 'critical' | null
 
@@ -35,7 +41,9 @@ export const ResourceWarningsTab = () => {
   const queryClient = useQueryClient()
   const { data: selectedOrg, isLoading: isOrgLoading } = useSelectedOrganizationQuery()
   const orgSlug = selectedOrg?.slug
+
   const [isReadOnly, setIsReadOnly] = useState(false)
+  const [orgWarning, setOrgWarning] = useState<string>('none')
   const [severities, setSeverities] = useState<WarningState>(INITIAL_STATE)
 
   // Track latest ref/orgSlug so the unmount cleanup always invalidates the
@@ -62,6 +70,8 @@ export const ResourceWarningsTab = () => {
           queryKey: usageKeys.resourceWarnings(latestOrgSlug, undefined),
         })
       }
+      queryClient.invalidateQueries({ queryKey: organizationKeys.list() })
+      queryClient.invalidateQueries({ queryKey: invoicesKeys.overdueInvoices() })
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
@@ -79,15 +89,26 @@ export const ResourceWarningsTab = () => {
         queryClient.invalidateQueries({
           queryKey: usageKeys.resourceWarnings(currentOrgSlug, undefined),
         })
+        queryClient.invalidateQueries({ queryKey: organizationKeys.list() })
+        queryClient.invalidateQueries({ queryKey: invoicesKeys.overdueInvoices() })
       }
       setSeverities(INITIAL_STATE)
       setIsReadOnly(false)
+      setOrgWarning('none')
       hasOverridesRef.current = false
     }
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [ref])
 
-  const applyOverrides = (nextSeverities: WarningState, nextIsReadOnly: boolean) => {
+  const applyOverrides = ({
+    nextSeverities,
+    nextIsReadOnly,
+    nextOrgWarnings,
+  }: {
+    nextSeverities: WarningState
+    nextIsReadOnly: boolean
+    nextOrgWarnings?: string
+  }) => {
     if (!orgSlug || !ref) return
     const mockWarning: ResourceWarning = {
       project: ref,
@@ -101,27 +122,78 @@ export const ResourceWarningsTab = () => {
     // slug-based (ProjectLayout, TopSection, ProjectList) consumers.
     queryClient.setQueryData(usageKeys.resourceWarnings(undefined, ref), [mockWarning])
     queryClient.setQueryData(usageKeys.resourceWarnings(orgSlug, undefined), [mockWarning])
+
+    const effectiveOrgWarning = nextOrgWarnings ?? orgWarning
+    const restrictionStatus: Organization['restriction_status'] =
+      effectiveOrgWarning === 'grace_period' ||
+      effectiveOrgWarning === 'grace_period_over' ||
+      effectiveOrgWarning === 'restricted'
+        ? effectiveOrgWarning
+        : null
+
+    queryClient.setQueryData<Organization[]>(organizationKeys.list(), (prev) =>
+      prev?.map((org) =>
+        org.slug === orgSlug
+          ? {
+              ...org,
+              restriction_status: restrictionStatus,
+              restriction_data:
+                restrictionStatus === 'grace_period'
+                  ? { grace_period_end: dayjs().add(7, 'day').toISOString() }
+                  : null,
+            }
+          : org
+      )
+    )
+
+    // Overdue invoices come from a separate, org-independent cache and are
+    // distinguished by organization_id rather than a status enum, so they can't
+    // be folded into the restriction_status patch above.
+    const selectedOrgId = selectedOrg?.id
+    const overdueInvoices: OverdueInvoicesResponse[] =
+      selectedOrgId === undefined
+        ? []
+        : effectiveOrgWarning === 'overdue_invoices'
+          ? [{ organization_id: selectedOrgId, overdue_invoice_count: 1 }]
+          : effectiveOrgWarning === 'overdue_invoices_from_other_org'
+            ? [{ organization_id: selectedOrgId + 1, overdue_invoice_count: 1 }]
+            : []
+    queryClient.setQueryData(invoicesKeys.overdueInvoices(), overdueInvoices)
+
     hasOverridesRef.current = true
   }
 
   const handleSeverityChange = (key: WarningKey, value: Severity) => {
     const next = { ...severities, [key]: value }
     setSeverities(next)
-    applyOverrides(next, isReadOnly)
+    applyOverrides({ nextSeverities: next, nextIsReadOnly: isReadOnly })
   }
 
   const handleReadOnlyChange = (value: boolean) => {
     setIsReadOnly(value)
-    applyOverrides(severities, value)
+    applyOverrides({ nextSeverities: severities, nextIsReadOnly: value })
+  }
+
+  const handleOrgWarningChange = (value: string) => {
+    setOrgWarning(value)
+    applyOverrides({
+      nextSeverities: severities,
+      nextIsReadOnly: isReadOnly,
+      nextOrgWarnings: value,
+    })
   }
 
   const handleReset = () => {
     setSeverities(INITIAL_STATE)
     setIsReadOnly(false)
+    setOrgWarning('none')
+
     hasOverridesRef.current = false
     queryClient.invalidateQueries({ queryKey: usageKeys.resourceWarnings(undefined, ref) })
     if (orgSlug) {
       queryClient.invalidateQueries({ queryKey: usageKeys.resourceWarnings(orgSlug, undefined) })
+      queryClient.invalidateQueries({ queryKey: organizationKeys.list() })
+      queryClient.invalidateQueries({ queryKey: invoicesKeys.overdueInvoices() })
     }
   }
 
@@ -133,7 +205,7 @@ export const ResourceWarningsTab = () => {
     <div className="p-6 space-y-4">
       <div className="flex items-center justify-between">
         <p className="text-sm text-foreground-light">
-          Override resource warning banners for the current project.
+          Override resource warning banners for the current organization or project.
         </p>
         <button
           onClick={handleReset}
@@ -145,15 +217,48 @@ export const ResourceWarningsTab = () => {
         </button>
       </div>
 
-      {isDisabled && (
-        <p className="text-xs text-foreground-muted">
-          {!ref ? 'Navigate to a project page to use this tab.' : 'Loading org context...'}
-        </p>
-      )}
+      <div className="flex flex-col gap-y-1">
+        <h4>Organization warnings</h4>
+      </div>
+
+      <div className={cn('space-y-3', isDisabled && 'opacity-50 pointer-events-none')}>
+        <div className="flex items-center justify-between">
+          <span className="text-sm text-foreground-light">Restriction status</span>
+          <Select value={orgWarning} onValueChange={handleOrgWarningChange}>
+            <SelectTrigger className="w-64">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="none">None</SelectItem>
+              <SelectItem value="grace_period">Grace period</SelectItem>
+              <SelectItem value="grace_period_over">Grace period over</SelectItem>
+              <SelectItem value="restricted">Restricted</SelectItem>
+              <SelectItem value="overdue_invoices">Overdue invoices</SelectItem>
+              <SelectItem value="overdue_invoices_from_other_org">
+                Overdue invoices from other org
+              </SelectItem>
+            </SelectContent>
+          </Select>
+        </div>
+      </div>
+
+      <Separator />
+
+      <div className="flex flex-col gap-y-1">
+        <h4>Project warnings</h4>
+        {isDisabled && (
+          <p className="text-xs text-foreground-muted">
+            {!ref ? 'Navigate to a project page to use this tab.' : 'Loading org context...'}
+          </p>
+        )}
+      </div>
 
       <div className={cn('space-y-3', isDisabled && 'opacity-50 pointer-events-none')}>
-        <div className="flex items-center justify-between py-2 border-b border-overlay">
-          <span className="text-sm font-medium">Read-only mode</span>
+        <div className="flex items-center justify-between">
+          <p className="text-sm text-foreground-light flex items-center gap-x-2">
+            <span>Read-only mode</span>
+            <InfoTooltip side="right">Takes precedence above all other warnings</InfoTooltip>
+          </p>
           <div className="flex gap-1">
             <SeverityButton
               active={!isReadOnly}

From 76f44bfa7122b445a290035b5f85ccbac6a7a21b Mon Sep 17 00:00:00 2001
From: Joshen Lim <joshenlimek@gmail.com>
Date: Tue, 21 Jul 2026 17:14:04 +0800
Subject: [PATCH 6/7] Update Dev toolbar to support filtering feature flags
 (#48137)

## Context

Only applies for local development - adds a way to filter feature flags
in the dev toolbar
<img width="1385" height="223" alt="image"
src="https://github.com/user-attachments/assets/323d29f6-209e-4fc3-a7d0-4160b62b5707"
/>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **New Features**
* Added search and filtering for feature flags from PostHog and
ConfigCat.
  * Added a clear button for quickly resetting searches.
* Added an informative empty state when no feature flags match the
search.
* Search terms reset automatically when switching between flag
providers.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 packages/dev-tools/DevToolbar.tsx | 51 +++++++++++++++++++++++++++++--
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/packages/dev-tools/DevToolbar.tsx b/packages/dev-tools/DevToolbar.tsx
index 413d9649e33c8..4ab86866ed045 100644
--- a/packages/dev-tools/DevToolbar.tsx
+++ b/packages/dev-tools/DevToolbar.tsx
@@ -212,6 +212,7 @@ export function DevToolbar({ extraTabs = [] }: { extraTabs?: ExtraTab[] }) {
   const [activeTab, setActiveTab] = useState<string>('events')
   const [flagsSubTab, setFlagsSubTab] = useState<'posthog' | 'configcat'>('posthog')
   const [eventFilter, setEventFilter] = useState<string>('')
+  const [flagFilter, setFlagFilter] = useState<string>('')
   const { posthog: posthogFlags, configcat: configcatFlags } = useFeatureFlags()
   const [phFlagOverrides, setPhFlagOverrides] = useState<Record<string, unknown>>({})
   const [ccFlagOverrides, setCcFlagOverrides] = useState<Record<string, unknown>>({})
@@ -353,6 +354,20 @@ export function DevToolbar({ extraTabs = [] }: { extraTabs?: ExtraTab[] }) {
   const ccOverrideCount = Object.keys(ccFlagOverrides).length
   const totalOverrideCount = phOverrideCount + ccOverrideCount
 
+  const normalizedFlagFilter = flagFilter.trim().toLowerCase()
+
+  const filteredPosthogEntries = normalizedFlagFilter
+    ? Object.entries(posthogFlags).filter(([flagName]) =>
+        flagName.toLowerCase().includes(normalizedFlagFilter)
+      )
+    : Object.entries(posthogFlags)
+
+  const filteredConfigcatEntries = normalizedFlagFilter
+    ? Object.entries(configcatFlags).filter(([flagName]) =>
+        flagName.toLowerCase().includes(normalizedFlagFilter)
+      )
+    : Object.entries(configcatFlags)
+
   if (!IS_TOOLBAR_ENABLED || !isEnabled) return null
 
   return (
@@ -493,7 +508,10 @@ export function DevToolbar({ extraTabs = [] }: { extraTabs?: ExtraTab[] }) {
                       <button
                         key={id}
                         type="button"
-                        onClick={() => setFlagsSubTab(id)}
+                        onClick={() => {
+                          setFlagsSubTab(id)
+                          setFlagFilter('')
+                        }}
                         className={cn(
                           'flex items-center justify-between px-3 py-1.5 rounded-sm text-sm text-left uppercase font-mono tracking-wide',
                           flagsSubTab === id
@@ -520,13 +538,35 @@ export function DevToolbar({ extraTabs = [] }: { extraTabs?: ExtraTab[] }) {
                 {/* Flag list */}
                 <div className="flex-1 min-h-0 overflow-y-auto pb-6">
                   <div className="divide-y">
+                    <div className="flex items-center gap-x-1 p-2">
+                      <Input
+                        size="tiny"
+                        value={flagFilter}
+                        onChange={(e) => setFlagFilter(e.target.value)}
+                        placeholder="Search flag"
+                        className="w-64"
+                      />
+                      {!!flagFilter && (
+                        <Button
+                          className="px-1"
+                          variant="text"
+                          icon={<X />}
+                          onClick={() => setFlagFilter('')}
+                        />
+                      )}
+                    </div>
+
                     {flagsSubTab === 'posthog' &&
                       (Object.keys(posthogFlags).length === 0 ? (
                         <div className="text-center text-foreground-lighter py-8 text-sm">
                           No PostHog feature flags loaded yet.
                         </div>
+                      ) : filteredPosthogEntries.length === 0 ? (
+                        <div className="text-center text-foreground-lighter py-8 text-sm">
+                          No PostHog flags match &quot;{flagFilter}&quot;.
+                        </div>
                       ) : (
-                        Object.entries(posthogFlags).map(([flagName, flagValue]) => (
+                        filteredPosthogEntries.map(([flagName, flagValue]) => (
                           <FlagRow
                             key={flagName}
                             flagName={flagName}
@@ -539,13 +579,18 @@ export function DevToolbar({ extraTabs = [] }: { extraTabs?: ExtraTab[] }) {
                           />
                         ))
                       ))}
+
                     {flagsSubTab === 'configcat' &&
                       (Object.keys(configcatFlags).length === 0 ? (
                         <div className="text-center text-foreground-lighter py-8 text-sm">
                           No ConfigCat feature flags loaded yet.
                         </div>
+                      ) : filteredConfigcatEntries.length === 0 ? (
+                        <div className="text-center text-foreground-lighter py-8 text-sm">
+                          No ConfigCat flags match &quot;{flagFilter}&quot;.
+                        </div>
                       ) : (
-                        Object.entries(configcatFlags).map(([flagName, flagValue]) => (
+                        filteredConfigcatEntries.map(([flagName, flagValue]) => (
                           <FlagRow
                             key={flagName}
                             flagName={flagName}

From c166bfc04470a541617808b1fbb6f8fd3e99358a Mon Sep 17 00:00:00 2001
From: Jordi Enric <37541088+jordienr@users.noreply.github.com>
Date: Tue, 21 Jul 2026 11:34:35 +0200
Subject: [PATCH 7/7] fix(studio): stop stacking overlaid area series in report
 charts (#48034)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Line-style report charts (auth processing time, percentiles, edge
functions, realtime, etc.) hardcoded `stackId="1"` on every `<Area>`, so
recharts summed the series additively instead of overlaying them.

When multiple series share a value (e.g. Max/Min/Avg all `153.98`), they
rendered as three stacked bands at 1x/2x/3x the value, even though the
tooltip showed the true identical values.

## Fix

Default each area to its own `stackId` (its attribute name) so series
overlay, while still honoring an explicit per-attribute `stackId` from
config — matching the existing bar-chart path directly above it.
`normalizeVisibleStackToPercent`, the only flag that would make stacked
areas intentional, is never enabled anywhere.

## Before / after

Before: three equal values drawn at `0→153.98`, `153.98→307.96`,
`307.96→461.94`.
After: all three overlay at `153.98`.

Affects every line-style multi-series report, not just auth.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- **Bug Fixes**
- Improved stacked chart behavior by consistently applying configured
series stacking settings.
- Ensured area charts can overlay correctly when no explicit stacking
configuration is provided.
  - Added safeguards for missing or invalid chart attribute data.

- **Tests**
- Added coverage for configured stack IDs, fallback behavior, empty
values, and invalid inputs.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 .../components/ui/Charts/ComposedChart.tsx    |  5 +-
 .../ui/Charts/ComposedChart.utils.test.ts     | 60 +++++++++++++++++++
 .../ui/Charts/ComposedChart.utils.tsx         | 20 +++++++
 3 files changed, 83 insertions(+), 2 deletions(-)
 create mode 100644 apps/studio/components/ui/Charts/ComposedChart.utils.test.ts

diff --git a/apps/studio/components/ui/Charts/ComposedChart.tsx b/apps/studio/components/ui/Charts/ComposedChart.tsx
index c8410e63a4843..b778bd848bc09 100644
--- a/apps/studio/components/ui/Charts/ComposedChart.tsx
+++ b/apps/studio/components/ui/Charts/ComposedChart.tsx
@@ -38,6 +38,7 @@ import {
   calculateTotalChartAggregate,
   CustomLabel,
   CustomTooltip,
+  getStackId,
   MultiAttribute,
 } from './ComposedChart.utils'
 import NoDataPlaceholder from './NoDataPlaceholder'
@@ -560,7 +561,7 @@ export function ComposedChart({
                 <Bar
                   key={attribute.name}
                   dataKey={attribute.name}
-                  stackId={attributes?.find((a) => a.attribute === attribute?.name)?.stackId ?? '1'}
+                  stackId={getStackId(attributes, attribute?.name, '1')}
                   fill={attribute.color}
                   radius={0.75}
                   opacity={1}
@@ -576,7 +577,7 @@ export function ComposedChart({
                   key={attribute.name}
                   type="linear"
                   dataKey={attribute.name}
-                  stackId="1"
+                  stackId={getStackId(attributes, attribute.name, attribute.name)}
                   fill={`url(#gradient-${attribute.name})`}
                   fillOpacity={1}
                   stroke={attribute.color}
diff --git a/apps/studio/components/ui/Charts/ComposedChart.utils.test.ts b/apps/studio/components/ui/Charts/ComposedChart.utils.test.ts
new file mode 100644
index 0000000000000..eec90bb5fe310
--- /dev/null
+++ b/apps/studio/components/ui/Charts/ComposedChart.utils.test.ts
@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+
+import { getStackId } from './ComposedChart.utils'
+import type { MultiAttribute } from './ComposedChart.utils'
+
+const attr = (attribute: string, stackId?: string): MultiAttribute => ({ attribute, stackId })
+
+describe('getStackId', () => {
+  it('returns the explicit stackId when the attribute configures one', () => {
+    const attributes = [attr('ingress', 'traffic'), attr('egress', 'traffic')]
+    expect(getStackId(attributes, 'ingress', '1')).toBe('traffic')
+    expect(getStackId(attributes, 'egress', '1')).toBe('traffic')
+  })
+
+  it('falls back when the attribute has no stackId (overlay case)', () => {
+    const attributes = [attr('avg'), attr('min'), attr('max')]
+    expect(getStackId(attributes, 'avg', 'avg')).toBe('avg')
+    expect(getStackId(attributes, 'min', 'min')).toBe('min')
+    expect(getStackId(attributes, 'max', 'max')).toBe('max')
+  })
+
+  it('falls back to the shared bar id when no stackId is configured', () => {
+    const attributes = [attr('reads'), attr('writes')]
+    expect(getStackId(attributes, 'reads', '1')).toBe('1')
+    expect(getStackId(attributes, 'writes', '1')).toBe('1')
+  })
+
+  it('falls back when the attribute is not found', () => {
+    expect(getStackId([attr('reads', 'io')], 'writes', 'fallback')).toBe('fallback')
+  })
+
+  it('does not crash on undefined or null attributes', () => {
+    expect(getStackId(undefined, 'reads', '1')).toBe('1')
+    expect(getStackId(null, 'reads', '1')).toBe('1')
+  })
+
+  it('does not crash on undefined or null name', () => {
+    expect(getStackId([attr('reads', 'io')], undefined, '1')).toBe('1')
+    expect(getStackId([attr('reads', 'io')], null, '1')).toBe('1')
+  })
+
+  it('does not crash on falsy entries in the attributes array', () => {
+    const attributes: (MultiAttribute | false | null | undefined)[] = [
+      false,
+      null,
+      undefined,
+      attr('reads', 'io'),
+    ]
+    expect(getStackId(attributes, 'reads', '1')).toBe('io')
+    expect(getStackId(attributes, 'writes', '1')).toBe('1')
+  })
+
+  it('does not crash on a non-array value', () => {
+    expect(getStackId('nope' as unknown as MultiAttribute[], 'reads', '1')).toBe('1')
+  })
+
+  it('treats an empty-string stackId as configured', () => {
+    expect(getStackId([attr('reads', '')], 'reads', '1')).toBe('')
+  })
+})
diff --git a/apps/studio/components/ui/Charts/ComposedChart.utils.tsx b/apps/studio/components/ui/Charts/ComposedChart.utils.tsx
index 9cfce65eec8f0..3aa6b215d159e 100644
--- a/apps/studio/components/ui/Charts/ComposedChart.utils.tsx
+++ b/apps/studio/components/ui/Charts/ComposedChart.utils.tsx
@@ -127,6 +127,26 @@ interface TooltipProps {
 
 const isMaxAttribute = (attributes?: MultiAttribute[]) => attributes?.find((a) => a.isMaxValue)
 
+/**
+ * Resolve the recharts `stackId` for a series.
+ *
+ * Series that share a `stackId` are stacked additively, so overlaid series
+ * (e.g. min/max/avg of the same metric) must each get a distinct id. Bar
+ * charts pass `'1'` as the fallback to stack together; area charts pass the
+ * attribute name so each series overlays independently. An explicit per-
+ * attribute `stackId` always wins.
+ */
+export const getStackId = (
+  attributes: (MultiAttribute | false | null | undefined)[] | null | undefined,
+  name: string | null | undefined,
+  fallback: string
+): string => {
+  const configured = Array.isArray(attributes)
+    ? attributes.find((a): a is MultiAttribute => !!a && a.attribute === name)?.stackId
+    : undefined
+  return configured ?? fallback
+}
+
 /**
  * Calculate the total aggregate of the chart values
  * by summing the values of the attributes