---
name: auth-schema
description: Regenerate the Better Auth Convex schema from the auth config with the Better Auth CLI. Read before changing the auth data model — editing plugins/fields in convex/auth.ts or convex/betterAuth/, bumping the better-auth version, or when a Convex push / tsc fails on a missing or renamed auth table (generated_schema.ts has drifted).
---

# auth-schema

The Better Auth Convex tables are **generated** from the auth config, never hand-written — this skill
covers regenerating them and what to touch afterward. The CLI reads the static `auth` instance in
[`convex/betterAuth/auth.ts`](../../../services/platform/convex/betterAuth/auth.ts) (built from the
real config in [`convex/auth.ts`](../../../services/platform/convex/auth.ts) — plugins like
`organization`+teams, `twoFactor`, passkey) and emits the table definitions. Backend conventions live
in [`convex`](../convex/SKILL.md); auth-handling rules in [`security`](../security/SKILL.md).

## When this applies

Regenerate after **any** change to the auth data model:

- editing the plugin list / fields / `getAuthOptions` in `convex/auth.ts`,
- bumping `better-auth` or `@convex-dev/better-auth` in
  [`services/platform/package.json`](../../../services/platform/package.json),
- a Convex push or `bunx tsc --noEmit` that fails on a missing or renamed auth table — the generated
  schema has drifted from the config.

## The rules

- **Run the CLI, not a script.** There is no bun/npm script for this; `bunx` fetches `@better-auth/cli`
  (the `better-auth` dep is already installed). From `services/platform`:

  ```bash
  cd convex/betterAuth && bunx @better-auth/cli generate -y --output generated_schema.ts
  ```

  This rewrites only
  [`convex/betterAuth/generated_schema.ts`](../../../services/platform/convex/betterAuth/generated_schema.ts)
  — the base `tables` (user, session, account, apikey, member, teamMember, …). It touches nothing else.

- **Never hand-edit `generated_schema.ts`.** It carries a "Do not edit this file manually" header;
  edits are lost on the next run. Repo-specific extensions — the `apikey` field relaxations + `suffix`,
  the `member`/`teamMember` composite indexes — go in the sibling
  [`convex/betterAuth/schema.ts`](../../../services/platform/convex/betterAuth/schema.ts), which spreads
  the generated `tables` and layers on top. Edit `schema.ts`, never `generated_schema.ts`. (reviewer-caught)

- **Commit the generated file** alongside the config change — it's checked in, not built at runtime.
  A stale committed schema is what makes a teammate's push fail.

## Patterns

After generating, in order:

1. **Review the diff** — `git diff services/platform/convex/betterAuth/generated_schema.ts`. The table
   changes must match the auth-config change you made; nothing else should move.
2. **Re-check `schema.ts`** — if a field you override (e.g. `apikey.configId`) was renamed or dropped
   upstream, fix the override so the spread still resolves.
3. **Regenerate Convex codegen** — `bunx convex codegen` (needs a live `CONVEX_DEPLOYMENT`) so
   `_generated`/`api.d.ts` reflect the new tables; see [`convex`](../convex/SKILL.md).
4. **Typecheck** — `bun run --filter @tale/platform typecheck`.