## Problem
We used to have a `_Shadcn_` suffix for all the shadcn form components
because we also had `formik` form components.
This is not needed anymore.
## Solution
- Remove the suffix
- Update all usages
## What kind of change does this PR introduce?
AGENTS.md update.
## What is the current behavior?
None of the below are specified in AGENTS.md.
## What is the new behavior?
- Specify U.S. English in code. This is necessary as many of us use
British English or equivalent, and this can creep into code
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Chores**
* Added/updated contribution documentation to specify that all
repository text should use U.S. English for consistency.
---
**Note:** This change updates internal documentation conventions only
and does not affect end-user functionality.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
The Claude Code post-tool-use format/lint hook was hardcoded to only run
on `apps/studio/` files. This updates it to work across the whole repo.
**Changed:**
- Prettier now runs on any supported file type in the repo (not just
Studio)
- ESLint runs for any workspace that has it configured, using a simple
lookup table
- Unsupported file types (e.g. `.sh`) are skipped to avoid "no parser"
errors
## To test
- Edit a file in `apps/studio/` with bad formatting — should get
auto-formatted and linted
- Edit a file in `packages/common/` — should get auto-formatted (no
ESLint since it's not configured there)
- Edit a `.sh` file — should be skipped with no errors
Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
Came up in a conversation with @pamelachia about what growth eng should
actually look for when reviewing dev toolbar PRs. We realized the review
criteria were all in my head and not documented anywhere, so this adds a
Claude skill that surfaces a checklist when PRs touch the relevant
files.
### What it covers
- Environment guards (tree-shaking ternaries, `IS_LOCAL_DEV` runtime
checks) — especially relevant since we're expanding visibility to
staging/preview
- Flag override cookies (`x-ph-flag-overrides`, `x-cc-flag-overrides`)
and the read/write sync across dev-tools, posthog-client, and
feature-flags
- Telemetry event subscription (`subscribeToEvents` /
`emitToDevListeners`) side-effect safety
- SSE server telemetry stream and cross-repo implications
- App-level mounting across studio, www, docs
- Also calls out a CODEOWNERS gap: `posthog-client.ts` and
`feature-flags.tsx` aren't assigned to growth-eng, so PRs touching only
those files won't auto-request review
### Testing
Verified the skill is discovered by Claude Code from the repo root.
Content reviewed against the actual code in `packages/dev-tools/` and
`packages/common/`.
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added internal review guidelines for development-toolbar changes,
covering build-time hiding outside local dev, local feature-flag
override handling, client telemetry listener expectations,
server-sent-event stream safety and reconnection, and app-level
mounting/props validation to ensure correct runtime behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Adds a Claude Code `PostToolUse` hook that automatically runs prettier
and ESLint `--fix` on `apps/studio/` files after every Write or Edit.
**Added:**
- `.claude/scripts/format_and_lint.sh` — standalone script that receives
hook JSON on stdin, extracts the file path, and runs prettier + ESLint
- `PostToolUse` hook in `.claude/settings.json` pointing to the script
## Approaches considered
**`if` field with path globs (didn't work):** Claude Code hooks support
an `if` field that uses permission rule syntax to filter when a hook
fires. We tried `"if": "Edit(/apps/studio/**)|Write(/apps/studio/**)"`
and variants (`/apps/studio/**`, `apps/studio/**`, single patterns
without `|`) to scope the hook to studio files without spawning a
process. None of these matched – the `if` field works for tool-name-only
matching (`"Edit"`) and Bash command patterns (`"Bash(git *)"`) but does
**not** support file path globs for Write/Edit tools.
**`$CLAUDE_TOOL_INPUT_FILE_PATH` env var (doesn't exist):** We also
tried using `$CLAUDE_TOOL_INPUT_FILE_PATH` to avoid jq parsing of stdin.
This env var is not provided by Claude Code – hook input comes
exclusively via stdin JSON. The only project-related env var available
is `$CLAUDE_PROJECT_DIR`.
**Inline shell pipeline (worked but hard to maintain):** The first
working version had the full jq + case pipeline inline in settings.json.
Copilot review flagged this for readability, error suppression, and the
jq dependency – so we extracted it to a script.
**Final approach — script with jq stdin parsing + shell `case`:**
`.claude/scripts/format_and_lint.sh` extracts the file path from stdin
JSON with `jq`, gates on `*apps/studio/*` via `case`, runs prettier on
all matched files, then ESLint `--fix` on `.ts/.tsx/.js/.jsx` only. Uses
`set -euo pipefail` so prettier/eslint errors surface instead of being
swallowed.
## To test
- Open a Claude Code session in this repo
- Edit any file under `apps/studio/` – should see "Formatting &
linting..." spinner
- Verify prettier formatting is applied (e.g. introduce extra blank
lines, they get collapsed)
- Verify ESLint autofixes run on `.ts`/`.tsx`/`.js`/`.jsx` files
- Editing files outside `apps/studio/` should not trigger formatting
---------
Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Migrates all studio-related Cursor rules to Claude skills and adds a
top-level `.claude/CLAUDE.md` for project context. Docs rules left in
place.
**Decisions:**
- Only studio + testing rules migrated — docs rules intentionally left
in `.cursor/rules/docs/`
- Vitest skill already shared via symlink (`.claude/skills/vitest` →
`.agents/skills/vitest`) — nothing to migrate
- Grouped ~21 granular cursor rules into 5 new skills + 1 updated skill
by topic
- `studio-architecture` skill fully merged into `CLAUDE.md` and deleted
to avoid overlap
- Skills are self-contained (content inlined, not relying on sub-files)
since Claude reads SKILL.md first
- Skills cross-reference each other inline where relevant (e.g.
best-practices → testing, error-handling, queries)
- No `paths` frontmatter — would auto-inject full skill content on every
matching file. Current description-based matching is more selective and
token-efficient.
**Removed:**
- `.cursor/rules/studio/` (21 rule files covering architecture, best
practices, UI patterns, queries, styling, etc.)
- `.cursor/rules/testing/` (e2e-studio + unit-integration rules)
- `.cursor/rules/studio-useStaticEffectEvent.mdc`
- `.claude/skills/studio-architecture/` — fully merged into CLAUDE.md to
avoid duplication
- `.claude/skills/studio-testing/rules/` — orphaned sub-files after
inlining content into SKILL.md
**Added:**
- `.claude/CLAUDE.md` — concise monorepo overview with structure,
commands, and conventions. Absorbs studio-architecture content.
References `studio-*` skills for detail.
- `.claude/skills/studio-best-practices/` — boolean naming, component
structure, loading/error/success patterns, state management, hooks,
TypeScript conventions. Cross-references `vercel-composition-patterns`,
`studio-ui-patterns`, `studio-queries`, `studio-error-handling`, and
`studio-testing` inline where relevant.
- `.claude/skills/studio-ui-patterns/` — layout, forms, tables, charts,
empty states, navigation, cards, alerts, sheets. Grouped from ~10
separate cursor rules into one cohesive skill.
- `.claude/skills/studio-queries/` — React Query `queryOptions` pattern,
`keys.ts` structure, mutation hook template, imperative fetching.
- `.claude/skills/use-static-effect-event/` — the `useStaticEffectEvent`
hook: when to use, when not to, patterns, implementation.
**Changed:**
- `.claude/skills/studio-e2e-tests/` — renamed from `e2e-studio-tests`
for `studio-*` naming consistency. Merged race condition, waiting
strategy, test structure, assertion, and cleanup patterns from the
cursor e2e rule.
- `.claude/skills/studio-testing/` — inlined key content from sub-rule
files directly into SKILL.md so it's self-contained. Removed broken
`AGENTS.md` reference. Deleted orphaned `rules/` sub-files.
- `.claude/skills/vercel-composition-patterns/` — added note that Studio
uses React 18, so React 19 patterns should be skipped.
- `.gitignore` — added `!.claude/CLAUDE.md` exception so it's tracked.
## To test
- Open Claude Code in the repo, verify `.claude/CLAUDE.md` loads as
project context
- Ask Claude about Studio conventions and verify it references the right
skills
- Check that `studio-*` skills appear in the skill list
---------
Co-authored-by: Alaister Young <10985857+alaister@users.noreply.github.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
## Context
Noticed while working on #43913 that `copilot-instructions.md` is
currently at ~4,600 characters. Per [GitHub's docs on Copilot code
review](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review):
> Copilot code review only reads the first 4,000 characters of any
custom instruction file. Any instructions beyond this limit will not
affect the reviews generated by Copilot code review.
This means the testing section at the bottom of our current file isn't
being read during reviews.
## Proposal
Split the single file into path-specific instruction files under
`.github/instructions/`, following [GitHub's recommended pattern for
repository custom
instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions):
> These are specified in one or more `NAME.instructions.md` files within
or below the `.github/instructions` directory.
> If the path you specify matches a file that Copilot is working on, and
a repository-wide custom instructions file also exists, then the
instructions from both files are used.
This gives us separate files that each stay under the 4K limit and get
combined automatically by Copilot during reviews:
| File | Size | Scope |
|------|------|-------|
| `copilot-instructions.md` | 929 chars | General repo context +
pointers |
| `instructions/studio-telemetry.instructions.md` | 3,570 chars |
Telemetry rules for `apps/studio/**` |
| `instructions/studio-testing.instructions.md` | 1,228 chars | Testing
rules for `apps/studio/**` |
Note: Copilot reads instructions from the **base branch** of a PR, not
the feature branch — so these won't take effect until merged to master.
### New telemetry guidance
The telemetry file adds guidance we've been missing — specifically
around feature-flagged rollouts:
- Flag PRs that use `usePHFlag`/`useFlag` to gate behavior but don't
capture the flag state in telemetry
- Flag rollouts that track flag state but not user response to the new
behavior
- Documents the raw flag pattern (read via `usePHFlag`, not coerced
wrapper hooks) to avoid the `undefined`→`false` data quality bug we hit
in #43913
### What didn't change
All existing telemetry and testing rules are preserved — nothing was
removed, just reorganized. The telemetry rules still reference
`.claude/skills/telemetry-standards/SKILL.md` as the authoritative
source.
## References
- [Adding repository custom instructions for GitHub
Copilot](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)
— file structure, path-specific instructions, frontmatter format
- [Using Copilot code
review](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review)
— 4K character limit, base branch behavior
## Open questions
Would love the team's input on:
- Does the file split make sense, or would you prefer keeping everything
in one file (and trimming to fit)?
- Are there other topics that should get their own instruction file?
- Any concerns with the new feature flag telemetry guidance?
When the dashboard hits a DB connection timeout, users currently see a
raw error message with no
path forward. This PR adds an inline troubleshooting system that detects
known error types and
surfaces contextual next steps — restart the DB, read the docs, or debug
with AI.
## Changes
- New ErrorDisplay component (packages/ui-patterns) — styled error card
with a title, monospace error
block, optional troubleshooting slot, and a "Contact support" link that
always renders. Accepts
typed supportFormParams to pre-fill the support form.
- Error classification in handleError (data/fetchers.ts) — on every API
error, the message is tested
against ERROR_PATTERNS. If matched, handleError throws a typed subclass
(ConnectionTimeoutError
extends ResponseError) instead of a plain ResponseError. Stack traces
now show the exact error
class. All existing instanceof ResponseError checks continue to work.
- ErrorMatcher component — reads errorType from the thrown class
instance, does an O(1) lookup into
ERROR_MAPPINGS, and renders the matching troubleshooting accordion as
children of ErrorDisplay.
Falls back to plain ErrorDisplay for unclassified errors.
- Connection timeout mapping — first error type wired up, with three
troubleshooting steps: restart
the database, link to the docs, and "Debug with AI" (opens the AI
assistant sidebar with a
pre-filled prompt).
- Telemetry — three new typed events track when the troubleshooter is
shown, when accordion steps are
toggled, and which CTAs are clicked.
## Adding a new error type
1. Add a class to types/api-errors.ts
2. Add { pattern, ErrorClass } to data/error-patterns.ts
3. Create a troubleshooting component in errorMappings/
4. Add an entry to error-mappings.tsx
## Summary
- Adds a combined telemetry standards skill
(`.claude/skills/telemetry-standards/SKILL.md`) that covers PostHog
event naming conventions, property standards, review rules, and
implementation guide
- Intended to be imported as CodeRabbit learnings after merge so
CodeRabbit can flag missing/incorrect tracking in PRs
- Consolidates standards from existing `review-telemetry` and
`implement-tracking` Claude commands into a single source of truth
## Post-merge steps
### 1. Import as CodeRabbit learnings (one-time)
Comment on any PR in the repo:
```
@coderabbitai add a learning using .claude/skills/telemetry-standards/SKILL.md
```
This teaches CodeRabbit the telemetry standards. It will then:
- Flag naming/property violations when `telemetry-constants.ts` is
changed
- Suggest adding `useTrack()` tracking when PRs add user-facing
interactions without it
- Propose event names following `[object]_[verb]` convention
### 2. Add path instructions in CodeRabbit web UI (optional,
recommended)
Go to CodeRabbit settings > Review > Path Instructions and add:
- **Path:** `packages/common/telemetry-constants.ts`
- **Instructions:** "Strictly enforce event naming: [object]_[verb] in
snake_case. Only approved verbs: opened, clicked, submitted, created,
removed, updated, retrieved, intended, evaluated, added. Properties must
be camelCase and self-explanatory. Flag any usage of
useSendEventMutation."
### 3. Remove old Claude commands (after verifying skill works)
Delete `.claude/commands/review-telemetry.md` and
`.claude/commands/implement-tracking.md` — this skill replaces both.
Closes GROWTH-661
## 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?
LLM configuration
## What is the current behavior?
No skills for E2E tests
## What is the new behavior?
Claude skill for E2E tests
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Documentation**
* Added comprehensive end-to-end testing guidelines for Studio
Playwright tests, covering test execution, environment setup, robust
selector patterns, common pitfalls, debugging workflows, and CI
troubleshooting.
* **Chores**
* Updated repository ignore settings so skills-related documentation
files are tracked and can be committed.
<sub>✏️ Tip: You can customize this high-level summary in your review
settings.</sub>
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
To use Claude Code on web, we need the LLM to have access to
dependencies. This creates a install_pkgs.sh script that runs `pnpm
install` only in the Claude Code remove environment.
Gildas Garcia