The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
chore(claude): improve CLAUDE.md files and skill triggering (#48261)
Alaister Young4b24cf028a3f
diff --git a/.agents/skills/vitest/SKILL.md b/.agents/skills/vitest/SKILL.mdindex 0578bdcf3a8..69776b6edad 100644--- a/.agents/skills/vitest/SKILL.md+++ b/.agents/skills/vitest/SKILL.md@@ -1,15 +1,21 @@---name: vitest-description: Vitest fast unit testing framework powered by Vite with Jest-compatible API. Use when writing tests, mocking, configuring coverage, or working with test filtering and fixtures.+description: >-+ Vitest API and config reference (Jest-compatible) — mocking with vi.*, spies,+ fake timers, coverage configuration, fixtures, snapshots, and test filtering.+ Use for Vitest API and configuration questions anywhere in the monorepo; for+ Studio-specific test strategy and component-test setup, start with+ studio-testing and studio-mock-api-tests.metadata:author: Anthony Fu- version: "2026.1.28"+ version: '2026.1.28'source: Generated from https://github.com/vitest-dev/vitest, scripts located at https://github.com/antfu/skills---Vitest is a next-generation testing framework powered by Vite. It provides a Jest-compatible API with native ESM, TypeScript, and JSX support out of the box. Vitest shares the same config, transformers, resolvers, and plugins with your Vite app.**Key Features:**+- Vite-native: Uses Vite's transformation pipeline for fast HMR-like test updates- Jest-compatible: Drop-in replacement for most Jest test suites- Smart watch mode: Only reruns affected tests based on module graph@@ -22,31 +28,31 @@ Vitest is a next-generation testing framework powered by Vite. It provides a Jes## Core-| Topic | Description | Reference |-|-------|-------------|-----------|-| Configuration | Vitest and Vite config integration, defineConfig usage | [core-config](references/core-config.md) |-| CLI | Command line interface, commands and options | [core-cli](references/core-cli.md) |-| Test API | test/it function, modifiers like skip, only, concurrent | [core-test-api](references/core-test-api.md) |-| Describe API | describe/suite for grouping tests and nested suites | [core-describe](references/core-describe.md) |-| Expect API | Assertions with toBe, toEqual, matchers and asymmetric matchers | [core-expect](references/core-expect.md) |-| Hooks | beforeEach, afterEach, beforeAll, afterAll, aroundEach | [core-hooks](references/core-hooks.md) |+| Topic | Description | Reference |+| ------------- | --------------------------------------------------------------- | -------------------------------------------- |+| Configuration | Vitest and Vite config integration, defineConfig usage | [core-config](references/core-config.md) |+| CLI | Command line interface, commands and options | [core-cli](references/core-cli.md) |+| Test API | test/it function, modifiers like skip, only, concurrent | [core-test-api](references/core-test-api.md) |+| Describe API | describe/suite for grouping tests and nested suites | [core-describe](references/core-describe.md) |+| Expect API | Assertions with toBe, toEqual, matchers and asymmetric matchers | [core-expect](references/core-expect.md) |+| Hooks | beforeEach, afterEach, beforeAll, afterAll, aroundEach | [core-hooks](references/core-hooks.md) |## Features-| Topic | Description | Reference |-|-------|-------------|-----------|-| Mocking | Mock functions, modules, timers, dates with vi utilities | [features-mocking](references/features-mocking.md) |-| Snapshots | Snapshot testing with toMatchSnapshot and inline snapshots | [features-snapshots](references/features-snapshots.md) |-| Coverage | Code coverage with V8 or Istanbul providers | [features-coverage](references/features-coverage.md) |-| Test Context | Test fixtures, context.expect, test.extend for custom fixtures | [features-context](references/features-context.md) |-| Concurrency | Concurrent tests, parallel execution, sharding | [features-concurrency](references/features-concurrency.md) |-| Filtering | Filter tests by name, file patterns, tags | [features-filtering](references/features-filtering.md) |+| Topic | Description | Reference |+| ------------ | -------------------------------------------------------------- | ---------------------------------------------------------- |+| Mocking | Mock functions, modules, timers, dates with vi utilities | [features-mocking](references/features-mocking.md) |+| Snapshots | Snapshot testing with toMatchSnapshot and inline snapshots | [features-snapshots](references/features-snapshots.md) |+| Coverage | Code coverage with V8 or Istanbul providers | [features-coverage](references/features-coverage.md) |+| Test Context | Test fixtures, context.expect, test.extend for custom fixtures | [features-context](references/features-context.md) |+| Concurrency | Concurrent tests, parallel execution, sharding | [features-concurrency](references/features-concurrency.md) |+| Filtering | Filter tests by name, file patterns, tags | [features-filtering](references/features-filtering.md) |## Advanced-| Topic | Description | Reference |-|-------|-------------|-----------|-| Vi Utilities | vi helper: mock, spyOn, fake timers, hoisted, waitFor | [advanced-vi](references/advanced-vi.md) |-| Environments | Test environments: node, jsdom, happy-dom, custom | [advanced-environments](references/advanced-environments.md) |-| Type Testing | Type-level testing with expectTypeOf and assertType | [advanced-type-testing](references/advanced-type-testing.md) |-| Projects | Multi-project workspaces, different configs per project | [advanced-projects](references/advanced-projects.md) |+| Topic | Description | Reference |+| ------------ | ------------------------------------------------------- | ------------------------------------------------------------ |+| Vi Utilities | vi helper: mock, spyOn, fake timers, hoisted, waitFor | [advanced-vi](references/advanced-vi.md) |+| Environments | Test environments: node, jsdom, happy-dom, custom | [advanced-environments](references/advanced-environments.md) |+| Type Testing | Type-level testing with expectTypeOf and assertType | [advanced-type-testing](references/advanced-type-testing.md) |+| Projects | Multi-project workspaces, different configs per project | [advanced-projects](references/advanced-projects.md) |diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.mdindex 175aec83c51..3cabdcbc36c 100644--- a/.claude/CLAUDE.md+++ b/.claude/CLAUDE.md@@ -24,7 +24,6 @@ pnpm 11 + Turborepo monorepo. Requires Node >= 22.13.## Common Commands```bash-pnpm install # install dependenciespnpm dev:studio # run Studio dev server → http://localhost:8082pnpm dev:docs # run docs dev serverpnpm dev:www # run www dev serverdiff --git a/.claude/settings.json b/.claude/settings.jsonindex 3ffd1f88913..66fdfd3e7e5 100644--- a/.claude/settings.json+++ b/.claude/settings.json@@ -1,4 +1,14 @@{+ "permissions": {+ "deny": [+ "Edit(packages/api-types/types/**)",+ "Edit(**/routeTree.gen.ts)",+ "Edit(**/__generated__/**)",+ "Edit(apps/docs/features/docs/generated/**)",+ "Edit(apps/www/.generated/**)",+ "Edit(supabase/functions/common/database-types.ts)"+ ]+ },"hooks": {"SessionStart": [{diff --git a/.claude/skills/copywriting/SKILL.md b/.claude/skills/copywriting/SKILL.mdindex 1a6994d8020..f69a7e0ed90 100644--- a/.claude/skills/copywriting/SKILL.md+++ b/.claude/skills/copywriting/SKILL.md@@ -1,6 +1,6 @@---name: copywriting-description: Write or audit UI copy (buttons, labels, empty states, error messages, tooltips, form text) anywhere in the monorepo. Always check this before shipping or reviewing user-facing text.+description: Write or audit UI copy (buttons, labels, empty states, error messages, tooltips, form text) anywhere in the monorepo. Load it before shipping or reviewing any user-facing text — including when copy is incidental to the task, like a new feature that adds buttons, toasts, dialogs, or validation messages.---# Copywritingdiff --git a/.claude/skills/dev-toolbar-review/SKILL.md b/.claude/skills/dev-toolbar-review/SKILL.mdindex 8ead0b413f4..ae6b81d10ab 100644--- a/.claude/skills/dev-toolbar-review/SKILL.md+++ b/.claude/skills/dev-toolbar-review/SKILL.md@@ -1,6 +1,7 @@---name: dev-toolbar-review-description: Use when reviewing PRs that touch packages/dev-tools/, packages/common/posthog-client.ts,+description: Safety rules for the dev toolbar, PostHog client, and feature flags. Use+ when writing or reviewing any change to packages/dev-tools/, packages/common/posthog-client.ts,or packages/common/feature-flags.tsx. Covers environment guards, flag override cookies,telemetry event subscription, and SSE stream safety.---@@ -30,10 +31,12 @@ so PRs touching only those files won't auto-request review. Watch for these in t**Files:** `packages/dev-tools/index.ts`, `DevToolbar.tsx`, `DevToolbarTrigger.tsx`, `DevToolbarContext.tsx`The toolbar uses two layers of protection:+- **Build-time tree-shaking** in `index.ts`: `process.env.NODE_ENV !== 'development'` ternaries that replace components with noops/stubs so the implementation is eliminated from production bundles.- **Runtime guards** in components: `IS_LOCAL_DEV` checks — `DevToolbar` and `DevToolbarTrigger` return `null` to hide themselves, while `DevToolbarProvider` passes children through (`<>{children}</>`) to preserve the component tree.**Check for:**+- Guards being removed or broadened. The toolbar is expanding to staging and preview deploys but must remain invisible in production.- Tree-shaking ternaries in `index.ts` staying intact — these are the primary production safety mechanism.- New components or exports that bypass the existing guard pattern.@@ -43,14 +46,17 @@ The toolbar uses two layers of protection:**Files:** `packages/dev-tools/DevToolbar.tsx`, `packages/common/posthog-client.ts`, `packages/common/feature-flags.tsx`The toolbar writes two cookies that override feature flags locally:+- `x-ph-flag-overrides` — PostHog flag overrides- `x-cc-flag-overrides` — ConfigCat flag overridesThese are read by:+- `posthog-client.ts:getFeatureFlag()` — checks the PostHog override cookie before querying the SDK- `feature-flags.tsx` — merges both override cookies into the flag store during initialization**Check for:**+- Cookie name changes (must stay in sync across writer and all readers)- Changes to the merge/precedence logic in `feature-flags.tsx` (currently: `vercel-flag-overrides` first, then `x-cc-flag-overrides` takes precedence in local dev)- Override cookies being read outside the `IS_LOCAL_DEV` / `isLocalDev` guard — overrides must never affect production flag evaluation@@ -66,6 +72,7 @@ and `identify`. Note: `captureExperimentExposure` calls `posthog.capture()` direwithout emitting to dev listeners — experiment exposure events are invisible in the toolbar.**Check for:**+- Changes to `emitToDevListeners` or `subscribeToEvents` that could introduce side effects on the actual capture path (e.g., throwing errors, blocking, mutating event data)- The listener set (`devListeners`) being iterated synchronously in a way that could delay event dispatch- New PostHog client methods that capture events but don't call `emitToDevListeners` (gap in toolbar visibility)@@ -78,6 +85,7 @@ The toolbar connects to `${apiUrl}/telemetry/stream` via Server-Sent Events to dserver-side telemetry. Uses exponential backoff on connection errors.**Check for:**+- Changes to the SSE endpoint URL or `session_id` cookie handling- Reconnection logic changes that could cause excessive retries or connection leaks- Note: the stream endpoint lives in the platform repo — cross-repo changes need coordinated review@@ -85,16 +93,19 @@ server-side telemetry. Uses exponential backoff on connection errors.### 5. App-Level Mounting**Provider + toolbar panel** (`DevToolbarProvider`, `DevToolbar`):+- `apps/studio/pages/_app.tsx`- `apps/www/pages/_app.tsx`, `apps/www/app/providers.tsx`- `apps/docs/features/app.providers.tsx`**Trigger button** (`DevToolbarTrigger`) — rendered separately in nav/header components:+- `apps/studio/components/layouts/Navigation/LayoutHeader/LayoutHeader.tsx`- `apps/www/components/Nav/index.tsx`- `apps/docs/components/Navigation/NavigationMenu/TopNavBar.tsx`**Check for:**+- Provider being added or removed from an app- `apiUrl` prop changes (must point to the correct platform API)- Rendering order changes that could affect the toolbar's access to PostHog contextdiff --git a/.claude/skills/safe-sql-execution/SKILL.md b/.claude/skills/safe-sql-execution/SKILL.mdindex c0f43cb8f8f..37674ce1114 100644--- a/.claude/skills/safe-sql-execution/SKILL.md+++ b/.claude/skills/safe-sql-execution/SKILL.md@@ -1,6 +1,20 @@---name: safe-sql-execution-description: Safely execute SQL queries against a user database without risking SQL injection or other security vulnerabilities.+description: >-+ Use whenever code will build, return, fetch, or execute SQL that runs against+ a user's real Postgres database — even when the request reads like an ordinary+ feature or bug fix and never says "security," "injection," or+ "SafeSqlFragment." This covers: writing or editing any pg-meta function, query+ builder, or endpoint that builds/returns SQL for database objects (tables,+ views, functions, DB triggers, indexes, RLS policies); interpolating a+ schema/table/column/search/route-param value into SQL text; storing, fetching,+ or re-running SQL that round-trips from the database (a policy's definition, a+ function/view definition, a snippet's saved content); and any+ "Run"/"Apply"/"Execute" action that sends SQL to a project's database (SQL+ editor run-selection, policy editor apply, snippet runner). Load this BEFORE+ writing such code, not only when reviewing a finished diff. Skip only for+ changes that never touch SQL text or execution — styling, unrelated data+ hooks, non-SQL form validation, or UI layout work.---# Safe SQL executiondiff --git a/.claude/skills/studio-best-practices/SKILL.md b/.claude/skills/studio-best-practices/SKILL.mddeleted file mode 100644index 62eca4c6d1d..00000000000--- a/.claude/skills/studio-best-practices/SKILL.md+++ /dev/null@@ -1,175 +0,0 @@-----name: studio-best-practices-description: React and TypeScript best practices for Supabase Studio. Use when writing- or reviewing Studio components — covers boolean naming, component structure, loading/error- states, state management, custom hooks, event handlers, conditional rendering,- performance, and TypeScript conventions.------# Studio Best Practices--Applies to `apps/studio/**/*.{ts,tsx}`.--## Boolean Naming--Use descriptive prefixes — derive from existing state rather than storing separately:--- `is` — state/identity: `isLoading`, `isPaused`, `isNewRecord`-- `has` — possession: `hasPermission`, `hasData`-- `can` — capability: `canUpdateColumns`, `canDelete`-- `should` — conditional behavior: `shouldFetch`, `shouldRender`--Extract complex conditions into named variables:--```tsx-// ❌ inline multi-condition-{- !isSchemaLocked && isTableLike(selectedTable) && canUpdateColumns && !isLoading && <Button />-}--// ✅ named variable-const canShowAddButton =- !isSchemaLocked && isTableLike(selectedTable) && canUpdateColumns && !isLoading-{- canShowAddButton && <Button />-}-```--Derive booleans — don't store them:--```tsx-// ❌ stored derived state-const [isFormValid, setIsFormValid] = useState(false)-useEffect(() => {- setIsFormValid(name.length > 0 && email.includes('@'))-}, [name, email])--// ✅ derived-const isFormValid = name.length > 0 && email.includes('@')-```--## Component Structure--See `vercel-composition-patterns` skill for compound component and composition patterns.--Keep components under 200–300 lines. Split when you see:--- Multiple distinct UI sections-- Complex conditional rendering-- Multiple unrelated `useState` calls-- Hard to understand at a glance--Co-locate sub-components in the same directory as the parent. Avoid barrel re-export files.--Extract repeated JSX patterns into small components.--## Data Fetching--All data fetching uses TanStack Query (React Query). See `studio-queries` skill for query/mutation patterns and `studio-error-handling` skill for error display conventions.--### Loading / Error / Success Pattern--Top level:--```tsx-const { data, error, isLoading, isError, isSuccess } = useQuery(...)--if (isLoading) return <GenericSkeletonLoader />-if (isError) return <AlertError error={error} subject="Failed to load data" />-if (isSuccess && data.length === 0) return <EmptyState />-return <DataDisplay data={data} />-```--Use early returns — avoid deeply nested conditionals.--Inline:--```tsx-<div>- {isLoading && <InlineLoader />}- {isError && <InlineError error={error} />}- {isSuccess && data.length === 0 && <EmptyState />}- {isSuccess && data.length > 0 && <DataDisplay data={data} />}-</div>-```--## State Management--Keep state as local as possible; lift only when needed.--Group related form state with `react-hook-form` rather than multiple `useState` calls. See `studio-ui-patterns` skill for form layout and component conventions.--```tsx-// ❌ multiple related useState-const [name, setName] = useState('')-const [email, setEmail] = useState('')--// ✅ grouped with react-hook-form-const form = useForm<FormValues>({ defaultValues: { name: '', email: '' } })-```--## Custom Hooks--Extract complex or reusable logic into hooks. Return objects, not arrays:--```tsx-// ❌ array return (hard to extend)-return [value, toggle]--// ✅ object return-return { value, toggle, setTrue, setFalse }-```--## Event Handlers--- Prop callbacks: `on` prefix (`onClose`, `onSave`)-- Internal handlers: `handle` prefix (`handleSubmit`, `handleCancel`)--Use `useCallback` for handlers passed to memoized children; avoid unnecessary inline arrow functions.--## Conditional Rendering--```tsx-// Simple show/hide-<>{isVisible && <Component />}</>--// Binary choice-<>{isLoading ? <Spinner /> : <Content />}</>--// Multiple conditions — use early returns, not nested ternaries-if (isLoading) return <Spinner />-if (isError) return <Error />-return <Content />-```--## Performance--`useMemo` for genuinely expensive computations (measured, not assumed). Don't wrap everything — only optimize when you have a measured problem or are passing values to memoized children.--## TypeScript--Define prop interfaces explicitly. Use discriminated unions for complex state:--```tsx-type AsyncState<T> =- | { status: 'idle' }- | { status: 'loading' }- | { status: 'success'; data: T }- | { status: 'error'; error: Error }-```--Avoid `as any` / `as Type` casts. Validate at boundaries with zod:--```tsx-// ❌ type cast-const user = apiResponse as User--// ✅ zod parse-const user = userSchema.parse(apiResponse)-// or safe:-const result = userSchema.safeParse(apiResponse)-```--## Testing--Extract logic into `.utils.ts` pure functions and test exhaustively. See the `studio-testing` skill for the full testing strategy and decision tree.diff --git a/.claude/skills/studio-e2e-tests/SKILL.md b/.claude/skills/studio-e2e-tests/SKILL.mdindex ecd48bc8376..ef4cec3fe29 100644--- a/.claude/skills/studio-e2e-tests/SKILL.md+++ b/.claude/skills/studio-e2e-tests/SKILL.md@@ -1,9 +1,9 @@---name: studio-e2e-tests-description: Write and run Playwright E2E tests for Supabase Studio. Use when asked- to run e2e tests, write new E2E tests, or debug flaky tests. Covers running commands,- avoiding race conditions, waiting strategies, selectors, helper functions, and CI- vs local differences.+description: Write and run Playwright E2E tests for Supabase Studio (e2e/studio).+ Use when asked to run e2e tests, write new E2E tests, or debug flaky or failing+ Playwright tests. Covers running commands, avoiding race conditions, waiting+ strategies, selectors, helper functions, and CI vs local differences.---# E2E Studio Testsdiff --git a/.claude/skills/studio-error-handling/SKILL.md b/.claude/skills/studio-error-handling/SKILL.mdindex de0ff4cbab9..1cf98d2bcd3 100644--- a/.claude/skills/studio-error-handling/SKILL.md+++ b/.claude/skills/studio-error-handling/SKILL.md@@ -1,8 +1,9 @@---name: studio-error-handlingdescription: Error display and troubleshooting pattern for Supabase Studio. Use when- rendering API errors in the UI, adding inline troubleshooting steps for a new- error type, or wiring up the AI assistant debug button from an error state.+ showing a failed API request or query error in the UI (AlertError, toast, inline+ message), adding troubleshooting steps for a new error type, or wiring up the AI+ assistant debug button from an error state.---# Studio Error Handling Patterndiff --git a/.claude/skills/studio-queries/SKILL.md b/.claude/skills/studio-queries/SKILL.mdindex adf4e2e2b78..528ec033b44 100644--- a/.claude/skills/studio-queries/SKILL.md+++ b/.claude/skills/studio-queries/SKILL.md@@ -1,7 +1,8 @@---name: studio-queriesdescription: React Query conventions for data fetching in Supabase Studio. Use when- writing or reviewing query hooks, mutation hooks, or query keys in apps/studio/data/.+ writing or reviewing query hooks, mutation hooks, or query keys in apps/studio/data/+ — including adding the first fetch or mutation for a new API endpoint or resource.Covers queryOptions pattern, keys.ts structure, mutation hook template, and imperativefetching.---diff --git a/.claude/skills/studio-testing/SKILL.md b/.claude/skills/studio-testing/SKILL.mdindex 85e23d80969..39a1720cb0d 100644--- a/.claude/skills/studio-testing/SKILL.md+++ b/.claude/skills/studio-testing/SKILL.md@@ -1,9 +1,9 @@---name: studio-testing-description: Testing strategy for Supabase Studio. Use when writing tests, deciding what- type of test to write, extracting logic from components into testable utility- functions, or reviewing test coverage. Covers unit tests, component tests,- and E2E test selection criteria.+description: Testing strategy for Supabase Studio. Use when writing tests, deciding+ whether a change needs tests and which type, extracting logic from components into+ testable utility functions, or reviewing test coverage. Covers unit tests, component+ tests, and E2E test selection criteria.---# Studio Testing Strategy@@ -162,14 +162,14 @@ try/finally for resource cleanup. For E2E execution details, see the## Codebase References-| What | Where |-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| What | Where |+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- || Util test examples | `apps/studio/tests/components/Grid/Grid.utils.test.ts`, `apps/studio/tests/components/Billing/TaxID.utils.test.ts`, `apps/studio/tests/components/Editor/SpreadsheetImport.utils.test.ts` |-| Component test examples | `apps/studio/tests/features/logs/LogsFilterPopover.test.tsx`, `apps/studio/tests/components/CopyButton.test.tsx` |-| E2E test example | `e2e/studio/features/filter-bar.spec.ts` |-| E2E helpers pattern | `e2e/studio/utils/filter-bar-helpers.ts` |-| Custom render | `apps/studio/tests/lib/custom-render.tsx` |-| MSW mock setup | `apps/studio/tests/lib/msw.ts` (`addAPIMock`) |-| Test README | `apps/studio/tests/README.md` |-| Vitest config | `apps/studio/vitest.config.ts` |-| Related skills | `studio-e2e-tests` (running E2E), `vitest` (API reference), `vercel-composition-patterns` (component architecture) |+| Component test examples | `apps/studio/tests/features/logs/LogsFilterPopover.test.tsx`, `apps/studio/tests/components/CopyButton.test.tsx` |+| E2E test example | `e2e/studio/features/filter-bar.spec.ts` |+| E2E helpers pattern | `e2e/studio/utils/filter-bar-helpers.ts` |+| Custom render | `apps/studio/tests/lib/custom-render.tsx` |+| MSW mock setup | `apps/studio/tests/lib/msw.ts` (`addAPIMock`) |+| Test README | `apps/studio/tests/README.md` |+| Vitest config | `apps/studio/vitest.config.ts` |+| Related skills | `studio-e2e-tests` (running E2E), `vitest` (API reference), `vercel-composition-patterns` (component architecture) |diff --git a/.claude/skills/telemetry-standards/SKILL.md b/.claude/skills/telemetry-standards/SKILL.mdindex b8075526ce1..7b06ed799e9 100644--- a/.claude/skills/telemetry-standards/SKILL.md+++ b/.claude/skills/telemetry-standards/SKILL.md@@ -1,8 +1,10 @@---name: telemetry-standards-description: PostHog event tracking standards for Supabase Studio. Use when reviewing- PRs for telemetry compliance or implementing new event tracking. Covers event naming,- property conventions, approved patterns, and implementation guide.+description: PostHog event tracking standards for Supabase Studio. Use when adding+ useTrack() calls, defining events in packages/common/telemetry-constants.ts,+ implementing tracking for a new feature, or reviewing PRs for telemetry compliance.+ Covers event naming, property conventions, approved patterns, and implementation+ guide.---# Telemetry Standards for Supabase Studio@@ -19,16 +21,19 @@ opened, clicked, submitted, created, removed, updated, intended, evaluated, addeenabled, disabled, copied, exposed, failed, converted, closed, completed, applied, sent, moved**Flag these:**+- Unapproved verbs (saved, viewed, seen, pressed, etc.)- Wrong order: `click_product_card` → should be `product_card_clicked`- Wrong casing: `productCardClicked` → should be `product_card_clicked`**Good examples:**+- `product_card_clicked`- `backup_button_clicked`- `sql_query_submitted`**Common mistakes with corrections:**+- `database_saved` → `save_button_clicked` or `database_updated` (unapproved verb)- `click_backup_button` → `backup_button_clicked` (wrong order)- `dashboardViewed` → don't track passive views on page load@@ -39,10 +44,12 @@ enabled, disabled, copied, exposed, failed, converted, closed, completed, applie**Casing:** camelCase preferred for new events. The codebase has existing snake_case properties (e.g., `schema_name`, `table_name`) — when adding properties to an existing event, match its established convention.**Names must be self-explanatory:**+- `{ productType: 'database', planTier: 'pro' }`- `{ assistantType: 'sql', suggestionType: 'optimization' }`**Flag these:**+- Generic names: `label`, `value`, `name`, `data`- PascalCase properties- Inconsistent names across similar events (e.g., `assistantType` in one event, `aiType` in a related event)@@ -117,6 +124,7 @@ When reviewing a PR, flag these as **required changes:**5. **Inaccurate docs** — `@page`/`@source` descriptions that don't match the actual implementationWhen a PR adds user-facing interactions (buttons, forms, toggles, modals) **without** tracking, suggest:+- "This adds a user interaction that may benefit from tracking."- Propose the event name following `[object]_[verb]` convention- Propose the `useTrack()` call with suggested propertiesdiff --git a/apps/studio/CLAUDE.md b/apps/studio/CLAUDE.mdindex e102a63417e..892cbf8e93d 100644--- a/apps/studio/CLAUDE.md+++ b/apps/studio/CLAUDE.md@@ -4,7 +4,7 @@ Next.js pages router + TanStack Start (mid-migration, see below), React 19. Dev## Skills — load before working-**Always load the `studio-best-practices` skill before writing or modifying any Studio code.** Then stack the area-specific skills:+Load the skills matching the task; stack them when a task spans areas:| Task | Additional skills || ------------------------------------------------------ | ------------------------------------------------------------------------------------------------- |@@ -39,6 +39,37 @@ Studio is migrating from the Next.js pages router (`pages/**`) to TanStack Start- **Reuse first** — before writing a new hook or helper, search for an existing one (`hooks/`, `lib/`, `packages/common`, `packages/ui-patterns`). If you do need a new one, make it as reusable as possible: general naming, no page-specific coupling, placed where other callers can find it.- Co-locate sub-components with their parent; avoid barrel re-export files.+## Code style++Older Studio code predates some of these conventions. For new or modified code, follow them rather than mirroring nearby legacy patterns:++- **Booleans** read as `is`/`has`/`can`/`should`. Derive them from existing state (`const isFormValid = name.length > 0 && email.includes('@')`) — mirroring a derivable value into `useState` synced by `useEffect` is a bug pattern. Give multi-condition logic a name (`const canShowAddButton = !isSchemaLocked && canUpdateColumns && …`) instead of inlining the chain in JSX.+- **Ternaries**: one is fine for a binary choice; never nest them. Anything bigger flattens — early returns in statement position, sibling `&&` blocks in JSX.+- **Fetch states** render with early returns at the top level, or a flat `&&` chain with mutually exclusive guards inline — never a nested ternary:++ ```tsx+ // Top level: early return per state+ if (isLoading) return <GenericSkeletonLoader />+ if (isError) return <AlertError error={error} subject="Failed to retrieve data" />+ if (isSuccess && data.length === 0) return <EmptyState />+ return <DataDisplay data={data} />++ // Inline: flat `&&` blocks, mutually exclusive guards+ <div>+ {isLoading && <ShimmeringLoader />}+ {isError && <AlertError error={error} />}+ {isSuccess && data.length === 0 && <EmptyState />}+ {isSuccess && data.length > 0 && <DataDisplay data={data} />}+ </div>+ ```++- **`useEffect` is for synchronizing with external systems** (subscriptions, DOM, timers) — not for deriving data (compute it in render), reacting to user actions (do it in the handler), or fetching (React Query). Older code uses effects for all of these; don't copy it.+- **State** stays as local as possible — lift it only when it's actually shared. Related form fields belong in a single react-hook-form + zod form, not parallel `useState` calls.+- **Component size**: split at ~200–300 lines — or sooner when a component grows multiple distinct UI sections, tangled conditional rendering, or clusters of unrelated `useState`. Extract repeated JSX into small components, non-trivial pure logic into `.utils.ts` functions (which get unit tests), and reusable stateful logic into custom hooks.+- **Memoization is not the default**: `useMemo`/`useCallback` only for measured expense or referential stability a memoized child depends on.+- **TypeScript**: avoid `as` casts — where external data enters, parse it with zod (`schema.parse`/`safeParse`) instead. Model multi-state values as discriminated unions (`{ status: 'success'; data: T } | { status: 'error'; error: Error }`) rather than independent boolean flags.+- **Naming**: prop callbacks are `onX`, internal handlers are `handleX`. Custom hooks return objects, not tuples.+## Defaults that differ here- **ESLint warnings are ratcheted in CI**: the per-rule occurrence count must not increase, so a new `any`, unresolved `exhaustive-deps` warning, or default export fails the build even though it's "only a warning". Check locally with `pnpm --filter studio run lint:ratchet`.