supabase

38,755 Commits 1,797 Branches 62 Tags

3 Commits

Include renames

Author	SHA1	Message	Date
Miranda Limonczenko	36371de151	docs: trim CONTRIBUTING to repo mechanics and point at the style guide (#50743 ) Part 3 of 3. Stack: #50742 → #50744 → #50743. Review #50742 and #50744 first. Closes DOCS-1177 ## Problem `CONTRIBUTING.md` mixed how to write a page with how the repo is laid out. That's why it reached 568 lines, and why a contributor looking for either half reads past the other. #50742 gives the writing half its own home. ## Solution Trim `CONTRIBUTING.md` to repo mechanics, 568 lines down to 163. Removed, now in the style guide: general principles, information types, document types, components and elements, styling and grammar, word usage. Kept: the skills table, repo organization, guide and reference structure, content reuse, search. Content listings keeps its data file, ID rules, and test command here; the when-to-use-one part is in the style guide. Added: a table linking each style guide file. Wire the contributor-facing entry points at the guide: - `apps/docs/AGENTS.md` — gains a style guide section listing each file separately, so an agent can load one file without the others. This auto-loads for anything under `apps/docs`, making it the highest-leverage pointer in the repo. - Root `AGENTS.md` — claimed the skills are "the source of truth for conventions." For docs content style that's now the guide, with the skills as the process that applies it. - `.github/pull_request_template.md`, `.coderabbit.yaml`, `apps/docs/README.md`, `apps/docs/DEVELOPERS.md` — updated paths. Drop the `.prettierignore` exemption for `apps/docs/CONTRIBUTING.md`. It's short enough to format now, and a repo that publishes a style guide shouldn't exempt its own contributing doc. ## Notes for review Discoverability in a markdown-only guide is entirely these pointers, so they're the load-bearing part of this PR rather than cleanup. Both surviving anchor links into `CONTRIBUTING.md` target `#ai-agent-skills-for-docs-authoring`, which is kept. No dangling anchors. This PR sits last in the stack on purpose. It deletes the style sections that seven skill instructions referenced, so it has to land after #50744 rewires them. ## Manual testing 1. Open `apps/docs/CONTRIBUTING.md` and confirm every remaining section is repo mechanics, and the style guide table links resolve. 2. Confirm `apps/docs/AGENTS.md` names each style guide file, in size order: `WORD_LIST`, `01-voice-and-tone`, `02-elements`, `03-page-structure`. 3. Run `grep -rn "apps/docs/WORD_LIST" --include=".md" --include=".yaml" . \| grep -v node_modules` and confirm only the intentional stub matches. 4. Run `npx prettier --config prettier.config.mjs --check apps/docs/CONTRIBUTING.md`. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * Documentation * Updated contributor guidance to distinguish writing conventions from repository mechanics, with the style guide as the reference for documentation style. * Added style guide links and clarified when to use the writing and editing skills. * Revised the docs contribution guide with a style guide file list and steps for adding content listings. * Updated the pull request checklist to direct contributors to the documentation skills for style guidance. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-25 20:22:47 -07:00
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 -->	2026-09-22 10:00:41 -07:00
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>	2026-09-03 21:58:29 +08:00

Author

SHA1

Message

Date

Miranda Limonczenko

36371de151

docs: trim CONTRIBUTING to repo mechanics and point at the style guide (#50743 )

Part 3 of 3. Stack: #50742 → #50744 → #50743. Review #50742 and #50744
first.

Closes DOCS-1177

## Problem

`CONTRIBUTING.md` mixed how to write a page with how the repo is laid
out. That's why it reached 568 lines, and why a contributor looking for
either half reads past the other.

#50742 gives the writing half its own home.

## Solution

Trim `CONTRIBUTING.md` to repo mechanics, 568 lines down to 163.

**Removed**, now in the style guide: general principles, information
types, document types, components and elements, styling and grammar,
word usage.

**Kept**: the skills table, repo organization, guide and reference
structure, content reuse, search. Content listings keeps its data file,
ID rules, and test command here; the when-to-use-one part is in the
style guide.

**Added**: a table linking each style guide file.

Wire the contributor-facing entry points at the guide:

- `apps/docs/AGENTS.md` — gains a style guide section listing each file
separately, so an agent can load one file without the others. This
auto-loads for anything under `apps/docs`, making it the
highest-leverage pointer in the repo.
- Root `AGENTS.md` — claimed the skills are "the source of truth for
conventions." For docs content style that's now the guide, with the
skills as the process that applies it.
- `.github/pull_request_template.md`, `.coderabbit.yaml`,
`apps/docs/README.md`, `apps/docs/DEVELOPERS.md` — updated paths.

Drop the `.prettierignore` exemption for `apps/docs/CONTRIBUTING.md`.
It's short enough to format now, and a repo that publishes a style guide
shouldn't exempt its own contributing doc.

## Notes for review

Discoverability in a markdown-only guide is entirely these pointers, so
they're the load-bearing part of this PR rather than cleanup.

Both surviving anchor links into `CONTRIBUTING.md` target
`#ai-agent-skills-for-docs-authoring`, which is kept. No dangling
anchors.

This PR sits last in the stack on purpose. It deletes the style sections
that seven skill instructions referenced, so it has to land after #50744
rewires them.

## Manual testing

1. Open `apps/docs/CONTRIBUTING.md` and confirm every remaining section
is repo mechanics, and the style guide table links resolve.
2. Confirm `apps/docs/AGENTS.md` names each style guide file, in size
order: `WORD_LIST`, `01-voice-and-tone`, `02-elements`,
`03-page-structure`.
3. Run `grep -rn "apps/docs/WORD_LIST" --include="*.md"
--include="*.yaml" . | grep -v node_modules` and confirm only the
intentional stub matches.
4. Run `npx prettier --config prettier.config.mjs --check
apps/docs/CONTRIBUTING.md`.


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

* **Documentation**
* Updated contributor guidance to distinguish writing conventions from
repository mechanics, with the style guide as the reference for
documentation style.
* Added style guide links and clarified when to use the writing and
editing skills.
* Revised the docs contribution guide with a style guide file list and
steps for adding content listings.
* Updated the pull request checklist to direct contributors to the
documentation skills for style guidance.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

2026-09-25 20:22:47 -07:00

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.

## 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.

2026-09-22 10:00:41 -07:00

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>

2026-09-03 21:58:29 +08:00