From ef09af21f09a5bf2e7972888c4326c9a7c18c79b Mon Sep 17 00:00:00 2001 From: Nik Richers Date: Wed, 2 Sep 2026 14:37:33 -0700 Subject: [PATCH] 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 00000000000..2154b39669d --- /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. + +
+