@abloatai/ablo 0.37.1 → 0.39.0

package/AGENTS.md

@@ -13,10 +13,10 @@ Don't hand-write the integration. Run the CLI; it generates the current-API sche
 - **Auth:** set `ABLO_API_KEY` in the environment. Do **NOT** run `ablo login` — it opens a browser device flow and blocks an agent.
 - **Connect your database — logical replication (the primary path):** `npx ablo connect` prints the setup SQL (`wal_level=logical`, a publication, a `REPLICATION` role); `npx ablo connect register` registers the source with Ablo in one step. Ablo **consumes your Postgres' logical-replication stream** — it never runs DDL on, writes to, owns, or migrates your database, and your application keeps the write path. Registration **is** the enable; there is no tier or flag to pick. (Ablo hosts only the transaction log + coordination, never your rows.)
 - **Fallback — signed Data Source endpoint** (DB can't grant a `REPLICATION` role): the generated `ablo/data-source.ts` exposes one route; Ablo sends signed requests and your app touches its own DB. **Only in this mode** does `npx ablo migrate` provision the adapter's bookkeeping tables (`ablo_outbox`, `ablo_idempotency`) plus your Ablo models — it does **not** touch your other tables. Keep your own migrations (drizzle-kit / prisma migrate) for auth and anything outside the Ablo schema.
-- **No database yet?** A sandbox `sk_test` key holds throwaway **test data** (Stripe-test-mode style) so you can try Ablo before connecting your own Postgres. Test-mode only — in production every row lives in your database.
+- **No database yet?** Run `npx ablo dev --no-watch --branch <name>` to create an isolated non-root branch and obtain its expiring `sk_test_` credential. The branch uses a throwaway hosted data plane; Production remains the protected root. There is no shared Sandbox mode.
 - **Adopt an existing DB schema:** `npx ablo pull prisma [path]` / `pull drizzle <module>` (lossless) or `pull` (live DB, lossy). Writes `ablo/schema.ts`.
-- **Push your schema — REQUIRED before any write works.** The server keeps its OWN copy of the schema. After you create or edit `ablo/schema.ts`, run `npx ablo push` (one-shot) — or `npx ablo dev --no-watch`. **Skip this and every write to a new or changed model fails with `server_execute_unknown_model`.** (Plain `ablo dev` watches forever — never run it bare in an agent.)
-- **Other long-running:** `npx ablo logs --no-follow` (default tails forever). `npx ablo mode test|live` ALWAYS pass the argument. `status`, `push`, `pull`, `check`, `generate`, `docs` are one-shot — safe as-is.
+- **Prepare a branch and push your schema — REQUIRED before any write works.** The server keeps its OWN copy of the schema. After you create or edit `ablo/schema.ts`, run `npx ablo dev --no-watch --branch <git-or-ci-ref>`: it ensures an isolated branch, mints a temporary branch credential, writes it to gitignored `.env.local`, pushes once, and exits. **Skip this and every write to a new or changed model fails with `server_execute_unknown_model`.** Plain `ablo dev` watches forever — never run it bare in an agent. `ablo push` is the lower-level one-shot command for an already selected key, including reviewed production deploys.
+- **Other long-running:** `npx ablo logs --no-follow` (default tails forever). `status`, `branch check`, `push`, `pull`, `check`, `generate`, `docs`, and `dev --no-watch` are one-shot.
 
 When you use the signed-endpoint fallback, the generated `ablo/data-source.ts` is the whole endpoint and needs no hand-editing: `dataSourceNext({ schema, apiKey, adapter: prismaDataSource(prisma, schema) })` (or `drizzleDataSource(db, schema)`). The adapter owns commit / idempotency / outbox.
 

package/CHANGELOG.md

@@ -1,5 +1,147 @@
 # Changelog
 
+## 0.39.0
+
+### Schema-relative session grants
+
+`mintUserSessionKey` accepts `activeSchemaOperations` in place of `operations`.
+Send the verbs a session needs, such as `['read', 'create', 'update',
+'delete']`, and the server resolves them against the models in that session's
+active schema. A backend that mints sessions for organizations whose schemas it
+does not own no longer has to enumerate models it has no way to know.
+
+Calls that pass `operations` are unchanged. A request carries one form or the
+other, and the SDK rejects a call carrying both or neither before the round
+trip. What the session ends up holding is the same concrete `model.verb`
+allowlist either way, so nothing about enforcement changes. A verb is granted
+only where the model accepts it, which leaves an immutable model with reads
+alone. An organization that has not pushed a schema yet is told to push one
+rather than issued a key, since a grant that resolves to nothing would widen
+rather than narrow what the session can reach.
+
+### A named error for models outside your schema
+
+Reaching for a model that your schema projection leaves out now fails with a
+named `model_not_in_schema` error at the point of access, rather than
+surfacing later as a property that happens to be undefined.
+
+### Declared premises serialize against concurrent writers
+
+A commit that declares row premises now serializes those rows against
+concurrent commits, not only the rows it writes. Two commits that read the
+same rows and wrote different ones could previously both pass validation in a
+narrow window. The later commit now observes the earlier one and is rejected
+as stale, so a functional update re-reads and re-runs instead of committing on
+outdated reads.
+
+### Faster, atomic live updates
+
+The client applies an incoming batch of changes as one action, so reactive
+observers see the whole batch or none of it, never a half-applied batch. The
+apply path does substantially less work per change, the final partial batch of
+a burst materializes after 10 ms rather than 100 ms, and the client no longer
+assembles debug payloads it discards.
+
+## 0.38.0
+
+### Branch-isolated development
+
+Ablo branches replace the former shared Sandbox mode. Every project has a
+protected Production root and can have multiple isolated development, preview,
+test, or long-lived branches. Credentials are bound to immutable branch
+identities, so changing a slug or request parameter cannot redirect a write.
+
+`npx ablo dev` now discovers the current Git or CI branch, ensures the matching
+Ablo branch, mints an expiring branch credential, writes it to the gitignored
+local environment, pushes the schema, and watches for changes. Use
+`npx ablo dev --no-watch --branch <name>` for a one-shot agent or CI setup.
+
+The CLI also provides `ablo branch list`, `create`, `ensure`, `status`, `check`,
+`credential`, and `delete`. The public HTTP and OpenAPI contracts expose the
+same lifecycle for other languages and deployment systems.
+
+This release removes the CLI mode switch and the dashboard Sandbox surface.
+Production remains the protected root; a development credential cannot select
+another branch or gain production authority.
+
+Source adapters and PostgreSQL footprint helpers now select immutable branches.
+If you construct `FootprintPlane` or `SourceRequestContext`, replace
+`environment`, `mode`, and `sandboxId` with `branchId`.
+
+### Temporal and Inngest integration guides
+
+New runnable examples and documentation show how Temporal and Inngest
+workflows use Ablo without introducing another authority path. Temporal
+activities and Inngest steps create the Ablo client, perform authoritative
+reads, acquire claims for long-running work, and submit idempotent writes
+through the same transaction API as every other caller.
+
+The integrations keep each product in its proper role: Temporal and Inngest
+own durable execution, scheduling, retries, and workflow history; Ablo owns
+shared-data authority, claims, conflicts, idempotency, settlement, and ordered
+observation. Workflow code does not open WebSockets or hold live client state.
+
+### Database adapter foundation, starting with PostgreSQL
+
+Customer-database adapters now declare their database, ORM binding, and
+observation strategy as separate axes. The existing Prisma, Drizzle, and Kysely
+integrations are accurately identified as PostgreSQL bindings using either a
+transactional outbox or PostgreSQL WAL.
+
+All built-in adapters are constructed through one validating factory and the
+shared conformance suite checks that the three axes are present. Impossible
+capability combinations fail during adapter construction instead of silently
+advertising guarantees the database path cannot provide.
+
+PostgreSQL is the first database profile on this axis. The contract leaves room
+for additional databases without pretending their transaction, observation,
+and change-capture guarantees are interchangeable with PostgreSQL.
+
+### Generated language SDK foundation
+
+The HTTP API is now explicitly treated as Ablo's language-neutral product
+boundary. Its OpenAPI artifact follows the current Ablo version and every
+operation has a stable, unique name suitable for deterministic Python and Go
+generation.
+
+The OpenAPI generator and drift check are restored as repository and CI gates.
+Future language clients will generate their transport, wire models, and error
+decoding from this contract, retaining handwritten code only for thin
+language-idiomatic resource and claim façades.
+
+The artifact now names shared claim, receipt, cursor, page, and error schemas;
+references the canonical error envelope from every operation; publishes typed
+pagination parameters and explicit union discriminators; and normalizes Zod's
+JSON Schema output to the portable subset accepted by the Python and Go
+generator candidates. CI also validates the rendered OpenAPI 3.1 document with
+an independent, pinned Redocly CLI.
+
+### AI SDK tools over the transaction API
+
+`@abloatai/ablo/ai-sdk` now exposes small tool adapters for authoritative
+reads, idempotent creates, concurrency-safe updates, and claimed deletes. These
+helpers use the caller's existing typed Ablo model resource; they do not add an
+agent runtime or a second transport.
+
+The public surface follows the model verbs directly: `readTool`, `createTool`,
+`updateTool`, and `deleteTool`. AI SDK metadata and approval policy pass through
+to each tool, destructive tools require approval by default, and cancellation
+stops queued claim acquisition.
+
+This deliberately replaces the previously published `coordinatedTool` naming:
+use `updateTool`, `UpdateToolModel`, `UpdateToolOptions`, `UpdateToolResult`,
+`UpdateStrategy`, and the `status` result field. The former
+`coordinatedTool`, `CoordinatedModel`, `CoordinatedToolOptions`,
+`CoordinatedWriteResult`, and `CoordinationStrategy` exports are removed rather
+than retained as legacy aliases.
+
+Queued tool writes now use Ablo's server-owned FIFO claim queue rather than
+recreating coordination with client-side polling.
+
+Internal job dispatch, concrete worker tools, prompts, sandboxes, and model
+selection remain application concerns and are not part of the public Ablo
+agent surface.
+
 ## 0.37.1
 
 ### A clearer introduction to Ablo
@@ -64,16 +206,3 @@ Use `authEndpoint` for the browser credential endpoint. The supported routes
 are `/v1/ephemeral_keys` and `/v1/capabilities`; the former `apiKey` endpoint
 option and legacy route aliases are removed. Credential callbacks now use the
 `CredentialProvider` type.
-
-### Verified throughput without dropping coordination guarantees
-
-The strict AWS benchmark sustained more than 10,000 committed operations per
-second across create, mixed-create, update, and delete workloads, with zero
-write errors and sub-second publication drain.
-
-The result covers the documented single-plane, 12-client, 500-operation test
-topology. Atomic commits, authorization, idempotency, conflict handling, audit
-delivery, ordered observation, replay, and authoritative confirmation remained
-enabled throughout the run.
-
-Release notes are generated from the repository changesets.

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Coordination infrastructure for humans, agents, and backend systems.</strong>
+  <strong>The transaction layer for AI agents.</strong>
 </p>
 
 <p align="center">
@@ -22,28 +22,56 @@
 
 ---
 
-Ablo is a TypeScript framework and API for applications where AI agents,
-people, and backend services work on the same data. It provides typed reads and
-writes, claims, safe retries, authoritative confirmation, live updates, and
-attribution while your Postgres remains the source of truth.
+Safely coordinate AI agents, humans, workflows, and services writing to the
+same database.
 
-The SDK is backed by a pure HTTP transaction API, so Ablo works in agents,
-servers, jobs, command-line tools, and interactive applications without
-requiring a browser or reactive client.
+Ablo is an authoritative transaction layer for shared application state. Every
+write goes through one typed API where authority, idempotency, conflicts,
+ordering, and confirmation can be enforced. Your Postgres remains the source
+of truth.
 
 ## Why Ablo
 
-Humans coordinate shared work naturally. We see that somebody is editing,
-agree on who takes which part, wait our turn, and look again before continuing.
+Software used to have one writer: a human clicking through an application. AI
+applications now have humans, agents, workflows, and services acting
+concurrently. Databases keep transactions consistent. They do not coordinate
+autonomous work that reads now, reasons for thirty seconds, and writes later.
 
-Agents do not have that awareness. Two agents can read the same row, think for
-thirty seconds, and overwrite each other. An agent can act on information that
-changed while it was reasoning without causing a database conflict at all.
+Humans handle this naturally. We see that somebody is editing, agree on who
+takes which part, wait our turn, and look again before continuing. Ablo gives
+software actors those same capabilities: bounded authority, shared ownership,
+fresh context, safe handoffs, and an attributed record of what happened.
 
-Ablo gives agents the same practical capabilities humans rely on: see who is
-working, claim a row or field, wait fairly, receive fresh state, prove what
-they may do, and leave an attributed record. Humans and backend services use
-the same rules, so there is no separate agent write path.
+## Start
+
+```sh
+npm install @abloatai/ablo
+npx ablo init
+npx ablo dev
+```
+
+`ablo dev` prepares an isolated Ablo branch for your Git branch, writes its
+temporary credential to gitignored `.env.local`, pushes the schema, and watches
+for changes.
+
+Read and write through the transaction layer:
+
+```ts
+const order = await ablo.orders.get({ id: orderId });
+
+if (!order) throw new Error('Order not found');
+await ablo.orders.update({
+  id: order.id,
+  data: { status: 'approved' },
+  wait: 'confirmed',
+});
+```
+
+`confirmed` means the authoritative database reported the change back. The
+same commit can be retried safely if the caller loses its connection.
+
+When work takes thirty seconds instead of one request, coordinate before the
+agent starts reasoning:
 
 ```ts
 await using claim = await ablo.orders.claim({ id: orderId });
@@ -51,33 +79,42 @@ await using claim = await ablo.orders.claim({ id: orderId });
 const priced = await pricingAgent(claim.data);
 
 await ablo.orders.update({
-  id: orderId,
+  id: claim.data.id,
   data: { total: priced.total, status: 'repriced' },
   claim,
   wait: 'confirmed',
 });
 ```
 
-The claim releases automatically. Overlapping work takes turns, stale work is
-rejected, retries are safe, and `confirmed` means the authoritative database
-reported the change back.
+Another actor touching the same work waits fairly and receives fresh state when
+its turn begins. If the agent fails, the claim releases automatically. If its
+context became stale, the write is rejected instead of silently overwriting
+work it never saw.
 
-## Start
+If you use AI SDK, expose the same operation as a typed model tool:
 
-```sh
-npm install @abloatai/ablo
-npx ablo init
-npx ablo push
+```ts
+import { updateTool } from '@abloatai/ablo/ai-sdk';
+
+const approveOrder = updateTool(ablo.orders, {
+  description: 'Approve an order after reviewing it.',
+  inputSchema: z.object({ orderId: z.string() }),
+  id: ({ orderId }) => orderId,
+  apply: () => ({ status: 'approved' }),
+});
 ```
 
+Ablo supplies `readTool`, `createTool`, `updateTool`, and `deleteTool` over the
+same authoritative resources. AI SDK keeps ownership of the model loop and tool
+execution.
+
 Use `@abloatai/ablo` for agents and backend code,
 `@abloatai/ablo/client` for live applications, and
 `@abloatai/ablo/react` for React. All entrypoints share the same schema,
 authority, commits, claims, and ordered changes.
 
-Read the [Quickstart](./docs/quickstart.md), browse
+Read the [Quickstart](https://docs.abloatai.com/quickstart), browse
 [docs.abloatai.com](https://docs.abloatai.com), or run `npx ablo docs`.
-Coding agents can read `node_modules/@abloatai/ablo/llms.txt`.
 
 ## Contributing
 

package/dist/ai-sdk.d.ts

@@ -0,0 +1,2 @@
+export * from '@abloatai/transaction/ai-sdk';
+//# sourceMappingURL=ai-sdk.d.ts.map

package/dist/ai-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk.d.ts","sourceRoot":"","sources":["../src/ai-sdk.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC"}

package/dist/ai-sdk.js

@@ -0,0 +1,2 @@
+export * from '@abloatai/transaction/ai-sdk';
+//# sourceMappingURL=ai-sdk.js.map

package/dist/ai-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-sdk.js","sourceRoot":"","sources":["../src/ai-sdk.ts"],"names":[],"mappings":"AAAA,cAAc,8BAA8B,CAAC"}

package/docs/agents.md

@@ -6,7 +6,7 @@ An agent is a **reactive** participant: it wakes on something happening, reads
 what it needs, writes a result, and goes idle. That's a request/response
 workload — so agents talk to Ablo over **plain HTTP**, holding no WebSocket. The
 credential *is* the identity; the server resolves the org, scope, and actor from
-the key on every request (the Stripe server-SDK / Liveblocks-node shape).
+the key on every request.
 
 Agents get the stateless plane (HTTP). People — when you add the `humans()`
 plugin — get the live plane (WebSocket: presence, optimistic, sub-100ms).
@@ -31,7 +31,7 @@ import { schema } from "./schema";
 const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY, transport: "http" });
 
 // Reads + writes, fully typed off your schema.
-// `retrieve` resolves to the row, or `undefined` when none matches.
+// `get` resolves to the row, or `undefined` when none matches.
 const open = await ablo.tasks.list({ where: { status: "todo" } });
 
 const task = await ablo.tasks.get({ id: open[0].id });
@@ -41,11 +41,57 @@ console.log(task.title);
 await ablo.tasks.update({ id: task.id, data: { status: "done" } });
 ```
 
-It exposes `retrieve` / `list` / `create` / `update` / `delete`, plus `commits`
-and `claim`. It does **not** expose the stateful-only surface (`get` /
-`local` reads, `onChange` live subscription) — those need a
-live connection, so with `transport: 'http'` the return type narrows and they
-are a *compile error*, not a runtime surprise.
+It exposes `get` / `list` / `create` / `update` / `delete`, plus `commits`
+and `claim`. It does **not** expose stateful-only `local` reads or `onChange`
+subscriptions. Those need a live connection, so with `transport: 'http'` they
+are compile errors rather than runtime surprises.
+
+## AI SDK tools
+
+Keep AI SDK in charge of the model loop and expose only the Ablo operations the
+model needs:
+
+```ts
+import { generateText } from 'ai';
+import {
+  createTool,
+  deleteTool,
+  readTool,
+  updateTool,
+} from '@abloatai/ablo/ai-sdk';
+
+const tools = {
+  getTask: readTool(ablo.tasks, {
+    description: 'Read the current task.',
+    inputSchema: z.object({ taskId: z.string() }),
+    id: ({ taskId }) => taskId,
+  }),
+  createTask: createTool(ablo.tasks, {
+    description: 'Create a task.',
+    inputSchema: z.object({ requestId: z.string(), title: z.string() }),
+    id: ({ requestId }) => requestId,
+    data: ({ title }) => ({ title, status: 'todo' }),
+  }),
+  updateTask: updateTool(ablo.tasks, {
+    description: 'Update a task without overwriting concurrent work.',
+    inputSchema: z.object({ taskId: z.string(), status: z.string() }),
+    id: ({ taskId }) => taskId,
+    apply: (_current, { status }) => ({ status }),
+  }),
+  deleteTask: deleteTool(ablo.tasks, {
+    description: 'Delete a task after taking its claim.',
+    inputSchema: z.object({ taskId: z.string() }),
+    id: ({ taskId }) => taskId,
+    // Destructive tools require AI SDK approval by default.
+  }),
+};
+
+await generateText({ model, messages, tools });
+```
+
+These are adapters over the same typed resources used by ordinary backend
+code. Ablo does not own the planner, prompt system, memory, provider, worker,
+or workflow runtime.
 
 ## Coordination: claim, queue, reorder
 
@@ -59,7 +105,11 @@ clobber the same record.
 await using claim = await ablo.tasks.claim({ id: taskId });
 const task = claim.data;
 // …no one else can hold this row while you work…
-await ablo.tasks.update({ id: task.id, data: { status: "in_review" } });
+await ablo.tasks.update({
+  id: task.id,
+  data: { status: "in_review" },
+  claim,
+});
 
 await ablo.tasks.claim.state({ id: taskId });   // who holds it now (or null)
 await ablo.tasks.claim.queue({ id: taskId });   // the FIFO wait-line behind the holder
@@ -111,5 +161,5 @@ agents costs nothing on the live plane — that capacity stays for humans.
 `onChange` (live subscriptions) and the `local` reads (local synced-pool
 reads) require a WebSocket and a local store — they're for interactive UIs, not
 stateless agents. An agent reacts to an external trigger (a job/queue/webhook),
-then reads with `list`/`retrieve`. See [client behavior](/client-behavior) for
+then reads with `list`/`get`. See [client behavior](/client-behavior) for
 the full surface and [guarantees](/guarantees) for the coordination semantics.

package/docs/api-keys.md

@@ -27,6 +27,11 @@ Pick your row:
 
 That's the whole story: one knob, filled by audience.
 
+The `mk_` credential created by `ablo login` is different: it is a CLI
+control-plane credential, not an application API key. It can manage projects
+and branches and exchange for a branch-bound runtime key. Do not pass it to
+`Ablo(...)` or put it in `ABLO_API_KEY`.
+
 **Coming from Stripe? It's the same key model, same prefixes:**
 
 | Stripe | Ablo | Where it goes |
@@ -36,7 +41,14 @@ That's the whole story: one knob, filled by audience.
 | restricted `rk_` (granular) | `rk_` | scoped agents (`agents.create({ can })`) |
 | ephemeral key (client, customer-scoped) | `ek_` | per-user browser sessions (`sessions.create({ user, can })`) |
 
-Mode lives in the prefix too — `sk_test_` / `sk_live_` — exactly like Stripe. The
+Ablo also has one credential class that Stripe does not need:
+
+| Prefix | Purpose | Mode | Stored where |
+|---|---|---|---|
+| `mk_` | project and branch management | none | CLI credential store or `ABLO_MANAGEMENT_KEY` |
+
+Trust class lives in the prefix too — `sk_test_` / `sk_live_` — exactly like Stripe.
+It does not select a branch; the immutable server-side binding does that. The
 `apiKey` resolver fetching an `ek_` is Ablo's ephemeral-key flow: server mints, client holds.
 
 **Why a function for browser writes?** Anything you ship to a browser must be public, and a
@@ -91,21 +103,28 @@ cannot reach any control-plane operation. The moment the browser needs to write
 on a specific user's behalf, mint a short-lived `ek_` user session from your
 backend instead (see the Sessions guide).
 
-## Sandboxes and production
+## Branches and production
 
-Test and live keys are the same shape; the prefix names the environment:
+A branch is your project at full strength over its own rows: the same models,
+the same schema, the same claims and the same rules production runs.
 
-- `sk_test_…` — a key bound to a **sandbox**. Its reads and writes are isolated
-  to that sandbox and are invisible to live keys (and to other sandboxes).
+Production is the project's root branch. Development branches are isolated
+children, and a key's immutable branch binding decides which rows, schema,
+claims, and log it can reach:
+
+- `sk_test_…` — a key bound to a development branch. Its reads and
+  writes are invisible to production and to other branches.
 - `sk_live_…` — a key against your live data.
 
-Every org has a default sandbox, plus any number of additional
-sandboxes you create. **Data is isolated per sandbox; 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 — how Stripe separates sandbox and production data while keeping
-the API shape identical. A schema change reaches production when you push it
-with a live key ([Deployment](./deployment.md)).
+`npx ablo dev` derives a branch from Git, ensures the matching child, and mints
+an expiring `sk_test_` key for it. The credential carries the immutable branch
+id; changing a slug in a request cannot change its authority. A child receives
+the parent's active schema when it is created and owns its artifact after that.
+A schema change reaches production only through the reviewed live-key path in
+[Deployment](./deployment.md).
+
+The shared default sandbox is no longer part of the development workflow.
+Branch identity is required for newly provisioned CLI and runtime credentials.
 
 ## Scopes
 
@@ -114,25 +133,30 @@ only what its job needs. A secret key with **no scopes** has full org authority
 (the default for a `sk_live_` backend key); a key with a non-empty scope set is
 restricted to exactly those grants:
 
-- `schema:push` — author the org schema (`ablo schema push`, `ablo dev`). A
-  high-risk, org-wide grant: because schema is shared, a push affects the live
-  table shape. A full-authority key has it implicitly; a *restricted* key (such
-  as a sandbox key) needs it granted explicitly.
-- `sandbox:<id>` — identifies which sandbox the key belongs to. (The key's data
-  isolation comes from that sandbox binding, not from this scope string.)
+- `schema:push` — author the schema artifact on the key's bound plane
+  (`ablo push`, `ablo dev`). A production push is high-risk because it changes
+  the live contract; a child push remains inside that branch. A
+  full-authority key has it implicitly; a restricted key needs it explicitly.
+- `project:manage` — list, create, and rename projects.
+- `branch:manage` — list, create, and delete child branches and mint their
+  temporary credentials.
+
+Both management scopes are explicit grants on `mk_` credentials. Runtime
+`sk_`, `rk_`, `pk_`, and `ek_` credentials cannot become management
+credentials through an empty scope set or a CLI fallback.
 
-A key minted from the default sandbox carries `schema:push`, so
-`ablo dev` works out of the box. Keys from other sandboxes are **data-only** by
-default — enable "schema authoring" when minting if you want that key to push
-schema too. Hand data-only keys to embedded apps and CI agents; reserve
-schema-authoring keys for the developer running `ablo dev`.
+Branch binding remains an authority boundary even when a key has no granular
+scope strings: a temporary child key can act only inside that child. It cannot
+manage siblings or gain root authority.
 
 ### `ablo dev`
 
 ```sh
-ABLO_API_KEY=sk_test_… npx ablo dev
+npx ablo login
+npx ablo dev
 ```
 
-Pushes your `ablo/schema.ts` to the test sandbox, prints the one line you need
-in `.env.local`, and re-pushes on every save. It refuses `sk_live_` keys so a
-tight save loop can never churn production data.
+The stored `mk_` project credential is used only to ensure the Git-derived child and
+mint an expiring branch credential. `dev` writes that temporary key to
+gitignored `.env.local`, pushes `ablo/schema.ts` to the child, and re-pushes on
+every save. See [Branch-first development](./branch-development.md).