@abloatai/ablo 0.7.0 → 0.9.0

package/docs/mcp/claude-code.md

@@ -3,22 +3,12 @@
 ## Install
 
 ```bash
-claude mcp add --transport http ablo-sync https://<your-app>/api/mcp
+claude mcp add --transport http ablo https://<your-app>/api/mcp
 ```
 
-That's it. The next `/help` in Claude Code will list the Ablo Sync tools.
-
-## With auth
-
-If your deployment requires a scoped bearer token (production setups should):
-
-```bash
-claude mcp add --transport http ablo-sync https://<your-app>/api/mcp \
-  --header "Authorization=Bearer $ABLO_MCP_TOKEN"
-```
-
-Create a session-scoped bearer token from your server or dashboard — see
-[MCP overview](/docs/mcp#auth).
+That's it — no token or header needed. The endpoint is public and serves
+only docs, schema lint, and scaffolds. The next `/help` in Claude Code will
+list the Ablo Sync tools.
 
 ## Verify
 
@@ -28,16 +18,18 @@ In Claude Code, run:
 /mcp list
 ```
 
-You should see `ablo-sync` with the model tools enumerated.
+You should see `ablo` with the integration tools enumerated:
+`search_ablo_docs`, `get_recipe`, `get_api_surface`, `validate_schema`,
+`scaffold_app`.
 
 ## Removing
 
 ```bash
-claude mcp remove ablo-sync
+claude mcp remove ablo
 ```
 
 ## More
 
-- [MCP overview](/docs/mcp) — how the transport works.
-- [Cursor setup](/docs/mcp/cursor) — same JSON, different UI.
-- [Windsurf setup](/docs/mcp/windsurf) — same JSON, different UI.
+- [MCP overview](/docs/mcp) — what the server exposes and how the transport works.
+- [Cursor setup](/docs/mcp/cursor) — same URL, different UI.
+- [Windsurf setup](/docs/mcp/windsurf) — same URL, different UI.

package/docs/mcp/cursor.md

@@ -7,7 +7,7 @@ Add the Ablo Sync MCP server to Cursor's `mcp.json`:
 ```json
 {
   "mcpServers": {
-    "ablo-sync": {
+    "ablo": {
       "transport": "http",
       "url": "https://<your-app>/api/mcp"
     }
@@ -15,39 +15,21 @@ Add the Ablo Sync MCP server to Cursor's `mcp.json`:
 }
 ```
 
-The file lives at `~/.cursor/mcp.json` on macOS / Linux.
+The file lives at `~/.cursor/mcp.json` on macOS / Linux. No auth header is
+needed — the endpoint is public and serves only docs, schema lint, and
+scaffolds.
 
 Restart Cursor. The Ablo Sync tools appear under the MCP icon in the agent
 panel.
 
-## With auth
-
-Add a `headers` block:
-
-```json
-{
-  "mcpServers": {
-    "ablo-sync": {
-      "transport": "http",
-      "url": "https://<your-app>/api/mcp",
-      "headers": {
-        "Authorization": "Bearer $ABLO_MCP_TOKEN"
-      }
-    }
-  }
-}
-```
-
-Cursor expands shell-style env vars in this block. Set `ABLO_MCP_TOKEN`
-in your shell config.
-
 ## Verify
 
 In Cursor's agent panel, open the MCP tools list. You should see the
-Ablo Sync model tools and their JSON schemas.
+Ablo Sync integration tools and their JSON schemas: `search_ablo_docs`,
+`get_recipe`, `get_api_surface`, `validate_schema`, `scaffold_app`.
 
 ## More
 
-- [MCP overview](/docs/mcp) — how the transport works.
+- [MCP overview](/docs/mcp) — what the server exposes and how the transport works.
 - [Claude Code setup](/docs/mcp/claude-code) — CLI install.
 - [Windsurf setup](/docs/mcp/windsurf) — same JSON shape.

package/docs/mcp/windsurf.md

@@ -7,7 +7,7 @@ Add the Ablo Sync MCP server to Windsurf's MCP config:
 ```json
 {
   "mcpServers": {
-    "ablo-sync": {
+    "ablo": {
       "transport": "http",
       "url": "https://<your-app>/api/mcp"
     }
@@ -16,31 +16,18 @@ Add the Ablo Sync MCP server to Windsurf's MCP config:
 ```
 
 The config path differs by platform — Windsurf surfaces it in Settings →
-Cascade → MCP. Restart Windsurf after saving.
-
-## With auth
-
-```json
-{
-  "mcpServers": {
-    "ablo-sync": {
-      "transport": "http",
-      "url": "https://<your-app>/api/mcp",
-      "headers": {
-        "Authorization": "Bearer $ABLO_MCP_TOKEN"
-      }
-    }
-  }
-}
-```
+Cascade → MCP. Restart Windsurf after saving. No auth header is needed —
+the endpoint is public and serves only docs, schema lint, and scaffolds.
 
 ## Verify
 
 Cascade's MCP panel lists every configured server with its tools. You
-should see `ablo-sync` with model tools enumerated.
+should see `ablo` with the integration tools enumerated:
+`search_ablo_docs`, `get_recipe`, `get_api_surface`, `validate_schema`,
+`scaffold_app`.
 
 ## More
 
-- [MCP overview](/docs/mcp) — how the transport works.
+- [MCP overview](/docs/mcp) — what the server exposes and how the transport works.
 - [Claude Code setup](/docs/mcp/claude-code) — CLI install.
 - [Cursor setup](/docs/mcp/cursor) — same JSON shape.

package/docs/mcp.md

@@ -1,44 +1,121 @@
 # Model Context Protocol
 
-Ablo ships an MCP server at `/api/mcp`. Connect any MCP-compatible AI
-assistant — Claude Code, Cursor, Windsurf — and your sync models become
-typed, callable tools.
+Ablo publishes **two** MCP servers for two different jobs. Don't confuse them:
 
-## Install
+| 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` |
+| **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 |
 
-Pick your client:
+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
+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`)
+
+The coordination server is the MCP projection of the model-scoped 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.**
+
+Install over stdio; set your key in the host's MCP env:
+
+```bash
+claude mcp add ablo -- npx -y @ablo/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:
+
+| Tool | Mirrors | Does |
+|---|---|---|
+| `get_model` | `ablo.<model>.get(id)` | read latest state + active claims |
+| `list_models` | `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 |
+
+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`).
+
+## Integration-helper server
+
+If you're integrating `@abloatai/ablo` with the help of an AI coding
+assistant (Claude Code, Cursor, Windsurf, Codex), you don't want it guessing
+at the API. This hosted server lets the assistant search the real docs,
+inspect the actual export surface, lint your schema, and scaffold a starter —
+so the code it writes uses APIs that exist. It serves docs only and returns
+nothing org-specific; data access happens through the SDK or the coordination
+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.
+
+### Install
+
+Point your assistant at the hosted endpoint — no auth, no token:
+
+```bash
+claude mcp add --transport http ablo https://<your-app>/api/mcp
+```
+
+Per-client walkthroughs:
 
 - [Claude Code](/docs/mcp/claude-code)
 - [Cursor](/docs/mcp/cursor)
 - [Windsurf](/docs/mcp/windsurf)
 
-## How it works
+### What it exposes
 
-Each model you declare becomes one or more MCP tools:
+#### Tools
 
-| Model method | MCP tool name | What it does |
-|---|---|---|
-| `retrieve` | `<model>.retrieve` | Returns the row + a stamp. |
-| `list` | `<model>.list` | Cursor-paginated discovery. |
-| `update` | `<model>.update` | Write, requires the prior stamp. |
-| `<model>.claim` | `claim.create` | Claim a row before writing, then release when held work finishes. |
+| Tool | What it does |
+|---|---|
+| `search_ablo_docs` | Keyword search across the docs corpus. Returns ranked matches with excerpts. Follow up with `get_recipe` on the top hit. |
+| `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 `managed` or `data-source` storage. |
+
+#### Resources
+
+Every doc file is addressable at `ablo://docs/{name}`, so a
+client can list the corpus and fetch individual files on demand instead of
+loading everything into context.
+
+#### Prompts
 
-The assistant gets typed JSON schemas, real argument types, and typed
-rejections when it writes stale state. No invention, no hallucinated IDs.
+Reusable, parameterised templates that drive an end-to-end flow:
 
-## Auth
+- `integrate-sync-engine` — wire the SDK into an existing project.
+- `add-agent` — add an agent worker that coordinates via intents and
+  conflict-safe writes.
+- `define-schema` — design a Zod-first schema from a description, then run
+  `validate_schema` before committing.
 
-The MCP transport uses a scoped bearer token issued by your server. Pass that
-token into the MCP client's auth header configuration. See your client's setup
-guide for the exact mechanism.
+### Transport and limits
 
-## Limits
+The endpoint uses the stateless Streamable HTTP transport (`POST /api/mcp`;
+`GET` returns 405 — SSE is not supported in stateless mode). A fresh
+server is built per request, which suits serverless and horizontally-scaled
+deployments.
 
-The MCP endpoint is rate-limited per token. Read-heavy bursts are fine;
-write-heavy bursts get throttled at the dashboard-configured cap.
+There is **no authentication**: the server only serves docs, schema lint,
+and scaffolds, so there's nothing org-scoped to protect. Abuse is bounded
+by IP-based rate limiting — 120 requests per minute per IP. Rate-limit
+headers are echoed on every response.
 
-## More
+### Where it lives
 
-The [MCP landing page](/mcp) has the product pitch. The route handler
-itself is at `apps/sync-web/src/app/api/mcp/route.ts` if you want to read
-the implementation.
+- Route handler: `apps/sync-web/src/app/api/mcp/route.ts`
+- Server setup: `apps/sync-web/src/lib/mcp-ablo/server.ts`
+  (`createSyncEngineMcpServer`)
+- Tools: `apps/sync-web/src/lib/mcp-ablo/tools/`

package/docs/quickstart.md

@@ -1,29 +1,26 @@
 # Quickstart
 
-Declare your state, create one row, and make one confirmed update.
+Start building with Ablo in two steps: install, then declare one model and write
+through its generated client.
 
 If you already have a backend and database, still start here. The SDK call shape
 is the same; [Integration Guide](./integration-guide.md) explains when to use
 Ablo-managed state versus a Data Source that calls your existing API service.
 
-## 1. Install
+## 1. Install and set a sandbox key
 
 ```bash
 npm install @abloatai/ablo
-```
-
-## 2. Set a Sandbox Key
-
-Use an Ablo sandbox key while integrating.
-
-```bash
 export ABLO_API_KEY=sk_test_...
 ```
 
 `ABLO_API_KEY` is for trusted server runtimes. Browser apps should use the React
 provider with a scoped session route, not a bundled API key.
 
-## 3. Declare a Schema
+## 2. Declare schema and write state
+
+Your schema is the contract. It generates `ablo.<model>` methods for app code,
+server actions, agents, React reads, and Data Source requests.
 
 ```ts
 import Ablo from '@abloatai/ablo';
@@ -41,25 +38,21 @@ export const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
 });
-```
-
-Customer apps should always pass `schema`. Treat it like Prisma's schema file:
-it is the source of truth for typed model clients, realtime subscriptions,
-agent writes, and Data Source requests.
-
-## 4. Create and Update
-
-```ts
 await ablo.ready();
 
 const created = await ablo.weatherReports.create({
-  location: 'Stockholm',
-  status: 'pending',
+  data: {
+    location: 'Stockholm',
+    status: 'pending',
+  },
 });
 
-const updated = await ablo.weatherReports.update(created.id, {
-  status: 'ready',
-  forecast: 'Light rain, 13C',
+const updated = await ablo.weatherReports.update({
+  id: created.id,
+  data: {
+    status: 'ready',
+    forecast: 'Light rain, 13C',
+  },
 });
 
 console.log({ id: updated.id, status: updated.status });
@@ -71,77 +64,86 @@ Expected output:
 { id: '...', status: 'ready' }
 ```
 
-## 5. Run the Example
+## Run the example
 
 ```bash
-cd examples
-ABLO_API_KEY=sk_test_... npx tsx quickstart.ts
+cd packages/sync-engine
+ABLO_API_KEY=sk_test_... npx tsx examples/quickstart.ts
 ```
 
-## 6. AI Activity on Existing State
+## Add coordination for slow work
 
 When AI or background work will touch an existing row for more than a quick
-write, coordinate through the flat model verbs: `ablo.<model>.claim(id, ...)` to
-claim the row (returns the row), `ablo.<model>.claimState(id)` to read who's working
-on it (synchronous; never blocks), and the normal `ablo.<model>.update(id, ...)`
-to write. Normal reads still work while the claim is held; server reads can opt
-into `ifClaimed: 'wait'` or `ifClaimed: 'fail'` when they should not read through
-active work. The callback form releases the claim when the callback returns or
-throws.
+write, coordinate through `claim({ id })`. It claims the row and hands a handle
+back; `claim.state({ id })` reads who is currently working on it without blocking;
+and you write the usual way with `ablo.<model>.update({ id, data })`.
+
+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. Normal reads still work while the claim is held. If a server read
+should not return a row while someone else is mid-edit, pass `ifClaimed: 'wait'`
+to wait for the claim to clear, or `ifClaimed: 'fail'` to error out instead.
+Call `handle.release()` when your work is done.
 
 ```ts
 // Claim the row so other participants serialize behind us while we work.
-await ablo.weatherReports.claim(
-  'weather_stockholm',
-  async (report) => {
-    // Your existing weather tool or agent call. While this runs, other clients
-    // see that weather_stockholm is being checked.
-    const weather = await weatherAgent.getWeather(report.location);
-
-    await ablo.weatherReports.update(report.id, {
-      status: 'ready',
-      forecast: weather.summary,
-    });
+const handle = await ablo.weatherReports.claim({
+  id: 'weather_stockholm',
+  action: 'checking_weather',
+  ttl: '2m',
+});
+
+// Your existing weather tool or agent call. While this runs, other clients
+// see that weather_stockholm is being checked.
+const weather = await weatherAgent.getWeather(handle.data.location);
+
+await ablo.weatherReports.update({
+  id: handle.data.id,
+  data: {
+    status: 'ready',
+    forecast: weather.summary,
   },
-  { action: 'checking_weather', ttl: '2m' },
-);
+});
+
+await handle.release();
 ```
 
-Ablo does not fetch the weather. The claim is **advisory**: if another
-participant already holds the row, `claim` waits for them to finish and re-reads
-before handing back the row. While you hold the claim, `update(id, ...)` is
-stale-guarded and rejects with `AbloStaleContextError` if the row changed under
-you. The claim releases automatically once the callback returns or throws.
+Ablo does not fetch the weather. If another participant already holds the row,
+`claim` waits for them to finish, re-reads, and then hands you the fresh row.
+While you hold the claim, `update({ id, data })` rejects with `AbloStaleContextError`
+if someone else changed the row first — so you never overwrite work you didn't
+see. Call `handle.release()` once your work is done.
 
-## 7. Multiplayer and Claimed Work
+## Multiplayer and claimed work
 
 There is no separate multiplayer mode. Use the same schema client for human UI,
 server actions, and agents; Ablo fans out confirmed writes and keeps active
 claims visible on the same model row.
 
-`claimState(id)` tells you when another human or agent is active on the same row.
-For schema clients, `claim(id, work)` waits fairly, re-reads, and then lets you
+`claim.state({ id })` tells you when another human or agent is active on the same row.
+For schema clients, `claim({ id })` waits fairly, re-reads, and then lets you
 write through the model.
 
 ```ts
-const active = ablo.weatherReports.claimState('weather_stockholm');
+const active = ablo.weatherReports.claim.state({ id: 'weather_stockholm' });
 if (active) {
   console.log(`${active.heldBy} is ${active.action}`);
 }
 
-await ablo.weatherReports.claim('weather_stockholm', async (report) => {
-  await ablo.weatherReports.update(report.id, { status: 'ready' });
-});
+const handle = await ablo.weatherReports.claim({ id: 'weather_stockholm' });
+await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' } });
+await handle.release();
 ```
 
 Use `{ wait: false }` on `claim` when work should be skipped instead of queued
 behind an active holder.
 
-## 8. Next Steps
+## Next steps
 
 Keep using the schema client for app and agent writes.
 
 - [Integration Guide](./integration-guide.md) explains the full app, React, Data Source, multiplayer, and agent path.
+- [Schema Contract](./schema-contract.md) explains what the schema drives across SDK, React, agents, Data Source, and schema push.
 - [Guarantees](./guarantees.md) explains what confirmed writes and stale checks mean.
 - [Client Behavior](./client-behavior.md) covers errors, retries, and public imports.
 - [Connect Your Database](./data-sources.md) covers the optional route for teams keeping rows in their own database.

package/docs/react.md

@@ -56,7 +56,7 @@ export function Providers({
 | `url`               | hosted endpoint        | WebSocket URL of the sync server (`wss://…`). Hosted apps omit it.                                         |
 | `apiKey`            | session/cookie         | Bootstrap auth. Browser apps **omit this** — the key stays server-side. See Identity below.               |
 | `fallback`          | neutral spinner        | Rendered during the *first* bootstrap only. Pass a branded skeleton, `null`, or `'passthrough'`.          |
-| `bootstrapMode`     | `'full'`               | `'full'` pulls the org's baseline before ready; `'none'` skips the baseline and processes live deltas only.|
+| `bootstrapMode`     | `'full'`               | `'full'` loads existing rows before the app renders, so reads are populated on first paint; `'none'` skips that initial load and only streams changes as they happen.|
 | `persistence`       | `'volatile'`           | `'indexeddb'` opts into a durable browser cache that survives reloads.                                     |
 | `onSessionExpired`  | —                      | Fired after the engine has already purged on a rejected session — use for redirect-to-sign-in.            |
 | `onError`           | —                      | Engine / WebSocket / `postBootstrap` errors. Wire to Sentry / Datadog.                                    |
@@ -74,8 +74,8 @@ reaches the browser, is the whole of
 import { useAblo } from '@abloatai/ablo/react';
 
 export function ReportView({ report: serverReport }: { report: { id: string; location: string } }) {
-  const report = useAblo((ablo) => ablo.weatherReports.retrieve(serverReport.id)) ?? serverReport;
-  const active = useAblo((ablo) => ablo.weatherReports.claimState(serverReport.id));
+  const report = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
   const claimed = Boolean(active);
 
   return <article>{report.location}</article>;
@@ -84,12 +84,13 @@ export function ReportView({ report: serverReport }: { report: { id: string; loc
 
 The hook:
 
-1. Reads through the same `ablo.<model>` methods as the rest of the SDK.
+1. Uses the same `ablo.<model>.get(id)` / `.getAll()` 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.
 3. Lets Server Component data stay outside the hook: use `?? serverReport` when a
    parent already loaded the row.
-4. Works for coordination state too, such as `ablo.weatherReports.claimState(id)`.
+4. Works for coordination state too, such as `ablo.weatherReports.claim.state({ id })`.
 
 Use the zero-argument form only when you need the full client for callbacks,
 effects, or writes:
@@ -98,15 +99,14 @@ effects, or writes:
 const abloClient = useAblo();
 ```
 
-Prefer selector reads like `useAblo((ablo) => ablo.<model>.retrieve(id))`.
-String model names are kept on older hooks for compatibility, but first examples
-should use the same model-client shape as the rest of the SDK.
+Prefer selector reads like `useAblo((ablo) => ablo.<model>.get(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.list({
+  ablo.weatherReports.getAll({
     where: { projectId },
     filter: (report) => report.status !== 'ready',
     state: 'live',
@@ -117,10 +117,14 @@ const reports = useAblo((ablo) =>
 ## Server Load
 
 ```tsx
-const [report] = await ablo.weatherReports.load({ where: { id } });
+const report = await ablo.weatherReports.retrieve({ id });
 ```
 
-Use `load` in Server Components when the row may not be in the local pool yet.
+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.)
 
 ## Writes
 
@@ -130,7 +134,9 @@ For Server Actions and route handlers, call the SDK directly:
 import { ablo } from '@/lib/ablo';
 
 const snap = ablo.snapshot({ weatherReports: id });
-await ablo.weatherReports.update(id, patch, {
+await ablo.weatherReports.update({
+  id,
+  data: patch,
   readAt: snap.stamp,
   onStale: 'reject',
   wait: 'confirmed',
@@ -146,11 +152,13 @@ const ablo = useAblo();
 async function markReady() {
   if (!ablo) return;
   const snap = ablo.snapshot({ weatherReports: id });
-  await ablo.weatherReports.update(
+  await ablo.weatherReports.update({
     id,
-    { status: 'ready' },
-    { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
-  );
+    data: { status: 'ready' },
+    readAt: snap.stamp,
+    onStale: 'reject',
+    wait: 'confirmed',
+  });
 }
 ```
 

package/docs/roadmap.md

@@ -5,22 +5,22 @@ What is shipped, what is next, and what we will not build.
 ## Shipped
 
 - **Models, claims, commits** — the core API.
-- **Audit log** — hash-chained per principal, with `delegationChainRoot`.
+- **Audit log** — a tamper-evident, hash-chained record of who did what,
+  per principal.
 - **MCP transport** — HTTP server at `/api/mcp`.
 - **TypeScript SDK** — `@abloatai/ablo`, with React bindings.
 - **Dashboard** — keys, audit, metrics, allowed origins.
-- **Schema migrations** — declarative model schema changes. Pure
-  diff/classify/cast-safety/backfill planning engine (`diffSchema`,
-  `classifyMigration`, `classifyCast`, `isAutoApplicable`) ships in the SDK;
-  `ablo generate` emits typed clients from a pushed schema; the server
-  applies and activates migrations only on success.
-- **Structured error contract** — versioned (`ERROR_CONTRACT_VERSION`),
-  drift-guarded code registry shared across the HTTP, WebSocket, and MCP
-  planes, with always-on request ids and an OpenAPI error envelope.
-- **Relation-driven sync groups** — membership-routed fan-out via branded
-  `SyncGroup` + schema-declared identity roles (schema-JSON v2).
-- **Intent coordination plane** — Stripe-shaped `Intent` with per-model
-  `intent(id)` handles for lease/await/commit coordination between agents.
+- **Schema migrations** — change a model's shape after it already has data.
+  Ablo plans the migration, tells you which changes are safe to auto-apply,
+  and backfills the rest; the server applies and activates a migration only
+  if it succeeds. `ablo generate` emits typed clients from a pushed schema.
+- **Structured errors** — every error has a stable code and a request id,
+  and the same codes work whether you reach Ablo over HTTP, WebSocket, or MCP.
+- **Sync groups** — clients automatically receive only the records they have
+  access to, based on relationships you declare in the schema.
+- **Agent coordination** — when several agents work on the same model, they
+  take turns instead of overwriting each other, via `intent(id)` handles
+  that claim, wait, and commit.
 
 ## In flight