@abloatai/ablo 0.34.1 → 0.36.0

package/docs/api.md

@@ -1,5 +1,7 @@
 # API
 
+> The per-method reference for every model call an agent or an interface can make.
+
 > **Upgrading?** Every breaking change and its migration is on the
 > [Version History & Migration Guide](./migration.md).
 
@@ -11,10 +13,12 @@ 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:**
-`retrieve({ id })` / `list({ where })` are async and hit the server (use them when
-the row may not be local yet); `get(id)` / `getAll({ where })` / `getCount({ where })`
-are synchronous reads off the local graph (use them in render, after data has
-synced). **Claims don't lock.** If another writer holds the row, `claim` waits
+`retrieve({ 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
+you get the same read restricted to what is already here, which is why it can
+return a value rather than a promise: `local.retrieve(id)`, `local.list({ where })`,
+`local.count({ where })`. Use those in render, after data has synced.
+**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.
 
@@ -49,31 +53,31 @@ Each schema model becomes a typed model on the client:
 
 - `ablo.weatherReports.retrieve({ id })` reads one row asynchronously (server read).
 - `ablo.weatherReports.list({ where })` reads a collection asynchronously (server read).
-- `ablo.weatherReports.get(id)` reads one row synchronously from the local graph.
+- `ablo.weatherReports.local.retrieve(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.
 
-`retrieve`/`list` and `get`/`getAll`/`getCount` are not aliases. Use
-`retrieve({ id })` or `list({ where })` when the row may not be local yet — they
-hydrate pool → IndexedDB → network. Use `get(id)` / `getAll({ where })` /
-`getCount({ where })` for a cheap synchronous snapshot of what is already in
-the local graph.
+`local.` narrows a read to what has already synced. `retrieve({ 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.retrieve(id)` and `local.list({ where })` are the same reads with the
+fallback removed — nothing to await, so they return a value.
 
 | Method | Returns | Use when |
 |---|---|---|
 | `retrieve({ id })` | `Promise<T \| undefined>` | You need one row, hydrating from local store and server. |
 | `list({ where })` | `Promise<T[]>` | You need to hydrate a collection from local store and server. |
-| `get(id)` | `T \| undefined` | You want a synchronous snapshot of one local row. |
-| `getAll(options?)` | `T[]` | You want a synchronous snapshot of a local collection. |
-| `getCount(options?)` | `number` | You want a synchronous count of local rows. |
+| `local.retrieve(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. |
+| `local.count(options?)` | `number` | You want a synchronous count of local rows. |
 | `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. |
 
 `retrieve`, `list`, `create`, `update`, and `delete` are the main path — they go
-through the server. `get` / `getAll` / `getCount` are **synchronous reads**
-off the rows a session has already synced, so a cheap re-read needs no round-trip.
+through the server. The `local` reads work off the rows a session has already
+synced, so a cheap re-read needs no round-trip.
 
 ## Protected Writes
 
@@ -103,7 +107,7 @@ Protected write options:
 
 ## Claims
 
-Before anyone writes a row, they can claim it so other people and agents see
+Before anyone writes a row, they can claim it so other agents and people see
 who is editing it in real time. 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. A claim is temporary: it expires
@@ -116,49 +120,11 @@ 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`.
 
-### The Claim State Object
-
-| Field | Type | Description |
-|---|---|---|
-| `object` | `'claim'` | String representing the object's type. |
-| `id` | string | Unique identifier for the claim. |
-| `status` | `'active' \| 'queued' \| 'committed' \| 'expired' \| 'canceled'` | The whole lifecycle, in one field. `active` is the holder; `queued` is a waiter in the FIFO line behind it. |
-| `target` | `{ type, id, field? }` | What is being coordinated. |
-| `description` | string | Peer-visible phrase for the work in progress — `'editing'`, `'writing'`, `'reviewing the risk section'`. Defaults to `'editing'`, and rides back in the rejection a blocked writer receives. |
-| `heldBy` | string | Participant id holding the claim. |
-| `participantKind` | `'user' \| 'agent' \| 'system'` | Who's behind it — a human (`user`), an AI (`agent`), or automated infrastructure (`system`). |
-| `createdAt` | number? | Ms-epoch the holder opened it. Optional — derived shapes may omit it. |
-| `expiresAt` | number | Ms-epoch at which the server auto-expires it if the holder doesn't finish. |
-
-```json
-{
-  "object": "claim",
-  "id": "claim_3MtwBwLkdIwHu7ix",
-  "status": "active",
-  "target": { "type": "weatherReports", "id": "report_stockholm", "field": "status" },
-  "description": "editing",
-  "heldBy": "agent:report-writer",
-  "participantKind": "agent",
-  "expiresAt": 1716580000000
-}
-```
-
-### Lifecycle
-
-```
-            claim({ id })              update({ id }) lands
-  (free) ───────────▶ active ───────────────────────▶ committed
-                        │
-            ┌───────────┴───────────┐
-            ▼                       ▼
-        canceled                 expired
-   (release w/o write)        (TTL; holder died)
-```
-
-A target is free when `ablo.<model>.claim.state({ id })` is `null`. Terminal
-states drop out of the live stream, so a present claim is either `active` (the
-holder) or `queued` (waiting in the FIFO line behind the holder; see
-`claim.queue({ id })`).
+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
+object is defined. Note that the entity half of `target` is spelled `model`/`id`
+on the SDK's model surface and `type`/`id` on the claim handle and the wait
+line.
 
 ### Reading and claiming
 
@@ -206,7 +172,7 @@ The SDK is a convenience wrapper over a model-scoped HTTP surface — the same
 noun (`model`) and verbs as `ablo.<model>.…`. Non-JS callers (or curl) use it
 directly. The table below shows the shape with `{model}` as a placeholder; the
 [OpenAPI spec](./openapi.json) expands it into one **typed** path per model
-(`/api/v1/models/task`, `/api/v1/models/deck`, …, generated from your schema) so each
+(`/api/v1/models/task`, `/api/v1/models/workspace`, …, generated from your schema) so each
 endpoint documents that model's real field contract instead of a generic blob.
 
 | SDK call | HTTP |
@@ -232,7 +198,7 @@ error `code` (e.g. `stale_context`, `intent_conflict`) to act on.
 operations across rows/models that must commit together) — the per-model routes
 above are the one-record path. Both run the identical guarded-write engine.
 
-The [coordination MCP server](./mcp.md) (`@ablo/mcp`) is this same surface
+The [coordination MCP server](./mcp.md) (`@abloatai/mcp`) is this same surface
 rendered as agent tools.
 
 ## Errors

package/docs/audit.md

@@ -1,5 +1,7 @@
 # Audit log
 
+> Trace any committed change back to the key that made it, and to the person behind that key.
+
 The audit log records who changed what in your org, and when — including
 changes an AI agent made on a person's behalf. Every change is one row, and the
 rows are chained with a keyed hash (HMAC-SHA256) so you can later prove the
@@ -21,11 +23,12 @@ with which key — and the chain columns that make the log tamper-evident:
   capabilityId:              string | null,    // the API key/capability used for the write
   capabilityLabel:           string | null,    // its human-readable name, for scanning the log
   delegationChainRootUserId: string | null,    // always points at a human
-  actionType:                string,           // e.g. 'weatherReport.update'
-  modelName:                 string,            // e.g. 'claude-opus-4-8'
+  actionType:                'I' | 'U' | 'D',  // insert, update, delete
+  modelName:                 string,           // the model that changed, e.g. 'orders'
+  modelId:                   string,           // the row that changed
   confirmationState:         'auto' | 'previewed' | 'approved' | 'required_human_approval' | 'auto_historical',
   diffSummary:               unknown,
-  // chain columns — carried on every stored row, checked by verify (below)
+  // chain columns, carried on every stored row and checked by verify (below)
   chainSeq:                  number,
   prevHash:                  string,
   rowHash:                   string,

package/docs/cli.md

@@ -1,5 +1,7 @@
 # CLI
 
+> Scaffold a schema, connect a database, push it, and watch it sync.
+
 The `ablo` CLI gets you from an empty project to live-syncing data: scaffold a
 schema, authenticate, push the schema, and watch it sync. Your
 `defineSchema(...)` is the single source of truth: whether you run the CLI
@@ -34,7 +36,7 @@ This mirrors `stripe login`.
 | `ablo login`             | Authorize in the browser; provisions + stores a test and a live key.       |
 | `ablo login --project <slug>` | Same, but scope (and mint) the pair to a project, and make it active. |
 | `ablo logout`            | Remove the stored keys.                                                    |
-| `ablo status`            | Show the active org, mode, both keys (prefix + expiry), and server health. |
+| `ablo status`            | Show the active org, mode, both keys (prefix, what each can do, expiry), and server health. |
 | `ablo mode [sandbox\|production]` | Switch the active environment. With no argument, prompts.                         |
 
 Keys live in `~/.config/ablo/credentials.json` (mode `0600`), keyed by project
@@ -49,8 +51,11 @@ belongs to one of them. Test keys are bound to an isolated sandbox: their reads
 and writes never touch production data. Switch with `ablo mode`; `ablo dev` is always
 the sandbox by design.
 
-The schema, however, is **shared** across the org — pushing a schema (from
-either environment) defines the same models sandbox and production see; only the rows differ.
+The schema is **one definition serving both**: a sandbox reads the production
+schema until it is pushed one of its own, so your test and live keys see the same
+models and only the rows differ. Each plane keeps its own copy once pushed, so a
+schema change reaches production when you push it with a live key — see
+[Deployment](./deployment.md).
 
 ## Projects
 
@@ -89,17 +94,40 @@ profiles entirely: it acts in whatever project it was minted for.
 
 | Command                            | What it does                                                                                                                                  | Flags                                                                                                  |
 | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `ablo init`                        | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. | —                                                                                                      |
-| `ablo login` / `logout` / `status` | Authentication & status (above).                                                                                                              | —                                                                                                      |
-| `ablo mode [sandbox\|production]`   | Switch active environment.                                                                                                                           | —                                                                                                      |
+| `ablo init`                        | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. |: |
+| `ablo login` / `logout` / `status` | Authentication & status (above).                                                                                                              |: |
+| `ablo mode [sandbox\|production]`   | Switch active environment.                                                                                                                           |: |
 | `ablo projects list\|create\|use\|rename` | Manage projects and the active one (see [Projects](#projects)). Each project's keys/schema/data are isolated.                          | `--name "<display>"` (create/rename)                                                                    |
-| `ablo dev`                         | **Hosted** — push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save.                                           | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>`                                      |
+| `ablo dev`                         | **Hosted**: push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save.                                           | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>`                                      |
 | `ablo logs`                        | Tail your scope's commit activity (`stripe logs tail`). Follows by default.                                                                   | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow`, `--mode sandbox\|production` |
-| `ablo push`                        | **Hosted** — upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |
-| `ablo migrate`                     | **Direct Postgres** — provision just the synced models (plus the adapter's `ablo_outbox` / `ablo_idempotency`) in your own `DATABASE_URL`. Leaves your other tables alone.                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
-| `ablo pull`                        | **Direct Postgres** — generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`).                              | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force`                                     |
-| `ablo check`                       | **Direct Postgres** — verify your _existing_ tables fit the schema (read-only, no schema changes).                                                       | `--schema <path>`, `--export <name>`, `--app-schema <name>`                                            |
+| `ablo push`                        | **Hosted**: upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |
+| `ablo migrate`                     | **Direct Postgres**: provision just the synced models (plus the adapter's `ablo_outbox` / `ablo_idempotency`) in your own `DATABASE_URL`. Leaves your other tables alone.                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
+| `ablo pull`                        | **Direct Postgres**: generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`).                              | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force`                                     |
+| `ablo check`                       | **Direct Postgres**: verify your _existing_ tables fit the schema (read-only, no schema changes).                                                       | `--schema <path>`, `--export <name>`, `--app-schema <name>`                                            |
 | `ablo generate`                    | Emit TypeScript types from the schema.                                                                                                        | `--out <path>`, `--schema`, `--export`                                                                 |
+| `ablo docs`                        | Read these pages for the version you installed: offline, no network (see [`ablo docs`](#ablo-docs)).                                          | `--json`                                                                                               |
+
+## `ablo docs`
+
+The documentation for the version in your `node_modules`, not the version on the
+website.
+
+```bash
+npx ablo docs                  # every page, with what it covers
+npx ablo docs coordination     # one page, as markdown
+npx ablo docs --json           # the page list, machine-readable
+```
+
+These pages ship inside the npm package, so they describe the code beside them
+and stay reachable with no network — the sandboxes and CI runners agents work in
+often have none. That matters most when a project is pinned: `get` / `getAll` /
+`getCount` became `retrieve` / `list` in 0.35.0, and a website always describes
+the newest release, so an agent on an earlier version reads the new name and
+writes a call its own package doesn't have.
+
+Pass a slug (`coordination`), a path (`docs/coordination.md`), or a file name
+(`AGENTS.md`). A miss names the closest page. The same pages are served over
+HTTP at `/api/docs/<slug>` and through the docs MCP server.
 
 ## `ablo dev`
 
@@ -213,7 +241,7 @@ The one type map, shared by both paths (there is no second mapping):
 | Zod                                                          | Postgres                                                                                                 |
 | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
 | `z.string()`                                                 | `TEXT`                                                                                                   |
-| `z.number()`                                                 | `DOUBLE PRECISION` — never `INTEGER`; a Zod number may be fractional, and truncating is silent data loss |
+| `z.number()`                                                 | `DOUBLE PRECISION`: never `INTEGER`; a Zod number may be fractional, and truncating is silent data loss |
 | `z.boolean()`                                                | `BOOLEAN`                                                                                                |
 | `z.date()`                                                   | `TIMESTAMPTZ`                                                                                            |
 | `z.enum([...])`                                              | `TEXT` + a `CHECK (col IN (...))` constraint                                                             |
@@ -268,7 +296,7 @@ migration can't leave clients gated against tables that don't match.
 
 | Variable                              | Purpose                                                                  | Default                    |
 | ------------------------------------- | ------------------------------------------------------------------------ | -------------------------- |
-| `ABLO_API_KEY`                        | Authenticate without `ablo login` (CI). Always overrides the stored key. | —                          |
+| `ABLO_API_KEY`                        | Authenticate without `ablo login` (CI). Always overrides the stored key. |: |
 | `ABLO_API_URL`                        | Control-plane / API host (`push`, `dev`, `status`).                      | `https://api.abloatai.com` |
 | `ABLO_AUTH_URL`                       | Dashboard origin for `ablo login`'s device flow.                         | `https://abloatai.com`     |
 | `ABLO_CONFIG_DIR` / `XDG_CONFIG_HOME` | Where the credential file lives.                                         | `~/.config/ablo`           |

package/docs/client-behavior.md

@@ -1,6 +1,8 @@
 # Client Behavior
 
-When several writers touch the same data at once — a person in the browser, a Server Action, an agent worker — 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.
+> Per-write options, 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.
 
 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.
 
@@ -32,7 +34,7 @@ Common options:
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
 | `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 (`get`/`getAll`, `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 `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. |
 | `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. |
@@ -52,7 +54,7 @@ Each schema model becomes a typed model:
 await ablo.ready();
 
 const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
-const local = ablo.weatherReports.get('report_stockholm');
+const local = ablo.weatherReports.local.retrieve('report_stockholm');
 
 await ablo.weatherReports.create({ data: { location: 'Stockholm', status: 'pending' } });
 await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' }, wait: 'confirmed' });
@@ -60,11 +62,11 @@ await ablo.weatherReports.delete({ id: 'report_stockholm', wait: 'confirmed' });
 ```
 
 Call `retrieve`/`list` first — they fetch from the server and you `await` them.
-After that, `get`/`getAll`/`getCount` read the already-synced data instantly with
+After that, `local.retrieve`/`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.
 
-`getAll` accepts the same practical read options the React selector path uses:
+`local.list` accepts the same practical read options the React selector path uses:
 `where`, `filter`, `orderBy`, `limit`, `offset`, and `state`. The `state`
 lifecycle filter defaults to `'live'`; pass `'archived'` or `'all'` when you
 intentionally want non-live rows.
@@ -91,7 +93,7 @@ await ablo.weatherReports.update({
 
 Once the server accepts the write, every other connected client gets the new row
 automatically — no polling or manual refresh on your side. React clients that use
-`useAblo((ablo) => ablo.weatherReports.get(id))` receive the new row, and selectors
+`useAblo((ablo) => ablo.weatherReports.local.retrieve(id))` receive the new row, and selectors
 such as `useAblo((ablo) => ablo.weatherReports.claim.state({ id }))`
 receive active claim state. There is
 no extra multiplayer setup beyond routing shared state through Ablo.
@@ -216,8 +218,8 @@ Only these imports are public SemVer surface:
 - `@abloatai/ablo`
 - `@abloatai/ablo/schema`
 - `@abloatai/ablo/react`
-- `@abloatai/ablo/testing`
 
 `dataSource(...)` is exported from the root package for customer-owned storage
-adapters. Everything outside the four import paths is internal to Ablo-owned
-apps and infrastructure.
+adapters. Everything outside the three import paths is internal to Ablo-owned
+apps and infrastructure. For adapter authors, `@abloatai/ablo/source/conformance`
+is the suite that proves a storage adapter behaves correctly.

package/docs/concurrency-convention.md

@@ -1,8 +1,10 @@
 # Concurrency Convention
 
-> The governing convention for how Ablo resolves concurrent writes to shared
-> state, and the boundaries of that convention. This is the contract; the
-> three-layer mechanics live in [`coordination.md`](./coordination.md).
+> The governing rule for how Ablo resolves concurrent writes to shared state.
+
+This page is the contract: the `onStale` dispositions, what a conflict is
+checked against, and where the convention stops. The three-layer mechanics of
+claiming live in [Coordination](./coordination.md).
 
 ---
 
@@ -25,8 +27,8 @@ moments in time:
 
 | form | when | mechanism |
 |---|---|---|
-| **Claim** | *prospective* — before you act | reserve the row; others queue. Coordinate so the conflict never forms. |
-| **Notification** | *in-flight* — after a concurrent change | surface the changed value; the actor resolves and re-issues. |
+| **Claim** | *prospective*: before you act | reserve the row; others queue. Coordinate so the conflict never forms. |
+| **Notification** | *in-flight*: after a concurrent change | surface the changed value; the actor resolves and re-issues. |
 
 Use a claim when you will hold the row across a slow read→reason→write gap. Use a
 notification when you didn't, and the premise moved under you.
@@ -35,14 +37,14 @@ notification when you didn't, and the premise moved under you.
 
 ## 2. The dispositions (`onStale`)
 
-Every guarded write (and every read dependency, §4) declares how a stale premise
-should be handled. Three modes, split by whether they **force** an outcome:
+Every guarded write (and every premise declared in §4) says what should happen
+when it goes stale. Three modes, split by whether they **force** an outcome:
 
 | mode | coercive? | what the engine does | who resolves | use when |
 |---|---|---|---|---|
-| `notify` | **No** — surface + delegate | Holds the write (does **not** apply it); returns a `StaleNotification` with the current value. | The actor (agent or human) reconciles and re-issues. | The aligned mode: tell the actor what changed, let it solve. |
-| `reject` | **Yes** — force-abort | Throws `AbloStaleContextError`; the batch is discarded. | The caller retries from scratch. | Hard invariants; legacy/strict callers. The current default. |
-| `overwrite` | **Yes** — force-clobber | Overwrites blindly last-writer-wins; **no** signal. | Nobody. | You genuinely own the field and concurrent values are noise. |
+| `notify` | **No**: surface + delegate | Holds the write (does **not** apply it); returns a `StaleNotification` with the current value. | The actor (agent or human) reconciles and re-issues. | The aligned mode: tell the actor what changed, let it solve. |
+| `reject` | **Yes**: force-abort | Throws `AbloStaleContextError`; the batch is discarded. | The caller retries from scratch. | Hard invariants; legacy/strict callers. The current default. |
+| `overwrite` | **Yes**: force-clobber | Overwrites blindly last-writer-wins; **no** signal. | Nobody. | You genuinely own the field and concurrent values are noise. |
 
 > `notify` is the convention. `reject` and `overwrite` are escape hatches for the
 > two ends — "never let this be wrong" and "never bother me." They are not the
@@ -50,43 +52,44 @@ should be handled. Three modes, split by whether they **force** an outcome:
 
 ---
 
-## 3. What is checked: two footprints
+## 3. What is checked: two premises
 
-A conflict is a **footprint intersection** — your operation's footprint overlaps
-a concurrent delta. Ablo checks two footprints, and they are independent:
+A conflict is a **premise intersection** — what your operation was based on
+overlaps a concurrent delta. Ablo checks two premises, and they are independent.
+They differ only in what declared them:
 
-| footprint | declared by | question | scope |
+| premise | declared by | question | scope |
 |---|---|---|---|
 | **Write-target** | per-op `readAt` | "did a row I'm **writing** change since I read it?" | the rows in `operations[]` |
-| **Read-set** | batch-level `reads[]` | "did anything I **looked at** change since I read it?" | rows/groups in `reads[]`, even if not written |
+| **Batch** | batch-level `reads[]` | "did anything I **looked at** change since I read it?" | rows/groups in `reads[]`, even if not written |
 
 The write-target check alone is the narrow case the canary anomaly defeats: an
 agent reads `deal.stage`, writes `task.status`, and a peer moves `deal.stage` —
-`task` never changed, so a write-target-only check waves it through. The read-set
-closes that gap.
+`task` never changed, so a write-target-only check waves it through. The batch
+premise closes that gap.
 
 ---
 
-## 4. The read-set (`reads[]`)
+## 4. The batch premise (`reads[]`)
 
-A commit may declare, at the batch level, the premises its writes depended on.
+A commit may declare, at the batch level, what its writes were based on.
 Two granularities, developer's choice per entry:
 
 ```ts
 reads: [
-  { model: 'Slide', id: 's-1', readAt: N, fields?: ['title'] }, // ROW premise
-  { group: 'deck:abc', readAt: N, onStale: 'notify' },          // GROUP premise
+  { model: 'Document', id: 's-1', readAt: N, fields?: ['title'] }, // ROW premise
+  { group: 'workspace:abc', readAt: N, onStale: 'notify' },          // GROUP premise
 ]
 ```
 
-- **Row** — did this specific row (optionally these fields) change? The literal
+- **Row:** did this specific row (optionally these fields) change? The literal
   per-object premise.
-- **Group** — did *anything* in this sync group change? `group` is a sync-group
-  key (`deck:abc`, `slide:s1`, `org:X`) — the same unit a participant **watches
+- **Group:** did *anything* in this sync group change? `group` is a sync-group
+  key (`workspace:abc`, `document:s1`, `org:X`) — the same unit a participant **watches
   and claims**. This is the more Ablo-native granularity.
 
-**Boundary — a stale read fires over the whole batch.** A read dependency is a
-premise for *all* the writes in the commit, so its disposition governs the batch:
+**Boundary — a stale premise fires over the whole batch.** Each entry covers
+*all* the writes in the commit, so its disposition governs the batch:
 `reject` aborts it, `notify` holds **every** write and notifies, `overwrite`
 lets them land. Per-entry `onStale` defaults to `reject`.
 
@@ -105,13 +108,13 @@ Shape (canonical in `coordination/schema.ts`):
 
 | field | meaning |
 |---|---|
-| `object` | Stripe-style type tag — `'stale_notification'` |
+| `object` | Stripe-style type tag: `'stale_notification'` |
 | `model`, `id` | the conflicting row (for a group dep, both are the group key) |
 | `group?` | set when this is a group-scoped notification |
 | `readAt` | the watermark the committer reasoned against |
-| `observedSyncId` | the newest delta on the premise — re-read at/after this |
+| `observedSyncId` | the newest delta on the premise: re-read at/after this |
 | `conflictingFields` | fields that moved (empty for group / whole-entity) |
-| `currentValues` | the live values of those fields — the premise to reconcile against (empty for group) |
+| `currentValues` | the live values of those fields: the premise to reconcile against (empty for group) |
 | `writtenBy` | `{ kind, id }` of the concurrent author, reported faithfully |
 
 Only `notify` produces a notification (the write was held). `reject` throws and
@@ -152,7 +155,7 @@ function reconcile(n: StaleNotification) {
 
 The loop **terminates** because each retry advances `readAt` to `observedSyncId`;
 a peer that keeps writing only ever notifies you against a *newer* baseline, never
-the same one twice. A group read-dep reconciles identically, except `group` is set
+the same one twice. A group premise reconciles identically, except `group` is set
 and `currentValues` is empty (re-read the group).
 
 ---
@@ -166,7 +169,7 @@ What the convention **guarantees**, and where it **stops**:
    or human) owns the resolution. The engine does not distinguish them — it is
    actor-neutral by design.
 
-2. **Truthfulness.** `currentValues` / `observedSyncId` reflect committed state at
+2. **Truthfulness:** `currentValues` / `observedSyncId` reflect committed state at
    detection time, inside the same transaction as the write. A notification is
    never speculative.
 
@@ -182,13 +185,11 @@ What the convention **guarantees**, and where it **stops**:
    so they must not be gated by `notify`.
 
 5. **Defaults.** A plain write (no `readAt`) is last-writer-wins with **no**
-   check. A guarded write with `readAt` but no `onStale` defaults to `reject`
-   (back-compat). *Open decision (§7).*
+   check. A guarded write with `readAt` but no `onStale` defaults to `reject`.
 
 6. **Policy seam.** Custom `ConflictPolicy` functions see **write-target**
-   conflicts (`stale_context` / `claim_held`). **Read-set** conflicts are
-   currently resolved directly via each entry's `onStale`, not through the policy
-   seam. *Open decision (§7).*
+   conflicts (`stale_context` / `claim_held`). **Batch-premise** conflicts are
+   resolved directly via each entry's `onStale`, not through the policy seam.
 
 7. **Claims win when held.** A non-holder writing to a claimed row is rejected
    (`AbloClaimedError`) regardless of `readAt` — the prospective form takes
@@ -197,26 +198,17 @@ What the convention **guarantees**, and where it **stops**:
 
 ---
 
-## 7. Open decisions (bounded, not yet made)
-
-These are deliberately left open; they change behavior and are the user's call.
-
-- **Default disposition for agents.** Should an agent-participant guarded write
-  default to `notify` (philosophy-aligned: surface, don't overwrite) instead of
-  `reject` (back-compat)? Trade-off: alignment vs. a behavior change for existing
-  agent callers.
-- **Read-deps through the policy seam.** Should read-set conflicts also pass
-  through `ConflictPolicy` (requires a group-aware conflict shape), or stay on
-  the direct `onStale` mapping?
-
----
+## 7. What this convention does not cover
 
-## 8. Out of scope
+Three limits worth knowing before you rely on it.
 
-- Irreversible external side-effects (§6.4) — not gated by this convention.
-- Cross-object *serializability proof*. The read-set is a sound premise check,
-  not a full precedence-graph guarantee; it needs declared reads to catch a
-  premise, and a caller that declares none gets only write-target checking.
-- Identity → participant-kind mapping. `writtenBy.kind` reports whatever
-  authenticated (an `sk_` key resolves to `system`, not `agent`); how identities
-  map to kinds is a separate concern.
+- **Irreversible external side-effects.** Emails, payments, and third-party
+  calls are not gated by this convention (§6.4). The engine cannot hold or undo
+  them, so never place one behind `notify`.
+- **A caller that declares nothing gets no check.** The batch premise catches
+  only what you declared. Write-target checking needs a `readAt` to compare
+  against, so a plain write with neither is last-writer-wins (§6.5). What you
+  declare is what is protected.
+- **`writtenBy.kind` reports what authenticated, not what you meant.** An `sk_`
+  key resolves to `system`, not `agent`. How identities map to participant kinds
+  is a separate concern from this convention.