@abloatai/ablo 0.5.0 → 0.6.0

package/docs/integration-guide.md

@@ -52,18 +52,17 @@ that same model path.
 schema -> ablo.<model>.load(...) -> ablo.<model>.update(...)
 ```
 
-Capabilities, tasks, commits, and receipts exist under the hood. Most apps do
-not create them by hand.
+Commits and receipts exist under the hood. Most apps do not create protocol
+objects by hand.
 
 ## Pick The Backing Mode
 
 Every schema model has a backing store. The SDK call shape stays the same.
 
-| Mode | Rows live in | Use when |
-|---|---|---|
-| Ablo-managed | Ablo | New collaborative or agent-written state can live in Ablo. |
-| Data Source | Your app database | You already have tables, service logic, and API endpoints that remain canonical. |
-| Schema-less resource API | Custom runtime | A server worker, MCP route, or migration script intentionally cannot import the app schema. |
+| Mode         | Rows live in      | Use when                                                                         |
+| ------------ | ----------------- | -------------------------------------------------------------------------------- |
+| Ablo-managed | Ablo              | New collaborative or agent-written state can live in Ablo.                       |
+| Data Source  | Your app database | You already have tables, service logic, and API endpoints that remain canonical. |
 
 Do not pass a database URL to `Ablo(...)`. Application and agent code use
 `ABLO_API_KEY`. If your database stays canonical, expose a signed Data Source
@@ -74,7 +73,7 @@ endpoint from your app and keep the database credentials inside your app.
 Use the public `/sandbox` page to understand the state flow. It is a visual,
 deterministic demo; it does not call your API key or mutate hosted Ablo data.
 It is also built for coding agents: copy the sandbox prompt into Claude Code or
-Codex and ask it to wire one real resource through the schema model API.
+Codex and ask it to wire one real model through the schema model API.
 
 Use the authenticated org dashboard sandbox for real integration work. The
 default sandbox is the equivalent of Stripe test mode:
@@ -92,7 +91,7 @@ and write path are ready for production.
 When handing this to a coding agent, give it a concrete target:
 
 ```txt
-Add Ablo Sync to this app for one resource that humans and agents both edit.
+Add Ablo to this app for one model that humans and agents both 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.
@@ -110,11 +109,11 @@ import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema(
   {
-    tasks: model({
+    weatherReports: model({
       id: z.string(),
       projectId: z.string(),
-      title: z.string(),
-      status: z.enum(['todo', 'doing', 'done']),
+      location: z.string(),
+      status: z.enum(['pending', 'ready']),
       assigneeId: z.string().nullable(),
       updatedAt: z.string(),
     }),
@@ -138,7 +137,7 @@ export const schema = defineSchema(
         extract: (i) => (i.userId ? [String(i.userId)] : []),
       },
     ],
-  },
+  }
 );
 ```
 
@@ -146,23 +145,25 @@ export const schema = defineSchema(
 
 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
+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.
 
 ```ts
 model(
-  { /* fields */ },
+  {
+    /* fields */
+  },
   /* relations */ {},
   {
     // Rows carry organization_id and bootstrap filters on it.
     orgScoped: true,
 
-    // Per-entity sync-group anchor. Lets a capability narrow into
+    // Per-entity sync-group anchor. Lets a scoped session narrow into
     // one row's scope via `syncGroupFormat.replace('{id}', rowId)`.
     syncGroupFormat: 'matter:{id}',
-  },
-)
+  }
+);
 ```
 
 For rows that don't carry `organization_id` themselves but inherit
@@ -185,7 +186,7 @@ export const ablo = Ablo({
 });
 ```
 
-Browser apps should use the React provider or a scoped session/capability, not a
+Browser apps should use the React provider or a scoped session token, not a
 server API key in the bundle.
 
 ```tsx
@@ -208,15 +209,14 @@ bundle, and signs server-to-server requests. It is the right credential
 for trusted runtimes (Next.js server actions, background workers,
 migration scripts) where the code reading it is yours.
 
-A browser or an agent runtime is not that environment. The React
-provider and the `agent.run(...)` wrapper both exchange your api key for
-a **capability** — a short-lived, narrowly-scoped bearer token. The
-browser holds the cap; the api key never leaves the server. The
-exchange is the bridge between two credential shapes:
+A browser is not that environment. The React provider exchanges your API key for
+a short-lived, narrowly scoped bearer token. The browser holds that scoped token;
+the API key never leaves the server. The exchange is the bridge between two
+credential shapes:
 
 ```
                      trusted runtime              browser / agent
-ABLO_API_KEY ─exchange─►  Capability token ────► narrow scope, leased
+ABLO_API_KEY ─exchange─►  scoped token ────────► narrow scope, leased
 (long-lived,             (short-lived,
  broad scope,             per-actor scope,
  server only)             revocable)
@@ -225,10 +225,8 @@ ABLO_API_KEY ─exchange─►  Capability token ────► narrow scope, l
 This is the same shape as Stripe's
 ephemeral keys (Issuing Elements expires in 15 minutes) and AWS STS
 AssumeRole (returns time-bounded creds with the minimal needed scope).
-You never *type* a capability into your app; the SDK mints one when it
-needs one and refreshes before expiry. See
-[Capabilities](./capabilities.md) for the design rationale and the
-manual create/revoke surface that custom runtimes use.
+You never type that token into your app; the SDK mints one when it needs one and
+refreshes before expiry.
 
 ## 3. Read State
 
@@ -237,18 +235,18 @@ Use `load` when the row may not already be local.
 ```ts
 await ablo.ready();
 
-const [task] = await ablo.tasks.load({ where: { id: 'task_123' } });
-if (!task) throw new Error('task not found');
+const [report] = await ablo.weatherReports.load({ where: { id: 'report_stockholm' } });
+if (!report) throw new Error('report not found');
 ```
 
 Use `retrieve`, `list`, and `count` for synchronous local reads after data has
 loaded.
 
 ```ts
-const task = ablo.tasks.retrieve('task_123');
-const activeTasks = ablo.tasks.list({
+const report = ablo.weatherReports.retrieve('report_stockholm');
+const activeReports = ablo.weatherReports.list({
   where: { projectId: 'proj_123' },
-  filter: (task) => task.status !== 'done',
+  filter: (report) => report.status !== 'ready',
   orderBy: { updatedAt: 'desc' },
   limit: 50,
 });
@@ -261,17 +259,15 @@ In React, selector `useAblo` is the public read API:
 
 import { useAblo } from '@abloatai/ablo/react';
 
-export function TaskRow({ task: serverTask }: { task: Task }) {
-  const task = useAblo((ablo) => ablo.tasks.retrieve(serverTask.id)) ?? serverTask;
-  const intents = useAblo((ablo) =>
-    ablo.intents.list({ resource: 'tasks', id: serverTask.id }),
-  ) ?? [];
-
-  return (
-    <button disabled={intents.length > 0 || task.status === 'done'}>
-      {task.title}
-    </button>
-  );
+export function ReportRow({
+  report: serverReport,
+}: {
+  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));
+
+  return <button disabled={Boolean(active) || report.status === 'ready'}>{report.location}</button>;
 }
 ```
 
@@ -286,27 +282,23 @@ const ablo = useAblo();
 For simple writes:
 
 ```ts
-await ablo.tasks.update(
-  'task_123',
-  { status: 'done' },
-  { wait: 'confirmed' },
-);
+await ablo.weatherReports.update('report_stockholm', { status: 'ready' }, { wait: 'confirmed' });
 ```
 
 For writes based on state the user or agent already read, snapshot first and
 reject stale updates:
 
 ```ts
-const snap = ablo.snapshot({ tasks: 'task_123' });
+const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
 
-await ablo.tasks.update(
-  'task_123',
-  { status: 'done' },
+await ablo.weatherReports.update(
+  'report_stockholm',
+  { status: 'ready' },
   {
     readAt: snap.stamp,
     onStale: 'reject',
     wait: 'confirmed',
-  },
+  }
 );
 ```
 
@@ -317,16 +309,16 @@ back optimistic local state and throw a typed `AbloError`.
 
 There is no separate multiplayer setup.
 
-If humans, server actions, and agents use the same schema model resource, they
+If humans, server actions, and agents use the same schema client, they
 share the same stream:
 
 ```txt
-human UI -> ablo.tasks.update(...)
-agent    -> ablo.tasks.update(...)
-server   -> ablo.tasks.update(...)
+human UI -> ablo.weatherReports.update(...)
+agent    -> ablo.weatherReports.update(...)
+server   -> ablo.weatherReports.update(...)
 ```
 
-Ablo coordinates those writes, fans out confirmed deltas, exposes active intents,
+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
@@ -342,7 +334,7 @@ the records that need multiplayer now and agent-safe writes later.
 
 ```txt
 Button
-  -> ablo.tasks.update(...)
+  -> ablo.weatherReports.update(...)
   -> Ablo
   -> signed Data Source request
   -> existing backend service
@@ -352,13 +344,13 @@ Button
 
 The migration can be gradual:
 
-1. Declare schema for one resource, such as `tasks`.
+1. Declare schema for one model, such as `reports`.
 2. Keep existing server loads for first paint.
-3. Add `useAblo((ablo) => ablo.tasks.retrieve(id)) ?? serverTask` for live rows.
+3. Add `useAblo((ablo) => ablo.weatherReports.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/tasks/...')` to `ablo.tasks.update(...)`.
+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.tasks.load(...)` and `ablo.tasks.update(...)`.
+7. Let agents use the same `ablo.weatherReports.load(...)` and `ablo.weatherReports.update(...)`.
 
 For the full Python shape, see
 [Existing Python Backend](./examples/existing-python-backend.md).
@@ -390,13 +382,13 @@ export const POST = dataSource({
     return { rows };
   },
 
-  tasks: {
+  reports: {
     async load({ id, context }) {
-      return context.auth.db.task.findUnique({ where: { id } });
+      return context.auth.db.report.findUnique({ where: { id } });
     },
 
     async list({ query, context }) {
-      return context.auth.db.task.findMany({
+      return context.auth.db.report.findMany({
         take: query.limit ?? 100,
       });
     },
@@ -420,18 +412,19 @@ Agents should use the same model methods as the app when they can import the
 schema.
 
 ```ts
-const [task] = await ablo.tasks.load({ where: { id: taskId } });
-if (!task) return;
-
-const intents = ablo.intents.list({ resource: 'tasks', id: taskId });
-if (intents.length > 0) return { skipped: true, reason: 'busy' };
-
-const snap = ablo.snapshot({ tasks: taskId });
-
-await ablo.tasks.update(
-  taskId,
-  { status: 'done', summary: await summarize(task) },
-  { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+const [report] = await ablo.weatherReports.load({ where: { id: reportId } });
+if (!report) return;
+
+await ablo.weatherReports.claim(
+  reportId,
+  async (claimed) => {
+    await ablo.weatherReports.update(
+      claimed.id,
+      { status: 'ready', forecast: await getForecast(claimed) },
+      { wait: 'confirmed' }
+    );
+  },
+  { wait: false, action: 'forecasting' }
 );
 ```
 
@@ -439,38 +432,36 @@ Use AI SDK for the model loop. Put Ablo inside the tool that persists the final
 change.
 
 ```ts
-const completeTask = tool({
-  description: 'Mark a task done with a summary',
+const completeReport = tool({
+  description: 'Mark a weather report ready with a forecast',
   inputSchema: z.object({
-    taskId: z.string(),
-    summary: z.string(),
+    reportId: z.string(),
+    forecast: z.string(),
   }),
-  execute: async ({ taskId, summary }) => {
-    const snap = ablo.snapshot({ tasks: taskId });
-    return ablo.tasks.update(
-      taskId,
-      { status: 'done', summary },
-      { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' },
+  execute: async ({ reportId, forecast }) => {
+    const snap = ablo.snapshot({ weatherReports: reportId });
+    return ablo.weatherReports.update(
+      reportId,
+      { status: 'ready', forecast },
+      { readAt: snap.stamp, onStale: 'reject', wait: 'confirmed' }
     );
   },
 });
 ```
 
-Use schema-less `agent.run(...)`, `resource(...)`, and `commits.create(...)` only
-for custom server runtimes that intentionally cannot import the schema.
+Keep agent writes on the same schema client surface as the app.
 
 ## Optional Surface
 
-| Optional piece | Why it exists |
-|---|---|
-| `/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. |
-| `intents` | 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. |
-| `resource(...)` and `commits.create(...)` | Low-level protocol access for custom runtimes. |
+| Optional piece                            | Why it exists                                                     |
+| ----------------------------------------- | ----------------------------------------------------------------- |
+| `/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.                   |
+| `snapshot` + `readAt`                     | Reject writes based on stale state.                               |
+| `mutable`, `readOnly`, `field`, `indexed` | Advanced schema and local-cache 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
@@ -478,17 +469,16 @@ 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 resource. |
-| `update(id, data, options?)` | Update through the model resource. |
-| `delete(id, options?)` | Delete through the model resource. |
-| `intents.list(target)` | See active work on a resource. |
-| `intents.waitFor(target)` | Wait on the live intent stream. |
-
-Do not use `ablo.commit` as the first write API. Most callers should never need
-the low-level commit plane directly.
+| 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. |
+
+Keep first integrations on the model methods above.

package/docs/interaction-model.md

@@ -1,17 +1,10 @@
 # Interaction Model
 
-Ablo separates the data path from the authority path.
-
-The data path is what your application does on every write:
-
-```
-Schema -> Model load -> Intent -> Model update -> Confirmation
-```
-
-The authority path is what makes that write defensible:
+Ablo's public model is the path every human UI, server action, and agent uses on
+every write:
 
 ```
-Capability -> Task -> Usage
+Schema -> Model load -> Claim -> Model update -> Confirmation
 ```
 
 ## Primitives
@@ -19,16 +12,10 @@ Capability -> Task -> Usage
 | Primitive | Plane | Purpose |
 |---|---|---|
 | `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` | 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. |
+| `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. |
 | `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. |
-| `Task` | Control | One agent run. It groups prompts, commits, child tasks, and cost. |
-| `Usage` | Control | Metering and audit rows derived from accepted work. |
-
-Capabilities, tasks, and usage do not mutate product data. They define and
-record the authority around mutation.
 
 ### Why each primitive is separate
 
@@ -37,94 +24,51 @@ 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:
 
-- **`Intent` is not a lock.** A pessimistic lock blocks a writer; an
-  intent *announces* one. Other writers can yield, wait, or proceed —
-  the choice is theirs, not the system's. This is the only primitive
-  that lets two agents discover each other's planned work *before* the
-  conflict and self-arbitrate. Without intents, agents only learn about
-  contention at commit time, when one of them has already wasted a
-  token budget.
+- **`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
+  from fresh state.
 - **`Receipt` is not a `200 OK`.** It's the durable artifact a commit
   produced — accepted commit id, server-assigned timestamps, stale-check
   outcome — addressable after the fact and replayable into a different
   client. A status code can't be re-read by a sub-agent that wasn't on
   the original call.
-- **`Capability` is not the actor.** The actor (`Task`) is what *ran*;
-  the capability is what it was *allowed* to do. Same human can spawn
-  many tasks under one cap (cheap re-run); same task can attenuate to
-  many sub-caps (sub-agent delegation). Folding them collapses both
-  directions of that fan.
-- **`Task` is not the credential.** It's the audit envelope: prompt,
-  commits, child tasks, tokens, duration. Long after the cap has
-  expired, the task row is what answers "what did this run do." Folding
-  task into capability loses the post-expiry audit.
-- **`Usage` is not derived from logs.** It's denormalized at commit
-  accept time so quota enforcement and billing reads stay O(1). Log
-  scans would work for audit but not for hot-path gating.
 
 The shape is borrowed from systems that learned the cost of collapse:
-intents from operational-transform CRDTs and Linear's
-optimistic-multiplayer model, capabilities + tasks from AWS IAM
-(`Role` ≠ `RoleSession`) and Vault (`policy` ≠ `lease`).
+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 [task] = await ablo.tasks.load({ where: { id } });
-const busy = ablo.intents.list({ resource: 'tasks', id });
-const snap = ablo.snapshot({ tasks: id });
-await ablo.tasks.update(id, patch, {
-  readAt: snap.stamp,
-  onStale: 'reject',
-  wait: 'confirmed',
+const [report] = await ablo.weatherReports.load({ where: { id } });
+const active = ablo.weatherReports.claimState(id);
+await ablo.weatherReports.claim(id, async (report) => {
+  await ablo.weatherReports.update(report.id, patch, { wait: 'confirmed' });
 });
 ```
 
-## Participants
-
-Every action is performed by one of three kinds:
-
-- `user` — a human, authenticated via session.
-- `agent` — an AI process acting on behalf of a human, authenticated via a capability minted from that human's session.
-- `system` — a customer-backend process acting on behalf of an organization, authenticated via an API key.
-
-The participant kind is enforced at the boundary. An agent capability cannot impersonate a user. A user session cannot open a task.
-
-## Delegation chain
-
-Every capability resolves to a `delegationChainRootUserId` — the human at the head of the chain. The chain is denormalized onto every commit's `on_behalf_of_*` columns so audit queries answer "what did this human authorize" with one lookup, not a recursive join.
-
-## Enforcement
-
-Capabilities are enforced per operation, not per request. When a commit arrives, Ablo decodes the bearer token, checks each operation against `operations` and `syncGroups`, and rejects with `capability_scope_denied` if the scope is missing. Revocation takes effect within seconds of `DELETE /v1/capabilities/:id`.
-
-Three independent checks gate every commit. The redundancy is intentional — each check covers a failure mode the others don't:
-
-- **Lease (TTL on the token).** Decoded from the bearer; no DB lookup. Caps the lifetime of a leaked token. Without this, a stolen token works until manually revoked.
-- **Signature + scope verification.** Stateless. Detects forged or tampered tokens and rejects operations outside the cap's `operations` / `syncGroups`. Without this, a malformed token with the right shape could pass.
-- **Revocation.** `DELETE /v1/capabilities/:id` flips status server-side; live WS sessions close, future commits reject. Closes the gap between lease refresh cycles when you need *immediate* cutoff. Without this, a compromised cap with a long lease leaks until expiry.
-
-Removing any one of the three leaves a class of attack uncovered. The pattern matches AWS STS, Vault leases, and the OAuth 2.1 / MCP agent-auth recommendation; see [Capabilities](./capabilities.md#the-three-layer-security-model) for the full design discussion.
-
 ## Coordination
 
-Intents broadcast across the org. Open and read one on any row through the
-model accessor:
+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:
 
 ```ts
-const task = ablo.tasks.intent('task_123');
-if (task.current) await task.whenFree();     // someone's working — wait
-await task.claim({ action: 'editing' });     // claim so others yield
-await task.update({ status: 'done' });        // commits + releases
+await ablo.weatherReports.claim(
+  'report_stockholm',
+  async (report) => {
+    await ablo.weatherReports.update(report.id, { status: 'ready' }); // stale-guarded under the claim
+  },
+  { action: 'editing' },
+);
 ```
 
-`task.current` is the live `Intent` (or `null`); `task.whenFree()` 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.
+`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.
 
 ## Conflict resolution
 
@@ -137,16 +81,6 @@ Schema updates can carry `readAt` and `onStale`. If the state advanced past
 
 The choice is per-commit. No CRDT default; the policy is explicit.
 
-## Audit
-
-Three tables observe the run:
-
-- `agent_tasks` — one row per open/close cycle. Cost stats, prompt hash, capability id.
-- `agent_actions_log` — one row per write, attributed to the task and the capability.
-- `usage_event` — one row per accounted API call, attributed to the api key, the participant, and the task.
-
-Joins between them answer "what did this agent do, on whose authority, at what cost." That answer is what makes giving an agent write access defensible.
-
 ## The contract in one sentence
 
-Declare schema, load state, coordinate intent, update the model, and wait for confirmation.
+Declare schema, load state, coordinate a claim, update the model, and wait for confirmation.

package/docs/mcp/claude-code.md

@@ -10,14 +10,14 @@ That's it. The next `/help` in Claude Code will list the Ablo Sync tools.
 
 ## With auth
 
-If your deployment requires a capability token (production setups should):
+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 capability from the dashboard or via the API — see
+Create a session-scoped bearer token from your server or dashboard — see
 [MCP overview](/docs/mcp#auth).
 
 ## Verify
@@ -28,7 +28,7 @@ In Claude Code, run:
 /mcp list
 ```
 
-You should see `ablo-sync` with the resource tools enumerated.
+You should see `ablo-sync` with the model tools enumerated.
 
 ## Removing
 

package/docs/mcp/cursor.md

@@ -44,7 +44,7 @@ in your shell config.
 ## Verify
 
 In Cursor's agent panel, open the MCP tools list. You should see the
-Ablo Sync resource tools and their JSON schemas.
+Ablo Sync model tools and their JSON schemas.
 
 ## More
 

package/docs/mcp/windsurf.md

@@ -37,7 +37,7 @@ Cascade → MCP. Restart Windsurf after saving.
 ## Verify
 
 Cascade's MCP panel lists every configured server with its tools. You
-should see `ablo-sync` with resource tools enumerated.
+should see `ablo-sync` with model tools enumerated.
 
 ## More