@abloatai/ablo 0.37.1 → 0.38.0

package/docs/branch-development.md

@@ -0,0 +1,392 @@
+# Branch-first development
+
+> Understand exactly what `ablo dev` prepares, what it watches, and how each Git branch gets an isolated Ablo schema and credential.
+
+`ablo dev` is Ablo's schema-development loop. It prepares an isolated Ablo
+branch for the Git branch you are working on, gives your local application a
+short-lived credential for that branch, pushes the schema, and keeps the schema
+registered as you edit it.
+
+It does **not** start your application or run database migrations.
+
+The everyday setup is two terminals:
+
+```bash
+# Terminal 1: your application
+npm run dev
+
+# Terminal 2: Ablo's schema loop
+npx ablo dev
+```
+
+## The mental model
+
+```text
+Git branch
+    │
+    │  npx ablo dev
+    ▼
+Ablo branch
+    ├── active schema artifact
+    ├── isolated transaction plane
+    ├── immutable branch id
+    └── expiring sk_test_ credential
+              │
+              ▼
+        gitignored .env.local
+              │
+              ▼
+       your local application
+```
+
+A branch name is a human handle. The credential carries the immutable Ablo
+branch id, so application requests cannot switch branches by changing a slug or
+request parameter.
+
+Production is the root branch. Development branches are children; they do not
+inherit production write authority.
+
+## Before the first run
+
+Initialize the project and sign in:
+
+```bash
+npx ablo init
+npx ablo login
+```
+
+Login stores one project-scoped `mk_` management credential. It has no
+production/test mode and no application-data authority. It can manage projects
+and branches and exchange for an expiring credential bound to one branch.
+
+If you switch projects, log in for the selected project before running `dev`:
+
+```bash
+npx ablo projects use orders
+npx ablo login --project orders
+```
+
+## What happens when you run it
+
+Given:
+
+```bash
+git switch -c feature/order-approval
+npx ablo dev
+```
+
+Ablo performs these steps.
+
+### 1. Discover the branch
+
+The first available source wins:
+
+1. `--branch <name>`
+2. `ABLO_BRANCH`
+3. GitHub's `GITHUB_HEAD_REF` or `GITHUB_REF_NAME`
+4. Vercel's `VERCEL_GIT_COMMIT_REF`
+5. GitLab's `CI_COMMIT_REF_NAME`
+6. the current local Git branch
+
+The reference is normalized into a lowercase plane-safe slug:
+
+```text
+feature/order-approval  →  feature-order-approval
+Feature: Billing V2     →  feature-billing-v2
+```
+
+Long names are shortened with a stable hash, so the same Git branch resolves to
+the same Ablo branch on every machine.
+
+### 2. Ensure the Ablo branch
+
+The CLI lists branches for the active project and reuses one with the same slug.
+If none exists, it creates a child of the project's production root.
+
+Creation is idempotent: two CI jobs racing to ensure the same branch converge on
+the same server record.
+
+At creation, the child receives its own copy of the parent's active schema.
+Later production schema pushes do not silently change an in-flight feature
+branch.
+
+### 3. Exchange for a temporary credential
+
+The stored `mk_` credential authorizes the branch-management call. The server then
+returns a new `sk_test_` credential bound only to the child branch.
+
+The default lifetime is eight hours:
+
+```bash
+npx ablo dev --branch-ttl-hours 12
+```
+
+Allowed values are 1–168 hours. Rerunning `ablo dev` mints a fresh credential.
+This lifetime belongs to the credential, not the branch. The branch persists
+until `ablo branch delete` or preview automation removes it.
+
+Temporary branch credentials can read, write, and push schema on their own
+branch. They cannot create or delete siblings, mint sibling credentials, or
+obtain production authority.
+
+### 4. Wire the local application
+
+The temporary credential is written to:
+
+```dotenv
+# .env.local
+ABLO_API_KEY=sk_test_...
+```
+
+The CLI creates `.env.local` with owner-only permissions when possible and adds
+it to `.gitignore` if it is not already ignored. The key is not added to Ablo's
+long-lived credential store.
+
+Most application frameworks load `.env.local` automatically. Plain Node can
+load it explicitly:
+
+```bash
+node --env-file=.env.local app.ts
+```
+
+An `ABLO_API_KEY` exported in your shell overrides `.env.local` for child
+processes. `ablo dev` warns when it detects that mismatch. Unset the exported
+value before starting the application:
+
+```bash
+unset ABLO_API_KEY
+npm run dev
+```
+
+### 5. Load and push the schema
+
+By default, the CLI imports:
+
+```text
+ablo/schema.ts
+```
+
+and reads its `schema` export. Override either:
+
+```bash
+npx ablo dev \
+  --schema src/ablo-schema.ts \
+  --export appSchema
+```
+
+The schema is serialized and uploaded to the selected branch. The server
+compares it with that branch's active artifact and returns either:
+
+- unchanged, with the current version;
+- activated, with a new version and hash; or
+- rejected, with the incompatible changes and the required next action.
+
+`push` registers a contract. It does not execute DDL.
+
+### 6. Watch for edits
+
+After the first successful push, `ablo dev` watches the schema module. Editor
+write/rename bursts are debounced into one reload and one push.
+
+Stop it with `Ctrl-C`.
+
+For a single branch preparation and push:
+
+```bash
+npx ablo dev --no-watch
+```
+
+## Command reference
+
+```bash
+# Discover from Git and watch
+npx ablo dev
+
+# Choose the branch explicitly
+npx ablo dev --branch preview-pr-482
+
+# Push once
+npx ablo dev --no-watch
+
+# Change the temporary-key lifetime
+npx ablo dev --branch-ttl-hours 24
+
+# Use another schema module/export
+npx ablo dev --schema db/ablo.ts --export schema
+
+```
+
+Lower-level branch operations are also available:
+
+```bash
+npx ablo branch list
+npx ablo branch status feature-orders
+npx ablo branch check feature-orders
+npx ablo branch create feature-orders
+npx ablo branch ensure preview-pr-482 --credential --ttl-hours 168 --json
+npx ablo branch credential br_... --ttl-hours 8
+npx ablo branch delete br_...
+```
+
+Automation should retain immutable ids returned by the API. Slugs are for
+people and discovery.
+
+`branch status` and `branch check` are aliases. They show lifecycle state, the
+active schema and hash, compatibility with the parent schema, the bound
+database's safe coordinates, and an exact readiness fix.
+
+## CI and preview deployments
+
+For a one-shot CI schema check:
+
+```bash
+# Store the project management credential as the masked secret.
+ABLO_MANAGEMENT_KEY="mk_..." \
+ABLO_BRANCH="preview-pr-${PR_NUMBER}" \
+  npx ablo dev --no-watch
+```
+
+For infrastructure that needs the credential response directly:
+
+```bash
+npx ablo branch ensure "preview-pr-${PR_NUMBER}" \
+  --kind preview \
+  --credential \
+  --ttl-hours 168 \
+  --json
+```
+
+`--credential` explicitly requests plaintext secret material. Treat the JSON
+result as a secret, mask it in logs, and pass it through the deployment
+provider's secret-variable mechanism.
+
+Closing a preview should call `branch delete`. Deletion immediately makes
+branch-bound credentials fail authentication even if their expiry is later.
+
+## Managing branches in Sync Web
+
+The persistent dashboard header selects a project and then one branch inside it. The
+selection scopes API keys, Schema, Audit log, and Server log. Production is the
+protected root; every other item is a named development branch.
+
+Use the **Branches** page to create, select, inspect, or delete a branch.
+Deleting a child revokes all of its credentials first, removes its datasource
+connection material, and then removes it from discovery. It never deletes a
+sibling, the production root, customer tables, or retained schema history.
+
+See [Ablo branch lifecycle](../../../docs/explainers/branch-lifecycle.md) for
+the complete project/branch mental model and dashboard journey.
+
+## Your database and migrations
+
+There are two independent contracts:
+
+```text
+Your ORM/migration tool     owns tables, columns, relations, and DDL
+Ablo schema                 owns the coordination contract for synced models
+```
+
+`ablo dev` currently isolates the Ablo branch and schema. It does not:
+
+- run Prisma, Drizzle, or SQL migrations;
+- create a Neon/Supabase/RDS database branch;
+- copy production data;
+- automatically register whichever `DATABASE_URL` happens to be present.
+
+The last point is a safety boundary. A generic `DATABASE_URL` does not prove
+that the database is an isolated feature branch; automatically registering it
+could bind a development credential to production.
+
+Until provider-verified database-branch binding lands, use Ablo's hosted branch
+plane for the inner loop or explicitly prepare and review an isolated database
+through [Connect Your Database](./data-sources.md). Never point a child branch at
+production merely because its migrations are compatible.
+
+## Production rollout
+
+There is intentionally no `branch merge` that promotes child rows or logs.
+
+Production rollout remains:
+
+1. Merge code and migration files through Git.
+2. Run the reviewed migration against the production database.
+3. Push the production/root Ablo schema through the deployment workflow.
+4. Deploy the application.
+
+The feature branch proves the change. It does not become production.
+
+## Troubleshooting
+
+### “Creating a development branch needs the active project CLI key”
+
+Run:
+
+```bash
+npx ablo login
+```
+
+For a non-default project:
+
+```bash
+npx ablo login --project <project>
+```
+
+If `ABLO_API_KEY` is exported, it overrides the stored login key. Unset it when
+you want the CLI to use the active project's stored profile.
+
+### “Branch credentials cannot manage branches”
+
+You supplied a temporary child credential to a management command. Branch
+runtime credentials are deliberately leaf authority. Unset the override and let
+the CLI use the project login key.
+
+### Check the whole branch
+
+```bash
+npx ablo branch check feature-order-approval
+```
+
+The result distinguishes a missing schema, a branch lifecycle failure, and an
+unready connected database. A hosted branch is a valid development state and
+is reported explicitly rather than as a missing database.
+
+### The app still reaches another plane
+
+Check for an exported variable:
+
+```bash
+env | grep '^ABLO_API_KEY='
+```
+
+An exported value wins over `.env.local`. Unset it and restart the application
+process so the framework reloads `.env.local`.
+
+### `server_execute_unknown_model`
+
+The active branch does not have the schema containing that model. Keep
+`ablo dev` running, or push once:
+
+```bash
+npx ablo dev --no-watch
+```
+
+Confirm that `--schema` and `--export` point at the module your application
+uses.
+
+### Git branch discovery fails
+
+Detached checkouts may not expose a local branch. Pass the intended name:
+
+```bash
+npx ablo dev --branch preview-pr-482
+```
+
+or set `ABLO_BRANCH` in CI.
+
+## Related guides
+
+- [Quickstart](./quickstart.md) — install, connect, define a schema, and write.
+- [CLI](./cli.md) — the complete command surface.
+- [Schema Contract](./schema-contract.md) — what the registered schema controls.
+- [Connect Your Database](./data-sources.md) — Postgres roles, WAL, and database ownership.
+- [Deployment](./deployment.md) — production schema rollout.

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]