create-daloy 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -17,6 +17,9 @@ pnpm create daloy@latest my-api
 npm  create daloy@latest my-api
 yarn create daloy           my-api
 bun  create daloy           my-api
+
+# scaffold into the current directory
+pnpm create daloy@latest .
 ```
 
 The CLI is interactive when arguments are missing. It will ask you for:

package/bin/create-daloy.mjs

@@ -363,6 +363,7 @@ ${heading("Usage")}
   ${color(COLORS.cyan, "npm")}  create daloy@latest ${color(COLORS.dim, "[project-name] [options]")}
   ${color(COLORS.cyan, "yarn")} create daloy       ${color(COLORS.dim, "[project-name] [options]")}
   ${color(COLORS.cyan, "bun")}  create daloy       ${color(COLORS.dim, "[project-name] [options]")}
+  ${color(COLORS.dim, "Use . as the project name to scaffold into the current directory.")}
 
 ${heading("Options")}
   ${color(COLORS.green, "--template <name>")}          ${TEMPLATES.join(" | ")}  ${color(COLORS.dim, "(default: node-basic)")}
@@ -568,7 +569,8 @@ const VALID_CODE_OWNER =
 
 function validateProjectName(name) {
   if (!name || !name.trim()) return "Project name cannot be empty.";
-  if (name === "." || name === "..") return "Use a real directory name.";
+  if (name === ".") return true;
+  if (name === "..") return "Use a real directory name.";
   if (name.length > 214) return "Project name is too long (max 214 chars).";
   if (!VALID_NAME.test(name)) {
     return "Project name must be a valid npm package name (lowercase, no spaces, no leading dot/underscore).";
@@ -576,6 +578,10 @@ function validateProjectName(name) {
   return true;
 }
 
+function projectPackageName(projectName, cwd) {
+  return projectName === "." ? path.basename(cwd).toLowerCase() : projectName;
+}
+
 async function isDirEmpty(dir) {
   try {
     const entries = await readdir(dir);
@@ -1677,7 +1683,7 @@ function createSpinner(initialMessage) {
   };
 }
 
-function printSummary({ projectName, template, packageManager, installDeps, skipPackageManager, withCi, withDeploy, missingTools = [] }) {
+function printSummary({ projectName, shouldChangeDirectory = true, template, packageManager, installDeps, skipPackageManager, withCi, withDeploy, missingTools = [] }) {
   const templateMeta = TEMPLATE_OPTIONS.find((option) => option.value === template);
   const templateLabel = templateMeta ? `${templateMeta.title} ${color(COLORS.dim, `(${template})`)}` : template;
   const summaryLines = [
@@ -1703,7 +1709,9 @@ function printSummary({ projectName, template, packageManager, installDeps, skip
 
   const arrow = color(COLORS.cyan, SYMBOLS.arrow);
   console.log(`${color(COLORS.bold, "Next steps")}`);
-  console.log(`  ${arrow} ${color(COLORS.cyan, `cd ${projectName}`)}`);
+  if (shouldChangeDirectory) {
+    console.log(`  ${arrow} ${color(COLORS.cyan, `cd ${projectName}`)}`);
+  }
   if (skipPackageManager) {
     console.log(`  ${arrow} ${color(COLORS.cyan, "deno task dev")}`);
   } else {
@@ -1835,7 +1843,14 @@ async function main() {
       process.exit(1);
     }
 
-    const targetDir = path.resolve(process.cwd(), projectName);
+    const cwd = process.cwd();
+    const packageName = projectPackageName(projectName, cwd);
+    const packageNameCheck = projectName === "." ? validateProjectName(packageName) : true;
+    if (packageNameCheck !== true) {
+      logError(`Current directory name "${packageName}" cannot be used as a package name. ${packageNameCheck}`);
+      process.exit(1);
+    }
+    const targetDir = projectName === "." ? cwd : path.resolve(cwd, projectName);
     if (existsSync(targetDir)) {
       const empty = await isDirEmpty(targetDir);
       if (!empty && !opts.force) {
@@ -1927,8 +1942,8 @@ async function main() {
       logStep("Minimal mode applied", `${count} file${count === 1 ? "" : "s"} trimmed`);
     }
     if (!skipPackageManager) {
-      await patchPackageJson(targetDir, projectName, packageManager);
-      logStep("Package metadata written", projectName);
+      await patchPackageJson(targetDir, packageName, packageManager);
+      logStep("Package metadata written", packageName);
       await patchTemplateTextFiles(targetDir, packageManager);
       await patchDockerignoreForPackageManager(targetDir, packageManager);
       if (packageManager !== "pnpm") {
@@ -1985,13 +2000,23 @@ async function main() {
         if (tail.trim().length > 0) {
           console.error(color(COLORS.dim, tail));
         }
-        logWarn(`Retry inside ${projectName} with: ${packageManager} install`);
+        logWarn(`Retry inside ${projectName === "." ? "this directory" : projectName} with: ${packageManager} install`);
       } else {
         spinner.stop(`Installed dependencies with ${color(COLORS.cyan, packageManager)}`);
       }
     }
 
-    printSummary({ projectName, template, packageManager, installDeps, skipPackageManager, withCi, withDeploy, missingTools });
+    printSummary({
+      projectName: packageName,
+      shouldChangeDirectory: projectName !== ".",
+      template,
+      packageManager,
+      installDeps,
+      skipPackageManager,
+      withCi,
+      withDeploy,
+      missingTools,
+    });
   } catch (err) {
     rl?.close();
     if (err && err.message === "Cancelled") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-daloy",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.6",
   "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",
@@ -27,7 +27,7 @@
     "openapi"
   ],
   "engines": {
-    "node": ">=24.0.0"
+    "node": "^24.0.0 || >=26.0.0"
   },
   "bin": {
     "create-daloy": "bin/create-daloy.mjs"

package/sbom.cdx.json

@@ -1,25 +1,25 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:1f97437c-9665-5c96-94a2-d8d548acda4b",
+  "serialNumber": "urn:uuid:f43c9f53-eb2b-530b-a5b0-1406b6ec4e9f",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-26T13:41:50.237Z",
+    "timestamp": "2026-07-01T22:47:11.159Z",
     "tools": [
       {
         "vendor": "DaloyJS",
         "name": "daloy-generate-sbom",
-        "version": "1.0.0-beta.4"
+        "version": "1.0.0-beta.6"
       }
     ],
     "authors": [],
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/create-daloy@1.0.0-beta.4",
+      "bom-ref": "pkg:npm/create-daloy@1.0.0-beta.6",
       "name": "create-daloy",
-      "version": "1.0.0-beta.4",
+      "version": "1.0.0-beta.6",
       "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.0.0-beta.4",
+      "purl": "pkg:npm/create-daloy@1.0.0-beta.6",
       "licenses": [
         {
           "license": {
@@ -42,9 +42,9 @@
         }
       ],
       "swid": {
-        "tagId": "swidtag-create-daloy-1.0.0-beta.4",
+        "tagId": "swidtag-create-daloy-1.0.0-beta.6",
         "name": "create-daloy",
-        "version": "1.0.0-beta.4",
+        "version": "1.0.0-beta.6",
         "tagVersion": 0,
         "patch": false
       }
@@ -53,7 +53,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "pkg:npm/create-daloy@1.0.0-beta.4",
+      "ref": "pkg:npm/create-daloy@1.0.0-beta.6",
       "dependsOn": []
     }
   ]

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "create-daloy-1.0.0-beta.4",
-  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-1.0.0-beta.4-1f97437c-9665-5c96-94a2-d8d548acda4b",
+  "name": "create-daloy-1.0.0-beta.6",
+  "documentNamespace": "https://github.com/daloyjs/daloy/sbom/create-daloy-1.0.0-beta.6-f43c9f53-eb2b-530b-a5b0-1406b6ec4e9f",
   "creationInfo": {
-    "created": "2026-06-26T13:41:50.237Z",
+    "created": "2026-07-01T22:47:11.159Z",
     "creators": [
       "Tool: daloy-generate-sbom",
       "Organization: DaloyJS"
@@ -16,7 +16,7 @@
     {
       "SPDXID": "SPDXRef-Package-create-daloy",
       "name": "create-daloy",
-      "versionInfo": "1.0.0-beta.4",
+      "versionInfo": "1.0.0-beta.6",
       "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.0.0-beta.4"
+          "referenceLocator": "pkg:npm/create-daloy@1.0.0-beta.6"
         }
       ]
     }

package/templates/bun-basic/AGENTS.md

@@ -1,9 +1,16 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API for the [Bun](https://bun.sh) 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).
+A [DaloyJS](https://daloyjs.dev) REST API for the [Bun](https://bun.sh) runtime. **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. 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 / runtime: Bun.
 
+## Agent guidance
+
+- Treat this file as the short, durable project contract for AI coding agents.
+- Use `.agents/skills/daloyjs-best-practices/SKILL.md` for the detailed DaloyJS workflow; keep this file concise and do not duplicate that skill.
+- If instructions conflict, follow the user's latest prompt first, then the nearest `AGENTS.md`, then the skill.
+- Change route definitions, schemas, metadata, and tests first; regenerate generated files instead of hand-editing OpenAPI or typed-client output.
+
 ## Commands
 
 - `bun run dev` — hot-reload server on http://localhost:3000
@@ -11,6 +18,8 @@ A [DaloyJS](https://daloyjs.dev) REST API for the [Bun](https://bun.sh) runtime.
 - `bun test` — Bun's native test runner
 - `bun run gen:openapi` — write `generated/openapi.json`
 - `bun run gen:client` — write the typed Hey API client
+- `bun run contract` — run the focused OpenAPI contract test
+- `bun run hooks:install` — enable the optional pre-push contract gate
 - `bun run build` — produce `dist/`
 
 ## Project shape
@@ -34,19 +43,20 @@ Do not write `.js` here — that's the Node NodeNext convention and will fail to
 ## Core rules
 
 1. The route definition is the contract. Method, path, request schemas, and response schemas live in one place — `app.route({...})`.
-2. Validate every input with Zod. Use `.strict()` on top-level object schemas to reject unknown keys at the boundary.
+2. Validate every input with Zod or another Standard Schema-compatible validator. For Zod object schemas, use `.strict()` to reject unknown keys at the boundary.
 3. Preserve literal types in responses: `status: 200 as const`, `z.literal(...)` on discriminator fields. Codegen depends on these.
 4. Throw typed errors (`NotFoundError`, `BadRequestError`, etc.) from `@daloyjs/core` — never return raw error responses.
 5. Keep `requestId()`, `secureHeaders()`, and `rateLimit()` enabled. They are the project's secure defaults.
-6. Every new route ships with a test that covers a happy path and at least one unhappy path.
-7. After any route change: `bun run gen:openapi && bun run gen:client && bun run typecheck && bun test`.
+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`.
 
 ## Secure-by-default (do not let an AI strip these)
 
-Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/blog/supabase-approach-to-secure-by-default-development): *"If you tell an AI to make something work, it might remove the very security checks that protect you."* When a guard rejects a request, **satisfy it, do not delete it.**
+Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/blog/supabase-approach-to-secure-by-default-development): _"If you tell an AI to make something work, it might remove the very security checks that protect you."_ When a guard rejects a request, **satisfy it, do not delete it.**
 
 - Keep `secureHeaders()`, `requestId()`, `rateLimit()` registered, and `bodyLimitBytes` / `requestTimeoutMs` set on `new App({...})`. Tighten per-route; never raise globally to pass a test.
-- 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.
+- Keep Zod `.strict()` on top-level request objects; do not switch to `.passthrough()`. For other validators, use the strict / no-extra-keys equivalent. 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 `timingSafeEqual`, never `===`. Throw typed errors from `@daloyjs/core` so problem+json redacts in prod; never return raw stack traces.
@@ -56,7 +66,7 @@ Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/
 ## Process expectations
 
 - Quality gates must pass before declaring work done: `bun run typecheck` and `bun test`.
-- Regenerate the OpenAPI spec and typed client whenever route shapes change.
+- Regenerate the OpenAPI spec and typed client whenever route shapes change, then run `bun run contract`.
 - Bug fixes include a regression test.
 - Never bypass safety checks without a clear reason.
 

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

@@ -2,10 +2,10 @@
 name: daloyjs-best-practices
 description: >-
   Best practices for building, testing, and hardening this DaloyJS REST API on
-  the Bun runtime. Use when adding or changing HTTP routes, Zod schemas,
-  middleware, or error handling; regenerating the OpenAPI spec or the typed
-  Hey API client; or working on auth, rate limits, secrets, and the project's
-  quality gates.
+  the Bun runtime. Use when adding or changing HTTP routes, Zod/Standard Schema
+  validation schemas, middleware, route metadata, or error handling;
+  regenerating the OpenAPI spec or typed Hey API client; running contract
+  gates; or working on auth, rate limits, secrets, and security defaults.
 license: MIT
 ---
 
@@ -37,8 +37,9 @@ recommendation below follows from them:
    and response schemas live in one place (`app.route({...})`). The OpenAPI
    spec, the typed client, and the runtime validation are all derived from
    it.
-2. **Zod schemas validate at every boundary.** Body, params, query, and
-   headers go through Zod.
+2. **Validation schemas protect every boundary.** This template uses Zod,
+   and Daloy accepts any Standard Schema-compatible library. Body, params,
+   query, and headers go through the declared schema.
 3. **Preserve literal types.** Return `status: 200 as const` and use
    `z.literal(...)` / `as const` on discriminator fields so the typed
    client can narrow responses.
@@ -47,6 +48,9 @@ recommendation below follows from them:
    codegen and tests import `buildApp()` without side effects.
 5. **Secure by default.** `requestId()`, `secureHeaders()`, and
    `rateLimit()` are registered before route definitions.
+6. **Contract gates are part of done.** Keep `operationId` values stable,
+   examples schema-valid, declared error responses accurate, and generated
+   OpenAPI / client artifacts in sync with the live route table.
 
 ## Project shape
 
@@ -69,12 +73,15 @@ bun run typecheck     # tsc --noEmit
 bun test              # Bun's native test runner
 bun run gen:openapi   # write generated/openapi.json
 bun run gen:client    # write generated/client/
+bun run contract      # run the focused contract test
 bun run build         # produce dist/
 ```
 
 Always run `bun run typecheck` and `bun test` before declaring a task done.
-If a change touches route shapes, also rerun `bun run gen:openapi && bun
-run gen:client` so the client stays in sync.
+`bun test` includes the contract gate; if you need a focused contract check,
+run `bun run contract`. If a change touches route shapes, also rerun
+`bun run gen:openapi && bun run gen:client` so the OpenAPI spec and client
+stay in sync.
 
 ## OpenAPI & docs routes
 
@@ -93,6 +100,18 @@ mount only outside production, or `docs: false` to disable all three.
 For hand-rolled mounting, `openapiToYAML` is exported from
 `@daloyjs/core/openapi`.
 
+## AI-ready contract metadata
+
+Daloy can expose route metadata to OpenAPI and agent tooling. Add metadata
+when it helps consumers understand or safely automate the route:
+
+- Use `summary`, `description`, and `tags` for concise human-facing docs.
+- Use `meta.examples` for realistic happy-path and unhappy-path examples.
+  Examples must match the declared schemas; the contract gate rejects drift.
+- Use `meta.extensions` for stable `x-*` fields consumed by internal tools.
+- Use `deprecated` and `sunset` when changing API lifecycle. Do not remove
+  a route or response shape silently if generated clients may depend on it.
+
 ## Workflow: add a new route
 
 1. **Open `src/build-app.ts`.**
@@ -100,7 +119,9 @@ For hand-rolled mounting, `openapiToYAML` is exported from
    response body per status code. Prefer `z.object({...}).strict()` for
    inputs so unknown keys are rejected at the boundary.
 3. **Call `app.route({...})`** with `method`, `path`, `operationId`, `tags`,
-   `responses`, `handler` (plus `request` when accepting input).
+   `responses`, `handler` (plus `request` when accepting input). Add `meta`
+   examples / descriptions when the route is user-facing or consumed by
+   agents.
 4. **Return `{ status, body, headers? }` from the handler.** Always use
    `status: 200 as const` so the typed client can narrow.
 5. **Throw typed errors**, do not return raw error responses. Use
@@ -108,9 +129,10 @@ For hand-rolled mounting, `openapiToYAML` is exported from
    `ForbiddenError`, `ConflictError`, etc.
 6. **Add a test in `tests/<route>.test.ts`** using `app.request(...)` for
    in-process testing — no port needed.
-7. **Regenerate the contract**: `bun run gen:openapi && bun run gen:client`.
+7. **Run the contract gate**: `bun run contract` or `bun test`.
+8. **Regenerate the contract artifacts**: `bun run gen:openapi && bun run gen:client`.
    Inspect `generated/openapi.json` to confirm the operation shows up.
-8. **Run the quality gates**: `bun run typecheck && bun test`.
+9. **Run the quality gates**: `bun run typecheck && bun test`.
 
 ### Example: a typed route
 
@@ -150,6 +172,8 @@ app.route({
   `.nullable()` for "explicitly null". They differ in OpenAPI output.
 - **Pagination**: standardize on `{ items, nextCursor }` cursor pagination.
 - **Discriminated unions**: use `z.discriminatedUnion("kind", [...])`.
+- Keep response examples close to the route definition and schema-valid.
+  The contract test intentionally fails invalid examples.
 - **Never** call `JSON.parse` or read `req.body` directly. Let the
   framework validate and pass the typed object to your handler.
 
@@ -168,8 +192,8 @@ Register middleware **before** route definitions. Order matters.
 Keep the secure baseline:
 
 ```ts
-app.use(requestId());      // x-request-id for log correlation
-app.use(secureHeaders());  // strict security headers
+app.use(requestId()); // x-request-id for log correlation
+app.use(secureHeaders()); // strict security headers
 app.use(rateLimit({ windowMs: 60_000, max: 120 }));
 ```
 
@@ -198,12 +222,18 @@ Cover both **happy paths and unhappy paths** for every route: valid input,
 validation failures (400), auth failures (401/403), not-found (404),
 conflicts (409), rate limiting (429). For external services, inject an
 in-memory fake via `buildApp({ store })` rather than mocking `fetch`.
+The shipped contract test should fail invalid examples, duplicate/missing
+`operationId`, or missing responses.
 
 Aim for **100% line and function coverage** on routes you add.
 
 ## Security best practices
 
 - Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled.
+- Never make a failing test pass by deleting or weakening a security guard.
+  If a guard blocks a legitimate route, add the narrowest per-route
+  override or configuration knob and cover both the allowed and rejected
+  paths in tests.
 - Never log secrets — filter `authorization`, `cookie`, and any
   token-bearing fields.
 - Validate secrets from `process.env` (or `Bun.env`) through a Zod schema
@@ -215,6 +245,9 @@ Aim for **100% line and function coverage** on routes you add.
   mitigate DoS.
 - Use parameterized queries for database access — never interpolate user
   input into SQL.
+- For outbound HTTP, prefer `fetchGuard()` or a transport layered on top
+  of it when URLs can be influenced by users or tenants. SSRF protections
+  should fail closed for private ranges and cloud metadata endpoints.
 - Bun ships its own audit story; check `bun pm audit` periodically and
   pin versions in `bun.lockb`.
 
@@ -236,6 +269,8 @@ Aim for **100% line and function coverage** on routes you add.
 - Never import `@daloyjs/core/bun` from `src/build-app.ts` or any script
   under `scripts/`. That would boot an HTTP listener during codegen.
 - Do not edit files under `generated/` by hand — they are overwritten.
+- Do not hand-edit OpenAPI paths or client types. Fix the route definition,
+  schema, or metadata and regenerate.
 - Do not weaken response literal types (`as const`); the typed client
   depends on them.
 - Do not return errors as `{ status: 4xx, body: {...} }`. Throw a typed
@@ -252,6 +287,8 @@ Aim for **100% line and function coverage** on routes you add.
 - `bun run typecheck` and `bun test` must pass before completion.
 - Run `bun run gen:openapi && bun run gen:client` when route shapes
   change; commit the updated artifacts.
+- When route metadata, examples, lifecycle flags, or operation IDs change,
+  run the contract gate and inspect the relevant generated OpenAPI diff.
 - Keep `README.md`, this `SKILL.md`, and `AGENTS.md` consistent with the
   code.
 

package/templates/bun-basic/package.json

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

package/templates/cloudflare-worker/AGENTS.md

@@ -1,15 +1,24 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) REST API deployed to **Cloudflare Workers**. **Contract-first**: routes are defined with Zod schemas 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 this adds negligible Worker bundle size; drop `docs` (and the `openapi` block) if you want the smallest possible 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`).
 
+## Agent guidance
+
+- Treat this file as the short, durable project contract for AI coding agents.
+- Use `.agents/skills/daloyjs-best-practices/SKILL.md` for the detailed DaloyJS workflow; keep this file concise and do not duplicate that skill.
+- If instructions conflict, follow the user's latest prompt first, then the nearest `AGENTS.md`, then the skill.
+- Change route definitions, schemas, metadata, and tests first; regenerate generated files instead of hand-editing OpenAPI output.
+
 ## Commands
 
 - `pnpm dev` — `wrangler dev` on http://localhost:8787
 - `pnpm typecheck` — `tsc --noEmit`
 - `pnpm test` — run test suite
+- `pnpm contract` — run `daloy inspect --check src/index.ts`
+- `pnpm hooks:install` — enable the optional pre-push contract gate
 - `pnpm deploy` — `wrangler deploy`
 - `pnpm audit` — supply-chain audit
 
@@ -22,31 +31,33 @@ A [DaloyJS](https://daloyjs.dev) REST API deployed to **Cloudflare Workers**. **
 ## Core rules
 
 1. The route definition is the contract. Method, path, request schemas, and response schemas live in one place — `app.route({...})`.
-2. Validate every input with Zod. Use `.strict()` on top-level object schemas to reject unknown keys at the boundary.
+2. Validate every input with Zod or another Standard Schema-compatible validator. For Zod object schemas, use `.strict()` to reject unknown keys at the boundary.
 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 high-traffic routes, attach Cloudflare's native rate-limit binding (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.
-9. Every new route ships with a test that covers a happy path and at least one unhappy path.
+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.
 
 ## Secure-by-default (do not let an AI strip these)
 
-Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/blog/supabase-approach-to-secure-by-default-development): *"If you tell an AI to make something work, it might remove the very security checks that protect you."* When a guard rejects a request, **satisfy it, do not delete it.**
+Per Supabase + Aikido on [secure-by-default development](https://www.aikido.dev/blog/supabase-approach-to-secure-by-default-development): _"If you tell an AI to make something work, it might remove the very security checks that protect you."_ When a guard rejects a request, **satisfy it, do not delete it.**
 
 - Keep `secureHeaders()`, `requestId()`, `rateLimit()` registered, and `bodyLimitBytes` / `requestTimeoutMs` set on `new App({...})`. For production, add Cloudflare's native rate-limit binding **in addition to** the in-memory limiter, not instead of it.
 - Read secrets and bindings (KV, D1, R2) from the `env` argument; never hard-code, never log them.
-- 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.
+- Keep Zod `.strict()` on top-level request objects; do not switch to `.passthrough()`. For other validators, use the strict / no-extra-keys equivalent. 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 constant-time verification, never `===`. Prefer Web Crypto verification APIs or the framework timing-safe helper where available. Throw typed errors from `@daloyjs/core` so problem+json redacts in prod; never return raw stack traces.
 - Keep `compatibility_date` pinned; do not enable `nodejs_compat` unless a feature requires it.
 - `.env`, `.dev.vars`, secrets, private keys: never commit. Use `wrangler secret put` for production secrets.
 
 ## Process expectations
 
 - Quality gates must pass before declaring work done: `pnpm typecheck` and `pnpm test`.
+- Run the contract gate (`pnpm contract`) whenever route shapes, examples, operation IDs, or OpenAPI metadata change.
 - Bug fixes include a regression test.
 - Pin `compatibility_date` in `wrangler.toml`; only bump it deliberately.
 - For deploys, ensure the user has run `wrangler login`; do not authenticate on their behalf.