From cf36ad9e52a7ebe2617c5b6d774fd19ea2b1040b Mon Sep 17 00:00:00 2001
From: Nik Richers <nrichers@gmail.com>
Date: Wed, 12 Aug 2026 15:48:30 -0700
Subject: [PATCH 1/3] =?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 <nik@validmind.ai>
---
 .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 0000000000000..d214049957a54
--- /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 0000000000000..60a56a1552923
--- /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                       | `<Heading>` 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 `<Link>`, `<GlassPanel>`, `<Heading>`, 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 `<Link>` + `<GlassPanel>` 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 (`<Heading>`, `<GlassPanel>`, 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 `<ul>`, regardless of whether it visually
+renders as a list or a grid. CSS handles layout; markup handles semantics.
+
+### Collapse near-duplicates with discriminator props
+
+When two components share structure and differ only in classes or markup
+details, collapse them. Extract the differences into class-name constants
+keyed by the discriminator (`type: 'grid' | 'list'`). Don't ship two
+components that are 90% identical.
+
+### Use maps / lookups over arithmetic on known sets
+
+If the input domain is `'h2' | 'h3' | 'h4'`, a `Map` (or `Record<Literal, T>`)
+keyed by those literals is clearer than slicing strings and synthesizing
+output. Exhaustiveness checking comes along for free.
+
+### Avoid render-time closure churn
+
+Hooks should return _stable_ callbacks (`useCallback`) that consumers
+invoke, not curried builders that create a new closure per item per render.
+Inline arrow functions at the call site are fine; building closures in a
+loop during render is not.
+
+### Be robust on URL / string parsing
+
+`/^https?:\/\//i` is incomplete. Protocol-relative (`//host`), `mailto:`,
+`tel:`, and bare schemes are all external. Prefer `new URL(href, base)` or
+a regex that covers `^(?:[a-z][a-z0-9+\-.]*:|\/\/)`.
+
+### Keep diffs minimal
+
+Import reordering, prettier reflows, or unrelated whitespace edits in a
+feature PR muddy the review. If a file isn't conceptually part of the
+change, revert it. Auto-formatter ran on a file you didn't touch? Reset
+it.
+
+## Step 5 — Pre-flight before opening the PR
+
+Run through this checklist before pushing:
+
+- [ ] Searched the inventory in Step 1 for existing primitives / pipelines.
+- [ ] Picked the smallest shape that delivers the feature (Step 2).
+- [ ] Renders consistently across pipelines that share content (Step 3).
+- [ ] File and export names match (Step 4 — file naming).
+- [ ] No unnecessary helpers, imports, files, or aliases.
+- [ ] Typography defers to shared primitives.
+- [ ] No `internals/` imports from client / MDX code.
+- [ ] Diff contains only changes relevant to the feature.
+- [ ] `pnpm format`, `pnpm typecheck`, and the relevant lint job pass.
+
+Replies on review threads move faster when they point to a specific commit
+("done in abc1234") than when they explain the reasoning at length.
+Expect review to come in **passes** that go progressively deeper — that is
+the path to a minimum-surface design, not nitpicking.
+
+## Related
+
+- [`docs-app-direction.md`](./docs-app-direction.md) — broader context on
+  the docs app's tech debt and refactoring direction.
+- [`app-map.md`](./app-map.md) — where each existing seam lives.
+- [`build-pipeline.md`](./build-pipeline.md) — the build steps you should
+  consider extending before adding a new one.
+- [`ci-and-lint.md`](./ci-and-lint.md) — the CI checks you should consider
+  extending before adding a new workflow.
+- [`gotchas.md`](./gotchas.md) — specific traps known to bite.
diff --git a/.agents/skills/ask-the-docs/reference/app-map.md b/.agents/skills/ask-the-docs/reference/app-map.md
new file mode 100644
index 0000000000000..c60e57aa420a2
--- /dev/null
+++ b/.agents/skills/ask-the-docs/reference/app-map.md
@@ -0,0 +1,242 @@
+# `apps/docs` architecture map
+
+What lives where, and what depends on what. **Verify against the live tree
+before acting** — paths drift. Cross-references the per-topic deep dives in
+this folder.
+
+## High-level architecture
+
+`apps/docs` is a **Next.js 15 App Router** site served at **`/docs`**
+(`basePath` in `next.config.mjs`). It combines hand-written MDX guides,
+machine-generated reference docs, troubleshooting content, federated content
+from external repos, and shared monorepo packages (`ui`, `common`,
+`ui-patterns`, etc.).
+
+```mermaid
+flowchart TB
+  subgraph routes ["app/ — Next.js routes"]
+    guides["/guides/*"]
+    reference["/reference/*"]
+    api["/api/*"]
+  end
+
+  subgraph content ["Content sources"]
+    mdx["content/guides/*.mdx"]
+    trouble["content/troubleshooting/*.mdx"]
+    spec["spec/*.yml, *.json"]
+    generated["features/docs/generated/**"]
+    refmdx["docs/ref/*.mdx"]
+    fed["External repos<br/>(federated)"]
+  end
+
+  subgraph render ["Rendering layer"]
+    features["features/docs/"]
+    components["components/"]
+    layouts["layouts/"]
+  end
+
+  guides --> mdx
+  guides --> trouble
+  guides --> fed
+  reference --> spec
+  reference --> generated
+  reference --> refmdx
+  guides --> features
+  reference --> features
+  features --> components
+  features --> layouts
+```
+
+## Top-level directory layout
+
+| Path                                   | Purpose                                                                            | Notes                                                                      |
+| -------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
+| `app/`                                 | Next.js App Router — thin route files that delegate to feature modules             | Slug-based catch-alls per section, e.g. `guides/auth/[[...slug]]/page.tsx` |
+| `apps/docs/content/guides/`            | Source MDX for `/docs/guides/...` pages                                            | One file per page; `_partials/` for shared blocks                          |
+| `apps/docs/content/_partials/`         | Reusable MDX snippets included via `<$Partial path="..." />`                       | Recursion supported                                                        |
+| `apps/docs/content/troubleshooting/`   | Troubleshooting articles                                                           | Some synced from GitHub issues via `Troubleshooting.script.mjs`            |
+| `apps/docs/components/`                | React components used inside MDX                                                   | One folder per component or component family                               |
+| `apps/docs/data/`                      | Typed data modules consumed by components                                          | `.data.ts` suffix; lookup helpers live in `.utils.ts`, not here            |
+| `apps/docs/lib/`                       | Pure library code shared across pipelines                                          | Schemas (zod), helpers (`.utils.ts`), tests                                |
+| `apps/docs/features/docs/`             | Page-level skeletons and the MDX renderer (`MdxBase`)                              | Shared `<Heading>` lives in `MdxBase.shared.tsx`                           |
+| `apps/docs/features/`                  | Domain logic — docs rendering, auth, search/command menu, telemetry, app providers | `app.providers.tsx` wires React Query, theme, dev toolbar, command menu    |
+| `apps/docs/spec/`                      | Source-of-truth specs for reference generation                                     | OpenAPI, SDK YAML, CLI config                                              |
+| `apps/docs/generator/`                 | Codegen templates for reference docs                                               |                                                                            |
+| `apps/docs/resources/`                 | Data loaders (guide, reference, search, errors)                                    |                                                                            |
+| `apps/docs/internals/`                 | Build-time markdown generation                                                     | **Do not import from runtime/client code**                                 |
+| `apps/docs/internals/markdown-schema/` | Per-component handlers: JSX → markdown string                                      | File name matches the component name                                       |
+| `apps/docs/public/markdown/guides/`    | Generated `.md` output; served via `/docs/guides/<path>.md` or `Accept: text/markdown` | Built by `generate-guides-markdown.ts`; see [`llm-agent-surface.md`](./llm-agent-surface.md) |
+| `apps/docs/public/markdown/reference/` | Generated reference `.md` files                                                    | Built by `generate-reference-markdown.ts`                                  |
+| `apps/docs/middleware.ts`              | Content negotiation for guides; bot rewrite for reference deep links               | Uses `packages/common/markdown-negotiation.ts`                             |
+| `apps/docs/app/api/guides-md/`         | Serves pre-generated guide markdown to agents                                      | Rewritten from `/docs/guides/<path>.md`                                    |
+| `apps/docs/examples/`                  | Copied from repo root `examples/` at build time                                    | `codegen:examples`                                                         |
+| `apps/docs/scripts/`                   | Build-time scripts (sitemap, markdown export, embeddings)                          |                                                                            |
+
+Published guide sections: `ai`, `api`, `auth`, `cron`, `database`, `deployment`,
+`functions`, `getting-started`, `integrations`, `local-development`, `platform`,
+`queues`, `realtime`, `resources`, `security`, `self-hosting`, `storage`,
+`telemetry`. Each has its own `layout.tsx` for sidebar navigation.
+
+## Content types
+
+| Type                   | Location                                              | Notes                                                                                                                                                                       |
+| ---------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Guides / tutorials** | `content/guides/`                                     | Hand-written MDX; goal-oriented                                                                                                                                             |
+| **Troubleshooting**    | `content/troubleshooting/`                            | Partly synced from GitHub issues                                                                                                                                            |
+| **Reference**          | Generated from `spec/` → `features/docs/generated/**` | Spec-driven (OpenAPI, SDKSpec, ConfigSpec, CLISpec). Reference pages do **not** use the standard MDX path — see [`docs-app-direction.md`](./docs-app-direction.md) for why. Management API OpenAPI path: [`management-api-reference.md`](./management-api-reference.md). |
+| **Federated**          | External repos at build time                          | Pulled via GitHub App. See [`federated-docs.md`](./federated-docs.md)                                                                                                       |
+
+## Routing model
+
+Routes stay **thin**; rendering lives in **`features/docs/`**.
+
+```tsx
+// app/guides/getting-started/[[...slug]]/page.tsx
+const slug = ['getting-started', ...(params.slug ?? [])]
+const data = await getGuidesMarkdown(slug)
+return <GuideTemplate {...data!} />
+```
+
+`getGuidesMarkdown()` (in `features/docs/GuidesMdx.utils.tsx`) loads the file,
+validates frontmatter, checks navigation enablement, and returns data for
+`GuideTemplate`.
+
+`slug` is just the Next.js param name. `[[...slug]]` is an optional catch-all
+(can match zero or more segments); `[...slug]` is required. The page handler
+prepends the section name and joins segments to find content on disk.
+
+For reference, `parseReferencePath(slug)` in `features/docs/Reference.utils.ts`
+interprets segments like `javascript`, `v2`, `auth-signin` to pick SDK,
+version, and section.
+
+## The two pipelines (and why they share data)
+
+The same content has to render twice:
+
+1. **MDX runtime** — React components render `<MyComponent id="..." />`,
+   read data via a data registry, output HTML.
+2. **Markdown export** — `internals/markdown-schema/<MyComponent>.ts`
+   handlers convert the same JSX into plain markdown for
+   `public/markdown/guides/`.
+
+**Load-bearing rule:** both pipelines dereference the _same_ data
+registry (typically `apps/docs/data/<topic>/index.ts` exporting an
+ID-keyed map and a `getById` lookup). The component reads it; the
+handler reads it. The JSX prop is just an `id`. This keeps the two
+outputs in sync without a parallel data shape.
+
+**Reference implementation: `ContentListings`** — the ID-keyed two-pipeline
+pattern in production:
+
+| Layer | Path |
+| ----- | ---- |
+| Data registry | `apps/docs/data/content-listings/` (`.data.ts` per topic + `index.ts`) |
+| Runtime component | `apps/docs/components/ContentListings/` |
+| Markdown handler | `apps/docs/internals/markdown-schema/ContentListings.ts` |
+| MDX registration | `apps/docs/features/docs/MdxBase.shared.tsx` |
+
+MDX usage: `<ContentListings id="storage-get-started" />`. For batch
+overview-page migration, see the `audit-content-listings` skill in
+[`docs-agent-skills`](https://github.com/supabase/docs-agent-skills).
+
+When adding a new component that has a markdown representation:
+
+1. Write the React component under `apps/docs/components/`.
+2. Add a handler under `apps/docs/internals/markdown-schema/<SameName>.ts`.
+3. Register the handler in `apps/docs/internals/generate-guides-markdown.ts`
+   (the `SCHEMA` object).
+4. If a component is purely visual and should be **dropped** from markdown,
+   omit the handler — `generate-guides-markdown.ts` unwraps unknown JSX to its
+   children automatically.
+
+For the full build flow (Turbo + pnpm lifecycle), see
+[`build-pipeline.md`](./build-pipeline.md).
+
+For how agents and LLMs consume exported markdown (negotiation, bulk
+downloads, `llms.txt`), see [`llm-agent-surface.md`](./llm-agent-surface.md).
+
+## The markdown export in 30 seconds
+
+`generate-guides-markdown.ts` walks `content/guides/**/*.mdx`:
+
+1. Parse MDX → mdast (mdx + gfm extensions).
+2. Inline `<$Partial path="..." />` recursively.
+3. `addBaseUrlPrefix(tree)` — prefixes internal links with `/docs/`.
+4. `applySchema(tree, SCHEMA)` — bottom-up: serializes children first, then
+   replaces each JSX node with the result of its handler (or unwraps it).
+5. Serialize mdast back to markdown.
+6. Prepend front-matter-derived header (`# title`, subtitle, description).
+7. Write to `public/markdown/guides/<same-path>.md`.
+
+Each `SCHEMA` entry receives `{ props, children, node }` and returns the
+markdown string to substitute.
+
+## `<Heading>` and the prose typography contract
+
+- `<Heading>` from `MdxBase.shared.tsx` is the canonical heading component
+  for MDX. It handles tag-from-level mapping and anchor IDs.
+- The MDX wrapper applies prose styles to everything inside `.prose` (default
+  for guide pages). Inside `.not-prose` blocks, typography is opt-in.
+- Pattern for new components with headings: render `<Heading>` _outside_
+  `not-prose`, render the structured layout _inside_ `not-prose`. The heading
+  inherits prose styles; the layout owns its own classes.
+
+## Telemetry conventions
+
+- Event names live in `packages/common/telemetry-constants.ts` (snake*case,
+  `docs*\*` prefix for docs events).
+- Components call `useSendTelemetryEvent()` from `~/lib/telemetry`.
+- Properties: prefer flat, ID-prefixed keys. Avoid optional spread tricks
+  unless a property is genuinely optional in the schema.
+
+## Linting and verification entry points
+
+See [`ci-and-lint.md`](./ci-and-lint.md) for the full CI surface. Local
+commands:
+
+| Tool                                        | Where       | What it catches                                           |
+| ------------------------------------------- | ----------- | --------------------------------------------------------- |
+| `pnpm test:local <path>` (from `apps/docs`) | per-test    | Vitest suite for `lib/` and `data/` schemas               |
+| `pnpm format`                               | repo root   | Prettier — run before opening a PR                        |
+| `pnpm lint --filter=docs`                   | repo root   | ESLint over `apps/docs`                                   |
+| `pnpm typecheck`                            | repo root   | TS across packages                                        |
+| `pnpm build --filter=docs`                  | repo root   | Includes markdown generation; failures here block release |
+| `pnpm run supa-mdx-lint`                    | `apps/docs` | MDX content lint                                          |
+
+Before adding a custom lint job, check whether the existing one can absorb
+the check (see [`adding-features.md`](./adding-features.md) "Reuse
+pipelines").
+
+## Providers (`features/app.providers.tsx`)
+
+Wraps the app with:
+
+- `QueryClientProvider` (React Query)
+- `FeatureFlagProvider`, `ThemeProvider` from `common`
+- `TooltipProvider` from `ui`
+- `DevToolbar` from `dev-tools`
+- `DocsCommandProvider` / `DocsCommandMenu`
+- `SiteLayout` from `layouts/`
+
+## Troubleshooting page subtree
+
+- `features/docs/Troubleshooting.page.tsx` — entry-level page renderer.
+- `features/docs/Troubleshooting.utils.ts` — TS utils.
+- `features/docs/Troubleshooting.utils.common.mjs` — `.mjs` because it's
+  consumed by both the Next.js build _and_ a Node sync script with import
+  resolution quirks. **Don't convert to `.ts`** without checking the sync
+  script.
+- Topics enum in `TroubleshootingSchema` (the `topics` field) is the source
+  of truth for product tag values.
+
+## Known integrations
+
+- **Studio** (`apps/studio`) links to docs URLs — check link consistency when
+  changing URL shapes.
+- **www** (`apps/www`) sometimes embeds docs sections.
+- **PostHog** receives `docs_*` events for analytics.
+- **`docs-agent-skills`** repo (https://github.com/supabase/docs-agent-skills)
+  holds batch audit/conversion skills that drive multi-PR docs migrations.
+- **Federated upstream repos** — see [`federated-docs.md`](./federated-docs.md)
+  for the full list (pg_graphql, vecs, wrappers, terraform-provider, setup-cli,
+  splinter, agent-skills).
diff --git a/.agents/skills/ask-the-docs/reference/build-pipeline.md b/.agents/skills/ask-the-docs/reference/build-pipeline.md
new file mode 100644
index 0000000000000..74f0318bb3fc8
--- /dev/null
+++ b/.agents/skills/ask-the-docs/reference/build-pipeline.md
@@ -0,0 +1,167 @@
+# Docs build pipeline
+
+How `apps/docs` is built through Turborepo and pnpm lifecycle hooks.
+Verify against the current `apps/docs/turbo.jsonc` and
+`apps/docs/package.json` if behavior surprises you.
+
+## Build flow
+
+```mermaid
+flowchart TB
+  subgraph turbo["Turborepo — apps/docs/turbo.jsonc"]
+    direction TB
+    WP["^build — workspace deps<br/>(common, ui, config, icons, …)"]
+    CE["codegen:examples<br/>copy ../../examples → apps/docs/examples"]
+    CR["codegen:references<br/>→ features/docs/generated/**"]
+    WP --> DOC["docs#build"]
+    CE --> DOC
+    CR --> DOC
+  end
+
+  subgraph npm["pnpm — apps/docs/package.json"]
+    direction TB
+    PRE["prebuild"]
+    NB["build — next build"]
+    POST["postbuild"]
+    PRE --> NB --> POST
+  end
+
+  DOC --> PRE
+
+  subgraph pre["prebuild steps"]
+    direction LR
+    GQL["codegen:graphql"]
+    REF["codegen:references"]
+    EX["codegen:examples"]
+    GM["build:markdown<br/>(guides + reference)"]
+    GZ["build:gz-archive"]
+  end
+
+  PRE --> GQL
+  PRE --> REF
+  PRE --> EX
+  PRE --> GM
+  PRE --> GZ
+
+  subgraph post["postbuild steps"]
+    direction LR
+    SM["build:sitemap"]
+    CDN["upload-static-assets.sh<br/>(R2, production-style deploys)"]
+  end
+
+  POST --> SM
+  POST --> CDN
+```
+
+## Commands
+
+From the repo root:
+
+- **Full graph:** `pnpm build` → `turbo run build` (builds every package/app
+  in dependency order).
+- **Docs only:** `pnpm build:docs` → `turbo run build --filter=docs`.
+
+```json
+"build:docs": "turbo run build --filter=docs"
+```
+
+## What Turbo does
+
+Root `turbo.jsonc` defines `build` with `dependsOn: ["^build"]`, so
+**workspace dependencies** of `docs` (e.g. `common`, `ui`, `config`, …) are
+built before `docs`.
+
+`apps/docs/turbo.jsonc` **extends** that and tightens the docs task:
+
+- **`build` also depends on** `codegen:examples` and `codegen:references`
+  (with explicit inputs/outputs so Turbo can cache them).
+- It lists **env vars** that affect caching for the docs app.
+- **`codegen:examples`** copies `../../examples` into `apps/docs/examples`;
+  **`codegen:references`** writes under `features/docs/generated/**`.
+
+Pipeline Turbo orchestrates for docs: **dependency packages → example /
+reference codegen → Next build**.
+
+## What the `docs` package runs (pnpm lifecycle)
+
+```json
+"prebuild": "pnpm run codegen:graphql && pnpm run codegen:references && pnpm run codegen:examples && pnpm run build:markdown && pnpm run build:gz-archive",
+"postbuild": "pnpm run build:sitemap && ./../../scripts/upload-static-assets.sh"
+```
+
+1. **`prebuild`** — GraphQL codegen, reference codegen, copy examples,
+   generate guides + reference markdown (`build:markdown`), then tarball
+   (`build:gz-archive`).
+2. **`build`** — `next build`.
+3. **`postbuild`** — sitemap, then `upload-static-assets.sh` (R2 CDN
+   upload on production-style deploys).
+
+Same monorepo pattern as Studio / www (pnpm workspaces + Turbo `^build`),
+with **extra codegen** wired as Turbo tasks and npm `pre`/`post` hooks around
+`next build`.
+
+## Codegen scripts
+
+- **`codegen:graphql`** — generates GraphQL types from schema.
+- **`codegen:examples`** — copies `examples/` from monorepo root into
+  `apps/docs/examples` for `$CodeSample` directive resolution.
+- **`codegen:references:legacy`** — `features/docs/Reference.generated.script.ts`
+  (includes Management API: merge OpenAPI v1+v2 → `api.latest.*` JSON).
+  Spec download/bundle lives in `apps/docs/spec/Makefile` (Redocly);
+  see [`management-api-reference.md`](./management-api-reference.md).
+- **`codegen:references:new`** — `scripts/build-reference-content.ts` (from
+  TSDoc JSON under `spec/reference/`). Output lands in
+  `features/docs/generated/**`.
+- **`build:guides-markdown`** — runs `internals/generate-guides-markdown.ts`
+  over `content/guides/**/*.mdx`. Produces `public/markdown/guides/**.md`.
+- **`build:reference-markdown`** — runs `internals/generate-reference-markdown.ts`.
+  Produces `public/markdown/reference/**.md`.
+- **`build:markdown`** — shorthand for guides + reference markdown.
+- **`build:gz-archive`** — runs `internals/generate-gz-archive.ts`.
+  Produces `public/docs.tar.gz` (tarball of all `public/markdown/`).
+
+For how agents consume these outputs, see
+[`llm-agent-surface.md`](./llm-agent-surface.md).
+
+## Deploy vs CI
+
+- **Production build** for the site is **Vercel**; `apps/docs/vercel.json`
+  sets `buildCommand` to `pnpm build` (the docs app's script chain above).
+- **GitHub Actions** mostly run **tests** (`test:docs` → Turbo), **lint**,
+  **sync** jobs, and **smoke** tests — not a separate full production build
+  graph in the way Turbo does locally. See [`ci-and-lint.md`](./ci-and-lint.md).
+
+## Local development
+
+From `apps/docs`:
+
+```bash
+pnpm dev   # http://localhost:3001/docs
+```
+
+- **`predev`** runs GraphQL and reference codegen plus example copy.
+- A concurrent watcher syncs troubleshooting content
+  (`dev:watch:troubleshooting`).
+- Community contributors: set `NEXT_PUBLIC_IS_PLATFORM=false` in `.env`.
+- Supabase employees: `pnpm run dev:secrets:pull` for internal env vars
+  (AWS profile + `scripts/getSecrets.js`).
+- In dev mode, the app **only builds routes upon request** rather than
+  pre-rendering — preview and production environments statically generate
+  routes during build for speed.
+
+## Why this shape matters for changes
+
+- Adding a new build step? See [`adding-features.md`](./adding-features.md)
+  "Reuse pipelines, don't fork them" and check if `prebuild` or `postbuild`
+  already has a hook that fits.
+- New env var? Add it to `apps/docs/turbo.jsonc`'s `env` so Turbo doesn't
+  cache stale.
+- Touching the markdown export? Read [`app-map.md`](./app-map.md) "The two
+  pipelines" first — runtime and export share data, not code paths.
+
+## Related
+
+- [`app-map.md`](./app-map.md) — directory layout and runtime / export split.
+- [`ci-and-lint.md`](./ci-and-lint.md) — GitHub Actions workflow surface.
+- [`federated-docs.md`](./federated-docs.md) — external content fetched
+  during build.
diff --git a/.agents/skills/ask-the-docs/reference/ci-and-lint.md b/.agents/skills/ask-the-docs/reference/ci-and-lint.md
new file mode 100644
index 0000000000000..fc8c039f48ec0
--- /dev/null
+++ b/.agents/skills/ask-the-docs/reference/ci-and-lint.md
@@ -0,0 +1,131 @@
+# Docs CI and lint surface
+
+GitHub Actions running on every PR touching `supabase/supabase`, plus
+the deploy path. Confirm against the current `.github/workflows/` if
+behavior surprises you.
+
+Before adding a new lint job or CI check, **scan this list first** — see
+[`adding-features.md`](./adding-features.md) "Reuse pipelines, don't fork them."
+
+## PR flow
+
+```
+PR opened / updated
+    │
+    ├── docs_lint                  (MDX/content linting; required)
+    ├── docs_lint_comment_external (posts results as PR comments for external PRs)
+    ├── Docs Tests                 (pnpm test:docs on .ts* file changes)
+    ├── TypeScript & Lint          (tsc + eslint)
+    ├── Prettier                   (format check)
+    ├── reviewdog                  (inline annotations)
+    ├── Validate pull request      (PR metadata)
+    └── Authorize Vercel Deploys → Vercel builds preview deploy → Preview on CDN
+
+Merge to master
+    └── Vercel → next build (with prebuild markdown generation) → deploy
+```
+
+## On every pull request
+
+Workflows run in parallel against any PR touching the repo:
+
+### 1. `docs_lint`
+
+Primary docs-specific CI check. MDX/content linting for the docs. **Required
+check before merging.** Backed by `supa-mdx-lint`.
+
+### 2. Docs Tests (`docs-tests.yml`)
+
+Triggered on PRs to master when files matching `apps/docs/**/*.ts*` or
+`apps/docs/spec/**/*.json` change. Runs on a Blacksmith 4-vCPU Ubuntu runner
+with concurrency controls to cancel stale builds.
+
+- Sparse checkout of `apps/docs`, `examples`, `packages`, `supabase`, and
+  `patches`.
+- Install pnpm (pinned hash).
+- Set up Node.js from `.nvmrc`.
+- `pnpm install --frozen-lockfile`.
+- Run `pnpm run test:docs` (with dummy GitHub OAuth env vars to prevent local
+  Supabase startup errors).
+
+### 3. TypeScript & Lint (`typecheck.yml`)
+
+TypeScript type checking and ESLint across the monorepo.
+
+### 4. Prettier (`prettier.yml`)
+
+Format checking across the whole repo including `apps/docs`.
+
+### 5. `docs_lint_comment_external`
+
+Companion to `docs_lint` that posts lint results as PR comments for external
+contributors.
+
+### 6. Authorize Vercel Deploys
+
+Gates Vercel preview deployment on a GitHub-side check first. Prevents
+arbitrary forks from triggering Vercel builds.
+
+### 7. reviewdog
+
+Inline code review annotations via reviewdog.
+
+### 8. Validate pull request
+
+PR metadata validation (title format, labels, etc.).
+
+## Deployment (on merge to master)
+
+Production deployment is handled by **Vercel**. Supabase employees branch the
+repo directly rather than fork it, so CI checks auto-run and Vercel deploys
+can be authorized without the external PR security gate.
+
+Key deployment detail: the project generates markdown files for each page
+under `/docs/guides/..` as a **prebuild task**. This lets Vercel bundle these
+files with middleware and functions at build time.
+
+The **Authorize Vercel Deploys** workflow is the glue between GitHub Actions
+and Vercel: it runs first to approve the deploy, then Vercel picks it up and
+builds/deploys the Next.js site to their CDN.
+
+## Notable design choices
+
+- **Sparse checkout** keeps CI fast by only pulling the relevant workspace
+  packages.
+- **Blacksmith runners** are used instead of standard GitHub-hosted runners
+  for speed.
+- All workflow steps use **pinned action hashes** rather than floating tags
+  for supply chain security.
+
+## Where to add a new check
+
+Before adding a new GitHub Actions workflow:
+
+1. **Can `docs_lint` absorb it?** — most MDX/content checks belong inside
+   `supa-mdx-lint` configuration, not as a new workflow.
+2. **Can `Docs Tests` absorb it?** — TypeScript / vitest checks for new
+   functionality fit here.
+3. **Is it cross-cutting?** — typecheck, prettier, and reviewdog already
+   cover the cross-cutting cases.
+4. **Last resort** — a new workflow file. Use a Blacksmith runner, sparse
+   checkout, pinned action hashes, and a concurrency group. Add a clear
+   trigger filter so it doesn't run on unrelated PRs.
+
+## Vale and prose linting (future)
+
+Chris Ward's wishlist (source: hiring conversations, not yet in the repo):
+
+- Vale linting MCP server.
+- Vale extension for VS Code.
+- More async automation that doesn't block PR merges.
+
+If adding prose linting, prefer async (commenting) checks over blocking ones
+to keep merge cadence high.
+
+## Related
+
+- [`app-map.md`](./app-map.md) — what `pnpm test:docs` actually runs.
+- [`build-pipeline.md`](./build-pipeline.md) — `prebuild` step that ships
+  markdown to Vercel.
+- [`adding-features.md`](./adding-features.md) — reuse existing pipelines
+  before adding new ones.
diff --git a/.agents/skills/ask-the-docs/reference/docs-app-direction.md b/.agents/skills/ask-the-docs/reference/docs-app-direction.md
new file mode 100644
index 0000000000000..29bcad18d880b
--- /dev/null
+++ b/.agents/skills/ask-the-docs/reference/docs-app-direction.md
@@ -0,0 +1,63 @@
+# `apps/docs` direction and vision
+
+Where the docs app is heading and what new work should align with. For
+the _current_ state of broken or fragile systems, see
+[`known-issues.md`](./known-issues.md). For feature-design best
+practices, see [`adding-features.md`](./adding-features.md).
+
+## Refactoring vision
+
+- **Docs-only project.** The long-term goal is for the documentation
+  project to handle _only_ documentation. Other functionalities (specific
+  APIs, etc.) should migrate to sub-projects.
+- **Ongoing surface reduction.** A substantial portion of legacy
+  critical code has already been refactored, and remaining work
+  continues to reduce surface area rather than add to it.
+- **One-to-one markdown fidelity.** Improvements to
+  `generate-guides-markdown` aim for exact correspondence between the
+  rendered guide and the LLM-oriented markdown export. New components
+  that render in MDX should serialize to markdown with the same
+  semantics.
+
+## Working norms
+
+- **Work inside `apps/docs/`, not the repo root.** Simpler terminal
+  commands, clearer debugging scope. Most docs commands assume you've
+  `cd`'d into the app.
+- **AI use is encouraged** for explaining complex or legacy sections of
+  the codebase. Considered effective for mechanical, non-creative tasks.
+- **Historical context.** For decisions older than the current
+  refactoring wave, check with longer-tenured maintainers — most
+  current code has clearer provenance.
+
+## What this means for new work
+
+When proposing changes that touch `apps/docs`:
+
+1. **Reuse existing seams before adding new ones.** Markdown export, MDX
+   pipeline, lint, codegen, and federated fetch are all places where
+   new surface area gets challenged. See
+   [`adding-features.md`](./adding-features.md) "Inventory before you
+   write."
+2. **Keep markdown fidelity in mind.** Anything that changes how a
+   guide renders should also change how it serializes to markdown — or
+   have a clear reason it doesn't.
+3. **Don't build against the broken parts.** See
+   [`known-issues.md`](./known-issues.md). Search, Sentry
+   instrumentation, and federated link handling are all in flux. New
+   features should not depend on their current shape.
+4. **Don't extend tech debt.** Component scatter, parallel pipelines,
+   and bespoke render paths are existing problems — don't add to them.
+5. **Refactor only what the feature requires.** Bundling unrelated
+   cleanup into a feature PR muddies review and gets cut anyway. Open a
+   separate refactor PR if the cleanup matters.
+
+## Related
+
+- [`adding-features.md`](./adding-features.md) — feature-design best
+  practices.
+- [`known-issues.md`](./known-issues.md) — what's currently broken or
+  fragile.
+- [`app-map.md`](./app-map.md) — where the existing seams are now.
+- [`federated-docs.md`](./federated-docs.md) — mechanics of one of the
+  known liabilities.
diff --git a/.agents/skills/ask-the-docs/reference/federated-docs.md b/.agents/skills/ask-the-docs/reference/federated-docs.md
new file mode 100644
index 0000000000000..07c4c993083b4
--- /dev/null
+++ b/.agents/skills/ask-the-docs/reference/federated-docs.md
@@ -0,0 +1,227 @@
+# Federated docs
+
+`apps/docs` can pull **markdown (and other files) from external GitHub repos**
+at **build or request time**, then render them inside the normal docs shell.
+Content lives in ecosystem repos (client libs, extensions, tooling) without
+duplicating into `apps/docs/content`.
+
+Documented upstream in root **`DEVELOPERS.md`** → "Federated docs."
+
+> **The maintainers treat this as a known liability.** See
+> [`docs-app-direction.md`](./docs-app-direction.md) for the full context
+> (lack of editorial oversight, brittle builds, quality drift). Treat
+> federated content as a liability when reviewing or debugging.
+
+## Why federate
+
+- **No duplication** — e.g. `supabase/vecs` docs stay in the vecs repo.
+- **Automatic sync** — fetched during the docs build (or on cached
+  revalidation), not hand-copied.
+- **Native feel** — same `GuideTemplate`, nav, typography, and search surface
+  as first-party guides.
+- **Flexible placement** — can embed external docs at nearly any path under
+  `/guides/`.
+
+Trade-off: **integration is manual and brittle**. Each federated section
+needs its own route file, `pageMap`, link transform, and often custom remark
+plugins.
+
+## Build-time flow
+
+```mermaid
+flowchart TB
+  subgraph upstream ["External repos"]
+    PG["supabase/pg_graphql"]
+    VECS["supabase/vecs"]
+    WRAP["supabase/wrappers"]
+    TF["supabase/terraform-provider-supabase"]
+    CI["supabase/setup-cli"]
+    SPL["supabase/splinter"]
+    SKILLS["supabase/agent-skills"]
+  end
+
+  subgraph fetch ["Fetch layer — lib/octokit.ts"]
+    APP["GitHub App auth<br/>DOCS_GITHUB_APP_*"]
+    API["getGitHubFileContents()"]
+    CACHE["fetchRevalidatePerDay<br/>(Next.js cache, retry up to 5x)"]
+    APP --> API --> CACHE
+  end
+
+  subgraph route ["Per-section route — app/guides/.../page.tsx"]
+    MAP["pageMap<br/>(slug → remoteFile + meta)"]
+    GET["getContent()"]
+    MAP --> GET
+  end
+
+  subgraph transform ["MDX pipeline"]
+    RM["remark plugins<br/>Admonition, Tabs, removeTitle"]
+    RH["rehype plugins<br/>linkTransform + rehypeSlug"]
+    RM --> RH
+  end
+
+  subgraph render ["Render"]
+    GT["GuideTemplate / GuideMdxContent"]
+    OUT["/docs/guides/..."]
+    GT --> OUT
+  end
+
+  upstream --> API
+  GET --> RM
+  RH --> GT
+```
+
+### Step-by-step
+
+1. **Route file** defines `org`, `repo`, `branch` (or tag), `docsDir`, and a
+   **`pageMap`** — each entry maps a local slug to a remote markdown file
+   plus page metadata.
+2. **`getGitHubFileContents()`** fetches file content via a **GitHub App**
+   (`DOCS_GITHUB_APP_ID`, `DOCS_GITHUB_APP_INSTALLATION_ID`,
+   `DOCS_GITHUB_APP_PRIVATE_KEY`). Uses **once-per-day revalidation** by
+   default (`fetchRevalidatePerDay`).
+3. Raw markdown is passed through **remark/rehype plugins** to bridge dialect
+   gaps.
+4. **`linkTransform` + custom `urlTransform`** rewrite relative links from
+   the source repo into `/docs/guides/...` paths (or fall back to the upstream
+   docs site / GitHub).
+5. Output is rendered with **`GuideTemplate`** so federated pages look like
+   native guides. **Edit on GitHub** links point at the source repo file.
+
+> Note: `DEVELOPERS.md` still mentions `getStaticProps()` — the current App
+> Router implementation uses async server components + `generateStaticParams`
+> instead, but the idea is the same: fetch remote markdown at build time.
+
+## Federated sources (inventory)
+
+| Local path                               | Source repo                            | Ref / branch                   | Pattern                                           |
+| ---------------------------------------- | -------------------------------------- | ------------------------------ | ------------------------------------------------- |
+| `/guides/graphql/*`                      | `supabase/pg_graphql`                  | `master`                       | Fully federated; `pageMap` per page               |
+| `/guides/ai/python/*`                    | `supabase/vecs`                        | `main`                         | Fully federated                                   |
+| `/guides/deployment/ci/*`                | `supabase/setup-cli`                   | `gh-pages`                     | Fully federated                                   |
+| `/guides/deployment/terraform/*`         | `supabase/terraform-provider-supabase` | branch in `terraformConstants` | Federated prose pages                             |
+| `/guides/deployment/terraform/reference` | same                                   | same                           | Federated **JSON schema** (not MDX)               |
+| `/guides/database/extensions/wrappers/*` | `supabase/wrappers`                    | **release tag** `docs_v*.*.*`  | **Hybrid** — local MDX + federated catalog        |
+| `/guides/database/database-advisors`     | `supabase/splinter`                    | `main`                         | **Dynamic listing** — all `docs/*.md` files       |
+| AI Skills index                          | `supabase/agent-skills`                | `main`                         | Lists `skills/*/SKILL.md` at runtime              |
+| `$CodeSample` directive                  | various                                | commit SHA only                | Snippets via `getGitHubFileContentsImmutableOnly` |
+
+### Related patterns (not quite "federated docs")
+
+| Pattern              | Source                    | Mechanism                                                                                              |
+| -------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------ |
+| **AI prompts**       | `examples/prompts/*.md`   | Copied into `apps/docs/examples` at build (`codegen:examples`); nav injected in getting-started layout |
+| **Integrations nav** | Supabase `partners` table | `integrations/layout.tsx` fetches approved partners (external URLs)                                    |
+| **Reference docs**   | `apps/docs/spec/`         | Generated locally, not fetched from GitHub — see [`build-pipeline.md`](./build-pipeline.md)            |
+
+## How to spot a federated page in the repo
+
+- Look for a **dynamic route** (`[[...slug]]/page.tsx`, `[slug]/page.tsx`)
+  instead of content-only routing.
+- Search for **`// We fetch these docs at build time from an external repo`**
+  or **`getGitHubFileContents`**.
+- Check for a local **`pageMap`** array mapping slugs to `remoteFile` names.
+- GraphQL is listed in `PUBLISHED_SECTIONS` comments as _"technically
+  published, but completely federated"_ — no MDX under `content/guides/graphql/`.
+
+Canonical starter example:
+`apps/docs/app/guides/ai/python/[slug]/page.tsx` (vecs).
+
+## Link and markdown transforms
+
+External repos often use **MkDocs Material** or similar dialects. Supabase
+docs do not understand those natively.
+
+### Remark plugins (`lib/mdx/plugins/`)
+
+| Plugin              | Purpose                                         |
+| ------------------- | ----------------------------------------------- |
+| `remarkAdmonition`  | `!!! note` / `!!! warning` → `<Admonition>`     |
+| `remarkTabs`        | pymdownx tab syntax → Supabase tabs             |
+| `remarkRemoveTitle` | Strip duplicate H1 when title comes from `meta` |
+
+New upstream syntax may need a **new remark plugin** — called out explicitly
+in `DEVELOPERS.md`.
+
+### Link transform (`rehypeLinkTransform.ts`)
+
+Each federated route defines its own **`urlTransform`** function:
+
+- **Relative `.md` links** → mapped via `pageMap` to `/docs/guides/...` (or
+  section-relative slug).
+- **Unmapped relative links** → fall back to upstream site (e.g.
+  `https://supabase.github.io/vecs/...`) or raw GitHub blob URL (terraform).
+- **Absolute URLs** → passed through unchanged.
+
+Wrappers additionally rewrites **`../assets/`** image paths to
+`raw.githubusercontent.com` URLs tied to the docs release tag.
+
+## Known failure modes
+
+Federated docs are a frequent source of **content quality issues** and
+**broken links**.
+
+### Broken or wrong links
+
+- **`pageMap` is manual** — upstream rename/remove → broken link until
+  someone updates the route file in `supabase/supabase`.
+- **`urlTransform` is per-section** — logic differs between graphql, vecs,
+  terraform, wrappers, etc.
+- **Unmapped pages fall back externally** — users leave the docs site or land
+  on a GitHub pages URL that may not match the embedded path structure.
+- **Absolute links in upstream** pass through untouched — may point at old
+  domains or anchors that moved.
+- **Cross-links between federated and native guides** are not automatic;
+  upstream authors don't know Supabase URL shapes.
+
+### Content quality
+
+- **No editorial gate in `apps/docs/content`** — upstream tone, structure,
+  and freshness vary.
+- **Dialect mismatches** — unsupported mkdocs extensions render as raw text
+  or fail MDX compile until a plugin is added.
+- **Duplicate titles** — mitigated by `removeTitle` / `removeRedundantH1`,
+  but layout can still look off.
+- **Stale content** — daily GitHub cache means upstream fixes may not appear
+  until revalidation; wrappers pin to **release tags** which can lag further.
+
+### Operational / dev failures
+
+- **GitHub App credentials required** — without `DOCS_GITHUB_APP_*`, fetches
+  fail. `$CodeSample` with external repos shows a **local dev warning** and
+  does not render real content.
+- **GitHub API timeouts** — `database-advisors` catches fetch errors and
+  shows a degraded view with a link to GitHub; build may still succeed with
+  partial content.
+- **Wrappers tag resolution** — `getLatestDocsTag()` queries `docs_v*.*.*`
+  tags; if tagging breaks, federated wrapper pages throw at build time.
+- **Dev mode gaps** — some federated routes return **empty
+  `generateStaticParams` in dev** (`IS_DEV`), so pages may 404 locally unless
+  you hit them via production build or adjust params.
+
+### Navigation drift
+
+- Sidebar entries for federated sections are often **hard-coded** in
+  `NavigationMenu.constants.ts` plus optional **`additionalNavItems`**
+  injection (prompts, integrations).
+- New upstream pages do not appear in nav until a maintainer adds them to
+  `pageMap` **and** navigation config.
+
+## When to federate vs copy into `content/`
+
+Federate when:
+
+- The canonical docs live in another repo and change frequently.
+- Maintainers of that repo own the content lifecycle.
+
+Prefer `content/guides/` when:
+
+- Editorial control, consistent voice, and link stability matter.
+- Content is tightly coupled to Supabase product UI and cross-links.
+
+## Related
+
+- [`app-map.md`](./app-map.md) — runtime + markdown export pipelines.
+- [`build-pipeline.md`](./build-pipeline.md) — where federated fetches sit
+  in the overall build.
+- [`docs-app-direction.md`](./docs-app-direction.md) — context on the
+  federated-docs liability and long-term direction.
diff --git a/.agents/skills/ask-the-docs/reference/gotchas.md b/.agents/skills/ask-the-docs/reference/gotchas.md
new file mode 100644
index 0000000000000..f842cd9735cd3
--- /dev/null
+++ b/.agents/skills/ask-the-docs/reference/gotchas.md
@@ -0,0 +1,139 @@
+# `apps/docs` gotchas
+
+Specific traps to watch for. One-liner per item.
+
+## Markdown pipeline
+
+- **JSX with no schema handler is unwrapped, not dropped.** Children pass
+  through as plain markdown. If a component should disappear entirely from
+  `.md` output, its handler must return `''`.
+- **Handlers run bottom-up.** Children are already-serialized markdown
+  strings by the time the parent handler sees them. Don't try to inspect
+  child JSX from a parent handler — use `node.children` only for structure
+  decisions.
+- **`mdxFlowExpression` / `mdxTextExpression` / `mdxjsEsm` are skipped.**
+  Anything wrapped in `{...}` won't appear in markdown output.
+- **`AiPrompt` prompts must be a `prompt={...}` prop, not children.** The
+  schema handler decodes the raw JS string literal from `propsFrom()`
+  (Prettier may emit single-quoted multiline forms). See
+  `internals/markdown-schema/AiPrompt.ts`.
+- **`<$Partial>` recursion is silent.** A missing or unreadable partial is
+  dropped without error. Check `partials/` paths when content seems missing
+  from generated `.md`.
+- **`$Partial` `variables` are runtime-only unless wired in markdown export.**
+  `partialsRemark` substitutes `{{ .key }}` placeholders; `inlinePartials`
+  in `generate-guides-markdown.ts` must do the same or nested partials like
+  `path="{{ .prompt }}"` fail silently (file not found).
+- **`GlassPanel` / `IconPanel` markdown handlers must include children.**
+  A handler that returns only `props.title` drops nested content. See
+  `internals/markdown-schema/Panel.ts`.
+
+## Markdown handler authoring
+
+- Handler files in `internals/markdown-schema/` must be named after the
+  component (`ContentListings.ts`, not `Listings.ts`). The registry key in
+  `generate-guides-markdown.ts` is the JSX element name.
+- Use the existing `withDocsBasePath` / `addBaseUrlPrefix` from
+  `internal-links.ts` for URL prefixing — don't roll your own.
+- If a handler needs data, the **JSX prop carries an `id`** and the handler
+  looks the data up from the same registry the runtime component uses. Don't
+  serialize data into JSX props.
+- Push a blank line right after each exported block (heading, description,
+  list). Keeps handler logic linear and avoids redundant trailing-empty-line
+  branches.
+
+## React / MDX components
+
+- `not-prose` is the canonical opt-out from the surrounding `.prose`
+  typography. Wrap structural layout in `not-prose`; keep headings outside so
+  they inherit prose styles.
+- `<Heading>` from `MdxBase.shared.tsx` is the canonical heading. Don't roll
+  your own `<h2>` / `<h3>` markup in MDX components — typography drifts.
+- `<Link>` from `next/link` works with `target="_blank"` for external
+  destinations. Don't construct `<a>` directly.
+- A `useSendTelemetryEvent()` call inside a render path returns a function;
+  don't invoke it directly inside the JSX, build a callback first.
+
+## Data modules
+
+- Shared zod schemas for MDX components should use HTML heading levels
+  (`'h2'|'h3'|'h4'`), not markdown marker strings (`'##'`). Markdown markers
+  belong only in `internals/markdown-schema/` handlers (via a `Record`/`Map`
+  lookup).
+- `getXById(id)` lookups belong in `*.utils.ts`, not in the data file or the
+  schema file. Schema files hold schemas; data files hold data; utils hold
+  functions.
+- Each `.data.ts` exports named groups; the topic `index.ts` aggregates them
+  into a `Record<id, group>` map. The aggregation file is the single source
+  of truth for "all valid IDs."
+
+## URL handling
+
+- External-link detection is **not** just `/^https?:\/\//`. Protocol-relative
+  (`//host`), `mailto:`, `tel:`, custom schemes — all external. Prefer
+  `new URL(href, base)` or a broader regex.
+- `withDocsBasePath('/guides/foo')` → `/docs/guides/foo`. Already-prefixed
+  URLs are passed through. Use it consistently in markdown output to avoid
+  broken links.
+
+## Troubleshooting subtree
+
+- `Troubleshooting.utils.common.mjs` is `.mjs` because the troubleshooting
+  sync script can't resolve `.ts` imports cleanly. Don't convert it.
+- Rebasing can resurrect a **stale** version of this file when you reset
+  unrelated changes — verify against current `master` after
+  `git checkout master -- <path>`.
+- The `topics` enum in `TroubleshootingSchema` is hand-maintained. Adding a
+  new product means updating that enum.
+
+## Build / CI
+
+- `pnpm build --filter=docs` runs markdown generation. A failure in
+  `generate-guides-markdown.ts` blocks the build — read its console output
+  rather than the cryptic CI error.
+- `pnpm format` from the repo root catches most prettier drift. Run it
+  before opening a PR; CI is unforgiving.
+- Auto-import sorting can silently shuffle imports across files you didn't
+  touch. Reset those files (`git checkout master -- <path>`) before pushing.
+
+## Federated docs
+
+See [`federated-docs.md`](./federated-docs.md) for the full surface — the
+short version:
+
+- **No GitHub App credentials in dev** = `$CodeSample` shows a warning, not
+  real content. Don't assume the page is broken.
+- **`pageMap` is manual.** Upstream renames break links until a maintainer
+  updates the route file.
+- **Wrappers pin to release tags** (`docs_v*.*.*`). If tagging breaks
+  upstream, build fails.
+- **Search and federated content interact poorly** — search infrastructure
+  is currently decoupled from the markdown generation. See
+  [`docs-app-direction.md`](./docs-app-direction.md).
+
+## Reference pages
+
+- SDK and CLI reference pages **don't go through the standard MDX path** —
+  they're too long for the AST parser in preview environments. Generated
+  from `spec/` instead, output to `features/docs/generated/**`.
+- Reference page length is a known UX/LLM problem. Long-term plan: split
+  into smaller modular pages. Management API is already one endpoint per
+  page (DOCS-1268); see [`management-api-reference.md`](./management-api-reference.md).
+- Management API Redocly bundle **omits `--dereferenced`** because of a
+  circular `$ref`. Don't "fix" that by adding `--dereferenced` without
+  checking codegen's cycle-safe `resolveRefs`.
+- Don't propose Scalar/Redoc/Elements as the Management API page UI
+  without covering markdown export, search, and `x-*` extension fields.
+
+## PR hygiene
+
+- No incidental import reorders or whitespace edits in a feature PR. Reset
+  files that are conceptually unchanged.
+- When resetting unrelated files (`git checkout master -- <path>`), verify the
+  result matches current `master` — rebases can resurrect stale file versions.
+- File names must match the primary export. Rename rather than aliasing on
+  import.
+- Single-use helpers stay in the consuming file. Don't add new files in
+  unrelated folders for one-shot utilities.
+- Two components with the same JSX shape and different classes → collapse
+  with a discriminator prop. Don't ship near-duplicates.
diff --git a/.agents/skills/ask-the-docs/reference/known-issues.md b/.agents/skills/ask-the-docs/reference/known-issues.md
new file mode 100644
index 0000000000000..45486038e5a50
--- /dev/null
+++ b/.agents/skills/ask-the-docs/reference/known-issues.md
@@ -0,0 +1,140 @@
+# `apps/docs` known issues
+
+What's currently broken, fragile, or intentionally being avoided. Read
+this before depending on a piece of infrastructure for new work — if it's
+listed here, expect it to change or fail in surprising ways.
+
+Living document — update when a new fragility shows up in a PR or
+incident.
+
+## Federated documentation pipeline
+
+**Severity:** load-bearing fragility. Affects daily builds.
+
+The docs site fetches markdown from external repos at build/request time
+(pg_graphql, vecs, wrappers, terraform-provider, setup-cli, splinter,
+agent-skills). Treat as a liability:
+
+- **Lack of oversight.** Quality control, linting, and formatting can't
+  be enforced because the source code isn't owned.
+- **Quality drift.** Inconsistent formatting, missing semicolons,
+  structural differences between federated and in-house content.
+- **Build brittleness.** Upstream fetches fail intermittently — retry
+  logic (up to 5x) is in place to mitigate. Builds can still degrade or
+  partially succeed.
+- **Manual `pageMap`.** Upstream rename/remove → broken links until a
+  maintainer updates the route file in `supabase/supabase`.
+- **Wrappers pins to release tags** (`docs_v*.*.*`). If tagging breaks
+  upstream, federated wrapper pages throw at build time.
+- **Dev mode gaps.** Some federated routes return empty
+  `generateStaticParams` in dev — pages may 404 locally unless hit via
+  production build.
+
+See [`federated-docs.md`](./federated-docs.md) for the full mechanics and
+failure modes. Implication: **don't add new federated sources** without
+strong justification; **don't extend federated patterns** to new content
+types.
+
+## Troubleshooting guides currently live in an external repo
+
+**Severity:** ongoing sync issues.
+
+This causes synchronization problems between the docs site and the source
+of truth. Proposed direction: bring them in-house and require support
+teams to contribute directly to `supabase/supabase` to ensure accuracy.
+
+## Reference pages can't go through standard MDX
+
+**Severity:** architectural constraint.
+
+SDK & CLI reference pages (e.g. JavaScript SDK, CLI) use a different
+rendering path than guides. Attempts to migrate them to MDX **failed
+because their length exceeded memory limits for the AST parser in
+preview environments.** They are generated from `spec/` instead, output
+to `features/docs/generated/**`.
+
+Implication: don't propose "unify everything under MDX" for reference
+pages without addressing the memory ceiling first.
+
+## Reference page length
+
+**Severity:** UX and LLM usability issue.
+
+Current reference pages are far too long, making them difficult for
+human users to navigate and inefficient for LLMs to process. Long-term
+goal: break them into specialized, modular pages for better readability
+and performance.
+
+Implication: new reference content should default to smaller, modular
+pages.
+
+## Search infrastructure is decoupled and considered broken
+
+**Severity:** functional, but not trustworthy for new features.
+
+Search relies on separate scripts and embeddings rather than the
+consolidated markdown files (`build:guides-markdown` output). It is
+decoupled from the main markdown-generation pipeline.
+
+Implication: **don't build new features against the current search
+infrastructure** assuming it's stable. Expect it to be reworked as part
+of the refactoring direction.
+
+## Error tracking and Sentry signal quality
+
+**Severity:** noise-to-signal issue.
+
+Sentry errors for slugs / 404s are often caused by:
+
+- Bots scanning paths.
+- Legacy URLs that no longer exist.
+- Broken inbound links from external sites.
+
+Error tracking and instrumentation are relatively new and
+underdeveloped. Implication: **don't trust noisy Sentry signals as proof
+of a real bug** without corroboration (reproduce locally, check the
+referrer, etc.).
+
+## Component dispersion
+
+**Severity:** tech debt — accumulating cost, not a runtime failure.
+
+React components for the docs app are inconsistently scattered across
+multiple folders (`components/`, `features/docs/`, `features/ui/`,
+`layouts/`, etc.). No canonical place for "this is a docs component."
+
+Implication:
+
+- Don't try to refactor the scatter as a side-quest in a feature PR.
+- Place new components by following the closest existing analogue, not
+  by inventing a new location.
+- Prioritize understanding the immediate task over mastering the whole
+  codebase.
+
+## "One-to-one" markdown fidelity is aspirational, not enforced
+
+**Severity:** ongoing improvement target.
+
+The stated direction is one-to-one fidelity between rendered guides and
+the markdown export produced by `generate-guides-markdown`. In practice,
+gaps exist:
+
+- Any MDX component without a `markdown-schema` handler is unwrapped to
+  its children, which may not match the rendered output.
+- `$Partial` recursion is silent — missing partials are dropped.
+- Some components (interactive, JSX-expression-heavy) inherently can't
+  serialize to markdown faithfully.
+
+Implication: when adding a component that should appear in markdown
+output, **always add a handler** in `internals/markdown-schema/` and
+register it in `generate-guides-markdown.ts`. See
+[`app-map.md`](./app-map.md) "The two pipelines."
+
+## Related
+
+- [`docs-app-direction.md`](./docs-app-direction.md) — where the
+  refactoring is headed; what these issues are being driven toward.
+- [`federated-docs.md`](./federated-docs.md) — full mechanics of the
+  federation pipeline.
+- [`gotchas.md`](./gotchas.md) — smaller per-change traps; this file
+  is for load-bearing systemic issues.
diff --git a/.agents/skills/ask-the-docs/reference/llm-agent-parity.md b/.agents/skills/ask-the-docs/reference/llm-agent-parity.md
new file mode 100644
index 0000000000000..207e2dc9f00aa
--- /dev/null
+++ b/.agents/skills/ask-the-docs/reference/llm-agent-parity.md
@@ -0,0 +1,97 @@
+# LLM / agent content parity and onboarding
+
+Companion to [`llm-agent-surface.md`](./llm-agent-surface.md) (routing and
+discovery). This file covers HTML↔markdown fidelity, search caveats, agent
+onboarding guides, and known stale wiring.
+
+**Verify against live code** before depending on any path here.
+
+## Two-pipeline parity for embedded content
+
+Content that renders on the HTML page is **not** automatically present
+in the `.md` export. Both pipelines must implement the same semantics.
+
+Example: framework quickstart **AI prompt blocks** (see
+supabase/supabase#47543). Each quickstart includes a bare partial:
+
+```mdx
+<$Partial path="ai/quickstart_prompt_nextjs.mdx" />
+```
+
+The partial is a self-closing `<AiPrompt>` with the prompt as a **prop**
+(not children — expression children are skipped by the guides markdown
+pipeline):
+
+```mdx
+<AiPrompt
+  prompt={
+    'Help me add Supabase to my Next.js project. Create a Supabase project at\ndatabase.new and run the instruments table SQL. Then:\n1. …'
+  }
+/>
+```
+
+| Pipeline     | Path                                                         |
+| ------------ | ------------------------------------------------------------ |
+| **HTML**     | `features/ui/AiPrompt.tsx` → `PromptPanel` (copy + expand)   |
+| **Markdown** | `internals/markdown-schema/AiPrompt.ts` reads `props.prompt` |
+
+`propsFrom()` stores the raw JS expression source. Prettier formats the
+prop as a multiline **single-quoted** string; the schema handler must
+decode that literal (trim + escapes), not only `JSON.parse` double-quoted
+JSON. Symptom if decoding is wrong: generated `.md` keeps surrounding
+quotes and literal `\n`.
+
+`$Partial` variable substitution (`lib/partials.utils.ts`, wired in both
+`partialsRemark` and `inlinePartials`) remains required for other nested
+partials — it is no longer the AI-prompt path.
+
+When adding content aimed at both humans and agents, always verify:
+
+```bash
+cd apps/docs && pnpm build:guides-markdown
+# then inspect public/markdown/guides/<same-path>.md for **AI Prompt**
+```
+
+## Programmatic search
+
+`/docs/api/graphql` exposes `searchDocs`, backed by embeddings generated
+offline via `scripts/search/generate-embeddings.ts`. Agents can request
+full `content` in results.
+
+**Caveat:** search infrastructure is decoupled from the markdown export
+pipeline and is considered fragile. See
+[`known-issues.md`](./known-issues.md) "Search infrastructure is
+decoupled and considered broken" before building features on top of it.
+
+## Agent onboarding content
+
+First-party guides under `content/guides/ai-tools/`:
+
+| Page             | Purpose                           |
+| ---------------- | --------------------------------- |
+| `mcp.mdx`        | Supabase MCP server setup         |
+| `plugins.mdx`    | One-click MCP + skills bundle     |
+| `byo-mcp.mdx`    | Build your own MCP server         |
+| `ai-skills.mdx`  | Index of installable agent skills |
+| `ai-prompts.mdx` | Curated IDE prompts               |
+
+The skills index is **federated** from `supabase/agent-skills` at
+runtime (`AiSkills.utils.ts`). See [`federated-docs.md`](./federated-docs.md).
+
+## In-flux / stale wiring
+
+- `apps/docs/.gitignore` lists `public/llms/` as generated by
+  `build:llms`, but **`build:llms` is not in `package.json`** today.
+  Per-source `llms/*.txt` links in `/llms.txt` may point at assets whose
+  generation path is unclear — verify before depending on them.
+- `llms-full.txt` fetches reference markdown from
+  `${NEXT_PUBLIC_DOCS_URL}/markdown/reference/<slug>.md` at runtime.
+
+## Related
+
+- [`llm-agent-surface.md`](./llm-agent-surface.md) — routing, negotiation,
+  entry points, bulk vs per-page retrieval.
+- [`app-map.md`](./app-map.md) — two-pipeline model, directory layout.
+- [`federated-docs.md`](./federated-docs.md) — agent-skills federation.
+- [`known-issues.md`](./known-issues.md) — search fragility, reference
+  page length.
diff --git a/.agents/skills/ask-the-docs/reference/llm-agent-surface.md b/.agents/skills/ask-the-docs/reference/llm-agent-surface.md
new file mode 100644
index 0000000000000..a162b0014451f
--- /dev/null
+++ b/.agents/skills/ask-the-docs/reference/llm-agent-surface.md
@@ -0,0 +1,181 @@
+# LLM and agent consumption surface
+
+How `apps/docs` exposes machine-readable content and how that relates to
+`apps/www`. For markdown export fidelity and agent onboarding pages, see
+[`llm-agent-parity.md`](./llm-agent-parity.md). For the markdown export
+pipeline itself, see [`app-map.md`](./app-map.md) "The two pipelines."
+
+**Verify against live code** — several pieces here span two apps and
+change independently.
+
+## Scope boundary
+
+| App             | Role                                                                                                               |
+| --------------- | ------------------------------------------------------------------------------------------------------------------ |
+| **`apps/docs`** | Produces markdown exports, serves per-guide `.md`, reference static files, GraphQL search, agent onboarding guides |
+| **`apps/www`**  | Serves discovery indexes (`/llms.txt`, `/llms-full.txt`) and product-page `.md` negotiation                        |
+
+`llms.txt` is **not** a route in `apps/docs`. It is assembled at runtime
+by `apps/www/app/llms.txt/route.ts`, reading guide directory names from
+`apps/docs/content/guides/` and linking to docs + reference exports.
+There is no static `llms.txt` file in the repo — the www route handler
+builds it on each request.
+
+### Key source files
+
+| What                  | Monorepo path                                    | Public URL (prod)                                 |
+| --------------------- | ------------------------------------------------ | ------------------------------------------------- |
+| `llms.txt` route      | `apps/www/app/llms.txt/route.ts`                 | `https://supabase.com/llms.txt`                   |
+| `llms-full.txt` route | `apps/www/app/llms-full.txt/route.ts`            | `https://supabase.com/llms-full.txt`              |
+| Guide middleware      | `apps/docs/middleware.ts`                        | — (lines ~16–38: negotiate, rewrite to guides-md) |
+| WWW middleware        | `apps/www/middleware.ts`                         | Product-page markdown negotiation                 |
+| Negotiation logic     | `packages/common/markdown-negotiation.ts`        | Shared by both middleware files                   |
+| Guides markdown API   | `apps/docs/app/api/guides-md/[...slug]/route.ts` | Reads `public/markdown/guides/` at runtime        |
+| Markdown manifest     | `apps/docs/public/markdown/manifest.json`        | Slugs eligible for `.md` negotiation              |
+
+## Build outputs → serving paths
+
+```mermaid
+flowchart TB
+  subgraph docsApp ["apps/docs prebuild"]
+    GM["build:guides-markdown"]
+    RM["build:reference-markdown"]
+    GZ["build:gz-archive"]
+    GM --> outGuides["public/markdown/guides/"]
+    RM --> outRef["public/markdown/reference/"]
+    GZ --> tarball["public/docs.tar.gz"]
+  end
+
+  subgraph docsServe ["apps/docs runtime"]
+    mw["middleware.ts"]
+    guidesMd["api/guides-md"]
+    crawlers["api/crawlers"]
+    gql["api/graphql searchDocs"]
+    mw --> guidesMd
+  end
+
+  subgraph wwwApp ["apps/www"]
+    llmsTxt["/llms.txt"]
+    llmsFull["/llms-full.txt"]
+  end
+
+  outGuides --> guidesMd
+  outGuides --> llmsFull
+  outRef --> llmsFull
+  outGuides --> llmsTxt
+  gql --> guidesMd
+```
+
+## Entry points
+
+| URL                                      | Owner       | Source                                                                                        |
+| ---------------------------------------- | ----------- | --------------------------------------------------------------------------------------------- |
+| `/llms.txt`                              | `apps/www`  | `app/llms.txt/route.ts` — index of guide sections + reference links                           |
+| `/llms-full.txt`                         | `apps/www`  | `app/llms-full.txt/route.ts` — concatenated guides + reference + product overviews            |
+| `/docs/guides/<path>.md`                 | `apps/docs` | Middleware → `app/api/guides-md/[...slug]/route.ts` reads `public/markdown/guides/`           |
+| `/docs/markdown/reference/<lib>.md`      | `apps/docs` | Static file from `public/markdown/reference/` (build output)                                  |
+| `/docs/docs.tar.gz`                      | `apps/docs` | `internals/generate-gz-archive.ts` tarballs all of `public/markdown/`                         |
+| `/docs/api/graphql` (`searchDocs`)       | `apps/docs` | Vector search over embedded doc sections — see [`llm-agent-parity.md`](./llm-agent-parity.md) |
+| `/docs/reference/<sdk>/<section>` (bots) | `apps/docs` | `isbot()` → `app/api/crawlers/route.ts` (simplified HTML, not markdown)                       |
+
+Homepage alternate link points agents at the full dump:
+`https://supabase.com/llms-full.txt` (`apps/docs/app/page.tsx`).
+
+## Audience routing (humans vs agents vs crawlers)
+
+Every guide exists in two forms from the same MDX source:
+
+| Form         | Produced by                                                          | Served to                            |
+| ------------ | -------------------------------------------------------------------- | ------------------------------------ |
+| **HTML**     | Live MDX render (`partialsRemark`, React components)                 | Humans in a browser                  |
+| **Markdown** | Prebuild (`generate-guides-markdown.ts` → `public/markdown/guides/`) | Live-fetch agents and bulk downloads |
+
+`apps/docs/middleware.ts` is the bouncer for guide requests. It calls
+`negotiateMarkdown()` from `packages/common/markdown-negotiation.ts` and
+checks `public/markdown/manifest.json` before serving markdown.
+
+```mermaid
+flowchart TD
+  req[Guide request] --> mdSuffix{URL ends in .md?}
+  mdSuffix -->|yes| markdown[Serve markdown]
+  mdSuffix -->|no| agentUA{Live-fetch agent UA?}
+  agentUA -->|yes| markdown
+  agentUA -->|no| accept{Accept prefers markdown?}
+  accept -->|yes| markdown
+  accept -->|no| html[Serve HTML page]
+  markdown --> rewrite["Rewrite to /api/guides-md/..."]
+  rewrite --> file["Read public/markdown/guides/..."]
+```
+
+### Who gets what
+
+| Audience                                 | Typical request                                                                  | Format   | Notes                                                                                |
+| ---------------------------------------- | -------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
+| **Human (browser)**                      | `/docs/guides/.../nextjs`                                                        | HTML     | Default — no special headers                                                         |
+| **Live-fetch agent**                     | Same URL with `Claude-User`, `ChatGPT-User`, `PerplexityBot`, or `Claude-Web` UA | Markdown | Auto-negotiated even without `.md` suffix                                            |
+| **Live-fetch agent**                     | `/docs/guides/.../nextjs.md` or `Accept: text/markdown`                          | Markdown | Explicit request                                                                     |
+| **SEO bot** (Googlebot)                  | Guide URL                                                                        | HTML     | Same page humans see; `isbot()` markdown rewrite applies only to **reference** pages |
+| **Training crawler** (GPTBot, ClaudeBot) | Guide URL                                                                        | HTML     | Allowed by `robots.txt` but **not** given alternate markdown — avoids cloaking       |
+| **Bulk ingest**                          | `/llms-full.txt`, `/docs/docs.tar.gz`                                            | Markdown | Reads prebuilt `public/markdown/` files                                              |
+
+Humans see interactive UI (copy buttons, styled panels). Agents and bulk
+tools read the pre-generated `.md` transcript — not the live HTML DOM.
+
+### Agent discovery
+
+Agents that don't know a specific URL can start from:
+
+- `/llms.txt` — section index with links to `.md` paths
+- `/llms-full.txt` — concatenated guides + reference + product overviews
+- `rel="alternate" type="text/markdown"` on each guide page
+  (`GuidesMdx.utils.tsx` → `${BASE_PATH}${pathname}.md`)
+- Docs homepage alternate → `https://supabase.com/llms-full.txt`
+
+## Content negotiation
+
+Shared logic lives in `packages/common/markdown-negotiation.ts`, used by
+both `apps/docs/middleware.ts` and `apps/www/middleware.ts`.
+
+Markdown is served when:
+
+- The URL ends in `.md`
+- `Accept: text/markdown` wins over HTML (q-value comparison)
+- The user-agent matches **live-fetch agents**: `Claude-User`,
+  `Claude-Web`, `ChatGPT-User`, `PerplexityBot`
+
+Training crawlers (`GPTBot`, `ClaudeBot`, etc.) are **not** given
+alternate markdown — they are governed by `robots.txt` to avoid
+cloaking penalties.
+
+On guides, negotiated requests rewrite to `/api/guides-md/<slug>`.
+Each guide page advertises its markdown alternate in metadata via
+`GuidesMdx.utils.tsx` (`text/markdown` → `${BASE_PATH}${pathname}.md`).
+
+404 responses from `guides-md` are also markdown and include
+`searchDocs` suggestions — useful when an agent fetches a stale URL.
+
+## Bulk vs per-page retrieval
+
+| Strategy                            | Best for                                          |
+| ----------------------------------- | ------------------------------------------------- |
+| `/llms.txt`                         | Discovering available sections and reference libs |
+| `/llms-full.txt`                    | One-shot full ingest                              |
+| `/docs/docs.tar.gz`                 | Offline/batch ingest of all generated markdown    |
+| `/docs/guides/<path>.md`            | Single guide page                                 |
+| `/docs/markdown/reference/<lib>.md` | Single reference lib export                       |
+
+Reference pages do **not** use the same `Accept: text/markdown`
+negotiation as guides. Reference markdown comes from the static export
+and `llms-full.txt`, not from middleware negotiation.
+
+## Related
+
+- [`llm-agent-parity.md`](./llm-agent-parity.md) — two-pipeline fidelity,
+  search caveat, agent onboarding pages, in-flux wiring.
+- [`app-map.md`](./app-map.md) — two-pipeline model, directory layout.
+- [`build-pipeline.md`](./build-pipeline.md) — prebuild steps that
+  produce markdown exports and the tarball.
+- [`docs-app-direction.md`](./docs-app-direction.md) — one-to-one
+  markdown fidelity goal.
+- [`known-issues.md`](./known-issues.md) — reference page length,
+  search fragility.
diff --git a/.agents/skills/ask-the-docs/reference/management-api-reference.md b/.agents/skills/ask-the-docs/reference/management-api-reference.md
new file mode 100644
index 0000000000000..98f0b1f009d72
--- /dev/null
+++ b/.agents/skills/ask-the-docs/reference/management-api-reference.md
@@ -0,0 +1,103 @@
+# Management API reference generation
+
+How `/docs/reference/api/*` is built from the live Management API OpenAPI
+spec. Verify against `apps/docs/spec/Makefile` and
+`features/docs/Reference.generated.script.ts` before acting — paths drift.
+
+## Pipeline
+
+```mermaid
+flowchart LR
+  live["api.supabase.com<br/>/api/v1-json + v2-json"]
+  raw["spec/api_v{1,2}_openapi.json"]
+  redocly["Redocly bundle<br/>(no --dereferenced)"]
+  bundled["spec/transforms/<br/>api_v*_openapi_deparsed.json"]
+  sections["common-api-sections.json"]
+  codegen["codegen:references:legacy"]
+  gen["features/docs/generated/<br/>api.latest.*.json"]
+  page["ApiReferencePage →<br/>ApiEndpointSection"]
+  md["public/markdown/reference/api.md"]
+
+  live --> raw --> redocly --> bundled
+  bundled --> sections
+  bundled --> codegen
+  sections --> codegen
+  codegen --> gen --> page
+  gen --> md
+```
+
+1. **Download** — `make download.api.v1` in `apps/docs/spec/` curls the
+   live OpenAPI into `api_v1_openapi.json` / `api_v2_openapi.json`.
+2. **Bundle** — `make dereference.api.v1` runs Redocly CLI
+   (`@redocly/cli`) `bundle` into `transforms/*_deparsed.json`.
+   Management API deliberately omits `--dereferenced` (circular `$ref` in
+   `APIErrorObject.issues`). `$refs` are resolved later in codegen with a
+   cycle guard.
+3. **Nav sections** — `sections/generateMgmtApiSections.cts` walks
+   operations/tags into `common-api-sections.json`.
+4. **Codegen** — `codegen:references:legacy`
+   (`Reference.generated.script.ts`) merges v1+v2, resolves refs, writes
+   `api.latest.endpointsById.json`, `sections.json`, `flat.json`,
+   `bySlug.json` under `features/docs/generated/`.
+5. **Runtime** — `/reference/api/[operation]` via `ApiReferencePage` →
+   `SectionSwitch` → `ApiEndpointSection` (custom React, not MDX). One
+   endpoint per page (DOCS-1268). Hand-written intro MDX lives under
+   `docs/ref/api/`.
+6. **Agents** — `generate-reference-markdown.ts` exports the same data to
+   `public/markdown/reference/api.md`.
+
+Legacy EJS (`generator/api.ts` + `ApiTemplate.ts`) is not the live path.
+
+## Redocly today (bundle / lint)
+
+| Job    | Where                                                                      | Notes                                                               |
+| ------ | -------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| Bundle | `make dereference.api.v1` (and sibling targets for auth/storage/analytics) | Invoked via `npx --package=@redocly/cli redocly bundle`             |
+| Lint   | `make validate.analytics.v0` only                                          | `redocly lint --extends=minimal`. Management API has no lint target |
+
+Redocly is the OpenAPI **toolchain** (bundle/lint), not the page renderer.
+
+## Rendering: keep the custom path
+
+Pages render via custom React (`ApiEndpointSection`), not Scalar / Redoc /
+Stoplight Elements. Reasons (see also [`adding-features.md`](./adding-features.md)
+and [`known-issues.md`](./known-issues.md)):
+
+- **Two pipelines** — HTML + markdown export + GraphQL search share one
+  `IApiEndPoint` / generated-JSON shape. A third-party viewer forks that.
+- **Custom extensions** — `x-oauth-scope`, `x-allowed-plans`,
+  `x-fga-permissions` need first-class rendering.
+- **Modular pages** — DOCS-1268 already split the monolithic API page;
+  embedding a full-spec viewer would reverse that.
+- **Surface** — new dep + theming + parity work fights docs-app direction
+  (reduce surface, don't add parallel renderers).
+
+Prefer improving `ApiEndpointSection` / schema helpers, or deepening
+Redocly lint on download/transform. Do not propose swapping the renderer
+for an OpenAPI UI kit without addressing markdown/search/`x-*` parity.
+
+Closest CLI substitutes if Redocly were unavailable: `@apidevtools/swagger-parser`
+or `swagger-cli` for bundle; Spectral for lint. Switching buys little while
+the custom cycle-safe resolve remains required.
+
+## Key files
+
+| Path                                                    | Role                                         |
+| ------------------------------------------------------- | -------------------------------------------- |
+| `apps/docs/spec/Makefile`                               | download / Redocly bundle / section generate |
+| `apps/docs/spec/sections/generateMgmtApiSections.cts`   | OpenAPI → `common-api-sections.json`         |
+| `apps/docs/features/docs/Reference.generated.script.ts` | merge, resolve refs, write `api.latest.*`    |
+| `apps/docs/features/docs/Reference.api.utils.ts`        | `IApiEndPoint` + schema display helpers      |
+| `apps/docs/features/docs/Reference.apiPage.tsx`         | route → one operation page                   |
+| `apps/docs/features/docs/Reference.sections.tsx`        | `ApiEndpointSection` UI                      |
+| `apps/docs/internals/generate-reference-markdown.ts`    | agent markdown export                        |
+
+## Related
+
+- [`build-pipeline.md`](./build-pipeline.md) — where `codegen:references`
+  sits in prebuild.
+- [`app-map.md`](./app-map.md) — reference vs guides routing.
+- [`known-issues.md`](./known-issues.md) — reference pages avoid standard
+  MDX; length / modularization direction.
+- [`llm-agent-surface.md`](./llm-agent-surface.md) — markdown export
+  consumption.
diff --git a/.agents/skills/pm-the-docs/SKILL.md b/.agents/skills/pm-the-docs/SKILL.md
new file mode 100644
index 0000000000000..02b49c9cbcc05
--- /dev/null
+++ b/.agents/skills/pm-the-docs/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: pm-the-docs
+description: >-
+  Docs-PM decision support for the "Write the docs" authoring process —
+  makes audience, stage, and cross-cutting scope calls during the Frame
+  and Shape stages, and helps decide when a docs question needs to
+  self-serve vs. escalate to a docs PM. Use when framing a new docs page
+  or launch, deciding what product stage or audience a feature targets,
+  or judging whether a docs question needs PM sign-off.
+---
+
+# PM the docs
+
+Backs the Frame and Shape stages of the "Write the docs" checklist (mirrored in [reference/write-the-docs-checklist.md](reference/write-the-docs-checklist.md)) — the audience, product-stage, and cross-cutting scope calls a docs PM would normally make before drafting starts.
+
+## When to invoke
+
+- Starting a new docs page or launch and need to state the product stage, audience, and "why" before drafting (Frame).
+- 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)).
+
+## Answering a scope/stage/audience question
+
+1. Read the relevant stage in [reference/write-the-docs-checklist.md](reference/write-the-docs-checklist.md) — its checkboxes state exactly what needs deciding.
+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.
+
+## Self-serve vs. escalate
+
+Self-serve when the checklist is clear, standards exist, and you already know the stage and audience.
+
+Escalate to your docs team's PM when scope or stage is unclear, you need a review path, the bar is ambiguous, or the launch touches cross-cutting surfaces (quickstarts, API keys, tutorials, onboarding, platform concepts) — see the full "Ask the Docs PM" section in the checklist mirror.
+
+## Related skills
+
+- [`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
+- [`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
new file mode 100644
index 0000000000000..e3eae3900c8b2
--- /dev/null
+++ b/.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md
@@ -0,0 +1,77 @@
+# Write the docs
+
+> Mirrors Supabase's proposed "Write the docs" process as of 2026-08-10. Process specifics may still evolve.
+
+A practical six-stage checklist and quality standard for planning, drafting, and reviewing product documentation.
+
+## What good looks like
+
+- The **why** is explicit: a reader learns what problem this solves and when to reach for it, not only the steps.
+- The **content type is deliberate** and consistent within the page.
+- **Audience and prerequisites** are stated up front.
+- At least one **example is runnable and has been run** (commands, code, expected result).
+- **Correct stage** is stated; limitations are named honestly.
+- The page **lives in the right place** in the IA and links to and from related pages.
+- Terminology and formatting match existing docs (defer to the style guide once one lands).
+
+## 1. Frame
+
+_Skills:_ `/ask-the-docs` to see how the surface works today; `/pm-the-docs` for audience, stage, and cross-cutting scope calls.
+
+- [ ] P: State the product stage (private/public alpha, beta, GA)
+- [ ] P: Name the audience and the job they are trying to do
+- [ ] P: Write one line on _why_ the feature exists (the problem it solves), not only what it does
+
+## 2. Shape
+
+_Skill:_ `/ask-the-docs` for IA placement, architecture, and where content lives.
+
+- [ ] P: Pick the content type(s): tutorial (learning), how-to (a task), reference (lookup), explanation (the why). Do not mix types on one page (refer to [Diátaxis](https://diataxis.fr/))
+- [ ] P: Decide where the page lives in the existing IA and what links in and out (avoid orphan pages)
+- [ ] P: List prerequisites and assumed knowledge up front
+
+## 3. Draft
+
+_Skill:_ `/write-the-docs` to draft net-new content grounded in Linear and the code.
+
+- [ ] P: Lead with the why and the outcome, then the how/what (product story first)
+- [ ] P: Include at least one runnable, copy-pasteable example that you have actually run
+- [ ] E: Contribute technical depth and verify accuracy (APIs, limits, edge cases)
+- [ ] P: Call out the current stage inline and any known limitations
+
+## 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.
+
+- [ ] P/E: Check the draft against "What good looks like" above before opening the PR
+- [ ] P/E: Follow authoring-experience standards and tooling when available
+
+## 5. PR review
+
+_Skill:_ `/review-the-docs` to triage, classify, verify the build, and report.
+
+- [ ] P/E: Open the PR and request review per the rules of engagement
+- [ ] Docs: Review against the published bar
+
+## 6. Keep it honest
+
+- [ ] P: Keep the product launch checklist's "start on day 1" docs gate honest through ship (update as stage or behavior changes)
+
+## Ask the Docs PM
+
+**Self-serve when:** the checklist above is clear, standards exist, and you know the product stage and audience.
+
+**Ask when:** scope or stage is unclear, you need a review path, the bar is ambiguous, or the launch docs touch cross-cutting surfaces (quickstarts, API keys, tutorials, onboarding, platform concepts).
+
+**What to expect:** the docs PM is the point of contact for questions and review against the bar.
+
+**Where to ping:** your team's PR-review channel and current docs PM — check your contributor guide for who that is today.
+
+## Reference
+
+Role prefixes:
+
+- **P** = Product. The product lead / area PM who writes the docs.
+- **E** = Engineering. Contributes technical depth and verifies accuracy.
+- **P/E** = Product and Engineering together.
+- **Docs** = Docs team, the reviewer.
diff --git a/.agents/skills/review-the-docs/SKILL.md b/.agents/skills/review-the-docs/SKILL.md
new file mode 100644
index 0000000000000..1b6bdcba37c78
--- /dev/null
+++ b/.agents/skills/review-the-docs/SKILL.md
@@ -0,0 +1,404 @@
+---
+name: review-the-docs
+description: >-
+  Review Supabase docs changes locally in ~/GitHub/supabase/supabase —
+  either an open PR (triage, classify, verify) or your own branch before
+  opening a PR (local self-review). Covers markdown pipeline, MDX content,
+  tutorials, examples, Studio links, and docs tooling. Use when asked to
+  review docs PRs, self-review a draft branch, check who has approved,
+  verify build output, or evaluate supabase/supabase documentation changes.
+---
+
+# Review docs PRs
+
+Local review workflow for `supabase/supabase` docs changes. Classify first, then follow the matching checklist.
+
+Two modes:
+
+- **Open PR review** (default) — triage via `gh`, checkout, verify, report. Start at [Phase 1](#phase-1--triage-read-only).
+- **Local self-review** — no open PR yet; verify the current branch before opening one. Start at [Local self-review](#local-self-review-no-open-pr).
+
+For **implementing** docs fixes (Linear tickets, worktrees, platform E2E), use [`work-linear-issue`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/work-linear-issue/SKILL.md) instead.
+
+## Core rules
+
+1. **Classify before reviewing** — path patterns determine which checklist applies.
+2. **Review stacked PRs bottom-up** — each PR may base on the previous branch.
+3. **Run verification locally** — do not approve from diff alone.
+4. **Compare against `master`** when the PR claims to fix missing or broken output.
+5. **One report per batch** — sequential review, consolidated output at the end.
+6. **Separate blockers from nits** — type/style notes are suggestions unless output breaks.
+
+## Repository layout
+
+| Path                                   | Purpose                                                   |
+| -------------------------------------- | --------------------------------------------------------- |
+| `~/GitHub/supabase/supabase`           | Main clone for review checkouts                           |
+| `apps/docs/content/guides/`            | Source MDX                                                |
+| `apps/docs/internals/`                 | Markdown pipeline (`generate-guides-markdown.ts`, etc.)   |
+| `apps/docs/internals/markdown-schema/` | Component handlers → plain markdown strings               |
+| `apps/docs/public/markdown/guides/`    | Generated output (produced by build)                      |
+| `apps/docs/components/`                | React MDX components                                      |
+| `examples/`                            | Tutorial/quickstart apps referenced via `$CodeSample`     |
+| `apps/studio/`                         | Dashboard UI; may link to hosted docs                     |
+| `.agents/skills/`                      | In-repo agent skills (symlinked from `.claude`/`.cursor`) |
+
+## Local self-review (no open PR)
+
+Use this on your own branch **before** opening a PR (checklist Stage 4). No `gh pr` required.
+
+```bash
+cd ~/GitHub/supabase/supabase
+# Ensure you're on the feature branch, not master
+git branch --show-current
+git diff --name-only master...HEAD
+```
+
+1. **Classify** from `git diff --name-only master...HEAD` using the [Phase 2](#phase-2--classify-pr-type) table.
+2. **Walk the bar** in [`pm-the-docs`'s checklist](../pm-the-docs/reference/write-the-docs-checklist.md) — "What good looks like" and the Self-review checkboxes.
+3. **Run type-specific checks** from the matching sections below on the current branch (no checkout step). Typical commands:
+
+```bash
+# Content / tutorial MDX
+cd apps/docs && pnpm lint:mdx -- <changed-paths>
+
+# Pipeline / schema handler
+cd apps/docs && pnpm build:guides-markdown
+# inspect public/markdown/guides/ for affected pages
+pnpm build:reference-markdown   # when reference pipeline changed
+```
+
+4. Spot-check frontmatter, internal links, and nav wiring for content changes.
+5. Write a short **self-review note** (blockers vs nits) suitable to paste into the future PR body under a "Self-review" heading.
+
+Then open the PR and continue with open-PR review if a second pass is needed.
+
+## Phase 1 — Triage (read-only)
+
+### List PRs
+
+Filter by author, label, or list all open docs PRs:
+
+```bash
+# By author
+gh pr list --repo supabase/supabase --author <github-user> --state open \
+  --json number,title,url,reviewDecision,latestReviews,changedFiles,additions,deletions,labels
+
+# All open docs-labeled PRs
+gh pr list --repo supabase/supabase --state open --label documentation \
+  --json number,title,url,reviewDecision,latestReviews,author,changedFiles
+```
+
+PRs with empty `reviewDecision` and no `APPROVED` review need approval.
+
+### Map the stack
+
+```bash
+gh pr view <number> --repo supabase/supabase \
+  --json number,title,baseRefName,headRefName,body,files
+```
+
+Stacked series: `master → PR A → PR B → PR C`. Review and merge bottom-up.
+
+## Phase 2 — Classify PR type
+
+Inspect changed files from `gh pr view` or:
+
+```bash
+gh pr diff <number> --repo supabase/supabase --name-only
+```
+
+| PR type                     | Path signals                                                                                                    | Primary skill section                                          |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| **Markdown-schema handler** | `apps/docs/internals/markdown-schema/`, `generate-guides-markdown.ts`                                           | [Schema handler review](#schema-handler-review)                |
+| **Pipeline / internals**    | `apps/docs/internals/` (not just one new handler)                                                               | [Pipeline review](#pipeline-review)                            |
+| **Content-only MDX**        | `apps/docs/content/**` only                                                                                     | [Content review](#content-review)                              |
+| **Tutorial / quickstart**   | `apps/docs/content/guides/**/tutorials/`, `quickstarts/`, plus `examples/`                                      | [Tutorial review](#tutorial-review) → also `work-linear-issue` |
+| **Example app only**        | `examples/**` without matching MDX                                                                              | [Example review](#example-review)                              |
+| **Studio ↔ docs links**     | `apps/studio/**`                                                                                                | [Studio review](#studio-review)                                |
+| **Docs UI / components**    | `apps/docs/components/`, `apps/docs/features/` (no pipeline)                                                    | [Component review](#component-review)                          |
+| **Docs tooling**            | `.agents/skills/`, `.claude/skills/`, `.cursor/skills/`, `apps/docs/CONTRIBUTING.md`, `apps/docs/DEVELOPERS.md` | [Docs tooling review](#docs-tooling-review)                    |
+| **Mixed**                   | Multiple path groups above                                                                                      | Run each applicable section; note overlap                      |
+
+When a PR spans types (e.g. schema handler + component refactor), run **all** matching sections.
+
+## Phase 3 — Sequential local review
+
+Repeat for **each PR** (bottom of stack first).
+
+### Common steps (all PR types)
+
+**Checkout and install:**
+
+```bash
+cd ~/GitHub/supabase/supabase
+gh pr checkout <number> --repo supabase/supabase
+pnpm install --filter docs...   # when node_modules missing or deps changed
+```
+
+**CI spot-check:**
+
+```bash
+gh pr checks <number> --repo supabase/supabase
+```
+
+**Baseline on master** (when PR fixes missing/broken output):
+
+```bash
+git checkout master
+# run type-specific verify command (see sections below)
+git checkout -   # return to PR branch
+```
+
+---
+
+### Schema handler review
+
+For PRs adding static markdown fallbacks for React MDX components.
+
+**Code checks** — each handler in `apps/docs/internals/markdown-schema/`:
+
+| Check            | What to verify                                                           |
+| ---------------- | ------------------------------------------------------------------------ |
+| Data source      | Same data/constants as the React component — no duplicated config        |
+| CJS interop      | `shared-data` via `createRequire(import.meta.url)` (see `SharedData.ts`) |
+| Local JSON       | Direct imports fine for `apps/docs/data/`                                |
+| Link prefix      | Links use `withDocsBasePath`                                             |
+| SCHEMA wiring    | Registered in `SCHEMA` in `generate-guides-markdown.ts`                  |
+| Props / shapes   | All MDX usages covered — flat arrays and `{ items: [...] }` sections     |
+| Silent fallbacks | `''` for unknown props OK if consistent with existing handlers           |
+
+Find usages: `rg '<ComponentName' apps/docs/content/`
+
+**Build and inspect:**
+
+```bash
+cd apps/docs && pnpm build:guides-markdown
+# Expect: Generated 546 markdown files under public/markdown/guides/
+```
+
+Inspect `public/markdown/guides/` for affected pages:
+
+- Previously blank sections now have lists, tables, or links
+- All MDX pages using the component are covered, not just the one in the PR description
+- Link format: `/docs/guides/...` locally; absolute URLs when `VERCEL_ENV=production`
+
+---
+
+### Pipeline review
+
+For AST refactors, link rewriting, reference markdown generation, etc.
+
+```bash
+cd apps/docs
+pnpm build:guides-markdown
+pnpm build:reference-markdown   # when reference pipeline changed
+pnpm test internals/internal-links.test.ts   # when link handling changed
+```
+
+Verify both guides and reference output when `generate-reference-markdown.ts` or `internal-links.ts` changed.
+
+---
+
+### Content review
+
+MDX prose, partials, navigation — no pipeline or example changes.
+
+```bash
+cd apps/docs
+pnpm lint:mdx -- <changed-paths>    # or monorepo equivalent on changed files
+```
+
+Checklist:
+
+- [ ] Frontmatter valid (`title`, `description` where required)
+- [ ] Internal links resolve (`/docs/guides/...`, not broken anchors)
+- [ ] `$CodeSample` paths match existing example directories
+- [ ] Admonitions, tabs, and partial includes render sensibly in PR preview
+- [ ] No accidental whitespace-only or empty sections where components were removed
+
+Compare PR preview URL (from Vercel/deployment comment) against production for visual regressions when layout components are involved.
+
+---
+
+### Tutorial review
+
+Tutorial MDX plus matching example app. **Read [`work-linear-issue`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/work-linear-issue/SKILL.md)** for full platform E2E — review is not complete without it when auth flows are involved.
+
+```bash
+# MDX lint
+cd apps/docs && pnpm lint:mdx -- content/guides/getting-started/tutorials/<path>
+
+# Example build (from work-linear-issue)
+cd examples/<example-dir>
+npm install && npm run build
+```
+
+Checklist:
+
+- [ ] MDX steps match example code after `pnpm codegen:examples` (if `$CodeSample` used)
+- [ ] Env var names and Supabase client setup match current `@supabase/ssr` patterns
+- [ ] Example pins catalog versions — no `"latest"` for in-repo packages
+- [ ] **Platform E2E** (when auth involved): SQL migration applied, auth flow walked, profiles verified — see `work-linear-issue` Phase 3
+
+---
+
+### Example review
+
+Example-only PRs (or example portion of a tutorial PR).
+
+```bash
+cd examples/<example-dir>
+npm install && npm run build
+```
+
+Checklist:
+
+- [ ] Build passes with no type errors
+- [ ] `.env.example` documents required vars (no secrets committed)
+- [ ] If docs reference this example, `$CodeSample` paths still valid
+
+---
+
+### Studio review
+
+Dashboard changes linking to docs.
+
+Checklist:
+
+- [ ] Links point to hosted docs anchors (e.g. `/guides/auth/auth-email-templates#terminology`)
+- [ ] Local-dev-only doc paths not used as the sole link target
+- [ ] Link text matches the destination section
+
+---
+
+### Component review
+
+React component changes under `apps/docs/components/` without a new schema handler.
+
+Checklist:
+
+- [ ] No browser-only APIs leaked into build-script imports
+- [ ] Shared constants extracted cleanly when also consumed by markdown handlers
+- [ ] Visual behavior unchanged or intentionally improved — check PR screenshots
+- [ ] If component is used in MDX exported to markdown, confirm a schema handler exists or file an follow-up
+
+---
+
+### Docs tooling review
+
+Agent skills, contributor docs, or skill symlink wiring — no MDX/pipeline changes required.
+
+Checklist:
+
+- [ ] Symlinks under `.claude/skills/` and `.cursor/skills/` resolve to `.agents/skills/...` (same pattern as `vitest`)
+- [ ] Cross-skill links resolve: relative for in-repo skills; absolute `docs-agent-skills` URLs only for skills that remain in that private repo
+- [ ] No personal vault paths, Obsidian references, or private-process-only instructions
+- [ ] `apps/docs/CONTRIBUTING.md` / `DEVELOPERS.md` pointers match skill names and checklist stages
+- [ ] Reference files under a skill stay near the ~250-line guideline (split if bloated)
+
+```bash
+# Symlink smoke check
+ls -la .claude/skills/<skill-name> .cursor/skills/<skill-name>
+test -f .claude/skills/<skill-name>/SKILL.md
+
+# Leftover internal refs
+rg -n 'Obsidian|pm-the-docs-full|Priorities/' .agents/skills
+```
+
+---
+
+## Phase 4 — Review report
+
+One consolidated report after all PRs are reviewed.
+
+### Report template
+
+```markdown
+# PR review report — <author, label, or topic>
+
+Reviewed locally at `~/GitHub/supabase/supabase`.
+
+**Stack order:** master → #NNN → … (if applicable)
+
+---
+
+## [#NNN — Title](https://github.com/supabase/supabase/pull/NNN)
+
+**Type:** schema handler | pipeline | content | tutorial | example | studio | component | docs tooling | mixed
+
+**Verdict:** Approve | Approve with nits | Request changes
+
+| Check              | Result |
+| ------------------ | ------ |
+| PR type checks     | …      |
+| Build / lint       | …      |
+| Baseline vs master | …      |
+| CI                 | …      |
+
+**Verified:**
+
+- …
+
+**Notes:**
+
+- …
+
+---
+
+## Summary
+
+| PR   | Type | Recommendation | Blockers |
+| ---- | ---- | -------------- | -------- |
+| #NNN | …    | …              | …        |
+
+**Merge order:** bottom-up after approval (if stacked).
+```
+
+### Verdict guidance
+
+| Verdict               | When                                                                                 |
+| --------------------- | ------------------------------------------------------------------------------------ |
+| **Approve**           | All type-specific checks pass; output correct                                        |
+| **Approve with nits** | Works correctly; minor type/style/docs nits only                                     |
+| **Request changes**   | Build/lint fails, broken links, wrong data, missing coverage, or failed platform E2E |
+
+## Inline review comments
+
+```text
+https://github.com/supabase/supabase/pull/<number>/files#diff-<blob-sha>R<line>
+```
+
+```bash
+gh api repos/supabase/supabase/pulls/<number>/files \
+  --jq '.[] | select(.filename | endswith("<file>")) | .sha'
+```
+
+Include concrete evidence — JSON line numbers, before/after output snippets, failing command output.
+
+## Handler pattern reference
+
+```typescript
+// apps/docs/internals/markdown-schema/Example.ts
+import { withDocsBasePath } from '../internal-links'
+
+export const Example = ({ props }: { props: Record<string, unknown> }): string => {
+  // Same data source as React component → plain markdown string
+}
+```
+
+## Parallel work
+
+Independent PRs: subagents can review in separate worktrees. **Stacked** series: review sequentially on one clone, bottom-up.
+
+## Output checklist
+
+- [ ] Approval status fetched for all requested PRs
+- [ ] Each PR classified by type
+- [ ] Stack order documented (if applicable)
+- [ ] Type-specific verification run locally (not just schema handler defaults)
+- [ ] Master baseline compared when PR fixes missing output
+- [ ] Platform E2E noted for tutorial/auth PRs (or deferred with reason)
+- [ ] Verdict and blockers stated per PR
+- [ ] Merge order recommended
+- [ ] Inline comment links provided for nits
diff --git a/.agents/skills/write-the-docs/SKILL.md b/.agents/skills/write-the-docs/SKILL.md
new file mode 100644
index 0000000000000..75902d79ddffe
--- /dev/null
+++ b/.agents/skills/write-the-docs/SKILL.md
@@ -0,0 +1,78 @@
+---
+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.
+---
+
+# 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.
+
+## 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)).
+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.
+
+## Phase 1 — Gather (read-only)
+
+Four inputs, in order:
+
+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 `<page>`."_ 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.
+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.
+
+Summarize all four back to the requester before drafting: what's confirmed, what's product intent vs. shipped behavior, what's still a gap. Stop and ask if a real gap would change the draft's structure or scope.
+
+## Phase 1.5 — Content-type gate
+
+Before drafting, classify what's actually being asked for against `apps/docs`'s real content types (see [`ask-the-docs`](../ask-the-docs/SKILL.md)'s `app-map.md` "Content types" table, and [reference/content-type-gate.md](reference/content-type-gate.md) here):
+
+- **Guide / tutorial** — hand-written MDX under `content/guides/`. This is what this skill drafts.
+- **Troubleshooting** — hand-written MDX under `content/troubleshooting/`, sometimes synced from GitHub issues. Also in scope.
+- **Reference** — generated from `spec/` (OpenAPI, SDK YAML, CLI config) → `features/docs/generated/**`. **Not hand-authored via the standard MDX path.** If the ask is actually reference-type content (a new API endpoint, config option, or SDK method that needs a reference entry), stop drafting MDX — it would diverge from or get silently overwritten by the generator. Instead point to the spec/codegen pipeline (`apps/docs/spec/`, `apps/docs/generator/`; see `ask-the-docs`'s `management-api-reference.md` for the OpenAPI-specific flow) and say so explicitly rather than producing a page that looks done but isn't the real fix.
+
+When in doubt, ask `ask-the-docs` rather than guessing — this classification is the one call in this skill most likely to be wrong if made from outside knowledge of the app.
+
+## Phase 2 — Draft
+
+- 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.
+
+## Phase 2.5 — Review checklist
+
+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
+- [ ] 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
+
+## Phase 3 — Handoff
+
+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.
+
+## 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)
+- Content-type gate detail: [reference/content-type-gate.md](reference/content-type-gate.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)
+- Screenshots/proof: [`proof-it-works`](https://github.com/supabase/docs-agent-skills/blob/main/.claude/skills/proof-it-works/SKILL.md)
diff --git a/.agents/skills/write-the-docs/reference/content-type-gate.md b/.agents/skills/write-the-docs/reference/content-type-gate.md
new file mode 100644
index 0000000000000..a12f15f4b85ff
--- /dev/null
+++ b/.agents/skills/write-the-docs/reference/content-type-gate.md
@@ -0,0 +1,22 @@
+# Content-type gate
+
+Before drafting anything, classify the request against `apps/docs`'s real content types. This is grounded in `ask-the-docs`'s `app-map.md` "Content types" table — re-check that table if this note and the live app-map ever disagree, since the app-map is the source of truth.
+
+| Type | Location | Hand-authored by this skill? |
+|---|---|---|
+| **Guide / tutorial** | `content/guides/` | Yes — hand-written MDX, goal-oriented. This is the default case. |
+| **Troubleshooting** | `content/troubleshooting/` | Yes, though some entries sync from GitHub issues — check before assuming a fresh page is needed. |
+| **Reference** | Generated from `spec/` (OpenAPI, SDK YAML, CLI config) → `features/docs/generated/**` | **No.** Reference pages do not use the standard MDX path — see `ask-the-docs`'s `docs-app-direction.md` for why, and `management-api-reference.md` for the OpenAPI-specific spec → codegen → reference-page flow. |
+| **Federated** | External repos, pulled at build time | No — out of scope for this skill; see `ask-the-docs`'s `federated-docs.md`. |
+
+## What to do when the ask is actually Reference-type
+
+A common trap: a ticket says "document the new `X` config option" or "add docs for the new API endpoint," which sounds like a normal doc-writing ask but is actually a spec change. If so:
+
+1. Don't hand-draft an MDX reference page — it will diverge from or get silently overwritten by the next `generate-reference-markdown.ts` run.
+2. Identify the correct spec source (`apps/docs/spec/` — OpenAPI, SDKSpec, ConfigSpec, or CLISpec depending on the surface).
+3. Say explicitly in the handoff that the real fix is a spec/codegen change, not a docs PR from this skill, and point to `ask-the-docs` for the specific spec-editing workflow.
+
+## When it's genuinely ambiguous
+
+Some features span both — e.g. a new API endpoint (Reference) that also needs a task-oriented guide showing how to use it (Guide). In that case, split the work: flag the Reference-type piece per above, and draft only the Guide-type piece here.
diff --git a/.agents/skills/write-the-docs/reference/style-fallback.md b/.agents/skills/write-the-docs/reference/style-fallback.md
new file mode 100644
index 0000000000000..e86e83fcd6ee1
--- /dev/null
+++ b/.agents/skills/write-the-docs/reference/style-fallback.md
@@ -0,0 +1,18 @@
+# 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:
+
+1. Read [`apps/docs/CONTRIBUTING.md`](../../../../apps/docs/CONTRIBUTING.md)
+   for authoring conventions (voice, structure, document types).
+2. Read [`apps/docs/WORD_LIST.md`](../../../../apps/docs/WORD_LIST.md) for
+   preferred spelling, capitalization, and terminology.
+3. If those don't cover the case, find the nearest comparable existing page
+   under `apps/docs/content/` (same product area, similar content type —
+   reference vs. guide vs. quickstart) and follow its voice, heading
+   structure, and code-sample conventions.
+4. State which page you followed as precedent in the handoff summary — e.g.
+   "no dedicated style guide yet — following the precedent of
+   `guides/storage/uploads.mdx`."
+5. When a dedicated style guide is added to the repo later, prefer it over
+   precedent-matching and drop this fallback step.
diff --git a/.claude/skills/ask-the-docs b/.claude/skills/ask-the-docs
new file mode 120000
index 0000000000000..d71a2076e4f03
--- /dev/null
+++ b/.claude/skills/ask-the-docs
@@ -0,0 +1 @@
+../../.agents/skills/ask-the-docs
\ No newline at end of file
diff --git a/.claude/skills/pm-the-docs b/.claude/skills/pm-the-docs
new file mode 120000
index 0000000000000..b2cc2ea4b4709
--- /dev/null
+++ b/.claude/skills/pm-the-docs
@@ -0,0 +1 @@
+../../.agents/skills/pm-the-docs
\ No newline at end of file
diff --git a/.claude/skills/review-the-docs b/.claude/skills/review-the-docs
new file mode 120000
index 0000000000000..49fccdd463dab
--- /dev/null
+++ b/.claude/skills/review-the-docs
@@ -0,0 +1 @@
+../../.agents/skills/review-the-docs
\ No newline at end of file
diff --git a/.claude/skills/write-the-docs b/.claude/skills/write-the-docs
new file mode 120000
index 0000000000000..d647d2d6b8817
--- /dev/null
+++ b/.claude/skills/write-the-docs
@@ -0,0 +1 @@
+../../.agents/skills/write-the-docs
\ No newline at end of file
diff --git a/.cursor/skills/ask-the-docs b/.cursor/skills/ask-the-docs
new file mode 120000
index 0000000000000..d71a2076e4f03
--- /dev/null
+++ b/.cursor/skills/ask-the-docs
@@ -0,0 +1 @@
+../../.agents/skills/ask-the-docs
\ No newline at end of file
diff --git a/.cursor/skills/pm-the-docs b/.cursor/skills/pm-the-docs
new file mode 120000
index 0000000000000..b2cc2ea4b4709
--- /dev/null
+++ b/.cursor/skills/pm-the-docs
@@ -0,0 +1 @@
+../../.agents/skills/pm-the-docs
\ No newline at end of file
diff --git a/.cursor/skills/review-the-docs b/.cursor/skills/review-the-docs
new file mode 120000
index 0000000000000..49fccdd463dab
--- /dev/null
+++ b/.cursor/skills/review-the-docs
@@ -0,0 +1 @@
+../../.agents/skills/review-the-docs
\ No newline at end of file
diff --git a/.cursor/skills/write-the-docs b/.cursor/skills/write-the-docs
new file mode 120000
index 0000000000000..d647d2d6b8817
--- /dev/null
+++ b/.cursor/skills/write-the-docs
@@ -0,0 +1 @@
+../../.agents/skills/write-the-docs
\ No newline at end of file
diff --git a/apps/docs/CONTRIBUTING.md b/apps/docs/CONTRIBUTING.md
index 3f868c0feb1c1..d7a0dfa8d215d 100644
--- a/apps/docs/CONTRIBUTING.md
+++ b/apps/docs/CONTRIBUTING.md
@@ -19,6 +19,21 @@ To make docs as clear as possible:
 - Avoid using idioms and colloquialisms, such as `piece of cake`. These phrases are often specific to a region or culture.
 - Refer to the reader as `you`. Don't use `we` to refer to the reader. Use `we` only to refer to the Supabase team.
 
+## 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.
+
+Invoke a skill by name: `/write-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 |
+| [`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/`.
+
 ## Document types
 
 Supabase docs contain 4 types of documents. Before you start writing, think about what type of doc you need.

From 77c5a0b9d941bc75719645d9cd0639296ceff586 Mon Sep 17 00:00:00 2001
From: Joshen Lim <joshenlimek@gmail.com>
Date: Thu, 13 Aug 2026 08:44:27 +0700
Subject: [PATCH 2/3] Joshen/fe 4077 explorer query cells (#48989)

## Context

Related to Explorer / Notebooks - adds a barebones query cell that
minimally can run SQL queries + render results

The intention is to migrate the components used in the SQL Editor into
this new Query cell since all the functionality is very similar, but the
SQL Editor component is tightly coupled to the SQL Editor valtio store.
So we'll be duplicating a bit of UI for now - which will also make
deprecating the SQL Editor eventually a bit easier by just deleting them

Have deliberately omitted a lot of details for now just to keep the PRs
small, so will be continuing to build out the QueryCell's functionality
in subsequent PRs. This includes
- Source selector
- Data display (Table / Chart)
- Autolimit logic

Other changes also includes
- Updating NotebookEditor to use the new Explorer UI components that
Saxon introduced

<img width="500" alt="image"
src="https://github.com/user-attachments/assets/d709f6f1-f6cc-4e6a-babd-f5b68bba2a55"
/>
<img width="500" alt="image"
src="https://github.com/user-attachments/assets/a286ceca-ac84-4fbd-afd5-b24f940e2e29"
/>



<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added notebook database cells for writing, editing, and running SQL
queries.
* Added query result displays with loading, empty, error, row-limit, and
result states.
  * Added editable notebook titles with save and cancel controls.
  * New notebooks can start with customizable Markdown and SQL cells.
* Added helpful SQL error actions, including copying messages, database
connection guidance, and AI Assistant support where available.

* **Improvements**
* Improved notebook spacing, section layout, toolbar tooltips, and
empty-result presentation.
  * Markdown changes now save automatically through the notebook editor.
  * Improved drag-and-drop controls and query visibility management.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 .../interfaces/Explorer/ExplorerHome.tsx      |  18 +-
 .../index.tsx => ExplorerQuery.tsx}           |   0
 .../index.tsx => ExplorerToolbar.tsx}         |  92 +++++++--
 .../interfaces/Explorer/MarkdownCell.tsx      |  33 ++-
 .../interfaces/Explorer/NotebookEditor.tsx    | 115 +++--------
 .../interfaces/Explorer/QueryCell/index.tsx   | 171 ++++++++++++++++
 .../interfaces/Explorer/QueryResultTable.tsx  | 188 ++++++++++++++++++
 .../ExplorerQuery.test.tsx                    |   4 +-
 .../ExplorerToolbar.test.tsx                  |  21 +-
 .../components/interfaces/Explorer/hooks.ts   |  60 +++---
 .../components/interfaces/Explorer/types.ts   |   7 +
 .../interfaces/ProjectHome/Home.tsx           |   2 +-
 .../SQLEditor/UtilityPanel/Results.tsx        |   8 +-
 apps/studio/components/ui/SortableSection.tsx |  14 +-
 .../studio/state/notebooks/notebooks-state.ts |  11 +
 15 files changed, 581 insertions(+), 163 deletions(-)
 rename apps/studio/components/interfaces/Explorer/{ExplorerQuery/index.tsx => ExplorerQuery.tsx} (100%)
 rename apps/studio/components/interfaces/Explorer/{ExplorerToolbar/index.tsx => ExplorerToolbar.tsx} (55%)
 create mode 100644 apps/studio/components/interfaces/Explorer/QueryCell/index.tsx
 create mode 100644 apps/studio/components/interfaces/Explorer/QueryResultTable.tsx
 rename apps/studio/components/interfaces/Explorer/{ExplorerQuery => __tests__}/ExplorerQuery.test.tsx (99%)
 rename apps/studio/components/interfaces/Explorer/{ExplorerToolbar => __tests__}/ExplorerToolbar.test.tsx (76%)
 create mode 100644 apps/studio/components/interfaces/Explorer/types.ts

diff --git a/apps/studio/components/interfaces/Explorer/ExplorerHome.tsx b/apps/studio/components/interfaces/Explorer/ExplorerHome.tsx
index 434903793dd90..b26f10ed33ed3 100644
--- a/apps/studio/components/interfaces/Explorer/ExplorerHome.tsx
+++ b/apps/studio/components/interfaces/Explorer/ExplorerHome.tsx
@@ -1,9 +1,11 @@
+import { untrustedSql } from '@supabase/pg-meta'
 import { MessageCirclePlus, NotebookText, SquareCode } from 'lucide-react'
 import { useState } from 'react'
 
 import { useCreateNotebook } from './hooks'
 import { ActionCard } from '@/components/layouts/Tabs/ActionCard'
 import { AssistantChatForm } from '@/components/ui/AIAssistantPanel/AssistantChatForm'
+import { generateUuid } from '@/lib/api/snippets.browser'
 import { AssistantModel } from '@/state/ai-assistant-state'
 
 export const ExplorerHome = () => {
@@ -43,14 +45,26 @@ export const ExplorerHome = () => {
               title="Create a notebook"
               description="Combine notes, queries, and results"
               bgColor="bg-blue-500"
-              onClick={createNotebook}
+              onClick={() => createNotebook()}
             />
             <ActionCard
               icon={<SquareCode className="h-4 w-4 text-foreground" strokeWidth={1.5} />}
               title="Run SQL"
               description="Write and run an ad-hoc query"
               bgColor="bg-blue-500"
-              onClick={onCreateNotebook}
+              onClick={() =>
+                createNotebook({
+                  name: 'SQL query',
+                  cells: [
+                    {
+                      _tag: 'database_cell',
+                      id: generateUuid(),
+                      unchecked_sql: untrustedSql(''),
+                      row_limit: 100,
+                    },
+                  ],
+                })
+              }
             />
           </div>
         </section>
diff --git a/apps/studio/components/interfaces/Explorer/ExplorerQuery/index.tsx b/apps/studio/components/interfaces/Explorer/ExplorerQuery.tsx
similarity index 100%
rename from apps/studio/components/interfaces/Explorer/ExplorerQuery/index.tsx
rename to apps/studio/components/interfaces/Explorer/ExplorerQuery.tsx
diff --git a/apps/studio/components/interfaces/Explorer/ExplorerToolbar/index.tsx b/apps/studio/components/interfaces/Explorer/ExplorerToolbar.tsx
similarity index 55%
rename from apps/studio/components/interfaces/Explorer/ExplorerToolbar/index.tsx
rename to apps/studio/components/interfaces/Explorer/ExplorerToolbar.tsx
index 6b21debb9339c..14e434db48823 100644
--- a/apps/studio/components/interfaces/Explorer/ExplorerToolbar/index.tsx
+++ b/apps/studio/components/interfaces/Explorer/ExplorerToolbar.tsx
@@ -1,5 +1,9 @@
-import React from 'react'
+import { Edit } from 'lucide-react'
+import React, { useState } from 'react'
 import { Button, cn } from 'ui'
+import { Input } from 'ui-patterns/DataInputs/Input'
+
+import { ButtonTooltip } from '@/components/ui/ButtonTooltip'
 
 export type ExplorerToolbarProps = React.ComponentProps<'div'>
 
@@ -15,7 +19,7 @@ const ExplorerToolbar = ({ className, role = 'toolbar', ...props }: ExplorerTool
     data-slot="explorer-toolbar"
     role={role}
     className={cn(
-      'flex h-10 w-full shrink-0 items-center gap-2 border-b bg-transparent px-3 md:min-h-[var(--header-height,2.5rem)]',
+      'flex h-10 w-full shrink-0 items-center gap-2 border-b bg-transparent px-3',
       className
     )}
     {...props}
@@ -40,16 +44,74 @@ const ExplorerToolbarIcon = ({
 )
 ExplorerToolbarIcon.displayName = 'ExplorerToolbarIcon'
 
-export type ExplorerToolbarTitleProps = React.ComponentProps<'div'>
+export type ExplorerToolbarTitleProps = Omit<React.ComponentProps<'div'>, 'children'> & {
+  children: string
+  onSaveTitle?: (value: string) => void
+}
 
 /** Flexible title region for static text or an editable resource name. */
-const ExplorerToolbarTitle = ({ className, ...props }: ExplorerToolbarTitleProps) => (
-  <div
-    data-slot="explorer-toolbar-title"
-    className={cn('min-w-0 flex-1 truncate text-sm', className)}
-    {...props}
-  />
-)
+const ExplorerToolbarTitle = ({
+  children: title,
+  className,
+  onSaveTitle,
+  ...props
+}: ExplorerToolbarTitleProps) => {
+  const [isEditingTitle, setIsEditingTitle] = useState(false)
+  const [value, setValue] = useState(title)
+
+  const handleStartEditing = () => {
+    setValue(title)
+    setIsEditingTitle(true)
+  }
+
+  return (
+    <div
+      data-slot="explorer-toolbar-title"
+      className={cn('min-w-0 flex-1 truncate text-sm', className)}
+      {...props}
+    >
+      {isEditingTitle ? (
+        <Input
+          autoFocus
+          size="tiny"
+          containerClassName="max-w-64 has-[[data-slot=input-group-control]:focus-visible]:ring-0"
+          className="outline-none"
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          onBlur={() => {
+            if (isEditingTitle) {
+              setIsEditingTitle(false)
+              onSaveTitle?.(value)
+            }
+          }}
+          onKeyDown={(e) => {
+            if (e.key === 'Escape') {
+              e.preventDefault()
+              e.stopPropagation()
+              setIsEditingTitle(false)
+            } else if (e.key === 'Enter') {
+              e.preventDefault()
+              e.stopPropagation()
+              setIsEditingTitle(false)
+              onSaveTitle?.(value)
+            }
+          }}
+        />
+      ) : onSaveTitle ? (
+        <Button
+          variant="text"
+          className="group"
+          onClick={handleStartEditing}
+          iconRight={<Edit className="opacity-0 group-hover:opacity-100 transition" />}
+        >
+          {title}
+        </Button>
+      ) : (
+        title
+      )}
+    </div>
+  )
+}
 ExplorerToolbarTitle.displayName = 'ExplorerToolbarTitle'
 
 export type ExplorerToolbarActionsProps = React.ComponentProps<'div'>
@@ -70,7 +132,9 @@ ExplorerToolbarActions.displayName = 'ExplorerToolbarActions'
 export type ExplorerToolbarActionProps = Omit<
   React.ComponentPropsWithRef<typeof Button>,
   'size' | 'variant'
->
+> & {
+  tooltip?: string
+}
 
 /**
  * The standard tiny, text-style button used for a direct toolbar action.
@@ -80,18 +144,20 @@ const ExplorerToolbarAction = ({
   children,
   className,
   ref,
+  tooltip,
   ...props
 }: ExplorerToolbarActionProps) => (
-  <Button
+  <ButtonTooltip
     ref={ref}
     data-slot="explorer-toolbar-action"
     variant="text"
     size="tiny"
     className={cn(children == null && 'w-7 px-0', className)}
+    tooltip={{ content: { side: 'bottom', text: tooltip } }}
     {...props}
   >
     {children}
-  </Button>
+  </ButtonTooltip>
 )
 ExplorerToolbarAction.displayName = 'ExplorerToolbarAction'
 
diff --git a/apps/studio/components/interfaces/Explorer/MarkdownCell.tsx b/apps/studio/components/interfaces/Explorer/MarkdownCell.tsx
index bdcc73f03f935..b08550a4408c6 100644
--- a/apps/studio/components/interfaces/Explorer/MarkdownCell.tsx
+++ b/apps/studio/components/interfaces/Explorer/MarkdownCell.tsx
@@ -8,18 +8,21 @@ import { CodeEditor } from '@/components/ui/CodeEditor/CodeEditor'
 import { SortableSection } from '@/components/ui/SortableSection'
 import { type MarkdownCell as MarkdownCellSchema } from '@/data/content/notebooks/notebook-schema'
 import { useLatest } from '@/hooks/misc/useLatest'
+import { useCurrentNotebook, useNotebooksStateSnapshot } from '@/state/notebooks/notebooks-state'
 
 interface MarkdownCellProps {
   cell: MarkdownCellSchema
-  onCommitChanges: (text: string) => void
 }
 
-export const MarkdownCell = ({ cell, onCommitChanges }: MarkdownCellProps) => {
+export const MarkdownCell = ({ cell }: MarkdownCellProps) => {
+  const snap = useNotebooksStateSnapshot()
+  const currentNotebook = useCurrentNotebook()
+  const cells = currentNotebook?.notebook.content?.cells ?? []
+
   const [value, setValue] = useState(cell.text)
   const [isEditing, setIsEditing] = useState(false)
 
   const valueRef = useLatest(value)
-  const onCommitChangesRef = useLatest(onCommitChanges)
 
   const handleStartEditing = () => {
     setValue(cell.text)
@@ -30,11 +33,17 @@ export const MarkdownCell = ({ cell, onCommitChanges }: MarkdownCellProps) => {
     setIsEditing(false)
   }
 
-  const handleCommit = () => {
-    onCommitChangesRef.current(valueRef.current)
+  const handleUpdateMarkdown = (cellId: string, text: string) => {
+    const notebookId = currentNotebook?.notebook.id
+    if (!notebookId) return
+
+    const nextCells = cells.map((c) => (c.id === cellId ? { ...c, text } : c))
+    snap.updateCells({ id: notebookId, cells: nextCells })
     setIsEditing(false)
   }
 
+  const handleUpdateMarkdownRef = useLatest(handleUpdateMarkdown)
+
   return (
     <SortableSection gripClassName="mt-2.5" id={cell.id}>
       {isEditing ? (
@@ -65,8 +74,12 @@ export const MarkdownCell = ({ cell, onCommitChanges }: MarkdownCellProps) => {
                   '!inlineSuggestionVisible',
                 ].join(' && ')
               )
-              editor.addCommand(monaco.KeyMod.CtrlCmd | monaco.KeyCode.Enter, handleCommit)
-              editor.onDidBlurEditorWidget(handleCommit)
+              editor.addCommand(monaco.KeyMod.CtrlCmd | monaco.KeyCode.Enter, () =>
+                handleUpdateMarkdownRef.current(cell.id, valueRef.current)
+              )
+              editor.onDidBlurEditorWidget(() =>
+                handleUpdateMarkdownRef.current(cell.id, valueRef.current)
+              )
             }}
           />
           <div className="border-t flex items-center justify-between pl-3 pr-1 py-1">
@@ -75,7 +88,11 @@ export const MarkdownCell = ({ cell, onCommitChanges }: MarkdownCellProps) => {
               <Button variant="text" onMouseDown={(e) => e.preventDefault()} onClick={handleCancel}>
                 Cancel
               </Button>
-              <Button variant="text" onMouseDown={(e) => e.preventDefault()} onClick={handleCommit}>
+              <Button
+                variant="text"
+                onMouseDown={(e) => e.preventDefault()}
+                onClick={() => handleUpdateMarkdown(cell.id, value)}
+              >
                 Save
               </Button>
             </div>
diff --git a/apps/studio/components/interfaces/Explorer/NotebookEditor.tsx b/apps/studio/components/interfaces/Explorer/NotebookEditor.tsx
index 11f42cf233c21..bb680a21b1d16 100644
--- a/apps/studio/components/interfaces/Explorer/NotebookEditor.tsx
+++ b/apps/studio/components/interfaces/Explorer/NotebookEditor.tsx
@@ -13,28 +13,30 @@ import {
   verticalListSortingStrategy,
 } from '@dnd-kit/sortable'
 import { useParams } from 'common'
-import { Edit, Notebook, NotebookText, Play, Save } from 'lucide-react'
-import { useEffect, useEffectEvent, useState } from 'react'
+import { Notebook, NotebookText, Play, Save } from 'lucide-react'
+import { useEffect, useEffectEvent } from 'react'
 import { AiIconAnimation, Button } from 'ui'
-import { Input } from 'ui-patterns/DataInputs/Input'
 import { EmptyStatePresentational } from 'ui-patterns/EmptyStatePresentational'
 
+import {
+  ExplorerToolbar,
+  ExplorerToolbarAction,
+  ExplorerToolbarActions,
+  ExplorerToolbarIcon,
+  ExplorerToolbarTitle,
+} from './ExplorerToolbar'
 import { MarkdownCell } from './MarkdownCell'
-import { ButtonTooltip } from '@/components/ui/ButtonTooltip'
-import { useNotebooksStateSnapshot } from '@/state/notebooks/notebooks-state'
+import { QueryCell } from './QueryCell'
+import { useCurrentNotebook, useNotebooksStateSnapshot } from '@/state/notebooks/notebooks-state'
 import { createTabId, useTabsStateSnapshot } from '@/state/tabs'
 
 export const NotebookEditor = () => {
   const { id } = useParams()
   const tabs = useTabsStateSnapshot()
   const snap = useNotebooksStateSnapshot()
-  const stateNotebook = id ? snap.notebooks[id] : undefined
-
-  const { name, content } = stateNotebook?.notebook ?? {}
-
-  const [titleValue, setTitleValue] = useState<string>(name ?? '')
-  const [isEditingTitle, setIsEditingTitle] = useState(false)
 
+  const currentNotebook = useCurrentNotebook()
+  const { name, content } = currentNotebook?.notebook ?? {}
   const cells = content?.cells ?? []
 
   const sensors = useSensors(
@@ -42,20 +44,12 @@ export const NotebookEditor = () => {
     useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates })
   )
 
-  const handleSaveTitle = () => {
+  const handleSaveTitle = (titleValue: string) => {
     const trimmedName = titleValue.trim()
     if (id && trimmedName && trimmedName !== name) {
       snap.renameNotebook({ id, name: trimmedName })
       tabs.updateTab(createTabId('notebook', { id }), { label: trimmedName })
     }
-    setIsEditingTitle(false)
-  }
-
-  const handleUpdateCellText = (cellId: string, text: string) => {
-    if (!id) return
-
-    const nextCells = cells.map((cell) => (cell.id === cellId ? { ...cell, text } : cell))
-    snap.updateCells({ id, cells: nextCells })
   }
 
   const handleDragEnd = (event: DragEndEvent) => {
@@ -84,66 +78,22 @@ export const NotebookEditor = () => {
 
   return (
     <div className="flex flex-col h-full bg-surface-100">
-      <div className="border-b min-h-10 flex items-center justify-between px-4">
-        <div className="flex items-center gap-x-2">
+      <ExplorerToolbar className="px-4">
+        <ExplorerToolbarIcon>
           <NotebookText size={14} className="text-foreground-light" />
-          {isEditingTitle ? (
-            <Input
-              autoFocus
-              size="tiny"
-              value={titleValue}
-              onChange={(e) => setTitleValue(e.target.value)}
-              onBlur={() => {
-                if (isEditingTitle) handleSaveTitle()
-              }}
-              onKeyDown={(e) => {
-                if (e.key === 'Escape') {
-                  e.preventDefault()
-                  e.stopPropagation()
-                  setIsEditingTitle(false)
-                  setTitleValue(name ?? '')
-                } else if (e.key === 'Enter') {
-                  e.preventDefault()
-                  e.stopPropagation()
-                  handleSaveTitle()
-                }
-              }}
-            />
-          ) : (
-            <Button
-              variant="text"
-              className="group"
-              onClick={() => {
-                setTitleValue(name ?? '')
-                setIsEditingTitle(true)
-              }}
-              iconRight={<Edit className="opacity-0 group-hover:opacity-100" />}
-            >
-              {name}
-            </Button>
-          )}
-        </div>
-        <div className="flex items-center gap-x-2">
-          <Button variant="outline" icon={<AiIconAnimation size={16} />}>
+        </ExplorerToolbarIcon>
+        <ExplorerToolbarTitle onSaveTitle={handleSaveTitle}>{name ?? ''}</ExplorerToolbarTitle>
+        <ExplorerToolbarActions>
+          <ExplorerToolbarAction icon={<AiIconAnimation size={16} />}>
             Analyze
-          </Button>
-          <ButtonTooltip
-            variant="outline"
-            icon={<Play />}
-            className="px-1"
-            tooltip={{ content: { side: 'bottom', text: 'Run notebook' } }}
-          />
-          <ButtonTooltip
-            variant="outline"
-            icon={<Save />}
-            className="px-1"
-            tooltip={{ content: { side: 'bottom', text: 'Save changes' } }}
-          />
-        </div>
-      </div>
+          </ExplorerToolbarAction>
+          <ExplorerToolbarAction icon={<Play />} tooltip="Run notebook" />
+          <ExplorerToolbarAction icon={<Save />} tooltip="Save changes" />
+        </ExplorerToolbarActions>
+      </ExplorerToolbar>
 
       <div className="w-full mx-auto flex-grow min-h-0 overflow-y-auto">
-        <div className="p-4">
+        <div className="p-4 pb-10">
           {cells.length === 0 && (
             <EmptyStatePresentational
               icon={<Notebook className="text-foreground-lighter" />}
@@ -163,18 +113,15 @@ export const NotebookEditor = () => {
                 items={cells.map((cell) => cell.id)}
                 strategy={verticalListSortingStrategy}
               >
-                <div className="flex flex-col gap-y-2">
+                <div className="flex flex-col gap-y-3">
                   {cells.map((cell) => {
                     switch (cell._tag) {
                       case 'markdown_cell':
-                        return (
-                          <MarkdownCell
-                            key={cell.id}
-                            cell={cell}
-                            onCommitChanges={(text) => handleUpdateCellText(cell.id, text)}
-                          />
-                        )
+                        return <MarkdownCell key={cell.id} cell={cell} />
+
                       case 'database_cell':
+                        return <QueryCell key={cell.id} cell={cell} />
+
                       case 'log_cell':
                         // [Joshen] Will eventually hook it up
                         return null
diff --git a/apps/studio/components/interfaces/Explorer/QueryCell/index.tsx b/apps/studio/components/interfaces/Explorer/QueryCell/index.tsx
new file mode 100644
index 0000000000000..bc3846d41d8e9
--- /dev/null
+++ b/apps/studio/components/interfaces/Explorer/QueryCell/index.tsx
@@ -0,0 +1,171 @@
+import { acceptUntrustedSql, untrustedSql } from '@supabase/pg-meta'
+import { CodeSquare, Eye, EyeOff, Play, Settings2 } from 'lucide-react'
+import { useState } from 'react'
+import { cn } from 'ui'
+
+import {
+  ExplorerQuery,
+  ExplorerQueryEditor,
+  ExplorerQueryFooter,
+  ExplorerQueryResults,
+} from '../ExplorerQuery'
+import {
+  ExplorerToolbar,
+  ExplorerToolbarAction,
+  ExplorerToolbarActions,
+  ExplorerToolbarIcon,
+  ExplorerToolbarTitle,
+} from '../ExplorerToolbar'
+import { QueryResultTable } from '../QueryResultTable'
+import { type QueryResult } from '../types'
+import { CodeEditor } from '@/components/ui/CodeEditor/CodeEditor'
+import { SortableSection } from '@/components/ui/SortableSection'
+import { type DatabaseCell as DatabaseCellSchema } from '@/data/content/notebooks/notebook-schema'
+import { useExecuteSqlMutation } from '@/data/sql/execute-sql-mutation'
+import { useLatest } from '@/hooks/misc/useLatest'
+import { useSelectedProjectQuery } from '@/hooks/misc/useSelectedProject'
+import { useCurrentNotebook, useNotebooksStateSnapshot } from '@/state/notebooks/notebooks-state'
+import { type ResponseError } from '@/types'
+
+interface QueryCellProps {
+  cell: DatabaseCellSchema
+}
+
+/**
+ * [Joshen] Aiming to keep PRs small so the following are deliberating missing for now:
+ * - Auto limit logic
+ * - Database selection logic
+ * - Data display logic
+ *
+ * QueryCell atm minimally supports running queries and rendering results
+ */
+
+export const QueryCell = ({ cell }: QueryCellProps) => {
+  const snap = useNotebooksStateSnapshot()
+  const currentNotebook = useCurrentNotebook()
+  const { data: project } = useSelectedProjectQuery()
+  const cells = currentNotebook?.notebook.content?.cells ?? []
+
+  const { title = 'Untitled snippet', row_limit } = cell
+
+  const [showQuery, setShowQuery] = useState(true)
+  const [value, setValue] = useState<string>(cell.unchecked_sql)
+  const [result, setResult] = useState<QueryResult>()
+
+  const valueRef = useLatest(value)
+
+  const { mutateAsync: executeQuery, isPending: isExecuting } = useExecuteSqlMutation({
+    onSuccess: (data) =>
+      setResult({
+        rows: data.result,
+        error: undefined,
+        autoLimit: undefined,
+      }),
+    onError: (error) =>
+      setResult({
+        rows: undefined,
+        error: error as unknown as ResponseError,
+        autoLimit: undefined,
+      }),
+  })
+
+  const onRunQuery = async () => {
+    if (!project) return console.error('Project is required')
+
+    handleUpdateCell({ sql: value })
+
+    executeQuery({
+      projectRef: project?.ref,
+      connectionString: project?.connectionString,
+      sql: acceptUntrustedSql(untrustedSql(value)),
+    })
+  }
+
+  const handleUpdateCell = (payload: { sql: string } | { title: string }) => {
+    const notebookId = currentNotebook?.notebook.id
+    if (!notebookId) return
+
+    const nextCells = cells.map((c) => {
+      if (c.id !== cell.id || c._tag !== 'database_cell') {
+        return c
+      }
+
+      if ('sql' in payload) {
+        return { ...c, unchecked_sql: untrustedSql(payload.sql) }
+      }
+
+      const trimmedTitle = payload.title.trim()
+      return trimmedTitle ? { ...c, title: trimmedTitle } : c
+    })
+
+    snap.updateCells({ id: notebookId, cells: nextCells })
+  }
+
+  const handleUpdateCellRef = useLatest(handleUpdateCell)
+
+  return (
+    <SortableSection gripClassName="mt-2.5" id={cell.id}>
+      <ExplorerQuery className="max-w-4xl mx-auto">
+        <ExplorerToolbar>
+          <ExplorerToolbarIcon>
+            <CodeSquare size={14} />
+          </ExplorerToolbarIcon>
+          <ExplorerToolbarTitle onSaveTitle={(newTitle) => handleUpdateCell({ title: newTitle })}>
+            {title}
+          </ExplorerToolbarTitle>
+          <ExplorerToolbarActions>
+            <ExplorerToolbarAction
+              disabled={(result?.rows ?? []).length === 0}
+              icon={<Settings2 />}
+              tooltip="Result settings"
+            />
+            <ExplorerToolbarAction
+              icon={showQuery ? <EyeOff /> : <Eye />}
+              tooltip={showQuery ? 'Hide query' : 'Show query'}
+              onClick={() => setShowQuery((prev) => !prev)}
+            />
+            <ExplorerToolbarAction
+              loading={isExecuting}
+              icon={<Play />}
+              tooltip="Run query"
+              onClick={onRunQuery}
+            />
+          </ExplorerToolbarActions>
+        </ExplorerToolbar>
+
+        {showQuery && (
+          <ExplorerQueryEditor>
+            <CodeEditor
+              language="pgsql"
+              value={value}
+              onInputChange={(v) => setValue(v ?? '')}
+              className="h-32"
+              actions={{ runQuery: { enabled: true, callback: onRunQuery } }}
+              onMount={(editor) => {
+                editor.onDidBlurEditorWidget(() =>
+                  handleUpdateCellRef.current({ sql: valueRef.current })
+                )
+              }}
+            />
+          </ExplorerQueryEditor>
+        )}
+
+        <ExplorerQueryResults
+          className={cn(
+            (result?.rows ?? []).length === 0
+              ? 'flex items-center justify-center'
+              : 'overflow-x-auto'
+          )}
+        >
+          <QueryResultTable result={result} />
+        </ExplorerQueryResults>
+
+        <ExplorerQueryFooter className="flex items-center gap-x-2">
+          <p>{(result?.rows ?? []).length.toLocaleString()} rows</p>
+          <p>·</p>
+          <p>Limit {row_limit} rows</p>
+        </ExplorerQueryFooter>
+      </ExplorerQuery>
+    </SortableSection>
+  )
+}
diff --git a/apps/studio/components/interfaces/Explorer/QueryResultTable.tsx b/apps/studio/components/interfaces/Explorer/QueryResultTable.tsx
new file mode 100644
index 0000000000000..b3aab76c07a2e
--- /dev/null
+++ b/apps/studio/components/interfaces/Explorer/QueryResultTable.tsx
@@ -0,0 +1,188 @@
+import { useParams } from 'common'
+import { ExternalLink } from 'lucide-react'
+import { parseAsBoolean, useQueryState } from 'nuqs'
+import { Button, cn, Tooltip, TooltipContent, TooltipTrigger } from 'ui'
+
+import { subscriptionHasHipaaAddon } from '../Billing/Subscription/Subscription.utils'
+import { Results } from '../SQLEditor/UtilityPanel/Results'
+import { getSqlErrorLines } from '../SQLEditor/UtilityPanel/UtilityTabResults.utils'
+import { type QueryResult } from './types'
+import { AiAssistantDropdown } from '@/components/ui/AiAssistantDropdown'
+import CopyButton from '@/components/ui/CopyButton'
+import { InlineLink, InlineLinkClassName } from '@/components/ui/InlineLink'
+import { useProjectSettingsV2Query } from '@/data/config/project-settings-v2-query'
+import { useOrgSubscriptionQuery } from '@/data/subscriptions/org-subscription-query'
+import { useSelectedOrganizationQuery } from '@/hooks/misc/useSelectedOrganization'
+import { DOCS_URL } from '@/lib/constants'
+
+interface QueryResultTableProps {
+  result?: QueryResult
+}
+
+// [Joshen] This is essentially a duplicate of UtilityTabResults from the SQL Editor
+// I'll eventually migrate the Results component over - just trying to avoid bloating
+// changes wherever possible
+
+export const QueryResultTable = ({ result }: QueryResultTableProps) => {
+  const { rows, error, autoLimit } = result ?? {}
+
+  if (!result) {
+    return <p className="text-xs text-foreground-light">Run the query to see results</p>
+  }
+
+  if (error) {
+    return <QueryError error={error} autoLimit={autoLimit} />
+  }
+
+  if ((rows ?? []).length === 0) {
+    return <p className="text-xs text-foreground-light">Success. No rows returned</p>
+  }
+
+  if (rows && rows.length > 0) {
+    return <QueryResults rows={rows} />
+  }
+}
+
+const QueryError = ({
+  error,
+  autoLimit,
+}: {
+  error: NonNullable<QueryResult['error']>
+  autoLimit?: QueryResult['autoLimit']
+}) => {
+  const { ref } = useParams()
+
+  const { data: org } = useSelectedOrganizationQuery()
+  const { data: subscription } = useOrgSubscriptionQuery({ orgSlug: org?.slug })
+  const { data: projectSettings } = useProjectSettingsV2Query({ projectRef: ref })
+  const hasHipaaAddon = subscriptionHasHipaaAddon(subscription) && projectSettings?.is_sensitive
+
+  const [, setShowConnect] = useQueryState('showConnect', parseAsBoolean.withDefault(false))
+
+  const isTimeout =
+    error.message?.includes('canceling statement due to statement timeout') ||
+    error.message?.includes('upstream request timeout') ||
+    error.message?.includes('Query read timeout')
+  const isNetWorkError = error.message?.includes('EHOSTUNREACH')
+
+  const errorLines = getSqlErrorLines(error)
+  // [Joshen] Need to check if a replica is selected as well
+  const readReplicaError = error.message.includes('in a read-only transaction')
+  const payloadTooLargeError = error.message.includes(
+    'Query is too large to be run via the SQL Editor'
+  )
+
+  return (
+    <div className="bg-table-header-light in-data-[theme*=dark]:bg-table-header-dark overflow-y-auto">
+      <div className="flex flex-row justify-between items-start py-4 px-6 gap-x-4">
+        {isTimeout ? (
+          <div className="flex flex-col gap-y-1">
+            <p className="font-mono text-sm tracking-tight">
+              Error: SQL query ran into an upstream timeout
+            </p>
+            <p className="text-sm text-foreground-light">
+              You can either{' '}
+              <InlineLink
+                href={`${DOCS_URL}/guides/platform/performance#examining-query-performance`}
+              >
+                optimize your query
+              </InlineLink>
+              , or{' '}
+              <InlineLink href={`${DOCS_URL}/guides/database/timeouts`}>
+                increase the statement timeout
+              </InlineLink>
+              {' or '}
+              <button
+                type="button"
+                tabIndex={0}
+                className={cn(InlineLinkClassName, 'cursor-pointer')}
+                onClick={() => setShowConnect(true)}
+              >
+                connect to your database directly
+              </button>
+              .
+            </p>
+          </div>
+        ) : (
+          <div className="flex flex-col gap-y-1">
+            {errorLines.length > 0 ? (
+              errorLines.map((x: string, i: number) => (
+                <pre key={`error-${i}`} className="font-mono text-sm text-wrap">
+                  {x}
+                </pre>
+              ))
+            ) : (
+              <p className="font-mono text-sm tracking-tight">Error: {error.message}</p>
+            )}
+            {!isTimeout && !isNetWorkError && autoLimit && (
+              <p className="text-sm text-foreground-light">
+                Note: A limit of {autoLimit} was applied to your query. If this was the cause of a
+                syntax error, try selecting "No limit" instead and re-run the query.
+              </p>
+            )}
+            {readReplicaError && (
+              <p className="text-sm text-foreground-light">
+                Note: Read replicas are for read only queries. Run write queries on the primary
+                database instead.
+              </p>
+            )}
+            {payloadTooLargeError && (
+              <p className="text-sm text-foreground-light flex items-center gap-x-1">
+                Run this query by{' '}
+                <button
+                  type="button"
+                  tabIndex={0}
+                  onClick={() => setShowConnect(true)}
+                  className={cn(InlineLinkClassName, 'flex items-center gap-x-1')}
+                >
+                  connecting to your database directly
+                  <ExternalLink size={12} />
+                </button>
+                .
+              </p>
+            )}
+          </div>
+        )}
+
+        <div className="flex items-center gap-x-2">
+          {readReplicaError && (
+            <Button
+              className="py-2"
+              variant="default"
+              // [Joshen] TODO
+              onClick={() => {}}
+            >
+              Switch to primary database
+            </Button>
+          )}
+          {errorLines.length > 0 && (
+            <Tooltip>
+              <TooltipTrigger>
+                <CopyButton iconOnly variant="default" text={errorLines.join('\n')} />
+              </TooltipTrigger>
+              <TooltipContent side="bottom" align="center">
+                <span>Copy error</span>
+              </TooltipContent>
+            </Tooltip>
+          )}
+          {!hasHipaaAddon && (
+            // [Joshen] TODO
+            <AiAssistantDropdown
+              telemetrySource="sql_debug"
+              label="Debug with Assistant"
+              buildPrompt={() => ''}
+              onOpenAssistant={() => {}}
+              disabled={false}
+              loading={false}
+            />
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// [Joshen] Eventually migrate the Results component here from SQL Editor
+const QueryResults = ({ rows }: { rows: NonNullable<QueryResult['rows']> }) => {
+  return <Results rows={rows} />
+}
diff --git a/apps/studio/components/interfaces/Explorer/ExplorerQuery/ExplorerQuery.test.tsx b/apps/studio/components/interfaces/Explorer/__tests__/ExplorerQuery.test.tsx
similarity index 99%
rename from apps/studio/components/interfaces/Explorer/ExplorerQuery/ExplorerQuery.test.tsx
rename to apps/studio/components/interfaces/Explorer/__tests__/ExplorerQuery.test.tsx
index f01c68a66e96e..7df4c9fc8e0de 100644
--- a/apps/studio/components/interfaces/Explorer/ExplorerQuery/ExplorerQuery.test.tsx
+++ b/apps/studio/components/interfaces/Explorer/__tests__/ExplorerQuery.test.tsx
@@ -2,14 +2,14 @@ import { render, screen } from '@testing-library/react'
 import { createRef } from 'react'
 import { describe, expect, it } from 'vitest'
 
-import { ExplorerToolbar, ExplorerToolbarTitle } from '../ExplorerToolbar'
 import {
   ExplorerQuery,
   ExplorerQueryEditor,
   ExplorerQueryFooter,
   ExplorerQueryResults,
   ExplorerQueryViewport,
-} from './index'
+} from '../ExplorerQuery'
+import { ExplorerToolbar, ExplorerToolbarTitle } from '../ExplorerToolbar'
 
 describe('ExplorerQuery', () => {
   it('composes the toolbar, editor, results, and footer without owning their behavior', () => {
diff --git a/apps/studio/components/interfaces/Explorer/ExplorerToolbar/ExplorerToolbar.test.tsx b/apps/studio/components/interfaces/Explorer/__tests__/ExplorerToolbar.test.tsx
similarity index 76%
rename from apps/studio/components/interfaces/Explorer/ExplorerToolbar/ExplorerToolbar.test.tsx
rename to apps/studio/components/interfaces/Explorer/__tests__/ExplorerToolbar.test.tsx
index b1cc53ed9220b..6b748059c21ab 100644
--- a/apps/studio/components/interfaces/Explorer/ExplorerToolbar/ExplorerToolbar.test.tsx
+++ b/apps/studio/components/interfaces/Explorer/__tests__/ExplorerToolbar.test.tsx
@@ -1,4 +1,4 @@
-import { render, screen, within } from '@testing-library/react'
+import { screen, within } from '@testing-library/react'
 import { createRef } from 'react'
 import { describe, expect, it } from 'vitest'
 
@@ -8,7 +8,8 @@ import {
   ExplorerToolbarActions,
   ExplorerToolbarIcon,
   ExplorerToolbarTitle,
-} from './index'
+} from '../ExplorerToolbar'
+import { customRender as render } from '@/tests/lib/custom-render'
 
 describe('ExplorerToolbar', () => {
   it('composes the resource icon, title, direct actions, and custom controls', () => {
@@ -65,20 +66,4 @@ describe('ExplorerToolbar', () => {
     expect(action).not.toHaveClass('w-7')
     expect(actionRef.current).toBe(action)
   })
-
-  it('defaults its height but lets a consumer drive it', () => {
-    const { rerender } = render(<ExplorerToolbar aria-label="Default height" />)
-
-    // The header height variable stays consumer-owned, but it carries a fallback
-    // so apps that leave it unset keep the default row instead of an invalid
-    // declaration the browser drops.
-    expect(screen.getByRole('toolbar')).toHaveClass('h-10')
-    expect(screen.getByRole('toolbar').className).toContain('var(--header-height,2.5rem)')
-
-    rerender(<ExplorerToolbar aria-label="Taller height" className="h-12" />)
-
-    const toolbar = screen.getByRole('toolbar')
-    expect(toolbar).toHaveClass('h-12')
-    expect(toolbar).not.toHaveClass('h-10')
-  })
 })
diff --git a/apps/studio/components/interfaces/Explorer/hooks.ts b/apps/studio/components/interfaces/Explorer/hooks.ts
index cdb0f932839e4..4ddb6c9e012d4 100644
--- a/apps/studio/components/interfaces/Explorer/hooks.ts
+++ b/apps/studio/components/interfaces/Explorer/hooks.ts
@@ -1,3 +1,4 @@
+import { untrustedSql } from '@supabase/pg-meta'
 import { useRouter } from 'next/router'
 
 import { useSelectedProjectQuery } from '@/hooks/misc/useSelectedProject'
@@ -5,6 +6,7 @@ import { generateUuid } from '@/lib/api/snippets.browser'
 import { useProfile } from '@/lib/profile'
 import { useNotebooksStateSnapshot } from '@/state/notebooks/notebooks-state'
 import { type Notebook } from '@/state/notebooks/types'
+import { Notebooks } from '@/types'
 
 export const useCreateNotebook = () => {
   const router = useRouter()
@@ -12,10 +14,43 @@ export const useCreateNotebook = () => {
   const { data: project } = useSelectedProjectQuery()
   const notebooksSnap = useNotebooksStateSnapshot()
 
-  const createNotebook = ({ id: idOverride, name }: { id?: string; name?: string } = {}) => {
+  const createNotebook = ({
+    id: idOverride,
+    name,
+    cells,
+  }: { id?: string; name?: string; cells?: Notebooks.Content['cells'] } = {}) => {
     if (!profile) return console.error('Profile is required')
     if (!project) return console.error('Project is required')
 
+    // [Joshen] Just adding sample data to play around with, keep for now - clean up at the end
+    const DEFAULT_CELLS = [
+      {
+        _tag: 'markdown_cell',
+        id: generateUuid(),
+        text: `
+# Title
+A brief description on what this notebook is about
+        `.trim(),
+      },
+      {
+        _tag: 'markdown_cell',
+        id: generateUuid(),
+        text: `
+## Section
+This is a sample paragraph to demonstrate the Markdown cells
+1. List item 1
+2. List item 2
+3. List item 3
+            `,
+      },
+      {
+        _tag: 'database_cell',
+        id: generateUuid(),
+        unchecked_sql: untrustedSql('select * from colors;'),
+        row_limit: 100,
+      },
+    ] as Notebooks.Content['cells']
+
     const id = idOverride ?? generateUuid()
 
     const notebook: Notebook = {
@@ -27,28 +62,7 @@ export const useCreateNotebook = () => {
       favorite: false,
       content: {
         schema_version: 1,
-        // [Joshen] Just adding sample data to play around with, keep for now - clean up at the end
-        cells: [
-          {
-            _tag: 'markdown_cell',
-            id: '1',
-            text: `
-# Title
-A brief description on what this notebook is about
-        `.trim(),
-          },
-          {
-            _tag: 'markdown_cell',
-            id: '2',
-            text: `
-## Section
-This is a sample paragraph to demonstrate the Markdown cells
-1. List item 1
-2. List item 2
-3. List item 3
-            `,
-          },
-        ],
+        cells: cells ?? DEFAULT_CELLS,
       },
       owner_id: profile.id,
       project_id: project.id,
diff --git a/apps/studio/components/interfaces/Explorer/types.ts b/apps/studio/components/interfaces/Explorer/types.ts
new file mode 100644
index 0000000000000..91c1087fd094b
--- /dev/null
+++ b/apps/studio/components/interfaces/Explorer/types.ts
@@ -0,0 +1,7 @@
+import { type ResponseError } from '@/types'
+
+export type QueryResult = {
+  rows?: Record<string, unknown>[]
+  error?: ResponseError
+  autoLimit?: number
+}
diff --git a/apps/studio/components/interfaces/ProjectHome/Home.tsx b/apps/studio/components/interfaces/ProjectHome/Home.tsx
index cde13bf4c2dbc..2935c87695584 100644
--- a/apps/studio/components/interfaces/ProjectHome/Home.tsx
+++ b/apps/studio/components/interfaces/ProjectHome/Home.tsx
@@ -33,7 +33,7 @@ import { IS_PLATFORM, PROJECT_STATUS } from '@/lib/constants'
 import { useTrack } from '@/lib/telemetry/track'
 import { useAppStateSnapshot } from '@/state/app-state'
 
-const SORT_GRIP_CLASS = 'absolute -left-6 top-1.5'
+const SORT_GRIP_CLASS = 'absolute -left-10'
 
 export const ProjectHome = () => {
   const { enableBranching } = useParams()
diff --git a/apps/studio/components/interfaces/SQLEditor/UtilityPanel/Results.tsx b/apps/studio/components/interfaces/SQLEditor/UtilityPanel/Results.tsx
index 393f243f8e032..ec9087f524efa 100644
--- a/apps/studio/components/interfaces/SQLEditor/UtilityPanel/Results.tsx
+++ b/apps/studio/components/interfaces/SQLEditor/UtilityPanel/Results.tsx
@@ -79,11 +79,9 @@ export const Results = ({ rows }: { rows: readonly any[] }) => {
   return (
     <>
       {rows.length === 0 ? (
-        <div className="bg-table-header-light in-data-[theme*=dark]:bg-table-header-dark">
-          <p className="m-0 border-0 px-4 py-3 font-mono text-sm text-foreground-light">
-            Success. No rows returned
-          </p>
-        </div>
+        <p className="px-4 py-3 font-mono text-sm text-foreground-light">
+          Success. No rows returned
+        </p>
       ) : (
         <>
           <ContextMenu modal={false}>
diff --git a/apps/studio/components/ui/SortableSection.tsx b/apps/studio/components/ui/SortableSection.tsx
index 09295a0b94d49..3484e61e49eb3 100644
--- a/apps/studio/components/ui/SortableSection.tsx
+++ b/apps/studio/components/ui/SortableSection.tsx
@@ -1,7 +1,7 @@
 import { useSortable } from '@dnd-kit/sortable'
 import { GripVertical } from 'lucide-react'
 import type { CSSProperties, PropsWithChildren } from 'react'
-import { cn } from 'ui'
+import { Button, cn } from 'ui'
 
 export const SortableSection = ({
   id,
@@ -23,22 +23,22 @@ export const SortableSection = ({
     <div
       ref={setNodeRef}
       style={style}
-      className="relative will-change-transform flex items-start gap-x-2"
+      className="relative will-change-transform flex items-start gap-x-4"
     >
-      <button
+      <Button
         type="button"
+        variant="text"
         aria-label="Drag to reorder section"
         className={cn(
-          'text-foreground-muted hover:text-foreground cursor-grab active:cursor-grabbing',
+          'w-6 text-foreground-muted hover:text-foreground cursor-grab active:cursor-grabbing',
           'rounded-sm focus-ring',
           gripClassName
         )}
         {...attributes}
         {...listeners}
         tabIndex={0}
-      >
-        <GripVertical size={14} />
-      </button>
+        icon={<GripVertical />}
+      />
       <div className={cn('w-full', isDragging && 'opacity-70')}>{children}</div>
     </div>
   )
diff --git a/apps/studio/state/notebooks/notebooks-state.ts b/apps/studio/state/notebooks/notebooks-state.ts
index faf55794eff8c..3f713c147d7f0 100644
--- a/apps/studio/state/notebooks/notebooks-state.ts
+++ b/apps/studio/state/notebooks/notebooks-state.ts
@@ -1,3 +1,4 @@
+import { useParams } from 'common'
 import { useMemo } from 'react'
 import { proxy, snapshot, useSnapshot } from 'valtio'
 import { proxyMap } from 'valtio/utils'
@@ -109,3 +110,13 @@ export const useNotebooks = (projectRef: string) => {
     [projectRef, snapshot.notebooks]
   )
 }
+
+export const useCurrentNotebook = () => {
+  const { id, ref } = useParams()
+  const snapshot = useNotebooksStateSnapshot()
+  const currentNotebook = id ? snapshot.notebooks[id] : undefined
+
+  if (!currentNotebook || currentNotebook.projectRef !== ref) return undefined
+
+  return currentNotebook
+}

From d434c63bada66338f09a764fc06a3e587d02f38e Mon Sep 17 00:00:00 2001
From: Joshen Lim <joshenlimek@gmail.com>
Date: Thu, 13 Aug 2026 10:09:54 +0700
Subject: [PATCH 3/3] joshen/fe 4150 explorer query cells result display
 settings (#49003)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Context

Related to Explorer / Notebooks - this adds chart functionality for the
Query cells
<img width="250" alt="image"
src="https://github.com/user-attachments/assets/4ea37c14-87dc-4c43-ba7f-cb9436085c81"
/>

Query results can be rendered as either bar or line chart - using the
chart packages from `ui-patterns`
[NOTE]: For design team reviewers - am patching the chart packages to be
agnostic to the `timestamp` property within the provided data set. Would
love to use this component from a consistency POV instead of the old
`BarChart` component we have.

Have intentionally omitted log scale functionality from this PR - will
have that separately 🙏

<img width="999" height="483" alt="image"
src="https://github.com/user-attachments/assets/14356ee4-c658-4fd1-90e0-17c38dac4822"
/>
<img width="988" height="478" alt="image"
src="https://github.com/user-attachments/assets/cd0ca088-9a03-4aa3-9884-17bc36d3cabf"
/>



<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Added chart views for notebook query results, including bar and line
charts.
- Added display settings for selecting X/Y columns, chart type, scale,
cumulative values, and label visibility.
  - Added configurable X-axis support for charts.
  - Display preferences are saved with each notebook cell.

- **Improvements**
  - New database cells default to table view.
  - Chart results better handle varied data types.
- Empty results and incomplete chart settings now display clear
placeholders.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---
 .../QueryCell/DisplaySettingsButton.tsx       | 225 ++++++++++++++++++
 .../Explorer/QueryCell/QueryResultChart.tsx   |  96 ++++++++
 .../interfaces/Explorer/QueryCell/index.tsx   |  21 +-
 .../interfaces/Explorer/QueryResultTable.tsx  |   2 +
 .../components/interfaces/Explorer/hooks.ts   |   2 +
 .../ui/QueryBlock/QueryBlock.utils.ts         |   7 +-
 .../data/content/notebooks/notebook-schema.ts |   6 +-
 apps/studio/lib/ai/tools/mock-tools.ts        |   9 +-
 .../studio/state/notebooks/notebooks-state.ts |   6 +-
 .../ui/QueryBlock/QueryBlock.utils.test.ts    |  18 +-
 .../src/Chart/charts/chart-bar.tsx            |  51 ++--
 .../src/Chart/charts/chart-line.tsx           |  51 ++--
 12 files changed, 428 insertions(+), 66 deletions(-)
 create mode 100644 apps/studio/components/interfaces/Explorer/QueryCell/DisplaySettingsButton.tsx
 create mode 100644 apps/studio/components/interfaces/Explorer/QueryCell/QueryResultChart.tsx

diff --git a/apps/studio/components/interfaces/Explorer/QueryCell/DisplaySettingsButton.tsx b/apps/studio/components/interfaces/Explorer/QueryCell/DisplaySettingsButton.tsx
new file mode 100644
index 0000000000000..96460ec03ec24
--- /dev/null
+++ b/apps/studio/components/interfaces/Explorer/QueryCell/DisplaySettingsButton.tsx
@@ -0,0 +1,225 @@
+import { BarChart2, Settings2, Table } from 'lucide-react'
+import {
+  Checkbox,
+  Popover,
+  PopoverContent,
+  PopoverSeparator,
+  PopoverTrigger,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  ToggleGroup,
+  ToggleGroupItem,
+} from 'ui'
+import { FormItemLayout } from 'ui-patterns/form/FormItemLayout/FormItemLayout'
+import { type Snapshot } from 'valtio'
+
+import { ExplorerToolbarAction } from '../ExplorerToolbar'
+import { type DatabaseCell as DatabaseCellSchema } from '@/data/content/notebooks/notebook-schema'
+import { useCurrentNotebook, useNotebooksStateSnapshot } from '@/state/notebooks/notebooks-state'
+
+interface DisplaySettingsButtonProps {
+  cell: Snapshot<DatabaseCellSchema>
+  columns: string[]
+  disabled: boolean
+}
+
+// [Joshen] TODO support multiple y axis charts
+
+export const DisplaySettingsButton = ({ cell, columns, disabled }: DisplaySettingsButtonProps) => {
+  const snap = useNotebooksStateSnapshot()
+  const currentNotebook = useCurrentNotebook()
+  const cells = currentNotebook?.notebook.content?.cells ?? []
+
+  const { view, chart } = cell
+  const {
+    type = 'bar',
+    x_column,
+    y_columns,
+    cumulative = false,
+    show_labels = false,
+    scale = 'linear',
+  } = chart ?? {}
+
+  const onChangeView = (view: 'table' | 'chart') => {
+    const notebookId = currentNotebook?.notebook.id
+    if (!notebookId) return
+
+    const nextCells = cells.map((c) =>
+      c.id === cell.id && c._tag === 'database_cell' ? { ...c, view } : c
+    )
+    snap.updateCells({ id: notebookId, cells: nextCells })
+  }
+
+  const onUpdateChartConfig = (
+    payload:
+      | { type: 'bar' | 'line' }
+      | { x_column: string }
+      | { y_columns: string[] }
+      | { cumulative: boolean }
+      | { show_labels: boolean }
+      | { scale: 'linear' | 'log' }
+  ) => {
+    const notebookId = currentNotebook?.notebook.id
+    if (!notebookId) return
+
+    const nextCells = cells.map((c) => {
+      if (c.id !== cell.id || c._tag !== 'database_cell') return c
+
+      return {
+        ...c,
+        chart: {
+          type: c.chart?.type ?? 'bar',
+          x_column: c.chart?.x_column ?? '',
+          y_columns: c.chart?.y_columns ?? [],
+          cumulative: c.chart?.cumulative ?? false,
+          scale: c.chart?.scale ?? 'linear',
+          show_labels: c.chart?.show_labels ?? false,
+          ...payload,
+        },
+      }
+    })
+    snap.updateCells({ id: notebookId, cells: nextCells })
+  }
+
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <ExplorerToolbarAction disabled={disabled} icon={<Settings2 />} tooltip="Result settings" />
+      </PopoverTrigger>
+      <PopoverContent side="bottom" className="flex flex-col gap-y-3 p-0 py-3">
+        <div className="flex flex-col gap-y-3 px-3">
+          <p className="text-xs tracking-tighter uppercase font-mono text-foreground-lighter">
+            Result display settings
+          </p>
+
+          <FormItemLayout isReactForm={false} label="View data as">
+            <ToggleGroup
+              value={view}
+              onValueChange={(value) => {
+                if (value === 'table' || value === 'chart') onChangeView(value)
+              }}
+              variant="outline"
+              type="single"
+            >
+              <ToggleGroupItem value="table" className="w-full gap-x-2 data-[state=on]:bg-accent">
+                <Table size={14} />
+                <p>Table</p>
+              </ToggleGroupItem>
+              <ToggleGroupItem value="chart" className="w-full gap-x-2 data-[state=on]:bg-accent">
+                <BarChart2 size={14} />
+                <p>Chart</p>
+              </ToggleGroupItem>
+            </ToggleGroup>
+          </FormItemLayout>
+        </div>
+
+        {view === 'chart' && (
+          <>
+            <PopoverSeparator />
+
+            <FormItemLayout isReactForm={false} label="Render chart as" className="px-3 mb-1">
+              <ToggleGroup
+                value={type}
+                onValueChange={(value) => {
+                  if (value === 'bar' || value === 'line') onUpdateChartConfig({ type: value })
+                }}
+                variant="outline"
+                type="single"
+              >
+                <ToggleGroupItem value="bar" className="w-full data-[state=on]:bg-accent">
+                  Bar
+                </ToggleGroupItem>
+                <ToggleGroupItem value="line" className="w-full data-[state=on]:bg-accent">
+                  Line
+                </ToggleGroupItem>
+              </ToggleGroup>
+            </FormItemLayout>
+
+            <div className="px-3 flex flex-col gap-y-2">
+              <FormItemLayout isReactForm={false} layout="flex-row-reverse" label="X axis">
+                <Select
+                  value={x_column}
+                  onValueChange={(x_column) => onUpdateChartConfig({ x_column })}
+                >
+                  <SelectTrigger className="w-32">
+                    <SelectValue placeholder="Select a column" />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {columns.map((x) => (
+                      <SelectItem key={x} value={x}>
+                        {x}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </FormItemLayout>
+
+              <FormItemLayout isReactForm={false} layout="flex-row-reverse" label="Y Axis">
+                <Select
+                  value={y_columns?.[0]}
+                  onValueChange={(y_column) => onUpdateChartConfig({ y_columns: [y_column] })}
+                >
+                  <SelectTrigger className="w-32">
+                    <SelectValue placeholder="Select a column" />
+                  </SelectTrigger>
+                  <SelectContent>
+                    {columns.map((x) => (
+                      <SelectItem key={x} value={x}>
+                        {x}
+                      </SelectItem>
+                    ))}
+                  </SelectContent>
+                </Select>
+              </FormItemLayout>
+
+              <FormItemLayout isReactForm={false} layout="flex-row-reverse" label="Scale">
+                <Select
+                  value={scale}
+                  onValueChange={(scale) =>
+                    onUpdateChartConfig({ scale: scale as 'log' | 'linear' })
+                  }
+                >
+                  <SelectTrigger className="w-32">
+                    <SelectValue placeholder="Select a column" />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="linear">Linear</SelectItem>
+                    <SelectItem value="log">Logarithmic</SelectItem>
+                  </SelectContent>
+                </Select>
+              </FormItemLayout>
+
+              <FormItemLayout id="cumulative" isReactForm={false} layout="flex" label="Cumulative">
+                <Checkbox
+                  id="cumulative"
+                  checked={cumulative}
+                  onCheckedChange={(cumulative) =>
+                    onUpdateChartConfig({ cumulative: Boolean(cumulative) })
+                  }
+                />
+              </FormItemLayout>
+
+              <FormItemLayout
+                id="show_labels"
+                isReactForm={false}
+                layout="flex"
+                label="Show labels"
+              >
+                <Checkbox
+                  id="show_labels"
+                  checked={show_labels}
+                  onCheckedChange={(show_labels) =>
+                    onUpdateChartConfig({ show_labels: Boolean(show_labels) })
+                  }
+                />
+              </FormItemLayout>
+            </div>
+          </>
+        )}
+      </PopoverContent>
+    </Popover>
+  )
+}
diff --git a/apps/studio/components/interfaces/Explorer/QueryCell/QueryResultChart.tsx b/apps/studio/components/interfaces/Explorer/QueryCell/QueryResultChart.tsx
new file mode 100644
index 0000000000000..8f6db1ffc8c47
--- /dev/null
+++ b/apps/studio/components/interfaces/Explorer/QueryCell/QueryResultChart.tsx
@@ -0,0 +1,96 @@
+import { useMemo } from 'react'
+import { Chart, ChartBar, ChartCard, ChartContent, ChartLine } from 'ui-patterns/Chart'
+import { type Snapshot } from 'valtio'
+
+import { type QueryResult } from '../types'
+import NoDataPlaceholder from '@/components/ui/Charts/NoDataPlaceholder'
+import { getCumulativeResults } from '@/components/ui/QueryBlock/QueryBlock.utils'
+import { type DatabaseCell as DatabaseCellSchema } from '@/data/content/notebooks/notebook-schema'
+
+interface QueryResultChartProps {
+  cell: Snapshot<DatabaseCellSchema>
+  result?: QueryResult
+}
+
+// [Joshen] Will need to implement log scale - refer to QueryBlock.tsx `effectiveLogScale`
+// [Joshen] Will also need to implement error handling where appropriate (e.g if query errors)
+
+const toChartValue = (value: unknown): string | number => {
+  if (typeof value === 'number' || typeof value === 'string') return value
+  if (value === null || value === undefined) return ''
+  return String(value)
+}
+
+export const QueryResultChart = ({ cell, result }: QueryResultChartProps) => {
+  const { chart } = cell
+  const { type, x_column, y_columns = [], cumulative, show_labels } = chart ?? {}
+
+  const hasConfig = !!x_column && y_columns.length > 0
+  const chartRows = useMemo(() => {
+    const xKey = x_column ?? ''
+    const yKey = y_columns[0] ?? ''
+    return (result?.rows ?? []).map((row) => ({
+      [xKey]: toChartValue(row[xKey]),
+      [yKey]: toChartValue(row[yKey]),
+    }))
+  }, [result, x_column, y_columns])
+
+  const cumulativeResults = useMemo(
+    () => getCumulativeResults({ rows: chartRows }, { yKey: y_columns[0] ?? '' }),
+    [chartRows, y_columns]
+  )
+  const resultToRender = cumulative ? cumulativeResults : chartRows
+
+  if (!result || (result?.rows && result.rows.length === 0)) {
+    return (
+      <NoDataPlaceholder
+        className="bg border-0"
+        size="normal"
+        message="No results"
+        description="Your query returned no rows"
+      />
+    )
+  }
+
+  if (!hasConfig) {
+    return (
+      <NoDataPlaceholder
+        className="bg border-0"
+        size="normal"
+        message="Configure your chart"
+        description="Select your X and Y axis in the display settings"
+      />
+    )
+  }
+
+  return (
+    <Chart>
+      <ChartCard className="rounded-none border-0">
+        <ChartContent>
+          <div className="h-40">
+            {type === 'bar' && (
+              <ChartBar
+                isFullHeight
+                xKey={x_column}
+                dataKey={y_columns[0]}
+                showXAxis={show_labels}
+                showYAxis={show_labels}
+                data={resultToRender}
+              />
+            )}
+            {type === 'line' && (
+              <ChartLine
+                isFullHeight
+                xKey={x_column}
+                dataKey={y_columns[0]}
+                showXAxis={show_labels}
+                showYAxis={show_labels}
+                data={resultToRender}
+              />
+            )}
+          </div>
+        </ChartContent>
+      </ChartCard>
+    </Chart>
+  )
+}
diff --git a/apps/studio/components/interfaces/Explorer/QueryCell/index.tsx b/apps/studio/components/interfaces/Explorer/QueryCell/index.tsx
index bc3846d41d8e9..bf225ba54c55a 100644
--- a/apps/studio/components/interfaces/Explorer/QueryCell/index.tsx
+++ b/apps/studio/components/interfaces/Explorer/QueryCell/index.tsx
@@ -1,7 +1,8 @@
 import { acceptUntrustedSql, untrustedSql } from '@supabase/pg-meta'
-import { CodeSquare, Eye, EyeOff, Play, Settings2 } from 'lucide-react'
+import { CodeSquare, Eye, EyeOff, Play } from 'lucide-react'
 import { useState } from 'react'
 import { cn } from 'ui'
+import { type Snapshot } from 'valtio'
 
 import {
   ExplorerQuery,
@@ -18,6 +19,8 @@ import {
 } from '../ExplorerToolbar'
 import { QueryResultTable } from '../QueryResultTable'
 import { type QueryResult } from '../types'
+import { DisplaySettingsButton } from './DisplaySettingsButton'
+import { QueryResultChart } from './QueryResultChart'
 import { CodeEditor } from '@/components/ui/CodeEditor/CodeEditor'
 import { SortableSection } from '@/components/ui/SortableSection'
 import { type DatabaseCell as DatabaseCellSchema } from '@/data/content/notebooks/notebook-schema'
@@ -28,7 +31,7 @@ import { useCurrentNotebook, useNotebooksStateSnapshot } from '@/state/notebooks
 import { type ResponseError } from '@/types'
 
 interface QueryCellProps {
-  cell: DatabaseCellSchema
+  cell: Snapshot<DatabaseCellSchema>
 }
 
 /**
@@ -46,11 +49,12 @@ export const QueryCell = ({ cell }: QueryCellProps) => {
   const { data: project } = useSelectedProjectQuery()
   const cells = currentNotebook?.notebook.content?.cells ?? []
 
-  const { title = 'Untitled snippet', row_limit } = cell
+  const { title = 'Untitled snippet', row_limit, view } = cell
 
   const [showQuery, setShowQuery] = useState(true)
   const [value, setValue] = useState<string>(cell.unchecked_sql)
   const [result, setResult] = useState<QueryResult>()
+  const columns = Object.keys(result?.rows?.[0] ?? {})
 
   const valueRef = useLatest(value)
 
@@ -114,10 +118,10 @@ export const QueryCell = ({ cell }: QueryCellProps) => {
             {title}
           </ExplorerToolbarTitle>
           <ExplorerToolbarActions>
-            <ExplorerToolbarAction
+            <DisplaySettingsButton
+              cell={cell}
+              columns={columns}
               disabled={(result?.rows ?? []).length === 0}
-              icon={<Settings2 />}
-              tooltip="Result settings"
             />
             <ExplorerToolbarAction
               icon={showQuery ? <EyeOff /> : <Eye />}
@@ -152,12 +156,13 @@ export const QueryCell = ({ cell }: QueryCellProps) => {
 
         <ExplorerQueryResults
           className={cn(
-            (result?.rows ?? []).length === 0
+            (result?.rows ?? []).length === 0 && view === 'table'
               ? 'flex items-center justify-center'
               : 'overflow-x-auto'
           )}
         >
-          <QueryResultTable result={result} />
+          {view === 'table' && <QueryResultTable result={result} />}
+          {view === 'chart' && <QueryResultChart cell={cell} result={result} />}
         </ExplorerQueryResults>
 
         <ExplorerQueryFooter className="flex items-center gap-x-2">
diff --git a/apps/studio/components/interfaces/Explorer/QueryResultTable.tsx b/apps/studio/components/interfaces/Explorer/QueryResultTable.tsx
index b3aab76c07a2e..ba88cb1d27424 100644
--- a/apps/studio/components/interfaces/Explorer/QueryResultTable.tsx
+++ b/apps/studio/components/interfaces/Explorer/QueryResultTable.tsx
@@ -23,6 +23,8 @@ interface QueryResultTableProps {
 // I'll eventually migrate the Results component over - just trying to avoid bloating
 // changes wherever possible
 
+// [Joshen] Should be shifted into QueryCell folder
+
 export const QueryResultTable = ({ result }: QueryResultTableProps) => {
   const { rows, error, autoLimit } = result ?? {}
 
diff --git a/apps/studio/components/interfaces/Explorer/hooks.ts b/apps/studio/components/interfaces/Explorer/hooks.ts
index 4ddb6c9e012d4..d4eedf60c547a 100644
--- a/apps/studio/components/interfaces/Explorer/hooks.ts
+++ b/apps/studio/components/interfaces/Explorer/hooks.ts
@@ -46,6 +46,8 @@ This is a sample paragraph to demonstrate the Markdown cells
       {
         _tag: 'database_cell',
         id: generateUuid(),
+        view: 'table',
+        chart: undefined,
         unchecked_sql: untrustedSql('select * from colors;'),
         row_limit: 100,
       },
diff --git a/apps/studio/components/ui/QueryBlock/QueryBlock.utils.ts b/apps/studio/components/ui/QueryBlock/QueryBlock.utils.ts
index 342f5b17a60c9..8a18bde468862 100644
--- a/apps/studio/components/ui/QueryBlock/QueryBlock.utils.ts
+++ b/apps/studio/components/ui/QueryBlock/QueryBlock.utils.ts
@@ -1,5 +1,3 @@
-import type { ChartConfig } from '@/components/interfaces/SQLEditor/UtilityPanel/ChartConfig'
-
 export const checkHasNonPositiveValues = (data: Record<string, unknown>[], key: string): boolean =>
   data.some((row) => (row[key] as number) <= 0)
 
@@ -47,7 +45,10 @@ export const formatLogTick = (value: number): string => {
   return value.toLocaleString()
 }
 
-export const getCumulativeResults = (results: { rows: readonly any[] }, config: ChartConfig) => {
+export const getCumulativeResults = (
+  results: { rows: readonly any[] },
+  config: { yKey: string }
+) => {
   if (!results?.rows?.length) {
     return []
   }
diff --git a/apps/studio/data/content/notebooks/notebook-schema.ts b/apps/studio/data/content/notebooks/notebook-schema.ts
index ada1639c751a7..545267b75e9b9 100644
--- a/apps/studio/data/content/notebooks/notebook-schema.ts
+++ b/apps/studio/data/content/notebooks/notebook-schema.ts
@@ -14,9 +14,12 @@ const isoDateTimeSchema = z.string().transform((raw, ctx) => {
 })
 
 const chartConfigSchema = z.object({
+  type: z.enum(['bar', 'line']),
   x_column: z.string(),
-  y_column: z.string(),
+  y_columns: z.array(z.string()),
   cumulative: z.boolean(),
+  scale: z.enum(['linear', 'log']).default('linear'),
+  show_labels: z.boolean(),
 })
 
 const absoluteTimeRangeSchema = z.object({
@@ -48,6 +51,7 @@ const databaseCellSchema = z.object({
   title: z.string().optional(),
   sql: z.string(),
   row_limit: z.number(),
+  view: z.enum(['table', 'chart']).default('table').optional(),
   chart: chartConfigSchema.optional(),
 })
 
diff --git a/apps/studio/lib/ai/tools/mock-tools.ts b/apps/studio/lib/ai/tools/mock-tools.ts
index 2ceb1b452b226..a5fc459e8142c 100644
--- a/apps/studio/lib/ai/tools/mock-tools.ts
+++ b/apps/studio/lib/ai/tools/mock-tools.ts
@@ -187,7 +187,14 @@ export const MOCK_NOTEBOOKS_DATA: MockNotebook[] = [
           title: 'Signups per day',
           sql: "select date_trunc('day', created_at) as day, count(*) as signups\nfrom auth.users\ngroup by day\norder by day desc",
           row_limit: 30,
-          chart: { x_column: 'day', y_column: 'signups', cumulative: false },
+          chart: {
+            x_column: 'day',
+            y_columns: ['signups'],
+            cumulative: false,
+            type: 'line',
+            scale: 'log',
+            show_labels: false,
+          },
         },
         {
           _tag: 'log_cell',
diff --git a/apps/studio/state/notebooks/notebooks-state.ts b/apps/studio/state/notebooks/notebooks-state.ts
index 3f713c147d7f0..f9f3054d93498 100644
--- a/apps/studio/state/notebooks/notebooks-state.ts
+++ b/apps/studio/state/notebooks/notebooks-state.ts
@@ -1,6 +1,6 @@
 import { useParams } from 'common'
 import { useMemo } from 'react'
-import { proxy, snapshot, useSnapshot } from 'valtio'
+import { proxy, snapshot, useSnapshot, type Snapshot } from 'valtio'
 import { proxyMap } from 'valtio/utils'
 
 import type { Notebook, StateNotebook } from './types'
@@ -82,12 +82,12 @@ export const notebooksState = proxy({
     skipSave,
   }: {
     id: string
-    cells: Notebooks.Cell[]
+    cells: Snapshot<Notebooks.Cell>[]
     skipSave?: boolean
   }) => {
     const stateNotebook = notebooksState.notebooks[id]
     if (!stateNotebook?.notebook.content) return
-    stateNotebook.notebook.content.cells = cells
+    stateNotebook.notebook.content.cells = cells as Notebooks.Cell[]
     stateNotebook.status = statusOnEdit(stateNotebook.status)
     if (!skipSave) notebooksState.needsSaving.set(id, false)
   },
diff --git a/apps/studio/tests/components/ui/QueryBlock/QueryBlock.utils.test.ts b/apps/studio/tests/components/ui/QueryBlock/QueryBlock.utils.test.ts
index b48ad9aafafd3..a5af0a97f5480 100644
--- a/apps/studio/tests/components/ui/QueryBlock/QueryBlock.utils.test.ts
+++ b/apps/studio/tests/components/ui/QueryBlock/QueryBlock.utils.test.ts
@@ -78,25 +78,11 @@ describe('formatLogTick', () => {
 
 describe('getCumulativeResults', () => {
   it('returns empty array when results are empty', () => {
-    expect(
-      getCumulativeResults(
-        { rows: [] },
-        { type: 'bar', xKey: 'x', yKey: 'y', cumulative: false, showLabels: false, showGrid: false }
-      )
-    ).toEqual([])
+    expect(getCumulativeResults({ rows: [] }, { yKey: 'y' })).toEqual([])
   })
 
   it('returns empty array when results are undefined', () => {
-    expect(
-      getCumulativeResults(undefined as any, {
-        type: 'bar',
-        xKey: 'x',
-        yKey: 'y',
-        cumulative: false,
-        showLabels: false,
-        showGrid: false,
-      })
-    ).toEqual([])
+    expect(getCumulativeResults(undefined as any, { yKey: 'y' })).toEqual([])
   })
 
   it('accumulates yKey values across rows', () => {
diff --git a/packages/ui-patterns/src/Chart/charts/chart-bar.tsx b/packages/ui-patterns/src/Chart/charts/chart-bar.tsx
index c9de5ef6acf16..79c0f16f512ea 100644
--- a/packages/ui-patterns/src/Chart/charts/chart-bar.tsx
+++ b/packages/ui-patterns/src/Chart/charts/chart-bar.tsx
@@ -22,10 +22,14 @@ const CHART_COLORS = {
   BRAND_HOVER: 'hsl(var(--brand-500))',
 }
 
-export type ChartBarTick = {
-  timestamp: string
-  [key: string]: string | number
-}
+export type ChartBarTick =
+  | {
+      timestamp: string
+      [key: string]: string | number
+    }
+  | {
+      [key: string]: string | number
+    }
 
 export type ChartHighlight = {
   handleMouseDown: (e: { activeLabel?: string; coordinates?: string }) => void
@@ -45,6 +49,7 @@ export type ChartHighlightAction = {
 
 export interface ChartBarProps {
   data: ChartBarTick[]
+  xKey?: string
   dataKey: string
   config?: ChartConfig
   onBarClick?: (datum: ChartBarTick, tooltipData?: CategoricalChartState) => void
@@ -59,6 +64,7 @@ export interface ChartBarProps {
   cursor?: string
   showGrid?: boolean
   showYAxis?: boolean
+  showXAxis?: boolean
   YAxisProps?: {
     tick?: boolean
     tickFormatter?: (value: any) => string
@@ -69,6 +75,7 @@ export interface ChartBarProps {
 
 export const ChartBar = ({
   data,
+  xKey = 'timestamp',
   dataKey,
   config,
   onBarClick,
@@ -83,6 +90,7 @@ export const ChartBar = ({
   cursor,
   showGrid = false,
   showYAxis = false,
+  showXAxis = false,
   YAxisProps,
 }: ChartBarProps) => {
   const [focusDataIndex, setFocusDataIndex] = useState<number | null>(null)
@@ -107,6 +115,18 @@ export const ChartBar = ({
 
   const chartCursor = cursor || (chartHighlight ? 'crosshair' : 'default')
 
+  const xAxisConfig = {
+    angle: 0,
+    dataKey: xKey,
+    tick: showXAxis
+      ? { fill: 'var(--color-foreground-lighter)', fontSize: 10, fontFamily: 'var(--font-mono)' }
+      : false,
+    hide: !showXAxis,
+    interval: 'preserveStartEnd' as const,
+    axisLine: { stroke: CHART_COLORS.AXIS },
+    tickLine: { stroke: CHART_COLORS.AXIS },
+  }
+
   const yAxisConfig = {
     tick: showYAxis
       ? { fill: 'var(--color-foreground-lighter)', fontSize: 10, fontFamily: 'var(--font-mono)' }
@@ -143,7 +163,7 @@ export const ChartBar = ({
             }
 
             if (chartHighlight) {
-              const activeTimestamp = data[e.activeTooltipIndex]?.timestamp
+              const activeTimestamp = data[e.activeTooltipIndex]?.[xKey]
               chartHighlight.handleMouseMove({
                 activeLabel: activeTimestamp?.toString(),
                 coordinates: e.activeLabel,
@@ -152,7 +172,7 @@ export const ChartBar = ({
           }}
           onMouseDown={(e: any) => {
             if (chartHighlight && e.activeTooltipIndex !== undefined) {
-              const activeTimestamp = data[e.activeTooltipIndex]?.timestamp
+              const activeTimestamp = data[e.activeTooltipIndex]?.[xKey]
               chartHighlight.handleMouseDown({
                 activeLabel: activeTimestamp?.toString(),
                 coordinates: e.activeLabel,
@@ -180,18 +200,14 @@ export const ChartBar = ({
         >
           {showGrid && <CartesianGrid vertical={false} stroke={CHART_COLORS.AXIS} />}
           <YAxis {...yAxisConfig} />
-          <XAxis
-            dataKey="timestamp"
-            interval={data.length - 2}
-            tick={false}
-            axisLine={{ stroke: CHART_COLORS.AXIS }}
-            tickLine={{ stroke: CHART_COLORS.AXIS }}
-          />
+          <XAxis {...xAxisConfig} />
           <ChartTooltip
             content={
               <ChartTooltipContent
                 className="text-foreground-light -mt-5"
-                labelFormatter={(v: string) => dayjs(v).format(DateTimeFormat)}
+                labelFormatter={(v: string) =>
+                  xKey === 'timestamp' ? dayjs(v).format(DateTimeFormat) : 'Value'
+                }
               />
             }
           />
@@ -217,10 +233,11 @@ export const ChartBar = ({
           </Bar>
         </RechartBarChart>
       </ChartContainer>
-      {data && data.length > 0 && (
+
+      {xKey === 'timestamp' && data && data.length > 0 && (
         <div className="text-foreground-lighter -mt-6 flex items-center justify-between text-[10px] font-mono">
-          <span>{dayjs(data[0]['timestamp']).format(DateTimeFormat)}</span>
-          <span>{dayjs(data[data.length - 1]?.['timestamp']).format(DateTimeFormat)}</span>
+          <span>{dayjs(data[0][xKey]).format(DateTimeFormat)}</span>
+          <span>{dayjs(data[data.length - 1]?.[xKey]).format(DateTimeFormat)}</span>
         </div>
       )}
     </div>
diff --git a/packages/ui-patterns/src/Chart/charts/chart-line.tsx b/packages/ui-patterns/src/Chart/charts/chart-line.tsx
index 2ecfa7424748d..1811933d845a0 100644
--- a/packages/ui-patterns/src/Chart/charts/chart-line.tsx
+++ b/packages/ui-patterns/src/Chart/charts/chart-line.tsx
@@ -22,10 +22,14 @@ const CHART_COLORS = {
   BRAND_HOVER: 'hsl(var(--brand-500))',
 }
 
-export type ChartLineTick = {
-  timestamp: string
-  [key: string]: string | number
-}
+export type ChartLineTick =
+  | {
+      timestamp: string
+      [key: string]: string | number
+    }
+  | {
+      [key: string]: string | number
+    }
 
 export type ChartHighlight = {
   handleMouseDown: (e: { activeLabel?: string; coordinates?: string }) => void
@@ -53,6 +57,7 @@ export type ChartReferenceLine = {
 
 export interface ChartLineProps {
   data: ChartLineTick[]
+  xKey?: string
   dataKey: string
   dataKeys?: string[]
   config?: ChartConfig
@@ -67,6 +72,7 @@ export interface ChartLineProps {
   showHighlightArea?: boolean
   cursor?: string
   showGrid?: boolean
+  showXAxis?: boolean
   showYAxis?: boolean
   YAxisProps?: {
     tick?: boolean
@@ -80,6 +86,7 @@ export interface ChartLineProps {
 
 export const ChartLine = ({
   data,
+  xKey = 'timestamp',
   dataKey,
   dataKeys,
   config,
@@ -94,6 +101,7 @@ export const ChartLine = ({
   showHighlightArea = true,
   cursor,
   showGrid = false,
+  showXAxis = false,
   showYAxis = false,
   YAxisProps,
   strokeWidth = 1.5,
@@ -124,6 +132,18 @@ export const ChartLine = ({
 
   const chartCursor = cursor || (chartHighlight ? 'crosshair' : 'default')
 
+  const xAxisConfig = {
+    angle: 0,
+    dataKey: xKey,
+    tick: showXAxis
+      ? { fill: 'var(--color-foreground-lighter)', fontSize: 10, fontFamily: 'var(--font-mono)' }
+      : false,
+    hide: !showXAxis,
+    interval: 'preserveStartEnd' as const,
+    axisLine: { stroke: CHART_COLORS.AXIS },
+    tickLine: { stroke: CHART_COLORS.AXIS },
+  }
+
   const yAxisConfig = {
     tick: showYAxis
       ? { fill: 'var(--color-foreground-lighter)', fontSize: 10, fontFamily: 'var(--font-mono)' }
@@ -168,7 +188,7 @@ export const ChartLine = ({
             }
 
             if (chartHighlight) {
-              const activeTimestamp = data[e.activeTooltipIndex]?.timestamp
+              const activeTimestamp = data[e.activeTooltipIndex]?.[xKey]
               chartHighlight.handleMouseMove({
                 activeLabel: activeTimestamp?.toString(),
                 coordinates: e.activeLabel,
@@ -177,7 +197,7 @@ export const ChartLine = ({
           }}
           onMouseDown={(e: any) => {
             if (chartHighlight && e.activeTooltipIndex !== undefined) {
-              const activeTimestamp = data[e.activeTooltipIndex]?.timestamp
+              const activeTimestamp = data[e.activeTooltipIndex]?.[xKey]
               chartHighlight.handleMouseDown({
                 activeLabel: activeTimestamp?.toString(),
                 coordinates: e.activeLabel,
@@ -205,18 +225,14 @@ export const ChartLine = ({
         >
           {showGrid && <CartesianGrid vertical={false} stroke={CHART_COLORS.AXIS} />}
           <YAxis {...yAxisConfig} />
-          <XAxis
-            dataKey="timestamp"
-            interval={data.length - 2}
-            tick={false}
-            axisLine={{ stroke: CHART_COLORS.AXIS }}
-            tickLine={{ stroke: CHART_COLORS.AXIS }}
-          />
+          <XAxis {...xAxisConfig} />
           <ChartTooltip
             content={
               <ChartTooltipContent
                 className="text-foreground-light -mt-5"
-                labelFormatter={(v: string) => dayjs(v).format(DateTimeFormat)}
+                labelFormatter={(v: string) =>
+                  xKey === 'timestamp' ? dayjs(v).format(DateTimeFormat) : 'Value'
+                }
                 formatter={(value, name, item) => {
                   const key = String(item.dataKey || name || dataKey)
                   const itemConfig = chartConfig[key]
@@ -295,10 +311,11 @@ export const ChartLine = ({
           })}
         </RechartAreaChart>
       </ChartContainer>
-      {data && data.length > 0 && (
+
+      {xKey === 'timestamp' && data && data.length > 0 && (
         <div className="text-foreground-lighter -mt-6 flex items-center justify-between text-[10px] font-mono">
-          <span>{dayjs(data[0]['timestamp']).format(DateTimeFormat)}</span>
-          <span>{dayjs(data[data.length - 1]?.['timestamp']).format(DateTimeFormat)}</span>
+          <span>{dayjs(data[0][xKey]).format(DateTimeFormat)}</span>
+          <span>{dayjs(data[data.length - 1]?.[xKey]).format(DateTimeFormat)}</span>
         </div>
       )}
     </div>