create-pracht 0.4.2 → 0.6.0

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
@@ -92,10 +92,35 @@ target. From `pracht inspect api --json`:
   `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) and each
-  HTTP-exposed capability, check whether
+  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.
 
@@ -142,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-headers/SKILL.md

@@ -49,8 +49,11 @@ The audit surface is therefore:
 - **(c)** HSTS and CSP, which genuinely need user action.
 
 Prerequisites: `pracht inspect` requires a vite config that registers the
-pracht plugin; `pracht inspect build` and `dist/client/_pracht/headers.json`
-require a prior `pracht build`.
+pracht plugin; `pracht inspect build` and
+`dist/server/headers-manifest.json` require a prior `pracht build`. Every
+serverful target currently publishes a client copy at
+`dist/client/_pracht/headers.json`; only Cloudflare reads it there. Pure static
+exports deliberately do not publish that copy.
 
 ## Step 1: Inventory header sources
 
@@ -134,9 +137,15 @@ the `headers()` sources statically to catch them **before** a build failure,
 and report each as `error` with the prerender failure it would cause.
 
 The real target is the `warn` class the framework cannot catch: innocuously
-named headers carrying user-specific values, which get copied into
-`dist/client/_pracht/headers.json` (public client output) and replayed across
-users on static responses.
+named headers carrying user-specific values in
+`dist/server/headers-manifest.json`, which serverful adapters may replay across
+users on static responses. Every serverful build currently also copies that
+manifest into public client output; Cloudflare reads it through the assets
+binding, while the other adapters retain the public copy for compatibility. A
+pure static export omits the client copy and has no runtime to replay the server
+manifest; instead, verify that the deployment's host-header configuration
+mirrors only safe, non-user-specific entries. Missing host configuration means
+route `headers()` values are not applied at all.
 
 Secret VALUES in headers are owned by `audit-secrets`; this skill owns policy
 headers. Cross-reference `audit-secrets` for value-level findings.

package/skills/audit-secrets/SKILL.md

@@ -95,10 +95,13 @@ Check for accidental exposure outside loaders:
 
 - `head()` returns: rare, but a `meta` value containing a token leaks into HTML.
 - `headers()` returns: flag values that look like secrets. For SSG/ISG pages,
-  document headers can be copied into `dist/client/_pracht/headers.json`, which
-  is public client output and may be replayed on static responses. This skill
-  owns secret VALUES in headers; header policy (CSP, HSTS, weakened defaults)
-  is owned by `audit-headers` — cross-reference it.
+  document headers enter `dist/server/headers-manifest.json`; every serverful
+  build currently also copies that manifest to public
+  `dist/client/_pracht/headers.json` (only Cloudflare reads it there). A pure
+  static export omits the client copy but may mirror the server manifest into
+  host configuration. This skill owns secret VALUES in headers; header policy
+  (CSP, HSTS, weakened defaults) is owned by `audit-headers` — cross-reference
+  it.
 - `<Form>` `action` URLs containing tokens in the query string.
 - `prefetchRouteState(url)` calls with sensitive query params.
 - Inline `<script>` content emitted from custom shells.

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
@@ -75,23 +81,29 @@ webhooks naming them are `skipped` on Node/Cloudflare (nothing to refresh).
 
 ## Step 3: The revalidation webhook
 
-All adapters expose `POST /__pracht/revalidate` (`PRACHT_REVALIDATE_ENDPOINT`
-from `@pracht/core`):
+All adapters expose `POST <base>/__pracht/revalidate`
+(`PRACHT_REVALIDATE_ENDPOINT` from `@pracht/core`). For example, an app with
+`base: "/app/"` uses:
 
 ```sh
-curl -X POST https://example.com/__pracht/revalidate \
+curl -X POST https://example.com/app/__pracht/revalidate \
   -H "Authorization: Bearer $PRACHT_REVALIDATE_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"paths":["/pricing"]}'
 ```
 
+At the default `base: "/"`, omit `/app`. Keep request-body paths base-free;
+they identify manifest routes rather than public deployment URLs.
+
 - Auth: `PRACHT_REVALIDATE_TOKEN` env var; fails closed with `401` when unset
   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 +112,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 +139,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 +171,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
 
@@ -78,13 +78,14 @@ For pages router projects, you can **skip manual manifest wiring entirely** (Pha
 | `"use client"` (few, in a mostly-server app) | `hydration: "islands"` + `src/islands/`            | Only islands ship JS; see the islands note in Phase 4                 |
 | `revalidatePath` / `res.revalidate()` | `webhookRevalidate()` + `POST /__pracht/revalidate`       | On-demand ISG regeneration; combinable with `timeRevalidate(seconds)` |
 | `useRouter()` (next/navigation) | `useNavigate()` from pracht                                     | Accepts paths or typed route targets after `pracht typegen`           |
-| `useSearchParams()`             | `useLocation()` from pracht                                     | Returns `{ pathname, search }`; loaders also receive `url` with searchParams |
+| `useSearchParams()`             | `useSearchParams()` from pracht                                 | Returns reactive read-only params; SSG receives the browser query after hydration, while loaders use `url.searchParams` |
 | `useParams()`                   | `useParams()` from pracht                                       | Direct equivalent; also available as `params` in loader args          |
 | `next/link` `<Link>`            | `<Link route="...">` or plain `<a>`                            | Prefer typed `<Link>` for known app routes after `pracht typegen`; plain anchors still work |
 | `next/link` `prefetch={false}`  | `<Link prefetch="none">`                                        | Pracht prefetches on hover/focus by default; also `"viewport"`, `"render"` |
 | `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
@@ -443,13 +452,13 @@ async function createPost(formData: FormData) {
 }
 
 // Pracht — API route handler
-import type { ApiRouteArgs } from "@pracht/core";
+import { withBase, type ApiRouteArgs } from "@pracht/core";
 
 export async function POST({ request }: ApiRouteArgs) {
   const form = await request.formData();
   await db.insert({ title: form.get("title") });
   // revalidatePath("/posts") equivalent: regenerate the ISG page on demand
-  await fetch(new URL("/__pracht/revalidate", request.url), {
+  await fetch(new URL(withBase("/__pracht/revalidate"), request.url), {
     method: "POST",
     headers: {
       authorization: `Bearer ${process.env.PRACHT_REVALIDATE_TOKEN}`,
@@ -459,7 +468,7 @@ export async function POST({ request }: ApiRouteArgs) {
   });
   return new Response(null, {
     status: 303,
-    headers: { location: "/posts" },
+    headers: { location: withBase("/posts") },
   });
 }
 ```
@@ -502,7 +511,8 @@ export async function loader({ request }: LoaderArgs) {
 | `next/image`    | `@pracht/image`                                         |
 | `react`         | `preact`                                                |
 | `react-dom`     | `preact`                                                |
-| `@next/font`    | CSS `@font-face` or `fontsource` packages               |
+| `next/font/local` | `defineFont()` from `@pracht/core` — register via `head() { return { fonts: [font] } }`, use `font.className`/`font.style` in components |
+| `next/font/google` | Download the woff2 files into `public/fonts/` (e.g. via google-webfonts-helper), then `defineFont()` — pracht never fetches fonts at build time |
 | `@next/mdx`     | `@mdx-js/rollup` (Vite plugin)                          |
 | `next-auth`     | Direct integration in middleware/loaders                |
 | `next/og`       | `@vercel/og` or custom solution                         |

package/skills/pracht-debug/SKILL.md

@@ -28,7 +28,7 @@ The user will describe a symptom (error, unexpected behavior, blank page, etc.).
 Before deep manual inspection, prefer running `pracht verify` (add `--changed` to scope the checks to git-changed files) for a fast agent loop or `pracht doctor` when the problem could be caused by broader broken app wiring or missing files.
 When another agent/tool needs the framework's resolved graph, prefer `pracht inspect routes --json`, `pracht inspect api --json`, or `pracht inspect build --json` over reconstructing it from source files. Prerequisites: `pracht inspect` needs the pracht plugin registered in the project's vite config, and `pracht inspect build` needs a prior `pracht build`.
 If the pracht MCP server is registered (docs/MCP.md), prefer the `inspect_routes`/`inspect_api`/`doctor`/`verify` MCP tools over shelling out — same payloads, structured results.
-While the dev server is running, `GET /_pracht` serves a devtools page with the same resolved route/API graph (raw JSON at `/_pracht.json`) — useful when you have a browser or `curl` handy but no CLI access. Dev SSR responses also carry a `Server-Timing` header (`mw`, `loader`, `render` durations in ms) — check it in the browser Network panel or with `curl -sI` to see which phase makes a route slow.
+While the dev server is running, `GET /_pracht` serves a devtools page with the same resolved route/API graph (raw JSON at `/_pracht.json`) — useful when you have a browser or `curl` handy but no CLI access. Under a Vite deploy base, prefix both paths with that base; links from the devtools and dev-404 pages already do so. Dev SSR responses also carry a `Server-Timing` header (`mw`, `loader`, `render` durations in ms) — check it in the browser Network panel or with `curl -sI` to see which phase makes a route slow.
 
 ## Iron Law
 

package/skills/pracht-deploy/SKILL.md

@@ -1,12 +1,14 @@
 ---
 name: pracht-deploy
-version: 1.1.0
+version: 1.2.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, Vercel, or a pure static
+  host. 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", "static
+  export", or
+  "production build".
 allowed-tools:
   - Bash
   - Read
@@ -34,7 +36,9 @@ 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 |
+| Static export      | `@pracht/adapter-static`     | Stable |
 
 ---
 
@@ -47,9 +51,35 @@ 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 })`.
+If that proxy strips Vite's deploy base from the forwarded path, set
+`nodeAdapter({ basePathStripped: true })` (or the same option on a custom
+`createNodeRequestHandler`). Do not infer this from the first path segment: a
+route may legitimately begin with the same segment as the deploy base. The
+adapter restores the public base before `createContext()`, loaders, and API
+handlers receive the request.
+The proxy must also own the public bare-base redirect (`/app` to `/app/`) in
+this mode because the stripped origin cannot distinguish it from a legitimate
+base-free `/app` route.
+
+The Node adapter compresses responses by default (brotli/gzip negotiated via
+`Accept-Encoding`, streaming for dynamic bodies, an in-memory LRU for static
+assets). When the deployment sits behind a reverse proxy or CDN that already
+compresses responses, set `nodeAdapter({ compression: false })` so bodies are
+not compressed twice.
+
 ### Build
 
 ```bash
@@ -105,6 +135,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 +161,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 +181,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 +225,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 +236,64 @@ 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 at the origin
+root. With a Vite deploy base, the function instead bundles and serves the
+base-free asset and `/_pracht` trees so `/app/...` requests remain inside the
+mount. Custom `excludedPath` entries still bypass their literal origin-root
+URLs, but matching files remain bundled for base-prefixed requests. The
+generated config enumerates only client files the function can serve and roots
+applicable 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 +315,96 @@ 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.
+
+---
+
+## Static Export Deployment
+
+For apps where every route is `render: "ssg"` (or loaderless, full-hydration
+`"spa"`), with no
+request middleware, API routes, or HTTP/MCP/WebMCP-exposed capabilities. SSG
+loaders run only at build time and must produce HTML plus valid JSON route
+state; dynamic SSG routes must export `getStaticPaths()`. Anything else fails the build with an error naming the
+offenders — that is the signal to pick a serverful adapter instead. Only
+manifest-registered capabilities participate; every registered capability
+module must load successfully so exposure validation can fail closed. The
+`notFound` page must use full hydration (the default), because the shared
+`404.html` needs the client router to adopt the visitor's actual URL. Sub-path
+deploys (GitHub Pages *project* sites, S3 key prefixes) set Vite `base` to that
+path; CDN and document-relative bases (`""` / `"./"`) are build errors,
+because they split assets from the deploy root or resolve them beneath nested
+page directories. Under a base,
+internal navigation must go through `<Link route>` / `href()` — a hand-written
+`<a href="/about">` still means the origin root.
+Pracht's preview and first-party serverful adapters redirect the bare base
+(`/app`) to its trailing-slash form (`/app/`) before serving the root document;
+custom adapters receive the same behavior through `handlePrachtRequest()`.
+Framework-owned browser URLs from the default image loader and OpenAPI
+companion artifacts pick up the same base automatically.
+
+### Setup
+
+1. Ensure `@pracht/adapter-static` is installed.
+2. In `vite.config.ts`:
+   ```ts
+   import { pracht } from "@pracht/vite-plugin";
+   import { staticAdapter } from "@pracht/adapter-static";
+   export default { plugins: [pracht({ adapter: staticAdapter() })] };
+   // With dynamic SPA routes, add { fallback: "200.html" } and configure the
+   // host to rewrite unmatched URLs to it. If the route or shell exports
+   // head(), also set generic fallbackHead metadata shared by every rewrite.
+   ```
+
+### Build & Deploy
+
+```bash
+pracht build      # dist/client/ is the whole deployment
+pracht preview    # local static file server over dist/client/
+```
+
+Upload `dist/client/` to any static host (GitHub Pages, S3, nginx, Netlify).
+`dist/server/` is build tooling only — never deploy it. The host must serve
+`<dir>/index.html` for clean URLs and should use `404.html` as its error
+document. A static `notFound` page must use full hydration so that shared
+document can adopt the visitor's real URL. Client navigation fetches collision-safe
+bounded opaque `.json` files under `_pracht/state/` for full-hydration SSG
+routes whose loader or route/shell `head()` metadata participates in navigation;
+equivalent raw-Unicode and percent-encoded URL segment spellings resolve to the
+same state file. Explicitly loaderless and headless routes fetch no Pracht
+state; loaderless routes with head metadata fetch static state for font-head
+fragments but still use browser-side requests to an external API for live
+data. Files under `public/_pracht/state/` may not occupy a generated
+route-state path; the build rejects the collision instead of overwriting the
+public file. Files copied from `public/` or emitted by Vite also may not occupy
+the generated `404.html` or configured fallback path, including a case- or
+Unicode-normalization-equivalent spelling; the build rejects the portable
+collision instead of overwriting existing output. Generic `fallbackHead` fonts
+remain registered while the fallback commits a loaderless dynamic SPA route.
+See docs/ADAPTERS.md § Static Adapter for host header
+configuration and limitations (markdown negotiation, base paths). Pages are
+written to the percent-decoded output path, matching how static hosts resolve
+requests; `pracht preview` decodes request segments the same way. The SPA fallback only client-renders matched SPA routes; dynamic
+SSG paths omitted by `getStaticPaths()` render the app's not-found page with
+the build-time loader data or handled error state carried over from `404.html`.
+The host rewrite that serves the fallback answers unknown URLs with status 200 (soft 404), and an app
+with no `notFound` page and no unshadowed client-routable SPA catch-all renders them blank — the build
+warns about that shape. A dynamic SPA route, its shell, or the not-found page
+with `head()` requires an explicit `fallbackHead`, because the shared static
+document cannot evaluate URL-specific server metadata. Prerendered pages must
+map to distinct portable filesystem paths; duplicate/case-folded or
+Unicode-normalization-equivalent outputs, Windows-invalid or overlong filename
+components, and file/directory conflicts such as `/` with `/index.html` fail
+before any page is written. Fallback names likewise reject Windows reserved
+device names and the portable 255-byte/code-unit component limit.
+
 ---
 
 ## Deployment Checklist
@@ -201,7 +420,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.