@abloatai/ablo 0.6.0 → 0.8.0

package/docs/mcp.md

@@ -1,44 +1,121 @@
 # Model Context Protocol
 
-Ablo ships an MCP server at `/api/mcp`. Connect any MCP-compatible AI
-assistant — Claude Code, Cursor, Windsurf — and your sync models become
-typed, callable tools.
+Ablo publishes **two** MCP servers for two different jobs. Don't confuse them:
 
-## Install
+| Server | Purpose | Auth | Tools |
+|---|---|---|---|
+| **Coordination** (`@ablo/mcp`) | Let an agent safely read & mutate your application data | API key (`sk_…` / `rk_…`) | per-model `get` / `list` / `create` / `update` / `delete` / `claim` / `release` |
+| **Integration-helper** (hosted `/api/mcp`) | Help an AI coding assistant write SDK integration code that compiles | none (public docs) | doc search, export surface, schema lint, scaffold |
 
-Pick your client:
+The coordination server **is the data plane** — it is how an agent changes
+state. The integration-helper server only serves docs, schema lint, and
+scaffolds; it does **not** read or write application data (there are no
+per-model data tools on it). Pick by what you're doing: shipping an agent that
+edits rows → coordination; teaching your IDE assistant the SDK → helper.
+
+## Coordination server (`@ablo/mcp`)
+
+The coordination server is the MCP projection of the model-scoped API
+(`/v1/models/...`) — the same surface as `ablo.<model>.create/update/claim` and
+the REST routes, rendered as tools. An agent connects with your API key and
+gets one safe loop: **claim → read → commit → release.**
+
+Install over stdio; set your key in the host's MCP env:
+
+```bash
+claude mcp add ablo -- npx -y @ablo/mcp
+# env:  ABLO_API_KEY=sk_…   (ABLO_API_URL optional; defaults to the hosted API)
+```
+
+Each tool mirrors an SDK verb, scoped to a model + id:
+
+| Tool | Mirrors | Does |
+|---|---|---|
+| `get_model` | `ablo.<model>.get(id)` | read latest state + active claims |
+| `list_models` | `ablo.<model>.list({…})` | cursor-paginated list with filters |
+| `create_model` | `ablo.<model>.create(data)` | guarded create |
+| `update_model` | `ablo.<model>.update(id, …)` | guarded update |
+| `delete_model` | `ablo.<model>.delete(id)` | guarded delete |
+| `claim_model` | `ablo.<model>.claim(id)` | acquire / queue a coordination lease |
+| `release_claim` | — | release the lease so others proceed |
+
+The agent-facing contract — the safe loop, the "derive idempotency keys from
+the business event" rule, and the error-code playbook — ships as a loadable
+skill at `@ablo/mcp/skill.md`. Lives in `packages/mcp/`
+(`createCoordinationMcpServer`, `src/tools.ts`).
+
+## Integration-helper server
+
+If you're integrating `@abloatai/ablo` with the help of an AI coding
+assistant (Claude Code, Cursor, Windsurf, Codex), you don't want it guessing
+at the API. This hosted server lets the assistant search the real docs,
+inspect the actual export surface, lint your schema, and scaffold a starter —
+so the code it writes uses APIs that exist. It serves docs only and returns
+nothing org-specific; data access happens through the SDK or the coordination
+server above, never here.
+
+> The `@abloatai/ablo` npm package itself bundles neither server — it has
+> no `@modelcontextprotocol/sdk` dependency. The helper is a feature of Ablo's
+> hosted app, mounted at `/api/mcp`; the coordination server is the separate
+> `@ablo/mcp` package.
+
+### Install
+
+Point your assistant at the hosted endpoint — no auth, no token:
+
+```bash
+claude mcp add --transport http ablo-sync https://<your-app>/api/mcp
+```
+
+Per-client walkthroughs:
 
 - [Claude Code](/docs/mcp/claude-code)
 - [Cursor](/docs/mcp/cursor)
 - [Windsurf](/docs/mcp/windsurf)
 
-## How it works
+### What it exposes
 
-Each model you declare becomes one or more MCP tools:
+#### Tools
 
-| Model method | MCP tool name | What it does |
-|---|---|---|
-| `retrieve` | `<model>.retrieve` | Returns the row + a stamp. |
-| `list` | `<model>.list` | Cursor-paginated discovery. |
-| `update` | `<model>.update` | Write, requires the prior stamp. |
-| `<model>.claim` | `claim.create` | Claim a row before writing, then release when held work finishes. |
+| Tool | What it does |
+|---|---|
+| `search_ablo_docs` | Keyword search across the docs corpus. Returns ranked matches with excerpts. Follow up with `get_recipe` on the top hit. |
+| `get_recipe` | Returns the full markdown of one doc by name (e.g. `readme`, `quickstart`, `schema-contract`, `integration-guide`, `api`, `guarantees`). |
+| `get_api_surface` | Returns the structured export list for an SDK subpath (`@abloatai/ablo`, `./react`, `./schema`, `./testing`, …). Call with no argument to list every subpath. |
+| `validate_schema` | Lints `defineSchema` source against the DSL rules (camelCase fields, lowercase model keys, `scope`/`grants` sync groups, valid `load` strategies, no legacy builders) and returns a structured issue list. Runs no code. |
+| `scaffold_app` | Emits a starter file tree for a schema-first integration — `next`, `node-agent`, or `plain`, with `managed` or `data-source` storage. |
+
+#### Resources
+
+Every doc file is addressable at `ablo-sync-engine://docs/{name}`, so a
+client can list the corpus and fetch individual files on demand instead of
+loading everything into context.
+
+#### Prompts
 
-The assistant gets typed JSON schemas, real argument types, and typed
-rejections when it writes stale state. No invention, no hallucinated IDs.
+Reusable, parameterised templates that drive an end-to-end flow:
 
-## Auth
+- `integrate-sync-engine` — wire the SDK into an existing project.
+- `add-agent` — add an agent worker that coordinates via intents and
+  conflict-safe writes.
+- `define-schema` — design a Zod-first schema from a description, then run
+  `validate_schema` before committing.
 
-The MCP transport uses a scoped bearer token issued by your server. Pass that
-token into the MCP client's auth header configuration. See your client's setup
-guide for the exact mechanism.
+### Transport and limits
 
-## Limits
+The endpoint uses the stateless Streamable HTTP transport (`POST /api/mcp`;
+`GET` returns 405 — SSE is not supported in stateless mode). A fresh
+server is built per request, which suits serverless and horizontally-scaled
+deployments.
 
-The MCP endpoint is rate-limited per token. Read-heavy bursts are fine;
-write-heavy bursts get throttled at the dashboard-configured cap.
+There is **no authentication**: the server only serves docs, schema lint,
+and scaffolds, so there's nothing org-scoped to protect. Abuse is bounded
+by IP-based rate limiting — 120 requests per minute per IP. Rate-limit
+headers are echoed on every response.
 
-## More
+### Where it lives
 
-The [MCP landing page](/mcp) has the product pitch. The route handler
-itself is at `apps/sync-web/src/app/api/mcp/route.ts` if you want to read
-the implementation.
+- Route handler: `apps/sync-web/src/app/api/mcp/route.ts`
+- Server setup: `apps/sync-web/src/lib/mcp-ablo/server.ts`
+  (`createSyncEngineMcpServer`)
+- Tools: `apps/sync-web/src/lib/mcp-ablo/tools/`

package/docs/quickstart.md

@@ -1,29 +1,26 @@
 # Quickstart
 
-Declare your state, create one row, and make one confirmed update.
+Start building with Ablo in two steps: install, then declare one model and write
+through its generated client.
 
 If you already have a backend and database, still start here. The SDK call shape
 is the same; [Integration Guide](./integration-guide.md) explains when to use
 Ablo-managed state versus a Data Source that calls your existing API service.
 
-## 1. Install
+## 1. Install and set a sandbox key
 
 ```bash
 npm install @abloatai/ablo
-```
-
-## 2. Set a Sandbox Key
-
-Use an Ablo sandbox key while integrating.
-
-```bash
 export ABLO_API_KEY=sk_test_...
 ```
 
 `ABLO_API_KEY` is for trusted server runtimes. Browser apps should use the React
 provider with a scoped session route, not a bundled API key.
 
-## 3. Declare a Schema
+## 2. Declare schema and write state
+
+Your schema is the contract. It generates `ablo.<model>` methods for app code,
+server actions, agents, React reads, and Data Source requests.
 
 ```ts
 import Ablo from '@abloatai/ablo';
@@ -41,15 +38,6 @@ export const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
 });
-```
-
-Customer apps should always pass `schema`. Treat it like Prisma's schema file:
-it is the source of truth for typed model clients, realtime subscriptions,
-agent writes, and Data Source requests.
-
-## 4. Create and Update
-
-```ts
 await ablo.ready();
 
 const created = await ablo.weatherReports.create({
@@ -71,23 +59,26 @@ Expected output:
 { id: '...', status: 'ready' }
 ```
 
-## 5. Run the Example
+## Run the example
 
 ```bash
-cd examples
-ABLO_API_KEY=sk_test_... npx tsx quickstart.ts
+cd packages/sync-engine
+ABLO_API_KEY=sk_test_... npx tsx examples/quickstart.ts
 ```
 
-## 6. AI Activity on Existing State
+## Add coordination for slow work
 
 When AI or background work will touch an existing row for more than a quick
-write, coordinate through the flat model verbs: `ablo.<model>.claim(id, ...)` to
-claim the row (returns the row), `ablo.<model>.claimState(id)` to read who's working
-on it (synchronous; never blocks), and the normal `ablo.<model>.update(id, ...)`
-to write. Normal reads still work while the claim is held; server reads can opt
-into `ifClaimed: 'wait'` or `ifClaimed: 'fail'` when they should not read through
-active work. The callback form releases the claim when the callback returns or
-throws.
+write, coordinate through `claim(id, work)`. It claims the row and hands the row
+back; `claim.state(id)` reads who is currently working on it without blocking;
+and you write the usual way with `ablo.<model>.update(id, ...)`.
+
+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. Normal reads still work while the claim is held. If a server read
+should not return a row while someone else is mid-edit, pass `ifClaimed: 'wait'`
+to wait for the claim to clear, or `ifClaimed: 'fail'` to error out instead. The
+callback form releases the claim when the callback returns or throws.
 
 ```ts
 // Claim the row so other participants serialize behind us while we work.
@@ -107,24 +98,24 @@ await ablo.weatherReports.claim(
 );
 ```
 
-Ablo does not fetch the weather. The claim is **advisory**: if another
-participant already holds the row, `claim` waits for them to finish and re-reads
-before handing back the row. While you hold the claim, `update(id, ...)` is
-stale-guarded and rejects with `AbloStaleContextError` if the row changed under
-you. The claim releases automatically once the callback returns or throws.
+Ablo does not fetch the weather. If another participant already holds the row,
+`claim` waits for them to finish, re-reads, and then hands you the fresh row.
+While you hold the claim, `update(id, ...)` rejects with `AbloStaleContextError`
+if someone else changed the row first — so you never overwrite work you didn't
+see. The claim releases automatically once the callback returns or throws.
 
-## 7. Multiplayer and Claimed Work
+## Multiplayer and claimed work
 
 There is no separate multiplayer mode. Use the same schema client for human UI,
 server actions, and agents; Ablo fans out confirmed writes and keeps active
 claims visible on the same model row.
 
-`claimState(id)` tells you when another human or agent is active on the same row.
+`claim.state(id)` tells you when another human or agent is active on the same row.
 For schema clients, `claim(id, work)` waits fairly, re-reads, and then lets you
 write through the model.
 
 ```ts
-const active = ablo.weatherReports.claimState('weather_stockholm');
+const active = ablo.weatherReports.claim.state('weather_stockholm');
 if (active) {
   console.log(`${active.heldBy} is ${active.action}`);
 }
@@ -137,11 +128,12 @@ await ablo.weatherReports.claim('weather_stockholm', async (report) => {
 Use `{ wait: false }` on `claim` when work should be skipped instead of queued
 behind an active holder.
 
-## 8. Next Steps
+## Next steps
 
 Keep using the schema client for app and agent writes.
 
 - [Integration Guide](./integration-guide.md) explains the full app, React, Data Source, multiplayer, and agent path.
+- [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 the optional route for teams keeping rows in their own database.

package/docs/react.md

@@ -23,7 +23,7 @@ pool, and the engine lifecycle; everything below it reads with `useAblo`.
 'use client';
 
 import { AbloProvider } from '@abloatai/ablo/react';
-import { schema } from '@/ablo.schema';
+import { schema } from '@/ablo/schema';
 
 export function Providers({
   children,
@@ -56,8 +56,8 @@ export function Providers({
 | `url`               | hosted endpoint        | WebSocket URL of the sync server (`wss://…`). Hosted apps omit it.                                         |
 | `apiKey`            | session/cookie         | Bootstrap auth. Browser apps **omit this** — the key stays server-side. See Identity below.               |
 | `fallback`          | neutral spinner        | Rendered during the *first* bootstrap only. Pass a branded skeleton, `null`, or `'passthrough'`.          |
-| `bootstrapMode`     | `'full'`               | `'full'` pulls the org's baseline before ready; `'none'` skips the baseline and processes live deltas only.|
-| `persistence`       | `'volatile'`           | `'indexeddb'` opts into an offline queue + reload-surviving cache.                                         |
+| `bootstrapMode`     | `'full'`               | `'full'` loads existing rows before the app renders, so reads are populated on first paint; `'none'` skips that initial load and only streams changes as they happen.|
+| `persistence`       | `'volatile'`           | `'indexeddb'` opts into a durable browser cache that survives reloads.                                     |
 | `onSessionExpired`  | —                      | Fired after the engine has already purged on a rejected session — use for redirect-to-sign-in.            |
 | `onError`           | —                      | Engine / WebSocket / `postBootstrap` errors. Wire to Sentry / Datadog.                                    |
 
@@ -74,8 +74,8 @@ reaches the browser, is the whole of
 import { useAblo } from '@abloatai/ablo/react';
 
 export function ReportView({ report: serverReport }: { report: { id: string; location: string } }) {
-  const report = useAblo((ablo) => ablo.weatherReports.retrieve(serverReport.id)) ?? serverReport;
-  const active = useAblo((ablo) => ablo.weatherReports.claimState(serverReport.id));
+  const report = useAblo((ablo) => ablo.weatherReports.get(serverReport.id)) ?? serverReport;
+  const active = useAblo((ablo) => ablo.weatherReports.claim.state(serverReport.id));
   const claimed = Boolean(active);
 
   return <article>{report.location}</article>;
@@ -84,12 +84,13 @@ export function ReportView({ report: serverReport }: { report: { id: string; loc
 
 The hook:
 
-1. Reads through the same `ablo.<model>` methods as the rest of the SDK.
+1. Uses the same `ablo.<model>.get(id)` / `.getAll()` methods you'd call anywhere
+   else in the SDK — the hook just makes them reactive.
 2. Tracks the model fields read by the selector and re-renders when confirmed
    deltas arrive.
 3. Lets Server Component data stay outside the hook: use `?? serverReport` when a
    parent already loaded the row.
-4. Works for coordination state too, such as `ablo.weatherReports.claimState(id)`.
+4. Works for coordination state too, such as `ablo.weatherReports.claim.state(id)`.
 
 Use the zero-argument form only when you need the full client for callbacks,
 effects, or writes:
@@ -98,18 +99,17 @@ effects, or writes:
 const abloClient = useAblo();
 ```
 
-Prefer selector reads like `useAblo((ablo) => ablo.<model>.retrieve(id))`.
-String model names are kept on older hooks for compatibility, but first examples
-should use the same model-client shape as the rest of the SDK.
+Prefer selector reads like `useAblo((ablo) => ablo.<model>.get(id))`. Older hooks
+also accept a string model name; prefer the selector form shown above.
 
 For collections, keep the selector on the model client too:
 
 ```tsx
 const reports = useAblo((ablo) =>
-  ablo.weatherReports.list({
+  ablo.weatherReports.getAll({
     where: { projectId },
     filter: (report) => report.status !== 'ready',
-    scope: 'live',
+    state: 'live',
   }),
 );
 ```
@@ -117,10 +117,14 @@ const reports = useAblo((ablo) =>
 ## Server Load
 
 ```tsx
-const [report] = await ablo.weatherReports.load({ where: { id } });
+const report = await ablo.weatherReports.retrieve(id);
 ```
 
-Use `load` in Server Components when the row may not be in the local pool yet.
+Use `retrieve` in Server Components when the row may not be in the local pool
+yet — it hydrates from the local store and the server, and returns a Promise, so
+`await` it. (Server reads come in two shapes: `retrieve(id)` for one row and
+`list({ where })` for many; both are async. The synchronous local reads are
+`get`/`getAll`/`getCount`, used in render below.)
 
 ## Writes
 

package/docs/roadmap.md

@@ -5,19 +5,31 @@ What is shipped, what is next, and what we will not build.
 ## Shipped
 
 - **Models, claims, commits** — the core API.
-- **Audit log** — hash-chained per principal, with `delegationChainRoot`.
+- **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.
+- **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
 
-- **Schema migrations** — declarative model schema changes.
 - **Field-level subscriptions** — subscribe to one path, not the whole row.
 - **Bulk import/export** — CSV/JSON round-trip with chain verification.
 

package/docs/schema-contract.md

@@ -0,0 +1,109 @@
+# Schema Contract
+
+Ablo's schema is the integration contract. Define it once, pass it to `Ablo(...)`,
+and every actor gets the same typed model surface:
+
+```txt
+defineSchema(...) -> ablo.<model>.create/retrieve/update/claim(...)
+```
+
+That one object drives:
+
+- typed model clients in trusted server runtimes,
+- React selectors through `useAblo((ablo) => ablo.<model>.get(id))`,
+- agent and background-worker writes,
+- Data Source request/response shape when your database stays canonical,
+- hosted schema push, migration planning, and schema-version gating.
+
+## Minimal shape
+
+```ts
+import Ablo from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+export const schema = defineSchema({
+  weatherReports: model({
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
+    forecast: z.string().optional(),
+  }),
+});
+
+export const ablo = Ablo({
+  schema,
+  apiKey: process.env.ABLO_API_KEY,
+});
+
+await ablo.ready();
+
+const report = await ablo.weatherReports.create({
+  location: 'Stockholm',
+  status: 'pending',
+});
+```
+
+The model key (`weatherReports`) becomes the client namespace
+(`ablo.weatherReports`). The Zod fields become the create/update/read type
+contract. You should not create a parallel string-keyed write path for the same
+data.
+
+## Reads and writes
+
+Use async reads when the row may not be local:
+
+```ts
+const report = await ablo.weatherReports.retrieve(reportId);
+const ready = await ablo.weatherReports.list({ where: { status: 'ready' } });
+```
+
+Use synchronous local reads in render after data has synced:
+
+```ts
+const report = ablo.weatherReports.get(reportId);
+const pending = ablo.weatherReports.getAll({ where: { status: 'pending' } });
+```
+
+Use model writes for every actor:
+
+```ts
+await ablo.weatherReports.update(reportId, { status: 'ready' }, { wait: 'confirmed' });
+```
+
+## Coordination
+
+Agents and background jobs often read, call a tool or model, then write later.
+Wrap that slow span in `claim`:
+
+```ts
+await ablo.weatherReports.claim(reportId, async (report) => {
+  const forecast = await getForecast(report.location);
+  await ablo.weatherReports.update(report.id, { status: 'ready', forecast });
+});
+```
+
+If another writer already holds the row, `claim` waits, re-reads, and gives your
+callback the fresh row. Reads stay open; only acting on the row serializes.
+
+## Storage boundary
+
+Every schema model needs a backing store:
+
+- Use Ablo-managed state when the row can live in Ablo.
+- Use a Data Source when your app database remains canonical.
+
+Do not pass a database URL to `Ablo(...)`. Trusted runtimes use `ABLO_API_KEY`.
+Browser code goes through `<AbloProvider>` or a scoped session route, never a raw
+API key.
+
+## Rules of thumb
+
+- Start with fields and relations before load/index tuning.
+- Import one schema into app code, server actions, agents, and Data Source routes.
+- Keep direct database writes out of the coordinated path unless they are reported
+  back through Data Source events.
+- Use `claim` for slow read -> think -> write spans.
+- Use `readAt` + `onStale: 'reject'` when a write must fail if the row changed
+  after it was read.
+
+For the shortest runnable path, start with [Quickstart](./quickstart.md). For a
+production app, continue with [Integration Guide](./integration-guide.md).

package/examples/README.md

@@ -31,9 +31,13 @@ intentionally cannot import the app schema.
 
 ## Running
 
+Run from the package root, not `examples/` — the `examples/` folder has
+no `package.json`, so Node resolves the entry path against the package
+root and a bare `quickstart.ts` won't be found.
+
 ```bash
-cd packages/sync-engine/examples
-ABLO_API_KEY=sk_test_... npx tsx quickstart.ts
+cd packages/sync-engine
+ABLO_API_KEY=sk_test_... npx tsx examples/quickstart.ts
 ```
 
 ## Data Source (customer-owned database)
@@ -45,8 +49,8 @@ orchestrator drives the customer handler in-process so signer and
 verifier exchange real signed bytes without leaving the process.
 
 ```bash
-cd packages/sync-engine/examples
-npx tsx data-source/run.ts
+cd packages/sync-engine
+npx tsx examples/data-source/run.ts
 ```
 
 See `data-source/README.md` for what each file teaches and the

package/examples/data-source/README.md

@@ -16,10 +16,14 @@ when they want Ablo to coordinate writes against rows stored in
 ## Run
 
 ```bash
-cd packages/sync-engine/examples
-npx tsx data-source/run.ts
+cd packages/sync-engine
+npx tsx examples/data-source/run.ts
 ```
 
+Run from the package root, not `examples/`: the `examples/` folder has
+no `package.json`, so Node resolves the entry path against the package
+root and a bare `data-source/run.ts` won't be found.
+
 No network port, no env vars, no cloud credentials. The orchestrator
 calls the handler in-process. Signer and verifier still exchange
 signed bytes — flip the API key and you'll see a 401.

package/examples/data-source/run.ts

@@ -1,10 +1,11 @@
 /**
  * End-to-end Data Source demo.
  *
- * Run:
+ * Run (from the package root — the examples/ folder has no package.json
+ * of its own, so Node resolves module paths against the package root):
  *
- *   cd packages/sync-engine/examples
- *   npx tsx data-source/run.ts
+ *   cd packages/sync-engine
+ *   npx tsx examples/data-source/run.ts
  *
  * What this proves:
  *

package/examples/quickstart.ts

@@ -3,7 +3,7 @@
  *
  * Run:
  *
- *   ABLO_API_KEY=sk_test_... npx tsx quickstart.ts
+ *   ABLO_API_KEY=sk_test_... npx tsx examples/quickstart.ts
  */
 
 import Ablo from '@abloatai/ablo';