[pull] master from supabase:master

.agents/skills/edit-the-docs/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: edit-the-docs
+description: >-
+  Restructure, reorder, and improve existing Supabase docs pages under
+  apps/docs — clarity, connective text, section grouping, and brevity.
+  Use when asked to edit, reorganize, restructure, tighten prose, or add
+  glue between sections on a page that already exists. Not for net-new
+  feature drafts (use write-the-docs) or PR triage/verification (use
+  review-the-docs).
+---
+
+# Edit the docs
+
+Improves **existing** Supabase docs pages: structure, order, connective text,
+and clarity. Distinct from [`write-the-docs`](../write-the-docs/SKILL.md)
+(draft net-new or product-grounded rewrites from intent + code) and
+[`review-the-docs`](../review-the-docs/SKILL.md) (lint, build, PR triage).
+
+## Core rules
+
+1. **Read before you rewrite.** Open the target page and nearby pages of the same type. Name the reader's goal and the page type (explainer, guide, tutorial, troubleshooting) before moving sections.
+2. **Improve structure and clarity; don't invent product truth.** Preserve behavior claims, UI labels, and positioning unless you verify a change against code or product intent. Accuracy gaps or missing net-new content belong with [`write-the-docs`](../write-the-docs/SKILL.md) / [`pm-the-docs`](../pm-the-docs/SKILL.md), not silent invention here.
+3. **Follow CONTRIBUTING.md and WORD_LIST.md** for voice, terminology, and formatting. See [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md) and [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md).
+4. **Prefer brevity.** Prefer broad strokes when mechanical detail doesn't help the reader's task. Cut redundancy; don't over-explain.
+5. **Reuse sibling skills.** IA/architecture via [`ask-the-docs`](../ask-the-docs/SKILL.md); validation and self-review via [`review-the-docs`](../review-the-docs/SKILL.md). Shared pitfalls live in [`write-the-docs/reference/common-pitfalls.md`](../write-the-docs/reference/common-pitfalls.md) — apply them, don't duplicate them.
+
+## Phase 1 — Diagnose
+
+1. Identify the document type per CONTRIBUTING.md (explainer, tutorial, guide, reference, or troubleshooting).
+2. State the reader's goal and prerequisites in one or two lines.
+3. Note structural problems: mixed information types interrupting a procedure, missing intro navigation on a long page, weak transitions, redundancy, or over-explained mechanics.
+4. Summarize the diagnosis to the requester before large moves when the restructure would change how the page is read.
+
+## Phase 2 — Restructure
+
+Apply [reference/structure-and-flow.md](reference/structure-and-flow.md):
+
+1. Classify substantial sections as contextual, procedural, or reference content. In a mixed page, group sections by information type so that context doesn't interrupt the procedural path.
+2. For a long or mixed page, add a short introduction that links to its major section groups and tells readers when to use each one. Skip this navigation when a short page is already easy to scan.
+3. Connect contextual sections to their corresponding procedures when useful. Add introductions to section groups, transitions between information types, and outcomes after procedures. Don't link every adjacent section.
+4. Move and regroup first; preserve meaning. Don't silently rewrite facts while restructuring.
+
+## Phase 3 — Edit for clarity
+
+- Use second person, present tense, short paragraphs, and ordered steps for sequential actions.
+- Cut restated points and mechanical over-explanation.
+- Apply [`write-the-docs/reference/common-pitfalls.md`](../write-the-docs/reference/common-pitfalls.md): timelessness, no internal planning context in shipped MDX, redundancy, single-item lists, admonition restatement.
+- Search [`apps/docs/WORD_LIST.md`](../../../apps/docs/WORD_LIST.md) when introducing or revising technical terms and UI actions.
+- Keep code samples executable in their stated context; mark intentionally omitted code. Prefer partials under `apps/docs/content/_partials/` over copied blocks.
+
+## Phase 4 — Validate
+
+Before handoff:
+
+- [ ] Section groups follow information type; procedures aren't interrupted by long context
+- [ ] Intro navigation present only when the page needs it; links resolve
+- [ ] Connective text is selective, not link spam
+- [ ] Voice matches CONTRIBUTING.md / WORD_LIST.md
+- [ ] No invented behavior or positioning
+- [ ] Shared pitfalls checklist considered
+
+Mechanics (anchors, lint, format): follow [`write-the-docs/reference/drafting-mechanics.md`](../write-the-docs/reference/drafting-mechanics.md). Before renaming or rewording headings, grep for `#<old-anchor-slug>` under `apps/docs/content` and update matches.
+
+Then run [`review-the-docs`](../review-the-docs/SKILL.md) local self-review (`pnpm lint:mdx`, and `pnpm build:guides-markdown` when guides/explainers/tutorials changed).
+
+## Additional resources
+
+- Structure SoT: [`apps/docs/CONTRIBUTING.md`](../../../apps/docs/CONTRIBUTING.md) (mixed types, navigation, glue)
+- Structure ops: [reference/structure-and-flow.md](reference/structure-and-flow.md)
+- Pitfalls: [`write-the-docs/reference/common-pitfalls.md`](../write-the-docs/reference/common-pitfalls.md)
+- Mechanics: [`write-the-docs/reference/drafting-mechanics.md`](../write-the-docs/reference/drafting-mechanics.md)
+- Architecture/IA: [`ask-the-docs`](../ask-the-docs/SKILL.md)
+- Net-new drafts: [`write-the-docs`](../write-the-docs/SKILL.md)
+- Review: [`review-the-docs`](../review-the-docs/SKILL.md)

.agents/skills/edit-the-docs/reference/structure-and-flow.md

@@ -0,0 +1,29 @@
+# Structure and flow
+
+Operational guidance for restructuring existing docs pages. The human-facing
+source of truth is [`apps/docs/CONTRIBUTING.md`](../../../../apps/docs/CONTRIBUTING.md)
+under Guides: **Mixed information types**, **Navigation**, and
+**Cross-references and glue**. Keep this file aligned with that section.
+
+## Classify and group
+
+Classify substantial sections as contextual, procedural, or reference content.
+In a mixed page, group sections by information type so that context doesn't
+interrupt the procedural path.
+
+## Introduction navigation
+
+For a long or mixed page, add a short introduction that links to its major
+section groups and tells readers when to use each one. Skip this navigation
+when a short page is already easy to scan.
+
+## Connective text
+
+Connect contextual sections to their corresponding procedures when useful.
+Add introductions to section groups, transitions between information types,
+and outcomes after procedures. Don't link every adjacent section.
+
+## Voice and procedure shape
+
+Use second person, present tense, short paragraphs, and ordered steps for
+sequential actions.

.agents/skills/pm-the-docs/SKILL.md

@@ -19,15 +19,15 @@ Backs the Frame and Shape stages of the "Write the docs" checklist (mirrored in
 - Deciding content type, IA placement, or prerequisites for a page (Shape).
 - Unsure whether a docs question is self-serve or needs a docs PM's sign-off.
 
-**Not for** drafting content itself (see [`write-the-docs`](../write-the-docs/SKILL.md)) or docs-app architecture/IA placement mechanics (see [`ask-the-docs`](../ask-the-docs/SKILL.md)).
+**Not for** drafting content itself (see [`write-the-docs`](../write-the-docs/SKILL.md)), restructuring existing pages (see [`edit-the-docs`](../edit-the-docs/SKILL.md)), or docs-app architecture/IA placement mechanics (see [`ask-the-docs`](../ask-the-docs/SKILL.md)).
 
 ## Answering a scope/stage/audience question
 
 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.
+5. If a decision is genuinely open at the org level (not a docs authoring call), say so and name who should decide instead of inventing an answer to look complete.
 
 ## Self-serve vs. escalate
 
@@ -39,4 +39,5 @@ Escalate to your docs team's PM when scope or stage is unclear, you need a revie
 
 - [`ask-the-docs`](../ask-the-docs/SKILL.md) — IA placement and docs-app architecture (Shape stage)
 - [`write-the-docs`](../write-the-docs/SKILL.md) — drafting once Frame/Shape are settled
+- [`edit-the-docs`](../edit-the-docs/SKILL.md) — restructure and improve existing pages
 - [`review-the-docs`](../review-the-docs/SKILL.md) — self-review and PR review stages

.agents/skills/pm-the-docs/reference/write-the-docs-checklist.md

@@ -39,6 +39,8 @@ _Skill:_ `/write-the-docs` to draft net-new content grounded in Linear and the c
 - [ ] E: Contribute technical depth and verify accuracy (APIs, limits, edge cases)
 - [ ] P: Call out the current stage inline and any known limitations
 
+When the work is improving an existing page (restructure, reorder, connective text, brevity) rather than authoring net-new content, use `/edit-the-docs` instead of `/write-the-docs`.
+
 ## 4. Self-review against the bar
 
 _Skill:_ `/review-the-docs` — [Local self-review](../review-the-docs/SKILL.md#local-self-review-no-open-pr) on your own branch before opening the PR.