@lunora/cli 1.0.0-alpha.361 → 1.0.0-alpha.363

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

@@ -1,162 +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 a **mutation or an action** — never a `query`,
-which is deterministic and re-runs. Target functions are passed by reference
-from the generated `api` / `internal` objects (a `"file:fn"` path string also
-works):
+- **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/_generated/server.js";
+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";
+```
 
-import { internal } from "./_generated/internal";
+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:
 
-export const startTrial = mutation.input({ userId: v.string() }).mutation(async ({ ctx, args: { userId } }) => {
-    // run an internal action 14 days from now
+- 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`)
+
+`lunora doctor` warns when the scheduler binding exists and the variable is unset.
+
+### 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?)` — run after a delay (`delayMs` must be a
-  non-negative finite number). `runAt(timestampMs, fnRef, args?)` — run at an
-  epoch-ms timestamp.
-- Both resolve the job id. Cancel with `ctx.scheduler.cancel(id)`;
-  inspect with `ctx.scheduler.get(id)` / `ctx.scheduler.list()`.
-- Those three arguments are the whole `ctx.scheduler` surface. Per-job
-  `RunOptions` — a `retry` policy (`{ maxAttempts, backoff, baseMs, maxMs }`), a
-  `shardKey` routing hint, `pool` — live on `@lunora/scheduler`'s own
-  `createScheduler(...)` client, which you construct yourself when you need them.
-  Jobs scheduled through `ctx.scheduler` take the DO defaults: 5 retries,
-  `backoff: "exponential"`, `baseMs: 30_000`. 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/internal";
+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.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 property access on the generated object
-  (`internal.<…path>.<fn>` or `api.<…path>.<fn>`, one segment per folder and
-  file, e.g. `internal.crons.jobs.run`) 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,
-    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.

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

@@ -1,108 +1,72 @@
 ---
 name: lunora-setup-storage
-description: Adds R2-backed file storage to a Lunora app. Use for uploads/downloads via `lunora registry add storage`, signed PUT/GET URLs, the `UPLOADS` R2 bucket binding, `STORAGE_SIGNING_SECRET`, per-tenant key scoping, and verifying downloads in the Worker.
+description: Adds R2-backed file storage to a Lunora app with the `storage` registry item (`@lunora/storage`). Covers worker-signed PUT/GET URLs, the `UPLOADS` R2 bucket binding, `STORAGE_SIGNING_SECRET` and `STORAGE_PUBLIC_BASE_URL`, per-user key scoping, and the `/storage/*` Worker route that verifies signatures and moves the bytes. Use when the user wants file or image uploads, avatars, attachments or gated downloads, runs `lunora add storage` or `lunora registry add storage`, edits `lunora/storage/index.ts`, or sees signed storage URLs return 404/403 or uploads fail CORS.
 ---
 
 # Lunora Setup Storage
 
-Wire R2-backed file storage into a Lunora app using the `storage` registry item,
-which is built on `@lunora/storage` (an R2 adapter plus HMAC signed-URL helpers)
-and exposes idiomatic Lunora functions for browser uploads, gated downloads,
-delete, and list — with no bucket credential in the client.
+The `storage` registry item wraps `@lunora/storage`, an R2 adapter with HMAC
+signed-URL helpers. It exposes Lunora functions for browser uploads, gated
+downloads, delete and list. The client never holds a bucket credential.
 
-A worker-signed URL points at **your Worker**, not at R2:
-`<base>/<key>?exp&method&bucket&sig`, where the base is the origin the request
-reached your Worker on (`ctx.origin`) unless `STORAGE_PUBLIC_BASE_URL` overrides
-it. The `/storage/*` route
-you add in step 4 is what verifies the signature and moves the bytes, for both
-the upload and the download. (The no-Worker-in-the-path variant is
-`@lunora/storage`'s S3 presigned URL, `getPresignedUrl` — it needs S3 credentials
-on the bucket and enforces none of your rules.)
+A worker-signed URL points at your Worker, not at R2. Its shape is
+`<base>/<key>?exp&method&bucket&sig`. The base is `ctx.origin` unless
+`STORAGE_PUBLIC_BASE_URL` overrides it. The `/storage/*` route from Step 3
+verifies the signature and moves the bytes, for both upload and download.
+`@lunora/storage`'s `getPresignedUrl` takes the Worker out of the path, but it
+needs S3 credentials and none of your rules apply to it.
 
-## When to Use
-
-- Uploading user files (avatars, attachments) into R2 under your own gate.
-- Serving private/gated downloads via short-lived signed URLs.
-- Listing or deleting a caller's stored objects.
-
-## When Not to Use
-
-- The project has no Lunora backend yet — use `lunora-quickstart` first.
-- Storage is already installed and you just want to upload — call
-  `client.action("storage/generateUploadUrl", …)` and `PUT` to the returned URL.
-
-## Workflow
-
-1. Add the `storage` item.
-2. Configure the `UPLOADS` R2 bucket binding and the signing secret.
-3. Regenerate types with `lunora codegen`.
-4. Add the `/storage/*` route to the Worker — it verifies signatures and serves
-   both the signed `PUT` and the signed `GET`.
-5. Upload/download from the client.
+If the project has no Lunora backend yet, start with `lunora-quickstart`.
 
 ## Step 1: Add the item
 
 ```bash
-lunora registry add storage
+lunora add storage                          # asks for the R2 bucket name
+lunora add storage --bucket my-app-uploads
+lunora registry add storage                 # low-level: writes bucket_name "replace-me-uploads"
 ```
 
-This:
-
-1. Adds `@lunora/storage` and `@lunora/server` to `package.json` (run
-   `pnpm install` afterwards).
-2. Adds an R2 bucket binding to `wrangler.jsonc` (`r2_buckets`, binding
-   **`UPLOADS`**, `bucket_name: "replace-me-uploads"` — rename it to a real
-   bucket). It **merges** into any existing `r2_buckets`.
-3. Scaffolds `STORAGE_SIGNING_SECRET` (a secret) and an empty, optional
-   `STORAGE_PUBLIC_BASE_URL` into `.dev.vars`.
-4. Copies `lunora/storage/index.ts` (the `generateUploadUrl` /
-   `getDownloadUrl` / `deleteObject` / `listObjects` functions) into your
-   project — it is **yours** to edit.
+Then run `pnpm install` and `lunora codegen`. The item does the following:
 
-## Step 2: Configure the binding + secrets
+1. Adds `@lunora/storage`, `@lunora/server`, `@lunora/errors` and `@lunora/ratelimit`.
+2. Merges an R2 binding named `UPLOADS` into `r2_buckets` in `wrangler.jsonc`.
+3. Writes `STORAGE_SIGNING_SECRET` (a secret) to `.dev.vars`, plus an empty, optional `STORAGE_PUBLIC_BASE_URL`.
+4. Copies `lunora/storage/index.ts` into the project. The project owns this file. Codegen exposes its functions as `api.storage.generateUploadUrl`, `getDownloadUrl` and `listObjects` (actions) and `deleteObject` (mutation). Every one requires a signed-in user, because `requireOwner` throws `UNAUTHORIZED` otherwise, so set up auth first (`lunora-setup-auth`). Each is rate-limited per user to 60 requests a minute through an in-memory, per-isolate limiter. For a durable limiter, run `lunora add ratelimit`.
 
-| Name                      | Where                                        | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| ------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `UPLOADS`                 | `wrangler.jsonc` → `r2_buckets[]`            | The R2 bucket binding. Point `bucket_name` at a real bucket.                                                                                                                                                                                                                                                                                                                                                                              |
-| `STORAGE_SIGNING_SECRET`  | secret (`.dev.vars` / `secret put`)          | HMAC secret for signed URLs. Min 32 chars, enforced — a shorter one throws on the first call. Never share across tenants.                                                                                                                                                                                                                                                                                                                 |
-| `STORAGE_PUBLIC_BASE_URL` | optional var (`.dev.vars` / Worker variable) | Leave it **empty** and URLs are signed against the origin the request reached your Worker on (`ctx.origin`), right in dev, previews and production alike. Set a **bare origin** only when another host (a CDN) serves `/storage/*`, or to sign where no request is behind the call: a query, a scheduled job, a workflow step have no `ctx.origin`, so signing there without it throws. A base carrying a path is rejected by the signer. |
+## Step 2: Configure the binding and secrets
 
-A configured `STORAGE_PUBLIC_BASE_URL` must be `https://` anywhere but local dev. A signed URL
-_is_ a bearer credential and the object bytes stream through it, so a plaintext
-origin hands both to anyone on the path. Only `http://localhost` /
-`http://127.0.0.1` belong in `.dev.vars`.
+| Name                      | Where                           | Notes                                                                                                                                   |
+| ------------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `UPLOADS`                 | `wrangler.jsonc` → `r2_buckets` | Set `bucket_name` to a real bucket: lowercase letters, digits and hyphens, 3–63 chars. Otherwise wrangler rejects it.                   |
+| `STORAGE_SIGNING_SECRET`  | secret                          | At least 32 chars; a shorter secret throws on the first call. Use `openssl rand -base64 32`, then `wrangler secret put` for production. |
+| `STORAGE_PUBLIC_BASE_URL` | optional var                    | See below.                                                                                                                              |
 
-Generate a real signing secret with `openssl rand -base64 32` and write it with
-`wrangler secret put STORAGE_SIGNING_SECRET` for production.
+Leave `STORAGE_PUBLIC_BASE_URL` empty for most apps. URLs are then signed
+against `ctx.origin`, which is correct in dev, in previews and in production.
+Set it only in two cases:
 
-## Step 3: Regenerate types
-
-```bash
-lunora codegen
-```
+- Another host, such as a CDN, serves `/storage/*`.
+- You sign where no request is behind the call: a query, a scheduled job or a workflow step. None of these has a `ctx.origin`, so signing there throws.
 
-The functions surface in the generated `api` as `api.storage.generateUploadUrl`,
-`api.storage.getDownloadUrl`, `api.storage.deleteObject`, and
-`api.storage.listObjects`.
+The value must be a bare origin. The key is verified from the whole URL
+pathname, so the signer rejects a base that includes a path. Outside local dev
+the value must use `https://`, because a signed URL is a bearer credential.
 
-## Step 4: Add the `/storage/*` route to the Worker
+## Step 3: Add the `/storage/*` route to the Worker
 
-**Required, not optional.** Without it a minted URL hits the Lunora catch-all and
-every upload and download 404s — and it is the only thing checking the signature,
-so skipping the check lets anyone read any key.
+The app needs this route. Without it, every minted URL falls through to the
+Lunora catch-all and returns 404. The route is also the only place the signature
+is checked, so a route that skips `verifySignedUrl` lets anyone read any key.
 
-`@lunora/server`'s `serveStorageObject(ctx, key, request, authorize)` handles
-the download half (`Range`/206, `ETag`, `nosniff`, and
-`content-disposition: attachment` for anything outside a small inline-safe set —
-raster images plus `audio/mpeg`, `audio/ogg`, `audio/wav`, `video/mp4`,
-`video/webm`, with `image/svg+xml` deliberately excluded). It verifies nothing on
-its own — its required `authorize` gate is where `verifySignedUrl` goes — and it
-does not handle the upload. Reach for it from an `httpAction`, where `ctx.storage`
-is in scope, whenever you want `Range` seeking or conditional requests.
+`@lunora/server`'s `serveStorageObject(ctx, key, request, authorize)` covers the
+download half. It handles `Range`/206, `ETag`, `nosniff` and the inline-safe
+`content-disposition` list. It verifies nothing on its own, so call
+`verifySignedUrl` inside its `authorize` gate. It also doesn't handle uploads.
+Use it from an `httpAction`, where `ctx.storage` is in scope, when you need
+`Range` seeking.
 
-The route below is the standalone version — a plain worker `fetch` with only the
-R2 binding to hand, so it serves whole objects and skips `Range`/`ETag`. Both
-verbs, by hand:
+The standalone route below is a plain Worker `fetch` that only has the R2
+binding. It handles both verbs and serves whole objects:
 
 ```ts
 import { isSafeHeaderValue } from "@lunora/server";
@@ -240,79 +204,49 @@ export default {
 };
 ```
 
-**Why the CORS lines are there.** If `STORAGE_PUBLIC_BASE_URL` is not your app's
-own origin, the browser `PUT` below is preflighted (`PUT` is not a simple method,
-and `content-type: image/png` is not a safelisted value). Answering `OPTIONS` is
-only half of it: the browser also reads
-`access-control-allow-origin` off the **real** response, so the 204 and the
-download response carry `...cors` too — a route that answers only the preflight
-passes it and then fails the request it was preflighting.
-
-Keep `STORAGE_PUBLIC_BASE_URL` same-origin if you would rather not maintain an
-allowlist; then `ALLOWED_ORIGINS` can be empty and `cors` never adds a header
-beyond `vary: origin`.
+CORS: if `STORAGE_PUBLIC_BASE_URL` is a different origin from the app, the
+browser preflights the `PUT`. The browser then reads
+`access-control-allow-origin` from the real response as well, which is why the
+204 and the download response also spread `...cors`. Keep the base same-origin
+and `ALLOWED_ORIGINS` can stay empty.
 
-`verifySignedUrl` checks expiry, then the HMAC. On a host-rewrite / CDN topology
-pass `{ expectedHost }` (the `STORAGE_PUBLIC_BASE_URL` host) so the signature
-canonicalizes against the host it was minted for.
+On a CDN or host-rewrite setup, pass `{ expectedHost }` to `verifySignedUrl`,
+set to the host of `STORAGE_PUBLIC_BASE_URL`, so the signature is checked
+against the host the URL was minted for.
 
-## Step 5: Upload / download from the client
+## Step 4: Upload and download from the client
 
 ```ts
-// 1. ask the server for a signed PUT URL
-const { key, url } = await client.action("storage/generateUploadUrl", {
-    key: "avatar.png",
-    contentType: file.type,
-});
-
-// 2. upload it — the URL points at your Worker's `/storage/*` route, which
-//    verifies the signature and writes to R2. The content type is pinned into
-//    the signature (and carried on the URL as `&ct=`); that signed value is what
-//    gets stored, so the request's own `content-type` header is not read and
-//    cannot override it.
+import { api } from "../lunora/_generated/api"; // path relative to your client file
+
+// 1. Mint a signed PUT URL. contentType must be in ALLOWED_UPLOAD_CONTENT_TYPES
+//    in lunora/storage/index.ts. The type is pinned into the signature, and the
+//    route stores that pinned value, not the request header.
+const { key, url } = await client.action(api.storage.generateUploadUrl, { key: "avatar.png", contentType: file.type });
+
+// 2. Upload straight to the Worker's /storage/* route.
 await fetch(url, { method: "PUT", headers: { "content-type": file.type }, body: file });
 
-// 3. later, get a signed GET URL to display it
-const { url: downloadUrl } = await client.action("storage/getDownloadUrl", { key: "avatar.png" });
+// 3. Later, mint a signed GET URL to display it.
+const { url: downloadUrl } = await client.action(api.storage.getDownloadUrl, { key: "avatar.png" });
 ```
 
-Every key is scoped per-tenant with `scopeKey(requireOwner(ctx.auth.userId),
-key)` — `requireOwner` returns `storage/<userId>` — so a client-supplied key can
-never address another user's data, and the `storage/` prefix is what lands the
-minted URL on the `/storage/*` route. The functions return the **scoped** key
-(`storage/<userId>/avatar.png`) alongside the URL; persist that, and pass the
-bare key back in — the component re-scopes it.
-
-## Common Pitfalls
-
-1. **Skipping `verifySignedUrl` on the download route.** Without it, anyone can
-   read any key. Always verify before streaming.
-2. **Placeholder bucket name.** `lunora init` and `lunora add storage` prompt for
-   the bucket name (or take `--bucket <name>`), but the low-level
-   `lunora registry add storage` writes the placeholder
-   `bucket_name: "replace-me-uploads"` — rename it to a real R2 bucket. (R2 names
-   are lowercase alphanumeric + hyphens, 3–63 chars; wrangler rejects anything
-   else on `dev`/`deploy`.)
-3. **Short / shared signing secret.** ≥32 chars is enforced (the item throws on
-   the first call below it). Cross-_bucket_ replay is not a risk here — the
-   bucket name is part of the HMAC canonical and rides on the URL as `&bucket=`,
-   so a URL minted for one bucket never verifies against another under the same
-   secret. Cross-_tenant_ reuse is the real hazard: one secret shared between two
-   apps lets either mint URLs the other's route will honour, so keep a distinct
-   secret per deployment.
-4. **Base URL with a path.** `STORAGE_PUBLIC_BASE_URL` must be a bare origin. The
-   key is verified from the whole URL pathname, so a subpath base would make
-   every minted URL fail verification — `buildSignedUrl` rejects it up front.
-5. **Routing the body through a Lunora function.** Uploads and downloads go
-   through the thin `/storage/*` route, which streams to and from R2 — don't
-   read the file into a `query`/`mutation`/`action` argument or return value.
-
-## Checklist
-
-- [ ] `lunora registry add storage` run, `pnpm install` done.
-- [ ] `UPLOADS` bucket bound to a real bucket; `STORAGE_SIGNING_SECRET` (≥32
-      chars) set; `STORAGE_PUBLIC_BASE_URL` left empty unless another host
-      serves `/storage/*` or you sign URLs in a query or a scheduled job.
-- [ ] `lunora codegen` run so `api.storage.*` is generated.
-- [ ] `/storage/*` route added, verifying signed URLs on both `PUT` and `GET`.
-- [ ] Verified a client upload → signed download round-trip.
+Every key is scoped as `storage/<userId>/<key>`, so a key from the client can't
+reach another user's data. The `storage/` prefix is also what routes the minted
+URL to `/storage/*`. The functions return the scoped key: persist it if you
+like, but always pass the bare key back in, because the function scopes it
+again. `listObjects` is an action, not a query, because R2 isn't reactive.
+Refetch it after an upload or a delete.
+
+## Pitfalls
+
+- **Signing secret reuse.** Signed URLs carry the bucket name inside the HMAC, so they can't be replayed across buckets. They can be replayed across deployments: two apps that share a secret will each honor URLs the other minted. Give each deployment its own secret.
+- **File bodies through functions.** Bytes stream through the `/storage/*` route. Don't pass file contents as a `query`/`mutation`/`action` argument or return value.
+- **Content types.** Widen the upload list through `ALLOWED_UPLOAD_CONTENT_TYPES`. Leave out `text/html` and `image/svg+xml`, since an uploaded one served from your origin is stored XSS.
+
+## Verify
+
+1. Run `lunora dev`, sign in, and upload a file through `generateUploadUrl` and `PUT`. The PUT should return 204.
+2. Open the URL from `getDownloadUrl`. It should return the bytes with `cache-control: private, no-store`.
+3. Change one character of `sig` in that URL. The route should return 403.
+4. Before deploying, check that `bucket_name` is a real bucket and that `STORAGE_SIGNING_SECRET` was set with `wrangler secret put`.