@abloatai/ablo 0.35.0 → 0.37.0

package/docs/mcp.md

@@ -6,7 +6,7 @@ Ablo publishes **two** MCP servers for two different jobs. Don't confuse them:
 
 | Server | Purpose | Auth | Tools |
 |---|---|---|---|
-| **Coordination** (`@abloatai/mcp`) | Manage your Ablo the way the CLI does, and let an agent safely read & mutate application data | API key (`sk_…` / `rk_…`) | projects, schema, logs, usage — plus `get` / `list` / `create` / `update` / `delete` / `claim` / `release` over your rows |
+| **Coordination** (`@abloatai/mcp`) | Manage your Ablo the way the CLI does, and let an agent safely read & mutate application data | API key (`sk_…` / `rk_…`) | projects, schema, logs, usage: plus `get` / `list` / `create` / `update` / `delete` / `claim` / `release` over your rows |
 | **Integration-helper** (hosted `/api/mcp`) | Help an AI coding assistant write SDK integration code that compiles | none (public docs) | doc search, export surface, schema lint, scaffold |
 
 The coordination server manages your account **and is the data plane** — it is
@@ -37,7 +37,7 @@ claude mcp add ablo -- npx -y @abloatai/mcp
 | `list_projects` | `ablo projects list` | the org's projects (needs `sk_`) |
 | `create_project` | `ablo projects create` | create one (needs `sk_`) |
 | `tail_logs` | `ablo logs` | recent commits and the actor behind each |
-| `get_usage` | — | usage in daily buckets |
+| `get_usage` |: | usage in daily buckets |
 
 There are no key-management tools. A mint returns the plaintext once — only a
 hash is kept — so no tool can hand it back later, and returning it at mint time
@@ -57,13 +57,13 @@ Each tool mirrors an SDK verb, scoped to a model + id. Model names come from
 
 | Tool | Mirrors | Does |
 |---|---|---|
-| `get_model` | `ablo.<model>.local.retrieve(id)` | read latest state + active claims |
+| `get_model` | `ablo.<model>.local.get(id)` | read latest state + active claims |
 | `list_records` | `ablo.<model>.list({…})` | cursor-paginated list with filters |
 | `create_model` | `ablo.<model>.create({ data })` | guarded create |
 | `update_model` | `ablo.<model>.update({ id, … })` | guarded update |
 | `delete_model` | `ablo.<model>.delete({ id })` | guarded delete |
 | `claim_model` | `ablo.<model>.claim({ id })` | acquire / queue a coordination lease |
-| `release_claim` | — | release the lease so others proceed |
+| `release_claim` |: | release the lease so others proceed |
 
 The agent-facing contract — the safe loop, the "derive idempotency keys from
 the business event" rule, and the error-code playbook — ships as a loadable
@@ -94,9 +94,9 @@ claude mcp add --transport http ablo https://<your-app>/api/mcp
 
 The endpoint is identical for every client — only the config surface differs:
 
-- **Claude Code** — run the `claude mcp add` command above; verify with `/mcp list`, remove with `claude mcp remove ablo`.
-- **Cursor** — add the server to `~/.cursor/mcp.json` (macOS / Linux), then restart.
-- **Windsurf** — add the same JSON via Settings → Cascade → MCP, then restart.
+- **Claude Code:** run the `claude mcp add` command above; verify with `/mcp list`, remove with `claude mcp remove ablo`.
+- **Cursor:** add the server to `~/.cursor/mcp.json` (macOS / Linux), then restart.
+- **Windsurf:** add the same JSON via Settings → Cascade → MCP, then restart.
 
 Cursor and Windsurf use the same config shape:
 
@@ -120,7 +120,7 @@ Each client then lists the Ablo tools (`search_ablo_docs`, `get_recipe`, `get_ap
 | `get_recipe` | Returns the full markdown of one doc by name (e.g. `readme`, `quickstart`, `schema-contract`, `integration-guide`, `api`, `guarantees`). |
 | `get_api_surface` | Returns the structured export list for an SDK subpath (`@abloatai/ablo`, `./react`, `./schema`, `./testing`, …). Call with no argument to list every subpath. |
 | `validate_schema` | Lints `defineSchema` source against the DSL rules (camelCase fields, lowercase model keys, `scope`/`grants` sync groups, valid `load` strategies, no legacy builders) and returns a structured issue list. Runs no code. |
-| `scaffold_app` | Emits a starter file tree for a schema-first integration — `next`, `node-agent`, or `plain`, with a `data-source` (your own database) endpoint. |
+| `scaffold_app` | Emits a starter file tree for a schema-first integration: `next`, `node-agent`, or `plain`, with a `data-source` (your own database) endpoint. |
 
 #### Resources
 
@@ -132,7 +132,7 @@ loading everything into context.
 
 Reusable, parameterised templates that drive an end-to-end flow:
 
-- `integrate-sync-engine` — wire the SDK into an existing project.
+- `integrate-ablo` — wire the SDK into an existing project.
 - `add-agent` — add an agent worker that coordinates via claims and
   conflict-safe writes.
 - `define-schema` — design a Zod-first schema from a description, then run

package/docs/migration.md

@@ -13,7 +13,8 @@ change when you upgrade.
 
 | Version | What changed | What to do |
 |---|---|---|
-| **0.35.0** | Synchronous reads moved under `local`, mirroring the async verbs | `get(id)` → `local.retrieve(id)`; `getAll(options)` → `local.list(options)`; `getCount(options)` → `local.count(options)` |
+| **0.36.0** | `ttlSeconds` deprecated on the join surfaces in favour of `ttl` | `useJoin({ scope, ttlSeconds: '5m' })` → `useJoin({ scope, ttl: '5m' })`; same for `ParticipantJoinOptions`. Both spellings work until 0.37.0 |
+| **0.35.0** | Synchronous reads moved under `local`, mirroring the async verbs | `get(id)` → `local.get(id)`; `getAll(options)` → `local.list(options)`; `getCount(options)` → `local.count(options)` |
 | **0.35.0** | `causedByTaskId` write option + seven `turn_*` error codes removed | Delete the `causedByTaskId` argument from writes; a branch on `turn_validation_failed` was unreachable and can go with it |
 | **0.34.0** | Presence verb renamed `watch` → `join` | `ablo.<model>.watch(ids)` → `ablo.<model>.join(ids)`; `useWatch` → `useJoin`; the `WatchOptions` / `UseWatchOptions` / `UseWatchReturn` types → `JoinOptions` / `UseJoinOptions` / `UseJoinReturn`; error code `model_watch_not_configured` → `model_join_not_configured` |
 | **0.28.0** | Removed React placeholders that had no working runtime | `usePresence` → `usePeers` or `useJoin`; `useClaim` → `ablo.<model>.claim`; `SyncGroupProvider` / `useSyncGroup` → `useJoin({ scope })` |
@@ -31,13 +32,31 @@ change when you upgrade.
 
 ---
 
-## 0.35.0 — the synchronous reads move under `local`
+## 0.36.0: one lease is spelled `ttl`
+
+```diff
+- useJoin({ scope: { documents: [id] }, ttlSeconds: '5m' })
++ useJoin({ scope: { documents: [id] }, ttl: '5m' })
+```
+
+`ablo.<model>.join(ids, { ttl })` has always said `ttl`, and so does every other
+lease in the SDK: `claim`'s `ttl`, `ClaimLeaseOptions.ttl`. The lower-level join
+surfaces said `ttlSeconds` while accepting exactly the same values, including
+duration strings, so a `ttl: '5m'` handed down from the model verb arrived as
+`ttlSeconds: '5m'`, a field asserting a unit its value did not carry.
+
+Both spellings work until 0.37.0, and `ttl` wins if you pass both. The wire is
+unchanged: it has always carried seconds and still does.
+
+---
+
+## 0.35.0: the synchronous reads move under `local`
 
 ```diff
 - const task  = ablo.tasks.get(id);
 - const open  = ablo.tasks.getAll({ where: { status: 'open' } });
 - const count = ablo.tasks.getCount({ where: { status: 'open' } });
-+ const task  = ablo.tasks.local.retrieve(id);
++ const task  = ablo.tasks.local.get(id);
 + const open  = ablo.tasks.local.list({ where: { status: 'open' } });
 + const count = ablo.tasks.local.count({ where: { status: 'open' } });
 ```
@@ -53,7 +72,7 @@ in most codebases it is outnumbered many times over by `Map.get` and
 the compiler name the sites — each one is a type error at exactly the call that
 has to move.
 
-## 0.35.0 — `causedByTaskId` and the `turn_*` error codes removed
+## 0.35.0: `causedByTaskId` and the `turn_*` error codes removed
 
 0.9.2 retired the `turn` primitive but left one field standing: `causedByTaskId`
 on the write options bag. It was never usable. The server validated it against a
@@ -85,7 +104,7 @@ migration of its own.
 
 ---
 
-## 0.34.0 — presence verb renamed `watch` → `join`
+## 0.34.0: presence verb renamed `watch` → `join`
 
 The model-level presence verb read like a data subscription but delivered
 presence — who else is on a row and what they hold — so it now says what it
@@ -108,7 +127,7 @@ no compatibility alias — rename the call sites and the `WatchOptions` /
 
 ---
 
-## 0.28.0 — dead React multiplayer placeholders removed
+## 0.28.0: dead React multiplayer placeholders removed
 
 Four React exports looked usable but had no live implementation:
 
@@ -123,7 +142,7 @@ Four React exports looked usable but had no live implementation:
 There is no compatibility alias: the replacement APIs were already the only
 working paths.
 
-## 0.11.0 — `intent` → `claim` rename completed
+## 0.11.0: `intent` → `claim` rename completed
 
 > **Historical note:** this section documents the 0.11.0 transition.
 > `useClaim` was subsequently removed in 0.28.0 because its provider callback
@@ -166,7 +185,7 @@ contending holders (`AbloClaimedError.claims` and a policy reason folded into th
 message), and `participantKind` is the canonical `'user' | 'agent' | 'system'`
 on presence and claim state.
 
-## 0.10.0 — environment enum `sandbox` / `production`; stateless HTTP transport
+## 0.10.0: environment enum `sandbox` / `production`; stateless HTTP transport
 
 ### Environment enum rename (the only breaking change)
 
@@ -222,7 +241,7 @@ await ablo.tasks.update({ id, data: { status: 'done' } });
 
 ---
 
-## 0.9.2 — `turn` / agent-`tasks` removed; `intents` deprecated
+## 0.9.2: `turn` / agent-`tasks` removed; `intents` deprecated
 
 The SDK's coordination surface is now exactly two things: `ablo.<model>` writes
 and `claim`. The parallel `turn` / agent-`tasks` mechanism was redundant —
@@ -271,7 +290,7 @@ everywhere you coordinate concurrent work.
 
 ---
 
-## 0.9.0 — one options object per verb; disposable `claim`
+## 0.9.0: one options object per verb; disposable `claim`
 
 Every model verb takes a single options object, so the id, the data, and every
 modifier are named siblings. Reactive local reads stay on the synchronous
@@ -285,7 +304,7 @@ modifier are named siblings. Reactive local reads stay on the synchronous
 + await ablo.tasks.retrieve({ id })
 
 - useAblo((ablo) => ablo.tasks.retrieve(id)) ?? serverTask
-+ useAblo((ablo) => ablo.tasks.local.retrieve(id)) ?? serverTask
++ useAblo((ablo) => ablo.tasks.local.get(id)) ?? serverTask
 ```
 
 `claim` now returns a disposable handle instead of taking a callback. The handle
@@ -305,7 +324,7 @@ options object.
 
 ---
 
-## 0.8.0 — callable `claim` namespace
+## 0.8.0: callable `claim` namespace
 
 The flat coordination methods are gone; everything lives under `claim`.
 
@@ -318,7 +337,7 @@ The flat coordination methods are gone; everything lives under `claim`.
 
 ---
 
-## 0.7.0 — legacy React hooks removed
+## 0.7.0: legacy React hooks removed
 
 The query/mutation hooks were replaced by the single `useAblo()` accessor over
 typed model methods.
@@ -340,7 +359,7 @@ shape with the canonical `{ type, code, message, doc_url, request_id }` envelope
 
 ---
 
-## 0.6.0 — `onChange` and the Resource → Model rename
+## 0.6.0: `onChange` and the Resource → Model rename
 
 ```diff
 - ablo.tasks.subscribe(cb)
@@ -356,7 +375,7 @@ Also renamed: `Ablo.Resource.*` → `Ablo.Model.*`, `ModelTarget.resource` →
 
 ---
 
-## 0.5.0 — intent-handle method renames
+## 0.5.0: intent-handle method renames
 
 On the model intent handle (`ablo.<model>.intent(id)`):
 
@@ -373,7 +392,7 @@ unchanged at this release. (They were later folded under `claim` in 0.9.2.)
 
 ---
 
-## 0.3.0 — umbrella `<AbloProvider>`
+## 0.3.0: umbrella `<AbloProvider>`
 
 One provider component now owns the full React lifecycle. `<SyncProvider>`,
 `createAbloContext()`, and `withSync` were removed.
@@ -407,10 +426,10 @@ old code or old docs, this is the through-line:
 
 | Release | State of coordination |
 |---|---|
-| 0.4.0 | `ablo.<model>.intent(id)` introduced — per-entity intent handle |
+| 0.4.0 | `ablo.<model>.intent(id)` introduced: per-entity intent handle |
 | 0.5.0 | Intent-handle methods renamed to claim vocabulary (`acquire`→`claim`, …) |
 | 0.8.0 | Callable `claim` namespace (`claim(id)`, `claim.state`, `claim.queue`, …) |
 | 0.9.0 | `claim` returns an `await using` disposable handle |
-| 0.9.2 | `intents` deprecated and made `@internal` — **`claim` is the one coordination API** |
+| 0.9.2 | `intents` deprecated and made `@internal`: **`claim` is the one coordination API** |
 
 For the full chronological history, see the [Changelog](../CHANGELOG.md).

package/docs/projects.md

@@ -95,5 +95,5 @@ another org's project ids 404 — never confirm existence across orgs.
 
 | Code | Status | Meaning |
 |------|--------|---------|
-| `project_scope_denied` | 403 | The model/resource belongs to another project in your org — use a key minted for that project. |
+| `project_scope_denied` | 403 | The model/resource belongs to another project in your org: use a key minted for that project. |
 | `project_slug_taken` | 409 | A project with this slug already exists in the organization. |

package/docs/quickstart.md

@@ -215,12 +215,12 @@ const updated = await ablo.weatherReports.update({
 console.log({ id: updated.id, status: updated.status }); // { id: '...', status: 'ready' }
 ```
 
-Read a single row back with `retrieve({ id })`. It resolves to the row, or to
+Read a single row back with `get({ id })`. It resolves to the row, or to
 `undefined` when no row has that id — so narrow it once, then the fields are
 fully typed:
 
 ```ts
-const report = await ablo.weatherReports.retrieve({ id: created.id });
+const report = await ablo.weatherReports.get({ id: created.id });
 if (!report) throw new Error(`weatherReports ${created.id} not found`);
 
 console.log(report.status); // 'ready'

package/docs/react.md

@@ -27,6 +27,7 @@ the thing, then pass it.
 ```ts
 // lib/ablo.ts
 import Ablo from '@abloatai/ablo';
+import { createAbloReact } from '@abloatai/ablo/react';
 import { schema } from '@/ablo/schema';
 
 // The browser never holds your API key. It mints a short-lived session token
@@ -35,8 +36,18 @@ export const ablo = Ablo({
   schema,
   authEndpoint: '/api/ablo-session',
 });
+
+// The typed binding: capture the schema once, and every component imports
+// born-typed hooks from this file — `useAblo()` takes no type arguments,
+// and a selector's `ablo` parameter knows your models.
+export const { AbloProvider, useAblo } = createAbloReact(schema);
 ```
 
+Import `AbloProvider` and `useAblo` from `lib/ablo` rather than from the
+package, and the schema generic never appears at a call site again — the
+same one-binding-file convention as tRPC's `createTRPCReact` or
+react-redux's typed hooks.
+
 ## AbloProvider
 
 Mount it once near the root of your tree. It owns the connection, the local
@@ -67,10 +78,10 @@ export function Providers({
 
 | Prop        | Default          | Purpose                                                                                                   |
 | ----------- | ---------------- | --------------------------------------------------------------------------------------------------------- |
-| `client`    | —                | **Required.** The `Ablo({ schema, apiKey })` instance. It carries the schema and connection config. |
+| `client`    |: | **Required.** The `Ablo({ schema, apiKey })` instance. It carries the schema and connection config. |
 | `userId`    | resolved from auth | App participant id for app-owned fields and your `identityRoles`. Not the security boundary.            |
 | `fallback`  | neutral spinner  | Rendered during the *first* bootstrap only. Pass a branded skeleton, `null`, or `'passthrough'`.          |
-| `onError`   | —                | Engine / WebSocket / bootstrap errors. Wire to Sentry / Datadog.                                          |
+| `onError`   |: | Engine / WebSocket / bootstrap errors. Wire to Sentry / Datadog.                                          |
 
 Everything that used to be a provider prop — `schema`, `url`, `apiKey`,
 `teamIds`, `syncGroups`, `persistence`, `bootstrapMode` — now lives on
@@ -79,7 +90,7 @@ identity comes from, and why the API key never reaches the browser, is the whole
 of [Identity & Sync Groups](./identity.md) — read that if it isn't obvious how
 org / team / user map to what a participant can see.
 
-## useAblo — model client
+## useAblo: model client
 
 ```tsx
 'use client';
@@ -87,7 +98,7 @@ org / team / user map to what a participant can see.
 import { useAblo } from '@abloatai/ablo/react';
 
 export function ReportView({ report: serverReport }: { report: { id: string; location: string } }) {
-  const report = useAblo((ablo) => ablo.weatherReports.local.retrieve(serverReport.id)) ?? serverReport;
+  const report = useAblo((ablo) => ablo.weatherReports.local.get(serverReport.id)) ?? serverReport;
   const active = useAblo((ablo) => ablo.weatherReports.claim.state({ id: serverReport.id }));
   const claimed = Boolean(active);
 
@@ -97,7 +108,7 @@ export function ReportView({ report: serverReport }: { report: { id: string; loc
 
 The hook:
 
-1. Uses the same `ablo.<model>.local.retrieve(id)` / `.local.list()` methods you'd call anywhere
+1. Uses the same `ablo.<model>.local.get(id)` / `.local.list()` 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.
@@ -112,7 +123,7 @@ effects, or writes:
 const abloClient = useAblo();
 ```
 
-Prefer selector reads like `useAblo((ablo) => ablo.<model>.local.retrieve(id))`. Older hooks
+Prefer selector reads like `useAblo((ablo) => ablo.<model>.local.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:
@@ -130,12 +141,12 @@ const reports = useAblo((ablo) =>
 ## Server Load
 
 ```tsx
-const report = await ablo.weatherReports.retrieve({ id });
+const report = await ablo.weatherReports.get({ id });
 ```
 
 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
+`await` it. (Server reads come in two shapes: `get({ id })` for one row and
 `list({ where })` for many; both are async. The synchronous local reads are
 the `local` reads, used in render below.)
 
@@ -180,7 +191,7 @@ imperative work after an event or effect.
 
 See [API reference](/docs/api) for the full options surface.
 
-## useJoin — scoped presence + read interest
+## useJoin: scoped presence + read interest
 
 `useJoin` is the React form of `ablo.<model>.join`. It joins multiplayer for a
 scope on the engine's existing socket (one TCP connection, N logical
@@ -209,10 +220,10 @@ Options (`UseJoinOptions`):
 
 | Option | Default | Effect |
 | --- | --- | --- |
-| `scope` | — | Model-form scope (`{ slideDecks: id }`), resolved through the schema. Omit for engine-wide. |
-| `claim` | `false` | Acquire a write-claim on the scope (sent so peers observe it; pins the scope so it never warm-drops while held). A viewer is not a claimant — leave `false` for read-only. |
+| `scope` |: | Model-form scope (`{ slideDecks: id }`), resolved through the schema. Omit for engine-wide. |
+| `claim` | `false` | Acquire a write-claim on the scope (sent so peers observe it; pins the scope so it never warm-drops while held). A viewer is not a claimant: leave `false` for read-only. |
 | `hydrate` | `false` | Backfill the scope's current rows into the pool once on enter, then keep them fresh via the live tail. Set `true` for deep-linked / never-opened entities. Single-flight; soft-fails. |
-| `ttlSeconds` | — | Lease TTL for the scope claim. |
+| `ttlSeconds` |: | Lease TTL for the scope claim. |
 | `paused` | `false` | Tear down and don't re-join while true. |
 
 Returns (`UseJoinReturn`): `{ participant, peers, claims, status, error }`.
@@ -220,7 +231,7 @@ Returns (`UseJoinReturn`): `{ participant, peers, claims, status, error }`.
 write-claims; `status` is the join lifecycle. Auto-cleans up on unmount or when
 `paused` flips true.
 
-## usePeers — read-only presence
+## usePeers: read-only presence
 
 `usePeers` is a *pure reader* of the presence stream already flowing on the
 connection. Unlike `useJoin`, it does **not** enter/leave a scope (no

package/docs/schema-contract.md

@@ -12,7 +12,7 @@ defineSchema(...) -> ablo.<model>.create/retrieve/update/claim(...)
 That one object drives:
 
 - typed model clients in trusted server runtimes,
-- React selectors through `useAblo((ablo) => ablo.<model>.local.retrieve(id))`,
+- React selectors through `useAblo((ablo) => ablo.<model>.local.get(id))`,
 - agent and background-worker writes,
 - Data Source request/response shape when your database stays canonical,
 - hosted schema push, migration planning, and schema-version gating.
@@ -70,14 +70,14 @@ readable, you just don't author them.
 Use async reads when the row may not be local:
 
 ```ts
-const report = await ablo.weatherReports.retrieve({ id: reportId });
+const report = await ablo.weatherReports.get({ id: reportId });
 const ready = await ablo.weatherReports.list({ where: { status: 'ready' } });
 ```
 
 Use synchronous local reads in render after data has synced:
 
 ```ts
-const report = ablo.weatherReports.local.retrieve(reportId);
+const report = ablo.weatherReports.local.get(reportId);
 const pending = ablo.weatherReports.local.list({ where: { status: 'pending' } });
 ```
 

package/docs/sessions.md

@@ -10,20 +10,23 @@ difference is the subject and how much authority it carries.
 One resource mints both:
 
 ```ts Your backend (sk_)
-// A logged-in person's browser session — full authority within their org.
+// A logged-in person's browser session — only the operations this UI needs.
 const userSession = await ablo.sessions.create({
   user: { id: currentUser.id },
+  can: { tasks: ['read', 'update'], workspaces: ['read'] },
 });
 
-// A scoped agent session — gated to exactly the operations you name.
-const agentSession = await ablo.sessions.create({
-  agent: { id: 'agent:task-writer' },
-  can: { Task: ['read', 'update'], Workspace: ['read'] },
+// Recommended agent path — returns a ready, scoped client.
+const agent = await ablo.agents.create({
+  name: 'task-writer',
+  can: { tasks: ['read', 'update'], workspaces: ['read'] },
 });
 ```
 
-`user` mints an `ek_` (ephemeral key); `agent` mints an `rk_` (restricted key).
-You pass `user` **or** `agent` — never both.
+`sessions.create({ user, can })` mints an `ek_` (ephemeral key).
+`agents.create({ can })` mints and manages an `rk_` (restricted key). Use the
+lower-level `sessions.create({ agent, can })` only when another runtime needs
+the raw agent token.
 
 It exists because of one rule: **the browser can never hold a secret.** Your
 `sk_` lives on the server; the browser only ever holds a minted session token
@@ -45,15 +48,24 @@ For a logged-in person using your app. Mint on a backend route that has already
 authenticated the user:
 
 ```ts Your backend route (session-authed)
-const { token } = await ablo.sessions.create({
+import { credentialEndpointSuccessSchema } from '@abloatai/ablo/auth';
+
+const { token, expiresAt } = await ablo.sessions.create({
   user: { id: currentUser.id },   // who the session acts as
+  can: { tasks: ['read', 'update'] },
   // syncGroups: [...],           // optional; defaults to the user's org + user
 });
-return Response.json({ token });  // return ONLY the token to the browser
+return Response.json(
+  credentialEndpointSuccessSchema.parse({
+    token,
+    expiresAt,
+    credentialKind: 'ephemeral',
+  }),
+  { headers: { 'Cache-Control': 'no-store' } },
+);
 ```
 
-A user session has **full data authority** within its org — no operation
-allowlist. It's the human acting as themselves.
+`can` is required. The mint fails closed when the grant is absent or empty.
 
 Point a browser `Ablo` client's `authEndpoint` at that route, and pass
 the **instance** to [`<AbloProvider>`](/react). The client fetches the token,
@@ -84,7 +96,7 @@ the socket. Need custom headers or a
 body on the exchange? `authEndpoint` also accepts an async resolver that
 returns the token.
 
-## Agent sessions (`rk_`)
+## Agents (`rk_`)
 
 For a non-human actor — an agent or automation that should only do **specific**
 operations. The `can` map is the permission boundary, and it's **typed against
@@ -92,23 +104,45 @@ your schema** — the model keys are your schema's models, so a typo is a compil
 error, not a silent over-grant:
 
 ```ts
-const session = await ablo.sessions.create({
-  agent: { id: 'agent:task-writer' },
-  can: { Task: ['read', 'update'] },  // typed off the schema — no magic strings
+const agent = await ablo.agents.create({
+  name: 'task-writer',
+  can: { tasks: ['update'] },  // typed off the schema — no magic strings
   ttlSeconds: 600,
 });
 
-const agent = Ablo({ schema, apiKey: session.token }); // the agent's scoped client
+await agent.tasks.update({ id, data });
+await agent.dispose();
 ```
 
-`can: { Task: ['update'] }` serializes to the wire allowlist `task.update`; the
-server rejects any commit whose operation isn't listed. Operations are
-`'read' | 'create' | 'update' | 'delete'`.
+The returned client refreshes its own short-lived credential. A write grant
+automatically includes the corresponding read, so
+`can: { tasks: ['update'] }` is enforced as `task.update` plus `task.read`.
+Operations are `'read' | 'create' | 'update' | 'delete'`.
+
+For a reusable grant, use TypeScript's `satisfies`. It checks the object against
+the schema while preserving its narrow literals—there is no string parser or
+second permission model:
+
+```ts
+import type { CapabilityGrant } from '@abloatai/ablo/auth';
+import { schema } from './ablo.schema';
+
+const taskWriterCan = {
+  tasks: ['update'],
+} satisfies CapabilityGrant<typeof schema>;
+
+const agent = await ablo.agents.create({ can: taskWriterCan });
+```
+
+`documents` instead of `tasks`, or `'write'` instead of `'update'`, is a compile
+error. At runtime the SDK parses the same grant with the schema-bound Zod
+contract before minting, and the server validates it again against the active
+pushed schema.
 
 <Note>
-Use `sessions.create({ agent })` to mint a scoped agent credential, then write
-with `ablo.<model>.update(...)` / `ablo.commits.create(...)` under a `claim`.
-This is the path for custom runtimes, MCP sessions, and protocol-level integrations.
+Use `sessions.create({ agent, can })` when a separate runtime, MCP process, or
+protocol integration needs the raw token. For an agent running in the current
+server process, prefer `agents.create({ can })`.
 </Note>
 
 ## Mint
@@ -120,7 +154,7 @@ for the actor.
 | Param | For | Meaning |
 |---|---|---|
 | `user` / `agent` | both | The actor. `id` becomes the token's `participantId`. Pass exactly one. |
-| `can` | agent | Per-model operation allowlist, typed off the schema. |
+| `can` | both | Required non-empty per-model operation allowlist, typed off the schema. |
 | `syncGroups` | both | Narrow the session below its default scope. Omit to inherit. |
 | `ttlSeconds` | both | Lifetime in seconds. Defaults to `900` (15m). |
 | `userMeta` | both | Opaque identity blob echoed back to the client. |
@@ -129,8 +163,28 @@ for the actor.
 
 Sessions are **short-lived by design** (~15 minutes) and, for browsers,
 **auto-refreshed** — the provider re-mints ahead of expiry, so a session never
-drops at the boundary. A revoked or signed-out actor simply stops getting a fresh
-token; the old one expires on its own. There's nothing to revoke by hand.
+drops at the boundary. Signing out stops refresh and the old token expires on
+its own.
+
+Revoke immediately when a token is exposed or an actor loses access:
+
+```ts
+await ablo.sessions.revoke({ id: session.id });
+```
+
+Agent sessions can rotate with overlap so a worker can adopt the replacement
+before the previous token expires:
+
+```ts
+const replacement = await ablo.sessions.rotate({
+  id: session.id,
+  graceSeconds: 300,
+  ttlSeconds: 900,
+});
+```
+
+Browser `ek_` sessions rotate through `authEndpoint`; do not distribute rotated
+browser tokens manually.
 
 ### Offline & sign-out
 
@@ -145,20 +199,19 @@ those two lifetimes separate, which means:
   connectivity or tab focus returns. The user stays signed in for as long as
   your underlying session is valid, however brief or long the network drop.
 - **The user is signed out only when the underlying session is genuinely
-  rejected** — i.e. your `authEndpoint` responds **`401`/`403`** because the
-  cookie (or IdP session) is missing, expired, or revoked. That's the one
-  signal the provider treats as terminal.
+  gone** — your `authEndpoint` responds `401` with the canonical
+  `{ error: { code: 'session_expired' } }` body. An unrelated `401` or `403`
+  is a policy/configuration failure, not proof that the login ended.
 
 This mirrors the OAuth refresh-token rule (Okta/Auth0/Authgear): only a
 rejection of the *long-lived* credential ends the session — a network failure
 never does.
 
 <Note>
-Your `authEndpoint` contract follows from this: return the token on success,
-respond **`401`/`403`** only when the user's session is actually gone, and let
-network/`5xx` failures surface as errors. Don't collapse "can't reach the mint
-endpoint" into "session expired" — returning a `401` for a transient blip will
-bounce a still-valid user to your sign-in page.
+Use `credentialEndpointSuccessSchema` and `credentialEndpointErrorSchema` from
+`@abloatai/ablo/auth` on the route. Return `session_expired` only when the
+application login is actually gone, and let network/`5xx` failures surface as
+errors.
 </Note>
 
 ## Scope
@@ -175,8 +228,8 @@ Your schema lives in a **project** — you push it once (`npx ablo push`) and ev
 session you mint resolves against it. The flow for serving end-users:
 
 1. **Push your schema** to your project.
-2. **Mint an `ek_` per user** — `sessions.create({ user: { id } })`. Your users
-   commit to that one schema.
+2. **Mint an `ek_` per user:** `sessions.create({ user: { id }, can })`. Your
+   users commit to that one schema with only the operations in `can`.
 
 **Your users do not have Ablo accounts.** You authenticate them however you
 already do; your server's `sk_` mints the `ek_`. By default the session lands in
@@ -205,6 +258,7 @@ const { token } = await mintUserSessionKey({
     organizationId: schemaOwnerOrgId,
     projectId: schemaProjectId,
   },
+  operations: ['task.read', 'task.update'],
   ttlSeconds: 3600,
 });
 ```
@@ -234,6 +288,6 @@ compromise — which is exactly why it never leaves your server.
 | | User session (`ek_`) | Agent session (`rk_`) |
 |---|---|---|
 | For | a **person** in the browser | an **agent** / automation |
-| Authority | full, within their org | narrow (explicit `can` allowlist) |
-| Mint | `ablo.sessions.create({ user: { id } })` | `ablo.sessions.create({ agent: { id }, can })` |
+| Authority | narrow (explicit `can` allowlist) | narrow (explicit `can` allowlist) |
+| Mint | `ablo.sessions.create({ user: { id }, can })` | `ablo.sessions.create({ agent: { id }, can })` |
 | Lives where | the user's **browser** | the agent runtime |