[pull] master from supabase:master

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

@@ -125,7 +125,10 @@ write it down.
 
 - [`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).
+  mirrored in `pm-the-docs`'s reference file). Cross-repo **product** lookup
+  (universe) lives there, not in this skill.
+- [`test-the-docs`](../test-the-docs/SKILL.md) — execute docs snippets against a
+  Docker-isolated local stack; verification report.
 - [`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

.agents/skills/ask-the-docs/reference/federated-docs.md

@@ -93,17 +93,17 @@ flowchart TB
 
 ## 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` |
+| 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/monitoring-and-debugging/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")
 

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

@@ -3,10 +3,12 @@ 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.
+  and Shape stages (including cross-repo product lookup via universe when
+  accessible, else the public OSS path), 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, judging whether a docs question needs PM sign-off, or
+  confirming which product repos a launch spans.
 ---
 
 # PM the docs
@@ -17,17 +19,26 @@ Backs the Frame and Shape stages of the "Write the docs" checklist (mirrored in
 
 - 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).
+- Judging whether a launch spans multiple product repos (CLI, Auth, migrations, platform, …) — see [reference/universe-lookup.md](reference/universe-lookup.md).
 - 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)), 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)).
+**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)), running snippets (see [`test-the-docs`](../test-the-docs/SKILL.md)), or docs-app architecture/IA placement mechanics (see [`ask-the-docs`](../ask-the-docs/SKILL.md)).
+
+## Reference files
+
+| File                                                                           | What's inside                                                              |
+| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
+| [reference/write-the-docs-checklist.md](reference/write-the-docs-checklist.md) | Six-stage authoring checklist mirror                                       |
+| [reference/universe-lookup.md](reference/universe-lookup.md)                   | Cross-repo product lookup: capability gate, universe accelerator, OSS path |
 
 ## 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 authoring call), say so and name who should decide instead of inventing an answer to look complete.
+3. When scope may span services (CLI, Auth, migrations, Dashboard, platform, …), follow [reference/universe-lookup.md](reference/universe-lookup.md) **capability gate** before settling Frame/Shape; use universe only if accessible, otherwise the OSS path. Record which repos you searched.
+4. Answer the checklist's questions directly: product stage, audience and job-to-be-done, the one-line "why," content type, IA placement, prerequisites.
+5. Distinguish **confirmed fact** (stated in the ticket/PRD/code) from **inference** (your best read) — flag inference explicitly rather than presenting it as settled.
+6. 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
 
@@ -37,7 +48,8 @@ Escalate to your docs team's PM when scope or stage is unclear, you need a revie
 
 ## Related skills
 
-- [`ask-the-docs`](../ask-the-docs/SKILL.md) — IA placement and docs-app architecture (Shape stage)
+- [`ask-the-docs`](../ask-the-docs/SKILL.md) — IA placement and docs-app architecture (Shape stage). Cross-repo **product** lookup lives here in `universe-lookup.md`, not in `ask-the-docs`.
 - [`write-the-docs`](../write-the-docs/SKILL.md) — drafting once Frame/Shape are settled
+- [`test-the-docs`](../test-the-docs/SKILL.md) — run snippets against a Docker-isolated local stack; verification report
 - [`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/universe-lookup.md

@@ -0,0 +1,96 @@
+# Cross-repo product lookup
+
+Cross-repo product search for Frame/Shape when a feature may span services. Use during `/pm-the-docs`, not `/ask-the-docs` (`ask-the-docs` stays on `apps/docs` architecture).
+
+**Cross-repo confirmation is required for everyone.** [`supabase/universe`](https://github.com/supabase/universe) is an optional accelerator when you have Supabase org access to that private meta-repo (and ideally a local clone). Contributors without that access use the OSS path below — that is a successful outcome, not a failure.
+
+## Capability gate
+
+Run this gate before any universe clone or submodule command.
+
+```mermaid
+flowchart TD
+  start[Cross-repo grounding needed]
+  clone{"Local universe root exists?"}
+  ghApi{"gh api repos/supabase/universe succeeds?"}
+  useUniverse[Use universe clone + rg in repos/]
+  ossPath[OSS path: public gh search + linked product repos]
+  start --> clone
+  clone -->|yes| useUniverse
+  clone -->|no| ghApi
+  ghApi -->|yes Supabase org access| useUniverse
+  ghApi -->|no 404/403| ossPath
+```
+
+### 1. Local clone?
+
+Resolve the universe root in order (do not hardcode machine-specific absolute paths in committed files):
+
+1. `$SUPABASE_UNIVERSE_ROOT` (if set)
+2. `$HOME/GitHub/supabase/universe`
+
+```bash
+UNIVERSE_ROOT="${SUPABASE_UNIVERSE_ROOT:-$HOME/GitHub/supabase/universe}"
+[[ -d "$UNIVERSE_ROOT/.git" || -f "$UNIVERSE_ROOT/.git" ]] && echo "local universe ok"
+```
+
+If that checkout exists → **accelerator path** (skip the `gh api` probe).
+
+### 2. Else probe org access (read-only, no clone)
+
+```bash
+gh api repos/supabase/universe -q .full_name
+```
+
+| Result | Next step |
+| ------ | --------- |
+| Success (`supabase/universe`) | Accelerator path: you **may** clone with `--recurse-submodules` (or ask the user to), then search |
+| 404, 403, or other failure | **OSS path only** — do **not** run `git clone` or `git submodule update` against universe |
+
+## OSS path (always valid)
+
+When the gate says universe is unavailable:
+
+- Search public code: `gh search code --owner supabase '<query>'` (plus other public owners named in the ticket)
+- Read any product repo already checked out or linked from Linear / the PR
+- Prefer `supabase/supabase` in-tree sources when that is enough
+- In the Frame/Shape summary, record `universe: unavailable (OSS)` and list the public sources used
+
+Never treat missing universe access as a blocker or an incomplete Frame/Shape.
+
+## Accelerator: universe (when accessible)
+
+Prefer an existing local clone. Only init or update submodules after the gate succeeds:
+
+```bash
+cd "$UNIVERSE_ROOT"
+git submodule update --init --recursive
+```
+
+Private submodules (`platform`, `branching`) may need a PAT. If those fail, note the gap and continue with public submodules plus the OSS search path.
+
+### Where to look
+
+Start from the universe README "Finding your way around" table, then `rg` inside the relevant submodule:
+
+| Looking for… | Start in |
+| ------------ | -------- |
+| Schema, extensions, RLS | `repos/postgres/`, `repos/postgrest/`, `repos/pg-toolbelt/` |
+| Auth flows | `repos/auth/`, `auth-js` under `repos/supabase-js/` |
+| Realtime / Storage / Edge Functions | `repos/realtime/`, `repos/storage/`, `repos/edge-runtime/` |
+| Dashboard / Studio | `repos/supabase/apps/studio` |
+| Management API / hosted infra | `repos/platform/` (private) |
+| CLI, local dev, `config.toml` | `repos/cli/` |
+| Docs & self-hosting Compose | `repos/supabase/` (`apps/docs`, `docker/`) |
+
+When scope is unknown, search initialized `repos/**` with a tight pattern rather than reading entire trees.
+
+## How to use in Frame / Shape
+
+1. Name the product surfaces the launch might touch (CLI, Auth, migrations, Dashboard, …).
+2. Run the **capability gate**.
+3. Resolve surfaces to repos (universe submodules **or** public search / linked checkouts).
+4. Confirm with a short search whether behavior lives in one repo or several.
+5. Record in the Frame/Shape summary: gate result (`universe: available` or `universe: unavailable (OSS)`), repos consulted, cross-cutting vs single-repo, and any gaps.
+
+Always distinguish confirmed fact from inference.