mirror of
https://github.com/supabase/supabase.git
synced 2026-10-05 09:25:06 +03:00
bot/decrease-eslint-ratchet-baselines
16
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Joshen Lim
|
54c2a2788f |
Joshenlim/fe 4474 add command to generate types off api production (#50960)
## Context Adds a pnpm command `api:codegen:prod` to generate API types off prod to work with the `verify-production-types` GHA. Just uses the existing logic in `verify-production-types.mjs` to fetch the OpenAPI specs, and writes it into the local API types files <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * API types can now be generated from the production API specifications when a local API environment is unavailable. * **Bug Fixes** * Resending invitations and updating project-scoped roles now handle roles without a base role ID more reliably. * **Documentation** * Updated guidance clarifies that API or schema changes must be deployed before relying on updated types. * Production is the source of truth for merge checks. Type verification should pass after deployment, and production-generated types are expected to pass verification. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
Miranda LimonczenkoandNik Richers
|
f5fcecf3d7 |
docs: point the authoring skills at the style guide (#50744)
Part 2 of 3. Stack: #50742 → #50744 → #50743. Review #50742 first. ## Problem Six skills restated style rules inline, so a rule could be corrected in the guide and stay wrong in a skill. `edit-the-docs` alone carried a second copy of the procedure format, the information-type classification rules, and the tables outline example. Two reference files said in their own text that they should be retired once a style guide existed. ## Solution Replace the restatements with pointers to the file that owns each rule. **Retired, as each file asked:** - `style-fallback.md` is deleted. It ended by telling an agent to follow the nearest comparable page, which launders whatever that page happens to do into a rule. The guide's References section replaces it. - `common-pitfalls.md` becomes a pointer, per the note at its own line 94. **Rewired**: `write-the-docs`, `edit-the-docs`, `review-the-docs`, `pm-the-docs`'s checklist, and `drafting-mechanics.md`. Skills cite a specific file rather than the directory, so one file can be loaded instead of the whole guide. `review-the-docs` gains a docs-tooling check for the inverse case: a style rule added to a skill belongs in the guide, with the skill pointing at it. ## Notes for review **`edit-the-docs`' PR 1 / PR 2 boundary is unchanged on purpose.** That split is by kind of diff — PR 1 is inline changes only, nothing moves a line — which is what makes each PR reviewable. The guide's files split by the size of the thing they govern, and the two cut across each other: choosing an admonition is an element decision but an inline diff, and chunking is a page-structure decision but currently applied in PR 1. Forcing them to match would stop PR 1 being a pure inline pass. Dropping the dash-aside rule from `write-the-docs` here lost it entirely, since it had no home in the guide. #50742 restores it in `01-voice-and-tone.md`. I audited the other four rules this PR removes from that checklist; only that one was lost. The skill's document-type list keeps `troubleshooting`, which CodeRabbit flagged as a fifth type not in the guide. The repo has 219 troubleshooting pages and a content-type gate that treats them as authorable, so the gap was in the guide. #50742 now lists five document types. ## Manual testing 1. Run `grep -rn "style-fallback\|apps/docs/WORD_LIST" .agents/skills/` and confirm no matches. 2. Open each rewired skill and confirm every style guide link resolves, including anchors such as `03-page-structure.md#chunking`. 3. Invoke `/edit-the-docs` and confirm it reads the guide rather than restating rules. 4. Run `npx prettier --config prettier.config.mjs --check ".agents/skills/*-the-docs/**/*.md"`. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated documentation writing, editing, and review guidance to reference the dedicated style guide for voice, terminology, page structure, and content elements. * Clarified how to classify and organize sections, and expanded style-consistency checks. * Updated related checklists and references to distinguish style guidance from repository contribution instructions. * Consolidated common drafting advice into the style guide and updated the page-type table layout. <!-- end of auto-generated comment: release notes by coderabbit.ai --> ## Stack order This PR moved above the `CONTRIBUTING.md` trim after review. The trim deletes the style sections that seven skill instructions still referenced, so trimming first left those references dangling until this PR landed. Rewiring the skills first removes that intermediate state: the skills point at the guide while `CONTRIBUTING.md` is still whole, and the trim then breaks nothing. --------- Co-authored-by: Nik Richers <nik@validmind.ai> |
||
|
Jordi Enric
|
e5685126b8 |
ci(api-types): require production verification FE-4455 (#50781)
## Problem API type changes still use the api-deploy-required label and an informational comment even though production verification has proven reliable enough to block merges. ## Fix Remove the obsolete API label path, scope the remaining labeler workflow to docs changes, and update the API-types guidance. Master branch protection now requires the app-bound verify-production-api-types check. ## How to test - Confirm the labeler workflow only runs for changes under apps/docs. - Confirm API type changes no longer receive the api-deploy-required label or comment. - Confirm master branch protection lists verify-production-api-types as a required GitHub Actions check. - Expected result: production API type verification blocks mismatched generated types while unrelated pull requests receive a successful skipped verification job. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Chores** * API type verification is now a required merge check; guidance to run it before review and treat failures as production drift remains. * Removed the API deployment label rule and the automated comment triggered when that label was applied. * The pull request labeling workflow now runs only for changes affecting the documentation app. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
Miranda Limonczenko
|
7ce4ee53ae |
chore(docs) Retire supa-mdx-lint (#50602)
Closes [DOCS-1289](https://linear.app/supabase/issue/DOCS-1289/get-the-linter-to-fix-what-it-flags-or-retirereplace-the-linter) Stacked on #50600, which points contributors at the authoring skills. Merge that one first. ## Problem Contributors experienced friction with the linter. They felt nickle and dimed for tiny nits and felt detracted from the work itself. PRs would become noisy with tiny one-word suggestions. Additionally, our homegrown linter is not very intelligent, causing frequent overrides. ## Solution This removes the linter entirely in favor of directing contributors to use SKILLS instead. The removal entails... - **CI.** Delete the three `docs_lint` workflows: the PR check, the external-PR comment companion, and the nightly `--fix` bot. Drop the stale `zizmor.yml` ignore entry for the deleted workflow. - **Tooling.** Delete `supa-mdx-lint.config.toml` and the 14 rule files. Drop the `lint:mdx` script and the `@supabase/supa-mdx-lint` dependency from docs, learn, and ui-library, and regenerate the lockfile. - **Content.** Remove the 181 directives. A separate commit carries Prettier's reformatting of the tables and blank lines those comments had suppressed, so the deletion commit stays readable. No prose changes. - **Style guide.** The word list states each rule directly instead of describing what the linter flagged. Every term survives, including the phrase groups that mirrored `Rule004ExcludeWords`. - **Skills.** `write-the-docs`, `edit-the-docs`, and `review-the-docs` drop `pnpm lint:mdx` from their self-review commands and check the word list directly. `ask-the-docs`'s CI reference drops both workflows. ## Manual testing 1. Run `git grep -i supa-mdx-lint -- . ':!pnpm-lock.yaml'`. No matches. 2. Run `pnpm install --frozen-lockfile --lockfile-only`. It passes, so the lockfile matches the three trimmed manifests. 3. Run `git diff master...HEAD --name-only --diff-filter=ACMR | grep -E '\.(md|mdx)$' | xargs npx prettier --config prettier.config.mjs --check`. All changed markdown passes. 4. Open the [reformatted filter table](https://docs-git-docs-retire-mdx-linter-supabase.vercel.app/docs/guides/observability/logs#filter-events) on the preview and compare it with [production](https://supabase.com/docs/guides/observability/logs#filter-events). The table renders the same. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Documentation guidance now uses manual prose and terminology review with the shared word list. * Clarified storage configuration and common Realtime channel mistakes. * Improved table formatting, text wrapping, and selected reference links. * Updated documentation authoring and review guidance. * **Chores** * Retired automated MDX linting from workflows and local validation commands. * Removed lint-suppression markers throughout documentation without changing instructions. * Added targeted documentation review guidance for pull requests. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
Nik RichersandNik Richers
|
ea79df46bc |
docs: explain purpose of /edit-the-docs in CONTRIBUTING.md rather than the "Write the docs" checklist (#50313)
## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs authoring guidance: keep `/edit-the-docs` out of the Write the docs checklist and document when to use what skill in `CONTRIBUTING.md`. ## What is the current behavior? The Write the docs checklist mentions `/edit-the-docs` mid-flow and lists it among checklist skills. That skill is a different workflow and audience, so it risks steering people off the six-stage process. ## What is the new behavior? - Checklist lists only Write the docs skills; no `/edit-the-docs` mid-stage note. - `CONTRIBUTING.md` splits **Write the docs skills** from **Edit existing pages**. - Write the docs applies when product intent and code drive the change, including revising or restructuring existing pages. `edit-the-docs` is for style, structure, or brevity when the product story is unchanged. ## Additional context Also drops a redundant `/test-the-docs` note from "What good looks like" (Self-review still covers it). --------- Co-authored-by: Nik Richers <nik@validmind.ai> |
||
|
Miranda LimonczenkoandClaude Opus 5
|
c7534b9e29 |
docs: document the stacked PRs workflow in edit-the-docs (#50018)
Closes DOCS-1381 ## Problem The `edit-the-docs` skill describes a page edit as one continuous pass and has no notion of output. No commits, no branches, no PRs. It ends at edited files in the working tree. That leaves a reviewer one diff that mixes reworded prose, moved sections, and corrected claims, where a move can't be told from a rewrite. ## Solution - **Split the edit by change type:** style, structure, technical revision, and additions. Style runs before structure, so the structure diff reads as pure moves against already-clean prose. - **Ship one PR, one change type per commit.** A stack of PRs is an ask, not a default. When the edit both rewrites prose and moves sections and runs over roughly 150 changed lines, the skill says how large the diff is and offers the split. The requester decides, and no answer means one PR. A stack buys clean per-type diffs, and it costs a reviewer the whole-edit view, since no PR page shows it. - **State the scope boundary once.** The edit is exactly the buckets that have content. A dropped bucket is beyond the edit, and a later request for that change type is a new request. Additions stay author-driven, which keeps a mid-edit request from reopening an earlier commit. - **Scope the technical pass with a wrong-outcome test.** A claim changes only when leaving it would hand the reader an error, a different result than the page promises, or a fact that isn't true. An external best-practices rule doesn't clear that gate on its own, and a missing safeguard is an absence, so it goes to additions. Without the test, a verification pass becomes a rewrite. - **Add `reference/stacked-prs.md`** for the `gh stack` commands, branch naming, restack auditing, and the one command that diffs a whole stack at once. ### What driving the skill on a real page changed Running it end to end on a 684-line guide, then shipping the result, corrected five things a read-through didn't: - **The anchor gate grepped the wrong scope.** It said `apps/docs/content`. Five of the seven inbound anchors to that page lived outside it, in Studio components and `apps/www`, and those are the matches that break a Docs button in the product. The gate is now repo-wide and is step 1 of the structure pass, because moving a section preserves its slug and only renaming breaks it. That's what makes an aggressive regroup safe. - **Grouping sections by subject doesn't work.** On a page about tables every section is about tables, so subject grouping produces one task-named bucket that collects the background too. Classification is now by what the reader is doing, and the skill carries the outline that page settled on. - **Snippet testing finds claims, it doesn't just confirm them.** One example re-created a table an earlier example had made, which stopped that block and left a third example referencing a table nothing ever created. Every fence was individually correct; the sequence was not. So the rule is to run every fence in document order, because that order is what the reader pastes. - **Restacking silently drops upper-branch edits.** The conflict presents as new structure versus old content being re-added, and resolving toward the structure takes the edit with it. `stacked-prs.md` says to audit each branch with a grep per expected change rather than reading the diff. - **`build:guides-markdown` dirties a tracked file.** It writes `apps/docs/public/markdown/manifest.json`, which the repo commits as `[]`. Without a note the artifact lands in the next commit. ## Manual testing 1. Open `.agents/skills/edit-the-docs/SKILL.md` and read Phase 0. You can tell whether to ship one PR or offer a stack, and what to say when offering it, without opening the reference file. 2. Read the PR 3 section. The wrong-outcome test, the external-rule tiebreaker, and the absences line together tell you where a best-practices violation goes. 3. Run `npx prettier --check .agents/skills/edit-the-docs apps/docs/CONTRIBUTING.md`. Reports all matched files use Prettier code style. 4. Run `cat .claude/skills/edit-the-docs/reference/stacked-prs.md`. The branch table resolves through the `.claude/skills` symlink and shows `4+` as a pattern. 5. Run `git diff master -- .agents/skills/write-the-docs/SKILL.md`. Reports no changes, so nothing in `write-the-docs` routes a drafter into this workflow. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Updated guidance for editing existing documentation through distinct style, structure, technical, and additions phases. - Added work-sizing, scope, validation, confirmation, and handoff rules for stacked pull requests. - Documented support for multiple topic-based additions branches and their merge order. - Clarified when to use drafting versus editing workflows, including when a draft becomes a restructure. - Improved guidance for validating code examples, checking repository-wide references, handling generated artifacts, and updating pull request titles. - Updated contributor guidance and related documentation references. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com> |
||
|
Jordi Enric
|
84db103ebb | ci(api): verify generated types against production (#49993) | ||
|
|
0bbd64743c |
docs: move inspect and advisors into observability (#49503)
<!-- CURSOR_AGENT_PR_BODY_BEGIN --> ## Stack Draft stack extracted from `docs/monitoring`. Merge bottom-up. Troubleshooting / debugging-guide rewrite is out of scope. 1. **#49503** move inspect and advisors ← **this PR** 2. #49501 split Studio logs from ClickHouse queries 3. #49500 treat reports as signal dashboards 4. #49502 add Observe the data hub 5. #49506 add agent setup components 6. #49504 add hire-an-agent templates 7. #49505 restructure observability nav and overview ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. First layer in the observability stack. ## What is the current behavior? Inspect and advisors live under Database (`/guides/database/inspect`, `/guides/database/database-advisors`). Observability readers have to leave the monitoring section to find them. ## What is the new behavior? - Moves inspect into `/guides/monitoring-and-debugging/inspect` - Adds `/guides/monitoring-and-debugging/advisors` (replaces the Database Advisors page) - Adds redirects and updates Studio/docs links so old URLs keep working - Adds both pages to the existing Monitoring nav so they are discoverable before the later IA PR ## Additional context Inspect and advisors pages render as standard MDX. Redirects cover `/docs/guides/database/inspect`, `/docs/guides/database/database-advisors`, and `/docs/guides/database/database-linter`. Debugging-guide content is unchanged except the inspect URL. ## Self-review - No leftover `/guides/database/inspect` or `/guides/database/database-advisors` links in docs guides or Studio linter/AI surfaces (historical blog posts left as-is) - Smoke test path updated to `/docs/guides/monitoring-and-debugging/advisors` <!-- CURSOR_AGENT_PR_BODY_END --> <div><a href="https://cursor.com/agents/bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-a3cb5ece-925b-4046-b58a-5d69e9a9d794&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **New Features** - Added a centralized Advisors guide for security and performance checks. - Updated database inspection guidance with live Postgres statistics, cache hit-rate context, and query-analysis resources. - **Documentation** - Reorganized Advisors and database inspection content under Monitoring and Debugging. - Updated navigation, cross-references, in-product help links, and CLI documentation links. - Added permanent redirects from previous documentation URLs to preserve access. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Saxon Fletcher <SaxonF@users.noreply.github.com> Co-authored-by: Nik Richers <nik@validmind.ai> |
||
|
Nik RichersandNik Richers
|
0322720743 |
docs: add test-the-docs skill and pm-the-docs universe lookup (#49913)
## I have read the CONTRIBUTING.md file. YES ## What kind of change does this PR introduce? Docs authoring skills / contributor enablement. ## What is the current behavior? - The "Write the docs" bar asks for runnable examples, but skills stop at lint/build (`/review-the-docs`) and do not execute inline MDX snippets. - Cross-repo product grounding depends on a single-repo read; there is no skill guidance for `supabase/universe` when you have Supabase org access. ## What is the new behavior? - Adds `/test-the-docs` to run procedural snippets against a Docker-isolated local stack (`supabase start` in a temp project), with Verification table output. - Teaches `/pm-the-docs` cross-repo product lookup (`reference/universe-lookup.md`) with a capability gate: universe when you have Supabase org access (or a local clone), otherwise a first-class OSS public-search path. `ask-the-docs` stays docs-app only. - Updates the checklist mirror, CONTRIBUTING skills table, and light handoffs in `write-the-docs` / `review-the-docs`. ## Additional context Vault "Write the docs" checklist updated separately; Linear document needs a Claude-side delta sync after merge. ### Test plan - [ ] Symlinks: `.claude/skills` is a Git symlink to `../.agents/skills`; `.claude/skills/test-the-docs/SKILL.md` resolves - [ ] No hardcoded personal absolute paths under `.agents/skills/` - [ ] CONTRIBUTING lists skills including `/test-the-docs` - [ ] `/pm-the-docs` references `universe-lookup.md` capability gate; `/ask-the-docs` Related points there for product lookup - [ ] OSS path: no universe clone / submodule init when `gh api repos/supabase/universe` fails - [ ] Docker up: dry-run `/test-the-docs` against one MDX page with SQL/CLI (optional smoke) - [ ] Docker down: skill documents graceful `deferred` (not silent skip) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **New Features** - Added documentation guidance for testing runnable examples in an isolated local environment. - Added cross-repository product lookup guidance, including capability checks and source tracking. - Added verification report templates with standardized results and environment details. - **Documentation** - Expanded authoring, review, self-review, and contribution guidance. - Improved safety instructions for local snippet testing, including credential protection and cleanup. - Updated repository layout, tooling, links, and workflow references for documentation skills. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Nik Richers <nik@validmind.ai> |
||
|
Alaister YoungandAlaister Young
|
f125126aec |
chore: make agent instructions agent-agnostic (#49941)
Makes the repo's AI-agent setup tool-agnostic: instructions live in
`AGENTS.md` files, skills live in `.agents/skills/`, and Claude Code,
Codex, Cursor, and Copilot all read the same sources. Also sweeps the
skills for stale and duplicated content while everything was being
moved.
**Changed:**
- Every `CLAUDE.md` (root, `apps/studio`, `apps/docs`, `apps/kb`) is now
a one-line `@AGENTS.md` import; the content moved verbatim into an
`AGENTS.md` beside it. The root one moved from `.claude/CLAUDE.md` to
the repo root for consistency.
- All skills now live in `.agents/skills/`; `.claude/skills` is a single
symlink to it (replacing the old mix of real dirs and per-skill
symlinks). Path references in `.coderabbit.yaml`, code comments, and
docs updated to match.
- `.github/copilot-instructions.md` keeps only the review policy and
points at `AGENTS.md` + `.agents/skills/`. Copilot code review reads
those natively now, so the per-topic
`.github/instructions/*.instructions.md` files were duplicates of the
skills.
- Stale skill content fixed: `studio-queries` imported a toast library
Studio doesn't use, `telemetry-standards` and `studio-testing` used
import paths that don't resolve, `safe-sql-execution` cited a boundary
test that doesn't exist, the ask-the-docs references described an
`AiPrompt` mechanism that was replaced by the ID-keyed registry, plus a
handful of wrong paths, a self-contradicting `waitForTimeout` rule, an
invalid Playwright signature, and a ConfigCat flag described as PostHog.
- `studio-error-handling` now explains when to use `AlertError` (the
default) vs `ErrorMatcher`.
**Added:**
- `apps/docs/AGENTS.md` (docs test requirements, from the old Cursor
rule)
- `studio-shortcuts` skill (from the old Copilot instruction file,
verified against the current registry)
- `ask-the-docs/reference/graphql-endpoint.md` and
`search-embeddings.md` (from the old Cursor rules, with the missing
resolver/registration/codegen steps filled in)
- Feature-flag measurement section in `telemetry-standards`
**Removed:**
- `.cursor/` (rules folded in as above; skill symlinks no longer needed)
and `.cursorignore`
- `.github/instructions/` (8 files)
- `vercel-composition-patterns/AGENTS.md` – a 946-line verbatim
concatenation of its own `rules/` directory, and a nested `AGENTS.md`
that agents could auto-load as repo instructions
- `edit-the-docs/reference/structure-and-flow.md` – word-for-word copy
of the skill's own Phase 2 text
## To test
- `readlink .claude/skills` → `../.agents/skills`, and `ls
.claude/skills/copywriting/SKILL.md` resolves
- Open a Claude Code session at the repo root and in `apps/studio` – the
imported `AGENTS.md` content should load as before
- `git diff master --stat -M` shows the skill moves as 100% renames
(content unchanged except the listed fixes)
- Spot-check a fixed claim, e.g. `import { toast } from 'sonner'` in
`studio-queries`, or the `logs.all` ESLint rule cited in
`clickhouse-logs-queries/references/codebase-integration.md`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Documentation**
- Expanded guidance for documentation workflows, GraphQL resources,
search, ClickHouse logs, React forms, Studio testing, shortcuts,
telemetry, accessibility, copywriting, and composition patterns.
- Clarified local testing, linting, build workflows, error handling, and
AI coding agent usage.
- Added contributor guidance for the knowledge base, documentation, and
Studio areas.
- **Chores**
- Consolidated agent instructions and skill references.
- Removed obsolete editor-specific guidance, duplicate links, and
superseded documentation.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
|
||
|
|
a27f81d5a0 |
docs: improve write-the-docs skill and retire docs-content (#49089)
## I have read the CONTRIBUTING.md file. YES ## What kind of change does this PR introduce? Improves the `write-the-docs` skill and retires the overlapping `docs-content` skill (provided @czenko agrees to the latter). ## What is the current behavior? - Docs drafts could leak future-tense / internal roadmap language, add redundant verbiage, and add single-item lists. - No explicit CONTRIBUTING.md / WORD_LIST.md compliance pass for docs drafts. - Product intent was assumed to come from Linear without a good path path for open-source contributors. - `docs-content` overlapped `write-the-docs` and the broader `*-the-docs` skill set (e.g. I started [#49432](https://github.com/supabase/supabase/pull/49432) before realizing we should likely not have overlapping skills). ## What is the new behavior? - Codifies draft pitfalls as principles in `reference/common-pitfalls.md` (timelessness, strip internal business context, redundancy, single-item lists), with style detail pointed from `SKILL.md` rather than duplicated. - Clarifies SoT: Linear + code inspection for content accuracy; CONTRIBUTING.md / WORD_LIST.md (and future DOCS-1177 style guide) for voice/terminology/formatting only. `common-pitfalls.md` is flagged to fold into that guide later. - Linear is internal and preferred when available, not required for open-source. Missing product intent: stop Draft and hand off to `pm-the-docs` (Frame) / `ask-the-docs` (Shape/IA); do not invent positioning or run Frame/Shape inside this skill. - Adds drafting mechanics notes, a compliance checklist before handoff, and a local `/review-the-docs` self-review step. - Removes `.claude/skills/docs-content/`; `.claude/CLAUDE.md` points at the canonical docs skills. Supersedes #49432. ## Additional context Based on @czenko review feedback on #49020 and feedback I received for `docs-content` from @aantti while trialing the "Write the docs" process with contributors, plus my own testing while drafting docs for product managers. ### Test plan - [ ] `SKILL.md` reads as Draft-only; Frame/Shape stay with `pm-the-docs` / `ask-the-docs` - [ ] No-Linear path: ask for Linear (internal) or hand off Frame/Shape; no invented positioning - [ ] `.claude/skills/docs-content/` gone; `.claude/CLAUDE.md` updated - [ ] `.claude/skills/write-the-docs` symlink still resolves to `.agents/skills/write-the-docs` - [ ] Next `/write-the-docs` run: compliance re-read + pitfalls guidance before handoff <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added an `edit-the-docs` workflow for restructuring and improving existing documentation pages. - Expanded authoring guidance for concise, timeless, user-focused content grounded in product intent. - Added references covering common writing pitfalls, link and anchor conventions, and validation workflows. - Clarified that style guidance applies to voice, formatting, and terminology—not product behavior. - Updated documentation workflows to distinguish planning, writing, editing, review, and assistance responsibilities. - Replaced the previous standalone docs-content skill with the updated authoring skill model. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Nik Richers <nik@validmind.ai> Co-authored-by: Miranda Limonczenko <miranda.limonczenko@supabase.io> |
||
|
Pamela Chia
|
eba2aeb517 |
chore: remove stale references to the removed build:llms pipeline (#49848)
## What The `build:llms` script no longer exists in apps/docs (its output, `apps/docs/public/llms/*.txt`, is superseded by `apps/www/app/llms/[slug]/route.ts` serving the generated reference markdown directly). Four stale references remained: - `apps/docs/.gitignore`: removed the `public/llms/` entry and its comment referencing the dead script. Nothing writes to that directory anymore; if you have leftover local files there, delete them. - `apps/docs/spec/reference/README.md`: the react-server `tsx` warning cited `pnpm build:llms` as the consumer. Replaced with `pnpm embeddings`, a live script that runs under `tsx --conditions=react-server`. I verified the constraint still holds: importing `Reference.utils.ts` crashes under `--conditions=react-server` (in `next/navigation`) and loads fine under plain `tsx`. - `apps/www/pages/modules/vector.tsx`: the maintenance comment pointed at `public/llms/vector.txt`, which doesn't exist in www. The hand-maintained markdown sibling lives at `content/md/modules/vector.md`. - `.agents/skills/ask-the-docs/reference/llm-agent-parity.md`: the "In-flux / stale wiring" bullet asserted the exact `.gitignore` line this PR deletes (and its "generation path is unclear" caveat no longer holds; per-source links resolve live via `apps/www/app/llms/[slug]/route.ts`). Removed the bullet so the ask-the-docs skill doesn't report a gitignore entry that no longer exists. No behavior change; docs and comments only (plus a gitignore entry). <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Updated the embeddings documentation to use the current `pnpm embeddings` command. - Clarified where vector module content should be maintained alongside the corresponding page. - Removed outdated references to generated per-source LLM files and retired documentation describing stale generation paths. - Improved consistency between reference documentation and the current content-generation workflow. <!-- end of auto-generated comment: release notes by coderabbit.ai --> |
||
|
Wen Bo Xie
|
2681a21f5c |
docs: add Personal Access Tokens guide with generated permission tables (#49732)
Add a guide that compares classic and scoped personal access tokens, explains how account roles constrain token permissions, and walks through creating and testing a project-scoped token. Include generated tables mapping permissions to Management API endpoints and MCP tools, and link the guide from docs navigation and Studio token sheets. Move the scoped-token permission catalog from Studio into shared-data. Studio and docs generation now share permission names, categories, descriptions, risk metadata, modes, scopes, and display order. Generate the tables from the shared catalog, OpenAPI x-fga-permissions, and the downloaded MCP permission map. Exclude Workers permissions until the feature is live. Run regeneration through the docs Makefile, verify checked-in output in CI, and refresh it in the weekly Management API workflow. Add Dashboard and Docs ownership plus contributor guidance so permission changes stay synchronized. |
||
|
Nik RichersandNik Richers
|
cf36ad9e52 |
feat(skills): move Write the docs skills into the monorepo — DO NOT REVIEW YET (#48914)
## 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> |
||
|
Alaister YoungandAlaister Young
|
4b24cf028a |
chore(claude): improve CLAUDE.md files and skill triggering (#48261)
Improves the repo's agent guidance: distills the always-required `studio-best-practices` skill into `apps/studio/CLAUDE.md`, tunes every skill description for reliable triggering, and mechanically enforces the generated-files rule. Grounded in Anthropic's official CLAUDE.md guidance (see justifications below). ## The main change: Studio CLAUDE.md gets a Code style section **Why:** `studio-best-practices` was a skill that instructed agents to *always* load it before any Studio code work. Anthropic's guidance draws the line as: sometimes-relevant guidance → skill (loaded on demand); always-relevant guidance → CLAUDE.md. A skill that must always load has failed the test for being a skill — it costs a tool-call round trip and, worse, silently does nothing in sessions that forget to load it. Since `apps/studio/CLAUDE.md` is lazy-loaded only when an agent touches Studio files, inlining is properly scoped: non-Studio sessions never pay for it. **Why not verbatim:** the skill was 175 lines, mostly ❌/✅ worked examples teaching practices models already know. Inlining it whole would push the file past the ~200-line point where Anthropic warns rules start getting lost. Instead each section was distilled to the rule it exists to enforce — e.g. the loading/error/success section kept its code block because the *shape* (early returns at top level, flat `&&` chains inline) is the prescription, and prose loses it. **The framing that makes the generic rules earn their place:** models default to matching surrounding code, and not all existing Studio code follows these practices. The section opens with "older Studio code predates some of these conventions — follow them rather than mirroring nearby legacy patterns," which converts otherwise-redundant React advice into an explicit instruction to break from local precedent. One rule was added that the old skill lacked: `useEffect` is for external-system sync only (~364 Studio files contain effects, many in patterns we don't want copied). **Changed:** - `apps/studio/CLAUDE.md` — new Code style section (84 lines total, within budget); skills table no longer mandates a pre-load - `.claude/CLAUDE.md` — dropped `pnpm install` from commands (guessable; Anthropic's test: "would removing this cause mistakes?") **Removed:** - `.claude/skills/studio-best-practices/` — fully absorbed; its cross-references to other skills were already covered by the skills routing table ## Skill description tuning Descriptions are the only signal an agent sees before deciding to load a skill, and the observed failure mode is under-triggering on tasks that don't name the skill. Nine descriptions reworded: front-loaded matchable keywords, added incidental-trigger cases (e.g. a new feature that adds copy is a `copywriting` moment), and disambiguated overlaps (`vitest` is now the API reference deferring to `studio-testing` for strategy). The `safe-sql-execution` rewrite was additionally validated with skill-creator's trigger-eval loop against 20 realistic queries: held-out test accuracy 54% → 71%, with zero false triggers across all iterations. (`vitest` shows under `.agents/` because `.claude/skills/vitest` symlinks there.) ## Generated-files enforcement **Added:** `permissions.deny` rules in `.claude/settings.json` for the six generated-file globs the root CLAUDE.md already lists. CLAUDE.md prose is advisory; permission rules are mechanical and also gate sandboxed Bash writes. (Verified live: the rule blocked an unintended regeneration of `database-types.ts` during testing.) ## To test - CI: prettier + typos checks pass (docs-only + settings change, no app code) - In a fresh Claude Code session in the repo: ask it to edit `apps/studio/routeTree.gen.ts` — should be denied by the new permission rule - Ask it to do any Studio UI task — it should pick up the Code style rules from `apps/studio/CLAUDE.md` without loading a best-practices skill <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated development guidance for testing, copywriting, SQL safety, telemetry, queries, error handling, and toolbar reviews. * Restructured Vitest references into clearer tables and improved formatting across several guides. * Added Studio code-style conventions and clarified when task-specific guidance should be applied. * Removed outdated Studio best-practices guidance. * **Chores** * Added safeguards preventing edits to generated and protected files. * Simplified the documented development command sequence. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com> |
||
|
Jordi Enric
|
ac64a902c1 | chore: adds tests (#42653) |
