@abloatai/ablo 0.7.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

@@ -2,9 +2,9 @@
 
 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 — the CLI and the hosted
-server lower it to **the same SQL** through one engine
-(`generateProvisionPlan` / `generateMigrationPlan` in `@abloatai/ablo/schema`).
+`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
@@ -12,6 +12,13 @@ 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
@@ -48,7 +55,8 @@ either mode) defines the same models test and live see; only the rows differ.
 | `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 schema 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 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` |
@@ -98,10 +106,11 @@ point: review it, then run `ablo check`.
 
 ## `ablo check`
 
-The BYO front door. Instead of migrating (DDL on your database), Ablo *adopts*
-the tables you already have: `ablo check` introspects `DATABASE_URL`, compares it
-to your `defineSchema(...)`, and reports — per model — whether the table is
-adoptable. It never writes or alters anything.
+`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
@@ -131,12 +140,13 @@ 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` vs `schema push`
+## `migrate` (BYO) vs `push` (Hosted)
 
-Two front doors to the same engine. Use `migrate` when your app owns the
-database (it applies to `DATABASE_URL`); use `schema push` (and `dev`) on the
-hosted path (the server applies to Ablo-managed Postgres and version-gates
-connecting clients).
+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
@@ -160,8 +170,8 @@ The one type map, shared by both paths (there is no second mapping):
 
 Each table also gets the platform columns (`id`, `organization_id`,
 `created_by`, `created_at`, `updated_at`), an `organization_id` index, and
-row-level security keyed on `current_setting('app.current_org_id')` for tenant
-isolation.
+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
@@ -185,7 +195,7 @@ that broke and the Postgres SQLSTATE, not just "migration failed".
 }
 ```
 
-`ablo schema push` (hosted) returns the canonical error envelope (HTTP 500),
+`ablo push` (hosted) returns the canonical error envelope (HTTP 500),
 which the SDK reconstructs as a typed `AbloServerError`:
 
 ```json
@@ -207,6 +217,6 @@ 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_URL` | Control-plane / API host (`schema push`, `dev`, `status`). | `https://api.abloatai.com` |
+| `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
 
@@ -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,16 +5,18 @@ 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` · `claimState` · `queue` · `release` · [writing under a
+(`claim` · `claim.state` · `claim.queue` · `claim.release` · [writing under a
 claim](#writing-under-a-claim)), and the [errors](#errors) you can catch.
 
 ---
@@ -27,8 +29,8 @@ make:
 
 | layer | kind | what it does | enforces? |
 |---|---|---|---|
-| **Presence** (`claimState`, 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`/`queue`/`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. |
+| **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 →
@@ -42,42 +44,29 @@ write)?**
   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):**
-
-1. **Claim supersedes stale-context for *foreign* writers.** A non-holder writing
-   to a claimed row is rejected by the claim guard (`AbloClaimedError`,
-   `claim_conflict`/`entity_claimed`) *before* any watermark check — `readAt` is
-   irrelevant when you don't hold the lease. Pessimistic exclusion is the outer
-   gate.
-2. **Stale-context is the always-on backstop for *unclaimed* writes.** No claim
-   held → the watermark check is the only protection, and it's automatic. This is
-   why the no-claim path is safe by default.
-3. **Inside a claim, both apply.** A claim is not a license to clobber yourself:
-   writes under a held claim carry the claim's snapshot as `readAt` with
-   `onStale: 'reject'` (see [Writing under a claim](#writing-under-a-claim)), so a
-   `bypass` write or a row that moved between snapshot and write still rejects.
-   Claim = "no one else"; stale-context = "and not against a moved snapshot."
-4. **Presence never decides.** It is the visualization of (1)–(3), not a fourth
-   gate. Never branch enforcement logic on `claimState` — read it to render, act
-   on the errors above.
-
-Claims and stale-context are **orthogonal by construction**, not wired into each
-other on the server: the claim guard runs pre-transaction; the watermark check
-runs inside it. The SDK attaches `readAt`/`onStale` for you when writing under a
-claim — that coupling lives in the SDK, deliberately, so the server's two checks
-stay independent and individually testable.
+**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'`). |
@@ -118,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**
 
@@ -157,8 +146,8 @@ 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
@@ -172,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
@@ -193,7 +182,7 @@ is free.
 **Example**
 
 ```ts
-const who = ablo.weatherReports.claimState('report_stockholm');
+const who = ablo.weatherReports.claim.state('report_stockholm');
 if (who) console.log(`${who.heldBy} is ${who.action}`);
 ```
 
@@ -211,17 +200,17 @@ Returns the active claim state when the row is held, or `null` when it's 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**
@@ -237,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));
 ```
 
-### `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
@@ -271,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

package/docs/data-sources.md

@@ -1,19 +1,19 @@
 # Connect Your Database
 
-Every schema model has a backing store.
+By default, Ablo stores the rows for the models you define, so you don't need a
+database to get started. But if you already have your own application database
+and want it to stay the source of truth, you can attach it as a Data Source —
+then Ablo coordinates each write and calls your app to commit it, instead of
+storing the data itself.
 
-Customer apps must define an Ablo schema. The schema is the contract between
-the SDK, agents, realtime subscriptions, and the Data Source endpoint. Use
-`defineSchema`, `model`, and Zod the same way a Prisma project starts with a
-`schema.prisma`.
+That default makes Ablo the managed state store for your models, the same way
+Stripe stores `Customer` and `PaymentIntent` objects that you create through
+Stripe's API.
 
-By default, Ablo stores the rows for the models you declare. That makes Ablo the
-managed state store for those models, the same way Stripe stores `Customer`
-and `PaymentIntent` objects that you create through Stripe's API.
-
-If you already have application tables and want those tables to remain
-canonical, attach a Data Source. Then Ablo coordinates the write and calls your
-app to commit it.
+Either way, you define an Ablo schema with `defineSchema`, `model`, and Zod —
+the same way a Prisma project starts with a `schema.prisma`. Your schema
+describes your data once, and everything else (the SDK, agents, and your
+database connection) relies on that one definition.
 
 Your app can keep using its own `DATABASE_URL`. Store that value in your app or
 backend environment, not in Ablo. The integration boundary is the HTTPS
@@ -56,15 +56,18 @@ The SDK call is the same in both modes:
 ```ts
 await ablo.weatherReports.create({ location: 'Stockholm', status: 'pending' });
 await ablo.weatherReports.update('report_stockholm', { status: 'ready' });
-const report = ablo.weatherReports.retrieve('report_stockholm');
+const report = ablo.weatherReports.get('report_stockholm');
 ```
 
 Only the backing store changes.
 
 Multiplayer behavior is the same in both modes. Writes made through
 `ablo.<model>.create/update/delete` are coordinated by Ablo, then confirmed rows
-fan out to subscribers. Direct database writes outside Ablo need Data Source
-events so connected humans and agents see the change.
+fan out to subscribers. If something writes to your database without going
+through Ablo (a cron job, an admin tool), Ablo can't know about it
+automatically. To keep everyone's screen up to date, your app reports those
+outside changes back through an events feed — shown below in
+[External Writes](#external-writes).
 
 ## When To Use A Data Source
 
@@ -231,10 +234,9 @@ Before using a customer-owned database in production:
 - Dedupe outbox events by event `id`.
 - Monitor last success, last error, retry count, event lag, and cursor.
 
-Do not send the customer's database URL to Ablo for this path. Direct database
-URL custody would be a separate connector product with encrypted secret storage,
-rotation, least-privilege roles, connection limits, table allowlists, and clear
-data-processing terms.
+Don't give Ablo your database URL for this integration — Ablo never connects to
+your database directly. (Direct database access would be a separate product with
+its own security model.)
 
 ## Security