The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
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.tsxindex 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.tsindex 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:REFERENCEhttps://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 constexport type AiPromptId = keyof typeof aiPromptsdiff --git a/apps/docs/data/monitoring-agents.data.ts b/apps/docs/data/monitoring-agents.data.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxindex 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 './Ptype 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.tsxindex 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.tsindex 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/McpUrlBuilimport { 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.mjsindex 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(),