@abloatai/ablo 0.34.1 → 0.35.0

package/docs/integration-guide.md

@@ -1,11 +1,13 @@
 # Integration Guide
 
-If humans and AI agents both edit the same records in your app, they overwrite
-each other and there's no good place to coordinate. Ablo gives them one shared,
-typed write path — the same `ablo.<model>.update(...)` call for a React
-component, a server action, a background worker, or an agent — and reconciles the
-edits. This guide adds it to a product that already has a backend and database,
-one model at a time.
+> The canonical end-to-end integration, added to an existing product one model at a time.
+
+When several AI agents edit the same records in your app — alongside any people
+watching them work — they overwrite each other, and there is no good place to
+coordinate. Ablo gives them one shared, typed write path: the same
+`ablo.<model>.update(...)` call from an agent, a background worker, a server
+action, or a React component. This guide adds it to a product that already has a
+backend and a database, one model at a time.
 
 Three things hold no matter which actor is writing:
 
@@ -79,7 +81,7 @@ and write path are ready for production.
 When handing this to a coding agent, give it a concrete target:
 
 ```txt
-Add Ablo to this app for one model that humans and agents both edit.
+Add Ablo to this app for one model your agents edit.
 Use the org sandbox sk_test_* key. Declare schema, add the Ablo client, replace
 one write with ablo.<model>.update(..., { readAt, onStale: 'reject',
 wait: 'confirmed' }), and add a smoke test for two concurrent writers.
@@ -139,7 +141,6 @@ model(
   {
     /* fields */
   },
-  /* relations */ {},
   {
     // Axis 1 — `policy`: who may READ a row (tenant isolation / RLS). A
     // row-local `organization_id` column is the default, so you omit this for
@@ -256,7 +257,7 @@ refreshes before expiry.
 Reads come in two flavors, and you pick based on whether you can wait.
 `retrieve({ id })` and `list({ where })` hit the server (and hydrate the local
 store) — they're async, so you `await` them. `get(id)` (positional),
-`getAll({ where })`, and `getCount({ where })` read the already-synced local
+`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
 use inside a `useAblo` selector, never the async `retrieve`/`list`.
 
@@ -270,12 +271,12 @@ const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
 if (!report) throw new Error('report not found');
 ```
 
-Use `get`, `getAll`, and `getCount` for synchronous local-graph reads after
+Use `local.retrieve`, `local.list`, and `local.count` for synchronous local-graph reads after
 data has synced.
 
 ```ts
-const report = ablo.weatherReports.get('report_stockholm');
-const activeReports = ablo.weatherReports.getAll({
+const report = ablo.weatherReports.local.retrieve('report_stockholm');
+const activeReports = ablo.weatherReports.local.list({
   where: { projectId: 'proj_123' },
   filter: (report) => report.status !== 'ready',
   orderBy: { updatedAt: 'desc' },
@@ -295,7 +296,7 @@ export function ReportRow({
 }: {
   report: { id: string; location: string; status: 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 }));
 
   return <button disabled={Boolean(active) || report.status === 'ready'}>{report.location}</button>;
@@ -375,7 +376,7 @@ The migration can be gradual:
 
 1. Declare schema for one model, such as `reports`.
 2. Keep existing server loads for first paint.
-3. Add `useAblo((ablo) => ablo.weatherReports.get(id)) ?? serverReport` for live rows.
+3. Add `useAblo((ablo) => ablo.weatherReports.local.retrieve(id)) ?? serverReport` for live rows.
 4. Add one Data Source endpoint that calls the existing service layer.
 5. Move one mutation button from `fetch('/api/reports/...')` to `ablo.weatherReports.update(...)`.
 6. Add an outbox/events path for writes that still happen outside Ablo.
@@ -507,8 +508,8 @@ them.
 | `retrieve({ id })`                     | Async read of one row from the server (await it).                                |
 | `list({ where })`                      | Async read of many rows from the server (await it).                              |
 | `get(id)`                              | Synchronous local read of one synced row (positional id; use in render).         |
-| `getAll({ where })`                    | Synchronous local read of many synced rows.                                      |
-| `getCount({ where })`                  | Synchronous local count of synced rows.                                          |
+| `local.list({ where })`                | Synchronous local read of many synced rows.                                      |
+| `local.count({ where })`               | Synchronous local count of synced rows.                                          |
 | `create({ data, id? })`                | Create through the model client.                                                 |
 | `update({ id, data, ...opts })`        | Update through the model client.                                                 |
 | `delete({ id, ...opts })`              | Delete through the model client.                                                 |

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

@@ -1,5 +1,7 @@
 # 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
@@ -79,7 +81,7 @@ 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: 'manual'` mapping is often present
+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

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.