@lunora/cli 0.0.0 → 1.0.0-alpha.10

package/skills/lunora-realtime/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: lunora-realtime
+description: Wires Lunora's live data into a client. Use for `LunoraClient`/`LunoraProvider`,
+    reactive `useQuery`/`useSubscription`, `useMutation` with optimistic updates,
+    pagination, connection status, the React/Vue/Solid/Svelte adapters, and the
+    `@lunora/db` TanStack binding.
+---
+
+# Lunora Realtime
+
+Consume Lunora functions reactively from the client. Queries are live
+subscriptions over WebSocket — a `useQuery` re-renders the instant a mutation
+changes the rows it reads — and mutations can paint optimistically with
+automatic rollback.
+
+## When to Use
+
+- Wiring a frontend to a Lunora backend (React, Vue, Solid, Svelte).
+- Adding optimistic updates, pagination, or presence to the UI.
+- Choosing between live hooks and the `@lunora/db` collection layer.
+
+## When Not to Use
+
+- Writing the server functions themselves — that's `lunora-functions`.
+- Initial project/provider scaffolding — that's `lunora-quickstart`.
+
+## Provider Setup
+
+Create the `LunoraClient` once at module scope and wrap the app. The client owns
+the WebSocket, the optimistic cache, and the offline queue.
+
+```tsx
+import { LunoraClient } from "@lunora/client";
+import { LunoraProvider } from "@lunora/react";
+
+const url = (import.meta.env.VITE_LUNORA_URL as string | undefined) ?? globalThis.location.origin;
+const client = new LunoraClient({ url });
+
+// <LunoraProvider client={client}>…</LunoraProvider>
+```
+
+Vue / Solid / Svelte have matching providers in `@lunora/vue`, `@lunora/solid`,
+`@lunora/svelte`; the hook names and semantics below mirror across them.
+
+## Live Queries
+
+`useQuery(reference, args)` opens a subscription and returns the value, or
+`undefined` while it loads. The reference comes from codegen
+(`api.<file>.<name>`).
+
+```tsx
+import { useQuery } from "@lunora/react";
+
+import { api } from "../../lunora/_generated/api";
+import type { Doc } from "../../lunora/_generated/dataModel";
+
+const todos = useQuery(api.todos.list, {}) as Doc<"todos">[] | undefined;
+```
+
+- `undefined` means "loading" — render a skeleton/spinner for it.
+- The subscription tears down on unmount and re-runs only when `args` change or
+  the underlying rows change. Keep `args` narrow so a write elsewhere doesn't
+  re-push unrelated data (see `lunora-performance-audit`).
+- `useSubscription` is the lower-level primitive for streaming subscriptions;
+  `usePreloadedQuery` + `lunoraQueryOptions` support SSR/preload handoff via
+  `@lunora/react/server`.
+
+## Authorization & Live Queries
+
+Subscriptions re-run the query handler **server-side under anonymous
+identity**. The one-shot `fetch` RPC behind the initial load carries the
+caller's identity, but the live WebSocket channel (the subscription seed and
+every write-driven refresh) does not — it evaluates as anonymous.
+
+This matters for any query that authorizes or filters on the authenticated
+user:
+
+- A query guarded by `.use(rls(...))` or one that reads `ctx.auth.userId`
+  directly returns the user's rows on the **initial** HTTP fetch, but its
+  **live** updates evaluate anonymously and may resolve to an empty/denied
+  set.
+- This **fails closed** — the live channel shows _less_ data, never another
+  user's data, so there is no leak. But it is a correctness caveat: the
+  initial render and the live updates can disagree.
+
+The supported pattern today is to scope per-user data **outside** of
+`ctx.auth` inside a subscribed query:
+
+- Partition the data by shard with `.shardBy(userId)` (or tenant/room), so the
+  subscription is already scoped to the right state, or
+- Pass the identifier as an **explicit query arg**
+  (`useQuery(api.todos.list, { userId })`) and filter on the arg rather than on
+  `ctx.auth`.
+
+Reserve `rls()` / `ctx.auth`-based filtering for non-subscribed reads (one-shot
+actions/queries) where identity is always present.
+
+## Mutations + Optimistic Updates
+
+`useMutation(reference)` returns `{ mutate, pending }`. Pass an `optimistic`
+callback to paint the next state immediately; if the server rejects the call the
+runtime rolls the cache back automatically.
+
+```tsx
+import { useMutation } from "@lunora/react";
+
+import type { Doc, Id } from "../../lunora/_generated/dataModel";
+
+const { mutate: add, pending } = useMutation(api.todos.add);
+
+await add(
+    { text },
+    {
+        optimistic: (current) => {
+            const list = (current as Doc<"todos">[] | undefined) ?? [];
+            const provisional: Doc<"todos"> = {
+                _id: `optimistic_${Date.now()}` as Id<"todos">,
+                _creationTime: Date.now(),
+                text,
+                done: false,
+                createdAt: Date.now(),
+            };
+            return [provisional, ...list];
+        },
+    },
+);
+```
+
+- The `optimistic` callback receives the current cached value and returns the
+  provisional one. When the server delta arrives it replaces the optimistic
+  entry; on failure the cache reverts.
+- `pending` is `true` while the call is in flight — disable the submit button
+  with it.
+- **Offline queue:** mutations made while disconnected are queued by
+  `LunoraClient` and replayed on reconnect (client-id-keyed, so they aren't
+  double-applied).
+
+## Pagination, Connection, Presence
+
+- `usePaginatedQuery` / `useInfiniteQuery` — cursor pagination over a query that
+  ends in `.paginate(...)` on the server.
+- `useConnectionStatus` — live socket state for an offline/reconnecting banner.
+- `usePresence` — who's-here + heartbeat (pairs with the `presence` registry
+  item).
+- `useAuth` + the `Authenticated` / `Unauthenticated` / `AuthLoading` gates —
+  see `lunora-setup-auth`.
+
+## `@lunora/db` — TanStack DB Collections
+
+For richer client state (indexed local collections, cross-query joins, a durable
+offline-transactions outbox), use `@lunora/db` instead of raw hooks. Scaffold
+with `vis generate lunora-collections` (wires `defineCollections` from your
+schema + functions into live TanStack DB collections). Reach for it when the app
+needs client-side indexes/joins or a persistent optimistic outbox; raw `useQuery`
+/`useMutation` are enough for straightforward live lists.
+
+## Common Pitfalls
+
+1. **Creating `LunoraClient` inside a component.** It re-opens the socket every
+   render — create it once at module scope.
+2. **Treating `undefined` as empty.** `undefined` is "loading", `[]` is "loaded,
+   empty" — branch on both.
+3. **Broad query args.** A subscription keyed too broadly re-renders on
+   unrelated writes; scope `args` to what the component shows.
+4. **Optimistic shape drift.** The provisional value must match the query's
+   element shape (including `_id`/`_creationTime`) or the UI flickers when the
+   real delta lands.
+
+## Checklist
+
+- [ ] `LunoraClient` created once at module scope; app wrapped in the provider.
+- [ ] Live reads use `useQuery`; `undefined` handled as loading.
+- [ ] Writes use `useMutation`; `pending` disables submit; `optimistic` matches
+      the row shape.
+- [ ] Query `args` scoped narrowly to avoid over-broad re-renders.
+- [ ] Pagination via `usePaginatedQuery`/`useInfiniteQuery` over `.paginate`.
+- [ ] Considered `@lunora/db` if the app needs local indexes/joins or an outbox.

package/skills/lunora-setup-auth/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: lunora-setup-auth
+description: Adds authentication to a Lunora app. Use for sign-up/sign-in, email/password,
+    OAuth (Clerk, Auth0), magic link, or email OTP via `lunora registry add auth`,
+    wiring the auth handler into the Worker, and gating functions on the session.
+---
+
+# Lunora Setup Auth
+
+Wire authentication into a Lunora app using the `auth` registry item, which is
+built on `@lunora/auth` (a thin wrapper over
+[better-auth](https://www.better-auth.com)) with sessions persisted in
+`SessionDO` and identity tables in D1.
+
+## When to Use
+
+- Adding sign-up / sign-in to a Lunora app.
+- Adding an OAuth/OIDC provider (Clerk, Auth0), magic link, or email OTP.
+- Gating queries/mutations on the signed-in user.
+
+## When Not to Use
+
+- The project has no Lunora backend yet — use `lunora-quickstart` first.
+- You only need to read `ctx.auth.userId` in a function and auth is already
+  installed — just use it.
+
+## Workflow
+
+1. Add the base `auth` item.
+2. Mount the auth request handler in the Worker entry.
+3. Configure env vars and the D1 database.
+4. (Optional) Layer a provider item (Clerk / Auth0 / magic link / OTP) on top.
+5. Gate functions on `ctx.auth.userId`; gate UI with the auth gates/hooks.
+
+## Step 1: Add the base item
+
+```bash
+lunora registry add auth
+```
+
+This:
+
+1. Adds `@lunora/auth`, `@lunora/mail`, and `@lunora/server` to `package.json`
+   (run `pnpm install` afterwards).
+2. Copies `lunora/auth/index.ts` — the auth instance (`buildAuth` / `getAuth`)
+   and the `/api/auth/*` request handler (`mountAuth`) — into your project. It is
+   **yours** to edit.
+3. Adds a D1 `DB` binding to `wrangler.jsonc` (better-auth persists
+   users/sessions there).
+4. Scaffolds `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`, and `MAIL_FROM` into
+   `.dev.vars`.
+
+## Step 2: Mount the handler
+
+In your Worker entry, route `/api/auth/*` to the scaffolded handler (see the
+generated `lunora/auth/index.ts` README block). `createWorker` handles the rest
+of the RPC surface; the auth handler owns the better-auth endpoints.
+
+## Step 3: Env vars and the D1 database
+
+| Var                  | Secret | Notes                                                               |
+| -------------------- | ------ | ------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET` | yes    | Encryption secret, min 32 chars. `openssl rand -base64 32`.         |
+| `BETTER_AUTH_URL`    | no     | Public base URL, e.g. `http://localhost:8787` in dev, your domain.  |
+| `MAIL_FROM`          | no     | Sender for verification / reset mail. Captured in the dev Mail tab. |
+
+Create the D1 database and paste its id into the `DB` binding in
+`wrangler.jsonc`:
+
+```bash
+wrangler d1 create my-app-db
+```
+
+The better-auth schema (user/session/account/verification tables) is **not**
+declared in `lunora/schema.ts` — it is managed by better-auth in D1. In dev,
+`ensureMigrated(auth)` auto-applies it; in production prefer
+`compileMigrationsSql(auth.options)` piped to `wrangler d1 execute`. Run
+`lunora doctor` to confirm the `DB` binding has a real `database_id` (not a
+placeholder).
+
+Verification and password-reset emails are **captured into the Lunora Studio
+Mail tab** in dev with zero email setup. For real delivery, `lunora registry add
+mail` (adds the `SEND_EMAIL` binding) or set `RESEND_API_KEY`.
+
+## Step 4: Add a provider (optional)
+
+Each provider item builds on the base `auth` item (`requires: ["auth"]`):
+
+```bash
+lunora registry add auth-clerk        # Clerk via better-auth genericOAuth
+lunora registry add auth-auth0        # Auth0 via better-auth genericOAuth
+lunora registry add auth-magic-link   # passwordless magic-link (mail)
+lunora registry add auth-otp          # passwordless email one-time-password
+```
+
+Add the base `auth` item first (or let the registry resolve the `requires`
+dependency). OAuth items need the provider's client id/secret added to
+`.dev.vars`.
+
+## Step 5: Use the session
+
+### In functions
+
+The runtime resolves the session and exposes the user on every context:
+
+```ts
+import { LunoraError, mutation, v } from "@lunora/server";
+
+export const createDocument = mutation.input({ title: v.string() }).mutation(async ({ ctx, args: { title } }) => {
+    if (!ctx.auth.userId) {
+        throw new LunoraError("UNAUTHORIZED", "not signed in");
+    }
+    return ctx.db.insert("documents", { ownerId: ctx.auth.userId, title, createdAt: Date.now() });
+});
+```
+
+For richer checks (org membership, roles), compose `withAuthPlugins(auth)` and
+call the better-auth server API — see the scaffolded `lunora/auth/index.ts`.
+
+### In the UI (React)
+
+```tsx
+import { Authenticated, Unauthenticated, useAuth } from "@lunora/react";
+
+function Account() {
+    const { user, signIn, signOut } = useAuth();
+
+    return (
+        <>
+            <Authenticated>
+                <span>Signed in as {user?.email}</span>
+                <button type="button" onClick={() => signOut()}>
+                    Sign out
+                </button>
+            </Authenticated>
+            <Unauthenticated>
+                <button type="button" onClick={() => signIn()}>
+                    Sign in
+                </button>
+            </Unauthenticated>
+        </>
+    );
+}
+```
+
+`@lunora/react` also exports `AuthLoading` and `useAuthState` for the loading
+window before the session resolves.
+
+## Common Pitfalls
+
+1. **Declaring better-auth tables in `lunora/schema.ts`.** They live in D1 and
+   are managed by better-auth — do not add them to `defineSchema`.
+2. **Placeholder `database_id`.** The `DB` binding ships with a placeholder;
+   `wrangler d1 create` + paste the id, then `lunora doctor` to confirm.
+3. **Missing/short `BETTER_AUTH_SECRET`.** better-auth needs ≥32 chars;
+   `@lunora/auth` surfaces a clear error when it is absent.
+4. **Expecting prod email to "just work".** Dev captures mail into the Studio;
+   production needs `mail` (the `SEND_EMAIL` binding) or `RESEND_API_KEY` and a
+   verified sender domain.
+
+## Checklist
+
+- [ ] `lunora registry add auth` run, `pnpm install` done.
+- [ ] Auth handler mounted in the Worker entry.
+- [ ] `BETTER_AUTH_SECRET` / `BETTER_AUTH_URL` / `MAIL_FROM` set in `.dev.vars`.
+- [ ] D1 database created and its id pasted into the `DB` binding (`lunora
+doctor` clean).
+- [ ] Provider item added if needed (Clerk / Auth0 / magic link / OTP).
+- [ ] Functions gate on `ctx.auth.userId`; UI uses the auth gates/`useAuth`.
+- [ ] Verified sign-in → session → an authenticated query round-trip.

package/skills/lunora-setup-hyperdrive/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: lunora-setup-hyperdrive
+description: Connects an existing Postgres/MySQL database to a Lunora app from an action via Cloudflare Hyperdrive. Use for `@lunora/hyperdrive`, `ctx.sql`, `createHyperdrive` + `fromPostgresJs`/`fromNodePg`/`fromMysql2`, the `HYPERDRIVE` binding, `wrangler hyperdrive create`, and the action-only / non-reactive guardrails (live queries don't track external writes).
+---
+
+# Lunora Setup Hyperdrive
+
+Wire an **existing** Postgres/MySQL database into a Lunora app using
+`@lunora/hyperdrive`, which surfaces a [Cloudflare
+Hyperdrive](https://developers.cloudflare.com/hyperdrive/) binding's connection
+string and a driver-agnostic `ctx.sql` client — usable **only inside an
+`action`**.
+
+> **Integrate, don't replace.** Hyperdrive talks to a database Lunora has no
+> visibility into. Queries through `ctx.sql` are **non-deterministic** (forbidden
+> in `query`/`mutation`, enforced by the `hyperdrive_outside_action` advisor
+> lint) and external writes are **invisible to Lunora live queries** —
+> subscriptions will NOT re-run when external rows change. Use it to read/write a
+> legacy DB from an action; if you want that data reactive, write a projection
+> into a `defineSchema` DO/D1 table.
+
+## When to Use
+
+- Reading/writing an existing Postgres or MySQL database from a Lunora action.
+- Incrementally migrating off a legacy DB while standing up Lunora alongside it.
+- Backfilling/syncing external rows into reactive Lunora tables (projection).
+
+## When Not to Use
+
+- You want the external data to be **reactive** out of the box — it can't be;
+  Hyperdrive writes don't hit the change-feed. Project into a `defineSchema`
+  table instead.
+- You're reaching for `ctx.sql` inside a `query` or `mutation` — forbidden by
+  design (the advisor lint flags it). Move the access into an `action`.
+- The app has no Lunora backend yet — use `lunora-quickstart` first.
+- You'd be replacing `defineSchema` entirely — then you lose realtime, OCC,
+  optimistic updates, the offline queue, and the advisors. Use Lunora's own data
+  layer for app state.
+
+## Workflow
+
+1. Install `@lunora/hyperdrive` and one SQL driver.
+2. Create the Hyperdrive config (`wrangler hyperdrive create`) and add the
+   `HYPERDRIVE` binding to `wrangler.jsonc`.
+3. Regenerate types with `lunora codegen` so `ctx.sql` appears on `ActionCtx`.
+4. Read/write the external DB from an action via `ctx.sql`.
+5. (Optional) Project external rows into a `defineSchema` table to make them
+   reactive.
+
+## Step 1: Install the package + a driver
+
+```bash
+pnpm add @lunora/hyperdrive
+# choose ONE driver (optional peer deps — none is bundled):
+pnpm add postgres        # postgres.js  → fromPostgresJs ($1, $2 placeholders)
+# or
+pnpm add pg              # node-postgres → fromNodePg     ($1, $2 placeholders)
+# or
+pnpm add mysql2          # mysql2        → fromMysql2      (?  placeholders)
+```
+
+## Step 2: Create the binding
+
+```bash
+wrangler hyperdrive create my-db --connection-string="postgres://user:pass@host:5432/db" # gitleaks:allow -- placeholder, not a real secret
+```
+
+This prints an `id`. Add the binding to `wrangler.jsonc`, using
+`localConnectionString` so `lunora dev` connects to your DB directly (no edge
+proxy locally):
+
+```jsonc
+{
+    "hyperdrive": [
+        {
+            "binding": "HYPERDRIVE",
+            "id": "<the id from the command above>",
+            "localConnectionString": "postgres://user:pass@localhost:5432/db", // gitleaks:allow -- placeholder, not a real secret
+        },
+    ],
+}
+```
+
+Lunora validates this binding (errors if `binding` is missing; warns if `id` is
+empty/placeholder — it can't connect), but it does **not** auto-write the `id`:
+that's a remote resource only `wrangler hyperdrive create` can mint. Importing
+`@lunora/hyperdrive` surfaces a hint reminding you to add it.
+
+## Step 3: Regenerate types
+
+```bash
+lunora codegen
+```
+
+When codegen sees `ctx.sql` used, it adds `sql: SqlClient` to **`ActionCtx`
+only** — never `QueryCtx`/`MutationCtx` — with a JSDoc restating the
+determinism/realtime caveat.
+
+## Step 4: Use `ctx.sql` from an action
+
+```ts
+import { createHyperdrive, fromPostgresJs } from "@lunora/hyperdrive";
+import postgres from "postgres";
+
+import { action, v } from "@lunora/server";
+
+export const listLegacyOrders = action.input({ orgId: v.string() }).action(async ({ ctx, args: { orgId } }) => {
+    const { connectionString } = createHyperdrive(ctx.env.HYPERDRIVE);
+    ctx.sql = fromPostgresJs(postgres(connectionString));
+
+    return ctx.sql.query<{ id: string; total: number }>("select id, total from orders where org = $1", [orgId]);
+});
+```
+
+The package never rewrites SQL — use your driver's native placeholders (`$1` for
+Postgres, `?` for MySQL).
+
+## Step 5 (optional): Make it reactive via a projection
+
+External writes don't hit the change-feed, so a subscription won't re-fire on a
+Postgres change. To make external data reactive, write a projection into a
+`defineSchema` table from the same action — that write _is_ tracked:
+
+```ts
+const [row] = await ctx.sql.query<{ id: string; total: number }>("select id, total from orders where id = $1", [id]);
+
+// This write re-runs live queries reading `orders`:
+await ctx.runMutation("orders:upsert", { id: row.id, total: row.total });
+```
+
+## Common Pitfalls
+
+1. **`ctx.sql` in a query/mutation.** It's action-only by design; the
+   `hyperdrive_outside_action` advisor lint flags it. Move the SQL into an
+   action.
+2. **Expecting external writes to be reactive.** They aren't — Lunora can't see
+   them. Project into a `defineSchema` table if you need reactivity.
+3. **Placeholder / empty `id`.** A Hyperdrive binding with no real `id` can't
+   connect (Lunora warns). Run `wrangler hyperdrive create` and paste the id.
+4. **Bundling a driver as a hard dependency.** Drivers are optional peer deps —
+   install the one you use; don't assume one ships with the package.
+5. **Wrong placeholder syntax.** `$1, $2` for Postgres drivers, `?` for mysql2.
+   The package does not rewrite SQL.
+
+## Checklist
+
+- [ ] `@lunora/hyperdrive` + one driver (`postgres`/`pg`/`mysql2`) installed.
+- [ ] `wrangler hyperdrive create` run; `HYPERDRIVE` binding added to
+      `wrangler.jsonc` with a real `id` and a `localConnectionString` for dev.
+- [ ] `lunora codegen` run so `ctx.sql` is typed on `ActionCtx`.
+- [ ] All `ctx.sql` access lives in actions (advisor clean — no
+      `hyperdrive_outside_action`).
+- [ ] If reactivity is needed, external rows are projected into a `defineSchema`
+      table.

package/skills/lunora-setup-hyperdrive-global/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: lunora-setup-hyperdrive-global
+description: Use PlanetScale (Postgres/MySQL via Cloudflare Hyperdrive) as a first-class, REACTIVE `.global()` storage backend for a Lunora app — and migrate an existing D1 `.global()` dataset to it. Use for `@lunora/hyperdrive/global`, `.global({ backend: "hyperdrive" })`, `createHyperdriveGlobalCtxDb`, the app-builder `.hyperdriveGlobal()` declaration, the `HYPERDRIVE` binding pointing at PlanetScale, and `lunora migrate d1-to-hyperdrive`. NOT the same as `@lunora/hyperdrive` (which is an action-only, non-reactive `ctx.sql`).
+---
+
+# Lunora Setup: Hyperdrive Global Backend (Postgres/MySQL)
+
+Store Lunora `.global()` tables in a **Postgres or MySQL database reached
+through [Cloudflare Hyperdrive](https://developers.cloudflare.com/hyperdrive/)**
+— **PlanetScale**, Neon, RDS, or any Hyperdrive-reachable database — instead of
+D1, as a **drop-in, fully reactive** backend. (PlanetScale on Cloudflare is the
+headline use case; nothing here is PlanetScale-specific.)
+
+> **`@lunora/hyperdrive/global` vs. `@lunora/hyperdrive` (`ctx.sql`).** The
+> `ctx.sql` surface is an action-only, **non-reactive** escape hatch for
+> integrating a legacy database. `@lunora/hyperdrive/global` is different: Lunora
+> **owns** the schema (column-per-field, like D1) and routes every write through
+> its own store core, so live queries stay reactive — the writer is injected as
+> `globalDb` and the shard DO's broadcast hook re-runs subscriptions exactly as
+> with D1.
+
+## When to Use
+
+- You want `.global()` (cross-tenant) tables to live in PlanetScale rather than
+  D1 — e.g. for larger datasets, existing SQL tooling, or unified Cloudflare
+  billing.
+- You're migrating an existing D1 `.global()` dataset to PlanetScale.
+
+## When Not to Use
+
+- You only need to read/write a **legacy** external DB from an action — use
+  `@lunora/hyperdrive` (`ctx.sql`) instead; it's lighter and action-scoped.
+- Your global data is small and D1 is fine — bare `.global()` (D1) needs no
+  extra binding or driver.
+
+## How it works
+
+PlanetScale reuses Lunora's dialect-parameterized store core (the same one D1
+uses): a `SqlDialect` (Postgres or MySQL) shapes the SQL, and a Hyperdrive-backed
+`SqlExec` runs it from inside the Durable Object that hosts the global writer.
+Values are stored SQLite-shaped (boolean → 1/0, JSON → text/json, bigint →
+decimal), so the value codec is shared with D1.
+
+## Step 1: Install the package + a driver
+
+```bash
+pnpm add @lunora/hyperdrive/global
+# choose the driver matching your engine (optional peer deps — none is bundled):
+pnpm add postgres        # PlanetScale Postgres → fromPostgresJs
+# or
+pnpm add mysql2          # PlanetScale MySQL    → mysql2/promise
+```
+
+## Step 2: Create the Hyperdrive binding pointing at PlanetScale
+
+Create a PlanetScale database from the Cloudflare dashboard (unified billing),
+then a Hyperdrive config over its connection string:
+
+```bash
+wrangler hyperdrive create my-db --connection-string="postgres://user:pass@host/db" # gitleaks:allow -- placeholder
+```
+
+Add the binding to `wrangler.jsonc` (use `localConnectionString` for `lunora dev`):
+
+```jsonc
+{
+    "hyperdrive": [
+        { "binding": "HYPERDRIVE", "id": "<id from the command>", "localConnectionString": "postgres://user:pass@localhost:5432/db" }, // gitleaks:allow -- placeholder
+    ],
+}
+```
+
+> **Read-your-writes:** point the Hyperdrive config at the **primary** (or pin
+> writes to it) so a write then immediate read isn't served by a stale replica.
+
+## Step 3: Mark tables `.global({ backend: "hyperdrive" })`
+
+```ts
+// lunora/schema.ts
+import { defineSchema, defineTable, v } from "@lunora/server";
+
+export default defineSchema({
+    settings: defineTable({ key: v.string(), value: v.string() }).global({ backend: "hyperdrive" }),
+});
+```
+
+A bare `.global()` stays on D1. **One backend per app** — mixing D1- and
+PlanetScale-backed global tables in the same app isn't supported yet (codegen
+errors clearly).
+
+## Step 4: Wire `.hyperdriveGlobal()` in the app composition
+
+Codegen emits a `.hyperdriveGlobal()` builder method. Supply the engine and an `exec`
+built from the Hyperdrive binding (cache the driver on the DO instance; rebuild
+lazily after hibernation):
+
+```ts
+import { buildPgExec } from "@lunora/hyperdrive/global";
+import { fromPostgresJs } from "@lunora/hyperdrive";
+import postgres from "postgres";
+
+export default defineApp<Env>()
+    .shard((env) => env.SHARD)
+    .hyperdriveGlobal({
+        engine: "postgres",
+        exec: (env) => buildPgExec(fromPostgresJs(postgres(env.HYPERDRIVE.connectionString))),
+    });
+```
+
+For MySQL, create the pool with the **`FOUND_ROWS`** flag (the optimistic-concurrency
+guard needs matched-row counts, or idempotent writes raise spurious conflicts):
+
+```ts
+import { buildMysqlExec } from "@lunora/hyperdrive/global";
+import mysql from "mysql2/promise";
+
+.hyperdriveGlobal({
+    engine: "mysql",
+    exec: (env) => buildMysqlExec(mysql.createPool({ uri: env.HYPERDRIVE.connectionString, flags: ["FOUND_ROWS"] })),
+});
+```
+
+## Step 5: Regenerate + run
+
+```bash
+lunora codegen   # wires config.hyperdriveGlobal and the .hyperdriveGlobal() method
+lunora dev
+```
+
+Tables auto-provision on first use (the runtime runs the PlanetScale DDL through
+the dialect — no manual migration needed), and subscriptions are reactive.
+
+## Migrating an existing D1 dataset → PlanetScale
+
+Blue-green: deploy the new PlanetScale-backed worker alongside the old D1 one,
+then copy the `.global()` data:
+
+```bash
+lunora migrate d1-to-hyperdrive \
+  --from-url https://old-d1.example.com   --from-token "$D1_ADMIN_TOKEN" \
+  --to-url   https://new-ps.example.com   --to-token   "$PS_ADMIN_TOKEN" \
+  --tables settings,orders                # omit to move every global table
+  # --out dump.ndjson                      # keep the intermediate dump to inspect
+```
+
+It streams the source's global rows to NDJSON, imports them into the target
+(whose `.global({ backend: "hyperdrive" })` tables route the writes to
+PlanetScale), and verifies the row counts match. Rows whose `_id` already exists
+are reported as conflicts, not duplicated.
+
+> **Direct external writes** to PlanetScale (bypassing Lunora) are invisible to
+> live queries — same as D1. Let Lunora own the writes.
+
+## Common Pitfalls
+
+1. **Mixing backends.** One global backend per app (codegen errors on a mix).
+2. **Missing driver.** `postgres`/`mysql2` are optional peer deps — install the
+   one matching your engine.
+3. **Stale-replica reads.** Point Hyperdrive at the primary for read-your-writes.
+4. **Expecting external writes to be reactive.** They aren't — route writes
+   through Lunora (`ctx.db`).
+
+## Checklist
+
+- [ ] `@lunora/hyperdrive/global` + the engine's driver installed.
+- [ ] Hyperdrive binding (`HYPERDRIVE`) created over the PlanetScale connection
+      string, with a `localConnectionString` for dev.
+- [ ] Target tables marked `.global({ backend: "hyperdrive" })` (one backend per app).
+- [ ] `.hyperdriveGlobal({ engine, exec })` wired in the app composition.
+- [ ] `lunora codegen` run; `lunora dev` serves the tables reactively.
+- [ ] (Migrating) `lunora migrate d1-to-hyperdrive` run; row counts verified.