@abloatai/ablo 0.6.0 → 0.8.0

package/docs/integration-guide.md

@@ -1,39 +1,26 @@
 # Integration Guide
 
-Use this guide when you are adding Ablo to a real product, not a demo.
+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.
 
-## Why Ablo, before the API
-
-Ablo is a sync engine designed from the ground up for **humans and AI
-agents editing the same state at the same time**. That premise drives
-every design choice in this guide; if you only need server-to-server
-data syncing without agents in the loop, the trade-offs land elsewhere
-(Replicache, ElectricSQL, PowerSync are good answers for human-only
-real-time apps; Zero is a good answer for query-shaped sync).
-
-The shape of the SDK reflects three commitments:
+Three things hold no matter which actor is writing:
 
 - **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.
-- **Server owns the scope convention; client picks a subset by id.** The
-  `org:` / `user:` / `team:` (or your own `region:` / `customer:`)
-  prefixes live in the schema's `identityRoles` once, never typed by
-  consumer code. Same boundary Liveblocks (`prepareSession`), PowerSync
-  (named streams), and Zero (synced queries) settled on after the same
-  realization: clients that compose scope strings drift; servers that
-  derive scope from authed identity don't.
-- **Capabilities, not API keys, are how agents authenticate.** Static
-  API keys protect server-to-server humans. Agents get per-run,
-  per-scope, leased credentials with per-request signature verification
-  and instant revocation. The 2025-2026 AI-agent auth consensus
-  (OAuth 2.1 / MCP, AWS STS, Vault leases, Auth0 Token Vault) converged
-  on this shape. Capabilities are Ablo's instance.
-
-If you have already built a sync layer or an agent runtime, you know
-what each of those costs. This guide assumes you want them solved once,
-together, behind one client.
+- **You never type `org:123` in client code.** The server derives what each
+  caller can see from their authenticated identity, using the `identityRoles`
+  you declare once in the schema. The client just names which model and id it
+  wants. The `org:` / `user:` / `team:` (or your own `region:` / `customer:`)
+  prefixes live in the schema, never in consumer code.
+- **Agents don't use your account API key.** Each agent run gets a short-lived
+  credential scoped to just what that run can touch, verified per request and
+  revocable instantly. (See the Agents section below for the actual calls.)
 
 ## The integration in one diagram
 
@@ -49,7 +36,7 @@ Declare the models Ablo coordinates, then read and write through
 that same model path.
 
 ```txt
-schema -> ablo.<model>.load(...) -> ablo.<model>.update(...)
+schema -> ablo.<model>.list(...) -> ablo.<model>.update(...)
 ```
 
 Commits and receipts exist under the hood. Most apps do not create protocol
@@ -101,10 +88,10 @@ wait: 'confirmed' }), and add a smoke test for two concurrent writers.
 
 Start with fields and relations. Keep load strategies, indexing hints, and
 read-only/mutable shortcuts out of the first version unless you already need
-offline-heavy local cache behavior.
+them.
 
 ```ts
-// src/ablo.schema.ts
+// src/ablo/schema.ts
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema(
@@ -119,23 +106,15 @@ export const schema = defineSchema(
     }),
   },
   {
-    // Identity-anchored sync-group roles. The server walks these to
-    // build each participant's allowed subscription set from the
-    // resolved identity context. Templates and extractors are fully
-    // consumer-controlled — no hardcoded `org:` / `user:` convention
-    // anywhere in the engine. Omit `identityRoles` entirely if your
-    // schema doesn't need identity-derived scoping.
+    // Identity-anchored sync-group roles. The server walks these to build each
+    // participant's allowed subscription set from the resolved identity context.
+    // `kind` is the group prefix; `source` is the identity field to read — both
+    // consumer-controlled, no hardcoded `org:` / `user:` convention anywhere in
+    // the engine. Pure data (no closures), so the schema stays JSON-serializable.
+    // Omit `identityRoles` entirely if you don't need identity-derived scoping.
     identityRoles: [
-      {
-        kind: 'tenant',
-        template: 'org:{id}',
-        extract: (i) => (i.organizationId ? [String(i.organizationId)] : []),
-      },
-      {
-        kind: 'participant',
-        template: 'user:{id}',
-        extract: (i) => (i.userId ? [String(i.userId)] : []),
-      },
+      identityRole({ kind: 'org', source: 'organizationId' }),
+      identityRole({ kind: 'user', source: 'userId' }),
     ],
   }
 );
@@ -143,11 +122,15 @@ export const schema = defineSchema(
 
 ### Declaring scope on a model
 
-Per-row tenancy and per-entity sync-group anchors live on the
-`defineModel` (or `model(...)`) options. The two halves compose: the
-identity roles above produce a participant's _allowed_ set; the
-per-model options below define how rows are filtered server-side and
-which sync-group label each row fans out on.
+> **Canonical reference: [Identity & Sync Groups](./identity.md).** This is the
+> short version — `scope` (root), `parent` (containment), `grants` (membership),
+> and the model-form `scope` prop are all covered in depth there. Read it once;
+> this guide only shows the minimal shape inline.
+
+Per-row tenancy and per-entity sync-group anchors live on the `model(...)`
+options. The two halves compose: the identity roles above produce a
+participant's _allowed_ set; the per-model options below define how rows are
+filtered server-side and which sync-group each row fans out on.
 
 ```ts
 model(
@@ -159,9 +142,9 @@ model(
     // Rows carry organization_id and bootstrap filters on it.
     orgScoped: true,
 
-    // Per-entity sync-group anchor. Lets a scoped session narrow into
-    // one row's scope via `syncGroupFormat.replace('{id}', rowId)`.
-    syncGroupFormat: 'matter:{id}',
+    // Scope root: rows form the group `matter:<id>`. Children point at it with
+    // `relation.belongsTo('matters', 'matterId', { parent: true })` to inherit.
+    scope: 'matter',
   }
 );
 ```
@@ -178,7 +161,7 @@ Trusted runtimes can use `ABLO_API_KEY`.
 ```ts
 // src/ablo.ts
 import Ablo from '@abloatai/ablo';
-import { schema } from './ablo.schema';
+import { schema } from './ablo/schema';
 
 export const ablo = Ablo({
   schema,
@@ -194,7 +177,7 @@ server API key in the bundle.
 'use client';
 
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo.schema';
+import { schema } from '@/ablo/schema';
 
 export function Providers({ children }: { children: React.ReactNode }) {
   return <AbloProvider schema={schema}>{children}</AbloProvider>;
@@ -230,21 +213,28 @@ refreshes before expiry.
 
 ## 3. Read State
 
-Use `load` when the row may not already be local.
+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)`, `getAll({ where })`,
+and `getCount({ where })` read the already-synced local graph synchronously, so
+they're the ones you call in render.
+
+Use `retrieve` when the row may not be local yet — it fetches from the server
+and waits.
 
 ```ts
 await ablo.ready();
 
-const [report] = await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+const report = await ablo.weatherReports.retrieve('report_stockholm');
 if (!report) throw new Error('report not found');
 ```
 
-Use `retrieve`, `list`, and `count` for synchronous local reads after data has
-loaded.
+Use `get`, `getAll`, and `getCount` for synchronous local-graph reads after
+data has synced.
 
 ```ts
-const report = ablo.weatherReports.retrieve('report_stockholm');
-const activeReports = ablo.weatherReports.list({
+const report = ablo.weatherReports.get('report_stockholm');
+const activeReports = ablo.weatherReports.getAll({
   where: { projectId: 'proj_123' },
   filter: (report) => report.status !== 'ready',
   orderBy: { updatedAt: 'desc' },
@@ -264,8 +254,8 @@ export function ReportRow({
 }: {
   report: { id: string; location: string; status: 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(serverReport.id));
 
   return <button disabled={Boolean(active) || report.status === 'ready'}>{report.location}</button>;
 }
@@ -346,11 +336,11 @@ 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.retrieve(id)) ?? serverReport` for live rows.
+3. Add `useAblo((ablo) => ablo.weatherReports.get(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.
-7. Let agents use the same `ablo.weatherReports.load(...)` and `ablo.weatherReports.update(...)`.
+7. Let agents use the same `ablo.weatherReports.list(...)` and `ablo.weatherReports.update(...)`.
 
 For the full Python shape, see
 [Existing Python Backend](./examples/existing-python-backend.md).
@@ -362,7 +352,7 @@ Use a Data Source when your app database remains the source of truth.
 ```ts
 // app/api/ablo/source/route.ts
 import { dataSource } from '@abloatai/ablo';
-import { schema } from '@/ablo.schema';
+import { schema } from '@/ablo/schema';
 import { db } from '@/db';
 
 export const POST = dataSource({
@@ -411,8 +401,13 @@ The API key verifies Ablo's request. It is not a database credential.
 Agents should use the same model methods as the app when they can import the
 schema.
 
+An agent often reads a row, calls an LLM, then writes back — a slow gap during
+which a human might touch the same row. Wrap that work in a claim. 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.
+
 ```ts
-const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+const report = await ablo.weatherReports.retrieve(reportId);
 if (!report) return;
 
 await ablo.weatherReports.claim(
@@ -458,10 +453,10 @@ Keep agent writes on the same schema client surface as the app.
 | `/react`                                  | Live React selectors, provider lifecycle, presence, sync status.  |
 | `/testing`                                | Test harnesses and deterministic mocks.                           |
 | `Data Source`                             | Keep your app database canonical.                                 |
-| `persistence: 'indexeddb'`                | Durable browser cache and offline queueing for apps that need it. |
-| `claim` / `claimState` / `queue`          | Show active work and coordinate before a write.                   |
+| `persistence: 'indexeddb'`                | Durable browser cache that survives reloads, for apps that need it. |
+| `claim` / `claim.state` / `claim.queue`          | Show active work and coordinate before a write.                   |
 | `snapshot` + `readAt`                     | Reject writes based on stale state.                               |
-| `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and local-cache tuning.                           |
+| `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and read tuning.                                  |
 
 The first integration should not need most of these. Start with schema and
 model methods, then add the optional pieces where the product actually needs
@@ -469,16 +464,17 @@ them.
 
 ## Method Cheatsheet
 
-| Method                       | Use it for                                                       |
-| ---------------------------- | ---------------------------------------------------------------- |
-| `load({ where })`            | Async hydration from backing store/server.                       |
-| `retrieve(id)`               | Synchronous local read of one loaded row.                        |
-| `list(options?)`             | Synchronous local collection read.                               |
-| `count(options?)`            | Synchronous local count.                                         |
-| `create(data, options?)`     | Create through the model client.                                  |
-| `update(id, data, options?)` | Update through the model client.                                  |
-| `delete(id, options?)`       | Delete through the model client.                                  |
-| `claimState(id)`             | See active work on a model row.                                  |
-| `claim(id, work, options?)`  | Wait for your turn, re-read, and hold the row while `work` runs. |
+| Method                       | Use it for                                                                  |
+| ---------------------------- | --------------------------------------------------------------------------- |
+| `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 (use in render).                   |
+| `getAll({ where })`         | Synchronous local read of many synced rows.                                 |
+| `getCount({ where })`       | Synchronous local count of synced rows.                                     |
+| `create(data, options?)`     | Create through the model client.                                            |
+| `update(id, data, options?)` | Update through the model client.                                            |
+| `delete(id, options?)`       | Delete through the model client.                                            |
+| `claim.state(id)`            | See who is currently working on a row (synchronous).                       |
+| `claim(id, work, options?)`  | Wait for your turn, re-read, and hold the row while `work` runs.            |
 
 Keep first integrations on the model methods above.

package/docs/interaction-model.md

@@ -1,28 +1,40 @@
 # Interaction Model
 
-Ablo's public model is the path every human UI, server action, and agent uses on
-every write:
+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
+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
+let the claim release when your callback returns:
+
+```ts
+const report = await ablo.weatherReports.retrieve('report_stockholm');
+
+await ablo.weatherReports.claim('report_stockholm', async (report) => {
+  await ablo.weatherReports.update(report.id, { status: 'ready' }, { wait: 'confirmed' });
+});
 ```
-Schema -> Model load -> Claim -> Model update -> Confirmation
-```
+
+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.
 
 ## Primitives
 
 | Primitive | Plane | Purpose |
 |---|---|---|
 | `Schema` | State | Declares typed models the app and agents can read and write. |
-| `Model` | State | The generated `ablo.<model>` model. Use `load`, `retrieve`, `create`, `update`, and `delete`. |
-| `Claim` | Coordination | Who is working on a target. Claimed via `ablo.<model>.claim(id, ...)` and read via `ablo.<model>.claimState(id)`. Ephemeral — never persisted. |
+| `Model` | State | The generated `ablo.<model>` model. Use `retrieve`/`list` (async server reads), `get`/`getAll`/`getCount` (synchronous local reads), `create`, `update`, and `delete`. |
+| `Claim` | Coordination | Who is working on a target. Taken via `ablo.<model>.claim(id, work)` 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'`. |
 
 ### Why each primitive is separate
 
-The plane separation isn't ceremony — collapsing any two of these would
-lose a property that's hard to recover later. A reader coming from
-Replicache or Yjs would expect just `Commit`; here's what the others buy
-you over that minimum:
+Why are `Claim`, `Commit`, and `Receipt` separate things instead of one? Each
+does a job the others can't. If you're coming from Replicache or Yjs you'd
+expect just `Commit`; here's what the other two buy you over that minimum:
 
 - **`Claim` is not a read lock.** Reads stay open. Claims serialize
   acting-on-the-row, so slow work can wait in FIFO order, re-read, and write
@@ -33,42 +45,45 @@ you over that minimum:
   client. A status code can't be re-read by a sub-agent that wasn't on
   the original call.
 
-The shape is borrowed from systems that learned the cost of collapse:
-coordination from operational-transform CRDTs and Linear's optimistic
-multiplayer model, and receipts from durable write protocols.
-
 ## Run Loop
 
 A normal schema-backed run is:
 
-```
-const [report] = await ablo.weatherReports.load({ where: { id } });
-const active = ablo.weatherReports.claimState(id);
+```ts
+const report = await ablo.weatherReports.retrieve(id);
+const active = ablo.weatherReports.claim.state(id);
 await ablo.weatherReports.claim(id, async (report) => {
   await ablo.weatherReports.update(report.id, patch, { wait: 'confirmed' });
 });
 ```
 
+`retrieve(id)` is an async server read (await it). `claim.state(id)` is a
+synchronous local read of who currently holds the row — it never blocks.
+
 ## Coordination
 
-Claims broadcast across the org. Claim a row through the flat model verb, write
-through the normal `update`, and the claim releases when the callback returns:
+> Loop view only. Full claim reference — methods, the claim-state object, the
+> `claim.queue`, errors — is [Coordination](./coordination.md).
+
+Claims broadcast across the org. Call `claim(id, callback)`, do your writes with
+the normal `update` inside the callback, and the claim releases automatically
+when the callback returns:
 
 ```ts
 await ablo.weatherReports.claim(
   'report_stockholm',
   async (report) => {
-    await ablo.weatherReports.update(report.id, { status: 'ready' }); // stale-guarded under the claim
+    await ablo.weatherReports.update(report.id, { status: 'ready' }); // rejected if the row changed under the claim
   },
   { action: 'editing' },
 );
 ```
 
-`ablo.weatherReports.claimState('report_stockholm')` reads the live claim (or `null`) without
-blocking. The claim is **advisory**: if another participant holds the row,
-`claim` waits for them to finish and re-reads before handing back the row. The
-same signal is visible to every schema client through `claimState(id)` and the live
-claim stream.
+`ablo.weatherReports.claim.state('report_stockholm')` reads the live claim (or
+`null`) without blocking. Claims don't lock: if another participant holds the
+row, `claim` waits for them to finish, re-reads, and then hands you the fresh
+row. The same signal is visible to every schema client through `claim.state(id)`
+and the live claim stream.
 
 ## Conflict resolution
 

package/docs/mcp/claude-code.md

@@ -6,19 +6,9 @@
 claude mcp add --transport http ablo-sync 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,7 +18,9 @@ In Claude Code, run:
 /mcp list
 ```
 
-You should see `ablo-sync` with the model tools enumerated.
+You should see `ablo-sync` with the integration tools enumerated:
+`search_ablo_docs`, `get_recipe`, `get_api_surface`, `validate_schema`,
+`scaffold_app`.
 
 ## Removing
 
@@ -38,6 +30,6 @@ claude mcp remove ablo-sync
 
 ## 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

@@ -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

@@ -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-sync` 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.