Skip to content

Commit edb9bab

Browse files
alexcarpenteralexcarpenter
authored
docs(repo): fix stale facts in agent instructions (#10544)
1 parent cd21ebe commit edb9bab

11 files changed

Lines changed: 66 additions & 116 deletions

File tree

‎.changeset/fix-stale-agent-docs.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
---
2+
---

‎.claude/skills/clerk-monorepo/SKILL.md‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,7 @@ description: >-
1111

1212
# Working in the clerk/javascript monorepo
1313

14-
This is Clerk's JavaScript SDK monorepo: 24 packages (22 published `@clerk/*` plus the private
15-
`@clerk/msw` and `@clerk/swingset`) managed with pnpm
14+
This is Clerk's JavaScript SDK monorepo: the `@clerk/*` packages under `packages/`, managed with pnpm
1615
workspaces and Turborepo. Read this before building, testing, committing, or touching anything
1716
under `packages/`.
1817

@@ -27,7 +26,7 @@ The order matters more than the commands. Do them in sequence:
2726
1. **Node `>=24.15.0`** (pinned in `.nvmrc`). `nvm use` if you have nvm. Wrong Node version is the
2827
single most common cause of cryptic "cannot find module @clerk/..." build errors.
2928
2. **`corepack enable`** before installing. The `preinstall` hook runs `only-allow pnpm`; npm/yarn
30-
are hard-blocked. Corepack pins the right pnpm (`>=10.33.0`).
29+
are hard-blocked. Corepack pins the right pnpm (`engines` in `package.json`).
3130
3. **`pnpm install` from the repo root** (never a subdirectory). It is a workspace; installing from
3231
a package dir leaves cross-package links broken.
3332
4. **`pnpm build`** before anything else. Packages depend on each other's built `dist/` + `.d.ts`.
@@ -39,7 +38,7 @@ Full sequence, the 11 footguns, and the internal integration-test / 1Password se
3938

4039
## Package map: where does X live?
4140

42-
The ~10 packages people touch most. Full 25-package table, the dependency pyramid, and the complete
41+
The ~10 packages people touch most. How to list every package, the dependency pyramid, and the complete
4342
"change X, touch Y" routing are in [`references/package-map.md`](references/package-map.md).
4443

4544
| Package | You change it when... |
@@ -143,8 +142,8 @@ see [`references/setup-and-footguns.md`](references/setup-and-footguns.md) and `
143142

144143
Each rule below restates `AGENTS.md`; the parenthetical is how it is enforced.
145144

146-
- **pnpm only, Node `>=24.15`, pnpm `>=10.33`.** (`preinstall` blocks npm/yarn; `engines` in
147-
`package.json`.)
145+
- **pnpm only, at the Node and pnpm versions in `engines` in `package.json`.** (`preinstall` blocks
146+
npm/yarn.)
148147
- **Every PR needs a changeset.** Write the file directly; the `pnpm changeset` /
149148
`pnpm changeset:empty` scripts are interactive prompts an agent cannot drive. A changeset is a
150149
changelog entry for users upgrading, not a summary of the diff. See

‎.claude/skills/clerk-monorepo/references/package-map.md‎

Lines changed: 16 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,25 @@
11
# Package map
22

3-
The 25 active, git-tracked packages, the dependency shape, and the full "change X, touch Y" routing.
4-
`SKILL.md` has the short version (the ~10 packages people touch most).
5-
6-
> The authoritative package list is the set of `packages/*/package.json` files tracked in git. The
7-
> `packages/` directory can also hold leftover build artifacts from **removed** packages (e.g.
8-
> `types`, `remix`, `themes`, `elements`, `agent-toolkit`, `dev-cli`) that contain only build output
9-
> (`dist/`, `node_modules/`, `.turbo/`) and no `package.json`. Those are not active packages and are
10-
> not valid commit scopes.
3+
Every package, the dependency shape, and the full "change X, touch Y" routing. `SKILL.md` has the
4+
short version (the ~10 packages people touch most).
115

126
## All packages
137

14-
Categories: **foundational** (depended on by most others), **browser-runtime** (ships to the
15-
browser directly), **adapter** (framework SDK), **ui/i18n**, **tooling**. The "BC" column marks the
16-
two packages whose runtime is pushed into apps pinned to older SDKs, so they carry the strict
17-
backwards-compatibility contract (see `breaking-changes.md`).
8+
The package list is the set of git-tracked `packages/*/package.json` files. Most have a
9+
`description` saying what the package is, and `"private": true` marks the ones that never publish:
10+
11+
```bash
12+
for f in $(git ls-files 'packages/*/package.json' | awk -F/ 'NF==3'); do
13+
node -p "const p = require('./$f'); p.name + (p.private ? ' (private)' : '') + ': ' + (p.description ?? '')"
14+
done
15+
```
16+
17+
The `packages/` directory can also hold leftover build artifacts from **removed** packages (e.g.
18+
`types`, `remix`, `themes`, `elements`) with no `package.json`. Those are not active packages and are
19+
not valid commit scopes.
1820

19-
| Package | Category | BC | Purpose |
20-
| ------------------------------- | --------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
21-
| `@clerk/shared` | foundational | | Internal utilities used by all SDKs (storage, events, React helpers). Hosts the shared types as `@clerk/shared/types`. Most-depended-on package. |
22-
| `@clerk/backend` | foundational | | Backend API REST client, JWT verification, webhook helpers. Used by every server adapter. |
23-
| `@clerk/clerk-js` | browser-runtime | ⚠️ | The browser runtime (script tag). Backwards-compat sensitive. |
24-
| `@clerk/ui` | ui | ⚠️ | React components for the hosted sign-in / sign-up flows (`packages/ui/src/components`). Consumed by the react/astro/vue/chrome-extension adapters. Backwards-compat sensitive. |
25-
| `@clerk/mosaic` | ui | | Experimental next-generation React components. Public ESM package (`UserButton` + `styles.css`). Ships unstyled, accessible primitives (dialog, menu, popover, ...) internally under `src/primitives/`. Reads Clerk context from the host SDK via `@clerk/shared`. |
26-
| `@clerk/react` | adapter (core) | | React hooks and context (`useAuth`, `useUser`, `useOrganization`, ...). Shared by the React-based adapters. |
27-
| `@clerk/nextjs` | adapter | | Next.js SDK: middleware, route handlers, server components. |
28-
| `@clerk/express` | adapter | | Express middleware and server helpers. |
29-
| `@clerk/fastify` | adapter | | Fastify plugin. |
30-
| `@clerk/hono` | adapter | | Hono SDK (edge / serverless). |
31-
| `@clerk/astro` | adapter | | Astro integration (components + server utilities). |
32-
| `@clerk/nuxt` | adapter | | Nuxt module (Vue). |
33-
| `@clerk/vue` | adapter | | Vue 3 composables and components. |
34-
| `@clerk/react-router` | adapter | | React Router v7 SDK. |
35-
| `@clerk/tanstack-react-start` | adapter | | TanStack React Start SDK. |
36-
| `@clerk/expo` | adapter | | React Native / Expo SDK. |
37-
| `@clerk/expo-native-components` | adapter | | Native components (`AuthView`, `UserButton`, `UserProfileView`) and the native module for Expo, built on clerk-ios / clerk-android. Optional companion to `@clerk/expo`. |
38-
| `@clerk/expo-passkeys` | adapter | | Passkeys companion library for Expo. |
39-
| `@clerk/chrome-extension` | browser-runtime | | SDK for Chrome extension contexts. |
40-
| `@clerk/localizations` | ui/i18n | | Translation strings for the UI components. Consumed by `ui`. |
41-
| `@clerk/testing` | tooling | | E2E test helpers for consumers (Playwright + Cypress). |
42-
| `@clerk/msw` | tooling | | MSW request handlers for mocking the Clerk API in tests. Private (not published). |
43-
| `@clerk/swingset` | tooling | | Component explorer for `@clerk/mosaic`. Private (not published). |
44-
| `@clerk/upgrade` | tooling | | CLI codemod tool for upgrading consumers between SDK versions. |
45-
| `@clerk/eslint-plugin` | tooling | | ESLint plugin enforcing Clerk patterns across JavaScript frameworks (lint rules shipped to apps). Published. |
21+
Only `@clerk/clerk-js` and `@clerk/ui` carry the strict backwards-compatibility contract: their
22+
runtime is pushed into apps pinned to older SDKs (see `breaking-changes.md`).
4623

4724
Tests: `pnpm turbo test --filter=@clerk/<name>` (or `pnpm --filter @clerk/<name> test` after a
4825
build). Most packages use vitest; `@clerk/backend` runs a multi-runtime suite (node + edge +

‎.claude/skills/clerk-monorepo/references/setup-and-footguns.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ integration-test setup. The short happy path is in `SKILL.md`; this is the full
1212
`Cannot find module '@clerk/shared'` or missing-type errors downstream.
1313
2. **`corepack enable`** before installing. `package.json` has `preinstall: only-allow pnpm`, so
1414
npm and yarn are blocked outright. Corepack reads `packageManager` and uses the pinned pnpm
15-
(`>=10.33.0`). Without it you may run a mismatched global pnpm.
15+
(`engines` in `package.json`). Without it you may run a mismatched global pnpm.
1616
3. **`git clone` and `cd` into the repo root.**
1717
4. **`pnpm install` from the root.** This is a pnpm workspace; the root install links all packages
1818
together. Installing from a package subdirectory leaves workspace links broken. First install

‎.cursor/commands/cmt.md‎

Lines changed: 19 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
description: v7 - Generate commit message from chat changes
2+
description: v8 - Generate commit message from chat changes
33
(note to LLMs: increment version when you make changes to this file)
44
---
55

@@ -9,16 +9,11 @@ Generate a commit message for changes in this chat. **Do not commit or push** (s
99

1010
---
1111

12-
## ⚙️ REPO-SPECIFIC CONFIGURATION
12+
## Scopes and types
1313

14-
> **Edit this section when using in a new repository.**
14+
The scope is required. Valid scopes: any `packages/*` short name, the same name with `clerk-` removed (`clerk-js` or `js`), or `repo`, `release`, `e2e`, `ci`, `*`. Source of truth: `commitlint.config.ts`.
1515

16-
### Valid Scopes
17-
18-
Scopes must match package/app names. No scope is also valid. Invalid scope = commitlint rejection.
19-
20-
- **Packages:** astro, backend, chrome-extension, clerk-js, elements, expo, expo-passkeys, express, fastify, localizations, nextjs, nuxt, react, react-router, remix, shared, tanstack-react-start, testing, themes, types, ui, upgrade, vue
21-
- **Other:** docs, repo, release, e2e, \*
16+
Only the PR title is linted, and it becomes the squash commit, so the title format matters most.
2217

2318
---
2419

@@ -33,31 +28,17 @@ Scopes must match package/app names. No scope is also valid. Invalid scope = com
3328

3429
## Valid Types
3530

36-
**Types (REQUIRED - ALWAYS FIRST):** feat | fix | build | chore | ci | perf | refactor | revert | style | test
37-
38-
## FORMAT - READ THIS CAREFULLY
39-
40-
**CRITICAL: Type is MANDATORY and ALWAYS comes FIRST**
41-
42-
```
43-
type(scope): description ← CORRECT: type first, scope optional
44-
type: description ← CORRECT: type without scope
45-
```
31+
feat | fix | docs | build | chore | ci | perf | refactor | revert | style | test
4632

47-
**WRONG FORMATS:**
33+
## Format
4834

4935
```
50-
docs: description ← WRONG: "docs" is a SCOPE, not a type!
51-
scope: description ← WRONG: missing type!
36+
type(scope): description ← CORRECT
37+
type: description ← WRONG: scope is required
38+
scope: description ← WRONG: missing type
5239
```
5340

54-
**If working with docs:**
55-
56-
```
57-
feat(docs): add new guide ← CORRECT
58-
chore(docs): update readme ← CORRECT
59-
docs: something ← WRONG
60-
```
41+
`docs` is a type, not a scope: `docs(repo): update contributing guide`.
6142

6243
## Process
6344

@@ -75,7 +56,7 @@ docs: something ← WRONG
7556
7657
Then **STOP and wait** for response.
7758

78-
6. Generate commit message (TYPE FIRST, then optional scope in parentheses)
59+
6. Generate commit message (type first, then the scope in parentheses)
7960
7. If "stage" present → run `git add` on affected files (only chat-mentioned files unless "all" flag present)
8061

8162
## Format Rules
@@ -84,9 +65,8 @@ docs: something ← WRONG
8465
type(scope): description
8566
```
8667

87-
- **TYPE IS REQUIRED** - one of: feat, fix, build, chore, ci, perf, refactor, revert, style, test
88-
- **SCOPE IS OPTIONAL** - if present, wrap in parentheses after type
89-
- All lowercase, ≤72 chars
68+
- Type and scope are both required
69+
- ≤72 chars
9070
- Title = "what it does", body = "why"
9171
- Be specific (use domain terms from conversation, not generic words)
9272
- No filler: avoid "update", "changes", "code" when meaningless
@@ -121,7 +101,7 @@ Why:
121101
## Examples
122102

123103
```
124-
feat(api): add rate limiting to auth endpoints
104+
feat(backend): add rate limiting to auth endpoints
125105
126106
Why:
127107
DDoS attacks on /api/sign-in caused production degradation.
@@ -136,21 +116,21 @@ May need IP allowlist for trusted services (CLERK-5678).
136116
```
137117

138118
```
139-
chore(docs): fix typo in authentication guide
119+
docs(nextjs): fix typo in the middleware README
140120
141121
Why:
142122
Users reported confusion from misspelling.
143123
```
144124

145125
```
146-
ci: consolidate test job into checks to speed up pipeline
126+
ci(repo): consolidate test job into checks to speed up pipeline
147127
148128
Why:
149129
Reduce CI overhead by running tests in same job as lint/type checks.
150130
```
151131

152132
```
153-
feat(docs): document commitlint scope validation system
133+
docs(repo): document commitlint scope validation system
154134
155135
Why:
156136
Added clear documentation to help contributors understand scope requirements.
@@ -159,9 +139,9 @@ Added clear documentation to help contributors understand scope requirements.
159139
## Remember
160140

161141
- Important:Do not add unnecessary new lines or paragraphs to sentences. Let the editor wrap lines as needed.
162-
- **TYPE FIRST, ALWAYS** - never start with a scope
142+
- **TYPE FIRST, ALWAYS**, then the scope in parentheses
163143
- **NEVER COMMIT OR PUSH**
164-
- Type is REQUIRED, scope is optional
144+
- Type and scope are both required
165145
- **Always explain WHY changes were made** - what problem was being solved, what issues were identified, what motivated the change
166146
- **Provide enough context** - someone reading the commit in 2 years should understand the reasoning without access to the conversation
167147
- Only ask questions for high-impact changes

‎.cursor/rules/clerk-js-ui.mdc‎

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -164,15 +164,10 @@ const errorMessage = translateError(apiError);
164164
### Card Pattern
165165
```tsx
166166
const MyCard = () => (
167-
<Card>
168-
<Card.Root>
169-
<Card.Header>
170-
<Card.Title>Title</Card.Title>
171-
</Card.Header>
172-
<Card.Content>Content</Card.Content>
173-
<Card.Footer>Footer</Card.Footer>
174-
</Card.Root>
175-
</Card>
167+
<Card.Root>
168+
<Card.Content>Content</Card.Content>
169+
<Card.Footer>Footer</Card.Footer>
170+
</Card.Root>
176171
);
177172
```
178173

0 commit comments

Comments
 (0)