@abloatai/ablo 0.16.1 → 0.16.3

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.16.3
+
+### Patch Changes
+
+- **Docs.** The bundled SDK docs are now the single source for the documentation
+  site, and several pages were expanded or corrected:
+  - The sessions/identity model is reframed around **projects** — push one schema
+    to a project, mint an `ek_` per user (your users need no Ablo account), and
+    all of them commit to that one schema. Per-customer org isolation
+    (`schemaProject`) is presented as the add-on it is, not the default.
+  - The declarative `conflict` schema axis (Axis 3) is now documented.
+  - The agent docs were corrected to the current claim vocabulary
+    (`reason`/`queue`, not the pre-0.12.0 `action`/`wait`).
+
+  No code changes.
+
+## 0.16.2
+
+### Patch Changes
+
+- **`mintUserSessionKey`: name the shared-schema binding around the project.** The
+  two flat options added in 0.16.0 (`schemaOwnerOrgId` + `schemaProjectId`) are
+  replaced by one project-centric option — `schemaProject: { organizationId, projectId }` —
+  naming "the project that owns the schema" as a single concept. The wire format
+  is unchanged (the SDK still sends the same keys), so no server redeploy is
+  needed. Released as a patch: the replaced options shipped in 0.16.0 and have no
+  external consumers yet.
+
+  ```ts
+  // before
+  mintUserSessionKey({ organizationId, schemaOwnerOrgId, schemaProjectId, ... });
+  // after
+  mintUserSessionKey({
+    organizationId,                                  // data org
+    schemaProject: { organizationId, projectId },    // the project that owns the schema
+    ...
+  });
+  ```
+
 ## 0.16.1
 
 ### Patch Changes
@@ -10,7 +49,7 @@
   `ABLO_AUTH_URL`), while the human approval page (`/cli`), sign-up, and the
   key-handoff route (`/api/cli/provision-key`) go to the dashboard host
   (`www.abloatai.com`, new override `ABLO_DASHBOARD_URL`). Previously every step
-  ran against `www`, where the Better Auth device endpoints no longer resolve —
+  ran against `www`, where the device endpoints no longer resolve —
   producing "Couldn't start login… Is the dashboard reachable?". The CLI now also
   builds the approval URL itself rather than trusting the server's
   `verification_uri`, which (being a relative `/cli`) resolved against the auth

package/dist/auth/index.d.ts

@@ -38,13 +38,18 @@ export interface MintUserSessionRequest {
      *  `Stripe-Account` analogue. Requires the `sk_` to carry
      *  `ephemeral:mint-any-org`; omit to mint into the key's own org. */
     readonly organizationId?: string;
-    /** FIRST-PARTY SHARED SCHEMA: bind the minted `ek_` to a schema owner-org +
-     *  project so SCHEMA resolves org-independently (one schema for all the
-     *  integrator's end-user orgs), while DATA stays scoped to `organizationId`.
-     *  Requires the `sk_` to carry `ephemeral:mint-any-org`. Omit for the normal
-     *  per-org behaviour (every external BYO customer). */
-    readonly schemaProjectId?: string;
-    readonly schemaOwnerOrgId?: string;
+    /** SHARED SCHEMA — point this session's SCHEMA at the project that owns it,
+     *  while its DATA stays scoped to `organizationId`. Use this for org-per-customer
+     *  isolation: keep one schema project, and every customer's session resolves its
+     *  schema from it instead of re-pushing the schema into each customer's org.
+     *  Requires the `sk_` to carry `ephemeral:mint-any-org`. Omit for the default
+     *  (the session resolves its schema from its own org). */
+    readonly schemaProject?: {
+        /** The org that owns the schema project. */
+        readonly organizationId: string;
+        /** The project the schema was pushed under. */
+        readonly projectId: string;
+    };
     readonly syncGroups?: readonly string[];
     readonly ttlSeconds: number;
     readonly label?: string;

package/dist/auth/index.js

@@ -108,8 +108,14 @@ export async function mintUserSessionKey(options) {
             body: JSON.stringify({
                 user: { id: options.userId },
                 ...(options.organizationId ? { organizationId: options.organizationId } : {}),
-                ...(options.schemaProjectId ? { schemaProjectId: options.schemaProjectId } : {}),
-                ...(options.schemaOwnerOrgId ? { schemaOwnerOrgId: options.schemaOwnerOrgId } : {}),
+                // Flattened to the existing wire keys — the public param is project-centric,
+                // the transport contract is unchanged (no coordinated server deploy needed).
+                ...(options.schemaProject
+                    ? {
+                        schemaProjectId: options.schemaProject.projectId,
+                        schemaOwnerOrgId: options.schemaProject.organizationId,
+                    }
+                    : {}),
                 ...(options.syncGroups ? { syncGroups: options.syncGroups } : {}),
                 ttlSeconds: options.ttlSeconds,
                 ...(options.label ? { label: options.label } : {}),

package/dist/cli.cjs

@@ -280564,7 +280564,8 @@ function parseProjectFlag(argv) {
   const eq = argv.find((a) => a.startsWith("--project="));
   return eq ? eq.slice("--project=".length) || void 0 : void 0;
 }
-async function deviceLogin(argv) {
+async function deviceLogin(argv, deps = {}) {
+  const openUrl = deps.openUrl ?? openBrowser;
   Ie(`${brand("ablo")} login`);
   const requested = parseProjectFlag(argv) ?? getActiveProject()?.slug;
   const targetProject = requested === DEFAULT_PROFILE ? void 0 : requested;
@@ -280599,7 +280600,7 @@ async function deviceLogin(argv) {
   Me(`${import_picocolors7.default.bold(code.user_code)}
 
 ${import_picocolors7.default.dim(url)}`, "Approve in your browser");
-  openBrowser(url);
+  openUrl(url);
   const s = Y2();
   s.start("Waiting for approval\u2026");
   let pollMs = (code.interval ?? 5) * 1e3;
@@ -280690,8 +280691,8 @@ ${import_picocolors7.default.dim(url)}`, "Approve in your browser");
     `${import_picocolors7.default.green("\u2713")} Logged in ${import_picocolors7.default.dim("(sandbox)")}${where}. Run ${import_picocolors7.default.bold("npx ablo push")} to push your schema.`
   );
 }
-async function login(argv = []) {
-  await deviceLogin(argv);
+async function login(argv = [], deps = {}) {
+  await deviceLogin(argv, deps);
 }
 function logout() {
   const removed = clearCredential();

package/docs/agent-messaging.md

@@ -0,0 +1,149 @@
+# Agent Messaging
+
+Use a normal model when agents or humans need durable communication inside a
+syncGroup. Use claim `description` and `meta` for live coordination context.
+Use a `messages` row when the information must survive reconnects, work over
+HTTP, or be replayed from the sync cursor.
+
+## The rule
+
+| Need | Use | Why |
+| --- | --- | --- |
+| "I am holding this row because..." | `claim({ reason, description, meta })` | Live and low-latency. Peers see it through presence while the claim exists. |
+| "Remember this handoff/status/request" | A `messages` model | Durable row. Ordered in `sync_deltas`, replayed after reconnect, readable by HTTP agents. |
+
+Claim context is ephemeral. If a participant was offline, reconnected later, or
+only uses `transport: "http"`, it can miss claim/presence frames. Message rows
+are facts in your database and in the sync log.
+
+## Schema
+
+Add a `messages` model to the same schema as the work it discusses. Scope it
+with the same field that scopes the work row.
+
+```ts
+import Ablo from "@abloatai/ablo";
+import { defineSchema, entityRole, model, z } from "@abloatai/ablo/schema";
+
+export const schema = defineSchema({
+  workItems: model(
+    {
+      title: z.string(),
+      status: z.string(),
+      teamId: z.string(),
+    },
+    {},
+    { entityRoles: [entityRole({ kind: "team", source: "teamId" })] },
+  ),
+
+  messages: model(
+    {
+      body: z.string(),
+      kind: z.enum(["status", "request", "handoff"]),
+      teamId: z.string(),
+
+      // Causal link back to coordination or the row being discussed.
+      aboutEntityType: z.string().optional(),
+      aboutEntityId: z.string().optional(),
+      aboutIntentId: z.string().optional(),
+    },
+    {},
+    { entityRoles: [entityRole({ kind: "team", source: "teamId" })] },
+  ),
+});
+```
+
+Push the schema before agents call it:
+
+```bash
+npx ablo push
+```
+
+## Server-side agent
+
+Most server-side agents use the direct database path. Pass the schema, API key,
+database URL, and transport selector:
+
+```ts
+const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+  databaseUrl: process.env.DATABASE_URL,
+  transport: "http",
+});
+
+await ablo.ready();
+```
+
+`databaseUrl` is server-only. Browser clients must not receive it; live UIs use
+the default WebSocket transport with a minted user/session token.
+
+If your backend mints restricted agent tokens, register the database once from a
+secret-key server process as above. Workers using the restricted token can then
+construct `Ablo({ schema, authToken, transport: "http" })` because the project
+already has a registered data plane.
+
+## Link a message to a claim
+
+The claim id is the causal id. Store it in `aboutIntentId` when the message is
+about work currently protected by a claim.
+
+```ts
+const claim = await ablo.workItems.claim({
+  id: workItemId,
+  reason: "reformatting",
+  description: "normalizing the pricing table",
+  meta: { estimateSeconds: 120 },
+  queue: false,
+});
+
+try {
+  await ablo.messages.create({
+    id: crypto.randomUUID(),
+    data: {
+      body: "Taking the pricing table for about two minutes.",
+      kind: "status",
+      teamId,
+      aboutEntityType: "workItems",
+      aboutEntityId: workItemId,
+      aboutIntentId: claim.claimId,
+    },
+    wait: "confirmed",
+  });
+} finally {
+  await claim.release();
+}
+```
+
+Peers in `team:${teamId}` receive the message through the normal delta stream.
+Peers outside that syncGroup do not.
+
+## Reading messages
+
+Live clients read locally and update when deltas arrive:
+
+```ts
+const rows = ablo.messages.getAll({
+  where: { teamId },
+  orderBy: { createdAt: "asc" },
+});
+```
+
+HTTP agents read by request:
+
+```ts
+const rows = await ablo.messages.list({
+  where: { teamId },
+  orderBy: { createdAt: "asc" },
+});
+```
+
+Because messages are ordinary synced rows, reconnecting clients catch up from
+their cursor and see the rows they missed while offline.
+
+## Retention
+
+Deleting or archiving old `messages` rows is your app's policy. The sync log is
+still durable audit/history: `sync_deltas` has no message-specific TTL. That is
+useful for coordination and compliance, but a chat-scale product should plan
+retention before writing high-volume conversation traffic.

package/docs/agents.md

@@ -0,0 +1,104 @@
+# Agents
+
+An agent is a **reactive** participant: it wakes on something happening, reads
+what it needs, writes a result, and goes idle. That's a request/response
+workload — so agents talk to Ablo over **plain HTTP**, holding no WebSocket. The
+credential *is* the identity; the server resolves the org, scope, and actor from
+the key on every request (the Stripe server-SDK / Liveblocks-node shape).
+
+Humans get the live plane (WebSocket: presence, optimistic, sub-100ms). Agents
+get the stateless plane (HTTP). **Both operate on the same typed, coordinated
+state — and coordinate *with each other*.**
+
+<Note>
+Agents transact against your **pushed schema**, same as everyone — `ablo.tasks`
+exists because you defined a `task` model and ran `ablo push`. The key
+authenticates; the [schema](/quickstart) defines what you can call.
+</Note>
+
+## The agent client
+
+Same `Ablo()` entry point as everywhere else — pass `transport: 'http'`. No
+socket, no connection state — just your schema (for types) and an API key.
+
+```ts
+import Ablo from "@abloatai/ablo";
+import { schema } from "./schema";
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: "http" });
+
+// Reads + writes, fully typed off your schema — each is one HTTP round-trip:
+const open = await ablo.tasks.list({ where: { status: "todo" } });
+const { data } = await ablo.tasks.retrieve({ id: open[0].id });
+await ablo.tasks.update({ id: open[0].id, data: { status: "done" } });
+```
+
+It exposes `retrieve` / `list` / `create` / `update` / `delete`, plus `commits`
+and `claim`. It does **not** expose the stateful-only surface (`get` /
+`getAll` / `getCount` local reads, `onChange` live subscription) — those need a
+live connection, so with `transport: 'http'` the return type narrows and they
+are a *compile error*, not a runtime surprise.
+
+## Coordination — claim, queue, reorder
+
+The differentiator. A claim is a **durable lease + FIFO wait-line** on a row —
+"who's working on this, who's waiting" — and it's request/response, so an agent
+holds it over HTTP. This is how two agents (or an agent and a human) don't
+clobber the same record.
+
+```ts
+// Acquire a lease, do work with the held row, release on scope exit:
+await using claim = await ablo.tasks.claim({ id: taskId });
+const task = claim.data;
+// …no one else can hold this row while you work…
+await ablo.tasks.update({ id: task.id, data: { status: "in_review" } });
+
+await ablo.tasks.claim.state({ id: taskId });   // who holds it now (or null)
+await ablo.tasks.claim.queue({ id: taskId });   // the FIFO wait-line behind the holder
+await ablo.tasks.claim.reorder({ id: taskId, order: line }); // re-rank the line (privileged)
+```
+
+Think of it as a queue per row — a durable, inspectable, reorderable lease line
+("SQS for entity contention"). Use `{ queue: false }` for fail-fast dedup: *if
+someone else has this job, skip it.*
+
+## Messaging between agents
+
+Use claim `description` and `meta` for live "what I am doing now" context. Use
+ordinary synced rows for handoffs, status notes, and requests that must survive
+reconnects or be readable by HTTP agents. The recipe is a `messages` model
+scoped by the same syncGroup field as the work row, with `aboutIntentId` linking
+a message back to the claim it discusses.
+
+See [Agent Messaging](/agent-messaging) for the schema and direct
+`databaseUrl` setup.
+
+## Humans + agents on one state
+
+There's no separate "agent mode." A human editing a record over their WebSocket
+and an agent acting over HTTP share the same typed state and the same coordination
+plane: the agent can claim the row a human is editing (and wait in line), and the
+human sees the agent's committed changes stream in **live** — over the human's
+own socket, even though the agent committed over HTTP. You write the agent once;
+it's a first-class participant, not a bolt-on.
+
+## How an agent runs
+
+```text
+something happens ──▶ your agent (HTTP, no socket)
+  (a job, a webhook,     read context (list/retrieve)
+   a queue message)      claim → work → commit
+                         done — no held connection
+```
+
+Because it holds nothing open, an agent is a **stateless worker**: deploys and
+restarts are free, and you scale by adding workers. A long-running fleet of idle
+agents costs nothing on the live plane — that capacity stays for humans.
+
+## What stays on the live (human) plane
+
+`onChange` (live subscriptions) and `get`/`getAll`/`getCount` (local synced-pool
+reads) require a WebSocket and a local store — they're for interactive UIs, not
+stateless agents. An agent reacts to an external trigger (a job/queue/webhook),
+then reads with `list`/`retrieve`. See [client behavior](/client-behavior) for
+the full surface and [guarantees](/guarantees) for the coordination semantics.

package/docs/coordination.md

@@ -67,6 +67,73 @@ anything extra.
 
 ---
 
+## Declaring conflict behaviour in the schema (Axis 3)
+
+The two enforcement layers above are decided **per write** (claim a row, or pass
+`readAt` + `onStale`). You can also declare a model's **default** conflict
+disposition once, in the schema, so every commit to that model is governed
+without per-call wiring. This is the third coordination axis — orthogonal to
+`policy` (who may read a row) and `groups` (which delta channels it fans into).
+
+Add a `conflict` map to `model(...)`, keyed by the **committer's** participant
+kind (`user` / `agent` / `system`), with the same `onStale` vocabulary as values:
+
+| value | meaning |
+|---|---|
+| `'overwrite'` | the write wins; that committer is never blocked. |
+| `'reject'` | the write is refused; that committer yields to a held claim / stale snapshot. |
+| `'notify'` | hold the write and hand back the current value so the committer re-reads and re-applies (stale writes only). |
+
+```ts
+import { model, field } from '@abloatai/ablo/schema';
+
+export const card = model('card', {
+  title: field.string(),
+}, {
+  // "a human's edit always wins (never blocked); an agent yields"
+  conflict: { user: 'overwrite', agent: 'reject' },
+});
+```
+
+### Composable helpers
+
+For the same map with an authoring surface that reads like the rest of the DSL,
+use the disposition helpers and the `coordination(...)` combinator (a `cn`/`cx`
+for conflict policy — later rules win on key collisions):
+
+```ts
+import { model, field, coordination, humansOverwrite, agentsReject } from '@abloatai/ablo/schema';
+
+export const card = model('card', {
+  title: field.string(),
+}, {
+  conflict: coordination(humansOverwrite(), agentsReject()),
+  // → { user: 'overwrite', agent: 'reject' }
+});
+```
+
+Helpers, one per disposition: `humansOverwrite` / `humansReject` / `humansNotify`,
+`agentsOverwrite` / `agentsReject` / `agentsNotify`,
+`systemOverwrite` / `systemReject` / `systemNotify`.
+
+### How it relates to per-write coordination
+
+- The `conflict` map is **pure, serializable data**: it ships in your pushed
+  schema (`npx ablo push`) and the engine interprets it at the commit
+  chokepoint — there is no per-model code on the server.
+- An **omitted committer kind falls through to the engine default**: reject, and
+  honor a per-write `onStale: 'notify'`. Declaring `conflict` is purely
+  additive — existing schemas behave exactly as before.
+- It sets the **default** disposition; a per-write `onStale` and a held `claim`
+  still apply on top as described above. Think of `conflict` as "the house rule
+  for this model," and `claim` / `onStale` as what an individual write does
+  within it.
+
+The `ConflictAxis` type (also available as `Ablo.Conflict.Axis`) and the
+`interpretConflictAxis` interpreter are exported for composing custom policies.
+
+---
+
 ## The claim state object
 
 The claim state object is the live record that a participant is coordinating work on

package/docs/identity.md

@@ -156,6 +156,40 @@ The identity is a **participant** — and a participant is either a human
 [Agents are participants too](#agents-are-participants-too) below. Everything in
 the next two sections applies to both.
 
+## Your schema lives in a project; your users commit to it
+
+The default is simple: your schema lives in a **project**, you push it once, and
+every session you mint resolves against it. Your end-users **don't have Ablo
+accounts** — your server's `sk_` mints an `ek_` per user, and by default that
+session lands in your project's own org. All your users share one schema, one
+data tenant, isolated from each other by sync-groups. That's the whole story for
+most apps.
+
+**Add-on — org-per-customer isolation.** If you need each customer to be its own
+hard tenant (separate row-level isolation, optionally a separate database) you'd
+otherwise have to re-push your schema into every customer's org. Instead, keep one
+project as the home of your schema and point each customer's session's *schema*
+at it while its *data* stays in the customer's org:
+
+```ts
+await mintUserSessionKey({
+  apiKey: platformKey,   // sk_ with the `ephemeral:mint-any-org` scope
+  userId,
+  organizationId,                  // DATA → this customer's org (RLS-isolated tenant)
+  schemaProject: {                 // SCHEMA → the project that owns your schema
+    organizationId: schemaOwnerOrgId,
+    projectId: schemaProjectId,
+  },
+  ttlSeconds: 3600,
+});
+```
+
+Server-side, the model **shape** loads from your schema project but column
+enrichment and the tenant connection still target `organizationId` — so the
+shared schema only *describes* the shape; the data plane stays the customer's and
+can't cross-leak. Omit these fields for the default above. Requires a platform
+`sk_` with `ephemeral:mint-any-org`.
+
 ## The two halves of scoping
 
 Scoping is two declarations that meet in the middle. One describes the

package/docs/index.md

@@ -86,7 +86,6 @@ Three things stay true no matter how you use Ablo:
 - [AI SDK Tool](./examples/ai-sdk-tool.md) — Put Ablo inside an AI SDK tool call.
 - [Existing Python Backend](./examples/existing-python-backend.md) — Add multiplayer and future agent writes without replacing a Python API server.
 - [Agent + Human](./examples/agent-human.md) — Yield when a human is editing the same report.
-- [Agent Scoped to One Deck](./examples/scoped-agent.md) — Scope an agent to one entity with `scope` / `parent`; realtime for just that deck.
 - [Server Agent](./examples/server-agent.md) — Schema-backed worker.
 - [Next.js](./examples/nextjs.md) — App-router setup with React bindings.
 

package/docs/projects.md

@@ -0,0 +1,97 @@
+# Projects
+
+A **project** is the isolation unit inside your organization — the shape you
+know from Neon or Supabase. Each app you build gets its own project, and each
+project gets its own schema, its own sandbox/production data planes, and its
+own API keys. Two teams in one org can ship two apps that never see each
+other's models, keys, or rows.
+
+```text
+organization
+├── project: default          ← every org has one; pre-project apps live here
+│   ├── schema (sandbox + production artifacts)
+│   ├── data planes (registered databases)
+│   └── keys (sk_/rk_/ek_/pk_)
+└── project: my-app           ← npx ablo init creates this for a new app
+    ├── schema
+    ├── data planes
+    └── keys
+```
+
+## The default project
+
+Every organization has a **default** project. If you never create another
+one, everything works exactly as if projects didn't exist — your keys, schema
+pushes, and registered databases all belong to it. Keys minted before
+projects existed are default-project keys automatically.
+
+## Keys belong to exactly one project
+
+A key's project is fixed at mint and can never be changed or overridden —
+the same discipline as its sandbox/production mode. Everything a key mints
+inherits its project: the short-lived session credentials (`ek_`), agent
+keys (`rk_`), everything. There is no way to "switch projects" with an
+existing key; you use a key minted for the project you mean.
+
+Schema pushes, database registrations, reads, and writes all act on the
+**key's** project:
+
+- `npx ablo push` activates the schema for the pushing key's project — it
+  can never demote another project's schema.
+- Registering a database (`DATABASE_URL`) attaches it to the key's project
+  and environment.
+- A write or read against a model that belongs to **another** project in
+  your org fails with a typed `project_scope_denied` — never a silent empty
+  result, and never the misleading "unknown model, run ablo push".
+
+## Sandboxes belong to a project
+
+Production is singular per project; sandboxes are many. Each sandbox of a
+project gets its **own data plane** (its own registered dev database) but
+they all share the project's **one** sandbox schema — pushing the same
+schema from a second sandbox doesn't create a second artifact, it just
+provisions that sandbox's database.
+
+## CLI
+
+`npx ablo init` creates a project for your app automatically (slug derived
+from your `package.json` name; `--project <slug>` to choose, `--no-project`
+to stay on the org default). Manage projects any time:
+
+```bash
+npx ablo projects list             # all projects (default first)
+npx ablo projects create my-app    # create one (--name "Display Name")
+npx ablo projects use my-app       # set the ACTIVE project locally
+npx ablo projects use default      # back to the org default
+npx ablo status                    # shows the active project
+```
+
+The active project is a local targeting preference (stored next to `mode` in
+your CLI config): new keys you mint pick it up. It never changes what an
+existing key can reach — a key's project scope is decided server-side at
+mint.
+
+## API
+
+Projects are a Stripe-shaped control-plane resource, authenticated with a
+secret (`sk_`) key:
+
+```bash
+curl https://api.abloatai.com/api/v1/projects \
+  -H "Authorization: Bearer $ABLO_API_KEY"            # list
+
+curl https://api.abloatai.com/api/v1/projects \
+  -H "Authorization: Bearer $ABLO_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{"slug": "my-app", "name": "My App"}'           # create
+```
+
+A create with a taken slug fails with `project_slug_taken` (409). Reads of
+another org's project ids 404 — never confirm existence across orgs.
+
+## Errors
+
+| 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_slug_taken` | 409 | A project with this slug already exists in the organization. |

package/docs/react.md

@@ -295,5 +295,5 @@ unmount.
 
 ## Next.js
 
-The Next.js [App Router landing](/nextjs) walks through Server Components
+The Next.js [App Router landing](./examples/nextjs.md) walks through Server Components
 + Server Actions + `useAblo` together.

package/docs/sessions.md

@@ -0,0 +1,239 @@
+# Sessions
+
+A **session** is a short-lived credential your backend mints with its `sk_` and
+hands to one actor — a signed-in **person's browser** or a scoped **agent**. It's
+the same primitive in both cases (backend-minted, short-lived, scoped); the only
+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.
+const userSession = await ablo.sessions.create({
+  user: { id: currentUser.id },
+});
+
+// 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'], Deck: ['read'] },
+});
+```
+
+`user` mints an `ek_` (ephemeral key); `agent` mints an `rk_` (restricted key).
+You pass `user` **or** `agent` — never both.
+
+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
+(which already names your org). So the per-actor credential is minted
+server-side, scoped, and expires in minutes — the model Stripe uses for
+client-side SDKs.
+
+## Why
+
+Ablo doesn't authenticate your users — you do, however you like (your own
+sessions, an IdP, anything). Ablo authenticates your **project** (the `sk_` that
+minted the session) and trusts the identity you asserted at mint time. The
+session token *is* that assertion: "this connection is acting as `U`, in org
+`O`, until it expires."
+
+## End-user sessions (`ek_`)
+
+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({
+  user: { id: currentUser.id },   // who the session acts as
+  // syncGroups: [...],           // optional; defaults to the user's org + user
+});
+return Response.json({ token });  // return ONLY the token to the browser
+```
+
+A user session has **full data authority** within its org — no operation
+allowlist. It's the human acting as themselves.
+
+Build a browser `Ablo` client whose `getToken` fetches from that route, and pass
+the **instance** to [`<AbloProvider>`](/react). The client fetches the token,
+opens the connection, and re-mints before expiry — your app writes no token
+plumbing:
+
+```tsx
+'use client';
+
+import Ablo from '@abloatai/ablo';
+import { AbloProvider } from '@abloatai/ablo/react';
+import { schema } from '@/ablo.schema';
+
+const ablo = Ablo({
+  schema,
+  getToken: () =>
+    fetch('/api/ablo-session', { method: 'POST' })
+      .then((r) => r.json())
+      .then((d) => d.token),
+});
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <AbloProvider client={ablo}>{children}</AbloProvider>;
+}
+```
+
+The client owns auth, the credential lifecycle, and the connection; the provider
+is the thin reactive binding over it (Stripe's `<Elements stripe={...}>` model).
+Build the client **once** at module scope — a new instance per render tears down
+the socket. `authEndpoint: '/api/ablo-session'` is accepted as sugar for the
+`getToken` fetch above if you prefer a URL.
+
+## Agent sessions (`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
+your schema** — the model keys are your schema's models, so a typo is a compile
+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
+  ttlSeconds: 600,
+});
+
+const agent = Ablo({ schema, apiKey: session.token }); // the agent's scoped client
+```
+
+`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'`.
+
+<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.
+</Note>
+
+## Mint
+
+Only a **secret key** (`sk_`) can mint a session — never another session token.
+The `sk_` is the trust anchor; minting is your backend vouching
+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. |
+| `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. |
+
+## Lifecycle
+
+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.
+
+### Offline & sign-out
+
+The short session token is **not** your user's login — it's a minutes-long
+credential layered on top of whatever long-lived auth your `authEndpoint`
+already enforces (your own session cookie, an IdP, etc.). The provider keeps
+those two lifetimes separate, which means:
+
+- **Going offline never signs the user out.** The provider keeps working from
+  its local cache and treats a failed re-mint (no network, a timeout, a `5xx`
+  from your endpoint) as **transient** — it retries, and re-mints the instant
+  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.
+
+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.
+</Note>
+
+## Scope
+
+A user session carries the user's **base** sync-groups (`org:`/`user:`/`team:`),
+derived from the identity you minted it for. **Dynamic, relation-driven
+membership** (e.g. a `dataroom:<id>` the user was just added to) is resolved
+**server-side at connect** and unioned on top — so scope stays live, not frozen
+at mint time. Pass `syncGroups` only when you want to *narrow* below the default.
+
+## Your schema, your users (the default)
+
+Your schema lives in a **project** — you push it once (`npx ablo push`) and every
+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.
+
+**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
+your project's own org, so all your users share one schema and one data tenant,
+isolated from each other by sync-groups. For most apps (the Cursor shape) that's
+the whole story — nothing below is needed.
+
+## Org-per-customer isolation (the add-on)
+
+Some apps need each customer to be its **own** tenant — a hard data boundary
+(separate row-level isolation, optionally a separate database), not just per-user
+scoping. The law-firm shape (Legora): every firm is its own org, many users
+inside it.
+
+The problem that creates: if each customer is a separate org, a naïve setup would
+make you re-push your schema into every new customer's org. You don't have to.
+Keep **one** project as the home of your schema, and point each customer's
+session's *schema* at it while its *data* stays in the customer's own org:
+
+```ts
+const { token } = await mintUserSessionKey({
+  apiKey: process.env.ABLO_PLATFORM_KEY, // sk_ with the ephemeral:mint-any-org scope
+  userId,
+  organizationId,                  // DATA → this customer's org (its own isolated tenant)
+  schemaProject: {                 // SCHEMA → the project that owns your schema
+    organizationId: schemaOwnerOrgId,
+    projectId: schemaProjectId,
+  },
+  ttlSeconds: 3600,
+});
+```
+
+Server-side the split is clean: the model **shape** loads from your schema
+project, but column enrichment and the tenant connection target the customer's
+`organizationId` — so the shared schema only *describes* the shape; the data
+plane (connection + row-level isolation) stays the customer's. A shared schema
+can't leak data across orgs.
+
+<Note>
+This requires a platform `sk_` carrying the `ephemeral:mint-any-org` scope —
+only a trusted first-party key can mint a session into another org and bind its
+schema to your project. Omit these fields and you get the default above: one
+project, one schema, all your users.
+</Note>
+
+## Security
+
+The whole safety argument is the short TTL: a session token leaked from a
+browser (XSS) is valid for minutes, scoped to one actor's data, and can't mint
+anything or touch the control plane. Contrast `sk_`, which would be a full org
+compromise — which is exactly why it never leaves your server.
+
+## User vs. agent sessions
+
+| | 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 })` |
+| Lives where | the user's **browser** | the agent runtime |

package/docs/webhooks.md

@@ -0,0 +1,231 @@
+# Webhooks
+
+Ablo owns the ordered transaction log — the source of truth. **Webhooks are how
+that log reaches your database.** Ablo streams every committed change to an
+endpoint in your app as a signed event; your handler writes your own database.
+
+It's the same two-sided shape as Stripe: you call Ablo to make changes (the
+client), and Ablo calls you to persist them (this webhook). Ablo never holds your
+database credentials.
+
+## The loop
+
+```mermaid
+flowchart LR
+    App["Your app<br/>(the client)"]
+    subgraph Ablo["Ablo (hosted)"]
+        Log["Transaction log<br/><i>source of truth</i>"]
+    end
+    Clients["Other clients<br/>(live, optimistic)"]
+    Route["/api/ablo/[...all]<br/>(your webhook route)"]
+    DB[("Your database")]
+
+    App -->|write| Log
+    Log -->|realtime sync| Clients
+    Log -->|signed event| Route
+    Route -->|write| DB
+```
+
+There are two ways data flows out of Ablo, and they're for different jobs:
+
+| | reaches | use it for |
+|---|---|---|
+| **Realtime** (`useAblo`, WSS) | your live UI | instant, optimistic rendering |
+| **Webhooks** (this page) | your database | a durable copy you own — analytics, backups, server logic |
+
+Most apps use both: the realtime stream for the UI, the webhook stream to keep
+their database in sync. This page is the webhook stream.
+
+If you know Stripe, you already know the shape:
+
+| Stripe | Ablo |
+|---|---|
+| `stripe.x.create(...)` — make the change | the Ablo client — make the change (+ live sync) |
+| `/stripe-webhook` — confirm and persist | `/api/ablo/[...all]` — persist into your database |
+| Stripe owns the charges | Ablo owns the transaction log |
+| you mirror charges into your database | you mirror the log into your database |
+
+The difference in Ablo's favor: every event carries `syncId`, a monotonic log
+position, so you can both dedupe **and** apply in order — Ablo guarantees the
+order because it owns the log.
+
+## The event object
+
+Every delivery is a batch of events. Each event:
+
+| field | meaning |
+|---|---|
+| `type` | `"<model>.<verb>"`, e.g. `task.updated` |
+| `model` | the model name (`task`) — the table to write |
+| `objectId` | the changed row's id |
+| `data` | the post-change row, or `null` on delete (like Stripe's `event.data.object`) |
+| `syncId` | monotonic log position — **dedupe and order by this** |
+| `id` | `String(syncId)` — the event id |
+| `createdAt` | ISO commit timestamp |
+
+```ts
+import type { AbloWebhookEvent } from '@abloatai/ablo/webhooks';
+```
+
+## 1. Create a handler
+
+`npx ablo init` scaffolds this for you at `app/api/ablo/[...all]/route.ts`. If
+your project uses Prisma it's a **working generic mirror** — one upsert/delete
+for every model, no per-model code. Otherwise it's a neutral route with a single
+place to plug your database in.
+
+```ts app/api/ablo/[...all]/route.ts
+import { Webhook } from 'svix'; // any Standard Webhooks library
+import type { AbloWebhookEvent } from '@abloatai/ablo/webhooks';
+import { PrismaClient } from '@prisma/client';
+
+const wh = new Webhook(process.env.ABLO_WEBHOOK_SECRET!);
+const prisma = new PrismaClient();
+
+type ModelDelegate = {
+  upsert(a: { where: { id: string }; create: Record<string, unknown>; update: Record<string, unknown> }): Promise<unknown>;
+  delete(a: { where: { id: string } }): Promise<unknown>;
+};
+
+export async function POST(req: Request): Promise<Response> {
+  const body = await req.text(); // RAW body — required to verify
+  let batch: { data: AbloWebhookEvent[] };
+  try {
+    batch = wh.verify(body, Object.fromEntries(req.headers)) as { data: AbloWebhookEvent[] };
+  } catch {
+    return new Response('invalid signature', { status: 400 });
+  }
+
+  const delegates = prisma as unknown as Record<string, ModelDelegate | undefined>;
+  for (const event of [...batch.data].sort((a, b) => a.syncId - b.syncId)) {
+    const model = delegates[event.model];
+    if (!model) continue; // a model you don't mirror — skip
+    if (event.data === null) {
+      await model.delete({ where: { id: event.objectId } }).catch(() => {});
+    } else {
+      await model.upsert({ where: { id: event.objectId }, create: event.data, update: event.data });
+    }
+  }
+
+  return new Response(null, { status: 200 }); // 2xx = delivered
+}
+```
+
+You only edit this if your tables **diverge** from Ablo's schema (renamed
+columns, extra side effects) — add a `case` for that model before the generic
+mirror. If your tables match Ablo's, you never touch it.
+
+<Note>
+Return a `2xx` quickly. Any other status is a failure and is retried. Do heavy
+work asynchronously after responding.
+</Note>
+
+## 2. Test locally
+
+You don't register a `localhost` URL. `npx ablo dev` forwards committed changes
+to your machine with a local signing secret — the same idea as Stripe's
+`stripe listen`. Run your app, run `ablo dev`, and writes flow into your local
+handler.
+
+## 3. Register your endpoint
+
+For a deployed URL, register it once. Ablo mints the signing secret and returns
+it a single time — the CLI writes it straight into your `.env.local`.
+
+```bash
+npx ablo webhooks create https://yourapp.com/api/ablo/[...all]
+# ✓ Registered we_… → https://yourapp.com/api/ablo/[...all]
+# ✓ Wrote ABLO_WEBHOOK_SECRET to .env.local (shown once)
+```
+
+Manage and inspect endpoints:
+
+```bash
+npx ablo webhooks list          # endpoints + delivery health (status, cursor, last error)
+npx ablo webhooks roll <id>     # mint a fresh signing secret
+npx ablo webhooks enable <id>   # re-enable a disabled endpoint
+```
+
+Or call the API directly — the org is derived from your secret key:
+
+```bash
+curl https://api.abloatai.com/api/v1/webhook_endpoints \
+  -H "authorization: Bearer $ABLO_API_KEY" \
+  -H "content-type: application/json" \
+  -d '{ "url": "https://yourapp.com/api/ablo/[...all]" }'
+# → { "id": "we_…", "secret": "whsec_…", "status": "enabled", ... }
+```
+
+## 4. Verify the signature
+
+Ablo signs every request with the [Standard Webhooks](https://www.standardwebhooks.com)
+scheme (the spec Svix authored). Verify with any compatible library — `svix` or
+`standardwebhooks` — using the secret from registration. Ablo ships no
+verification code of its own; you use the open library.
+
+```ts
+const wh = new Webhook(process.env.ABLO_WEBHOOK_SECRET!);
+const event = wh.verify(rawBody, Object.fromEntries(req.headers));
+```
+
+Verification checks three headers — `webhook-id`, `webhook-timestamp`,
+`webhook-signature` — and rejects a timestamp outside a 5-minute window (replay
+protection). Always verify against the **raw** request body.
+
+## Event delivery
+
+Ablo delivers from a per-endpoint **cursor** over the log, advancing only on a
+`2xx`. A failed delivery leaves the cursor in place, so the same events are
+re-sent until they land — at-least-once, in order.
+
+```mermaid
+sequenceDiagram
+    participant L as Ablo log
+    participant W as Delivery worker
+    participant E as Your endpoint
+    W->>L: read events after cursor
+    L-->>W: events (ordered by syncId)
+    W->>E: POST signed batch
+    alt 2xx
+        E-->>W: 200
+        W->>L: advance cursor
+    else non-2xx / timeout
+        E-->>W: error
+        Note over W,E: retry with backoff<br/>5s → 5m → … → 10h (8 attempts)<br/>then auto-disable
+    end
+```
+
+| behavior | how it works |
+|---|---|
+| **Ordering** | Every event carries `syncId`, a monotonic log position. Apply in `syncId` order — Ablo guarantees the order because it owns the log. |
+| **Retries** | A non-`2xx` (or no response within the timeout) is retried with backoff: immediate, 5s, 5m, 30m, 2h, 5h, 10h, 10h — 8 attempts over ~32h. |
+| **Auto-disable** | After the retries exhaust, the endpoint is marked `disabled` and delivery stops until you `ablo webhooks enable <id>`. |
+| **Replay** | Nothing is lost on failure: the log *is* the durable buffer, and delivery resumes from the endpoint's cursor once it's healthy. |
+
+## Best practices
+
+- **Dedupe by `syncId`.** Skip any `syncId` you've already stored. Delivery is
+  at-least-once, so the same event can arrive twice after a retry.
+- **Apply in `syncId` order.** It's the log position; sort each batch by it.
+- **Return `2xx` fast.** Acknowledge first, then do slow work asynchronously.
+- **Subscribe to only what you need.** Set `enabledEvents` to the models you
+  mirror (`['*']` is the default = all).
+- **Roll secrets periodically.** `ablo webhooks roll <id>` mints a new secret;
+  Standard Webhooks supports a rotation window so in-flight events still verify.
+- **Verify the raw body.** Frameworks that re-serialize JSON will break the
+  signature — verify the bytes you received.
+
+## Event types
+
+The verb is derived from the change:
+
+| type | when |
+|---|---|
+| `<model>.created` | a row was inserted |
+| `<model>.updated` | a row was updated |
+| `<model>.deleted` | a row was deleted (`data` is `null`) |
+| `<model>.archived` | a row was soft-archived |
+| `<model>.unarchived` | a soft-archived row was restored |
+
+Internal coordination changes (permissions, sync groups) carry no webhook — only
+your data models produce events.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -140,7 +140,9 @@
     "build:cli": "tsup --config tsup.cli.config.ts",
     "typecheck:cli": "tsc -p tsconfig.cli.json",
     "pack:check": "npm_config_cache=${TMPDIR:-/tmp}/ablo-npm-cache npm pack --dry-run",
-    "lint": "npm run lint:imports && npm run lint:errors && npm run lint:docs",
+    "lint": "npm run lint:imports && npm run lint:errors && npm run lint:docs && npm run lint:mintlify",
+    "build:docs": "node scripts/build-mintlify-docs.mjs",
+    "lint:mintlify": "node scripts/build-mintlify-docs.mjs --check",
     "lint:imports": "node scripts/check-js-extensions.mjs",
     "generate:errors": "tsx scripts/generate-error-docs.mts",
     "lint:errors": "tsx scripts/check-error-docs.mts",