@abloatai/ablo 0.9.5 → 0.9.7

package/dist/client/Ablo.d.ts

@@ -442,6 +442,15 @@ export interface IntentCreateOptions {
 }
 export interface IntentHandle extends AsyncDisposable {
     readonly id: string;
+    /**
+     * True when the lease was granted AFTER waiting in the server's FIFO
+     * queue behind a holder (`intent_granted`), false/absent for an
+     * immediate grant (`intent_acquired`). Consumers re-read the target
+     * row when this is set — the row may have changed while we queued, and
+     * the local coordination snapshot can't detect that for org-scoped
+     * subscriptions (intent fan-out is entity-scoped).
+     */
+    readonly waited?: boolean;
     release(): Promise<void>;
     revoke(): void;
 }

package/dist/client/Ablo.js

@@ -1238,12 +1238,13 @@ export function Ablo(options) {
         }
         await waitForModelUnclaimed(target, { timeout: options?.claimedTimeout });
     }
-    function wrapIntentHandle(claim) {
+    function wrapIntentHandle(claim, waited = false) {
         const release = async () => {
             claim.revoke();
         };
         return {
             id: claim.id,
+            waited,
             release,
             revoke: claim.revoke,
             [Symbol.asyncDispose]: release,
@@ -1269,14 +1270,15 @@ export function Ablo(options) {
             // we reach the head of the FIFO line). Block here on that grant so
             // callers — chiefly `ablo.<model>.claim` — get a handle that already
             // holds the lease, never a half-claimed one racing the queue.
+            let waited = false;
             if (intentOptions.queue) {
                 const ws = store.getSyncWebSocket();
                 if (ws) {
                     try {
-                        await awaitIntentGrant(ws, claim.id, {
+                        ({ waited } = await awaitIntentGrant(ws, claim.id, {
                             timeoutMs: intentOptions.waitTimeoutMs,
                             maxQueueDepth: intentOptions.maxQueueDepth,
-                        });
+                        }));
                     }
                     catch (err) {
                         // Gave up waiting (queue too deep, timed out, or lost) — abandon
@@ -1287,7 +1289,7 @@ export function Ablo(options) {
                     }
                 }
             }
-            return wrapIntentHandle(claim);
+            return wrapIntentHandle(claim, waited);
         },
         list(target) {
             return listModelClaims(target);

package/dist/client/createModelProxy.d.ts

@@ -75,6 +75,14 @@ export interface ModelLoadOptions<T> {
 export type ModelRetrieveOptions = Pick<ModelLoadOptions<unknown>, 'type' | 'expand'>;
 export interface IntentLeaseHandle {
     readonly id: string;
+    /**
+     * True when the grant came AFTER waiting in the server's FIFO line
+     * (`intent_granted`) — the authoritative "the row may have changed
+     * underneath us" signal. The local `observe()` snapshot can't stand in
+     * for this: intent fan-out is entity-scoped, so org-wide subscriptions
+     * (the default hosted client) never see peers' claims at all.
+     */
+    readonly waited?: boolean;
     release(): Promise<void>;
     revoke(): void;
 }

package/dist/client/createModelProxy.js

@@ -31,6 +31,16 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         throw new AbloValidationError(`Ablo: schema model "${schemaKey}" resolved to "${registeredModelName}", ` +
             'but no matching constructor was registered.', { code: 'model_not_registered' });
     }
+    // The coordination plane (claims/intents) must speak the SAME wire dialect
+    // as the commit plane: the lowercased TYPENAME (`task`), not the schema key
+    // (`tasks`). The server's commit-time intent guard probes the lease store
+    // with the commit op's model name; a lease recorded under the schema key
+    // never collides with it — which silently disarmed the guard for every
+    // model whose schema key differs from its typename (i.e. nearly all of
+    // them, plural key vs singular typename). Public surfaces (ClaimHandle.
+    // target.model) keep the schema key; only the wire/coordination targets
+    // use this.
+    const wireModel = registeredModelName.toLowerCase();
     // Last-line guarantee for the public surface: any rejection from a lower
     // layer (transport timeout, IndexedDB failure, a third-party throw) is
     // coerced to an AbloError before it reaches the consumer. The SDK's
@@ -98,7 +108,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // Is someone ELSE already on this target? Read the local coordination
         // snapshot up front — it decides whether we'll need to re-read after the
         // claim (a free / already-mine target can't have changed under us).
-        const held = collaboration.observe({ model: schemaKey, id });
+        const held = collaboration.observe({ model: wireModel, id });
         const contended = !!held && held.heldBy !== collaboration.selfParticipantId;
         const failFast = options?.wait === false;
         // Fail-fast (`wait: false`): if another participant already holds it,
@@ -113,7 +123,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // Ensure the row exists locally before claiming.
         let model = objectPool.get(id);
         if (!model) {
-            await load({ where: { id } });
+            await load({ where: [['id', id]] });
             model = objectPool.get(id);
         }
         if (!model) {
@@ -126,7 +136,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         // observed conflict above, so this just records our lease.
         const lease = await collaboration.createIntent({
             target: {
-                model: schemaKey,
+                model: wireModel,
                 id,
                 ...(options?.field ? { field: options.field } : {}),
                 ...(options?.path ? { path: options.path } : {}),
@@ -140,9 +150,19 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         });
         // Only when we actually waited behind another holder can the row have
         // changed underneath us — re-read so the claimed snapshot reflects what
-        // they committed before releasing.
-        if (contended && !failFast) {
-            await load({ where: { id } });
+        // they committed before releasing. Two signals, either suffices:
+        //   - `lease.waited` — the server granted via `intent_granted`, i.e. we
+        //     provably queued behind a holder. Authoritative; works even when
+        //     the local snapshot is blind (intent fan-out is entity-scoped, so
+        //     org-wide-subscribed clients never observe peers' claims).
+        //   - `contended` — the local snapshot saw a holder up front. Kept for
+        //     the no-queue paths where no grant frame exists.
+        if ((contended || lease.waited === true) && !failFast) {
+            // `type: 'complete'` forces the round-trip: the hydration ledger
+            // otherwise serves the LOCAL row for an already-hydrated id, and the
+            // holder's final write may not have fanned out to us yet — the exact
+            // stale-snapshot race this re-read exists to close.
+            await load({ where: [['id', id]], type: 'complete' });
             model = objectPool.get(id) ?? model;
         }
         const snapshot = collaboration.createSnapshot(schemaKey, id);
@@ -178,16 +198,16 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
     // are the same object.
     const claimApi = Object.assign(guard(claim), {
         state(params) {
-            return collaboration?.observe({ model: schemaKey, id: params.id }) ?? null;
+            return collaboration?.observe({ model: wireModel, id: params.id }) ?? null;
         },
         queue(params) {
             return {
                 object: 'list',
-                data: collaboration?.queue({ model: schemaKey, id: params.id }) ?? [],
+                data: collaboration?.queue({ model: wireModel, id: params.id }) ?? [],
             };
         },
         reorder(params) {
-            collaboration?.reorder({ model: schemaKey, id: params.id }, params.order);
+            collaboration?.reorder({ model: wireModel, id: params.id }, params.order);
         },
         release: guard((params) => releaseClaim(isClaimHandle(params) ? params.target.id : params.id)),
     });
@@ -195,7 +215,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
         retrieve: guard(async (params) => {
             const rows = await load({
                 ...params,
-                where: { id: params.id },
+                where: [['id', params.id]],
                 limit: 1,
             });
             return rows[0];
@@ -251,7 +271,7 @@ export function createModelProxy(schemaKey, registeredModelName, objectPool, syn
                 }
                 autoLease = await collaboration.createIntent({
                     target: {
-                        model: schemaKey,
+                        model: wireModel,
                         id,
                         ...(claim.field ? { field: claim.field } : {}),
                         ...(claim.path ? { path: claim.path } : {}),

package/dist/errorCodes.js

@@ -142,13 +142,22 @@ export const ERROR_CODES = {
     byo_tenant_tables_unforced_rls: wire('permission', 403, false, 'Tenant tables do not have RLS forced under the direct Postgres connector role.'),
     byo_host_not_allowed: wire('permission', 403, false, 'The direct Postgres connector host resolves to a private, loopback, or link-local address and cannot be used.'),
     // ── claim / intent conflict (409) ──────────────────────────────────
-    claim_conflict: wire('claim', 409, true, 'The target entity is claimed by another participant.'),
-    claim_lost: wire('claim', 409, true, 'A previously held claim was lost before the write applied.'),
-    entity_claimed: wire('claim', 409, true, 'The target entity is currently claimed; write was blocked.'),
-    intent_conflict: wire('claim', 409, true, 'An intent on the target conflicts with an active intent (server-internal alias of claim_conflict).'),
+    // Held-claim rejections are NOT queue-retryable (gRPC FAILED_PRECONDITION /
+    // ABORTED semantics; Replicache/Zero SETTLE a rejected mutation — reject the
+    // caller, roll back the optimistic effect — instead of resending it).
+    // Blindly re-sending the same payload cannot succeed while the lease is
+    // held, and a lease can outlive any sane retry budget. The correct recovery
+    // lives at the CALLER: take a claim (`ablo.<model>.claim` queues fairly
+    // behind the holder) or re-read and rebase. `retryable: true` here turned
+    // every cross-client claim conflict into an infinite client resend loop
+    // (~150ms storm — found by the claims journey, 2026-06-10).
+    claim_conflict: wire('claim', 409, false, 'The target entity is claimed by another participant.'),
+    claim_lost: wire('claim', 409, false, 'A previously held claim was lost before the write applied.'),
+    entity_claimed: wire('claim', 409, false, 'The target entity is currently claimed; write was blocked.'),
+    intent_conflict: wire('claim', 409, false, 'An intent on the target conflicts with an active intent (server-internal alias of claim_conflict).'),
     malformed_claim: wire('claim', 400, false, 'The claim payload was malformed.'),
-    model_claimed: wire('claim', 409, true, 'The model instance is claimed by another participant.'),
-    model_claimed_timeout: wire('claim', 409, true, 'Timed out waiting for a model claim to clear.'),
+    model_claimed: wire('claim', 409, false, 'The model instance is claimed by another participant.'),
+    model_claimed_timeout: wire('claim', 409, false, 'Timed out waiting for a model claim to clear.'),
     model_claim_not_configured: client('claim', 'Claiming was requested on a model that has no claim configuration.'),
     // ── stale context / idempotency (409) ──────────────────────────────
     stale_context: wire('conflict', 409, true, 'The write carried a readAt watermark that is now stale; re-read and retry.'),

package/dist/sync/SyncWebSocket.d.ts

@@ -385,6 +385,19 @@ export declare class SyncWebSocket<TCollaboration extends EventMap<TCollaboratio
      * Setup WebSocket event handlers
      */
     private setupEventHandlers;
+    /**
+     * Normalize a wire delta at the receive boundary. The contract
+     * (`syncDeltaWireCoreSchema`) says `id: number`, but deployed servers
+     * have sent the raw Postgres BIGINT serialization — a STRING — and
+     * every downstream watermark gate (`typeof syncId === 'number'` in
+     * `Database.processDeltaBatch`, the metadata-cursor update, numeric
+     * `>=` threshold comparisons in TransactionQueue) silently breaks on
+     * strings: acks are withheld, the resume cursor never advances, and
+     * every reconnect replays from 0 (or force-bootstraps once the gap
+     * exceeds maxDeltaGapForPartial). Coerce ONCE here so the rest of the
+     * client can trust the declared type — and old servers stay compatible.
+     */
+    private normalizeWireDelta;
     /**
      * Handle incoming sync delta
      */

package/dist/sync/SyncWebSocket.js

@@ -318,8 +318,11 @@ export class SyncWebSocket extends EventEmitter {
                         clearTimeout(pending.timeout);
                         this.pendingMutations.delete(clientTxId);
                         if (success) {
+                            // Coerce defensively — bigint columns serialize as strings
+                            // from older servers (see normalizeWireDelta).
+                            const ackedSyncId = Number(lastSyncId);
                             pending.resolve({
-                                lastSyncId: typeof lastSyncId === 'number' ? lastSyncId : 0,
+                                lastSyncId: Number.isFinite(ackedSyncId) ? ackedSyncId : 0,
                             });
                         }
                         else {
@@ -631,10 +634,29 @@ export class SyncWebSocket extends EventEmitter {
             }
         };
     }
+    /**
+     * Normalize a wire delta at the receive boundary. The contract
+     * (`syncDeltaWireCoreSchema`) says `id: number`, but deployed servers
+     * have sent the raw Postgres BIGINT serialization — a STRING — and
+     * every downstream watermark gate (`typeof syncId === 'number'` in
+     * `Database.processDeltaBatch`, the metadata-cursor update, numeric
+     * `>=` threshold comparisons in TransactionQueue) silently breaks on
+     * strings: acks are withheld, the resume cursor never advances, and
+     * every reconnect replays from 0 (or force-bootstraps once the gap
+     * exceeds maxDeltaGapForPartial). Coerce ONCE here so the rest of the
+     * client can trust the declared type — and old servers stay compatible.
+     */
+    normalizeWireDelta(delta) {
+        if (typeof delta.id === 'number')
+            return delta;
+        const coerced = Number(delta.id);
+        return { ...delta, id: Number.isFinite(coerced) ? coerced : 0 };
+    }
     /**
      * Handle incoming sync delta
      */
-    handleDelta(delta) {
+    handleDelta(rawDelta) {
+        const delta = this.normalizeWireDelta(rawDelta);
         getContext().logger.debug('Received delta', {
             action: delta.actionType,
             model: delta.modelName,
@@ -1342,8 +1364,10 @@ export class SyncWebSocket extends EventEmitter {
         }
         // Process incremental deltas
         if (payload.deltas && Array.isArray(payload.deltas)) {
-            // Process all deltas from sync response - store handles idempotency
-            const newDeltas = payload.deltas;
+            // Process all deltas from sync response - store handles idempotency.
+            // Same receive-boundary normalization as handleDelta — catch-up
+            // replays from older servers carry string ids too.
+            const newDeltas = payload.deltas.map((d) => this.normalizeWireDelta(d));
             if (newDeltas.length > 0) {
                 // DO NOT pre-advance `this.lastSyncId` here. Same reasoning as
                 // `handleDelta`: the runtime cursor must stay consistent with

package/dist/sync/awaitIntentGrant.d.ts

@@ -15,6 +15,20 @@
 export interface GrantTransport {
     subscribe(event: 'intent_acquired' | 'intent_granted' | 'intent_lost' | 'intent_queued', handler: (payload: Record<string, unknown>) => void): () => void;
 }
+export interface IntentGrantInfo {
+    /**
+     * True when the grant arrived as `intent_granted` — i.e. the target was
+     * HELD when we asked and we waited in the FIFO line behind the holder.
+     * False for the immediate `intent_acquired` (target was free).
+     *
+     * Callers use this to know the row may have changed while we queued:
+     * intent VISIBILITY is entity-scoped (org-wide subscriptions receive no
+     * presence/intent fan-out — see Hub.broadcastPresenceChange), so the
+     * local coordination snapshot cannot be trusted to detect "we waited".
+     * The grant frame itself is the authoritative signal.
+     */
+    readonly waited: boolean;
+}
 export declare function awaitIntentGrant(transport: GrantTransport, intentId: string, options?: {
     timeoutMs?: number;
     /**
@@ -23,4 +37,4 @@ export declare function awaitIntentGrant(transport: GrantTransport, intentId: st
      * already ahead of us). Omit to wait however deep the queue is.
      */
     maxQueueDepth?: number;
-}): Promise<void>;
+}): Promise<IntentGrantInfo>;

package/dist/sync/awaitIntentGrant.js

@@ -24,15 +24,17 @@ export function awaitIntentGrant(transport, intentId, options) {
                 u();
             fn();
         };
-        const onGrant = (p) => {
-            if (p?.intentId === intentId)
-                settle(resolve);
-        };
         // The target was free → `intent_acquired` (immediate); it was contended,
         // we waited in line, and reached the head → `intent_granted`. Either frame
-        // means the lease is now ours, so one await covers both grant paths.
-        unsubs.push(transport.subscribe('intent_acquired', onGrant));
-        unsubs.push(transport.subscribe('intent_granted', onGrant));
+        // means the lease is now ours; `waited` records which path it was.
+        unsubs.push(transport.subscribe('intent_acquired', (p) => {
+            if (p?.intentId === intentId)
+                settle(() => resolve({ waited: false }));
+        }));
+        unsubs.push(transport.subscribe('intent_granted', (p) => {
+            if (p?.intentId === intentId)
+                settle(() => resolve({ waited: true }));
+        }));
         if (options?.maxQueueDepth !== undefined) {
             const max = options.maxQueueDepth;
             unsubs.push(transport.subscribe('intent_queued', (p) => {

package/dist/transactions/TransactionQueue.js

@@ -852,7 +852,17 @@ export class TransactionQueue extends EventEmitter {
         // LINEAR PATTERN: Simplified coalescing for updates
         // Staging already batches all transactions in same event loop tick
         // We only need to handle: (1) in-flight merging, (2) same-entity merging
-        if (transaction.type === 'update') {
+        //
+        // RETRIES (attempts > 0) must NEVER take either merge path. A retry is
+        // re-enqueued from `handleFailure` while its own modelKey is still in
+        // `inFlightByModel` (the post-batch cleanup runs after the catch), so the
+        // in-flight merge mistook the retry for a concurrent user edit: it moved
+        // the data into `pendingMergeByModel`, REMOVED the transaction, and the
+        // post-batch block minted a fresh follow-up with `attempts: 0`. The
+        // attempt counter never accumulated and `maxRetries` never tripped — an
+        // infinite ~`batchDelay` resend storm of self-laundering transaction
+        // clones (found by the claims journey, 2026-06-10).
+        if (transaction.type === 'update' && transaction.attempts === 0) {
             const preserveWatermark = hasStaleWriteOptions(transaction.writeOptions);
             // If there is an in-flight update for this model, merge into post-flight buffer
             if (!preserveWatermark && this.inFlightByModel.has(modelKey)) {
@@ -1606,25 +1616,40 @@ export class TransactionQueue extends EventEmitter {
                 await this.rollbackOptimistic(transaction, 'permanent_error', error);
             }
             this.emit('transaction:failed', { transaction, error, permanent: true });
+            // The id-suffixed event is what `waitForConfirmation` (the
+            // `wait:'confirmed'` path) listens on — without it a permanently
+            // rejected write left the caller's promise hanging forever.
+            this.emit(`transaction:failed:${transaction.id}`, { error });
             return;
         }
         if (transaction.attempts < this.config.maxRetries) {
-            // Backoff for retryable server responses (HTTP 429/503).
-            // Exponential with jitter, capped — tunable via
-            // `TransactionQueueConfig.retryBackoff`.
+            // Exponential backoff with FULL jitter for EVERY transient retry
+            // (AWS-standard shape: `sleep = random(0, min(cap, base × 2^attempt))`
+            // — see the Exponential Backoff And Jitter analysis). Throttling
+            // signals (429/503) get a longer base, mirroring the AWS SDK's
+            // transient-vs-throttle split. Previously only 429/503 backed off
+            // AND the sleep blocked the whole batch loop — every other failure
+            // retried at raw `batchDelay` cadence. The re-enqueue is scheduled
+            // (never awaited) so one backing-off transaction can't stall
+            // unrelated commits.
+            const { baseMs, capMs } = this.config.retryBackoff;
+            let base = baseMs;
             try {
                 const status = extractStatusCode(error);
-                if (status === 429 || status === 503) {
-                    const { baseMs, capMs } = this.config.retryBackoff;
-                    const delay = Math.min(capMs, Math.floor(baseMs * Math.pow(2, transaction.attempts - 1)));
-                    const jitter = Math.floor(Math.random() * 100);
-                    await new Promise((r) => setTimeout(r, delay + jitter));
-                }
+                if (status === 429 || status === 503)
+                    base = Math.max(baseMs, 1_000);
             }
             catch { }
-            // Retry
+            const ceiling = Math.min(capMs, base * Math.pow(2, transaction.attempts - 1));
+            const delay = Math.floor(Math.random() * ceiling);
             this.store.updateStatus(transaction.id, 'pending');
-            this.enqueue(transaction);
+            setTimeout(() => {
+                // The queue may have shut down or the tx may have been settled
+                // (e.g. delta-confirmed) while we backed off.
+                if (this.store.get(transaction.id)?.status !== 'pending')
+                    return;
+                this.enqueue(transaction);
+            }, delay);
         }
         else {
             // Mark as failed and rollback
@@ -1633,6 +1658,8 @@ export class TransactionQueue extends EventEmitter {
                 await this.rollbackOptimistic(transaction, 'max_retries_exhausted', error);
             }
             this.emit('transaction:failed', { transaction, error });
+            // Settle `waitForConfirmation` waiters (see the permanent branch above).
+            this.emit(`transaction:failed:${transaction.id}`, { error });
         }
     }
     /**

package/docs/quickstart.md

@@ -7,17 +7,19 @@ is the system of record — Ablo never hosts your data. It is the transaction
 layer on top: it registers your connection, commits every write there behind
 row-level security, and fans the confirmed rows out to every connected client.
 
-## 1. Install and get a key
+## 1. Install and initialize
 
 ```bash
 npm install @abloatai/ablo
-npx ablo login
+npx ablo init
 ```
 
-`ablo login` opens the browser — sign in (or sign up) and a `sk_test_` key is
-saved locally for the CLI. Later, `npx ablo dev` (step 4) writes
-`ABLO_API_KEY` into your `.env.local` so the SDK finds it too — no manual
-copy-paste. In CI, or to manage it by hand, set it yourself instead:
+`ablo init` scaffolds your project (next step shows what it creates) and ends
+by signing you in — one browser click, and a `sk_test_` key is saved locally
+for the CLI. Later, `npx ablo push` (step 4) writes `ABLO_API_KEY` into your
+`.env.local` so the SDK finds it too — no manual copy-paste. `npx ablo login`
+also exists standalone. In CI, or to manage the key by hand, set it yourself
+instead:
 
 ```bash
 export ABLO_API_KEY=sk_test_...
@@ -28,7 +30,7 @@ except both point at databases *you* own: `sk_test_*` for your dev database,
 `sk_live_*` for production. There is no keyless mode; the public `/sandbox` page
 is a hosted demo, not your app.
 
-## 2. Declare your Ablo schema
+## 2. Your Ablo schema (init scaffolded it)
 
 The schema is the contract — it generates `ablo.<model>` methods for app code,
 server actions, agents, and React reads. Declare **only the synced models** Ablo
@@ -78,10 +80,11 @@ tenant isolation with row-level security, so the server rejects superuser or
 
 > **Neon / Supabase note:** the connection string those dashboards hand you
 > uses the database OWNER role (e.g. `neondb_owner`), which is `BYPASSRLS` —
-> Ablo will reject it. You don't have to fix that by hand: `npx ablo migrate`
-> detects the unsafe role and offers to create the scoped one for you — from
-> your machine, so the owner credential never reaches Ablo. It writes the new
-> `DATABASE_URL` into your env file (the generated password is never printed).
+> Ablo will reject it. You don't have to fix that by hand: `npx ablo dev`
+> (next step) detects the unsafe role and offers to create the scoped one for
+> you — from your machine, so the owner credential never reaches Ablo. It
+> writes the new `DATABASE_URL` into your env file (the generated password is
+> never printed).
 >
 > Prefer to do it manually? The equivalent SQL:
 >
@@ -101,16 +104,25 @@ built from an ORM adapter instead — same product, same writes, see
 [Connect Your Database](./data-sources.md). In that setup, omit `databaseUrl`
 from `Ablo(...)`.
 
-## 4. Provision your tables, then push the schema
+## 4. Push — Ablo provisions your tables for you
 
 ```bash
-npx ablo migrate   # creates your synced-model tables (with row-level security)
-                   # in YOUR database — your other tables are left untouched
-npx ablo dev       # pushes the schema (sandbox), writes ABLO_API_KEY to
-                   # .env.local, and re-pushes on every save — the dev loop
+npx ablo push      # checks your DATABASE_URL role, pushes the schema (sandbox),
+                   # provisions your synced-model tables (with row-level
+                   # security) IN YOUR database, and writes ABLO_API_KEY to
+                   # .env.local. Add --watch to re-push on every save.
 ```
 
-`ablo dev` (or one-shot `npx ablo push`) uploads the schema *definition* —
+Nothing runs locally — there is no dev server to start. Your app talks to
+Ablo's hosted API with the sandbox key; the rows land in your database.
+
+There is no separate migration step: the push provisions your synced-model
+tables in the registered database server-side — your other tables are left
+untouched. (`npx ablo migrate` still exists for the signed Data Source
+endpoint mode, where Ablo never touches your database and DDL must run from
+your side.)
+
+`ablo push` uploads the schema *definition* —
 model names, fields, types. That metadata is the only thing Ablo keeps; the
 rows stay in your database. Skipping the push makes every write to a new or
 changed model fail with `server_execute_unknown_model` — that error literally

package/llms-full.txt

@@ -201,7 +201,7 @@ Use these public environment names:
 
 - `ABLO_API_KEY` — SDK authentication for app and agent code. Where it comes
   from: the human runs `npx ablo login` once (browser; an agent must not run
-  it), and `npx ablo dev` then writes `ABLO_API_KEY=sk_test_…` into
+  it), and `npx ablo push` then writes `ABLO_API_KEY=sk_test_…` into
   `.env.local` automatically (and gitignores it). Check the environment and
   `.env.local` for PRESENCE only (`grep -cq '^ABLO_API_KEY=' .env.local`)
   before asking the human for a key — never print or echo the key value; a

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 dev --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 dev` 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 --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).
 
 ## Use this API
 
@@ -179,8 +179,8 @@ Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subp
 `ablo init` and other prompts need a TTY; an agent/CI run has none and will HANG. Always:
 
 - `npx ablo init --yes` (flags: `--framework`, `--auth`, `--storage`, `--no-agent`, `--no-pull`, `--no-install`, `--no-login`). Generates `ablo/schema.ts` + the `ablo/data-source.ts` endpoint above.
-- Key: see "Start here" — env → `.env.local` → ask the human to `npx ablo login`; never run `login` yourself, never copy keys by hand (`ablo dev` writes `.env.local`).
+- 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 dev --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 --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.
 
 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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "description": "State control API for AI agents and collaborative apps.",
   "license": "Apache-2.0",
   "type": "module",