@abloatai/ablo 0.16.2 → 0.17.0

package/docs/quickstart.md

@@ -1,16 +1,16 @@
 # Quickstart
 
 Build with Ablo on **the Postgres you already have**. You declare a small Ablo
-schema for the models humans and agents edit together, hand the client your
-Postgres `DATABASE_URL` (passed explicitly), and coordinate every write through
-`ablo.<model>`. In production, your database is the system of record. Ablo is the
-transaction layer on top: it registers your connection, commits every write there
-behind row-level security, and fans the confirmed rows out to every connected
-client.
+schema for the models humans and agents edit together, connect Ablo to your
+database with **logical replication** (`ablo connect`), and coordinate every read
+and claim through `ablo.<model>`. Your database stays the system of record: your
+app keeps writing through its own backend, Ablo tails your write-ahead log (WAL),
+and the confirmed rows fan out to every connected client. Ablo **never runs DDL,
+owns, or migrates your schema**.
 
 > No database yet? The hosted **sandbox** can host rows in Ablo's test plane —
-> pass an `apiKey` only and omit `databaseUrl`, like Stripe test mode — so you can
-> try Ablo before pointing it at your Postgres.
+> pass an `apiKey` only and skip the database setup, like Stripe test mode — so
+> you can try Ablo before connecting your Postgres.
 
 ## 1. Install and initialize
 
@@ -95,15 +95,34 @@ same idiom as tRPC's `typeof appRouter` and Drizzle's `typeof db`; it resolves
 the typed overload at the call site. Avoid `ReturnType<typeof Ablo>`, which
 collapses to the untyped client.
 
-## 3. Point Ablo at your database
+## 3. Connect your database with `ablo connect`
 
-The client takes your schema, your key, and your `DATABASE_URL`. On first
-connect Ablo registers the connection (sent once over TLS, stored sealed, never
-echoed back) and from then on commits every write directly to your Postgres.
+Connecting a real database = Postgres logical replication, and `ablo connect` is
+the one way to set it up. Ablo **reads** your WAL and never runs DDL, owns, or
+migrates your schema — your app keeps writing through its own backend.
+
+```bash
+# 1. Enable logical decoding (then RESTART Postgres — wal_level is not reloadable)
+#    ALTER SYSTEM SET wal_level = 'logical';
+#    On RDS/Aurora: set rds.logical_replication = 1 in the parameter group, reboot.
+
+# 2. Print the exact publication + replication-role SQL for YOUR Postgres, run it:
+npx ablo connect
+
+# 3. Put the replication role's connection string in DATABASE_URL, then validate:
+npx ablo connect --check
+```
+
+`ablo connect` prints the copy-pasteable SQL (a publication named
+`ablo_publication` and a least-privilege `ablo_replicator` role with
+`REPLICATION` + `SELECT`, password you choose). `ablo connect --check` connects to
+`DATABASE_URL` and verifies `wal_level=logical`, the publication, the role's
+`REPLICATION` attribute, and that every published table has a usable
+`REPLICA IDENTITY` — a green checklist or the precise fix per item.
 
 ```bash
 # .env — server runtime only, never the browser
-DATABASE_URL=postgres://ablo_app:...@host:5432/db
+DATABASE_URL=postgres://ablo_replicator:<password>@host:5432/db?sslmode=require
 ABLO_API_KEY=sk_test_...
 ```
 
@@ -115,50 +134,18 @@ import { schema } from './schema';
 export const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
-  databaseUrl: process.env.DATABASE_URL, // your Postgres, passed explicitly — rows live here
 });
 ```
 
-`databaseUrl` is not auto-read from the environment — you pass it explicitly
-(as above). If a `DATABASE_URL` is set for another tool, `Ablo()` ignores it
-unless you wire it in like this.
-
-Use a dedicated **non-superuser role** for the connection — Ablo enforces
-tenant isolation with row-level security, so the server rejects superuser or
-`BYPASSRLS` roles outright (`database_role_cannot_enforce_rls`).
-
-> **Neon / Supabase note:** the connection string those dashboards hand you
-> uses the database OWNER role (e.g. `neondb_owner`), which is `BYPASSRLS` —
-> Ablo will reject it. You don't have to fix that by hand: `npx ablo dev`
-> (next step) detects the unsafe role and offers to create the scoped one for
-> you — from your machine, so the owner credential never reaches Ablo. It
-> writes the new `DATABASE_URL` into your env file (the generated password is
-> never printed).
->
-> Prefer to do it manually? The equivalent SQL:
->
-> ```sql
-> CREATE ROLE ablo_app LOGIN PASSWORD '<strong password>'
->   NOSUPERUSER NOBYPASSRLS NOCREATEDB NOCREATEROLE;
-> GRANT CREATE, CONNECT ON DATABASE <your_db> TO ablo_app;
-> GRANT CREATE, USAGE ON SCHEMA public TO ablo_app;
-> ```
->
-> Then swap the user/password in the dashboard's string:
-> `postgres://ablo_app:<password>@<same-host>/<same-db>?sslmode=require`.
-
-Don't want a connection string to leave your infrastructure? Keep
-`DATABASE_URL` in your app only and expose one signed **Data Source endpoint**
-built from an ORM adapter instead — same product, same writes, see
-[Connect Your Database](./data-sources.md). In that setup, omit `databaseUrl`
-from `Ablo(...)`.
+The full setup, the honest footprint (publication + slot + `REPLICATION` role +
+the `wal_level` restart + slot/WAL retention Ablo monitors), and the Preview
+status of the WAL runtime are in [Connect Your Database](./data-sources.md).
 
 ## 4. Push the schema, then map it to tables
 
 ```bash
-npx ablo push      # checks your DATABASE_URL role, pushes the schema (sandbox),
-                   # and writes ABLO_API_KEY to .env.local. Add --watch to
-                   # re-push on every save.
+npx ablo push      # pushes the schema definition and writes ABLO_API_KEY to
+                   # .env.local. Add --watch to re-push on every save.
 ```
 
 `ablo push` uploads the schema *definition* — model names, fields, types. That
@@ -166,21 +153,22 @@ metadata is what tells Ablo which models to coordinate. Skipping it makes every
 write to a new or changed model fail with `server_execute_unknown_model` — that
 error literally means "run `npx ablo push`."
 
-Now Ablo needs real Postgres tables behind those models. Two ways, depending on
-who owns the tables:
+Now map those models to your real Postgres tables. **Your migration tool owns the
+tables** — Ablo reads them, it does not create or migrate them:
+
+- Run `npx ablo pull` to import the shape of your existing tables (created by
+  Prisma, Drizzle, or hand-written migrations) into your schema, or
+  `npx ablo check` to verify your schema and the live tables agree. Keep managing
+  the tables with your own migration tool; Ablo syncs the subset of models you
+  declared and reports the rest as "ignored / owned by you."
 
-- **Adopt existing tables (the common case).** Most teams already have the
-  tables — created by Prisma, Drizzle, or hand-written migrations. Run
-  `npx ablo pull` to import their shape into your schema, or `npx ablo check`
-  to verify your schema and the live tables agree. Keep managing the tables
-  with your own migration tool; Ablo just syncs the subset of models you
-  declared.
-- **Let Ablo provision them.** If Ablo should own the tables, `npx ablo migrate`
-  creates your synced-model tables (with row-level security) in the registered
-  database. Your other tables are left untouched.
+> **Optional escape hatch:** if you have no tables yet and want Ablo to scaffold
+> them, `npx ablo migrate` can create your synced-model tables for you. This is
+> not the happy path — connecting a real database is `ablo connect` (step 3), and
+> your own migrations stay in charge of your schema.
 
 Nothing runs locally — there is no dev server to start. Your app talks to Ablo's
-hosted API with the sandbox key; the rows land in your database.
+hosted API; the rows live in your database.
 
 ## 5. Write through the model
 
@@ -279,5 +267,5 @@ Keep using the schema client for app and agent writes.
 - [Schema Contract](./schema-contract.md) explains what the schema drives across SDK, React, agents, Data Source, and schema push.
 - [Guarantees](./guarantees.md) explains what confirmed writes and stale checks mean.
 - [Client Behavior](./client-behavior.md) covers errors, retries, and public imports.
-- [Connect Your Database](./data-sources.md) covers both connection shapes — `databaseUrl` and the signed Data Source endpoint.
+- [Connect Your Database](./data-sources.md) covers the logical-replication connect path end to end — `ablo connect`, the honest footprint, and the WAL runtime's Preview status.
 - [AI SDK Tool](./examples/ai-sdk-tool.md) shows the same write path inside a tool call.

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.2",
+  "version": "0.17.0",
   "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",