@lunora/cli 1.0.0-alpha.32 → 1.0.0-alpha.321

package/skills/lunora-quickstart/SKILL.md

@@ -31,9 +31,12 @@ Set up a working Lunora project as fast as possible.
    Lunora into the current project.
 4. Run `lunora codegen` to generate `lunora/_generated/` and typecheck the
    schema + functions. This is the agent's feedback loop.
-5. Start the dev loop with `lunora dev` (ask the user to run it locally, or
-   start it in the background for cloud/headless agents — it is long-running and
-   does not exit).
+5. Start the dev loop. As an agent, run `lunora dev --background` — it starts
+   the server as a managed detached process, blocks until it accepts requests,
+   prints the URL + PID, and returns (under a detected AI agent, plain
+   `lunora dev` does this automatically, with JSON logs). Never leave a bare
+   `lunora dev` running in your own shell — it is long-running and does not
+   exit.
 6. Verify a query/mutation round-trip works end to end.
 
 ## Path 1: New Project (Recommended)
@@ -42,27 +45,69 @@ Set up a working Lunora project as fast as possible.
 plugin + `lunora/` already wired together).
 
 ```bash
-lunora init my-app --template vite
+lunora init my-app --vite react
 cd my-app
 pnpm install
 ```
 
-### Pick a template
+### Pick a stack: `--vite` (SPA) or `-t` (bespoke template)
+
+There are **two scaffold paths**, and they take different flags:
+
+**`--vite <framework>` — the create-vite overlay.** Fetches the official
+create-vite base and applies the Lunora layer on top. Use it for a plain SPA:
+
+| `--vite` value | Stack                                           |
+| -------------- | ----------------------------------------------- |
+| `react`        | React SPA (**the default**)                     |
+| `vue`          | Vue SPA                                         |
+| `solid`        | Solid SPA                                       |
+| `svelte`       | Svelte SPA                                      |
+| `vanilla`      | No framework (overlay-only — not in the picker) |
+
+**`-t` / `--template <type>` — a bespoke Lunora template.** Whole-project
+templates fetched remotely (via `giget`) from
+`gh:anolilab/lunora/templates/<type>`:
+
+| `-t` value             | Stack                                                      |
+| ---------------------- | ---------------------------------------------------------- |
+| `next`                 | Next.js (App Router, OpenNext on Cloudflare)               |
+| `tanstack-start-react` | TanStack Start (React) — SSR with live-loader routes       |
+| `tanstack-start-solid` | TanStack Start (Solid)                                     |
+| `solid-v2`             | Solid 2.0 SPA (`@solidjs/web`, `vite-plugin-solid` 3)      |
+| `react-router`         | React Router v7 (framework mode), SSR in the Lunora worker |
+| `astro`                | Astro + a standalone Lunora worker                         |
+| `analog`               | AnalogJS (Angular) — single worker, Lunora in Nitro        |
+| `nuxt`                 | Nuxt (Vue) — single worker, Lunora in Nitro                |
+| `sveltekit`            | SvelteKit + a standalone Lunora worker                     |
+| `expo`                 | React Native (Expo) — iOS/Android/web + a Lunora worker    |
+| `standalone`           | Worker-only Lunora backend, no frontend                    |
+
+> There is **no `--template vite`.** SPAs go through `--vite <framework>`; `-t`
+> is only for the bespoke templates above. The one exception is `solid-v2`:
+> create-vite's Solid base is still 1.x, and Solid 2.0 needs its own renderer
+> package, `jsxImportSource`, and Vite plugin major — so it ships as a template
+> rather than an overlay. `--vite solid` stays on Solid 1.x.
+
+With neither flag, an interactive run shows the framework picker (defaulting to
+the React overlay) and a **non-interactive run errors out** — so as an agent,
+always pass `--vite` or `-t` explicitly. If the user stated no preference,
+use `--vite react`.
+
+### Useful `init` flags
 
-| Template               | Stack                                          |
-| ---------------------- | ---------------------------------------------- |
-| `vite`                 | React + Vite (the simplest full-stack starter) |
-| `standalone`           | Worker-only Lunora backend, no frontend        |
-| `astro`                | Astro integration                              |
-| `nuxt`                 | Nuxt (Vue)                                     |
-| `sveltekit`            | SvelteKit                                      |
-| `tanstack-start-react` | TanStack Start (React)                         |
-| `tanstack-start-solid` | TanStack Start (Solid)                         |
+```bash
+lunora init my-app --vite react --ci github     # + a GitHub Actions deploy pipeline (or --ci gitlab)
+lunora init my-app -t next --add auth,email     # scaffold capabilities non-interactively
+lunora init my-app --vite react --yes           # skip the interactive auth/email offer
+lunora init my-app --vite react --dry-run       # walk every step, write nothing
+```
 
-If the user has not specified a preference, default to `vite`. Pass `--template`
-explicitly to avoid the interactive prompt. Templates are fetched remotely (via
-`giget`) from `gh:anolilab/lunora/templates/<type>`; pass `--from <dir>` to use a
-local template directory offline.
+`--add` accepts a comma-separated list of `ai | auth | backup | browser |
+cloudflare-access | crons | email | flags | hyperdrive | payment | presence |
+queue | storage | workflow`. `--ref <branch|tag|commit>` pins the template
+source (e.g. `--ref alpha`); `--from <dir>` copies from a local templates root
+offline (expects `<type>/` subdirs).
 
 ### Generate types and push the first run
 
@@ -87,7 +132,23 @@ not exit, so:
 
 - **Local development (user at the keyboard):** ask the user to run `lunora dev`
   in a terminal.
-- **Cloud or headless agents:** start `lunora dev` in the background.
+- **Agents:** run `lunora dev --background`. It detaches the server, waits until
+  it answers HTTP, prints `Dev server running at <url> (pid <n>)`, and exits —
+  no orphaned shell, no PID bookkeeping. When Lunora detects an AI agent
+  (Claude Code, Cursor, Codex, …), plain `lunora dev` flips into this mode
+  automatically with JSON logs; `LUNORA_AGENT_MODE=0` opts out.
+
+Manage the running server afterwards:
+
+```bash
+lunora dev status --json   # machine-readable: url, pid, uptime, logFile
+lunora dev logs --lines 50 # tail the captured output (.lunora/dev.log)
+lunora dev stop            # idempotent — succeeds even if nothing runs
+```
+
+A second `lunora dev` never double-starts: it reports the existing instance
+(`.lunora/dev.json` is the lockfile). Probe readiness or liveness at
+`GET /_lunora/status` (`{"ok":true}`).
 
 Vite serves on `http://localhost:5173` by default; the Worker is served on the
 same origin via `@cloudflare/vite-plugin`.
@@ -132,9 +193,12 @@ createRoot(document.querySelector("#root")!).render(
 );
 ```
 
-Vue, Solid, and Svelte have matching providers in `@lunora/vue`, `@lunora/solid`,
-and `@lunora/svelte`. `VITE_LUNORA_URL` is optional — it defaults to
-`location.origin`, which is correct for the single-origin dev setup.
+Every client adapter has a matching provider: `@lunora/vue`, `@lunora/solid`,
+`@lunora/svelte`, `@lunora/angular` (`provideLunora` / `injectLunoraClient`),
+and `@lunora/react-native` (`createLunoraClient`, re-exporting `@lunora/react`).
+For meta-frameworks, `@lunora/astro` and `@lunora/nuxt` mount Lunora on the
+server side. `VITE_LUNORA_URL` is optional — it defaults to `location.origin`,
+which is correct for the single-origin dev setup.
 
 ## Writing Your First Function
 
@@ -143,7 +207,7 @@ Create a schema and a query/mutation to verify the full loop.
 `lunora/schema.ts`:
 
 ```ts
-import { defineSchema, defineTable, v } from "@lunora/server";
+import { defineSchema, defineTable, v } from "lunorash/server";
 
 export default defineSchema({
     todos: defineTable({
@@ -157,8 +221,8 @@ export default defineSchema({
 `lunora/todos.ts`:
 
 ```ts
-import type { Id } from "@lunora/server";
-import { mutation, query, v } from "@lunora/server";
+import type { Id } from "#lunora/_generated/server.js";
+import { mutation, query, v } from "#lunora/_generated/server.js";
 
 export const list = query.query(async ({ ctx }) => ctx.db.query("todos").withIndex("by_creation").collect());
 
@@ -233,8 +297,10 @@ ids, `.dev.vars` secrets, and container exports.
 ## Checklist
 
 - [ ] Determined starting point: new project or existing app.
-- [ ] New project: scaffolded with `lunora init --template <t>`.
+- [ ] New project: scaffolded with `lunora init --vite <framework>` (SPA) or
+      `lunora init -t <template>` (bespoke) — never `--template vite`.
 - [ ] Existing app: ran `lunora init --here` and wired `LunoraProvider`.
 - [ ] Ran `lunora codegen`: `lunora/_generated/` exists and typecheck is clean.
-- [ ] `lunora dev` is running — user terminal, or background for cloud agents.
+- [ ] Dev server is running — user terminal, or `lunora dev --background`
+      (check with `lunora dev status`).
 - [ ] Verified a query/mutation round-trip re-renders the client live.

package/skills/lunora-realtime/SKILL.md

@@ -2,8 +2,8 @@
 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.
+    pagination, connection status, the React/Vue/Solid/Svelte/Angular/React Native
+    adapters, and the `@lunora/db` TanStack binding.
 ---
 
 # Lunora Realtime
@@ -15,7 +15,8 @@ automatic rollback.
 
 ## When to Use
 
-- Wiring a frontend to a Lunora backend (React, Vue, Solid, Svelte).
+- Wiring a frontend to a Lunora backend (React, Vue, Solid, Svelte, Angular,
+  React Native/Expo, or an Astro/Nuxt meta-framework).
 - Adding optimistic updates, pagination, or presence to the UI.
 - Choosing between live hooks and the `@lunora/db` collection layer.
 
@@ -42,6 +43,19 @@ const client = new LunoraClient({ url });
 Vue / Solid / Svelte have matching providers in `@lunora/vue`, `@lunora/solid`,
 `@lunora/svelte`; the hook names and semantics below mirror across them.
 
+Two adapters differ in shape:
+
+- **`@lunora/angular`** is signal-based rather than hook-based: register with
+  `provideLunora(...)`, read the client via `injectLunoraClient()`, and use
+  `liveQuery(...)` / `mutate(...)` / `connectionStatus(...)` in place of the
+  hooks below.
+- **`@lunora/react-native`** re-exports all of `@lunora/react` and adds
+  `createLunoraClient` (plus `@lunora/react-native/auth` for the better-auth
+  Expo bridge) — build the client with that instead of `new LunoraClient`.
+
+For SSR meta-frameworks, `@lunora/astro` and `@lunora/nuxt` compose Lunora into
+the server (Nitro for Nuxt) and ship reactive-loader server helpers.
+
 ## Live Queries
 
 `useQuery(reference, args)` opens a subscription and returns the value, or
@@ -67,39 +81,38 @@ const todos = useQuery(api.todos.list, {}) as Doc<"todos">[] | undefined;
 
 ## 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.
+**Live queries are identity-aware.** At the WebSocket upgrade the runtime
+stamps the caller's verified identity onto the socket (from the server-minted
+`x-lunora-userid` / `x-lunora-identity` headers, which a client cannot forge).
+Every subscription re-run, shape resolution, and poke-driven refresh executes
+under that socket's own identity, passed by value so a concurrent RPC can't
+clobber it.
+
+Practically, this means:
+
+- `.use(rls(...))` and `ctx.auth.userId` work the same in a subscribed query as
+  in a one-shot read. Shape subscriptions AND-merge the shape predicate with
+  the table's RLS read base-where, so the membership query the poke protocol
+  runs is RLS-correct by construction — never the client's word for it.
+- An **anonymous** socket carries no identity, so an RLS/`ctx.auth` query fails
+  closed (empty/denied) rather than leaking another user's rows.
+- **Token expiry is enforced on the socket.** When the resolved credential
+  carries an expiry, the DO sends a `TOKEN_EXPIRED` error frame and closes with
+  code `4001` at the next send at or after that instant. `LunoraClient`
+  reconnects automatically and re-resolves a fresh identity — but surface it in
+  the UI if a re-login is required.
+
+You can still scope data structurally when it fits the domain — `.shardBy(userId)`
+(or tenant/room) partitions state so a subscription is narrow by construction,
+and explicit query args keep subscriptions cheap (see the args-scoping note
+above). Prefer those for _performance_; use `rls()` / `ctx.auth` for
+_authorization_. They compose.
 
 ## 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.
+`useMutation(reference)` returns `{ mutate, pending }`. Pass an
+`optimisticUpdate` 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";
@@ -111,8 +124,8 @@ const { mutate: add, pending } = useMutation(api.todos.add);
 await add(
     { text },
     {
-        optimistic: (current) => {
-            const list = (current as Doc<"todos">[] | undefined) ?? [];
+        optimisticUpdate: (store) => {
+            const list = store.getQuery(api.todos.list, {}) ?? [];
             const provisional: Doc<"todos"> = {
                 _id: `optimistic_${Date.now()}` as Id<"todos">,
                 _creationTime: Date.now(),
@@ -120,15 +133,21 @@ await add(
                 done: false,
                 createdAt: Date.now(),
             };
-            return [provisional, ...list];
+            store.setQuery(api.todos.list, {}, [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.
+- `optimisticUpdate` names the query it patches, because `todos.add` and
+  `todos.list` are different functions and nothing can infer the link. When the
+  server delta arrives it replaces the optimistic entry; on failure the cache
+  reverts. `store.getAllQueries(fn)` patches every subscribed variant of a query
+  at once.
+- The per-call `optimistic: (current) => next` shortcut exists too, but it only
+  patches a subscription registered under the **mutation's own** reference and
+  args — a counter or a document by id. It is a silent no-op for the
+  `add`-updates-`list` shape above.
 - `pending` is `true` while the call is in flight — disable the submit button
   with it.
 - **Offline queue:** mutations made while disconnected are queued by
@@ -154,6 +173,13 @@ 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.
 
+Call `defineCollections` **once** at module scope and treat the returned
+collections as the single source of truth for each table. Don't mirror rows into
+a parallel store, and never build derived indexes (trees, search, undo captures)
+from a copy — optimistic writes and sync deltas land only on the Lunora
+collection, so code reading a copy silently reads stale rows while `useLiveQuery`
+renders fresh data.
+
 ## Common Pitfalls
 
 1. **Creating `LunoraClient` inside a component.** It re-opens the socket every
@@ -165,6 +191,12 @@ needs client-side indexes/joins or a persistent optimistic outbox; raw `useQuery
 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.
+5. **Two sources of truth for the same rows.** `defineCollections` more than once
+   per table (or a parallel store of your own) mints copies that drift. Reads
+   through `useLiveQuery` look fine, but derived indexes built from the copy can
+   **miss rows** — rows written to the collection after the copy was taken never
+   appear in the index — or **hold stale rows** — rows updated or deleted in the
+   collection still show their old value. One instance, one collection per table.
 
 ## Checklist
 
@@ -175,3 +207,5 @@ needs client-side indexes/joins or a persistent optimistic outbox; raw `useQuery
 - [ ] 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.
+- [ ] `@lunora/db`: one `defineCollections` instance; no parallel copy of rows;
+      derived indexes built from the same collection the UI renders.

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

@@ -9,8 +9,10 @@ description: Adds authentication to a Lunora app. Use for sign-up/sign-in, email
 
 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.
+[better-auth](https://www.better-auth.com)) with identity **and session** tables
+in D1. (`SessionDO` is a standalone TTL'd token store `@lunora/auth` never
+calls — don't wire it for auth. The Durable Object option is `LunoraAuthDO` /
+`.auth({ namespace })`, which holds the whole better-auth schema.)
 
 ## When to Use
 
@@ -104,7 +106,9 @@ dependency). OAuth items need the provider's client id/secret added to
 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) {
@@ -119,22 +123,35 @@ call the better-auth server API — see the scaffolded `lunora/auth/index.ts`.
 
 ### In the UI (React)
 
+`useAuth()` returns exactly `{ setToken, status, token, user }` — there is no
+`signIn` / `signOut`. Lunora owns the **token**, not the sign-in flow: run the
+flow with the better-auth client (`authClient.signIn.email(...)`), then hand the
+resulting JWT to `setToken`. `setToken(null)` signs out.
+
 ```tsx
 import { Authenticated, Unauthenticated, useAuth } from "@lunora/react";
 
+import { authClient } from "./auth-client";
+
 function Account() {
-    const { user, signIn, signOut } = useAuth();
+    const { setToken, user } = useAuth();
+
+    const signIn = async () => {
+        const { data } = await authClient.signIn.email({ email, password });
+
+        setToken(data?.token ?? null);
+    };
 
     return (
         <>
             <Authenticated>
                 <span>Signed in as {user?.email}</span>
-                <button type="button" onClick={() => signOut()}>
+                <button type="button" onClick={() => setToken(null)}>
                     Sign out
                 </button>
             </Authenticated>
             <Unauthenticated>
-                <button type="button" onClick={() => signIn()}>
+                <button type="button" onClick={signIn}>
                     Sign in
                 </button>
             </Unauthenticated>
@@ -146,6 +163,16 @@ function Account() {
 `@lunora/react` also exports `AuthLoading` and `useAuthState` for the loading
 window before the session resolves.
 
+**Branch on `status`, never on `user === null`.** `status` is one of
+`"unauthenticated"`, `"loading"`, `"authenticated"` or `"unreachable"`, and the
+same four values back the gates in every adapter (`@lunora/vue`,
+`@lunora/solid`, `@lunora/svelte`, `@lunora/angular`). `"unreachable"` means the
+credential is held but the session endpoint could not be reached — an offline
+reload, or a transient 5xx. It gates as **authenticated**, so the app renders,
+but `user` may still be `null`; a UI that treats that `null` as signed out shows
+a signed-out screen to a signed-in user. The full contract is documented on
+`AuthStatus` in `@lunora/client/auth`.
+
 ## Common Pitfalls
 
 1. **Declaring better-auth tables in `lunora/schema.ts`.** They live in D1 and

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

@@ -92,24 +92,41 @@ 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 codegen sees `ctx.sql` used, it adds `readonly sql: SqlClient` to
+**`ActionCtx` only** — never `QueryCtx`/`MutationCtx` — with a JSDoc restating
+the determinism/realtime caveat, and emits a `.hyperdrive()` method on the
+generated app builder for you to supply the client (step 4).
 
-## Step 4: Use `ctx.sql` from an action
+## Step 4: Wire the client once, on the app builder
 
-```ts
+`ctx.sql` is `readonly` — assigning to it inside a handler is a `TS2540`.
+Codegen cannot build the client for you (turning a connection string into a
+`SqlClient` needs the driver you chose), so it emits a config thunk you fill in
+at the app level. It is called once per shard construction, not per request:
+
+```ts title="src/server/index.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";
+
+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 read it from any action:
 
-export const listLegacyOrders = action.input({ orgId: v.string() }).action(async ({ ctx, args: { orgId } }) => {
-    const { connectionString } = createHyperdrive(ctx.env.HYPERDRIVE);
-    ctx.sql = fromPostgresJs(postgres(connectionString));
+```ts
+import { action, v } from "@/lunora/_generated/server";
 
-    return ctx.sql.query<{ id: string; total: number }>("select id, total from orders where org = $1", [orgId]);
-});
+export const listLegacyOrders = action
+    .input({ orgId: v.string() })
+    .action(async ({ ctx, args: { orgId } }) => 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
@@ -122,10 +139,13 @@ Postgres change. To make external data reactive, write a projection into a
 `defineSchema` table from the same action — that write _is_ tracked:
 
 ```ts
+import { api } from "@/lunora/_generated/api";
+
 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 });
+// This write re-runs live queries reading `orders`. Pass the generated
+// reference — `ctx.run*` takes a reference, not a "file:fn" string.
+await ctx.runMutation(api.orders.upsert, { id: row.id, total: row.total });
 ```
 
 ## Common Pitfalls

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

@@ -70,6 +70,11 @@ Add the binding to `wrangler.jsonc` (use `localConnectionString` for `lunora dev
 }
 ```
 
+The binding is required, not optional: with no `hyperdrive` entry at all,
+`lunora dev` and `lunora deploy` both refuse to start. The NAME is yours — the
+validator only checks that some binding exists, because your `exec` selector is
+what picks it.
+
 > **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.
 

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

@@ -7,8 +7,9 @@ description: Adds transactional email to a Lunora app. Use for sending mail (ver
 
 Wire transactional email into a Lunora app using the `mail` registry item, which
 is built on `@lunora/mail` (a Cloudflare Email Workers transport with
-header-injection-safe address handling) and exposes a `sendEmail` action plus a
-fire-and-forget `queueEmail` action. In dev, every send is captured into the
+header-injection-safe address handling) and exposes a `sendEmail` `internalAction`
+plus a fire-and-forget `queueEmail` `internalAction` — server-only, because a
+client-callable general-purpose mailer is an open relay. In dev, every send is captured into the
 Studio Mail tab instead of going out.
 
 ## When to Use
@@ -21,14 +22,14 @@ Studio Mail tab instead of going out.
 
 - The project has no Lunora backend yet — use `lunora-quickstart` first.
 - Mail is already installed and you just want to send — call
-  `ctx.runAction(api.mail.sendEmail, …)` or `client.action("mail/sendEmail", …)`.
+  `ctx.runAction(internal.mail.sendEmail, …)` from a server handler.
 
 ## Workflow
 
 1. Add the `mail` item.
 2. Configure the `SEND_EMAIL` binding (or a provider) and `MAIL_FROM`.
 3. Regenerate types with `lunora codegen`.
-4. Send mail from a function (or the client); render a React template if needed.
+4. Send mail from a server function; render a React template if needed.
 
 ## Step 1: Add the item
 
@@ -40,8 +41,8 @@ This:
 
 1. Adds `@lunora/mail` and `@lunora/server` to `package.json` (run
    `pnpm install` afterwards).
-2. Copies `lunora/mail/index.ts` (the `sendEmail` / `queueEmail` actions) into
-   your project — it is **yours** to edit.
+2. Copies `lunora/mail/index.ts` (the `sendEmail` / `queueEmail`
+   **`internalAction`s**) into your project — it is **yours** to edit.
 3. Adds a `send_email` binding (`SEND_EMAIL`, with a `destination_address`
    placeholder) to `wrangler.jsonc` and scaffolds `MAIL_FROM` (the default
    sender) into `.dev.vars`.
@@ -71,24 +72,27 @@ verification and forgot-password mail — is intercepted and surfaced in the
 lunora codegen
 ```
 
-The functions surface in the generated `api` as `api.mail.sendEmail` and
-`api.mail.queueEmail`.
+The functions surface in the generated **`internal`** (server-only) namespace as
+`internal.mail.sendEmail` and `internal.mail.queueEmail` — they are deliberately
+**not** in the client-reachable `api`.
 
 ## Step 4: Send mail
 
 ### From another function
 
-`sendEmail` is an **action** (sending is non-transactional network I/O). From a
-mutation, schedule it as a follow-up so the request is not blocked:
+`sendEmail` is an **`internalAction`** (sending is non-transactional network
+I/O). From a mutation, schedule it as a follow-up so the request is not blocked:
 
 ```ts
-import { mutation, v } from "@lunora/server";
+import { internalMutation, v } from "#lunora/_generated/server.js";
 
-import { api } from "./_generated/api";
+import { internal } from "./_generated/api";
 
-export const inviteUser = mutation.input({ email: v.string() }).mutation(async ({ ctx, args: { email } }) => {
-    // ...persist the invite, then send the mail as a follow-up action
-    await ctx.scheduler.runAfter(0, api.mail.sendEmail, {
+export const inviteUser = internalMutation.input({ email: v.string() }).mutation(async ({ ctx, args: { email } }) => {
+    // ...authenticate the caller and persist the invite, then send the mail as a
+    // follow-up action. The recipient is decided server-side — never forward a
+    // client-chosen `to`/`from`/`html` straight through.
+    await ctx.scheduler.runAfter(0, internal.mail.sendEmail, {
         to: email,
         subject: "You're invited",
         html: "<p>Click the link to join.</p>",
@@ -96,15 +100,15 @@ export const inviteUser = mutation.input({ email: v.string() }).mutation(async (
 });
 ```
 
-### From a client
+### Not from a client
 
-```ts
-await client.action("mail/sendEmail", {
-    to: "alice@example.com",
-    subject: "Welcome",
-    text: "Thanks for signing up!",
-});
-```
+There is no `client.action("mail/sendEmail", …)` path, and adding one is the
+mistake this item exists to prevent: a general-purpose mailer that lets the
+caller pick recipient, subject and body is an open relay for phishing through
+your verified domain. If you need a client-callable send, write a
+_purpose-specific_ public `action` that takes only safe business inputs (e.g.
+`{ orderId }`), checks `ctx.auth`/RBAC, derives the recipient server-side,
+rate-limits it (`@lunora/ratelimit`), and calls `internal.mail.sendEmail`.
 
 ### With a React email template
 
@@ -131,8 +135,10 @@ await createMailer({ apiKey: env.RESEND_API_KEY as string, from: env.MAIL_FROM a
 1. **Expecting prod email to "just work".** Dev captures into the Studio;
    production needs the `SEND_EMAIL` binding (a verified destination) or
    `RESEND_API_KEY`.
-2. **Calling `sendEmail` as a query/mutation.** It is an action — invoke it via
-   `ctx.runAction` / `ctx.scheduler.runAfter` / `client.action`, never `ctx.db`.
+2. **Calling `sendEmail` from the client, or as a query/mutation.** It is an
+   `internalAction` — invoke it via `ctx.runAction` / `ctx.scheduler.runAfter`
+   from a server handler. A client `client.action("mail/sendEmail", …)` is not
+   reachable and answers `FUNCTION_NOT_FOUND`.
 3. **Using `queueEmail` without a Queue binding.** It requires a Cloudflare
    Queue producer binding; until you add one, `@lunora/mail` throws
    `` `queue` binding is required for mailer.queue() ``. The item does not add
@@ -145,7 +151,7 @@ await createMailer({ apiKey: env.RESEND_API_KEY as string, from: env.MAIL_FROM a
 - [ ] `lunora registry add mail` run, `pnpm install` done.
 - [ ] `SEND_EMAIL` binding configured (verified destination) or
       `RESEND_API_KEY` set; `MAIL_FROM` set.
-- [ ] `lunora codegen` run so `api.mail.*` is generated.
-- [ ] Mail sent from a function (`ctx.scheduler.runAfter`/`ctx.runAction` with
-      `api.mail.sendEmail`) or the client (`client.action("mail/sendEmail", …)`).
+- [ ] `lunora codegen` run so `internal.mail.*` is generated.
+- [ ] Mail sent from a server function (`ctx.scheduler.runAfter` / `ctx.runAction`
+      with `internal.mail.sendEmail`) — never from the client.
 - [ ] Verified the send appears in the Studio Mail tab in dev.