create-daloy 0.1.18 → 0.1.20

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

@@ -0,0 +1,236 @@
+# SKILL.md — DaloyJS best practices (Cloudflare Workers)
+
+Operational guidance and best practices for AI coding agents working in this
+DaloyJS **Cloudflare Workers** 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.
+
+## When to use this skill
+
+Use this skill when you need to:
+
+- Add, modify, or remove HTTP routes in this Worker.
+- Adjust middleware, validation, or error handling.
+- Change Worker bindings (KV, D1, R2, Queues, env vars) in `wrangler.toml`.
+- Run tests/typecheck or deploy the Worker.
+- 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 Workers, additionally:
+
+1. **Stay on the Workers runtime.** Only Web Standards APIs and
+   Cloudflare-specific bindings. No `node:` modules unless
+   `nodejs_compat` is enabled in `wrangler.toml` and the user explicitly
+   opts in.
+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.**
+4. **Preserve literal types.** Return `status: 200 as const`.
+5. **Secure by default.** `requestId()`, `secureHeaders()`, and
+   `rateLimit()` are registered. Note: the in-memory rate limiter resets
+   per isolate — for production traffic, prefer Cloudflare's native
+   rate-limit binding.
+6. **Bindings flow through `env`.** Read KV/D1/R2/secrets from the
+   `env` argument to `fetch`, never from globals.
+
+## Project shape
+
+- `src/index.ts` — the Worker entrypoint. Builds the `App`, registers
+  routes/middleware, and exports `default { fetch: toFetchHandler(app) }`
+  from `@daloyjs/core/cloudflare`.
+- `wrangler.toml` — Worker config (name, compatibility date, bindings,
+  routes).
+- `tests/` — test files using Workers-compatible test runners (e.g.
+  `vitest` + `@cloudflare/vitest-pool-workers`) or in-process
+  `app.request(...)` for pure logic.
+
+## Commands cheat-sheet
+
+```bash
+pnpm dev          # wrangler dev on http://localhost:8787
+pnpm typecheck    # tsc --noEmit
+pnpm test         # run test suite
+pnpm deploy       # wrangler deploy
+pnpm audit        # supply-chain audit
+```
+
+Always run `pnpm typecheck` and `pnpm test` before declaring a task done.
+
+## Workflow: add a new route
+
+1. **Open `src/index.ts`.**
+2. **Design schemas first.** Use `z.object({...}).strict()` for inputs.
+3. **Call `app.route({...})`** with `method`, `path`, `operationId`,
+   `tags`, `responses`, `handler` (plus `request` when accepting input).
+4. **Return `{ status, body, headers? }`** with `status: 200 as const`.
+5. **Throw typed errors** (`NotFoundError`, `BadRequestError`, etc.).
+6. **Add a test** under `tests/`. Use `app.request(...)` for pure logic;
+   use `unstable_dev` (Wrangler) or `@cloudflare/vitest-pool-workers`
+   when you need bindings.
+7. **Run the quality gates**: `pnpm typecheck && pnpm test`.
+
+### Example: a typed route with bindings
+
+```ts
+import { z } from "zod";
+import { App, NotFoundError, rateLimit, requestId, secureHeaders } from "@daloyjs/core";
+import { toFetchHandler } from "@daloyjs/core/cloudflare";
+
+interface Env {
+  BOOKS: KVNamespace;
+  JWT_SECRET: string;
+}
+
+const Book = z.object({ id: z.string(), title: z.string() }).strict();
+
+function buildApp(env: Env) {
+  const app = new App({ bodyLimitBytes: 1024 * 1024, requestTimeoutMs: 5_000 });
+  app.use(requestId());
+  app.use(secureHeaders());
+  app.use(rateLimit({ windowMs: 60_000, max: 120 }));
+
+  app.route({
+    method: "GET",
+    path: "/books/:id",
+    operationId: "getBookById",
+    tags: ["Books"],
+    request: { params: z.object({ id: z.string().min(1) }).strict() },
+    responses: {
+      200: { description: "Found", body: Book },
+      404: { description: "Not found" },
+    },
+    handler: async ({ params }) => {
+      const raw = await env.BOOKS.get(params.id, "json");
+      if (!raw) throw new NotFoundError(`Book ${params.id} not found`);
+      return { status: 200 as const, body: Book.parse(raw) };
+    },
+  });
+
+  return app;
+}
+
+export default {
+  fetch: (req: Request, env: Env, ctx: ExecutionContext) =>
+    toFetchHandler(buildApp(env))(req, env, ctx),
+};
+```
+
+## Validation & schema conventions
+
+- **Inputs**: use `.strict()` on top-level object schemas.
+- **IDs**: prefer `z.string().min(1)`; use `z.string().uuid()` when
+  applicable.
+- **Numbers from query strings**: `z.coerce.number().int().min(...)`.
+- **Optional vs nullable**: differ in OpenAPI output.
+- **Pagination**: standardize on `{ items, nextCursor }` cursor
+  pagination.
+- **Discriminated unions**: `z.discriminatedUnion("kind", [...])`.
+
+## Error handling
+
+- Throw typed errors from `@daloyjs/core` — they serialize to RFC 7807
+  problem responses.
+- Add a `responses[code]` entry for every error you throw.
+- For unexpected errors, let them bubble. The framework's error
+  middleware converts them to a 500 problem response.
+
+## Middleware
+
+Register middleware **before** route definitions. Order matters.
+
+Keep the secure baseline (`requestId`, `secureHeaders`, `rateLimit`).
+Add CORS only when needed, with an explicit `origin` allowlist.
+
+## Working with bindings
+
+1. Add the binding (`[[kv_namespaces]]`, `[[d1_databases]]`, `[vars]`,
+   etc.) to `wrangler.toml`.
+2. Type the binding in the `Env` interface inside `src/index.ts`.
+3. Pass `env` into `buildApp(env)` so handlers receive bindings via
+   closure or factory argument. **Never read bindings via globals.**
+4. Store secrets via `wrangler secret put` — they appear on `env` but
+   are not committed to `wrangler.toml`.
+
+## Testing best practices
+
+Two patterns:
+
+- **In-process** with `app.request(...)` for pure logic that does not
+  need bindings.
+- **Workers-aware** runners (`@cloudflare/vitest-pool-workers` or
+  Wrangler `unstable_dev`) when KV/D1/etc. are involved.
+
+Cover **happy paths and unhappy paths** for every route: valid input,
+validation failures (400), auth failures (401/403), not-found (404),
+conflict (409), rate limiting (429). For external services, inject an
+in-memory fake into `buildApp(env)` during tests.
+
+Aim for **100% line and function coverage** on the routes you add.
+
+## Security best practices
+
+- Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled. For
+  high-traffic routes, attach Cloudflare's native rate-limit binding so
+  limits are shared across isolates.
+- Never log secrets — filter `authorization`, `cookie`, etc.
+- Read secrets via `wrangler secret put`, never via plain `[vars]` in
+  `wrangler.toml`.
+- For auth, verify JWT signatures with the Web Crypto API
+  (`crypto.subtle`). Never trust the `alg` header from the token.
+- Validate redirects against an allowlist.
+- Set `bodyLimitBytes` and `requestTimeoutMs` on `new App({...})` to
+  mitigate DoS.
+- Workers have CPU and bundle-size limits; be cautious about adding
+  heavy dependencies. Run `wrangler deploy --dry-run --outdir=dist` to
+  inspect bundle size.
+- Use `ctx.waitUntil(...)` for fire-and-forget work so the response
+  returns promptly.
+- Pin a `compatibility_date` in `wrangler.toml` and only bump it
+  deliberately. New compat flags can change runtime semantics.
+
+## Logging & observability
+
+- Use `ctx.log` — it carries the request id.
+- `console.log` in Workers shows up in `wrangler tail`. Prefer
+  structured logs through the framework logger.
+- For tracing, the `tracing()` middleware emits OpenTelemetry-compatible
+  spans; wire up a Workers-friendly exporter when needed.
+
+## Configuration & secrets
+
+- Centralize env shape in an `Env` interface.
+- Validate env via Zod once per request (cheap with Workers) or on first
+  access via a memoized helper.
+- Treat env as immutable during a request.
+
+## Pitfalls and guardrails
+
+- Use `toFetchHandler(app)` from `@daloyjs/core/cloudflare` — never
+  hand-roll a `fetch(req, env, ctx)` adapter.
+- Do not import `@daloyjs/core/node`, `@daloyjs/core/bun`, etc. — only
+  `@daloyjs/core` and `@daloyjs/core/cloudflare`.
+- Avoid Node-only APIs (`Buffer`, `fs`, `process` beyond
+  `process.env`) unless `nodejs_compat` is enabled and required.
+- 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).
+- Long-running work belongs in `ctx.waitUntil(...)`, not blocking the
+  response.
+
+## Process expectations
+
+- Every new feature ships with happy-path and unhappy-path tests.
+- Bug fixes include a regression test.
+- `pnpm typecheck` and `pnpm test` must pass before completion.
+- For deploys, ask the user to run `wrangler login` first if needed —
+  do not attempt to authenticate on their behalf.
+- Keep `README.md`, this `SKILL.md`, and `AGENTS.md` consistent.
+
+## More
+
+- Framework docs: <https://daloyjs.dev/docs>
+- Issues: <https://github.com/daloyjs/daloy/issues>

package/templates/deno-basic/AGENTS.md

@@ -1,8 +1,8 @@
 # AGENTS.md
 
-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.
+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.
 
-- Runtime: Deno (no Node package manager). Dependencies are loaded via `npm:` specifiers in `deno.json`.
+- Runtime: Deno (no Node package manager). Dependencies are loaded via `npm:` and `jsr:` specifiers in `deno.json`.
 
 ## Commands
 
@@ -11,12 +11,33 @@ A [DaloyJS](https://daloyjs.dev) REST API for the [Deno](https://deno.com) runti
 - `deno task test`
 - `deno task gen:openapi` — write `generated/openapi.json`
 
-The typed Hey API SDK is generated outside Deno (Hey API has no Deno entrypoint yet). Run `npx @hey-api/openapi-ts` against `generated/openapi.json` if you need the client.
+The typed Hey API SDK is generated outside Deno (Hey API has no Deno entrypoint yet). Run `npx @hey-api/openapi-ts -i generated/openapi.json -o generated/client` if you need the client.
 
-## Structure hints
+## Project shape
 
-- Route + middleware wiring lives in `src/build-app.ts` (`buildApp()` factory; pure, no side effects).
-- The HTTP listener is started in `src/main.ts` via `@daloyjs/core/deno`.
-- Codegen reads from `buildApp()` only — never import `src/main.ts` from scripts.
+- `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.
+- `generated/` — machine-written. Do not edit by hand.
+- `tests/` — Deno test files.
 
-For workflows (adding routes, regenerating the spec, common pitfalls) see [SKILL.md](SKILL.md).
+## 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.
+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.
+6. Deno permissions are part of the contract — keep `--allow-net --allow-env --allow-read` narrow; never use `--allow-all`.
+7. Every new route ships with a test that covers a happy path and at least one unhappy path.
+8. After any route change: `deno task gen:openapi && deno task typecheck && deno task test`.
+
+## Process expectations
+
+- Quality gates must pass before declaring work done: `deno task typecheck` and `deno task test`.
+- Regenerate the OpenAPI spec whenever route shapes change.
+- Bug fixes include a regression test.
+- Use `deno task ...`, not `npm`/`pnpm`. There is no `package.json` here.
+
+For the full workflow — adding routes step-by-step, schema conventions, testing patterns, security guidance, and deployment notes — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).

package/templates/deno-basic/README.md

@@ -44,7 +44,7 @@ deno task test
 ## What's included
 
 - `@daloyjs/core` (loaded via `npm:` specifiers in `deno.json`).
-- `secureHeaders`, `requestId`, and `rateLimit` enabled by default.
+- 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 -->

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

@@ -0,0 +1,225 @@
+# SKILL.md — DaloyJS best practices (Deno)
+
+Operational guidance and best practices for AI coding agents working in this
+DaloyJS [Deno](https://deno.com) 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.
+
+## When to use this skill
+
+Use this skill when you need to:
+
+- Add, modify, or remove HTTP routes in this project.
+- Regenerate the OpenAPI spec.
+- Wire up new middleware, validation, or error handling.
+- Add or update tests, run typecheck, or build the project.
+- Harden the API (auth, CORS, rate limits, permissions, secrets).
+
+Do **not** use this skill for tasks unrelated to the API itself.
+
+## Core principles
+
+DaloyJS is a **contract-first** framework. Internalize these rules:
+
+1. **The route definition is the contract.** Method, path, request schemas,
+   and response schemas live in one place (`app.route({...})`).
+2. **Zod schemas validate at every boundary.**
+3. **Preserve literal types.** Return `status: 200 as const`; use
+   `z.literal(...)` / `as const` on discriminator fields.
+4. **`buildApp()` is pure.** Construction never opens sockets. The HTTP
+   listener lives in `src/main.ts` via `@daloyjs/core/deno`.
+5. **Secure by default.** `requestId()`, `secureHeaders()`, and
+   `rateLimit()` are registered before route definitions.
+6. **Deno permissions are part of the contract.** Tasks declare exactly
+   the permissions they need (`--allow-net`, `--allow-env`, `--allow-read`).
+   Do not broaden them casually.
+
+## Project shape
+
+- `src/build-app.ts` — exports `buildApp()`. All routes and middleware
+  registered here. **Pure factory.**
+- `src/main.ts` — calls `buildApp()` and starts the Deno HTTP listener via
+  `@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
+  `package.json`** in this project — do not add one.
+- `tests/` — Deno test files (`*.test.ts`).
+- `generated/` — **machine-written**. Never edit by hand.
+
+## Commands cheat-sheet
+
+```bash
+deno task dev           # watch-mode server on http://localhost:3000
+deno task typecheck     # deno check
+deno task test          # deno test
+deno task gen:openapi   # write generated/openapi.json
+```
+
+The typed Hey API SDK is generated outside Deno today (Hey API has no
+Deno entrypoint yet). To produce the client, run:
+
+```bash
+npx @hey-api/openapi-ts -i generated/openapi.json -o generated/client
+```
+
+Always run `deno task typecheck` and `deno task test` before declaring a
+task done.
+
+## Workflow: add a new route
+
+1. **Open `src/build-app.ts`.**
+2. **Design schemas first.** Define request body/params/query/headers and a
+   response body per status code. Prefer `z.object({...}).strict()` for
+   inputs.
+3. **Call `app.route({...})`** with `method`, `path`, `operationId`,
+   `tags`, `responses`, `handler` (plus `request` when accepting input).
+4. **Return `{ status, body, headers? }` from the handler.** Always
+   `status: 200 as const`.
+5. **Throw typed errors** (`NotFoundError`, `BadRequestError`, etc.) from
+   `@daloyjs/core`.
+6. **Add a test in `tests/<route>.test.ts`** using `app.request(...)` for
+   in-process tests.
+7. **Regenerate the contract**: `deno task gen:openapi`.
+8. **Run the quality gates**: `deno task typecheck && deno task test`.
+
+### Example: a typed route
+
+```ts
+import { z } from "zod";
+import { NotFoundError } from "@daloyjs/core";
+
+const Book = z.object({ id: z.string(), title: z.string() }).strict();
+const BookParams = z.object({ id: z.string().min(1) }).strict();
+
+app.route({
+  method: "GET",
+  path: "/books/:id",
+  operationId: "getBookById",
+  tags: ["Books"],
+  request: { params: BookParams },
+  responses: {
+    200: { description: "Found", body: Book },
+    404: { description: "Not found" },
+  },
+  handler: async ({ params }) => {
+    const book = await store.find(params.id);
+    if (!book) throw new NotFoundError(`Book ${params.id} not found`);
+    return { status: 200 as const, body: book };
+  },
+});
+```
+
+## Validation & schema conventions
+
+- **Inputs**: use `.strict()` on top-level object schemas.
+- **IDs**: prefer `z.string().min(1)`; use `z.string().uuid()` or
+  `z.string().regex(...)` when shape is known.
+- **Numbers from query strings**: `z.coerce.number().int().min(...)`.
+- **Optional vs nullable**: `.optional()` ≠ `.nullable()` in OpenAPI.
+- **Pagination**: standardize on `{ items, nextCursor }` cursor
+  pagination.
+- **Discriminated unions**: `z.discriminatedUnion("kind", [...])`.
+- **Never** parse `req.body` directly — let the framework validate.
+
+## Error handling
+
+- Throw typed errors from `@daloyjs/core` — they serialize to RFC 7807
+  problem responses.
+- Add a `responses[code]` entry for every error you throw.
+- Do not swallow errors. Log via `ctx.log.error(...)` and rethrow.
+
+## Middleware
+
+Register middleware **before** route definitions. Order matters.
+
+Keep the secure baseline:
+
+```ts
+app.use(requestId());
+app.use(secureHeaders());
+app.use(rateLimit({ windowMs: 60_000, max: 120 }));
+```
+
+Add CORS only when needed, with an explicit `origin` allowlist.
+
+## Testing best practices
+
+Tests run with `deno test`. Use **in-process** `app.request()` — no port
+needed.
+
+```ts
+import { assertEquals } from "jsr:@std/assert";
+import { buildApp } from "../src/build-app.ts";
+
+Deno.test("GET /healthz returns ok", async () => {
+  const app = buildApp();
+  const res = await app.request("/healthz");
+  assertEquals(res.status, 200);
+  const body = await res.json();
+  assertEquals(body.ok, true);
+});
+```
+
+Cover **happy paths and unhappy paths**: valid input, validation failures
+(400), auth failures (401/403), not-found (404), conflict (409), rate
+limiting (429). For external services, inject an in-memory fake via
+`buildApp({ store })`.
+
+Aim for **100% line and function coverage** on routes you add.
+
+## Security best practices
+
+- Keep `secureHeaders()`, `requestId()`, and `rateLimit()` enabled.
+- Permissions for the `dev` task are intentionally narrow: `--allow-net
+  --allow-env --allow-read`. If a change requires more permissions, add
+  them explicitly to the relevant task in `deno.json` and call it out to
+  the user — never `--allow-all`.
+- Never log secrets — filter `authorization`, `cookie`, etc.
+- Validate env via Zod at boot (`Deno.env.toObject()`). Fail fast on
+  missing config.
+- For auth, verify JWT signatures against an allowlist of keys, never
+  trust the `alg` header, always check `exp` / `nbf`.
+- Validate redirects against an allowlist.
+- Set `bodyLimitBytes` and `requestTimeoutMs` on `new App({...})` to
+  mitigate DoS.
+- Pin `npm:` and `jsr:` specifiers in `deno.json` to exact or
+  caret-locked versions; review changes in `deno.lock` before committing.
+
+## Logging & observability
+
+- Use `ctx.log` — it carries the request id.
+- Avoid `console.log` in production code paths.
+
+## Configuration & secrets
+
+- Centralize config parsing (e.g. `src/config.ts`) validated by Zod.
+- Read from `Deno.env`; do not introduce a `package.json` or dotenv
+  shim.
+
+## Pitfalls and guardrails
+
+- Never import `@daloyjs/core/deno` from `src/build-app.ts` or any
+  script under `scripts/`. That would boot a listener during codegen.
+- Do not edit files under `generated/` by hand.
+- Do not weaken response literal types (`as const`).
+- Do not return errors as `{ status: 4xx, body }`. Throw a typed error.
+- Use `deno task ...`, not `npm`/`pnpm`. There is no `package.json`.
+- If you need a new dependency, add it to `imports` in `deno.json` via
+  `npm:` or `jsr:` specifiers; do not introduce a `package.json`.
+
+## Process expectations
+
+- Every new feature ships with happy-path and unhappy-path tests.
+- Bug fixes include a regression test.
+- `deno task typecheck` and `deno task test` must pass before completion.
+- Run `deno task gen:openapi` when route shapes change; commit the
+  updated `generated/openapi.json`.
+- Keep `README.md`, this `SKILL.md`, and `AGENTS.md` consistent with the
+  code.
+
+## More
+
+- Framework docs: <https://daloyjs.dev/docs>
+- Issues: <https://github.com/daloyjs/daloy/issues>

package/templates/node-basic/AGENTS.md

@@ -1,6 +1,7 @@
 # AGENTS.md
 
-A [DaloyJS](https://daloyjs.dev) Node.js REST API. Contract-first: routes are defined with Zod schemas and OpenAPI 3.1 is generated from them.
+A [DaloyJS](https://daloyjs.dev) Node.js REST API. **Contract-first**:
+routes are defined with Zod schemas and OpenAPI 3.1 is generated from them.
 
 - Package manager: pnpm (use `pnpm` unless the project's `package.json` was rewritten for npm/yarn/bun).
 - Runtime: Node.js >= 20.10.
@@ -12,11 +13,31 @@ A [DaloyJS](https://daloyjs.dev) Node.js REST API. Contract-first: routes are de
 - `pnpm test` — Node built-in test runner
 - `pnpm gen` — regenerate `generated/openapi.json` and the typed Hey API client
 - `pnpm build` — emit `dist/`
+- `pnpm audit` — supply-chain audit (respects the hardened `.npmrc`)
 
-## Structure hints
+## Project shape
 
-- Route + middleware wiring lives in `src/build-app.ts` (`buildApp()` factory; pure, no side effects).
-- The HTTP listener is started in `src/index.ts` via `@daloyjs/core/node`.
-- Codegen reads from `buildApp()` only — never import `src/index.ts` from scripts.
+- `src/build-app.ts` — `buildApp()` factory. Routes, schemas, and middleware live here. **Pure, no side effects.**
+- `src/index.ts` — calls `buildApp()` and starts the listener via `@daloyjs/core/node`. 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/index.ts` from scripts.
+- `generated/` — machine-written by `pnpm gen`. Do not edit by hand.
+- `tests/` — `*.test.ts` files run with `node --test` (via `tsx`).
 
-For workflows (adding routes, regenerating the SDK, common pitfalls) see [SKILL.md](SKILL.md).
+## 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.
+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: `pnpm gen && pnpm typecheck && pnpm test`.
+
+## Process expectations
+
+- Quality gates must pass before declaring work done: `pnpm typecheck` and `pnpm test`.
+- Update the OpenAPI spec and typed client whenever route shapes change (`pnpm gen`).
+- Bug fixes include a regression test.
+- Never bypass safety checks (`--no-verify`, `--ignore-scripts=false`) without a clear reason.
+
+For the full workflow — adding routes step-by-step, schema conventions, testing patterns, security guidance, and deployment notes — read [.agents/skills/daloyjs-best-practices/SKILL.md](.agents/skills/daloyjs-best-practices/SKILL.md).

package/templates/node-basic/README.md

@@ -44,7 +44,7 @@ node dist/index.js
 
 ## What's included
 
-- `@daloyjs/core` with `secureHeaders`, `requestId`, and `rateLimit` enabled.
+- `@daloyjs/core` with starter security middleware: `secureHeaders`, `requestId`, and `rateLimit`.
 <!-- daloy-minimal:strip-start books -->
 - A health route and a contract-first `/books/:id` route with Zod validation.
 <!-- daloy-minimal:strip-end books -->