create-pracht 0.5.0 → 0.6.1

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

@@ -81,16 +81,20 @@ 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.

package/skills/migrate-nextjs/SKILL.md

@@ -78,7 +78,7 @@ 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"` |
@@ -424,6 +424,15 @@ the `@pracht/image/client` types once in a `.d.ts`, and keep
 `width`/`height`/`blurDataURL` exactly like Next's static imports. Pracht's
 blur is CSS-only (no fade animation, no inline event handlers).
 
+For apps that relied on `next/image` producing files during a static export,
+use `?pracht&pracht-static` instead. It emits cached responsive WebP variants
+and bypasses the runtime loader while retaining plain, hydration-free `<img>`
+markup. When Markdown content contains relative images, prefer
+`defineMarkdownCollection()` from `@pracht/markdown`; it applies the same
+static pipeline to normal `![alt](./photo.jpg)` syntax. Keep root-relative
+`public/` and remote image URLs unchanged, and use an absolute Vite `base` for
+static variants.
+
 #### `useRouter` → navigation
 
 ```tsx
@@ -452,13 +461,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}`,
@@ -468,7 +477,7 @@ export async function POST({ request }: ApiRouteArgs) {
   });
   return new Response(null, {
     status: 303,
-    headers: { location: "/posts" },
+    headers: { location: withBase("/posts") },
   });
 }
 ```
@@ -511,7 +520,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
 
@@ -72,6 +72,14 @@ Work through these in order, stopping when you find the root cause:
   - Date/time rendering differences
   - Browser-only APIs used during SSR (`window`, `document`, `localStorage`)
   - Conditional rendering based on client state
+  - Two copies of `@pracht/core` in the SSR module graph. The tell is that
+    `useLocation()` returns `/`, `useParams()` returns `{}`, and
+    `useRouteData()` returns `undefined` in the server-rendered HTML for
+    *every* page, while the hydrated client is correct — the provider and the
+    hooks hold different `createContext()` objects. The plugin prevents this by
+    keeping `@pracht/*` in `ssr.noExternal` (dev and build alike); listing a
+    `@pracht/*` package in `ssr.external` overrides that and brings the split
+    back.
 - **Missing shell**: Referencing an unregistered shell name throws at manifest resolution — `Unknown shell "..." for route "...". Did you mean "..."? Registered shells: ...` — and shows up in the dev error overlay as soon as the server loads the manifest. Verify the shell is registered in `defineApp({ shells: { ... } })` and assigned to the route/group.
 - **404 page**: Route not matched — check manifest wiring (step 1). In `pracht dev`, unmatched navigations render a dev-only 404 page listing every registered route with its render mode; compare the requested path against that table. The route table is also printed on dev-server startup and available via `pracht inspect routes`. Apps that declare `defineApp({ notFound })` render their own 404 page instead (in dev and production alike), so the route table is not shown — check `pracht inspect routes` directly. A 404 on a URL you *do* expect to work usually means the loader threw `notFound()`, not that matching failed.
 

package/skills/pracht-deploy/SKILL.md

@@ -1,12 +1,13 @@
 ---
 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, Netlify, or Vercel. Handles platform
-  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 netlify", "deploy to vercel", or
+  "deploy to cloudflare", "deploy to netlify", "deploy to vercel", "static
+  export", or
   "production build".
 allowed-tools:
   - Bash
@@ -37,6 +38,7 @@ If the pracht MCP server is registered (docs/MCP.md), prefer the `inspect_build`
 | Cloudflare Workers | `@pracht/adapter-cloudflare` | Stable |
 | Netlify            | `@pracht/adapter-netlify`    | Stable |
 | Vercel             | `@pracht/adapter-vercel`     | Stable |
+| Static export      | `@pracht/adapter-static`     | Stable |
 
 ---
 
@@ -62,6 +64,21 @@ 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
 
@@ -116,7 +133,7 @@ pracht build
 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`.
+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`. Keep `no_bundle: true` and the JavaScript `ESModule` rule: Pracht's Vite output is already bundled and can contain lazy server chunks that Wrangler must upload separately.
 
 Wrangler owns the Worker's binding environment. Put local-only secrets such as
 `PRACHT_CONFIRMATION_SECRET` and `PRACHT_REVALIDATE_TOKEN` in a gitignored
@@ -134,8 +151,10 @@ 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.
+The local config must keep `main: "dist/server/worker.js"`, keep
+`no_bundle: true`, include the JavaScript `ESModule` rule, and omit the
+production route. `pracht preview` does not forward Wrangler's `--config`
+flag.
 
 ### Wrangler Configuration
 
@@ -144,6 +163,8 @@ production route. `pracht preview` does not forward Wrangler's `--config` flag.
 {
   "name": "my-pracht-app",
   "main": "dist/server/worker.js",
+  "no_bundle": true,
+  "rules": [{ "type": "ESModule", "globs": ["**/*.js", "**/*.mjs"] }],
   "compatibility_date": "2026-04-06",
   "assets": {
     "binding": "ASSETS",
@@ -153,7 +174,7 @@ production route. `pracht preview` does not forward Wrangler's `--config` flag.
 }
 ```
 
-`"binding": "ASSETS"` and `"run_worker_first": true` are required. Without the binding, the worker's `env.ASSETS` resolves to nothing and the runtime silently falls back to `null` — headers and ISG manifests load empty, so SSG serving, ISG revalidation, and per-route headers all silently no-op. The canonical config lives at `examples/cloudflare/wrangler.jsonc`. If you rename the binding with `assetsBinding` (below), the wrangler `binding` value must match.
+`"no_bundle": true`, the JavaScript `ESModule` rule, `"binding": "ASSETS"`, and `"run_worker_first": true` are required. Without the first two settings, Wrangler either re-bundles Pracht's Vite output and folds lazy server chunks into the entry or omits those chunks from the upload. Without the binding, the worker's `env.ASSETS` resolves to nothing and the runtime silently falls back to `null` — headers and ISG manifests load empty, so SSG serving, ISG revalidation, and per-route headers all silently no-op. The canonical config lives at `examples/cloudflare/wrangler.jsonc`. If you rename the binding with `assetsBinding` (below), the wrangler `binding` value must match.
 
 ### Bindings (KV, D1, R2)
 
@@ -249,10 +270,14 @@ 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
+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
@@ -305,6 +330,87 @@ 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
 
 1. **Build**: Run `pracht build` and verify `dist/` output.

package/skills/pracht-scaffold/SKILL.md

@@ -53,7 +53,7 @@ pracht generate api --path /health --methods GET,POST
 - `--shell`/`--middleware` names must already be registered in the app manifest — the CLI errors otherwise. Generate the shell/middleware first, then the route that references it.
 - If the pracht MCP server is registered (docs/MCP.md), call the `generate_route`/`generate_shell`/`generate_middleware`/`generate_api` MCP tools instead of Bash — same behavior, structured results.
 - Add `--json` when another agent/tool needs machine-readable output.
-- `generate route` also emits a Playwright smoke test in `e2e/` when the app has a Playwright setup (`playwright.config.*` or an `e2e/` directory). Pass `--no-test` to skip it, `--test` to force it. Keep the generated test — it is the output-level proof the route works.
+- `generate route` also emits a Playwright smoke test in `e2e/` when the app has a Playwright setup (`playwright.config.*` or an `e2e/` directory). Pass `--no-test` to skip it, `--test` to force it. The test imports `@playwright/test`; if that dependency is absent, follow the generator's install note before typechecking. Keep the generated test — it is the output-level proof the route works.
 - Use `pracht inspect routes --json` or `pracht inspect api --json` to confirm current wiring before manual edits when the existing graph matters. `pracht inspect` requires the pracht plugin registered in the project's vite config.
 - If the app has typed routes (`src/pracht-routes.ts` / `.d.ts`) or the user asks for typed links, run `pracht typegen` after adding or renaming routes.
 - If the app commits `.pracht/app-graph.json`, run `pracht plan --write` after changing routes and include the refreshed snapshot — `pracht verify` fails when it is stale.
@@ -161,6 +161,16 @@ export function GET({ params, url }: ApiRouteArgs) {
 - Use `request.json()`, `request.formData()`, etc. for body parsing.
 - Always return `Response` objects (typically `Response.json()`).
 - Dynamic segments use bracket syntax in filenames: `[id].ts`, `[...slug].ts`.
+- For live server→client updates, use Server-Sent Events:
+  `createEventStream(request, { keepAlive: 15 })` from `@pracht/core/server`
+  returns `{ response, send, close }` — return `response`, push with
+  `send({ data, event?, id? })`, and stop producing when `send()` returns
+  `false` (client disconnected). Consume in components with
+  `useEventSource(url, { json: true })` from `@pracht/core`. Works on all
+  adapters. For WebSockets use `isUpgradeRequest(request)` plus the
+  per-adapter recipes in `docs/ADAPTERS.md` (Cloudflare: API route + Durable
+  Object; Node: `nodeAdapter({ configureServerFrom })`; Vercel: unsupported —
+  use SSE).
 
 ## Wiring Into the Manifest (manual fallback only)
 

package/skills/pre-deploy/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: pre-deploy
-version: 1.2.0
+version: 1.3.0
 description: |
   Adapter-aware pre-deployment checklist for pracht apps targeting Node,
-  Cloudflare Workers, or Vercel. Catches the issues that only surface in the
-  production runtime: missing env vars, Node-only APIs in edge bundles,
-  ISG manifest absence, oversized edge bundles, missing wrangler/vercel config.
+  Cloudflare Workers, Vercel, or a pure static export. Catches the issues that
+  only surface in the production runtime: missing env vars, Node-only APIs in
+  edge bundles, ISG manifest absence, oversized edge bundles, missing
+  wrangler/vercel config, and static hosts missing clean-URL, 404, or security
+  header configuration.
   Use when asked to "pre-deploy check", "ready to ship?", "deployment
   checklist", "is my build production-safe", or before running `wrangler
   deploy` / `vercel deploy`.
@@ -27,8 +29,8 @@ If the pracht MCP server is registered (see docs/MCP.md), prefer its tools
 (`inspect_routes`, `inspect_api`, `inspect_build`, `doctor`, `verify`) over
 shelling out.
 
-Read `vite.config.ts` and look for `nodeAdapter()`, `cloudflareAdapter()`, or
-`vercelAdapter()`. Confirm with:
+Read `vite.config.ts` and look for `nodeAdapter()`, `cloudflareAdapter()`,
+`vercelAdapter()`, or `staticAdapter()`. Confirm with:
 
 ```bash
 pracht inspect build --json
@@ -82,6 +84,10 @@ a markdown summary (graph diff + verify + budgets) worth attaching to it.
   are intentionally not trusted.
 - Reverse-proxy / TLS termination configured (out of scope for this skill —
   flag for confirmation).
+- If the proxy strips Vite's deploy base, confirm
+  `nodeAdapter({ basePathStripped: true })`; application code should still
+  observe the public base in `request.url`, and the proxy must own the public
+  bare-base redirect (`/app` to `/app/`).
 
 ### Cloudflare Workers (`@pracht/adapter-cloudflare`)
 
@@ -92,6 +98,10 @@ a markdown summary (graph diff + verify + budgets) worth attaching to it.
   validates every named export of the deploy entry and rejects the build
   metadata (`buildTarget`, manifests, `resolvedApp`, ...) that `server.js`
   exports for the prerender pass.
+- `no_bundle` is `true`, with an `ESModule` rule whose globs include
+  `"**/*.js"`. Pracht's Vite output is already bundled and may contain lazy
+  server chunks; these settings make Wrangler upload the chunks as separate
+  modules instead of folding them into the entry file.
 - `assets.directory` points to `dist/client`.
 - `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
@@ -122,8 +132,10 @@ a markdown summary (graph diff + verify + budgets) worth attaching to it.
   gateway with a normalized `cf.cacheKey`; also check that markdown-capable
   routes normalize `Accept` at the gateway when variant fan-out matters.
 - Bundle size: measure what actually deploys — `dist/server/worker.js` plus
-  its `dist/server/server.js` import (wrangler bundles the import graph of
-  `main`; `worker.js` alone is a few lines). Workers limit is ~1 MB
+  its `dist/server/server.js` import and lazy chunks (`no_bundle: true` plus
+  the JavaScript `ESModule` rule uploads the pre-built module graph;
+  `worker.js` alone is a few lines).
+  Workers limit is ~1 MB
   compressed for free tier, ~10 MB on paid. Warn at 80% of the active limit.
 
 ### Vercel (`@pracht/adapter-vercel`)
@@ -156,12 +168,67 @@ a markdown summary (graph diff + verify + budgets) worth attaching to it.
   `passthroughLoader` instead.
 - Build Output API v3 sanity: `config.json` has `version: 3`.
 
+### Static export (`@pracht/adapter-static`)
+
+`adapterTarget` is `"static"`. There is no server to get wrong, so the
+checklist is about what the *host* must do and what the build cannot enforce.
+
+- `dist/client/` exists and is the deploy root. `dist/server/` is build tooling
+  only — it must not be uploaded (it contains the prerender bundle).
+- The build itself is the gate: it fails closed on `ssr`/`isg` routes, SPA
+  loaders, non-full SPA hydration, API routes, route/not-found middleware,
+  network-exposed capabilities, and any Vite `base` that is not `/` or a
+  root-absolute path (CDN and document-relative bases are rejected). If
+  `pracht build` succeeded, those contracts already hold — do not re-derive
+  them by hand. Report a failing build verbatim; the message names the routes.
+- Host must serve `index.html` for directory URLs (clean URLs). Confirm the
+  host's setting: S3 website endpoints need an index document, nginx needs
+  `try_files $uri $uri/index.html`, GitHub Pages and Netlify do it by default.
+- Host must map `404.html` as the error document, otherwise unknown URLs get
+  the host's generic error page instead of the app's `notFound` route. Verify
+  `dist/client/404.html` exists; if it does not, the app declares no `notFound`
+  page — flag it as a `warn`.
+- **Security headers are not applied.** Every other adapter sets the four
+  default security headers at request time; a static host has no request
+  runtime. `dist/server/headers-manifest.json` records the headers each route
+  *would* have carried — mirror the ones you need in the host's own header
+  config (`_headers` on Netlify, CloudFront response header policies, nginx
+  `add_header`). This is an `error` for any app handling user input, and
+  `warn` otherwise. HSTS and CSP are host-side decisions either way.
+- If `staticAdapter({ fallback })` is configured, the host needs a rewrite of
+  unmatched URLs to that file, and the rewrite must not shadow real files.
+  Note that it makes unknown URLs answer `200` (soft 404s). Without the
+  rewrite the fallback file is inert — deep links into dynamic `render: "spa"`
+  routes will 404.
+- Smoke test the real output, not the dev server:
+  `pracht preview --skip-build` serves `dist/client/` the way a dumb host
+  would. Check `/`, one dynamic SSG path, one deep link into a SPA route, and
+  one unknown URL.
+- Routes exporting `markdown` rely on server-side `Accept` negotiation, which
+  a static host cannot do — agents asking for `text/markdown` get HTML. The
+  build prints a note when this applies; publish `.md` files under `public/`
+  if a raw-markdown corpus matters.
+- Deploying to a sub-path (GitHub Pages *project* site, S3 key prefix) needs
+  Vite `base` set to that path (`base: "/my-project/"`). Check it matches the
+  deploy path exactly — a mismatch 404s every asset. Then check the app has no
+  hand-written root-absolute internal links (`<a href="/about">`): those are
+  not base-prefixed and will leave the deploy. `grep -rn 'href="/' src/` and
+  confirm each hit is external, an asset under `public/`, or a `<Link route>`.
+  Framework-owned URLs from `@pracht/image`'s `defaultLoader` and the OpenAPI
+  companion UI/document already carry the base; do not flag their base-free
+  route declarations. Custom image loaders and OpenAPI provider asset URLs
+  still need to match the intended host.
+  CDN bases (`https://cdn…`) and document-relative bases (`""` / `"./"`) are
+  build errors, not sub-path deploys.
+
 ## Step 4: Cross-cutting checks
 
 - Run `audit-secrets` to confirm no `process.env.*` or `context.env.*` values
   flow into loader return values.
 - Run `audit-headers` to confirm `applyDefaultSecurityHeaders` is in use on
   user-facing responses (or that `headers()` exports cover the same ground).
+  On a static export this check moves entirely to the host's header config —
+  see the static section above.
 - Confirm `git status` is clean (deploying uncommitted work is a footgun).
 
 ## Step 5: Report
@@ -179,9 +246,13 @@ status. End with a one-line verdict: `READY` / `BLOCKED (N errors)` /
 3. For Cloudflare/Vercel-edge, the Node-only API check is non-negotiable; an
    API not covered by the active compatibility flags will crash the worker on
    a code path that may never hit in dev.
-4. If the app does not use generated typed route files yet, note that `pracht typegen --check` is optional; if it does, stale generated files block deployment.
-5. Do not deploy on the user's behalf. End the skill at the verdict.
-6. If `pracht doctor` reports errors, do not run any other checks until those
+4. For a static export, never report `READY` without naming the host settings
+   the deploy depends on (clean URLs, `404.html`, security headers, and the
+   fallback rewrite if configured). The build cannot verify any of them, so an
+   unqualified `READY` is the one way this skill can mislead.
+5. If the app does not use generated typed route files yet, note that `pracht typegen --check` is optional; if it does, stale generated files block deployment.
+6. Do not deploy on the user's behalf. End the skill at the verdict.
+7. If `pracht doctor` reports errors, do not run any other checks until those
    are resolved — they will produce noisy false positives.
 
 $ARGUMENTS

package/skills/typed-routes/SKILL.md

@@ -107,8 +107,12 @@ same-origin anchor. It also accepts navigation-behavior props:
 `prefetch="none" | "hover" | "intent" | "viewport" | "render"` (per-link
 prefetch strategy, default `"intent"`), `preserveScroll` (keep the scroll
 position), and `viewTransition` (animate the navigation with the View Transitions API
-where supported). There is also an imperative `prefetch()` export and a
-`useNavigation()` hook for pending navigation/submission state.
+where supported). Set `speculate={false}` on links that browser speculation
+rules must not prefetch or prerender. Because it is independent of the JS
+`prefetch` strategy, use both `speculate={false}` and `prefetch="none"` for GET
+links with side effects. There is also an imperative
+`prefetch()` export and a `useNavigation()` hook for pending
+navigation/submission state.
 
 ### Outside components
 

package/skills/upgrade-pracht/SKILL.md

@@ -33,8 +33,9 @@ pnpm list --depth 1 --json | grep -A2 '@pracht/'   # or read package.json + lock
 
 The family: `@pracht/core`, `@pracht/cli`, `@pracht/vite-plugin`,
 `@pracht/adapter-node`, `@pracht/adapter-cloudflare`, `@pracht/adapter-vercel`,
-`@pracht/preact-ssr-precompile`, `@pracht/image`. Get the latest published
-versions with `npm view <pkg> version`.
+`@pracht/preact-ssr-precompile`, `@pracht/content`, `@pracht/markdown`,
+`@pracht/image`. Get the latest published versions with
+`npm view <pkg> version`.
 
 ## Step 2: Understand the versioning model
 
@@ -75,6 +76,8 @@ https://raw.githubusercontent.com/JoviDeCroock/pracht/main/packages/<dir>/CHANGE
 | `@pracht/vite-plugin` | `packages/vite-plugin` |
 | `@pracht/adapter-node` / `-cloudflare` / `-vercel` | `packages/adapter-*` |
 | `@pracht/preact-ssr-precompile` | `packages/preact-ssr-precompile` |
+| `@pracht/content` | `packages/content` |
+| `@pracht/markdown` | `packages/markdown` |
 | `@pracht/image` | `packages/image` |
 
 Changelogs are changesets-generated: `## X.Y.Z` sections containing