@abloatai/ablo 0.10.1 → 0.11.1

package/docs/migration.md

@@ -11,6 +11,7 @@ change when you upgrade.
 
 | Version | What changed | What to do |
 |---|---|---|
+| **0.11.0** | `intent` → `claim` rename completed across the React hook, type namespace, and wire frames | `useIntent` → `useClaim`; `Register.Intents` → `Register.Claims`; `Ablo.Intent.*` → `Ablo.Claim.*`. Upgrade client **and** server together (wire frames moved `intent_*` → `claim_*`) |
 | **0.10.0** | Environment enum renamed `test`/`live` → `sandbox`/`production` | Update code that branches on the environment (e.g. source `mode`): `'test'`→`'sandbox'`, `'live'`→`'production'`. Key prefixes `sk_test_`/`sk_live_` are unchanged |
 | **0.9.2** | `turn` primitive + agent-work `tasks` resource removed | Coordinate with `claim`; mint a scoped session instead of `agent().run()` |
 | **0.9.2** | `intents` deprecated in favor of `claim` | Use `ablo.<model>.claim`; `ablo.intents` is now `@internal` |
@@ -24,6 +25,45 @@ change when you upgrade.
 
 ---
 
+## 0.11.0 — `intent` → `claim` rename completed
+
+The coordination primitive has been `claim` since 0.9.2, but a few `intent`-named
+surfaces lingered. 0.11.0 finishes the rename. There are three edits, all
+mechanical:
+
+**1. React hook.** `useIntent` is now `useClaim` (same signature):
+
+```diff
+- import { useIntent } from '@abloatai/ablo/react';
+- const claimEditLayer = useIntent('editLayer');
++ import { useClaim } from '@abloatai/ablo/react';
++ const claimEditLayer = useClaim('editLayer');
+```
+
+**2. Type registration.** The `Register` interface key is `Claims`, not `Intents`:
+
+```diff
+  declare module '@abloatai/ablo' {
+    interface Register {
+-     Intents: { editLayer: { slideId: string; layerId: string } };
++     Claims: { editLayer: { slideId: string; layerId: string } };
+    }
+  }
+```
+
+**3. Type namespace.** The `Ablo.Intent.*` helper types moved to `Ablo.Claim.*`.
+If you referenced them directly, rename the namespace; the shapes are unchanged.
+
+> **Coordinated deploy required.** The on-the-wire frames moved from `intent_*`
+> to `claim_*`. A `claim_*`-aware client cannot coordinate with an `intent_*`
+> server (and vice-versa), so ship the client and server together. If you run a
+> self-managed sync server, deploy it first.
+
+Two non-breaking improvements ride along: claim-rejection errors now surface the
+contending holders (`AbloClaimedError.claims` and a policy reason folded into the
+message), and `participantKind` is the canonical `'user' | 'agent' | 'system'`
+on presence and claim state.
+
 ## 0.10.0 — environment enum `sandbox` / `production`; stateless HTTP transport
 
 ### Environment enum rename (the only breaking change)

package/docs/quickstart.md

@@ -1,11 +1,16 @@
 # Quickstart
 
-Build with Ablo on **your own database**. You declare a small Ablo schema for the
-models humans and agents edit together, hand the client your Postgres
-`DATABASE_URL`, and coordinate every write through `ablo.<model>`. Your database
-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.
+Build with Ablo on **the Postgres you already have**. You declare a small Ablo
+schema for the models humans and agents edit together, hand the client your
+Postgres `DATABASE_URL` (passed explicitly), and coordinate every write through
+`ablo.<model>`. In production, your database is the system of record. Ablo 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.
+
+> No database yet? The hosted **sandbox** can host rows in Ablo's test plane —
+> pass an `apiKey` only and omit `databaseUrl`, like Stripe test mode — so you can
+> try Ablo before pointing it at your Postgres.
 
 ## 1. Install and initialize
 
@@ -25,10 +30,12 @@ instead:
 export ABLO_API_KEY=sk_test_...
 ```
 
-Every SDK and CLI call needs a key. Test and live keys work like Stripe's —
-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.
+Every SDK and CLI call needs a key. Test and live keys work like Stripe's:
+`sk_test_*` for the sandbox, `sk_live_*` for production. In production a key
+points at the database *you* own; in the sandbox you can skip the database
+entirely and let Ablo's test plane host the rows (apiKey only). There is no
+keyless mode — a key is always required. (The public `/sandbox` page is a
+separate hosted demo, not your app.)
 
 ## 2. Your Ablo schema (init scaffolded it)
 
@@ -51,18 +58,24 @@ export const schema = defineSchema({
 ```
 
 
-Register the schema once (init scaffolds this `ablo.d.ts`), and every type
-is one parameter away — no `typeof schema` re-stating, anywhere:
+The schema is registered once (init scaffolds `ablo/register.ts` for you), and
+every type is one parameter away — no `typeof schema` re-stating, anywhere:
 
 ```ts
-// ablo.d.ts — once per project
-import type { schema } from './ablo/schema';
+// ablo/register.ts — scaffolded by `npx ablo init`, sits beside ablo/schema.ts
+import type { schema } from './schema';
 declare module '@abloatai/ablo' {
   interface Register { Schema: typeof schema }
 }
 export {};
 ```
 
+It's a regular `.ts` module, not a hand-authored `.d.ts`. The top-level
+`import type { schema }` makes the `declare module` block *merge* into (augment)
+the SDK's `Register` interface instead of colliding with it — the same shape
+[TanStack Router uses in `src/router.tsx`](https://tanstack.com/router/latest/docs/framework/react/guide/type-safety). Any `.ts` file in your
+`tsconfig` `include` works; it never needs to be imported.
+
 ```ts
 import type { Model } from '@abloatai/ablo/schema';
 
@@ -73,6 +86,12 @@ type WeatherReport = Model<'weatherReports'>; // fully typed from YOUR schema
 TanStack-Router pattern: declare the source of truth once, everything
 infers from it.)
 
+When you need to name the client type — to pass it to a function or store it in
+a context — **infer it from the value**: `type Sync = typeof sync`. That's the
+same idiom as tRPC's `typeof appRouter` and Drizzle's `typeof db`; it resolves
+the typed overload at the call site. Avoid `ReturnType<typeof Ablo>`, which
+collapses to the untyped client.
+
 ## 3. Point Ablo at your database
 
 The client takes your schema, your key, and your `DATABASE_URL`. On first
@@ -93,10 +112,14 @@ import { schema } from './schema';
 export const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY,
-  databaseUrl: process.env.DATABASE_URL, // your Postgres — rows live here, never with Ablo
+  databaseUrl: process.env.DATABASE_URL, // your Postgres, passed explicitly — rows live here
 });
 ```
 
+`databaseUrl` is not auto-read from the environment — you pass it explicitly
+(as above). If a `DATABASE_URL` is set for another tool, `Ablo()` ignores it
+unless you wire it in like this.
+
 Use a dedicated **non-superuser role** for the connection — Ablo enforces
 tenant isolation with row-level security, so the server rejects superuser or
 `BYPASSRLS` roles outright (`database_role_cannot_enforce_rls`).
@@ -127,29 +150,34 @@ 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. Push — Ablo provisions your tables for you
+## 4. Push the schema, then map it to tables
 
 ```bash
 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.
+                   # and writes ABLO_API_KEY to .env.local. Add --watch to
+                   # re-push on every save.
 ```
 
-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
-means "run `npx ablo push`."
+`ablo push` uploads the schema *definition* — model names, fields, types. That
+metadata is what tells Ablo which models to coordinate. Skipping it makes every
+write to a new or changed model fail with `server_execute_unknown_model` — that
+error literally means "run `npx ablo push`."
+
+Now Ablo needs real Postgres tables behind those models. Two ways, depending on
+who owns the tables:
+
+- **Adopt existing tables (the common case).** Most teams already have the
+  tables — created by Prisma, Drizzle, or hand-written migrations. Run
+  `npx ablo pull` to import their shape into your schema, or `npx ablo check`
+  to verify your schema and the live tables agree. Keep managing the tables
+  with your own migration tool; Ablo just syncs the subset of models you
+  declared.
+- **Let Ablo provision them.** If Ablo should own the tables, `npx ablo migrate`
+  creates your synced-model tables (with row-level security) in the registered
+  database. Your other tables are left untouched.
+
+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.
 
 ## 5. Write through the model
 

package/docs/react.md

@@ -178,6 +178,52 @@ imperative work after an event or effect.
 
 See [API reference](/docs/api) for the full options surface.
 
+## useClaim — named-claim dispatcher
+
+`useClaim` (renamed from `useIntent` in 0.11.0) is typed sugar for invoking a
+*named* claim from your own coordination vocabulary — distinct from the
+row-level `ablo.<model>.claim({ id })` resource claim. Use it when you want to
+broadcast a semantic claim like "I'm editing this layer" or "the agent is
+generating here" and let your transport turn it into a network effect.
+
+Declare the vocabulary once via module augmentation on the `Register` interface
+(the `Claims` key — previously `Intents`):
+
+```ts
+declare module '@abloatai/ablo' {
+  interface Register {
+    Claims: {
+      editLayer: { slideId: string; layerId: string };
+      generateWithAI: { entityId: string; tool: string };
+    };
+  }
+}
+```
+
+Then `useClaim('editLayer')` returns a function whose sole argument is the
+`editLayer` shape — purely compile-time narrowing, no runtime checks:
+
+```tsx
+'use client';
+
+import { useClaim } from '@abloatai/ablo/react';
+
+export function LayerToolbar({ slideId, layerId }: { slideId: string; layerId: string }) {
+  const claimEditLayer = useClaim('editLayer');
+
+  return (
+    <button onClick={() => claimEditLayer({ slideId, layerId })}>
+      Edit layer
+    </button>
+  );
+}
+```
+
+The hook is pure sugar: the actual network effect lives in the `beginClaim`
+function wired into the provider (bound to your transport). If no `beginClaim`
+is wired, the returned invoker throws `AbloValidationError` with code
+`claim_not_wired`.
+
 ## Next.js
 
 The Next.js [App Router landing](/nextjs) walks through Server Components

package/llms-full.txt

@@ -19,7 +19,7 @@ Public imports:
 - `@abloatai/ablo/react` — React provider and hooks.
 - `@abloatai/ablo/testing` — test harnesses and mocks.
 
-TYPES: have the project register its schema ONCE via declaration merging (init scaffolds `ablo.d.ts`): `declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`. Then model types are one parameter: `type Task = Model<'tasks'>` (import type { Model } from '@abloatai/ablo/schema'). Do NOT teach `InferModel` (deprecated) or the two-param `Model<typeof schema,'tasks'>` unless multiple schemas exist. Never hand-write model interfaces — derive from the schema.
+TYPES: the project registers its schema ONCE via declaration merging — `npx ablo init` scaffolds `ablo/register.ts` (a regular `.ts` module beside schema.ts, NOT a hand-authored `.d.ts`): `import type { schema } from './schema'; declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`. The top-level `import type` makes `declare module` MERGE (augment) the SDK's Register interface rather than collide — same shape TanStack Router uses in src/router.tsx; any `.ts` file in tsconfig include works, never imported. Then model types are one parameter: `type Task = Model<'tasks'>` (import type { Model } from '@abloatai/ablo/schema'). Do NOT teach `InferModel` (deprecated) or the two-param `Model<typeof schema,'tasks'>` unless multiple schemas exist. Never hand-write model interfaces — derive from the schema. To NAME the client type (function param, context value), infer from the value: `type Sync = typeof sync` — same idiom as tRPC `typeof appRouter` / Drizzle `typeof db`; it resolves the typed overload at the call site. Do NOT use `ReturnType<typeof Ablo>` (collapses to the untyped last overload) and do NOT import a bespoke client-type generic — there is none.
 
 
 Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or `internal/*` as public imports. The Data Source surface — `/source`, `/source/next`, `/source/drizzle`, `/source/kysely`, `/source/conformance` — IS public (it's how a customer-owned database is wired).
@@ -145,9 +145,21 @@ This applies to any API-backed app: Python, Rails, Go, or Node. The backend keep
 its service layer and DB credentials. Ablo gets a Data Source endpoint and uses
 `ABLO_API_KEY`, not a database URL.
 
-When the user DOES use the connection-string path (`Ablo({ databaseUrl })` /
-`DATABASE_URL` at init): the role must be NON-superuser and NON-BYPASSRLS —
-Ablo enforces row-level security and rejects owner roles with
+The connection-string path is the PRIMARY one: pass `databaseUrl` explicitly to
+`Ablo({ databaseUrl })`. It is NOT auto-read from the environment — a
+`DATABASE_URL` set for another tool (Prisma, Drizzle, docker-compose) is ignored
+unless you pass `databaseUrl`. The typical user ALREADY has a Postgres (often
+Prisma-managed for auth/audit/log tables that are NOT in the Ablo schema); Ablo
+syncs a SUBSET of models against it. Most users do NOT run `ablo migrate` — they
+ADOPT existing tables with `npx ablo pull` / `npx ablo check`, or keep managing
+tables with their own migration tool. Run `npx ablo migrate` only when Ablo
+should OWN the tables. NOTE: Ablo's CLOUD connects to your Postgres over the
+NETWORK, so a localhost / private-range DB is unreachable and rejected — for a
+local dev DB, expose a signed Data Source endpoint (your app proxies to it) or
+use the hosted sandbox (no DB needed).
+
+When the user DOES use the connection-string path: the role must be NON-superuser
+and NON-BYPASSRLS — Ablo enforces row-level security and rejects owner roles with
 `database_role_cannot_enforce_rls`. Neon's and Supabase's default dashboard
 strings use the database OWNER (e.g. `neondb_owner`) and ARE rejected. EASIEST: have the user run `npx ablo migrate` — it detects the unsafe role and creates the scoped one automatically from their machine (owner credential never reaches Ablo; new DATABASE_URL written to the env file). Manual alternative — create a scoped role first (`CREATE ROLE ablo_app LOGIN PASSWORD '...'
 NOSUPERUSER NOBYPASSRLS; GRANT CREATE, CONNECT ON DATABASE <db> TO ablo_app;
@@ -162,9 +174,11 @@ The options that matter: `schema` and `apiKey`. Everything else
 breaks the connection. It exists only for self-hosted/proxy setups the human
 explicitly asks for.
 
-There is intentionally no `databaseURL` option on `Ablo(...)`. Application and
-agent code use `ABLO_API_KEY`. Customer-owned app databases stay private behind
-a signed Data Source endpoint.
+`databaseUrl` is an OPTIONAL, server-only option on `Ablo(...)`. It is NOT
+auto-read from the environment — pass it EXPLICITLY to register your Postgres
+directly (the primary connection-string path). Omit it when you expose a signed
+Data Source endpoint (so customer-owned app databases stay private), or when
+trying Ablo against the hosted sandbox (apiKey only, no database).
 
 Important per-write options: `wait`, `readAt`, `onStale`,
 `idempotencyKey`, and `timeout`.
@@ -187,7 +201,10 @@ There are two sandbox surfaces:
   be pasted into Claude Code or Codex to wire one real model through Ablo.
 - Authenticated org sandboxes are real test environments. The default sandbox is
   the Stripe-style sandbox for an org. It has an isolated sync group prefix,
-  can mint `sk_test_*` keys, and can be reset without touching live state.
+  can mint `sk_test_*` keys, and can be reset without touching live state. The
+  sandbox CAN host rows in Ablo's test plane, so you can try Ablo with NO
+  database — `apiKey` only, no `databaseUrl` — like Stripe test mode. (In
+  production, your own Postgres is the system of record.)
 
 Additional org sandboxes can start blank or copy live configuration. Keep
 customer production traffic on `sk_live_*`; use `sk_test_*` for app setup, Data

package/llms.txt

@@ -8,7 +8,7 @@ Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist
 
 ## Start here
 
-First action when integrating into an app: run `npx ablo init --yes --framework <nextjs|vite|remix|vanilla> --storage datasource`. Agents have no TTY — `--yes` is REQUIRED or it HANGS. It scaffolds `ablo/schema.ts`, the client, the Data Source endpoint, and (for Next.js) the browser provider + session route, all on the current API. Edit the generated files rather than hand-writing from this doc.
+First action when integrating into an app: run `npx ablo init --yes --framework <nextjs|vite|remix|vanilla>`. Agents have no TTY — `--yes` is REQUIRED or it HANGS. The default `--storage direct` (connection string) scaffolds `ablo/schema.ts`, the client, and (for Next.js) the browser provider + session route; pass `--storage endpoint` instead when database credentials must stay inside the app — that variant scaffolds a signed Data Source endpoint. All on the current API. Edit the generated files rather than hand-writing from this doc.
 
 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.
 
@@ -24,7 +24,7 @@ Each app gets its own PROJECT inside the org — its own schema, its own sandbox
 import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
-TYPES: have the project register its schema ONCE via declaration merging (init scaffolds `ablo.d.ts`): `declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`. Then model types are one parameter: `type Task = Model<'tasks'>` (import type { Model } from '@abloatai/ablo/schema'). Do NOT teach `InferModel` (deprecated) or the two-param `Model<typeof schema,'tasks'>` unless multiple schemas exist. Never hand-write model interfaces — derive from the schema.
+TYPES: the project registers its schema ONCE via declaration merging — `npx ablo init` scaffolds `ablo/register.ts` (a regular `.ts` module beside schema.ts, NOT a hand-authored `.d.ts`): `import type { schema } from './schema'; declare module '@abloatai/ablo' { interface Register { Schema: typeof schema } }`. The top-level `import type` makes `declare module` MERGE (augment) the SDK's Register interface rather than collide — same shape TanStack Router uses in src/router.tsx; any `.ts` file in tsconfig include works, never imported. Then model types are one parameter: `type Task = Model<'tasks'>` (import type { Model } from '@abloatai/ablo/schema'). Do NOT teach `InferModel` (deprecated) or the two-param `Model<typeof schema,'tasks'>` unless multiple schemas exist. Never hand-write model interfaces — derive from the schema. To NAME the client type (function param, context value), infer from the value: `type Sync = typeof sync` — same idiom as tRPC `typeof appRouter` / Drizzle `typeof db`; it resolves the typed overload at the call site. Do NOT use `ReturnType<typeof Ablo>` (collapses to the untyped last overload) and do NOT import a bespoke client-type generic — there is none.
 
 
 const schema = defineSchema({
@@ -123,9 +123,9 @@ A schema is model fields and relations. Advanced schema helpers such as `mutable
 
 ## Storage Boundary
 
-Do not add `databaseURL` to `Ablo(...)`. Application and agent code use `ABLO_API_KEY`.
+`databaseUrl` is an OPTIONAL, server-only constructor option on `Ablo(...)`. It is NOT auto-read from the environment — pass it EXPLICITLY to register your Postgres directly. Omit it when you expose a signed Data Source endpoint, or when trying Ablo against the hosted sandbox (apiKey only). A `DATABASE_URL` set for another tool (Prisma, Drizzle, docker-compose) is ignored unless you pass `databaseUrl` explicitly.
 
-Every schema model is backed by a database, and the default is YOUR OWN. Keep your rows in your Postgres and expose a Data Source endpoint that hands Ablo an ORM `adapter` (Drizzle is the default; Prisma and Kysely are also supported) — it owns the transaction, exactly-once idempotency, and outbox in ONE pass (no hand-written `commit`/`events`). Your `DATABASE_URL` lives in your app, never in `Ablo(...)`; run `npx ablo migrate` to provision the synced-model tables in your DB.
+In production, every schema model is backed by YOUR OWN database. The PRIMARY path is the connection string: pass `databaseUrl` (most users already have a Postgres — often Prisma- or Drizzle-managed for auth/audit/log tables that are NOT in the Ablo schema; Ablo syncs a SUBSET of models against it). Most users do NOT run `ablo migrate` — they ADOPT existing tables with `npx ablo pull` / `npx ablo check`, or keep managing tables with their own migration tool. Run `npx ablo migrate` only when Ablo should OWN the tables (it provisions the synced-model tables in your DB). The alternative to the connection string is a signed Data Source endpoint that hands Ablo an ORM `adapter` (Drizzle is the default; Prisma and Kysely are also supported) — it owns the transaction, exactly-once idempotency, and outbox in ONE pass (no hand-written `commit`/`events`); use it when database credentials must never leave your infrastructure (or for a local/private-range DB, which Ablo's cloud cannot reach over the network).
 
 GOTCHA the user WILL hit: `DATABASE_URL` must use a NON-superuser, NON-BYPASSRLS role (Ablo enforces row-level security; owner roles are rejected with `database_role_cannot_enforce_rls`). Neon's and Supabase's default dashboard connection strings use the database OWNER (e.g. `neondb_owner`) and are rejected. EASIEST: `npx ablo migrate` detects the unsafe role and creates the scoped one automatically from the user's machine (owner credential never reaches Ablo; new DATABASE_URL written to the env file). Manual alternative — create a scoped role first: `CREATE ROLE ablo_app LOGIN PASSWORD '...' NOSUPERUSER NOBYPASSRLS; GRANT CREATE, CONNECT ON DATABASE <db> TO ablo_app; GRANT CREATE, USAGE ON SCHEMA public TO ablo_app;` — then swap user/password into the same host/db string.
 
@@ -145,7 +145,7 @@ export const { POST } = dataSourceNext({
 });
 ```
 
-`npx ablo init` defaults to this — it scaffolds the endpoint and the `DATABASE_URL` for you (see CLI below). Your app database credentials stay private — Ablo only calls the endpoint.
+`npx ablo init` defaults to `--storage direct` (the connection-string path — it scaffolds the client carrying `databaseUrl` and the `DATABASE_URL` env entry; see CLI below). Pass `--storage endpoint` to scaffold the signed Data Source endpoint above instead, when app database credentials must stay private — Ablo only calls the endpoint.
 
 ## Sandboxes
 
@@ -156,9 +156,11 @@ when an agent is asked to "make Ablo work" in an existing app.
 
 Authenticated org sandboxes are real test environments. Treat the default
 sandbox like Stripe test mode: it has an isolated sync group prefix and mints
-`sk_test_*` keys. Extra sandboxes can start blank or copy live configuration.
-Resetting a sandbox creates a clean future stream without touching live data.
-Use `sk_live_*` only for production.
+`sk_test_*` keys. The sandbox CAN host rows in Ablo's test plane, so you can try
+Ablo with NO database — `apiKey` only, no `databaseUrl`. (In production, your own
+Postgres is the system of record.) Extra sandboxes can start blank or copy live
+configuration. Resetting a sandbox creates a clean future stream without
+touching live data. Use `sk_live_*` only for production.
 
 For coding agents, the sandbox success path is: pick one shared model,
 declare schema, create the Ablo client, replace one direct mutation with a typed
@@ -185,7 +187,7 @@ 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.
+- `npx ablo init --yes` (flags: `--framework`, `--auth`, `--storage direct|endpoint` (default `direct`), `--no-agent`, `--no-pull`, `--no-install`, `--no-login`). Generates `ablo/schema.ts` + the client; `--storage direct` (default) wires `databaseUrl`, `--storage endpoint` scaffolds the `ablo/data-source.ts` endpoint above instead.
 - Key: see "Start here" — env → `.env.local` → ask the human to `npx ablo login`; never run `login` yourself, never copy keys by hand (`ablo push` writes `.env.local`).
 - Adopt an existing DB: `npx ablo pull prisma [path]` / `npx ablo pull drizzle <module>`.
 - `npx ablo push --no-watch` pushes the schema (sandbox) AND writes `ABLO_API_KEY` to `.env.local` (default watches forever); `npx ablo logs --no-follow` (default tails forever); `npx ablo mode sandbox|production` (always pass the arg). `npx ablo push`/`status`/`pull`/`check`/`generate` are one-shot.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.10.1",
+  "version": "0.11.1",
   "description": "The Collaboration Layer For AI Agents",
   "license": "Apache-2.0",
   "type": "module",
@@ -221,6 +221,7 @@
     "ts-morph": "^26.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.8.3",
-    "publint": "^0.3.21"
+    "publint": "^0.3.21",
+    "yjs": "^13.6.29"
   }
 }

package/dist/react/useIntent.js

@@ -1,42 +0,0 @@
-'use client';
-import { useCallback } from 'react';
-import { useSyncContext } from './context.js';
-import { AbloValidationError } from '../errors.js';
-/**
- * Named-intent invoker, typed via `ResolveIntents[IntentName]`.
- *
- * The consumer declares their intent vocabulary in the global:
- *
- * ```ts
- * declare module '@abloatai/ablo' {
- *   interface Register {
- *     Intents: {
- *       editLayer: { slideId: string; layerId: string };
- *       generateWithAI: { entityId: string; tool: string };
- *     };
- *   }
- * }
- * ```
- *
- * Then `useIntent('editLayer')` returns a function whose sole argument
- * is the `editLayer` claim shape — no runtime checks, purely compile-
- * time narrowing.
- *
- * The SDK doesn't own what happens next: the `beginIntent` function on
- * the React context (supplied via `SyncProvider`) is where the intent
- * claim turns into a network effect. A Node-backed consumer wires it
- * through `SyncAgent.beginIntent`; a browser-backed consumer may
- * broadcast it through their own WebSocket. This hook is pure sugar
- * that adds the typed name + claim narrowing.
- */
-export function useIntent(intentName) {
-    const { beginIntent } = useSyncContext();
-    return useCallback((claim) => {
-        if (!beginIntent) {
-            throw new AbloValidationError(`useIntent: no \`beginIntent\` wired into SyncProvider. Pass ` +
-                `a \`beginIntent\` prop (typically bound to your transport) ` +
-                `to enable intent invocations.`, { code: 'intent_not_wired' });
-        }
-        return beginIntent(intentName, claim);
-    }, [beginIntent, intentName]);
-}

package/dist/sync/awaitIntentGrant.d.ts

@@ -1,40 +0,0 @@
-/**
- * `awaitIntentGrant` — the client side of the fair-queue handover.
- *
- * When a `claim` is contended, the server enqueues it and replies `queued`
- * (HTTP 202 on `/v1/intents`, or `intent_queued` over WS). The grant is then
- * PUSHED later over the WS as `intent_granted` when the claim reaches the head.
- * This resolves once that frame arrives for our `intentId` — so the caller's
- * `claim` promise stays pending (event-driven; no poll, no race) until it's
- * actually our turn. Rejects on `intent_lost` (surfaced as `claim_lost`: the claim was taken away — TTL
- * lapse on disconnect, revoke) or an optional timeout.
- *
- * Takes only a minimal `{ subscribe }` transport so it unit-tests against a
- * fake; `SyncWebSocket` satisfies it structurally.
- */
-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;
-    /**
-     * Backpressure: reject instead of waiting if, when we join the line, the
-     * server reports `position >= maxQueueDepth` (i.e. that many claims are
-     * already ahead of us). Omit to wait however deep the queue is.
-     */
-    maxQueueDepth?: number;
-}): Promise<IntentGrantInfo>;

package/dist/sync/awaitIntentGrant.js

@@ -1,62 +0,0 @@
-/**
- * `awaitIntentGrant` — the client side of the fair-queue handover.
- *
- * When a `claim` is contended, the server enqueues it and replies `queued`
- * (HTTP 202 on `/v1/intents`, or `intent_queued` over WS). The grant is then
- * PUSHED later over the WS as `intent_granted` when the claim reaches the head.
- * This resolves once that frame arrives for our `intentId` — so the caller's
- * `claim` promise stays pending (event-driven; no poll, no race) until it's
- * actually our turn. Rejects on `intent_lost` (surfaced as `claim_lost`: the claim was taken away — TTL
- * lapse on disconnect, revoke) or an optional timeout.
- *
- * Takes only a minimal `{ subscribe }` transport so it unit-tests against a
- * fake; `SyncWebSocket` satisfies it structurally.
- */
-import { AbloClaimedError } from '../errors.js';
-export function awaitIntentGrant(transport, intentId, options) {
-    return new Promise((resolve, reject) => {
-        const unsubs = [];
-        let timer;
-        const settle = (fn) => {
-            if (timer)
-                clearTimeout(timer);
-            for (const u of unsubs)
-                u();
-            fn();
-        };
-        // 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; `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) => {
-                if (p?.intentId !== intentId)
-                    return;
-                const position = typeof p.position === 'number' ? p.position : 0;
-                if (position >= max) {
-                    settle(() => reject(new AbloClaimedError(`Claim queue for ${intentId} is ${position} deep (max ${max}).`, { code: 'queue_too_deep' })));
-                }
-            }));
-        }
-        unsubs.push(transport.subscribe('intent_lost', (p) => {
-            if (p?.intentId === intentId) {
-                settle(() => reject(new AbloClaimedError(`Claim lost while queued for ${intentId}.`, {
-                    code: 'claim_lost',
-                })));
-            }
-        }));
-        if (options?.timeoutMs && options.timeoutMs > 0) {
-            timer = setTimeout(() => {
-                settle(() => reject(new AbloClaimedError(`Timed out waiting for the queue grant on claim ${intentId}.`, { code: 'grant_timeout' })));
-            }, options.timeoutMs);
-        }
-    });
-}

package/dist/sync/createIntentStream.d.ts

@@ -1,34 +0,0 @@
-/**
- * Transport-driven IntentStream factory.
- *
- * Mirrors `createPresenceStream` — built directly on `SyncWebSocket`,
- * no SyncAgent wrapper. Intents derive their `others` view from the
- * same `presence_update` frames the presence stream consumes (the
- * Hub piggybacks `activeIntents` on every presence frame). Outbound
- * announce/revoke ride the same socket via `intent_begin` /
- * `intent_abandon` frames.
- *
- * Wire contract (apps/sync-server/src/hub/types.ts):
- *   • Outbound: `{ type: 'intent_begin', payload: { intentId,
- *       entityType, entityId, action, field?, estimatedMs? } }`
- *   • Outbound: `{ type: 'intent_abandon', payload: { intentId,
- *       entityType?, entityId? } }`
- *   • Inbound (via presence): `event.activeIntents: IntentClaim[]`
- *     stamped with `declaredAt`, `expiresAt`.
- *   • Inbound: `intent_rejected` event with conflict metadata.
- *
- * After the dual-engine collapse (step #36), this is the only
- * IntentStream factory in the SDK; the older compatibility path
- * deletes.
- */
-import type { SyncWebSocket } from './SyncWebSocket.js';
-import type { IntentStream } from '../types/streams.js';
-export interface IntentStreamConfig {
-    /** Identity used to filter our own active intents out of `others`. */
-    participantId: string;
-}
-export interface AttachableIntentStream extends IntentStream {
-    attach(transport: SyncWebSocket): void;
-    dispose(): void;
-}
-export declare function createIntentStream(config: IntentStreamConfig, transport?: SyncWebSocket | null): AttachableIntentStream;