@abloatai/ablo 0.42.0 → 0.44.0

package/AGENTS.md

@@ -13,9 +13,10 @@ Don't hand-write the integration. Run the CLI; it generates the current-API sche
 - **Auth:** set `ABLO_API_KEY` in the environment. Do **NOT** run `ablo login` — it opens a browser device flow and blocks an agent.
 - **Connect your database — logical replication (the primary path):** `npx ablo connect` prints the setup SQL (`wal_level=logical`, a publication, a `REPLICATION` role); `npx ablo connect register` registers the source with Ablo in one step. Ablo **consumes your Postgres' logical-replication stream** — it never runs DDL on, writes to, owns, or migrates your database, and your application keeps the write path. Registration **is** the enable; there is no tier or flag to pick. (Ablo hosts only the transaction log + coordination, never your rows.)
 - **Fallback — signed Data Source endpoint** (DB can't grant a `REPLICATION` role): the generated `ablo/data-source.ts` exposes one route; Ablo sends signed requests and your app touches its own DB. **Only in this mode** does `npx ablo migrate` provision the adapter's bookkeeping tables (`ablo_outbox`, `ablo_idempotency`) plus your Ablo models — it does **not** touch your other tables. Keep your own migrations (drizzle-kit / prisma migrate) for auth and anything outside the Ablo schema.
-- **No database yet?** Run `npx ablo dev --no-watch --branch <name>` to create an isolated non-root branch and obtain its expiring `sk_test_` credential. The branch uses a throwaway hosted data plane; Production remains the protected root. There is no shared Sandbox mode.
+- **No database yet?** Run `npx ablo dev --no-watch --branch <name>` to create an isolated non-root branch and obtain its expiring `sk_` credential. The branch uses a throwaway hosted data plane; Production remains the protected root. There is no shared Sandbox mode.
 - **Adopt an existing DB schema:** `npx ablo pull prisma [path]` / `pull drizzle <module>` (lossless) or `pull` (live DB, lossy). Writes `ablo/schema.ts`.
 - **Prepare a branch and push your schema — REQUIRED before any write works.** The server keeps its OWN copy of the schema. After you create or edit `ablo/schema.ts`, run `npx ablo dev --no-watch --branch <git-or-ci-ref>`: it ensures an isolated branch, mints a temporary branch credential, writes it to gitignored `.env.local`, pushes once, and exits. **Skip this and every write to a new or changed model fails with `server_execute_unknown_model`.** Plain `ablo dev` watches forever — never run it bare in an agent. `ablo push` is the lower-level one-shot command for an already selected key, including reviewed production deploys.
+- **Do not invent one key variable per environment.** Branches replaced manual `ABLO_STAGING_KEY` / `ABLO_DEV_KEY` switching. Runtime code always reads `ABLO_API_KEY`; `ablo dev` wires the Git branch's expiring key. Use `npx ablo whoami` for the strict server-confirmed project/branch, or `npx ablo whoami --key-env <NAME>` only to inspect an explicitly named CI/legacy/recovery key without copying its value into argv.
 - **Other long-running:** `npx ablo logs --no-follow` (default tails forever). `status`, `branch check`, `push`, `pull`, `check`, `generate`, `docs`, and `dev --no-watch` are one-shot.
 
 When you use the signed-endpoint fallback, the generated `ablo/data-source.ts` is the whole endpoint and needs no hand-editing: `dataSourceNext({ schema, apiKey, adapter: prismaDataSource(prisma, schema) })` (or `drizzleDataSource(db, schema)`). The adapter owns commit / idempotency / outbox.

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## 0.44.0
+
+### A scope denial names the wall it hit
+
+`capability_scope_denied` now distinguishes the Ablo capability allowlist
+from the customer database's row-level security. The error carries the
+required capability, the resolved operations, the participant and user
+principal, the branch, the organization and project, and any applied session
+settings, so "permission denied" is a diagnosis instead of a dead end: you
+can see whether your grant was missing a verb or whether your own database's
+row policy rejected the session context Ablo applied.
+
+### Write failures carry their request id
+
+A WebSocket write failure now carries the `requestId` the server logged it
+under, and a `wait: 'confirmed'` write rejects with the complete typed error
+rather than a bare failure, so the error you catch is the error the server
+recorded.
+
+### `doctor` reports readiness, not destiny
+
+`doctor` now says infrastructure is ready rather than promising a write will
+succeed, because database constraints and row-level security still apply at
+write time. The debugging guide explains how to read the new diagnostics,
+and documents that `list()` may answer from the local pool while
+`list({ type: 'complete' })` waits for the server round trip.
+
+## 0.43.0
+
+### Keys are branch-first
+
+A new key is simply `sk_…`, `rk_…`, `pk_…`, `ek_…`, or `mk_…`: thirty
+characters and a checksum, with no `live` or `test` in the name. A key's
+project and branch are bindings on the server-side key record, never claims
+encoded in the plaintext, so rotating, moving, or inspecting a key is a
+server-side question with a server-confirmed answer. Existing `live`/`test`
+keys keep working; those spellings are now compatibility forms rather than
+the model.
+
+What used to be called the effective key is now the runtime key, and
+`status --json` exposes it as `runtimeKey`. The documentation explains the
+project, branch, and capability model end to end in `docs/api-keys.md`,
+`docs/branch-development.md`, `docs/cli.md`, and `docs/data-sources.md`.
+
+### Credential lookup in the order mature CLIs use
+
+Commands resolve their credential from the process `ABLO_API_KEY` first, then
+an explicit `--env-file <path>`, then the stored credential. Read-only
+diagnostics may inspect `.env.local` to help; anything that mutates requires
+an explicit selection. Recovering a database connection is now one command:
+`ablo connect rotate` re-keys the existing roles in place and reuses the
+replication slot, so recovery never drops roles or touches your database by
+hand.
+
+### Removed
+
+`logs --mode` is gone: `logs` follows the branch bound to the key it runs
+with. The `effectiveKey` field of `status --json` is renamed `runtimeKey`.
+
 ## 0.42.0
 
 ### `ablo whoami`: what does this key act on?

package/docs/api-keys.md

@@ -10,19 +10,74 @@ import Ablo from '@abloatai/ablo';
 const ablo = Ablo({ apiKey: process.env.ABLO_API_KEY });
 ```
 
-The key identifies the Ablo account. Application code does not pass an organization id; Ablo derives scope from the credential.
+The server resolves the organization, project, immutable branch, and authority
+from the key. Application code does not pass those targeting axes separately.
 
 "Trusted" means the runtime can hold a secret: a backend or other server-side environment a browser can't read. Browser and app clients use the same `@abloatai/ablo` import but authenticate differently — they never carry a secret key.
 
-## Which credential to use
+## Start here: the normal workflow
+
+Branches replace manual environment-key juggling. You should not normally keep
+`ABLO_STAGING_KEY`, `ABLO_DEV_KEY`, and `ABLO_API_KEY_LIVE` beside one another
+and remap them before each command.
+
+| Job | Credential | How you get it |
+|---|---|---|
+| Manage a project or its branches | `mk_` | `npx ablo login --project <slug>` stores it for the CLI. |
+| Develop locally | expiring `sk_` bound to the current branch | `npx ablo dev` writes it as `ABLO_API_KEY` in gitignored `.env.local`. |
+| Prepare a branch once, including CI | expiring `sk_` bound to that branch | `npx ablo dev --no-watch --branch <ref>`; CI supplies `ABLO_MANAGEMENT_KEY`. |
+| Run the production backend | `sk_` bound to the production root | Store it as the deployment's `ABLO_API_KEY`. |
+| Read in a browser | `pk_` | Publishable, read-only key. |
+| Write in a browser as a user | short-lived `ek_` | Your backend exposes `authEndpoint` and mints it. |
+
+The everyday loop is therefore:
+
+```bash
+npx ablo login --project <project>  # once per project
+npx ablo dev                        # follows Git, mints and wires this branch
+npx ablo status                     # broad readiness report
+```
+
+Application code and agents still read one variable:
+
+```ts
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+```
+
+Switching Git branches does not re-scope the old key. Run `ablo dev` again; it
+ensures the matching Ablo branch and replaces `.env.local` with a fresh key
+bound to it.
+
+## Three axes, not a key per environment name
+
+A credential answers three separate questions:
+
+1. **Project:** which application inside the organization.
+2. **Branch (plane):** the production root or one immutable development/preview
+   child. Rows, schema, claims, logs, and database registration are isolated
+   here.
+3. **Capability and audience:** management (`mk_`), trusted runtime (`sk_`),
+   restricted/delegated runtime (`rk_`), publishable browser read (`pk_`), or
+   ephemeral user session (`ek_`).
+
+The prefix identifies the credential's capability class, not its target.
+`sk_` means a trusted runtime secret. The server-side key row decides whether
+that secret is bound to the production root or to a specific child branch. A
+project selection or branch slug in a request cannot override that binding.
+
+That is why Ablo does not need an application-level `environment` argument and
+why `ablo projects use` cannot re-scope a credential. The bearer credential
+already carries the target.
+
+## Which credential to pass to the SDK
 
 There's **one field — `apiKey`** — and what you pass depends on **where the code runs**.
 Pick your row:
 
 | Where your code runs | What to pass | Example |
 |---|---|---|
-| **Server / worker / CLI** (can hold a secret) | your secret `sk_`: it defaults to `ABLO_API_KEY`, so usually pass **nothing** | `Ablo({ schema })` |
-| **Browser: read-only** | a publishable `pk_` (safe to ship, like a Stripe `pk_`) | `Ablo({ schema, apiKey: process.env.NEXT_PUBLIC_ABLO_PUBLISHABLE_KEY })` |
+| **Server / worker / agent** (can hold a secret) | your secret `sk_`: it defaults to `ABLO_API_KEY`, so usually pass **nothing** | `Ablo({ schema })` |
+| **Browser: read-only** | a publishable `pk_` (safe to ship) | `Ablo({ schema, apiKey: process.env.NEXT_PUBLIC_ABLO_PUBLISHABLE_KEY })` |
 | **Browser: writing as the signed-in user** | `authEndpoint`: the route on your own backend that mints a short-lived per-user token | `Ablo({ schema, authEndpoint: '/api/ablo-session' })` |
 
 That's the whole story: one knob, filled by audience.
@@ -32,24 +87,18 @@ control-plane credential, not an application API key. It can manage projects
 and branches and exchange for a branch-bound runtime key. Do not pass it to
 `Ablo(...)` or put it in `ABLO_API_KEY`.
 
-**Coming from Stripe? It's the same key model, same prefixes:**
+The credential class lives in the prefix:
 
-| Stripe | Ablo | Where it goes |
+| Prefix | Purpose | Stored where |
 |---|---|---|
-| publishable `pk_` (client-safe) | `pk_` | browser: read-only |
-| secret `sk_` (server, full) | `sk_` | server: full authority |
-| restricted `rk_` (granular) | `rk_` | scoped agents (`agents.create({ can })`) |
-| ephemeral key (client, customer-scoped) | `ek_` | per-user browser sessions (`sessions.create({ user, can })`) |
-
-Ablo also has one credential class that Stripe does not need:
+| `mk_` | project and branch management | CLI credential store or `ABLO_MANAGEMENT_KEY` |
+| `sk_` | trusted runtime, full branch authority | server-side `ABLO_API_KEY` |
+| `rk_` | restricted runtime or agent | trusted runtime that needs the delegated scope |
+| `pk_` | publishable, browser-safe read access | browser bundle |
+| `ek_` | short-lived user session | browser memory |
 
-| Prefix | Purpose | Mode | Stored where |
-|---|---|---|---|
-| `mk_` | project and branch management | none | CLI credential store or `ABLO_MANAGEMENT_KEY` |
-
-Trust class lives in the prefix too — `sk_test_` / `sk_live_` — exactly like Stripe.
-It does not select a branch; the immutable server-side binding does that. The
-`apiKey` resolver fetching an `ek_` is Ablo's ephemeral-key flow: server mints, client holds.
+The prefix does not select a branch; the immutable server-side binding does.
+For an `ek_`, the server mints and the client holds the short-lived result.
 
 **Why a function for browser writes?** Anything you ship to a browser must be public, and a
 public `pk_` is **read-only** — it can't carry one specific user's write authority. So when
@@ -57,8 +106,8 @@ the browser writes *as the logged-in user*, your backend (which holds the secret
 knows who's signed in) mints a short-lived per-user token with `sessions.create({ user, can })`,
 and the browser's `apiKey` function fetches it. You don't manage refresh — the SDK calls the
 function once before connecting and then keeps the token fresh (re-mint before expiry, and on
-tab-focus / network-online / device-wake). This is the Stripe ephemeral-key / Supabase
-session model. For a read-only app you don't need any of this — just the `pk_` above.
+tab-focus / network-online / device-wake). For a read-only app you don't need
+any of this — just the `pk_` above.
 
 Server-side, because `apiKey` defaults to `process.env.ABLO_API_KEY`, most backend and agent
 code passes nothing. The secret `sk_` is **server-only** — never in a
@@ -90,12 +139,12 @@ Never ship a secret API key to a browser bundle.
 ## Publishable key (`pk_`): browser-safe, read-only
 
 For a read-only browser experience, a publishable key is safe to ship in the
-bundle. Like a Stripe `pk_` or a Supabase anon key, it is long-lived,
-org-scoped, and used **directly as the bearer** — never exchanged, never
+bundle. It is long-lived, org-scoped, and used **directly as the bearer** —
+never exchanged, never
 expires, nothing to refresh:
 
 ```ts
-const ablo = Ablo({ apiKey: process.env.NEXT_PUBLIC_ABLO_PUBLISHABLE_KEY }); // pk_live_…
+const ablo = Ablo({ apiKey: process.env.NEXT_PUBLIC_ABLO_PUBLISHABLE_KEY }); // pk_…
 ```
 
 A `pk_` grants **read-only** access to the org's data plane: it cannot write and
@@ -112,25 +161,53 @@ Production is the project's root branch. Development branches are isolated
 children, and a key's immutable branch binding decides which rows, schema,
 claims, and log it can reach:
 
-- `sk_test_…` — a key bound to a development branch. Its reads and
-  writes are invisible to production and to other branches.
-- `sk_live_…` — a key against your live data.
+- an `sk_…` bound to a development branch reads and writes only that child;
+  its rows are invisible to production and to other branches.
+- an `sk_…` bound to the root reads and writes production.
 
 `npx ablo dev` derives a branch from Git, ensures the matching child, and mints
-an expiring `sk_test_` key for it. The credential carries the immutable branch
+an expiring `sk_` key for it. The credential carries the immutable branch
 id; changing a slug in a request cannot change its authority. A child receives
 the parent's active schema when it is created and owns its artifact after that.
-A schema change reaches production only through the reviewed live-key path in
+A schema change reaches production only through the reviewed root-branch path in
 [Deployment](./deployment.md).
 
 The shared default sandbox is no longer part of the development workflow.
 Branch identity is required for newly provisioned CLI and runtime credentials.
 
+## Inspecting a credential
+
+Use `status` for the whole setup and `whoami` for the narrow identity question:
+
+```bash
+npx ablo status
+npx ablo whoami
+```
+
+`whoami` succeeds only when the server confirms the credential's organization,
+project, and branch. It never prints the full secret. For CI or recovery, inspect
+an explicitly named value without remapping `ABLO_API_KEY`:
+
+```bash
+npx ablo whoami --key-env PREVIEW_ABLO_KEY
+npx ablo whoami --key-env ABLO_API_KEY_LIVE --json
+```
+
+`--key-env` reads that exact name from the process, `.env.local`, or `.env`; the
+name makes the choice explicit, while the secret stays out of argv and shell
+history. `--key <value>` exists for one-off use but is less safe because shells
+and process listings may retain the value.
+
+Multiple custom-named keys are reasonable at a CI secret boundary or during a
+one-time migration from the old environment model. They are not the normal
+local-development workflow. After a stranded-plane recovery, retire obsolete
+variables rather than keeping them as permanent branch selectors.
+
 ## Scopes
 
 Keys carry scopes following the principle of least privilege — each key gets
 only what its job needs. A secret key with **no scopes** has full org authority
-(the default for a `sk_live_` backend key); a key with a non-empty scope set is
+(the default for a `sk_` backend key); a key with a non-empty scope set is
 restricted to exactly those grants:
 
 - `schema:push` — author the schema artifact on the key's bound plane
@@ -149,6 +226,23 @@ Branch binding remains an authority boundary even when a key has no granular
 scope strings: a temporary child key can act only inside that child. It cannot
 manage siblings or gain root authority.
 
+## Current and legacy key spellings
+
+New credentials use one spelling per capability class:
+
+```text
+sk_…  trusted runtime
+rk_…  restricted runtime
+pk_…  publishable read-only browser
+ek_…  ephemeral user session
+mk_…  project and branch management
+```
+
+Older `sk_live_…`, `sk_test_…`, `rk_live_…`, and related credentials continue
+to authenticate during migration. Their `live`/`test` segment is a legacy hint,
+not the source of truth. Rotation mints the current spelling, and `ablo whoami`
+shows the persisted branch that actually controls the key.
+
 ### `ablo dev`
 
 ```sh

package/docs/branch-development.md

@@ -30,7 +30,7 @@ Ablo branch
     ├── active schema artifact
     ├── isolated transaction plane
     ├── immutable branch id
-    └── expiring sk_test_ credential
+    └── expiring sk_ credential
               │
               ▼
         gitignored .env.local
@@ -46,6 +46,13 @@ request parameter.
 Production is the root branch. Development branches are children; they do not
 inherit production write authority.
 
+The branch workflow replaces a hand-maintained collection of environment keys.
+Your application always reads `ABLO_API_KEY`; `ablo dev` changes which
+branch-bound value sits there. Do not select branches in application code or
+invent `ABLO_STAGING_KEY`/`ABLO_FEATURE_KEY` conventions. See
+[API Keys](./api-keys.md#start-here-the-normal-workflow) for the complete
+project → branch → credential model.
+
 ## Before the first run
 
 Initialize the project and sign in:
@@ -113,7 +120,7 @@ branch.
 ### 3. Exchange for a temporary credential
 
 The stored `mk_` credential authorizes the branch-management call. The server then
-returns a new `sk_test_` credential bound only to the child branch.
+returns a new `sk_` credential bound only to the child branch.
 
 The default lifetime is eight hours:
 
@@ -135,7 +142,7 @@ The temporary credential is written to:
 
 ```dotenv
 # .env.local
-ABLO_API_KEY=sk_test_...
+ABLO_API_KEY=sk_...
 ```
 
 The CLI creates `.env.local` with owner-only permissions when possible and adds
@@ -158,6 +165,12 @@ unset ABLO_API_KEY
 npm run dev
 ```
 
+Confirm the branch the resulting key actually targets:
+
+```bash
+npx ablo whoami
+```
+
 ### 5. Load and push the schema
 
 By default, the CLI imports:

package/docs/cli.md

@@ -35,36 +35,59 @@ resume a branch and exchanges it for a temporary branch-bound runtime key.
 | `ablo login`             | Authorize in the browser; store one project management credential.         |
 | `ablo login --project <slug>` | Same, scoped to a project, which becomes active.                     |
 | `ablo logout`            | Remove the stored credentials.                                             |
-| `ablo status`            | Show the active org/project, effective credential, branch target, and server health. |
+| `ablo whoami`            | Strictly confirm which project and branch a credential acts on.            |
+| `ablo status`            | Show the active org/project, resolved runtime credential, branch target, and server health. |
+
+Credential precedence is deliberately small:
+
+1. `ABLO_API_KEY` in the process environment.
+2. An explicitly selected file, for commands that support
+   `--env-file <path>`.
+3. A stored credential for legacy compatibility.
+
+Read-only orientation commands (`status`, `whoami`, `logs`, and `connect
+locate/check`) may inspect the application's `.env.local` so they describe what
+the app would use. Mutations (`push`, `connect apply/rotate/register`, and
+`connect deregister`) never let an ambient file silently choose a branch. Pass
+`--env-file .env.local` when that file is the intended source; the command
+reports the server-confirmed branch before it writes. For one-time recovery,
+`connect deregister --key-env <NAME>` selects that exact named value without
+putting the secret in argv.
 
 Keys live in `~/.config/ablo/credentials.json` (mode `0600`), keyed by project.
 The non-secret `config.json` holds the active project. In **CI**, don't log in —
 set the project management credential as `ABLO_MANAGEMENT_KEY`; it overrides the
 stored credential during branch bootstrap.
 
-## Development branches vs live
+## Development branches and the production root
 
 A branch is your project at full strength over its own rows: the same models,
 the same schema artifacts, the same claims and the same rules production runs.
 
 Production is the project root. `ablo dev` creates or reuses a child branch for
-your Git branch, then mints a temporary `sk_test_` key bound to that child.
+your Git branch, then mints a temporary `sk_` key bound to that child.
 Reads, writes, schema artifacts, claims, and credentials stay isolated from
 production and from other development branches, which is what makes a
 schema-changing pull request as routine as a code-only one.
 
 There is no local mode switch. Development selection comes from Git or
-`--branch`; production authority comes only from an explicit live credential.
+`--branch`; production authority comes only from an explicit root-bound
+credential.
 Production schema changes use the reviewed one-shot path in
 [Deployment](./deployment.md).
 
+`ABLO_API_KEY` is the one runtime variable in every environment. Branches
+replace manually switching between custom names such as `ABLO_STAGING_KEY` and
+`ABLO_DEV_KEY`: rerun `ablo dev` when Git branches change. Use `ablo whoami`
+for the narrow identity question, or `ablo whoami --key-env <NAME>` to inspect
+an explicitly named CI/legacy key without exposing its value in argv.
+
 ## Projects
 
 An org can have multiple **projects**, each with its own isolated keys, schema,
 and data. Keys are scoped to a project **at mint** and never re-scoped, so the
-CLI keeps a separate credential profile per project — Stripe's
-`login --project-name` model. The active project (set with `projects use`)
-selects which profile every command authenticates with.
+CLI keeps a separate credential profile per project. The active project (set
+with `projects use`) selects which profile every command authenticates with.
 
 | Command                       | What it does                                                                       |
 | ----------------------------- | ---------------------------------------------------------------------------------- |
@@ -97,11 +120,11 @@ bypasses profiles for project/branch administration; the runtime key remains
 | Command                            | What it does                                                                                                                                  | Flags                                                                                                  |
 | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
 | `ablo init`                        | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. |: |
-| `ablo login` / `logout` / `status` | Authentication & status (above).                                                                                                              |: |
+| `ablo login` / `logout` / `whoami` / `status` | Authentication, exact credential identity, and readiness (above).                                                                              | `whoami --key-env <NAME>`, `whoami --json`, `status --json` |
 | `ablo projects list\|create\|use\|rename` | Manage projects and the active one (see [Projects](#projects)). Each project's keys/schema/data are isolated.                          | `--name "<display>"` (create/rename)                                                                    |
 | `ablo dev`                         | **Hosted**: ensure an isolated Git branch, wire its temporary key, push, then watch `ablo/schema.ts`.                                        | `--branch <slug>`, `--branch-ttl-hours <1-168>`, `--no-watch`, `--schema`, `--export`, `--url` |
 | `ablo branch list\|status\|check\|create\|ensure\|credential\|delete` | Manage and diagnose immutable branch planes and expiring credentials.                          | Run `ablo branch --help`; use `--json` for automation.                                                   |
-| `ablo logs`                        | Tail the effective credential's branch activity. Follows by default.                                                                          | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow` |
+| `ablo logs`                        | Tail the resolved runtime credential's branch activity. Follows by default.                                                                          | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow` |
 | `ablo push`                        | **Hosted**: upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |
 | `ablo migrate`                     | **Direct Postgres**: provision just the synced models (plus the adapter's `ablo_outbox` / `ablo_idempotency`) in your own `DATABASE_URL`. Leaves your other tables alone.                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
 | `ablo pull`                        | **Direct Postgres**: generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`).                              | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force`                                     |
@@ -121,7 +144,7 @@ npx ablo docs --json           # the page list, machine-readable
 ```
 
 These pages ship inside the npm package, so they describe the code beside them
-and stay reachable with no network — the sandboxes and CI runners agents work in
+and stay reachable with no network — isolated agent environments and CI runners
 often have none. That matters most when a project is pinned: `get` / `getAll` /
 `getCount` became `retrieve` / `list` in 0.35.0, and a website always describes
 the newest release, so an agent on an earlier version reads the new name and
@@ -151,9 +174,10 @@ for the exact discovery order, CI flow, database boundary, and troubleshooting.
 
 ## `ablo logs`
 
-Tail commit activity, like `stripe logs tail`. Scope comes from the key — a test
-key streams only its sandbox's writes, a live key the org's — so you never pass
-an org. Follows by default; `--no-follow` prints recent and exits.
+Tail commit activity. Scope comes from the persisted key binding: a child-bound
+key streams only that child, while a root-bound key
+streams production. You never pass a project or branch. Follows by default;
+`--no-follow` prints recent and exits.
 
 ```bash
 npx ablo logs                      # last 50, then stream

package/docs/concurrency-convention.md

@@ -111,7 +111,7 @@ Both scopes carry:
 
 | field | meaning |
 |---|---|
-| `object` | Stripe-style type tag: `'stale_notification'` |
+| `object` | stable type tag: `'stale_notification'` |
 | `scope` | `'row'` or `'group'` — which premise granularity fired |
 | `target` | **the row that moved**, and which parts: `{ model, id, fields }`. The same locator a claim names its subject with |
 | `readAt` | the watermark the committer reasoned against |

package/docs/data-sources.md

@@ -15,15 +15,48 @@ Ablo only writes rows into tables you already have, through a role scoped to
 exactly that.
 
 > **Just trying Ablo?** You don't need a database to start. Pass an `apiKey` only,
-> and Ablo keeps your rows in its own log so you can build the whole app today —
-> like Stripe test mode. For a sandbox you can throw away, point Ablo at a separate
-> or local Postgres. Connect your production database (below) when you're ready for
-> it to be the system of record.
+> and Ablo keeps your rows in its own log so you can build the whole app today.
+> `ablo dev` gives each Git branch its own isolated plane.
+> Keep it hosted with no database, or point that branch at a separate/local
+> Postgres. Connect your production root (below) when you're ready for its
+> database to be the system of record.
 
 Connecting sets up two capabilities on your Postgres: **logical replication**, so
 Ablo can read and confirm, and a **scoped DML role**, so Ablo can write. `ablo
 connect` prints the exact SQL. `ablo connect apply` runs it for you.
 
+Connect commands do not silently load a dotenv file for a mutation. Either
+export `ABLO_API_KEY` and `DATABASE_URL`, pass `--url`, or explicitly select the
+file:
+
+```bash
+npx ablo connect apply --env-file .env.local --yes
+```
+
+The explicit flag makes the credential choice visible and loads both the
+branch-bound key and database URL. Shell environment variables take precedence.
+
+If scoped roles already exist but their passwords are unavailable, do not drop
+them or run `DROP OWNED`. Rotate them in place and re-register the fresh
+credentials:
+
+```bash
+npx ablo connect rotate --env-file .env.local --yes
+```
+
+This is the supported recovery after moving a database between branches.
+
+For a one-time release from an older branch, select the named recovery key
+directly—no shell remapping:
+
+```bash
+npx ablo connect deregister --key-env OLD_ABLO_KEY --yes
+npx ablo connect rotate --env-file .env.local --yes
+```
+
+`--key-env` reads that exact variable from the process, `.env.local`, or `.env`
+without printing the secret. Retire the old variable after the move.
+
 ## Connect in one command
 
 ```bash
@@ -148,7 +181,7 @@ Your **app** holds only the API key — never a connection string:
 
 ```bash
 # .env — server runtime only, never the browser
-ABLO_API_KEY=sk_live_...
+ABLO_API_KEY=sk_...
 ```
 
 ```ts

package/docs/debugging.md

@@ -15,14 +15,31 @@ const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, debug: true });
 
 ## CLI environment and target
 
-The CLI checks an explicit credential in this order: exported `ABLO_API_KEY`,
-`.env.local`, `.env`, then the key saved by `ablo login`. An exported value wins
-over project files. If a stale shell export (for example `OPENAI_API_KEY`) is
-shadowing a value in `.env.local`, restart the shell or unset the stale variable.
+Read-only diagnostics (`status`, `whoami`, `logs`, and `connect locate/check`)
+may inspect the application-facing chain: exported `ABLO_API_KEY`,
+`.env.local`, `.env`, then the stored credential. An exported value wins over
+project files. Mutations (`push` and `connect apply/rotate/register/deregister`)
+are intentionally stricter: they read the process environment, an explicit
+`--env-file`, or a stored compatibility credential. An ambient file cannot
+silently choose the branch a mutation acts on.
 
-When a command appears to use the wrong plane or project, run `ablo status`.
-It reports the credential source and, when reachable, the server-confirmed
-project and environment; that confirmed target is authoritative.
+Use the two diagnostics according to the question:
+
+```bash
+npx ablo whoami    # strict: which project + branch does this credential target?
+npx ablo status    # broad: target, database, schema, drift, and write blockers
+```
+
+For an old, CI, or recovery key stored under another variable name:
+
+```bash
+npx ablo whoami --key-env ABLO_API_KEY_LIVE
+```
+
+That explicit lookup checks the process, `.env.local`, and `.env` for the named
+variable, keeps the value out of argv, and either returns a server-confirmed
+identity or fails non-zero. Do not infer that a key is invalid from an older
+CLI's generic identity error; rerun with the current CLI.
 
 `debug: true` is the simple switch. For finer control use `logLevel`, or set it without touching code via the `ABLO_LOG_LEVEL` environment variable.
 
@@ -216,3 +233,57 @@ AbloValidationError [model_required_field_missing]: A required field was absent.
 ```
 
 Branch on `err.code` (stable) — never on the message (rewordable). See [Client Behavior](./client-behavior.md) for the full error model and which codes are safe to retry.
+
+### Diagnosing `capability_scope_denied`
+
+The same stable code covers two different enforcement layers, so inspect
+`error.details.origin`:
+
+- `capability_allowlist`: the branch/session credential did not grant the
+  operation. `requiredCapability.scope` names the missing `model.verb`, and
+  `details.resolvedOperations` shows the grants the server actually resolved.
+- `database_row_level_security`: Ablo's capability gate allowed the operation,
+  but Postgres rejected it under the customer table's RLS policy.
+  `details.databaseSessionContext` shows the organization, project, branch,
+  participant kind, user principal, and custom session-setting values applied
+  to that transaction.
+
+Every rejected live commit carries `requestId` on the thrown error and
+`request_id` in its JSON form and warning line:
+
+```ts
+import { AbloError } from '@abloatai/ablo';
+
+try {
+  await ablo.documents.create({
+    data,
+    wait: 'confirmed',
+  });
+} catch (error) {
+  if (error instanceof AbloError) {
+    console.error(error.code, error.requestId, error.requiredCapability, error.details);
+  }
+}
+```
+
+With `wait: 'confirmed'`, the awaited call rejects with that complete typed
+error. `onMutationFailure` remains the notification channel for optimistic
+writes that return before the server answers; it is not required to recover
+details from a confirmed write.
+
+### Local reads versus a confirmed server read
+
+`list()` without a completeness option may return the current local pool
+immediately. That is why it can be empty while Postgres contains rows: it is not
+evidence that the replication source has no history.
+
+Use:
+
+```ts
+await ablo.documents.list({ type: 'complete' });
+```
+
+`type: 'complete'` waits for a server round trip and returns the confirmed
+result. `type: 'unknown'` returns the local result immediately and refreshes it
+in the background. The distinction is freshness/completeness, not claimed
+versus unclaimed data.