@lunora/cli 1.0.0-alpha.38 → 1.0.0-alpha.380

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

@@ -1,110 +1,153 @@
 ---
 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.
+description: Adds authentication to a Lunora app with the `auth` registry item (better-auth via `@lunora/auth`, users and sessions in D1). Covers email/password sign-up and sign-in, Clerk or Auth0 OAuth, magic link, email OTP, copy-in auth screens (`lunora add auth-ui`), wiring `/api/auth/*` and `resolveIdentity` into the Worker, and gating functions on `ctx.auth.userId`. Use when the user asks to "add auth", "add login/sign-in/sign-up", "protect this query", or "add Clerk/Auth0/magic link/OTP", runs `lunora add auth` or `lunora registry add auth`, edits `lunora/auth/index.ts`, or `ctx.auth.userId` is unexpectedly `null`.
 ---
 
 # 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.
+The `auth` registry item is built on `@lunora/auth`, a thin wrapper over
+[better-auth](https://www.better-auth.com). Users and sessions are stored in D1.
+Lunora's `SessionDO` is a separate TTL'd token store that `@lunora/auth` never
+calls, so don't wire it for auth. If you need auth state in a Durable Object
+instead of D1, use `LunoraAuthDO` / `.auth({ namespace, internalSecret })`.
 
-## When to Use
+If the project has no Lunora backend yet, start with `lunora-quickstart`.
 
-- 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.
+## Step 1: Add the item
 
-## When Not to Use
+```bash
+lunora add auth                      # asks for the provider and D1 database name
+lunora add auth --provider clerk --db my-app-db   # non-interactive (auth | clerk | auth0)
+lunora registry add auth             # low-level: writes placeholder names
+```
 
-- 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.
+Then run `pnpm install`. The item does the following:
 
-## Workflow
+1. Adds `@lunora/auth`, `@lunora/mail` and `@lunora/server` to `package.json`.
+2. Copies `lunora/auth/index.ts` into the project. The project owns this file and can edit it. It exports `buildAuth(env)`, `getAuth(env)` (memoized per isolate) and `mountAuth(env, request)`, which routes `/api/auth/*` and returns `undefined` for any other path. The scaffold turns on email/password with `requireEmailVerification: true` and sends verification and reset mail through `@lunora/mail`. It also adds the `uiConfig()` plugin.
+3. Adds a D1 `DB` binding to `wrangler.jsonc`. The `database_id` is a placeholder.
+4. Writes `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL` and `MAIL_FROM` to `.dev.vars`.
 
-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 2: Database and env vars
 
-## Step 1: Add the base item
+| Var                  | Secret | Notes                                                                             |
+| -------------------- | ------ | --------------------------------------------------------------------------------- |
+| `BETTER_AUTH_SECRET` | yes    | At least 32 chars (`openssl rand -base64 32`). Production: `wrangler secret put`. |
+| `BETTER_AUTH_URL`    | no     | Public base URL. better-auth uses it for callbacks and cookies.                   |
+| `MAIL_FROM`          | no     | Sender for verification and reset mail.                                           |
 
 ```bash
-lunora registry add auth
+wrangler d1 create my-app-db   # paste the returned id into the DB binding
+lunora doctor                  # flags a placeholder database_id
 ```
 
-This:
+Don't declare the better-auth tables (`user`, `session`, `account`,
+`verification`) in `lunora/schema.ts`. better-auth owns them in D1. In dev the
+schema is auto-applied on the first `/api/auth/*` request. For production,
+pre-apply it with `compileMigrationsSql(auth.options)` piped to
+`wrangler d1 execute <db> --remote --file -`. The item README has the script.
+Re-run that migration after adding a plugin that brings its own tables, such as
+`organization` or `twoFactor`.
 
-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 3: Wire the Worker
 
-## Step 2: Mount the handler
+There are two parts. `/api/auth/*` has to reach better-auth. `resolveIdentity`
+has to turn the session cookie into `ctx.auth`. If `resolveIdentity` is missing,
+sign-in still works but `ctx.auth.userId` stays `null` in every function.
 
-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.
+**Through the generated `defineApp` builder.** This is the default for
+templates. `.auth()` does both parts: it builds the instance lazily, runs
+`ensureMigrated`, dispatches `/api/auth/*` and sets `resolveIdentity`. A
+Vite-first app (`"main": "virtual:lunora/worker"`) has no entry file, so chain
+the call in the `lunora.config.ts` `app` hook. A hand-written entry
+(`src/server.ts`) chains it on `defineApp()` directly:
 
-## Step 3: Env vars and the D1 database
+```ts
+// lunora.config.ts
+import type { AppBuilder, LunoraConfig } from "./lunora/_generated/app";
+// Move the object `buildAuth` passes to `createAuth` (minus `database`; the
+// builder supplies the D1 adapter) into an exported `authOptions(env)` in
+// lunora/auth/index.ts, and have `buildAuth` spread it too.
+import { authOptions } from "./lunora/auth/index.js";
+
+interface Env {
+    BETTER_AUTH_SECRET: string;
+    BETTER_AUTH_URL: string;
+    DB: D1Database;
+}
 
-| 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. |
+export default {
+    target: "cloudflare",
+    app: (app: AppBuilder<Env>): AppBuilder<Env> =>
+        app.auth({
+            d1: (env) => env.DB,
+            options: (env) => authOptions(env),
+        }),
+} satisfies LunoraConfig<Env>;
+```
 
-Create the D1 database and paste its id into the `DB` binding in
-`wrangler.jsonc`:
+Reuse the scaffold's options rather than retyping a subset: a hand-written
+`{ emailAndPassword: { enabled: true } }` drops `requireEmailVerification`,
+`sendResetPassword` and `sendVerificationEmail`, so users sign in unverified and
+no verification or reset mail goes out.
 
-```bash
-wrangler d1 create my-app-db
-```
+`.auth()` appears on the builder only after codegen sees `@lunora/auth`
+installed, so run `lunora codegen` first.
 
-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).
+**Hand-rolled `createWorker` entry.** Call the scaffolded `mountAuth` first in
+`fetch`, then hand every other request to the Lunora worker, which resolves the
+identity:
 
-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`.
+```ts
+import type { AuthEnv } from "../../lunora/auth/index.js";
+import { getAuth, mountAuth } from "../../lunora/auth/index.js";
+
+const worker = createWorker({
+    resolveIdentity: async (req, env) => {
+        const session = await getAuth(env as AuthEnv).api.getSession({ headers: req.headers });
+        return session?.user ? { userId: session.user.id } : null;
+    },
+    // …
+});
+
+export default {
+    async fetch(request: Request, env: AuthEnv, ctx: ExecutionContext): Promise<Response> {
+        const authResponse = await mountAuth(env, request);
+        if (authResponse) return authResponse;
+        return worker.fetch(request, env, ctx); // RPC, WebSocket, everything else
+    },
+};
+```
 
-## Step 4: Add a provider (optional)
+## Step 4: Providers and add-ons (optional)
 
-Each provider item builds on the base `auth` item (`requires: ["auth"]`):
+Each of these items requires the base `auth` item and installs it if it is
+missing:
 
 ```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
+lunora add auth-clerk        # Clerk OIDC (genericOAuth): CLERK_CLIENT_ID / _SECRET / CLERK_ISSUER_URL
+lunora add auth-auth0        # Auth0 OIDC: AUTH0_CLIENT_ID / _SECRET / AUTH0_DOMAIN
+lunora add auth-magic-link   # passwordless link, sent via @lunora/mail
+lunora add auth-otp          # email one-time code, sent via @lunora/mail
+lunora add auth-emails       # styled React templates for the auth mails (renderEmail)
+lunora add auth-ui           # copy-in screens; framework auto-detected (no React Native port)
 ```
 
-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`.
+The provider items copy a file into `lunora/auth/` but don't register it
+anywhere. Add the plugin to the `plugins` array yourself, in `buildAuth` or in
+`.auth({ options })`. For example, `plugins: [uiConfig(), clerk(env)]` with
+`import { clerk } from "./clerk.js"`. The other exports are `auth0`,
+`magicLinkPlugin` and `emailOtpPlugin`. The OAuth callback URL is
+`<BETTER_AUTH_URL>/api/auth/oauth2/callback/<clerk|auth0>`.
 
 ## 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";
+import { LunoraError } from "lunorash/server";
+
+import { mutation, v } from "#lunora/_generated/server.js";
 
 export const createDocument = mutation.input({ title: v.string() }).mutation(async ({ ctx, args: { title } }) => {
     if (!ctx.auth.userId) {
@@ -114,27 +157,41 @@ export const createDocument = mutation.input({ title: v.string() }).mutation(asy
 });
 ```
 
-For richer checks (org membership, roles), compose `withAuthPlugins(auth)` and
-call the better-auth server API — see the scaffolded `lunora/auth/index.ts`.
+`ctx.auth.getIdentity()` returns the full session claims, such as email and
+name. For org or role checks, compose `withAuthPlugins(auth)` and call the
+better-auth server API.
+
+### In the client
 
-### In the UI (React)
+The default is a better-auth **cookie session**. `LunoraClient` needs no token,
+so don't call `setToken` / `setAuthToken` for it. Sign in with the better-auth
+client. Build that client with `createLunoraAuthClient`, which installs
+`lunoraSessionSync()`. That plugin tells every open `LunoraClient`, including
+ones in other tabs, to re-resolve the session after sign-in or sign-out. Without
+it, live queries keep serving the previous user's rows. If you call
+`createAuthClient` yourself, add `lunoraSessionSync()` to its plugins.
 
 ```tsx
-import { Authenticated, Unauthenticated, useAuth } from "@lunora/react";
+import { createLunoraAuthClient } from "@lunora/auth/plugins/client";
+import { Authenticated, AuthLoading, Unauthenticated, useAuth } from "@lunora/react";
+import { createAuthClient } from "better-auth/react";
 
-function Account() {
-    const { user, signIn, signOut } = useAuth();
+export const authClient = createLunoraAuthClient(createAuthClient);
+
+function Account({ email, password }: { email: string; password: string }) {
+    const { user } = useAuth(); // { setToken, status, token, user }
 
     return (
         <>
+            <AuthLoading>…</AuthLoading>
             <Authenticated>
                 <span>Signed in as {user?.email}</span>
-                <button type="button" onClick={() => signOut()}>
+                <button type="button" onClick={() => authClient.signOut()}>
                     Sign out
                 </button>
             </Authenticated>
             <Unauthenticated>
-                <button type="button" onClick={() => signIn()}>
+                <button type="button" onClick={() => authClient.signIn.email({ email, password })}>
                     Sign in
                 </button>
             </Unauthenticated>
@@ -143,28 +200,31 @@ function Account() {
 }
 ```
 
-`@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.
+A client plugin toggle such as `{ plugins: { twoFactor: true } }` only adds
+the client half. Register the matching server plugin (`twoFactor()` from
+`@lunora/auth/plugins`) in `buildAuth`'s `plugins` too, or its endpoints don't
+exist.
+
+`setToken` is only for bearer-token setups, such as React Native or a JWT from
+an external IdP.
+
+Branch on `status`, not on `user === null`. `status` takes one of four values:
+`"unauthenticated"`, `"loading"`, `"authenticated"` or `"unreachable"`. The gates
+in `@lunora/vue`, `@lunora/solid`, `@lunora/svelte` and `@lunora/angular` use the
+same four. `"unreachable"` means a credential is held but the session endpoint
+failed, for example on an offline reload. The gates treat it as authenticated,
+yet `user` can still be `null` at that point. A UI that reads that `null` as
+"signed out" shows a signed-in user the signed-out screen. The full contract is
+documented on `AuthStatus` in `@lunora/client/auth`.
+
+## Pitfalls
+
+- **Sign-in rejected right after sign-up.** The scaffold sets `requireEmailVerification: true`, so the user has to open the verification link first. In dev, that link is in the Studio Mail tab.
+- **Mail in production.** Dev captures mail into the Studio. In production with no `MAIL_FROM`, the scaffold throws rather than logging the link. Auth links are bearer credentials, so this is intentional. Production needs `lunora add email` (the `SEND_EMAIL` binding) or `RESEND_API_KEY`, plus a verified sender domain. See `lunora-setup-mail`.
+- **Unauthenticated storage or other items.** Items that call `requireOwner` throw `UNAUTHORIZED` until `resolveIdentity` is wired (Step 3).
+
+## Verify
+
+1. Run `lunora doctor`. It should report no placeholder `database_id`.
+2. Run `lunora dev`. Sign up, open the verification link from the Studio Mail tab, then sign in.
+3. Call a query that returns `ctx.auth.userId`. It should return the user's id, not `null`.

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

@@ -1,73 +1,42 @@
 ---
 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).
+description: Connects an existing, externally owned Postgres/MySQL database to a Lunora app through Cloudflare Hyperdrive. Lunora does not own its schema. Covers `@lunora/hyperdrive`, the action-only, non-reactive `ctx.sql` client (`createHyperdrive` + `fromPostgresJs`/`fromNodePg`/`fromMysql2`, wired with the app builder's `.hyperdrive()`), the `HYPERDRIVE` binding and `wrangler hyperdrive create`, and making external rows live through a projection or a `.source()` ingest table. Use when the user wants to "query our existing Postgres", "read the legacy DB from an action", "connect Neon/RDS/Supabase", or sync external rows into Lunora, or sees `ctx.sql` / `hyperdrive_outside_action` errors. For storing Lunora's own `.global()` tables in Postgres/MySQL with reactive live queries, use `lunora-setup-hyperdrive-global` instead.
 ---
 
 # 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
+`@lunora/hyperdrive` exposes a Cloudflare Hyperdrive binding as a
+driver-agnostic `ctx.sql` client that is available only inside an `action`. It integrates
+a database Lunora doesn't own. Don't use it to replace `defineSchema`, because you'd lose
+realtime, OCC, optimistic updates, the offline queue and the advisors.
+
+> **`ctx.sql` is not reactive.** Lunora cannot see this database, so subscriptions
+> do not re-run when its rows change, including rows you write through `ctx.sql`.
+> Queries are non-deterministic, so `ctx.sql` exists only on `ActionCtx`.
+> The `hyperdrive_outside_action` advisor lint flags any use in a
+> `query`/`mutation`. To make the data live, see Step 5. If you instead want Lunora-owned tables
+> stored in Postgres/MySQL and fully reactive, use `lunora-setup-hyperdrive-global`.
+
+## Step 1: Install the package + one 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)
+pnpm add postgres   # → fromPostgresJs   ($1, $2 placeholders)
+# or: pnpm add pg      → fromNodePg       ($1, $2)
+# or: pnpm add mysql2  → fromMysql2       (?)
 ```
 
+The drivers are optional peer dependencies, so none ships with the package.
+The package never rewrites SQL, so use your driver's native 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):
+Add the printed `id` to `wrangler.jsonc`. `localConnectionString` lets `lunora dev`
+connect directly:
 
 ```jsonc
 {
@@ -81,10 +50,9 @@ proxy locally):
 }
 ```
 
-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.
+Lunora validates the entry but never writes the `id` itself, because only
+`wrangler hyperdrive create` can mint it. Validation fails without a `binding`
+and warns when `id` is empty.
 
 ## Step 3: Regenerate types
 
@@ -92,63 +60,112 @@ that's a remote resource only `wrangler hyperdrive create` can mint. Importing
 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.
+When `ctx.sql` is used, codegen adds `readonly sql: SqlClient` to `ActionCtx` only. It also
+emits a `.hyperdrive()` method on the generated app builder.
 
-## Step 4: Use `ctx.sql` from an action
+## Step 4: Wire the client on the app builder
 
-```ts
+`ctx.sql` is `readonly`, so assigning it in a handler is a `TS2540` error.
+Codegen can't build the client because it depends on your driver, so supply a
+thunk instead. It runs once per shard construction, not per request:
+
+```ts title="src/server.ts"
+import type { HyperdriveLike } from "@lunora/hyperdrive";
 import { createHyperdrive, fromPostgresJs } from "@lunora/hyperdrive";
 import postgres from "postgres";
 
-import { action, v } from "@lunora/server";
+import { defineApp } from "../lunora/_generated/app.js";
 
-export const listLegacyOrders = action.input({ orgId: v.string() }).action(async ({ ctx, args: { orgId } }) => {
-    const { connectionString } = createHyperdrive(ctx.env.HYPERDRIVE);
-    ctx.sql = fromPostgresJs(postgres(connectionString));
+const app = defineApp<Env>()
+    .shard((env) => env.SHARD)
+    .hyperdrive((env) => fromPostgresJs(postgres(createHyperdrive(env.HYPERDRIVE as HyperdriveLike).connectionString)))
+    .build();
+
+export const ShardDO = app.ShardDO;
+```
+
+Then query from any action:
+
+```ts
+import { LunoraError } from "lunorash/server";
 
-    return ctx.sql.query<{ id: string; total: number }>("select id, total from orders where org = $1", [orgId]);
+import { action, v } from "#lunora/_generated/server.js";
+
+export const listLegacyOrders = action.input({ orgId: v.string() }).action(async ({ ctx, args: { orgId } }) => {
+    if (!ctx.auth.userId) {
+        throw new LunoraError("UNAUTHORIZED", "not signed in");
+    }
+
+    // `orgId` comes from the client: the join scopes it to orgs the caller belongs to.
+    return ctx.sql.query<{ id: string; total: number }>(
+        "select o.id, o.total from orders o join org_members m on m.org_id = o.org where o.org = $1 and m.user_id = $2",
+        [orgId, ctx.auth.userId],
+    );
 });
 ```
 
-The package never rewrites SQL — use your driver's native placeholders (`$1` for
-Postgres, `?` for MySQL).
+**Verify:** call the action from the studio's function runner and check that it returns rows.
+
+## Step 5 (optional): Make external data reactive
 
-## Step 5 (optional): Make it reactive via a projection
+Pick one approach:
 
-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:
+**A. Projection from an action.** This works when your app is the writer. Write the row into a
+`defineSchema` table through a mutation. That write is tracked:
 
 ```ts
+import { LunoraError } from "lunorash/server";
+
+import { internal } from "#lunora/_generated/internal.js";
+
 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 });
+if (!row) {
+    throw new LunoraError("NOT_FOUND", `order ${id} not found`);
+}
+
+// Re-runs live queries over `orders`. ctx.run* takes a generated reference, not a "file:fn" string.
+await ctx.runMutation(internal.orders.upsert, { id: row.id, total: row.total });
 ```
 
+**B. A `.source()` table.** This works when other systems also write the database. Lunora polls
+the external query on the shard's alarm, diffs the result, materializes it into the
+DO's SQLite and notifies subscribers, so you don't write an action or a cron:
+
+```ts
+// lunora/schema.ts
+messages: defineTable({ body: v.string(), channelId: v.string() })
+    .shardBy("channelId")
+    .source({
+        binding: "HYPERDRIVE",
+        query: 'select id, body, channel_id as "channelId" from messages where channel_id = $1',
+        tenantBy: (shardKey) => [shardKey], // required under .shardBy(): the tenant boundary
+    }),
+```
+
+```ts
+// worker entry: one client per binding name
+.sourceClient((env, binding) => fromPostgresJs(postgres((env[binding] as { connectionString: string }).connectionString)))
+```
+
+How `.source()` behaves:
+
+- Freshness depends on the poll interval: every alarm tick by default,
+  `refresh: { everyMs }` to throttle it, or `"manual"`.
+- The table is read-only from Lunora: rows come only from the ingest loop.
+- The default `mode: "full-pull"` re-reads the whole slice on every tick, which
+  works up to about 10k rows. For larger slices, use `mode: "incremental"` with a
+  `cursor`, plus either `reconcileEveryMs` or `softDeleteColumn` so deletes are
+  still detected.
+- A source table can't also be `.global()`.
+
 ## 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.
+1. **`ctx.sql` in a query/mutation.** It's action-only. Move the SQL into an action.
+2. **Expecting `ctx.sql` writes to update subscriptions.** They don't. Use Step 5.
+3. **Placeholder or empty `id`.** The binding can't connect. Run
+   `wrangler hyperdrive create` and paste the id.
+4. **Wrong placeholders.** Use `$1` for `postgres`/`pg` and `?` for `mysql2`.
+5. **Unscoped `.source()` under `.shardBy()`.** Without `tenantBy`, every tenant's
+   rows are copied into each shard. `defineSchema` throws, and the
+   `external_source_unscoped` lint fails the build.