@abloatai/ablo 0.34.1 → 0.36.0

package/docs/data-sources.md

@@ -1,5 +1,7 @@
 # Connect Your Database
 
+> Keep the rows in your own Postgres while Ablo coordinates and confirms every write.
+
 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
@@ -73,7 +75,7 @@ Run it against your database as a superuser or the DB owner. It creates:
 
   Scope it to a subset with `npx ablo connect --tables a,b,c`.
 
-- **A replication role** — it streams the WAL and `SELECT`s, nothing more. This is
+- **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:
 
@@ -85,7 +87,7 @@ Run it against your database as a superuser or the DB owner. It creates:
   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
+- **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:
@@ -180,14 +182,14 @@ await ablo.weatherReports.update({ id: 'report_stockholm', data: { high: 21 } })
 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 report = ablo.weatherReports.local.retrieve('report_stockholm');
 ```
 
 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
+## What Ablo touches in your database: the honest footprint
 
 This is the complete list. Nothing else.
 
@@ -195,7 +197,7 @@ This is the complete list. Nothing else.
 |---|---|---|
 | `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). |
+| `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. |
 | `wal_level = logical` | A server setting that **requires a restart**. | You set it (step 1). |
 

package/docs/debugging.md

@@ -1,6 +1,8 @@
 # Debugging & Logs
 
-By default the SDK is quiet — it logs only warnings and errors. When you're building a human + agent flow and want to *see* the coordination happen (who claimed what, who's waiting in line, who got preempted), turn on Ablo's diagnostic logging. Every line is prefixed `[Ablo]` so it's obvious which output is ours in a console full of other tools.
+> Watch claims, queueing, and grants as they happen while you build.
+
+By default the SDK is quiet — it logs only warnings and errors. When you're building a multi-agent flow and want to *see* the coordination happen (who claimed what, who's waiting in line, who got preempted), turn on Ablo's diagnostic logging. Every line is prefixed `[Ablo]` so it's obvious which output is ours in a console full of other tools.
 
 ## Turn it on
 
@@ -11,6 +13,17 @@ import { schema } from './ablo/schema';
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, debug: true });
 ```
 
+## CLI environment and target
+
+The CLI checks an explicit credential in this order: exported `ABLO_API_KEY`,
+`.env.local`, `.env`, then the key saved by `ablo login`. An exported value wins
+over project files. If a stale shell export (for example `OPENAI_API_KEY`) is
+shadowing a value in `.env.local`, restart the shell or unset the stale variable.
+
+When a command appears to use the wrong plane or project, run `ablo status`.
+It reports the credential source and, when reachable, the server-confirmed
+project and environment; that confirmed target is authoritative.
+
 `debug: true` is the simple switch. For finer control use `logLevel`, or set it without touching code via the `ABLO_LOG_LEVEL` environment variable.
 
 ```ts
@@ -29,17 +42,17 @@ ABLO_LOG_LEVEL=debug npm run dev               # same, from the environment
 |---|---|
 | `silent` | nothing |
 | `error` | failures only |
-| `warn` | **default** — warnings + errors |
+| `warn` | **default**: warnings + errors |
 | `info` | the above + the **coordination trace** (claims, grants, queueing) + connection state |
-| `debug` | the above + internal lifecycle (per-model registration, store hydration) — the full firehose |
+| `debug` | the above + internal lifecycle (per-model registration, store hydration): the full firehose |
 
 Precedence: an explicit `logLevel` wins, then `debug: true` (⇒ `debug`), then `ABLO_LOG_LEVEL`, then the `warn` default. `debug: false` (or omitting it) just means "don't raise the level."
 
 > For watching coordination, **`logLevel: 'info'` is the sweet spot** — you get the claim trace without the per-model registration chatter that `debug` adds.
 
-## What you'll see — the coordination trace
+## What you'll see: the coordination trace
 
-These lines (all at `info`) let you watch the human + agent handover you built:
+These lines (all at `info`) let you watch the handover you built:
 
 ```
 [Ablo] claim: requesting documents:doc_42 for "editing" (will queue if contended)
@@ -52,16 +65,16 @@ These lines (all at `info`) let you watch the human + agent handover you built:
 
 Read it as the lifecycle of one claim:
 
-- **`requesting`** — your code (or an agent) called `ablo.<model>.claim(...)`. `(will queue if contended)` appears when you passed `{ queue: true }`.
-- **`queued … position N of M`** — the row was held, so you're waiting in the FIFO line. This is the "an agent is waiting behind a claim" moment; it re-logs only when your position changes, so you can watch it advance.
-- **`granted … your turn`** — you reached the head of the line; the lease is now yours and the row may have changed while you waited.
-- **`rejected … held by <who>`** — your claim was refused because someone else holds it (and the model's policy didn't let you in).
-- **`lost`** — you held the lease and it was taken (preempted by a higher-priority writer, or it expired).
-- **`released`** — you (or `await using`'s scope exit) gave the lease back.
+- **`requesting`:** your code (or an agent) called `ablo.<model>.claim(...)`. `(will queue if contended)` appears when you passed `{ queue: true }`.
+- **`queued … position N of M`:** the row was held, so you're waiting in the FIFO line. This is the "an agent is waiting behind a claim" moment; it re-logs only when your position changes, so you can watch it advance.
+- **`granted … your turn`:** you reached the head of the line; the lease is now yours and the row may have changed while you waited.
+- **`rejected … held by <who>`:** your claim was refused because someone else holds it (and the model's policy didn't let you in).
+- **`lost`:** you held the lease and it was taken (preempted by a higher-priority writer, or it expired).
+- **`released`:** you (or `await using`'s scope exit) gave the lease back.
 
 ## Where the logs run
 
-The coordination trace and the proactive credential refresh run **in the browser** (and any client that holds a live socket) — that's where the human + agent activity is. Server-side code that mints credentials or does one-shot reads won't emit the trace; it has no live session to narrate.
+The coordination trace and the proactive credential refresh run **in the browser** (and any client that holds a live socket) — that's where the live coordination activity is. Server-side code that mints credentials or does one-shot reads won't emit the trace; it has no live session to narrate.
 
 ## Bring your own logger
 
@@ -80,7 +93,7 @@ Ablo({
 });
 ```
 
-## Read the coordination in code — the activity log
+## Read the coordination in code: the activity log
 
 The console trace above is for *you*, at a terminal. To put the same activity **inside your app** — an activity feed, a "who's editing" badge, a Sentry breadcrumb trail — read it programmatically. Same events, three layers; pick by audience:
 
@@ -112,7 +125,7 @@ interface ConflictEvent {
 
 `phase` is past-tense — the state the claim just entered — and maps one-to-one to what arrives on the wire.
 
-### Collect them — `ClaimLog`
+### Collect them: `ClaimLog`
 
 `ClaimLog` records both into an ordered list. Hand it to `observability`, then read it back:
 
@@ -134,7 +147,7 @@ It's also the simplest way to **assert** coordination in a test — no log scrap
 expect(log.collisions()).toHaveLength(0);   // no one stepped on anyone
 ```
 
-### Show it on a page — reactive
+### Show it on a page: reactive
 
 `ClaimLog.onChange` fires on every event and returns an unsubscribe — the exact shape `useSyncExternalStore` wants, so a live feed is a few lines:
 
@@ -183,6 +196,17 @@ const ablo = Ablo({
 });
 ```
 
+`ClaimLog` implements the full `SyncObservabilityProvider`, so it drops straight
+into the `observability` slot. The surface exports `ClaimLog`, `formatClaim`,
+`formatConflict`, and `noopObservability`, plus the types `ClaimEvent`,
+`ConflictEvent`, `ClaimLogEntry`, and `SyncObservabilityProvider`.
+
+> **Both transports, from 0.21.0.** Observability fires on the WebSocket and on
+> the stateless HTTP transport (claim acquired, plus coordination-conflict
+> rejections on every write door). Before 0.21.0 only WebSocket emitted, so a
+> `ClaimLog` on an HTTP client, such as a headless server-agent eval, stayed
+> silent even though coordination still worked.
+
 ## Errors
 
 Ablo's thrown errors are typed and self-describing — `String(err)` (or logging it) yields one clean line, never a stack dump:

package/docs/deployment.md

@@ -0,0 +1,267 @@
+# Deployment
+
+> What production takes: a database Ablo can reach, a key minted for the plane you mean, and a schema push in the deploy.
+
+One command answers the question this page exists for — would a write succeed
+right now, and if not, why:
+
+```bash
+ABLO_API_KEY=sk_live_… npx ablo status
+```
+
+```text
+  ablo status
+
+  key     sk_live_51H8… (ABLO_API_KEY env — overrides stored)
+  mode    production
+  org     org_3nKq…
+  project checkout (prj_7Yb2…)
+  acts on production
+  ○ sandbox     sk_test_9fJd… · expires in 71d
+  ● production  — no key
+  push    production with sk_live_51H8… (env)
+  api     https://api.abloatai.com  reachable
+  data    ✓ database connected to this plane (direct)
+  schema  4 models pushed (rev 12) hash 3f9a2c81 @ 2026-07-18
+          • orders         typename=orders
+          • lineItems      typename=lineItems
+          • fulfilments    typename=fulfilments
+          • reviews        typename=reviews
+
+  ✓ ready — a write should succeed
+```
+
+`status` asks the routing authority rather than sampling a read, because reads
+resolve while writes are held — a plane with no database connected serves every
+read and refuses every write. The verdict at the bottom is the whole page in one
+line, and `--json` puts the same conclusion in a `blockers` array you can gate a
+deploy on.
+
+## The three ingredients
+
+There is no Ablo service for you to deploy. Ablo is hosted, your rows live in
+your own Postgres, and your app runs where it already runs — so a deployment is
+three pieces pointed at the same plane.
+
+| Ingredient | Who runs it | What "deploying" means for it |
+|---|---|---|
+| **Your Postgres** | You (or your provider) | Registering it against your production plane, once, with a production key. |
+| **Ablo** | Hosted at `api.abloatai.com` | Nothing to run. You choose a project, a plane, and the keys that reach them. |
+| **Your app and agents** | You | Holding the right credential for the runtime, and pushing the schema in the deploy. |
+
+Everything below is those three in order.
+
+### Planes: what a deployment targets
+
+A **plane** is the isolation unit a credential acts on. `production` is the root
+plane; every sandbox sits beside it. Three things are per-plane, and knowing
+which three is most of what production readiness means:
+
+- **Rows:** a sandbox write is invisible to production and to every other sandbox.
+- **The registered database:** one per plane, so your production database and
+  your dev database are separate registrations.
+- **The active schema artifact:** the model shapes the engine actually routes on.
+
+A key's plane is fixed at mint and spelled in its prefix: `sk_live_` acts on
+production, `sk_test_` on a sandbox. There is no runtime override — the
+credential *is* the environment selector, which is why application code never
+passes one.
+
+One asymmetry is worth carrying into your deploy plan. A sandbox with no schema
+artifact of its own reads **production's**, so a schema pushed to production
+reaches your sandboxes automatically. The reverse does not hold: a push from a
+sandbox key creates a sandbox artifact that shadows production **for that
+sandbox's readers only**, and production keeps running the schema it was last
+pushed. Production gets its models when you push to production.
+
+## 1. The database production writes to
+
+Your production database joins Ablo the same way your dev database did — logical
+replication so Ablo can read and confirm, a scoped writer role so Ablo can land
+rows — run once, with a production key so the registration attaches to the
+production plane:
+
+```bash
+ABLO_API_KEY=sk_live_… npx ablo connect apply --url postgres://admin:…@host:5432/db
+ABLO_API_KEY=sk_live_… npx ablo connect check
+```
+
+[Connect Your Database](./data-sources.md) is the full walkthrough — the SQL, the
+two roles, and the complete list of what Ablo touches. Five things about it are
+specifically production concerns:
+
+**Your agents do not each hold a connection.** Every agent, worker, and function
+talks to Ablo, and Ablo holds the database connections — at most 4 connections
+per plane, the same 4 whether one caller is writing behind them or ten thousand
+are. They identify themselves as `ablo-direct-writer`, so `pg_stat_activity`
+accounts for everything Ablo has open at any moment. Size the database for that
+number rather than for your agent count.
+
+**Register the direct host, not the pooler.** A pooler terminates the session
+that replication needs, and it refuses the connection in the same words a wrong
+password would — so a pooled host reads as a credentials problem for as long as
+you let it. `ablo status` names a pooled host when it sees one, with the direct
+host to use instead.
+
+**Reachability is measured from Ablo's network, not yours.** `connect check`
+runs from the infrastructure replication runs on, so an IPv6-only,
+IP-allowlisted, or VPC-private database still verifies — and a database your
+laptop can reach but Ablo cannot fails here rather than at the first write.
+
+**`wal_level = logical` needs a restart.** It is server-wide and not reloadable.
+On RDS and Aurora it is a parameter-group change plus a reboot. Schedule it;
+it is the one setup step with downtime in it.
+
+**A replication slot retains WAL.** While Ablo is connected the slot holds what
+it has not yet acknowledged, so a long disconnection accumulates disk. Ablo
+monitors slot lag and retention and surfaces it, and drops an abandoned slot
+rather than letting it grow without bound.
+
+A database that cannot grant a `REPLICATION` role connects through the signed
+[Data Source endpoint](./data-sources.md) instead. Same model surface, same
+commit chokepoint — it is the marked fallback, so reach for it when replication
+is genuinely unavailable.
+
+## 2. The credential each runtime holds
+
+There is one field, `apiKey`, and what goes in it follows from where the code
+runs. In production that resolves to four rows:
+
+| Runtime | Credential | Notes |
+|---|---|---|
+| Server, worker, agent, cron | `sk_live_` in `ABLO_API_KEY` | Defaults from the environment, so most code passes nothing. |
+| Serverless function | `sk_live_` in `ABLO_API_KEY`, with `transport: 'http'` | Stateless request/response; nothing held open across invocations. |
+| Browser, read-only | `pk_live_` | Publishable and safe to ship, like a Stripe `pk_`. Reads only. |
+| Browser, writing as the signed-in user | `authEndpoint` | A route on your backend mints a short-lived `ek_` per user. |
+
+[API Keys](./api-keys.md) covers the model; [Sessions](./sessions.md) covers
+minting. Two things bite specifically at deploy time.
+
+**The live key `ablo login` gives you cannot push schema.** It is a restricted,
+observe-only `rk_live_` by design, so a stolen CLI config cannot write to
+production. A production deploy needs a **secret** `sk_live_` from the dashboard,
+supplied as `ABLO_API_KEY`. You do not have to discover this from a failed
+deploy: `ablo login`, `ablo mode production`, and `ablo status` each name what
+the key in hand does, and `ablo status --json` reports it as `effectiveKey.kind`
+for a pipeline to check before it pushes.
+
+**An explicit key always wins.** The CLI resolves `ABLO_API_KEY`, then
+`.env.local`, then `.env`, then the stored login — and `ablo status` prints which
+one it found under `key`, with its source. When a deploy lands somewhere
+surprising, that line is usually the answer.
+
+## 3. Pushing the schema is a deploy step
+
+The server keeps its own copy of your schema and routes on that copy. Until it
+has yours, a write to a new model fails with `server_execute_unknown_model` — so
+`ablo push` belongs in your deploy pipeline, ordered **before** the code that
+depends on the new models goes live.
+
+```bash
+ABLO_API_KEY=sk_live_… npx ablo push --yes
+```
+
+Production requires confirmation: interactively you type the destination
+project's name, which is what makes a wrong-project deploy impossible to do by
+reflex. In CI there is no TTY, so `--yes` is the confirmation and a push without
+it stops rather than proceeding unattended.
+
+**Additive changes pass; destructive ones ask.** Adding a model or an optional
+field applies cleanly. Dropping a model or a field, narrowing an enum, or a lossy
+cast is classified as data loss and needs `--force`; adding a required field to a
+populated table needs a `--backfill`. A push that fails is recorded `failed` and
+never activated, so a broken migration cannot leave clients gated against tables
+that do not match.
+
+This is the same expand-and-contract shape any online migration has, and it
+sequences the same way: push the additive change, deploy the code that writes
+both shapes, backfill, then push the removal in a later deploy once nothing reads
+the old field.
+
+**Drift is a connect-time rejection, not a runtime surprise.** A client built
+against a schema the server is no longer running is turned away when it connects.
+`ablo status` prints the local hash beside the deployed one, and the running
+client reports the same `serverSchemaHash` value, so the two can be matched at a
+glance.
+
+## Gate the deploy on the verdict
+
+`ablo status --json` reports the same conclusion the human output ends with, in a
+form a pipeline can act on. An empty `blockers` array is the machine-readable
+form of "ready":
+
+```bash
+blockers=$(ABLO_API_KEY=$ABLO_API_KEY npx ablo status --json | jq '.blockers | length')
+[ "$blockers" -eq 0 ] || { npx ablo status; exit 1; }
+```
+
+Each blocker carries a `problem` and the single `fix` that resolves it, in the
+order you should act on them: an unreachable API makes every other finding
+unverifiable, and a plane with nothing connected makes a schema question
+academic. The JSON also carries `confirmedTarget` — the org, project, and
+environment the server says this key resolves to — which is the authoritative
+answer to where a push would land.
+
+## Webhooks point at the deployed URL
+
+`npx ablo dev` forwards commits to your machine while you build, the way
+`stripe listen` does. A deployed endpoint is registered once, and Ablo returns
+the signing secret a single time:
+
+```bash
+ABLO_API_KEY=sk_live_… npx ablo webhooks create https://yourapp.com/api/ablo/[...all]
+ABLO_API_KEY=sk_live_… npx ablo webhooks list   # endpoints + delivery health
+```
+
+`webhooks list` reports each endpoint's status, cursor, and last error — the
+place to look when a mirror falls behind. [Webhooks](./webhooks.md) covers the
+handler, the Standard Webhooks signature, and rolling a secret.
+
+## What to watch once it is live
+
+- **`ablo logs`:** commit activity as it happens, scoped by the key, so a live
+  key streams the org and a test key streams only its sandbox. `--json` emits
+  NDJSON for piping.
+- **`ablo status`:** the readiness verdict. Cheap enough to run from a health
+  check on your own side.
+- **The [audit log](./audit.md):** every confirmed write traced back to the key
+  that made it and the person who authorized that key.
+- **Your own logger:** pass `logger` to the client and SDK lifecycle, sync,
+  retry, and rollback events join your existing pipeline.
+
+Writes carry receipts rather than being fire-and-forget: a commit is accepted the
+moment Ablo takes it (`queued`) and becomes `confirmed` once the row appears on
+your database's WAL. [Guarantees](./guarantees.md) covers which state to wait for
+and what each promises.
+
+## When something is wrong
+
+| What you see | What it means | The fix |
+|---|---|---|
+| `no database is connected to this plane` | Writes are held rather than routed. Reads still resolve, which is why a read probe stays quiet. | `ablo connect apply` with a key for that plane. |
+| `password authentication failed` during connect | Often a pooled host refusing a session it cannot serve, in the words of a wrong password. | Register the direct database host. |
+| `server_execute_unknown_model` | The plane's active schema does not carry that model. | `ablo push` with a key for that plane. |
+| Clients rejected at connect | The deployed schema and the client's schema disagree. | Push this tree, or deploy the revision the server is running. |
+| `project_scope_denied` (403) | The model belongs to another project in your org. | Use a key minted for that project: a push cannot cross projects. |
+| 403 on `ablo push` | The key authenticated but cannot author schema. | A secret `sk_live_`; the `ablo login` live key is observe-only. |
+
+## The checklist
+
+1. Production database registered against the production plane, direct host, and
+   `ablo connect check` all green.
+2. A secret `sk_live_` in the deploy environment as `ABLO_API_KEY` — never in a
+   browser bundle.
+3. `ablo push --yes` in the pipeline, ahead of the code that needs the new models.
+4. `ablo status --json` gating the deploy on an empty `blockers` array.
+5. Browser clients on a `pk_live_` or an `authEndpoint`, not a secret key.
+6. Webhook endpoints registered at their deployed URLs, with the signing secret
+   in your environment.
+
+## Next steps
+
+- [Connect Your Database](./data-sources.md) — the setup this page registers, in full.
+- [Projects](./projects.md) — one org, many apps, each with its own planes and keys.
+- [API Keys](./api-keys.md) — which credential each runtime holds, and what it may do.
+- [CLI](./cli.md) — every command, its flags, and the environment variables.
+- [Operating on Your Database](./operating-on-your-database.md) — which actions run freely and which belong to a human.
+- [Debugging & Logs](./debugging.md) — watching claims, queueing, and grants while you build.

package/docs/examples/agent-human.md

@@ -1,15 +1,18 @@
 # Agent + Human
 
-A report-writing agent that yields when a human is editing the same report.
+> An agent that yields the row when a person is already holding it.
+
+A task-writing agent that yields when a person is editing the same task.
 
 ## Scenario
 
-The same reports are edited by both humans and agents. They must not collide:
+The same tasks are edited by agents and by the people watching them. They must
+not collide:
 
-- If a human already holds the row, the agent yields instead of fighting for it.
+- If a person already holds the row, the agent yields instead of fighting for it.
 - While the agent is updating, the UI can show who is active.
-- If the report changes mid-run, the commit is rejected instead of overwriting
-  the human's newer edit.
+- If the task changes mid-run, the commit is rejected instead of overwriting the
+  newer edit.
 
 A **claim** does both jobs. Claims don't lock — if another writer holds the row,
 `claim` waits for them, re-reads the fresh row, then hands it back to you on
@@ -21,70 +24,74 @@ a typed error if the row moved underneath you while the agent was busy.
 
 ## Schema-Backed Worker
 
-The worker uses the same schema client the app uses. It reads the report from
-the server with `retrieve({ id })`, claims the row, and writes through
-`ablo.weatherReports.update(...)` with a stale-check so a human's concurrent edit
-can't be overwritten.
+The worker uses the same schema client the app uses. It reads the task from the
+server with `retrieve({ id })`, claims the row, and writes through
+`ablo.tasks.update(...)` with a stale-check so a concurrent edit can't be
+overwritten.
 
 ```ts
 import Ablo, { AbloClaimedError, AbloStaleContextError } from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
-  weatherReports: model({
-    location: z.string(),
-    status: z.enum(['pending', 'ready']),
+  tasks: model({
+    title: z.string(),
+    status: z.enum(['todo', 'doing', 'done']),
   }),
 });
 
-const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+  transport: 'http',
+});
 
-export async function markReady(reportId: string) {
+export async function markDone(taskId: string) {
   await ablo.ready();
 
   // retrieve({ id }) is an async server read — await it.
-  const report = await ablo.weatherReports.retrieve({ id: reportId });
-  if (!report) return { status: 'not_found' };
+  const task = await ablo.tasks.retrieve({ id: taskId });
+  if (!task) return { status: 'not_found' };
 
   try {
-    // queue: false → don't queue behind a current holder. If a human already
+    // queue: false → don't queue behind a current holder. If someone 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. description → the label observers see while we work.
-    await using claim = await ablo.weatherReports.claim({
-      id: reportId,
+    await using claim = await ablo.tasks.claim({
+      id: taskId,
       queue: false,
-      description: 'marking_ready',
+      description: 'marking_done',
     });
-    const claimed = claim.data;
+    if (claim.data.status === 'done') return { status: 'noop' };
 
     // Inside an active claim, `update` is stale-checked automatically: the SDK
     // attaches the claim's snapshot version as `readAt` and sets
     // `onStale: 'reject'`. The write below is therefore equivalent to passing
     // those options yourself:
     //
-    //   ablo.weatherReports.update({
-    //     id: claimed.id,
-    //     data: { status: 'ready' },
+    //   ablo.tasks.update({
+    //     id: claim.data.id,
+    //     data: { status: 'done' },
     //     wait: 'confirmed',
     //     readAt: <claim snapshot version>,
     //     onStale: 'reject',
     //   });
     //
-    // If a human saved a newer version mid-run, the row no longer matches
-    // `readAt`, so the server rejects this commit with AbloStaleContextError
-    // (caught below) instead of clobbering their edit.
-    const updated = await ablo.weatherReports.update({
-      id: claimed.id,
-      data: { status: 'ready' },
+    // If a newer version landed mid-run, the row no longer matches `readAt`, so
+    // the server rejects this commit with AbloStaleContextError (caught below)
+    // instead of clobbering that edit.
+    const updated = await ablo.tasks.update({
+      id: claim.data.id,
+      data: { status: 'done' },
       wait: 'confirmed',
     });
 
-    return { status: 'ready', report: updated };
+    return { status: 'done', task: updated };
   } catch (err) {
-    // A human already holds the row — yield this run and let them finish.
+    // Someone already holds the row — yield this run and let them finish.
     if (err instanceof AbloClaimedError) return { status: 'yielded' };
-    // A human saved a newer version while we held the claim. The stale-check
+    // A newer version was saved while we held the claim. The stale-check
     // rejected our commit, so nothing was overwritten — re-run on fresh data.
     if (err instanceof AbloStaleContextError) return { status: 'stale' };
     throw err;
@@ -101,14 +108,14 @@ Keep workers on the same schema-backed client as the app.
 
 import { useAblo } from '@abloatai/ablo/react';
 
-export function ReportRow({ report: serverReport }: Props) {
-  const data = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
-  const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
-  const agentActive = active?.participantKind === 'agent';
+export function TaskRow({ task: serverTask }: Props) {
+  const data = useAblo((ablo) => ablo.tasks.local.retrieve(serverTask.id)) ?? serverTask;
+  const holder = useAblo((ablo) => ablo.tasks.claim.state({ id: serverTask.id }));
+  const agentActive = holder?.participantKind === 'agent';
 
   return (
     <div>
-      <span>{data.location}</span>
+      <span>{data.title}</span>
       {agentActive ? <span>Agent is updating...</span> : null}
     </div>
   );
@@ -120,9 +127,9 @@ export function ReportRow({ report: serverReport }: Props) {
 - The claim is visible to everyone: the UI reads it synchronously with
   `claim.state({ id })`, and it also arrives over the live stream.
 - `claim({ id })` makes writers take turns instead of racing — with
-  `queue: false`, the agent simply yields when a human already holds the row.
-- The `update` made while the claim is held is stale-checked automatically, so a human's
+  `queue: false`, the agent simply yields when someone already holds the row.
+- The `update` made while the claim is held is stale-checked automatically, so an
   edit landing mid-run rejects the agent's write with a typed
   `AbloStaleContextError` instead of overwriting it.
-- That same write carries the claim, so each accepted change is attributed to
-  the run that made it.
+- That same write carries the claim, so each accepted change is attributed to the
+  run that made it.