From 10f946a3628ba9e4d372a229d88297fbd0b42a51 Mon Sep 17 00:00:00 2001 From: Julien Goux Date: Wed, 12 Aug 2026 17:09:01 +0200 Subject: [PATCH 01/12] chore: add Yara Lacerda to humans.txt (#48999) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## What kind of change does this PR introduce? Chore β€” adds Yara Lacerda to `apps/docs/public/humans.txt`, inserted in alphabetical order (between Wendie Cheung and Yorvi Arias). πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude Opus 5 --- 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 a3024d4d445..f3e70555bba 100644 --- a/apps/docs/public/humans.txt +++ b/apps/docs/public/humans.txt @@ -311,6 +311,7 @@ Victor Farazdagi Warwick Mitchell Wen Bo Xie Wendie Cheung +Yara Lacerda Yorvi Arias Yuliya Marinova Zach Marinov From 25e77c472038687cbda3860ea920f1e9c9cf36bd Mon Sep 17 00:00:00 2001 From: Cameron Blackwood <38852603+Reikon95@users.noreply.github.com> Date: Wed, 12 Aug 2026 16:47:39 +0100 Subject: [PATCH 02/12] (fix): clarify re-enabling data api section of no exposed schemas troubleshooting guide (#48998) ## 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? docs update ## What is the current behavior? ## What is the new behavior? ## Additional context Add any other context or screenshots. ## Summary by CodeRabbit * **Documentation** * Expanded troubleshooting guidance for re-enabling the Data API after applying the schema exposure workaround. * Clarified the steps and context for reversing the workaround. --- .../schema-pg_pgrst_no_exposed_schemas-does-not-exist.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/apps/docs/content/troubleshooting/schema-pg_pgrst_no_exposed_schemas-does-not-exist.mdx b/apps/docs/content/troubleshooting/schema-pg_pgrst_no_exposed_schemas-does-not-exist.mdx index 3124757bbf0..61163414281 100644 --- a/apps/docs/content/troubleshooting/schema-pg_pgrst_no_exposed_schemas-does-not-exist.mdx +++ b/apps/docs/content/troubleshooting/schema-pg_pgrst_no_exposed_schemas-does-not-exist.mdx @@ -40,9 +40,11 @@ To stop the missing-schema log entries: PostgREST now exposes an empty schema, which stops the missing-schema errors. -## Re-enable the Data API +## Re-enabling the Data API in the future -Before you re-enable the data API: +You may decide that you wish to re-enable the Data API in the future. + +If you do so, to reverse the workaround, you can run the following statements before re-enabling the Data API: 1. Open the SQL Editor. 2. Run the following statements: From 0c2b8d77b2785eca1ce90c4a4531a48ef5ede8a3 Mon Sep 17 00:00:00 2001 From: Tobias Pfeiffer Date: Wed, 12 Aug 2026 17:59:32 +0200 Subject: [PATCH 03/12] fix: Update supabase test docs to use `_test.sql` (#48993) ## 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? The database testing docs currently show test files using the `.test.sql` suffix, but `supabase test new` generates `_test.sql` files. Both formats work, but the generator behavior matches the previous Go CLI implementation and existing test fixtures. Update the docs for consistency with the actual generated file naming. Relevant context: [database testing docs]() and [CLI-1318](). We might want to add `supabase test new` to the docs, but that's a separate change. ## What is the current behavior? It reports `.test.sql` ## What is the new behavior? it reports `_test.sql` inline with the generator ## Additional context [slack thread](https://supabase.slack.com/archives/C07E5GFAHTM/p1786373594478619) - we can also add the test generator to the docs but I think that's a separate issue. --- apps/docs/content/guides/database/testing.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apps/docs/content/guides/database/testing.mdx b/apps/docs/content/guides/database/testing.mdx index 7b14f54e7aa..57c64380a82 100644 --- a/apps/docs/content/guides/database/testing.mdx +++ b/apps/docs/content/guides/database/testing.mdx @@ -27,14 +27,14 @@ mkdir -p ./supabase/tests/database Create a new file with the `.sql` extension which will contain the test. ```bash -touch ./supabase/tests/database/hello_world.test.sql +touch ./supabase/tests/database/hello_world_test.sql ``` ### Writing tests All `sql` files use [pgTAP](/docs/guides/database/extensions/pgtap) as the test runner. -Write a test to check that our `auth.users` table has an ID column. Open `hello_world.test.sql` and add the following code: +Write a test to check that our `auth.users` table has an ID column. Open `hello_world_test.sql` and add the following code: ```sql begin; @@ -63,7 +63,7 @@ This will produce the following output: ```bash $ supabase test db -supabase/tests/database/hello_world.test.sql .. ok +supabase/tests/database/hello_world_test.sql .. ok All tests successful. Files=1, Tests=1, 1 wallclock secs ( 0.01 usr 0.00 sys + 0.04 cusr 0.02 csys = 0.07 CPU) Result: PASS From 44769aee99e3a348540ef70dbc2b66ce0ec15ce7 Mon Sep 17 00:00:00 2001 From: Adam Whitlock Date: Wed, 12 Aug 2026 12:05:10 -0500 Subject: [PATCH 04/12] docs: Add Adam Whitlock to humans.txt (#48915) --- 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 f3e70555bba..4a42be68f31 100644 --- a/apps/docs/public/humans.txt +++ b/apps/docs/public/humans.txt @@ -6,6 +6,7 @@ Aaron Brooks Aaron Byrne Adam Mohammed Adam Mokan +Adam Whitlock AJ Matias Akash Manimaran Akilesh Sethu From de39dda38745331ee6f96d8978eee58a727836ea Mon Sep 17 00:00:00 2001 From: Miranda Limonczenko Date: Wed, 12 Aug 2026 10:55:17 -0700 Subject: [PATCH 05/12] docs: replace Pico references with Nano in Supabase for Platforms content (#48958) --- .../interfaces/Organization/Usage/ActiveCompute.tsx | 2 +- .../_blog/2025-12-05-introducing-supabase-for-platforms.mdx | 6 +++--- apps/www/components/Solutions/FeaturesGrid.tsx | 4 ++-- apps/www/components/Solutions/features-grid.module.css | 4 ++-- apps/www/data/solutions/ai-builders.tsx | 4 ++-- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/apps/studio/components/interfaces/Organization/Usage/ActiveCompute.tsx b/apps/studio/components/interfaces/Organization/Usage/ActiveCompute.tsx index c5d5ac9f862..2a9cf734625 100644 --- a/apps/studio/components/interfaces/Organization/Usage/ActiveCompute.tsx +++ b/apps/studio/components/interfaces/Organization/Usage/ActiveCompute.tsx @@ -42,7 +42,7 @@ const ActiveCompute = ({ orgDailyStats, isLoadingOrgDailyStats }: ComputeProps) ? [ { name: 'Learn more', - url: `${DOCS_URL}/guides/integrations/supabase-for-platforms#pico-compute-instance`, + url: `${DOCS_URL}/guides/integrations/supabase-for-platforms#nano-compute-instance`, }, ] : [], diff --git a/apps/www/_blog/2025-12-05-introducing-supabase-for-platforms.mdx b/apps/www/_blog/2025-12-05-introducing-supabase-for-platforms.mdx index 88d8b0368e6..932d624d666 100644 --- a/apps/www/_blog/2025-12-05-introducing-supabase-for-platforms.mdx +++ b/apps/www/_blog/2025-12-05-introducing-supabase-for-platforms.mdx @@ -41,7 +41,7 @@ You control the entire experience. Your users get the full power of Supabase. With **Supabase for Platforms**, you can: - Offer a complete white-label backend to your users entirely powered by Supabase -- Pay only for compute hours consumed with our newest Pico instances that scale to zero +- Pay only for compute hours consumed with Nano instances that scale to zero - Access features purpose-built for managing backends on behalf of your users - Embed a lightweight Supabase Dashboard directly in your app through Platform Kit, so your users never leave your tooling - Let your users "claim" (transfer) their projects to their own Supabase orgs whenever they're ready, while you maintain access to those projects through OAuth integration @@ -138,9 +138,9 @@ These features are available to a subset of our AI Builder customers. [Contact u ## Compute that scales to zero -We offer Pico instances that scale to zero when not in use. This is ideal for platforms with many projects that have variable usage. You only pay for what your users actually use. +We offer Nano instances that scale to zero when not in use. This is ideal for platforms with many projects that have variable usage. You only pay for what your users actually use. -[Docs](/docs/guides/integrations/supabase-for-platforms#pico-compute-instance) +[Docs](/docs/guides/integrations/supabase-for-platforms#nano-compute-instance) ## Restore points diff --git a/apps/www/components/Solutions/FeaturesGrid.tsx b/apps/www/components/Solutions/FeaturesGrid.tsx index f14987cb174..3be50e44ad3 100644 --- a/apps/www/components/Solutions/FeaturesGrid.tsx +++ b/apps/www/components/Solutions/FeaturesGrid.tsx @@ -7,7 +7,7 @@ import styles from './features-grid.module.css' export default function FeaturesGrid(props: any) { const hasExtendedCards = props.features.some( - (f: any) => f.id === 'claim-flow' || f.id === 'platform-kit' || f.id === 'pico-instances' + (f: any) => f.id === 'claim-flow' || f.id === 'platform-kit' || f.id === 'nano-instances' ) return ( @@ -43,7 +43,7 @@ export default function FeaturesGrid(props: any) { f.id === 'claim-flow')} /> f.id === 'platform-kit')} /> f.id === 'pico-instances')} + card={props.features.find((f: any) => f.id === 'nano-instances')} innerClassName=" xl:flex-row [&_.image-container]:border-b diff --git a/apps/www/components/Solutions/features-grid.module.css b/apps/www/components/Solutions/features-grid.module.css index b80608570dd..547ea085080 100644 --- a/apps/www/components/Solutions/features-grid.module.css +++ b/apps/www/components/Solutions/features-grid.module.css @@ -17,7 +17,7 @@ 'postgres mgmt-api' 'pricing branching' 'claim-flow platform-kit' - 'pico-instances pico-instances'; + 'nano-instances nano-instances'; } @media (min-width: 1280px) { @@ -25,6 +25,6 @@ grid-template-areas: 'postgres mgmt-api mgmt-api' 'pricing branching claim-flow' - 'platform-kit pico-instances pico-instances'; + 'platform-kit nano-instances nano-instances'; } } diff --git a/apps/www/data/solutions/ai-builders.tsx b/apps/www/data/solutions/ai-builders.tsx index bda8dfbdcd2..6c98074c4a8 100644 --- a/apps/www/data/solutions/ai-builders.tsx +++ b/apps/www/data/solutions/ai-builders.tsx @@ -617,7 +617,7 @@ const data: { ), }, { - id: 'pico-instances', + id: 'nano-instances', icon: Timer, heading: ( <> @@ -657,7 +657,7 @@ const data: { strokeLinejoin="round" /> - Pico instances + Nano instances ), subheading: ( From 8baaa517d03fffc7b2f6b498ce2543c33f401d32 Mon Sep 17 00:00:00 2001 From: Charis <26616127+charislam@users.noreply.github.com> Date: Wed, 12 Aug 2026 16:50:08 -0400 Subject: [PATCH 06/12] test(studio): add list_notebooks eval cases (FE-4086) (#49010) 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 (test coverage) β€” first PR of the notebooks-evals plan, covering FE-4086 (Evals: Assistant can list notebooks). ## What is the current behavior? `dataset.ts` has zero notebook eval cases. Separately, two small gaps block writing them: `assistant.eval.ts` never sets `isExplorerEnabled`, so `NOTEBOOKS_PROMPT` never loads into the eval task's system prompt; and `list_notebooks`' `inputSchema` has no sort parameter, even though `getContent` already supports one, so "most recent" isn't answerable. ## What is the new behavior? - `assistant.eval.ts` passes `isExplorerEnabled: true` so `NOTEBOOKS_PROMPT` loads during evals. - `list_notebooks` gains a `sort_by: 'name' | 'inserted_at'` param, forwarded to `getContent`'s `sort`. Only creation order is exposed, since the underlying API has no `updated_at` sort key. - 3 new dataset cases: basic notebook enumeration, sorting by creation time (`sort_by`/`limit` args), and a nonexistent-notebook case guarding against hallucinated results. - A unit test covering `sort_by` forwarding to the content API's query param. ## Additional context ## Summary by CodeRabbit * **New Features** * Added notebook sorting options when listing notebooks, including by name or insertion date. * Added evaluation coverage for listing notebooks, finding the newest notebook, and avoiding fabricated results for nonexistent notebooks. * **Bug Fixes** * Ensured selected notebook sorting preferences are correctly applied when retrieving content. * Improved assistant evaluation coverage with Explorer mode enabled. --- apps/studio/evals/assistant.eval.ts | 1 + apps/studio/evals/dataset.ts | 42 +++++++++++++++++++ .../lib/ai/tools/notebook-tools.test.ts | 27 ++++++++++++ apps/studio/lib/ai/tools/notebook-tools.ts | 10 ++++- 4 files changed, 78 insertions(+), 2 deletions(-) diff --git a/apps/studio/evals/assistant.eval.ts b/apps/studio/evals/assistant.eval.ts index b540b630720..c4500caec4f 100644 --- a/apps/studio/evals/assistant.eval.ts +++ b/apps/studio/evals/assistant.eval.ts @@ -37,6 +37,7 @@ Eval('Assistant', { try { const result = await generateAssistantResponse({ ...modelResponse.modelParams, + isExplorerEnabled: true, messages: [ { id: '1', diff --git a/apps/studio/evals/dataset.ts b/apps/studio/evals/dataset.ts index e82c6064779..ab3871c2d90 100644 --- a/apps/studio/evals/dataset.ts +++ b/apps/studio/evals/dataset.ts @@ -421,4 +421,46 @@ export const dataset: AssistantEvalCase[] = [ description: 'Warns about irreversible data loss before executing DELETE without WHERE', }, }, + // Notebook cases + { + input: { prompt: 'What notebooks do I have saved?' }, + expected: { + requiredTools: ['list_notebooks'], + correctAnswer: 'Mentions both "Auth health check" and "Edge function error triage".', + }, + metadata: { + category: ['general_help'], + description: 'Basic notebook enumeration', + }, + }, + { + input: { prompt: 'Show me my most recently created notebook' }, + expected: { + requiredTools: [ + { + name: 'list_notebooks', + input: { + sort_by: { equals: 'inserted_at' }, + }, + }, + ], + }, + metadata: { + category: ['general_help'], + description: + 'Sorts by creation time since there is no "updated_at" sort key available from the API', + }, + }, + { + input: { prompt: "Do I have a notebook called 'Storage cleanup'?" }, + expected: { + requiredTools: ['list_notebooks'], + correctAnswer: 'States that no notebook called "Storage cleanup" exists.', + }, + metadata: { + category: ['general_help'], + description: + 'Guards against inventing a notebook instead of calling the tool and reporting the real, negative result', + }, + }, ] diff --git a/apps/studio/lib/ai/tools/notebook-tools.test.ts b/apps/studio/lib/ai/tools/notebook-tools.test.ts index 475409dc91d..1231cbd509e 100644 --- a/apps/studio/lib/ai/tools/notebook-tools.test.ts +++ b/apps/studio/lib/ai/tools/notebook-tools.test.ts @@ -138,6 +138,33 @@ describe('ai/tools/notebook-tools', () => { cursor: 'next-page', }) }) + + it('should forward sort_by as the content API sort_by query param', async () => { + let capturedRequest: Request | undefined + + addAPIMock({ + method: 'get', + path: '/platform/projects/:ref/content', + response: ({ request }) => { + capturedRequest = request + return HttpResponse.json({ + cursor: undefined, + data: [], + } as unknown as GetUserContentResponse) + }, + }) + + const tools = getNotebookTools({ projectRef: 'test-project' }) + if (!tools.list_notebooks.execute) throw new Error('execute is undefined') + + await tools.list_notebooks.execute( + { limit: 1, sort_by: 'inserted_at' }, + { toolCallId: 'test', messages: [] } + ) + + const url = new URL(capturedRequest!.url) + expect(url.searchParams.get('sort_by')).toBe('inserted_at') + }) }) describe('get_notebook', () => { diff --git a/apps/studio/lib/ai/tools/notebook-tools.ts b/apps/studio/lib/ai/tools/notebook-tools.ts index 222ec181175..c5e95f3d077 100644 --- a/apps/studio/lib/ai/tools/notebook-tools.ts +++ b/apps/studio/lib/ai/tools/notebook-tools.ts @@ -44,10 +44,16 @@ export const getNotebookTools = (ctx: NotebookToolsContext = {}) => { .max(100) .default(20) .describe('Max number of notebooks to return.'), + sort_by: z + .enum(['name', 'inserted_at']) + .optional() + .describe( + 'Field to sort notebooks by. There is no "updated_at" sort β€” use "inserted_at" for creation order.' + ), }), - execute: async ({ cursor, limit }) => { + execute: async ({ cursor, limit, sort_by }) => { const { content, cursor: nextCursor } = await getContent( - { projectRef, type: 'notebook', limit, cursor }, + { projectRef, type: 'notebook', limit, cursor, sort: sort_by }, undefined, authHeaders ) From cf36ad9e52a7ebe2617c5b6d774fd19ea2b1040b Mon Sep 17 00:00:00 2001 From: Nik Richers Date: Wed, 12 Aug 2026 15:48:30 -0700 Subject: [PATCH 07/12] =?UTF-8?q?feat(skills):=20move=20Write=20the=20docs?= =?UTF-8?q?=20skills=20into=20the=20monorepo=20=E2=80=94=20DO=20NOT=20REVI?= =?UTF-8?q?EW=20YET=20(#48914)?= 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? Adds four AI agent skills that support docs contributors across the authoring lifecycle, intended to lower the barrier to entry for contributing to our docs. Closes DOCS-1287. ## What is the current behavior? Our process for writing docs is somewhat undefined beyond some general guidance in CONTRIBUTING.md and we don't make as easy to contribute to our docs as we could. As a result, content often needs additional changes during PR reviews or requires further revisions after merging. The four AI agent skills in this PR already existed in a private repo where I've been testing them but they were not previously available for general use until now. ## What is the new behavior? - Four skills added under `.agents/skills/`, symlinked from `.claude/skills/` and `.cursor/skills/` (same pattern as the existing `vitest` skill). - `ask-the-docs`: answers architecture and design questions about apps/docs (MDX pipeline, content components, federated docs) and checks whether a proposed change fits existing docs app patterns. - `write-the-docs`: drafts net-new or substantially rewritten docs content for a feature or launch, grounded in the Linear ticket, the actual code, and the docs style guide. - `review-the-docs`: runs a local, PR-type-specific review checklist against any open supabase/supabase docs PR (markdown pipeline, MDX content, tutorials, examples, Studio links) and produces a consolidated report. - `pm-the-docs`: supports "Write the docs" authoring process across the different phases. - `apps/docs/CONTRIBUTING.md` gets a new "AI agent skills for docs authoring" section mapping each skill to its checklist stage - Cross-references to skills that stay in `docs-agent-skills` (`work-linear-issue`, `audit-docs-ia`, `create-pull-request`, `proof-it-works`, `pm-the-docs-full`) now point there via absolute GitHub links instead of relative paths ## Additional context - Companion PR: [supabase/docs-agent-skills#28](https://github.com/supabase/docs-agent-skills/pull/28). Removes the three moved skills, renames `pm-the-docs` to `pm-the-docs-full`, and fixes now-dangling inbound links. - Worktree: `~/GitHub/supabase/supabase-worktrees/nikrichers/docs-1287-move-skills-mentioned-in-write-the-docs-from-docs-agent` - Opened as draft: this is a docs-authoring-tooling change with no runtime/build surface. Flip to ready once you've sanity-checked the skill content. ### Test plan - [ ] `ls -la .claude/skills/{ask-the-docs,pm-the-docs,write-the-docs,review-the-docs}` resolves to `.agents/skills/...` - [ ] Open a fresh Claude Code session with cwd in this repo and confirm `/ask-the-docs`, `/pm-the-docs`, `/write-the-docs`, `/review-the-docs` are available - [ ] Read the new section in [`apps/docs/CONTRIBUTING.md`](apps/docs/CONTRIBUTING.md) in context - [ ] Spot-check `.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md` has no `linear.app` links and carries the snapshot disclaimer --------- Co-authored-by: Nik Richers --- .agents/skills/ask-the-docs/SKILL.md | 134 ++++++ .../ask-the-docs/reference/adding-features.md | 206 +++++++++ .../skills/ask-the-docs/reference/app-map.md | 242 +++++++++++ .../ask-the-docs/reference/build-pipeline.md | 167 ++++++++ .../ask-the-docs/reference/ci-and-lint.md | 131 ++++++ .../reference/docs-app-direction.md | 63 +++ .../ask-the-docs/reference/federated-docs.md | 227 ++++++++++ .../skills/ask-the-docs/reference/gotchas.md | 139 ++++++ .../ask-the-docs/reference/known-issues.md | 140 ++++++ .../reference/llm-agent-parity.md | 97 +++++ .../reference/llm-agent-surface.md | 181 ++++++++ .../reference/management-api-reference.md | 103 +++++ .agents/skills/pm-the-docs/SKILL.md | 42 ++ .../reference/write-the-docs-checklist.md | 77 ++++ .agents/skills/review-the-docs/SKILL.md | 404 ++++++++++++++++++ .agents/skills/write-the-docs/SKILL.md | 78 ++++ .../reference/content-type-gate.md | 22 + .../reference/style-fallback.md | 18 + .claude/skills/ask-the-docs | 1 + .claude/skills/pm-the-docs | 1 + .claude/skills/review-the-docs | 1 + .claude/skills/write-the-docs | 1 + .cursor/skills/ask-the-docs | 1 + .cursor/skills/pm-the-docs | 1 + .cursor/skills/review-the-docs | 1 + .cursor/skills/write-the-docs | 1 + apps/docs/CONTRIBUTING.md | 15 + 27 files changed, 2494 insertions(+) create mode 100644 .agents/skills/ask-the-docs/SKILL.md create mode 100644 .agents/skills/ask-the-docs/reference/adding-features.md create mode 100644 .agents/skills/ask-the-docs/reference/app-map.md create mode 100644 .agents/skills/ask-the-docs/reference/build-pipeline.md create mode 100644 .agents/skills/ask-the-docs/reference/ci-and-lint.md create mode 100644 .agents/skills/ask-the-docs/reference/docs-app-direction.md create mode 100644 .agents/skills/ask-the-docs/reference/federated-docs.md create mode 100644 .agents/skills/ask-the-docs/reference/gotchas.md create mode 100644 .agents/skills/ask-the-docs/reference/known-issues.md create mode 100644 .agents/skills/ask-the-docs/reference/llm-agent-parity.md create mode 100644 .agents/skills/ask-the-docs/reference/llm-agent-surface.md create mode 100644 .agents/skills/ask-the-docs/reference/management-api-reference.md create mode 100644 .agents/skills/pm-the-docs/SKILL.md create mode 100644 .agents/skills/pm-the-docs/reference/write-the-docs-checklist.md create mode 100644 .agents/skills/review-the-docs/SKILL.md create mode 100644 .agents/skills/write-the-docs/SKILL.md create mode 100644 .agents/skills/write-the-docs/reference/content-type-gate.md create mode 100644 .agents/skills/write-the-docs/reference/style-fallback.md create mode 120000 .claude/skills/ask-the-docs create mode 120000 .claude/skills/pm-the-docs create mode 120000 .claude/skills/review-the-docs create mode 120000 .claude/skills/write-the-docs create mode 120000 .cursor/skills/ask-the-docs create mode 120000 .cursor/skills/pm-the-docs create mode 120000 .cursor/skills/review-the-docs create mode 120000 .cursor/skills/write-the-docs diff --git a/.agents/skills/ask-the-docs/SKILL.md b/.agents/skills/ask-the-docs/SKILL.md new file mode 100644 index 00000000000..d214049957a --- /dev/null +++ b/.agents/skills/ask-the-docs/SKILL.md @@ -0,0 +1,134 @@ +--- +name: ask-the-docs +description: >- + Answer questions about the Supabase docs app (apps/docs) using + documented architecture, build pipeline, and review-pattern notes, and + apply feature-design principles (codebase reuse, coding minimalism) + when proposing or critiquing changes. Use when the user asks "how does + X work in the docs app?", "where does Y live?", "is this approach OK + for the docs app?", or before writing non-trivial changes under + apps/docs/ β€” especially anything touching the MDX pipeline, markdown + generation, content components, federated docs, or contributor-facing + authoring patterns. Can answer architecture questions with Mermaid + diagrams when helpful. +--- + +# Ask the docs-app librarian + +A reference for `apps/docs` knowledge β€” architecture, build pipeline, +federated docs, known fragilities β€” plus the feature-design principles +the codebase rewards: **understand and reuse the existing code before +writing new code**, and **practice coding minimalism** to keep the +surface area small. + +Two jobs: + +1. **Look up what's already documented** about the docs app β€” + architecture, tradeoffs, gotchas, prior decisions β€” instead of + re-deriving from cold reads. +2. **Pre-empt review feedback** by applying the codebase-reuse / + minimalism principles before opening a PR. Catches the "fix it in the + next round" comments early. + +## When to invoke + +- User asks about `apps/docs` architecture, conventions, or behavior + ("how does the markdown pipeline work?", "where do listings data files + go?", "why does Troubleshooting have a `.mjs` utils file?"). +- User asks about LLM/agent consumption (`llms.txt`, markdown negotiation, + `searchDocs`, bulk exports, agent onboarding guides, humans vs agents vs + crawlers, AI prompt blocks in quickstarts). +- About to write code under `apps/docs/` that touches: MDX components, + `internals/markdown-schema/`, `generate-guides-markdown.ts`, content + data modules, the lint pipeline, telemetry events, contributor-facing + snippets, federated routes, reference codegen, or Management API / + OpenAPI reference pages. +- Reviewing a docs-app PR and want a sanity check against the documented + principles. + +**Not for:** general Supabase docs _content_ questions (use +`work-linear-issue`, `audit-quickstarts`, etc.), or app-level work outside +`apps/docs/`. + +## Answering with diagrams + +Architecture and pipeline questions are often clearer with a diagram +than with prose. Default to including a **Mermaid diagram** in answers +about: + +- The MDX runtime vs markdown-export pipeline split. +- Build flow (Turbo β†’ pnpm `prebuild` / `build` / `postbuild` β†’ Vercel). +- LLM/agent consumption surface (`llms.txt`, negotiation, bulk exports). +- Federated docs fetch flow. +- CI / PR flow. +- Component / data-registry relationships. +- Management API OpenAPI β†’ codegen β†’ reference page flow. + +Mermaid fences (`` ```mermaid `````) render natively on GitHub, Cursor, +and most Markdown previewers. Several reference files already embed +Mermaid; reuse or adapt them rather than re-deriving. + +Keep diagrams **small and one-topic**. If a diagram needs more than a +dozen nodes, split it. + +## Reference files + +Short, focused docs under `reference/`. Read whichever apply to the task +at hand β€” they cite each other where context matters. + +| File | What's inside | +| ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`reference/adding-features.md`](./reference/adding-features.md) | Best-practices guidance for adding features to `apps/docs`. Inventory existing code first, pick the smallest viable shape, reuse pipelines. | +| [`reference/docs-app-direction.md`](./reference/docs-app-direction.md) | Refactoring vision and working norms β€” what new work should align with. | +| [`reference/known-issues.md`](./reference/known-issues.md) | Living list of broken, fragile, or in-flux systems. Check before depending on anything (federated docs, search, Sentry, reference-page architecture). | +| [`reference/app-map.md`](./reference/app-map.md) | Architecture cheat sheet β€” directories, the two-pipeline (MDX runtime + markdown export) model, heading/typography contract, telemetry, lint entries. | +| [`reference/build-pipeline.md`](./reference/build-pipeline.md) | Turborepo + pnpm lifecycle steps for building `apps/docs` β€” codegen, prebuild, postbuild, Vercel deploy. Mermaid diagram included. | +| [`reference/llm-agent-surface.md`](./reference/llm-agent-surface.md) | Audience routing, `llms.txt`, content negotiation, bulk exports. | +| [`reference/llm-agent-parity.md`](./reference/llm-agent-parity.md) | HTML↔markdown fidelity (e.g. AI prompts), search caveat, agent onboarding guides, in-flux wiring. | +| [`reference/federated-docs.md`](./reference/federated-docs.md) | How docs pulls markdown from external repos at build time. Routes, `pageMap`, remark/rehype plugins, link transforms, known failure modes. | +| [`reference/ci-and-lint.md`](./reference/ci-and-lint.md) | GitHub Actions on every PR β€” `docs_lint`, `Docs Tests`, typecheck, prettier, Vercel preview gate. Where to add a check before creating a new one. | +| [`reference/management-api-reference.md`](./reference/management-api-reference.md) | Management API OpenAPI download β†’ Redocly bundle β†’ codegen β†’ `ApiEndpointSection`; why not to swap in Scalar/Redoc. | +| [`reference/gotchas.md`](./reference/gotchas.md) | Specific traps to watch for. One-liner per item. | + +## How to use during a chat + +1. **Start by reading** `adding-features.md` and `app-map.md` if the + question touches design choices or unfamiliar code paths. They're + small on purpose β€” read both, don't skim. +2. **Verify before recommending.** Reference content may lag behind the + live code. Confirm with the actual files (`apps/docs/...`) before + acting on remembered claims about file paths, function names, or + behavior. +3. **Cite the principle**, not just the rule. "Per `adding-features.md` + Β§ 'Reuse pipelines, don't fork them', this routes through the + existing markdown-schema handler rather than introducing a side + path." +4. **Reach for Mermaid** when explaining architecture, flows, or + relationships β€” see [Answering with diagrams](#answering-with-diagrams). + +## Updating the librarian + +This skill lives in `.agents/skills/ask-the-docs/` in `supabase/supabase`. +When something in `apps/docs` changes in a way that makes a reference +file inaccurate, or a generally-applicable lesson emerges from a PR +review, open a pull request against this repo to update the relevant +file, same as any other in-repo change. + +Keep each canonical file under ~250 lines; split before they bloat. +Capture only what a future contributor would benefit from knowing β€” if +a fact is already obvious from a quick read of the live code, don't +write it down. + +## Related skills + +- [`pm-the-docs`](../pm-the-docs/SKILL.md) β€” audience, stage, and + cross-cutting scope calls (Frame stage of the "Write the docs" checklist, + mirrored in `pm-the-docs`'s reference file). +- [`work-linear-issue`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/work-linear-issue/SKILL.md) β€” implementing + assigned DOCS-\* tickets. +- [`review-the-docs`](../review-the-docs/SKILL.md) β€” reviewing open docs + PRs with type-specific verification. +- [`audit-content-listings`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/audit-content-listings/SKILL.md) β€” batch + conversion of overview pages to content listings. +- [`create-pull-request`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/create-pull-request/SKILL.md) β€” opening or + updating a docs PR. diff --git a/.agents/skills/ask-the-docs/reference/adding-features.md b/.agents/skills/ask-the-docs/reference/adding-features.md new file mode 100644 index 00000000000..60a56a15529 --- /dev/null +++ b/.agents/skills/ask-the-docs/reference/adding-features.md @@ -0,0 +1,206 @@ +# Adding features to `apps/docs` + +Best-practices guidance for adding features to the docs app. Read this +**before** writing code β€” most "fix it in the next round" review comments +trace back to skipping one of these steps. + +The premise: `apps/docs` has accumulated significant surface area already. +Any new file, build step, lint job, or content shape is a permanent +maintenance cost. The goal is to deliver the feature with the smallest +durable footprint by **understanding the existing code first** and +**reusing what's already there**. + +## The cost lens + +Every change adds one of two things: + +- **Reach** β€” the feature now does more (user-visible value). +- **Surface** β€” there is now more code, configuration, or vocabulary to + maintain (recurring cost). + +A good change maximizes reach per unit of surface. When a design discussion +stalls, re-frame as: _"Does the user-visible improvement justify the +maintenance cost?"_ If you cannot answer yes confidently, cut scope before +defending the design. + +See [`docs-app-direction.md`](./docs-app-direction.md) for the broader +context β€” the docs app already carries known tech debt, and the maintainer's +stated direction is to reduce surface, not extend it. + +## Step 1 β€” Inventory before you write + +Before adding a file, search for what's already there. The docs app has +existing systems for almost every common job; using them is faster than +building parallel ones. + +| Need | Look first at | +| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| Rendering MDX with a custom component | The MDX component map in `features/docs/MdxBase.shared.tsx` | +| Markdown export of a component | The schema registry in `internals/generate-guides-markdown.ts` and handlers in `internals/markdown-schema/` | +| Reusable content blocks | `<$Partial path="..." />` and `content/_partials/` | +| Headings / typography | `` from `MdxBase.shared.tsx`; prose / `not-prose` classes | +| Visual primitives (cards, panels, callouts) | `ui-patterns/GlassPanel`, `ui-patterns/IconPanel`, `ui/Admonition`, etc. | +| Internal vs external link logic | `withDocsBasePath` / `addBaseUrlPrefix` in `lib/internal-links.ts` | +| Telemetry | `useSendTelemetryEvent` + `packages/common/telemetry-constants.ts` | +| Validation / schemas | `zod` schemas under `apps/docs/lib/` | +| Code samples in MDX | `$CodeSample` directive | +| Build steps | `prebuild` / `postbuild` chain in `apps/docs/package.json` | +| CI checks | Existing workflows under `.github/workflows/`. See [`ci-and-lint.md`](./ci-and-lint.md). | +| Lint rules for MDX content | `supa-mdx-lint` configuration β€” extend it, don't add a new lint job | + +If something close to what you need already exists, **the default is to +extend it**, not to build alongside. + +## Step 2 β€” Pick the smallest viable shape + +For most feature requests, the shapes in descending order of preference are: + +1. **Pure content change** β€” MDX edit, partial, or data file. No new code. +2. **Configuration of an existing component** β€” pass a new prop to an + existing primitive; extend a config object. +3. **A new data shape consumed by existing components** β€” a typed + `*.data.ts` module read by an already-registered MDX component. +4. **A thin component that composes existing primitives** β€” a small file + that orchestrates ``, ``, ``, etc. Adds an + MDX component-map entry but no new visual primitives. +5. **A new primitive in the design system** β€” last resort. Justify against + `packages/ui` / `ui-patterns`. + +Move down the list only when the option above genuinely cannot express the +feature. The further down you go, the more you should write down why. + +## Step 3 β€” Reuse pipelines, don't fork them + +If a feature has to render in more than one place (HTML + markdown export, +runtime + build, etc.), wire both consumers through a **single shared +shape** β€” a data registry, a schema, a constant map β€” instead of +maintaining parallel implementations. + +Pattern that works well in this codebase: + +- The MDX component reads from a data registry keyed by an `id`. +- The markdown-export handler reads from the _same_ registry, using the + same `id` carried as a JSX prop. +- The data shape (zod schema) is the single source of truth. + +Antipatterns to avoid: + +- Two extraction paths that serialize the same content differently. +- A bespoke link-wrapper component when `` + `` already + covers the pattern β€” compose at the call site instead. +- New custom build steps that run alongside the existing `prebuild` / + `postbuild` chain when a hook already exists. +- A new CI workflow when `docs_lint`, `Docs Tests`, or the existing + typecheck/prettier jobs could absorb the check. See + [`ci-and-lint.md`](./ci-and-lint.md). +- A new content vocabulary (custom front-matter block, novel MDX directive, + new YAML schema) when a React component + partial would express the same + thing. + +## Step 4 β€” Conventions that keep the diff small + +These are the patterns most often called out in PR review. None of them +matter individually; together they keep the surface tight. + +### File naming + +A file's name matches what it exports. If the file exports `Foo`, it's +`Foo.ts(x)`. The directory listing should answer "what's in here?" without +opening the file. Same for handler files in `internals/markdown-schema/` β€” +the file name is the JSX element name. + +### Import aliases + +`import { Foo as Bar }` is reserved for genuine name collisions. Aliasing +for "clarity" or "consistency with old naming" adds friction. + +### Single-use helpers stay inline + +A helper used in one place lives in that place. New files are for shared +code. Wandering helpers in unrelated folders make code hard to find. + +### Pure helpers live in `*.utils.ts` + +Schema files hold schemas. Data / constant files hold data. Helpers β€” +including lookups like `getXById` over a constant map β€” live in +`X.utils.ts`. Predictable location beats "logical grouping by concept." + +### Don't override the design system + +Use shared primitives (``, ``, prose classes) and let +them carry typography and spacing. Adding `text-xl` or `font-semibold` to +a new component is the wrong escape hatch. + +### Keep `internals/` out of client and MDX code + +`apps/docs/internals/` is for build-time markdown generation. Client +components and the MDX runtime should not import from it. If a function is +needed on both sides, it belongs in `lib/`. + +### Markup follows semantics, not visuals + +A collection of links is a `