@abloatai/ablo 0.3.0 → 0.4.0

package/docs/api.md

@@ -7,8 +7,8 @@ agents, read [Integration Guide](./integration-guide.md).
 
 
 ```ts
-import Ablo from '@ablo/sync-engine';
-import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+import Ablo from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
   tasks: model({
@@ -107,31 +107,89 @@ that work to clear, or `ifBusy: 'fail'` to throw `AbloBusyError`.
 
 ## Intent
 
-Intent is the coordination signal. It tells humans and agents who is working on
-a target before the write lands.
+Intent is the coordination object — it tells humans and agents who is working on
+a target before the write lands. Like Stripe's `PaymentIntent`, one
+self-describing object carries the whole lifecycle in a single `status` field.
+It lives on the **coordination plane**: ephemeral, TTL'd, broadcast to peers in
+real time, and never persisted as a row.
+
+Read or open one through the model accessor — `ablo.<model>.intent(id)` — which
+sits beside `create`/`update`/`retrieve` and returns a handle **synchronously**,
+so you can inspect who holds a target without awaiting.
+
+### The Intent object
+
+| Field | Type | Description |
+|---|---|---|
+| `object` | `'intent'` | String representing the object's type. Always `'intent'`. |
+| `id` | string | Unique identifier for the intent. |
+| `status` | `'active' \| 'committed' \| 'expired' \| 'canceled'` | The whole lifecycle, in one field. |
+| `target` | `{ type, id, field? }` | What is being coordinated. |
+| `action` | string | Human-readable phase — `'editing'`, `'writing'`, `'reviewing'`. |
+| `heldBy` | string | Participant id holding the intent. |
+| `participantKind` | `'human' \| 'agent'` | Whether a human session or an agent holds it. |
+| `expiresAt` | string | Ms-epoch at which the server auto-expires it if the holder doesn't finish. |
+
+```json
+{
+  "object": "intent",
+  "id": "int_3MtwBwLkdIwHu7ix",
+  "status": "active",
+  "target": { "type": "tasks", "id": "task_123", "field": "status" },
+  "action": "editing",
+  "heldBy": "agent:task-writer",
+  "participantKind": "agent",
+  "expiresAt": "1716580000000"
+}
+```
+
+### Lifecycle
+
+```
+            acquire()                  update() lands
+  (free) ───────────▶ active ───────────────────────▶ committed
+                        │
+            ┌───────────┴───────────┐
+            ▼                       ▼
+        canceled                 expired
+     (release w/o write)      (TTL; holder died)
+```
+
+A target is free when `ablo.<model>.intent(id).current` is `null`. Terminal
+states drop out of the live stream — a present intent is, by definition,
+`active`.
+
+### Reading and acquiring
 
 ```ts
-const intent = await ablo.intents.create({
-  target: { resource: 'tasks', id: 'task_123', field: 'status' },
-  action: 'update',
-});
+const task = ablo.tasks.intent('task_123');
 
-try {
-  const snap = ablo.snapshot({ tasks: 'task_123' });
-  const task = await ablo.tasks.update(
-    'task_123',
-    { status: 'done' },
-    { intent, readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
-  );
-
-  task.status; // done
-} finally {
-  await intent.release();
+// Read side — who is working on this target right now?
+if (task.current) {
+  task.current.heldBy; // 'agent:task-writer'
+  task.current.action; // 'editing'
+  await task.settled(); // wait until they finish, then continue
 }
+
+// Write side — claim, write, auto-release in one flow.
+await task.acquire({ action: 'editing', field: 'status', ttl: '2m' });
+const updated = await task.update({ status: 'done' });
+updated.status; // 'done'
 ```
 
-`intents.waitFor(target)` waits until the live intent stream clears. Pass
-`timeout` only when your product needs an upper bound.
+`task.update(...)` carries the same stale-check as a plain update: it rejects
+with `AbloStaleContextError` if the row advanced past your acquire point, so you
+re-read before retrying. The intent releases automatically when `update`
+resolves; call `task.release()` if the work ends without a write.
+
+`task.settled({ timeout })` waits until the target is free. Pass `timeout` only
+when your product needs an upper bound.
+
+### Cross-resource coordination
+
+For lower-level coordination that isn't scoped to a single model row, the
+top-level `ablo.intents` resource (`create`, `list`, `waitFor`) remains
+available. Most callers should prefer `ablo.<model>.intent(id)`.
 
 ## Advanced Commit API
 
@@ -171,12 +229,12 @@ Use `dataSource(...)` only when the customer's app database remains canonical
 and Ablo should call a signed endpoint instead of storing customer rows itself.
 
 ```ts
-import { dataSource } from '@ablo/sync-engine';
+import { dataSource } from '@abloatai/ablo';
 import { schema } from './ablo.schema';
 
 export const POST = dataSource({
   schema,
-  signingSecret: process.env.ABLO_DATA_SOURCE_SIGNING_SECRET,
+  apiKey: process.env.ABLO_API_KEY,
   async commit({ operations, clientTxId, context }) {
     // Write operations to the customer's database transaction.
     return { rows: [] };

package/docs/capabilities.md

@@ -104,7 +104,7 @@ behalf-of).
 ## Create
 
 ```ts
-import Ablo from '@ablo/sync-engine';
+import Ablo from '@abloatai/ablo';
 
 const admin = Ablo({ apiKey: process.env.ABLO_API_KEY });
 

package/docs/client-behavior.md

@@ -5,8 +5,8 @@ This page covers the SDK behavior around options, errors, retries, and runtimes.
 ## Constructor
 
 ```ts
-import Ablo from '@ablo/sync-engine';
-import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+import Ablo from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
   tasks: model({
@@ -152,7 +152,7 @@ All SDK errors extend `AbloError` and carry a stable `type`.
 | `AbloBusyError` | Active intent conflicted with `ifBusy: 'fail'` or a busy wait timed out. |
 
 ```ts
-import { AbloBusyError } from '@ablo/sync-engine';
+import { AbloBusyError } from '@abloatai/ablo';
 
 try {
   await ablo.tasks.update('task_123', { status: 'done' }, { wait: 'confirmed' });
@@ -192,10 +192,10 @@ request bodies that may contain customer data.
 
 Only these imports are public SemVer surface:
 
-- `@ablo/sync-engine`
-- `@ablo/sync-engine/schema`
-- `@ablo/sync-engine/react`
-- `@ablo/sync-engine/testing`
+- `@abloatai/ablo`
+- `@abloatai/ablo/schema`
+- `@abloatai/ablo/react`
+- `@abloatai/ablo/testing`
 
 `dataSource(...)` is exported from the root package for customer-owned storage
 adapters. Everything outside the four import paths is internal to Ablo-owned

package/docs/data-sources.md

@@ -2,6 +2,11 @@
 
 Every schema model has a backing store.
 
+Customer apps must define an Ablo schema. The schema is the contract between
+the SDK, agents, realtime subscriptions, and the Data Source endpoint. Use
+`defineSchema`, `model`, and Zod the same way a Prisma project starts with a
+`schema.prisma`.
+
 By default, Ablo stores the rows for the models you declare. That makes Ablo the
 managed state store for those resources, the same way Stripe stores `Customer`
 and `PaymentIntent` objects that you create through Stripe's API.
@@ -10,10 +15,15 @@ If you already have application tables and want those tables to remain
 canonical, attach a Data Source. Then Ablo coordinates the write and calls your
 app to commit it.
 
+Your app can keep using its own `DATABASE_URL`. Store that value in your app or
+backend environment, not in Ablo. The integration boundary is the HTTPS
+endpoint your app exposes. The happy path uses the same server-side
+`ABLO_API_KEY` to verify Ablo calls.
+
 Use the SDK with an API key:
 
 ```ts
-import Ablo from '@ablo/sync-engine';
+import Ablo from '@abloatai/ablo';
 import { schema } from './ablo.schema';
 
 export const ablo = Ablo({
@@ -24,6 +34,16 @@ export const ablo = Ablo({
 
 Do not pass a database URL to `Ablo(...)`.
 
+For the first production integration, prefer this shape:
+
+```bash
+# Stored only in your app/backend
+DATABASE_URL=postgres://...
+
+# The only Ablo credential in the customer app
+ABLO_API_KEY=sk_live_...
+```
+
 ## Backing Modes
 
 | Mode | Where rows live | What `create/update/delete` does | Use when |
@@ -62,33 +82,30 @@ When you add a Data Source in Ablo, you get:
 
 | Field | Purpose |
 |---|---|
-| Data Source URL | The public HTTPS route in your app that Ablo will call. |
-| Signing secret | Stored in your app as `ABLO_DATA_SOURCE_SIGNING_SECRET`; used to verify Ablo calls. |
-| Push events URL | Ablo endpoint your app can call when rows change outside Ablo. |
+| Data Source endpoint | The public HTTPS endpoint in your app that Ablo calls. |
+| API key | Stored in your app as `ABLO_API_KEY`; used by the SDK and the Data Source endpoint. |
+| External-write feed | Optional `events` handler on the same Data Source endpoint. |
 | Status | Last successful request, last error, and delivery attempts. |
 
 The shape is the same as a production webhook integration:
 
-1. Add a Data Source URL in Ablo.
-2. Store the signing secret in your app.
-3. Expose one signed HTTP route from your app.
+1. Expose one Data Source endpoint in your app.
+2. Store `ABLO_API_KEY` in your app.
+3. Verify signed HTTP calls before opening a database transaction.
 4. Keep your database credentials in your app.
-
-```bash
-ABLO_DATA_SOURCE_SIGNING_SECRET=whsec_...
-```
+5. Write an outbox row when data changes outside Ablo.
 
 ## Route
 
 ```ts
 // app/api/ablo/source/route.ts
-import { dataSource } from '@ablo/sync-engine';
+import { dataSource } from '@abloatai/ablo';
 import { schema } from '@/ablo.schema';
 import { db } from '@/db';
 
 export const POST = dataSource({
   schema,
-  signingSecret: process.env.ABLO_DATA_SOURCE_SIGNING_SECRET,
+  apiKey: process.env.ABLO_API_KEY,
 
   authorize() {
     return { db };
@@ -176,7 +193,7 @@ handler so connected humans and agents stay current:
 ```ts
 export const POST = dataSource({
   schema,
-  signingSecret: process.env.ABLO_DATA_SOURCE_SIGNING_SECRET,
+  apiKey: process.env.ABLO_API_KEY,
 
   async events({ cursor, limit, context }) {
     const page = await context.auth.db.outbox.after(cursor, { limit });
@@ -201,14 +218,31 @@ export const POST = dataSource({
 `clientTxId` lets Ablo drop SDK echoes that already produced a realtime update.
 Events without `clientTxId` are treated as external writes.
 
+## Production Checklist
+
+Before using a customer-owned database in production:
+
+- Keep `DATABASE_URL` in the customer app or backend environment.
+- Use only the Data Source endpoint and `ABLO_API_KEY` as the customer-facing integration boundary.
+- Verify signatures before opening a database transaction.
+- Store `clientTxId` in an idempotency table before applying writes.
+- Return canonical rows after each commit.
+- Write outbox events in the same transaction as non-Ablo writes.
+- Dedupe outbox events by event `id`.
+- Monitor last success, last error, retry count, event lag, and cursor.
+
+Do not send the customer's database URL to Ablo for this path. Direct database
+URL custody would be a separate connector product with encrypted secret storage,
+rotation, least-privilege roles, connection limits, table allowlists, and clear
+data-processing terms.
+
 ## Security
 
-- Verify requests with `ABLO_DATA_SOURCE_SIGNING_SECRET`.
+- Verify requests with `ABLO_API_KEY`.
 - Keep database credentials in your app.
 - Dedupe commits by `clientTxId`.
 - Dedupe external events by event `id`.
 - Use HTTPS in production.
 
-The signing secret is not a database credential and does not give Ablo access to
-your database. It only lets your route verify that the request came from Ablo
-and was not modified in transit.
+The API key is not a database credential. It only lets your route verify that
+the request came from Ablo and was not modified in transit.

package/docs/examples/agent-human.md

@@ -18,8 +18,8 @@ Use the same schema client the app uses. The worker loads the task, checks activ
 intents, and writes through `ablo.tasks.update(...)`.
 
 ```ts
-import Ablo from '@ablo/sync-engine';
-import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+import Ablo from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
   tasks: model({
@@ -58,7 +58,7 @@ not the first integration path.
 ```tsx
 'use client';
 
-import { useAblo } from '@ablo/sync-engine/react';
+import { useAblo } from '@abloatai/ablo/react';
 
 export function TaskRow({ task: serverTask }: Props) {
   const data = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;

package/docs/examples/ai-sdk-tool.md

@@ -3,8 +3,8 @@
 Use AI SDK for the loop and Ablo for the state boundary inside the tool.
 
 ```ts
-import Ablo from '@ablo/sync-engine';
-import { defineSchema, model, z as schemaZ } from '@ablo/sync-engine/schema';
+import Ablo from '@abloatai/ablo';
+import { defineSchema, model, z as schemaZ } from '@abloatai/ablo/schema';
 import { streamText, tool } from 'ai';
 import { z } from 'zod';
 
@@ -34,38 +34,21 @@ const updateTask = tool({
     const [task] = await ablo.tasks.load({ where: { id: taskId } });
     if (!task) return { ok: false, reason: 'not_found' };
 
-    const busy = ablo.intents.list({ resource: 'tasks', id: taskId });
-    if (busy.length > 0) {
-      await ablo.intents.waitFor(
-        { resource: 'tasks', id: taskId },
-        { timeout: 30_000 },
-      );
-    }
-
-    const snap = ablo.snapshot({ tasks: taskId });
-    const intent = await ablo.intents.create({
-      target: { resource: 'tasks', id: taskId, field: 'status' },
-      action: 'update',
-    });
+    const claim = ablo.tasks.intent(taskId);
+    if (claim.current) await claim.settled({ timeout: 30_000 });
 
+    await claim.acquire({ action: 'editing', field: 'status', ttl: '2m' });
     try {
-      const updated = await ablo.tasks.update(
-        taskId,
-        {
-          status: status ?? task.status,
-          summary: summary ?? task.summary,
-        },
-        {
-          intent,
-          readAt: snap.stamp,
-          onStale: 'reject',
-          wait: 'confirmed',
-        },
-      );
+      // update commits with the held claim and auto-releases on success
+      const updated = await claim.update({
+        status: status ?? task.status,
+        summary: summary ?? task.summary,
+      });
 
       return { ok: true, task: updated };
-    } finally {
-      await intent.release();
+    } catch (err) {
+      await claim.release();
+      throw err;
     }
   },
 });
@@ -85,8 +68,8 @@ The important part is not the model provider. The important part is that the
 tool:
 
 - loads the latest task,
-- checks active intent,
-- writes with `readAt`,
-- rejects stale state,
+- waits if another participant already holds the row,
+- acquires a claim before writing,
+- writes and auto-releases through the same handle,
 - waits for server confirmation.
 

package/docs/examples/existing-python-backend.md

@@ -27,7 +27,7 @@ Create a schema for the records that need realtime coordination.
 
 ```ts
 // web/ablo.schema.ts
-import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema({
   tasks: model({
@@ -41,7 +41,7 @@ export const schema = defineSchema({
 
 ```ts
 // web/ablo.ts
-import Ablo from '@ablo/sync-engine';
+import Ablo from '@abloatai/ablo';
 import { schema } from './ablo.schema';
 
 export const ablo = Ablo({
@@ -57,7 +57,7 @@ model resources without importing server credentials.
 // web/app/providers.tsx
 'use client';
 
-import { AbloProvider } from '@ablo/sync-engine/react';
+import { AbloProvider } from '@abloatai/ablo/react';
 import { schema } from '@/ablo.schema';
 
 export function Providers({ children }: { children: React.ReactNode }) {
@@ -73,7 +73,7 @@ subscribe to the same model resource Ablo writes through.
 ```tsx
 'use client';
 
-import { useAblo } from '@ablo/sync-engine/react';
+import { useAblo } from '@abloatai/ablo/react';
 
 export function TaskRow({ task: serverTask }: { task: Task }) {
   const task = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;
@@ -95,16 +95,16 @@ No string model key is needed in the first example. The selector reads from
 
 ## 3. Add One Python Data Source Endpoint
 
-In Ablo, configure the Data Source URL:
+Expose one customer-owned Data Source endpoint:
 
 ```txt
 https://api.example.com/api/ablo/source
 ```
 
-Store the signing secret in the Python server:
+Store the Ablo API key in the Python server:
 
 ```bash
-ABLO_DATA_SOURCE_SIGNING_SECRET=whsec_...
+ABLO_API_KEY=sk_live_...
 ```
 
 Then expose one route that verifies the signed request and calls the existing
@@ -126,7 +126,7 @@ router = APIRouter()
 
 
 def verify_ablo_signature(request: Request, raw_body: bytes) -> None:
-    secret = os.environ["ABLO_DATA_SOURCE_SIGNING_SECRET"].encode()
+    api_key = os.environ["ABLO_API_KEY"].encode()
     message_id = request.headers.get("webhook-id")
     timestamp = request.headers.get("webhook-timestamp")
     signature_header = request.headers.get("webhook-signature", "")
@@ -135,12 +135,12 @@ def verify_ablo_signature(request: Request, raw_body: bytes) -> None:
         raise HTTPException(status_code=401, detail="missing signature")
 
     signed_at = int(timestamp)
-    if abs(int(time.time() * 1000) - signed_at) > 5 * 60 * 1000:
+    if abs(int(time.time()) - signed_at) > 5 * 60:
         raise HTTPException(status_code=401, detail="expired signature")
 
     payload = message_id.encode() + b"." + timestamp.encode() + b"." + raw_body
     expected = base64.b64encode(
-        hmac.new(secret, payload, hashlib.sha256).digest()
+        hmac.new(api_key, payload, hashlib.sha256).digest()
     ).decode()
 
     presented = [

package/docs/examples/nextjs.md

@@ -64,7 +64,7 @@ rejects. The action can re-fetch and ask the user to retry.
 ```tsx
 'use client';
 
-import { useAblo } from '@ablo/sync-engine/react';
+import { useAblo } from '@abloatai/ablo/react';
 
 export function TaskEditor({ task: serverTask }: Props) {
   const data = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;

package/docs/examples/server-agent.md

@@ -4,8 +4,8 @@ Most server agents should import the app schema and use the same model methods
 as the product UI.
 
 ```ts
-import Ablo from '@ablo/sync-engine';
-import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+import Ablo from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 const schema = defineSchema({
   tasks: model({

package/docs/index.md

@@ -87,7 +87,7 @@ query-shaped sync).
 
 ## Runtime builds
 
-- `@ablo/sync-engine` — schema-powered sync client for typed model operations, realtime, intents, and receipts.
+- `@abloatai/ablo` — schema-powered sync client for typed model operations, realtime, intents, and receipts.
 - `Ablo({ apiKey })` — advanced resource client for runtimes that intentionally cannot import a schema.
 
 ## More

package/docs/integration-guide.md

@@ -40,8 +40,8 @@ together, behind one client.
 The normal integration is one client:
 
 ```ts
-import Ablo from '@ablo/sync-engine';
-import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+import Ablo from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
 ```
 
 Declare the models Ablo coordinates, then read and write through
@@ -66,8 +66,8 @@ Every schema model has a backing store. The SDK call shape stays the same.
 | Schema-less resource API | Custom runtime | A server worker, MCP route, or migration script intentionally cannot import the app schema. |
 
 Do not pass a database URL to `Ablo(...)`. Application and agent code use
-`ABLO_API_KEY`. If your database stays canonical, add a Data Source URL in Ablo
-and keep the database credentials inside your app.
+`ABLO_API_KEY`. If your database stays canonical, expose a signed Data Source
+endpoint from your app and keep the database credentials inside your app.
 
 ## Test With Sandboxes
 
@@ -106,7 +106,7 @@ offline-heavy local cache behavior.
 
 ```ts
 // src/ablo.schema.ts
-import { defineSchema, model, z } from '@ablo/sync-engine/schema';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema(
   {
@@ -176,7 +176,7 @@ Trusted runtimes can use `ABLO_API_KEY`.
 
 ```ts
 // src/ablo.ts
-import Ablo from '@ablo/sync-engine';
+import Ablo from '@abloatai/ablo';
 import { schema } from './ablo.schema';
 
 export const ablo = Ablo({
@@ -192,7 +192,7 @@ server API key in the bundle.
 // app/providers.tsx
 'use client';
 
-import { AbloProvider } from '@ablo/sync-engine/react';
+import { AbloProvider } from '@abloatai/ablo/react';
 import { schema } from '@/ablo.schema';
 
 export function Providers({ children }: { children: React.ReactNode }) {
@@ -259,7 +259,7 @@ In React, selector `useAblo` is the public read API:
 ```tsx
 'use client';
 
-import { useAblo } from '@ablo/sync-engine/react';
+import { useAblo } from '@abloatai/ablo/react';
 
 export function TaskRow({ task: serverTask }: { task: Task }) {
   const task = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;
@@ -369,13 +369,13 @@ Use a Data Source when your app database remains the source of truth.
 
 ```ts
 // app/api/ablo/source/route.ts
-import { dataSource } from '@ablo/sync-engine';
+import { dataSource } from '@abloatai/ablo';
 import { schema } from '@/ablo.schema';
 import { db } from '@/db';
 
 export const POST = dataSource({
   schema,
-  signingSecret: process.env.ABLO_DATA_SOURCE_SIGNING_SECRET,
+  apiKey: process.env.ABLO_API_KEY,
 
   authorize() {
     return { db };
@@ -404,14 +404,15 @@ export const POST = dataSource({
 });
 ```
 
-Ablo gives you a Data Source URL, a signing secret, push/events URL, and status.
-Your app stores:
+Ablo needs your Data Source endpoint and API key. External writes can be
+reported through an optional `events` handler on the same route. Your app
+stores one Ablo credential:
 
 ```bash
-ABLO_DATA_SOURCE_SIGNING_SECRET=whsec_...
+ABLO_API_KEY=sk_live_...
 ```
 
-The signing secret verifies Ablo's request. It is not a database credential.
+The API key verifies Ablo's request. It is not a database credential.
 
 ## 8. Agents
 

package/docs/interaction-model.md

@@ -20,7 +20,7 @@ Capability -> Task -> Usage
 |---|---|---|
 | `Schema` | State | Declares typed models the app and agents can read and write. |
 | `Model` | State | The generated `ablo.<model>` resource. Use `load`, `retrieve`, `create`, `update`, and `delete`. |
-| `Intent` | State | Pre-write coordination. It says what this actor is preparing to change. |
+| `Intent` | Coordination | Who is working on a target, as one Stripe-shaped object with a single `status`. Opened and read through `ablo.<model>.intent(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'`. |
 | `Capability` | Control | Signed credentials. It says who can do what, where, for how long, and on whose behalf. |
@@ -110,9 +110,21 @@ Removing any one of the three leaves a class of attack uncovered. The pattern ma
 
 ## Coordination
 
-Intents broadcast across the org. When `agent:task-writer` declares an intent to
-update a task, schema clients can see it through `ablo.intents.list(...)` or the
-live intent stream. Callers decide whether to yield, wait, or fail fast.
+Intents broadcast across the org. Open and read one on any row through the
+model accessor:
+
+```ts
+const task = ablo.tasks.intent('task_123');
+if (task.current) await task.settled();      // someone's working — wait
+await task.acquire({ action: 'editing' });   // claim so others yield
+await task.update({ status: 'done' });        // commits + releases
+```
+
+`task.current` is the live `Intent` (or `null`); `task.settled()` resolves when
+the holder finishes. The same signal is visible to every schema client through
+`ablo.intents.list(...)` and the live intent stream, so callers decide whether
+to yield, wait, or fail fast. See [API → Intent](./api.md#intent) for the object
+reference and lifecycle.
 
 ## Conflict resolution
 

package/docs/mcp.md

@@ -21,7 +21,7 @@ Each resource you declare becomes one or more MCP tools:
 | `retrieve` | `<resource>.retrieve` | Returns the row + a stamp. |
 | `list` | `<resource>.list` | Cursor-paginated discovery. |
 | `update` | `<resource>.update` | Write, requires the prior stamp. |
-| `intents.create` | `intent.create` | Declare a claim before writing. |
+| `<model>.intent` | `intent.create` | Claim a row before writing, then auto-release on update. |
 
 The assistant gets typed JSON schemas, real argument types, and typed
 rejections when it writes stale state. No invention, no hallucinated IDs.