better-supabase 0.3.0 → 0.5.0

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "better-supabase",
-  "version": "0.3.0",
-  "description": "Strongly typed Supabase: generated schema, typed repositories, plugins, auth glue and framework integrations. The CLI ships as @better-supabase/cli.",
+  "version": "0.5.0",
+  "description": "Strongly typed Supabase: generated schema, typed repositories, plugins, auth glue, framework integrations and the better-supabase CLI.",
   "keywords": [
+    "cli",
+    "codegen",
     "hono",
     "mcp",
     "nextjs",
@@ -25,7 +27,11 @@
     "url": "git+https://github.com/ScaleDockHQ/better-supabase.git",
     "directory": "packages/better-supabase"
   },
+  "bin": {
+    "better-supabase": "./bin/better-supabase.js"
+  },
   "files": [
+    "bin",
     "dist",
     "schemas",
     "skills",
@@ -43,6 +49,10 @@
       "types": "./dist/config/index.d.ts",
       "default": "./dist/config/index.js"
     },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "default": "./dist/cli/index.js"
+    },
     "./client": {
       "types": "./dist/client/index.d.ts",
       "default": "./dist/client/index.js"
@@ -96,6 +106,14 @@
       "types": "./dist/jobs/index.d.ts",
       "default": "./dist/jobs/index.js"
     },
+    "./orgs": {
+      "types": "./dist/orgs/index.d.ts",
+      "default": "./dist/orgs/index.js"
+    },
+    "./notifications": {
+      "types": "./dist/notifications/index.d.ts",
+      "default": "./dist/notifications/index.js"
+    },
     "./env": {
       "types": "./dist/env/index.d.ts",
       "default": "./dist/env/index.js"
@@ -174,6 +192,7 @@
   "dependencies": {
     "@standard-schema/spec": "1.1.0",
     "@supabase/middleware": "1.0.0",
+    "@supabase/postgrest-js": "2.117.2",
     "@supabase/postgrest-typegen": "0.3.1",
     "@supabase/server": "1.9.0",
     "@supabase/ssr": "0.12.7"
@@ -182,12 +201,16 @@
     "@arethetypeswrong/cli": "0.18.5",
     "@better-supabase/ox-config": "0.0.0",
     "@better-supabase/typescript-config": "0.0.0",
+    "@clack/prompts": "1.8.1",
+    "@effect/platform-node": "4.0.0",
     "@opentelemetry/api": "1.9.1",
     "@orpc/server": "2.0.0-beta.40",
+    "@supabase/config": "0.11.1",
     "@supabase/supabase-js": "2.117.2",
+    "@t3-oss/env-core": "0.13.11",
     "@tanstack/query-core": "5.104.0",
     "@tanstack/react-query": "5.104.0",
-    "@types/node": "24.19.0",
+    "@types/node": "26.6.3",
     "@types/pg": "8.23.1",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",
@@ -195,14 +218,22 @@
     "@vitest/coverage-v8": "5.0.3",
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
+    "c12": "4.0.0-rc.2",
+    "citty": "0.2.2",
+    "diff": "9.0.0",
+    "effect": "4.0.0",
+    "fastest-levenshtein": "1.0.16",
     "hono": "4.13.12",
     "next": "16.3.8",
+    "oxfmt": "0.71.0",
     "oxlint": "1.86.0",
     "pg": "8.23.1",
     "publint": "0.3.24",
     "react": "19.3.0",
     "react-dom": "19.3.0",
+    "smol-toml": "1.9.0",
     "temporal-polyfill": "1.0.5",
+    "tinyexec": "1.3.1",
     "tsdown": "0.23.0",
     "typescript": "7.0.2",
     "valibot": "1.5.0",
@@ -210,13 +241,15 @@
     "zod": "4.6.5"
   },
   "peerDependencies": {
-    "@opentelemetry/api": ">=1.9",
-    "@orpc/server": ">=2.0.0-0",
+    "@opentelemetry/api": ">=1.9 <2",
+    "@orpc/server": ">=2.0.0-beta.40 <3",
+    "@supabase/config": ">=0.9.0 <0.12",
     "@supabase/supabase-js": "^2.116.0",
-    "@tanstack/query-core": "^5",
-    "hono": ">=4",
-    "next": ">=16",
-    "pg": ">=8",
+    "@tanstack/query-core": "^5.62.0",
+    "hono": ">=4 <5",
+    "next": ">=16 <17",
+    "oxfmt": "0.66.0",
+    "pg": ">=8.15 <9",
     "react": "^19",
     "temporal-polyfill": ">=1"
   },
@@ -227,6 +260,9 @@
     "@orpc/server": {
       "optional": true
     },
+    "@supabase/config": {
+      "optional": true
+    },
     "@tanstack/query-core": {
       "optional": true
     },
@@ -236,6 +272,9 @@
     "next": {
       "optional": true
     },
+    "oxfmt": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     },
@@ -253,8 +292,9 @@
     "bench": "node tests/next/next.bench.ts",
     "build": "tsdown",
     "check:publish": "publint && pnpm pack --out pack.tgz && attw --profile esm-only pack.tgz && rm -f pack.tgz",
+    "gen:fixtures": "node scripts/gen-fixtures.ts",
     "lint": "oxlint",
-    "test": "vitest run --coverage",
+    "test": "vitest run --project unit --coverage",
     "transit": "true",
     "typecheck": "tsc --noEmit"
   }

package/schemas/config-v1.json

@@ -292,7 +292,10 @@
               "type": "object",
               "additionalProperties": false,
               "properties": {
-                "scope": { "type": "string", "default": "organization" }
+                "scope": {
+                  "type": "string",
+                  "description": "The PermDock scope tenants are. Defaults to the manifest's root scope, the rls.scopes entry without within."
+                }
               }
             }
           ]
@@ -346,6 +349,11 @@
           "description": "Tables that broadcast change signals (`table` or `schema.table`). Install with `better-supabase sql add realtime-tables`.",
           "type": "array",
           "items": { "type": "string" }
+        },
+        "global": {
+          "description": "Tables in `tables` without a tenant column, which broadcast on one topic for every signed-in user.",
+          "type": "array",
+          "items": { "type": "string" }
         }
       }
     },
@@ -359,6 +367,14 @@
         "kit": { "type": "array", "items": { "type": "string" } }
       }
     },
+    "kits": {
+      "type": "object",
+      "description": "How each SQL kit module maps onto the database, keyed by module name.",
+      "properties": {
+        "access": { "$ref": "#/$defs/accessKit" }
+      },
+      "additionalProperties": { "$ref": "#/$defs/kitModule" }
+    },
     "seed": {
       "type": "object",
       "additionalProperties": false,
@@ -394,6 +410,120 @@
     }
   },
   "$defs": {
+    "stringRecord": {
+      "type": "object",
+      "additionalProperties": { "type": "string" }
+    },
+    "kitModuleProperties": {
+      "mode": { "enum": ["managed", "adopt", "custom"], "default": "managed" },
+      "schema": { "type": "string", "default": "better_supabase" },
+      "tables": {
+        "type": "object",
+        "additionalProperties": { "type": ["string", "null"] }
+      },
+      "columns": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "additionalProperties": { "type": ["string", "null"] }
+        }
+      },
+      "idType": { "type": "string" },
+      "triggerPrefix": { "type": "string", "default": "bs_" },
+      "permissions": { "$ref": "#/$defs/stringRecord" },
+      "options": { "type": "object" }
+    },
+    "kitModule": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "$ref": "#/$defs/kitModuleProperties/mode" },
+        "schema": { "$ref": "#/$defs/kitModuleProperties/schema" },
+        "tables": { "$ref": "#/$defs/kitModuleProperties/tables" },
+        "columns": { "$ref": "#/$defs/kitModuleProperties/columns" },
+        "idType": { "$ref": "#/$defs/kitModuleProperties/idType" },
+        "triggerPrefix": {
+          "$ref": "#/$defs/kitModuleProperties/triggerPrefix"
+        },
+        "permissions": { "$ref": "#/$defs/kitModuleProperties/permissions" },
+        "options": { "$ref": "#/$defs/kitModuleProperties/options" }
+      }
+    },
+    "accessKit": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "mode": { "$ref": "#/$defs/kitModuleProperties/mode" },
+        "schema": { "$ref": "#/$defs/kitModuleProperties/schema" },
+        "tables": { "$ref": "#/$defs/kitModuleProperties/tables" },
+        "columns": { "$ref": "#/$defs/kitModuleProperties/columns" },
+        "idType": { "$ref": "#/$defs/kitModuleProperties/idType" },
+        "triggerPrefix": {
+          "$ref": "#/$defs/kitModuleProperties/triggerPrefix"
+        },
+        "permissions": { "$ref": "#/$defs/kitModuleProperties/permissions" },
+        "options": { "$ref": "#/$defs/kitModuleProperties/options" },
+        "model": {
+          "enum": ["roles", "catalog", "permdock", "custom"],
+          "default": "roles"
+        },
+        "roles": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        },
+        "functions": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "can": { "type": "string" },
+            "tenantIdsWith": { "type": "string" },
+            "isPlatform": { "type": "string" },
+            "canUser": { "type": "string" },
+            "canAssign": { "type": "string" },
+            "permissionClaims": { "type": "string" }
+          }
+        },
+        "platformClaim": {
+          "type": "string",
+          "default": "platform_permissions"
+        },
+        "disabled": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "tenant": { "type": "string" },
+            "tenantKey": { "type": "string" },
+            "user": { "type": "string" },
+            "userKey": { "type": "string" }
+          }
+        },
+        "activeTenant": {
+          "oneOf": [
+            { "enum": ["claim", "resolver"] },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["profileColumn"],
+              "properties": {
+                "profileColumn": { "type": "string" },
+                "key": { "type": "string" }
+              }
+            }
+          ]
+        },
+        "permdock": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "schema": { "type": "string" },
+            "scope": { "type": "string" }
+          }
+        }
+      }
+    },
     "casing": { "enum": ["snake", "camel"] },
     "privileges": {
       "type": "array",

package/schemas/doctor-report-v1.json

@@ -73,6 +73,14 @@
               "BS304",
               "BS305",
               "BS306",
+              "BS307",
+              "BS308",
+              "BS309",
+              "BS310",
+              "BS311",
+              "BS312",
+              "BS313",
+              "BS314",
               "BS401",
               "BS402",
               "BS403",
@@ -81,6 +89,8 @@
               "BS406",
               "BS407",
               "BS408",
+              "BS409",
+              "BS410",
               "BS501",
               "BS502"
             ]

package/skills/better-supabase/SKILL.md

@@ -1,14 +1,18 @@
 ---
 name: better-supabase
-description: Query and write Supabase data with better-supabase's typed repositories, Results and codegen. Use when code imports better-supabase, when adding a table, query or mutation, or when a Supabase type is out of date.
+description: Query and write Supabase data with better-supabase's typed repositories, Results and codegen. Use when code imports better-supabase, when adding a table, query or mutation, when a Supabase type is out of date, or after upgrading better-supabase.
 ---
 
 # better-supabase
 
-The data layer is `sb = defineSupabase(schema)` in `src/lib/supabase.ts`.
+The data layer is `betterSupabase = defineSupabase(schema)` in `src/lib/supabase/index.ts`.
 `schema` comes from the generated module (`config.output`, usually
 `src/lib/supabase/generated.ts`). Never edit generated files.
 
+The `better-supabase` command ships in the `better-supabase` package, so
+`pnpm better-supabase <command>` works once the package is installed. There
+is no separate CLI package to add.
+
 ## Workflow: change the schema
 
 1. Write the migration: edit `supabase/schemas/*.sql`, then run
@@ -18,15 +22,18 @@ The data layer is `sb = defineSupabase(schema)` in `src/lib/supabase.ts`.
    data and role settings.
 2. For a new table in an exposed schema, in the same file: `enable row level
 security`, a policy per role and command the app uses, and an index on
-   every column a policy filters by. List the table in `expose` in
+   every column a policy filters by. Write tenant checks as
+   `organization_id in (select better_supabase.member_org_ids())`, which
+   Postgres runs once per statement, not `has_org_role(organization_id)`,
+   which runs once per row. List the table in `expose` in
    `better-supabase.config.ts` and run `pnpm better-supabase sql add grants`:
    new tables get no Data API grants on their own.
 3. Apply it with `supabase db reset` (or `supabase migration up`).
 4. Run `pnpm better-supabase gen`, then fix the type errors it surfaces.
-   The command comes from the `@better-supabase/cli` dev dependency.
 5. Run `pnpm better-supabase doctor` and fix every error it reports (RLS off,
    missing policies, missing grants, unindexed foreign keys, drift).
-6. Commit the generated files. CI runs `better-supabase gen --check`.
+6. Commit the generated files. CI runs `better-supabase gen --check`, which
+   prints a diff of each stale file.
 
 Done when `gen --check` and `doctor` exit 0 and the project typechecks.
 
@@ -44,14 +51,42 @@ Done when the call typechecks without casts, the error path returns the
 `DbError` (not a thrown exception), and a test shows another tenant's rows
 stay hidden.
 
+## Workflow: after upgrading better-supabase
+
+1. Run `pnpm better-supabase codemod <version> --dry-run` for each minor
+   version you crossed (`codemod` without a name lists them), then without
+   `--dry-run`, and fix the lines it lists for review.
+2. Run `pnpm better-supabase sql upgrade`, so the kit modules get the
+   release's SQL and any forward steps land in a migration, then write a
+   migration from the changed files.
+3. Run `pnpm better-supabase gen` and commit the result. Since 0.3, a
+   composite foreign key such as `(customer_id, organization_id)` is named
+   after the remaining column (`customer`); set `tables.<name>.relations` in
+   the config to keep an old relation name.
+4. Run `pnpm better-supabase skills install --check` and reinstall the skills
+   when it reports them stale.
+5. Read the release's breaking changes in
+   https://github.com/ScaleDockHQ/better-supabase/blob/main/CHANGELOG.md
+   (guides live under https://bettersupabase.com/docs/migration). For 0.3: time values are
+   `Temporal` (see below), `--db-url` is gone, `doctor --format json` is
+   `doctor --json`, `BetterResultShape` is `BetterResultValue`, and an
+   exhaustive `switch` over the `invalid` auth reason needs an `'actor'` case.
+
+Done when `gen --check`, `doctor` and the typecheck pass.
+
 ## Where `db` comes from
 
-- Next.js: `const { db } = await next.server()`, `next.route(...)`, `next.action(...)`
-- Next.js Cache Components: keep layouts synchronous; read `next.session()` in a `'use cache: private'` function inside `<Suspense>`, pass the promise to `<SessionProvider>` and read it with `useSession()`
+Name the definition `betterSupabase` (in `lib/supabase/index.ts`) and every runtime instance `bs` (`lib/supabase/server.ts`, `lib/supabase/client.ts`, or the Hono, oRPC or Edge Function entry).
+
+- Next.js: `const { db } = await bs.context()`, `bs.route(...)`, `bs.action(...)`
+- Next.js Cache Components: keep layouts synchronous; read `bs.session()` in a `'use cache: private'` function inside `<Suspense>`, pass the promise to `<SessionProvider>` and read it with `useSession()`
 - Hono: `c.var.db` after `bs.middleware()`
 - oRPC: `context.db` after `bs.middleware()`
 - Edge Functions: `bs.handler((request, { db }) => ...)`
-- Browser: `browser.db`, or the hooks from `createHooks<typeof browser>()`
+- Browser: `bs.db`, or the hooks from `createHooks<typeof bs>()`
+
+For who the caller is (sessions, claims, OAuth clients, agents, scopes), use
+the `better-supabase-auth` skill.
 
 ## Querying
 
@@ -68,18 +103,33 @@ const customers = result.data;
 ```
 
 - Methods return a `Result`, and database errors never throw. Use `.orThrow()` only where an exception is really wanted.
-- Column names use the configured casing (`casing: 'camel'` means `organizationId`). Raw escape hatches (`$client`, `$sql`) use database names.
+- Column names use the configured casing (`casing: 'camel'` means `organizationId`). Raw escape hatches (`$client`, and `queryRaw` on the `better-supabase/postgres` clients) use database names.
 - Writes: `create`, `createMany`, `update(id, patch)`, `updateMany`, `upsert`, `delete`.
+- Page lists with a cursor: `paginate({ after: null, size: 25, orderBy })`, then pass `nextCursor` back as `after` with the same `orderBy` and `where`. Use `page` numbers only when users jump to a page and need a total.
 - Handlers may return a `Result` directly. Adapters turn errors into RFC 9457 Problem Details with the right status.
-- Server-only admin access: `server.admin()`. Only use it for trusted jobs, never for a user's request.
+- Server-only admin access: `bs.admin()`. Only use it for trusted jobs, never for a user's request.
 - PostgREST has no multi-request transactions. Put multi-step writes in a database function (`db.$rpc()`) or use `postgres.transaction()` on the server.
 
+## Time values
+
+- With `codecs: { timestamptz: 'instant' }` in the config, `timestamptz` columns decode to `Temporal.Instant` and `timestamp` columns to `Temporal.PlainDateTime`, with microseconds. Without the codec they stay ISO strings.
+- `now` options, job and webhook timestamps and `bucket.sweep({ olderThan })` take `Temporal` values. Auth's `now` stays in epoch milliseconds.
+- On Node 24, Safari and other runtimes without `Temporal`, add `temporal-polyfill` and `import "temporal-polyfill/global"` once at startup. Without it, calls that need `Temporal` return an `unexpected` `DbError` that names the import.
+- Use TypeScript 6 or 7; 5.9 has no Temporal lib.
+
+## CLI in scripts and CI
+
+- No command takes a connection string as an argument. Set `$DATABASE_URL` or `source.dbUrl`, or pipe it in with `--db-url-stdin`.
+- `--json` prints one JSON document on stdout: the result, or Problem Details with a `code` on failure. `--yes` and `CI` turn prompts off.
+- Exit codes: 0 success, 1 a failure or finding (`--check` drift, doctor errors), 2 a usage, config or environment problem. Each error code is listed at https://bettersupabase.com/docs/cli/errors.
+
 ## Don't
 
 - Don't create supabase-js clients by hand, and don't read cookies yourself. Use the adapters.
 - Don't add `declare module` augmentation for types; everything comes from `schema`.
 - Don't catch and swallow `DbError`; return it, or map it with `mapDbError`.
 - Don't cast rows (`as Customer`). If a type is wrong, the schema or the generated file is out of date: rerun `gen`.
+- Don't convert `Temporal` values to `Date` to compare them; use `.equals()` or `Temporal.Instant.compare`.
 
 ## When something fails
 

package/skills/better-supabase/references/plugins.md

@@ -1,6 +1,6 @@
 # Plugins
 
-```ts title="src/lib/supabase.ts"
+```ts title="src/lib/supabase/index.ts"
 import { defineSupabase } from "better-supabase";
 import { actor } from "better-supabase/plugins/actor";
 import { softDelete } from "better-supabase/plugins/soft-delete";
@@ -8,10 +8,10 @@ import { tenant } from "better-supabase/plugins/tenant";
 import { timestamps } from "better-supabase/plugins/timestamps";
 import { validation } from "better-supabase/plugins/validation";
 
-import { schema } from "./supabase/generated.ts";
-import { validators } from "./supabase/generated.zod.ts";
+import { schema } from "./generated.ts";
+import { validators } from "./generated.zod.ts";
 
-export const sb = defineSupabase(schema)
+export const betterSupabase = defineSupabase(schema)
   .use(timestamps())
   .use(softDelete())
   .use(tenant())
@@ -53,16 +53,15 @@ filled it.
 RLS still decides what a user can read and write. `tenant()` makes queries
 explicit and fills the column; it doesn't replace the policy.
 
-The tenant comes from the verified `tenant_id` claim (renamed with
-`claims.tenant` in `better-supabase.config.ts`), then `app_metadata.tenant_id`.
-Never read it from `user_metadata`, a URL or a request body. When the project
+The tenant comes from `context.tenant`, which the server's `tenant` resolver
+sets per request (the default `kits.access.activeTenant: 'resolver'`), then
+the verified `tenant_id` claim (renamed with `claims.tenant` in
+`better-supabase.config.ts`), then `app_metadata.tenant_id`. A resolver may
+read the URL, but `current_tenant_id()` only returns a tenant the caller is a
+member of. Never trust a tenant from `user_metadata` or a request body. When the project
 has a `permdock.config.ts`, PermDock's hook writes that claim and the
-memberships; don't run `sql add tenant` there or call `membership_claims()`
-from a hook. `sql add entitlements` is fine: `features` is not a PermDock
-claim. Add `claims: { features: 'better_supabase.feature_claims' }` to
-`supabase.hook` in `permdock.config.ts`, run `permdock supabase hook generate`,
-and `hasEntitlement(session, ...)` works. Run `permdock supabase inspect --out`
-first: with `permdock.manifest.json` present, the entitlements module reads
-PermDock's `member_<scope>_ids` helpers and doesn't add `tenant`.
+memberships: don't run `sql add tenant`, and follow the PermDock reference of
+the `better-supabase-auth` skill
+(https://bettersupabase.com/docs/auth/permdock.md).
 
 Docs: https://bettersupabase.com/docs/plugins.md

package/skills/better-supabase/references/troubleshooting.md

@@ -11,29 +11,50 @@ Branch on `result.error.kind`, not on the message.
 | ----------------------------------------------------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
 | `not_found`                                           | The row doesn't exist, or RLS hides it from this user                          | Check the policy with an `asUser` test before assuming the row is gone        |
 | `unauthorized`                                        | No valid session or token                                                      | Get `db` from the adapter for this request                                    |
-| `forbidden`                                           | RLS or a grant rejected the write                                              | Fix the policy or the grant; don't switch to `server.admin()`                 |
+| `forbidden`                                           | RLS or a grant rejected the write                                              | Fix the policy or the grant; don't switch to `bs.admin()`                     |
 | `conflict`                                            | Unique violation                                                               | Use `upsert`, or return the error to the caller                               |
 | `foreign_key`                                         | Referenced row missing, or still referenced on delete                          | Create the parent first, or delete children                                   |
 | `not_null`, `check`, `exclusion`                      | A constraint rejected the row                                                  | Validate input earlier with the `validation()` plugin                         |
 | `invalid_input`                                       | Postgres couldn't parse a value (bad uuid, enum)                               | Validate before the call                                                      |
+| `invalid_value`                                       | A stored value the app type can't hold (`infinity` in a Temporal timestamp)    | Store a real timestamp or `null`, or read the column without the codec        |
 | `validation`                                          | A Standard Schema rejected the input; see `issues`                             | Show the issues to the user                                                   |
 | `invalid_request`                                     | The query can't run over PostgREST (for example a relation filter on `update`) | Read the keys first, or use a database function or `better-supabase/postgres` |
 | `multiple_rows`                                       | `findUnique` or a single-row write matched more than one row                   | Filter by a unique key                                                        |
 | `stale`                                               | `update(..., { expect })` found a newer row                                    | Reload the row and retry                                                      |
 | `serialization`, `timeout`, `network`, `rate_limited` | Transient                                                                      | Retry with backoff, or surface the error                                      |
 | `raised`                                              | A database function raised an exception                                        | Read `message` and `code` from the function                                   |
+| `unexpected` naming `temporal-polyfill/global`        | The runtime has no `Temporal` (Node 24, Safari)                                | Install `temporal-polyfill` and import `temporal-polyfill/global` at startup  |
+
+## By error `code`
+
+| Code                             | Meaning                                                                    | Fix                                                                                        |
+| -------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `CLAIMS_INVALID` (unauthorized)  | The token verified but failed the `betterSupabase.claims(schema)` schema   | Fix the access token hook or loosen the schema; the error names the failing paths          |
+| `SESSION_REVOKED` (unauthorized) | `checkSession` found the session gone (signed out, or ended by an admin)   | Expected for irreversible actions; ask the user to sign in again                           |
+| `INSUFFICIENT_SCOPE` (forbidden) | A delegated token (OAuth client or agent) lacks a scope the route requires | The 403 carries an `insufficient_scope` challenge; the client asks the user for that scope |
 
 ## Other symptoms
 
 - Types don't match the database: run `pnpm better-supabase gen`, then
   `gen --check` in CI.
 - A column name is `snake_case` in one place and `camelCase` in another:
-  repositories use the configured casing, `$client` and `$sql` use database
-  names.
+  repositories use the configured casing, `$client` and `queryRaw` use
+  database names.
 - Every request calls the Auth server: the token is being refreshed outside
-  the proxy. Refresh happens only in the Next.js proxy (`next.proxy`).
+  the proxy. Refresh happens only in the Next.js proxy (`bs.proxy`).
 - Tests pass with the service role but fail as a user: that's the RLS policy.
   Test as users, never with the service role.
+- A relation name changed after `gen`: a composite foreign key that repeats a
+  column on both sides is named after the remaining column. Set
+  `tables.<name>.relations` in the config to keep the old name.
+- The CLI exits with 2: the command line, the config or an environment
+  variable needs a change. Rerun with `--json` to get the error `code`, and
+  look it up at https://bettersupabase.com/docs/cli/errors.
+- `--db-url` is rejected: set `$DATABASE_URL` or pipe the URL in with
+  `--db-url-stdin`.
+- Two different `Temporal.Instant` values compare equal in `toEqual`: compare
+  with `.equals()` or register an equality tester (the
+  `better-supabase-testing` skill).
 
 Docs: https://bettersupabase.com/docs/cli/doctor.md and
 https://bettersupabase.com/docs/guides/limitations.md