@abloatai/ablo 0.30.2 → 0.32.0

package/docs/audit.md

@@ -2,33 +2,40 @@
 
 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.
+rows are chained with a keyed hash (HMAC-SHA256) so you can later prove the
+history wasn't altered. You can filter it, page through it, and export it.
 
 ## Row shape
 
+Each stored row carries both the attribution fields — who acted, on whose behalf,
+with which key — and the chain columns that make the log tamper-evident:
+
 ```ts
 {
-  occurredAt:           '2026-05-14T14:22:01.034Z',
-  actorKind:            'user' | 'agent' | 'system',
-  actorId:              string,
-  onBehalfOfKind:       'user' | 'agent' | 'system' | null,
-  onBehalfOfId:         string | null,
-  capabilityId:         string | null,    // the API key/capability used for the write
-  capabilityLabel:      string | null,    // its human-readable name, for scanning the log
-  delegationChainRoot:  string | null,    // always points at a human
-  actionType:           string,           // e.g. 'weatherReport.update'
-  modelName:            string | null,    // e.g. 'claude-opus-4-7'
-  diffSummary:          unknown,
-  // tamper-evident
-  chainSeq:             number,
-  prevHash:             string,
-  rowHash:              string,
+  id:                        string,
+  occurredAt:                '2026-05-14T14:22:01.034Z',
+  actorKind:                 'user' | 'agent' | 'system',
+  actorId:                   string,
+  onBehalfOfKind:            'user' | 'agent' | 'system' | null,
+  onBehalfOfId:              string | null,
+  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'
+  confirmationState:         'auto' | 'previewed' | 'approved' | 'required_human_approval' | 'auto_historical',
+  diffSummary:               unknown,
+  // chain columns — carried on every stored row, checked by verify (below)
+  chainSeq:                  number,
+  prevHash:                  string,
+  rowHash:                   string,
 }
 ```
 
+`confirmationState` records whether an agent's write ran on its own (`auto`), was
+shown first (`previewed`), was signed off (`approved`), or is still waiting on a
+person (`required_human_approval`) — it's also a filter on the list endpoint.
+
 ## Delegation chain
 
 Every action traces back to a human. Even when an agent makes the change,
@@ -53,9 +60,14 @@ or, on tamper:
 
 ```json
 { "ok": false, "brokenAtSeq": 8419, "reason": "hash_mismatch",
-  "expectedHash": "sha256:…", "foundHash": "sha256:…" }
+  "expectedHash": "a3f1c9…", "foundHash": "b7e04d…" }
 ```
 
+Hashes come back as plain hex. `expectedHash`/`foundHash` accompany a
+`hash_mismatch` or `prev_hash_mismatch`; the other reasons (`sequence_gap`,
+`missing_root`, `no_rows`) stand on their own. Recomputing a row's hash needs the
+org's HMAC key, so verification runs where that secret is available.
+
 ## Filter and paginate
 
 The dashboard at `/[orgSlug]/audit` is the UI for this. The same filters
@@ -82,6 +94,6 @@ JSON `GET` endpoint above using `nextCursor`.
 ## Compliance posture
 
 The [audit log landing page](/audit-log) is the marketing-side description.
-The verifier's hash algorithm and chain semantics live in the
-`@ablo/audit-chain` package — embeddable if you need to verify chains in a
-detached service.
+The HMAC-SHA256 chain algorithm and its semantics live in the
+`@ablo/audit-chain` package — the reference implementation, embeddable if you
+need to verify chains in a detached service (given the org's HMAC key).

package/docs/client-behavior.md

@@ -39,8 +39,9 @@ Common options:
 | `dangerouslyAllowBrowser` | Required before sending an API key from browser code. Prefer a server route instead. |
 
 Your database connects out of band — through logical replication (`npx ablo
-connect`) or a signed [Data Source](./data-sources.md) endpoint — so the client
-holds only `apiKey`, never a connection string. See
+connect`), or the signed [Data Source](./data-sources.md) endpoint as the
+fallback for databases that can't grant replication — so the client holds only
+`apiKey`, never a connection string. See
 [Connect Your Database](./data-sources.md) for the full setup.
 
 ## Model Methods
@@ -95,8 +96,10 @@ 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.
 
-If an app writes directly to its database, Ablo cannot coordinate that write
-until the app reports it through Data Source events.
+Writes flow through Ablo's commit chokepoint and land in your database, so every
+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
 

package/docs/concurrency-convention.md

@@ -161,7 +161,7 @@ and `currentValues` is empty (re-read the group).
 
 What the convention **guarantees**, and where it **stops**:
 
-1. **Engine surfaces, actor decides.** For `flag`/`merge` the engine never
+1. **Engine surfaces, actor decides.** Under `notify` the engine never
    repairs, merges, or re-plans. It reports `currentValues` and the actor (agent
    or human) owns the resolution. The engine does not distinguish them — it is
    actor-neutral by design.
@@ -179,7 +179,7 @@ What the convention **guarantees**, and where it **stops**:
    shared database, which are inherently reversible (prior value in
    `sync_deltas`). **Irreversible external side-effects** (emails, payments,
    third-party calls) are *out of scope* — the engine cannot hold or undo them,
-   so they must not be gated by `flag`/`merge`.
+   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`
@@ -202,7 +202,7 @@ What the convention **guarantees**, and where it **stops**:
 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 `flag` (philosophy-aligned: surface, don't force) instead of
+  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

package/docs/data-sources.md

@@ -1,31 +1,49 @@
 # Connect Your Database
 
-**Connect your database = Postgres logical replication.** That is the one way.
-Ablo reads your write-ahead log (WAL) and **never runs DDL, never owns your
-schema, and never migrates it**. Your application keeps writing to its own
-Postgres through its own backend, exactly as it does today; Ablo only tails the
-changes and fans the confirmed rows out to every connected human and agent. This
-is the same model ElectricSQL, PowerSync, and Zero use — a publication plus a
-replication slot. Ablo consumes the logical-replication stream; your application
-continues to own the write path.
+You write through Ablo, and Ablo writes to your Postgres. A call to
+`ablo.<model>.create / update / delete` enters Ablo's commit chokepoint — where
+claims, ordering, and idempotency are enforced — and Ablo applies the change to
+your database through a scoped role. Your rows live in your database, which stays
+the system of record. Ablo reads your write-ahead log (WAL) to confirm each write
+landed and to keep every connected human and agent current.
+
+Ablo writes your **rows**; it never touches your **schema**. It runs no DDL and no
+migrations — your migration tool stays in charge of the shape of your database.
+Ablo only writes rows into tables you already have, through a role scoped to
+exactly that.
+
+> **Just trying Ablo?** You don't need a database to start. Pass an `apiKey` only,
+> and Ablo keeps your rows in its own log so you can build the whole app today —
+> like Stripe test mode. For a sandbox you can throw away, point Ablo at a separate
+> or local Postgres. Connect your production database (below) when you're ready for
+> it to be the system of record.
+
+Connecting sets up two capabilities on your Postgres: **logical replication**, so
+Ablo can read and confirm, and a **scoped DML role**, so Ablo can write. `ablo
+connect` prints the exact SQL. `ablo connect apply` runs it for you.
+
+## Connect in one command
 
-> **Just trying Ablo?** You don't need a database at all to start. The hosted
-> **sandbox** can host rows in Ablo's test plane — pass an `apiKey` only and omit
-> any database setup, like Stripe test mode. Connect your Postgres with logical
-> replication (below) when you're ready for it to be the system of record.
+```bash
+npx ablo connect apply --url postgres://admin:...@host:5432/db
+```
 
-Your database stays the system of record. Ablo never becomes a second source of
-truth and never takes over operating your Postgres.
+Pass an admin connection string with `--url` and it creates the publication, the
+two scoped roles, and the grants, turns on logical decoding where it can, registers
+both scoped roles with Ablo, and proves the setup by reconnecting and reading back.
+The admin credential is used on this machine only and never persisted — nothing is
+written to your `.env`, which keeps holding only `ABLO_API_KEY`. Pass `--show-sql`
+to see every statement first, or drop `--apply` to print the SQL and run it
+yourself. Rotate the scoped passwords any time with `ablo connect rotate`.
 
-## The five steps (mirrors Zero's install flow)
+The rest of this page is what that command sets up, step by step, for when you want
+to run it by hand or review exactly what changes.
 
-You run the setup once against your own database, then point Ablo at it. The CLI
-prints the exact SQL and validates it for you — you never hand-craft replication
-internals.
+## The setup, step by step
 
 ### 1. Enable logical decoding
 
-Turn on logical WAL so Ablo can decode row changes:
+Turn on logical WAL so Ablo can decode row changes and confirm writes:
 
 ```sql
 ALTER SYSTEM SET wal_level = 'logical';
@@ -34,21 +52,20 @@ ALTER SYSTEM SET wal_level = 'logical';
 `wal_level` is **not reloadable** — you must **restart Postgres** for it to take
 effect. On Amazon RDS / Aurora you can't `ALTER SYSTEM`; set
 `rds.logical_replication = 1` in the instance's parameter group instead, then
-reboot.
+reboot. (`ablo connect apply` attempts this for you and, where a managed
+provider refuses, hands you the one remaining step.)
 
-### 2. Run `ablo connect` to get the publication / slot / role SQL
+### 2. Run `ablo connect` for the publication and roles
 
 ```bash
 npx ablo connect
 ```
 
-`ablo connect` prints the exact, copy-pasteable setup SQL for **your** Postgres
-and nothing else — it does not ask for a connection-string flavor, an adapter, or
-a driver, because logical replication is how you connect. Run the printed SQL
-against your database (as a superuser / the DB owner). It does three things:
+`ablo connect` prints the exact, copy-pasteable setup SQL for **your** Postgres.
+Run it against your database as a superuser or the DB owner. It creates:
 
-- **A publication** naming the tables Ablo should read (`ablo_publication`, the
-  single canonical name the runtime subscribes to):
+- **A publication** naming the tables Ablo reads and confirms against
+  (`ablo_publication`, the single canonical name the runtime subscribes to):
 
   ```sql
   CREATE PUBLICATION "ablo_publication" FOR ALL TABLES;
@@ -56,53 +73,79 @@ against your database (as a superuser / the DB owner). It does three things:
 
   Scope it to a subset with `npx ablo connect --tables a,b,c`.
 
-- **A least-privilege replication role** — it can stream replication and `SELECT`,
-  nothing more. You choose the password; it never passes through Ablo's CLI or
-  servers:
+- **A replication role** — it streams the WAL and `SELECT`s, nothing more. This is
+  the role Ablo reads and confirms through. You choose the password; it never
+  passes through Ablo's CLI or servers:
 
   ```sql
   CREATE ROLE "ablo_replicator" WITH REPLICATION LOGIN PASSWORD '<password>';
   GRANT SELECT ON ALL TABLES IN SCHEMA public TO "ablo_replicator";
-  ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO "ablo_replicator";
   ```
 
-  Rename it with `--role <name>`. On Amazon RDS the `REPLICATION` attribute is
-  granted, not set directly: `GRANT rds_replication TO "ablo_replicator";`.
+  On Amazon RDS the `REPLICATION` attribute is granted, not set directly:
+  `GRANT rds_replication TO "ablo_replicator";`.
+
+- **A scoped writer role** — the role Ablo writes your rows through. It gets row
+  DML (`SELECT, INSERT, UPDATE, DELETE`) and the sync ledger, and nothing else: no
+  `REPLICATION`, no schema `CREATE`, `NOSUPERUSER NOBYPASSRLS`, row security on. It
+  can change rows in your tables; it cannot change your database:
+
+  ```sql
+  CREATE ROLE "ablo_writer" WITH LOGIN PASSWORD '<write-password>'
+    NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE NOREPLICATION NOINHERIT;
+  GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO "ablo_writer";
+  ```
+
+  Rename either role with `--role <name>` / `--write-role <name>`.
 
 The **replication slot** is created and owned by Ablo's runtime when it first
-subscribes with this role — you don't pre-create it. The publication and the role
-are the only objects the recipe asks you to create.
+subscribes — you don't pre-create it.
 
-### 3. Validate with `ablo connect --check`
+### 3. Register the database with Ablo
 
-Put the replication role's connection string in `DATABASE_URL`, then verify the
-database is replication-ready:
+`ablo connect apply` already did this. If you ran the SQL by hand instead, hand
+Ablo both scoped connection strings once — the replication role it reads and
+confirms through, and the writer role it lands your rows through. Set them just
+long enough to register:
 
 ```bash
-npx ablo connect --check
+export ABLO_REPLICATION_DATABASE_URL=...   # the replication role
+export ABLO_WRITE_DATABASE_URL=...         # the writer role
+npx ablo connect register
 ```
 
-This connects and checks the four invariants, printing a green checklist or the
-precise per-item fix:
+`--register` posts them to Ablo, which holds them encrypted and uses them to read
+and write your database. Ablo holds them from here, so you can drop both from your
+environment — your app keeps only `ABLO_API_KEY`. The role passwords are generated
+for you and never printed; rotate them any time with `ablo connect rotate`. After
+this, Ablo does all the connecting.
+
+### 4. Verify readiness with `ablo connect check`
+
+```bash
+npx ablo connect check
+```
+
+`--check` needs only `ABLO_API_KEY`. It asks Ablo to check the database it now
+holds, from the same infrastructure replication runs on, and prints a green
+checklist or the precise per-item fix:
 
 - `wal_level` is `logical`
 - the `ablo_publication` publication exists
-- the `DATABASE_URL` role has the `REPLICATION` attribute
+- the replication role has the `REPLICATION` attribute
 - every published table has a usable `REPLICA IDENTITY` (a primary key, or
   `REPLICA IDENTITY FULL`) so `UPDATE`/`DELETE` can replicate
+- the writer role is DML-ready — scoped, non-superuser, with the idempotency
+  ledger in place
 
-Re-run it until every item is green.
-
-### 4. Point Ablo at the database with the replication role
+Because Ablo checks from its own network, a database your own machine can't reach —
+IPv6-only, IP-allowlisted, behind a VPN — still verifies. Re-run it until every
+item is green.
 
-Give Ablo the connection string for the **replication role** you created — a
-`REPLICATION`-attributed role that streams the WAL and `SELECT`s, nothing more
-(not a read-only account; see the privilege note below). The same value `--check`
-validated:
+Your **app** holds only the API key — never a connection string:
 
 ```bash
 # .env — server runtime only, never the browser
-DATABASE_URL=postgres://ablo_replicator:<password>@host:5432/db?sslmode=require
 ABLO_API_KEY=sk_live_...
 ```
 
@@ -116,28 +159,33 @@ export const ablo = Ablo({
 });
 ```
 
-You define an Ablo schema with `defineSchema`, `model`, and Zod. The Ablo schema
-describes **only your synced, collaborative models** — the rows Ablo coordinates
-and fans out in realtime. It is *not* your whole-database schema and does *not*
-replace your `schema.prisma` (or your Drizzle schema). Your auth, billing, and
-any other tables stay in your own ORM schema, owned by your own migrations.
-`ablo check` reflects this — it reports tables you didn't declare as "ignored /
-owned by you," which is exactly right.
+The Ablo schema describes **only your synced, collaborative models** — the rows
+Ablo coordinates and fans out in realtime. It is *not* your whole-database schema
+and does *not* replace your `schema.prisma` (or Drizzle schema). Your auth,
+billing, and other tables stay in your own ORM schema, owned by your own
+migrations. `ablo check` reflects this — it reports tables you didn't declare as
+"ignored / owned by you," which is exactly right.
 
-### 5. Writes go through your own backend
+### 5. Write through `ablo.<model>`
 
-Your application writes to its Postgres the way it always has — its own ORM, its
-own backend, its own transactions. Ablo does not intercept or proxy those writes.
-It observes them on the WAL and fans the confirmed rows out to connected clients.
-The read, claim, and coordination surface (`ablo.<model>`) layers on top:
+Every change goes through Ablo. The write enters the commit chokepoint, Ablo
+applies it to your Postgres through the writer role, and the WAL echo confirms it
+landed:
 
 ```ts
+// Enters the chokepoint (claims, ordering, idempotency), lands in your Postgres.
+await ablo.weatherReports.update({ id: 'report_stockholm', data: { high: 21 } });
+
+// Block until your database has it and the WAL echo confirms.
+await ablo.weatherReports.update({ id: 'report_stockholm', data: { high: 21 }, wait: 'confirmed' });
+
+// Reads are live off the same stream.
 const report = ablo.weatherReports.get('report_stockholm');
-const active = ablo.weatherReports.claim.state({ id: 'report_stockholm' });
 ```
 
-For the typed read/claim/write surface itself, see
-[Quickstart](./quickstart.md) and [Schema Contract](./schema-contract.md).
+A commit is accepted the moment Ablo takes it (`queued`); it becomes `confirmed`
+once the row appears on your WAL. See [Guarantees](./guarantees.md) for what each
+state means and when to wait.
 
 ## What Ablo touches in your database — the honest footprint
 
@@ -145,9 +193,10 @@ This is the complete list. Nothing else.
 
 | Object | What it is | Owned by |
 |---|---|---|
-| `ablo_publication` | A Postgres publication naming the tables Ablo reads. | You create it (step 2). |
+| `ablo_publication` | A publication naming the tables Ablo reads and confirms against. | You create it (step 2). |
+| `ablo_replicator` role | A `REPLICATION` + `SELECT` role Ablo reads and confirms through. | You create it (step 2). |
+| `ablo_writer` role | A scoped DML role Ablo writes your rows through — row DML + ledger, nothing more. | You create it (step 2). |
 | Replication slot | A logical slot Ablo subscribes through to track its WAL position. | Ablo's runtime creates it on first connect. |
-| `ablo_replicator` role | A least-privilege `REPLICATION` + `SELECT` role. | You create it (step 2). |
 | `wal_level = logical` | A server setting that **requires a restart**. | You set it (step 1). |
 
 Operational reality you should know up front:
@@ -155,30 +204,26 @@ Operational reality you should know up front:
 - **`wal_level = logical` needs a restart.** It is a one-time, server-wide change
   and is not reloadable.
 - **A replication slot retains WAL.** While Ablo is connected, the slot holds the
-  WAL it hasn't yet acknowledged. If Ablo is disconnected for a long time, that
-  WAL accumulates and consumes disk. **Ablo monitors slot lag and WAL retention**
-  and surfaces it so you're never surprised by disk pressure; an abandoned slot is
-  dropped rather than left to grow unbounded.
-- **The role's privilege footprint is narrow and precise — not a "read-only"
-  account.** It carries the `REPLICATION` attribute, which lets it stream the WAL
-  and `SELECT`; it cannot `INSERT`/`UPDATE`/`DELETE`, run DDL, or own objects, and
-  the recipe never grants it more. (For a security review, state it that way — a
-  logical-replication role is a real privilege, just a tightly-scoped one — rather
-  than calling it "read-only", which a reviewer will correctly push back on.)
-
-What Ablo explicitly does **not** do:
-
-- It **never runs DDL** against your database.
-- It **never owns or migrates your schema** — your migration tool stays in charge.
-- It **never writes your rows** — writes are yours, through your backend.
+  WAL it hasn't yet acknowledged. If Ablo is disconnected for a long time, that WAL
+  accumulates and consumes disk. **Ablo monitors slot lag and WAL retention** and
+  surfaces it, so disk pressure never surprises you; an abandoned slot is dropped
+  rather than left to grow unbounded.
+- **The writer role changes rows, not your database.** It carries row DML plus the
+  sync ledger and nothing more — no `REPLICATION`, no DDL, no object ownership, and
+  it runs with row security on and `NOBYPASSRLS`. It is a real, tightly-scoped
+  privilege — describe it that way in a security review.
+
+Ablo runs **no DDL** and **owns no schema**: your migration tool stays in charge of
+the shape of your database, and Ablo writes only rows, only into tables you already
+have.
 
 ## What Ablo stores on its side
 
 Your schema *definition* (model names, fields, types — pushed with `ablo push`),
 your hashed API keys, a safe projection of the connection registration (host,
 database, schema — the connection string itself is sealed and never echoed back),
-the replication slot position, and the commit log that drives sync. Never your
-rows.
+the replication slot position, and the ordered transaction log that drives sync and
+coordination. Your rows live in your database.
 
 > **Postgres replication status: Preview.** Registration, readiness checks, and
 > the server replication fleet are implemented and boot-wired. Preview describes
@@ -186,6 +231,17 @@ rows.
 > [internal/postgres-replication.md](./internal/postgres-replication.md) for the
 > architecture and operational invariants.
 
+## When your database can't grant replication
+
+Some managed databases won't grant a `REPLICATION` role. For those, Ablo connects
+through a **signed Data Source endpoint** instead: you expose one signed HTTP route
+built from your ORM (`prismaDataSource` / `drizzleDataSource`, with `ablo_outbox` /
+`ablo_idempotency` bookkeeping), and Ablo writes and confirms through it — same
+`ablo.<model>` surface, same commit chokepoint, same `queued` → `confirmed`
+lifecycle. It needs no replication setup, which is exactly why it's the fallback:
+reach for it only when logical replication isn't available, and prefer `ablo
+connect` everywhere else.
+
 ## Next steps
 
 - [Quickstart](./quickstart.md) — connect and write through `ablo.<model>`.
@@ -194,20 +250,3 @@ rows.
 - [Guarantees](./guarantees.md) — what confirmed writes and stale checks mean.
 - [Integration Guide](./integration-guide.md) — the full app, React, multiplayer,
   and agent path.
-
----
-
-## Legacy / not recommended
-
-> **Use logical replication instead** (top of this page). The shapes below
-> predate the single connect path. They are documented only so existing
-> integrations can be read and understood — do **not** reach for them when
-> connecting a new database. They are the seams that caused painful onboarding,
-> and `ablo connect` exists precisely to replace them.
-
-This older shape connected Ablo to a database by exposing a **signed Data Source
-endpoint** built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`,
-with `ablo_outbox` / `ablo_idempotency` bookkeeping and a reverse-channel
-connector for VPCs). It required Ablo to proxy every write, and has been superseded
-by logical replication, where Ablo only reads your WAL. If you are maintaining one
-of these integrations, migrate it to `ablo connect` at the next opportunity.

package/docs/examples/agent-human.md

@@ -50,11 +50,11 @@ export async function markReady(reportId: string) {
     // queue: false → don't queue behind a current holder. If a human already
     // holds the row, claim rejects with AbloClaimedError (caught below), so the
     // agent yields instead of waiting. Omit it, or pass queue: true, to queue
-    // behind them. reason → the label observers see while we work.
+    // behind them. description → the label observers see while we work.
     await using claim = await ablo.weatherReports.claim({
       id: reportId,
       queue: false,
-      reason: 'marking_ready',
+      description: 'marking_ready',
     });
     const claimed = claim.data;
 

package/docs/examples/ai-sdk-tool.md

@@ -43,7 +43,7 @@ const updateReport = tool({
     // The claim is released automatically when it goes out of scope.
     await using claim = await ablo.weatherReports.claim({
       id: reportId,
-      reason: 'editing',
+      description: 'editing',
       ttl: '2m',
     });
     const claimed = claim.data;

package/docs/examples/nextjs.md

@@ -58,7 +58,7 @@ export async function markReady(id: string) {
   await using claim = await ablo.weatherReports.claim({
     id,
     queue: false,
-    reason: 'marking_ready',
+    description: 'marking_ready',
   });
   const claimed = claim.data;
 

package/docs/examples/server-agent.md

@@ -39,7 +39,7 @@ export async function completeReport(reportId: string) {
   await using claim = await ablo.weatherReports.claim({
     id: reportId,
     queue: false,
-    reason: 'completing',
+    description: 'completing',
   });
   const claimed = claim.data;
 
@@ -62,7 +62,7 @@ The two options on the claim:
 
 - `queue: false` — skip this record if another claim is already in progress,
   rather than queueing behind it. (The default queues.)
-- `reason: 'completing'` — a human-readable label for what your worker is doing,
+- `description: 'completing'` — a human-readable label for what your worker is doing,
   visible to anyone reading `claim.state({ id })`.
 
 Because the worker uses the same schema and `claim()` as the UI, its writes sync