create-pracht 0.4.1 → 0.5.0

package/README.md

@@ -17,10 +17,15 @@ npm run dev
 - Detects the active package manager from the current environment.
 - Lets the user choose between the Node.js, Cloudflare, and Vercel adapters.
 - Optionally wires up Tailwind CSS (`tailwindcss` + `@tailwindcss/vite`, a global stylesheet, and the shell import).
-- Scaffolds a minimal app with a route manifest or pages router, shell, home route, sample API route, runnable project README, and agent instructions.
+- Scaffolds a minimal app with a route manifest or pages router, shell, home route, not-found page, sample API route, runnable project README, TypeScript typecheck script, and (with agent tooling enabled) agent instructions.
 - Manifest scaffolds include a commented-out `constraints` example in `src/routes.ts`, ready for `pracht verify`.
 - The generated `.gitignore` keeps `.pracht/app-graph.json` committable, and the README and agent instructions cover the `pracht verify` / `pracht plan` / `pracht report` loop.
-- Seeds the pracht Claude Code skills into `.claude/skills/` and writes a `.mcp.json` registering the `pracht mcp` server (yes-default prompt; skipped with `--no-agent-tools`).
+- Every standalone pnpm scaffold includes a narrow lifecycle-script policy for
+  its required native dependencies in `pnpm-workspace.yaml`:
+  `onlyBuiltDependencies` for pnpm 10 or `allowBuilds` for pnpm 11. All adapters
+  allow `esbuild`, Cloudflare also allows `workerd`, and Tailwind starters also
+  allow `@tailwindcss/oxide`.
+- Seeds the pracht Claude Code skills into `.claude/skills/`, writes a `.mcp.json` registering the `pracht mcp` server, and writes `AGENTS.md` (yes-default prompt; all of it skipped with `--no-agent-tools`, which leaves a project with no agent files at all).
 - Initializes a git repository with an initial commit (skipped with `--no-git`, when git is unavailable, or when the target is already inside a repository).
 - `--dry-run` uses pinned fallback versions and does not require npm registry access.
 
@@ -30,17 +35,18 @@ npm run dev
 node ./packages/start/bin/create-pracht.js
 node ./packages/start/bin/create-pracht.js my-app --adapter=node --skip-install
 node ./packages/start/bin/create-pracht.js my-app --adapter=vercel --skip-install
+node ./packages/start/bin/create-pracht.js my-app --adapter=netlify --skip-install
 node ./packages/start/bin/create-pracht.js my-app --template=tailwind --yes
 node ./packages/start/bin/create-pracht.js my-app --adapter=node --no-tailwind --no-git --yes
 ```
 
 ## Options
 
-- `--adapter=node|cf|vercel` — choose the hosting adapter (default: node).
+- `--adapter=node|cf|netlify|vercel` — choose the hosting adapter (default: node).
 - `--router=manifest|pages` — choose the routing system (default: manifest).
 - `--template=minimal|tailwind` — non-interactive template selection; `minimal` is the default output, `tailwind` is minimal plus Tailwind CSS wiring.
 - `--tailwind` / `--no-tailwind` — enable or disable Tailwind CSS without going through the prompt.
-- `--agent-tools` / `--no-agent-tools` — seed the Claude Code skills and `.mcp.json` (or skip them) without going through the prompt.
+- `--agent-tools` / `--no-agent-tools` — seed the Claude Code skills, `.mcp.json`, and `AGENTS.md`/`CLAUDE.md` (or skip all of them) without going through the prompt.
 - `--no-git` — skip `git init` and the initial commit.
 - `--skip-install` — skip dependency installation.
 - `--yes`, `-y` — accept defaults (node adapter, manifest router, no Tailwind, agent tooling on) and skip all prompts.
@@ -53,11 +59,14 @@ node ./packages/start/bin/create-pracht.js my-app --adapter=node --no-tailwind -
 - `vite.config.ts`
 - `src/routes.ts`
 - `src/routes/home.tsx`
+- `src/routes/not-found.tsx` — the app's 404 page, wired via `notFound` in the manifest (pages scaffolds get `src/pages/404.tsx`, which pracht wires automatically)
 - `src/shells/public.tsx`
 - `src/api/health.ts`
 - `.gitignore`
 - `.claude/skills/<name>/SKILL.md` — the pracht agent skills (unless `--no-agent-tools`)
 - `.mcp.json` — registers the `pracht mcp` server for MCP clients (unless `--no-agent-tools`)
+- `AGENTS.md` (plus a `CLAUDE.md` symlink pointing at it) — project conventions for coding
+  agents (unless `--no-agent-tools`; `README.md` documents the same commands for humans)
 
 The skills are copied from the repo's [skills/](../../skills/README.md) directory into this
 package at build/publish time (`scripts/sync-skills.js`), so the published npm tarball is
@@ -76,10 +85,17 @@ Cloudflare scaffolds also include:
 
 - `wrangler.jsonc`
 
+Standalone pnpm scaffolds for every adapter include `pnpm-workspace.yaml` with
+the version-appropriate lifecycle policy. When the new app belongs to an
+ancestor pnpm workspace, that workspace owns the policy instead: the generated
+README and completion message list the exact entries to add and no nested
+workspace file is created.
+
 ## Generated Scripts
 
 - `dev` -> `pracht dev`
 - `build` -> `pracht build`
+- `typecheck` -> `tsc --noEmit`
 
 Node starters also include:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pracht",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Interactive and scriptable starter CLI for creating full-stack Preact apps with Pracht.",
   "keywords": [
     "pracht",

package/skills/audit-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit-auth
-version: 1.1.0
+version: 1.2.3
 description: |
   Find pracht routes that look protected but aren't — missing auth middleware,
   middleware that augments context but never gates, client-side auth checks
@@ -91,9 +91,36 @@ target. From `pracht inspect api --json`:
   serves ALL methods but reports `methods: []` — treat
   `hasDefaultHandler: true` as "every method exposed". On older CLIs where
   the field is missing, grep the handler file for `export default` instead.
-- For each mutation handler (named method export or default handler), check
-  whether `defineApp({ api: { middleware } })` applies a Gate, OR the handler
-  reads/validates a session itself.
+- For each mutation handler (named method export or default handler) and each
+  HTTP- or remote-MCP-exposed capability, check whether
+  `defineApp({ api: { middleware } })` applies a Gate, OR the handler/capability
+  reads and validates a session itself. App-level API middleware wraps generated
+  capability endpoints before capability-specific middleware.
+- For remote MCP, cookie-bearing transport requests are rejected before
+  capability dispatch and only `Authorization` is forwarded. Flag MCP-exposed
+  capabilities whose gate depends on a browser session cookie or a custom
+  credential header that the projection does not carry.
+- Treat `context.agent` as framework-owned, read-only verified identity. Flag
+  middleware or capability code that attempts to mutate or replace it instead
+  of deriving application authorization state on a separate context field.
+- When a custom adapter supplies a frozen or sealed context, flag authorization
+  helpers that read `agent` or middleware-added fields through `this`. The
+  framework binds private-field methods to the immutable source receiver, which
+  cannot observe fields added on its extensible overlay. Callable fields keep
+  their own API and arrays keep their brand. Application-defined
+  `Symbol.toStringTag` branding does not affect whether an ordinary context can
+  be overlaid, but immutable native built-ins such as `Map` and `Date` fail
+  closed because an overlay cannot preserve their internal slots. Use a fresh
+  mutable wrapper when a context needs native built-ins or when receiver-bound
+  helpers depend on request state.
+- Inspect every HTTP-, WebMCP-, or MCP-exposed capability body for
+  `invokeCapability()`. Direct composition never re-applies app-level API
+  middleware. Remote MCP additionally re-applies the callee's `agentPolicy`
+  and refuses destructive callees, but private non-destructive capabilities
+  stay composable and rely on their named middleware for authorization. For
+  HTTP/WebMCP composition, flag sensitive callees whose required transport
+  authorization or approval is absent from the composing capability and the
+  callee's named middleware.
 - Common bug: dashboard route is protected by middleware, but
   `POST /api/items` is not — attacker bypasses the UI entirely.
 
@@ -140,5 +167,10 @@ Severity is the primary scale; the verdict is a secondary domain label:
 4. Public routes deliberately exposed (login, signup, marketing) should be
    listed but not flagged.
 5. Do not auto-add middleware. Auth wiring is policy.
+6. Treat allowed composed capability reachability as transitive. MCP blocks
+   destructive callees and re-applies `agentPolicy`; named middleware remains
+   the authorization seam for private non-destructive composition. Audit events
+   identify every nested attempt with `transport: "server"` and trusted request
+   provenance in `via`, but observability is not an authorization gate.
 
 $ARGUMENTS

package/skills/audit-csrf/SKILL.md

@@ -128,7 +128,8 @@ The canonical shape is in `recipes-auth.md` (the `origin-check.ts` example).
 
 Verify the wiring: the middleware name must appear in
 `defineApp({ api: { middleware: [...] } })` — that single global list applies
-to every API route. There is no per-group API middleware, and
+to every API route and generated capability HTTP endpoint. There is no
+per-group API middleware, and
 `pracht inspect api --json` output has no middleware field, so the manifest is
 the only place to check.
 

package/skills/audit-secrets/SKILL.md

@@ -115,6 +115,12 @@ Check for accidental exposure outside loaders:
   intentionally public, so flag client-side `VITE_*` references unless they are
   explicitly allowlisted and reviewed. Warn loudly if a public env name has a
   secret-shaped name.
+- Flag any client-side read of `import.meta.env` that is not a single-key
+  access — a bare reference, destructuring, a spread, or bracket access such as
+  `const env = import.meta.env` or `import.meta.env["MODE"]`. Vite replaces
+  those with an object literal holding **every** exposed variable, so the
+  `VITE_*` values land in the bundle with no accessor text left for a
+  name-based grep to find. Use `publicEnv` to enumerate public values.
 - Confirm server-side env access uses `serverEnv` (from
   `@pracht/core/env/server`) or `context.env` rather than ad-hoc globals.
 

package/skills/configure-isg/SKILL.md

@@ -62,12 +62,18 @@ route("/pricing", () => import("./routes/pricing.tsx"), {
 - `revalidate` accepts one policy or an array (`RouteRevalidate`); the array
   above means "hourly, or sooner when a webhook names this path".
 
-**Pages router caveat:** `export const RENDER_MODE = "isg"` exists, but there
-is no `REVALIDATE` page constant — the pages scanner only extracts
-`RENDER_MODE` and `HYDRATION`, so pages-router ISG routes are frozen
-build-time snapshots. To attach a policy, eject to an explicit manifest with
-`generateRoutesFile` from `@pracht/vite-plugin/pages-router` (see
-docs/ROUTING.md "Ejecting to Explicit Manifest") and edit the generated route.
+**Pages router:** time-based ISG is expressed with two static page exports:
+
+```ts
+export const RENDER_MODE = "isg";
+export const REVALIDATE = 3600;
+```
+
+`REVALIDATE` must be a positive integer literal number of seconds. Build,
+`doctor`, and `verify` reject a missing or misplaced policy. Pages mode does
+not accept policies on `_app` or `404`, and fenced Markdown/MDX examples are
+ignored. It does not support webhook or combined policies; eject with `generateRoutesFile`
+from `@pracht/vite-plugin/pages-router` for those.
 
 For dynamic routes, `getStaticPaths()` enumerates the prerendered params.
 Paths it did not enumerate render per-request without a cached copy, and
@@ -89,9 +95,11 @@ curl -X POST https://example.com/__pracht/revalidate \
   or wrong. Providers that can't send bearer auth may use the
   `x-pracht-revalidate-token` header instead.
 - Body: `paths` array, max 64 entries (else `400`). Response reports
-  `revalidated` / `skipped` / `failed` arrays; failed paths keep serving the
-  previous copy. Regeneration is single-flighted per path and never replays
-  the caller's cookies/auth headers.
+  `revalidated` / `skipped` / `failed` arrays plus a `details` array naming why
+  each path was skipped (`not_a_route`, `not_isg`, `not_prerendered`,
+  `no_webhook_policy`) or failed — check `details` first when a webhook appears
+  to do nothing. Failed paths keep serving the previous copy. Regeneration is
+  single-flighted per path and never replays the caller's cookies/auth headers.
 
 ## Step 4: Adapter mechanics
 
@@ -100,7 +108,7 @@ curl -X POST https://example.com/__pracht/revalidate \
 | Node | File mtime vs window; serves stale, refreshes in background | Regenerates the on-disk HTML synchronously |
 | Cloudflare (default) | Worker-managed Cache API timestamp, `env.ASSETS` fallback — **per colo** | Overwrites the Cache API entry in the receiving colo only |
 | Cloudflare (`cache: true`) | Edge-tier Workers Caching in front of the Worker for time-revalidated routes | Webhook-only routes keep the worker-managed path; time+webhook routes also get their edge entry purged |
-| Vercel | Build Output prerender functions: `.prerender-config.json` with `expiration` from the time policy and build HTML as fallback | `x-vercel-cache`-verified bypass; `PRACHT_REVALIDATE_TOKEN` becomes the `bypassToken` and **must be set at build time** (runtime-only setting → webhook paths report `failed` until you rebuild) |
+| Vercel | Build Output prerender functions: `.prerender-config.json` with `expiration` from the time policy and build HTML as fallback, next to a Node Serverless Function per ISG route (Vercel rejects ISR on an Edge Function) | For webhook revalidation, `x-vercel-cache` verifies the bypass; `PRACHT_REVALIDATE_TOKEN` becomes the `bypassToken` and **must be set at build time** (runtime-only setting → webhook paths report `failed` until you rebuild). Time-only ISR does not require the token. |
 
 Cloudflare specifics (`docs/ADAPTERS.md#isg-via-workers-caching-cache`):
 
@@ -127,8 +135,9 @@ exact path **plus query string** (param order and trailing slash included), so
 revalidation — and attacker-chosen query values create unbounded cold entries.
 Before enabling `cache: true`, canonicalize or reject stray query params (the
 docs describe an uncached-gateway pattern), and note that routes exporting
-`markdown` carry `Vary: Accept`, which multiplies variants per `Accept`
-string. Vercel prerender functions are generated with `allowQuery: []`, so
+`markdown` or declaring middleware-owned `markdown: true` carry `Vary: Accept`,
+which multiplies variants per `Accept` string. Vercel prerender functions are
+generated with `allowQuery: []`, so
 query strings do not fragment that cache. Middleware never runs for cached ISG
 hits on any adapter — keep per-visitor logic on SSR routes.
 
@@ -158,9 +167,15 @@ pracht typegen   # if src/routes.ts changed
 
 1. Never overwrite `wrangler.jsonc`/`wrangler.toml` or `vercel.json` — diff
    and merge, confirming collisions with `AskUserQuestion`.
-2. Never propose ISG for personalized responses: `Set-Cookie` or
-   `Cache-Control: private`/`no-store` output fails regeneration, and
-   `Vary: Cookie`/`Authorization`/`*` is kept out of shared caches by design.
+2. Never propose ISG for personalized responses. ISG HTML renders always run
+   on a sanitized request (`GET`, `Accept: text/html`, path only — no cookies,
+   credentials, query, or body); Cloudflare Workers Caching uses the same
+   isolation with `Accept: text/markdown` for its markdown cache variant. A
+   loader that reads the session therefore sees an anonymous visitor. On top of that, `Set-Cookie` or
+   `Cache-Control: private`/`no-store` output fails regeneration on Node and
+   Cloudflare (on Vercel the credential headers are stripped and the mismatch
+   is logged), and `Vary: Cookie`/`Authorization`/`*` is kept out of shared
+   caches by design.
 3. Always pair `render: "isg"` with an explicit `revalidate` policy — without
    one the route silently behaves like SSG.
 4. On Vercel, set `PRACHT_REVALIDATE_TOKEN` in the build environment, not

package/skills/migrate-nextjs/SKILL.md

@@ -53,7 +53,7 @@ If the source Next.js project uses the **pages router** (`pages/` directory), pr
 2. Copy `pages/` to `src/pages/`
 3. Convert `_app.tsx` to pracht shell format (`Shell` export + `children` prop)
 4. Convert `getServerSideProps`/`getStaticProps` to `loader` exports
-5. Add `export const RENDER_MODE = "ssg"` to static pages, `"ssr"` for dynamic (default is `"ssr"`)
+5. Add `export const RENDER_MODE = "ssg"` to static pages, `"ssr"` for dynamic (default is `"ssr"`). For time-revalidated pages, export `RENDER_MODE = "isg"` and a positive integer `REVALIDATE` in seconds. Webhook policies require ejection.
 6. Run dev server, iterate on errors
 7. Optionally run `generateRoutesFile` to eject to explicit manifest
 
@@ -85,6 +85,7 @@ For pages router projects, you can **skip manual manifest wiring entirely** (Pha
 | `useLinkStatus()` / pending UI  | `useNavigation()`                                               | `{ state, location, formData }` — powers progress bars and optimistic UI |
 | `next/image`                    | `<Image>` from `@pracht/image`                                  | Responsive srcsets plus Node, Cloudflare, Vercel, or passthrough loaders |
 | `next/head` or Metadata API     | `head()` export on route/shell                                  | Per-route and per-shell head merging                                  |
+| `next/script` `<Script>`        | `<Script>` from `@pracht/core`                                  | Strategies: `beforeHydration` (≈ `beforeInteractive`), `afterHydration` (≈ `afterInteractive`, default), `idle` (≈ `lazyOnload`), `visible` |
 | `className`                     | `class`                                                         | Preact uses `class` attribute                                         |
 | `React.useState` etc.           | `import { useState } from "preact/hooks"`                       | Preact hooks API is compatible                                        |
 | `React.useEffect`               | `import { useEffect } from "preact/hooks"`                      | Same API                                                              |
@@ -117,7 +118,7 @@ For pages router projects, you can **skip manual manifest wiring entirely** (Pha
 3. Update `package.json`:
    - Replace `react`, `react-dom` → `preact`
    - Replace `next` → `@pracht/core` (framework runtime), `@pracht/cli` (provides the `pracht` bin), `@pracht/vite-plugin`, and `@pracht/adapter-node` (or target adapter). There is no package named `pracht`.
-   - If the app imports `next/image`, add `@pracht/image`; add `sharp` only for the built-in Node optimization endpoint.
+   - If the app imports `next/image`, add `@pracht/image`; add `sharp` only for the built-in Node optimization endpoint or build-time `?pracht` imports (static imports / blur placeholders).
    - Update scripts: `dev` → `pracht dev`, `build` → `pracht build`, `start` → `node dist/server/server.js` (Node.js) or a platform-specific deploy command; add `preview` → `pracht preview` to serve the production build locally
 4. Remove Next.js config files: `next.config.*`, `next-env.d.ts`, `.next/`
 5. If `tsconfig.json` has `"jsx": "preserve"`, change to `"jsx": "react-jsx"` and add `"jsxImportSource": "preact"`.
@@ -415,6 +416,14 @@ Choose the loader for the deployment target:
 Preserve the original `width`, `height`, `fill`, `sizes`, `quality`, and
 priority intent. See `docs/IMAGES.md` for the endpoint and loader wiring.
 
+Static imports and blur placeholders migrate too: replace
+`import photo from "./photo.jpg"` with `import photo from "./photo.jpg?pracht"`,
+add `prachtImage()` (from `@pracht/image/vite`) to the Vite plugins, reference
+the `@pracht/image/client` types once in a `.d.ts`, and keep
+`<Image src={photo} placeholder="blur" />` as-is — the import supplies
+`width`/`height`/`blurDataURL` exactly like Next's static imports. Pracht's
+blur is CSS-only (no fade animation, no inline event handlers).
+
 #### `useRouter` → navigation
 
 ```tsx

package/skills/pracht-deploy/SKILL.md

@@ -3,10 +3,11 @@ name: pracht-deploy
 version: 1.1.0
 description: |
   Pracht deployment guide. Walks through adapter configuration, building, and
-  deploying to Node.js, Cloudflare Workers, or Vercel. Handles wrangler config,
-  Docker and production checklist.
+  deploying to Node.js, Cloudflare Workers, Netlify, or Vercel. Handles platform
+  config, Docker and production checklist.
   Use when asked to "deploy", "set up deployment", "configure adapter",
-  "deploy to cloudflare", "deploy to vercel", or "production build".
+  "deploy to cloudflare", "deploy to netlify", "deploy to vercel", or
+  "production build".
 allowed-tools:
   - Bash
   - Read
@@ -34,6 +35,7 @@ If the pracht MCP server is registered (docs/MCP.md), prefer the `inspect_build`
 | ------------------ | ---------------------------- | ------ |
 | Node.js            | `@pracht/adapter-node`       | Stable |
 | Cloudflare Workers | `@pracht/adapter-cloudflare` | Stable |
+| Netlify            | `@pracht/adapter-netlify`    | Stable |
 | Vercel             | `@pracht/adapter-vercel`     | Stable |
 
 ---
@@ -47,9 +49,20 @@ If the pracht MCP server is registered (docs/MCP.md), prefer the `inspect_build`
    ```ts
    import { pracht } from "@pracht/vite-plugin";
    import { nodeAdapter } from "@pracht/adapter-node";
-   export default { plugins: [pracht({ adapter: nodeAdapter() })] };
+   export default {
+     plugins: [
+       pracht({
+         adapter: nodeAdapter({ canonicalOrigin: "https://app.example.com" }),
+       }),
+     ],
+   };
    ```
 
+Pin `canonicalOrigin` in production so `request.url` does not depend on the
+incoming `Host` header. `maxBodySize` is also available on `nodeAdapter()`.
+Only custom entries behind a trusted proxy that overwrites forwarded headers
+should use `createNodeRequestHandler({ trustProxy: true })`.
+
 ### Build
 
 ```bash
@@ -105,6 +118,25 @@ npx wrangler deploy
 
 To smoke-test the built worker locally first, run `pracht preview` — it builds and then delegates to `wrangler dev`, which serves the wrangler config's `main` entry, `dist/server/worker.js`.
 
+Wrangler owns the Worker's binding environment. Put local-only secrets such as
+`PRACHT_CONFIRMATION_SECRET` and `PRACHT_REVALIDATE_TOKEN` in a gitignored
+`.dev.vars`; prefixing the host command with those variables does not
+automatically expose them inside the Worker. Keep production values in
+`wrangler secret`.
+
+If the config contains a custom-domain route, preview can listen on localhost
+while `request.url` inside the Worker uses the custom domain. Sign that
+effective `@authority` for Web Bot Auth or temporarily disable the route. To use
+a separate local config, build first, then run:
+
+```bash
+pracht build
+npx wrangler dev --config wrangler.local.jsonc --port 3000
+```
+
+The local config must keep `main: "dist/server/worker.js"` and omit the
+production route. `pracht preview` does not forward Wrangler's `--config` flag.
+
 ### Wrangler Configuration
 
 ```jsonc
@@ -112,7 +144,7 @@ To smoke-test the built worker locally first, run `pracht preview` — it builds
 {
   "name": "my-pracht-app",
   "main": "dist/server/worker.js",
-  "compatibility_date": "2024-01-01",
+  "compatibility_date": "2026-04-06",
   "assets": {
     "binding": "ASSETS",
     "directory": "dist/client",
@@ -132,12 +164,33 @@ export async function loader({ context }: LoaderArgs) {
 }
 ```
 
+Keep Cloudflare binding reads inside the loader, API handler, capability
+`run()`, or another request-time function. Although Workers permits top-level
+`env.MY_KV`, Pracht graph inspection intentionally fails such module-initializer
+reads because it cannot supply an authoritative binding without risking false
+graph metadata.
+
 ### Custom Assets Binding
 
 ```ts
 pracht({ adapter: cloudflareAdapter({ assetsBinding: "STATIC" }) });
 ```
 
+### Named bindings and default-export handlers
+
+Durable Object and Workflow classes are named Worker exports. Re-export them
+from the module configured with `workerExportsFrom`. Queue consumers, Cron
+Triggers, and Email Routing are instead methods on the default export; expose
+named `queue`, `scheduled`, or `email` functions from the module configured
+with `workerHandlersFrom`:
+
+```ts
+cloudflareAdapter({
+  workerExportsFrom: "/src/cloudflare.ts",
+  workerHandlersFrom: "/src/worker-handlers.ts",
+});
+```
+
 ### ISG via Workers Caching
 
 ISG works out of the box: without any cache option, the default worker-managed path serves the build-time snapshot, detects staleness, and regenerates pages in the background via the Workers Cache API — per colo — and `POST /__pracht/revalidate` triggers on-demand regeneration. Enabling `cache: true` moves ISG from that per-colo worker-managed path to edge-tier Workers Caching, on both sides:
@@ -155,7 +208,8 @@ Before enabling it, audit ISG URLs for unbounded query strings. Workers Caching
 keys the exact path and query string, including parameter order and trailing
 slashes; use a bounded query allowlist/canonical redirect or an uncached gateway
 with a pathname-only `cf.cacheKey`, and normalize `Accept` there for routes that
-export markdown. See `docs/ADAPTERS.md#cache-key-cardinality`.
+export markdown or declare `markdown: true` for middleware-owned negotiation.
+See `docs/ADAPTERS.md#cache-key-cardinality`.
 
 Time-revalidated ISG pages then render on demand, are cached at the edge for
 their `revalidate` window (stale pages served instantly while the Worker
@@ -165,6 +219,60 @@ build-time snapshots and the worker-managed path either way.
 
 ---
 
+## Netlify Deployment
+
+### Setup
+
+1. Ensure `@pracht/adapter-netlify` and `netlify-cli` are installed.
+2. In `vite.config.ts`:
+   ```ts
+   import { pracht } from "@pracht/vite-plugin";
+   import { netlifyAdapter } from "@pracht/adapter-netlify";
+   export default { plugins: [pracht({ adapter: netlifyAdapter() })] };
+   ```
+3. Add `netlify.toml`:
+   ```toml
+   [build]
+     command = "pnpm build"
+     publish = "dist/client"
+
+   [functions]
+     directory = "netlify/functions"
+   ```
+
+### Build, Preview, and Deploy
+
+```bash
+npx pracht build && npx netlify dev
+npx netlify deploy --build --prod
+```
+
+The build emits `netlify/functions/pracht.mjs`. Page requests go through that
+function so Markdown negotiation and route-state requests remain correct;
+hashed assets bypass it and stay outside the function bundle. The generated
+config enumerates only client files the function can serve and roots matching
+exclusions at the function file so Netlify's tracer cannot re-add bypassed
+trees. Netlify durable caching
+implements time-based ISG and per-path cache tags implement authenticated
+webhook revalidation. A trailing-slash ISG document request permanently
+redirects to the canonical slashless URL before rendering, and webhook
+revalidation normalizes either spelling before purging the cache tag.
+Only `Cache-Control`, `CDN-Cache-Control`, and `Netlify-CDN-Cache-Control`
+override the adapter's cache defaults; provider-specific headers for another
+CDN do not. Set a cache window to `0` to disable stale serving or freshness.
+`Netlify-Vary` owns route-state variants, while the standard `Vary: Accept`
+header owns Markdown negotiation. Cacheable negotiated SSG representations use
+the same `Netlify-Vary` instructions as their prerendered HTML. Shared ISG
+renders strip visitor-specific request data and Netlify context metadata before
+loaders or context factories run.
+
+`pracht preview` exits with guidance because it cannot emulate Netlify's
+Functions and CDN behavior. Build the generated function before using
+`netlify dev` for the platform-shaped local runtime. Configure
+`PRACHT_REVALIDATE_TOKEN` in Netlify when webhook revalidation is enabled.
+
+---
+
 ## Vercel Deployment
 
 ### Setup
@@ -186,6 +294,15 @@ npx vercel deploy --prebuilt
 
 Produces: `.vercel/output/config.json`, `.vercel/output/static/`, `.vercel/output/functions/render.func/server.js`
 
+There is no faithful local Vercel production runtime, so `pracht preview`
+exits with guidance. Use `vercel build` or `vercel dev`. Set
+`PRACHT_REVALIDATE_TOKEN` at build time when using webhook revalidation; its
+Vercel bypass token is embedded in `.prerender-config.json`. Rename the main
+Edge Function with `vercelAdapter({ functionName })` if its default `render`
+name would collide with an ISG route. Custom entries must export the
+`nodeListener` created by `createVercelNodeListener(handle)` for Node ISR
+functions.
+
 ---
 
 ## Deployment Checklist
@@ -201,7 +318,7 @@ Produces: `.vercel/output/config.json`, `.vercel/output/static/`, `.vercel/outpu
 
 1. Read `vite.config.ts` and `package.json` before giving advice.
 2. Run `pracht build` to verify the build succeeds before deploying.
-3. Smoke-test the production runtime before pushing to production. For Node.js and Cloudflare, run `pracht preview`.
+3. Smoke-test the production runtime before pushing to production. For Node.js and Cloudflare, run `pracht preview`; for Netlify, run `pracht build && netlify dev`.
 4. If the user needs an adapter that isn't installed, help them add it (`pnpm add @pracht/adapter-*`).
 5. Don't push to production without the user's explicit confirmation.
 

package/skills/pracht-test-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pracht-test-api
-version: 1.1.0
+version: 1.2.0
 description: |
   Auto-generate Vitest request/response tests for every handler in `src/api/`.
   Each test instantiates a `Request`, calls the exported HTTP method handler
@@ -53,34 +53,28 @@ Ask the user which subset to scaffold or accept paths via `$ARGUMENTS`.
 ## Step 3: Generate one test per handler file
 
 Place tests next to the handler with `.test.ts` suffix
-(`src/api/users/[id].test.ts`). Use a small helper to construct
-`ApiRouteArgs`:
+(`src/api/users/[id].test.ts`). Use `createApiArgs()` from `@pracht/test`
+(add it as a dev dependency if missing) to construct `ApiRouteArgs`:
 
 ```ts
 import { describe, it, expect } from "vitest";
+import { createApiArgs, readJson } from "@pracht/test";
 import { GET, POST /* import only what the handler exports */ } from "./<file>";
 
-function args(url: string, init?: RequestInit, params: Record<string, string> = {}) {
-  const request = new Request(url, init);
-  return {
-    request,
-    params,
-    context: {} as never,
-    url: new URL(request.url),
-    signal: AbortSignal.timeout(5000),
-    route: {} as never,
-  };
-}
-
 describe("<METHOD> <api-path>", () => {
   it("returns 200 on a valid request", async () => {
-    const res = await GET(args("http://localhost<api-path>"));
+    const res = await GET(createApiArgs({ url: "<api-path>" }));
     expect(res).toBeInstanceOf(Response);
     expect(res.status).toBe(200);
   });
 });
 ```
 
+Pass `params` for dynamic segments, `body` for JSON payloads (plain objects
+are JSON-encoded with the right `Content-Type`), and use `submitForm()` for
+form-encoded/multipart POSTs — it drives the same `FormData` parsing path
+`defineApi()` uses.
+
 ## Step 4: Generate method-specific cases
 
 For each exported method, emit the smallest realistic case:
@@ -108,7 +102,7 @@ middleware is in that list. If it is, scaffold an extra test:
 
 ```ts
 it("rejects unauthenticated requests", async () => {
-  const res = await POST(args("http://localhost<api-path>", { method: "POST" }));
+  const res = await POST(createApiArgs({ url: "<api-path>", method: "POST" }));
   expect([401, 403, 302]).toContain(res.status);
 });
 ```
@@ -127,9 +121,9 @@ For handlers that return `Response.json(...)`, generate:
 
 ```ts
 it("returns JSON with the expected keys", async () => {
-  const res = await GET(args("http://localhost<api-path>"));
+  const res = await GET(createApiArgs({ url: "<api-path>" }));
   expect(res.headers.get("content-type")).toMatch(/application\/json/);
-  const body = await res.json();
+  const body = await readJson(res);
   expect(body).toEqual(expect.objectContaining({ /* fill in */ }));
 });
 ```

package/skills/pre-deploy/SKILL.md

@@ -77,8 +77,9 @@ a markdown summary (graph diff + verify + budgets) worth attaching to it.
   deployment environment. List them for the user.
 - If the app mounts `createImageHandler()` from `@pracht/image/node`, confirm
   `sharp` is installed and `localOrigin` is the same trusted public origin as
-  `nodeAdapter({ canonicalOrigin })`. A production-relative image endpoint
-  without both values is an error.
+  `nodeAdapter({ canonicalOrigin })`. A relative image endpoint without both
+  values is an error in every environment; loopback-looking request origins
+  are intentionally not trusted.
 - Reverse-proxy / TLS termination configured (out of scope for this skill —
   flag for confirmation).
 
@@ -92,7 +93,11 @@ a markdown summary (graph diff + verify + budgets) worth attaching to it.
   metadata (`buildTarget`, manifests, `resolvedApp`, ...) that `server.js`
   exports for the prerender pass.
 - `assets.directory` points to `dist/client`.
-- `compatibility_date` is set and recent.
+- `compatibility_date` is set, and is a date the installed workerd supports.
+  It must not be *newer* than the runtime: workerd refuses to start with
+  "This Worker requires compatibility date X, but the newest date supported
+  by this server binary is Y". Never set it to today's date — that is by
+  construction at or beyond the newest released workerd.
 - Bindings declared in wrangler config for every `context.env.*` access in
   loaders, middleware, and API routes (grep, then cross-check).
 - **No Node-only APIs in the server bundle.** Grep the server files for:
@@ -133,11 +138,19 @@ a markdown summary (graph diff + verify + budgets) worth attaching to it.
 - Required env vars are configured in the Vercel project (cannot verify from
   CLI without `vercel env pull` — run that and diff against `process.env.*`
   references).
-- Edge runtime constraints: pracht **always** writes the function's
-  `.vc-config.json` with `runtime: "edge"` — there is no Node runtime
-  variant, so run the same Node-only API check as Cloudflare
-  **unconditionally** for Vercel builds. Do not skip it based on a runtime
-  probe.
+- Edge runtime constraints: the render function's `.vc-config.json` is
+  **always** written with `runtime: "edge"`, so run the same Node-only API
+  check as Cloudflare **unconditionally** for Vercel builds. Do not skip it
+  based on a runtime probe — ISG routes run the same bundle on Node, but any
+  Node-only API still breaks the edge function.
+- ISG functions: every `<route>.prerender-config.json` must sit next to a
+  **Serverless** `<route>.func` (`.vc-config.json` with `launcherType:
+  "Nodejs"`). Vercel rejects a prerender config paired with an edge function:
+  `Unexpected function type "EdgeFunction" at path "<route>"`.
+- Region configuration: `vercelAdapter({ regions: "all" })` is valid for the
+  Edge render function, but generated Node ISG function configs must omit
+  `regions` so the project's default Serverless region applies. Node configs
+  may only contain arrays of concrete region identifiers.
 - An API route importing `@pracht/image/node` is an error for the Vercel Edge
   function. Require `vercelLoader` (with aligned allowed sizes) or
   `passthroughLoader` instead.