@abloatai/ablo 0.11.2 → 0.13.0

package/docs/integration-guide.md

@@ -142,20 +142,23 @@ model(
   },
   /* relations */ {},
   {
-    // Rows carry organization_id and bootstrap filters on it.
-    orgScoped: true,
+    // Axis 1 — `policy`: who may READ a row (tenant isolation / RLS). A
+    // row-local `organization_id` column is the default, so you omit this for
+    // normal tables; set it only for the exceptions (parent-inherited / global).
 
+    // Axis 2 — `groups`: which sync-group CHANNELS a row fans into.
     // Scope root: rows form the group `matter:<id>`. Children point at it with
     // `relation.belongsTo('matters', 'matterId', { parent: true })` to inherit.
-    scope: 'matter',
+    groups: { root: 'matter' },
   }
 );
 ```
 
-For rows that don't carry `organization_id` themselves but inherit
-tenancy via a foreign key, use `scopedVia` instead of `orgScoped:
-false` — the latter exposes the entire table cross-tenant. See
-`packages/sync-engine/src/schema/model.ts` for the full option set.
+For rows that don't carry `organization_id` themselves but inherit tenancy via a
+foreign key, set `policy: { by: 'parent', fk: '<fk>', parent: '<parentTable>' }`.
+For genuinely global/reference data, `policy: { by: 'none' }`. ⚠ `by: 'none'`
+exposes the whole table cross-tenant, so it's an explicit, named branch — never a
+falsy flag. See `packages/sync-engine/src/schema/model.ts` for the full option set.
 
 ## 2. Create The Client
 
@@ -444,7 +447,7 @@ scope.
 ```ts
 await using claim = await ablo.weatherReports.claim({
   id: reportId,
-  action: 'forecasting',
+  reason: 'forecasting',
 });
 const claimed = claim.data;
 if (!claimed) return;
@@ -510,7 +513,7 @@ them.
 | `update({ id, data, ...opts })`        | Update through the model client.                                                 |
 | `delete({ id, ...opts })`              | Delete through the model client.                                                 |
 | `claim.state({ id })`                  | See who is currently working on a row (synchronous).                             |
-| `claim({ id, action?, ttl? })`         | Acquire a disposable handle: wait for your turn, re-read, and hold the row.       |
+| `claim({ id, reason?, ttl? })`         | Acquire a disposable handle: wait for your turn, re-read, and hold the row.       |
 
 Keep first integrations on the model methods above. Every mutation and
 server-read verb takes one options object; only the synchronous `get(id)` stays

package/docs/interaction-model.md

@@ -70,7 +70,7 @@ automatically when the scope exits:
 ```ts
 await using claim = await ablo.weatherReports.claim({
   id: 'report_stockholm',
-  action: 'editing',
+  reason: 'editing',
 });
 await ablo.weatherReports.update({ id: claim.data.id, data: { status: 'ready' } }); // rejected if the row changed under the claim
 ```

package/docs/mcp.md

@@ -67,11 +67,23 @@ Point your assistant at the hosted endpoint — no auth, no token:
 claude mcp add --transport http ablo https://<your-app>/api/mcp
 ```
 
-Per-client walkthroughs:
+The endpoint is identical for every client — only the config surface differs:
 
-- [Claude Code](/docs/mcp/claude-code)
-- [Cursor](/docs/mcp/cursor)
-- [Windsurf](/docs/mcp/windsurf)
+- **Claude Code** — run the `claude mcp add` command above; verify with `/mcp list`, remove with `claude mcp remove ablo`.
+- **Cursor** — add the server to `~/.cursor/mcp.json` (macOS / Linux), then restart.
+- **Windsurf** — add the same JSON via Settings → Cascade → MCP, then restart.
+
+Cursor and Windsurf use the same config shape:
+
+```json
+{
+  "mcpServers": {
+    "ablo": { "transport": "http", "url": "https://<your-app>/api/mcp" }
+  }
+}
+```
+
+Each client then lists the Ablo tools (`search_ablo_docs`, `get_recipe`, `get_api_surface`, `validate_schema`, `scaffold_app`) in its MCP panel.
 
 ### What it exposes
 
@@ -96,7 +108,7 @@ loading everything into context.
 Reusable, parameterised templates that drive an end-to-end flow:
 
 - `integrate-sync-engine` — wire the SDK into an existing project.
-- `add-agent` — add an agent worker that coordinates via intents and
+- `add-agent` — add an agent worker that coordinates via claims and
   conflict-safe writes.
 - `define-schema` — design a Zod-first schema from a description, then run
   `validate_schema` before committing.

package/docs/migration.md

@@ -284,7 +284,8 @@ One provider component now owns the full React lifecycle. `<SyncProvider>`,
 - <SyncProvider store={sync._store} organizationId={orgId}>
 -   <AbloProvider ablo={ablo}>{children}</AbloProvider>
 - </SyncProvider>
-+ <AbloProvider schema={schema} url={url} userId={userId} organizationId={orgId}>
++ const ablo = Ablo({ schema, apiKey });
++ <AbloProvider client={ablo}>
 +   {children}
 + </AbloProvider>
 ```

package/docs/quickstart.md

@@ -222,7 +222,7 @@ Call `handle.release()` when your work is done.
 // Claim the row so other participants serialize behind us while we work.
 const handle = await ablo.weatherReports.claim({
   id: 'weather_stockholm',
-  action: 'checking_weather',
+  reason: 'checking_weather',
   ttl: '2m',
 });
 
@@ -260,7 +260,7 @@ write through the model.
 ```ts
 const active = ablo.weatherReports.claim.state({ id: 'weather_stockholm' });
 if (active) {
-  console.log(`${active.heldBy} is ${active.action}`);
+  console.log(`${active.heldBy} is ${active.reason}`);
 }
 
 const handle = await ablo.weatherReports.claim({ id: 'weather_stockholm' });
@@ -268,7 +268,7 @@ await ablo.weatherReports.update({ id: handle.data.id, data: { status: 'ready' }
 await handle.release();
 ```
 
-Use `{ wait: false }` on `claim` when work should be skipped instead of queued
+Use `{ queue: false }` on `claim` when work should be skipped instead of queued
 behind an active holder.
 
 ## Next steps

package/llms.txt

@@ -12,7 +12,7 @@ First action when integrating into an app: run `npx ablo init --yes --framework
 
 Second: make sure a key exists — WITHOUT printing it. The key is a secret; it must never appear in your output, your reasoning, or a file you echo (it would live in the conversation history forever). Check PRESENCE only: `[ -n "$ABLO_API_KEY" ] && echo set` and `grep -cq '^ABLO_API_KEY=' .env.local && echo wired` — never `cat .env.local`, never `echo $ABLO_API_KEY`. If neither check passes, ask the HUMAN to run `npx ablo login` once — it opens a browser and saves a `sk_test_` key locally; an agent must NOT run it. You never copy the key by hand: the next step writes it into `.env.local` (and gitignores it) for you.
 
-Then PUSH — this is the step everything depends on. The server keeps its OWN copy of the schema. Run `npx ablo push --no-watch`: it pushes `ablo/schema.ts` (sandbox) AND writes `ABLO_API_KEY` into `.env.local` from the stored login. Until the schema is pushed, EVERY write to a new or changed model fails with `server_execute_unknown_model`. Re-run it after schema changes (`npx ablo push` also works once the key is wired; bare `npx ablo push` watches forever — don't, you have no TTY).
+Then PUSH — this is the step everything depends on. The server keeps its OWN copy of the schema. Run `npx ablo push`: it pushes `ablo/schema.ts` (sandbox) AND writes `ABLO_API_KEY` into `.env.local` from the stored login. Until the schema is pushed, EVERY write to a new or changed model fails with `server_execute_unknown_model`. Re-run it after schema changes. `push` is one-shot; `dev` is the watcher, so use `npx ablo dev --no-watch` only when you intentionally want the dev command to push once and exit.
 
 ## Projects (one org, many apps)
 
@@ -29,7 +29,6 @@ TYPES: the project registers its schema ONCE via declaration merging — `npx ab
 
 const schema = defineSchema({
   weatherReports: model({
-    id: z.string(),
     location: z.string(),
     status: z.enum(['pending', 'ready']),
     forecast: z.string().optional(),
@@ -190,6 +189,6 @@ Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subp
 - `npx ablo init --yes` (flags: `--framework`, `--auth`, `--storage direct|endpoint` (default `direct`), `--no-agent`, `--no-pull`, `--no-install`, `--no-login`). Generates `ablo/schema.ts` + the client; `--storage direct` (default) wires `databaseUrl`, `--storage endpoint` scaffolds the `ablo/data-source.ts` endpoint above instead.
 - 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 --no-watch` pushes the schema (sandbox) AND writes `ABLO_API_KEY` to `.env.local` (default watches forever); `npx ablo logs --no-follow` (default tails forever); `npx ablo mode sandbox|production` (always pass the arg). `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`; `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.
 
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.11.2",
+  "version": "0.13.0",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -119,7 +119,6 @@
     "examples",
     "AGENTS.md",
     "llms.txt",
-    "llms-full.txt",
     "LICENSE",
     "NOTICE",
     "README.md",
@@ -131,9 +130,11 @@
     "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:imports": "node scripts/check-js-extensions.mjs",
     "generate:errors": "tsx scripts/generate-error-docs.mts",
     "lint:errors": "tsx scripts/check-error-docs.mts",
+    "lint:docs": "node scripts/check-doc-drift.mjs",
     "lint:pkg": "publint",
     "prepublishOnly": "npm run build && npm run lint:pkg",
     "check:dist": "node scripts/check-dist-fresh.mjs",

package/docs/mcp/claude-code.md

@@ -1,35 +0,0 @@
-# Claude Code
-
-## Install
-
-```bash
-claude mcp add --transport http ablo https://<your-app>/api/mcp
-```
-
-That's it — no token or header needed. The endpoint is public and serves
-only docs, schema lint, and scaffolds. The next `/help` in Claude Code will
-list the Ablo Sync tools.
-
-## Verify
-
-In Claude Code, run:
-
-```
-/mcp list
-```
-
-You should see `ablo` with the integration tools enumerated:
-`search_ablo_docs`, `get_recipe`, `get_api_surface`, `validate_schema`,
-`scaffold_app`.
-
-## Removing
-
-```bash
-claude mcp remove ablo
-```
-
-## More
-
-- [MCP overview](/docs/mcp) — what the server exposes and how the transport works.
-- [Cursor setup](/docs/mcp/cursor) — same URL, different UI.
-- [Windsurf setup](/docs/mcp/windsurf) — same URL, different UI.

package/docs/mcp/cursor.md

@@ -1,35 +0,0 @@
-# Cursor
-
-## Install
-
-Add the Ablo Sync MCP server to Cursor's `mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "ablo": {
-      "transport": "http",
-      "url": "https://<your-app>/api/mcp"
-    }
-  }
-}
-```
-
-The file lives at `~/.cursor/mcp.json` on macOS / Linux. No auth header is
-needed — the endpoint is public and serves only docs, schema lint, and
-scaffolds.
-
-Restart Cursor. The Ablo Sync tools appear under the MCP icon in the agent
-panel.
-
-## Verify
-
-In Cursor's agent panel, open the MCP tools list. You should see the
-Ablo Sync integration tools and their JSON schemas: `search_ablo_docs`,
-`get_recipe`, `get_api_surface`, `validate_schema`, `scaffold_app`.
-
-## More
-
-- [MCP overview](/docs/mcp) — what the server exposes and how the transport works.
-- [Claude Code setup](/docs/mcp/claude-code) — CLI install.
-- [Windsurf setup](/docs/mcp/windsurf) — same JSON shape.

package/docs/mcp/windsurf.md

@@ -1,33 +0,0 @@
-# Windsurf
-
-## Install
-
-Add the Ablo Sync MCP server to Windsurf's MCP config:
-
-```json
-{
-  "mcpServers": {
-    "ablo": {
-      "transport": "http",
-      "url": "https://<your-app>/api/mcp"
-    }
-  }
-}
-```
-
-The config path differs by platform — Windsurf surfaces it in Settings →
-Cascade → MCP. Restart Windsurf after saving. No auth header is needed —
-the endpoint is public and serves only docs, schema lint, and scaffolds.
-
-## Verify
-
-Cascade's MCP panel lists every configured server with its tools. You
-should see `ablo` with the integration tools enumerated:
-`search_ablo_docs`, `get_recipe`, `get_api_surface`, `validate_schema`,
-`scaffold_app`.
-
-## More
-
-- [MCP overview](/docs/mcp) — what the server exposes and how the transport works.
-- [Claude Code setup](/docs/mcp/claude-code) — CLI install.
-- [Cursor setup](/docs/mcp/cursor) — same JSON shape.

package/docs/roadmap.md

@@ -1,55 +0,0 @@
-# Roadmap
-
-What is shipped, what is next, and what we will not build.
-
-## Shipped
-
-- **Models, claims, commits** — the core API.
-- **Audit log** — a tamper-evident, hash-chained record of who did what,
-  per principal.
-- **MCP transport** — HTTP server at `/api/mcp`.
-- **TypeScript SDK** — `@abloatai/ablo`, with React bindings.
-- **Dashboard** — keys, audit, metrics, allowed origins.
-- **Schema migrations** — change a model's shape after it already has data.
-  Ablo plans the migration, tells you which changes are safe to auto-apply,
-  and backfills the rest; the server applies and activates a migration only
-  if it succeeds. `ablo generate` emits typed clients from a pushed schema.
-- **Structured errors** — every error has a stable code and a request id,
-  and the same codes work whether you reach Ablo over HTTP, WebSocket, or MCP.
-- **Sync groups** — clients automatically receive only the records they have
-  access to, based on relationships you declare in the schema.
-- **Agent coordination** — when several agents work on the same model, they
-  take turns instead of overwriting each other, via `intent(id)` handles
-  that claim, wait, and commit.
-
-## In flight
-
-- **Real-time presence** — see who else is viewing/editing a model
-  (coordination primitives landed; presence surface in progress).
-- **Cross-instance fan-out via Redis** — pub/sub deltas at scale.
-
-## On deck
-
-- **Field-level subscriptions** — subscribe to one path, not the whole row.
-- **Bulk import/export** — CSV/JSON round-trip with chain verification.
-
-## Maybe, if demand
-
-- **Python SDK** — when a customer is shipping a Python-only product.
-- **Go SDK** — same.
-- **Multi-region replication** — when latency requirements force it.
-
-## We will not build
-
-- **A general-purpose Postgres wrapper** — Ablo is for state with
-  concurrency semantics, not for storing every table.
-- **Server-side compute** — no triggers, no stored procedures. Compute
-  belongs in your application code.
-- **A document database UI** — your data lives in Ablo; the UI is your
-  product, not ours.
-
-## How priorities shift
-
-We move items between sections based on what customers ask for in
-production. Filing a [feature request](/docs/contact) with a concrete use
-case is more effective than a thread on Twitter.

package/docs/the-loop.md

@@ -1,21 +0,0 @@
-# The loop: how your data flows
-
-This explainer moved to the canonical, maintained docs:
-
-**→ https://abloatai.com/docs/webhooks**
-
-The short version: Ablo has the same two-sided shape as Stripe — **you call Ablo to make changes (the client), and Ablo calls you to persist them (a signed webhook)** — plus realtime sync to every connected client.
-
-```
-your app ──write──▶  Ablo (hosted)  ──realtime sync──▶  other clients
- (the client)        the transaction log               (live, optimistic)
-                            │
-                            └──signed event──▶  /api/ablo/[...all]  ──▶  YOUR database
-                                                (the webhook route)
-```
-
-Ablo owns the ordered transaction log (the source of truth); your database is a
-materialized copy you keep via the webhook. See the link above for the full
-guide: scaffolding the handler (`ablo init`), local testing (`ablo dev`),
-registering an endpoint (`ablo webhooks create`), signature verification, the
-delivery/retry model, and best practices.