create-daloy 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-daloy",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Scaffold a new DaloyJS project. Run with `pnpm create daloy`, `npm create daloy@latest`, `yarn create daloy`, or `bun create daloy`.",
   "type": "module",
   "license": "MIT",

package/sbom.cdx.json

@@ -1,25 +1,25 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:225c0848-3f06-5b6c-b289-7c58ce4fb1ea",
+  "serialNumber": "urn:uuid:334286a9-ce6f-53b5-9ece-5e69ac3b7aac",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-08-20T14:37:41.578Z",
+    "timestamp": "2026-08-28T11:08:56.276Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.2.1"
+        "version": "1.3.0"
       }
     ],
     "authors": [],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/create-daloy@1.2.1",
+      "bom-ref": "pkg:npm/create-daloy@1.3.0",
       "name": "create-daloy",
-      "version": "1.2.1",
+      "version": "1.3.0",
       "description": "Scaffold a new DaloyJS project. Run with `pnpm create daloy`, `npm create daloy@latest`, `yarn create daloy`, or `bun create daloy`.",
-      "purl": "pkg:npm/create-daloy@1.2.1",
+      "purl": "pkg:npm/create-daloy@1.3.0",
       "licenses": [
         {
           "license": {
@@ -42,9 +42,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag-create-daloy-1.2.1",
+        "tagId": "swidtag-create-daloy-1.3.0",
         "name": "create-daloy",
-        "version": "1.2.1",
+        "version": "1.3.0",
         "tagVersion": 0,
         "patch": false
       }
@@ -53,7 +53,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/create-daloy@1.2.1",
+      "ref": "pkg:npm/create-daloy@1.3.0",
       "dependsOn": []
     }
   ]

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "create-daloy-1.2.1",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-1.2.1-225c0848-3f06-5b6c-b289-7c58ce4fb1ea",
+  "name": "create-daloy-1.3.0",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-1.3.0-334286a9-ce6f-53b5-9ece-5e69ac3b7aac",
   "creationInfo": {
-    "created": "2026-08-20T14:37:41.578Z",
+    "created": "2026-08-28T11:08:56.276Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package-create-daloy",
       "name": "create-daloy",
-      "versionInfo": "1.2.1",
+      "versionInfo": "1.3.0",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/create-daloy@1.2.1"
+          "referenceLocator": "pkg:npm/create-daloy@1.3.0"
         }
       ]
     }

package/templates/bun-basic/AGENTS.md

@@ -53,6 +53,7 @@ Do not write `.js` here — that's the Node NodeNext convention and will fail to
 6. Keep operation IDs stable and examples schema-valid; `bun run contract` must pass after route, metadata, or OpenAPI-facing changes.
 7. Every new route ships with a test that covers a happy path and at least one unhappy path.
 8. After any route change: `bun run gen:openapi && bun run gen:client && bun run contract && bun run typecheck && bun test`.
+9. Side effects that must outlive a request: enqueue a job (`app.useJobs` + idempotency key); pattern in the skill.
 
 ## Secure-by-default (do not let an AI strip these)
 
@@ -74,4 +75,4 @@ Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/
 - Bug fixes include a regression test.
 - Never bypass safety checks without a clear reason.
 
-For the full workflow — adding routes step-by-step, schema conventions, testing patterns, security guidance, and deployment notes — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).
+For the full workflow — routes, background jobs, testing, security, and deployment — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).

package/templates/bun-basic/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -4,7 +4,8 @@ description: >-
   Build, test, and harden this DaloyJS REST API on Bun. Use when the user
   asks to add or change an endpoint, route, Zod/Standard Schema,
   middleware, error handling, OpenAPI spec, typed Hey API client, contract
-  gate, auth, rate limit, or security default. Also use for phrasing like
+  gate, auth, rate limit, background jobs, or security default. Also use
+  for phrasing like
   "add GET /...", "new route", "regenerate the client", "bun test", or
   "fix the 401". Do not use for frontend UI, infra-only work, or unrelated
   docs.
@@ -217,6 +218,48 @@ app.use(rateLimit({ windowMs: 60_000, max: 120 }));
 
 Add CORS only when needed, with an explicit `origin` allowlist.
 
+## Background jobs
+
+Side effects that must outlive the HTTP request (welcome emails, webhook
+fan-out, thumbnails, nightly reconciliation) belong in a **job**, not
+inline in the handler and not in a fire-and-forget promise.
+
+- `app.useJobs({ store, handlers, startWorker })` wires a queue (and an
+  optional in-process worker) into the app lifecycle, including the
+  graceful-shutdown drain.
+- Enqueue **after** the DB commit, always with an idempotency key:
+
+```ts
+import { jobIdempotencyKey } from "@daloyjs/core";
+
+await app.jobs!.enqueue({
+  name: "email.welcome",
+  payload: { userId: user.id, to: user.email }, // ids, never file bytes
+  idempotencyKey: jobIdempotencyKey({ name: "email.welcome", key: user.id }),
+});
+```
+
+- Delivery is **at-least-once**: handlers must be idempotent. Pass a key
+  through to downstream APIs (e.g. Stripe's `Idempotency-Key`) when a
+  duplicate run would move money or send email.
+- Throw `JobFatalError` for permanent failures (no retry); any other throw
+  retries with full-jitter backoff, then dead-letters.
+- `app.cronEnqueue(def, { name, payload })` turns a cron tick into an
+  idempotent enqueue. Use it for side effects that must run once
+  cluster-wide; keep plain `app.cron()` for process-local maintenance
+  (other replicas have their own memory to sweep).
+- Payloads are plain JSON capped at 64 KiB: enqueue ids and blob URLs,
+  never file contents.
+- `MemoryJobStore` is for tests (`worker.runOnce()`) and single-process
+  dev. Production needs a shared `JobStore` adapter (Redis/Postgres/SQS)
+  in app code; `useJobs` warns on Memory in production, and
+  `strictProduction: true` refuses to boot.
+- `startWorker: true` in the same process is fine for small deployments;
+  split a dedicated worker process (same app, `useJobs` with
+  `startWorker`, no public ingress) as you grow.
+
+Full reference: <https://daloyjs.dev/docs/jobs>
+
 ## Testing best practices
 
 Tests run with `bun test`. Use **in-process** requests through

package/templates/bun-basic/package.json

@@ -19,7 +19,7 @@
     "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
-    "@daloyjs/core": "^1.2.1",
+    "@daloyjs/core": "^1.3.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/cloudflare-worker/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API deployed to **Cloudflare Workers**. **Contract-first**: routes are defined with validation schemas (Zod in this template; DaloyJS also supports Standard Schema-compatible validators) and OpenAPI 3.1 is generated from them. `docs: true` is set in `new App({...})`, so `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI) are auto-mounted. DaloyJS is dependency-free and the Scalar UI loads from a CDN, so this adds negligible Worker bundle size; drop `docs` (and the `openapi` block) if you want the smallest possible bundle.
+A [DaloyJS](https://daloyjs.dev) REST API deployed to **Cloudflare Workers**. **Contract-first**: routes are defined with validation schemas (Zod in this template; DaloyJS also supports Standard Schema-compatible validators) and OpenAPI 3.1 is generated from them. `docs: true` is set in `new App({...})`, so `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI) are auto-mounted. DaloyJS is dependency-free and the Scalar UI loads from a CDN, so bundle cost is negligible; drop `docs` (and the `openapi` block) for the smallest bundle.
 
 - Package manager: pnpm (use `pnpm` unless the project's `package.json` was rewritten for npm/yarn/bun).
 - Runtime: Cloudflare Workers (Web Standard `Request`/`Response`).
@@ -37,7 +37,7 @@ A [DaloyJS](https://daloyjs.dev) REST API deployed to **Cloudflare Workers**. **
 5. Keep `requestId()`, `secureHeaders()`, and `rateLimit()` enabled. The in-memory limiter resets per isolate.
 6. Stay on the Workers runtime: only Web Standards APIs + Cloudflare bindings. No `node:` modules unless you explicitly add `nodejs_compat` and require it.
 7. Bindings flow through `env`. Read KV/D1/R2/secrets from the `env` argument; never read them via globals.
-8. Long-running work belongs in `ctx.waitUntil(...)`, not blocking the response.
+8. Long-running work: `ctx.waitUntil(...)` or a remote-store job via `app.useJobs` (enqueue only, no worker loop on an isolate); never block the response.
 9. Keep operation IDs stable and examples schema-valid; `pnpm contract` must pass after route, metadata, or OpenAPI-facing changes.
 10. Every new route ships with a test that covers a happy path and at least one unhappy path.
 
@@ -64,4 +64,4 @@ Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/
 - For deploys, ensure the user has run `wrangler login`; do not authenticate on their behalf.
 - Never bypass safety checks without a clear reason.
 
-For the full workflow — adding routes step-by-step, bindings, testing patterns, security guidance, and deployment notes — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).
+For the full workflow — routes, background jobs, bindings, testing, security, and deployment — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).

package/templates/cloudflare-worker/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -4,7 +4,8 @@ description: >-
   Build, test, and harden this DaloyJS REST API on Cloudflare Workers. Use
   when the user asks to add or change an endpoint, route, Zod/Standard
   Schema, middleware, error handling, Worker binding (KV, D1, R2, Queues,
-  env), contract gate, auth, or rate limit. Also use for phrasing like
+  env), contract gate, auth, rate limit, or background jobs. Also use for
+  phrasing like
   "add GET /...", "new route", "wrangler", "fix the 401", or "add a KV
   binding". Do not use for frontend UI, infra-only work, or unrelated
   docs.
@@ -226,6 +227,49 @@ Add CORS only when needed, with an explicit `origin` allowlist.
 4. Store secrets via `wrangler secret put` — they appear on `env` but
    are not committed to `wrangler.toml`.
 
+## Background jobs
+
+Side effects that must outlive the HTTP request (welcome emails, webhook
+fan-out, thumbnails, nightly reconciliation) belong in a **job**, not
+inline in the handler and not in a fire-and-forget promise.
+
+- `app.useJobs({ store, handlers, startWorker })` wires a queue (and an
+  optional in-process worker) into the app lifecycle, including the
+  graceful-shutdown drain.
+- Enqueue **after** the DB commit, always with an idempotency key:
+
+```ts
+import { jobIdempotencyKey } from "@daloyjs/core";
+
+await app.jobs!.enqueue({
+  name: "email.welcome",
+  payload: { userId: user.id, to: user.email }, // ids, never file bytes
+  idempotencyKey: jobIdempotencyKey({ name: "email.welcome", key: user.id }),
+});
+```
+
+- Delivery is **at-least-once**: handlers must be idempotent. Pass a key
+  through to downstream APIs (e.g. Stripe's `Idempotency-Key`) when a
+  duplicate run would move money or send email.
+- Throw `JobFatalError` for permanent failures (no retry); any other throw
+  retries with full-jitter backoff, then dead-letters.
+- `app.cronEnqueue(def, { name, payload })` turns a cron tick into an
+  idempotent enqueue. Use it for side effects that must run once
+  cluster-wide; keep plain `app.cron()` for process-local maintenance
+  (other replicas have their own memory to sweep).
+- Payloads are plain JSON capped at 64 KiB: enqueue ids and blob URLs,
+  never file contents.
+- `MemoryJobStore` is for tests (`worker.runOnce()`) and single-process
+  dev. Production needs a shared `JobStore` adapter (Redis/Postgres/SQS)
+  in app code; `useJobs` warns on Memory in production, and
+  `strictProduction: true` refuses to boot.
+- A Workers isolate **enqueues only**: never `startWorker: true` here —
+  the isolate is torn down once the response flushes. Run the worker as a
+  separate long-lived Node service (same app code, `useJobs` with
+  `startWorker`) against the same remote store.
+
+Full reference: <https://daloyjs.dev/docs/jobs>
+
 ## Testing best practices
 
 Two patterns:

package/templates/cloudflare-worker/package.json

@@ -16,7 +16,7 @@
     "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
-    "@daloyjs/core": "^1.2.1",
+    "@daloyjs/core": "^1.3.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/deno-basic/AGENTS.md

@@ -42,6 +42,7 @@ The typed Hey API SDK is generated outside Deno (Hey API has no Deno entrypoint
 7. Keep operation IDs stable and examples schema-valid; `deno task contract` must pass after route, metadata, or OpenAPI-facing changes.
 8. Every new route ships with a test that covers a happy path and at least one unhappy path.
 9. After any route change: `deno task gen:openapi && deno task contract && deno task typecheck && deno task test`.
+10. Side effects that must outlive a request: enqueue a job (`app.useJobs` + idempotency key); pattern in the skill.
 
 ## Secure-by-default (do not let an AI strip these)
 
@@ -63,4 +64,4 @@ Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/
 - Bug fixes include a regression test.
 - Use `deno task ...`, not `npm`/`pnpm`. There is no `package.json` here.
 
-For the full workflow — adding routes step-by-step, schema conventions, testing patterns, security guidance, and deployment notes — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).
+For the full workflow — routes, background jobs, testing, security, and deployment — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).

package/templates/deno-basic/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -4,7 +4,8 @@ description: >-
   Build, test, and harden this DaloyJS REST API on Deno. Use when the user
   asks to add or change an endpoint, route, Zod/Standard Schema,
   middleware, error handling, OpenAPI spec, contract gate, Deno
-  permission, deno.json import, auth, or rate limit. Also use for phrasing
+  permission, deno.json import, auth, rate limit, or background jobs.
+  Also use for phrasing
   like "add GET /...", "new route", "deno task", "fix the 401", or "allow
   net". Do not use for frontend UI, npm/pnpm package.json work, or
   unrelated docs.
@@ -214,6 +215,48 @@ app.use(rateLimit({ windowMs: 60_000, max: 120 }));
 
 Add CORS only when needed, with an explicit `origin` allowlist.
 
+## Background jobs
+
+Side effects that must outlive the HTTP request (welcome emails, webhook
+fan-out, thumbnails, nightly reconciliation) belong in a **job**, not
+inline in the handler and not in a fire-and-forget promise.
+
+- `app.useJobs({ store, handlers, startWorker })` wires a queue (and an
+  optional in-process worker) into the app lifecycle, including the
+  graceful-shutdown drain.
+- Enqueue **after** the DB commit, always with an idempotency key:
+
+```ts
+import { jobIdempotencyKey } from "@daloyjs/core";
+
+await app.jobs!.enqueue({
+  name: "email.welcome",
+  payload: { userId: user.id, to: user.email }, // ids, never file bytes
+  idempotencyKey: jobIdempotencyKey({ name: "email.welcome", key: user.id }),
+});
+```
+
+- Delivery is **at-least-once**: handlers must be idempotent. Pass a key
+  through to downstream APIs (e.g. Stripe's `Idempotency-Key`) when a
+  duplicate run would move money or send email.
+- Throw `JobFatalError` for permanent failures (no retry); any other throw
+  retries with full-jitter backoff, then dead-letters.
+- `app.cronEnqueue(def, { name, payload })` turns a cron tick into an
+  idempotent enqueue. Use it for side effects that must run once
+  cluster-wide; keep plain `app.cron()` for process-local maintenance
+  (other replicas have their own memory to sweep).
+- Payloads are plain JSON capped at 64 KiB: enqueue ids and blob URLs,
+  never file contents.
+- `MemoryJobStore` is for tests (`worker.runOnce()`) and single-process
+  dev. Production needs a shared `JobStore` adapter (Redis/Postgres/SQS)
+  in app code; `useJobs` warns on Memory in production, and
+  `strictProduction: true` refuses to boot.
+- `startWorker: true` in the same process is fine for small deployments;
+  split a dedicated worker process (same app, `useJobs` with
+  `startWorker`, no public ingress) as you grow.
+
+Full reference: <https://daloyjs.dev/docs/jobs>
+
 ## Testing best practices
 
 Tests run with `deno test`. Use **in-process** `app.request()` — no port

package/templates/deno-basic/deno.json

@@ -10,11 +10,11 @@
     "hooks:install": "git config core.hooksPath .githooks"
   },
   "imports": {
-    "@daloyjs/core": "jsr:@daloyjs/daloy@^1.2.1",
-    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^1.2.1/banner",
-    "@daloyjs/core/contract": "jsr:@daloyjs/daloy@^1.2.1/contract",
-    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^1.2.1/deno",
-    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^1.2.1/openapi",
+    "@daloyjs/core": "jsr:@daloyjs/daloy@^1.3.0",
+    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^1.3.0/banner",
+    "@daloyjs/core/contract": "jsr:@daloyjs/daloy@^1.3.0/contract",
+    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^1.3.0/deno",
+    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^1.3.0/openapi",
     "zod": "npm:zod@^4.4.3"
   },
   "compilerOptions": {

package/templates/node-basic/AGENTS.md

@@ -56,6 +56,7 @@ You import the file you see. On `pnpm build`, TypeScript rewrites the `.ts` spec
 6. Keep operation IDs stable and examples schema-valid; `pnpm contract` must pass after route, metadata, or OpenAPI-facing changes.
 7. Every new route ships with a test that covers a happy path and at least one unhappy path.
 8. After any route change: `pnpm gen && pnpm contract && pnpm typecheck && pnpm test`.
+9. Side effects that must outlive a request: enqueue a job (`app.useJobs` + idempotency key); pattern in the skill.
 
 ## Secure-by-default (do not let an AI strip these)
 
@@ -74,4 +75,4 @@ Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/
 
 - Bug fixes include a regression test.
 
-For the full workflow — adding routes step-by-step, schema conventions, testing patterns, security guidance, and deployment notes — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).
+For the full workflow — routes, background jobs, testing, security, and deployment — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).

package/templates/node-basic/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -4,7 +4,8 @@ description: >-
   Build, test, and harden this DaloyJS REST API on Node.js. Use when the
   user asks to add or change an endpoint, route, Zod/Standard Schema,
   middleware, error handling, OpenAPI spec, typed Hey API client, contract
-  gate, auth, rate limit, or security default. Also use for phrasing like
+  gate, auth, rate limit, background jobs, or security default. Also use
+  for phrasing like
   "add GET /...", "new route", "regenerate the client", or "fix the 401".
   Do not use for frontend UI, infra-only work, or unrelated docs.
 license: MIT
@@ -256,6 +257,48 @@ Custom middleware should be small, well-typed, and call `await next()`
 exactly once. Wrap it in `try { await next() } finally { ... }` if it
 needs to run code after the handler.
 
+## Background jobs
+
+Side effects that must outlive the HTTP request (welcome emails, webhook
+fan-out, thumbnails, nightly reconciliation) belong in a **job**, not
+inline in the handler and not in a fire-and-forget promise.
+
+- `app.useJobs({ store, handlers, startWorker })` wires a queue (and an
+  optional in-process worker) into the app lifecycle, including the
+  graceful-shutdown drain.
+- Enqueue **after** the DB commit, always with an idempotency key:
+
+```ts
+import { jobIdempotencyKey } from "@daloyjs/core";
+
+await app.jobs!.enqueue({
+  name: "email.welcome",
+  payload: { userId: user.id, to: user.email }, // ids, never file bytes
+  idempotencyKey: jobIdempotencyKey({ name: "email.welcome", key: user.id }),
+});
+```
+
+- Delivery is **at-least-once**: handlers must be idempotent. Pass a key
+  through to downstream APIs (e.g. Stripe's `Idempotency-Key`) when a
+  duplicate run would move money or send email.
+- Throw `JobFatalError` for permanent failures (no retry); any other throw
+  retries with full-jitter backoff, then dead-letters.
+- `app.cronEnqueue(def, { name, payload })` turns a cron tick into an
+  idempotent enqueue. Use it for side effects that must run once
+  cluster-wide; keep plain `app.cron()` for process-local maintenance
+  (other replicas have their own memory to sweep).
+- Payloads are plain JSON capped at 64 KiB: enqueue ids and blob URLs,
+  never file contents.
+- `MemoryJobStore` is for tests (`worker.runOnce()`) and single-process
+  dev. Production needs a shared `JobStore` adapter (Redis/Postgres/SQS)
+  in app code; `useJobs` warns on Memory in production, and
+  `strictProduction: true` refuses to boot.
+- `startWorker: true` in the same process is fine for small deployments;
+  split a dedicated worker process (same app, `useJobs` with
+  `startWorker`, no public ingress) as you grow.
+
+Full reference: <https://daloyjs.dev/docs/jobs>
+
 ## Testing best practices
 
 Tests live under `tests/` and run with `node --test` (Node's built-in

package/templates/node-basic/package.json

@@ -20,7 +20,7 @@
     "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
-    "@daloyjs/core": "^1.2.1",
+    "@daloyjs/core": "^1.3.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/vercel/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel** on the **Node.js runtime**. **Contract-first**: routes use validation schemas (Zod here; DaloyJS also supports Standard Schema-compatible validators) and generate OpenAPI 3.1. With `docs: true`, DaloyJS auto-mounts `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI).
+A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel** on the **Node.js runtime**. **Contract-first**: routes use validation schemas (Zod here; DaloyJS also supports Standard Schema-compatible validators) and generate OpenAPI 3.1. `docs: true` auto-mounts `GET /openapi.json`, `GET /openapi.yaml`, and `GET /docs` (Scalar UI).
 
 - Package manager: pnpm (use `pnpm` unless the project's `package.json` was rewritten for npm/yarn/bun).
 - Runtime: Vercel Node.js Functions on Fluid Compute (Web Standard `Request`/`Response`).
@@ -14,7 +14,7 @@ A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel** on the **Node.j
 
 ## Commands
 
-- `pnpm dev` — local Node dev server (`src/dev.ts`) on http://localhost:3000 (no `vercel dev` / login needed; serves the same app the Vercel Function runs)
+- `pnpm dev` — local Node dev server (`src/dev.ts`) on http://localhost:3000 (no `vercel dev` needed)
 - `pnpm typecheck` — `tsc --noEmit`
 - `pnpm test` — run test suite
 - `pnpm contract` — run `daloy inspect --check api/index.ts`
@@ -51,6 +51,7 @@ You import the file you see. Vercel resolves `.ts` at deploy time; Node runs it
 7. Keep a single `api/index.ts` entry and the `vercel.json` `/(.*)` → `/api` rewrite so DaloyJS handles all routing at the site root.
 8. Keep operation IDs stable and examples schema-valid; `pnpm contract` must pass after route, metadata, or OpenAPI-facing changes.
 9. Every new route ships with a test that covers a happy path and at least one unhappy path.
+10. Side effects that must outlive a request: `app.useJobs` + remote store; enqueue only, no worker loop in the Function.
 
 ## Secure-by-default (do not let an AI strip these)
 
@@ -73,4 +74,4 @@ Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/
 - For deploys, ensure the user has run `vercel login`; do not authenticate on their behalf.
 - Never bypass safety checks without a clear reason.
 
-For the full workflow — adding routes step-by-step, schema conventions, testing patterns, security guidance, and deployment notes — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).
+For the full workflow — routes, background jobs, testing, security, and deployment — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).

package/templates/vercel/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -4,8 +4,8 @@ description: >-
   Build, test, and harden this DaloyJS REST API on Vercel (Node.js
   runtime). Use when the user asks to add or change an endpoint, route,
   Zod/Standard Schema, middleware, error handling, OpenAPI spec, typed
-  client, contract gate, auth, rate limit, or the single Functions
-  entrypoint / rewrite. Also use for phrasing like "add GET /...", "new
+  client, contract gate, auth, rate limit, background jobs, or the
+  single Functions entrypoint / rewrite. Also use for phrasing like "add GET /...", "new
   route", "fix the 401", or "deploy this API". Do not use for Next.js App
   Router work, frontend UI, or unrelated docs.
 license: MIT
@@ -201,6 +201,49 @@ Register middleware **before** route definitions. Order matters.
 Keep the secure baseline (`requestId`, `secureHeaders`, `rateLimit`).
 Add CORS only when needed, with an explicit `origin` allowlist.
 
+## Background jobs
+
+Side effects that must outlive the HTTP request (welcome emails, webhook
+fan-out, thumbnails, nightly reconciliation) belong in a **job**, not
+inline in the handler and not in a fire-and-forget promise.
+
+- `app.useJobs({ store, handlers, startWorker })` wires a queue (and an
+  optional in-process worker) into the app lifecycle, including the
+  graceful-shutdown drain.
+- Enqueue **after** the DB commit, always with an idempotency key:
+
+```ts
+import { jobIdempotencyKey } from "@daloyjs/core";
+
+await app.jobs!.enqueue({
+  name: "email.welcome",
+  payload: { userId: user.id, to: user.email }, // ids, never file bytes
+  idempotencyKey: jobIdempotencyKey({ name: "email.welcome", key: user.id }),
+});
+```
+
+- Delivery is **at-least-once**: handlers must be idempotent. Pass a key
+  through to downstream APIs (e.g. Stripe's `Idempotency-Key`) when a
+  duplicate run would move money or send email.
+- Throw `JobFatalError` for permanent failures (no retry); any other throw
+  retries with full-jitter backoff, then dead-letters.
+- `app.cronEnqueue(def, { name, payload })` turns a cron tick into an
+  idempotent enqueue. Use it for side effects that must run once
+  cluster-wide; keep plain `app.cron()` for process-local maintenance
+  (other replicas have their own memory to sweep).
+- Payloads are plain JSON capped at 64 KiB: enqueue ids and blob URLs,
+  never file contents.
+- `MemoryJobStore` is for tests (`worker.runOnce()`) and single-process
+  dev. Production needs a shared `JobStore` adapter (Redis/Postgres/SQS)
+  in app code; `useJobs` warns on Memory in production, and
+  `strictProduction: true` refuses to boot.
+- Vercel Functions **enqueue only**: never `startWorker: true` here — a
+  Function is frozen once the response flushes. Run the worker as a
+  separate long-lived Node service (same app code, `useJobs` with
+  `startWorker`) against the same remote store.
+
+Full reference: <https://daloyjs.dev/docs/jobs>
+
 ## Testing best practices
 
 Tests use in-process `app.request(...)` — no port, no Vercel runtime

package/templates/vercel/package.json

@@ -16,7 +16,7 @@
     "hooks:install": "git config core.hooksPath .githooks"
   },
   "dependencies": {
-    "@daloyjs/core": "^1.2.1",
+    "@daloyjs/core": "^1.3.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {