@abloatai/ablo 0.41.0 → 0.43.0

package/docs/deployment.md

@@ -6,20 +6,17 @@ One command answers the question this page exists for — would a write succeed
 right now, and if not, why:
 
 ```bash
-ABLO_API_KEY=sk_live_… npx ablo status
+ABLO_API_KEY=sk_… npx ablo status
 ```
 
 ```text
   ablo status
 
-  key     sk_live_51H8… (ABLO_API_KEY env — overrides stored)
-  mode    production
+  key     sk_51H8… (ABLO_API_KEY env — overrides stored)
   org     org_3nKq…
   project checkout (prj_7Yb2…)
-  acts on production
-  ○ sandbox     sk_test_9fJd… · expires in 71d
-  ● production  — no key
-  push    production with sk_live_51H8… (env)
+  acts on production root
+  push    production with sk_51H8… (env)
   api     https://api.abloatai.com  reachable
   data    ✓ database connected to this plane (direct)
   schema  4 models pushed (rev 12) hash 3f9a2c81 @ 2026-07-18
@@ -45,7 +42,7 @@ three pieces pointed at the same plane.
 
 | Ingredient | Who runs it | What "deploying" means for it |
 |---|---|---|
-| **Your Postgres** | You (or your provider) | Registering it against your production plane, once, with a production key. |
+| **Your Postgres** | You (or your provider) | Registering it against the production root, once, with a root-bound key. |
 | **Ablo** | Hosted at `api.abloatai.com` | Nothing to run. You choose a project, a plane, and the keys that reach them. |
 | **Your app and agents** | You | Holding the right credential for the runtime, and pushing the schema in the deploy. |
 
@@ -62,10 +59,9 @@ per-plane, and knowing which three is most of what production readiness means:
   your dev database are separate registrations.
 - **The active schema artifact:** the model shapes the engine actually routes on.
 
-A key's plane is fixed at mint: `sk_live_` acts on production, while `sk_test_`
-is bound to one development branch. The immutable branch id,
-not a user-supplied slug, is the selector. This is why application code never
-passes an environment.
+Every `sk_` is fixed to one branch at mint. The persisted branch id—not a
+suffix or user-supplied slug—says whether that is the production root or one
+development child. This is why application code never passes an environment.
 
 A child copies its parent's active schema when it is created, then owns its
 schema history. A child push never changes production. Production gets new
@@ -78,12 +74,12 @@ There is no shared development plane. New credentials are branch-bound; follow
 
 Your production database joins Ablo the same way your dev database did — logical
 replication so Ablo can read and confirm, a scoped writer role so Ablo can land
-rows — run once, with a production key so the registration attaches to the
-production plane:
+rows — run once, with a root-bound key so the registration attaches to the
+production root:
 
 ```bash
-ABLO_API_KEY=sk_live_… npx ablo connect apply --url postgres://admin:…@host:5432/db
-ABLO_API_KEY=sk_live_… npx ablo connect check
+ABLO_API_KEY=sk_… npx ablo connect apply --url postgres://admin:…@host:5432/db
+ABLO_API_KEY=sk_… npx ablo connect check
 ```
 
 [Connect Your Database](./data-sources.md) is the full walkthrough — the SQL, the
@@ -129,28 +125,41 @@ runs. In production that resolves to four rows:
 
 | Runtime | Credential | Notes |
 |---|---|---|
-| Server, worker, agent, cron | `sk_live_` in `ABLO_API_KEY` | Defaults from the environment, so most code passes nothing. |
-| Serverless function | `sk_live_` in `ABLO_API_KEY`, with `transport: 'http'` | Stateless request/response; nothing held open across invocations. |
-| Browser, read-only | `pk_live_` | Publishable and safe to ship, like a Stripe `pk_`. Reads only. |
+| Server, worker, agent, cron | `sk_` in `ABLO_API_KEY` | Defaults from the environment, so most code passes nothing. |
+| Serverless function | `sk_` in `ABLO_API_KEY`, with `transport: 'http'` | Stateless request/response; nothing held open across invocations. |
+| Browser, read-only | root-bound `pk_` | Publishable, safe to ship, and read-only. |
 | Browser, writing as the signed-in user | `authEndpoint` | A route on your backend mints a short-lived `ek_` per user. |
 
 [API Keys](./api-keys.md) covers the model; [Sessions](./sessions.md) covers
 minting. Two things bite specifically at deploy time.
 
-**The live key `ablo login` gives you cannot push schema.** It is a restricted,
-observe-only `rk_live_` by design, so a stolen CLI config cannot write to
-production. A production deploy needs a **secret** `sk_live_` from the dashboard,
-supplied as `ABLO_API_KEY`. You do not have to discover this from a failed
-deploy: `ablo login` and `ablo status` name what the key in hand does, and
-`ablo status --json` reports it as `effectiveKey.kind` for a pipeline to check
-before it pushes. The deploy itself uses an explicit dashboard `sk_live_` in
-`ABLO_API_KEY`; there is no local mode switch.
-
-**An explicit key always wins.** The CLI resolves `ABLO_API_KEY`, then
-`.env.local`, then `.env`, then the stored login — and `ablo status` prints which
-one it found under `key`, with its source. When a deploy lands somewhere
+**`ablo login` does not give the application production authority.** It stores
+a project-scoped `mk_` management credential that manages branches and exchanges
+for temporary child credentials; it cannot read or write application data or
+push the production schema. A production deploy needs a **secret** `sk_`
+from the dashboard, supplied as `ABLO_API_KEY`. `ablo whoami` names what an
+explicit key acts on, and `ablo status --json` reports its capability as
+`runtimeKey.kind` for a pipeline to check before pushing. There is no local
+mode switch.
+
+**An explicit key always wins.** Application-facing commands resolve
+`ABLO_API_KEY`, then `.env.local`, then `.env`, then a legacy stored runtime
+credential — never the `mk_` management login for data operations. `ablo status`
+prints what it found under `key`, with its source. When a deploy lands somewhere
 surprising, that line is usually the answer.
 
+Use `ablo whoami` when you need only the authoritative identity:
+
+```bash
+ABLO_API_KEY=sk_… npx ablo whoami
+```
+
+For a deployment secret already stored under another name, prefer
+`ablo whoami --key-env <NAME>` over copying it into argv or permanently
+maintaining parallel local variables. The command reads the explicitly named
+value from the process or project env files and reports its project and branch
+without printing the full secret.
+
 ## 3. Pushing the schema is a deploy step
 
 The server keeps its own copy of your schema and routes on that copy. Until it
@@ -159,7 +168,9 @@ has yours, a write to a new model fails with `server_execute_unknown_model` —
 depends on the new models goes live.
 
 ```bash
-ABLO_API_KEY=sk_live_… npx ablo push --yes
+ABLO_API_KEY=sk_… npx ablo push --yes
+# or, explicitly:
+npx ablo push --env-file .env.production --yes
 ```
 
 Production requires confirmation: interactively you type the destination
@@ -210,8 +221,8 @@ deployed HTTPS endpoint is registered once, and Ablo returns the signing secret
 a single time:
 
 ```bash
-ABLO_API_KEY=sk_live_… npx ablo webhooks create https://yourapp.com/api/ablo/[...all]
-ABLO_API_KEY=sk_live_… npx ablo webhooks list   # endpoints + delivery health
+ABLO_API_KEY=sk_… npx ablo webhooks create https://yourapp.com/api/ablo/[...all]
+ABLO_API_KEY=sk_… npx ablo webhooks list   # endpoints + delivery health
 ```
 
 `webhooks list` reports each endpoint's status, cursor, and last error — the
@@ -220,9 +231,9 @@ handler, the Standard Webhooks signature, and rolling a secret.
 
 ## What to watch once it is live
 
-- **`ablo logs`:** commit activity as it happens, scoped by the key, so a live
-  key streams the org and a test key streams only its sandbox. `--json` emits
-  NDJSON for piping.
+- **`ablo logs`:** commit activity as it happens, scoped by the key. A
+  root-bound key streams production; a child-bound key streams only that child.
+  `--json` emits NDJSON for piping.
 - **`ablo status`:** the readiness verdict. Cheap enough to run from a health
   check on your own side.
 - **The [audit log](./audit.md):** every confirmed write traced back to the key
@@ -244,17 +255,17 @@ and what each promises.
 | `server_execute_unknown_model` | The plane's active schema does not carry that model. | `ablo push` with a key for that plane. |
 | Clients rejected at connect | The deployed schema and the client's schema disagree. | Push this tree, or deploy the revision the server is running. |
 | `project_scope_denied` (403) | The model belongs to another project in your org. | Use a key minted for that project: a push cannot cross projects. |
-| 403 on `ablo push` | The key authenticated but cannot author schema. | A secret `sk_live_`; the `ablo login` live key is observe-only. |
+| 403 on `ablo push` | The key authenticated but cannot author schema. | A secret `sk_`; the `mk_` stored by `ablo login` is management-only. |
 
 ## The checklist
 
 1. Production database registered against the production plane, direct host, and
    `ablo connect check` all green.
-2. A secret `sk_live_` in the deploy environment as `ABLO_API_KEY` — never in a
+2. A secret `sk_` in the deploy environment as `ABLO_API_KEY` — never in a
    browser bundle.
 3. `ablo push --yes` in the pipeline, ahead of the code that needs the new models.
 4. `ablo status --json` gating the deploy on an empty `blockers` array.
-5. Browser clients on a `pk_live_` or an `authEndpoint`, not a secret key.
+5. Browser clients on a root-bound `pk_` or an `authEndpoint`, not a secret key.
 6. Webhook endpoints registered at their deployed URLs, with the signing secret
    in your environment.
 

package/docs/examples/existing-python-backend.md

@@ -150,7 +150,7 @@ https://api.example.com/api/ablo/source
 Store the Ablo API key in the Python server:
 
 ```bash
-ABLO_API_KEY=sk_live_...
+ABLO_API_KEY=sk_...
 ```
 
 Then expose one route that verifies the signed request and calls the existing

package/docs/how-it-works.md

@@ -93,7 +93,7 @@ npx ablo connect apply --url postgres://admin:...@host:5432/db
 
 ```bash
 # Your app's environment holds only the API key — never a connection string.
-ABLO_API_KEY=sk_live_...
+ABLO_API_KEY=sk_...
 ```
 
 ```ts
@@ -127,8 +127,9 @@ here is the current, correct reading:
   It is not the write path. You write **through** Ablo.
 - **"Ablo is out of the write path."** Not anymore. Ablo is the write chokepoint;
   every write flows through its coordination and then into your database.
-- **"Ablo holds my rows."** Only in the no-database-yet sandbox. Once you connect a
-  database, your rows live in *your* Postgres — Ablo keeps just the log.
+- **"Ablo holds my rows."** Only on a development branch where you have not
+  connected a database yet. Once you connect one, your rows live in *your*
+  Postgres — Ablo keeps just the log.
 - **"Ablo migrates my schema."** No. Ablo writes rows through a scoped role and runs
   no DDL; your migrations own the shape of your database.
 

package/docs/idempotency.md

@@ -62,7 +62,7 @@ use a new key.
 
 ## Failures are not replayed: they re-run
 
-This is where Ablo deliberately differs from Stripe and from most payment APIs, and it is the
+This is where Ablo deliberately differs from most request/response APIs, and it is the
 behaviour most likely to surprise you.
 
 **Only successful writes are recorded.** A write that failed leaves no idempotency record, so

package/docs/identity.md

@@ -318,7 +318,7 @@ session" glossed over. Concretely:
 
 1. **Your `ABLO_API_KEY` lives only on your trusted server**, scoped to your
    account. It signs your app's relationship with Ablo. It must never reach a
-   browser bundle — treat it like a Stripe secret key.
+   browser bundle.
 2. **Your server authenticates the user with your own system.** That's the
    request that knows "this is user `U`, org `O`, teams `[...]`".
 3. **Your server hands that authenticated identity to Ablo**, and the browser
@@ -342,9 +342,8 @@ server, never by the browser.**
 > the client could name its own org or sync groups, any user could read another
 > tenant's data by editing a request. By keeping the API key server-side and
 > deriving scope from the identity your server already authenticated, the trust
-> boundary lands in the one place you control. This is the same reason
-> Liveblocks resolves scope in `prepareSession` and Stripe mints ephemeral keys
-> server-side.
+> boundary lands in the one place you control. Scope resolution and session
+> minting therefore stay server-side.
 
 ## Wiring the provider
 

package/docs/integration-guide.md

@@ -59,7 +59,7 @@ confirms it over the WAL. Application and agent code hold only `ABLO_API_KEY`
 client never sees a connection string. [Connect Your Database](./data-sources.md)
 is the single source of truth for both paths.
 
-## Test With Sandboxes
+## Try the public sandbox demo
 
 Use the public `/sandbox` page to understand the state flow. It is a visual,
 deterministic demo; it does not call your API key or mutate hosted Ablo data.
@@ -69,7 +69,7 @@ Codex and ask it to wire one real model through the schema model API.
 Use `npx ablo dev` for real integration work. It derives an immutable branch
 from Git, inherits the parent schema, and writes a temporary branch credential
 to `.env.local`. Each developer or pull request gets independent schema, rows,
-claims, and logs. Use an explicit `sk_live_*` root credential only in the
+claims, and logs. Use an explicit `sk_*` root credential only in the
 reviewed production deployment.
 
 When handing this to a coding agent, give it a concrete target:
@@ -231,9 +231,9 @@ export async function POST() {
 
 ### Why two credential shapes
 
-`ABLO_API_KEY` is your long-lived account credential. Treat it like a
-Stripe secret key: it stays on trusted servers, never reaches a browser
-bundle, and signs server-to-server requests. It is the right credential
+`ABLO_API_KEY` is your long-lived account credential. It stays on trusted
+servers, never reaches a browser bundle, and signs server-to-server requests.
+It is the right credential
 for trusted runtimes (Next.js server actions, background workers,
 migration scripts) where the code reading it is yours.
 
@@ -250,10 +250,8 @@ ABLO_API_KEY ─exchange─►  scoped token ────────► narrow
  server only)             revocable)
 ```
 
-This is the same shape as Stripe's
-ephemeral keys (Issuing Elements expires in 15 minutes) and AWS STS
-AssumeRole (returns time-bounded creds with the minimal needed scope).
-You never type that token into your app; the SDK mints one when it needs one and
+You never type that token into your app; the SDK mints a time-bounded,
+minimally scoped token when it needs one and
 refreshes before expiry.
 
 ## 3. Read State
@@ -440,7 +438,7 @@ Ablo needs your Data Source endpoint and API key. Your app
 stores one Ablo credential:
 
 ```bash
-ABLO_API_KEY=sk_live_...
+ABLO_API_KEY=sk_...
 ```
 
 The API key verifies Ablo's request. It is not a database credential.

package/docs/internal/data-source-reverse-channel.md

@@ -3,8 +3,8 @@
 Maintainer scoping doc. Closes the one real day-one DX gap in Data Source
 mode: the `commit`/`load`/`list` legs are inbound webhooks (Ablo → your
 endpoint), so on `localhost` they need a tunnel (ngrok/cloudflared). This
-scopes a built-in reverse channel so Data Source works on localhost the way
-managed mode already does — the Stripe-CLI `stripe listen` pattern.
+scopes a built-in reverse channel so Data Source works on localhost without a
+public tunnel.
 
 ## The gap, precisely
 
@@ -26,10 +26,9 @@ managed mode "just works" locally and Data Source doesn't.
 
 ## Prior art
 
-- **Stripe CLI `stripe listen`:** the canonical fix. The CLI opens an
-  *outbound* WebSocket to Stripe; Stripe drains webhook events down it and the
-  CLI forwards them to `localhost`. No public URL, no tunnel. We want the same
-  for the `commit`/`load`/`list` leg.
+- **Outbound relay:** the CLI opens a WebSocket to the hosted service, receives
+  events over that connection, and forwards them to `localhost`. No public URL
+  or tunnel is required. We want the same for the `commit`/`load`/`list` leg.
 - **Our own `createPushQueue`:** already proves the outbound-from-customer
   pattern for the `events` leg. The reverse channel is the symmetric primitive
   for the other direction.
@@ -78,7 +77,7 @@ import { dataSource, createSourceConnector } from '@abloatai/ablo';
 import { sourceOptions } from './ablo.source'; // shared with route.ts
 
 const connector = createSourceConnector({
-  apiKey: process.env.ABLO_API_KEY!,      // sk_test_*
+  apiKey: process.env.ABLO_API_KEY!,      // sk_* bound to a child branch
   handler: dataSource(sourceOptions),     // the unchanged (Request)=>Response
 });
 await connector.run(abortSignal);
@@ -90,8 +89,8 @@ await connector.run(abortSignal);
 ### Server side (sync-server)
 
 - New WS endpoint `/v1/source/listen`. Auth: project API key → resolves the
-  source. Reject if the key isn't `sk_test_*` unless the source explicitly
-  opts into reverse-channel for production (see "Production" below).
+  source. Reject if the persisted key binding is the root branch unless the
+  source explicitly opts into a production reverse channel (see below).
 - Per-source request queue. When a `commit`/`load`/`list` needs the customer
   and a connector is attached, enqueue + drain down the socket instead of
   POSTing the webhook URL. Reuse the same signed-envelope shape so the
@@ -106,18 +105,16 @@ await connector.run(abortSignal);
   project key, so the connector verifies them through the existing
   `verifyAbloSourceRequest` with no special-casing. The transport changes; the
   trust model does not.
-- Gate to `sk_test_*` by default. The DB still stays canonical in the
-  customer's process; nothing here gives Ablo the `DATABASE_URL`.
-
-## Test-mode interplay
-
-`SourceRequestContext.mode` (`src/source/types.ts`) already distinguishes
-`test`/`live`. The reverse channel is the natural home for `mode: 'test'`
-traffic: a local connector attached with an `sk_test_*` key receives the
-source's test commits, runs them against the customer's test DB, and the SDK
-sees confirmed rows + fan-out exactly as in production. This is the missing
-piece that makes `sk_test_*` a complete local loop rather than just a data
-namespace.
+- Gate to non-root branch bindings by default. The DB still stays canonical in
+  the customer's process; nothing here gives Ablo the `DATABASE_URL`.
+
+## Development-branch interplay
+
+The reverse channel is the natural home for child-branch traffic: a local
+connector attached with a child-bound `sk_*` receives that branch's commits,
+runs them against the customer's development DB, and the SDK sees confirmed
+rows and fan-out exactly as on the root. The server resolves child versus root
+from the persisted branch binding, never from the key spelling.
 
 ## Production stance
 

package/docs/migration.md

@@ -13,13 +13,14 @@ change when you upgrade.
 
 | Version | What changed | What to do |
 |---|---|---|
+| **Next** | New keys no longer encode `live`/`test`; branch binding is authoritative | Accept the new `sk_…`/`rk_…`/`pk_…`/`ek_…` spellings. Do not route or authorize from a key prefix. Old `_live_`/`_test_` keys continue to authenticate; rotate them to mint the current form |
 | **0.36.0** | `ttlSeconds` deprecated on the join surfaces in favour of `ttl` | `useJoin({ scope, ttlSeconds: '5m' })` → `useJoin({ scope, ttl: '5m' })`; same for `ParticipantJoinOptions`. Both spellings work until 0.37.0 |
 | **0.35.0** | Synchronous reads moved under `local`, mirroring the async verbs | `get(id)` → `local.get(id)`; `getAll(options)` → `local.list(options)`; `getCount(options)` → `local.count(options)` |
 | **0.35.0** | `causedByTaskId` write option + seven `turn_*` error codes removed | Delete the `causedByTaskId` argument from writes; a branch on `turn_validation_failed` was unreachable and can go with it |
 | **0.34.0** | Presence verb renamed `watch` → `join` | `ablo.<model>.watch(ids)` → `ablo.<model>.join(ids)`; `useWatch` → `useJoin`; the `WatchOptions` / `UseWatchOptions` / `UseWatchReturn` types → `JoinOptions` / `UseJoinOptions` / `UseJoinReturn`; error code `model_watch_not_configured` → `model_join_not_configured` |
 | **0.28.0** | Removed React placeholders that had no working runtime | `usePresence` → `usePeers` or `useJoin`; `useClaim` → `ablo.<model>.claim`; `SyncGroupProvider` / `useSyncGroup` → `useJoin({ scope })` |
 | **0.11.0** | Historical `intent` → `claim` rename | The hook renamed in that release was later removed in 0.28.0. Current code uses `ablo.<model>.claim` or `useJoin` |
-| **0.10.0** | Environment enum renamed `test`/`live` → `sandbox`/`production` | Update code that branches on the environment (e.g. source `mode`): `'test'`→`'sandbox'`, `'live'`→`'production'`. Key prefixes `sk_test_`/`sk_live_` are unchanged |
+| **0.10.0** | Environment enum renamed `test`/`live` → `sandbox`/`production` | Historical: update code that branches on the environment (`'test'`→`'sandbox'`, `'live'`→`'production'`). That release retained `sk_test_`/`sk_live_`; current releases mint mode-free, branch-bound keys |
 | **0.9.2** | `turn` primitive + agent-work `tasks` resource removed | Coordinate with `claim`; mint a scoped session instead of `agent().run()` |
 | **0.9.2** | `intents` deprecated in favor of `claim` | Use `ablo.<model>.claim`; `ablo.intents` is now `@internal` |
 | **0.9.0** | One options object per verb | `update(id, data, opts)` → `update({ id, data, ...opts })` |
@@ -32,6 +33,27 @@ change when you upgrade.
 
 ---
 
+## Next: key spelling follows capability, branch binding follows authority
+
+New runtime credentials have one prefix per capability class:
+
+```diff
+- sk_live_… / sk_test_…
++ sk_…
+```
+
+The same applies to `rk_`, `pk_`, and `ek_`. This does **not** merge branch
+data or weaken production safety. Every key row is still immutably bound to one
+project and one branch, and the server-confirmed `branchRoot` flag distinguishes
+the protected production root from a development child.
+
+Remove code that chooses an endpoint, environment, or confirmation policy by
+matching `_live_` or `_test_`. Use the resolved identity (`ablo whoami` in the
+CLI) instead. Existing suffixed credentials remain valid compatibility inputs,
+so rollout does not require an immediate rotation.
+
+---
+
 ## 0.36.0: one lease is spelled `ttl`
 
 ```diff
@@ -187,14 +209,18 @@ on presence and claim state.
 
 ## 0.10.0: environment enum `sandbox` / `production`; stateless HTTP transport
 
+> Historical migration note: current development uses immutable branches, not a
+> shared sandbox selector. The enum and compatibility fields below remain
+> relevant to integrations written against 0.10, but new applications let the
+> branch-bound credential select the plane.
+
 ### Environment enum rename (the only breaking change)
 
-The canonical environment values are now **`production`** and **`sandbox`** (was
-`live` and `test`). This is a *vocabulary* change at the type/API layer — the
-on-the-wire key prefixes are **unchanged**: keys are still `sk_test_…` /
-`sk_live_…` and parse exactly as before. What changed is the enum you see in
-code: `Environment`, the source-handler `mode` field, and `ApiKeyEnv` now read
-`production` / `sandbox`.
+In 0.10 the canonical environment values became **`production`** and
+**`sandbox`** (from `live` and `test`). At that release this was only a
+vocabulary change at the type/API layer: on-the-wire keys still used
+`sk_test_…` / `sk_live_…`. Current releases accept those legacy spellings but
+mint mode-free `sk_…` keys whose persisted branch binding is authoritative.
 
 You only need to act if your code branches on the environment value — most
 commonly a Data Source handler keyed on `mode`. The mapping is exactly

package/docs/projects.md

@@ -4,20 +4,20 @@
 
 A **project** is the isolation unit inside your organization — the shape you
 know from Neon or Supabase. Each app you build gets its own project, and each
-project gets its own schema, its own sandbox/production data planes, and its
-own API keys. Two teams in one org can ship two apps that never see each
+project gets its own root and child branches, schemas, data planes, and API
+keys. Two teams in one org can ship two apps that never see each
 other's models, keys, or rows.
 
 ```text
 organization
 ├── project: default          ← every org has one; pre-project apps live here
-│   ├── schema (sandbox + production artifacts)
-│   ├── data planes (registered databases)
-│   └── keys (sk_/rk_/ek_/pk_)
+│   ├── production root
+│   ├── development/preview branches
+│   └── branch-bound schema, data plane, and credentials
 └── project: my-app           ← npx ablo init creates this for a new app
-    ├── schema
-    ├── data planes
-    └── keys
+    ├── production root
+    ├── development/preview branches
+    └── branch-bound schema, data plane, and credentials
 ```
 
 ## The default project
@@ -40,19 +40,23 @@ Schema pushes, database registrations, reads, and writes all act on the
 
 - `npx ablo push` activates the schema for the pushing key's project — it
   can never demote another project's schema.
-- Registering a database (`DATABASE_URL`) attaches it to the key's project
-  and environment.
+- Registering a database (`DATABASE_URL`) attaches it to the key's project and
+  immutable branch.
 - A write or read against a model that belongs to **another** project in
   your org fails with a typed `project_scope_denied` — never a silent empty
   result, and never the misleading "unknown model, run ablo push".
 
-## Sandboxes belong to a project
+## Branches belong to a project
 
-Production is singular per project; sandboxes are many. Each sandbox of a
-project gets its **own data plane** (its own registered dev database) but
-they all share the project's **one** sandbox schema — pushing the same
-schema from a second sandbox doesn't create a second artifact, it just
-provisions that sandbox's database.
+Production is the protected root branch; development and preview branches are
+children. Each branch has its own rows, active schema artifact, claims, log,
+credentials, and optional registered database. A child copies the parent's
+active schema when created and owns its history afterward, so a feature-branch
+push cannot change a sibling or production.
+
+`ablo dev` derives a child from Git and mints an expiring `sk_` credential
+bound to its immutable branch id. Production runtimes use `sk_` bound to
+the root. There is no shared sandbox schema and no runtime environment switch.
 
 ## CLI
 
@@ -68,15 +72,16 @@ npx ablo projects use default      # back to the org default
 npx ablo status                    # shows the active project
 ```
 
-The active project is a local targeting preference (stored next to `mode` in
-your CLI config): new keys you mint pick it up. It never changes what an
-existing key can reach — a key's project scope is decided server-side at
-mint.
+The active project is a local targeting preference in your CLI config: new
+management and branch credentials you mint pick it up. It never changes what
+an existing key can reach — project and branch scope are decided server-side at
+mint. Use `npx ablo whoami` to confirm the exact target of the active
+credential.
 
 ## API
 
-Projects are a Stripe-shaped control-plane resource, authenticated with a
-secret (`sk_`) key:
+Projects are a control-plane resource authenticated with a management (`mk_`)
+key:
 
 ```bash
 curl https://api.abloatai.com/api/v1/projects \

package/docs/quickstart.md

@@ -11,7 +11,7 @@ which stays the system of record. Ablo writes rows but **runs no DDL and owns no
 schema** — your migration tool stays in charge of the shape of your database.
 
 > No database yet? 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. Point it at a
+> so you can build the whole app today. Point it at a
 > separate or local Postgres for a development branch, or at your production
 > database when you're ready.
 
@@ -35,12 +35,18 @@ export ABLO_MANAGEMENT_KEY=mk_...
 
 Every runtime call needs a branch-bound API key. `ablo dev` exchanges the
 stored management credential for
-an expiring `sk_test_*` key bound to the current development branch.
-Production runtimes use `sk_live_*`. In production a key points at the database
+an expiring `sk_*` key bound to the current development branch.
+Production runtimes use `sk_*`. In production a key points at the database
 *you* own; on a development branch you can skip the database entirely and let
 Ablo host the rows (apiKey only). There is no keyless mode — a key is always
 required. (The public `/sandbox` page is a separate hosted demo, not your app.)
 
+You do not create a separate named variable per development environment.
+Application code always reads `ABLO_API_KEY`; `ablo dev` wires the value for the
+current branch. Run `npx ablo whoami` whenever you want the server-confirmed
+project and branch for that value. See [API Keys](./api-keys.md) for the full
+project → branch → credential model.
+
 ## 2. Your Ablo schema (init scaffolded it)
 
 The schema is the contract — it generates `ablo.<model>` methods for app code,
@@ -149,7 +155,7 @@ Your **app** holds only the API key — never a connection string:
 
 ```bash
 # .env — server runtime only, never the browser
-ABLO_API_KEY=sk_test_...
+ABLO_API_KEY=sk_...
 ```
 
 ```ts

package/docs/react.md

@@ -21,8 +21,7 @@ import { useAblo } from '@abloatai/ablo/react';
 You build the Ablo client once — that's where the schema, the session endpoint,
 and connection config live — then hand it to the provider. The provider takes
 the already-built `client`; it no longer takes `schema`, `url`, `apiKey`, etc.
-as props. This mirrors Stripe's `<Elements stripe={stripePromise}>`: construct
-the thing, then pass it.
+as props. Construct the client once, then pass that instance to the provider.
 
 ```ts
 // lib/ablo.ts

package/docs/schema-contract.md

@@ -106,11 +106,11 @@ the fresh row. Reads stay open; only acting on the row serializes.
 
 Every schema model is backed by your own database, and you write to it through
 `ablo.<model>`. There are three start states, all covered in [Connect Your
-Database](./data-sources.md) (the single source of truth): the sandbox (`apiKey`
-only, no database — Ablo keeps your rows in its own log), `npx ablo connect` (a
-scoped writer role plus logical replication, so Ablo writes your rows and confirms
-them over the WAL), or a signed Data Source endpoint when your database can't grant
-replication.
+Database](./data-sources.md) (the single source of truth): a development branch
+with no database yet (`apiKey` only — Ablo keeps that branch's rows in its own
+log), `npx ablo connect` (a scoped writer role plus logical replication, so Ablo
+writes your rows and confirms them over the WAL), or a signed Data Source
+endpoint when your database can't grant replication.
 
 Your database connects out of band, so the client holds only `ABLO_API_KEY` —
 never a connection string. Browser code goes through `<AbloProvider>` or a scoped

package/docs/session-settings.md

@@ -45,8 +45,8 @@ context, whether or not you map anything:
 | --- | --- |
 | `app.current_org_id` | The organization the credential acts for |
 | `app.current_project_id` | The project |
-| `app.current_environment` | The environment |
-| `app.current_sandbox_id` | The sandbox, when the write is in one |
+| `app.current_environment` | The key's test/live trust class (`sandbox`/`production` on this compatibility surface) |
+| `app.current_sandbox_id` | Legacy compatibility coordinate for older test planes; not a branch selector |
 | `app.current_participant_id` | The participant making the write |
 | `app.current_participant_kind` | Whether that participant is a person, an agent, or the system |
 | `app.current_user_id` | The person on whose behalf the write is made |
@@ -70,6 +70,11 @@ authenticated key and the plane:
 `orgId` · `projectId` · `environment` · `sandboxId` · `participantId` ·
 `participantKind`
 
+`environment` and `sandboxId` retain their published names for compatibility
+with existing RLS policies. Current development isolation comes from the
+credential's immutable branch binding; callers do not choose a sandbox or
+branch through session settings.
+
 Because none of them come from the caller, a mapping can forward the tenant
 identity Ablo already trusts, but cannot widen what a writer sees. A setting name
 takes exactly one source — the name is the key — so naming the same setting twice