create-daloy 0.38.0 → 0.38.2

package/README.md

@@ -22,7 +22,7 @@ bun  create daloy           my-api
 The CLI is interactive when arguments are missing. It will ask you for:
 
 - A project directory name (defaults to `my-daloy-app`)
-- A template (`node-basic`, `vercel-edge`, `cloudflare-worker`, `bun-basic`, or `deno-basic`)
+- A template (`node-basic`, `vercel`, `cloudflare-worker`, `bun-basic`, or `deno-basic`)
 - A package manager (`pnpm`, `npm`, `yarn`, or `bun`) — not asked for the
   `deno-basic` runtime template
 - Whether to install dependencies
@@ -50,7 +50,7 @@ pnpm create daloy@latest my-api \
 
 | Flag | Description |
 | --- | --- |
-| `--template <name>` | `node-basic` (default), `vercel-edge`, `cloudflare-worker`, `bun-basic`, or `deno-basic`. |
+| `--template <name>` | `node-basic` (default), `vercel`, `cloudflare-worker`, `bun-basic`, or `deno-basic`. (`vercel-edge` is a deprecated alias for `vercel`.) |
 | `--package-manager <pm>` | `pnpm` (default), `npm`, `yarn`, or `bun`. Ignored for `deno-basic`. |
 | `--list-templates` | Print available templates with descriptions. |
 | `--install` / `--no-install` | Install dependencies after scaffolding. Defaults to **Y** for npm/yarn/bun and **N** for pnpm so you can review the hardened `.npmrc` / `pnpm-workspace.yaml` and aren't blocked by the 24h `minimumReleaseAge` embargo on the first run. |
@@ -88,17 +88,20 @@ A minimal Cloudflare Worker bootstrap using `@daloyjs/core/cloudflare` with:
 - `secureHeaders` and `requestId` enabled by default, with smaller edge-friendly body and timeout limits.
 - A Zod-validated `/healthz` route and contract-first `/books/:id` route exposed via `toFetchHandler(app)`.
 
-### `vercel-edge`
+### `vercel`
 
-A Vercel Edge API bootstrap using `@daloyjs/core/vercel` with:
+A Vercel API bootstrap on the **Node.js runtime** (Vercel's recommended runtime
+for standalone functions, on Fluid Compute) using `@daloyjs/core/vercel` with:
 
 - `api/[...path].ts` catch-all routing so DaloyJS owns the API surface.
-- `export const config = { runtime: "edge" }` ready for Vercel Edge.
-- Node.js migration notes using Vercel's default `{ fetch }` export shape.
+- `export default toFetchHandler(app)` — the `{ fetch }` shape Vercel Node.js Functions expect (no `runtime` export needed; Node.js is the default).
+- Notes for opting into the Edge runtime (`export const runtime = "edge"` + `toWebHandler(app)`) if you specifically need it.
 - `vercel dev` / `vercel deploy` scripts.
-- `secureHeaders` and `requestId` enabled by default, with smaller edge-friendly body and timeout limits.
+- `secureHeaders` and `requestId` enabled by default, with smaller serverless-friendly body and timeout limits.
 - A health route and bookstore route mirroring the Node starter.
 
+> The previous template name `vercel-edge` still works as a deprecated alias for `vercel`.
+
 ### `bun-basic`
 
 A [Bun](https://bun.sh) runtime starter using `@daloyjs/core/bun` with:
@@ -120,6 +123,20 @@ A [Deno](https://deno.com) runtime starter using `@daloyjs/core/deno` with:
 - A health route and contract-first `/books/:id` route with Zod validation.
 - The CLI skips Node-style installs for this template (no `package.json`).
 
+## Authentication (OAuth2 / OpenID Connect)
+
+Scaffolded apps are **resource servers**: DaloyJS verifies and enforces access
+tokens, it does **not** issue them. There is no built-in login UI, user
+database, or OAuth2 authorization server (it is not an identity provider like
+Keycloak, Auth0, or Duende IdentityServer). To add login, bring an OpenID
+Connect provider — managed (Auth0, Okta, Clerk, Microsoft Entra ID, AWS
+Cognito) or self-hosted open source (Keycloak, Zitadel, Ory, Logto) — and have
+DaloyJS verify its JWTs with the first-party `jwk()`, `bearerAuth()`, and
+`requireScopes()` helpers. Don't build your own authorization server.
+
+See [Auth architecture](https://daloyjs.dev/docs/auth/architecture) for the full
+picture and the two recommended designs (API resource server and browser BFF).
+
 ## Minimal scaffolds
 
 Pass `--minimal` to drop the bookstore demo route and the built-in
@@ -246,7 +263,7 @@ not need.
 - Zero runtime dependencies (uses only Node built-ins) for a clean supply-chain footprint.
 - A modern terminal experience with Unicode/color capability detection and ASCII fallbacks.
 - Templates are copied verbatim from this package's `templates/` directory.
-- Files and folders prefixed with `_` are renamed on copy (`_gitignore` → `.gitignore`, `_npmrc` → `.npmrc`, `_github/` → `.github`, `_agents/` → `.agents/`, `_Dockerfile` → `Dockerfile`, `_dockerignore` → `.dockerignore`, `_env.example` → `.env.example`) to survive npm packing.
+- Files and folders prefixed with `_` are renamed on copy (`_gitignore` → `.gitignore`, `_npmrc` → `.npmrc`, `_github/` → `.github`, `_agents/` → `.agents/`, `_vscode/` → `.vscode/`, `_Dockerfile` → `Dockerfile`, `_dockerignore` → `.dockerignore`, `_env.example` → `.env.example`) to survive npm packing.
 - pnpm-specific `.npmrc` hardening is kept only when you choose `pnpm`; other package managers get a clean project without unsupported config warnings.
 - pnpm projects ship with `ignore-scripts=true`, `minimum-release-age=1440`, `verify-store-integrity=true`, `prefer-frozen-lockfile=true`, and `strict-peer-dependencies=true` by default.
 - `--with-ci` projects ship with pinned GitHub Actions workflows, CODEOWNERS, Dependabot, SECURITY.md, and lockfile-source verification.
@@ -260,3 +277,5 @@ Every scaffolded project ships with two files that help AI coding agents (Copilo
 - `.agents/skills/daloyjs-best-practices/SKILL.md` — comprehensive operational guidance following the open `agents/skills/<skill-name>/SKILL.md` convention: when to use the skill, project structure, core workflows (adding routes, regenerating the OpenAPI spec and client), schema and validation conventions, error-handling patterns, middleware order, testing best practices (happy and unhappy paths), security best practices, logging and observability notes, configuration and secrets handling, deployment notes, pitfalls and guardrails, and process expectations.
 
 Both files are tailored to the chosen template (Node, Bun, Deno, Vercel Edge, or Cloudflare Workers), and Node-style templates rewrite their commands to match your selected package manager. They follow the "instruction budget" advice — small root file, progressive disclosure for the rest — so they don't waste agent tokens. Edit or delete them freely; the framework does not depend on them at runtime.
+
+Every scaffold also ships a `.vscode/mcp.json` (authored as `_vscode/mcp.json` in the template) that wires VS Code and other MCP-aware editors to the DaloyJS documentation MCP server (`https://daloyjs.dev/mcp`) over HTTP. AI assistants in your editor can then pull current DaloyJS docs with no manual setup. Delete the file or remove the server entry to opt out; it is editor configuration only and the framework does not depend on it at runtime.

package/bin/create-daloy.mjs

@@ -23,9 +23,9 @@ const TEMPLATE_OPTIONS = [
     description: "Traditional REST API with secure defaults and Hey API codegen",
   },
   {
-    value: "vercel-edge",
-    title: "Vercel Edge",
-    description: "Catch-all Vercel Edge route with Node.js migration notes",
+    value: "vercel",
+    title: "Vercel",
+    description: "Catch-all Vercel Functions REST API on the Node.js runtime (Fluid Compute)",
   },
   {
     value: "cloudflare-worker",
@@ -54,6 +54,15 @@ const PACKAGE_MANAGER_OPTIONS = [
 const TEMPLATES = TEMPLATE_OPTIONS.map((option) => option.value);
 const PACKAGE_MANAGERS = PACKAGE_MANAGER_OPTIONS.map((option) => option.value);
 
+// Deprecated template names kept as aliases so existing
+// `--template <old>` commands (and published docs/blog posts) keep working.
+// Each maps to its current canonical template value.
+const TEMPLATE_ALIASES = new Map([
+  // `vercel-edge` shipped before Vercel deprecated standalone Edge Functions;
+  // the template now targets the recommended Node.js runtime as `vercel`.
+  ["vercel-edge", "vercel"],
+]);
+
 const RENAME_ON_COPY = new Map([
   ["_gitignore", ".gitignore"],
   ["_npmrc", ".npmrc"],
@@ -65,6 +74,11 @@ const RENAME_ON_COPY = new Map([
   // `.agents/skills/<skill-name>/SKILL.md`. Templates author this as
   // `_agents/` so npm pack does not drop the dotfolder during publish.
   ["_agents", ".agents"],
+  // Directory: holds editor configuration such as `mcp.json`, which wires
+  // VS Code (and compatible editors) to the DaloyJS docs MCP server.
+  // Templates author this as `_vscode/` so npm pack does not drop the
+  // dotfolder during publish.
+  ["_vscode", ".vscode"],
 ]);
 
 // Templates that target a runtime instead of an npm package manager.
@@ -972,7 +986,7 @@ function cloudflareDeploySteps(packageManager) {
 }
 
 function renderDeployConfig({ template, packageManager, needsBunRuntime }) {
-  if (template === "vercel-edge") {
+  if (template === "vercel") {
     return {
       header: vercelDeployHeader(),
       jobName: "Deploy to Vercel",
@@ -1669,6 +1683,12 @@ async function main() {
     if (!template) {
       template = rl ? await askChoice(rl, "Choose a starter template:", TEMPLATE_OPTIONS, "node-basic") : "node-basic";
     }
+    // Resolve deprecated template aliases (e.g. `vercel-edge` -> `vercel`).
+    if (TEMPLATE_ALIASES.has(template)) {
+      const canonical = TEMPLATE_ALIASES.get(template);
+      logWarn(`Template "${template}" is deprecated; using "${canonical}" instead.`);
+      template = canonical;
+    }
     if (!TEMPLATES.includes(template)) {
       logError(`Unknown template "${template}". Available: ${TEMPLATES.join(", ")}`);
       process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-daloy",
-  "version": "0.38.0",
+  "version": "0.38.2",
   "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:b1a2eb69-121b-5cae-87a9-5d036a3e1a7a",
+  "serialNumber": "urn:uuid:2bbd5e7e-5035-5e09-92c8-3e1aec60f5a1",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-10T11:58:38.391Z",
+    "timestamp": "2026-06-16T14:42:42.888Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "0.38.0"
+        "version": "0.38.2"
       }
     ],
     "authors": [],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/create-daloy@0.38.0",
+      "bom-ref": "pkg:npm/create-daloy@0.38.2",
       "name": "create-daloy",
-      "version": "0.38.0",
+      "version": "0.38.2",
       "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@0.38.0",
+      "purl": "pkg:npm/create-daloy@0.38.2",
       "licenses": [
         {
           "license": {
@@ -42,9 +42,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag-create-daloy-0.38.0",
+        "tagId": "swidtag-create-daloy-0.38.2",
         "name": "create-daloy",
-        "version": "0.38.0",
+        "version": "0.38.2",
         "tagVersion": 0,
         "patch": false
       }
@@ -53,7 +53,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/create-daloy@0.38.0",
+      "ref": "pkg:npm/create-daloy@0.38.2",
       "dependsOn": []
     }
   ]

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "create-daloy-0.38.0",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-0.38.0-b1a2eb69-121b-5cae-87a9-5d036a3e1a7a",
+  "name": "create-daloy-0.38.2",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-0.38.2-2bbd5e7e-5035-5e09-92c8-3e1aec60f5a1",
   "creationInfo": {
-    "created": "2026-06-10T11:58:38.391Z",
+    "created": "2026-06-16T14:42:42.888Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package-create-daloy",
       "name": "create-daloy",
-      "versionInfo": "0.38.0",
+      "versionInfo": "0.38.2",
       "downloadLocation": "https://github.com/daloyjs/daloy",
       "filesAnalyzed": false,
       "licenseConcluded": "MIT",
@@ -27,7 +27,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/create-daloy@0.38.0"
+          "referenceLocator": "pkg:npm/create-daloy@0.38.2"
         }
       ]
     }

package/templates/_ci/deno/_github/workflows/codeql.yml

@@ -44,13 +44,13 @@ jobs:
           show-progress: false
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
           queries: security-extended,security-and-quality
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           category: "/language:${{ matrix.language }}"

package/templates/_ci/deno/_github/workflows/container-scan.yml

@@ -139,7 +139,7 @@ jobs:
 
       - name: Upload hadolint SARIF
         if: steps.detect.outputs.present == 'true'
-        uses: github/codeql-action/upload-sarif@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           sarif_file: hadolint.sarif
           category: hadolint
@@ -162,7 +162,7 @@ jobs:
           exit-code: "0"
 
       - name: Upload Trivy filesystem SARIF
-        uses: github/codeql-action/upload-sarif@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           sarif_file: trivy-fs.sarif
           category: trivy-fs
@@ -186,7 +186,7 @@ jobs:
 
       - name: Upload Trivy image SARIF
         if: always() && steps.detect.outputs.present == 'true'
-        uses: github/codeql-action/upload-sarif@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           sarif_file: trivy-image.sarif
           category: trivy-image

package/templates/_ci/deno/_github/workflows/opengrep.yml

@@ -131,7 +131,7 @@ jobs:
 
       - name: Upload SARIF to GitHub code scanning
         if: always()
-        uses: github/codeql-action/upload-sarif@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           sarif_file: opengrep.sarif
           category: opengrep

package/templates/_ci/deno/_github/workflows/scorecard.yml

@@ -41,6 +41,6 @@ jobs:
           publish_results: true
 
       - name: Upload to code-scanning
-        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           sarif_file: results.sarif

package/templates/_ci/node/_github/workflows/codeql.yml

@@ -44,13 +44,13 @@ jobs:
           show-progress: false
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           languages: ${{ matrix.language }}
           build-mode: ${{ matrix.build-mode }}
           queries: security-extended,security-and-quality
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           category: "/language:${{ matrix.language }}"

package/templates/_ci/node/_github/workflows/container-scan.yml

@@ -157,7 +157,7 @@ jobs:
 
       - name: Upload hadolint SARIF
         if: steps.detect.outputs.present == 'true'
-        uses: github/codeql-action/upload-sarif@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           sarif_file: hadolint.sarif
           category: hadolint
@@ -180,7 +180,7 @@ jobs:
           exit-code: "0"
 
       - name: Upload Trivy filesystem SARIF
-        uses: github/codeql-action/upload-sarif@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           sarif_file: trivy-fs.sarif
           category: trivy-fs
@@ -207,7 +207,7 @@ jobs:
 
       - name: Upload Trivy image SARIF
         if: always() && steps.detect.outputs.present == 'true'
-        uses: github/codeql-action/upload-sarif@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           sarif_file: trivy-image.sarif
           category: trivy-image

package/templates/_ci/node/_github/workflows/opengrep.yml

@@ -163,7 +163,7 @@ jobs:
 
       - name: Upload SARIF to GitHub code scanning
         if: always()
-        uses: github/codeql-action/upload-sarif@52485aec7be33610227643b0fe83936b8b5f061a # v3
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           sarif_file: opengrep.sarif
           category: opengrep

package/templates/_ci/node/_github/workflows/scorecard.yml

@@ -41,6 +41,6 @@ jobs:
           publish_results: true
 
       - name: Upload to code-scanning
-        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
         with:
           sarif_file: results.sarif

package/templates/bun-basic/README.md

@@ -63,4 +63,18 @@ Do not use `.js` here — that's the Node NodeNext convention and will not resol
 - Hot reload via `bun --hot`.
 - Hey API codegen wired to `bun run gen:openapi` + `bun run gen:client`.
 
+## Authentication (OAuth2 / OpenID Connect)
+
+This app is a **resource server**: DaloyJS verifies and enforces access tokens,
+it does **not** issue them. There is no built-in login UI, user database, or
+OAuth2 authorization server (it is not an identity provider like Keycloak,
+Auth0, or Duende IdentityServer). To add login, bring an OpenID Connect provider
+— managed (Auth0, Okta, Clerk, Microsoft Entra ID, AWS Cognito) or self-hosted
+open source (Keycloak, Zitadel, Ory, Logto) — and verify its JWTs with the
+first-party `jwk()`, `bearerAuth()`, and `requireScopes()` helpers. Don't build
+your own authorization server.
+
+See [Auth architecture](https://daloyjs.dev/docs/auth/architecture) for the
+recommended designs (API resource server and browser BFF).
+
 Read the docs at <https://daloyjs.dev/docs>.

package/templates/bun-basic/_vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "daloyjs-docs": {
+      "type": "http",
+      "url": "https://daloyjs.dev/mcp"
+    }
+  }
+}

package/templates/bun-basic/package.json

@@ -17,7 +17,7 @@
     "audit": "pnpm audit --prod"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.38.0",
+    "@daloyjs/core": "^0.38.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/bun-basic/src/build-app.ts

@@ -18,6 +18,19 @@ export function buildApp(): App {
     bodyLimitBytes: 1024 * 1024,
     requestTimeoutMs: 5_000,
     production: process.env.NODE_ENV === "production",
+    // Reverse-proxy posture. When the app runs behind a trusted edge proxy
+    // (Railway, Render, Fly, Heroku, a single nginx / load balancer), set the
+    // TRUST_PROXY_HOPS env var to the number of proxy hops in front of it — a
+    // single PaaS edge is 1. DaloyJS then reads the real client IP from the
+    // matching X-Forwarded-For slot (used by rateLimit, requestId, and audit
+    // logs). Leave it unset when the app is exposed directly to the public
+    // internet: DaloyJS refuses to honor spoofable X-Forwarded-* headers
+    // (returning 500 on the first forwarded request) rather than trust a
+    // header an attacker can set. See the DaloyJS deployment guide for the
+    // per-platform hop counts.
+    ...(process.env.TRUST_PROXY_HOPS
+      ? { behindProxy: { hops: Number(process.env.TRUST_PROXY_HOPS) } }
+      : {}),
     // daloy-minimal:strip-start docs
     // Auto-mounted docs (when `docs: true`):
     //   GET /openapi.json — OpenAPI 3.1 spec (JSON)
@@ -27,7 +40,19 @@ export function buildApp(): App {
     // `info.title` / `info.version` are pulled from package.json by default;
     // set `openapi.info` here to override them.
     openapi: {
-      servers: [{ url: `http://localhost:${process.env.PORT ?? 3000}` }],
+      // Advertise the public origin so the Scalar "Try it" panel calls the
+      // deployed URL (and stays within the connect-src 'self' CSP) instead of
+      // localhost. Resolves PUBLIC_URL, then Railway's injected domain, then
+      // the local dev port.
+      servers: [
+        {
+          url:
+            process.env.PUBLIC_URL ??
+            (process.env.RAILWAY_PUBLIC_DOMAIN
+              ? `https://${process.env.RAILWAY_PUBLIC_DOMAIN}`
+              : `http://localhost:${process.env.PORT ?? 3000}`),
+        },
+      ],
     },
     docs: true,
     // daloy-minimal:strip-end docs

package/templates/bun-basic/src/index.ts

@@ -23,4 +23,7 @@ const links: StartupBannerLink[] = [
 
 printStartupBanner({ name: "DaloyJS API", url, runtime: "Bun", links });
 
-export default app;
+// NOTE: This module intentionally has no default export. Bun auto-starts a
+// server from any module whose default-exported object has a `fetch` method,
+// which would collide with the explicit `serve()` call above on the same port
+// (EADDRINUSE) and crash on startup (Railway's "Uncaught exception" loop).

package/templates/cloudflare-worker/README.md

@@ -22,3 +22,19 @@ pnpm deploy
 - `@daloyjs/core/cloudflare` with starter security middleware: `secureHeaders` and `requestId`.
 - Smaller edge-friendly body and timeout limits in the generated app.
 - `wrangler.toml` ready for local development and deploys.
+
+## Authentication (OAuth2 / OpenID Connect)
+
+This app is a **resource server**: DaloyJS verifies and enforces access tokens,
+it does **not** issue them. There is no built-in login UI, user database, or
+OAuth2 authorization server (it is not an identity provider like Keycloak,
+Auth0, or Duende IdentityServer). To add login, bring an OpenID Connect provider
+— managed (Auth0, Okta, Clerk, Microsoft Entra ID, AWS Cognito) or self-hosted
+open source (Keycloak, Zitadel, Ory, Logto) — and verify its JWTs with the
+first-party `jwk()`, `bearerAuth()`, and `requireScopes()` helpers. Don't build
+your own authorization server.
+
+See [Auth architecture](https://daloyjs.dev/docs/auth/architecture) for the
+recommended designs (API resource server and browser BFF).
+
+Read the docs at <https://daloyjs.dev/docs>.

package/templates/cloudflare-worker/_vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "daloyjs-docs": {
+      "type": "http",
+      "url": "https://daloyjs.dev/mcp"
+    }
+  }
+}

package/templates/cloudflare-worker/package.json

@@ -11,7 +11,7 @@
     "audit": "pnpm audit --prod"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.38.0",
+    "@daloyjs/core": "^0.38.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/deno-basic/README.md

@@ -56,4 +56,18 @@ deno task test
 <!-- daloy-minimal:strip-end books -->
 - Minimal permissions: `--allow-net --allow-env --allow-read` for `dev`.
 
+## Authentication (OAuth2 / OpenID Connect)
+
+This app is a **resource server**: DaloyJS verifies and enforces access tokens,
+it does **not** issue them. There is no built-in login UI, user database, or
+OAuth2 authorization server (it is not an identity provider like Keycloak,
+Auth0, or Duende IdentityServer). To add login, bring an OpenID Connect provider
+— managed (Auth0, Okta, Clerk, Microsoft Entra ID, AWS Cognito) or self-hosted
+open source (Keycloak, Zitadel, Ory, Logto) — and verify its JWTs with the
+first-party `jwk()`, `bearerAuth()`, and `requireScopes()` helpers. Don't build
+your own authorization server.
+
+See [Auth architecture](https://daloyjs.dev/docs/auth/architecture) for the
+recommended designs (API resource server and browser BFF).
+
 Read the docs at <https://daloyjs.dev/docs>.

package/templates/deno-basic/_vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "daloyjs-docs": {
+      "type": "http",
+      "url": "https://daloyjs.dev/mcp"
+    }
+  }
+}

package/templates/deno-basic/deno.json

@@ -8,10 +8,10 @@
     "gen:openapi": "deno run --allow-net --allow-env --allow-read --allow-write scripts/dump-openapi.ts"
   },
   "imports": {
-    "@daloyjs/core": "jsr:@daloyjs/daloy@^0.38.0",
-    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^0.38.0/banner",
-    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^0.38.0/deno",
-    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^0.38.0/openapi",
+    "@daloyjs/core": "jsr:@daloyjs/daloy@^0.38.2",
+    "@daloyjs/core/banner": "jsr:@daloyjs/daloy@^0.38.2/banner",
+    "@daloyjs/core/deno": "jsr:@daloyjs/daloy@^0.38.2/deno",
+    "@daloyjs/core/openapi": "jsr:@daloyjs/daloy@^0.38.2/openapi",
     "zod": "npm:zod@^4.4.3"
   },
   "compilerOptions": {

package/templates/deno-basic/src/build-app.ts

@@ -19,6 +19,19 @@ export function buildApp(): App {
     bodyLimitBytes: 1024 * 1024,
     requestTimeoutMs: 5_000,
     production: Deno.env.get("DENO_ENV") === "production",
+    // Reverse-proxy posture. When the app runs behind a trusted edge proxy
+    // (Railway, Render, Fly, Heroku, a single nginx / load balancer), set the
+    // TRUST_PROXY_HOPS env var to the number of proxy hops in front of it — a
+    // single PaaS edge is 1. DaloyJS then reads the real client IP from the
+    // matching X-Forwarded-For slot (used by rateLimit, requestId, and audit
+    // logs). Leave it unset when the app is exposed directly to the public
+    // internet: DaloyJS refuses to honor spoofable X-Forwarded-* headers
+    // (returning 500 on the first forwarded request) rather than trust a
+    // header an attacker can set. See the DaloyJS deployment guide for the
+    // per-platform hop counts.
+    ...(Deno.env.get("TRUST_PROXY_HOPS")
+      ? { behindProxy: { hops: Number(Deno.env.get("TRUST_PROXY_HOPS")) } }
+      : {}),
     // daloy-minimal:strip-start docs
     // Auto-mounted docs (when `docs: true`):
     //   GET /openapi.json — OpenAPI 3.1 spec (JSON)
@@ -28,7 +41,19 @@ export function buildApp(): App {
     // `info.title` / `info.version` are pulled from deno.json by default;
     // set `openapi.info` here to override them.
     openapi: {
-      servers: [{ url: `http://localhost:${Deno.env.get("PORT") ?? "3000"}` }],
+      // Advertise the public origin so the Scalar "Try it" panel calls the
+      // deployed URL (and stays within the connect-src 'self' CSP) instead of
+      // localhost. Resolves PUBLIC_URL, then Railway's injected domain, then
+      // the local dev port.
+      servers: [
+        {
+          url:
+            Deno.env.get("PUBLIC_URL") ??
+            (Deno.env.get("RAILWAY_PUBLIC_DOMAIN")
+              ? `https://${Deno.env.get("RAILWAY_PUBLIC_DOMAIN")}`
+              : `http://localhost:${Deno.env.get("PORT") ?? "3000"}`),
+        },
+      ],
     },
     docs: true,
     // daloy-minimal:strip-end docs

package/templates/node-basic/README.md

@@ -65,4 +65,18 @@ On `pnpm build`, TypeScript rewrites the `.ts` specifier to `.js` in the compile
 - Hardened `.npmrc` for safer installs.
 - Hey API codegen wired to `pnpm gen`.
 
+## Authentication (OAuth2 / OpenID Connect)
+
+This app is a **resource server**: DaloyJS verifies and enforces access tokens,
+it does **not** issue them. There is no built-in login UI, user database, or
+OAuth2 authorization server (it is not an identity provider like Keycloak,
+Auth0, or Duende IdentityServer). To add login, bring an OpenID Connect provider
+— managed (Auth0, Okta, Clerk, Microsoft Entra ID, AWS Cognito) or self-hosted
+open source (Keycloak, Zitadel, Ory, Logto) — and verify its JWTs with the
+first-party `jwk()`, `bearerAuth()`, and `requireScopes()` helpers. Don't build
+your own authorization server.
+
+See [Auth architecture](https://daloyjs.dev/docs/auth/architecture) for the
+recommended designs (API resource server and browser BFF).
+
 Read the docs at <https://daloyjs.dev/docs>.

package/templates/node-basic/_vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "daloyjs-docs": {
+      "type": "http",
+      "url": "https://daloyjs.dev/mcp"
+    }
+  }
+}

package/templates/node-basic/package.json

@@ -18,7 +18,7 @@
     "audit": "pnpm audit --prod"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.38.0",
+    "@daloyjs/core": "^0.38.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/node-basic/src/build-app.ts

@@ -20,6 +20,19 @@ export function buildApp(): App {
     bodyLimitBytes: 1024 * 1024,
     requestTimeoutMs: 5_000,
     production: process.env.NODE_ENV === "production",
+    // Reverse-proxy posture. When the app runs behind a trusted edge proxy
+    // (Railway, Render, Fly, Heroku, a single nginx / load balancer), set the
+    // TRUST_PROXY_HOPS env var to the number of proxy hops in front of it — a
+    // single PaaS edge is 1. DaloyJS then reads the real client IP from the
+    // matching X-Forwarded-For slot (used by rateLimit, requestId, and audit
+    // logs). Leave it unset when the app is exposed directly to the public
+    // internet: DaloyJS refuses to honor spoofable X-Forwarded-* headers
+    // (returning 500 on the first forwarded request) rather than trust a
+    // header an attacker can set. See the DaloyJS deployment guide for the
+    // per-platform hop counts.
+    ...(process.env.TRUST_PROXY_HOPS
+      ? { behindProxy: { hops: Number(process.env.TRUST_PROXY_HOPS) } }
+      : {}),
     // daloy-minimal:strip-start docs
     // Auto-mounted docs (when `docs: true`):
     //   GET /openapi.json — OpenAPI 3.1 spec (JSON)
@@ -32,7 +45,19 @@ export function buildApp(): App {
     // `info.title` / `info.version` are pulled from package.json by default;
     // set `openapi.info` here to override them.
     openapi: {
-      servers: [{ url: `http://localhost:${process.env.PORT ?? 3000}` }],
+      // Advertise the public origin so the Scalar "Try it" panel calls the
+      // deployed URL (and stays within the connect-src 'self' CSP) instead of
+      // localhost. Resolves PUBLIC_URL, then Railway's injected domain, then
+      // the local dev port.
+      servers: [
+        {
+          url:
+            process.env.PUBLIC_URL ??
+            (process.env.RAILWAY_PUBLIC_DOMAIN
+              ? `https://${process.env.RAILWAY_PUBLIC_DOMAIN}`
+              : `http://localhost:${process.env.PORT ?? 3000}`),
+        },
+      ],
     },
     docs: true,
     // daloy-minimal:strip-end docs

package/templates/node-basic/tsconfig.build.json

@@ -3,8 +3,9 @@
   "compilerOptions": {
     "declaration": true,
     "outDir": "dist",
+    "rootDir": "src",
     "sourceMap": true
   },
-  "include": ["src/**/*", "scripts/**/*"],
+  "include": ["src/**/*"],
   "exclude": ["node_modules", "dist", "tests"]
 }

package/templates/{vercel-edge → vercel}/AGENTS.md

@@ -1,9 +1,9 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel Edge**. **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them. When `docs: true` is set in `new App({...})`, three routes are auto-mounted: `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** (Vercel's recommended runtime for standalone functions, running on Fluid Compute). **Contract-first**: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them. When `docs: true` is set in `new App({...})`, three routes are auto-mounted: `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 Edge (Web Standard `Request`/`Response`).
+- Runtime: Vercel Node.js Functions on Fluid Compute (Web Standard `Request`/`Response`).
 
 ## Commands
 
@@ -15,7 +15,7 @@ A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel Edge**. **Contrac
 
 ## Project shape
 
-- `api/[...path].ts` — Vercel Edge entrypoint. Builds the `App`, registers routes/middleware, and exports `default toWebHandler(app)` plus `export const config = { runtime: "edge" }`. **Keep it a catch-all** so DaloyJS owns routing. For Vercel's recommended Node.js runtime, remove the Edge config and export `default toFetchHandler(app)` from `@daloyjs/core/vercel`.
+- `api/[...path].ts` — Vercel Node.js Functions entrypoint. Builds the `App`, registers routes/middleware, and exports `default toFetchHandler(app)` from `@daloyjs/core/vercel` (Node.js Functions expect a default export with a `fetch` method; Node.js is the default runtime, so no `runtime` export is needed). **Keep it a catch-all** so DaloyJS owns routing. If you specifically need the Edge runtime, add `export const runtime = "edge"` and switch to `default toWebHandler(app)`.
 - `vercel.json` — Vercel build/runtime configuration.
 - `tests/` — test files.
 
@@ -36,7 +36,7 @@ You import the file you see. Vercel bundles the `api/` functions at deploy time
 3. Preserve literal types in responses: `status: 200 as const`, `z.literal(...)` on discriminator fields.
 4. Throw typed errors (`NotFoundError`, `BadRequestError`, etc.) from `@daloyjs/core`.
 5. Keep `requestId()`, `secureHeaders()`, and `rateLimit()` enabled. For production traffic, back rate-limiting with Vercel KV or another shared store (the in-memory limiter resets per instance).
-6. Stay on the Edge runtime: only Web Standards APIs. No `node:` modules, no `fs`, no `Buffer`. If a feature requires Node, switch to a Node-runtime template.
+6. On the Node.js runtime the full Node API is available (`node:*`, `Buffer`, `fs`), but prefer Web Standards (`Request`/`Response`, `fetch`, Web Crypto) so the same app can also run on the Edge runtime or another adapter unchanged. If you opt into the Edge runtime, drop `node:` modules entirely.
 7. The catch-all `api/[...path].ts` must remain a catch-all so DaloyJS handles routing.
 8. Every new route ships with a test that covers a happy path and at least one unhappy path.
 
@@ -48,7 +48,7 @@ Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/
 - Keep Zod `.strict()` on top-level request objects; do not switch to `.passthrough()`. Keep `responses[N].body` schemas tight; never widen to `z.any()` to let a privileged field escape.
 - Every protected route attaches an auth `beforeHandle` and ships an unhappy-path test proving an unauthenticated request returns `401` (and wrong scope returns `403`) — the HTTP-boundary equivalent of Supabase's pgTAP policy tests.
 - JWT verifiers keep an explicit `algorithms` allowlist; never trust the token's `alg` header, never allow `none`, always check `exp` / `nbf`.
-- Credential / HMAC comparisons use `crypto.subtle.timingSafeEqual`, never `===`. Throw typed errors from `@daloyjs/core` so problem+json redacts in prod; never return raw stack traces.
+- Credential / HMAC comparisons use a constant-time comparison (the framework's `timingSafeEqual`), never `===`. Throw typed errors from `@daloyjs/core` so problem+json redacts in prod; never return raw stack traces.
 - Keep `api/[...path].ts` a catch-all so DaloyJS owns routing — do not split into per-path files that bypass the middleware chain.
 - `.env`, `.env.local`, secrets, private keys: never commit. Use `vercel env` for production secrets.
 

package/templates/{vercel-edge → vercel}/README.md

@@ -1,6 +1,6 @@
 # my-daloy-vercel-api
 
-A [DaloyJS](https://daloyjs.dev) Vercel Edge API starter.
+A [DaloyJS](https://daloyjs.dev) Vercel API starter on the Node.js runtime.
 
 ## Develop
 
@@ -26,7 +26,7 @@ curl http://localhost:3000/books/1
 - OpenAPI 3.1 JSON: <http://localhost:3000/openapi.json>
 - OpenAPI 3.1 YAML: <http://localhost:3000/openapi.yaml>
 
-After deploying, the same routes serve `/docs`, `/openapi.json`, and `/openapi.yaml` from your Vercel Edge URL.
+After deploying, the same routes serve `/docs`, `/openapi.json`, and `/openapi.yaml` from your Vercel deployment URL.
 To brand Scalar, change `docs: true` in `api/[...path].ts` to `docs: { scalar: { theme, customCss } }`.
 
 <!-- daloy-minimal:strip-end docs -->
@@ -40,19 +40,23 @@ pnpm deploy
 The API entry lives at `api/[...path].ts` and uses `@daloyjs/core/vercel`:
 
 ```ts
-export const config = { runtime: "edge" };
-export default toWebHandler(app);
+import { toFetchHandler } from "@daloyjs/core/vercel";
+
+// Node.js is the default runtime — no `runtime` export needed.
+export default toFetchHandler(app);
 ```
 
-This starter defaults to Vercel's Edge runtime for compatibility with the
-`vercel-edge` template name. Vercel now recommends Node.js for new projects;
-for Node.js Functions, remove the `config` export and use the official default
-`{ fetch }` shape instead:
+This starter targets Vercel's Node.js runtime (on Fluid Compute), which Vercel
+now recommends for standalone functions. Node.js Functions expect a default
+export with a `fetch` method, which is exactly what `toFetchHandler(app)`
+returns. If you specifically need the Edge runtime, add the `runtime` export and
+switch to the bare web handler:
 
 ```ts
-import { toFetchHandler } from "@daloyjs/core/vercel";
+import { toWebHandler } from "@daloyjs/core/vercel";
 
-export default toFetchHandler(app);
+export const runtime = "edge";
+export default toWebHandler(app);
 ```
 
 That catch-all API route lets DaloyJS own routing while Vercel handles the runtime.
@@ -70,10 +74,24 @@ Vercel bundles the `api/` functions at deploy time and resolves `.ts` directly,
 ## What's included
 
 - `@daloyjs/core/vercel` with starter security middleware: `secureHeaders` and `requestId`.
-- Smaller edge-friendly body and timeout limits in the generated app.
+- Smaller serverless-friendly body and timeout limits in the generated app.
 <!-- daloy-minimal:strip-start books -->
 - A health route and a contract-first `/books/:id` route with Zod validation.
   <!-- daloy-minimal:strip-end books -->
   <!-- daloy-minimal:strip-start docs -->
 - A Scalar API reference UI at `/docs`, plus live OpenAPI 3.1 specs at `/openapi.json` and `/openapi.yaml`.
 <!-- daloy-minimal:strip-end docs -->
+
+## Authentication (OAuth2 / OpenID Connect)
+
+This app is a **resource server**: DaloyJS verifies and enforces access tokens,
+it does **not** issue them. There is no built-in login UI, user database, or
+OAuth2 authorization server (it is not an identity provider like Keycloak,
+Auth0, or Duende IdentityServer). To add login, bring an OpenID Connect provider
+— managed (Auth0, Okta, Clerk, Microsoft Entra ID, AWS Cognito) or self-hosted
+open source (Keycloak, Zitadel, Ory, Logto) — and verify its JWTs with the
+first-party `jwk()`, `bearerAuth()`, and `requireScopes()` helpers. Don't build
+your own authorization server.
+
+See [Auth architecture](https://daloyjs.dev/docs/auth/architecture) for the
+recommended designs (API resource server and browser BFF).

package/templates/{vercel-edge → vercel}/_Dockerfile

@@ -1,8 +1,8 @@
 # syntax=docker/dockerfile:1.7
-# Containerized local-dev / CI environment for a DaloyJS Vercel Edge API.
+# Containerized local-dev / CI environment for a DaloyJS Vercel API.
 #
 # Production deploys go through `vercel deploy` to Vercel's managed
-# Edge runtime — **this Dockerfile is not a production runtime**. Ship
+# Node.js runtime — **this Dockerfile is not a production runtime**. Ship
 # the function to Vercel; use this image for:
 #   - Reproducible local dev (devcontainers, GitHub Codespaces).
 #   - CI smoke tests that exercise the handler against `vercel dev`

package/templates/{vercel-edge → vercel}/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -2,20 +2,21 @@
 name: daloyjs-best-practices
 description: >-
   Best practices for building, testing, and hardening this DaloyJS REST API on
-  Vercel Edge. Use when adding or changing HTTP routes, Zod schemas,
-  middleware, or error handling; regenerating the OpenAPI spec or the typed
-  Hey API client; keeping the catch-all Edge entrypoint and Web-Standard
-  runtime constraints; or working on auth, rate limits, secrets, and the
+  Vercel (Node.js runtime). Use when adding or changing HTTP routes, Zod
+  schemas, middleware, or error handling; regenerating the OpenAPI spec or the
+  typed Hey API client; keeping the catch-all Vercel Functions entrypoint and
+  Web-Standard handler; or working on auth, rate limits, secrets, and the
   project's quality gates.
 license: MIT
 ---
 
-# SKILL.md — DaloyJS best practices (Vercel Edge)
+# SKILL.md — DaloyJS best practices (Vercel, Node.js runtime)
 
 Operational guidance and best practices for AI coding agents working in this
-DaloyJS **Vercel Edge** project. This is the project's **single source of
-truth** for how to add routes, write tests, ship secure defaults, and run
-the quality gates. Read this in full before making non-trivial changes.
+DaloyJS **Vercel** project on the **Node.js runtime** (Fluid Compute). This is
+the project's **single source of truth** for how to add routes, write tests,
+ship secure defaults, and run the quality gates. Read this in full before
+making non-trivial changes.
 
 ## When to use this skill
 
@@ -24,18 +25,21 @@ Use this skill when you need to:
 - Add, modify, or remove HTTP routes in this project.
 - Adjust middleware, validation, or error handling.
 - Run tests or typecheck the project.
-- Deploy or troubleshoot the Edge runtime entrypoint.
+- Deploy or troubleshoot the Vercel Functions entrypoint.
 - Harden the API (auth, CORS, rate limits, secrets, dependency hygiene).
 
 Do **not** use this skill for tasks unrelated to the API itself.
 
 ## Core principles
 
-DaloyJS is a **contract-first** framework. On Vercel Edge, additionally:
+DaloyJS is a **contract-first** framework. On Vercel, additionally:
 
-1. **Stay on the Edge runtime.** Only Web Standards APIs (no `node:`
-   modules, no `fs`, no `Buffer`). If a feature requires Node APIs, the
-   user must switch to a Node template.
+1. **Node.js runtime by default.** The full Node API is available
+   (`node:*`, `Buffer`, `fs`), but prefer Web Standards (`Request` /
+   `Response`, `fetch`, Web Crypto) so the same app can also run on the
+   Edge runtime or another adapter unchanged. Opt into Edge only when you
+   need it (`export const runtime = "edge"` + `toWebHandler(app)`), and
+   then drop `node:` modules.
 2. **The route definition is the contract.** Method, path, request
    schemas, and response schemas live in one place (`app.route({...})`).
 3. **Zod schemas validate at every boundary.**
@@ -43,16 +47,17 @@ DaloyJS is a **contract-first** framework. On Vercel Edge, additionally:
 5. **Secure by default.** `requestId()`, `secureHeaders()`, and
    `rateLimit()` are registered before route definitions. Note the
    in-memory rate limiter resets per instance — for high-traffic
-   deployments, prefer Vercel's native rate-limiting (e.g.
-   `@vercel/edge` + KV) or an external store.
+   deployments, back it with an external shared store (e.g. Upstash
+   Redis).
 6. **One catch-all entrypoint.** `api/[...path].ts` owns all routing so
    DaloyJS can generate a unified OpenAPI spec.
 
 ## Project shape
 
-- `api/[...path].ts` — the Edge entrypoint. Builds the `App`, registers
-  routes/middleware, and exports `default toWebHandler(app)` plus
-  `export const config = { runtime: "edge" }`.
+- `api/[...path].ts` — the Vercel Functions entrypoint. Builds the `App`,
+  registers routes/middleware, and exports `default toFetchHandler(app)`
+  (Node.js Functions expect a default export with a `fetch` method; Node.js
+  is the default runtime, so no `runtime` export is needed).
 - `vercel.json` — Vercel build/runtime configuration.
 - `tests/` — test files (`*.test.ts`).
 
@@ -82,9 +87,9 @@ definitions:
 Customize via `docs: { openapiPath, openapiYamlPath, path, ui }`. Set
 `openapiYamlPath: false` to disable just the YAML route, `docs: "auto"` to
 mount only outside production, or `docs: false` to disable all three.
-On Vercel Edge the YAML serializer is pure-string (no Node deps) and
-adds <1KB to the bundle. For hand-rolled mounting, `openapiToYAML` is
-exported from `@daloyjs/core/openapi`.
+On Vercel the YAML serializer is pure-string (no extra deps) and adds
+<1KB to the bundle. For hand-rolled mounting, `openapiToYAML` is exported
+from `@daloyjs/core/openapi`.
 
 ## Workflow: add a new route
 
@@ -151,7 +156,7 @@ Add CORS only when needed, with an explicit `origin` allowlist.
 
 ## Testing best practices
 
-Tests use in-process `app.request(...)` — no port, no Edge runtime
+Tests use in-process `app.request(...)` — no port, no Vercel runtime
 needed for unit tests.
 
 ```ts
@@ -159,10 +164,11 @@ import { test } from "node:test";
 import assert from "node:assert/strict";
 import handler from "../api/[...path].ts";
 
-// Either import the underlying app, or test via the Edge handler's
-// fetch interface by passing a Web Request.
+// Either import the underlying app, or test via the handler's fetch
+// method (the default export is the Vercel `{ fetch }` object) by
+// passing a Web Request.
 test("GET /healthz returns ok", async () => {
-  const res = await handler(new Request("http://local/healthz"));
+  const res = await handler.fetch(new Request("http://local/healthz"));
   assert.equal(res.status, 200);
 });
 ```
@@ -180,23 +186,25 @@ Aim for **100% line and function coverage** on the routes you add.
   production traffic, back rate-limiting with Vercel KV or another
   shared store so limits apply across instances.
 - Never log secrets — filter `authorization`, `cookie`, etc.
-- Read secrets from `process.env` (available on Edge). Validate via Zod
-  at module load.
+- Read secrets from `process.env` (available on Node.js Functions).
+  Validate via Zod at module load.
 - For auth, verify JWT signatures with the Web Crypto API
-  (`crypto.subtle`). Never trust the `alg` header from the token.
+  (`crypto.subtle`, available on both Node.js and Edge). Never trust the
+  `alg` header from the token.
 - Validate redirects against an allowlist.
 - Set `bodyLimitBytes` and `requestTimeoutMs` on `new App({...})` to
   mitigate DoS.
-- Edge functions have small bundle and CPU limits; be cautious about
-  adding heavy dependencies. Inspect bundle size during deploy.
-- Pin Vercel project settings (regions, runtime version) explicitly in
-  `vercel.json` rather than relying on dashboard defaults.
+- Serverless functions still have bundle-size and cold-start costs; be
+  cautious about adding heavy dependencies. Inspect bundle size during
+  deploy.
+- Pin Vercel project settings (regions, memory, maxDuration) explicitly
+  in `vercel.json` rather than relying on dashboard defaults.
 
 ## Logging & observability
 
 - Use `ctx.log` — it carries the request id.
-- `console.log` on Edge shows up in Vercel's runtime logs; the framework
-  logger emits structured JSON for log aggregators.
+- `console.log` shows up in Vercel's runtime logs; the framework logger
+  emits structured JSON for log aggregators.
 
 ## Configuration & secrets
 
@@ -209,13 +217,14 @@ Aim for **100% line and function coverage** on the routes you add.
   handles routing. Do not split routes into multiple Vercel API files
   unless the user explicitly asks (it disables shared middleware and a
   unified OpenAPI).
-- Use `toWebHandler(app)` from `@daloyjs/core/vercel` for Edge — never
-  hand-roll a `fetch(req)` adapter. For Vercel's recommended Node.js
-  runtime, remove the Edge config and export `default toFetchHandler(app)`.
+- Use `toFetchHandler(app)` from `@daloyjs/core/vercel` for Node.js
+  Functions — never hand-roll a `fetch(req)` adapter. If you opt into the
+  Edge runtime, use `toWebHandler(app)` with `export const runtime = "edge"`.
 - Do not import `@daloyjs/core/node`, `@daloyjs/core/bun`, etc. — only
   `@daloyjs/core` and `@daloyjs/core/vercel`.
-- Avoid Node-only APIs (`Buffer`, `fs`, full `process` API). If a
-  feature needs Node, switch to a Node-runtime template.
+- Node APIs (`Buffer`, `fs`, full `process`) are available on the Node.js
+  runtime, but keep handlers Web-Standard where practical so the app can
+  also run on the Edge runtime unchanged.
 - Do not weaken response literal types (`as const`).
 - Do not return errors as `{ status: 4xx, body }`. Throw a typed error.
 - Do not add runtime dependencies without checking the hardened `.npmrc` (installs wait 24h after publish by default).

package/templates/vercel/_vscode/mcp.json

@@ -0,0 +1,8 @@
+{
+  "servers": {
+    "daloyjs-docs": {
+      "type": "http",
+      "url": "https://daloyjs.dev/mcp"
+    }
+  }
+}

package/templates/{vercel-edge → vercel}/api/[...path].ts

@@ -1,11 +1,15 @@
 import { z } from "zod";
 import { App, NotFoundError, requestId, secureHeaders } from "@daloyjs/core";
-import { toWebHandler } from "@daloyjs/core/vercel";
+import { toFetchHandler } from "@daloyjs/core/vercel";
 
-// This template defaults to Vercel's Edge runtime for compatibility with the
-// existing `vercel-edge` starter. For Vercel's recommended Node.js runtime,
-// remove this config and export `toFetchHandler(app)` from @daloyjs/core/vercel.
-export const config = { runtime: "edge" };
+// This template targets Vercel's Node.js runtime — the runtime Vercel now
+// recommends for standalone functions (it runs on Fluid Compute, with the
+// performance of the edge network but full Node API support). Node.js is the
+// default runtime, so no `runtime` export is needed. Vercel Node.js Functions
+// in `/api` expect a default export with a `fetch` method, which is exactly
+// what `toFetchHandler(app)` returns. If you specifically need the Edge runtime
+// instead, add `export const runtime = "edge"` and switch the default export to
+// `toWebHandler(app)` from "@daloyjs/core/vercel".
 
 const app = new App({
   bodyLimitBytes: 256 * 1024,
@@ -17,7 +21,7 @@ const app = new App({
   //   GET /openapi.yaml — OpenAPI 3.1 spec (YAML, served inline as text/yaml)
   //   GET /docs         — Scalar API reference UI that loads the spec
   openapi: {
-    info: { title: "My Daloy Edge API", version: "0.0.1" },
+    info: { title: "My Daloy Vercel API", version: "0.0.1" },
   },
   docs: true,
   // daloy-minimal:strip-end docs
@@ -34,12 +38,12 @@ app.route({
   responses: {
     200: {
       description: "Service is healthy",
-      body: z.object({ ok: z.literal(true), runtime: z.literal("vercel-edge") }),
+      body: z.object({ ok: z.literal(true), runtime: z.literal("vercel") }),
     },
   },
   handler: async () => ({
     status: 200,
-    body: { ok: true as const, runtime: "vercel-edge" as const },
+    body: { ok: true as const, runtime: "vercel" as const },
   }),
 });
 
@@ -67,4 +71,4 @@ app.route({
 });
 // daloy-minimal:strip-end books
 
-export default toWebHandler(app);
+export default toFetchHandler(app);

package/templates/{vercel-edge → vercel}/package.json

@@ -11,7 +11,7 @@
     "audit": "pnpm audit --prod"
   },
   "dependencies": {
-    "@daloyjs/core": "^0.38.0",
+    "@daloyjs/core": "^0.38.2",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/templates/vercel/tests/app.test.ts

@@ -0,0 +1,10 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import handler from "../api/[...path].ts";
+
+test("Vercel Node.js handler responds through DaloyJS", async () => {
+  // Vercel Node.js Functions invoke the default export's `fetch` method.
+  const response = await handler.fetch(new Request("https://example.test/healthz"));
+  assert.equal(response.status, 200);
+  assert.equal((await response.json()).runtime, "vercel");
+});

package/templates/vercel/vercel.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "cleanUrls": true,
+  "functions": {
+    "api/[...path].ts": { "memory": 1024, "maxDuration": 30 }
+  }
+}

package/templates/vercel-edge/tests/app.test.ts

@@ -1,9 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import handler from "../api/[...path].ts";
-
-test("Vercel Edge handler responds through DaloyJS", async () => {
-  const response = await handler(new Request("https://example.test/healthz"));
-  assert.equal(response.status, 200);
-  assert.equal((await response.json()).runtime, "vercel-edge");
-});

package/templates/vercel-edge/vercel.json

@@ -1,4 +0,0 @@
-{
-  "version": 2,
-  "cleanUrls": true
-}