@abloatai/ablo 0.34.0 → 0.35.0

package/docs/interaction-model.md

@@ -1,8 +1,10 @@
 # Interaction Model
 
-When a person, a server action, and an AI agent can all write to the same row,
-you need one write path that stops them from clobbering each other. Ablo gives
-you exactly one: load the row, claim it while you work, update it, and wait for
+> The one write path every actor shares: load, claim, update, confirm.
+
+When two agents, a server action, and a person can all write to the same row, you
+need one write path that stops them from clobbering each other. Ablo gives you
+exactly one: load the row, claim it while you work, update it, and wait for
 confirmation. This page walks through that path and the few primitives behind it.
 
 Here's the whole path in one block — claim a row, update it inside the claim, and
@@ -24,7 +26,7 @@ of clobbering.
 | Primitive | Plane | Purpose |
 |---|---|---|
 | `Schema` | State | Declares typed models the app and agents can read and write. |
-| `Model` | State | The generated `ablo.<model>` model. Use `retrieve`/`list` (async server reads), `get`/`getAll`/`getCount` (synchronous local reads), `create`, `update`, and `delete`. |
+| `Model` | State | The generated `ablo.<model>` model. Use `retrieve`/`list` (async reads), `local.retrieve`/`local.list`/`local.count` (the same verbs, synchronous and local-only), `create`, `update`, and `delete`. |
 | `Claim` | Coordination | Who is working on a target. Taken via `ablo.<model>.claim({ id })` and read via `ablo.<model>.claim.state({ id })`. Ephemeral — never persisted. |
 | `Commit` | Protocol | The durable write underneath model updates. Most users do not call it directly. |
 | `Receipt` | Protocol | The lower-level durable result for custom runtimes. Schema writes use `wait: 'confirmed'`. |

package/docs/mcp.md

@@ -1,38 +1,64 @@
 # Model Context Protocol
 
+> Two MCP servers for two different jobs — one of them is a data plane, one is not.
+
 Ablo publishes **two** MCP servers for two different jobs. Don't confuse them:
 
 | Server | Purpose | Auth | Tools |
 |---|---|---|---|
-| **Coordination** (`@ablo/mcp`) | Let an agent safely read & mutate your application data | API key (`sk_…` / `rk_…`) | per-model `get` / `list` / `create` / `update` / `delete` / `claim` / `release` |
+| **Coordination** (`@abloatai/mcp`) | Manage your Ablo the way the CLI does, and let an agent safely read & mutate application data | API key (`sk_…` / `rk_…`) | projects, schema, logs, usage — plus `get` / `list` / `create` / `update` / `delete` / `claim` / `release` over your rows |
 | **Integration-helper** (hosted `/api/mcp`) | Help an AI coding assistant write SDK integration code that compiles | none (public docs) | doc search, export surface, schema lint, scaffold |
 
-The coordination server **is the data plane** — it is how an agent changes
-state. The integration-helper server only serves docs, schema lint, and
-scaffolds; it does **not** read or write application data (there are no
+The coordination server manages your account **and is the data plane** — it is
+how an agent changes state. The integration-helper server only serves docs,
+schema lint, and scaffolds; it does **not** read or write application data (there are no
 per-model data tools on it). Pick by what you're doing: shipping an agent that
 edits rows → coordination; teaching your IDE assistant the SDK → helper.
 
-## Coordination server (`@ablo/mcp`)
+## Coordination server (`@abloatai/mcp`)
 
-The coordination server is the MCP projection of the model-scoped API
-(`/api/v1/models/...`) — the same surface as `ablo.<model>.create/update/claim` and
-the REST routes, rendered as tools. An agent connects with your API key and
-gets one safe loop: **claim → read → commit → release.**
+The coordination server does two jobs: it manages your Ablo the way the `ablo`
+CLI does, and it renders the model-scoped API (`/api/v1/models/...`) as tools —
+the same surface as `ablo.<model>.create/update/claim`. An agent connects with
+your API key and gets one safe loop: **claim → read → commit → release.**
 
 Install over stdio; set your key in the host's MCP env:
 
 ```bash
-claude mcp add ablo -- npx -y @ablo/mcp
+claude mcp add ablo -- npx -y @abloatai/mcp
 # env:  ABLO_API_KEY=sk_…   (ABLO_API_URL optional; defaults to the hosted API)
 ```
 
-Each tool mirrors an SDK verb, scoped to a model + id:
+### Managing your Ablo
+
+| Tool | Mirrors | Does |
+|---|---|---|
+| `get_schema` | `ablo status` | the models this key can address, and its environment + project |
+| `list_projects` | `ablo projects list` | the org's projects (needs `sk_`) |
+| `create_project` | `ablo projects create` | create one (needs `sk_`) |
+| `tail_logs` | `ablo logs` | recent commits and the actor behind each |
+| `get_usage` | — | usage in daily buckets |
+
+There are no key-management tools. A mint returns the plaintext once — only a
+hash is kept — so no tool can hand it back later, and returning it at mint time
+would write a live secret into the agent's context and the conversation
+transcript, where it outlives any revocation. Listing and revoking will arrive
+once a grant identifies the caller as a person rather than a key. Manage keys
+with `ablo login` or the dashboard.
+
+`ablo init`, `push`, `pull`, and `generate` have no tools: they read and write
+files in your repo, which the server cannot see. Run those in a shell — then
+call `get_schema` to see the result.
+
+### Reading and changing rows
+
+Each tool mirrors an SDK verb, scoped to a model + id. Model names come from
+`get_schema`:
 
 | Tool | Mirrors | Does |
 |---|---|---|
-| `get_model` | `ablo.<model>.get(id)` | read latest state + active claims |
-| `list_models` | `ablo.<model>.list({…})` | cursor-paginated list with filters |
+| `get_model` | `ablo.<model>.local.retrieve(id)` | read latest state + active claims |
+| `list_records` | `ablo.<model>.list({…})` | cursor-paginated list with filters |
 | `create_model` | `ablo.<model>.create({ data })` | guarded create |
 | `update_model` | `ablo.<model>.update({ id, … })` | guarded update |
 | `delete_model` | `ablo.<model>.delete({ id })` | guarded delete |
@@ -41,8 +67,7 @@ Each tool mirrors an SDK verb, scoped to a model + id:
 
 The agent-facing contract — the safe loop, the "derive idempotency keys from
 the business event" rule, and the error-code playbook — ships as a loadable
-skill at `@ablo/mcp/skill.md`. Lives in `packages/mcp/`
-(`createCoordinationMcpServer`, `src/tools.ts`).
+skill at `@abloatai/mcp/skill.md`.
 
 ## Integration-helper server
 
@@ -57,7 +82,7 @@ server above, never here.
 > The `@abloatai/ablo` npm package itself bundles neither server — it has
 > no `@modelcontextprotocol/sdk` dependency. The helper is a feature of Ablo's
 > hosted app, mounted at `/api/mcp`; the coordination server is the separate
-> `@ablo/mcp` package.
+> `@abloatai/mcp` package.
 
 ### Install
 

package/docs/migration.md

@@ -1,5 +1,7 @@
 # Version History & Migration Guide
 
+> Every breaking change and the edit it requires, newest first.
+
 The breaking-changes-first companion to the [Changelog](../CHANGELOG.md). The
 changelog tells the story of each release; this page tells you exactly what to
 change when you upgrade.
@@ -11,6 +13,8 @@ change when you upgrade.
 
 | Version | What changed | What to do |
 |---|---|---|
+| **0.35.0** | Synchronous reads moved under `local`, mirroring the async verbs | `get(id)` → `local.retrieve(id)`; `getAll(options)` → `local.list(options)`; `getCount(options)` → `local.count(options)` |
+| **0.35.0** | `causedByTaskId` write option + seven `turn_*` error codes removed | Delete the `causedByTaskId` argument from writes; a branch on `turn_validation_failed` was unreachable and can go with it |
 | **0.34.0** | Presence verb renamed `watch` → `join` | `ablo.<model>.watch(ids)` → `ablo.<model>.join(ids)`; `useWatch` → `useJoin`; the `WatchOptions` / `UseWatchOptions` / `UseWatchReturn` types → `JoinOptions` / `UseJoinOptions` / `UseJoinReturn`; error code `model_watch_not_configured` → `model_join_not_configured` |
 | **0.28.0** | Removed React placeholders that had no working runtime | `usePresence` → `usePeers` or `useJoin`; `useClaim` → `ablo.<model>.claim`; `SyncGroupProvider` / `useSyncGroup` → `useJoin({ scope })` |
 | **0.11.0** | Historical `intent` → `claim` rename | The hook renamed in that release was later removed in 0.28.0. Current code uses `ablo.<model>.claim` or `useJoin` |
@@ -27,6 +31,60 @@ change when you upgrade.
 
 ---
 
+## 0.35.0 — the synchronous reads move under `local`
+
+```diff
+- const task  = ablo.tasks.get(id);
+- const open  = ablo.tasks.getAll({ where: { status: 'open' } });
+- const count = ablo.tasks.getCount({ where: { status: 'open' } });
++ const task  = ablo.tasks.local.retrieve(id);
++ const open  = ablo.tasks.local.list({ where: { status: 'open' } });
++ const count = ablo.tasks.local.count({ where: { status: 'open' } });
+```
+
+Options, return types, and reactivity inside `useAblo` selectors are unchanged.
+Every verb now matches its asynchronous sibling, and `local` narrows the read to
+what has already synced — which is what lets it return a value rather than a
+promise.
+
+`getAll` and `getCount` are distinctive enough to rename by search. `get` is not:
+in most codebases it is outnumbered many times over by `Map.get` and
+`headers.get`, and no search separates them. Upgrade the package first and let
+the compiler name the sites — each one is a type error at exactly the call that
+has to move.
+
+## 0.35.0 — `causedByTaskId` and the `turn_*` error codes removed
+
+0.9.2 retired the `turn` primitive but left one field standing: `causedByTaskId`
+on the write options bag. It was never usable. The server validated it against a
+task record that nothing in the system has ever created, so supplying it had the
+whole batch rejected with `turn_validation_failed`, while leaving it null passed
+straight through. The safe way to use the option was to not use it.
+
+**Removed:** `MutationOptions.causedByTaskId`, the seven `turn_*` error codes
+(`turn_validation_failed`, `turn_open_failed`, `turn_close_failed`,
+`turn_not_found`, `turn_foreign_agent`, `parent_turn_not_found`,
+`parent_turn_foreign_agent`), and the stored row's provenance slice
+(`deltaProvenanceSchema` and the `DeltaProvenance` type). `syncDeltaRowSchema` is
+now the core and attribution slices composed.
+
+```diff
+- await ablo.documents.update({ id, data, causedByTaskId: turnId });
++ await ablo.documents.update({ id, data });
+```
+
+Attribution is unaffected. A delta still records the actor, the `onBehalfOf`
+principal behind a delegated write, the capability that authorized it, and the
+claim it was made under — which is what answers "who did this, and by what
+right." On the wire the field was optional and nullable, so a client that still
+sends it is accepted and ignored.
+
+The `caused_by_task_id` column stays, for the reason 0.9.2 gave when it kept it:
+the audit hash-chain signs its value into every row. Dropping it is a versioned
+migration of its own.
+
+---
+
 ## 0.34.0 — presence verb renamed `watch` → `join`
 
 The model-level presence verb read like a data subscription but delivered
@@ -35,13 +93,13 @@ does. `ablo.<model>.join(ids, { ttl })` opens the participant handle
 (`.peers`, `.claims`, `await using` disposal); the returned `status` was
 already `'joined'`, and the layer beneath always called itself `join`, so the
 verb now matches. `onChange` remains the way to hear row *values* change, and
-`track` remains the durable read-dependency for actors.
+`track` remains the durable premise for actors.
 
 ```ts
 // before
-await using room = await ablo.slides.watch(slideIds, { ttl: '5m' });
+await using room = await ablo.documents.watch(documentIds, { ttl: '5m' });
 // after
-await using room = await ablo.slides.join(slideIds, { ttl: '5m' });
+await using room = await ablo.documents.join(documentIds, { ttl: '5m' });
 ```
 
 The React hook follows: `useWatch({ scope })` → `useJoin({ scope })`. There is
@@ -148,7 +206,7 @@ distinct stores.
 server-side actors (agents, workers, serverless): the same `ablo.<model>` surface
 and `claim` coordination, but each call is one HTTP round-trip with identity on
 the Bearer credential — no websocket, no local synced pool. The return type
-narrows, so stateful-only APIs (`get` / `getAll` / `onChange`) become compile
+narrows, so stateful-only APIs (the `local` reads, `onChange`) become compile
 errors instead of latent runtime gaps. Existing code keeps the default
 `'websocket'` transport, unchanged.
 
@@ -227,7 +285,7 @@ modifier are named siblings. Reactive local reads stay on the synchronous
 + await ablo.tasks.retrieve({ id })
 
 - useAblo((ablo) => ablo.tasks.retrieve(id)) ?? serverTask
-+ useAblo((ablo) => ablo.tasks.get(id)) ?? serverTask
++ useAblo((ablo) => ablo.tasks.local.retrieve(id)) ?? serverTask
 ```
 
 `claim` now returns a disposable handle instead of taking a callback. The handle

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

@@ -0,0 +1,111 @@
+# Operating on Your Database
+
+> Which actions run freely, which to verify first, and which belong to a human.
+
+Ablo sits over your database as a coordination layer, not an owner. It reads
+your Postgres replication stream and routes each write through a claim-checked
+commit that lands in your own tables. It never runs DDL, never migrates, never
+drops. That single boundary is why almost everything you do through Ablo is
+either read-only or reversible — and why the few actions that aren't are easy to
+name. This page is how to tell them apart, so you can work on a real database
+without guessing which move is the dangerous one.
+
+The habit that makes it easy is to look before you act. One command shows you
+the real shape of your database measured against your schema, and changes
+nothing:
+
+```bash
+npx ablo check   # read-only — reports which columns fit your models and which don't
+```
+
+When a question is about the live database — does this column exist, is it
+nullable, will this write fit — you can usually answer it by observing rather
+than reasoning in the dark.
+
+## The floor: what Ablo never does
+
+These hold on every database Ablo connects to, and they are what bound the blast
+radius of anything you do through the model API:
+
+- It **never runs DDL or migrations** on your database, and never drops a table
+  or column. Schema changes to your own tables are always your application's
+  action, run with your admin credential — never Ablo's.
+- It **never owns your rows.** Canonical data stays in your tables; Ablo hosts
+  only the transaction log and the coordination state.
+- Every model write is **claim-checked and recorded.** A write based on a row
+  that moved under you is rejected rather than applied, and the prior value is
+  retained in the log, so a confirmed change is attributable and
+  reconstructable.
+
+So a normal `ablo.<model>.update(...)` cannot silently corrupt your database:
+the worst case is a clean rejection and a re-read, not a lost row.
+
+## Three kinds of action
+
+Sort any action you're about to take into one of these, and the right move
+follows.
+
+**Run freely — read-only or reversible.**
+Reads (`retrieve`, `list`, `get`), `ablo check`, and `ablo pull` observe and
+never change anything. Previews — `--show-sql`, `--dry-run` — print the exact
+SQL a command would run without executing it. Model writes through
+`ablo.<model>.create` / `update` are claim-checked, optimistic, rolled back if
+the server rejects them, and recorded in the log with the prior value. All of
+these are safe to run on your own initiative.
+
+**Verify first — needs one look at the live database.**
+Routing an existing table's writes through a model requires the model to match
+the table's real columns. Run `ablo check`: it names the columns that fit and
+the ones that don't, so a `NOT NULL` column your model doesn't set shows up as a
+line in the report rather than a surprise at commit time. Decide the model shape
+from what `check` tells you, then proceed. Nothing here is risky — it just reads
+better after you've seen the ground truth.
+
+**Hand to a human — irreversible, outside the log's protection.**
+Raw DDL on the live database — `ALTER TABLE … OWNER TO`, adding or dropping a
+column, changing a constraint — changes the database itself and is not covered
+by the reversible log, so it belongs to a person with their hand on it. So does
+a `connect` cutover run with its confirmation skipped (`--yes`): the prompt
+exists because the step provisions real roles and reconciles publication on a
+live database, and on a shared or production database that confirmation is the
+human's to give. Removing a model from your schema belongs here too — for the
+reason below.
+
+## The one action that isn't what it looks like
+
+Deleting a model from `ablo/schema.ts` reads like a code cleanup, but it is a
+schema change. Your schema is a desired-state declaration: `ablo push` diffs it
+against the server's copy, and a model that has vanished from the schema can be
+read as a table that should no longer exist. "Nothing imports it" answers a
+code question. The question that governs safety is *does removing this drop a
+real table on the next push* — and that one is answered against the database,
+not the codebase. Before removing a model that maps a live table, confirm the
+table is gone or empty and that your push path is additive; otherwise keep the
+model until the data is dealt with. A `load: 'lazy'` mapping is often present
+precisely to hold a table in place, so treat its comment as load-bearing.
+
+## The verification loop
+
+Most of the uncertainty in working on a live database dissolves into a few
+read-only checks:
+
+- `ablo check` — does the live database match the schema? Reports the exact
+  column-by-column fit. Read-only.
+- `ablo pull` — what is actually in the database, expressed as a schema.
+  Read-only, like `prisma db pull`.
+- `--show-sql` / `--dry-run` on `connect` and `migrate` — the exact statements,
+  printed and unexecuted, so you approve the SQL before it runs.
+- Read the row and its claim state before you write — `retrieve` / `list`, and
+  `ablo.<model>.claim.state({ id })` for who is already working on it.
+
+The pattern underneath all of it is steady: reads and model writes flow freely
+because the boundary and the log make them safe, DDL and cutovers pause for a
+human because they change the database itself, and the space between the two is
+one `ablo check` away from certain.
+
+## See also
+
+- [Connect Your Database](./data-sources.md) — the one path a database joins Ablo.
+- [Guarantees](./guarantees.md) — what a confirmed write, a stale check, and a claim promise.
+- [CLI & Migrations](./cli.md) — `check`, `pull`, `migrate`, and their read-only / preview flags.
+- [Schema Contract](./schema-contract.md) — how the schema drives push, and why it is a desired-state declaration.

package/docs/projects.md

@@ -1,5 +1,7 @@
 # Projects
 
+> One organization, many apps — each with its own schema, data planes, and keys.
+
 A **project** is the isolation unit inside your organization — the shape you
 know from Neon or Supabase. Each app you build gets its own project, and each
 project gets its own schema, its own sandbox/production data planes, and its

package/docs/quickstart.md

@@ -1,7 +1,9 @@
 # Quickstart
 
+> Make your first coordinated write, on the Postgres you already have.
+
 Build with Ablo on **the Postgres you already have**. You declare a small Ablo
-schema for the models humans and agents edit together, connect Ablo to your
+schema for the models your agents edit together, connect Ablo to your
 database (`ablo connect`), and read and write every one of those models through
 `ablo.<model>`. You write through Ablo; it lands the change in your Postgres and
 confirms it by tailing your write-ahead log (WAL). Your rows live in your database,
@@ -86,6 +88,22 @@ import type { Model } from '@abloatai/ablo/schema';
 type WeatherReport = Model<'weatherReports'>; // fully typed from YOUR schema
 ```
 
+The same block is where you name the metadata your claims carry. Add a
+`ClaimMeta` key and every `claim.state`, `claim.queue`, and held claim reads
+`target.meta` as that shape:
+
+```ts
+declare module '@abloatai/ablo' {
+  interface Register {
+    Schema: typeof schema;
+    ClaimMeta: { blocks: string[] };
+  }
+}
+
+const holder = ablo.weatherReports.claim.state({ id });
+holder?.target.meta?.blocks.length; // typed, no guard
+```
+
 (The same `Register` binding types every hook and client — it's the
 TanStack-Router pattern: declare the source of truth once, everything
 infers from it.)
@@ -169,10 +187,9 @@ tables** — Ablo reads them, it does not create or migrate them:
   the tables with your own migration tool; Ablo syncs the subset of models you
   declared and reports the rest as "ignored / owned by you."
 
-> **Optional escape hatch:** if you have no tables yet and want Ablo to scaffold
-> them, `npx ablo migrate` can create your synced-model tables for you. This is
-> not the happy path — connecting a real database is `ablo connect` (step 3), and
-> your own migrations stay in charge of your schema.
+> **Starting from an empty database?** `npx ablo migrate` creates the tables
+> your schema needs. Once they exist, your own migration tool stays in charge
+> of them — Ablo adopts whatever shape you evolve.
 
 Nothing runs locally — there is no dev server to start. Your app talks to Ablo's
 hosted API; the rows live in your database.

package/docs/react.md

@@ -1,5 +1,7 @@
 # React
 
+> Provider, hooks, and reactive reads for the interfaces people watch agent work arrive in.
+
 The React bindings for `@abloatai/ablo`. Use them when you want live
 data on the client without writing fetch + WebSocket plumbing yourself.
 
@@ -85,7 +87,7 @@ org / team / user map to what a participant can see.
 import { useAblo } from '@abloatai/ablo/react';
 
 export function ReportView({ report: serverReport }: { report: { id: string; location: string } }) {
-  const report = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
+  const report = useAblo((ablo) => ablo.weatherReports.local.retrieve(serverReport.id)) ?? serverReport;
   const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
   const claimed = Boolean(active);
 
@@ -95,7 +97,7 @@ export function ReportView({ report: serverReport }: { report: { id: string; loc
 
 The hook:
 
-1. Uses the same `ablo.<model>.get(id)` / `.getAll()` methods you'd call anywhere
+1. Uses the same `ablo.<model>.local.retrieve(id)` / `.local.list()` methods you'd call anywhere
    else in the SDK — the hook just makes them reactive.
 2. Tracks the model fields read by the selector and re-renders when confirmed
    deltas arrive.
@@ -110,14 +112,14 @@ effects, or writes:
 const abloClient = useAblo();
 ```
 
-Prefer selector reads like `useAblo((ablo) => ablo.<model>.get(id))`. Older hooks
+Prefer selector reads like `useAblo((ablo) => ablo.<model>.local.retrieve(id))`. Older hooks
 also accept a string model name; prefer the selector form shown above.
 
 For collections, keep the selector on the model client too:
 
 ```tsx
 const reports = useAblo((ablo) =>
-  ablo.weatherReports.getAll({
+  ablo.weatherReports.local.list({
     where: { projectId },
     filter: (report) => report.status !== 'ready',
     state: 'live',
@@ -135,7 +137,7 @@ Use `retrieve` in Server Components when the row may not be in the local pool
 yet — it hydrates from the local store and the server, and returns a Promise, so
 `await` it. (Server reads come in two shapes: `retrieve({ id })` for one row and
 `list({ where })` for many; both are async. The synchronous local reads are
-`get`/`getAll`/`getCount`, used in render below.)
+the `local` reads, used in render below.)
 
 ## Writes
 
@@ -191,11 +193,11 @@ write interest in it.
 
 import { useJoin } from '@abloatai/ablo/react';
 
-export function DeckPresence({ deckId }: { deckId: string }) {
+export function DeckPresence({ workspaceId }: { workspaceId: string }) {
   const { peers, claims, status } = useJoin({
-    scope: { slideDecks: deckId },
+    scope: { slideDecks: workspaceId },
     claim: true,   // I intend to write — pin the scope + let peers observe the claim
-    hydrate: true, // backfill the deck's current rows if not already loaded
+    hydrate: true, // backfill the workspace's current rows if not already loaded
   });
 
   if (status !== 'joined') return <span>connecting…</span>;
@@ -230,8 +232,8 @@ connection is subscribed to.
 
 import { usePeers } from '@abloatai/ablo/react';
 
-export function CursorBroadcaster({ deckId }: { deckId: string }) {
-  const peers = usePeers({ slideDecks: deckId });
+export function CursorBroadcaster({ workspaceId }: { workspaceId: string }) {
+  const peers = usePeers({ slideDecks: workspaceId });
   const alone = !peers.some((p) => p.participantKind === 'user');
   // suppress live-cursor broadcasts while alone
 }

package/docs/schema-contract.md

@@ -1,5 +1,7 @@
 # Schema Contract
 
+> One schema becomes typed clients, agent writes, interface reads, and the hosted push.
+
 Ablo's schema is the integration contract. Define it once, pass it to `Ablo(...)`,
 and every actor gets the same typed model surface:
 
@@ -10,7 +12,7 @@ defineSchema(...) -> ablo.<model>.create/retrieve/update/claim(...)
 That one object drives:
 
 - typed model clients in trusted server runtimes,
-- React selectors through `useAblo((ablo) => ablo.<model>.get(id))`,
+- React selectors through `useAblo((ablo) => ablo.<model>.local.retrieve(id))`,
 - agent and background-worker writes,
 - Data Source request/response shape when your database stays canonical,
 - hosted schema push, migration planning, and schema-version gating.
@@ -75,8 +77,8 @@ const ready = await ablo.weatherReports.list({ where: { status: 'ready' } });
 Use synchronous local reads in render after data has synced:
 
 ```ts
-const report = ablo.weatherReports.get(reportId);
-const pending = ablo.weatherReports.getAll({ where: { status: 'pending' } });
+const report = ablo.weatherReports.local.retrieve(reportId);
+const pending = ablo.weatherReports.local.list({ where: { status: 'pending' } });
 ```
 
 Use model writes for every actor:

package/docs/session-settings.md

@@ -0,0 +1,108 @@
+# Session Settings
+
+> Point your row-level-security policies at Ablo's writes, by naming the Postgres session settings they already read.
+
+Ablo writes your rows through a scoped role with `row_security` on and
+`NOBYPASSRLS` set, so your policies govern its writes the same way they govern
+your own application's. They only govern well if they can see who the write is
+for. Before each write, Ablo sets its own identity context on the transaction —
+and if your policies read settings under names you chose, `sessionSettings` maps
+one to the other:
+
+```ts
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+export const schema = defineSchema(
+  {
+    invoices: model({
+      total: z.number(),
+      reference: z.string(),
+    }),
+  },
+  {
+    sessionSettings: { 'app.current_org': 'orgId' },
+  },
+);
+```
+
+A policy written against `current_setting('app.current_org')` now applies to
+Ablo's write, unchanged:
+
+```sql
+CREATE POLICY tenant_isolation ON invoices
+  USING (organization_id = current_setting('app.current_org', true));
+```
+
+The key is the setting name **your** policies read. The value names which piece
+of Ablo's authenticated identity fills it.
+
+## What Ablo sets on its own
+
+Every direct write runs inside a transaction that begins by setting this
+context, whether or not you map anything:
+
+| Setting | Carries |
+| --- | --- |
+| `app.current_org_id` | The organization the credential acts for |
+| `app.current_project_id` | The project |
+| `app.current_environment` | The environment |
+| `app.current_sandbox_id` | The sandbox, when the write is in one |
+| `app.current_participant_id` | The participant making the write |
+| `app.current_participant_kind` | Whether that participant is a person, an agent, or the system |
+| `app.current_user_id` | The person on whose behalf the write is made |
+
+If your policies read these names directly, you need no mapping at all — this
+page is for the case where they read different ones.
+
+`app.current_user_id` is worth reading twice, because it has three states rather
+than two. It carries a person's id when a person is behind the write. It carries
+`*` when a backend credential is acting as the organization itself, which is the
+authority a server-side key holds. And it carries the empty string when no
+identity could be established — written explicitly rather than left alone, so a
+policy on a pooled connection reads absence as absence and denies, instead of
+inheriting whatever the previous transaction left behind.
+
+## What a mapping may name
+
+The value side is a closed set, and every member is resolved by Ablo from the
+authenticated key and the plane:
+
+`orgId` · `projectId` · `environment` · `sandboxId` · `participantId` ·
+`participantKind`
+
+Because none of them come from the caller, a mapping can forward the tenant
+identity Ablo already trusts, but cannot widen what a writer sees. A setting name
+takes exactly one source — the name is the key — so naming the same setting twice
+is unrepresentable rather than something to resolve later.
+
+## What a mapping may not name
+
+The settings in the table above, along with `row_security`, `search_path`,
+`statement_timeout`, and `lock_timeout`, are reserved. `defineSchema` rejects a
+mapping onto any of them, and the engine refuses one at write time too.
+
+The reason is worth stating plainly: those settings are how Ablo bounds its own
+write. A schema that could reassign them could relax the scoping under which
+Ablo writes, which would put the boundary inside the thing being bounded. Point
+your policies at a name you own — `app.current_org` rather than
+`app.current_org_id` — and map that.
+
+## Reads served from the log
+
+One arrangement cannot honour a policy that names a person. When a plane is
+served from its retained log rather than from its tables, every row carries the
+organization and the project, but not the owner — so a rule about who owns a row
+has nothing to act on.
+
+Rather than fold those rows and return a plausible answer, such a read is
+declined whole with `user_scope_not_enforced`: a member reading a colleague's
+private records would otherwise be indistinguishable from a member reading their
+own. Reads made by a credential acting for the organization are unaffected, as is
+every plane served from its tables.
+
+## Related
+
+- [Data Sources](./data-sources.md) — the writer role's privileges, and what it
+  can and cannot do to your database.
+- [Operating on Your Database](./operating-on-your-database.md) — which actions
+  are read-only, which are reversible, and which belong to a human.

package/docs/sessions.md

@@ -1,5 +1,7 @@
 # Sessions
 
+> Short-lived scoped credentials your backend mints for a browser or an agent.
+
 A **session** is a short-lived credential your backend mints with its `sk_` and
 hands to one actor — a signed-in **person's browser** or a scoped **agent**. It's
 the same primitive in both cases (backend-minted, short-lived, scoped); the only
@@ -16,7 +18,7 @@ const userSession = await ablo.sessions.create({
 // A scoped agent session — gated to exactly the operations you name.
 const agentSession = await ablo.sessions.create({
   agent: { id: 'agent:task-writer' },
-  can: { Task: ['read', 'update'], Deck: ['read'] },
+  can: { Task: ['read', 'update'], Workspace: ['read'] },
 });
 ```
 

package/docs/webhooks.md

@@ -1,7 +1,9 @@
 # Webhooks
 
+> Stream the committed transaction log to your own systems as signed events.
+
 Ablo keeps an ordered transaction log of every committed change and coordinates
-the writers — people and agents — that produce it. Your rows live in your own
+the writers — agents, and the people alongside them — that produce it. Your rows live in your own
 database; Ablo holds only the log. **Webhooks stream that log to your systems as
 signed events:** every committed change is POSTed to an endpoint in your app, and
 your handler decides what to do with it.