@abloatai/ablo 0.57.0 → 0.58.0

package/docs/groups.md

@@ -17,30 +17,28 @@ block `C`. Between those steps someone else edits `A`. The agent is now building
 `C` on a premise that has moved — and nothing about writing `C` looks wrong in
 isolation. That is stale context, and it is the thing sync groups let you catch.
 
-The recipe is one field on the commit: declare the group you read as a premise,
-and say what should happen if it moved.
+The recipe is one field on the commit: declare the group you read as a premise.
 
 ```ts
 // The agent read everything under workspace:abc to compose this write.
 await ablo.blocks.update({
   id: 'block-C',
   data: { text: revised },
-  reads: [{ group: 'workspace:abc', readAt: watermark, onStale: 'notify' }],
+  reads: [{ group: 'workspace:abc', readAt: watermark }],
 });
 ```
 
 At commit, inside the write transaction, the engine asks a single question: *did
 any delta routed to `workspace:abc` land after `watermark`?* If nothing moved, the
-write applies. If something moved, `onStale` decides — `notify` holds the write
-and hands the agent a `StaleNotification` naming the group, so it re-reads
-`workspace:abc` and regenerates; `reject` aborts the batch with a `409`. The agent
-never persists work built on a premise it can no longer see.
+write applies. If something moved, Ablo rejects the batch with a `409`, so the
+agent can re-read `workspace:abc`, regenerate, and submit a fresh guarded
+write. The agent never persists work built on a premise it can no longer see.
 
 ---
 
 ## How you hear about it
 
-Four channels carry "something changed", and they answer four different
+Three channels carry "something changed", and they answer three different
 questions. Pick by the question you have.
 
 ```ts
@@ -52,10 +50,9 @@ await using room = await ablo.records.join(documentIds, { ttl: '5m' });
 room.peers;
 
 // Stop this write if the thing I read moved while I composed it.
-await ablo.blocks.update({ id, data, reads: [{ group: 'workspace:abc', readAt, onStale: 'notify' }] });
-
-// Tell me later if this moves, even though I am not writing now.
-await ablo.records.track({ id: 's-1' });
+const record = await ablo.records.read({ id: 's-1' });
+if (!record) throw new Error('Record not found');
+await ablo.blocks.update({ id, data, reads: [record] });
 ```
 
 | Question | Channel | Arrives |
@@ -63,29 +60,12 @@ await ablo.records.track({ id: 's-1' });
 | What do the rows say right now? | `onChange` | As deltas land, on the socket |
 | Who else is working here? | `join`, then `room.peers` and `room.claims` | As participants come and go, on the socket |
 | Did the premise for **this** write move? | `reads` on the write | On that write's receipt, before it applies |
-| Has anything I read moved since? | `track` | On your next commit's receipt |
-| Stop me writing if it has | `track` with `onStale: 'reject'` | Refuses that commit, at the chokepoint |
-
-Two distinctions do most of the work here.
-
-**`join` is about people; `track` is about data.** Both open a subscription and
-both are scoped by sync group, which is why they look alike. `join` reports
-participants: who is present, what they are doing, which rows they hold. `track`
-reports the rows themselves: something you said you cared about moved, here is
-the watermark to re-read it at. A tool that wants to avoid duplicating a peer's
-work needs `join`. A tool whose output goes stale when its inputs change needs
-`track`.
-
-**`reads` guards one write; `track` outlives it.** They speak the same
-vocabulary and produce the same `StaleNotification`. A `reads` entry is checked
-once, at the commit that carried it, and discarded. A `track` is persisted and
-re-checked against every delta after it, so a long-running actor hears about a
-change that landed while it was thinking, on the next commit it makes.
 
 `onChange` and `join` need a live socket, so they are available on the default
-WebSocket client. `reads` and `track` ride the commit, so they reach a socketless
-actor over HTTP too, which is what makes them the notification path for agents
-and workers.
+WebSocket client. `reads` rides the commit, so it reaches a socketless actor over
+HTTP too. The row returned by `read` privately carries its model, id, and
+watermark; passing that row in `reads` is enough to protect a later write. Ablo
+does not retain the row contents as read evidence.
 
 ---
 
@@ -158,13 +138,12 @@ Two consequences worth designing around:
 ## Declaring the batch premise
 
 `reads[]` declares what the commit was based on. Each entry is a premise, and
-each governs the *whole* commit: if one goes stale, its disposition applies to
-every write in the batch, not just one operation. You choose the granularity per
-entry.
+each governs the *whole* commit: if one goes stale, every write in the batch
+rejects. You choose the granularity per entry.
 
 ```ts
 reads: [
-  { group: 'workspace:abc', readAt: N, onStale: 'notify' },      // did anything in the workspace move?
+  { group: 'workspace:abc', readAt: N },                         // did anything in the workspace move?
   { model: 'Document', id: 's-1', readAt: N, fields: ['title'] }, // did this row (this field) move?
 ]
 ```
@@ -175,108 +154,9 @@ literal: this object, optionally these fields. A row premise with `fields`
 conflicts only on real field overlap, so two actors editing disjoint fields of
 the same row don't collide.
 
-`onStale` has three settings, defaulting to `reject`:
-
-- **`notify`** holds every write in the batch and returns a `StaleNotification`.
-  For a group premise it carries the group name and the new watermark
-  (`observedSyncId`); re-read the group at that point and regenerate. This is the
-  setting a chain wants — the actor gets the truth and resolves it.
-- **`reject`** aborts the batch with a `stale_context` error (`409`). The right
-  default when there is nothing to reconcile and the write should simply not
-  land.
-- **`overwrite`** skips the check and lets the write land — last-write-wins, the
-  explicit escape hatch.
-
----
-
-## Staying subscribed across commits: `track`
-
-A batch premise guards a single commit: you state what you read, the engine
-checks it, the premise is gone. That fits an actor that reads and writes in one
-breath. It does not fit a long-running one — an agent that reads a row now,
-works for a few minutes, and writes much later. By the time it commits, the
-premise it would have declared is stale, and there was no commit in between on
-which to hear that the ground had shifted.
-
-`track` is the durable half of the same idea. Register what you are watching and
-it persists on the server; the next time you commit anything, a change that
-landed on the tracked target since you registered rides back on your receipt —
-the same `StaleNotification` an `onStale: 'notify'` premise would have handed
-you, arriving on the write you were going to make anyway.
-
-```ts
-// Register interest and walk away — no write required.
-await ablo.records.track({ id: 's-1' });
-
-// …minutes of other work later, on your next commit…
-const res = await ablo.blocks.update({ id: 'block-C', data: { text: revised } });
-res.notifications; // populated if s-1 moved under you in the meantime
-```
-
-The target is a row (`{ id }` on the model verb) or a sync group (as a write
-option, below). A track is an idempotent registration: calling it again refreshes
-the same subscription rather than stacking duplicates, and once a change fires the
-track re-baselines, so the same change notifies once. Your own writes to a target
-you track never notify you — the signal is about what *others* did.
-
-You can also register a track as part of a write you are already making, the
-persisted companion to `reads`:
-
-```ts
-await ablo.records.update({
-  id: 's-1',
-  data: { title: revised },
-  reads: [{ group: 'workspace:abc', readAt: N, onStale: 'notify' }], // guards THIS commit
-  track: [{ group: 'workspace:abc' }],                               // and keeps watching after it
-});
-```
-
-So `reads` is the premise for the commit in hand; `track` is a standing
-subscription that outlives it. Both speak the same notification vocabulary.
-Delivery is on your next commit's receipt; a track does not yet push out of band
-between commits.
-
-### Reporting, or gating: `onStale`
-
-A track says what a moved belief should do to your **next write**. Same enum the
-`reads` premise carries, minus the one mode that cannot apply:
-
-```ts
-await ablo.records.track({ id: 's-1' });                        // notify (default)
-await ablo.records.track({ id: 's-1', onStale: 'reject' });     // gate
-```
-
-- **`notify`** — the change rides your next receipt and the commit proceeds. You
-  decide what it means.
-- **`reject`** — your next commit is **refused** while that belief is stale, even
-  if it writes an unrelated row. The gate is on what you *know*, not on what you
-  are touching.
-
-`reject` is for an actor that must not act on a stale picture — an agent that
-read a row, reasoned for minutes, and is about to write based on what it
-believed. Ablo enforces it at the commit chokepoint, so it is a guarantee rather
-than a convention: the write cannot land.
-
-The gate takes a key. It does **not** reopen on its own, because an agent that
-retried blindly would land exactly the write `reject` was asked to prevent. You
-re-read, then re-register the track to say so:
-
-```ts
-try {
-  await ablo.records.update({ id, data });
-} catch (err) {
-  if (err.code === 'stale_context') {
-    const fresh = await ablo.records.get({ id: 's-1' });   // read
-    await ablo.records.track({ id: 's-1', onStale: 'reject' }); // acknowledge
-    await ablo.records.update({ id, data: reconsider(fresh) });     // now it lands
-  }
-}
-```
-
-A track-only call is never gated, so acknowledging is always reachable.
-
-`overwrite` is not offered: it means "apply my write anyway", and a track guards
-no write of its own to apply.
+Any stale premise aborts the batch with `stale_context` (`409`). Re-read and
+regenerate if the work is still relevant. Omit `reads` only when the write is
+intentionally unconditional.
 
 ---
 

package/docs/guarantees.md

@@ -44,11 +44,11 @@ The server remains the source of truth.
 
 ## Stale-Write Protection
 
-Use `snapshot(...)` and `readAt` when a write depends on state the agent already
-read:
+Use `read(...)` and carry the returned row in `reads` when a write depends on
+state the agent already read:
 
 ```ts
-const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
 if (!report) throw new Error('report missing');
 
 await ablo.weatherReports.update({
@@ -67,7 +67,7 @@ not acquire this guarantee.
 
 Two other dispositions exist. `overwrite` applies the write with no stale check
 at all. `notify` **holds** the write, so the row is left as it stands, and hands
-back a `StaleNotification` carrying the current value for the actor to reconcile
+back an `AbloStaleContextError` so the actor can re-read and reconcile
 and re-issue; the rest of the batch still commits.
 
 See [Concurrency Convention](./concurrency-convention.md) for the full taxonomy,
@@ -96,8 +96,7 @@ claim queues fairly behind the holder).
 
 By default, a held claim rejects writes from other participants to the claimed
 target. Contenders that call `claim` wait their turn; ordinary reads remain
-open. An explicit model conflict policy can choose another disposition for a
-participant kind. While you hold a claim, the matching
+open. While you hold a claim, the matching
 `ablo.<model>.update({ id, ... })` is rejected with `AbloStaleContextError` if
 the row changed underneath you after your claim point.
 

package/docs/identity.md

@@ -410,7 +410,7 @@ it to the provider:
 
 ```ts
 // lib/ablo.ts
-import Ablo from '@abloatai/ablo';
+import { Ablo } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
 // Build the client from the identity your server already resolved.
@@ -505,6 +505,7 @@ subset of what its user could see:
 // (the floor). Build each group from the model's scope with `syncGroup(kind, id)`.
 const session = await server.sessions.create({
   agent: { id: agentId },
+  onBehalfOf: { user: { id: triggeringUser.id } },
   can: { Document: ['read', 'update'], Workspace: ['read', 'update'] },
   syncGroups: [syncGroup('document', recordId), syncGroup('workspace', workspaceId)],
 });

package/docs/index.md

@@ -162,6 +162,11 @@ default caller, not a special one.
 
 ## Build
 
+- [Agent Integration Decision Guide](./agent-integration-decision-guide.md) — choose identifier or row claims, captured reads, atomic boundaries, persistence ownership, transport, and the smallest proof before opening an example.
+- [TypeScript Library](./libraries/typescript.md) — construct the server client,
+  keep schema ownership beneath one boundary, and select an integration approach.
+- [GraphQL.js over an Existing Backend](./approaches/graphql/graphql-js.md) —
+  keep resolvers thin and call one named Ablo-backed domain operation.
 - [Quickstart](./quickstart.md) — make your first coordinated write.
 - [Integration Guide](./integration-guide.md) — the canonical end-to-end integration.
 - [Integrations](./integrations.md) — long-running records, ingestion, and other application-edge runtimes.

package/docs/integration-guide.md

@@ -77,7 +77,7 @@ When handing this to a coding agent, give it a concrete target:
 ```txt
 Add Ablo to this app for one model your agents edit.
 Run npx ablo dev and use its branch-bound key. Declare schema, add the Ablo client, replace
-one write with ablo.<model>.update(..., { readAt, onStale: 'reject' }), and add a smoke test for two concurrent writers.
+one decision read with ablo.<model>.read(...), pass that row in the write's reads array, and add a smoke test for two concurrent writers.
 ```
 
 ## 1. Declare A Schema
@@ -93,9 +93,9 @@ import { defineSchema, model, z } from '@abloatai/ablo/schema';
 export const schema = defineSchema(
   {
     weatherReports: model({
-      // Reserved fields (id, createdAt, updatedAt, organizationId, createdBy)
-      // are SDK-provided automatically — never declare them. Declare only your
-      // own fields.
+      // `id` is the only field the SDK supplies; never declare it. Audit
+      // fields are ordinary fields: declare `createdAt` / `updatedAt` /
+      // `createdBy` here if you want columns for them.
       projectId: z.string(),
       location: z.string(),
       status: z.enum(['pending', 'ready']),
@@ -158,7 +158,7 @@ falsy flag. See `packages/transaction/src/schema/model.ts` for the full option s
 Trusted runtimes can use `ABLO_API_KEY`.
 
 ```ts
-// src/ablo.ts
+// src/client/ablo.ts
 import Ablo from '@abloatai/ablo';
 import { schema } from './ablo/schema';
 
@@ -176,7 +176,7 @@ client now).
 
 ```tsx
 // src/ablo-client.ts
-import Ablo from '@abloatai/ablo';
+import { Ablo } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
 // The browser never holds the API key. The client mints a short-lived token
@@ -256,7 +256,7 @@ refreshes before expiry.
 ## 3. Read State
 
 Reads come in two flavors, and you pick based on whether you can wait.
-`get({ id })` and `list({ where })` hit the server (and hydrate the local
+`get({ id })`, `read({ id })`, and `list({ where })` hit the server (and hydrate the local
 store) — they're async, so you `await` them. `local.get(id)`,
 `local.list({ where })`, and `local.count({ where })` read the already-synced local
 graph synchronously, so they're the ones you call in render — and the ones you
@@ -268,7 +268,7 @@ and waits.
 ```ts
 await ablo.ready();
 
-const report = await ablo.weatherReports.get({ id: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
 if (!report) throw new Error('report not found');
 ```
 
@@ -318,17 +318,17 @@ For simple writes:
 await ablo.weatherReports.update({ id: 'report_stockholm', data: { status: 'ready' } });
 ```
 
-For writes based on state the user or agent already read, snapshot first and
-reject stale updates:
+For writes based on current state, use a decision read and pass the exact row
+to the mutation:
 
 ```ts
-const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
+const report = await ablo.weatherReports.read({ id: 'report_stockholm' });
+if (!report) throw new Error('report not found');
 
 await ablo.weatherReports.update({
-  id: 'report_stockholm',
+  id: report.id,
   data: { status: 'ready' },
-  readAt: snap.stamp,
-  onStale: 'reject',
+  reads: [report],
 });
 ```
 
@@ -481,12 +481,12 @@ const completeReport = tool({
     forecast: z.string(),
   }),
   execute: async ({ reportId, forecast }) => {
-    const snap = ablo.snapshot({ weatherReports: reportId });
+    const report = await ablo.weatherReports.read({ id: reportId });
+    if (!report) throw new Error('report not found');
     return ablo.weatherReports.update({
       id: reportId,
       data: { status: 'ready', forecast },
-      readAt: snap.stamp,
-      onStale: 'reject',
+      reads: [report],
     });
   },
 });
@@ -529,7 +529,7 @@ that guarantee as eventual completion with repair—not atomicity.
 | `persistence: 'indexeddb'`                | Durable browser cache that survives reloads, for apps that need it. |
 | `durableWrites: { store, namespace? }`     | Recover unacknowledged worker writes after a process restart.      |
 | `claim` / `claim.state` / `claim.queue`          | Show active work and coordinate before a write.                   |
-| `snapshot` + `readAt`                     | Reject writes based on stale state.                               |
+| `read` + `reads`                          | Reject writes based on stale state.                               |
 | `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and read tuning.                                  |
 
 The first integration should not need most of these. Start with schema and
@@ -540,7 +540,8 @@ them.
 
 | Method                                 | Use it for                                                                       |
 | -------------------------------------- | -------------------------------------------------------------------------------- |
-| `get({ id })`                     | Async read of one row from the server (await it).                                |
+| `get({ id })`                      | Observe one row from the server (await it).                                      |
+| `read({ id })`                     | Read one decision input to carry in a mutation's `reads` array.                  |
 | `list({ where })`                      | Async read of many rows from the server (await it).                              |
 | `listAll({ where, maxPages?, signal? })` | Explicit bounded traversal of every matching page; filter before collecting.   |
 | `local.get(id)`                   | Synchronous local read of one synced row (use in render).                        |

package/docs/integrations/sandbox-runtime.md

@@ -0,0 +1,148 @@
+# Anthropic Sandbox Runtime
+
+> Run an Ablo agent with OS-enforced filesystem and network boundaries while its coordinated work remains durable outside the sandbox.
+
+Anthropic Sandbox Runtime and Ablo own different boundaries:
+
+| Concern | Owner |
+|---|---|
+| Filesystem, network, Unix sockets, process-tree restrictions | Sandbox Runtime |
+| Typed reads and writes, claims, fencing, idempotency, confirmation | Ablo |
+| Prompts, tools, model calls, and business behavior | Your application |
+| Authentication, branch creation, schema push, and database connection | A trusted host workflow |
+
+An **execution sandbox** is the disposable process boundary. An **Ablo branch**
+is an isolated data and schema plane. Keep the names and lifecycles separate.
+
+## Use two profiles
+
+Do not give a repository-editing agent the same authority as a runtime agent.
+
+The **integration profile** adapts source code. It receives no Ablo credential,
+has no Ablo network access, cannot read real environment files, and writes only
+inside the selected application root. It can still read the installed-version
+documentation without a network connection:
+
+```bash
+npm exec --offline -- ablo docs integration-guide
+npm exec --offline -- ablo docs api
+npm exec --offline -- ablo setup --plan --json
+```
+
+The **runtime profile** executes application work. It receives one short-lived,
+branch-bound runtime credential, permits the Ablo API, and normally has no
+repository write access. Give it only the model operations and sync groups one
+run needs.
+
+Never inject control-plane authority, a database URL, cloud credentials, or an
+ambient host environment into either profile.
+
+## Prepare authority outside the sandbox
+
+Run control-plane and database operations in a trusted host workflow. That
+workflow prepares the branch, pushes the reviewed schema, and delegates a
+per-run `rk_` credential. Management and broad branch credentials are
+infrastructure details and never enter the agent-facing launcher:
+
+```bash
+# Supplied by trusted CI or a credential broker after branch preparation.
+export ABLO_API_KEY=rk_...
+npm run sandbox -- agent job_123
+```
+
+The sandbox launcher should build an explicit child environment rather than
+inherit `process.env`. A runtime credential is not a substitute for process
+isolation, and process isolation is not a substitute for a narrowly scoped
+credential.
+
+## Keep the repository tree downward
+
+Give the Ablo boundary and agent behavior separate entry points:
+
+```text
+src/
+  ablo/
+    index.ts          schema-backed client boundary
+    client.ts
+    schema.ts
+  agent/
+    index.ts          process entry point
+    processJob.ts
+sandbox/
+  index.ts            sanitized launcher and command catalog
+  integration.policy.json
+  runtime.policy.json
+```
+
+The agent enters through `agent/index.ts` and follows dependencies down into
+`ablo/index.ts`. Ablo code never imports the agent or sandbox implementation.
+
+## Coordinate effects that outlive the process
+
+A filesystem sandbox cannot prevent two valid agents from overwriting the same
+shared row. Read, claim, and write through the schema-backed Ablo client:
+
+```ts
+const claim = await ablo.jobs.claim({
+  id: jobId,
+  description: 'processing in a sandbox',
+  ttl: '30s',
+  heartbeat: { every: '10s' },
+});
+
+try {
+  const result = await performWork(claim.data);
+  await ablo.jobs.update({
+    id: claim.data.id,
+    data: { status: 'complete', result },
+    claim,
+    idempotencyKey: `job:${claim.data.id}:complete`,
+  });
+} finally {
+  await claim.release();
+}
+```
+
+If the sandbox disappears, its heartbeat stops and the lease expires. A later
+holder reads fresh state. If the old process resumes, the checked write is
+refused because it no longer owns the claim.
+
+## Start from deny-first policies
+
+Sandbox Runtime denies writes and network access unless they are allowed, but
+filesystem reads require explicit deny regions. A practical policy should:
+
+- deny the user's home region, then re-allow the selected repository;
+- keep real `.env*`, SSH material, cloud configuration, and credentials denied;
+- allow writes only to the selected application root and a dedicated temporary directory;
+- allow only `api.abloatai.com:443` for an Ablo runtime agent;
+- add a model-provider domain only when the model process itself runs inside the sandbox;
+- leave Docker sockets and Apple Events disabled; and
+- use resolved literal paths because filesystem globs are not supported on Linux.
+
+Domain allowlists are coarse: an allowed domain can still be an exfiltration
+channel. Filesystem isolation, environment sanitation, and least-authority
+credentials must be used together.
+
+## Run the complete example
+
+The repository example contains the launcher, both policies, the schema-backed
+agent, and boundary tests:
+
+```bash
+cd examples/sandboxed-agent
+npm install
+npm run docs:sandboxed
+npm test
+npm run typecheck
+```
+
+Sandbox Runtime is a beta research preview. Keep it behind the launcher boundary
+so policy and API changes do not spread through application or Ablo code.
+
+## References
+
+- [Anthropic Sandbox Runtime](https://github.com/anthropic-experimental/sandbox-runtime)
+- [Agents](../agents.md)
+- [Branch-first development](../branch-development.md)
+- [Coordination](../coordination.md)

package/docs/integrations.md

@@ -13,6 +13,7 @@ into authoritative application state.
 
 | Category | Integration | Status | Use it for |
 |---|---|---|---|
+| Agent execution | [Anthropic Sandbox Runtime](./integrations/sandbox-runtime.md) | Available | Restricting the filesystem, network, sockets, and inherited authority of an agent process |
 | Long-running records | [Temporal](./integrations/temporal.md) | Available | Durable Workflows, Activity retries, timers, cancellation, and durable AI SDK calls |
 | Long-running records | [Inngest](./integrations/inngest.md) | Available | Event-driven durable functions, retriable steps, flow control, and checkpointed AI SDK calls |
 | Data ingestion | Connector runtimes | Planned | Bringing external data into Ablo-backed models without creating a second write authority |
@@ -22,6 +23,14 @@ the boundary has been tested. A dedicated package comes later still: only
 repeated production integrations that reveal substantial reusable behavior
 justify adding another public runtime dependency.
 
+## Agent execution
+
+Use [Anthropic Sandbox Runtime](./integrations/sandbox-runtime.md) to enforce the
+boundary around an agent process. The runtime owns filesystem and network
+access. Ablo remains below it and owns typed shared-state operations, claims,
+idempotency, and confirmation. The runnable example lives in
+`examples/sandboxed-agent`.
+
 ## Long-running records
 
 Use [Temporal](./integrations/temporal.md) when work must survive process

package/docs/operating-on-your-database.md

@@ -39,6 +39,13 @@ Ablo prevents a non-holder from writing through another participant's claim by
 default. It does not infer that every plain update is a read-modify-write
 operation; use the guarded forms when lost-update protection matters.
 
+Direct SQL remains outside that enforcement path. If an existing application
+service writes the same row directly, keep its database constraints and locks
+as the final integrity boundary and route every participating caller through
+one named operation. Ablo can select one worker before expensive work begins;
+the existing service must still re-read, validate, and commit authoritatively.
+See [Coordinate an existing database operation](./coordination.md#coordinate-an-existing-database-operation).
+
 ## Three kinds of action
 
 Sort any action you're about to take into one of these, and the right move

package/docs/quickstart.md

@@ -10,10 +10,11 @@ confirms it by tailing your write-ahead log (WAL). Your rows live in your databa
 which stays the system of record. Ablo writes rows but **runs no DDL and owns no
 schema** — your migration tool stays in charge of the shape of your database.
 
-> No database yet? Pass an `apiKey` only and Ablo keeps your rows in its own log,
-> so you can build the whole app today. Point it at a
-> separate or local Postgres for a development branch, or at your production
-> database when you're ready.
+> **Which database?** A branch needs one connected before a schema will push, so
+> start on a throwaway rather than your production Postgres. `ablo dev` gives
+> each Git branch its own isolated plane: point a development branch at a local
+> or separate database, and connect your production one when you're ready for it
+> to be the system of record.
 
 ## 1. Install and initialize
 
@@ -26,14 +27,16 @@ npx ablo init
 by signing you in — one browser click, and a project-scoped `mk_` management
 credential is saved locally. Later, `npx ablo dev` (step 4) prepares an isolated branch and writes
 its temporary `ABLO_API_KEY` into `.env.local`, so the SDK follows your Git
-branch with no manual copy-paste. `npx ablo login` also exists standalone. In
-CI, set project management access explicitly:
+branch with no manual copy-paste. `npx ablo login` also exists standalone.
+Headless CI uses the same credential input as every other Ablo process; during branch
+preparation it contains an `mk_` credential:
 
 ```bash
-export ABLO_MANAGEMENT_KEY=mk_...
+export ABLO_API_KEY=mk_...
 ```
 
-Every runtime call needs a branch-bound API key. `ablo dev` exchanges the
+Do not pass that value to application code. Every runtime call needs a
+branch-bound API key. `ablo dev` exchanges the
 stored management credential for
 an expiring `sk_*` key bound to the current development branch.
 Production runtimes use `sk_*`. In production a key points at the database
@@ -67,9 +70,12 @@ export const schema = defineSchema({
 });
 ```
 
-**Reserved fields** — `id`, `createdAt`, `updatedAt`, `organizationId`, and
-`createdBy` are provided by the SDK automatically. Don't declare them in your
-`model(...)` fields; declare only your own.
+**`id` is the only automatic field.** Every row carries one, so leave it out of
+`model(...)`. Everything else is yours, audit fields included: declare
+`createdAt`, `updatedAt` or `createdBy` and `ablo migrate` gives each a column,
+which your write or a database default then fills. Ablo does not write them for
+you. A model that omits them still reads and writes, it just orders and
+attributes its history less precisely.
 
 The schema is registered once (init scaffolds `ablo/register.ts` for you), and
 every type is one parameter away — no `typeof schema` re-stating, anywhere:
@@ -229,12 +235,12 @@ const updated = await ablo.weatherReports.update({
 console.log({ id: updated.id, status: updated.status }); // { id: '...', status: 'ready' }
 ```
 
-Read a single row back with `get({ id })`. It resolves to the row, or to
+Read a single row back with `read({ id })`. It resolves to the row, or to
 `undefined` when no row has that id — so narrow it once, then the fields are
 fully typed:
 
 ```ts
-const report = await ablo.weatherReports.get({ id: created.id });
+const report = await ablo.weatherReports.read({ id: created.id });
 if (!report) throw new Error(`weatherReports ${created.id} not found`);
 
 console.log(report.status); // 'ready'