@abloatai/ablo 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.11.1
+
+### Patch Changes
+
+- 7f91f6e: DX hardening from a real onboarding session — onboarding, CLI, coordination, types, and docs.
+
+  **Client behavior**
+  - `databaseUrl` is now an explicit, server-only option: `Ablo(...)` no longer auto-reads `process.env.DATABASE_URL`. A stray `DATABASE_URL` (common — Prisma/Drizzle/docker set it) no longer silently flips the client into connection-string mode; a one-time warning points at the explicit option. Passing `databaseUrl: process.env.DATABASE_URL` explicitly is unchanged.
+  - Claims/presence are now observable from any client (including Node agents): reading a row enters its entity sync group (read-interest) and claiming pins it (write-intent), so `ablo.<model>.claim.state({ id })` reports co-participants without any manual subscribe step — whether the observer arrives before the claim (live delta) or after it (subscribe-time backfill). The claim **holder** now also sees its own claim via `claim.state`. **Requires a coordinated `sync-server` deploy** (the subscribe-time claim backfill + the entity-scope subscription gate that lets an org-authority agent key narrow into a row's group live server-side); the client package change alone does not deliver cross-client agent observation.
+
+  **CLI**
+  - `ablo init` detects the `src/app` layout (routes + the `@/ablo` import alias resolve correctly), writes the **real** stored sandbox key into `.env.local` instead of a placeholder, and scaffolds `ablo/register.ts` (a regular module, not a colliding `ablo.d.ts`).
+  - `ablo <command> --help` / `-h` now prints usage instead of erroring with "unknown flag", and `migrate` is listed in the top-level help.
+  - `ablo dev --no-watch` now exits after one push instead of watching forever.
+
+  **Types**
+  - Name the client with `typeof sync` (the value-inferred idiom, like tRPC's `typeof appRouter` / Drizzle's `typeof db`) — `ReturnType<typeof Ablo>` collapses to the untyped client and should not be used. No bespoke client-type generic is needed.
+  - `model_claim_not_configured` message clarified: claiming needs no per-model schema configuration; every model is claimable through the standard client.
+
+  **Docs**
+  - Reconciled the self-contradictory `databaseUrl` story (it is an explicit, server-only option, not auto-read from the environment; consistent casing), documented that the sandbox can host rows (apiKey only, no database), explained why a localhost Postgres can't be the system of record, and led the connect-your-database flow with `ablo pull`/`ablo check` over `ablo migrate`. Fixed stale `api.md` vocabulary (`object: 'claim'`, `participantKind: 'user' | 'agent' | 'system'`).
+
+- 7f91f6e: Docs: document the completed `intent` → `claim` rename. Adds a 0.11.0 migration entry (`useIntent` → `useClaim`, `Register.Intents` → `Register.Claims`, `Ablo.Intent.*` → `Ablo.Claim.*`, and the coordinated client/server deploy for the `claim_*` wire frames), a `useClaim` section in the React reference, and fixes the stale `participantKind` union to the canonical `'user' | 'agent' | 'system'`.
+
 ## 0.11.0
 
 ### Minor Changes

package/README.md

@@ -54,10 +54,12 @@ claims are visible while the work is still in progress.
 `llms.txt`  ·  **upgrading?** see the
 [Version History & Migration Guide](./docs/migration.md)
 
-It works with the auth and database you already have. **Your database is the
-system of record — Ablo never hosts your data.** Ablo is the transaction layer
-on top of it: realtime data is scoped to *sync groups* from your own identity,
-and every committed row lives in your Postgres.
+It works with the auth and database you already have. **In production, your
+database is the system of record.** Ablo is the transaction layer on top of it:
+realtime data is scoped to *sync groups* from your own identity, and every
+committed row lives in your Postgres. (Trying Ablo with no database yet? The
+hosted **sandbox** can host rows in Ablo's test plane — apiKey only, like
+Stripe test mode — so you can explore before pointing it at your Postgres.)
 
 **Built for** collaborative editors, AI agent workflows, and internal tools —
 anywhere people and agents change shared state and everyone has to see it live.
@@ -65,18 +67,24 @@ anywhere people and agents change shared state and everyone has to see it live.
 ## Set up
 
 The CLI takes you from nothing to a synced schema — it handles the account,
-the key, and the env file. You bring one thing: a Postgres `DATABASE_URL`
-(local, Neon, RDS — any will do; **your database is the system of record,
-Ablo never hosts your data**).
+the key, and the env file. You bring one thing: a Postgres you already have —
+the same `DATABASE_URL` (local, Neon, RDS — any will do) that backs your auth,
+audit, and log tables. Ablo syncs a *subset* of models against it; **in
+production, your database is the system of record**.
 
 ```bash
 npm install @abloatai/ablo
 npx ablo login     # opens the browser: sign in (or sign up) → a sk_test_ key is saved locally
 npx ablo init      # scaffolds ablo/schema.ts (offers to log in if you skipped it)
-npx ablo migrate   # creates the synced tables in YOUR Postgres (reads DATABASE_URL)
-npx ablo push       # pushes your schema (sandbox), writes ABLO_API_KEY to .env.local, watches for changes
+npx ablo push      # pushes your schema (sandbox), writes ABLO_API_KEY to .env.local, watches for changes
 ```
 
+Then point Ablo at the tables for your synced models. Most teams **already
+have those tables** (often Prisma- or Drizzle-managed) — adopt them with
+`npx ablo pull` / `npx ablo check`, the common case. Let Ablo own its own
+tables instead? `npx ablo migrate` provisions them in your Postgres (reads
+`DATABASE_URL`). Either way your other tables are left untouched.
+
 After `ablo push`, the [Quick Start](#quick-start) below runs as-is —
 `ABLO_API_KEY` is already in `.env.local` (frameworks load it automatically;
 plain Node: `node --env-file=.env.local app.ts`). `npx ablo status` shows
@@ -106,18 +114,24 @@ import Ablo from '@abloatai/ablo';
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 ```
 
-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';
 
@@ -128,6 +142,25 @@ type WeatherReport = Model<'weatherReports'>; // fully typed from YOUR schema
 TanStack-Router pattern: declare the source of truth once, everything
 infers from it.)
 
+### Naming the client type
+
+When you need to pass the client around (a function parameter, a context value),
+**infer the type from the value** — `type Sync = typeof sync`:
+
+```ts
+export const sync = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+export type Sync = typeof sync; // fully-typed, schema-aware
+
+function persist(client: Sync) { /* ... */ }
+```
+
+This is the same idiom as tRPC's `type AppRouter = typeof appRouter` and
+Drizzle's `typeof db` — the factory resolves the typed overload at the call
+site, so `typeof sync` carries your schema. Do **not** write
+`ReturnType<typeof Ablo>`: that collapses to the untyped last overload and
+loses your model types. There is no bespoke client-type generic to import —
+`typeof` your client value is the type.
+
 ```ts
 const schema = defineSchema({
   weatherReports: model({
@@ -140,7 +173,7 @@ const schema = defineSchema({
 const ablo = Ablo({
   schema,
   apiKey: process.env.ABLO_API_KEY, // written to .env.local by `npx ablo push`
-  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
 });
 
 await ablo.ready();
@@ -388,29 +421,35 @@ curl https://api.abloatai.com/v1/commits \
 
 ## Your Database
 
-Every schema model is backed by **your own database** — Ablo is the transaction
-layer on top of it, never the home for your rows. Two ways to connect it:
+In production, every schema model is backed by **your own database** — Ablo is
+the transaction layer on top of it. Two ways to connect it:
 
 | | How Ablo reaches your Postgres | Use when |
 | --- | --- | --- |
-| **Connection string** (default) | `databaseUrl` at init. Ablo registers the connection once (sent over TLS, stored sealed, never echoed back) and commits each write directly — through a non-superuser role, behind row-level security. | You can hand over a scoped connection string. |
+| **Connection string** (primary) | `databaseUrl` at init — passed explicitly, never auto-read from the environment. Ablo registers the connection once (sent over TLS, stored sealed, never echoed back) and commits each write directly — through a non-superuser role, behind row-level security. | You can hand over a scoped connection string. |
 | **Signed endpoint** | Your app exposes one route built from an ORM adapter (`prismaDataSource` / `drizzleDataSource`); Ablo sends signed commit requests and your app writes its own database. | Database credentials must never leave your infrastructure. |
 
-Same product, same truth either way: your database is the system of record. See
+(No database yet? The hosted **sandbox** can host rows in Ablo's test plane —
+omit `databaseUrl` and pass an `apiKey` only, like Stripe test mode — so you can
+try Ablo before connecting your Postgres.)
+
+Same product, same truth either way: in production your database is the system of
+record. See
 [Connect Your Database](./docs/data-sources.md) for both shapes.
 
 ## Configuration
 
-`Ablo({ ... })` takes three things: your schema, your key, and your database —
-the last either as `databaseUrl` here or as a signed
-[Data Source endpoint](./docs/data-sources.md) in your app. Every other option
-has correct defaults:
+`Ablo({ ... })` takes your schema, your key, and — in production — your database,
+either as an explicit `databaseUrl` here or as a signed
+[Data Source endpoint](./docs/data-sources.md) in your app. (`databaseUrl` is
+never auto-read from the environment; omit it to try Ablo against the hosted
+sandbox.) Every other option has correct defaults:
 
 | Option | Type | Default | Purpose |
 | --- | --- | --- | --- |
 | `schema` | `Schema` | — (required) | Typed model proxies (`ablo.<model>.*`) |
 | `apiKey` | `string \| ApiKeySetter \| null` | `process.env.ABLO_API_KEY` | Server key — a string, or an async function for rotation |
-| `databaseUrl` | `string \| null` | `process.env.DATABASE_URL` | Your Postgres, registered as the data plane. Server runtimes only — the SDK throws if it sees this in a browser. Omit it when your app exposes a signed [Data Source endpoint](./docs/data-sources.md) instead. |
+| `databaseUrl` | `string \| null` | `—` | Your Postgres, registered as the data plane. **Must be passed explicitly — it is not auto-read from the environment.** If you have a `DATABASE_URL` set for another tool (Prisma, Drizzle, docker-compose), `Ablo()` ignores it unless you pass `databaseUrl` explicitly. Server runtimes only — the SDK throws if it sees this in a browser. Omit it when your app exposes a signed [Data Source endpoint](./docs/data-sources.md) instead, or when trying Ablo against the hosted sandbox. |
 
 Keep `apiKey` in trusted server runtimes. In the browser, `<AbloProvider>`
 authenticates with the signed-in user's session; the raw-key path is gated

package/dist/cli.cjs

@@ -276803,7 +276803,7 @@ var ERROR_CODES = {
   malformed_subscription: wire("validation", 400, false, "The update_subscription payload was malformed; expected { syncGroups: string[] }."),
   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."),
+  model_claim_not_configured: client("claim", "Claiming requires the collaboration runtime, which the standard Ablo({ schema, apiKey }) client wires up for every model automatically \u2014 there is no per-model claim configuration to add. This appears only when a model proxy is constructed directly without that runtime (an internal/advanced path)."),
   // ── stale context / idempotency (409) ──────────────────────────────
   stale_context: wire("conflict", 409, true, "The write carried a readAt watermark that is now stale; re-read and retry."),
   idempotency_conflict: wire("conflict", 409, false, "The same Idempotency-Key was reused with a different request body."),
@@ -279942,6 +279942,14 @@ async function push(argv) {
 }
 
 // src/cli/migrate.ts
+var MIGRATE_USAGE = `  ablo migrate \u2014 provision your schema's tables in your own Postgres (DATABASE_URL)
+
+  Usage:
+    npx ablo migrate                      Create the synced-model tables (with row-level security)
+    npx ablo migrate --dry-run            Print the SQL without executing it
+    npx ablo migrate --output schema.sql  Write the SQL to a file instead of applying
+    npx ablo migrate --schema <path>      Use a schema file other than ablo/schema.ts
+    npx ablo migrate --export <name>      Use a named export other than \`schema\``;
 var DEFAULT_SCHEMA_PATH2 = "ablo/schema.ts";
 var DEFAULT_EXPORT2 = "schema";
 function parseMigrateArgs(argv) {
@@ -280478,7 +280486,10 @@ ${import_picocolors7.default.dim(url)}`, "Approve in your browser");
   s.message("Provisioning a sandbox key\u2026");
   const provRes = await fetch(`${AUTH_URL}/api/cli/provision-key`, {
     method: "POST",
-    headers: { authorization: `Bearer ${accessToken}` }
+    headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
+    // Pass the device_code so the server can scope the minted keys to the
+    // project the user picked at /cli (login project picker). Harmless if none.
+    body: JSON.stringify({ device_code: code.device_code })
   }).catch(() => null);
   if (!provRes || !provRes.ok) {
     s.stop("Could not provision a key.");
@@ -280706,6 +280717,39 @@ async function projects(argv) {
     );
     return;
   }
+  if (sub === "rename") {
+    const ref = argv[1];
+    const name = argv.slice(2).join(" ").trim();
+    if (!ref || ref.startsWith("-") || !name) {
+      console.error(import_picocolors9.default.red("  usage: ablo projects rename <slug|id> <new name>"));
+      process.exit(1);
+    }
+    const all = await fetchProjects();
+    const target = all.find((p2) => p2.slug === ref || p2.id === ref);
+    if (!target) {
+      console.error(import_picocolors9.default.red(`  No project "${ref}".`) + import_picocolors9.default.dim(" Run ablo projects list."));
+      process.exit(1);
+    }
+    if (target.default) {
+      console.error(import_picocolors9.default.red("  The default project cannot be renamed."));
+      process.exit(1);
+    }
+    const { status: status2, body } = await request(`/api/v1/projects/${target.id}`, requireKey(), {
+      method: "PATCH",
+      body: { name }
+    });
+    if (status2 !== 200) {
+      console.error(
+        import_picocolors9.default.red(`  Rename failed (${status2}): ${String(body.message ?? body.code ?? "")}`)
+      );
+      process.exit(1);
+    }
+    const updated = body;
+    console.log(
+      `  ${import_picocolors9.default.green("\u2713")} Renamed ${import_picocolors9.default.bold(updated.slug)} \u2192 ${import_picocolors9.default.bold(updated.name ?? updated.slug)} ${import_picocolors9.default.dim(`(${updated.id})`)}`
+    );
+    return;
+  }
   if (sub === "use") {
     const ref = argv[1];
     if (!ref) {
@@ -280733,7 +280777,9 @@ async function projects(argv) {
     return;
   }
   console.error(
-    import_picocolors9.default.red(`  unknown subcommand: ${sub}`) + import_picocolors9.default.dim(` (expected ${import_picocolors9.default.bold("list")}, ${import_picocolors9.default.bold("create")}, or ${import_picocolors9.default.bold("use")})`)
+    import_picocolors9.default.red(`  unknown subcommand: ${sub}`) + import_picocolors9.default.dim(
+      ` (expected ${import_picocolors9.default.bold("list")}, ${import_picocolors9.default.bold("create")}, ${import_picocolors9.default.bold("rename")}, or ${import_picocolors9.default.bold("use")})`
+    )
   );
   process.exit(1);
 }
@@ -282130,8 +282176,18 @@ async function drizzlePull(argv) {
 var LOGO = `
   ${brand("ablo")} ${import_picocolors18.default.dim("sync engine")}
 `;
+var SUBCOMMAND_USAGE = {
+  migrate: MIGRATE_USAGE
+};
 async function main() {
-  const command = process.argv[2];
+  let command = process.argv[2];
+  if (command && process.argv.slice(3).some((a) => a === "--help" || a === "-h")) {
+    if (SUBCOMMAND_USAGE[command]) {
+      console.log(SUBCOMMAND_USAGE[command]);
+      return;
+    }
+    command = void 0;
+  }
   if (command === "init") {
     await init(process.argv.slice(3));
   } else if (command === "login") {
@@ -282149,8 +282205,14 @@ async function main() {
   } else if (command === "webhooks") {
     await webhooks(process.argv.slice(3));
   } else if (command === "dev") {
-    console.log(import_picocolors18.default.dim("  `ablo dev` is now `ablo push --watch` \u2014 running that."));
-    await dev([...process.argv.slice(3), "--watch"]);
+    const devArgs = process.argv.slice(3);
+    const oneShot = devArgs.includes("--no-watch");
+    console.log(
+      import_picocolors18.default.dim(
+        oneShot ? "  `ablo dev --no-watch` is `ablo push` (push once, no watcher) \u2014 running that." : "  `ablo dev` is now `ablo push --watch` \u2014 running that."
+      )
+    );
+    await dev(oneShot ? devArgs : [...devArgs, "--watch"]);
   } else if (command === "check") {
     await check(process.argv.slice(3));
   } else if (command === "pull") {
@@ -282208,6 +282270,8 @@ async function main() {
     console.log(`    npx ablo pull prisma [path]            Generate schema.ts from a Prisma schema (keeps enums + relations)`);
     console.log(`    npx ablo pull drizzle <module>         Generate schema.ts from a Drizzle schema (keeps enums + relations)`);
     console.log(`    npx ablo check                         Check your existing database fits the schema (read-only, creates no tables)`);
+    console.log(`    npx ablo migrate                       Provision your synced-model tables in your own Postgres (DATABASE_URL)`);
+    console.log(`    npx ablo migrate --dry-run             Print the SQL without executing (preview)`);
     console.log(`    npx ablo push                          Upload your schema definition to Ablo (metadata only \u2014 rows stay in your DB)`);
     console.log(`    npx ablo push --force                  Allow destructive/unexecutable changes`);
     console.log(`    npx ablo push --rename a:b             Treat model "a" as renamed to "b"`);
@@ -282285,6 +282349,10 @@ function detectOrm(override) {
   }
   return "none";
 }
+function detectNextLayout() {
+  const useSrc = (0, import_fs12.existsSync)((0, import_path7.join)("src", "app")) || !(0, import_fs12.existsSync)("app") && (0, import_fs12.existsSync)("src");
+  return useSrc ? { appBase: (0, import_path7.join)("src", "app"), aliasBase: "src" } : { appBase: "app", aliasBase: "." };
+}
 async function chooseOption(name, flagValue, fallback, allowed, interactive, prompt) {
   if (flagValue !== void 0) {
     if (!allowed.includes(flagValue)) {
@@ -282384,7 +282452,8 @@ async function init(args = []) {
       "Non-interactive (no TTY / --yes)"
     );
   }
-  const abloDir = "ablo";
+  const layout = framework === "nextjs" ? detectNextLayout() : { appBase: "app", aliasBase: "." };
+  const abloDir = (0, import_path7.join)(layout.aliasBase, "ablo");
   (0, import_fs12.mkdirSync)(abloDir, { recursive: true });
   const created = [];
   let schemaSource = generateSchema();
@@ -282415,41 +282484,51 @@ async function init(args = []) {
   created.push(`${abloDir}/schema.ts${schemaNote}`);
   (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "index.ts"), generateSyncConfig(auth, storage));
   created.push(`${abloDir}/index.ts`);
+  (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "register.ts"), generateRegister());
+  created.push(`${abloDir}/register.ts`);
   const orm = detectOrm(opts.orm);
   if (storage === "endpoint") {
     (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "data-source.ts"), generateDataSource(orm));
     created.push(`${abloDir}/data-source.ts${orm === "drizzle" ? " (Drizzle)" : " (Prisma)"}`);
   }
   const envFile = framework === "nextjs" ? ".env.local" : ".env";
+  const resolvedKey = process.env.ABLO_API_KEY ? void 0 : resolveApiKey("sandbox");
+  const wireRealKey = envFile === ".env.local" && Boolean(resolvedKey);
+  const envBody = generateEnv(storage, { includeApiKey: !wireRealKey });
   if (!(0, import_fs12.existsSync)(envFile)) {
-    (0, import_fs12.writeFileSync)(envFile, generateEnv(storage));
+    (0, import_fs12.writeFileSync)(envFile, envBody);
     created.push(envFile);
   } else {
     const existing = (0, import_fs12.readFileSync)(envFile, "utf-8");
     if (!existing.includes("ABLO_")) {
-      (0, import_fs12.writeFileSync)(envFile, existing + "\n" + generateEnv(storage));
+      (0, import_fs12.writeFileSync)(envFile, existing + "\n" + envBody);
       created.push(`${envFile} ${import_picocolors18.default.dim("(appended)")}`);
     } else {
       created.push(`${envFile} ${import_picocolors18.default.dim("(already configured)")}`);
     }
   }
+  if (wireRealKey && resolvedKey) {
+    wireEnvLocal(resolvedKey);
+    created.push(`.env.local ${import_picocolors18.default.dim("(ABLO_API_KEY set from your login)")}`);
+  }
   if (agent) {
     (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "agent.ts"), generateAgent());
     created.push(`${abloDir}/agent.ts`);
   }
   if (framework === "nextjs") {
     if (storage === "endpoint") {
-      const webhookDir = (0, import_path7.join)("app", "api", "ablo", "webhooks");
+      const webhookDir = (0, import_path7.join)(layout.appBase, "api", "ablo", "webhooks");
       (0, import_fs12.mkdirSync)(webhookDir, { recursive: true });
       (0, import_fs12.writeFileSync)((0, import_path7.join)(webhookDir, "route.ts"), generateWebhookRoute(orm));
       created.push(`${webhookDir}/route.ts${orm === "prisma" ? " (Prisma mirror)" : " (add your database write)"}`);
     }
-    (0, import_fs12.writeFileSync)((0, import_path7.join)("app", "providers.tsx"), generateProviders());
-    created.push(`app/providers.tsx ${import_picocolors18.default.dim("(wrap app/layout.tsx in <Providers>)")}`);
-    const sessionDir = (0, import_path7.join)("app", "api", "ablo-session");
+    const providersPath = (0, import_path7.join)(layout.appBase, "providers.tsx");
+    (0, import_fs12.writeFileSync)(providersPath, generateProviders());
+    created.push(`${providersPath} ${import_picocolors18.default.dim(`(wrap ${(0, import_path7.join)(layout.appBase, "layout.tsx")} in <Providers>)`)}`);
+    const sessionDir = (0, import_path7.join)(layout.appBase, "api", "ablo-session");
     (0, import_fs12.mkdirSync)(sessionDir, { recursive: true });
     (0, import_fs12.writeFileSync)((0, import_path7.join)(sessionDir, "route.ts"), generateSessionRoute());
-    created.push(`app/api/ablo-session/route.ts ${import_picocolors18.default.dim("(wire your auth)")}`);
+    created.push(`${(0, import_path7.join)(sessionDir, "route.ts")} ${import_picocolors18.default.dim("(wire your auth)")}`);
   }
   if (framework !== "vanilla") {
     (0, import_fs12.writeFileSync)((0, import_path7.join)(abloDir, "TaskList.tsx"), generateComponent());
@@ -282478,7 +282557,7 @@ async function init(args = []) {
       `Provision your DB: ${import_picocolors18.default.bold("npx ablo migrate")} (creates your Ablo-model tables + the adapter tables; keep your own migrations for everything else), then mount ${import_picocolors18.default.bold(`${abloDir}/data-source.ts`)} at ${import_picocolors18.default.bold("/api/ablo/source")}`
     ],
     ...framework === "nextjs" ? [
-      `Wrap ${import_picocolors18.default.bold("app/layout.tsx")} in ${import_picocolors18.default.bold("<Providers>")} (app/providers.tsx) and add your auth to ${import_picocolors18.default.bold("app/api/ablo-session/route.ts")}`
+      `Wrap ${import_picocolors18.default.bold((0, import_path7.join)(layout.appBase, "layout.tsx"))} in ${import_picocolors18.default.bold("<Providers>")} (${(0, import_path7.join)(layout.appBase, "providers.tsx")}) and add your auth to ${import_picocolors18.default.bold((0, import_path7.join)(layout.appBase, "api", "ablo-session", "route.ts"))}`
     ] : [],
     `Run ${import_picocolors18.default.bold(`${pm} run dev`)} and open two browser tabs \u2014 changes sync in real-time`,
     ...agent ? [
@@ -282557,14 +282636,31 @@ export const sync = Ablo({
   apiKey: process.env.ABLO_API_KEY,${databaseLine}${authLine}
   schema,
 });
+
+// Name the client's type off the constructed value \u2014 the overload resolves at
+// this call site, so this carries the full typed surface. (Like tRPC's
+// \`typeof appRouter\`, Drizzle's \`typeof db\`.) Prefer this over \`ReturnType<typeof Ablo>\`.
+export type Sync = typeof sync;
+`;
+}
+function generateRegister() {
+  return `import type { schema } from './schema';
+
+declare module '@abloatai/ablo' {
+  interface Register {
+    Schema: typeof schema;
+  }
+}
+
+export {};
 `;
 }
-function generateEnv(storage) {
+function generateEnv(storage, opts = {}) {
+  const { includeApiKey = true } = opts;
   const databaseBlock = storage === "direct" ? "# Your Postgres \u2014 the system of record. The client registers this connection\n# (sent once over TLS, stored sealed) and every row lives HERE, never with Ablo.\n# Use a dedicated non-superuser role; the browser never sees this value.\nDATABASE_URL=postgres://user:password@host:5432/db\n" : "# Used by ablo/data-source.ts (your DB endpoint) + `ablo migrate` \u2014 NOT the client.\n# Ablo never sees it; the browser never sees it. Your DB stays in your app.\nDATABASE_URL=postgres://user:password@host:5432/db\n";
   const webhookBlock = storage === "endpoint" ? "# Signing secret for the webhook receiver (app/api/ablo/webhooks/route.ts).\n# Ablo mints this when you register the endpoint's URL (POST /v1/webhook_endpoints\n# or the dashboard) and returns it once \u2014 paste it here.\nABLO_WEBHOOK_SECRET=whsec_your_endpoint_secret_here\n" : "";
-  return `# Ablo Sync Engine \u2014 use a sk_test_ key for local dev (\`npx ablo dev\`)
-ABLO_API_KEY=sk_test_your_key_here
-${webhookBlock}${databaseBlock}`;
+  const apiKeyBlock = includeApiKey ? "# Ablo Sync Engine \u2014 use a sk_test_ key for local dev (`npx ablo push`)\nABLO_API_KEY=sk_test_your_key_here\n" : "";
+  return `${apiKeyBlock}${webhookBlock}${databaseBlock}`;
 }
 function generateDataSource(orm) {
   return orm === "drizzle" ? drizzleDataSourceScaffold() : prismaDataSourceScaffold();

package/dist/client/Ablo.js

@@ -42,7 +42,7 @@ import { createProtocolClient, } from './ApiClient.js';
 // Value import is cycle-safe: httpClient.js only value-imports ApiClient.js,
 // which imports this module type-only.
 import { createAbloHttpClient, } from './httpClient.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, } from './auth.js';
+import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfDatabaseUrlEnvIgnored, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
 import { shouldUseInMemoryPersistence, } from './persistence.js';
 import { createModelProxy } from './createModelProxy.js';
@@ -725,6 +725,9 @@ export function Ablo(options) {
         dangerouslyAllowBrowser: options.dangerouslyAllowBrowser,
     });
     const { logger = consoleLogger } = internalOptions;
+    // Nudge (once) if a stray DATABASE_URL is in the env but `databaseUrl` wasn't
+    // passed — the env value is no longer auto-adopted (see resolveDatabaseUrl).
+    warnIfDatabaseUrlEnvIgnored(authInput, (m) => logger.warn(m));
     const schema = options.schema;
     const url = resolveBaseURL(authInput);
     // 1. Derive config from schema
@@ -1370,6 +1373,18 @@ export function Ablo(options) {
             },
             waitFor: (target, waitOptions) => publicClaims.waitFor({ model: target.model, id: target.id }, waitOptions),
             selfParticipantId: participantId,
+            selfParticipantKind: kind,
+            // Read-interest / write-intent enrolment for the typed surface.
+            // `enterScope`/`pinScope` resolve the `{ [schemaKey]: id }` scope
+            // through the SAME resolver the claim path uses, landing this client in
+            // the entity-scoped group the holder's claim presence fans out on.
+            // Return the store promise so the claim write path can AWAIT pinScope
+            // BEFORE acquiring the lease (closing the subscribe-vs-broadcast race);
+            // read-interest callers (`retrieve`/`claim.state`) still `void` it and
+            // stay fire-and-forget. SOFT either way — the store swallows reconcile
+            // errors so read interest never makes a read reject or stall.
+            enterScope: (scope) => store.enterScope(scope),
+            pinScope: (scope) => store.pinScope(scope),
         });
     }
     const commits = {

package/dist/client/ApiClient.js

@@ -6,7 +6,7 @@
  * nouns directly to HTTP routes on sync-server.
  */
 import { AbloClaimedError, AbloAuthenticationError, AbloConnectionError, AbloValidationError, claimedError, translateHttpError, } from '../errors.js';
-import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, } from './auth.js';
+import { assertBrowserSafety, readProcessEnv, resolveApiKey, resolveApiKeyValue, resolveAuthToken, resolveBaseURL, resolveBootstrapBaseUrl, resolveDatabaseUrl, warnIfDatabaseUrlEnvIgnored, } from './auth.js';
 import { registerDataSource } from './registerDataSource.js';
 import { toSeconds } from '../utils/duration.js';
 import { assertWriteOptions } from './writeOptionsSchema.js';
@@ -17,6 +17,9 @@ export function createProtocolClient(options) {
     const configuredApiKey = resolveApiKey(authInput);
     const configuredAuthToken = resolveAuthToken(authInput);
     const configuredDatabaseUrl = resolveDatabaseUrl(authInput);
+    // Nudge (once) if a stray DATABASE_URL is in the env but `databaseUrl` wasn't
+    // passed — no logger on this path, so the helper falls back to console.warn.
+    warnIfDatabaseUrlEnvIgnored(authInput);
     assertBrowserSafety({
         apiKey: configuredApiKey,
         databaseUrl: configuredDatabaseUrl,

package/dist/client/auth.d.ts

@@ -45,12 +45,17 @@ export declare function resolveAuthToken(input: AuthResolveInput): string | null
 /**
  * Resolve the direct-URL connector's Postgres connection string.
  *
- * The default Data Source path should not call this: the customer keeps
- * `DATABASE_URL` in their app and exposes `dataSource(...)`. This helper exists
- * only for the opt-in direct connector where Ablo registers a dedicated tenant
- * database. Returns null for Ablo-managed storage.
+ * `databaseUrl` is an EXPLICIT, opt-in option: Ablo registers a dedicated
+ * tenant database only when the caller passes it to `Ablo(...)`. It is NOT
+ * read from `process.env.DATABASE_URL` — per this module's invariant
+ * (`ABLO_API_KEY` is the only environment fallback), an app's `DATABASE_URL`
+ * (commonly set for Prisma/Drizzle/docker) must never silently flip the client
+ * into connection-string mode. The default Data Source path keeps `DATABASE_URL`
+ * in the app and exposes `dataSource(...)`; that path leaves this null.
+ * `warnIfDatabaseUrlEnvIgnored` nudges callers who set the env but omitted the option.
  */
 export declare function resolveDatabaseUrl(input: AuthResolveInput): string | null;
+export declare function warnIfDatabaseUrlEnvIgnored(input: AuthResolveInput, warn?: (message: string) => void): void;
 export declare const ABLO_HOSTED_API_DOMAIN = "api.abloatai.com";
 export declare const ABLO_HOSTED_HTTP_BASE_URL = "https://api.abloatai.com";
 export declare const ABLO_DEFAULT_BASE_URL = "https://api.abloatai.com";

package/dist/client/auth.js

@@ -30,13 +30,48 @@ export function resolveAuthToken(input) {
 /**
  * Resolve the direct-URL connector's Postgres connection string.
  *
- * The default Data Source path should not call this: the customer keeps
- * `DATABASE_URL` in their app and exposes `dataSource(...)`. This helper exists
- * only for the opt-in direct connector where Ablo registers a dedicated tenant
- * database. Returns null for Ablo-managed storage.
+ * `databaseUrl` is an EXPLICIT, opt-in option: Ablo registers a dedicated
+ * tenant database only when the caller passes it to `Ablo(...)`. It is NOT
+ * read from `process.env.DATABASE_URL` — per this module's invariant
+ * (`ABLO_API_KEY` is the only environment fallback), an app's `DATABASE_URL`
+ * (commonly set for Prisma/Drizzle/docker) must never silently flip the client
+ * into connection-string mode. The default Data Source path keeps `DATABASE_URL`
+ * in the app and exposes `dataSource(...)`; that path leaves this null.
+ * `warnIfDatabaseUrlEnvIgnored` nudges callers who set the env but omitted the option.
  */
 export function resolveDatabaseUrl(input) {
-    return input.options.databaseUrl ?? input.env.DATABASE_URL ?? null;
+    return input.options.databaseUrl ?? null;
+}
+/**
+ * One-time migration nudge for the dropped `DATABASE_URL` env fallback.
+ *
+ * Earlier versions silently adopted `process.env.DATABASE_URL` when `databaseUrl`
+ * was not passed, registering a direct connector behind the caller's back — which
+ * surprised any app that keeps `DATABASE_URL` for another tool (Prisma, Drizzle,
+ * docker-compose) and, on localhost, tried to register a database Ablo's cloud
+ * cannot reach. The env value is now ignored; this points the developer at the
+ * explicit option instead of flipping their mode for them. Warns once per process
+ * so it never spams, and falls back to `console.warn` when no logger is supplied
+ * (the `transport: 'api'` client has none).
+ */
+let warnedDatabaseUrlEnvIgnored = false;
+export function warnIfDatabaseUrlEnvIgnored(input, warn) {
+    if (warnedDatabaseUrlEnvIgnored)
+        return;
+    if (input.options.databaseUrl != null)
+        return;
+    const envUrl = input.env.DATABASE_URL;
+    if (typeof envUrl !== 'string' || envUrl.length === 0)
+        return;
+    warnedDatabaseUrlEnvIgnored = true;
+    const message = 'Found DATABASE_URL in the environment but `databaseUrl` was not passed to Ablo(...). ' +
+        'Ablo no longer auto-adopts DATABASE_URL — the environment value is ignored. ' +
+        'To register your Postgres directly, pass `databaseUrl: process.env.DATABASE_URL` explicitly; ' +
+        'otherwise ignore this (the hosted sandbox and signed Data Source endpoints need no databaseUrl).';
+    if (warn)
+        warn(message);
+    else if (typeof console !== 'undefined')
+        console.warn('[sync]', message);
 }
 export const ABLO_HOSTED_API_DOMAIN = 'api.abloatai.com';
 export const ABLO_HOSTED_HTTP_BASE_URL = `https://${ABLO_HOSTED_API_DOMAIN}`;

package/dist/client/createModelProxy.d.ts

@@ -136,6 +136,31 @@ export interface ModelCollaboration<T> {
      * from "someone else holds it" in `claimOrWait`.
      */
     readonly selfParticipantId: string;
+    /**
+     * The local participant's kind (`'user' | 'agent' | 'system'`). Used to
+     * stamp the synthesized self-claim returned from `claim.state` when the
+     * LOCAL proxy holds the lease (server presence frames exclude one's own
+     * claims, so the holder must build its own view).
+     */
+    readonly selfParticipantKind?: 'user' | 'agent' | 'system';
+    /**
+     * Subscribe the connection to a scope's sync group(s) (read-interest).
+     * The typed surface calls this on single-entity reads/claim observation so
+     * a Node/agent client lands in the SAME entity-scoped group the holder's
+     * claim presence fans out on — otherwise a peer subscribed only to
+     * `org:`/`user:` groups never sees claim broadcasts. Fire-and-forget and
+     * SOFT: read interest is best-effort and must never make a read reject or
+     * stall (see `AreaOfInterestManager.reconcile`). Optional so minimal test
+     * doubles can omit it. Forwards to `BaseSyncedStore.enterScope`.
+     */
+    enterScope?(scope: Record<string, string>): void | Promise<void>;
+    /**
+     * Pin a scope's sync group(s) (write-intent / prominence): a row this
+     * client holds an active claim on stays subscribed regardless of
+     * navigation. Same fire-and-forget, soft semantics as `enterScope`.
+     * Forwards to `BaseSyncedStore.pinScope`.
+     */
+    pinScope?(scope: Record<string, string>): void | Promise<void>;
 }
 export interface ClaimTargetOptions<T = Record<string, unknown>> {
     /** Phase shown to observers while held. Defaults to `'editing'`. */