@abloatai/ablo 0.6.0 → 0.8.0

package/docs/audit.md

@@ -1,7 +1,11 @@
 # Audit log
 
-Every commit becomes one row. Rows are hash-chained per principal —
-tamper-evident, queryable, exportable.
+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 signed in a chain so you can later prove the history wasn't altered.
+You can filter it, page through it, and export it.
+
+Every commit becomes one row.
 
 ## Row shape
 
@@ -12,10 +16,10 @@ tamper-evident, queryable, exportable.
   actorId:              string,
   onBehalfOfKind:       'user' | 'agent' | 'system' | null,
   onBehalfOfId:         string | null,
-  credentialId:         string | null,
-  credentialLabel:      string | null,
+  credentialId:         string | null,    // the API key/credential used for the write
+  credentialLabel:      string | null,    // its human-readable name, for scanning the log
   delegationChainRoot:  string | null,    // always points at a human
-  causedByRunId:        string | null,
+  causedByRunId:        string | null,    // the agent run that produced this write — group every change from one run
   actionType:           string,           // e.g. 'weatherReport.update'
   modelName:            string | null,    // e.g. 'claude-opus-4-7'
   diffSummary:          unknown,
@@ -28,9 +32,9 @@ tamper-evident, queryable, exportable.
 
 ## Delegation chain
 
-`delegationChainRoot` always points at the human who started the chain.
-There is no audit row whose root is an agent. Autonomous AI writes are not
-a thing in this system; every chain starts with a person.
+Every action traces back to a human. Even when an agent makes the change,
+`delegationChainRoot` names the person who set that work in motion — there is no
+audit row whose root is an agent.
 
 ## Verify
 
@@ -71,7 +75,10 @@ curl 'https://<your-app>/api/orgs/<slug>/audit/export?actorKind=agent&since=2026
   > may-agent-writes.csv
 ```
 
-CSV up to a hard cap per request. For larger windows, paginate.
+One request exports CSV up to a hard row cap. If your window is larger than the
+cap, the response is truncated at the cap rather than erroring — so for large
+windows, split the window by date and request each slice, or page through the
+JSON `GET` endpoint above using `nextCursor`.
 
 ## Compliance posture
 

package/docs/cli.md

@@ -0,0 +1,222 @@
+# CLI
+
+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
+locally or push to the hosted server, the same engine turns it into the same
+SQL — so what you test is what ships.
+
+```bash
+npx ablo init      # scaffold ablo/schema.ts + client
+npx ablo login     # authorize in the browser
+npx ablo dev       # push schema to the test sandbox + watch
+```
+
+**Two setups, and they pick your commands.** If Ablo manages your Postgres —
+the default, **hosted** path — use `ablo dev` and `ablo push`. If you
+**bring your own database (BYO)**, use `ablo migrate` to apply changes to your
+own `DATABASE_URL` directly, and `ablo check` / `ablo pull` to adopt tables you
+already have. The commands below are tagged **Hosted** or **BYO** so you can
+tell which apply to you.
+
+## Authenticate
+
+`ablo login` runs the OAuth 2.0 device flow: it opens your browser, you choose
+**log in** or **create an account** and approve, and the CLI provisions a
+**test + live key pair** (90-day, restricted) and stores them locally. This
+mirrors `stripe login`.
+
+| Command | What it does |
+| --- | --- |
+| `ablo login` | Authorize in the browser; provisions + stores a test and a live key. |
+| `ablo logout` | Remove the stored keys. |
+| `ablo status` | Show the active org, mode, both keys (prefix + expiry), and server health. |
+| `ablo mode [test\|live]` | Switch the active mode. With no argument, prompts. |
+
+Keys are stored in `~/.config/ablo/config.json` (mode `0600`). In **CI**, don't
+log in — set `ABLO_API_KEY`, which always overrides the stored key.
+
+## Test vs live
+
+Like Stripe, every account has a **test** mode and a **live** mode, and a key
+belongs to one of them. Test keys are bound to an isolated sandbox: their reads
+and writes never touch live data. Switch with `ablo mode`; `ablo dev` is always
+test mode by design.
+
+The schema, however, is **shared** across the org — pushing a schema (from
+either mode) defines the same models test and live see; only the rows differ.
+
+## Commands
+
+| 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 [test\|live]` | Switch active mode. | — |
+| `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 test\|live` |
+| `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` | **BYO** — apply the schema to your own `DATABASE_URL` (you run the DDL). | `--dry-run`, `--output <file>`, `--schema`, `--export` |
+| `ablo pull` | **BYO** — generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`). | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force` |
+| `ablo check` | **BYO** — verify your *existing* tables fit the schema (read-only, no DDL). | `--schema <path>`, `--export <name>`, `--app-schema <name>` |
+| `ablo generate` | Emit TypeScript types from the schema. | `--out <path>`, `--schema`, `--export` |
+
+## `ablo dev`
+
+The development loop. It pushes `ablo/schema.ts` to your **test sandbox**,
+prints the env line your app needs, then watches the file and re-pushes on every
+save (300 ms debounce). It refuses live keys so a tight save loop can never
+churn production data.
+
+```bash
+npx ablo dev             # push + watch
+npx ablo dev --no-watch  # push once and exit
+```
+
+## `ablo logs`
+
+Tail commit activity, like `stripe logs tail`. Scope comes from the key — a test
+key streams only its sandbox's writes, a live key the org's — so you never pass
+an org. Follows by default; `--no-follow` prints recent and exits.
+
+```bash
+npx ablo logs                      # last 50, then stream
+npx ablo logs -n 100 --model task  # backfill 100, one model
+npx ablo logs --since 15m --json   # last 15m as NDJSON, then stream
+```
+
+Each line is `time · op · model · id · actor`. `--json` emits one event per line
+(NDJSON) for piping to `jq` or an agent.
+
+## `ablo pull`
+
+Generate `defineSchema(...)` from the tables you already have — the inverse of
+provisioning, and read-only (like `prisma db pull`). It introspects
+`DATABASE_URL`, emits a model per adoptable table (one that has `id` +
+`organization_id`), maps Postgres types back to Zod, and writes `ablo/schema.ts`.
+
+```bash
+DATABASE_URL=postgres://… npx ablo pull
+```
+
+It never touches the database, and won't overwrite an existing schema without
+`--force`. Introspection is lossy — enum members, JSON shape, relations, and
+defaults can't be recovered from columns — so treat the output as a starting
+point: review it, then run `ablo check`.
+
+## `ablo check`
+
+`ablo check` is how you adopt a database you already own. Instead of creating or
+altering tables, it inspects your existing ones and tells you which fit the
+schema: it introspects `DATABASE_URL`, compares each table to your
+`defineSchema(...)`, and reports — per model — whether the table is adoptable.
+It never writes or alters anything.
+
+A table is adoptable when it has a primary key `id` and (for org-scoped models)
+an `organization_id` column — the tenancy marker the engine isolates on. Every
+other table in your database is ignored.
+
+**Why `organization_id`?** It's the one column that makes a table safe to
+multiplayer-sync. Row-level security scopes every read and write by it (org A
+can't see org B's rows), and the engine routes realtime deltas by `org:<id>`. A
+table without a tenancy key has no isolation boundary, so Ablo excludes it
+**by default** rather than risk exposing it across tenants. If your tenancy
+column has a different name, keep that table behind a
+[Data Source endpoint](/data-sources) for now.
+
+```bash
+DATABASE_URL=postgres://… npx ablo check
+```
+
+```text
+  ✓ tasks     → tasks (id, organization_id ok)
+  ✗ projects  → projects
+      • missing "organization_id" — add it, or move this model behind a Data Source
+  2 models · 1 ok · 1 error
+  12 other tables in your database — ignored by Ablo
+```
+
+If a table can't carry `organization_id` (or has business logic Ablo shouldn't
+bypass), keep it behind a [Data Source endpoint](/data-sources) rather than
+reshaping it. `ablo check` is read-only; it never proposes a migration.
+
+## `migrate` (BYO) vs `push` (Hosted)
+
+Same engine, two setups. If you **bring your own database (BYO)**, use
+`ablo migrate` — it applies the schema to your own `DATABASE_URL`, and you run
+the DDL. If Ablo manages your Postgres (the **hosted** path), use `ablo push`
+(and `ablo dev`) — the server applies the change to Ablo-managed Postgres
+and version-gates connecting clients.
+
+```bash
+ablo migrate --dry-run            # preview the exact SQL
+ablo migrate                      # apply to DATABASE_URL
+ablo migrate --output schema.sql  # write SQL to a file
+```
+
+## Zod → Postgres type mapping
+
+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.boolean()` | `BOOLEAN` |
+| `z.date()` | `TIMESTAMPTZ` |
+| `z.enum([...])` | `TEXT` + a `CHECK (col IN (...))` constraint |
+| `z.object` / `z.array` / `z.record` / `z.union` / `z.custom` | `JSONB` |
+| `.optional()` / `.nullable()` | nullable column |
+
+Each table also gets the platform columns (`id`, `organization_id`,
+`created_by`, `created_at`, `updated_at`), an `organization_id` index, and
+row-level security so each org only sees its own rows — the engine sets this per
+request (via `current_setting('app.current_org_id')`); you don't manage it.
+
+`.default(...)` is **not** emitted as a SQL column default — Zod applies the
+default at write time (`create`), in one place, so a DB default and a schema
+default can't drift.
+
+## Structured errors
+
+A failed migration aborts the whole transaction (nothing partial lands) and
+reports the same `migration_failed` shape on both paths — naming the statement
+that broke and the Postgres SQLSTATE, not just "migration failed".
+
+`ablo migrate` (local) logs it:
+
+```txt
+[migrate] migration plan failed {
+  code: 'migration_failed',
+  failedStatement: 'ALTER TABLE "public"."tasks" RENAME COLUMN a TO b;',
+  failedStatementIndex: 4,
+  pgCode: '42P01',
+  durationMs: 133
+}
+```
+
+`ablo push` (hosted) returns the canonical error envelope (HTTP 500),
+which the SDK reconstructs as a typed `AbloServerError`:
+
+```json
+{
+  "type": "AbloServerError",
+  "code": "migration_failed",
+  "message": "schema migration failed: relation \"...\" does not exist",
+  "doc_url": "https://docs.abloatai.com/errors#migration_failed",
+  "failedStatement": "ALTER TABLE ... RENAME COLUMN a TO b;",
+  "pgCode": "42P01"
+}
+```
+
+The pushed artifact is recorded `failed` and is never activated, so a broken
+migration can't leave clients gated against tables that don't match.
+
+## Environment
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `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
 
-This page covers the SDK behavior around options, errors, retries, and runtimes.
+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.
+
+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.
 
 ## Constructor
 
@@ -28,7 +30,7 @@ Common options:
 | `schema` | Required for typed model clients. |
 | `apiKey` | Bearer credential for trusted server runtimes. Defaults to `ABLO_API_KEY` when available. |
 | `baseURL` | Override the hosted sync endpoint for staging or private deployments. |
-| `persistence` | `volatile` by default. Use `indexeddb` for browser durable cache and offline queueing. |
+| `persistence` | `volatile` by default. Use `indexeddb` for a durable browser cache that survives reloads. |
 | `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. |
@@ -45,30 +47,33 @@ Each schema model becomes a typed model:
 ```ts
 await ablo.ready();
 
-const [report] = await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
-const local = ablo.weatherReports.retrieve('report_stockholm');
+const report = await ablo.weatherReports.retrieve('report_stockholm');
+const local = ablo.weatherReports.get('report_stockholm');
 
 await ablo.weatherReports.create({ location: 'Stockholm', status: 'pending' });
 await ablo.weatherReports.update('report_stockholm', { status: 'ready' }, { wait: 'confirmed' });
 await ablo.weatherReports.delete('report_stockholm', { wait: 'confirmed' });
 ```
 
-`load` is async hydration from local store and server. `retrieve`, `list`, and
-`count` are synchronous local reads after data is loaded.
+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
+no `await`, and stay reactive in render. Use the async pair to load, the sync trio
+to read.
 
-`list` accepts the same practical read options the React selector path uses:
-`where`, `filter`, `orderBy`, `limit`, `offset`, and `scope`. Scope defaults to
-`'live'`; pass `'archived'` or `'all'` when you intentionally want non-live
-rows.
+`getAll` 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.
 
 ## Multiplayer Behavior
 
-Multiplayer works when every participant uses the same model client path. A
-human Server Action, a browser view, and an agent worker can all use
-`ablo.weatherReports`:
+Two writers both try to mark `report_stockholm` ready at the same time. To stop
+the second write from silently overwriting the first, every participant goes
+through the same model client path. A human Server Action, a browser view, and an
+agent worker can all use `ablo.weatherReports`:
 
 ```ts
-const [report] = await ablo.weatherReports.load({ where: { id } });
+const report = await ablo.weatherReports.retrieve(id);
 const snap = ablo.snapshot({ weatherReports: id });
 
 await ablo.weatherReports.update(id, patch, {
@@ -78,9 +83,10 @@ await ablo.weatherReports.update(id, patch, {
 });
 ```
 
-The confirmed write fans out over realtime subscriptions. React clients that use
-`useAblo((ablo) => ablo.weatherReports.retrieve(id))` receive the new row, and selectors
-such as `useAblo((ablo) => ablo.weatherReports.claimState(id))`
+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
+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.
 
@@ -113,8 +119,13 @@ await ablo.weatherReports.update(
 
 ## Claimed Behavior
 
+If your update involves a slow step — an API call, an LLM round-trip — and someone
+else might write the same record meanwhile, claiming the record stops you from
+overwriting their change. Check who holds the record with `claim.state(id)`, then
+take it with `claim(id, work)`:
+
 ```ts
-const active = ablo.weatherReports.claimState('report_stockholm');
+const active = ablo.weatherReports.claim.state('report_stockholm');
 
 if (active) {
   return { status: 'claimed', active };
@@ -125,14 +136,17 @@ await ablo.weatherReports.claim('report_stockholm', async (report) => {
 });
 ```
 
-Reads never silently block. For schema model calls, use `claimState(id)` to observe
-current work and `claim(id, work)` to serialize a write across a slow step:
+`claim.state(id)` returns the current holder (or nothing) without ever blocking.
+When you call `claim(id, work)`, the SDK queues other claimers behind you, re-reads
+the latest row, then runs your `work` — so you can't overwrite a change you didn't
+see. Options on the wait:
 
 - default `claim` waits in the fair queue and re-reads before invoking `work`;
 - `{ wait: false }` rejects with `AbloClaimedError` instead of queuing;
 - `{ maxQueueDepth }` rejects if the wait line is already too deep.
 
-Schema clients use the realtime stream for waits.
+While waiting, schema clients learn when the claim clears from the live claim
+stream, so they never poll.
 
 ## Errors
 

package/docs/coordination.md

@@ -5,28 +5,68 @@ other. Most writes need none of this — `ablo.<model>.update(id, …)` is optim
 and the server rejects it if the row moved. Reach for `claim` only when you'll
 **hold a row across a slow gap** (read → LLM call → write).
 
-Claims are **fair**: on contention a second claimer joins a **server-side FIFO
-queue** and blocks until promoted to the head of the line — it does not fail and
-does not poll. Reads are open by default; reading a claimed row is allowed unless
-the caller explicitly asks for claimed gating. A claim carries a TTL so a crashed
-holder is auto-released and the queue advances.
+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. The wait is a **server-side FIFO queue**: a second claimer blocks
+until promoted to the head of the line — it does not fail and does not poll.
+Reads stay open: reading a claimed row is allowed unless the caller explicitly
+asks for claimed gating. A claim carries a TTL so a crashed holder is
+auto-released and the queue advances.
+
+This reference opens with [the model](#the-model--three-layers-one-decision) — the
+one answer to "how do two agents not clobber each other" — then covers the
+[claim state object](#the-claim-state-object), the SDK [methods](#methods)
+(`claim` · `claim.state` · `claim.queue` · `claim.release` · [writing under a
+claim](#writing-under-a-claim)), and the [errors](#errors) you can catch.
 
-This reference has three sections: the [claim state object](#the-claim-state-object),
-the SDK [methods](#methods) (`claim` · `claimState` · `queue` · `release` ·
-[writing under a claim](#writing-under-a-claim)), and the [errors](#errors) you
-can catch.
+---
+
+## The model — three layers, one decision
+
+Ablo has exactly **three** coordination layers. They are **not** three competing
+answers to the same question — they stack, and only one of them is a decision you
+make:
+
+| layer | kind | what it does | enforces? |
+|---|---|---|---|
+| **Presence** (`claim.state`, observers) | observation | Broadcasts who is working where, live. Renders cursors / "agent X is editing." | **No.** Advisory only — it never blocks or rejects a write. |
+| **Claim** (`claim`/`claim.queue`/`claim.release`) | pessimistic | Reserves a row for one participant. Foreign writers are rejected server-side; contenders join a fair FIFO queue. | **Yes**, between participants — mutual exclusion. |
+| **Stale-context** (`readAt` + `onStale`) | optimistic (LWW) | On commit, rejects a write whose snapshot is older than the row's latest delta. Last-writer-wins detection. | **Yes**, against time — lost-update detection. |
+
+**The one decision: do you hold the row across a slow gap (read → LLM call →
+write)?**
+
+- **No** (the common case — a single quick `update`): do nothing. `ablo.<model>.update`
+  is optimistically guarded by stale-context already; it rejects with
+  `AbloStaleContextError` if the row moved under you. This is the default and
+  needs no ceremony.
+- **Yes** (you'll reason for seconds while holding the row): `claim` it. The claim
+  excludes other participants for the duration, queues contenders fairly, and —
+  see below — your own writes under it stay stale-guarded too.
+
+**How they compose (what wins):** If you don't hold the row, claims win — a
+non-holder writing to a claimed row is rejected (`AbloClaimedError`) regardless of
+`readAt`. If you do hold it, your own writes are still stale-checked — a row that
+moved between your snapshot and your write still rejects with
+`AbloStaleContextError`. With no claim held, the stale check is the only
+protection, and it's automatic, which is why the no-claim path is safe by default.
+Presence (`claim.state`) never decides anything — read it to render, act on the
+errors. The two checks are independent: one rejects writes from people who don't
+hold the claim, the other rejects writes based on a stale snapshot, and the SDK
+adds the stale-check for you when you write under a claim, so you don't pass
+anything extra.
 
 ---
 
 ## The claim state object
 
 The claim state object is the live record that a participant is coordinating work on
-a model row. It's what `claimState()` returns and what observers render.
+a model row. It's what `claim.state()` returns and what observers render.
 
 | field | type | description |
 |---|---|---|
 | `id` | `string` | The claim id (distinct from the target row id). |
-| `status` | `ClaimStatus` | `'active' \| 'queued' \| 'committed' \| 'expired' \| 'canceled'`. `active` = the holder; `queued` = waiting in line behind it. |
+| `status` | `ClaimStatus` | `'active' \| 'queued' \| 'committed' \| 'expired' \| 'canceled'`. `active` = the holder; `queued` = waiting in line behind it. The other three are terminal states you only see on a claim you just finished — `committed` (released after a successful write), `expired` (TTL lapsed), `canceled` (released early). |
 | `target` | `EntityRef` | What is being coordinated (`{ model, id, field? }`). |
 | `action` | `string` | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. |
 | `heldBy` | `string` | Participant holding (or waiting on) it (e.g. `'agent:forecaster'`). |
@@ -36,7 +76,6 @@ a model row. It's what `claimState()` returns and what observers render.
 | `expiresAt` | `string` | Ms-epoch the server reclaims it if the holder goes **silent**. Renewed automatically while the holder's connection stays alive — a crash-cleanup floor, not a duration you size. |
 
 ```jsonc
-// A live claim state, as returned by claimState():
 {
   "id": "claim_8fJ2",
   "status": "active",
@@ -68,8 +107,8 @@ open by default. The claim acquires through the server's fair FIFO queue: if the
 target is free the lease is yours immediately, and if another participant holds
 it your claim **waits in line** and resolves only once it reaches the head —
 then re-reads so the claimed snapshot reflects what the previous holder
-committed. There's no client-side poll and no TOCTOU gap: the server orders
-contenders.
+committed. There's no polling and no race window — the server decides the order,
+so two claimers can't both think they won.
 
 **Parameters**
 
@@ -95,7 +134,6 @@ release hook for manual scopes.
 **Example**
 
 ```ts
-// Callback form — works on any toolchain:
 const forecast = await ablo.weatherReports.claim('report_stockholm', async (report) => {
   const weather = await weatherAgent.getWeather(report.location);
   await ablo.weatherReports.update(report.id, { forecast: weather });
@@ -108,14 +146,14 @@ held work should use the callback form above.
 
 ### Claim-gated reads
 
-`claimState(id)` always returns immediately. Model reads such as
-`ablo.<model>.retrieve(id)` are local reads and stay available while a claim is
+`claim.state(id)` always returns immediately. Model reads such as
+`ablo.<model>.get(id)` are local reads and stay available while a claim is
 held. Server/model reads can choose a claimed policy:
 
 ```ts
 await ablo.model('weatherReports').retrieve('report_stockholm', {
-  ifClaimed: 'wait',       // wait until the active claim clears
-  claimedTimeout: 30_000,  // maximum wait
+  ifClaimed: 'wait',
+  claimedTimeout: 30_000,
 });
 ```
 
@@ -123,10 +161,10 @@ await ablo.model('weatherReports').retrieve('report_stockholm', {
 - `ifClaimed: 'wait'` waits for the active claim to clear before reading.
 - `ifClaimed: 'fail'` throws `AbloClaimedError` if the row is claimed.
 
-### `claimState`
+### `claim.state`
 
 ```ts
-ablo.<model>.claimState(id)
+ablo.<model>.claim.state(id)
 ```
 
 Read who's currently working on a row, for observers and UI. Synchronous and
@@ -144,12 +182,13 @@ is free.
 **Example**
 
 ```ts
-const who = ablo.weatherReports.claimState('report_stockholm');
-if (who) console.log(`${who.heldBy} is ${who.action}`); // 'agent:forecaster is editing'
+const who = ablo.weatherReports.claim.state('report_stockholm');
+if (who) console.log(`${who.heldBy} is ${who.action}`);
 ```
 
+Returns the active claim state when the row is held, or `null` when it's free:
+
 ```jsonc
-// Resolved value when the row is held:
 {
   "id": "claim_8fJ2",
   "status": "active",
@@ -159,20 +198,19 @@ if (who) console.log(`${who.heldBy} is ${who.action}`); // 'agent:forecaster is
   "participantKind": "agent",
   "expiresAt": "1748160030000"
 }
-// → null when free.
 ```
 
-### `queue`
+### `claim.queue`
 
 ```ts
-ablo.<model>.queue(id)
+ablo.<model>.claim.queue(id)
 ```
 
 Read the **wait line** behind a row — the FIFO of claims queued behind the
-current holder, in promotion order. Like `claimState`, it's synchronous and
+current holder, in promotion order. Like `claim.state`, it's synchronous and
 reactive (it reads the local coordination snapshot, kept current by the server's
-queue-mutation frames), and reading never blocks. Where `claimState` answers "who
-holds it," `queue` answers "who's lined up next" — render "3rd in line", or
+queue-mutation frames), and reading never blocks. Where `claim.state` answers "who
+holds it," `claim.queue` answers "who's lined up next" — render "3rd in line", or
 decide the wait isn't worth it.
 
 **Parameters**
@@ -188,15 +226,15 @@ the active holder; `[]` when no one is waiting.
 **Example**
 
 ```ts
-const { data: waiting } = ablo.weatherReports.queue('report_stockholm');
+const { data: waiting } = ablo.weatherReports.claim.queue('report_stockholm');
 console.log(`${waiting.length} ahead of you`);
-console.log(waiting.map((i) => i.heldBy)); // ['agent:b', 'agent:c']
+console.log(waiting.map((i) => i.heldBy));
 ```
 
-### `release`
+### `claim.release`
 
 ```ts
-ablo.<model>.release(id): Promise<void>
+ablo.<model>.claim.release(id): Promise<void>
 ```
 
 Release a claim you hold. Usually **implicit** — the callback returning releases
@@ -222,13 +260,13 @@ try {
   if (!ok) return; // abandon, no write
   await ablo.weatherReports.update(report.id, { status: 'ready' });
 } finally {
-  await ablo.weatherReports.release(report.id);
+  await ablo.weatherReports.claim.release(report.id);
 }
 ```
 
 ### Writing under a claim
 
-There is no separate "write" method on a claim — use the normal flat
+There is no separate "write" method on a claim — use the normal
 `ablo.<model>.update(id, data)`. While you hold a claim on `id`, that `update` is
 automatically stale-guarded against the snapshot the claim took (`readAt` =
 snapshot watermark, `onStale: 'reject'`) and attributed to the claim's lease, so