f125126aec
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>
6.4 KiB
Supabase Monorepo
pnpm 11 + Turborepo monorepo. Requires Node >= 22.13.
Structure
| Directory | Purpose |
|---|---|
apps/studio |
Supabase Studio/Dashboard — has its own apps/studio/AGENTS.md (see below) |
apps/docs |
Documentation site — Next.js app router, MDX (port 3001, served under /docs) — has its own apps/docs/AGENTS.md |
apps/www |
Marketing website — Next.js, app + pages (port 3000) |
apps/design-system |
Component demos — source of truth for Studio UI patterns (port 3003) |
apps/ui-library |
shadcn-style registry site for Supabase UI blocks (port 3004) |
apps/lite-studio |
Lightweight Studio — different stack: React Router 7 + Vite + Tailwind v4 |
apps/kb |
Knowledge base — Astro — has its own apps/kb/AGENTS.md |
apps/learn |
Courses site — Next.js + Contentlayer (port 3007), early stage |
packages/ui |
Shared UI components (shadcn/ui based) — import { Button } from 'ui' |
packages/ui-patterns |
Composite components — subpath imports, e.g. ui-patterns/AssistantChat |
packages/common |
Shared utils, telemetry constants, feature flags |
packages/api-types |
Generated platform Management API types |
packages/pg-meta |
SQL builders for Postgres introspection (SafeSqlFragment) |
packages/shared-data |
Static data: pricing, plans, regions, error codes |
e2e/studio, e2e/docs |
Playwright E2E tests |
supabase/ |
Local Supabase project: edge functions, migrations, config.toml |
Common Commands
pnpm dev:studio # run Studio dev server → http://localhost:8082
pnpm dev:docs # run docs dev server
pnpm dev:www # run www dev server
pnpm dev:kb # run knowledge base dev server
pnpm test:studio # Studio unit tests (vitest)
pnpm e2e # Studio E2E tests (playwright)
pnpm build --filter=studio # build Studio
pnpm lint --filter=studio # lint Studio
pnpm typecheck # typecheck all packages
pnpm format # Prettier write (check: pnpm test:prettier)
pnpm generate:types # local DB types → supabase/functions/common/database-types.ts
pnpm api:codegen # platform Management API types → packages/api-types
CI
Every PR must pass typecheck + lint (one workflow), Prettier, and a typos check. Other checks are path-filtered: Studio unit tests/build and the lint ratchet (ESLint warning count must not increase) run on apps/studio/** changes; app-specific test suites run on their own paths.
Never hand-edit generated files: packages/api-types/types/**, **/routeTree.gen.ts, **/__generated__/**, apps/docs/features/docs/generated/**, apps/www/.generated/**, supabase/functions/common/database-types.ts, apps/docs/content/_partials/access-control/scoped_pat_*.mdx (run make -C apps/docs/spec generate.partials.access-control).
Conventions
UI — import from 'ui'; primitives are shadcn/ui-based and exported unsuffixed (Input, Select, Form, …). Use Button — the in-house component and the standard everywhere (a raw shadcn Button_Shadcn_ also exists but is rarely the right choice). Check packages/ui/index.tsx before creating new primitives. Higher-level patterns live in packages/ui-patterns.
Styling — Tailwind only, semantic tokens (bg-muted, text-foreground-light), no hardcoded colors.
Exports — named exports only; default exports are allowed only where a framework requires them (pages/**, app/**, config files — the eslint preset has the exact carve-out list). Lint-enforced across all apps via eslint-config-supabase (severity warn everywhere; hard-enforced in Studio by the lint ratchet).
Language — Use U.S. English everywhere.
Public surfaces — this repo is public: PR descriptions, issues, and code comments are world-readable. Keep internal content out of them: absolute production metrics (event counts, user counts, revenue figures: state percentages, ratios, or relative change instead), internal decision detail (vendor, legal, pricing, or strategy discussions), and competitor names (protocol identifiers such as user-agent strings are fine). Put that context in the Linear issue and link it.
Skills
The skills in .agents/skills/ are the source of truth for conventions — load the relevant ones before working, don't guess:
copywriting— any user-facing text, anywhere in the monorepopm-the-docs/write-the-docs/edit-the-docs/ask-the-docs/review-the-docs— anything underapps/docs(seeapps/docs/CONTRIBUTING.mdfor the authoring skill model)telemetry-standards— PostHog events,packages/common/telemetry-constants.tsdev-toolbar-review—packages/dev-tools,packages/common/posthog-client.ts,packages/common/feature-flags.tsxsafe-sql-execution— any code that builds or executes SQL against user databasesreact-hook-form— writing or modifying any form code, anywhere in the monorepovitest/vercel-composition-patterns— generic unit-testing and React composition references
Studio
Before working on anything in apps/studio, read apps/studio/AGENTS.md if it isn't already in context — it maps Studio tasks to required skills and covers the TanStack Start migration rules.