From 90f59aebbc3bd2cdf84028c7694c443c5e901080 Mon Sep 17 00:00:00 2001 From: Prashant Sridharan <914007+CoolAssPuppy@users.noreply.github.com> Date: Wed, 2 Sep 2026 17:23:05 +0100 Subject: [PATCH 1/6] Add VIP dinner go pages back (#49915) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Feature ## What is the current behavior? The Select 2026 VIP Dinner RSVP pages were removed. VIP Experience remains live as one invite cohort for the same dinner. ## What is the new behavior? Restores `/go/select-2026/vip-dinner` and its thank-you page as a second invite cohort for the same Penny Roma dinner (October 1, 2026, 7:00 PM / 7:30 PM). RSVPs write to the VIP Dinner Notion database. VIP Experience is unchanged. ## Additional context Same event, two invite lists. Venue, time, and hosts match VIP Experience. ## Test plan - [ ] Open `/go/select-2026/vip-dinner` and confirm Penny Roma, October 1, 2026, and the RSVP form render - [ ] Submit a test RSVP and confirm a row lands in the VIP Dinner Notion database - [ ] Confirm `/go/select-2026/vip-experience` still works and writes to its own database Made with [Cursor](https://cursor.com) ## Summary by CodeRabbit - **New Features** - Added a Select 2026 VIP dinner event page with event details, venue information, host profiles, and seat reservation form. - Added RSVP submission and confirmation flow, including a dedicated thank-you page with confirmation details. - Added event pages to the website’s public page registry. Co-authored-by: Cursor --- .../select-2026/vip-dinner-thank-you.tsx | 34 +++ .../www/_go/events/select-2026/vip-dinner.tsx | 194 ++++++++++++++++++ apps/www/_go/index.tsx | 4 + 3 files changed, 232 insertions(+) create mode 100644 apps/www/_go/events/select-2026/vip-dinner-thank-you.tsx create mode 100644 apps/www/_go/events/select-2026/vip-dinner.tsx diff --git a/apps/www/_go/events/select-2026/vip-dinner-thank-you.tsx b/apps/www/_go/events/select-2026/vip-dinner-thank-you.tsx new file mode 100644 index 0000000000000..5413edb9444da --- /dev/null +++ b/apps/www/_go/events/select-2026/vip-dinner-thank-you.tsx @@ -0,0 +1,34 @@ +import type { GoPageInput } from 'marketing' +import Link from 'next/link' +import { Button } from 'ui' + +const page: GoPageInput = { + template: 'thank-you', + slug: 'select-2026/vip-dinner/thank-you', + metadata: { + title: "You're confirmed | Supabase VIP Dinner", + description: + 'Your RSVP for the Supabase VIP dinner at Penny Roma in San Francisco on October 1, 2026 has been confirmed. Cocktails begin at 7:00 PM and dinner starts at 7:30 PM.', + }, + hero: { + title: "You're confirmed", + description: + "We'll see you at Penny Roma in San Francisco on October 1, 2026. Cocktails begin at 7:00 PM and dinner starts at 7:30 PM. We look forward to seeing you.", + }, + sections: [ + { + type: 'single-column', + title: 'In the meantime', + description: 'Learn more about what we are building at Supabase.', + children: ( +
+ +
+ ), + }, + ], +} + +export default page diff --git a/apps/www/_go/events/select-2026/vip-dinner.tsx b/apps/www/_go/events/select-2026/vip-dinner.tsx new file mode 100644 index 0000000000000..f91f8836a1b03 --- /dev/null +++ b/apps/www/_go/events/select-2026/vip-dinner.tsx @@ -0,0 +1,194 @@ +import type { GoPageInput } from 'marketing' +import Image from 'next/image' +import { cn } from 'ui' + +import authors from '@/lib/authors.json' + +const sugu = authors.find((a) => a.author_id === 'sugu_sougoumarane') +const paul = authors.find((a) => a.author_id === 'paul_copplestone') +const ant = authors.find((a) => a.author_id === 'ant_wilson') +const deepthi = authors.find((a) => a.author_id === 'deepthi_sigireddi') + +const hosts = [paul, ant, sugu, deepthi] + +const page: GoPageInput = { + template: 'lead-gen', + slug: 'select-2026/vip-dinner', + metadata: { + title: 'VIP Dinner | Supabase Select 2026', + description: + 'Join Supabase leaders for an intimate VIP dinner at Penny Roma in San Francisco on October 1, 2026. Cocktails at 7:00 PM, dinner at 7:30 PM.', + }, + hero: { + title: 'The future of scalable databases', + subtitle: 'An intimate VIP dinner hosted by Supabase', + description: + 'Join Supabase product and engineering leaders for a dinner conversation about where Postgres is headed -- from scaling beyond single-node limits to managing globally distributed workloads. Expect sharp perspectives, good food, and the opportunity to connect with other engineering leaders.', + image: { + src: '/images/landing-pages/select-2026/pennyroma.jpg', + alt: 'Private dining room at Penny Roma, San Francisco', + width: 600, + height: 450, + }, + ctas: [ + { + label: 'Reserve your seat', + href: '#rsvp', + variant: 'primary', + }, + ], + }, + sections: [ + { + type: 'single-column', + title: 'Details', + children: ( +
+

Date

+

October 1, 2026

+

Location

+

Penny Roma

+

San Francisco, CA

+

Schedule

+

7:00 PM — Cocktails and introductions

+

7:30 PM — Dinner and discussion

+
+ ), + }, + { + type: 'single-column', + title: 'Your hosts', + children: ( +
+
+ {hosts.map((host, i) => ( +
+ {host?.author_image_url && ( + {host.author} + )} +
+

{host?.author}

+

+ {host?.position && `${host.position}, `}Supabase +

+
+
+ ))} +
+
+ ), + }, + { + type: 'form', + id: 'rsvp', + title: 'Reserve your seat', + description: "Space is limited. Let us know you're coming.", + fields: [ + { + type: 'text', + name: 'first_name', + label: 'First Name', + placeholder: 'First Name', + required: true, + half: true, + }, + { + type: 'text', + name: 'last_name', + label: 'Last Name', + placeholder: 'Last Name', + required: true, + half: true, + }, + { + type: 'email', + name: 'email_address', + label: 'Email', + placeholder: 'Work email', + required: true, + }, + { + type: 'text', + name: 'company_name', + label: 'Company', + placeholder: 'ACME, Inc.', + required: true, + }, + { + type: 'text', + name: 'job_title', + label: 'Job Title', + placeholder: 'VP of Engineering', + required: false, + }, + { + type: 'text', + name: 'phone_number', + label: 'Phone Number', + placeholder: '+1 212 555 1212', + required: false, + }, + { + type: 'select', + name: 'attending', + label: 'Are you attending Select 2026?', + placeholder: 'Select an option', + required: true, + options: [ + { label: 'Yes', value: 'Yes' }, + { label: 'No', value: 'No' }, + ], + }, + ], + submitLabel: 'Confirm RSVP', + successRedirect: '/go/select-2026/vip-dinner/thank-you', + disclaimer: + 'By submitting this form, I confirm that I have read and understood the [Privacy Policy](https://supabase.com/privacy).', + crm: { + hubspot: { + formGuid: 'd0699f2e-225a-4224-91b5-341fb5336613', + fieldMap: { + first_name: 'firstname', + last_name: 'lastname', + email_address: 'email', + company_name: 'company', + job_title: 'jobtitle', + phone_number: 'phone', + }, + // `attending` is a Notion-only field — keep it out of the HubSpot payload. + excludeFields: ['attending'], + consent: + 'By submitting this form, I confirm that I have read and understood the Privacy Policy.', + }, + notion: { + database_id: '37d5004b775f80c585c7fc15377098dc', + columnMap: { + first_name: 'First Name', + last_name: 'Last Name', + email_address: 'Email', + company_name: 'Company', + job_title: 'Job Title', + phone_number: 'Phone Number', + attending: 'Attending', + }, + }, + }, + }, + ], +} + +export default page diff --git a/apps/www/_go/index.tsx b/apps/www/_go/index.tsx index 197fefd01bcaf..5e587993f9af9 100644 --- a/apps/www/_go/index.tsx +++ b/apps/www/_go/index.tsx @@ -14,6 +14,8 @@ import postgresconfContest from './events/postgresconf-sjc-2026/contest' import postgresconfContestThankYou from './events/postgresconf-sjc-2026/contest-thank-you' import selectPartnerDay from './events/select-2026/partner-day' import selectPartnerDayThankYou from './events/select-2026/partner-day-thank-you' +import selectVipDinner from './events/select-2026/vip-dinner' +import selectVipDinnerThankYou from './events/select-2026/vip-dinner-thank-you' import selectVipExperience from './events/select-2026/vip-experience' import selectVipExperienceThankYou from './events/select-2026/vip-experience-thank-you' import startupGrindContest from './events/startup-grind-2026/contest' @@ -60,6 +62,8 @@ const pages: GoPageInput[] = [ datadogDinner, // remove after June 30, 2026 aiEngineerEuropeContest, aiEngineerEuropeContestThankYou, + selectVipDinner, // remove after Select 2026 + selectVipDinnerThankYou, // remove after Select 2026 selectVipExperience, // remove after Select 2026 selectVipExperienceThankYou, // remove after Select 2026 selectPartnerDay, // remove after Select 2026 From aa393fdb7348adb33846dca2f98dafa613bb2465 Mon Sep 17 00:00:00 2001 From: Anthony Lio Date: Wed, 2 Sep 2026 20:04:42 +0300 Subject: [PATCH 2/6] chore(docs): add Anthony Lio to humans.txt (#49758) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## What kind of change does this PR introduce? add new entry in `humans.txt` file ## What is the current behavior? idle ## What is the new behavior? ˗ˏˋ Anthony Lio ˎˊ- in `humans.txt` ## Summary by CodeRabbit * **Documentation** * Added Anthony Lio to the team member listing. --- apps/docs/public/humans.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/apps/docs/public/humans.txt b/apps/docs/public/humans.txt index f6ab7613eb97f..3230223df18ac 100644 --- a/apps/docs/public/humans.txt +++ b/apps/docs/public/humans.txt @@ -28,6 +28,7 @@ Angelico de los Reyes Anna Baker Ant Evans Ant Wilson +Anthony Lio Ariuna K Arshdeep Singh Artur Zakirov From d159f03b8690531909c5a89360f74e7865a1991c Mon Sep 17 00:00:00 2001 From: Prashant Sridharan <914007+CoolAssPuppy@users.noreply.github.com> Date: Wed, 2 Sep 2026 18:29:22 +0100 Subject: [PATCH 3/6] fix: use correct Notion database ID for VIP dinner RSVPs (#49920) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Bug fix ## What is the current behavior? Submitting the `/go/select-2026/vip-dinner` form fails with a Notion 400: `Provided ID 37d5004b-775f-80c5-85c7-fc15377098dc is a page, not a database.` The form was writing to the Notion page that contains the RSVP database, not the database itself. ## What is the new behavior? RSVPs now write to the VIP dinner Notion database (`37d5004b775f809e8cc4e29fdec302aa`). ## Additional context No visual changes. This only updates the Notion `database_id` on the VIP dinner go page. Made with [Cursor](https://cursor.com) ## Summary by CodeRabbit * **Bug Fixes** * Updated the VIP dinner RSVP form’s backend configuration to ensure submissions are directed to the correct destination. * No changes were made to the form fields, configuration, or CRM mapping. Co-authored-by: Cursor --- apps/www/_go/events/select-2026/vip-dinner.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/www/_go/events/select-2026/vip-dinner.tsx b/apps/www/_go/events/select-2026/vip-dinner.tsx index f91f8836a1b03..98eeba6c23b57 100644 --- a/apps/www/_go/events/select-2026/vip-dinner.tsx +++ b/apps/www/_go/events/select-2026/vip-dinner.tsx @@ -175,7 +175,7 @@ const page: GoPageInput = { 'By submitting this form, I confirm that I have read and understood the Privacy Policy.', }, notion: { - database_id: '37d5004b775f80c585c7fc15377098dc', + database_id: '37d5004b775f809e8cc4e29fdec302aa', columnMap: { first_name: 'First Name', last_name: 'Last Name', From 37a95fd912f4be3c5c351cb1cab1a8a8bd92c115 Mon Sep 17 00:00:00 2001 From: Illia Basalaiev <44750366+Ellba@users.noreply.github.com> Date: Wed, 2 Sep 2026 20:27:02 +0200 Subject: [PATCH 4/6] docs: update edge functions limits and examples across guides (#49899) --- apps/docs/content/guides/functions/auth.mdx | 17 +++++++++++++++-- .../content/guides/functions/compression.mdx | 2 +- apps/docs/content/guides/functions/cors.mdx | 4 +++- .../content/guides/functions/dependencies.mdx | 2 +- .../content/guides/functions/error-handling.mdx | 4 ++-- .../functions/examples/mcp-server-mcp-lite.mdx | 2 +- .../guides/functions/function-configuration.mdx | 4 ++-- .../edge-function-cpu-limits.mdx | 8 ++++---- .../edge-function-monitoring-resource-usage.mdx | 2 +- ...edge-function-shutdown-reasons-explained.mdx | 2 +- .../edge-function-takes-too-long-to-respond.mdx | 2 +- ...ion-wall-clock-time-limit-reached-Nk38bW.mdx | 4 ++-- .../unable-to-deploy-edge-function.mdx | 5 +++-- 13 files changed, 37 insertions(+), 21 deletions(-) diff --git a/apps/docs/content/guides/functions/auth.mdx b/apps/docs/content/guides/functions/auth.mdx index 071707aeaf1e2..b052c70362e6c 100644 --- a/apps/docs/content/guides/functions/auth.mdx +++ b/apps/docs/content/guides/functions/auth.mdx @@ -93,14 +93,27 @@ import Stripe from 'npm:stripe' const stripe = new Stripe(Deno.env.get('STRIPE_SECRET_KEY')!) +// Deno has no synchronous Node crypto, so signature verification must go through +// Stripe's SubtleCryptoProvider. The synchronous `constructEvent()` throws +// "SubtleCryptoProvider cannot be used in a synchronous context" on this runtime. +const cryptoProvider = Stripe.createSubtleCryptoProvider() + export default { fetch: withSupabase({ auth: 'none' }, async (req, ctx) => { const signature = req.headers.get('stripe-signature') ?? '' const body = await req.text() try { - stripe.webhooks.constructEvent(body, signature, Deno.env.get('STRIPE_WEBHOOK_SECRET')!) - } catch { + await stripe.webhooks.constructEventAsync( + body, + signature, + Deno.env.get('STRIPE_WEBHOOK_SECRET')!, + undefined, + cryptoProvider + ) + } catch (err) { + // Log the reason so a configuration error isn't mistaken for a forged payload. + console.error('Stripe signature verification failed:', err) return new Response('bad signature', { status: 400 }) } diff --git a/apps/docs/content/guides/functions/compression.mdx b/apps/docs/content/guides/functions/compression.mdx index c735106fb9971..eb385e08b793e 100644 --- a/apps/docs/content/guides/functions/compression.mdx +++ b/apps/docs/content/guides/functions/compression.mdx @@ -45,6 +45,6 @@ Deno.serve(async (req) => { -Edge functions have a runtime memory limit of 150MB. Overly large compressed payloads may result in an out-of-memory error. +Edge functions have a runtime memory limit of 256MB. Overly large compressed payloads may result in an out-of-memory error. diff --git a/apps/docs/content/guides/functions/cors.mdx b/apps/docs/content/guides/functions/cors.mdx index 351beb104210f..6ae913d9cc9ee 100644 --- a/apps/docs/content/guides/functions/cors.mdx +++ b/apps/docs/content/guides/functions/cors.mdx @@ -49,7 +49,8 @@ export default { const { name } = await req.json() return Response.json({ message: `Hello ${name}!` }, { headers: corsHeaders }) } catch (error) { - return Response.json({ error: error.message }, { status: 400, headers: corsHeaders }) + const message = error instanceof Error ? error.message : String(error) + return Response.json({ error: message }, { status: 400, headers: corsHeaders }) } }, } @@ -83,6 +84,7 @@ export const corsHeaders = { 'Access-Control-Allow-Origin': '*', 'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type, x-retry-count, traceparent, tracestate, baggage', + 'Access-Control-Allow-Methods': 'GET, POST, PUT, PATCH, DELETE, OPTIONS', } ``` diff --git a/apps/docs/content/guides/functions/dependencies.mdx b/apps/docs/content/guides/functions/dependencies.mdx index 5278bdeea5397..691274669987a 100644 --- a/apps/docs/content/guides/functions/dependencies.mdx +++ b/apps/docs/content/guides/functions/dependencies.mdx @@ -103,7 +103,7 @@ You can override the default import map location using the `--import-map { }) } catch (error) { console.error('Function error:', error) - return new Response(JSON.stringify({ error: error.message }), { + return new Response(JSON.stringify({ error: 'Internal Server Error' }), { headers: { 'Content-Type': 'application/json' }, status: 500, }) @@ -47,7 +47,7 @@ Within your client-side code, an Edge Function can throw three types of errors: - **`FunctionsFetchError`**: Function couldn't be reached at all ```jsx -import { FunctionsHttpError, FunctionsRelayError, FunctionsFetchError } from '@supabase/supabase-js' +import { FunctionsFetchError, FunctionsHttpError, FunctionsRelayError } from '@supabase/supabase-js' const { data, error } = await supabase.functions.invoke('hello', { headers: { 'my-custom-header': 'my-custom-header-value' }, diff --git a/apps/docs/content/guides/functions/examples/mcp-server-mcp-lite.mdx b/apps/docs/content/guides/functions/examples/mcp-server-mcp-lite.mdx index 9b6cebcbe2e2b..f0df57dcff831 100644 --- a/apps/docs/content/guides/functions/examples/mcp-server-mcp-lite.mdx +++ b/apps/docs/content/guides/functions/examples/mcp-server-mcp-lite.mdx @@ -16,7 +16,7 @@ This guide shows you how to scaffold, develop, and deploy an MCP server using mc This combination offers several advantages: -- **Zero cold starts**: Edge Functions stay warm for fast responses +- **Fast cold starts**: Edge Functions boot in milliseconds, and warm isolates serve subsequent requests without restarting - **Global distribution**: Deploy once and run everywhere - **Direct database access**: Connect directly to your Supabase Postgres - **Minimal footprint**: mcp-lite has zero runtime dependencies diff --git a/apps/docs/content/guides/functions/function-configuration.mdx b/apps/docs/content/guides/functions/function-configuration.mdx index 86bbfc2649eec..59b4fd82c8e7d 100644 --- a/apps/docs/content/guides/functions/function-configuration.mdx +++ b/apps/docs/content/guides/functions/function-configuration.mdx @@ -28,7 +28,7 @@ import_map = './functions/image-processor/import_map.json' # Custom entrypoint for legacy function using JavaScript [functions.legacy-processor] -entrypoint = './functions/legacy-processor/index.js +entrypoint = './functions/legacy-processor/index.js' ``` This configuration tell Supabase that the `stripe-webhook` function doesn't require a valid JWT, the `image-processor` function uses a custom import map, and `legacy-processor` uses a custom entrypoint. @@ -80,7 +80,7 @@ Save your Function as a JavaScript file (e.g. `index.js`) update the `supabase/c ```toml [functions.hello-world] -entrypoint = './index.js' # path must be relative to config.toml +entrypoint = './functions/hello-world/index.js' # path must be relative to config.toml ``` You can use any `.ts`, `.js`, `.tsx`, `.jsx` or `.mjs` file as the entrypoint for a Function. diff --git a/apps/docs/content/troubleshooting/edge-function-cpu-limits.mdx b/apps/docs/content/troubleshooting/edge-function-cpu-limits.mdx index 3ff348531e2d2..4de75b8ed4266 100644 --- a/apps/docs/content/troubleshooting/edge-function-cpu-limits.mdx +++ b/apps/docs/content/troubleshooting/edge-function-cpu-limits.mdx @@ -9,7 +9,7 @@ Learn how Edge Functions manage CPU resources and what happens when limits are r ## How isolates work -An isolate is like a worker that can handle multiple requests for a function. It works until a time limit of 400 seconds is reached. Edge Functions use isolates with soft and hard CPU limits. +An isolate is like a worker that can handle multiple requests for a function. It works until it reaches the wall clock time limit. Edge Functions use isolates with soft and hard CPU limits. ## Soft limit @@ -17,7 +17,7 @@ When the isolate hits the soft limit, it **retires**. This means: - It won't take on any new requests - It will finish processing requests it's already working on -- It keeps going until it hits the hard limit for CPU time or reaches the 400-second time limit, whichever comes first +- It keeps going until it hits the hard limit for CPU time or reaches the wall clock time limit, whichever comes first ## Hard limit @@ -29,8 +29,8 @@ If there are new requests after the soft limit is reached: ## Current limits -- **Wall clock time limit:** 400 seconds total duration -- **CPU execution time:** 200 milliseconds of active computing +- **Wall clock time limit:** 150 seconds on the Free plan, 400 seconds on paid plans +- **CPU execution time:** 2 seconds of active computing per request ## What happens when limits are exceeded diff --git a/apps/docs/content/troubleshooting/edge-function-monitoring-resource-usage.mdx b/apps/docs/content/troubleshooting/edge-function-monitoring-resource-usage.mdx index 38a8b415c054a..56eec3616728f 100644 --- a/apps/docs/content/troubleshooting/edge-function-monitoring-resource-usage.mdx +++ b/apps/docs/content/troubleshooting/edge-function-monitoring-resource-usage.mdx @@ -47,7 +47,7 @@ Edge Functions have limited resources compared to traditional servers. Optimize - **Memory efficiency:** Avoid loading large datasets into memory - **CPU optimization:** Minimize complex computations -- **Execution time:** Keep functions under 60 seconds +- **Execution time:** Send a response before the 150-second request idle timeout ## Best practices diff --git a/apps/docs/content/troubleshooting/edge-function-shutdown-reasons-explained.mdx b/apps/docs/content/troubleshooting/edge-function-shutdown-reasons-explained.mdx index eca96448772bd..2614ec2d72434 100644 --- a/apps/docs/content/troubleshooting/edge-function-shutdown-reasons-explained.mdx +++ b/apps/docs/content/troubleshooting/edge-function-shutdown-reasons-explained.mdx @@ -135,7 +135,7 @@ Make your functions safe to run multiple times with the same input. Use executio ```typescript // Store execution_id to detect retries -const executionId = Deno.env.get('EXECUTION_ID') +const executionId = Deno.env.get('SB_EXECUTION_ID') const alreadyProcessed = await checkIfProcessed(executionId) if (alreadyProcessed) { diff --git a/apps/docs/content/troubleshooting/edge-function-takes-too-long-to-respond.mdx b/apps/docs/content/troubleshooting/edge-function-takes-too-long-to-respond.mdx index e47714f1608bf..99ce65bbf1de5 100644 --- a/apps/docs/content/troubleshooting/edge-function-takes-too-long-to-respond.mdx +++ b/apps/docs/content/troubleshooting/edge-function-takes-too-long-to-respond.mdx @@ -5,7 +5,7 @@ keywords = [ "slow", "timeout", "performance", "boot", "response time", "edge fu database_id = "89b868a9-17fe-4c6d-86f6-0b04e5794678" --- -Edge Functions have a 60-second execution limit. If your function is taking too long to respond, follow these steps to diagnose and optimize performance. +Edge Functions must send a response within the 150-second request idle timeout, or the platform returns a 504 Gateway Timeout. If your function is taking too long to respond, follow these steps to diagnose and optimize performance. ## Diagnose the issue diff --git a/apps/docs/content/troubleshooting/edge-function-wall-clock-time-limit-reached-Nk38bW.mdx b/apps/docs/content/troubleshooting/edge-function-wall-clock-time-limit-reached-Nk38bW.mdx index 402453a70fcb5..b7a402227c50a 100644 --- a/apps/docs/content/troubleshooting/edge-function-wall-clock-time-limit-reached-Nk38bW.mdx +++ b/apps/docs/content/troubleshooting/edge-function-wall-clock-time-limit-reached-Nk38bW.mdx @@ -19,8 +19,8 @@ When this message appears in the context of your edge function, it means that th **Current Limits Explained** -- Wall Clock Time Limit: Currently set at 400 seconds for the total duration your edge function can run. -- CPU Execution Time: Limited to 200 milliseconds of active computing. +- Wall Clock Time Limit: 150 seconds on the Free plan and 400 seconds on paid plans, for the total duration your edge function can run. +- CPU Execution Time: Limited to 2 seconds of active computing per request. This means that if your edge function completes its task within these time constraints, there's no need to be concerned about the "wall clock time limit reached" error message. diff --git a/apps/docs/content/troubleshooting/unable-to-deploy-edge-function.mdx b/apps/docs/content/troubleshooting/unable-to-deploy-edge-function.mdx index 6c644de9e3e85..2ce50a477958a 100644 --- a/apps/docs/content/troubleshooting/unable-to-deploy-edge-function.mdx +++ b/apps/docs/content/troubleshooting/unable-to-deploy-edge-function.mdx @@ -28,7 +28,7 @@ supabase functions deploy your-function --debug - **Syntax errors:** TypeScript or JavaScript syntax issues in your function code - **Invalid imports:** Importing modules that don't exist or aren't compatible with Deno -- **Large bundle size:** Functions have a 10MB source code limit. See [Bundle size issues](./edge-function-bundle-size-issues) for more details +- **Large bundle size:** Functions have a maximum size of 20MB when bundled locally through the CLI, or 5MB when bundled server-side, for example through the Management API or Dashboard. See [Bundle size issues](./edge-function-bundle-size-issues) for more details - **Network issues:** Problems reaching the Supabase API during deployment ## Before opening a support ticket @@ -37,9 +37,10 @@ Make sure you're using the latest version of the Supabase CLI: ```bash supabase --version -supabase update ``` +If it's out of date, upgrade using whichever package manager installed the CLI, for example `brew upgrade supabase`, `npm update supabase --save-dev`, or `scoop update supabase`. + If these steps don't resolve the issue, open a support ticket via the Supabase Dashboard and include all output from the diagnostic commands. ## Additional resources From a27f81d5a046b95dab3f5ad0e0302c0dd5a611b0 Mon Sep 17 00:00:00 2001 From: Nik Richers Date: Wed, 2 Sep 2026 11:48:59 -0700 Subject: [PATCH 5/6] docs: improve write-the-docs skill and retire docs-content (#49089) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## I have read the CONTRIBUTING.md file. YES ## What kind of change does this PR introduce? Improves the `write-the-docs` skill and retires the overlapping `docs-content` skill (provided @czenko agrees to the latter). ## What is the current behavior? - Docs drafts could leak future-tense / internal roadmap language, add redundant verbiage, and add single-item lists. - No explicit CONTRIBUTING.md / WORD_LIST.md compliance pass for docs drafts. - Product intent was assumed to come from Linear without a good path path for open-source contributors. - `docs-content` overlapped `write-the-docs` and the broader `*-the-docs` skill set (e.g. I started [#49432](https://github.com/supabase/supabase/pull/49432) before realizing we should likely not have overlapping skills). ## What is the new behavior? - Codifies draft pitfalls as principles in `reference/common-pitfalls.md` (timelessness, strip internal business context, redundancy, single-item lists), with style detail pointed from `SKILL.md` rather than duplicated. - Clarifies SoT: Linear + code inspection for content accuracy; CONTRIBUTING.md / WORD_LIST.md (and future DOCS-1177 style guide) for voice/terminology/formatting only. `common-pitfalls.md` is flagged to fold into that guide later. - Linear is internal and preferred when available, not required for open-source. Missing product intent: stop Draft and hand off to `pm-the-docs` (Frame) / `ask-the-docs` (Shape/IA); do not invent positioning or run Frame/Shape inside this skill. - Adds drafting mechanics notes, a compliance checklist before handoff, and a local `/review-the-docs` self-review step. - Removes `.claude/skills/docs-content/`; `.claude/CLAUDE.md` points at the canonical docs skills. Supersedes #49432. ## Additional context Based on @czenko review feedback on #49020 and feedback I received for `docs-content` from @aantti while trialing the "Write the docs" process with contributors, plus my own testing while drafting docs for product managers. ### Test plan - [ ] `SKILL.md` reads as Draft-only; Frame/Shape stay with `pm-the-docs` / `ask-the-docs` - [ ] No-Linear path: ask for Linear (internal) or hand off Frame/Shape; no invented positioning - [ ] `.claude/skills/docs-content/` gone; `.claude/CLAUDE.md` updated - [ ] `.claude/skills/write-the-docs` symlink still resolves to `.agents/skills/write-the-docs` - [ ] Next `/write-the-docs` run: compliance re-read + pitfalls guidance before handoff ## Summary by CodeRabbit - **Documentation** - Added an `edit-the-docs` workflow for restructuring and improving existing documentation pages. - Expanded authoring guidance for concise, timeless, user-focused content grounded in product intent. - Added references covering common writing pitfalls, link and anchor conventions, and validation workflows. - Clarified that style guidance applies to voice, formatting, and terminology—not product behavior. - Updated documentation workflows to distinguish planning, writing, editing, review, and assistance responsibilities. - Replaced the previous standalone docs-content skill with the updated authoring skill model. --------- Co-authored-by: Cursor Agent Co-authored-by: Nik Richers Co-authored-by: Miranda Limonczenko --- .agents/skills/edit-the-docs/SKILL.md | 74 ++++++++++++++ .../reference/structure-and-flow.md | 29 ++++++ .agents/skills/pm-the-docs/SKILL.md | 5 +- .../reference/write-the-docs-checklist.md | 2 + .agents/skills/write-the-docs/SKILL.md | 53 +++++++--- .../reference/common-pitfalls.md | 94 ++++++++++++++++++ .../reference/drafting-mechanics.md | 46 +++++++++ .../reference/style-fallback.md | 6 +- .claude/CLAUDE.md | 2 +- .claude/skills/docs-content/SKILL.md | 97 ------------------- .claude/skills/edit-the-docs | 1 + .cursor/skills/edit-the-docs | 1 + apps/docs/CONTRIBUTING.md | 5 +- 13 files changed, 298 insertions(+), 117 deletions(-) create mode 100644 .agents/skills/edit-the-docs/SKILL.md create mode 100644 .agents/skills/edit-the-docs/reference/structure-and-flow.md create mode 100644 .agents/skills/write-the-docs/reference/common-pitfalls.md create mode 100644 .agents/skills/write-the-docs/reference/drafting-mechanics.md delete mode 100644 .claude/skills/docs-content/SKILL.md create mode 120000 .claude/skills/edit-the-docs create mode 120000 .cursor/skills/edit-the-docs diff --git a/.agents/skills/edit-the-docs/SKILL.md b/.agents/skills/edit-the-docs/SKILL.md new file mode 100644 index 0000000000000..6c8df9905779a --- /dev/null +++ b/.agents/skills/edit-the-docs/SKILL.md @@ -0,0 +1,74 @@ +--- +name: edit-the-docs +description: >- + Restructure, reorder, and improve existing Supabase docs pages under + apps/docs — clarity, connective text, section grouping, and brevity. + Use when asked to edit, reorganize, restructure, tighten prose, or add + glue between sections on a page that already exists. Not for net-new + feature drafts (use write-the-docs) or PR triage/verification (use + review-the-docs). +--- + +# Edit the docs + +Improves **existing** Supabase docs pages: structure, order, connective text, +and clarity. Distinct from [`write-the-docs`](../write-the-docs/SKILL.md) +(draft net-new or product-grounded rewrites from intent + code) and +[`review-the-docs`](../review-the-docs/SKILL.md) (lint, build, PR triage). + +## Core rules + +1. **Read before you rewrite.** Open the target page and nearby pages of the same type. Name the reader's goal and the page type (explainer, guide, tutorial, troubleshooting) before moving sections. +2. **Improve structure and clarity; don't invent product truth.** Preserve behavior claims, UI labels, and positioning unless you verify a change against code or product intent. Accuracy gaps or missing net-new content belong with [`write-the-docs`](../write-the-docs/SKILL.md) / [`pm-the-docs`](../pm-the-docs/SKILL.md), not silent invention here. +3. **Follow CONTRIBUTING.md and WORD_LIST.md** for voice, terminology, and formatting. See [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md) and [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md). +4. **Prefer brevity.** Prefer broad strokes when mechanical detail doesn't help the reader's task. Cut redundancy; don't over-explain. +5. **Reuse sibling skills.** IA/architecture via [`ask-the-docs`](../ask-the-docs/SKILL.md); validation and self-review via [`review-the-docs`](../review-the-docs/SKILL.md). Shared pitfalls live in [`write-the-docs/reference/common-pitfalls.md`](../write-the-docs/reference/common-pitfalls.md) — apply them, don't duplicate them. + +## Phase 1 — Diagnose + +1. Identify the document type per CONTRIBUTING.md (explainer, tutorial, guide, reference, or troubleshooting). +2. State the reader's goal and prerequisites in one or two lines. +3. Note structural problems: mixed information types interrupting a procedure, missing intro navigation on a long page, weak transitions, redundancy, or over-explained mechanics. +4. Summarize the diagnosis to the requester before large moves when the restructure would change how the page is read. + +## Phase 2 — Restructure + +Apply [reference/structure-and-flow.md](reference/structure-and-flow.md): + +1. Classify substantial sections as contextual, procedural, or reference content. In a mixed page, group sections by information type so that context doesn't interrupt the procedural path. +2. For a long or mixed page, add a short introduction that links to its major section groups and tells readers when to use each one. Skip this navigation when a short page is already easy to scan. +3. Connect contextual sections to their corresponding procedures when useful. Add introductions to section groups, transitions between information types, and outcomes after procedures. Don't link every adjacent section. +4. Move and regroup first; preserve meaning. Don't silently rewrite facts while restructuring. + +## Phase 3 — Edit for clarity + +- Use second person, present tense, short paragraphs, and ordered steps for sequential actions. +- Cut restated points and mechanical over-explanation. +- Apply [`write-the-docs/reference/common-pitfalls.md`](../write-the-docs/reference/common-pitfalls.md): timelessness, no internal planning context in shipped MDX, redundancy, single-item lists, admonition restatement. +- Search [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md) when introducing or revising technical terms and UI actions. +- Keep code samples executable in their stated context; mark intentionally omitted code. Prefer partials under `apps/docs/content/_partials/` over copied blocks. + +## Phase 4 — Validate + +Before handoff: + +- [ ] Section groups follow information type; procedures aren't interrupted by long context +- [ ] Intro navigation present only when the page needs it; links resolve +- [ ] Connective text is selective, not link spam +- [ ] Voice matches CONTRIBUTING.md / WORD_LIST.md +- [ ] No invented behavior or positioning +- [ ] Shared pitfalls checklist considered + +Mechanics (anchors, lint, format): follow [`write-the-docs/reference/drafting-mechanics.md`](../write-the-docs/reference/drafting-mechanics.md). Before renaming or rewording headings, grep for `#` under `apps/docs/content` and update matches. + +Then run [`review-the-docs`](../review-the-docs/SKILL.md) local self-review (`pnpm lint:mdx`, and `pnpm build:guides-markdown` when guides/explainers/tutorials changed). + +## Additional resources + +- Structure SoT: [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md) (mixed types, navigation, glue) +- Structure ops: [reference/structure-and-flow.md](reference/structure-and-flow.md) +- Pitfalls: [`write-the-docs/reference/common-pitfalls.md`](../write-the-docs/reference/common-pitfalls.md) +- Mechanics: [`write-the-docs/reference/drafting-mechanics.md`](../write-the-docs/reference/drafting-mechanics.md) +- Architecture/IA: [`ask-the-docs`](../ask-the-docs/SKILL.md) +- Net-new drafts: [`write-the-docs`](../write-the-docs/SKILL.md) +- Review: [`review-the-docs`](../review-the-docs/SKILL.md) diff --git a/.agents/skills/edit-the-docs/reference/structure-and-flow.md b/.agents/skills/edit-the-docs/reference/structure-and-flow.md new file mode 100644 index 0000000000000..57cad4b37a869 --- /dev/null +++ b/.agents/skills/edit-the-docs/reference/structure-and-flow.md @@ -0,0 +1,29 @@ +# Structure and flow + +Operational guidance for restructuring existing docs pages. The human-facing +source of truth is [`apps/docs/CONTRIBUTING.md`](../../../../apps/docs/CONTRIBUTING.md) +under Guides: **Mixed information types**, **Navigation**, and +**Cross-references and glue**. Keep this file aligned with that section. + +## Classify and group + +Classify substantial sections as contextual, procedural, or reference content. +In a mixed page, group sections by information type so that context doesn't +interrupt the procedural path. + +## Introduction navigation + +For a long or mixed page, add a short introduction that links to its major +section groups and tells readers when to use each one. Skip this navigation +when a short page is already easy to scan. + +## Connective text + +Connect contextual sections to their corresponding procedures when useful. +Add introductions to section groups, transitions between information types, +and outcomes after procedures. Don't link every adjacent section. + +## Voice and procedure shape + +Use second person, present tense, short paragraphs, and ordered steps for +sequential actions. diff --git a/.agents/skills/pm-the-docs/SKILL.md b/.agents/skills/pm-the-docs/SKILL.md index 02b49c9cbcc05..3d3d2a4867b20 100644 --- a/.agents/skills/pm-the-docs/SKILL.md +++ b/.agents/skills/pm-the-docs/SKILL.md @@ -19,7 +19,7 @@ Backs the Frame and Shape stages of the "Write the docs" checklist (mirrored in - Deciding content type, IA placement, or prerequisites for a page (Shape). - Unsure whether a docs question is self-serve or needs a docs PM's sign-off. -**Not for** drafting content itself (see [`write-the-docs`](../write-the-docs/SKILL.md)) or docs-app architecture/IA placement mechanics (see [`ask-the-docs`](../ask-the-docs/SKILL.md)). +**Not for** drafting content itself (see [`write-the-docs`](../write-the-docs/SKILL.md)), restructuring existing pages (see [`edit-the-docs`](../edit-the-docs/SKILL.md)), or docs-app architecture/IA placement mechanics (see [`ask-the-docs`](../ask-the-docs/SKILL.md)). ## Answering a scope/stage/audience question @@ -27,7 +27,7 @@ Backs the Frame and Shape stages of the "Write the docs" checklist (mirrored in 2. Read whatever context exists for the feature: the linked issue/project, the PRD, the shipped code or PR. When code and PRD disagree, the code wins for behavior claims. 3. Answer the checklist's questions directly: product stage, audience and job-to-be-done, the one-line "why," content type, IA placement, prerequisites. 4. Distinguish **confirmed fact** (stated in the ticket/PRD/code) from **inference** (your best read) — flag inference explicitly rather than presenting it as settled. -5. If a decision is genuinely open at the org level (not a docs-content call), say so and name who should decide instead of inventing an answer to look complete. +5. If a decision is genuinely open at the org level (not a docs authoring call), say so and name who should decide instead of inventing an answer to look complete. ## Self-serve vs. escalate @@ -39,4 +39,5 @@ Escalate to your docs team's PM when scope or stage is unclear, you need a revie - [`ask-the-docs`](../ask-the-docs/SKILL.md) — IA placement and docs-app architecture (Shape stage) - [`write-the-docs`](../write-the-docs/SKILL.md) — drafting once Frame/Shape are settled +- [`edit-the-docs`](../edit-the-docs/SKILL.md) — restructure and improve existing pages - [`review-the-docs`](../review-the-docs/SKILL.md) — self-review and PR review stages diff --git a/.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md b/.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md index e3eae3900c8b2..caefd757d4adc 100644 --- a/.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md +++ b/.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md @@ -39,6 +39,8 @@ _Skill:_ `/write-the-docs` to draft net-new content grounded in Linear and the c - [ ] E: Contribute technical depth and verify accuracy (APIs, limits, edge cases) - [ ] P: Call out the current stage inline and any known limitations +When the work is improving an existing page (restructure, reorder, connective text, brevity) rather than authoring net-new content, use `/edit-the-docs` instead of `/write-the-docs`. + ## 4. Self-review against the bar _Skill:_ `/review-the-docs` — [Local self-review](../review-the-docs/SKILL.md#local-self-review-no-open-pr) on your own branch before opening the PR. diff --git a/.agents/skills/write-the-docs/SKILL.md b/.agents/skills/write-the-docs/SKILL.md index 75902d79ddffe..989d7a61fbb8b 100644 --- a/.agents/skills/write-the-docs/SKILL.md +++ b/.agents/skills/write-the-docs/SKILL.md @@ -2,31 +2,32 @@ name: write-the-docs description: >- Draft new or updated Supabase docs content for a feature or launch, - grounded in Linear (the ticket plus its product/PM context), a read of the - actual code, and the docs style guide once one exists. Use when asked to - write docs for a new feature, a launch (e.g. Select 2026), or a Linear - ticket that needs net-new content rather than a bug fix. Not for - implementing existing docs bug reports — use work-linear-issue for that. + grounded in product intent (Linear when available), a read of the actual + code, and the docs style guide once one exists. Use when asked to write + docs for a new feature, a product launch, or a Linear ticket that needs + net-new content rather than a bug fix. Not for implementing existing docs + bug reports — use work-linear-issue for that. Not for restructuring + existing pages — use edit-the-docs for that. --- # Write the docs -Drafts net-new (or substantially rewritten) Supabase docs content for a feature or launch. Distinct from [`work-linear-issue`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/work-linear-issue/SKILL.md), which implements and fixes existing docs tickets — this skill is for the case where the content doesn't exist yet and has to be authored from scratch, grounded in four inputs rather than guessed. +Drafts net-new Supabase docs content (or product-grounded rewrites) for a feature or launch. Distinct from [`work-linear-issue`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/work-linear-issue/SKILL.md), which implements and fixes existing docs tickets, and from [`edit-the-docs`](../edit-the-docs/SKILL.md), which restructures and tightens pages that already exist without gathering net-new product intent. This skill is for the case where the content doesn't exist yet (or must be rewritten from intent + code), grounded in four inputs rather than guessed. ## Core rules 1. **Gather before drafting.** Never draft from a ticket title alone. Pull all four inputs below first; a thin gather phase produces a draft that's wrong about how the feature actually works. -2. **Separate confirmed behavior from product intent from inference.** Code tells you what the feature does today. Linear/PRD/PRFAQ tells you what it's meant to do and how it should be positioned. Anything you had to guess, flag explicitly rather than stating it as fact. -3. **Follow CONTRIBUTING.md and WORD_LIST.md; say so when you fall back to a precedent page.** Don't silently invent voice/structure rules — name the nearest existing-page precedent you followed instead (see [reference/style-fallback.md](reference/style-fallback.md)). +2. **Separate confirmed behavior from product intent from inference.** Code tells you what the feature does today. Linear/PRD/PRFAQ (or prior Frame/Shape output) tells you what it's meant to do and how it should be positioned. Anything you had to guess, flag explicitly rather than stating it as fact. +3. **Follow CONTRIBUTING.md and WORD_LIST.md for voice, terminology, and formatting only, never for content accuracy.** These are a style reference, not a source of truth: rule 2's Linear+code read is what governs what the page actually says. Don't silently invent voice/structure rules either; name the nearest existing-page precedent you followed instead (see [reference/style-fallback.md](reference/style-fallback.md)). 4. **Reuse, don't duplicate.** For docs-app architecture/placement questions, use [`ask-the-docs`](../ask-the-docs/SKILL.md) and [`audit-docs-ia`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/audit-docs-ia/SKILL.md) rather than re-deriving that knowledge here. -5. **Know what you're actually drafting.** Not everything that looks like "docs for a feature" is a hand-written page — see the content-type gate below before you start writing. +5. **Know what you're actually drafting.** Not everything that looks like "docs for a feature" is a hand-written page — see the content-type gate below before you start writing. If the ask is restructure, reorder, connective text, or clarity on an existing page (no new product story), use [`edit-the-docs`](../edit-the-docs/SKILL.md) instead. ## Phase 1 — Gather (read-only) -Four inputs, in order: +Four inputs, read in this sequence (sequence, not priority; Linear remains the product-intent source and code remains the behavior source per rule 2 and Phase 1 step 3): -1. **Style guide.** Start with [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md) and [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md) for voice, structure, and terminology. If those don't cover the case, fall back to the nearest comparable existing page under `apps/docs/content/` and say explicitly: _"no dedicated style guide yet — following the precedent of ``."_ See [reference/style-fallback.md](reference/style-fallback.md). -2. **Linear — the ticket and its product context.** Pull the Linear issue itself, then don't stop there: pull its parent project/initiative description too (PRD, PRFAQ, RFC, or initiative narrative) and any PM comments. Product framing/positioning language usually lives one level up from the ticket, not in the ticket body — see how the Select 2026 initiative's own description carried the real launch narrative, not any single project's ticket. Distinguish scope the ticket actually commits to from aspirational language in the PRD. +1. **Style guide — voice/terminology reference.** Start with [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md) and [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md) for voice, structure, and terminology. If those don't cover the case, fall back to the nearest comparable existing page under `apps/docs/content/` and say explicitly: _"no dedicated style guide yet — following the precedent of ``."_ See [reference/style-fallback.md](reference/style-fallback.md). +2. **Linear — the ticket and its product context.** Linear is an internal Supabase tool: preferred when available, not required for open-source contributors. When a Linear issue is available, pull it, then its parent project/initiative description too (PRD, PRFAQ, RFC, or initiative narrative) and any PM comments. Product framing/positioning language usually lives one level up from the ticket, in the parent project or initiative description rather than the ticket body. Distinguish scope the ticket actually commits to from aspirational language in the PRD. If there is no Linear issue and no prior Frame/Shape product-intent output, stop drafting: ask internal authors for a Linear URL, otherwise hand off to [`pm-the-docs`](../pm-the-docs/SKILL.md) (Frame) and [`ask-the-docs`](../ask-the-docs/SKILL.md) when Shape/IA is unsettled. Resume only after product intent exists — never invent positioning, and never run Frame/Shape inside this Draft skill. 3. **Code.** Read the actual implementation before writing a single behavior claim — the PRD describes intent, the code describes what shipped. Check the Linear issue/project first for a linked `supabase/supabase` PR — its diff and description are the most precise "what actually shipped" source, more precise than a general codebase read. If no PR is linked, locate the feature directly in `supabase/supabase` (or the product's own repo), and apply [`ask-the-docs`](../ask-the-docs/SKILL.md)'s reuse/minimalism lens: understand what exists before describing it. If code and PRD disagree, the code wins for behavior claims — flag the mismatch rather than silently picking one. 4. **Whatever else the author supplies.** Screenshots, example projects, related pages, Slack threads, a specific voice sample. Screenshots are for more than general context — use them to verify the _exact_ button/menu/field labels before writing instructional steps that reference them; a mismatched UI label is one of the easiest, most avoidable errors in a draft. Ask for these when the feature's user-facing shape is still unclear after 1–3, rather than guessing. @@ -47,7 +48,13 @@ When in doubt, ask `ask-the-docs` rather than guessing — this classification i - Follow `apps/docs` MDX conventions (component usage, frontmatter, code sample wiring) — see [`ask-the-docs`](../ask-the-docs/SKILL.md) for the pipeline details rather than re-deriving them. - Place the page using existing IA precedent; for a placement call that isn't obvious, consult [`audit-docs-ia`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/audit-docs-ia/SKILL.md)'s nav/IA knowledge rather than guessing a nav slot. - **Wire it into navigation, not just onto disk.** Placement (which section) and nav enablement (whether it actually shows up) are separate — confirm the current nav-registration mechanism via `ask-the-docs`/`audit-docs-ia` rather than assuming a page is discoverable just because the file exists in the right folder. -- Ground every behavior claim in Phase 1's code read (the linked PR when there is one); ground every "why this matters" framing in the PRD/PM context; mark inferred material inline (e.g. an HTML comment or a flagged line in the handoff summary) so a reviewer can find it fast. +- Ground every behavior claim in Phase 1's code read (the linked PR when there is one); ground every "why this matters" framing in Linear/PM context or prior Frame/Shape output; mark inferred material inline (e.g. an HTML comment or a flagged line in the handoff summary) so a reviewer can find it fast. +- **Write for timelessness.** Prefer documenting what exists now over promising future features. See [reference/common-pitfalls.md](reference/common-pitfalls.md#2-timeless-documentation). +- **Keep it concise and avoid redundancy.** See [reference/common-pitfalls.md](reference/common-pitfalls.md#4-redundancy). +- **Prefer paragraphs over single-item lists.** See [reference/common-pitfalls.md](reference/common-pitfalls.md#5-single-item-lists). +- **Strip internal business context before the final draft.** HTML comments flagging PRD intent, roadmap speculation, internal ticket discussions, or "gap-fill" notes must be removed from MDX before handoff. Open-source docs shouldn't expose internal planning. Flag assumptions and open questions for reviewers in the PR description instead, not in the shipped content. +- Search [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md) when introducing or reviewing technical terms, UI actions, abbreviations, and potentially ambiguous language during drafting. This targeted search supplements, but does not replace, the full-file compliance check in Phase 2.5. +- Reuse repeated content through `apps/docs/content/_partials/` instead of copying it. For nav wiring, partials, and file placement, see [`ask-the-docs`](../ask-the-docs/SKILL.md)'s `app-map.md` and `federated-docs.md`. ## Phase 2.5 — Review checklist @@ -55,11 +62,25 @@ Before handing off, confirm: - [ ] CONTRIBUTING.md / WORD_LIST.md followed, or precedent page named explicitly - [ ] Every behavior claim traces to the code read (ideally the linked PR), not just the PRD -- [ ] Every "why it matters" / positioning line traces to Linear/PM context, not invented +- [ ] Every "why it matters" / positioning line traces to Linear/PM context or prior Frame/Shape output, not invented - [ ] Inferred or assumed material is flagged, not stated as fact - [ ] Content type confirmed as Guide/Troubleshooting (not something that belongs in generated Reference instead) - [ ] Nav placement and nav enablement both wired, not just the placement - [ ] Internal links resolve; first-use of new terms/acronyms is defined +- [ ] Future promises minimized where possible (timeless documentation principle) +- [ ] No unnecessary redundancy (same point restated multiple ways) +- [ ] Single-item lists avoided unless there's a specific reason +- [ ] Internal gap-fill and business context comments removed from MDX (keep only in PR description if needed for review) + +### Compliance checklist + +Re-read [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md) and [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md) in full before handoff, not just the sections searched during drafting. When a dedicated style guide lands in the repo, extend this checklist to cover it too. + +- [ ] Parentheses used only for acronyms or `(Optional)`, not prose asides +- [ ] Bold, italics, and code used only for their distinct purposes (UI labels, must-not-miss terms), not for visual emphasis alone +- [ ] No dash-based asides where a direct sentence reads better +- [ ] Terminology matches `WORD_LIST.md` (including any terms flagged as imprecise, not just spelling/capitalization) +- [ ] Headings, admonitions, and links follow CONTRIBUTING.md's "Styling, formatting, and grammar" and "Components and elements" sections ## Phase 3 — Handoff @@ -67,11 +88,15 @@ This skill stops at a reviewable draft. It does not open worktrees or PRs itself - Hand off to [`create-pull-request`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/create-pull-request/SKILL.md) (and [`work-linear-issue`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/work-linear-issue/SKILL.md) if the ticket needs a full worktree+PR flow) for the actual PR mechanics. Carry the Phase 1/2 flagged-assumptions list forward explicitly into that handoff — it belongs in the PR description (e.g. a "needs review" section) so a reviewer sees it, not just as an inline comment buried in the draft. - If the feature is UI-driven and the PR will need screenshots/GIFs, flag [`proof-it-works`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/proof-it-works/SKILL.md) as the next step rather than capturing evidence here. +- Before opening the PR, run [`review-the-docs`](../review-the-docs/SKILL.md) local self-review: `pnpm lint:mdx`, `pnpm build:guides-markdown` where applicable, and anchor checks per [reference/drafting-mechanics.md](reference/drafting-mechanics.md). ## Additional resources - Style / terminology: [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md), [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md), [reference/style-fallback.md](reference/style-fallback.md) +- Common pitfalls to avoid: [reference/common-pitfalls.md](reference/common-pitfalls.md) +- Drafting mechanics: [reference/drafting-mechanics.md](reference/drafting-mechanics.md) - Content-type gate detail: [reference/content-type-gate.md](reference/content-type-gate.md) +- Existing-page restructure/clarity: [`edit-the-docs`](../edit-the-docs/SKILL.md) - "Write the docs" checklist (Draft stage): [`pm-the-docs`](../pm-the-docs/SKILL.md)'s [reference/write-the-docs-checklist.md](../pm-the-docs/reference/write-the-docs-checklist.md) - Docs-app architecture/placement: [`ask-the-docs`](../ask-the-docs/SKILL.md), [`audit-docs-ia`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/audit-docs-ia/SKILL.md) - PR mechanics: [`create-pull-request`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/create-pull-request/SKILL.md), [`work-linear-issue`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/work-linear-issue/SKILL.md) diff --git a/.agents/skills/write-the-docs/reference/common-pitfalls.md b/.agents/skills/write-the-docs/reference/common-pitfalls.md new file mode 100644 index 0000000000000..87df439528d83 --- /dev/null +++ b/.agents/skills/write-the-docs/reference/common-pitfalls.md @@ -0,0 +1,94 @@ +# Common pitfalls in docs drafts + +Patterns to watch for when drafting docs, based on review feedback. These are guidelines, not absolute rules — use judgment based on context. + +## 1. Internal planning context in open-source docs + +**Principle:** Supabase docs are open source. Internal planning context, unshipped features, and business intent shouldn't be visible in the public repo. + +**What to watch for:** + +- HTML comments referencing PRDs, roadmaps, or internal ticket discussions +- "Gap-fill" notes about what's planned but not shipped +- Internal product strategy or positioning discussions +- References to any project-management or ticketing system (internal or a contributor's own tools) + +**Where to put internal context instead:** + +- PR description (for review-time context) +- The team's project-management tool (for product/PM handoff) +- Internal docs (for roadmap tracking) + +## 2. Timeless documentation + +**Principle:** Prefer documenting what exists now over promising future features ([Google's timeless documentation](https://developers.google.com/style/timeless-documentation)). Future promises become stale. + +**Common patterns to watch for:** + +- "Coming soon" / "will be available" / "once finalized" +- "This page is a placeholder" +- "Being rolled out gradually" without concrete eligibility criteria + +**Better alternatives:** + +- Document what exists today +- Wait to publish until the feature is complete +- If phased rollout is real, be specific: "Available to organizations on Pro and Enterprise plans" + +**Context matters:** Changelog and roadmap content naturally references the future — this guidance applies primarily to feature documentation. + +## 3. Placeholder pages + +**Principle:** Generally avoid shipping pages that explicitly say "This is a placeholder" or "More details coming soon." + +**Alternatives:** + +- Wait to publish until content is ready +- If navigation structure requires it, link to external resources that are complete +- Ship minimal but useful content (what's true today) rather than promises + +**Valid exceptions:** Navigation structure needs, federated docs where the placeholder provides context and links out, cross-references where the page existing (even minimal) provides value. + +## 4. Redundancy and over-explanation + +**Principle:** Avoid restating the same point in multiple ways. Prefer brevity — sometimes broad strokes help more than mechanical detail. + +**Common patterns:** + +- Multiple ways of saying the same thing: "It's free" + "You won't be billed" + "No charge" +- Admonition stating a risk, then body text restating it verbatim +- Adjacent sentences that rephrase each other +- Over-explaining mechanical steps or implementation detail that doesn't help the reader complete the task + +**How to catch it:** If you can remove a sentence without losing information, it's probably redundant. If a procedure works with less setup explanation, prefer the shorter path. + +## 5. Single-item lists + +**Principle:** Prefer paragraphs over single-item bullet lists. + +**Why:** Single-item lists can signal incomplete content. + +**Valid exceptions:** Layout consistency across sections, future expansion expected, or when the item needs special visual emphasis. + +## 6. Restating admonition content + +**Principle:** Admonitions and body text should cover distinct points, not repeat each other. + +**What to watch for:** An admonition stating a risk/limitation, then the next paragraph restating it verbatim. + +## Summary checklist + +Before submitting a draft, check: + +- [ ] No HTML comments with internal PRD/roadmap/ticket context in MDX +- [ ] Future promises minimized where appropriate (timeless documentation) +- [ ] Placeholder pages avoided where possible +- [ ] No unnecessary redundancy or mechanical over-explanation +- [ ] Single-item lists avoided unless there's a reason +- [ ] Admonitions and body text cover distinct points + +**Note:** These are guidelines based on review feedback, not absolute rules. Use judgment based on content type, context, and the specific documentation needs. The goal is clearer, more maintainable docs, not rigid adherence to formatting rules. + +## Style guide consolidation + +This content is style guidance, not skill-specific process. It belongs in a shared, human-and-agent-readable style guide rather than only inside this skill. When a dedicated style guide exists in the repo, fold this content into it and replace this file with a pointer, the same pattern [reference/style-fallback.md](style-fallback.md) already uses for CONTRIBUTING.md/WORD_LIST.md. diff --git a/.agents/skills/write-the-docs/reference/drafting-mechanics.md b/.agents/skills/write-the-docs/reference/drafting-mechanics.md new file mode 100644 index 0000000000000..0097c98b47c98 --- /dev/null +++ b/.agents/skills/write-the-docs/reference/drafting-mechanics.md @@ -0,0 +1,46 @@ +# Drafting mechanics + +Mechanics that come up during drafting but aren't worth duplicating from +`CONTRIBUTING.md` or `ask-the-docs`. For nav wiring, partials, and file +placement, see `ask-the-docs`'s `app-map.md` and `federated-docs.md`. + +## Link paths + +- Use `/docs/...` paths for pages in Supabase docs. +- Use site-root paths such as `/dashboard` for pages outside docs. +- Use descriptive link text and sparse admonitions with the appropriate severity. + +## Anchor stability + +Anchor IDs are generated from heading text at render time, and nothing in CI +checks that `#anchor` links still resolve. Before renaming, removing, or +substantially rewording a heading, run: + +```bash +grep -rn "#" apps/docs/content +``` + +Update every in-page and cross-file match. If a heading needs a stable anchor +independent of its wording, pin it with a custom anchor, for example +`## Some heading [#some-heading]`. + +## Lint and format + +From `apps/docs`: + +```bash +pnpm lint:mdx +pnpm build:guides-markdown +``` + +`pnpm lint:mdx` covers all content under `apps/docs/content`, including +troubleshooting entries. `pnpm build:guides-markdown` only applies to guides, +explainers, and tutorials. + +From the repository root, run `pnpm format` to apply Prettier to changed MDX +files. This enforces repo-wide formatting rules, including lowercase SQL +keyword casing in code samples. + +Treat `supa-mdx-lint` replacements as suggestions when context matters. Rewrite +the sentence instead of applying a replacement that changes its technical +meaning. diff --git a/.agents/skills/write-the-docs/reference/style-fallback.md b/.agents/skills/write-the-docs/reference/style-fallback.md index e86e83fcd6ee1..f89cd07321089 100644 --- a/.agents/skills/write-the-docs/reference/style-fallback.md +++ b/.agents/skills/write-the-docs/reference/style-fallback.md @@ -1,7 +1,11 @@ # Style guide fallback There is no separate published style guide yet beyond what already lives in -this repo. Use the public sources below, in order: +this repo. Use the public sources below, in order. + +This fallback governs voice, formatting, and terminology only. It's not a +source of truth for behavior or product framing (that's the Gather phase's +Linear + code read, per SKILL.md rule 3). 1. Read [`apps/docs/CONTRIBUTING.md`](../../../../apps/docs/CONTRIBUTING.md) for authoring conventions (voice, structure, document types). diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 144e60df965cb..8d358ee0e73bb 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -60,7 +60,7 @@ Never hand-edit generated files: `packages/api-types/types/**`, `**/routeTree.ge The skills in `.claude/skills/` are the source of truth for conventions — load the relevant ones before working, don't guess: - `copywriting` — any user-facing text, anywhere in the monorepo -- `docs-content` — anything under `apps/docs` +- `pm-the-docs` / `write-the-docs` / `edit-the-docs` / `ask-the-docs` / `review-the-docs` — anything under `apps/docs` (see `apps/docs/CONTRIBUTING.md` for the authoring skill model) - `telemetry-standards` — PostHog events, `packages/common/telemetry-constants.ts` - `dev-toolbar-review` — `packages/dev-tools`, `packages/common/posthog-client.ts`, `packages/common/feature-flags.tsx` - `safe-sql-execution` — any code that builds or executes SQL against user databases diff --git a/.claude/skills/docs-content/SKILL.md b/.claude/skills/docs-content/SKILL.md deleted file mode 100644 index a24486efb6410..0000000000000 --- a/.claude/skills/docs-content/SKILL.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -name: docs-content -description: Write, edit, organize, and review Supabase content anywhere in apps/docs — guides, explainers, tutorials, troubleshooting entries, reference docs, and partials. Use for MDX/TOML authoring, frontmatter, navigation, terminology, links, code samples, content listings, and docs validation. ---- - -# Supabase docs authoring - -## Sources of truth - -Before changing docs content: - -1. Read `apps/docs/CONTRIBUTING.md` for content types, structure, components, and - style. -2. Read `apps/docs/WORD_LIST.md` for preferred terminology, spelling, and - capitalization. -3. Inspect nearby content of the same type and the relevant navigation section - before deciding on file placement or structure. Guides, explainers, and - tutorials live under `apps/docs/content/guides`. Troubleshooting entries live - under `apps/docs/content/troubleshooting` and use TOML frontmatter — follow - `_template.mdx` in that directory rather than a guide's YAML frontmatter. - Reference docs are generated from `apps/docs/spec` and library source, so - look for the spec file or repo definition instead of editing rendered output - directly. - -When guidance conflicts, follow `apps/docs/CONTRIBUTING.md`. Match literal code, -API names, UI labels, and third-party product names even when they differ from the -word list. - -## Writing workflow - -1. Identify the document type: explainer, tutorial, guide, or reference, per - `apps/docs/CONTRIBUTING.md`. A guide is a concise procedure for a targeted - task; a tutorial covers a larger goal and includes more explanatory context; - an explainer is conceptual and prose-based; reference content is factual, - like a dictionary entry. Troubleshooting entries follow their own TOML - structure rather than these four types. -2. Define the reader's goal and prerequisites before drafting. -3. Classify substantial sections as contextual, procedural, or reference content. - In a mixed page, group sections by information type so that context doesn't - interrupt the procedural path. -4. For a long or mixed page, add a short introduction that links to its major - section groups and tells readers when to use each one. Skip this navigation - when a short page is already easy to scan. -5. Connect contextual sections to their corresponding procedures when useful. - Add introductions to section groups, transitions between information types, - and outcomes after procedures. Don't link every adjacent section. -6. Use second person, present tense, short paragraphs, and ordered steps for - sequential actions. -7. Search `apps/docs/WORD_LIST.md` when introducing or reviewing technical terms, - UI actions, abbreviations, and potentially ambiguous language. -8. Keep code samples executable in their stated context and consistent with - repository formatting. Clearly mark intentionally omitted code. Use lowercase - SQL keywords. -9. Reuse repeated content through `apps/docs/content/_partials` instead of copying - it. -10. Add new guide, explainer, and tutorial pages to - `apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts`. - File placement alone doesn't add a page to navigation. Troubleshooting - entries are indexed automatically and don't need a navigation entry. -11. Use `/docs/...` paths for pages in Supabase docs and site-root paths such as - `/dashboard` for pages outside docs. Use descriptive link text and sparse - admonitions with the appropriate severity. - -## Validation - -From `apps/docs`, run: - -```bash -pnpm lint:mdx -pnpm build:guides-markdown -``` - -`pnpm lint:mdx` covers all content under `apps/docs/content`, including -troubleshooting entries. `pnpm build:guides-markdown` only applies to guides, -explainers, and tutorials. - -From the repository root, run `pnpm format` to apply Prettier to any changed -MDX (and other) files. This enforces repo-wide formatting rules, including -lowercase SQL keyword casing in code samples. - -Run broader type checking or tests when the change affects MDX components, -content listings, navigation code, or generated output. - -For a mixed page, verify that context and procedures are grouped, introductory -navigation links resolve to the intended sections, related context and procedures -are cross-referenced where useful, and transitions make the reading path clear. - -Treat lint replacements as suggestions when context matters. Rewrite the sentence -instead of applying a replacement that changes its technical meaning. - -Anchor IDs are generated from heading text at render time, and nothing in CI -checks that `#anchor` links still resolve. Before renaming, removing, or -substantially rewording a heading, run -`grep -rn "#" apps/docs/content` to find in-page and -cross-file links that target it, and update every match. If a heading needs a -stable anchor independent of its wording, pin it with a custom anchor, for -example `## Some heading [#some-heading]`. diff --git a/.claude/skills/edit-the-docs b/.claude/skills/edit-the-docs new file mode 120000 index 0000000000000..474cc6eaf3a62 --- /dev/null +++ b/.claude/skills/edit-the-docs @@ -0,0 +1 @@ +../../.agents/skills/edit-the-docs \ No newline at end of file diff --git a/.cursor/skills/edit-the-docs b/.cursor/skills/edit-the-docs new file mode 120000 index 0000000000000..474cc6eaf3a62 --- /dev/null +++ b/.cursor/skills/edit-the-docs @@ -0,0 +1 @@ +../../.agents/skills/edit-the-docs \ No newline at end of file diff --git a/apps/docs/CONTRIBUTING.md b/apps/docs/CONTRIBUTING.md index 67f870ed593c0..aaa7638984559 100644 --- a/apps/docs/CONTRIBUTING.md +++ b/apps/docs/CONTRIBUTING.md @@ -21,15 +21,16 @@ To make docs as clear as possible: ## AI agent skills for docs authoring -If you're using Claude Code or Cursor, this repo ships four skills that back the [Write the docs](../../.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md) authoring checklist. +If you're using Claude Code or Cursor, this repo ships skills that back the [Write the docs](../../.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md) authoring checklist. -Invoke a skill by name: `/write-the-docs`, `/ask-the-docs`, `/pm-the-docs`, `/review-the-docs`. +Invoke a skill by name: `/write-the-docs`, `/edit-the-docs`, `/ask-the-docs`, `/pm-the-docs`, `/review-the-docs`. | Skill | Checklist stage | Use for | | --- | --- | --- | | [`pm-the-docs`](../../.agents/skills/pm-the-docs/SKILL.md) | Frame / Shape | Audience, product-stage, and cross-cutting scope calls | | [`ask-the-docs`](../../.agents/skills/ask-the-docs/SKILL.md) | Frame / Shape | `apps/docs` architecture, IA placement, and where content lives | | [`write-the-docs`](../../.agents/skills/write-the-docs/SKILL.md) | Draft | Drafting net-new content grounded in the code | +| [`edit-the-docs`](../../.agents/skills/edit-the-docs/SKILL.md) | Edit | Restructure and improve existing pages | | [`review-the-docs`](../../.agents/skills/review-the-docs/SKILL.md) | Self-review / PR review | Checking a draft and PR triage/verification | The canonical files live in `.agents/skills/`, with Git symlinks in `.claude/skills/` and `.cursor/skills/`. From ef09af21f09a5bf2e7972888c4326c9a7c18c79b Mon Sep 17 00:00:00 2001 From: Nik Richers Date: Wed, 2 Sep 2026 14:37:33 -0700 Subject: [PATCH 6/6] Add blog post: Are Supabase docs agent-friendly? (#49800) ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Adds a new `apps/www` blog post, "Are Supabase docs agent-friendly? We didn't know, so we checked," backdated to 2026-08-01 so it slots in chronologically between the existing 2026-07-31 Evals launch post and the 2026-08-05 post. The post writes up an eval-driven audit of the Row Level Security guide built on `supabase/evals`: the first eval run found the guide let agents grant the `anon` role write access to everything by default, and the fix that stuck was structural, moving test guidance next to the exact policy code a reader (human or agent) would copy. ## What is the current behavior? No blog post exists yet for this project. Miranda Limonczenko and Nik Richers also don't have author entries in `apps/www/lib/authors.json`. ## What is the new behavior? - New post at `apps/www/_blog/2026-08-01-are-supabase-docs-agent-friendly.mdx` - New author entries for `miranda_limonczenko` and `nik_richers` in `apps/www/lib/authors.json` - Demo video embedded via YouTube (`youtube-nocookie.com/embed`), matching the pattern used by other recent posts - New image assets under `apps/www/public/images/blog/are-supabase-docs-agent-friendly/`: the eval pass/fail chart (`eval-chart.png`) and the `og.png`/`thumb.png` hero images (cropped/resized to the standard 2400x1260 format) Check the preview: [Are Supabase docs agent-friendly? We didn't know, so we checked](https://zone-www-dot-com-git-nikrichers-blog-agent-frie-514f83-supabase.vercel.app/blog/are-supabase-docs-agent-friendly) ## Remaining work before merge - [x] Marketing +1 review per the Blog Post Process (post in `#team-marketing`) ## Additional context - Branch created directly off `origin/master` (no Linear ticket associated; this is blog content, not a docs bug/feature). - Content is adapted from an internal Notion writeup, tightened for blog voice; internal Notion discussion-thread markup and an internal Linear project link were stripped since they aren't accessible to public readers. ### Test plan - [ ] `pnpm run dev:www` and confirm `/blog/are-supabase-docs-agent-friendly` renders: title, description, both author bylines/positions, backdated date, chart image, video embed, og:image meta tag - [ ] Confirm `/blog` index card shows the new post with the thumb image - [ ] Confirm `/blog/authors/miranda_limonczenko` and `/blog/authors/nik_richers` render Verified locally (2026-09-01): all of the above pass. ## Summary by CodeRabbit - **New Content** - Added a blog post evaluating Supabase documentation with AI coding agents, highlighting lessons for clearer, more effective guides. - Added two contributors to the author directory. --------- Co-authored-by: Nik Richers Co-authored-by: Claude Sonnet 5 --- ...08-01-are-supabase-docs-agent-friendly.mdx | 106 ++++++++++++++++++ apps/www/lib/authors.json | 16 +++ .../eval-chart.png | Bin 0 -> 78991 bytes .../are-supabase-docs-agent-friendly/og.png | Bin 0 -> 1163770 bytes .../thumb.png | Bin 0 -> 1163770 bytes 5 files changed, 122 insertions(+) create mode 100644 apps/www/_blog/2026-08-01-are-supabase-docs-agent-friendly.mdx create mode 100644 apps/www/public/images/blog/are-supabase-docs-agent-friendly/eval-chart.png create mode 100644 apps/www/public/images/blog/are-supabase-docs-agent-friendly/og.png create mode 100644 apps/www/public/images/blog/are-supabase-docs-agent-friendly/thumb.png diff --git a/apps/www/_blog/2026-08-01-are-supabase-docs-agent-friendly.mdx b/apps/www/_blog/2026-08-01-are-supabase-docs-agent-friendly.mdx new file mode 100644 index 0000000000000..2154b39669d3a --- /dev/null +++ b/apps/www/_blog/2026-08-01-are-supabase-docs-agent-friendly.mdx @@ -0,0 +1,106 @@ +--- +title: "Are Supabase docs agent-friendly? We didn't know, so we checked" +description: 'We built an eval for our Row Level Security guide, found agents were granted risky default database access, and fixed the docs until the eval passed.' +author: miranda_limonczenko,nik_richers +date: '2026-08-01' +categories: + - product +tags: + - ai + - evals + - security +imgSocial: 'are-supabase-docs-agent-friendly/og.png' +imgThumb: 'are-supabase-docs-agent-friendly/thumb.png' +toc_depth: 2 +--- + +Our data proves it: people aren't reading our docs. They're pointing a coding agent at them instead. + +Someone opens Claude Code or Cursor, says "here, set this up", and the agent does the rest. A human can usually spot what isn't right: a missing flag, a step buried in a dashboard widget. An agent treads along, unaware. + +Are our Supabase docs agent-friendly? Can an agent finish these tasks? Until recently, the answer was "we don't know." That's why we kicked off a project with the goal of measuring our Supabase documentation. We run agents against Supabase docs, find friction in our pages, and iterate toward guides that stand alone and work for agents and humans alike. + +
+