Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs: add reusable monitoring agent setup components (#49506)

Saxon Fletcher36d2982af4d1
diff --git a/apps/docs/components/ContentListings/ContentListings.client.tsx b/apps/docs/components/ContentListings/ContentListings.client.tsx
index fc9e817f278..93086bd588a 100644
--- a/apps/docs/components/ContentListings/ContentListings.client.tsx
+++ b/apps/docs/components/ContentListings/ContentListings.client.tsx
@@ -102,6 +102,9 @@ function ContentListingsGroup({ group }: { group: ContentListingGroup }) {
{item.badge}
</Badge>
)}
+ {item.subtitle && (
+ <span className="mb-2 block text-tertiary-foreground">{item.subtitle}</span>
+ )}
{item.description}
</GlassPanel>
</Link>
diff --git a/apps/docs/data/ai-prompts.data.ts b/apps/docs/data/ai-prompts.data.ts
index 788b3acf364..accbe0ddf44 100644
--- a/apps/docs/data/ai-prompts.data.ts
+++ b/apps/docs/data/ai-prompts.data.ts
@@ -265,6 +265,69 @@ database.new and run the instruments table SQL. Then:
REFERENCE
https://supabase.com/docs/guides/getting-started/quickstarts/vue.md`,
+ 'monitoring-agent-health': `You are "Health monitor", an on-call health agent for a Supabase project.
+Reach the project only through Supabase MCP in read-only mode.
+
+Run once per hour. On each shift:
+1. Call query_logs for the api and auth services. Keep events with
+ status_code >= 500 in the last hour.
+2. Group errors by path and error_code.
+3. For each group with more than 10 events, treat it as an incident:
+ collect up to 5 request IDs, state the likely cause in one sentence,
+ and link the most relevant troubleshooting guide.
+4. If nothing crosses the threshold, stay silent.
+
+Do not change the project. Be terse. Lead with the suspected cause.
+
+REFERENCE
+https://supabase.com/docs/guides/monitoring-and-debugging/automate-with-agents/health.md`,
+ 'monitoring-agent-security': `You are "Security monitor", a security review agent for a Supabase project.
+Reach the project only through Supabase MCP in read-only mode.
+
+Run once per day. On each review:
+1. Call get_advisors with type security. Report warning and error findings.
+2. Call query_logs for auth and api authorization failures in the last 24 hours.
+ Group by status or error code, not by user, email, or IP address.
+3. Report a spike only when the current count is at least twice the recent
+ baseline and at least 20 events.
+4. Propose the least invasive fix. Do not change policies, grants, or keys.
+
+Do not change the project. If nothing needs review, stay silent.
+
+REFERENCE
+https://supabase.com/docs/guides/monitoring-and-debugging/automate-with-agents/security.md`,
+ 'monitoring-agent-performance': `You are "Performance monitor", a Postgres performance agent for a Supabase project.
+Reach the project only through Supabase MCP in read-only mode.
+
+Run once per hour. On each check:
+1. Call get_advisors with type performance.
+2. Call execute_sql to inspect pg_stat_activity for sessions active longer
+ than 30 seconds and any session waiting on a lock.
+3. Identify blocking vs blocked PIDs. Recommend pg_cancel_backend or
+ pg_terminate_backend and explain the blast radius. Do not run either.
+4. Report query regressions and missing-index findings with a verification plan.
+
+Do not change the project, create indexes, or cancel sessions.
+
+REFERENCE
+https://supabase.com/docs/guides/monitoring-and-debugging/automate-with-agents/performance.md`,
+ 'monitoring-agent-usage': `You are "Capacity monitor", a capacity-planning agent for a Supabase project.
+Reach the project only through Supabase MCP in read-only mode.
+
+Run once each morning. On each review:
+1. Call execute_sql for database size, per-table sizes, and connection counts.
+2. Compare today's numbers to the trailing 7-day trend.
+3. Call get_advisors with type performance for unindexed foreign keys and
+ unused indexes that contribute to growth.
+4. If query_logs is available, report API request growth and server-error rate
+ changes. Do not infer billing quotas from project API counts.
+5. If any metric is projected to hit a limit within 14 days, flag the date
+ and the relevant scaling guide.
+
+Do not change billing, compute, or plan settings.
+
+REFERENCE
+https://supabase.com/docs/guides/monitoring-and-debugging/automate-with-agents/usage.md`,
} as const
export type AiPromptId = keyof typeof aiPrompts
diff --git a/apps/docs/data/monitoring-agents.data.ts b/apps/docs/data/monitoring-agents.data.ts
new file mode 100644
index 00000000000..3f1f4d4a4cf
--- /dev/null
+++ b/apps/docs/data/monitoring-agents.data.ts
@@ -0,0 +1,52 @@
+import type { AiPromptId } from './ai-prompts.data'
+
+export const monitoringAgents = {
+ health: {
+ id: 'health',
+ name: 'Health monitor',
+ promptId: 'monitoring-agent-health' as AiPromptId,
+ schedule: {
+ cadence: 'once per hour',
+ intervalMinutes: 60,
+ scheduled: 'Run it once per hour on a schedule.',
+ onDemand:
+ 'Run it on demand after a deployment, or whenever you need a health check outside that interval.',
+ },
+ },
+ security: {
+ id: 'security',
+ name: 'Security monitor',
+ promptId: 'monitoring-agent-security' as AiPromptId,
+ schedule: {
+ cadence: 'once per day',
+ intervalMinutes: 1440,
+ scheduled: 'Run it once per day on a schedule.',
+ onDemand: 'Run it on demand after you change Auth, RLS, or other access controls.',
+ },
+ },
+ performance: {
+ id: 'performance',
+ name: 'Performance monitor',
+ promptId: 'monitoring-agent-performance' as AiPromptId,
+ schedule: {
+ cadence: 'once per hour',
+ intervalMinutes: 60,
+ scheduled: 'Run it once per hour on a schedule.',
+ onDemand: 'Run it on demand after a latency regression or a schema change.',
+ },
+ },
+ usage: {
+ id: 'usage',
+ name: 'Capacity monitor',
+ promptId: 'monitoring-agent-usage' as AiPromptId,
+ schedule: {
+ cadence: 'once each morning',
+ intervalMinutes: 1440,
+ scheduled: 'Run it once per day on a schedule.',
+ onDemand: 'Run it on demand after an unexpected traffic change.',
+ },
+ },
+} as const
+
+export type MonitoringAgentId = keyof typeof monitoringAgents
+export type MonitoringAgent = (typeof monitoringAgents)[MonitoringAgentId]
diff --git a/apps/docs/data/monitoring-agents.utils.test.ts b/apps/docs/data/monitoring-agents.utils.test.ts
new file mode 100644
index 00000000000..bf488d8e34d
--- /dev/null
+++ b/apps/docs/data/monitoring-agents.utils.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it } from 'vitest'
+
+import { monitoringAgents } from './monitoring-agents.data'
+import {
+ getCronExpression,
+ getMonitoringAgent,
+ getMonitoringAgentHarnesses,
+ getScheduleMarks,
+} from './monitoring-agents.utils'
+
+describe('getMonitoringAgent', () => {
+ it('returns a registered agent', () => {
+ expect(getMonitoringAgent('health').name).toBe('Health monitor')
+ })
+
+ it('fails clearly for an unknown id', () => {
+ expect(() => getMonitoringAgent('missing')).toThrow('Unknown monitoring agent id: missing')
+ })
+})
+
+describe('getScheduleMarks', () => {
+ it('renders a 24-hour day for 15-minute cadence', () => {
+ const { window, marks } = getScheduleMarks(15)
+ expect(window).toBe('day')
+ expect(marks).toHaveLength(96)
+ expect(marks.filter((mark) => mark.label).map((mark) => mark.label)).toEqual([
+ '12am',
+ '6am',
+ '12pm',
+ '6pm',
+ ])
+ })
+
+ it('renders a 24-hour day for hourly cadence', () => {
+ const { window, marks } = getScheduleMarks(60)
+ expect(window).toBe('day')
+ expect(marks).toHaveLength(24)
+ expect(marks[0].label).toBe('12am')
+ expect(marks[12].label).toBe('12pm')
+ })
+
+ it('renders a week for daily cadence', () => {
+ const { window, marks } = getScheduleMarks(1440)
+ expect(window).toBe('week')
+ expect(marks.map((mark) => mark.label)).toEqual([
+ 'Mon',
+ 'Tue',
+ 'Wed',
+ 'Thu',
+ 'Fri',
+ 'Sat',
+ 'Sun',
+ ])
+ })
+})
+
+describe('getCronExpression', () => {
+ it('maps supported intervals', () => {
+ expect(getCronExpression(15)).toBe('*/15 * * * *')
+ expect(getCronExpression(60)).toBe('0 * * * *')
+ expect(getCronExpression(1440)).toBe('0 9 * * *')
+ })
+})
+
+describe('getMonitoringAgentHarnesses', () => {
+ it('uses a Claude routine for hourly health checks', () => {
+ const claude = getMonitoringAgentHarnesses(monitoringAgents.health).find(
+ (harness) => harness.key === 'claude'
+ )
+
+ expect(claude?.intro).toContain('Create a Claude routine')
+ expect(claude?.note).toBeUndefined()
+ })
+
+ it('omits the Desktop-task note when the cadence is hourly or slower', () => {
+ const claude = getMonitoringAgentHarnesses(monitoringAgents.performance).find(
+ (harness) => harness.key === 'claude'
+ )
+
+ expect(claude?.intro).toContain('Create a Claude routine')
+ expect(claude?.note).toBeUndefined()
+ })
+})
diff --git a/apps/docs/data/monitoring-agents.utils.ts b/apps/docs/data/monitoring-agents.utils.ts
new file mode 100644
index 00000000000..5c084726600
--- /dev/null
+++ b/apps/docs/data/monitoring-agents.utils.ts
@@ -0,0 +1,139 @@
+import { aiPrompts } from './ai-prompts.data'
+import {
+ monitoringAgents,
+ type MonitoringAgent,
+ type MonitoringAgentId,
+} from './monitoring-agents.data'
+
+export type MonitoringAgentHarnessKey = 'claude' | 'codex' | 'cursor'
+
+export type ScheduleMark = {
+ key: string
+ label?: string
+}
+
+export type MonitoringAgentHarnessSetup = {
+ key: MonitoringAgentHarnessKey
+ label: string
+ icon: 'claude' | 'openai' | 'cursor'
+ hasDistinctDarkIcon?: boolean
+ docsUrl: string
+ intro: string
+ steps: string[]
+ note?: string
+}
+
+const WEEKDAY_LABELS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'] as const
+const DAY_LABELS = ['12am', '6am', '12pm', '6pm'] as const
+
+const MCP_STEP =
+ 'Connect the [Supabase MCP server](/docs/guides/ai-tools/mcp) with `project_ref` and `read_only=true`.'
+
+export function getMonitoringAgent(id: string): MonitoringAgent {
+ const agent = monitoringAgents[id as MonitoringAgentId]
+ if (!agent) {
+ throw new Error(`Unknown monitoring agent id: ${id}`)
+ }
+ return agent
+}
+
+export function getMonitoringAgentPrompt(agent: MonitoringAgent): string {
+ const prompt = aiPrompts[agent.promptId]
+ if (!prompt) {
+ throw new Error(`Unknown AiPrompt id: ${agent.promptId}`)
+ }
+ return prompt
+}
+
+export function getCronExpression(intervalMinutes: number): string {
+ if (intervalMinutes === 15) return '*/15 * * * *'
+ if (intervalMinutes === 60) return '0 * * * *'
+ if (intervalMinutes === 1440) return '0 9 * * *'
+ throw new Error(`Unsupported monitoring agent interval: ${intervalMinutes}`)
+}
+
+export function getScheduleMarks(intervalMinutes: number): {
+ window: 'day' | 'week'
+ marks: ScheduleMark[]
+} {
+ if (intervalMinutes >= 24 * 60) {
+ return {
+ window: 'week',
+ marks: WEEKDAY_LABELS.map((label) => ({ key: label, label })),
+ }
+ }
+
+ const marksPerDay = (24 * 60) / intervalMinutes
+ if (!Number.isInteger(marksPerDay)) {
+ throw new Error(`intervalMinutes must divide 1440 evenly. Received: ${intervalMinutes}`)
+ }
+
+ const labelEvery = marksPerDay / 4
+ const marks = Array.from({ length: marksPerDay }, (_, index) => ({
+ key: String(index),
+ label: index % labelEvery === 0 ? DAY_LABELS[index / labelEvery] : undefined,
+ }))
+
+ return { window: 'day', marks }
+}
+
+export function getScheduleLabel(agent: MonitoringAgent): string {
+ const cadence = agent.schedule.cadence
+ return cadence.charAt(0).toUpperCase() + cadence.slice(1)
+}
+
+export function getMonitoringAgentHarnesses(agent: MonitoringAgent): MonitoringAgentHarnessSetup[] {
+ const cron = getCronExpression(agent.schedule.intervalMinutes)
+ const cadence = agent.schedule.cadence
+ const isSubHourly = agent.schedule.intervalMinutes < 60
+
+ return [
+ {
+ key: 'claude',
+ label: 'Claude',
+ icon: 'claude',
+ docsUrl: isSubHourly
+ ? 'https://code.claude.com/docs/en/desktop-scheduled-tasks'
+ : 'https://code.claude.com/docs/en/routines',
+ intro: isSubHourly
+ ? `Create a Claude Desktop scheduled task that runs ${agent.name} ${cadence}.`
+ : `Create a Claude routine that runs ${agent.name} ${cadence}.`,
+ steps: [
+ MCP_STEP,
+ isSubHourly
+ ? 'In the Claude Code Desktop app, open **Routines**, click **New routine**, and choose **Local**.'
+ : 'Open [Claude routines](https://claude.ai/code/routines) or run `/schedule` in Claude Code.',
+ `Name it ${agent.name}. Paste the prompt. Set the schedule to ${cadence}.`,
+ ],
+ note: isSubHourly
+ ? 'Cloud routines have a 1-hour minimum. Use a [Desktop scheduled task](https://code.claude.com/docs/en/desktop-scheduled-tasks) for this cadence.'
+ : undefined,
+ },
+ {
+ key: 'codex',
+ label: 'Codex',
+ icon: 'openai',
+ hasDistinctDarkIcon: true,
+ docsUrl: 'https://developers.openai.com/codex/app/automations',
+ intro: `Create a Codex scheduled task that runs ${agent.name} ${cadence}.`,
+ steps: [
+ MCP_STEP,
+ 'Open **Scheduled** in the ChatGPT desktop app, or ask Codex to create a standalone scheduled task.',
+ `Name it ${agent.name}. Paste the prompt. Set the schedule to ${cadence}. Each run should start a new chat.`,
+ ],
+ },
+ {
+ key: 'cursor',
+ label: 'Cursor',
+ icon: 'cursor',
+ hasDistinctDarkIcon: true,
+ docsUrl: 'https://cursor.com/docs/cloud-agent/automations',
+ intro: `Create a Cursor automation that runs ${agent.name} ${cadence}.`,
+ steps: [
+ MCP_STEP,
+ 'Create an automation in the Agents Window, at [cursor.com/automations](https://cursor.com/automations), or with the `/automate` skill.',
+ `Name it ${agent.name}. Use a scheduled trigger (${cadence}, cron \`${cron}\`). Paste the prompt. Keep the agent read-only, with no repository.`,
+ ],
+ },
+ ]
+}
diff --git a/apps/docs/features/docs/MdxBase.shared.tsx b/apps/docs/features/docs/MdxBase.shared.tsx
index a7124288ec4..355c3f129ab 100644
--- a/apps/docs/features/docs/MdxBase.shared.tsx
+++ b/apps/docs/features/docs/MdxBase.shared.tsx
@@ -39,6 +39,8 @@ import { GlassPanel } from 'ui-patterns/GlassPanel'
import SqlToRest from 'ui-patterns/SqlToRest'
import { AgentPluginsPanel } from '../ui/AgentPluginsPanel'
+import { AgentSetup } from '../ui/AgentSetup'
+import { AgentWatchSchedule } from '../ui/AgentWatchSchedule'
import { AiPrompt } from '../ui/AiPrompt'
import { ErrorCodes } from '../ui/ErrorCodes'
import { McpConfigPanel } from '../ui/McpConfigPanel'
@@ -69,6 +71,8 @@ const components = {
AccordionItem,
Admonition: AdmonitionWithMargin,
AgentPluginsPanel,
+ AgentSetup,
+ AgentWatchSchedule,
AiPrompt,
AiPromptsIndex,
AiSkillsIndex,
diff --git a/apps/docs/features/ui/AgentSetup.tsx b/apps/docs/features/ui/AgentSetup.tsx
new file mode 100644
index 00000000000..5c7c30e68b7
--- /dev/null
+++ b/apps/docs/features/ui/AgentSetup.tsx
@@ -0,0 +1,111 @@
+'use client'
+
+import {
+ getMonitoringAgent,
+ getMonitoringAgentHarnesses,
+ type MonitoringAgentHarnessSetup,
+} from '~/data/monitoring-agents.utils'
+import { Sparkles } from 'lucide-react'
+import { useTheme } from 'next-themes'
+import { type ReactNode } from 'react'
+import ReactMarkdown from 'react-markdown'
+import { ConnectionIcon } from 'ui-patterns/McpUrlBuilder'
+
+import { AiPrompt } from './AiPrompt'
+import { TabPanel, Tabs } from './Tabs'
+
+type AgentSetupProps = {
+ id: string
+}
+
+const markdownComponents = {
+ p: ({ children }: { children?: ReactNode }) => <>{children}</>,
+ a: ({ href, children }: { href?: string; children?: ReactNode }) => {
+ if (!href) return <>{children}</>
+ const external = /^(?:[a-z][a-z0-9+\-.]*:|\/\/)/i.test(href)
+ return (
+ <a
+ href={href}
+ className="text-brand-link hover:underline"
+ {...(external ? { target: '_blank', rel: 'noreferrer noopener' } : {})}
+ >
+ {children}
+ </a>
+ )
+ },
+ code: ({ children }: { children?: ReactNode }) => (
+ <code className="rounded bg-surface-200 px-1 py-0.5 font-mono text-xs text-foreground">
+ {children}
+ </code>
+ ),
+}
+
+function HarnessBody({ harness }: { harness: MonitoringAgentHarnessSetup }) {
+ return (
+ <>
+ <p>{harness.intro}</p>
+ <ol>
+ {harness.steps.map((step) => (
+ <li key={step}>
+ <ReactMarkdown components={markdownComponents}>{step}</ReactMarkdown>
+ </li>
+ ))}
+ </ol>
+ {harness.note && (
+ <p>
+ <ReactMarkdown components={markdownComponents}>{harness.note}</ReactMarkdown>
+ </p>
+ )}
+ <p>
+ <a
+ href={harness.docsUrl}
+ className="text-brand-link hover:underline"
+ target="_blank"
+ rel="noreferrer noopener"
+ >
+ {harness.label} docs
+ </a>
+ </p>
+ </>
+ )
+}
+
+function AgentSetup({ id }: AgentSetupProps) {
+ const agent = getMonitoringAgent(id)
+ const harnesses = getMonitoringAgentHarnesses(agent)
+ const { resolvedTheme } = useTheme()
+ const theme = resolvedTheme?.includes('dark') ? 'dark' : 'light'
+
+ return (
+ <Tabs
+ defaultActiveId="prompt"
+ type="underlined"
+ size="small"
+ wrappable
+ queryGroup="agent-setup"
+ >
+ <TabPanel id="prompt" label="Prompt" icon={<Sparkles size={14} />}>
+ <AiPrompt id={agent.promptId} />
+ </TabPanel>
+ {harnesses.map((harness) => (
+ <TabPanel
+ key={harness.key}
+ id={harness.key}
+ label={harness.label}
+ icon={
+ <ConnectionIcon
+ theme={theme}
+ connection={harness.icon}
+ hasDistinctDarkIcon={harness.hasDistinctDarkIcon}
+ />
+ }
+ >
+ <HarnessBody harness={harness} />
+ </TabPanel>
+ ))}
+ </Tabs>
+ )
+}
+
+export { AgentSetup }
+export type { AgentSetupProps }
diff --git a/apps/docs/features/ui/AgentWatchSchedule.tsx b/apps/docs/features/ui/AgentWatchSchedule.tsx
new file mode 100644
index 00000000000..bed8bd0b8fd
--- /dev/null
+++ b/apps/docs/features/ui/AgentWatchSchedule.tsx
@@ -0,0 +1,89 @@
+import {
+ getMonitoringAgent,
+ getScheduleLabel,
+ getScheduleMarks,
+} from '~/data/monitoring-agents.utils'
+
+type AgentWatchScheduleProps = {
+ id: string
+}
+
+function DaySchedule({
+ marks,
+ cadence,
+}: {
+ marks: ReturnType<typeof getScheduleMarks>['marks']
+ cadence: string
+}) {
+ const labeled = marks.filter((mark) => mark.label)
+
+ return (
+ <div className="space-y-2" role="img" aria-label={`Scheduled ${cadence} across a 24-hour day`}>
+ <div className="relative h-4">
+ {labeled.map((mark) => {
+ const index = marks.findIndex((item) => item.key === mark.key)
+ return (
+ <span
+ key={mark.key}
+ className="absolute text-xs text-foreground-muted"
+ style={{ left: `${(index / marks.length) * 100}%` }}
+ >
+ {mark.label}
+ </span>
+ )
+ })}
+ </div>
+ <div className="flex h-8 gap-px">
+ {marks.map((mark) => (
+ <span key={mark.key} className="h-full min-w-0 flex-1 rounded-[2px] bg-brand/80" />
+ ))}
+ </div>
+ </div>
+ )
+}
+
+function WeekSchedule({
+ marks,
+ cadence,
+}: {
+ marks: ReturnType<typeof getScheduleMarks>['marks']
+ cadence: string
+}) {
+ return (
+ <div
+ className="grid grid-cols-7 gap-2"
+ role="img"
+ aria-label={`Scheduled ${cadence} across a week`}
+ >
+ {marks.map((mark) => (
+ <div key={mark.key} className="flex flex-col items-center gap-2">
+ <div className="flex h-16 w-full flex-col rounded-md bg-surface-200 p-1">
+ <span className="h-3 w-full rounded-[2px] bg-brand/80" />
+ </div>
+ <span className="text-xs text-foreground-muted">{mark.label}</span>
+ </div>
+ ))}
+ </div>
+ )
+}
+
+function AgentWatchSchedule({ id }: AgentWatchScheduleProps) {
+ const agent = getMonitoringAgent(id)
+ const { window, marks } = getScheduleMarks(agent.schedule.intervalMinutes)
+ const title = getScheduleLabel(agent)
+
+ return (
+ <div className="not-prose my-6 rounded-lg border bg-surface-75 p-4">
+ <p className="mb-4 text-sm text-foreground">{title}</p>
+ {window === 'week' ? (
+ <WeekSchedule marks={marks} cadence={agent.schedule.cadence} />
+ ) : (
+ <DaySchedule marks={marks} cadence={agent.schedule.cadence} />
+ )}
+ <p className="mt-4 text-sm text-foreground-light">{agent.schedule.onDemand}</p>
+ </div>
+ )
+}
+
+export { AgentWatchSchedule }
+export type { AgentWatchScheduleProps }
diff --git a/apps/docs/features/ui/AiPrompt.tsx b/apps/docs/features/ui/AiPrompt.tsx
index 0abe0bac1cd..2162b500a89 100644
--- a/apps/docs/features/ui/AiPrompt.tsx
+++ b/apps/docs/features/ui/AiPrompt.tsx
@@ -8,6 +8,8 @@ import { Prompt, PromptContent, PromptCopy, PromptPanel, PromptTitle } from './P
type AiPromptProps = {
/** Looks up prompt text from `aiPrompts`. */
id: AiPromptId | string
+ /** Includes the prompt body in generated guide Markdown. */
+ includeInMarkdown?: boolean
}
/**
@@ -16,8 +18,8 @@ type AiPromptProps = {
* boundary (where child types arrive as `react.lazy` and the panel
* would otherwise render nothing).
*
- * Prompt text lives in `~/data/ai-prompts.data`. Markdown export
- * intentionally omits this component (HTML-only copy panel).
+ * Prompt text lives in `~/data/ai-prompts.data`. Markdown export is opt-in so
+ * existing quickstarts do not duplicate their instructions in bulk exports.
*/
function AiPrompt({ id }: AiPromptProps) {
const prompt = aiPrompts[id as AiPromptId]
diff --git a/apps/docs/features/ui/Tabs.tsx b/apps/docs/features/ui/Tabs.tsx
index 2c01f57be29..66344d117ec 100644
--- a/apps/docs/features/ui/Tabs.tsx
+++ b/apps/docs/features/ui/Tabs.tsx
@@ -55,7 +55,7 @@ export const tabsListVariants = cva(cn('flex'), {
export const tabsTriggerListVariants = cva(
cn(
- 'relative cursor-pointer flex items-center space-x-2 text-center transition-colors focus-ring'
+ 'relative cursor-pointer flex items-center space-x-2 text-center transition-colors focus-ring [&_img]:m-0 [&_img]:size-3.5 [&_svg]:size-3.5'
),
{
variants: {
@@ -218,7 +218,7 @@ export const Tabs = ({
type,
scrollable,
wrappable,
- className: cn({ 'bg-background': stickyTabList != null }, listClassNames),
+ className: cn('not-prose', { 'bg-background': stickyTabList != null }, listClassNames),
})}
ref={stickyRef}
>
diff --git a/apps/docs/internals/generate-guides-markdown.ts b/apps/docs/internals/generate-guides-markdown.ts
index c7d94bce7f0..788bb55c6c7 100644
--- a/apps/docs/internals/generate-guides-markdown.ts
+++ b/apps/docs/internals/generate-guides-markdown.ts
@@ -16,6 +16,9 @@ import { mcpConfigPanelMarkdown as McpConfigPanel } from 'ui-patterns/McpUrlBuil
import { addBaseUrlPrefix, getInternalLinkBaseUrl, withDocsBasePath } from './internal-links'
import { AccordionItem } from './markdown-schema/Accordion'
import { Admonition } from './markdown-schema/Admonition'
+import { AgentSetup } from './markdown-schema/AgentSetup'
+import { AgentWatchSchedule } from './markdown-schema/AgentWatchSchedule'
+import { AiPrompt } from './markdown-schema/AiPrompt'
import { AiSkillsIndex } from './markdown-schema/AiSkillsIndex'
import { AuthProviders } from './markdown-schema/AuthProviders'
import { ComputeDiskLimitsTable } from './markdown-schema/ComputeDiskLimitsTable'
@@ -184,6 +187,9 @@ function applySchema(parent: Parent, schema: ComponentSchema): void {
const SCHEMA: ComponentSchema = {
AccordionItem,
Admonition,
+ AgentSetup,
+ AgentWatchSchedule,
+ AiPrompt,
AiSkillsIndex,
IconCheck,
IconX,
diff --git a/apps/docs/internals/markdown-schema/AgentSetup.test.ts b/apps/docs/internals/markdown-schema/AgentSetup.test.ts
new file mode 100644
index 00000000000..23899b887ea
--- /dev/null
+++ b/apps/docs/internals/markdown-schema/AgentSetup.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+
+import { AgentSetup } from './AgentSetup'
+
+describe('AgentSetup markdown schema', () => {
+ it('serializes the prompt and harness setup for a registered agent', () => {
+ const markdown = AgentSetup({ props: { id: 'health' } })
+
+ expect(markdown).toContain('**Prompt**')
+ expect(markdown).toContain('You are "Health monitor"')
+ expect(markdown).toContain('```text')
+ expect(markdown).toContain('**Claude**')
+ expect(markdown).toContain('**Codex**')
+ expect(markdown).toContain('**Cursor**')
+ expect(markdown).toContain('claude.ai/code/routines')
+ expect(markdown).toContain('`0 * * * *`')
+ expect(markdown).toContain('[Claude docs](https://code.claude.com/docs/en/routines)')
+ expect(markdown).toContain('[Codex docs](https://developers.openai.com/codex/app/automations)')
+ expect(markdown).toContain('[Cursor docs](https://cursor.com/docs/cloud-agent/automations)')
+ })
+
+ it('points hourly agents at Claude cloud routines', () => {
+ const markdown = AgentSetup({ props: { id: 'performance' } })
+
+ expect(markdown).toContain('claude.ai/code/routines')
+ expect(markdown).not.toContain('Desktop scheduled task')
+ })
+
+ it('fails clearly for an unknown agent', () => {
+ expect(() => AgentSetup({ props: { id: 'missing' } })).toThrow(
+ 'Unknown monitoring agent id: missing'
+ )
+ })
+})
diff --git a/apps/docs/internals/markdown-schema/AgentSetup.ts b/apps/docs/internals/markdown-schema/AgentSetup.ts
new file mode 100644
index 00000000000..8b6d5568e47
--- /dev/null
+++ b/apps/docs/internals/markdown-schema/AgentSetup.ts
@@ -0,0 +1,31 @@
+import {
+ getMonitoringAgent,
+ getMonitoringAgentHarnesses,
+ getMonitoringAgentPrompt,
+} from '~/data/monitoring-agents.utils'
+
+type HandlerContext = {
+ props: Record<string, unknown>
+}
+
+function renderMarkdownSteps(steps: string[]): string {
+ return steps.map((step, index) => `${index + 1}. ${step}`).join('\n')
+}
+
+export function AgentSetup({ props }: HandlerContext): string {
+ const agent = getMonitoringAgent(String(props.id ?? ''))
+ const prompt = getMonitoringAgentPrompt(agent)
+ const harnesses = getMonitoringAgentHarnesses(agent)
+
+ const sections = [
+ `**Prompt**\n\n\`\`\`text\n${prompt}\n\`\`\``,
+ ...harnesses.map((harness) => {
+ const parts = [`**${harness.label}**`, harness.intro, renderMarkdownSteps(harness.steps)]
+ if (harness.note) parts.push(harness.note)
+ parts.push(`[${harness.label} docs](${harness.docsUrl})`)
+ return parts.join('\n\n')
+ }),
+ ]
+
+ return sections.join('\n\n')
+}
diff --git a/apps/docs/internals/markdown-schema/AgentWatchSchedule.test.ts b/apps/docs/internals/markdown-schema/AgentWatchSchedule.test.ts
new file mode 100644
index 00000000000..5f974c56eee
--- /dev/null
+++ b/apps/docs/internals/markdown-schema/AgentWatchSchedule.test.ts
@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+
+import { AgentWatchSchedule } from './AgentWatchSchedule'
+
+describe('AgentWatchSchedule markdown schema', () => {
+ it('serializes the scheduled and on-demand copy', () => {
+ const markdown = AgentWatchSchedule({ props: { id: 'health' } })
+
+ expect(markdown).toContain('Run it once per hour on a schedule.')
+ expect(markdown).toContain('Run it on demand after a deployment')
+ })
+
+ it('fails clearly for an unknown agent', () => {
+ expect(() => AgentWatchSchedule({ props: { id: 'missing' } })).toThrow(
+ 'Unknown monitoring agent id: missing'
+ )
+ })
+})
diff --git a/apps/docs/internals/markdown-schema/AgentWatchSchedule.ts b/apps/docs/internals/markdown-schema/AgentWatchSchedule.ts
new file mode 100644
index 00000000000..a5c33b3ffd8
--- /dev/null
+++ b/apps/docs/internals/markdown-schema/AgentWatchSchedule.ts
@@ -0,0 +1,10 @@
+import { getMonitoringAgent } from '~/data/monitoring-agents.utils'
+
+type HandlerContext = {
+ props: Record<string, unknown>
+}
+
+export function AgentWatchSchedule({ props }: HandlerContext): string {
+ const agent = getMonitoringAgent(String(props.id ?? ''))
+ return `${agent.schedule.scheduled}\n\n${agent.schedule.onDemand}`
+}
diff --git a/apps/docs/internals/markdown-schema/AiPrompt.test.ts b/apps/docs/internals/markdown-schema/AiPrompt.test.ts
new file mode 100644
index 00000000000..4b6920d94d1
--- /dev/null
+++ b/apps/docs/internals/markdown-schema/AiPrompt.test.ts
@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest'
+
+import { AiPrompt } from './AiPrompt'
+
+describe('AiPrompt markdown schema', () => {
+ it('omits prompts by default', () => {
+ expect(AiPrompt({ props: { id: 'nextjs' } })).toBe('')
+ })
+
+ it('serializes an opted-in prompt from the shared registry', () => {
+ const markdown = AiPrompt({
+ props: { id: 'nextjs', includeInMarkdown: true },
+ })
+
+ expect(markdown).toContain('**AI Prompt**')
+ expect(markdown).toContain('Help me add Supabase to my Next.js project.')
+ expect(markdown).toContain('```text')
+ })
+
+ it.each([
+ ['monitoring-agent-health', 'Health monitor'],
+ ['monitoring-agent-security', 'Security monitor'],
+ ['monitoring-agent-performance', 'Performance monitor'],
+ ['monitoring-agent-usage', 'Capacity monitor'],
+ ])('serializes the %s agent prompt', (id, persona) => {
+ const markdown = AiPrompt({ props: { id, includeInMarkdown: true } })
+
+ expect(markdown).toContain('**AI Prompt**')
+ expect(markdown).toContain(persona)
+ expect(markdown).toContain('read-only')
+ expect(markdown).toContain('```text')
+ })
+
+ it('fails clearly for an unknown opted-in prompt', () => {
+ expect(() => AiPrompt({ props: { id: 'missing-prompt', includeInMarkdown: true } })).toThrow(
+ 'Unknown AiPrompt id: missing-prompt'
+ )
+ })
+})
diff --git a/apps/docs/internals/markdown-schema/AiPrompt.ts b/apps/docs/internals/markdown-schema/AiPrompt.ts
new file mode 100644
index 00000000000..6a1ed36cfdb
--- /dev/null
+++ b/apps/docs/internals/markdown-schema/AiPrompt.ts
@@ -0,0 +1,20 @@
+import { aiPrompts, type AiPromptId } from '~/data/ai-prompts.data'
+
+type HandlerContext = {
+ props: Record<string, unknown>
+}
+
+export function AiPrompt({ props }: HandlerContext): string {
+ const includeInMarkdown = props.includeInMarkdown === true || props.includeInMarkdown === 'true'
+
+ if (!includeInMarkdown) return ''
+
+ const id = String(props.id ?? '')
+ const prompt = aiPrompts[id as AiPromptId]
+
+ if (!prompt) {
+ throw new Error(`Unknown AiPrompt id: ${id}`)
+ }
+
+ return `**AI Prompt**\n\n\`\`\`text\n${prompt}\n\`\`\``
+}
diff --git a/apps/docs/internals/markdown-schema/ContentListings.ts b/apps/docs/internals/markdown-schema/ContentListings.ts
index ce78463b70a..6817ce1f919 100644
--- a/apps/docs/internals/markdown-schema/ContentListings.ts
+++ b/apps/docs/internals/markdown-schema/ContentListings.ts
@@ -37,7 +37,8 @@ export function serializeContentListingGroupToMarkdown(
const href = isExternalContentListingHref(item.href)
? item.href
: `${linkBaseUrl}${withDocsBasePath(item.href)}`
- lines.push(`- **[${item.title}](${href}):** ${item.description}`)
+ const description = item.subtitle ? `${item.subtitle}. ${item.description}` : item.description
+ lines.push(`- **[${item.title}](${href}):** ${description}`)
}
return lines.join('\n')
diff --git a/apps/docs/lib/content-listings.test.ts b/apps/docs/lib/content-listings.test.ts
index 87b0d5d82fe..dd2788a5989 100644
--- a/apps/docs/lib/content-listings.test.ts
+++ b/apps/docs/lib/content-listings.test.ts
@@ -62,6 +62,27 @@ describe('serializeContentListingGroupToMarkdown', () => {
)
})
+ it('includes a subtitle before the description', () => {
+ const markdown = serializeContentListingGroupToMarkdown(
+ {
+ id: 'hire-agent',
+ items: [
+ {
+ title: 'Doctor',
+ href: '/guides/monitoring-and-debugging/automate-with-agents/health',
+ subtitle: 'Every 15 minutes',
+ description: 'Watch logs for 5xx spikes and Auth failures.',
+ },
+ ],
+ },
+ 'https://supabase.com'
+ )
+
+ expect(markdown).toContain(
+ '**[Doctor](https://supabase.com/docs/guides/monitoring-and-debugging/automate-with-agents/health):** Every 15 minutes. Watch logs for 5xx spikes and Auth failures.'
+ )
+ })
+
it('preserves external hrefs in markdown export', () => {
const markdown = serializeContentListingGroupToMarkdown(
{
@@ -261,6 +282,14 @@ describe('contentListingItemSchema icon', () => {
description: 'Stream logs directly into Datadog for monitoring and analysis.',
}
+ it('accepts an optional subtitle', () => {
+ const result = contentListingItemSchema.safeParse({
+ ...baseItem,
+ subtitle: 'Every 15 minutes',
+ })
+ expect(result.success).toBe(true)
+ })
+
it('accepts a plain string icon path', () => {
const result = contentListingItemSchema.safeParse({
...baseItem,
diff --git a/apps/docs/lib/content-listings.zod.mjs b/apps/docs/lib/content-listings.zod.mjs
index a678cb6b578..decf8220a03 100644
--- a/apps/docs/lib/content-listings.zod.mjs
+++ b/apps/docs/lib/content-listings.zod.mjs
@@ -24,6 +24,8 @@ export const contentListingItemSchema = z.object({
title: z.string().min(1),
href: z.string().min(1),
description: z.string().min(1),
+ /** Shown under the title on grid cards, before the description. */
+ subtitle: z.string().min(1).optional(),
icon: contentListingIconSchema.optional(),
hasLightIcon: z.boolean().optional(),
badge: z.string().min(1).optional(),