@abloatai/ablo 0.57.0 → 0.58.0

package/docs/agent-integration-decision-guide.md

@@ -0,0 +1,123 @@
+# Agent Integration Decision Guide
+
+> Choose one integration route before reading an example. Most existing products should coordinate one existing operation first; they should not copy the document pipeline.
+
+## Start with the operation you already own
+
+Name one existing application operation, such as `completeTask`, `approveInvoice`,
+or `publishReport`. Keep its authorization, database transaction, constraints,
+and public API in place. Add Ablo at that operation boundary.
+
+Use this routing table for the decisions that are easy to conflate:
+
+| Question | Choose | When |
+|---|---|---|
+| What is being coordinated? | Identifier-only claim | Work has a stable business identity, but the authoritative row and final write remain in the existing service or Postgres. |
+|  | Row-backed claim | The coordinated row is an Ablo schema model and the final write goes through that model resource. |
+| Did the decision depend on previously read rows? | Captured reads | Read the premises with `read(...)`, then pass those returned rows through `reads`. Use this even when the written row is different from a premise row. |
+| Must several Ablo mutations either all land or none land? | Atomic commit | Put the mutations, captured reads, and any typed claim handles in one `commits.create(...)`. Separate mutation calls are independently successful or failed. |
+| Where should the final write happen? | Existing database write | Keep it when the current service owns the transaction, constraints, or rollout switch. Ablo's lease does not join a transaction running in another process. Re-read and validate inside the database transaction. |
+|  | Ablo-routed write | Use it for declared schema models after the database connection and server schema are configured. Guard decision-dependent writes with a held claim or captured reads. |
+| Who is participating? | Stateless HTTP client | Agents, jobs, and request/response server handlers. Give each concurrent participant its own scoped credential. |
+|  | Reactive WebSocket client | Human-facing applications that need live state, presence, or local reactive reads. This transport is not required for worker coordination. |
+
+These choices compose. For example, a stateless worker can take an
+identifier-only claim, perform slow work, and then call an existing Postgres
+operation. Another worker can take a row-backed claim and submit an atomic Ablo
+commit guarded by captured premise rows.
+
+## Choose the smallest example
+
+### Coordinate existing work
+
+Start with
+[`examples/graphql-existing-backend`](../../../examples/graphql-existing-backend/README.md)
+when an application already owns its API, operation, and Postgres write.
+
+It demonstrates:
+
+- GraphQL delegating to a named application operation;
+- an identifier lease around expensive work;
+- the existing service retaining its authoritative transaction and re-read;
+- an operation-level switch between existing and coordinated paths; and
+- recovery and contract parity without replacing the application's API.
+
+Use
+[`examples/coordination-conformance`](../../../examples/coordination-conformance/README.md)
+alongside it to verify real hosted lease behavior independently of the domain.
+
+### Build evidence-backed document state
+
+Read
+[`examples/existing-document-pipeline`](../../../examples/existing-document-pipeline/README.md)
+only when the feature genuinely needs versioned source evidence, citations,
+guarded review decisions, atomic multi-row review writes, and retained search
+projections.
+
+That example is an advanced reference application. Its document ingestion,
+search, review, projection-retention, and append-only event policies are not
+prerequisites for adopting Ablo.
+
+## Know which owner makes each promise
+
+| Ablo responsibility | Application responsibility |
+|---|---|
+| Participant-scoped claims, lease expiry, wait/skip behavior, heartbeat, release, and commit-time fencing | Choosing the business claim identity and issuing distinct participant credentials |
+| Capturing model-row versions returned by `read(...)` and rejecting a guarded write when those premises are stale | Choosing every row that is a premise of the decision |
+| Atomicity among mutations submitted in one Ablo commit | Database transactions and constraints outside that commit; never presenting separate writes as an atomic batch |
+| Request idempotency within the documented identity, retention, and identical-request rules | Durable workflow idempotency and deduplication of external effects |
+| Synchronizing declared model rows and serving reactive state | Uploads, search semantics, projections, workflow execution, review policy, and external APIs |
+| Credentials, participant attribution, and schema-declared scope enforcement | Existing application authentication and authorization at the operation boundary |
+
+Claims coordinate cooperative participants; they are leases, not absolute locks.
+A writer outside the coordinated path can still change Postgres. Database
+constraints and a commit-time guarded re-read remain the final backstop.
+
+## Minimum integration contract
+
+Write down these answers next to the operation before implementing it:
+
+1. **Existing operation:** Which named operation and public API remain stable?
+2. **Claim identity:** Which stable model row or business identifier represents the contested work?
+3. **Participant identity:** Which distinct scoped credential does each concurrent human, agent, or worker use?
+4. **Premises:** Which exact rows does the decision depend on, and which of them must use `read(...)`?
+5. **Atomic boundary:** Which writes must all succeed together? Are they one Ablo commit, one existing database transaction, or deliberately independent?
+6. **Persistence owner:** What remains in Postgres and which writes, if any, are routed through Ablo?
+7. **Failure behavior:** What happens on contention, lease expiry, stale evidence, request retry, partial completion, and an external side-effect failure?
+8. **Proof:** Which local contract test and which hosted or staging test proves each claimed guarantee?
+
+If an answer is unknown, keep the existing write path available. Do not broaden
+the schema or copy an advanced example to hide the missing decision.
+
+## Guarantee-to-test matrix
+
+The examples prove different layers. A local fixture proves application behavior;
+it does not prove hosted infrastructure. Conversely, hosted claim conformance
+does not prove a domain transition or a real Postgres transaction.
+
+| Statement | Proof level | Executable evidence |
+|---|---|---|
+| GraphQL keeps the same result while the named operation changes implementation | Local application contract | `examples/graphql-existing-backend/tests/graphql.test.ts` and `tests/pilot.test.ts` — `the GraphQL resolver delegates one typed input to the named operation`; `the operation switch preserves the uncontended GraphQL contract` |
+| Coordination moves expensive work outside the retained database critical section | Local application contract; real DB timing requires staging | `examples/graphql-existing-backend/tests/pilot.test.ts` — `coordination moves expensive work outside the retained critical section`; optional `npm run test:live:postgres` |
+| Contenders do not duplicate expensive work, and failure releases the path | Local application contract | `examples/graphql-existing-backend/tests/pilot.test.ts` — `two coordinated workers pay for expensive work once`; `a failed owner releases coordination so the existing path remains available` |
+| Distinct hosted participants exclude one another, heartbeat, release, and recover after expiry | Hosted infrastructure | `examples/coordination-conformance`: `npm run test:live`; its live runner also executes the exit-without-release expiry probe |
+| A decision based on changed source evidence is rejected | Local application contract using Ablo-shaped guards | `examples/existing-document-pipeline/tests/processDocument.test.ts` — `a source change rejects stale extracted output`; `tests/review.test.ts` — `guarded mutations reject stale evidence and release claims for retry` |
+| Several review records submitted as one commit are atomic; separate calls can partially complete | Local application contract | `examples/existing-document-pipeline/tests/review.test.ts` — `requesting review atomically creates durable issue state and an event`; `independent review writes expose partial completion and retry only the stale target` |
+| Rebuilding search does not remove a complete snapshot referenced by durable review evidence | Local application policy | `examples/existing-document-pipeline/tests/search.test.ts` — `publishing a rebuild retains the complete projection snapshot referenced by review`; `an unreferenced superseded projection becomes removable as one snapshot` |
+| The documented ownership tree, public exports, dependency direction, and lack of cycles match disk | Local structure contract | Each focused example's `tests/structure.test.ts`; the document fixture additionally validates exact inventory and dependency direction from `structure.json` |
+| Authorization, latency, database locking, and external-effect behavior match the production application | Partner staging | Run the operation against the real auth, Postgres schema, workload, and provider sandbox. No repository fixture can establish this claim. |
+
+## Safe first adoption
+
+For an existing product, the default sequence is:
+
+1. Wrap one named operation without changing its public API.
+2. Use an identifier-only claim if the existing database remains authoritative.
+3. Keep the Postgres transaction, lock, validation, and constraints in place.
+4. Verify participant-scoped lease behavior with coordination conformance.
+5. Add captured reads or an atomic Ablo commit only when the operation actually needs them.
+6. Move more persistence through Ablo only after the guarded hosted write path and staging behavior are proven for that operation.
+
+Continue with the [Integration Guide](./integration-guide.md) for setup and API
+details, or [Concurrency Convention](./concurrency-convention.md) for the exact
+guarding rules.

package/docs/agents.md

@@ -34,7 +34,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 +42,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 +60,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 +206,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,8 +85,14 @@ 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.
 
@@ -157,30 +172,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 +214,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 +229,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 +241,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;
@@ -258,7 +281,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` |

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
 

package/docs/client-behavior.md

@@ -1,8 +1,11 @@
 # Client Behavior
 
-> Per-write options, claim behavior, and which errors are safe to retry.
+> Guarded writes, claim behavior, and which errors are safe to retry.
 
-When several writers touch the same data at once — an agent worker, a Server Action, a person in the browser — the SDK decides whose write lands and how the others find out. This page is the reference for that: per-write options like `wait` and `onStale`, claiming a record so your slow work runs uninterrupted, and which errors are safe to retry.
+When several writers touch the same data at once — an agent worker, a Server
+Action, a person in the browser — the SDK protects explicit read dependencies
+and claims records across slow work. This page describes those guarantees and
+which errors are safe to retry.
 
 Claims don't lock. If another writer holds the row, `claim` waits for them, re-reads the fresh row, then hands it to you — so two writers serialize instead of clobbering.
 
@@ -34,7 +37,7 @@ Common options:
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. An HTTPS origin, optionally with a path prefix; plain HTTP is accepted for localhost. Your key travels here, so a URL carrying its own credentials, a query, or a fragment is refused at construction. |
 | `persistence` | `memory` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
 | `durableWrites` | Optional crash recovery for unacknowledged agent/worker writes. Independent of the default memory cache; accepts `{ store, namespace? }`. |
-| `transport` | `'websocket'` (default) is the live, stateful client: a persistent socket, a local synced pool, and `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but each call is one HTTP round-trip with no socket. Under `'http'` the return type narrows to `AbloHttpClient`, so stateful-only methods (the `local` reads, `onChange`, `join`) are compile errors rather than runtime gaps. |
+| `transport` | `'websocket'` (default) is the live, stateful client: a persistent socket, a local synced pool, and model `onChange` subscriptions. `'http'` returns the **stateless** client for server-side actors (agents, workers, serverless): the same `ablo.<model>` read/write/claim surface, but ordinary calls are HTTP round trips with no socket. Stateful-only model methods (`local`, model `onChange`, and `join`) are compile errors. A listener added through `context().onChange` holds one HTTP response open only until its context changes or its last listener stops. |
 | `fetch` | Custom fetch implementation for tests or non-standard runtimes. |
 | `defaultHeaders` | Extra headers attached to every HTTP request. |
 | `defaultQuery` | Extra query parameters attached to every HTTP request. |
@@ -53,7 +56,7 @@ Each schema model becomes a typed model:
 ```ts
 await ablo.ready();
 
-const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
 const local = ablo.weatherReports.local.get('report_stockholm');
 
 await ablo.weatherReports.create({ data: { location: 'Stockholm', status: 'pending' } });
@@ -65,7 +68,7 @@ On the reactive client, each model write changes local state optimistically
 before the call returns. Its promise always waits for authoritative
 confirmation, so `await update(...)` is the confirmation barrier.
 
-Call `get`/`list` first — they fetch from the server and you `await` them.
+Call `get`/`list` to observe, or `read` when a later mutation depends on the row.
 After that, `local.get`/`local.list`/`local.count` read the already-synced data instantly with
 no `await`, and stay reactive in render. Use the async pair to load, the sync trio
 to read.
@@ -83,14 +86,13 @@ through the same model client path. A human Server Action, a browser view, and a
 agent worker can all use `ablo.weatherReports`:
 
 ```ts
-const report = await ablo.weatherReports.get({ id });
-const snap = ablo.snapshot({ weatherReports: id });
+const report = await ablo.weatherReports.read({ id });
+if (!report) throw new Error('Row not found');
 
 await ablo.weatherReports.update({
   id,
   data: patch,
-  readAt: snap.stamp,
-  onStale: 'reject',
+  reads: [report],
 });
 ```
 
@@ -106,24 +108,28 @@ actor routing through Ablo is coordinated. The one write it can't coordinate is
 one made directly against your database, around Ablo — the WAL echo still catches
 it for reads, but it bypasses claims and ordering.
 
-## Per-Write Options
+## Guarded Writes
 
 ```ts
+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],
   idempotencyKey: 'report_stockholm:mark-ready:v1',
 });
 ```
 
 | Option | Purpose |
 |---|---|
-| `readAt` | State cursor the write was based on. |
-| `onStale` | Policy when the target changed after `readAt`. Prefer `reject`. |
+| `reads` | Exact rows returned by `read` that this mutation depends on. |
 | `idempotencyKey` | Stable key for retry-safe writes. The SDK generates one when omitted. |
 
+A stale premise always rejects with `AbloStaleContextError`. Omit `reads` only
+when the assignment is intentionally unconditional.
+
 ## Claimed Behavior
 
 If your update involves a slow step — an API call, an LLM round-trip — and someone