@abloatai/ablo 0.37.0 → 0.38.0

package/docs/cli.md

@@ -11,7 +11,7 @@ SQL — so what you test is what ships.
 ```bash
 npx ablo init      # scaffold ablo/schema.ts + client
 npx ablo login     # authorize in the browser
-npx ablo dev       # push schema to the test sandbox + watch
+npx ablo dev       # prepare an isolated Git branch + push/watch
 ```
 
 **Two setup styles, and they pick your commands.** If your app database is the
@@ -19,42 +19,43 @@ source of truth, expose a [Data Source endpoint](./data-sources.md) and keep DB
 credentials in your app. If you explicitly want Ablo to open a Postgres
 connection, use the **Direct Postgres connector** commands: `ablo migrate`
 applies changes to your own `DATABASE_URL`, and `ablo check` / `ablo pull`
-adopt tables you already have. Hosted sandbox commands are tagged **Hosted**;
+adopt tables you already have. Hosted branch commands are tagged **Hosted**;
 direct-connector commands are tagged **Direct Postgres**.
 
 ## Authenticate
 
 `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) 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`.
+90-day, project-scoped `mk_` management credential. It has no test/live mode
+and cannot read or write application data. `ablo dev` uses it to create or
+resume a branch and exchanges it for a temporary branch-bound runtime key.
 
 | 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, what each can do, expiry), and server health. |
-| `ablo mode [sandbox\|production]` | Switch the active environment. With no argument, prompts.                         |
-
-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
-
-Like Stripe, every account has a **test** mode and a **live** mode, and a key
-belongs to one of them. Test keys are bound to an isolated sandbox: their reads
-and writes never touch production data. Switch with `ablo mode`; `ablo dev` is always
-the sandbox by design.
-
-The schema is **one definition serving both**: a sandbox reads the production
-schema until it is pushed one of its own, so your test and live keys see the same
-models and only the rows differ. Each plane keeps its own copy once pushed, so a
-schema change reaches production when you push it with a live key — see
+| `ablo login`             | Authorize in the browser; store one project management credential.         |
+| `ablo login --project <slug>` | Same, scoped to a project, which becomes active.                     |
+| `ablo logout`            | Remove the stored credentials.                                             |
+| `ablo status`            | Show the active org/project, effective credential, branch target, and server health. |
+
+Keys live in `~/.config/ablo/credentials.json` (mode `0600`), keyed by project.
+The non-secret `config.json` holds the active project. In **CI**, don't log in —
+set the project management credential as `ABLO_MANAGEMENT_KEY`; it overrides the
+stored credential during branch bootstrap.
+
+## Development branches vs live
+
+A branch is your project at full strength over its own rows: the same models,
+the same schema artifacts, the same claims and the same rules production runs.
+
+Production is the project root. `ablo dev` creates or reuses a child branch for
+your Git branch, then mints a temporary `sk_test_` key bound to that child.
+Reads, writes, schema artifacts, claims, and credentials stay isolated from
+production and from other development branches, which is what makes a
+schema-changing pull request as routine as a code-only one.
+
+There is no local mode switch. Development selection comes from Git or
+`--branch`; production authority comes only from an explicit live credential.
+Production schema changes use the reviewed one-shot path in
 [Deployment](./deployment.md).
 
 ## Projects
@@ -70,7 +71,7 @@ selects which profile every command authenticates with.
 | `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.                       |
+| `ablo login --project <slug>` | Store management access 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
@@ -81,14 +82,15 @@ 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
+npx ablo login --project war-room   # stores its management credential, 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.
+(`ablo login --project <slug>`). In CI, an explicit `ABLO_MANAGEMENT_KEY`
+bypasses profiles for project/branch administration; the runtime key remains
+`ABLO_API_KEY`.
 
 ## Commands
 
@@ -96,10 +98,10 @@ profiles entirely: it acts in whatever project it was minted for.
 | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
 | `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 dev`                         | **Hosted**: ensure an isolated Git branch, wire its temporary key, push, then watch `ablo/schema.ts`.                                        | `--branch <slug>`, `--branch-ttl-hours <1-168>`, `--no-watch`, `--schema`, `--export`, `--url` |
+| `ablo branch list\|status\|check\|create\|ensure\|credential\|delete` | Manage and diagnose immutable branch planes and expiring credentials.                          | Run `ablo branch --help`; use `--json` for automation.                                                   |
+| `ablo logs`                        | Tail the effective credential's branch activity. Follows by default.                                                                          | `-n, --tail <N>`, `--since <dur\|ts>`, `--model`, `--op`, `--json`, `--no-follow` |
 | `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`         |
 | `ablo migrate`                     | **Direct Postgres**: provision just the synced models (plus the adapter's `ablo_outbox` / `ablo_idempotency`) in your own `DATABASE_URL`. Leaves your other tables alone.                                                          | `--dry-run`, `--output <file>`, `--schema`, `--export`                                                 |
 | `ablo pull`                        | **Direct Postgres**: generate `defineSchema(...)` from your existing tables (read-only, like `prisma db pull`).                              | `--out <path>`, `--app-schema <name>`, `--import <pkg>`, `--force`                                     |
@@ -131,16 +133,22 @@ HTTP at `/api/docs/<slug>` and through the docs MCP server.
 
 ## `ablo dev`
 
-The development loop. It pushes `ablo/schema.ts` to your **test sandbox**,
-prints the env line your app needs, then watches the file and re-pushes on every
-save (300 ms debounce). It refuses live keys so a tight save loop can never
-churn production data.
+The branch-first development loop. It discovers your Git/CI branch, ensures the
+matching Ablo child branch, exchanges the stored `mk_` project credential for an
+expiring branch-only key, writes that key to gitignored `.env.local`, pushes
+`ablo/schema.ts`, and re-pushes on every save.
 
 ```bash
-npx ablo dev             # push + watch
-npx ablo dev --no-watch  # push once and exit
+npx ablo dev                              # discover from Git, push + watch
+npx ablo dev --branch preview-pr-482      # explicit branch
+npx ablo dev --no-watch                   # prepare, push once, exit
+npx ablo dev --branch-ttl-hours 24        # change temporary-key lifetime
 ```
 
+It does not start your app, run migrations, create a database-provider branch,
+or copy production rows. Read [Branch-first development](./branch-development.md)
+for the exact discovery order, CI flow, database boundary, and troubleshooting.
+
 ## `ablo logs`
 
 Tail commit activity, like `stripe logs tail`. Scope comes from the key — a test
@@ -212,7 +220,7 @@ reshaping it. `ablo check` is read-only; it never proposes a migration.
 
 Same engine, two setups. If you use the **Direct Postgres connector**, use
 `ablo migrate` — it provisions the synced models in your own `DATABASE_URL`. If
-Ablo manages the sandbox/hosted store, use `ablo push` and `ablo dev` — the
+Ablo manages the hosted store, use `ablo push` and `ablo dev` — the
 server applies the change and version-gates connecting clients.
 
 ```bash

package/docs/data-sources.md

@@ -244,6 +244,17 @@ lifecycle. It needs no replication setup, which is exactly why it's the fallback
 reach for it only when logical replication isn't available, and prefer `ablo
 connect` everywhere else.
 
+The current Prisma, Drizzle, and Kysely adapters are PostgreSQL bindings. Their
+profiles record three independent facts: the database is PostgreSQL, the binding
+is Prisma/Drizzle/Kysely, and observation is either the transactional outbox or
+PostgreSQL WAL. An ORM name does not imply that the same adapter supports every
+database that ORM can connect to.
+
+The outbox automatically observes writes made through Ablo. A write made
+directly by other application code is visible only if that code writes the same
+outbox record in its transaction. Native WAL observation sees both Ablo and
+external writes.
+
 ## Next steps
 
 - [Quickstart](./quickstart.md) — connect and write through `ablo.<model>`.

package/docs/deployment.md

@@ -54,25 +54,25 @@ Everything below is those three in order.
 ### Planes: what a deployment targets
 
 A **plane** is the isolation unit a credential acts on. `production` is the root
-plane; every sandbox sits beside it. Three things are per-plane, and knowing
-which three is most of what production readiness means:
+branch; development and preview branches are children. Three things are
+per-plane, and knowing which three is most of what production readiness means:
 
-- **Rows:** a sandbox write is invisible to production and to every other sandbox.
+- **Rows:** a child-branch write is invisible to production and every sibling.
 - **The registered database:** one per plane, so your production database and
   your dev database are separate registrations.
 - **The active schema artifact:** the model shapes the engine actually routes on.
 
-A key's plane is fixed at mint and spelled in its prefix: `sk_live_` acts on
-production, `sk_test_` on a sandbox. There is no runtime override — the
-credential *is* the environment selector, which is why application code never
-passes one.
+A key's plane is fixed at mint: `sk_live_` acts on production, while `sk_test_`
+is bound to one development branch. The immutable branch id,
+not a user-supplied slug, is the selector. This is why application code never
+passes an environment.
 
-One asymmetry is worth carrying into your deploy plan. A sandbox with no schema
-artifact of its own reads **production's**, so a schema pushed to production
-reaches your sandboxes automatically. The reverse does not hold: a push from a
-sandbox key creates a sandbox artifact that shadows production **for that
-sandbox's readers only**, and production keeps running the schema it was last
-pushed. Production gets its models when you push to production.
+A child copies its parent's active schema when it is created, then owns its
+schema history. A child push never changes production. Production gets new
+models only when the reviewed deployment pushes them to the root.
+
+There is no shared development plane. New credentials are branch-bound; follow
+[Branch-first development](./branch-development.md).
 
 ## 1. The database production writes to
 
@@ -141,9 +141,10 @@ minting. Two things bite specifically at deploy time.
 observe-only `rk_live_` by design, so a stolen CLI config cannot write to
 production. A production deploy needs a **secret** `sk_live_` from the dashboard,
 supplied as `ABLO_API_KEY`. You do not have to discover this from a failed
-deploy: `ablo login`, `ablo mode production`, and `ablo status` each name what
-the key in hand does, and `ablo status --json` reports it as `effectiveKey.kind`
-for a pipeline to check before it pushes.
+deploy: `ablo login` and `ablo status` name what the key in hand does, and
+`ablo status --json` reports it as `effectiveKey.kind` for a pipeline to check
+before it pushes. The deploy itself uses an explicit dashboard `sk_live_` in
+`ABLO_API_KEY`; there is no local mode switch.
 
 **An explicit key always wins.** The CLI resolves `ABLO_API_KEY`, then
 `.env.local`, then `.env`, then the stored login — and `ablo status` prints which
@@ -204,9 +205,9 @@ answer to where a push would land.
 
 ## Webhooks point at the deployed URL
 
-`npx ablo dev` forwards commits to your machine while you build, the way
-`stripe listen` does. A deployed endpoint is registered once, and Ablo returns
-the signing secret a single time:
+`npx ablo dev` prepares the schema branch; it does not forward webhooks. A
+deployed HTTPS endpoint is registered once, and Ablo returns the signing secret
+a single time:
 
 ```bash
 ABLO_API_KEY=sk_live_… npx ablo webhooks create https://yourapp.com/api/ablo/[...all]

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

@@ -1,17 +1,14 @@
-# AI SDK Tool
+# AI SDK Tools
 
-> Put a claim-and-commit loop inside an AI SDK tool call.
+> Give an AI SDK agent safe access to the same typed Ablo resources as your
+> backend.
 
 Use AI SDK for the agent loop and Ablo for the state boundary inside the tool.
 When an agent updates a shared record from inside a tool call you have a
-concurrency problem: another agent may be editing the same row, and a naive write
-silently overwrites it. This is the safe pattern — read the record, claim the row
-so anyone else waits their turn, write through a checked update, and release the
-claim automatically.
-
-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.
+concurrency problem: another agent or a person may be editing the same row, and
+a naive write can overwrite work the model never saw. Ablo's tool adapters put
+the authoritative read, retry, claim, and confirmed-write behavior behind the
+ordinary AI SDK tool contract.
 
 ```ts
 // app/api/chat/route.ts
@@ -20,11 +17,11 @@ import { defineSchema, model, z as schemaZ } from '@abloatai/ablo/schema';
 import { anthropic } from '@ai-sdk/anthropic';
 import {
   streamText,
-  tool,
   convertToModelMessages,
   stepCountIs,
   type UIMessage,
 } from 'ai';
+import { updateTool } from '@abloatai/ablo/ai-sdk';
 import { z } from 'zod';
 
 export const runtime = 'nodejs';
@@ -43,42 +40,19 @@ const ablo = Ablo({
   transport: 'http',
 });
 
-const updateTask = tool({
-  description: 'Update a task in the product database.',
+const updateTask = updateTool(ablo.tasks, {
+  title: 'Update task',
+  description: 'Update a task without overwriting concurrent work.',
   inputSchema: z.object({
     taskId: z.string(),
     status: z.enum(['todo', 'doing', 'done']).optional(),
     summary: z.string().optional(),
   }),
-  execute: async ({ taskId, status, summary }) => {
-    await ablo.ready();
-
-    // retrieve hits the server for the latest row (async — await it).
-    const task = await ablo.tasks.get({ id: taskId });
-    if (!task) return { ok: false, reason: 'not_found' };
-
-    // If another agent already holds this row, claim waits for them to finish,
-    // re-reads the fresh row, then hands it back on `claim.data`. The claim is
-    // released automatically when it goes out of scope.
-    await using claim = await ablo.tasks.claim({
-      id: taskId,
-      description: 'editing',
-      ttl: '2m',
-    });
-
-    // Because you hold the claim, this update is rejected if the row changed
-    // underneath you, instead of silently overwriting it.
-    const updated = await ablo.tasks.update({
-      id: claim.data.id,
-      data: {
-        status: status ?? claim.data.status,
-        summary: summary ?? claim.data.summary,
-      },
-      wait: 'confirmed',
-    });
-
-    return { ok: true, task: updated };
-  },
+  id: ({ taskId }) => taskId,
+  apply: (current, { status, summary }) => ({
+    status: status ?? current.status,
+    summary: summary ?? current.summary,
+  }),
 });
 
 export async function POST(req: Request) {
@@ -100,13 +74,12 @@ export async function POST(req: Request) {
 
 The model provider is interchangeable — swap `anthropic(...)` for any
 server-bound provider instance. What matters is that the route binds the model on
-the server (never trusting one sent in the request body), converts the incoming
-`UIMessage[]` with `convertToModelMessages`, and that the tool:
-
-- reads the latest row with `retrieve` (a server read),
-- claims it for exclusive, ordered access — if someone else holds it, the claim
-  waits for them, then re-reads,
-- writes through the model resource, which is rejected if the row changed
-  underneath you,
-- waits for confirmation with `wait: 'confirmed'`,
-- and auto-releases the claim when the tool returns.
+the server (never trusting one sent in the request body) and converts the
+incoming `UIMessage[]` with `convertToModelMessages`.
+
+`updateTool` defaults to a functional update: Ablo re-reads and reapplies the
+patch if another participant writes first. Use `strategy: 'claim'` when the
+model should skip work already owned by someone else, or `strategy: 'queue'`
+when it should wait in Ablo's server-owned FIFO claim queue. The same entrypoint
+also exports `readTool`, `createTool`, and `deleteTool`; deletes require AI SDK
+approval unless the application explicitly disables it.

package/docs/how-it-works.md

@@ -69,8 +69,9 @@ database differs by environment — the code is identical.
 - **Production:** your Postgres. `ablo connect` sets up a scoped writer role and
   logical replication; your rows live in your database, and Ablo writes to them
   through that role.
-- **Sandbox and local dev:** a separate or local Postgres you can throw away. Same
-  models, same code, a different database behind them.
+- **Development branches and local dev:** a separate or local Postgres, or a
+  branch of the one you already run. Same models, same code, a different
+  database behind them.
 - **Before you connect one.** Ablo keeps state in its own log, so you can build the
   whole app today and point it at a real database when you're ready.
 

package/docs/index.md

@@ -60,11 +60,14 @@ based on a row that has since changed is turned away rather than applied.
     stay in your own migrations.
 
     ```bash
-    npx ablo init && npx ablo push
+    npx ablo init
+    npx ablo dev
     ```
 
-    `push` is the step everything depends on: the server keeps its own copy of the schema, and
-    until it has yours, a write to a new model fails with `server_execute_unknown_model`.
+    `dev` gives the current Git branch an isolated Ablo branch, wires its temporary key,
+    pushes the schema, and watches for changes. Until the server has your schema, a write to
+    a new model fails with `server_execute_unknown_model`. See
+    [Branch-first development](./branch-development.md).
   </Step>
 
   <Step title="Connect the database the rows live in">
@@ -161,6 +164,7 @@ default caller, not a special one.
 
 - [Quickstart](./quickstart.md) — make your first coordinated write.
 - [Integration Guide](./integration-guide.md) — the canonical end-to-end integration.
+- [Integrations](./integrations.md) — long-running tasks, ingestion, and other application-edge runtimes.
 - [CLI & Migrations](./cli.md) — `init` / `connect` / `push` / `migrate` / `generate`.
 - [Connect Your Database](./data-sources.md) — where rows land when your own database is canonical.
 - [Deployment](./deployment.md) — the database, the keys, and the schema push that take an integration to production.

package/docs/integration-guide.md

@@ -66,24 +66,17 @@ deterministic demo; it does not call your API key or mutate hosted Ablo data.
 It is also built for coding agents: copy the sandbox prompt into Claude Code or
 Codex and ask it to wire one real model through the schema model API.
 
-Use the authenticated org dashboard sandbox for real integration work. The
-default sandbox is the equivalent of Stripe test mode:
-
-- it is scoped to the organization,
-- it has an isolated sync group prefix,
-- it mints `sk_test_*` keys,
-- it can be reset without touching live state,
-- additional sandboxes can start blank or from copied live configuration.
-
-Live keys and sandbox keys are separate. Use `sk_test_*` while wiring your app,
-agents, and Data Source endpoint; move to `sk_live_*` only when the same schema
-and write path are ready for production.
+Use `npx ablo dev` for real integration work. It derives an immutable branch
+from Git, inherits the parent schema, and writes a temporary branch credential
+to `.env.local`. Each developer or pull request gets independent schema, rows,
+claims, and logs. Use an explicit `sk_live_*` root credential only in the
+reviewed production deployment.
 
 When handing this to a coding agent, give it a concrete target:
 
 ```txt
 Add Ablo to this app for one model your agents edit.
-Use the org sandbox sk_test_* key. Declare schema, add the Ablo client, replace
+Run npx ablo dev and use its branch-bound key. Declare schema, add the Ablo client, replace
 one write with ablo.<model>.update(..., { readAt, onStale: 'reject',
 wait: 'confirmed' }), and add a smoke test for two concurrent writers.
 ```