@lunora/cli 1.0.0-alpha.46 → 1.0.0-alpha.461

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

@@ -1,151 +1,125 @@
 ---
 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.
+description: Adds transactional email to a Lunora app with the `mail` registry item (`@lunora/mail`). Covers the server-only `internal.mail.sendEmail` / `queueEmail` actions, the `SEND_EMAIL` Cloudflare Email Workers binding, Resend via `RESEND_API_KEY`, `react-email` templates via `renderEmail`, the dev mail catcher (Studio Mail tab), E2E inbox helpers, and inbound mail. Use when the user wants to send verification, password-reset, invite or notification email, runs `lunora add email` or `lunora registry add mail`, edits `lunora/mail/index.ts`, asks why mail isn't delivered or doesn't show up in the Studio, or wants to receive email.
 ---
 
 # 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.
+The `mail` registry item wraps `@lunora/mail`, which validates addresses against
+header injection before sending. It exposes two `internalAction`s, `sendEmail`
+and `queueEmail`. Both are server-only on purpose: a mailer that lets the client
+pick the recipient, subject and body is an open relay for phishing through your
+verified domain. In dev, every send is captured into the Studio Mail tab and
+nothing is delivered.
 
-## 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.
+If the project has no Lunora backend yet, start with `lunora-quickstart`.
 
 ## Step 1: Add the item
 
 ```bash
-lunora registry add mail
+lunora add email                          # asks for the verified destination address
+lunora add email --mail-to ops@example.com
+lunora registry add mail                  # low-level: leaves the REPLACE_ME@example.com placeholder
 ```
 
-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`.
+Then run `pnpm install` and `lunora codegen`. The item does the following:
 
-## Step 2: Configure delivery
+1. Adds `@lunora/mail` and `@lunora/server`.
+2. Copies `lunora/mail/index.ts` into the project. The project owns this file. It defines `sendEmail`, which returns `{ id }`, and `queueEmail`, which returns `{ queued: true }`.
+3. Adds a `send_email` binding named `SEND_EMAIL` (with `destination_address`) to `wrangler.jsonc`.
+4. Writes `MAIL_FROM` to `.dev.vars`.
 
-| 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`. |
+Codegen emits the two functions as `internal.mail.sendEmail` and
+`internal.mail.queueEmail`. They are not in the client-reachable `api`. A client
+call to them returns `FUNCTION_NOT_FOUND`.
 
-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`.
+## Step 2: Choose the delivery path
 
-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.
+The copied file builds its mailer with `createMailerFromEnv`. That function
+picks the transport in this order:
 
-## Step 3: Regenerate types
+| Condition                                             | Transport                                           |
+| ----------------------------------------------------- | --------------------------------------------------- |
+| `LUNORA_MAIL_CAPTURE=1`, or a dev environment (below) | **Capture** into the Studio Mail tab                |
+| `SEND_EMAIL` binding present                          | Cloudflare Email Workers                            |
+| no binding, `RESEND_API_KEY` secret set               | Resend                                              |
+| none of the above                                     | throws on send (production never captures silently) |
 
-```bash
-lunora codegen
-```
-
-The functions surface in the generated `api` as `api.mail.sendEmail` and
-`api.mail.queueEmail`.
+- **Cloudflare Email Workers.** The binding sends to a single recipient, and only to verified [Email Routing](https://developers.cloudflare.com/email-routing/) destinations. That fits app-to-operator mail. Verify the address and replace the placeholder.
+- **Resend.** Use this to send to arbitrary users. Run `wrangler secret put RESEND_API_KEY` and remove the `send_email` binding. While the binding exists it takes precedence over Resend.
+- **Capture.** Capture turns on when every env-name var (`WORKER_ENV`, `NODE_ENV`, …) looks like dev. `lunora dev` sets `WORKER_ENV=development`, so capture is on in dev. Capture writes to the root shard. If `SHARD` or `LUNORA_ADMIN_TOKEN` is missing, captured mail is discarded and a one-time warning is logged. To deliver for real from dev, set `LUNORA_MAIL_CAPTURE=0`.
 
-## Step 4: Send mail
+`MAIL_FROM` is required on every path. It accepts `Name <addr@host>` or a bare
+address.
 
-### From another function
+## Step 3: Send from a server 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 action because sending is non-transactional network I/O. From
+a mutation, schedule it so the send runs only after the mutation commits:
 
 ```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,
+import { internal } from "#lunora/_generated/internal.js";
+import { mutation, v } from "#lunora/_generated/server.js";
+
+export const inviteMember = mutation.input({ teamId: v.id("teams"), email: v.string() }).mutation(async ({ ctx, args }) => {
+    // Authorize the caller and persist the invite first. The server decides
+    // the recipient and the content: never forward a client-chosen to/from/html.
+    await ctx.scheduler.runAfter(0, internal.mail.sendEmail, {
+        to: args.email,
         subject: "You're invited",
         html: "<p>Click the link to join.</p>",
     });
 });
 ```
 
-### From a client
+Sending to an arbitrary `args.email` needs the Resend path in production: the
+`SEND_EMAIL` binding only reaches its verified destination.
 
-```ts
-await client.action("mail/sendEmail", {
-    to: "alice@example.com",
-    subject: "Welcome",
-    text: "Thanks for signing up!",
-});
-```
+From an action, call `await ctx.runAction(internal.mail.sendEmail, { … })`.
 
-### With a React email template
+If a client needs to trigger a send, write a public action for that one purpose.
+It should take only business inputs (for example `{ orderId }`), check
+`ctx.auth`, derive the recipient on the server, rate-limit the call
+(`@lunora/ratelimit`), and then call `internal.mail.sendEmail`.
 
-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`:
+### React templates
 
-```ts
-import { createMailer } from "@lunora/mail";
-import { env } from "cloudflare:workers";
+A React element can't be serialized across the RPC boundary, so render it to
+`html` and `text` first. Rendering this way keeps dev capture working:
 
-import { WelcomeEmail } from "./emails/Welcome";
+```tsx
+import { renderEmail } from "@lunora/mail"; // needs `react` installed
 
-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" />,
-});
+import { WelcomeEmail } from "./emails/welcome";
+
+const { html, text } = await renderEmail(<WelcomeEmail name={name} />);
+await ctx.runAction(internal.mail.sendEmail, { to, subject: "Welcome", html, text });
 ```
 
-## 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.
+For the auth flows, `lunora add auth-emails` adds ready-made templates.
+
+### Queueing (optional)
+
+`queueEmail` requires a Cloudflare Queue producer binding passed as
+`createMailerFromEnv(env, { queue })` in `mailer()`, and the item doesn't add one. Without it, the call
+throws `` `queue` binding is required for mailer.queue() ``, except under
+capture, where it sends straight to the capture inbox so dev flows keep working.
+A consumer builds its mailer with `createMailerFromEnv` too, drains the queue
+with `consumeQueuedSend(mailer, message.body)` and then calls `message.ack()`
+for each message. On a throw, branch on `isRetryableMailError(error)`: retry with
+`message.retry()` when it is true, and ack and log when it is false, since a refused
+address or malformed body never sends and a retry only dead-letters it. With a queue bound in dev, the message still goes through the
+queue and the consumer's mailer captures it into the inbox. Queues deliver at least once: with
+per-message acks a later throw retries only the unacknowledged messages, while
+without them a single throw resends the whole batch. The full wiring is in the "Queueing"
+section of the item README.
+
+## Testing and inbound
+
+- **E2E.** `@lunora/mail/testing` exports `waitForMail({ baseUrl, adminToken, to, subjectMatch })` and `extractLink(mail, { match })`. Together they let you read the captured inbox and pull out a verification or reset link.
+- **Receiving mail.** `@lunora/mail/inbound` provides `createInboundEmailHandler`, `parseInboundEmail` and `dispatchToLunoraFunction`. They route Email Routing messages into a Lunora function. Mount them with the generated builder's `.onEmail(...)`.
+
+## Verify
+
+1. Run `lunora dev` and trigger a send. With `SHARD` and `LUNORA_ADMIN_TOKEN` set, the message should appear in the Studio Mail tab; if either is missing, capture discards it and logs a warning.
+2. Before deploying, run `lunora doctor`. It flags the placeholder destination. Confirm that `MAIL_FROM` is set, and that either the binding uses a verified destination or `RESEND_API_KEY` is set with the binding removed.

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

@@ -1,157 +1,193 @@
 ---
 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.
+description: Schedules deferred and recurring work in a Lunora app. Covers `ctx.scheduler.runAfter` / `runAt` (delayed dispatch of a function or workflow), cron jobs in `lunora/crons.ts` via `lunora registry add crons` and the `cronJobs()` builder, the `SchedulerDO` / `SCHEDULER` binding and `LUNORA_ORIGIN_URL`, retries and dead-lettering, and `createWorkpool` for bounded concurrency. Use when the user wants to "run this later", "send a reminder in 3 days", "run every night / every 5 minutes", add a cron, cancel a scheduled job, or sees `ORIGIN_NOT_CONFIGURED` or a missing `SchedulerDO` export.
 ---
 
 # Lunora Setup Scheduler
 
-Schedule work in Lunora two ways, both backed by `@lunora/scheduler` (re-exported
-from `@lunora/server`):
+Lunora schedules work in two ways, both implemented in `@lunora/scheduler`:
 
-- **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`.
+- **Deferred dispatch**: `ctx.scheduler.runAfter` / `runAt` run a function (or
+  start a workflow) later. Jobs are stored in the `SchedulerDO` Durable Object
+  (binding `SCHEDULER`), which owns the alarm, the retries and the dead-letter list.
+- **Recurring jobs (crons)**: declared in `lunora/crons.ts` with `cronJobs()`.
+  Codegen compiles them into Cloudflare Cron Triggers, and the Worker's
+  `scheduled()` handler dispatches them directly. They don't go through the
+  `SchedulerDO`.
 
-Both run jobs through the `SchedulerDO` Durable Object (binding `SCHEDULER`),
-which owns the alarm and durable storage.
+## When Not to Use
 
-## When to Use
+- The project has no Lunora backend yet: use `lunora-quickstart` first.
+- You only need to react to data changes: use a reactive `query` /
+  subscription (`lunora-realtime`).
+- Multi-step orchestration with sleeps and waits belongs in a durable workflow.
+  A scheduler or cron can start one, but don't build step logic on top of jobs.
 
-- 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).
+## Deferred dispatch: `runAfter` / `runAt`
 
-## When Not to Use
+### Wire it once
 
-- 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.
+```bash
+pnpm add @lunora/scheduler
+lunora codegen
+```
 
-## Deferred dispatch — `runAfter` / `runAt`
+Codegen needs `@lunora/scheduler` installed as soon as `ctx.scheduler` is used,
+because the generated `_generated/app.ts` imports `createScheduler`. Once the
+dependency is present, codegen emits `_generated/scheduler.ts` (re-exporting
+`SchedulerDO`) and a `.scheduler()` method on the app builder.
 
-Available on `ctx.scheduler` in any function. Target functions are passed by
-reference from the generated `api` / `internal` proxy:
+- **Vite-first apps** (generated worker entry): the plugin forwards
+  `SchedulerDO` and calls `.scheduler()` for you.
+- **Hand-written worker entry** (`src/server.ts` with `defineApp`): wire it yourself.
+  `wrangler.jsonc`'s `SCHEDULER` binding is reconciled from this export:
 
 ```ts
-import { mutation, v } from "@lunora/server";
+const app = defineApp<Env>()
+    .shard((env) => env.SHARD)
+    .scheduler({ namespace: (env) => env.SCHEDULER })
+    .build();
+
+export const ShardDO = app.ShardDO;
+export { SchedulerDO } from "../lunora/_generated/scheduler.js";
+```
+
+The `SchedulerDO` calls back into the Worker at `LUNORA_ORIGIN_URL`. It reads
+that value from its own env and never from the request, so a caller can't point
+dispatch at an arbitrary URL. Without it, every `runAfter`/`runAt` fails with
+`ORIGIN_NOT_CONFIGURED`, and nothing provisions it for you:
 
-import { internal } from "./_generated/api";
+- dev: `LUNORA_ORIGIN_URL="http://localhost:5173"` in `.dev.vars` (your dev
+  server's URL)
+- prod: `vars.LUNORA_ORIGIN_URL` in `wrangler.jsonc`, or
+  `wrangler secret put LUNORA_ORIGIN_URL` (per `--env`)
 
-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 });
+`lunora doctor` warns when the scheduler binding exists and the variable is unset.
 
-    return { jobId: id };
+### Schedule from a mutation or action
+
+```ts
+import { LunoraError } from "lunorash/server";
+
+import { internal } from "#lunora/_generated/internal.js";
+import { mutation } from "#lunora/_generated/server.js";
+
+export const startTrial = mutation.mutation(async ({ ctx }) => {
+    // the caller's own id, never one the client passes in
+    const { userId } = ctx.auth;
+    if (!userId) {
+        throw new LunoraError("UNAUTHORIZED", "not signed in");
+    }
+    // run an internal action 14 days from now; the id is a plain string
+    const jobId = await ctx.scheduler.runAfter(14 * 24 * 60 * 60 * 1000, internal.billing.endTrial, { userId });
+
+    return { jobId };
 });
 ```
 
-- `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
+- The full `ctx.scheduler` surface is `runAfter(delayMs, target, args?)`,
+  `runAt(timestampMs, target, args?)` (epoch ms), `cancel(id)`, `get(id)`, and `list()`.
+  It is not available in a `query`, because queries are deterministic and re-run.
+- `target` is a generated `internal.*` / `api.*` mutation or action reference, a
+  `"file:fn"` string, or a `workflows.<name>` / `agents.<name>` reference.
+  A workflow or agent reference starts a fresh instance when the job fires, with
+  `args` as its params. Scheduled jobs run with no end-user identity, so target
+  `internal.*` functions.
+- **Inside a mutation, scheduling is transactional.** The call is buffered and
+  dispatched only after the mutation commits. If the mutation rolls back (OCC
+  conflict, validation error), the job is dropped too. The returned id is final
+  immediately, so you can store it on the row you're writing and `cancel` it later.
+- Retries use the DO defaults: 5 retries, exponential backoff from 30 s. A job
+  that exhausts them is dead-lettered (visible in the studio), not dropped. To set
+  a per-job `retry` policy (`{ maxAttempts, backoff: "exponential" | "linear",
+baseMs, maxMs }`) or a `shardKey`, build your own client with
+  `createScheduler({ namespace })` from `@lunora/scheduler`. Its `runAfter`/`runAt`
+  take a fourth `RunOptions` argument and add `dead()` / `deadRetry(id)`.
+
+## Recurring jobs: crons
 
 ### Step 1: Add the starter
 
 ```bash
 lunora registry add crons
+pnpm install
 ```
 
-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.
+This adds `@lunora/server` + `@lunora/scheduler` to `package.json` and copies two
+files you own: `lunora/crons.ts` (a `cronJobs()` registry) and
+`lunora/crons/jobs.ts` (an example `internalMutation`, `internal.crons.jobs.run`).
 
 ### Step 2: Declare jobs
 
 ```ts
 import { cronJobs } from "@lunora/server";
 
-import { internal } from "./_generated/api";
+import { internal } from "#lunora/_generated/internal.js";
 
 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
+crons.interval("purge sessions", { minutes: 5 }, internal.sessions.purgeExpired, {});
+crons.hourly("rollup", { minuteUTC: 17 }, internal.stats.rollup);
+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).
+- Names must be non-empty string literals, unique across the project.
+- Targets must be static property accesses (`internal.<…path>.<fn>`, one segment
+  per folder and file, e.g. `internal.crons.jobs.run`) or a `workflows.<name>` /
+  `agents.<name>` reference. Codegen resolves them from the AST, so a computed
+  reference fails codegen. `args` is optional and must be a literal.
+- Schedules are UTC and validated when the job is defined. `interval` takes exactly one of
+  `{ minutes }` (must divide 60) or `{ hours }` (must divide 24). `{ seconds }`
+  is rejected because Cron Triggers have a one-minute floor. For sub-minute work,
+  use `runAfter`.
+- Use `hourly` with an offset minute to spread jobs away from `:00`.
 
-### Step 3: Regenerate types and the schedule
+### Step 3: Regenerate
 
 ```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.
+Codegen emits `lunora/_generated/crons.ts` (`LUNORA_CRON_TRIGGERS` plus the
+`LUNORA_CRONS` dispatcher map, which `defineApp` wires into `scheduled()`) and
+syncs `triggers.crons` in `wrangler.jsonc`. Don't hand-edit that array.
+
+**Verify:** the studio's scheduled-jobs view lists each cron and has a "Run now"
+action, which calls the same dispatch path as a real tick.
 
-## Bounded concurrency — workpool (optional)
+## 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):
+A workpool is a named pool inside the same `SchedulerDO`. It needs no extra
+binding. Build it in Worker code that has the raw `env`:
 
 ```ts
 import { createWorkpool } from "@lunora/scheduler";
 
-const pool = createWorkpool({
-    namespace: env.SCHEDULER,
-    originUrl: "https://my-app.example.com",
-    name: "imports",
-    maxConcurrency: 3,
-});
+const pool = createWorkpool({ namespace: env.SCHEDULER, name: "imports", maxConcurrency: 3 });
 
-await pool.enqueue(internal.imports.processRow, { rowId });
+await pool.enqueue(internal.imports.processRow, { rowId }, { retry: { maxAttempts: 3 } });
+// pool.cancel(id), pool.status() → { inFlight, queued, maxConcurrency }
 ```
 
-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.
+The DO dispatches at most `maxConcurrency` jobs at once and queues the rest
+durably. One alarm drain keeps at most six dispatches in flight (the DO connection limit),
+so a long-running job holds a slot for its whole duration. For individually long jobs
+(LLM calls, exports), prefer `createQueueWorkpool`, which is backed by Cloudflare Queues.
+You give up the hard cap, per-job cancel and per-job status in exchange.
 
 ## 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.
+1. **`ORIGIN_NOT_CONFIGURED`**: `LUNORA_ORIGIN_URL` is unset for the `SchedulerDO`
+   (see above).
+2. **`SchedulerDO` not exported** from a hand-written worker entry: wrangler
+   only binds classes the entry exports, so `SCHEDULER` is never provisioned.
+3. **Dynamic `name` or target in `cronJobs()`**: codegen cannot discover it.
+4. **Editing crons without re-running `lunora codegen`**: `triggers.crons` and the
+   dispatcher map are generated output and go stale.
+5. **Non-idempotent handlers**: a failed job is retried, and a slow cron tick
+   can overlap the next one.