@abloatai/ablo 0.34.1 → 0.36.0

package/docs/index.md

@@ -1,103 +1,189 @@
 # Ablo Docs
 
-You have a database, and you want an AI agent to edit the same rows your
-users are editing — without the two clobbering each other's work. Ablo gives
-the agent a narrow, audited write path: you declare your models, then everyone
-(React components, server actions, and agents) calls the same
-`ablo.deck.update(...)`. Ablo streams confirmed changes to everyone live and
-rejects any write based on stale data.
+> Collaboration infrastructure for AI agents: one API for agents, apps, and services to claim, change, and confirm the same rows.
 
-The flow is four steps: declare your models, read the current rows, claim the
-row you're about to change, then write — and the write is rejected if someone
-changed the row first.
+Two agents reach for the same row. One claims it, does slow work — an LLM call,
+a fetch, a chain of tools — and commits. The second is neither rejected nor
+allowed to clobber: it waits in line, is handed the row as it now stands, and
+proceeds. Contention becomes an ordering problem instead of a retry loop.
 
 ```ts
-// The same call, whether a person, a server action, or an agent makes it.
-await ablo.deck.update({ id: deckId, data: { title: "Q3 Strategy" } });
+// Take the row. Anyone else who wants it waits, then reads it fresh.
+await using claim = await ablo.reports.claim({ id: reportId });
+
+await ablo.reports.update({
+  id: claim.data.id,
+  data: { forecast: await generateForecast(claim.data) },
+  wait: 'confirmed',
+});
 ```
 
-Claims don't lock. If another writer holds the row, `claim` waits for them,
-re-reads the fresh row, then hands it to you — so two writers serialize
-instead of clobbering.
-
-## What you get
-
-Three things stay true no matter how you use Ablo:
-
-- **One model API for every actor.** `ablo.<model>.update(...)` is the
-  call from React components, server actions, background workers, and
-  AI agents alike. No separate "agent SDK," no parallel mutation path.
-  Attribution comes from the credential, not the call site.
-- **You declare tenancy scopes once.** Tenancy / per-entity scope
-  prefixes (`org:`, `deck:`, or your own `region:` / `customer:`) are
-  declared once on the schema's `identityRoles`, so application code
-  never builds an `org:123` string by hand — which keeps tenant
-  boundaries from leaking.
-- **Stale writes are rejected.** If the row changed after you read it,
-  your write is turned away instead of silently overwriting the change
-  you didn't see.
-
-## Start here
-
-- [Quickstart](./quickstart.md) — Make your first schema-backed write.
-- [Schema Contract](./schema-contract.md) — One schema becomes typed model clients, React reads, agent writes, Data Source shape, and schema push.
-- [CLI & Migrations](./cli.md) — `init` / `migrate` / `push` / `generate`, the shared Zod→Postgres type map, and structured migration errors.
-- [Identity & Sync Groups](./identity.md) — Use your own authentication; tell Ablo who's connecting and how org / team / user map to sync-group scope.
-- [Integration Guide](./integration-guide.md) — Connect your database via Data Source, plus React, multiplayer, and agent patterns.
-- [Guarantees](./guarantees.md) — What confirmed writes, stale checks, and claims guarantee.
-- [Interaction Model](./interaction-model.md) — The schema, claim, update, confirmation loop.
-- [API Reference](./api.md) — Model-by-model method shape.
-- [Client Behavior](./client-behavior.md) — Options, errors, retries, timeouts, and imports.
-- [Debugging & Logs](./debugging.md) — Turn on the `[Ablo]` coordination trace (`debug` / `logLevel`) to watch claims, queueing, and grants while you build — or read the same activity in code via `ClaimLog` to render an activity feed.
-- [Connect Your Database](./data-sources.md) — Keep canonical rows in your app database without giving Ablo database credentials.
-- [Operating on Your Database](./operating-on-your-database.md) — Which actions run freely, which to verify first, and which belong to a human — and how to tell.
-- [React](./react.md) — Provider, hooks, and reactive reads for React apps.
-- [API Keys](./api-keys.md) — Bearer tokens for the public API.
-
-## API shape
-
-| Plane | Primitives | Purpose |
-|---|---|---|
-| State | `Schema`, `Model`, `Claim`, `Receipt` | The product path. Load, coordinate, write, confirm. |
-| Storage | `Data Source` | Your rows live in your own database behind a signed Data Source endpoint. |
-
-## Use cases
-
-- **Let agents write to shared state** — Give an AI agent scoped, revocable write access to your typed data.
-- **Coordinate multiple actors** — Use claims to show pre-write work across humans and agents.
-- **Audit every agent action** — Trace any write back to a human in one query.
-- **Build collaborative editors** — Humans and agents on the same record, with realtime updates and stale-read protection.
-- **Meter and gate API usage** — Per-key, per-team usage reports and quota enforcement.
-- **Integrate with A2A and MCP** — Speak the same protocols as Claude, Cursor, Gemini.
+Claims do not lock. A lock is held against a caller who may never come back; a
+claim is a durable lease with a wait-line behind it, so you can always ask who
+holds a row and who is queued for it. The write returns a receipt, and a write
+based on a row that has since changed is turned away rather than applied.
 
-## Concepts
+## What people build
 
-- [Schema Contract](./schema-contract.md) — What the schema drives across SDK, React, agents, Data Source, and migrations.
-- [Model Methods](./api.md#model-methods) — Load and write typed state.
-- [Integration Guide](./integration-guide.md) — The normal app path and optional pieces.
-- [Guarantees](./guarantees.md) — Confirmed writes, optimistic state, stale-write protection, and agent lifecycle.
-- [Coordination](./coordination.md) — `claim`, `claim.state`, and `claim.queue` for active work.
-- [Connect Your Database](./data-sources.md) — Where data lands when your app database is canonical.
-- [Operating on Your Database](./operating-on-your-database.md) — The safety model for working on a live database: reversible model writes vs. human-gated DDL, and the read-only checks that resolve the doubt.
-- [Receipt](./api.md#receipt) — Confirm what landed.
-- [Usage](./api.md#usage) — Metering and audit dimensions.
-- [Audit Log](./audit.md) — Trace any confirmed write back to the human behind it.
-- [MCP](./mcp.md) — Expose Ablo models to MCP clients (Claude, Cursor).
+<Columns>
+  <Card title="Run agents in parallel" icon="users" href="/coordination">
+    Many agents over one dataset. Claims put them in a line instead of a race.
+  </Card>
+
+  <Card title="Hand work between agents" icon="arrow-left-right" href="/agent-messaging">
+    One agent claims, works, releases. The next picks up with the fresh row and a durable note about why.
+  </Card>
 
-## Examples
+  <Card title="Scope what an agent may write" icon="key-round" href="/api-keys">
+    A revocable key bound to one project's models. Attribution comes from the credential, not the call site.
+  </Card>
+
+  <Card title="Confirm what landed" icon="receipt" href="/guarantees">
+    Every write returns a receipt. Nothing is fire-and-forget, and stale writes are rejected.
+  </Card>
+
+  <Card title="Audit every agent action" icon="scroll-text" href="/audit">
+    Trace any committed change back to the key that made it, and to the person who authorized that key.
+  </Card>
+
+  <Card title="Keep a person in the loop" icon="hand" href="/react">
+    Add the `humans()` plugin and people get presence and live queries. A person's claim is just another holder the agent waits behind.
+  </Card>
+</Columns>
+
+## Using Ablo
+
+<Steps>
+  <Step title="Declare the models agents share">
+    `npx ablo init` scaffolds `ablo/schema.ts`, the typed client, and the type registration.
+    Declare only the models agents coordinate over — your auth, billing, and everything else
+    stay in your own migrations.
+
+    ```bash
+    npx ablo init && npx ablo push
+    ```
+
+    `push` is the step everything depends on: the server keeps its own copy of the schema, and
+    until it has yours, a write to a new model fails with `server_execute_unknown_model`.
+  </Step>
+
+  <Step title="Connect the database the rows live in">
+    Ablo writes through a scoped role and confirms by tailing your write-ahead log. It runs no
+    DDL and owns no schema — your migration tool stays in charge of the shape of your database.
+
+    ```bash
+    npx ablo connect
+    ```
+
+    No database yet? Pass an `apiKey` only and Ablo keeps the rows in its own log, so you can
+    build the whole system today and point it at Postgres when you are ready.
+  </Step>
+
+  <Step title="Build with Ablo">
+    You are writing the agent yourself — a worker, a job handler, a tool inside a model loop.
+    Agents hold no socket; the credential is the identity.
+
+    ```ts
+    const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: 'http' });
+    ```
+
+    Read with `list` / `retrieve`, coordinate with `claim`, write with `create` / `update` /
+    `delete`. See [Agents](./agents.md) for the loop and [API Reference](./api.md) for the shape.
+  </Step>
 
-- [AI SDK Tool](./examples/ai-sdk-tool.md) — Put Ablo inside an AI SDK tool call.
-- [Existing Python Backend](./examples/existing-python-backend.md) — Add multiplayer and future agent writes without replacing a Python API server.
-- [Agent + Human](./examples/agent-human.md) — Yield when a human is editing the same report.
-- [Server Agent](./examples/server-agent.md) — Schema-backed worker.
-- [Next.js](./examples/nextjs.md) — App-router setup with React bindings.
+  <Step title="Or point an MCP host at it">
+    The agent is Claude, Cursor, or another MCP host, and you want it operating your data
+    directly. The coordination server exposes the same claim-and-commit loop as tools.
 
-## Runtime builds
+    ```bash
+    claude mcp add ablo -- npx -y @abloatai/mcp
+    ```
 
-- `@abloatai/ablo` — schema-powered sync client for typed model operations, realtime claims, and receipts.
+    See [Model Context Protocol](./mcp.md) — and read the surface table below before you pick,
+    because Ablo publishes two MCP servers and only one of them is a data plane.
+  </Step>
+</Steps>
+
+## Surfaces
+
+Every surface reaches the same coordinated state. Pick by who is calling.
+
+| Surface | Use it for |
+|---|---|
+| **SDK**: `@abloatai/ablo`, `transport: 'http'` | The agents themselves. Stateless, request/response, nothing held open. The main path. |
+| **Coordination MCP**: `@abloatai/mcp` | An agent living inside an MCP host that needs claim and commit as tools. A data plane. |
+| **`humans()`**: with `@abloatai/ablo/react` | The interfaces a person watches agent work arrive in: presence, live queries, a local copy. |
+| **CLI**: `ablo` | Scaffolding, schema push, connecting a database. Terminals and CI. |
+| **REST**: `/api/v1` | Runtimes with no SDK. |
+| **Integration-helper MCP**: hosted `/api/mcp` | Teaching a coding assistant the SDK while you build. Docs, lint, and scaffolds only. |
+
+The two MCP servers are not interchangeable. The coordination server changes
+your data; the integration-helper server serves documentation and has no
+per-model data tools at all. An agent that edits rows uses the SDK or the
+coordination server — never the helper.
+
+### Where people fit
+
+The bare client is the coordination layer: commit, read, observe, claim. People
+are something you add to it. `humans()` is the plugin that declares the local,
+watchable copy — the offline store, live queries, presence, and the framework
+bindings — and it needs a duplex connection, so a stateless agent cannot install
+it and is told so at construction rather than left with a subscription that never
+delivers.
+
+There is no `agents()` plugin, and the absence is the point: agents are the
+default caller, not a special one.
+
+## Concepts
+
+- [How Ablo Works](./how-it-works.md) — the mental model in one page: you write through Ablo, it lands in your Postgres, the write-ahead log confirms it. **Read this first.**
+- [Coordination](./coordination.md) — `claim`, `claim.state`, and `claim.queue`: who holds a row, and who is waiting.
+- [Concurrency Convention](./concurrency-convention.md) — the governing rule for how concurrent writes resolve.
+- [Guarantees](./guarantees.md) — what a confirmed write, a stale-write rejection, and a claim each promise.
+- [Idempotency](./idempotency.md) — make a retried write safe; what replays, what re-runs, and for how long.
+- [Schema Contract](./schema-contract.md) — one schema becomes typed clients, agent writes, React reads, and the push.
+- [Agents](./agents.md) — the stateless participant: wake, read, claim, commit, idle.
+- [Agent Messaging](./agent-messaging.md) — durable handoffs between agents, linked to the claim they discuss.
+- [Identity & Sync Groups](./identity.md) — who is connecting, and which slice of state they see.
+- [Change Propagation](./groups.md) — how one row's change reaches the actors that depend on it.
+- [Client Behavior](./client-behavior.md) — options, errors, retries, timeouts, and imports.
+
+## Authority
+
+- [Projects](./projects.md) — one organization, many apps; each with its own schema, planes, and keys.
+- [API Keys](./api-keys.md) — the credential that carries an agent's identity and its scopes.
+- [Sessions](./sessions.md) — short-lived scoped credentials your backend mints.
+- [Audit Log](./audit.md) — trace any confirmed write back to the person behind it.
+- [Operating on Your Database](./operating-on-your-database.md) — which actions run freely, which to verify first, and which belong to a human.
+- [Session Settings](./session-settings.md) — point your row-level-security policies at Ablo's writes, by naming the settings they already read.
+
+## Build
+
+- [Quickstart](./quickstart.md) — make your first coordinated write.
+- [Integration Guide](./integration-guide.md) — the canonical end-to-end integration.
+- [CLI & Migrations](./cli.md) — `init` / `connect` / `push` / `migrate` / `generate`.
+- [Connect Your Database](./data-sources.md) — where rows land when your own database is canonical.
+- [Deployment](./deployment.md) — the database, the keys, and the schema push that take an integration to production.
+- [React](./react.md) — provider, hooks, and reactive reads.
+- [Webhooks](./webhooks.md) — react to confirmed change from outside the SDK.
+- [Debugging & Logs](./debugging.md) — watch claims, queueing, and grants while you build.
+
+## Reference
+
+- [API Reference](./api.md) — model-by-model method shape.
+- [Errors](./errors.md) — the code registry, its categories, and what to do about each.
+- [Version History & Migration](./migration.md) — every breaking change and its migration.
+- [Changelog](../CHANGELOG.md) — what shipped recently.
+
+## Examples
+
+- [AI SDK Tool](./examples/ai-sdk-tool.md) — put Ablo inside a model's tool call.
+- [Agent + Human](./examples/agent-human.md) — yield when a person is holding the same report.
+- [Server Agent](./examples/server-agent.md) — a schema-backed worker.
+- [Existing Python Backend](./examples/existing-python-backend.md) — add coordination without replacing your API server.
+- [Next.js](./examples/nextjs.md) — app-router setup with React bindings.
 
 ## More
 
 - [README](../README.md) — product overview and first example.
-- [AGENTS.md](../AGENTS.md) — short installation guidance for coding assistants.
-- [Changelog](../CHANGELOG.md) — what shipped recently.
+- [AGENTS.md](../AGENTS.md) — installation guidance for coding assistants.

package/docs/integration-guide.md

@@ -1,15 +1,17 @@
 # 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:
 
-- **One model API for every actor.** `ablo.<model>.update(...)` is what
+- **One model API for every actor:** `ablo.<model>.update(...)` is what
   React components, server actions, background workers, and AI agents
   all call. No separate "agent SDK," no parallel mutation path. The
   attribution comes from the credential, not the call site.
@@ -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>;
@@ -350,8 +351,19 @@ server   -> ablo.weatherReports.update(...)
 Ablo coordinates those writes, fans out confirmed deltas, exposes active claims,
 and lets callers reject stale writes with `readAt`.
 
-Direct writes to your own database bypass that stream until your app reports the
-change through Data Source events.
+A write that reaches your database some other way still reaches connected
+clients. A `psql` session, a cron job, an admin tool, a legacy endpoint: Ablo
+tails your write-ahead log, so a change it did not make is picked up and fanned
+out like any other, attributed to the data source rather than to an agent.
+
+What such a write does not get is the coordination. It never entered the commit
+chokepoint, so no claim was checked, no `readAt` was compared, and no idempotency
+key was honoured. It can land on top of a row an agent is holding. Route anything
+that must respect a claim through `ablo.<model>`.
+
+On the [Data Source endpoint fallback](./data-sources.md) there is no replication
+stream to tail, and there the original caveat holds: a direct write stays
+invisible until your app reports it through Data Source events.
 
 ## 6. Existing API Backend
 
@@ -375,7 +387,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 +519,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/mcp.md

@@ -1,48 +1,73 @@
 # 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 |
 | `claim_model` | `ablo.<model>.claim({ id })` | acquire / queue a coordination lease |
-| `release_claim` | — | release the lease so others proceed |
+| `release_claim` |: | release the lease so others proceed |
 
 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
 
@@ -69,9 +94,9 @@ claude mcp add --transport http ablo https://<your-app>/api/mcp
 
 The endpoint is identical for every client — only the config surface differs:
 
-- **Claude Code** — run the `claude mcp add` command above; verify with `/mcp list`, remove with `claude mcp remove ablo`.
-- **Cursor** — add the server to `~/.cursor/mcp.json` (macOS / Linux), then restart.
-- **Windsurf** — add the same JSON via Settings → Cascade → MCP, then restart.
+- **Claude Code:** run the `claude mcp add` command above; verify with `/mcp list`, remove with `claude mcp remove ablo`.
+- **Cursor:** add the server to `~/.cursor/mcp.json` (macOS / Linux), then restart.
+- **Windsurf:** add the same JSON via Settings → Cascade → MCP, then restart.
 
 Cursor and Windsurf use the same config shape:
 
@@ -95,7 +120,7 @@ Each client then lists the Ablo tools (`search_ablo_docs`, `get_recipe`, `get_ap
 | `get_recipe` | Returns the full markdown of one doc by name (e.g. `readme`, `quickstart`, `schema-contract`, `integration-guide`, `api`, `guarantees`). |
 | `get_api_surface` | Returns the structured export list for an SDK subpath (`@abloatai/ablo`, `./react`, `./schema`, `./testing`, …). Call with no argument to list every subpath. |
 | `validate_schema` | Lints `defineSchema` source against the DSL rules (camelCase fields, lowercase model keys, `scope`/`grants` sync groups, valid `load` strategies, no legacy builders) and returns a structured issue list. Runs no code. |
-| `scaffold_app` | Emits a starter file tree for a schema-first integration — `next`, `node-agent`, or `plain`, with a `data-source` (your own database) endpoint. |
+| `scaffold_app` | Emits a starter file tree for a schema-first integration: `next`, `node-agent`, or `plain`, with a `data-source` (your own database) endpoint. |
 
 #### Resources