@abloatai/ablo 0.9.2 → 0.9.3

package/docs/mcp.md

@@ -83,7 +83,7 @@ Per-client walkthroughs:
 | `get_recipe` | Returns the full markdown of one doc by name (e.g. `readme`, `quickstart`, `schema-contract`, `integration-guide`, `api`, `guarantees`). |
 | `get_api_surface` | Returns the structured export list for an SDK subpath (`@abloatai/ablo`, `./react`, `./schema`, `./testing`, …). Call with no argument to list every subpath. |
 | `validate_schema` | Lints `defineSchema` source against the DSL rules (camelCase fields, lowercase model keys, `scope`/`grants` sync groups, valid `load` strategies, no legacy builders) and returns a structured issue list. Runs no code. |
-| `scaffold_app` | Emits a starter file tree for a schema-first integration — `next`, `node-agent`, or `plain`, with `managed` or `data-source` storage. |
+| `scaffold_app` | Emits a starter file tree for a schema-first integration — `next`, `node-agent`, or `plain`, with a `data-source` (your own database) endpoint. |
 
 #### Resources
 

package/docs/quickstart.md

@@ -1,74 +1,121 @@
 # Quickstart
 
-Start building with Ablo in two steps: install, then declare one model and write
-through its generated client.
+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.
 
-If you already have a backend and database, still start here. The SDK call shape
-is the same; [Integration Guide](./integration-guide.md) explains when to use
-Ablo-managed state versus a Data Source that calls your existing API service.
-
-## 1. Install and set a sandbox key
+## 1. Install and get a key
 
 ```bash
 npm install @abloatai/ablo
+npx ablo login
+```
+
+`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:
+
+```bash
 export ABLO_API_KEY=sk_test_...
 ```
 
-`ABLO_API_KEY` is for trusted server runtimes. Browser apps should use the React
-provider with a scoped session route, not a bundled API key.
+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.
 
-## 2. Declare schema and write state
+## 2. Declare your Ablo schema
 
-Your schema is the contract. It generates `ablo.<model>` methods for app code,
-server actions, agents, React reads, and Data Source requests.
+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
+coordinates; your auth, billing, and other tables stay in your own Drizzle schema,
+owned by your own migrations.
 
 ```ts
-import Ablo from '@abloatai/ablo';
+// ablo/schema.ts
 import { defineSchema, model, z } from '@abloatai/ablo/schema';
 
-const schema = defineSchema({
+export const schema = defineSchema({
   weatherReports: model({
     location: z.string(),
     status: z.enum(['pending', 'ready']),
     forecast: z.string().optional(),
   }),
 });
+```
+
+## 3. Point Ablo at your database
+
+The client takes your schema, your key, and your `DATABASE_URL`. On first
+connect Ablo registers the connection (sent once over TLS, stored sealed, never
+echoed back) and from then on commits every write directly to your Postgres.
+
+```bash
+# .env — server runtime only, never the browser
+DATABASE_URL=postgres://ablo_app:...@host:5432/db
+ABLO_API_KEY=sk_test_...
+```
+
+```ts
+// ablo/client.ts
+import Ablo from '@abloatai/ablo';
+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
 });
+```
+
+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.
+
+Don't want a connection string to leave your infrastructure? Keep
+`DATABASE_URL` in your app only and expose one signed **Data Source endpoint**
+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
+
+```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 (test mode), writes ABLO_API_KEY to
+                   # .env.local, and re-pushes on every save — the dev loop
+```
+
+`ablo dev` (or one-shot `npx 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`."
+
+## 5. Write through the model
+
+The rows land in your Postgres; every connected client sees them live.
+
+```ts
+import { ablo } from './ablo/client';
+
 await ablo.ready();
 
 const created = await ablo.weatherReports.create({
-  data: {
-    location: 'Stockholm',
-    status: 'pending',
-  },
+  data: { location: 'Stockholm', status: 'pending' },
 });
 
 const updated = await ablo.weatherReports.update({
   id: created.id,
-  data: {
-    status: 'ready',
-    forecast: 'Light rain, 13C',
-  },
+  data: { status: 'ready', forecast: 'Light rain, 13C' },
 });
 
-console.log({ id: updated.id, status: updated.status });
-```
-
-Expected output:
-
-```txt
-{ id: '...', status: 'ready' }
-```
-
-## Run the example
-
-```bash
-cd packages/sync-engine
-ABLO_API_KEY=sk_test_... npx tsx examples/quickstart.ts
+console.log({ id: updated.id, status: updated.status }); // { id: '...', status: 'ready' }
 ```
 
 ## Add coordination for slow work
@@ -146,5 +193,5 @@ Keep using the schema client for app and agent writes.
 - [Schema Contract](./schema-contract.md) explains what the schema drives across SDK, React, agents, Data Source, and schema push.
 - [Guarantees](./guarantees.md) explains what confirmed writes and stale checks mean.
 - [Client Behavior](./client-behavior.md) covers errors, retries, and public imports.
-- [Connect Your Database](./data-sources.md) covers the optional route for teams keeping rows in their own database.
+- [Connect Your Database](./data-sources.md) covers both connection shapes — `databaseUrl` and the signed Data Source endpoint.
 - [AI SDK Tool](./examples/ai-sdk-tool.md) shows the same write path inside a tool call.

package/docs/schema-contract.md

@@ -88,10 +88,8 @@ the fresh row. Reads stay open; only acting on the row serializes.
 
 ## Storage boundary
 
-Every schema model needs a backing store:
-
-- Use Ablo-managed state when the row can live in Ablo.
-- Use a Data Source when your app database remains canonical.
+Every schema model is backed by your own database through a Data Source — Ablo
+coordinates each write and your app commits it to your Postgres.
 
 Do not pass a database URL to `Ablo(...)`. Trusted runtimes use `ABLO_API_KEY`.
 Browser code goes through `<AbloProvider>` or a scoped session route, never a raw

package/llms-full.txt

@@ -0,0 +1,360 @@
+# Ablo Full Context
+
+Ablo is the state coordination layer for apps where humans and agents edit the same data.
+
+Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist to the database, coordinate with concurrent human or agent work, and leave an audit trail.
+
+The product surface should read like Stripe, Turbopuffer, or Reducto: one product-name import, models by dot access, optional subpaths only for schema, React, and tests.
+
+```ts
+import Ablo from '@abloatai/ablo';
+```
+
+## Public Surface
+
+Public imports:
+
+- `@abloatai/ablo` — `Ablo`, errors, typed model clients, claims, `dataSource`, and advanced schema-less protocol models.
+- `@abloatai/ablo/schema` — `defineSchema`, `model`, `z`, relations, schema types.
+- `@abloatai/ablo/react` — React provider and hooks.
+- `@abloatai/ablo/testing` — test harnesses and mocks.
+
+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).
+
+The canonical integration doc is `integration-guide`. It explains the end-to-end
+path for schema, React selectors, your Data Source-backed database, multiplayer,
+and agent workers. Use it before inventing a new setup
+flow.
+
+## Production Guarantees
+
+`wait: 'confirmed'` resolves after the server accepts the write. Schema model
+writes are optimistic; a server rejection rolls back local state and raises a
+typed `AbloError`.
+
+Use `snapshot(...)` and `readAt` when an agent write depends on state it already
+read. `onStale: 'reject'` prevents lost updates by rejecting if the target
+changed after the snapshot.
+
+Claims are live coordination signals, not database locks. Schema clients wait
+from the realtime claim stream. Schema-less HTTP clients must pass an explicit
+`claimedPollInterval` for `ifClaimed: 'wait'`; no hidden hard-coded polling.
+
+Agent run bookkeeping is internal. Most users should not create run ledger
+records or scoped access credentials manually.
+
+## Primary App Path
+
+Declare models in a schema, then use typed model clients:
+
+```ts
+import Ablo from '@abloatai/ablo';
+import { defineSchema, model, z } from '@abloatai/ablo/schema';
+
+const schema = defineSchema({
+  weatherReports: model({
+    id: z.string(),
+    location: z.string(),
+    status: z.enum(['pending', 'ready']),
+    forecast: z.string().optional(),
+    updatedAt: z.string(),
+  }),
+  projects: model({
+    id: z.string(),
+    name: z.string(),
+  }),
+});
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+const report = await ablo.weatherReports.retrieve({ id: 'report_stockholm' });
+if (!report) throw new Error('Row not found');
+
+await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+const updated = await ablo.weatherReports.update({
+  id: claim.data.id,
+  data: { status: 'ready', forecast: await getForecast(claim.data) },
+  wait: 'confirmed',
+});
+```
+
+The normal app API (every verb takes ONE options object):
+
+- `ablo.<model>.retrieve({ id })` — async read of one row from the server
+- `ablo.<model>.list({ where })` — async read of many from the server
+- `ablo.<model>.get(id)` / `getAll({ where })` / `getCount({ where })` — synchronous local-graph reads (reactive in React render)
+- `ablo.<model>.create({ data, id? })`
+- `ablo.<model>.update({ id, data })`
+- `ablo.<model>.delete({ id })`
+- `await using claim = await ablo.<model>.claim({ id })` — disposable claim handle; read the fresh row off `claim.data`; auto-releases on scope exit
+- `ablo.<model>.claim.state({ id })` / `claim.queue({ id })` / `claim.release({ id })` / `claim.reorder({ id, order })`
+
+The synchronous reads (`getAll`/`getCount`) accept `where`, `filter`, `orderBy`,
+`limit`, `offset`, and `state`; state defaults to `'live'`, with `'archived'`
+and `'all'` for lifecycle-aware reads.
+
+Use `ablo.model<T>(name)` only when the caller intentionally does not have a schema, such as custom server agents, MCP routes, migration scripts, or generic admin tools.
+
+React reads should use selector `useAblo`:
+
+```tsx
+const report = useAblo((ablo) => ablo.weatherReports.get(id)) ?? serverReport;
+const visibleReports = useAblo((ablo) =>
+  ablo.weatherReports.getAll({ where: { projectId } }),
+);
+```
+
+Use zero-argument `useAblo()` only for callbacks, effects, and writes that need
+the provider-owned client:
+
+```tsx
+const ablo = useAblo();
+await ablo?.weatherReports.update({ id, data: patch, wait: 'confirmed' });
+```
+
+Treat `useQuery`, `useOne`, `useReader`, and `useMutate` as compatibility hooks
+for older string-keyed integrations. Do not teach them as the first React API.
+
+## Multiplayer
+
+Multiplayer is an effect of the normal model API, not a separate setup path.
+When human UI, server actions, and agents use the same
+`Ablo({ schema, apiKey })` client and write through `ablo.<model>`, Ablo
+coordinates the shared model stream:
+
+- confirmed model writes fan out as realtime deltas,
+- React hooks read the latest row and active claims,
+- claims announce active work before a commit,
+- `snapshot(...)` plus `readAt` protects against stale writes.
+
+Direct database writes outside Ablo are not coordinated until the app reports
+them through Data Source events. In Data Source mode, writes made through Ablo
+still coordinate normally because Ablo sends the signed commit request, receives
+canonical rows, and fans out the resulting deltas.
+
+For existing Python backends, keep the Python service layer and database as the
+source of truth. Add one signed Data Source endpoint, keep initial page loads on
+existing APIs if needed, use `useAblo((ablo) => ablo.<model>.get(id)) ?? serverRow`
+for live rows, then migrate buttons one at a time from direct Python endpoint
+writes to `ablo.<model>.update(...)`.
+
+This applies to any API-backed app: Python, Rails, Go, or Node. The backend keeps
+its service layer and DB credentials. Ablo gets a Data Source endpoint and uses
+`ABLO_API_KEY`, not a database URL.
+
+## Client Behavior
+
+Important options: `schema`, `apiKey`, `baseURL`, `persistence`, `fetch`,
+`defaultHeaders`, `defaultQuery`, `logger`, and `dangerouslyAllowBrowser`.
+
+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.
+
+Important per-write options: `wait`, `readAt`, `onStale`,
+`idempotencyKey`, and `timeout`.
+
+Errors: `AbloAuthenticationError`, `AbloPermissionError`, `AbloRateLimitError`,
+`AbloIdempotencyError`, `AbloConnectionError`, `AbloValidationError`,
+`AbloServerError`, `AbloStaleContextError`, and `AbloClaimedError`.
+
+Retry transport failures and 5xx with backoff only when the operation is
+idempotent. Do not blindly retry validation, permission, idempotency, claimed, or
+stale-context errors without changing the request.
+
+## Sandboxes
+
+There are two sandbox surfaces:
+
+- Public `/sandbox` is a deterministic visual playground. It demonstrates shared
+  state, active claims, stale-write rejection, receipts, and deltas without
+  making real Ablo calls. It is agent-first: it should expose a prompt that can
+  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 test mode for an org. It has an isolated sync group prefix,
+  can mint `sk_test_*` keys, and can be reset without touching live state.
+
+Additional org sandboxes can start blank or copy live configuration. Keep
+customer production traffic on `sk_live_*`; use `sk_test_*` for app setup, Data
+Source endpoint wiring, and agent integration testing.
+
+The coding-agent handoff should ask for a narrow integration: one schema model,
+one Ablo client module, one React selector read, one typed model write with
+`readAt`/`onStale: 'reject'`/`wait: 'confirmed'`, and one smoke test where two
+writers prove claim/stale behavior.
+
+## Data Sources
+
+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
+  `.env.local` automatically. Check the environment and `.env.local` before
+  asking the human for a key.
+
+Do not ask customers to paste their app database URL into Ablo. If their app
+database is canonical, they expose a Data Source endpoint and keep database
+credentials inside their app.
+
+Every schema model is backed by the customer's own database. The SDK methods
+`ablo.<model>.create/update/delete` produce a signed commit request to the
+customer's Data Source route, and that route writes the app database.
+
+When the customer's database is canonical, expose one signed source route:
+
+```ts
+import { dataSourceNext } from '@abloatai/ablo/source/next';
+import { prismaDataSource } from '@abloatai/ablo/source';
+import { schema } from './ablo.schema';
+import { prisma } from './lib/prisma';
+
+// The adapter owns commit / idempotency / outbox — no hand-written commit.
+export const { POST } = dataSourceNext({
+  schema,
+  apiKey: process.env.ABLO_API_KEY!,
+  adapter: prismaDataSource(prisma, schema), // or drizzleDataSource(db, schema) / kyselyDataSource(db, schema)
+});
+```
+
+Commit request shape:
+
+```ts
+{
+  type: 'commit',
+  clientTxId: 'tx_...',
+  operations: [
+    { type: 'UPDATE', model: 'weatherReports', id: 'report_stockholm', input, readAt, onStale: 'reject' },
+  ],
+  scope: { participantId, participantKind, organizationId, requiredSyncGroups, mode: 'live' },
+}
+```
+
+Return `{ rows }` for normal apps or `{ deltas }` for sources that already
+compute canonical change events. External writes come back through the source
+`events` handler or `POST /api/source/events`.
+
+## Advanced Schema Options
+
+Teach schema as model fields and relations first:
+
+```ts
+const schema = defineSchema({
+  weatherReports: model({
+    id: z.string(),
+    location: z.string(),
+  }),
+});
+```
+
+Advanced helpers such as `mutable`, `readOnly`, `field`, `indexed`, query definitions, `load` strategies, parent metadata, and sync-group formats are still part of the schema package for offline/cache/indexing-heavy apps. Do not put them in the first example unless the user asks for local persistence, offline sync, custom loading, or low-level indexing behavior.
+
+## Server Agent Path
+
+Server agents should import the same schema as the app and use the same model
+methods. Claim the row around slow work, then write through `ablo.<model>`.
+
+```ts
+import Ablo from '@abloatai/ablo';
+
+const ablo = Ablo({ schema, apiKey: process.env.ABLO_API_KEY });
+
+await using claim = await ablo.weatherReports.claim({ id: 'report_stockholm' });
+const forecast = await getForecast(claim.data);
+await ablo.weatherReports.update({
+  id: claim.data.id,
+  data: { status: 'ready', forecast },
+  wait: 'confirmed',
+});
+```
+
+Do not require users to manually create protocol bookkeeping objects in the
+common agent path.
+
+## Model
+
+Every model read returns state plus coordination metadata:
+
+```ts
+type ModelRead<T> = {
+  data: T;
+  stamp: number;
+  claims: ModelClaim[];
+};
+```
+
+`stamp` is the state watermark. Pass it to writes as `readAt`.
+
+`claims` lists active work on the target. Reads are allowed while another participant is working. The caller decides whether to return, fail, or wait.
+
+## Claimed Behavior
+
+Claimed behavior is explicit:
+
+- `ifClaimed: 'return'` returns the current claims with the read.
+- `ifClaimed: 'fail'` throws `AbloClaimedError`.
+- `ifClaimed: 'wait'` waits for matching claims to clear.
+
+Schema clients use the realtime claim stream for waits.
+
+Schema-less HTTP clients cannot know when a claim clears unless the caller opts into polling. When using `ifClaimed: 'wait'` over HTTP, provide `claimedPollInterval` and usually `claimedTimeout`.
+
+```ts
+await api.model('reports').retrieve({
+  id: 'report_stockholm',
+  ifClaimed: 'wait',
+  claimedPollInterval: 1_000,
+  claimedTimeout: 30_000,
+});
+```
+
+No hidden hard-coded claimed polling. `claimedTimeout` is a maximum wait, not the coordination mechanism.
+
+## Write
+
+Use model methods as the normal write path:
+
+```ts
+const snap = ablo.snapshot({ weatherReports: 'report_stockholm' });
+const updated = await ablo.weatherReports.update({
+  id: 'report_stockholm',
+  data: { status: 'ready' },
+  readAt: snap.stamp,
+  onStale: 'reject',
+  wait: 'confirmed',
+});
+```
+
+Write checks:
+
+- authorization
+- stale state via `readAt`
+- active claim conflicts
+- idempotency when an idempotency key is provided
+
+Use `commits.create(...)` only for low-level batch writes.
+
+## Receipt
+
+Schema model writes return the updated row. Passing `wait: 'confirmed'` waits for
+the server confirmation before resolving. Lower-level model writes return a
+receipt object for custom runtimes that need protocol-level proof.
+
+## Interaction Model
+
+The common agent run is:
+
+1. Read the row through `ablo.<model>.retrieve({ id })` (or `list({ where })`).
+2. Claim it: `await using claim = await ablo.<model>.claim({ id })` — waits if held, hands you `claim.data`.
+3. Do the slow work from `claim.data`.
+4. Write with `ablo.<model>.update({ id, data })`.
+5. The claim auto-releases when it goes out of scope (`await using`).
+
+The underlying primitives are Model, Claim, Commit, and Receipt. Most schema
+users should not call `commits.create(...)` directly.
+
+## Public HTTP Routes
+
+- `GET    /v1/models/{model}/{id}` — read state plus active claims
+- `POST   /v1/commits` — apply mutations
+Use `Authorization: Bearer <api key>` for platform calls.

package/llms.txt

@@ -10,7 +10,9 @@ Use AI SDK for the agent loop. Use Ablo when agent reads and writes must persist
 
 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.
 
-Then PUSH — this is the step everything depends on. The server keeps its OWN copy of the schema. After you create or change `ablo/schema.ts`, run `npx ablo push` (one-shot). Until you push, EVERY write to a new or changed model fails with `server_execute_unknown_model`. (Or keep `npx ablo dev` running — it pushes on save.)
+Second: make sure a key exists. Check `ABLO_API_KEY` in the environment, then `.env.local`. If neither has one, 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` 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` (test mode) 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).
 
 ## Use this API
 
@@ -50,7 +52,7 @@ hosted schema push, and schema-version gating. Do not invent a parallel
 string-keyed write path for rows that belong to a schema model.
 
 For full integrations, use `integration-guide` as the canonical doc. It covers
-the same model API across Ablo-managed state, Data Source-backed app databases,
+the same model API across your own Data Source-backed app databases,
 React selectors, multiplayer, and future agent workers.
 
 Reads come in two flavors, and you pick by whether you can wait. `retrieve({ id })`
@@ -116,23 +118,25 @@ A schema is model fields and relations. Advanced schema helpers such as `mutable
 
 Do not add `databaseURL` to `Ablo(...)`. Application and agent code use `ABLO_API_KEY`.
 
-Every schema model has a backing store. By default, Ablo stores rows for declared models, so `ablo.<model>.create/update/delete` write to Ablo-managed state. If the customer database is canonical, expose a Data Source endpoint. With Prisma or Drizzle this is ONE line — pass an ORM `adapter` and it owns the transaction, idempotency, and outbox (no hand-written `commit`/`events`):
+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.
 
 ```ts
 // app/api/ablo/source/route.ts
 import { dataSourceNext } from '@abloatai/ablo/source/next';
-import { prismaDataSource } from '@abloatai/ablo/source';
+import { drizzleDataSource } from '@abloatai/ablo/source/drizzle';
 import { schema } from '@/ablo/schema';
-import { prisma } from '@/lib/prisma';
+import { db } from '@/db';
+
+export const runtime = 'nodejs'; // the route touches your database
 
 export const { POST } = dataSourceNext({
   schema,
   apiKey: process.env.ABLO_API_KEY!,
-  adapter: prismaDataSource(prisma, schema), // or drizzleDataSource(db, schema)
+  adapter: drizzleDataSource(db, schema), // or prismaDataSource(prisma, schema) / kyselyDataSource(db, schema)
 });
 ```
 
-`npx ablo init` generates this file for you (see CLI below). Customer-owned app database credentials stay private — Ablo only calls the endpoint.
+`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.
 
 ## Sandboxes
 
@@ -163,6 +167,7 @@ Import from these public paths only:
 - `@abloatai/ablo/source` — `dataSource`, the `DataSourceAdapter` spine, `prismaDataSource`. For a customer-canonical Data Source endpoint.
 - `@abloatai/ablo/source/next` — `dataSourceNext` (Next.js App Router `{ POST }`).
 - `@abloatai/ablo/source/drizzle` — `drizzleDataSource`.
+- `@abloatai/ablo/source/kysely` — `kyselyDataSource`.
 - `@abloatai/ablo/source/conformance` — `runDataSourceTests` to prove a custom adapter/handler.
 
 Do not teach `/api`, `/agent`, `/ai-sdk`, `/core`, `/realtime`, or internal subpaths. (`/source` IS public — it's the Data Source endpoint surface above.)
@@ -172,8 +177,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.
-- Authenticate with the `ABLO_API_KEY` env var. Do NOT run `ablo login` (opens a browser).
+- 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`).
 - Adopt an existing DB: `npx ablo pull prisma [path]` / `npx ablo pull drizzle <module>`.
-- `npx ablo dev --no-watch` (default watches forever); `npx ablo logs --no-follow` (default tails forever); `npx ablo mode test|live` (always pass the arg). `npx ablo push`/`status`/`pull`/`check`/`generate` are one-shot.
+- `npx ablo dev --no-watch` pushes the schema (test mode) AND writes `ABLO_API_KEY` to `.env.local` (default watches forever); `npx ablo logs --no-follow` (default tails forever); `npx ablo mode test|live` (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`.