@abloatai/ablo 0.34.1 → 0.36.0

package/docs/webhooks.md

@@ -1,7 +1,9 @@
 # Webhooks
 
+> Stream the committed transaction log to your own systems as signed events.
+
 Ablo keeps an ordered transaction log of every committed change and coordinates
-the writers — people and agents — that produce it. Your rows live in your own
+the writers — agents, and the people alongside them — that produce it. Your rows live in your own
 database; Ablo holds only the log. **Webhooks stream that log to your systems as
 signed events:** every committed change is POSTed to an endpoint in your app, and
 your handler decides what to do with it.
@@ -23,7 +25,7 @@ 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 |
+| **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.
@@ -32,8 +34,8 @@ 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.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 |
 
@@ -48,11 +50,11 @@ Every delivery is a batch of events. Each event:
 | field | meaning |
 |---|---|
 | `type` | `"<model>.<verb>"` with the model name lowercased, e.g. `task.updated` |
-| `model` | the model name exactly as declared in your schema — the table to write |
+| `model` | the model name exactly as declared in your schema: 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 |
+| `syncId` | monotonic log position: **dedupe and order by this** |
+| `id` | `String(syncId)`: the event id |
 | `createdAt` | ISO commit timestamp |
 
 ```ts
@@ -198,8 +200,8 @@ sequenceDiagram
 
 | 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. |
+| **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. |
 
@@ -211,7 +213,7 @@ sequenceDiagram
 - **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;
+- **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.

package/llms.txt

@@ -1,11 +1,24 @@
 # Ablo
 
-Ablo is the state coordination layer for apps where humans and agents edit the same data.
+Ablo is collaboration infrastructure for AI agents: one API for agents, apps, and services to claim, change, and confirm the same rows.
 
-Here is the problem it solves. Two writers touch `report_stockholm` at once. The agent claims the row, does slow work (an LLM call, a fetch), and commits; the human's UI sees the claim live and never clobbers it. Claims don't lock. If another writer holds the row, `claim` waits for them, re-reads the fresh row, then hands it to you — so two writers serialize instead of clobbering.
+Here is the problem it solves. Two agents reach for `report_stockholm` at once. One claims the row, does slow work (an LLM call, a fetch, a chain of tools), and commits. The second is neither rejected nor allowed to clobber: it waits in line, is handed the row as it now stands, and proceeds. Claims don't lock. If another writer holds the row, `claim` waits for them, re-reads the fresh row, then hands it to you — so writers serialize instead of colliding. A person editing that row is simply another holder; the agent waits behind them the same way. And a claim is as narrow as its target: name a `path`, a `range`, or a `field` and two claims on non-overlapping parts of the same row are both granted — region locking within one row, with no queueing between regions.
 
 Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist, coordinate with concurrent work, and leave an audit trail.
 
+## Surfaces: pick by who is calling
+
+Every surface reaches the same coordinated state. They are not interchangeable.
+
+- SDK, `@abloatai/ablo` with `transport: 'http'` — THE AGENTS THEMSELVES. Stateless, request/response, nothing held open; the credential is the identity. This is the main path — default to it.
+- Coordination MCP, `@abloatai/mcp` — an agent living inside an MCP host (Claude, Cursor). Two jobs: MANAGING your Ablo the way the CLI does (`get_schema`, `list_projects`, `create_project`, `tail_logs`, `get_usage`), and claim/commit as tools over your rows. Call `get_schema` first — it is the only way to learn the model names every data tool needs. `init`, `push`, `pull`, `generate` have no tools (they touch your repo); run those in a shell.
+- `humans()` with `@abloatai/ablo/react` — the interfaces a person watches agent work arrive in. The bare client is the coordination layer (commit, read, observe, claim); `humans()` is the PLUGIN that adds the local watchable copy, live queries, and presence. It `requires: { duplex: true }`, so a `transport: 'http'` agent is rejected at construction rather than left holding a subscription that never delivers. It is installed by default on a socket client with no `plugins` list. There is no `agents()` plugin — agents are the default caller, not a special one. A browser NEVER receives the secret key; mint a session token.
+- CLI, `ablo` — scaffolding, schema push, connecting a database. Terminals and CI. Agents must run it non-interactively (see the CLI section below).
+- REST, `/api/v1` — runtimes with no SDK.
+- Integration-helper MCP, hosted `/api/mcp` — teaching a coding assistant the SDK WHILE BUILDING an integration. Docs, schema lint, and scaffolds only; it has NO per-model data tools and cannot touch application rows.
+
+The two MCP servers do different jobs and are the most common mix-up: to change application rows use the SDK or the COORDINATION server; the integration-helper server cannot do it at all. Do not hand-roll HTTP against `/api/v1` when a typed SDK exists for the runtime you are in.
+
 ## Start here
 
 First action when integrating into an app: run `npx ablo init --yes --framework <nextjs|vite|remix|vanilla>`. Agents have no TTY — `--yes` is REQUIRED or it HANGS. It scaffolds `ablo/schema.ts`, the `Ablo({ schema, apiKey })` client, and (for Next.js) the browser provider + session route. All on the current API. Edit the generated files rather than hand-writing from this doc. Connecting a database is a SEPARATE step with one path — logical replication via `npx ablo connect` (see Storage Boundary); the signed Data Source endpoint is the fallback when database credentials must stay inside the app.
@@ -24,7 +37,7 @@ Each app gets its own PROJECT inside the org — its own schema, its own sandbox
 import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
-TYPES: the project registers its schema ONCE via declaration merging — `npx ablo init` scaffolds `ablo/register.ts` (a regular `.ts` module beside schema.ts, NOT a hand-authored `.d.ts`): `import type { schema } from './schema'; declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`. The top-level `import type` makes `declare module` MERGE (augment) the SDK's Register interface rather than collide — same shape TanStack Router uses in src/router.tsx; any `.ts` file in tsconfig include works, never imported. Then model types are one parameter: `type Task = Model<'tasks'>` (import type { Model } from '@abloatai/ablo/schema'). Do NOT teach `InferModel` (deprecated) or the two-param `Model<typeof schema,'tasks'>` unless multiple schemas exist. Never hand-write model interfaces — derive from the schema. To NAME the client type (function param, context value), infer from the value: `type Sync = typeof sync` — same idiom as tRPC `typeof appRouter` / Drizzle `typeof db`; it resolves the typed overload at the call site. Do NOT use `ReturnType<typeof Ablo>` (collapses to the untyped last overload) and do NOT import a bespoke client-type generic — there is none.
+TYPES: the project registers its schema ONCE via declaration merging — `npx ablo init` scaffolds `ablo/register.ts` (a regular `.ts` module beside schema.ts, NOT a hand-authored `.d.ts`): `import type { schema } from './schema'; declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`. The top-level `import type` makes `declare module` MERGE (augment) the SDK's Register interface rather than collide — same shape TanStack Router uses in src/router.tsx; any `.ts` file in tsconfig include works, never imported. Then model types are one parameter: `type Task = Model<'tasks'>` (import type { Model } from '@abloatai/ablo/schema'); the two-parameter `Model<typeof schema,'tasks'>` form is only for projects carrying multiple schemas. Never hand-write model interfaces — derive from the schema. To NAME the client type (function param, context value), infer from the value: `type Sync = typeof sync` — same idiom as tRPC `typeof appRouter` / Drizzle `typeof db`; it resolves the typed overload at the call site. Do NOT use `ReturnType<typeof Ablo>` (collapses to the untyped last overload) and do NOT import a bespoke client-type generic — there is none.
 
 
 const schema = defineSchema({
@@ -62,10 +75,12 @@ the same model API across your own Data Source-backed app databases,
 React selectors, multiplayer, and future agent workers.
 
 Reads come in two flavors, and you pick by whether you can wait. `retrieve({ id })`
-(one row) and `list({ where })` (many) are async — they hit the server and return
-a Promise, so await them. `get(id)`, `getAll({ where })`, and `getCount({ where })`
-are synchronous — they read the local graph and are reactive in render, so no
-await. The query reads accept `where`, `filter`, `orderBy`, `limit`, `offset`,
+(one row) and `list({ where })` (many) are async — they answer from the local
+graph and fall back to the server, so await them. `local.retrieve(id)`,
+`local.list({ where })`, and `local.count({ where })` are the same reads narrowed
+to what has already synced: nothing to await, reactive in render. There is no
+second verb to learn — `local.` is the only difference. The query reads accept
+`where`, `filter`, `orderBy`, `limit`, `offset`,
 and `state`; state defaults to `'live'`, with `'archived'` and `'all'` to include
 retired rows.
 
@@ -73,10 +88,10 @@ Workers import the same app schema and select `transport: 'http'`. The transport
 changes; the typed `ablo.<model>` contract does not. There is no public
 schema-less or string-keyed model client.
 
-React reads should use selector `useAblo`: `useAblo((ablo) => ablo.weatherReports.get(id))` (synchronous local read, reactive in render).
+React reads should use selector `useAblo`: `useAblo((ablo) => ablo.weatherReports.local.retrieve(id))` (synchronous local read, reactive in render).
 Use zero-argument `useAblo()` only when a component needs the client for an
-event handler or effect. The older string-keyed hooks (`useQuery`, `useOne`,
-`useReader`, and `useMutate`) are removed; do not import or recommend them.
+event handler or effect. The selector form above is the complete reactive
+surface — every read goes through it.
 
 ## Multiplayer
 
@@ -90,7 +105,7 @@ coordination until the app reports it through Data Source events.
 
 ## Change propagation
 
-A change to one row reaches other rows three ways. ROUTING: a write fans out to every sync group the row belongs to, INCLUDING its ancestors' groups (editing a layer routes to `layer:` + `slide:` + `deck:`), so everyone watching the deck sees it — delivery, not recomputation. DELETE CASCADE: deleting a parent emits explicit tombstone deltas for its descendants, so open clients never silently hold rows that are gone. VALUE: derived values are NOT recomputed server-side — Ablo surfaces that the source moved and the actor decides. To keep dependent work fresh, declare what you read as a batch premise: `reads: [{ group: 'deck:abc', readAt: N, onStale: 'notify' }]`. At commit the server checks whether anything in that group moved past `readAt`; `notify` holds the write and returns a `StaleNotification` (re-read the group and regenerate), `reject` aborts. To chain A→B→C, put A+B in one group and B+C in another: A's change reaches B, and C hears it only once B ITSELF writes — the engine wires the edges and signals each hop, the actor walks them. No transitive auto-recompute, no convergence guarantee for cycles. `reads` guards ONE commit; for a long-running actor that reads now and writes much later, register a DURABLE premise with `track`: `ablo.<model>.track({ id })` for a row, or the `track:` write option (`track: [{ group: 'deck:abc' }]`) alongside a write. A track persists server-side; the next time you commit anything, a change that landed on the tracked target rides back on your receipt's `notifications` (same `StaleNotification` shape as `onStale: 'notify'`). It is an idempotent registration, re-baselines so a change fires once, and never notifies you of your own writes. Delivery is on your next commit — a track does not yet push out of band between commits.
+A change to one row reaches other rows three ways. ROUTING: a write fans out to every sync group the row belongs to, INCLUDING its ancestors' groups (editing a block routes to `block:` + `document:` + `workspace:`), so everyone watching the workspace sees it — delivery, not recomputation. DELETE CASCADE: deleting a parent emits explicit tombstone deltas for its descendants, so open clients never silently hold rows that are gone. VALUE: derived values are NOT recomputed server-side — Ablo surfaces that the source moved and the actor decides. To keep dependent work fresh, declare what you read as a batch premise: `reads: [{ group: 'workspace:abc', readAt: N, onStale: 'notify' }]`. At commit the server checks whether anything in that group moved past `readAt`; `notify` holds the write and returns a `StaleNotification` (re-read the group and regenerate), `reject` aborts. To chain A→B→C, put A+B in one group and B+C in another: A's change reaches B, and C hears it only once B ITSELF writes — the engine wires the edges and signals each hop, the actor walks them. No transitive auto-recompute, no convergence guarantee for cycles. `reads` guards ONE commit; for a long-running actor that reads now and writes much later, register a DURABLE premise with `track`: `ablo.<model>.track({ id })` for a row, or the `track:` write option (`track: [{ group: 'workspace:abc' }]`) alongside a write. A track persists server-side; the next time you commit anything, a change that landed on the tracked target rides back on your receipt's `notifications` (same `StaleNotification` shape as `onStale: 'notify'`). It is an idempotent registration, re-baselines so a change fires once, and never notifies you of your own writes. Delivery is on your next commit — a track does not yet push out of band between commits.
 
 ## Nouns
 
@@ -107,6 +122,13 @@ even while it is claimed. Pass `ifClaimed: 'fail'` to throw
 `AbloClaimedError`, and inspect active coordination separately through
 `ablo.<model>.claim.state({ id })`.
 
+A claim carries app metadata verbatim in `target.meta`. Declare its shape in the
+SAME register block as the schema — `interface Register { Schema: typeof schema;
+ClaimMeta: { blocks: string[] } }` — and it types both what you write
+(`claim({ id, meta })`) and every read (`claim.state`, `claim.queue`, the held
+claim), so no read needs a `typeof` guard. The per-call `claim.state<M>({ id })`
+still works and is for a program carrying more than one metadata shape.
+
 Reads never block on a claim. To wait for a row to free up, `claim({ id })` it —
 the claim queues fairly behind the current holder and is granted when the row
 frees. Use `ifClaimed: 'fail'` when you'd rather refuse to read a claimed row.
@@ -133,7 +155,7 @@ RLS GOVERNS ABLO'S WRITES. The writer role is `NOSUPERUSER NOBYPASSRLS`, and bef
 
 FALLBACK (only when Ablo can't dial the database, e.g. a private VPC with no inbound route): a signed Data Source endpoint that hands Ablo an ORM `adapter` (Drizzle default; Prisma and Kysely supported) — Ablo writes and confirms through it, and it owns the transaction, exactly-once idempotency, and outbox in ONE pass; your credentials never leave your infrastructure.
 
-DEPRECATED — removed, do NOT recommend or scaffold: the `databaseUrl` constructor option (the old DIAL-IN, where the CLIENT held a read/write connection string and committed directly, bypassing Ablo's coordination). It is deleted. DO NOT confuse it with the current model: today's writes also land in your Postgres, but through Ablo's SERVER-SIDE commit chokepoint and a scoped writer role Ablo provisions — coordination is never bypassed, and no connection string lives in your app. The NON-superuser / NON-BYPASSRLS role rule is NOT retired — it now applies to the scoped writer role `ablo connect` provisions (see RLS above), because Ablo does hold a scoped connection to write your rows. The end-state constructor is `Ablo({ schema, apiKey })`; the database is connected out of band via `ablo connect`. `ablo init` may still scaffold legacy `--storage direct`/`databaseUrl` for old projects and the CLI warns on it; prefer `ablo connect`.
+The constructor is `Ablo({ schema, apiKey })` — the app holds an API key and nothing else; no connection string ever lives in the app. The database is connected out of band with `ablo connect`: writes land in your Postgres through Ablo's server-side commit path using the scoped writer role `ablo connect` creates, and that role is always NON-superuser / NON-BYPASSRLS (see RLS above).
 
 ```ts
 // app/api/ablo/source/route.ts
@@ -151,7 +173,7 @@ export const { POST } = dataSourceNext({
 });
 ```
 
-Connect a database with `npx ablo connect` (logical replication — the one path above). The signed Data Source endpoint (code above) is the fallback when app database credentials must stay private; scaffold it with `npx ablo init --storage endpoint` — Ablo only calls the endpoint. (`--storage direct` still exists for existing dial-in projects but is deprecated; the CLI warns on it.)
+Connect a database with `npx ablo connect` (logical replication — the one path above). The signed Data Source endpoint (code above) is the fallback when app database credentials must stay private; scaffold it with `npx ablo init --storage endpoint` — Ablo only calls the endpoint.
 
 ## Sandboxes
 
@@ -163,7 +185,7 @@ when an agent is asked to "make Ablo work" in an existing app.
 Authenticated org sandboxes are real test environments. Treat the default
 sandbox like Stripe test mode: it has an isolated sync group prefix and mints
 `sk_test_*` keys. The sandbox CAN host rows in Ablo's test plane, so you can try
-Ablo with NO database — `apiKey` only, no `databaseUrl`. (In production, your own
+Ablo with NO database — `apiKey` only, nothing else. (In production, your own
 Postgres is the system of record.) Extra sandboxes can start blank or copy live
 configuration. Resetting a sandbox creates a clean future stream without
 touching live data. Use `sk_live_*` only for production.
@@ -173,6 +195,12 @@ declare schema, create the Ablo client, replace one direct mutation with a typed
 `ablo.<model>.update(...)`, use selector `useAblo` for live reads, and add a
 two-writer stale/claim smoke test.
 
+## Production
+
+A PLANE is what a credential acts on: `production` is the root, sandboxes sit beside it. Rows, the registered database, and the active schema artifact are all PER PLANE, and a key's plane is fixed at mint by its prefix (`sk_live_` → production, `sk_test_` → sandbox) — there is no runtime override, which is why app code never passes an environment. ONE ASYMMETRY: a sandbox with no schema artifact of its own READS PRODUCTION'S, so a production push reaches sandboxes; a SANDBOX push does NOT reach production — it creates a sandbox artifact that shadows production for that sandbox's readers only. Production gets models when you push to production.
+
+Going live is three things, each done with a `sk_live_` key: register the production database (`ablo connect apply` — the DIRECT host, never a pooler; a pooler refuses in the words of a wrong password), push the schema AHEAD of the code that needs it, and hold the right credential per runtime (server/serverless `sk_live_`; browser `pk_live_` read-only or an `authEndpoint` minting `ek_`). The live key `ablo login` stores is a RESTRICTED observe-only `rk_live_` and CANNOT push schema — a production push needs a dashboard `sk_live_` in `ABLO_API_KEY`. Gate a deploy on `npx ablo status --json` having an EMPTY `blockers` array; each blocker carries a `problem` and the one `fix`. Your agents do NOT each hold a database connection — they talk to Ablo, and Ablo holds at most 4 connections per plane (`application_name = 'ablo-direct-writer'`) however many callers write behind them, so size the database for that number and not for your agent count. Read `deployment` for the full path.
+
 ## Public Surface
 
 Import from these public paths only:
@@ -189,14 +217,16 @@ Import from these public paths only:
 
 Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subpaths. (`/source` IS public — it's the Data Source endpoint surface above.)
 
-## CLI — agents run it NON-INTERACTIVELY
+## CLI: agents run it NON-INTERACTIVELY
 
 `ablo init` and other prompts need a TTY; an agent/CI run has none and will HANG. Always:
 
-- `npx ablo init --yes` (flags: `--framework`, `--auth`, `--storage direct|endpoint`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`). Generates `ablo/schema.ts` + the `Ablo({ schema, apiKey })` client. `--storage endpoint` also scaffolds the `ablo/data-source.ts` fallback endpoint; `--storage direct` (deprecated, CLI warns) wires the legacy `databaseUrl`.
+- `npx ablo init --yes` (flags: `--framework`, `--auth`, `--storage replication|endpoint`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`). Generates `ablo/schema.ts` + the `Ablo({ schema, apiKey })` client. `--storage replication` (the default) pairs with `ablo connect`; `--storage endpoint` also scaffolds the `ablo/data-source.ts` fallback endpoint.
 - `npx ablo connect` connects your database via logical replication — the read path (prints the `wal_level=logical` + publication + `REPLICATION`-role SQL); `npx ablo connect register` registers it, `npx ablo connect check` validates the registered database from Ablo's own side and needs only `ABLO_API_KEY` (no database credential in your environment). `npx ablo connect apply` does the whole setup from a one-time admin connection and leaves your app holding only `ABLO_API_KEY`.
 - Key: see "Start here" — env → `.env.local` → ask the human to `npx ablo login`; never run `login` yourself, never copy keys by hand (`ablo push` writes `.env.local`).
 - Adopt an existing DB: `npx ablo pull prisma [path]` / `npx ablo pull drizzle <module>`.
-- `npx ablo push` pushes the schema (sandbox) AND writes `ABLO_API_KEY` to `.env.local`; `npx ablo dev --no-watch` is the push-once form of the watcher; `npx ablo logs --no-follow` exits instead of tailing forever; `npx ablo mode sandbox|production` always needs the argument. `npx ablo push`/`status`/`pull`/`check`/`generate` are one-shot.
+- `npx ablo push` pushes the schema (sandbox) AND writes `ABLO_API_KEY` to `.env.local`. A PRODUCTION push (`sk_live_` key) needs `--yes`: with no TTY it REFUSES rather than deploying unattended, and interactively it demands the destination project typed by name. Destructive steps (dropped model/field, narrowed enum, lossy cast) need `--force`; a new required field on a populated table needs `--backfill model.field=value`. `npx ablo dev --no-watch` is the push-once form of the watcher; `npx ablo logs --no-follow` exits instead of tailing forever; `npx ablo mode sandbox|production` always needs the argument. `npx ablo push`/`status`/`pull`/`check`/`generate` are one-shot.
+
+- `npx ablo docs` lists every documentation page; `npx ablo docs <page>` prints one as markdown. These pages ship INSIDE the installed package, so they describe the version in `node_modules` and need no network. Prefer them over a docs URL whenever the project pins a version: a website always describes the newest release, so on an older pin it will hand you a call your package does not have (`retrieve`/`list` replaced `get`/`getAll`/`getCount` in 0.35.0). One-shot, safe to run unattended.
 
-Canonical docs to read before integrating: `quickstart`, `schema-contract`, `integration-guide`, `guarantees`, `client-behavior`, `data-sources`, `examples/existing-python-backend`, `api`, `examples/ai-sdk-tool`, and `examples/server-agent`. When upgrading an existing integration, read `migration` — every breaking change, what to change, and which version introduced it.
+Canonical docs to read before integrating: `quickstart`, `schema-contract`, `integration-guide`, `deployment`, `guarantees`, `client-behavior`, `data-sources`, `examples/existing-python-backend`, `api`, `examples/ai-sdk-tool`, and `examples/server-agent` — read each with `npx ablo docs <page>`. When upgrading an existing integration, read `migration` — every breaking change, what to change, and which version introduced it. When the customer's database has row-level-security policies, read `session-settings` — the identity context Ablo sets before every write, and how to map it to the setting names those policies already read.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.34.1",
+  "version": "0.36.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -10,7 +10,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "ablo": "./dist/cli.cjs"
+    "ablo": "./bin/ablo.cjs"
   },
   "exports": {
     ".": {
@@ -33,11 +33,6 @@
       "import": "./dist/react/index.js",
       "default": "./dist/react/index.js"
     },
-    "./testing": {
-      "types": "./dist/testing/index.d.ts",
-      "import": "./dist/testing/index.js",
-      "default": "./dist/testing/index.js"
-    },
     "./core": {
       "types": "./dist/core/index.d.ts",
       "import": "./dist/core/index.js",
@@ -48,11 +43,6 @@
       "import": "./dist/batching/index.js",
       "default": "./dist/batching/index.js"
     },
-    "./agent": {
-      "types": "./dist/agent/index.d.ts",
-      "import": "./dist/agent/index.js",
-      "default": "./dist/agent/index.js"
-    },
     "./ai-sdk": {
       "types": "./dist/ai-sdk/index.d.ts",
       "import": "./dist/ai-sdk/index.js",
@@ -103,6 +93,11 @@
       "import": "./dist/wire/index.js",
       "default": "./dist/wire/index.js"
     },
+    "./syncLog": {
+      "types": "./dist/syncLog/index.d.ts",
+      "import": "./dist/syncLog/index.js",
+      "default": "./dist/syncLog/index.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "import": "./dist/server/index.js",
@@ -112,14 +107,19 @@
       "types": "./dist/webhooks/index.d.ts",
       "import": "./dist/webhooks/index.js",
       "default": "./dist/webhooks/index.js"
+    },
+    "./docs": {
+      "types": "./dist/docs/index.d.ts",
+      "import": "./dist/docs/index.js",
+      "default": "./dist/docs/index.js"
     }
   },
   "files": [
+    "bin",
     "dist",
     "!dist/__type_probe.*",
     "docs/*.md",
     "docs/examples/*.md",
-    "docs/mcp/*.md",
     "examples",
     "AGENTS.md",
     "llms.txt",
@@ -130,18 +130,21 @@
   ],
   "scripts": {
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "npm run clean && tsc -p tsconfig.build.json && npm run build:cli",
-    "build:cli": "tsup --config tsup.cli.config.ts",
-    "typecheck:cli": "tsc -p tsconfig.cli.json",
+    "build": "npm run clean && tsc -p tsconfig.build.json",
+    "typecheck": "npm run typecheck:src && npm run typecheck:scripts",
+    "typecheck:src": "tsc -p tsconfig.json",
+    "typecheck:scripts": "tsc -p tsconfig.scripts.json",
     "prepack": "node scripts/strip-source-condition.mjs",
     "postpack": "node scripts/restore-source-condition.mjs",
     "pack:check": "node scripts/pack-check.mjs",
-    "lint": "npm run lint:imports && npm run lint:errors && npm run lint:docs && npm run lint:docs-site",
+    "lint": "npm run lint:imports && npm run lint:errors && npm run lint:openapi && npm run lint:docs && npm run lint:docs-site",
     "build:docs": "node scripts/build-blume-docs.mjs",
     "lint:docs-site": "node scripts/build-blume-docs.mjs --check",
     "lint:imports": "node scripts/check-js-extensions.mjs",
     "generate:errors": "tsx scripts/generate-error-docs.mts",
+    "generate:openapi": "tsx --conditions=@ablo/source scripts/generate-openapi.mts",
     "lint:errors": "tsx scripts/check-error-docs.mts",
+    "lint:openapi": "tsx --conditions=@ablo/source scripts/generate-openapi.mts --check",
     "lint:docs": "node scripts/check-doc-drift.mjs",
     "lint:eslint": "eslint . --cache",
     "lint:pkg": "publint",
@@ -149,7 +152,6 @@
     "check:dist": "node scripts/check-dist-fresh.mjs",
     "pretest": "node scripts/check-dist-fresh.mjs",
     "test": "jest",
-    "test:quickstart": "node scripts/test-quickstart.mjs",
     "test:unit": "jest --testPathPatterns __tests__/unit",
     "test:integration": "jest --testPathPatterns __tests__/integration",
     "test:contract": "jest --testPathPatterns __tests__/contract",
@@ -203,17 +205,14 @@
     }
   },
   "dependencies": {
-    "jiti": "^2.7.0",
     "mobx": "^6.13.7",
     "mobx-react-lite": "^4.0.0",
     "uuid": "^11.1.0",
-    "zod": "^4.1.11"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@ai-sdk/provider": "^3.0.0",
-    "@clack/prompts": "^0.11.0",
     "@jest/globals": "^30.2.0",
-    "@prisma/client": "^7.3.0",
     "@types/jest": "^30.0.0",
     "@types/node": "^22.0.0",
     "@types/react": "^19.0.0",
@@ -228,13 +227,9 @@
     "jest": "^30.2.0",
     "jest-environment-jsdom": "^30.2.0",
     "jest-environment-node": "^30.2.0",
-    "picocolors": "^1.1.0",
-    "postgres": "^3.4.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "ts-jest": "^29.4.5",
-    "ts-morph": "^26.0.0",
-    "tsup": "^8.0.0",
     "tsx": "^4.19.0",
     "typescript": "^5.8.3",
     "publint": "^0.3.21",