@abloatai/ablo 0.12.0 → 0.13.0

package/docs/cli.md

@@ -24,18 +24,23 @@ direct-connector commands are tagged **Direct Postgres**.
 
 `ablo login` runs the OAuth 2.0 device flow: it opens your browser, you choose
 **log in** or **create an account** and approve, and the CLI provisions a
-**test + live key pair** (90-day, restricted) and stores them locally. This
-mirrors `stripe login`.
+**test + live key pair** (90-day) and stores them locally. The test key is a
+sandbox `sk_test_` key; the live key is a restricted `rk_live_` key (read-only
+observation — `logs`, `status`), so a stolen config can't write to production.
+This mirrors `stripe login`.
 
 | Command                  | What it does                                                               |
 | ------------------------ | -------------------------------------------------------------------------- |
 | `ablo login`             | Authorize in the browser; provisions + stores a test and a live key.       |
+| `ablo login --project <slug>` | Same, but scope (and mint) the pair to a project, and make it active. |
 | `ablo logout`            | Remove the stored keys.                                                    |
 | `ablo status`            | Show the active org, mode, both keys (prefix + expiry), and server health. |
 | `ablo mode [sandbox\|production]` | Switch the active environment. With no argument, prompts.                         |
 
-Keys are stored in `~/.config/ablo/config.json` (mode `0600`). In **CI**, don't
-log in — set `ABLO_API_KEY`, which always overrides the stored key.
+Keys live in `~/.config/ablo/credentials.json` (mode `0600`), keyed by project
+then environment; the non-secret `config.json` holds only the active mode and
+project. In **CI**, don't log in — set `ABLO_API_KEY`, which always overrides
+the stored key.
 
 ## Test vs live
 
@@ -47,6 +52,39 @@ the sandbox by design.
 The schema, however, is **shared** across the org — pushing a schema (from
 either environment) defines the same models sandbox and production see; only the rows differ.
 
+## Projects
+
+An org can have multiple **projects**, each with its own isolated keys, schema,
+and data. Keys are scoped to a project **at mint** and never re-scoped, so the
+CLI keeps a separate credential profile per project — Stripe's
+`login --project-name` model. The active project (set with `projects use`)
+selects which profile every command authenticates with.
+
+| Command                       | What it does                                                                       |
+| ----------------------------- | ---------------------------------------------------------------------------------- |
+| `ablo projects list`          | List the org's projects (marks the active one and the org-default).                |
+| `ablo projects create <slug>` | Create a project (`--name "Display Name"`). Its keys/schema/data are isolated.     |
+| `ablo projects use <slug>`    | Switch the active project. `ablo projects use default` returns to the org-default. |
+| `ablo login --project <slug>` | Mint and store a key pair for a project, and make it active.                       |
+
+Because keys are fixed to a project, `projects use` only changes which profile
+is active — it never re-scopes an existing key. Switch to a project you haven't
+logged into yet and the CLI tells you to mint one:
+
+```bash
+npx ablo projects use war-room
+#   ✓ now targeting project war-room (prj_…)
+#   No key stored for this project yet — run `ablo login --project war-room` to mint one.
+
+npx ablo login --project war-room   # mints + stores its key pair, keeps it active
+```
+
+If you run a project-scoped command (`push`, `dev`) while the active project has
+no key — but other projects do — the CLI **refuses** rather than silently
+deploying with the wrong project's credential, and names the fix
+(`ablo login --project <slug>`). In CI, an explicit `ABLO_API_KEY` bypasses
+profiles entirely: it acts in whatever project it was minted for.
+
 ## Commands
 
 | Command                            | What it does                                                                                                                                  | Flags                                                                                                  |
@@ -54,6 +92,7 @@ either environment) defines the same models sandbox and production see; only the
 | `ablo init`                        | Scaffold `ablo/` (`schema.ts`, client, optional Data Source / agent / component), write `.env`, install the SDK. Offers to log in at the end. | —                                                                                                      |
 | `ablo login` / `logout` / `status` | Authentication & status (above).                                                                                                              | —                                                                                                      |
 | `ablo mode [sandbox\|production]`   | Switch active environment.                                                                                                                           | —                                                                                                      |
+| `ablo projects list\|create\|use\|rename` | Manage projects and the active one (see [Projects](#projects)). Each project's keys/schema/data are isolated.                          | `--name "<display>"` (create/rename)                                                                    |
 | `ablo dev`                         | **Hosted** — push the schema to your test sandbox, then watch `ablo/schema.ts` and re-push on save.                                           | `--no-watch`, `--schema <path>`, `--export <name>`, `--url <url>`                                      |
 | `ablo logs`                        | Tail your scope's commit activity (`stripe logs tail`). Follows by default.                                                                   | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow`, `--mode sandbox\|production` |
 | `ablo push`                        | **Hosted** — upload the schema to Ablo; the server diffs, migrates, and activates it.                                                         | `--force`, `--rename old:new`, `--backfill model.field=value`, `--schema`, `--export`, `--url`         |

package/docs/client-behavior.md

@@ -146,7 +146,7 @@ the latest row, then hands you the fresh row — so you can't overwrite a change
 see. Options on the claim:
 
 - default `claim` waits in the fair queue and re-reads before handing you the row;
-- `{ wait: false }` rejects with `AbloClaimedError` instead of queuing;
+- `{ queue: false }` rejects with `AbloClaimedError` instead of queuing;
 - `{ maxQueueDepth }` rejects if the wait line is already too deep.
 
 While waiting, schema clients learn when the claim clears from the live claim
@@ -166,7 +166,7 @@ All SDK errors extend `AbloError` and carry a stable `type`.
 | `AbloValidationError` | Invalid input or unsupported request shape. |
 | `AbloServerError` | Server-side 5xx. Retry with backoff if the operation is idempotent. |
 | `AbloStaleContextError` | Write was based on stale `readAt` state. Re-read and retry. |
-| `AbloClaimedError` | An active claim conflicted with `{ wait: false }`, the queue was too deep, or a claim wait timed out. |
+| `AbloClaimedError` | An active claim conflicted with `{ queue: false }`, the queue was too deep, or a claim wait timed out. |
 
 ```ts
 import { AbloClaimedError } from '@abloatai/ablo';

package/docs/coordination.md

@@ -280,7 +280,7 @@ Releasing **promotes the head of the queue**: the next waiter receives the claim
 **Example**
 
 ```ts
-const claim = await ablo.weatherReports.claim({ id: 'report_stockholm', action: 'reviewing' });
+const claim = await ablo.weatherReports.claim({ id: 'report_stockholm', reason: 'reviewing' });
 const report = claim.data;
 try {
   const ok = await reviewExternally(report);

package/docs/examples/agent-human.md

@@ -47,14 +47,14 @@ export async function markReady(reportId: string) {
   if (!report) return { status: 'not_found' };
 
   try {
-    // wait: false → don't queue behind a current holder. If a human already
+    // queue: false → don't queue behind a current holder. If a human already
     // holds the row, claim rejects with AbloClaimedError (caught below), so the
-    // agent yields instead of waiting. Omit it, or pass wait: true, to queue
-    // behind them. action → the label observers see while we work.
+    // agent yields instead of waiting. Omit it, or pass queue: true, to queue
+    // behind them. reason → the label observers see while we work.
     await using claim = await ablo.weatherReports.claim({
       id: reportId,
-      wait: false,
-      action: 'marking_ready',
+      queue: false,
+      reason: 'marking_ready',
     });
     const claimed = claim.data;
 
@@ -120,7 +120,7 @@ export function ReportRow({ report: serverReport }: Props) {
 - The claim is visible to everyone: the UI reads it synchronously with
   `claim.state({ id })`, and it also arrives over the live stream.
 - `claim({ id })` makes writers take turns instead of racing — with
-  `wait: false`, the agent simply yields when a human already holds the row.
+  `queue: false`, the agent simply yields when a human already holds the row.
 - The `update` made while the claim is held is stale-checked automatically, so a human's
   edit landing mid-run rejects the agent's write with a typed
   `AbloStaleContextError` instead of overwriting it.

package/docs/examples/ai-sdk-tool.md

@@ -43,7 +43,7 @@ const updateReport = tool({
     // The claim is released automatically when it goes out of scope.
     await using claim = await ablo.weatherReports.claim({
       id: reportId,
-      action: 'editing',
+      reason: 'editing',
       ttl: '2m',
     });
     const claimed = claim.data;

package/docs/examples/existing-python-backend.md

@@ -37,10 +37,8 @@ import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
 export const schema = defineSchema({
   weatherReports: model({
-    id: z.string(),
     location: z.string(),
     status: z.enum(['pending', 'ready']),
-    updatedAt: z.string(),
   }),
 });
 ```

package/docs/examples/nextjs.md

@@ -57,8 +57,8 @@ import { ablo } from '@/lib/ablo';
 export async function markReady(id: string) {
   await using claim = await ablo.weatherReports.claim({
     id,
-    wait: false,
-    action: 'marking_ready',
+    queue: false,
+    reason: 'marking_ready',
   });
   const claimed = claim.data;
 

package/docs/examples/scoped-agent.md

@@ -19,18 +19,18 @@ import { defineSchema, identityRole, model, relation, z } from '@abloatai/ablo/s
 
 export const schema = defineSchema(
   {
-    // A deck's rows form the group `deck:<id>` (the kind comes from `scope`).
+    // A deck's rows form the group `deck:<id>` (the kind comes from `groups.root`).
     decks: model(
       { title: z.string() },
       {},
-      { orgScoped: true, scope: 'deck' },
+      { groups: { root: 'deck' } },
     ),
     // A slide has no group of its own. It inherits its deck's group via the
     // `parent` edge, so a slide write reaches everyone viewing the deck.
     slides: model(
       { deckId: z.string(), body: z.string() },
       { deck: relation.belongsTo('decks', 'deckId', { parent: true }) },
-      { orgScoped: true },
+      {},
     ),
   },
   {

package/docs/examples/server-agent.md

@@ -38,8 +38,8 @@ export async function completeReport(reportId: string) {
 
   await using claim = await ablo.weatherReports.claim({
     id: reportId,
-    wait: false,
-    action: 'completing',
+    queue: false,
+    reason: 'completing',
   });
   const claimed = claim.data;
 
@@ -60,9 +60,9 @@ the server has accepted it.
 
 The two options on the claim:
 
-- `wait: false` — skip this record if another claim is already in progress,
+- `queue: false` — skip this record if another claim is already in progress,
   rather than queueing behind it. (The default queues.)
-- `action: 'completing'` — a human-readable label for what your worker is doing,
+- `reason: 'completing'` — a human-readable label for what your worker is doing,
   visible to anyone reading `claim.state({ id })`.
 
 Because the worker uses the same schema and `claim()` as the UI, its writes sync

package/docs/identity.md

@@ -47,18 +47,20 @@ import { defineSchema, identityRole, relation, model, z } from '@abloatai/ablo/s
 
 export const schema = defineSchema(
   {
-    // A scope root: its rows form the group `deck:<id>` (kind from `scope`).
+    // A scope root: its rows form the group `deck:<id>` (kind from `groups.root`).
+    // Tenant isolation defaults to a row-local `organization_id` column, so no
+    // `policy` is needed here.
     decks: model(
       { title: z.string(), status: z.enum(['draft', 'published']) },
       {},
-      { orgScoped: true, scope: 'deck' },
+      { groups: { root: 'deck' } },
     ),
     // A child: it has no group of its own; it inherits its deck's group via the
     // `parent` edge. A write to a slide reaches everyone viewing the deck.
     slides: model(
       { deckId: z.string() },
       { deck: relation.belongsTo('decks', 'deckId', { parent: true }) },
-      { orgScoped: true },
+      {},
     ),
   },
   {
@@ -208,13 +210,13 @@ You never write a sync-group string for a row. You declare a model's *place* in
 the entity graph and the engine derives the groups its rows fan out on. Three
 declarations, in order of how often you reach for them:
 
-**`scope` — this model is a scope root.** Its rows form a group of their own.
-The kind comes from the model's `typename` by default, or pass a string to set
-it explicitly (use the string form when the wire kind differs from the typename,
-e.g. typename `SlideDeck` but group `deck:<id>`):
+**`groups.root` — this model is a scope root.** Its rows form a group of their
+own. The kind comes from the model's `typename` by default, or pass a string to
+set it explicitly (use the string form when the wire kind differs from the
+typename, e.g. typename `SlideDeck` but group `deck:<id>`):
 
 ```ts
-decks: model({ title: z.string() }, {}, { orgScoped: true, scope: 'deck' });
+decks: model({ title: z.string() }, {}, { groups: { root: 'deck' } });
 // a deck row → group `deck:<id>`
 ```
 
@@ -232,7 +234,7 @@ slides: model(
     deck: relation.belongsTo('decks', 'deckId', { parent: true }),  // ownership → inherit deck:<id>
     sourceSlide: relation.belongsTo('slides', 'sourceSlideId'),     // reference → NOT routed
   },
-  { orgScoped: true },
+  {},  // default policy: row-local organization_id
 );
 ```
 
@@ -241,8 +243,8 @@ slides: model(
 > some required FKs are mere references. Containment is a fact only you know, so
 > it's declared, exactly as it is in OpenFGA/Zanzibar.
 
-**`grants` — a membership edge.** On a join model (e.g. `dataroomMember`), it
-says "this row grants a *subject* access to a *scope root*." Both are relation
+**`groups.grants` — a membership edge.** On a join model (e.g. `dataroomMember`),
+it says "this row grants a *subject* access to a *scope root*." Both are relation
 names on the model. The server resolves it at connect time — for user `U`, it
 finds the scope-root groups `U` is a member of and adds them to `U`'s allowed
 set (Linear's `/sync/user_sync_groups`). Use this for sub-org sharing; plain
@@ -255,15 +257,19 @@ dataroomMember: model(
     member: relation.belongsTo('users', 'userId'),
     room: relation.belongsTo('datarooms', 'dataroomId'),
   },
-  { orgScoped: true, grants: { subject: 'member', scope: 'room' } },
+  { groups: { grants: { subject: 'member', scope: 'room' } } },
 );
 ```
 
 For the rare group keyed on a plain field rather than a relation (per-recipient
-inbox fan-out, say), there's an `entityRoles: [entityRole({ kind, source })]`
+inbox fan-out, say), there's a `groups: { roles: [entityRole({ kind, source })] }`
 escape hatch. For rows that inherit *tenancy* (not a sync group) through a
-foreign key without carrying `organization_id`, use `scopedVia` rather than
-`orgScoped: false` — the latter exposes the whole table cross-tenant. See
+foreign key without carrying `organization_id`, use `policy: { by: 'parent', fk,
+parent }` rather than opting out of isolation. The old `orgScoped: false`
+exposed the whole table cross-tenant, so `validate_schema` rejects the removed
+options as `tenancy-option-removed` errors and steers you to `policy: { by:
+'parent' }` (FK inheritance) or, for genuinely global reference data, the
+explicit `policy: { by: 'none' }`. See
 `packages/sync-engine/src/schema/model.ts` for the full option set.
 
 ## How identity reaches Ablo — the proxy model
@@ -393,8 +399,8 @@ an entity anchor on the models an agent operates on:
 
 ```ts
 // each scope-root model an agent edits forms a per-entity group
-documents: model({ /* … */ }, {}, { orgScoped: true, scope: 'document' }),
-decks:     model({ /* … */ }, {}, { orgScoped: true, scope: 'deck' }),
+documents: model({ /* … */ }, {}, { groups: { root: 'document' } }),
+decks:     model({ /* … */ }, {}, { groups: { root: 'deck' } }),
 ```
 
 Then a run subscribes only to the entity groups for the rows it works on — a
@@ -484,9 +490,10 @@ an agent pointed at the entities it's working on. You **never hand-write**
    (it returns a participant handle with `.peers`). See
    [Coordination](./coordination.md).
 
-> **`scope` is the schema model option, not a client setting.** `scope: 'deck'`
-> in `model(...)` declares a scope root ([Half 2](#half-2--per-model-scope-row--group)) —
-> it names the group (`deck:<id>`) that the mechanisms above then subscribe to.
+> **`groups.root` is the schema model option, not a client setting.**
+> `groups: { root: 'deck' }` in `model(...)` declares a scope root
+> ([Half 2](#half-2--per-model-scope-row--group)) — it names the group
+> (`deck:<id>`) that the mechanisms above then subscribe to.
 > There is no `Ablo({ scope })` constructor option. The lifecycle filter on
 > [`list()`](./api.md#model-methods) is a separate axis named **`state`**
 > (`'live' | 'archived' | 'all'`, GitHub's open/closed/all), precisely so it

package/docs/index.md

@@ -99,4 +99,3 @@ Three things stay true no matter how you use Ablo:
 - [README](../README.md) — product overview and first example.
 - [AGENTS.md](../AGENTS.md) — short installation guidance for coding assistants.
 - [Changelog](../CHANGELOG.md) — what shipped recently.
-- [Roadmap](./roadmap.md) — what's planned next.

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/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.12.0",
+  "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.