create-daloy 0.37.0 → 0.38.1

package/README.md

@@ -120,6 +120,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

package/bin/create-daloy.mjs

@@ -630,8 +630,12 @@ async function patchDockerfileForPackageManager(dir, packageManager) {
 
   const raw = await readFile(file, "utf8");
   const install = dockerInstallSnippet(packageManager);
+  // Match the pnpm install block tolerant of both LF and CRLF line endings.
+  // Windows checkouts (and packages published from Windows) can carry CRLF;
+  // an `\n`-only pattern would silently fail to match there, leaving the
+  // pnpm-specific COPY/RUN lines in place for npm/yarn/bun scaffolds.
   let next = raw.replace(
-    /COPY package\.json pnpm-lock\.yaml\* \.\/\nRUN corepack enable && corepack prepare pnpm@latest --activate && \\\n+\s+pnpm install --frozen-lockfile --ignore-scripts/,
+    /COPY package\.json pnpm-lock\.yaml\* \.\/\r?\nRUN corepack enable && corepack prepare pnpm@latest --activate && \\\r?\n\s+pnpm install --frozen-lockfile --ignore-scripts/,
     `${install.copy}\n${install.run}`,
   );
 
@@ -645,8 +649,11 @@ async function patchDockerfileForPackageManager(dir, packageManager) {
 
   if (packageManager === "bun" && next.includes("FROM ${NODE_IMAGE} AS builder")) {
     if (!next.includes("ARG BUN_IMAGE=")) {
+      // CRLF-tolerant: the working tree may carry `\r\n`, so a plain
+      // `"...alpine\n"` substring replace would miss and the BUN_IMAGE ARG
+      // would never be inserted.
       next = next.replace(
-        "ARG NODE_IMAGE=node:24-alpine\n",
+        /ARG NODE_IMAGE=node:24-alpine\r?\n/,
         "ARG NODE_IMAGE=node:24-alpine\nARG BUN_IMAGE=oven/bun:1-alpine\n",
       );
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-daloy",
-  "version": "0.37.0",
+  "version": "0.38.1",
   "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:a4416ef1-59e7-5669-9295-8eb452a49fdf",
+  "serialNumber": "urn:uuid:5874d6d1-4f7c-5889-b1dc-59abaf86bc40",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-31T20:28:16.974Z",
+    "timestamp": "2026-06-11T09:54:26.989Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "0.37.0"
+        "version": "0.38.1"
       }
     ],
     "authors": [],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/create-daloy@0.37.0",
+      "bom-ref": "pkg:npm/create-daloy@0.38.1",
       "name": "create-daloy",
-      "version": "0.37.0",
+      "version": "0.38.1",
       "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.37.0",
+      "purl": "pkg:npm/create-daloy@0.38.1",
       "licenses": [
         {
           "license": {
@@ -42,9 +42,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag-create-daloy-0.37.0",
+        "tagId": "swidtag-create-daloy-0.38.1",
         "name": "create-daloy",
-        "version": "0.37.0",
+        "version": "0.38.1",
         "tagVersion": 0,
         "patch": false
       }
@@ -53,7 +53,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/create-daloy@0.37.0",
+      "ref": "pkg:npm/create-daloy@0.38.1",
       "dependsOn": []
     }
   ]

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "create-daloy-0.37.0",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-0.37.0-a4416ef1-59e7-5669-9295-8eb452a49fdf",
+  "name": "create-daloy-0.38.1",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-0.38.1-5874d6d1-4f7c-5889-b1dc-59abaf86bc40",
   "creationInfo": {
-    "created": "2026-05-31T20:28:16.974Z",
+    "created": "2026-06-11T09:54:26.989Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package-create-daloy",
       "name": "create-daloy",
-      "versionInfo": "0.37.0",
+      "versionInfo": "0.38.1",
       "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.37.0"
+          "referenceLocator": "pkg:npm/create-daloy@0.38.1"
         }
       ]
     }

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/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

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/package.json

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

package/templates/cloudflare-worker/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

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/package.json

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

package/templates/deno-basic/AGENTS.md

@@ -2,7 +2,7 @@
 
 A [DaloyJS](https://daloyjs.dev) REST API for the [Deno](https://deno.com) runtime. **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).
 
-- Runtime: Deno (no Node package manager). Dependencies are loaded via `npm:` and `jsr:` specifiers in `deno.json`.
+- Runtime: Deno (no Node package manager). DaloyJS loads from `jsr:` and third-party packages such as Zod load from `npm:` in `deno.json`.
 
 ## Commands
 
@@ -18,7 +18,7 @@ The typed Hey API SDK is generated outside Deno (Hey API has no Deno entrypoint
 - `src/build-app.ts` — `buildApp()` factory. Routes, schemas, and middleware live here. **Pure, no side effects.**
 - `src/main.ts` — calls `buildApp()` and starts the listener via `@daloyjs/core/deno`. The only file that opens a port.
 - `scripts/dump-openapi.ts` — imports `buildApp()` and writes `generated/openapi.json`. Codegen reads from `buildApp()` only — never import `src/main.ts` from scripts.
-- `deno.json` — tasks, import map, and `npm:` specifiers. There is no `package.json` in this project.
+- `deno.json` — tasks, import map, and JSR-first dependency specifiers. There is no `package.json` in this project.
 - `generated/` — machine-written. Do not edit by hand.
 - `tests/` — Deno test files.
 

package/templates/deno-basic/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/deno-basic/README.md

@@ -49,11 +49,25 @@ deno task test
 
 ## What's included
 
-- `@daloyjs/core` (loaded via `npm:` specifiers in `deno.json`).
+- `@daloyjs/core` (loaded via `jsr:` specifiers in `deno.json`).
 - Starter security middleware: `secureHeaders`, `requestId`, and `rateLimit`.
 <!-- daloy-minimal:strip-start books -->
 - A health route and contract-first `/books/:id` route with Zod validation.
 <!-- 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/_agents/skills/daloyjs-best-practices/SKILL.md

@@ -54,7 +54,7 @@ DaloyJS is a **contract-first** framework. Internalize these rules:
   `@daloyjs/core/deno`. The only file allowed to open a port.
 - `scripts/dump-openapi.ts` — imports `buildApp()` and writes
   `generated/openapi.json`.
-- `deno.json` — tasks, import map, and `npm:` specifiers. **There is no
+- `deno.json` — tasks, import map, and JSR-first dependency specifiers. **There is no
   `package.json`** in this project — do not add one.
 - `tests/` — Deno test files (`*.test.ts`).
 - `generated/` — **machine-written**. Never edit by hand.

package/templates/deno-basic/deno.json

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

package/templates/deno-basic/deno.lock

@@ -0,0 +1,35 @@
+{
+  "version": "5",
+  "specifiers": {
+    "jsr:@std/assert@1": "1.0.19",
+    "jsr:@std/internal@^1.0.12": "1.0.14",
+    "npm:@daloyjs/core@0.37": "0.37.0",
+    "npm:zod@^4.4.3": "4.4.3"
+  },
+  "jsr": {
+    "@std/assert@1.0.19": {
+      "integrity": "eaada96ee120cb980bc47e040f82814d786fe8162ecc53c91d8df60b8755991e",
+      "dependencies": [
+        "jsr:@std/internal"
+      ]
+    },
+    "@std/internal@1.0.14": {
+      "integrity": "291516b3d4c35024d6ffbc0a9df5bf4c64116e05b50012cf846710152d2ffdf7"
+    }
+  },
+  "npm": {
+    "@daloyjs/core@0.37.0": {
+      "integrity": "sha512-z7XRaoue2TqDIyQIdsg8ZKlBPmvYU8WX2ieYk3sGBMyt181bkb9NBgnxD/m6W54ojpiz4ArFRxyJ9BQTfjLvnQ==",
+      "bin": true
+    },
+    "zod@4.4.3": {
+      "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ=="
+    }
+  },
+  "workspace": {
+    "dependencies": [
+      "npm:@daloyjs/core@0.37",
+      "npm:zod@^4.4.3"
+    ]
+  }
+}

package/templates/node-basic/AGENTS.md

@@ -27,13 +27,13 @@ When `docs: true` is set in `new App({...})`, three routes are auto-mounted:
 
 ## Imports
 
-This project uses TypeScript with `"module": "NodeNext"` (ESM). Relative imports **must include a `.js` extension**, even when the source file is `.ts`:
+This project uses TypeScript with `"module": "NodeNext"` plus `"rewriteRelativeImportExtensions"`, so relative imports use the **`.ts` extension** — the actual file you see on disk:
 
 ```ts
-import { buildApp } from "./build-app.js"; // resolves to build-app.ts at typecheck, build-app.js at runtime
+import { buildApp } from "./build-app.ts";
 ```
 
-This is the official Node.js ESM convention — TypeScript rewrites the specifier during typecheck, and the compiled output really is `.js`. Bare-specifier imports from packages (`@daloyjs/core`, `zod`, …) do not need an extension.
+You import the file you see. On `pnpm build`, TypeScript rewrites the `.ts` specifier to `.js` in the compiled `dist/` output, so the deployed code is still valid Node ESM. (Node ESM has no extensionless relative imports — `.ts` is the most natural form available.) Bare-specifier imports from packages (`@daloyjs/core`, `zod`, …) do not need an extension.
 
 ## Core rules
 

package/templates/node-basic/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/node-basic/README.md

@@ -48,13 +48,13 @@ node dist/index.js
 
 ## Imports
 
-This project uses Node.js **ESM** with `"module": "NodeNext"`. Relative imports must include a `.js` extension, even when the source file is `.ts`:
+This project uses Node.js **ESM** with `"module": "NodeNext"` and `"rewriteRelativeImportExtensions"`. Relative imports use the `.ts` extension — the actual file on disk:
 
 ```ts
-import { buildApp } from "./build-app.js"; // ./build-app.ts on disk
+import { buildApp } from "./build-app.ts";
 ```
 
-TypeScript resolves the `.js` specifier to the matching `.ts` file at typecheck, and the compiled output really is `.js`. This is the official Node ESM convention — not a typo.
+On `pnpm build`, TypeScript rewrites the `.ts` specifier to `.js` in the compiled `dist/` output, so the deployed code is valid Node ESM. (Node ESM has no extensionless relative imports — `.ts` is the most natural form available.)
 
 ## What's included
 
@@ -65,4 +65,18 @@ TypeScript resolves the `.js` specifier to the matching `.ts` file at typecheck,
 - 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/package.json

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

package/templates/node-basic/scripts/dump-openapi.ts

@@ -1,6 +1,6 @@
 import { writeFile, mkdir } from "node:fs/promises";
 import { generateOpenAPI } from "@daloyjs/core/openapi";
-import { buildApp } from "../src/build-app.js";
+import { buildApp } from "../src/build-app.ts";
 
 // Build a fresh app from the factory so the spec dump never starts the HTTP
 // listener as a side effect. Keep this script deterministic so codegen output

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

@@ -1,6 +1,6 @@
 import { serve } from "@daloyjs/core/node";
 import { printStartupBanner, type StartupBannerLink } from "@daloyjs/core/banner";
-import { buildApp } from "./build-app.js";
+import { buildApp } from "./build-app.ts";
 
 const app = buildApp();
 const port = Number(process.env.PORT ?? 3000);

package/templates/node-basic/tsconfig.json

@@ -11,7 +11,9 @@
     "esModuleInterop": true,
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true,
-    "resolveJsonModule": true
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "rewriteRelativeImportExtensions": true
   },
   "include": ["src/**/*", "scripts/**/*", "tests/**/*"],
   "exclude": ["node_modules", "dist"]

package/templates/vercel-edge/AGENTS.md

@@ -21,13 +21,13 @@ A [DaloyJS](https://daloyjs.dev) REST API deployed to **Vercel Edge**. **Contrac
 
 ## Imports
 
-This project uses TypeScript with `"module": "NodeNext"` (ESM). Relative imports **must include a `.js` extension**, even when the source file is `.ts`:
+This project uses TypeScript with `"allowImportingTsExtensions"`, so relative imports use the **`.ts` extension** — the actual file you see on disk:
 
 ```ts
-import handler from "../api/[...path].js"; // resolves to the .ts source at typecheck, .js at runtime
+import handler from "../api/[...path].ts";
 ```
 
-This is the official Node.js ESM convention — TypeScript rewrites the specifier during typecheck, and the deployed output really is `.js`. Bare-specifier imports from packages (`@daloyjs/core`, `zod`, …) do not need an extension.
+You import the file you see. Vercel bundles the `api/` functions at deploy time and resolves `.ts` directly, and the test runner (tsx) does too. Bare-specifier imports from packages (`@daloyjs/core`, `zod`, …) do not need an extension.
 
 ## Core rules
 

package/templates/vercel-edge/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/vercel-edge/README.md

@@ -59,13 +59,13 @@ That catch-all API route lets DaloyJS own routing while Vercel handles the runti
 
 ## Imports
 
-This project uses TypeScript with `"module": "NodeNext"` (ESM). Relative imports must include a `.js` extension, even when the source file is `.ts`:
+This project uses TypeScript with `"allowImportingTsExtensions"`. Relative imports use the `.ts` extension — the actual file on disk:
 
 ```ts
-import handler from "../api/[...path].js"; // ../api/[...path].ts on disk
+import handler from "../api/[...path].ts";
 ```
 
-TypeScript resolves the `.js` specifier to the matching `.ts` file at typecheck, and the deployed output really is `.js`. This is the official Node ESM convention — not a typo.
+Vercel bundles the `api/` functions at deploy time and resolves `.ts` directly, and the test runner (tsx) does too.
 
 ## What's included
 
@@ -77,3 +77,17 @@ TypeScript resolves the `.js` specifier to the matching `.ts` file at typecheck,
   <!-- 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/package.json

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

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

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import handler from "../api/[...path].js";
+import handler from "../api/[...path].ts";
 
 test("Vercel Edge handler responds through DaloyJS", async () => {
   const response = await handler(new Request("https://example.test/healthz"));

package/templates/vercel-edge/tsconfig.json

@@ -12,7 +12,8 @@
     "forceConsistentCasingInFileNames": true,
     "resolveJsonModule": true,
     "isolatedModules": true,
-    "noEmit": true
+    "noEmit": true,
+    "allowImportingTsExtensions": true
   },
   "include": ["api/**/*.ts", "tests/**/*.ts"]
 }