diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts index 6cb155ab043..e18d9eac41f 100644 --- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts +++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts @@ -3093,16 +3093,16 @@ export const telemetry: NavMenuConstant = { ], }, { - name: 'Hire an agent', + name: 'Agent prompts', items: [ - { name: 'Set up an agent', url: '/guides/observability/automate-with-agents' }, - { name: 'Health monitor', url: '/guides/observability/automate-with-agents/health' }, - { name: 'Security monitor', url: '/guides/observability/automate-with-agents/security' }, + { name: 'Overview', url: '/guides/observability/automate-with-agents' }, + { name: 'Health', url: '/guides/observability/automate-with-agents/health' }, + { name: 'Security', url: '/guides/observability/automate-with-agents/security' }, { - name: 'Performance monitor', + name: 'Performance', url: '/guides/observability/automate-with-agents/performance', }, - { name: 'Resource monitor', url: '/guides/observability/automate-with-agents/usage' }, + { name: 'Resources', url: '/guides/observability/automate-with-agents/usage' }, ], }, { diff --git a/apps/docs/content/guides/observability.mdx b/apps/docs/content/guides/observability.mdx index 31c7817a010..5ddf6197d23 100644 --- a/apps/docs/content/guides/observability.mdx +++ b/apps/docs/content/guides/observability.mdx @@ -1,6 +1,6 @@ --- title: Observability -description: 'Read project data, diagnose issues, and hire an agent to monitor your project' +description: 'Read project data, diagnose issues, and run agent prompts to check your project' --- Use project data to understand what is happening, investigate issues, and give an agent repeatable checks to run. @@ -15,9 +15,9 @@ Query logs for events, inspect database statistics, or review advisor findings. Run [detection checks](/docs/guides/observability/detecting) to identify health, security, performance, or capacity issues. Take the resulting error code, time window, or affected object to the [troubleshooting guides](/docs/guides/troubleshooting), then rerun the check after a fix. -## Hire an agent +## Agent prompts -Give an agent recurring checks to run and findings to report. [Set up an agent](/docs/guides/observability/automate-with-agents) with read-only access to your project. +Give an agent a prompt to check your project and report issues to fix. [See the prompts](/docs/guides/observability/automate-with-agents) and run them with read-only access to your project. diff --git a/apps/docs/content/guides/observability/automate-with-agents.mdx b/apps/docs/content/guides/observability/automate-with-agents.mdx index 839a03f71f7..68f9f53e0dc 100644 --- a/apps/docs/content/guides/observability/automate-with-agents.mdx +++ b/apps/docs/content/guides/observability/automate-with-agents.mdx @@ -1,33 +1,33 @@ --- id: 'automate-with-agents' -title: 'Hire an agent' -subtitle: 'Run a read-only monitoring routine in your own agent harness.' -description: 'Choose and set up a Health, Security, Performance, or Resource monitor in Claude, Codex, or Cursor.' +title: 'Agent prompts' +subtitle: 'Give an agent a prompt to check your project and report issues to fix.' +description: 'Run a Health, Security, Performance, or Resource prompt in Claude, Codex, or Cursor.' --- -This guide explains how to run a Supabase monitoring agent in your own harness. Each agent is a prompt plus a schedule. It reads project data and reports findings. It does not change the project. +Each prompt tells an agent to check one area of your project — health, security, performance, or resources — and report issues worth fixing. It reads project data read-only and changes nothing. Run it on demand, or put it on a schedule. -## Choose a routine +## Choose a prompt -Start with one monitor. Add another only when the project needs a different source or cadence. +Start with one prompt. Add another only when you need a different source or cadence. -| Monitor | What it watches | Default cadence | Use it when | -| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | --------------- | -------------------------------------------------------------- | -| [Health monitor](/docs/guides/observability/automate-with-agents/health) | API and Auth server errors, error-rate spikes, connection pressure | Hourly | You need incident detection and regular feedback loops | -| [Security monitor](/docs/guides/observability/automate-with-agents/security) | Security Advisor findings, authentication and authorization failures | Daily | You need a regular access-control and configuration review | -| [Performance monitor](/docs/guides/observability/automate-with-agents/performance) | Slow queries, lock waits, long-running sessions, Performance Advisor findings | Hourly | You need query and database performance checks | -| [Resource monitor](/docs/guides/observability/automate-with-agents/usage) | Request, error, storage, table, and connection growth | Daily | You need to identify growth before it reaches a resource limit | +| Prompt | What it checks | Suggested cadence | Use it when | +| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------- | +| [Health](/docs/guides/observability/automate-with-agents/health) | API and Auth server errors, error-rate spikes, connection pressure | Hourly | You need incident detection and regular feedback loops | +| [Security](/docs/guides/observability/automate-with-agents/security) | Security Advisor findings, authentication and authorization failures | Daily | You need a regular access-control and configuration review | +| [Performance](/docs/guides/observability/automate-with-agents/performance) | Slow queries, lock waits, long-running sessions, Performance Advisor findings | Hourly | You need query and database performance checks | +| [Resources](/docs/guides/observability/automate-with-agents/usage) | Request, error, storage, table, and connection growth | Daily | You need to identify growth before it reaches a resource limit | -For a small project, run the most relevant routine daily or weekly and include the other categories in its prompt. Split it into specialized monitors only when you need different owners, schedules, or alert thresholds. +For a small project, run the most relevant prompt daily or weekly and fold the other categories into it. Split into separate prompts only when you need different owners, schedules, or alert thresholds. -## Run the routine +## Run a prompt 1. Connect the [Supabase MCP server](/docs/guides/ai-tools/mcp) with `project_ref` and `read_only=true`. -2. Open the monitor that matches the job from the table above. +2. Open the prompt that matches the job from the table above. 3. Set it up in Claude, Codex, Cursor, or copy the prompt into another harness. 4. Run it on demand first. Then put the same prompt on a schedule. -Each agent page describes what it will output. Send those findings through the connections your harness already has, such as Linear in Codex. +Each prompt page describes what it will output. Send those findings through the connections your harness already has, such as Linear in Codex. Scheduled tasks start a fresh context on every run, so the prompt is self-contained. Review the first runs before you rely on the schedule. diff --git a/apps/docs/content/guides/observability/automate-with-agents/health.mdx b/apps/docs/content/guides/observability/automate-with-agents/health.mdx index 98f5d081764..58b0e0e44c9 100644 --- a/apps/docs/content/guides/observability/automate-with-agents/health.mdx +++ b/apps/docs/content/guides/observability/automate-with-agents/health.mdx @@ -1,8 +1,8 @@ --- id: 'automate-with-agents-health' -title: 'Health monitor' +title: 'Health' subtitle: 'A read-only agent that checks API and Auth errors and Postgres connection pressure once per hour.' -description: 'Hourly monitoring for server errors and connection pressure' +description: 'Hourly checks for server errors and connection pressure' --- ```mermaid @@ -28,7 +28,7 @@ It uses `query_logs` and read-only `execute_sql` on project-scoped [Supabase MCP ## What it will output -Health monitor reports new or changed problems with the affected service, measured error rate or connection usage, and a next investigation step. See [what triggers a health report](/docs/guides/observability/detecting#health). +This prompt reports new or changed problems with the affected service, measured error rate or connection usage, and a next investigation step. See [what triggers a health report](/docs/guides/observability/detecting#health). If a check cannot run, the agent tells you what is missing. Clear checks and unchanged findings stay quiet. diff --git a/apps/docs/content/guides/observability/automate-with-agents/performance.mdx b/apps/docs/content/guides/observability/automate-with-agents/performance.mdx index 942ffa9ab8d..3edd61981bc 100644 --- a/apps/docs/content/guides/observability/automate-with-agents/performance.mdx +++ b/apps/docs/content/guides/observability/automate-with-agents/performance.mdx @@ -1,8 +1,8 @@ --- id: 'automate-with-agents-performance' -title: 'Performance monitor' +title: 'Performance' subtitle: 'A read-only agent that inspects query performance, blocking sessions, and Performance Advisor findings once per hour.' -description: 'Hourly monitoring for query regressions, blocking sessions, and performance findings' +description: 'Hourly checks for query regressions, blocking sessions, and performance findings' --- ```mermaid @@ -29,7 +29,7 @@ It uses `get_advisors` and read-only `execute_sql` on project-scoped [Supabase M ## What it will output -Performance monitor reports new or changed findings with the affected query, session, or object, plus an investigation and verification step. It does not infer a regression without comparable measurements or recommend cancellation based only on query age. See [what triggers a performance report](/docs/guides/observability/detecting#performance). +This prompt reports new or changed findings with the affected query, session, or object, plus an investigation and verification step. It does not infer a regression without comparable measurements or recommend cancellation based only on query age. See [what triggers a performance report](/docs/guides/observability/detecting#performance). If a check cannot run, the agent tells you what is missing. Clear checks and unchanged findings stay quiet. diff --git a/apps/docs/content/guides/observability/automate-with-agents/security.mdx b/apps/docs/content/guides/observability/automate-with-agents/security.mdx index 243ab8ac540..d0885192507 100644 --- a/apps/docs/content/guides/observability/automate-with-agents/security.mdx +++ b/apps/docs/content/guides/observability/automate-with-agents/security.mdx @@ -1,6 +1,6 @@ --- id: 'automate-with-agents-security' -title: 'Security monitor' +title: 'Security' subtitle: 'A read-only agent that reviews Security Advisor findings and authentication and authorization failures each day.' description: 'Daily review of security findings and access failures' --- @@ -29,7 +29,7 @@ It uses `get_advisors` and `query_logs` on project-scoped, read-only [Supabase M ## What it will output -Security monitor reports new or changed advisor findings and access-failure spikes, with the affected object or service and a next investigation step. A spike is a review signal, not proof of an attack. See [what triggers a security report](/docs/guides/observability/detecting#security). +This prompt reports new or changed advisor findings and access-failure spikes, with the affected object or service and a next investigation step. A spike is a review signal, not proof of an attack. See [what triggers a security report](/docs/guides/observability/detecting#security). If a check cannot run, the agent tells you what is missing. Clear checks and unchanged findings stay quiet. diff --git a/apps/docs/content/guides/observability/automate-with-agents/usage.mdx b/apps/docs/content/guides/observability/automate-with-agents/usage.mdx index 2fa7c18387d..4be7eb548ad 100644 --- a/apps/docs/content/guides/observability/automate-with-agents/usage.mdx +++ b/apps/docs/content/guides/observability/automate-with-agents/usage.mdx @@ -1,8 +1,8 @@ --- id: 'automate-with-agents-usage' -title: 'Resource monitor' +title: 'Resources' subtitle: 'A read-only agent that tracks resource and request growth and estimates when a confirmed limit could be reached.' -description: 'Daily monitoring for resource growth and approaching limits' +description: 'Daily checks for resource growth and approaching limits' --- ```mermaid @@ -30,7 +30,7 @@ It uses read-only `execute_sql` and `query_logs` on project-scoped [Supabase MCP ## What it will output -Resource monitor reports new or changed request-growth signals and resource-limit risks. When saved measurements support a forecast within 14 days, it includes the estimated date, calculation, and scaling guide. If history or a matching limit is missing, it explains what it needs instead of inventing a date. See [what triggers a resource report](/docs/guides/observability/detecting#usage). +This prompt reports new or changed request-growth signals and resource-limit risks. When saved measurements support a forecast within 14 days, it includes the estimated date, calculation, and scaling guide. If history or a matching limit is missing, it explains what it needs instead of inventing a date. See [what triggers a resource report](/docs/guides/observability/detecting#usage). If a check cannot run, the agent tells you what is missing. Clear checks and unchanged findings stay quiet. diff --git a/apps/docs/content/guides/observability/detecting.mdx b/apps/docs/content/guides/observability/detecting.mdx index 60b3d1b9807..c1eff9aa597 100644 --- a/apps/docs/content/guides/observability/detecting.mdx +++ b/apps/docs/content/guides/observability/detecting.mdx @@ -4,7 +4,7 @@ title: 'Detection checks' description: 'Repeatable health, security, performance, and capacity checks with explicit inputs and outcomes' --- -Use these checks to identify evidence worth investigating. A finding does not establish a cause. The specialist [monitoring agents](/docs/guides/observability/automate-with-agents) use these same checks. +Use these checks to identify evidence worth investigating. A finding does not establish a cause. The [agent prompts](/docs/guides/observability/automate-with-agents) use these same checks. ## Before running checks diff --git a/apps/docs/data/monitoring-agents.data.ts b/apps/docs/data/monitoring-agents.data.ts index 5655d134e5c..e3516f3efeb 100644 --- a/apps/docs/data/monitoring-agents.data.ts +++ b/apps/docs/data/monitoring-agents.data.ts @@ -3,7 +3,7 @@ import type { AiPromptId } from './ai-prompts.data' export const monitoringAgents = { health: { id: 'health', - name: 'Health monitor', + name: 'Health', promptId: 'monitoring-agent-health' as AiPromptId, schedule: { cadence: 'once per hour', @@ -15,7 +15,7 @@ export const monitoringAgents = { }, security: { id: 'security', - name: 'Security monitor', + name: 'Security', promptId: 'monitoring-agent-security' as AiPromptId, schedule: { cadence: 'once per day', @@ -26,7 +26,7 @@ export const monitoringAgents = { }, performance: { id: 'performance', - name: 'Performance monitor', + name: 'Performance', promptId: 'monitoring-agent-performance' as AiPromptId, schedule: { cadence: 'once per hour', @@ -37,7 +37,7 @@ export const monitoringAgents = { }, usage: { id: 'usage', - name: 'Resource monitor', + name: 'Resources', promptId: 'monitoring-agent-usage' as AiPromptId, schedule: { cadence: 'once each morning', diff --git a/apps/docs/data/monitoring-agents.utils.test.ts b/apps/docs/data/monitoring-agents.utils.test.ts index bf488d8e34d..502a9b58383 100644 --- a/apps/docs/data/monitoring-agents.utils.test.ts +++ b/apps/docs/data/monitoring-agents.utils.test.ts @@ -10,7 +10,7 @@ import { describe('getMonitoringAgent', () => { it('returns a registered agent', () => { - expect(getMonitoringAgent('health').name).toBe('Health monitor') + expect(getMonitoringAgent('health').name).toBe('Health') }) it('fails clearly for an unknown id', () => { diff --git a/apps/docs/data/monitoring-agents.utils.ts b/apps/docs/data/monitoring-agents.utils.ts index b6c975bf19a..15ae433deaa 100644 --- a/apps/docs/data/monitoring-agents.utils.ts +++ b/apps/docs/data/monitoring-agents.utils.ts @@ -98,14 +98,14 @@ export function getMonitoringAgentHarnesses(agent: MonitoringAgent): MonitoringA ? '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}.`, + ? `Create a Claude Desktop scheduled task that runs the ${agent.name} prompt ${cadence}.` + : `Create a Claude routine that runs the ${agent.name} prompt ${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](#${AGENT_PROMPT_ANCHOR}). Set the schedule to ${cadence}.`, + `Name it ${agent.name} checks. Paste the [prompt](#${AGENT_PROMPT_ANCHOR}). 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.' @@ -117,11 +117,11 @@ export function getMonitoringAgentHarnesses(agent: MonitoringAgent): MonitoringA icon: 'openai', hasDistinctDarkIcon: true, docsUrl: 'https://developers.openai.com/codex/app/automations', - intro: `Create a Codex scheduled task that runs ${agent.name} ${cadence}.`, + intro: `Create a Codex scheduled task that runs the ${agent.name} prompt ${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](#${AGENT_PROMPT_ANCHOR}). Set the schedule to ${cadence}. Each run should start a new chat.`, + `Name it ${agent.name} checks. Paste the [prompt](#${AGENT_PROMPT_ANCHOR}). Set the schedule to ${cadence}. Each run should start a new chat.`, ], }, { @@ -130,11 +130,11 @@ export function getMonitoringAgentHarnesses(agent: MonitoringAgent): MonitoringA icon: 'cursor', hasDistinctDarkIcon: true, docsUrl: 'https://cursor.com/docs/cloud-agent/automations', - intro: `Create a Cursor automation that runs ${agent.name} ${cadence}.`, + intro: `Create a Cursor automation that runs the ${agent.name} prompt ${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](#${AGENT_PROMPT_ANCHOR}). Keep the agent read-only, with no repository.`, + `Name it ${agent.name} checks. Use a scheduled trigger (${cadence}, cron \`${cron}\`). Paste the [prompt](#${AGENT_PROMPT_ANCHOR}). Keep the agent read-only, with no repository.`, ], }, ]