@abloatai/ablo 0.57.0 → 0.59.0

package/dist/source-drizzle.d.ts

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/drizzle';
+export * from '@abloatai/transaction/source/adapters/drizzle';
 //# sourceMappingURL=source-drizzle.d.ts.map

package/dist/source-drizzle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-drizzle.d.ts","sourceRoot":"","sources":["../src/source-drizzle.ts"],"names":[],"mappings":"AAAA,cAAc,sCAAsC,CAAC"}
+{"version":3,"file":"source-drizzle.d.ts","sourceRoot":"","sources":["../src/source-drizzle.ts"],"names":[],"mappings":"AAAA,cAAc,+CAA+C,CAAC"}

package/dist/source-drizzle.js

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/drizzle';
+export * from '@abloatai/transaction/source/adapters/drizzle';
 //# sourceMappingURL=source-drizzle.js.map

package/dist/source-drizzle.js.map

@@ -1 +1 @@
-{"version":3,"file":"source-drizzle.js","sourceRoot":"","sources":["../src/source-drizzle.ts"],"names":[],"mappings":"AAAA,cAAc,sCAAsC,CAAC"}
+{"version":3,"file":"source-drizzle.js","sourceRoot":"","sources":["../src/source-drizzle.ts"],"names":[],"mappings":"AAAA,cAAc,+CAA+C,CAAC"}

package/dist/source-kysely.d.ts

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/kysely';
+export * from '@abloatai/transaction/source/adapters/kysely';
 //# sourceMappingURL=source-kysely.d.ts.map

package/dist/source-kysely.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-kysely.d.ts","sourceRoot":"","sources":["../src/source-kysely.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC"}
+{"version":3,"file":"source-kysely.d.ts","sourceRoot":"","sources":["../src/source-kysely.ts"],"names":[],"mappings":"AAAA,cAAc,8CAA8C,CAAC"}

package/dist/source-kysely.js

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/kysely';
+export * from '@abloatai/transaction/source/adapters/kysely';
 //# sourceMappingURL=source-kysely.js.map

package/dist/source-kysely.js.map

@@ -1 +1 @@
-{"version":3,"file":"source-kysely.js","sourceRoot":"","sources":["../src/source-kysely.ts"],"names":[],"mappings":"AAAA,cAAc,qCAAqC,CAAC"}
+{"version":3,"file":"source-kysely.js","sourceRoot":"","sources":["../src/source-kysely.ts"],"names":[],"mappings":"AAAA,cAAc,8CAA8C,CAAC"}

package/dist/source-next.d.ts

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/next';
+export * from '@abloatai/transaction/source/endpoint';
 //# sourceMappingURL=source-next.d.ts.map

package/dist/source-next.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"source-next.d.ts","sourceRoot":"","sources":["../src/source-next.ts"],"names":[],"mappings":"AAAA,cAAc,mCAAmC,CAAC"}
+{"version":3,"file":"source-next.d.ts","sourceRoot":"","sources":["../src/source-next.ts"],"names":[],"mappings":"AAAA,cAAc,uCAAuC,CAAC"}

package/dist/source-next.js

@@ -1,2 +1,2 @@
-export * from '@abloatai/transaction/source/next';
+export * from '@abloatai/transaction/source/endpoint';
 //# sourceMappingURL=source-next.js.map

package/dist/source-next.js.map

@@ -1 +1 @@
-{"version":3,"file":"source-next.js","sourceRoot":"","sources":["../src/source-next.ts"],"names":[],"mappings":"AAAA,cAAc,mCAAmC,CAAC"}
+{"version":3,"file":"source-next.js","sourceRoot":"","sources":["../src/source-next.ts"],"names":[],"mappings":"AAAA,cAAc,uCAAuC,CAAC"}

package/docs/agents.md

@@ -2,6 +2,25 @@
 
 > The stateless participant: wake on a trigger, read, claim, commit, go idle.
 
+## Stateless HTTP reads
+
+Use `get` to read one task row by id and `list` to find matching rows. Agents
+and other stateless workers use the HTTP client directly, without a
+synchronization step or a `.data` wrapper.
+
+```ts
+const task = await ablo.tasks.get({ id: taskId });
+if (!task) throw new Error('task not found');
+console.log(task.title);
+
+const matching = await ablo.tasks.list({ where: { title } });
+if (!matching[0]) throw new Error('task not found');
+console.log(matching[0].title);
+```
+
+These are observational reads. Use `read({ id })` only when a later Ablo write
+depends on that exact version and will pass it through `reads`.
+
 An agent is a **reactive** participant: it wakes on something happening, reads
 what it needs, writes a result, and goes idle. That's a request/response
 workload — so agents talk to Ablo over **plain HTTP**, holding no WebSocket. The
@@ -16,7 +35,7 @@ other*.**
 <Note>
 Agents transact against your **pushed schema**, same as everyone — `ablo.records`
 exists because you defined a `record` model and ran `ablo push`. The key
-authenticates; the [schema](/quickstart) defines what you can call.
+authenticates; the [schema](/installation) defines what you can call.
 </Note>
 
 ## The agent client
@@ -34,7 +53,7 @@ const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: "http"
 // `get` resolves to the row, or `undefined` when none matches.
 const open = await ablo.records.list({ where: { status: "todo" } });
 
-const record = await ablo.records.get({ id: open[0].id });
+const record = await ablo.records.read({ id: open[0].id });
 if (!record) throw new Error("record not found");
 
 console.log(record.title);
@@ -42,9 +61,11 @@ await ablo.records.update({ id: record.id, data: { status: "done" } });
 ```
 
 It exposes `get` / `list` / `create` / `update` / `delete`, plus `commits`
-and `claim`. It does **not** expose stateful-only `local` reads or `onChange`
-subscriptions. Those need a live connection, so with `transport: 'http'` they
-are compile errors rather than runtime surprises.
+and `claim`. It does **not** expose stateful-only `local` reads or model
+`onChange` subscriptions. Those need a WebSocket, so with `transport: 'http'`
+they are compile errors. `context().onChange` is separate: while its listener
+is active, it holds one HTTP response open until the context changes or the
+listener stops.
 
 ## Managed scoped agents
 
@@ -58,7 +79,7 @@ model output or an HTTP request body. A serverless handler normally creates and
 disposes one child per invocation:
 
 ```ts
-const run = await control.runs.get({ id: verifiedRunId });
+const run = await control.runs.read({ id: verifiedRunId });
 if (!run) throw new Error('run not found');
 
 const agent = await control.agents.create({
@@ -204,19 +225,21 @@ default caller here, not a bolt-on.
 
 ```text
 something happens ──▶ your agent (HTTP, no socket)
-  (a job, a webhook,     read context (list/get)
+  (a job, a webhook,     read context (list/get/read)
    a queue message)      claim → work → commit
                          done — no held connection
 ```
 
-Because it holds nothing open, an agent is a **stateless worker**: deploys and
-restarts are free, and you scale by adding workers. A long-running fleet of idle
-agents costs nothing on the live plane — that capacity stays for humans.
+Without `context().onChange`, an agent holds nothing open and remains a
+**stateless worker**: deploys and restarts are free, and you scale by adding
+workers. Each active context listener is explicit connection capacity and must
+be stopped when its work ends.
 
 ## What stays on the live (human) plane
 
-`onChange` (live subscriptions) and the `local` reads (local synced-pool
-reads) require a WebSocket and a local store — they're for interactive UIs, not
-stateless agents. An agent reacts to an external trigger (a job/queue/webhook),
-then reads with `list`/`get`. See [client behavior](/client-behavior) for
-the full surface and [guarantees](/guarantees) for the coordination semantics.
+Model `onChange` and `local` reads require a WebSocket and a local store —
+they're for interactive UIs. An HTTP agent normally reacts to an external
+trigger, then reads with `list`/`get`. For costly work, `context().onChange` can
+stop that one run early while the final write still uses `context().reads`.
+See [client behavior](/client-behavior) for the full surface and
+[guarantees](/guarantees) for the coordination semantics.

package/docs/api-keys.md

@@ -23,9 +23,9 @@ 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. |
+| Manage a project or its branches | `mk_` | `npx ablo login` stores it for the CLI; pick the project in the terminal, or name it with `--project <slug>`. |
 | 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`. |
+| Prepare a branch once, including CI | expiring `sk_` bound to that branch | `npx ablo dev --no-watch --branch <ref>`; headless CI supplies an `mk_` credential through `ABLO_API_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. |
@@ -33,9 +33,9 @@ and remap them before each command.
 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
+npx ablo login    # once per project: approve in the browser, pick the 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:
@@ -91,7 +91,7 @@ The credential class lives in the prefix:
 
 | Prefix | Purpose | Stored where |
 |---|---|---|
-| `mk_` | project and branch management | CLI credential store or `ABLO_MANAGEMENT_KEY` |
+| `mk_` | project and branch management | CLI credential store; `ABLO_API_KEY` only in headless automation |
 | `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 |

package/docs/api.md

@@ -12,9 +12,11 @@ confirmed write streams to everyone watching. When two writers touch the same
 row, you can optionally `claim` it so they serialize instead of clobbering
 each other.
 
-Two things to know before the method list. **Reads come in two flavors:**
-`get({ id })` / `list({ where })` are async — they answer from what is
-already local and fall back to the server. Put `local.` in front of either and
+Three things to know before the method list. **`get` observes; `read` declares.**
+Both fetch one current row, but only the exact object returned by `read({ id })`
+can be carried in a mutation's `reads` array. If it changed, that mutation does
+not land. `get({ id })` and `list({ where })` are ordinary queries with no stale
+guard. **Local reads do not fetch.** Put `local.` in front of a query and
 you get the same read restricted to what is already here, which is why it can
 return a value rather than a promise: `local.get(id)`, `local.list({ where })`,
 `local.count({ where })`. Use those in render, after data has synced.
@@ -38,10 +40,14 @@ const schema = defineSchema({
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
 
 await ablo.ready();
-const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
 if (!report) throw new Error('Row not found');
 
-await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' } });
+await ablo.weatherReports.update({
+  id: 'report_stockholm',
+  data: { status: 'ready' },
+  reads: [report],
+});
 ```
 
 For end-to-end app setup across React, existing backends, Data Source, and
@@ -51,15 +57,17 @@ agents, read the [Integration Guide](./integration-guide.md).
 
 Each schema model becomes a typed model on the client:
 
-- `ablo.weatherReports.get({ id })` reads one row asynchronously (server read).
-- `ablo.weatherReports.list({ where })` reads a collection asynchronously (server read).
+- `ablo.weatherReports.get({ id })` fetches one row without declaring a decision dependency.
+- `ablo.weatherReports.read({ id })` fetches one guardable decision input.
+- `ablo.weatherReports.list({ where })` fetches an observational collection.
 - `ablo.weatherReports.listAll({ where })` explicitly reads every matching page.
 - `ablo.weatherReports.local.get(id)` reads one row synchronously from the local graph.
 - `ablo.weatherReports.create({ data })` creates a row.
 - `ablo.weatherReports.update({ id, data, ...options })` updates a row.
 - `ablo.weatherReports.delete({ id, ...options })` deletes a row.
+- `ablo.weatherReports.claim({ id, description })` acquires a durable write lease; the HTTP form is awaited.
 
-`local.` narrows a read to what has already synced. `get({ id })` and
+`local.` narrows a query to what has already synced. `get({ id })`, `read({ id })`, and
 `list({ where })` answer from the local graph and fall back to IndexedDB and
 then the network, so reach for them when the row may not be here yet.
 `local.get(id)` and `local.list({ where })` are the same reads with the
@@ -67,8 +75,9 @@ fallback removed — nothing to await, so they return a value.
 
 | Method | Returns | Use when |
 |---|---|---|
-| `get({ id })` | `Promise<T \| undefined>` | You need one row, hydrating from local store and server. |
-| `list({ where })` | `Promise<ModelList<T>>` | You need to hydrate a collection from local store and server. |
+| `get({ id })` | `Promise<T \| undefined>` | You need to observe one current row. |
+| `read({ id })` | `Promise<CapturedRow<T> \| undefined>` | A later mutation is based on this row. |
+| `list({ where })` | `Promise<ModelList<T>>` | You need to observe a collection. |
 | `listAll({ where, maxPages?, signal? })` | `Promise<T[]>` | You deliberately need every matching row. |
 | `local.get(id)` | `T \| undefined` | You want a synchronous snapshot of one local row. |
 | `local.list(options?)` | `T[]` | You want a synchronous snapshot of a local collection. |
@@ -76,11 +85,60 @@ fallback removed — nothing to await, so they return a value.
 | `create({ data, ...options })` | `Promise<T>` | You want to create through the schema model. |
 | `update({ id, data, ...options })` | `Promise<T>` | You want to update through the schema model. |
 | `delete({ id, ...options })` | `Promise<void>` | You want to delete through the schema model. |
-
-`get`, `list`, `create`, `update`, and `delete` are the main path — they go
+| `claim({ id, description })` | `Promise<HeldClaim<T>>` | Slow or expensive work must exclude another writer. |
+| `claim.state({ id })` | `Promise<Claim \| null>` on HTTP | You need the current holder without acquiring the row. |
+| `claim.list({ id })` | `Promise<{ object: 'list'; data: Claim[] }>` on HTTP | You need every disjoint holder on the row. |
+| `claim.queue({ id })` | `Promise<ClaimQueueView>` on HTTP | You need the durable wait line. |
+| `claim.release({ id })` | `Promise<void>` on HTTP | You need to release a claim early. |
+| `claim.reorder({ id, order })` | `Promise<void>` on HTTP | A privileged coordinator needs to reorder the wait line. |
+
+`get`, `read`, `list`, `create`, `update`, `delete`, and `claim` go
 through the server. The `local` reads work off the rows a session has already
 synced, so a cheap re-read needs no round-trip.
 
+## Atomic commits
+
+Use one `ablo.commits.create` when several Ablo model writes must all land or
+none may land. Put every operation in `operations` and every exact row returned
+by `read` that influenced the batch in the top-level `reads` array.
+
+```ts
+import { AbloStaleContextError } from '@abloatai/ablo';
+
+const task = await ablo.tasks.read({ id: taskId });
+if (!task) throw new Error('task not found');
+
+try {
+  await ablo.commits.create({
+    operations: [
+      {
+        action: 'update', model: 'tasks',
+        id: task.id,
+        data: { status: 'done' },
+      },
+      {
+        action: 'create', model: 'tasks',
+        id: markerId,
+        data: { title: 'atomic marker', status: 'done' },
+      },
+    ],
+    reads: [task],
+  });
+} catch (error) {
+  if (error instanceof AbloStaleContextError && error.code === 'stale_context') {
+    console.log(error.code);
+  } else {
+    throw error;
+  }
+}
+```
+
+The server checks the premises and applies the operations in one transaction.
+If any premise is stale or any operation fails, no operation lands. Independent
+model calls are not an atomic batch. External effects and application-owned
+Postgres writes cannot join this commit; keep those in their existing
+transaction or outbox.
+
 ### Reading a whole collection
 
 Prefer a filtered `listAll` when the application truly needs one complete
@@ -157,30 +215,35 @@ whenever a value is going away, and the type will hold you to it — only a
 field your schema declares optional accepts one, since a required field has no
 empty value to move to.
 
-## Protected Writes
+## Guarded Writes
 
-Use `snapshot` when a write should reject if the row changed mid-flight:
+Use `read` when a write depends on the row's current state, then pass that exact
+row in `reads`:
 
 ```ts
-const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
+if (!report) throw new Error('report not found');
 
 await ablo.weatherReports.update({
-  id: 'report_stockholm',
+  id: report.id,
   data: { status: 'ready' },
-  readAt: snap.stamp,
-  onStale: 'reject',
+  reads: [report],
 });
 ```
 
 Reactive local state changes optimistically at call time; awaiting the model
 write waits for authoritative confirmation.
 
-Protected write options:
+If the row changed after `read`, the write rejects with
+`AbloStaleContextError`. Ablo retains only model, id, and the read watermark as
+evidence; it does not record the row contents. A write without `reads` is an
+intentional unconditional assignment.
+
+Write options:
 
 | Option | Purpose |
 |---|---|
-| `readAt` | The state cursor the write was based on. |
-| `onStale` | Stale-state policy. Prefer `reject` for agent writes. |
+| `reads` | Exact rows returned by `read` that the mutation depends on. |
 | `idempotencyKey` | Stable key for retry-safe writes. The SDK generates one when omitted. |
 | `timeout` | Maximum time to wait for the write call. |
 
@@ -194,10 +257,12 @@ on its own if the holder stops, and is never saved as a row.
 
 You coordinate a row with calls on its model, beside `create`/`update`/`get`:
 `ablo.<model>.claim({ id })` takes the claim and returns a handle,
-`ablo.<model>.claim.state({ id })` reads who currently holds it (synchronous, never
-blocks), and `ablo.<model>.claim.release({ id })` releases it early. The full
-coordination surface is `claim.state({ id })` / `claim.queue({ id })` /
-`claim.release({ id })` / `claim.reorder({ id, order })` hanging off `claim`.
+`ablo.<model>.claim.state({ id })` reads who currently holds it, and
+`ablo.<model>.claim.release({ id })` releases it early. These reads are synchronous
+on the stateful client and awaited server calls on the HTTP client. The full
+coordination surface is `claim.state({ id })` / `claim.list({ id })` /
+`claim.queue({ id })` / `claim.release({ id })` /
+`claim.reorder({ id, order })` hanging off `claim`.
 
 The fields on a claim, its lifecycle diagram, and the full method surface are in
 [Coordination](./coordination.md#the-claim-state-object), which is where that
@@ -207,8 +272,9 @@ line.
 
 ### Reading and claiming
 
-`claim.state({ id })` is the read side for observers: synchronous, never blocks, and
-returns the live claim state object (or `null`). `claim({ id })` is the write
+`claim.state({ id })` is the read side for observers and returns the current claim
+state object (or `null`). It reads the stateful client's local cache synchronously;
+the HTTP client returns a promise because it asks the server. `claim({ id })` is the write
 side: it takes the claim and returns a `ClaimHandle`. Claims don't lock — if someone else
 already holds the row, `claim` waits for them to finish, re-reads the fresh row,
 then hands it to you, so you always proceed from current state. Default reads
@@ -218,7 +284,7 @@ Reads never block on a claim — to wait for a row to free up, `claim({ id })` i
 (the claim queues fairly behind the holder).
 
 ```ts
-const claim = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
+const claim = await ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 if (claim) {
   claim.heldBy;
   claim.description;
@@ -229,13 +295,18 @@ const handle = await ablo.weatherReports.claim({
   description: 'editing',
   ttl: '2m',
 });
-await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' } });
+await ablo.weatherReports.update({
+  id: handle.data.id,
+  data: { status: 'ready' },
+  claim: handle,
+});
 await handle.release();
 ```
 
-Writes go through the normal `ablo.<model>.update({ id, data })`. While you hold
-a claim on `id`, that `update` rejects with `AbloStaleContextError` if the row
-changed underneath you since you took the claim, so you re-read before retrying.
+Writes go through the normal model mutation and pass the held handle as `claim`.
+That explicit handle carries commit-time fencing. If the row changed underneath
+you since you took the claim, the update rejects with `AbloStaleContextError`,
+so you re-read before retrying.
 Call `handle.release()` (or `ablo.weatherReports.claim.release({ id })`) to release
 the claim when your work is done.
 
@@ -258,7 +329,7 @@ endpoint documents that model's real field contract instead of a generic blob.
 |---|---|
 | `ablo.<model>.create({ data })` | `POST /api/v1/models/{model}` |
 | `ablo.<model>.list({ where })` | `GET /api/v1/models/{model}` |
-| `ablo.<model>.get({ id })` | `GET /api/v1/models/{model}/{id}` |
+| `ablo.<model>.read({ id })` | `GET /api/v1/models/{model}/{id}` |
 | `ablo.<model>.update({ id, data })` | `PATCH /api/v1/models/{model}/{id}` |
 | `ablo.<model>.delete({ id })` | `DELETE /api/v1/models/{model}/{id}` |
 | `ablo.<model>.claim({ id })` | `POST /api/v1/models/{model}/{id}/claim` |
@@ -284,7 +355,9 @@ rendered as agent tools.
 
 ## Errors
 
-All SDK errors extend `AbloError` and expose a stable `type` string.
+All SDK errors extend `AbloError`. `type` is the class-name discriminator, such
+as `AbloStaleContextError`; `code` is the wire condition, such as
+`stale_context`. Use `instanceof` in-process and `type` after serialization.
 
 | Error | Meaning |
 |---|---|

package/docs/basic-usage.md

@@ -0,0 +1,84 @@
+# Basic Usage
+
+> Read one task row by id, list matching rows, create and update state, and coordinate work when needed.
+
+Assume the configured client from [Installation](./installation.md) is exported
+from `./ablo/client`.
+
+## Read rows
+
+```ts
+import { ablo } from './ablo/client';
+
+const task = await ablo.tasks.get({ id: taskId });
+if (!task) throw new Error('task not found');
+
+const open = await ablo.tasks.list({ where: { status: 'open' } });
+```
+
+`get` observes one current row. Use `read` instead only when a later Ablo write
+must be rejected if that exact premise changes.
+
+## Write rows
+
+```ts
+const created = await ablo.tasks.create({
+  data: { title: 'Review return', status: 'open' },
+});
+
+await ablo.tasks.update({
+  id: created.id,
+  data: { status: 'done' },
+});
+```
+
+Writes return after Ablo confirms the authoritative result. Your PostgreSQL
+constraints and schema remain in force.
+
+## Coordinate slow work
+
+When the target is an Ablo model row, claim it before the expensive step and
+pass the claim to the final write.
+
+```ts
+await using claim = await ablo.tasks.claim({ id: taskId });
+
+const result = await performExpensiveWork(claim.data);
+
+await ablo.tasks.update({
+  id: claim.data.id,
+  data: { title: result.title, status: 'done' },
+  claim,
+});
+```
+
+A contender follows the chosen wait, skip, or fail policy. Disposal releases
+the claim, and expiry lets another participant recover when the owner
+disappears.
+
+## Preserve an existing write
+
+The claimed target does not have to be an Ablo row. Claim a stable business id
+and keep the final transaction in the application that already owns it.
+
+```ts
+await using lease = await ablo.taskRuns.claim(taskId, {
+  contention: { mode: 'skip' },
+});
+if (!lease) return;
+
+const prepared = await performExpensiveWork(taskId);
+return existingTaskService.commitPrepared(taskId, prepared);
+```
+
+That transaction must still re-read, validate, and commit authoritatively. An
+Ablo claim does not join a transaction in another process.
+
+## Add stronger guarantees when required
+
+- [Concurrency Convention](./concurrency-convention.md): reject a write when an
+  earlier premise changed.
+- [Atomic commits](./api.md#atomic-commits): apply several Ablo writes together.
+- [Idempotency](./idempotency.md): make retrying the same Ablo mutation safe.
+- [Agents](./agents.md): configure a stateless HTTP worker.
+- [React](./react.md): add live state and presence for a human interface.

package/docs/branch-development.md

@@ -66,7 +66,9 @@ Login stores one project-scoped `mk_` management credential. It has no
 production/test mode and no application-data authority. It can manage projects
 and branches and exchange for an expiring credential bound to one branch.
 
-If you switch projects, log in for the selected project before running `dev`:
+If you switch projects, log in for the selected project before running `dev`.
+A plain `npx ablo login` offers the organization's projects in the terminal;
+`--project` names one outright:
 
 ```bash
 npx ablo projects use orders
@@ -253,8 +255,8 @@ database's safe coordinates, and an exact readiness fix.
 For a one-shot CI schema check:
 
 ```bash
-# Store the project management credential as the masked secret.
-ABLO_MANAGEMENT_KEY="mk_..." \
+# The one credential input temporarily carries CI's masked management grant.
+ABLO_API_KEY="mk_..." \
 ABLO_BRANCH="preview-pr-${PR_NUMBER}" \
   npx ablo dev --no-watch
 ```
@@ -273,6 +275,22 @@ npx ablo branch ensure "preview-pr-${PR_NUMBER}" \
 result as a secret, mask it in logs, and pass it through the deployment
 provider's secret-variable mechanism.
 
+For live integration tests that should not require a customer database, request
+an explicitly hosted, expiring test branch:
+
+```bash
+npx ablo branch ensure "sandbox-live-${RUN_ID}" \
+  --kind test \
+  --hosted \
+  --expires-at "${EXPIRES_AT}" \
+  --credential \
+  --json
+```
+
+Hosted storage is never inferred. It is accepted only for `kind: test` branches
+that expire within 24 hours; ordinary branches stay unbound until connected to
+the customer's database.
+
 Closing a preview should call `branch delete`. Deletion immediately makes
 branch-bound credentials fail authentication even if their expiry is later.
 
@@ -338,7 +356,8 @@ Run:
 npx ablo login
 ```
 
-For a non-default project:
+The terminal then offers the organization's projects, cursor on the active
+one; a plain Enter keeps it. To name the project and skip the picker:
 
 ```bash
 npx ablo login --project <project>

package/docs/cli.md

@@ -32,8 +32,8 @@ resume a branch and exchanges it for a temporary branch-bound runtime key.
 
 | Command                  | What it does                                                               |
 | ------------------------ | -------------------------------------------------------------------------- |
-| `ablo login`             | Authorize in the browser; store one project management credential.         |
-| `ablo login --project <slug>` | Same, scoped to a project, which becomes active.                     |
+| `ablo login`             | Authorize in the browser, pick a project; store its management credential.  |
+| `ablo login --project <slug>` | Same without the picker: scoped to the named project, which becomes active. |
 | `ablo logout`            | Remove the stored credentials.                                             |
 | `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. |
@@ -55,9 +55,10 @@ reports the server-confirmed branch before it writes. For one-time recovery,
 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.
+The non-secret `config.json` holds the active project. There is one explicit
+credential input: `ABLO_API_KEY`. In headless CI it may temporarily contain an
+`mk_` credential during branch bootstrap; the runtime receives the resulting
+branch-bound `sk_` or restricted `rk_` value through the same variable.
 
 ## Development branches and the production root
 
@@ -94,7 +95,8 @@ with `projects use`) selects which profile every command authenticates with.
 | `ablo projects list`          | List the org's projects (marks the active one and the org-default).                |
 | `ablo projects create <slug>` | Create a project (`--name "Display Name"`). Its keys/schema/data are isolated.     |
 | `ablo projects use <slug>`    | Switch the active project. `ablo projects use default` returns to the org-default. |
-| `ablo login --project <slug>` | Store management access for a project and make it active.                          |
+| `ablo login`                  | Pick a project in the terminal; store its management access and make it active.    |
+| `ablo login --project <slug>` | The same for a named project, with no picker.                                      |
 
 Because keys are fixed to a project, `projects use` only changes which profile
 is active — it never re-scopes an existing key. Switch to a project you haven't
@@ -108,12 +110,17 @@ npx ablo projects use war-room
 npx ablo login --project war-room   # stores its management credential, keeps it active
 ```
 
+A plain `npx ablo login` reaches the same place through a picker: once the
+browser has approved, the terminal lists the organization's projects, with the
+cursor on the active one, and the choice becomes the credential's project. An
+organization holding only its default project is not asked.
+
 If you run a project-scoped command (`push`, `dev`) while the active project has
 no key — but other projects do — the CLI **refuses** rather than silently
 deploying with the wrong project's credential, and names the fix
-(`ablo login --project <slug>`). In CI, an explicit `ABLO_MANAGEMENT_KEY`
-bypasses profiles for project/branch administration; the runtime key remains
-`ABLO_API_KEY`.
+(`ablo login --project <slug>`). In CI, an explicit `mk_` in `ABLO_API_KEY`
+bypasses profiles for project/branch administration. Replace it with the
+branch-bound runtime credential before starting application code.
 
 ## Commands