@lunora/cli 0.0.0 → 1.0.0-alpha.2

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.

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

@@ -0,0 +1,151 @@
+---
+name: lunora-setup-mail
+description: Adds transactional email to a Lunora app. Use for sending mail (verification, password reset, invites, notifications) via `lunora registry add mail`, the `sendEmail` / `queueEmail` actions, the `SEND_EMAIL` Cloudflare Email Workers binding, Resend, React email templates, and the dev mail catcher.
+---
+
+# Lunora Setup Mail
+
+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
+Studio Mail tab instead of going out.
+
+## When to Use
+
+- Sending app→user mail: invites, notifications, receipts.
+- Delivering verification / password-reset mail from `@lunora/auth`.
+- Using a React (`react-email`) template or a hosted provider (Resend).
+
+## When Not to Use
+
+- 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", …)`.
+
+## 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.
+
+## Step 1: Add the item
+
+```bash
+lunora registry add mail
+```
+
+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.
+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`.
+
+## Step 2: Configure delivery
+
+| Name             | Where                                | Notes                                                                             |
+| ---------------- | ------------------------------------ | --------------------------------------------------------------------------------- |
+| `SEND_EMAIL`     | `wrangler.jsonc` → `send_email[]`    | Cloudflare Email Workers binding. Single-recipient; only verified destinations.   |
+| `MAIL_FROM`      | var (`.dev.vars` / `wrangler.jsonc`) | Default sender address.                                                           |
+| `RESEND_API_KEY` | secret (optional)                    | Use a hosted provider instead — pass `apiKey` to `createMailer` in `lunora/mail`. |
+
+For production with Cloudflare Email Workers, set up
+[Email Routing](https://developers.cloudflare.com/email-routing/): verify a
+destination address and replace the `REPLACE_ME@example.com` placeholder. Prefer
+Resend? Pass `apiKey` (or a custom `transport`) to `createMailer` in your copied
+`lunora/mail/index.ts`.
+
+In `lunora dev` (`WORKER_ENV=development`) the scaffold swaps in `@lunora/mail`'s
+**capture transport** automatically: every send — including `@lunora/auth`'s
+verification and forgot-password mail — is intercepted and surfaced in the
+**Studio Mail tab**. Nothing leaves your machine and no provider setup is needed.
+
+## Step 3: Regenerate types
+
+```bash
+lunora codegen
+```
+
+The functions surface in the generated `api` as `api.mail.sendEmail` and
+`api.mail.queueEmail`.
+
+## 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:
+
+```ts
+import { mutation, v } from "@lunora/server";
+
+import { api } 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, {
+        to: email,
+        subject: "You're invited",
+        html: "<p>Click the link to join.</p>",
+    });
+});
+```
+
+### From a client
+
+```ts
+await client.action("mail/sendEmail", {
+    to: "alice@example.com",
+    subject: "Welcome",
+    text: "Thanks for signing up!",
+});
+```
+
+### With a React email template
+
+React elements are not JSON-serializable across the RPC boundary, so the
+`sendEmail` args take `html` / `text`. To use a `react-email` template, render it
+where you call the mailer — edit `lunora/mail/index.ts` to pass `react` straight
+into `mailer.send`:
+
+```ts
+import { createMailer } from "@lunora/mail";
+import { env } from "cloudflare:workers";
+
+import { WelcomeEmail } from "./emails/Welcome";
+
+await createMailer({ apiKey: env.RESEND_API_KEY as string, from: env.MAIL_FROM as string }).send({
+    to: "alice@example.com",
+    subject: "Welcome",
+    react: <WelcomeEmail name="Alice" />,
+});
+```
+
+## Common Pitfalls
+
+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`.
+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
+   the Queue for you — see the `mail` README's "Queueing" section.
+4. **Passing a React element through the action args.** Render it inside the
+   mailer (`mailer.send({ react })`), not across the RPC boundary.
+
+## Checklist
+
+- [ ] `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", …)`).
+- [ ] Verified the send appears in the Studio Mail tab in dev.

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

@@ -0,0 +1,157 @@
+---
+name: lunora-setup-scheduler
+description: Schedules deferred and recurring work in a Lunora app. Use for `ctx.scheduler.runAfter` / `runAt` (delayed function dispatch), cron jobs via `lunora registry add crons` (the `cronJobs()` builder), the `SchedulerDO` / `SCHEDULER` binding, retries, and the workpool for bounded concurrency.
+---
+
+# Lunora Setup Scheduler
+
+Schedule work in Lunora two ways, both backed by `@lunora/scheduler` (re-exported
+from `@lunora/server`):
+
+- **Deferred dispatch** — `ctx.scheduler.runAfter` / `runAt` from any function,
+  to run a function later. Built into the runtime; **no registry install**.
+- **Recurring jobs (crons)** — declare them in `lunora/crons.ts` with
+  `cronJobs()`. Add the starter with `lunora registry add crons`.
+
+Both run jobs through the `SchedulerDO` Durable Object (binding `SCHEDULER`),
+which owns the alarm and durable storage.
+
+## When to Use
+
+- Running a function after a delay or at a specific time
+  (`runAfter` / `runAt`).
+- Declaring recurring jobs (sweep, digest, report) on a cron schedule.
+- Bounding concurrency for many enqueued jobs (a workpool).
+
+## When Not to Use
+
+- The project has no Lunora backend yet — use `lunora-quickstart` first.
+- You just need to react to live data changes — use a reactive `query` /
+  subscription (`lunora-realtime`), not a scheduled job.
+
+## Deferred dispatch — `runAfter` / `runAt`
+
+Available on `ctx.scheduler` in any function. Target functions are passed by
+reference from the generated `api` / `internal` proxy:
+
+```ts
+import { mutation, v } from "@lunora/server";
+
+import { internal } from "./_generated/api";
+
+export const startTrial = mutation.input({ userId: v.string() }).mutation(async ({ ctx, args: { userId } }) => {
+    // run an internal action 14 days from now
+    const { id } = await ctx.scheduler.runAfter(14 * 24 * 60 * 60 * 1000, internal.billing.endTrial, { userId });
+
+    return { jobId: id };
+});
+```
+
+- `runAfter(delayMs, fnRef, args, options?)` — run after a delay (`delayMs` must
+  be a non-negative finite number). `runAt(date, fnRef, args, options?)` — run at
+  a `Date` or epoch-ms timestamp.
+- Both return `{ id, scheduledFor }`. Cancel with `ctx.scheduler.cancel(id)`;
+  inspect with `ctx.scheduler.get(id)` / `ctx.scheduler.list()`.
+- `options` accepts a `retry` policy (`{ maxAttempts, backoff, baseMs, maxMs }`;
+  DO defaults: `maxAttempts: 5`, `backoff: "exponential"`, `baseMs: 30_000`) and
+  a `shardKey` routing hint. On retry exhaustion the job is dead-lettered, never
+  silently dropped.
+- The `SchedulerDO` binding (`SCHEDULER`) is **auto-inferred and reconciled**
+  into `wrangler.jsonc` by `@lunora/config` once `@lunora/scheduler` is in use —
+  run `lunora codegen` / `lunora doctor` to confirm. Scheduled jobs run with no
+  end-user identity, so target **internal** functions (`internal.*`).
+
+## Recurring jobs — crons
+
+### Step 1: Add the starter
+
+```bash
+lunora registry add crons
+```
+
+This adds `@lunora/server` to `package.json` (run `pnpm install`) and copies
+`lunora/crons.ts` (a `cronJobs()` registry with one illustrative job) and
+`lunora/crons/jobs.ts` (the example `run` internal mutation it fires) into your
+project — both **yours** to edit. No extra DO binding is required.
+
+### Step 2: Declare jobs
+
+```ts
+import { cronJobs } from "@lunora/server";
+
+import { internal } from "./_generated/api";
+
+const crons = cronJobs();
+
+crons.interval("sweep presence", { minutes: 5 }, internal.presence.sweep, { roomId: "lobby" });
+crons.daily("digest", { hourUTC: 9, minuteUTC: 0 }, internal.email.digest, {});
+crons.weekly("report", { dayOfWeek: "monday", hourUTC: 8, minuteUTC: 0 }, internal.reports.weekly, {});
+crons.monthly("invoice", { day: 1, hourUTC: 0, minuteUTC: 0 }, internal.billing.invoice, {});
+crons.cron("custom", "0 */6 * * *", internal.foo.bar, {}); // raw cron escape hatch
+
+export default crons;
+```
+
+- `name` must be a non-empty **string literal**, unique across the project.
+- `fnRef` must be a static two-segment access on the proxy
+  (`internal.<file>.<fn>` or `api.<file>.<fn>`) so codegen can discover it.
+  Cron targets must be **internal** functions — a client can never invoke them.
+- All schedules are UTC and validated at definition time
+  (`hourUTC: 25` throws immediately).
+
+### Step 3: Regenerate types and the schedule
+
+```bash
+lunora codegen
+```
+
+Codegen discovers each registration by AST, compiles the schedule to a cron
+expression, and emits `lunora/_generated/crons.ts` (the dispatcher the Worker's
+`scheduled()` handler consumes) plus the matching `triggers.crons` entry in
+`wrangler.jsonc`. You never hand-edit the wrangler schedule array.
+
+## Bounded concurrency — workpool (optional)
+
+For many enqueued jobs that must not all run at once, use a workpool — a named
+logical pool inside the same `SchedulerDO` (no extra binding):
+
+```ts
+import { createWorkpool } from "@lunora/scheduler";
+
+const pool = createWorkpool({
+    namespace: env.SCHEDULER,
+    originUrl: "https://my-app.example.com",
+    name: "imports",
+    maxConcurrency: 3,
+});
+
+await pool.enqueue(internal.imports.processRow, { rowId });
+```
+
+The DO caps simultaneous dispatch at `maxConcurrency` and queues the rest
+durably. A Cloudflare-Queues-backed variant (`createQueueWorkpool`) leans on
+queue config for concurrency/retries instead — reach for the DO workpool when you
+need per-job cancel / status.
+
+## Common Pitfalls
+
+1. **Targeting a non-internal function from a job/cron.** Scheduled dispatch has
+   no end-user identity — target `internal.*` functions.
+2. **Non-static `fnRef` or `name` in `cronJobs()`.** Codegen discovers them by
+   AST; a dynamic reference or computed name can't be found.
+3. **Forgetting `lunora codegen` after editing crons.** The `triggers.crons`
+   array and the dispatcher map are codegen output — re-run it.
+4. **Non-idempotent job handlers.** A missed tick may be retried and a slow tick
+   can overlap the next — make handlers idempotent.
+
+## Checklist
+
+- [ ] Deferred work uses `ctx.scheduler.runAfter` / `runAt` against
+      `internal.*` functions.
+- [ ] `SCHEDULER` (SchedulerDO) binding present in `wrangler.jsonc`
+      (`lunora doctor` clean) when using the scheduler.
+- [ ] Recurring jobs declared in `lunora/crons.ts` via `cronJobs()` (after
+      `lunora registry add crons`).
+- [ ] `lunora codegen` run so `_generated/crons.ts` + `triggers.crons` are
+      synced.
+- [ ] Job handlers are idempotent.