create-pracht 0.5.0 → 0.6.0

package/README.md

@@ -15,9 +15,9 @@ npm run dev
 
 - Prompts for the target folder.
 - Detects the active package manager from the current environment.
-- Lets the user choose between the Node.js, Cloudflare, and Vercel adapters.
+- Lets the user choose between the Node.js, Cloudflare, Vercel, Netlify, and static 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, not-found page, sample API route, runnable project README, TypeScript typecheck script, and (with agent tooling enabled) agent instructions.
+- Scaffolds a minimal app with a route manifest or pages router, shell, home route, not-found page, a sample API route for serverful adapters, 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.
 - Every standalone pnpm scaffold includes a narrow lifecycle-script policy for
@@ -36,13 +36,16 @@ 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 --adapter=static --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|netlify|vercel` — choose the hosting adapter (default: node).
+- `--adapter=node|cf|netlify|vercel|static` — choose the hosting adapter (default: node).
+  `static` scaffolds a pure static export (`@pracht/adapter-static`): no API route is
+  generated, because a static export has no server to answer one.
 - `--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.
@@ -61,7 +64,7 @@ node ./packages/start/bin/create-pracht.js my-app --adapter=node --no-tailwind -
 - `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`
+- `src/api/health.ts` — serverful adapters only
 - `.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`)

package/package.json

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

package/skills/add-i18n/SKILL.md

@@ -1,14 +1,18 @@
 ---
 name: add-i18n
-version: 1.1.0
+version: 2.1.0
 description: |
-  Wire internationalization into a pracht app following the framework's
-  recommended pattern (middleware detects locale, loaders return translations,
-  components consume via route data). Generates locale dictionaries, the
-  detection middleware (URL-prefix, cookie, or `Accept-Language`), and a
-  helper for in-component translation.
+  Wire internationalization into a pracht app with the first-party
+  `@pracht/i18n` package, following the framework's recommended pattern
+  (middleware detects locale, loaders return translations, components
+  consume via route data). Sets up the i18n instance, lazy locale
+  dictionaries with typed keys, the detection middleware (URL-prefix,
+  cookie, and `Accept-Language`), and either strategy: locale-prefixed
+  route groups with hreflang metadata, or one URL per page with a
+  cookie-backed switcher that changes no URLs.
   Use when asked to "add i18n", "set up translations", "make my app
-  multilingual", "add locale routing", or "extract strings".
+  multilingual", "add locale routing", "switch language without changing
+  URLs", or "extract strings".
 allowed-tools:
   - Bash
   - Read
@@ -21,219 +25,372 @@ allowed-tools:
 
 # Pracht Add i18n
 
-Pracht ships no i18n library — the framework gives you primitives. The
-recommended recipe lives at
-`examples/docs/src/routes/docs/recipes-i18n.md`.
+Pracht ships its i18n primitives as `@pracht/i18n`: locale-detection
+middleware, lazy dictionaries with keys typed from the default locale,
+`t()`/`tPlural()` (plurals via `Intl.PluralRules`), `localePath()`, and an
+`hreflang()` helper for `head()`. The full guide lives at
+`examples/docs/src/routes/docs/recipes-i18n.md`; working setups are in
+`examples/basic` — locale-prefixed (`/welcome`, `/en/welcome`,
+`/nl/welcome`) and prefix-free (`/greeting`, `src/api/locale.ts`). That page
+also keeps a hand-rolled fallback recipe if the user refuses the dependency.
 
 If the pracht MCP server is registered (see docs/MCP.md), prefer its tools
 (`inspect_routes`, `inspect_api`, `inspect_build`, `doctor`, `verify`,
 `generate_*`) over shelling out. Prerequisite: `pracht inspect` needs a vite
 config with the pracht plugin registered.
 
-## Step 1: Pick the locale-detection strategy
+## Step 1: Pick locales and a URL strategy
 
-Use `AskUserQuestion`:
+Use `AskUserQuestion` once for: supported locales (default: `en` plus one or
+two more), the default locale, and the **URL strategy**:
 
-| Strategy        | URL shape          | Pros                          | Cons                       |
-| --------------- | ------------------ | ----------------------------- | -------------------------- |
-| URL-prefix      | `/fr/about`        | Best for SEO; explicit        | Requires manifest changes  |
-| Cookie          | `/about` + cookie  | URL stays clean               | Hidden state; SEO weaker   |
-| Accept-Language | `/about` (varies)  | No user action                | Caching/SEO get tricky     |
+- **A. Locale-prefixed URLs** (`/en/about`) — the default for public,
+  indexable content: each language is its own URL, `hreflang()` works, and
+  routes can stay `ssg`/`isg`. Adopting it changes every URL.
+- **B. One URL per page** (`/about`) — for an existing site whose URLs
+  cannot move, or an app behind a login where indexing does not matter. The
+  cookie decides the locale, switching needs no navigation, and no URL
+  changes. Cost: `Vary: Cookie, Accept-Language` makes those routes
+  per-request (`ssr`/`spa`, never `ssg`/`isg`) and a single URL cannot carry
+  hreflang alternates.
 
-Default to **URL-prefix** unless the user explicitly chooses otherwise.
+Ask explicitly if the user already has a live site — never migrate an
+existing app's URLs without saying so. Both strategies can coexist in one
+app on one instance.
 
-## Step 2: Pick the supported locales
+Keep the default detection order `["path", "cookie", "header"]` in both
+cases (the path source simply never matches a prefix-free route); only
+change it when the user explicitly wants cookie-only or header-only
+detection.
 
-Ask once. Default suggestion: `en` plus one to two more. Confirm a default
-locale (used as fallback in `t()`).
+Install the package:
 
-## Step 3: Translation files
-
-`src/i18n/<locale>.ts` per locale:
-
-```ts
-export default {
-  "home.title": "Welcome",
-  "home.subtitle": "Built with pracht",
-  "nav.home": "Home",
-  "nav.about": "About",
-} as const;
+```bash
+npm install @pracht/i18n
 ```
 
-`src/i18n/index.ts`:
+## Step 2: The i18n instance and dictionaries
 
 ```ts
-import en from "./en";
-import fr from "./fr";
+// src/i18n/index.ts
+import { createDictionaries, defineI18n } from "@pracht/i18n";
 
-export const translations = { en, fr } as const;
-export const defaultLocale = "en" as const;
-export const supportedLocales = Object.keys(translations) as Array<keyof typeof translations>;
+export const i18n = defineI18n({
+  locales: ["en", "fr"],
+  defaultLocale: "en",
+});
 
-export type Locale = keyof typeof translations;
-export type TranslationKey = keyof typeof en;
+export type AppLocale = (typeof i18n.locales)[number];
 
-export function t(locale: string, key: TranslationKey): string {
-  const dict = (translations as Record<string, Record<string, string>>)[locale]
-    ?? translations[defaultLocale];
-  return dict[key] ?? translations[defaultLocale][key] ?? key;
-}
+export const dictionaries = createDictionaries(
+  {
+    en: () => import("./locales/en.ts"),
+    fr: () => import("./locales/fr.ts"),
+  },
+  { defaultLocale: "en" },
+);
 ```
 
-## Step 4: Locale-detection middleware
-
-### URL-prefix variant
+One dictionary module per locale — flat string keys, default export,
+`as const` so key typing works:
 
 ```ts
-// src/middleware/i18n.ts
-import type { MiddlewareFn } from "@pracht/core";
-import { defaultLocale, supportedLocales } from "../i18n";
-
-export const middleware: MiddlewareFn = ({ request, url }, next) => {
-  const segments = url.pathname.split("/").filter(Boolean);
-  const maybe = segments[0] ?? "";
-  const locale = (supportedLocales as readonly string[]).includes(maybe) ? maybe : defaultLocale;
-  request.headers.set("x-locale", locale);
-  return next();
-};
+// src/i18n/locales/en.ts
+export default {
+  "home.title": "Welcome, {name}",
+  "cart.items.one": "{count} item",
+  "cart.items.other": "{count} items",
+} as const;
 ```
 
-Caveat: a `/:locale/...` route pattern matches ANY first segment — `/zz/about`
-would happily serve default-locale content at a bogus URL, and search engines
-will index it as duplicate content. Guard against unsupported prefixes in the
-middleware — 404 (or redirect to the default-locale URL) when the first
-segment looks like a locale but isn't supported:
+Plural keys declare one entry per `Intl.PluralRules` category the locale
+needs (`.one`, `.other`, plus `.few`/`.many` for e.g. Polish); `tPlural()`
+falls back to `.other`. Non-default locales may omit keys — `load()` merges
+the default locale underneath.
 
-```ts
-// Add before `return next()` in the URL-prefix middleware:
-if (maybe.length === 2 && !(supportedLocales as readonly string[]).includes(maybe)) {
-  return new Response("Not Found", { status: 404 });
-  // or redirect to the default-locale URL (import `redirect` from "@pracht/core"):
-  // return redirect(`/${url.pathname.split("/").slice(2).join("/")}`, { request });
-}
-```
-
-### Cookie variant
+## Step 3: Detection middleware
 
 ```ts
-import type { MiddlewareFn } from "@pracht/core";
-import { defaultLocale, supportedLocales } from "../i18n";
-
-export const middleware: MiddlewareFn = ({ request }, next) => {
-  const cookie = request.headers.get("cookie") ?? "";
-  const m = cookie.match(/locale=([^;]+)/);
-  const requested = m?.[1] ?? defaultLocale;
-  const locale = (supportedLocales as readonly string[]).includes(requested) ? requested : defaultLocale;
-  request.headers.set("x-locale", locale);
-  return next();
-};
-```
-
-### Accept-Language variant
+// src/middleware/i18n.ts
+import { i18n } from "../i18n/index.ts";
 
-```ts
-import type { MiddlewareFn } from "@pracht/core";
-import { defaultLocale, supportedLocales } from "../i18n";
-
-export const middleware: MiddlewareFn = ({ request }, next) => {
-  const header = request.headers.get("accept-language") ?? "";
-  const preferred = header.split(",").map(p => p.split(";")[0]?.trim().toLowerCase().slice(0, 2));
-  const match = preferred.find(p => (supportedLocales as readonly string[]).includes(p));
-  request.headers.set("x-locale", match ?? defaultLocale);
-  return next();
-};
+export const middleware = i18n.middleware;
 ```
 
-## Step 5: Use in a loader
+The middleware sets `context.locale` and persists URL-prefix choices in a
+`SameSite=Lax` cookie — but only on per-request (SSR/SPA) routes: SSG/ISG
+output is stored and replayed to every visitor, so the middleware never
+attaches `Set-Cookie` there (a baked-in cookie would fail the prerender
+build and block ISG revalidation). It also appends `Vary: Cookie` /
+`Accept-Language` when those sources were consulted. Path-resolved SSR/SPA
+responses vary on `Cookie` too, because the presence of their persistence
+`Set-Cookie` depends on the incoming cookie; path-only SSG/ISG output stays
+keyed solely by URL. Type the context once via the Register pattern:
+
+Cookie configuration stays browser-valid: `SameSite=None` always forces
+`Secure`, even if an explicit option attempts to disable it.
 
 ```ts
-import type { LoaderArgs } from "@pracht/core";
-import { t } from "../i18n";
+// src/env.d.ts
+import type { I18nRequestContext } from "@pracht/i18n";
 
-export async function loader({ request }: LoaderArgs) {
-  const locale = request.headers.get("x-locale") ?? "en";
-  return {
-    locale,
-    title: t(locale, "home.title"),
-    subtitle: t(locale, "home.subtitle"),
-  };
+declare module "@pracht/core" {
+  interface Register {
+    context: I18nRequestContext<"en" | "fr">;
+  }
 }
 ```
 
-## Step 6: Wire the manifest
+Intersect with the existing registered context type if the app already has
+one.
 
-For the URL-prefix strategy, the routes need to live under per-locale
-groups. Update `src/routes.ts`:
+## Step 4: Wire the manifest
+
+### Strategy A — locale-prefixed URLs
+
+One `pathPrefix` group per locale — only registered locales produce URLs, so
+`/zz/about` 404s instead of serving duplicate default-locale content (never
+use a `/:locale` param route for this; it matches any first segment):
 
 ```ts
 import { defineApp, group, route } from "@pracht/core";
 
+const localizedRoutes = [
+  route("/", "./routes/home.tsx", { render: "ssr" }),
+  route("/about", "./routes/about.tsx", { render: "ssr" }),
+];
+
 export const app = defineApp({
   middleware: { i18n: "./middleware/i18n.ts" },
   routes: [
     group({ middleware: ["i18n"] }, [
-      route("/", "./routes/home.tsx", { id: "home-default" }),
-      route("/:locale/", "./routes/home.tsx", { id: "home-localized" }),
-      route("/:locale/about", "./routes/about.tsx"),
+      group({ pathPrefix: "/en" }, localizedRoutes),
+      group({ pathPrefix: "/fr" }, localizedRoutes),
+      route("/", "./routes/locale-redirect.tsx", { render: "ssr" }),
     ]),
   ],
 });
 ```
 
-For cookie / Accept-Language strategies, just add the middleware to the root
-group; no path changes.
+Notes:
 
-This step restructures route paths (`/` → `/:locale/...`), so route ids and
-generated types change — `pracht typegen` in the verification step is
-mandatory, not optional.
+- Reusing one `localizedRoutes` array is fine with auto-generated ids; if
+  the app sets explicit `id`s, each locale's copy needs unique ids.
+- The unprefixed detector redirects using what the middleware resolved.
+  `return` the redirect — a *thrown* Response short-circuits past the
+  middleware chain, so the i18n middleware could not stamp
+  `Vary: Cookie, Accept-Language` on it (a shared cache could then replay
+  one visitor's locale redirect to everyone):
 
-## Step 7: SEO touch-ups
+```ts
+// src/routes/locale-redirect.tsx
+import { redirect, type LoaderArgs } from "@pracht/core";
+import { i18n } from "../i18n/index.ts";
 
-- Set `lang` in `head()` per route from the resolved locale.
-- For URL-prefix: emit `<link rel="alternate" hreflang="fr" href="...">`
-  pairs in `head()` so search engines learn the locale graph.
-- Update sitemap (cross-reference with `audit-seo`) to include all
-  per-locale URLs.
+export async function loader({ context, request }: LoaderArgs) {
+  return redirect(i18n.localePath("/", context.locale), { request });
+}
 
-## Step 8: String extraction (optional)
+export function Component() {
+  return null;
+}
+```
+
+- Route matching is exact: locale prefixes are lowercase URLs; build links
+  with `i18n.localePath()` so they always come out canonical. It resolves
+  literal and encoded dot segments before prefixing, so even a path assembled
+  from user input cannot escape the locale namespace during browser URL
+  normalization.
+- If localized routes are SSG/ISG, their stored response cannot safely carry
+  a visitor-specific `Set-Cookie`. In a hydrated component shared by those
+  routes, persist the explicit prefix with
+  `useEffect(() => { i18n.setLocaleCookie(data.locale); }, [data.locale])` so the
+  SSR detector remembers it later. This is harmless on SSR pages. Without
+  JavaScript, remembering a prerendered visit requires SSR or platform edge
+  middleware before static asset serving.
+
+### Strategy B — one URL per page
+
+Nothing about the routes changes: add the middleware to the group and skip
+the prefix groups and the detector route entirely. Detection falls to the
+cookie, then `Accept-Language`; the middleware adds
+`Vary: Cookie, Accept-Language`, so keep those routes `ssr`/`spa`.
+
+Because no URL prefix ever signals an explicit choice, the *switcher* writes
+the cookie. Generate an API route (works with JavaScript disabled):
 
-First create `scripts/i18n-extract.mjs`, a script that:
+```ts
+// src/api/locale.ts
+import { redirect, type BaseRouteArgs } from "@pracht/core";
+import { i18n } from "../i18n/index.ts";
+
+function sameOriginPath(value: FormDataEntryValue | null, base: URL, fallback: string): string {
+  if (typeof value !== "string" || !value.startsWith("/")) return fallback;
+  try {
+    const target = new URL(value, base);
+    return target.origin === base.origin
+      ? `${target.pathname}${target.search}${target.hash}`
+      : fallback;
+  } catch {
+    return fallback;
+  }
+}
 
-1. Greps for `t(locale, "...")` calls.
-2. Builds a key set.
-3. Diffs against each `src/i18n/<locale>.ts`.
-4. Reports missing keys per locale.
+export async function POST({ request, url }: BaseRouteArgs) {
+  const form = await request.formData();
+  const locale = form.get("locale");
+  if (!i18n.isLocale(locale)) return new Response("Unknown locale", { status: 400 });
 
-Then run it:
+  // Parse `next` before trusting it: URL normalization can expose an origin.
+  const next = form.get("next");
+  const target = sameOriginPath(next, url, "/");
 
-```bash
-node scripts/i18n-extract.mjs
+  const response = redirect(target, { request, status: 303 });
+  response.headers.append("set-cookie", i18n.localeCookie(locale, { url }));
+  return response;
+}
 ```
 
-The output is a TODO list per locale, not auto-translation.
+…and a `<Form method="post" action="/api/locale">` switcher with one
+`<button name="locale" value={locale}>` per locale plus a hidden `next`
+field carrying `useLocation().pathname + useLocation().search` so switching
+does not drop the current query. Hydrated, `<Form>` uses the framework's
+redirect handshake and re-runs the loader; without JavaScript the browser
+follows the 303 normally.
+
+For an instant switch with no request at all, `i18n.setLocaleCookie(locale)`
+writes the same cookie from the browser and
+`await dictionaries.load(locale)` swaps the dictionary in place — hold the
+result in state, reset it when loader data changes, and set both
+`document.documentElement.lang` and a localized `document.title` by hand
+(`head()` already ran server-side).
+Load the dictionary before writing the cookie, and guard concurrent lazy
+loads with a monotonically increasing request id so only the latest successful
+selection commits both the cookie and component state. Catch import failures
+instead of leaving an unhandled event-handler rejection or a partially applied
+locale choice. Invalidate that request id from a `useLayoutEffect` cleanup
+keyed by loader messages so a loader-data change or unmount wins during commit;
+a passive `useEffect` cleanup leaves time for a stale import to write its cookie.
+Also increment the shared request id synchronously in the server switcher's
+`<Form onSubmit>` and before any other navigation that can replace loader data.
+Cleanup at commit cannot undo a stale cookie written while that transition was
+still in flight.
+`i18n.detectClient()` is the browser-side `detect()` if a client-only
+surface needs to resolve the locale itself.
+
+## Step 5: Use in loaders and components
+
+```tsx
+import type { HeadArgs, LoaderArgs, RouteComponentProps } from "@pracht/core";
+import { t, tPlural } from "@pracht/i18n";
+import { dictionaries, i18n } from "../i18n/index.ts";
+import { useEffect } from "preact/hooks";
+
+export async function loader({ context }: LoaderArgs) {
+  const messages = await dictionaries.load(context.locale);
+  return { locale: context.locale, messages };
+}
+
+export function head({ data, url }: HeadArgs<typeof loader>) {
+  return {
+    lang: data.locale,
+    title: t(data.messages, "home.title"),
+    link: i18n.hreflang(url.pathname, { origin: "https://example.com" }),
+  };
+}
+
+export function Component({ data }: RouteComponentProps<typeof loader>) {
+  // Required for SSG/ISG locale routes; harmless when SSR middleware already
+  // persisted the matching path locale.
+  useEffect(() => {
+    i18n.setLocaleCookie(data.locale);
+  }, [data.locale]);
+  return <h1>{t(data.messages, "home.title", { name: "Jovi" })}</h1>;
+}
+```
+
+`messages` is a plain serializable object, so the same `t()` calls work
+after hydration and on client navigations. `hreflang()` emits one alternate
+link per locale plus `x-default` pointing at the unprefixed detector; pass
+the app's canonical origin. Relative previews remain current-origin because
+`splitLocale()` always keeps the stripped pathname root-relative, and every
+alternate preserves an input query/hash suffix. Under strategy B, omit the
+`link` entry: there is no alternate URL to point at, so emitting hreflang
+would be a lie.
+
+## Step 6: SEO touch-ups
+
+- Set `lang` from the resolved locale in `head()` (as above).
+- Keep the detector route SSR; locale-prefixed routes may be `ssg` or
+  `isg` — every prefixed URL is a real route, so each locale prerenders,
+  and the middleware skips cookie persistence on those routes so no
+  `Set-Cookie` lands in stored output. Persist the resolved path locale after
+  hydration when the SSR detector should remember it; without JavaScript,
+  use SSR or platform edge middleware. Keep `"path"` first in the detect order
+  for prerendered routes: cookie/header detection cannot run against a stored
+  document (prerender/ISG requests carry no cookies or `Accept-Language`), and
+  a route that *depends* on those sources gets `Vary: Cookie` and is refused by
+  the ISG cache.
+- Prerendered `head()` runs against a placeholder request origin — pass the
+  app's canonical origin to `hreflang()` on SSG/ISG routes instead of
+  `url.origin`, or the alternates bake in `http://localhost`.
+- Update the sitemap (cross-reference with `audit-seo`) to include all
+  per-locale URLs.
+- Strategy B only: one URL means one indexed language (whatever the
+  crawler's `Accept-Language` resolves to). Say this out loud to the user;
+  if it matters, that is the argument for strategy A. Still set `lang`, and
+  leave sitemap entries as the single canonical URLs they already are.
 
-## Step 9: Verify
+## Step 7: Verify
 
-- Step 6 changed route paths — run `pracht typegen` to refresh the generated
-  route types/`href()` helper. Add `pracht typegen --check` to CI so stale
-  types fail the build.
+- If step 4 changed route paths (strategy A) or added the API route, run
+  `pracht typegen` to refresh the generated route types/`href()` helper. Add
+  `pracht typegen --check` to CI so stale types fail the build.
 - Boot dev: `pracht dev`.
-- Visit `/` and the locale-prefixed variant; confirm content swaps.
-- Visit an unsupported prefix (e.g. `/zz/about`); confirm the middleware
-  404s or redirects rather than serving default-locale content.
+- Strategy A: `curl -i` the unprefixed detector with `Accept-Language: fr`
+  (expect a 302 to `/fr/...`), with a `pracht_locale` cookie (cookie beats
+  header), and with garbage (`;q=`, unknown tags — expect the default
+  locale). Visit a locale-prefixed page; confirm translated content and the
+  hreflang links in the head. On SSR, confirm `Set-Cookie` on first visit and
+  `Vary: Cookie` whether or not the request cookie already matches. On SSG/ISG,
+  confirm the stored response has neither `Set-Cookie` nor a path-only `Vary`, hydration writes
+  the locale cookie, and then the unprefixed detector returns to that locale.
+  Visit an unsupported prefix (e.g. `/zz/about`); confirm it 404s.
+- Strategy B: `curl -i` the page with `Accept-Language: fr` (expect French
+  content, `Vary: Cookie, Accept-Language`, no `Set-Cookie`) and with
+  `Cookie: pracht_locale=fr` while sending `Accept-Language: en` (cookie
+  wins). `curl -i -X POST` the switcher with `-d locale=fr` and an
+  `Origin` header matching the host (mutation API routes are
+  same-origin-checked): expect a 303 plus `Set-Cookie`. Post an unregistered
+  locale and an off-origin `next`; expect a 400 and a same-origin redirect.
+  In the browser, switch and confirm the URL never changes.
 - `pnpm test` and `pnpm e2e` still pass.
 - Run `pracht verify --json` and confirm no failures.
 
 ## Rules
 
-1. The middleware sets a request header; loaders read it. Do not stash the
+1. The middleware sets `context.locale`; loaders read it. Do not stash the
    locale in module-level state — concurrent requests will collide.
-2. Always include the default locale as the fallback in `t()`.
-3. For SSG, only prerender the URL combinations that exist; provide
-   `getStaticPaths` returning the locale × dynamic-param product.
-4. Recommend `Intl.DateTimeFormat` and `Intl.NumberFormat` for formatting —
-   no library needed.
-5. Never bundle every translation into the client. If translations grow
-   large, split per-locale and import lazily in loaders.
+2. Only registered locales may ever reach paths, cookies, or hreflang.
+   `defineI18n`/`localePath` enforce this — never bypass them with string
+   concatenation on user input. `localePath` also resolves dot segments before
+   adding the locale prefix. Accept-Language wildcard fallbacks are resolved
+   through the registered locale list, respect explicit `q=0` exclusions, and
+   neither lookup truncation nor best-fit fallback can bypass those exclusions.
+   Directly matched longer variants win before same-language best fit, which
+   never crosses conflicting script subtags. If the defensive header-length
+   limit cuts an entry in half, discard that entry rather than parsing it with
+   an implied quality of 1.
+3. For SSG, only prerender URL combinations that exist; provide
+   `getStaticPaths` returning the locale × dynamic-param product when a
+   localized route has dynamic segments.
+4. Recommend `Intl.DateTimeFormat` and `Intl.NumberFormat` with
+   `data.locale` for formatting — no library needed.
+5. Never bundle every translation into the client: `createDictionaries`
+   loaders are per-locale lazy imports resolved in loaders; keep them that
+   way.
+6. Never move an existing app's URLs without asking. Locale prefixes are a
+   strategy, not a requirement — if the user says their URLs are fixed,
+   strategy B is the answer, not a redirect table.
 
 $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

@@ -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"` |
@@ -452,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}`,
@@ -468,7 +468,7 @@ export async function POST({ request }: ApiRouteArgs) {
   });
   return new Response(null, {
     status: 303,
-    headers: { location: "/posts" },
+    headers: { location: withBase("/posts") },
   });
 }
 ```
@@ -511,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,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
 
@@ -249,10 +266,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 +326,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`)
 
@@ -156,12 +162,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 +240,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/src/index.js

@@ -16,10 +16,11 @@ const FALLBACK_VERSION_RANGES = {
   "@pracht/adapter-cloudflare": "^0.5.8",
   "@pracht/adapter-netlify": "^0.1.0",
   "@pracht/adapter-node": "^0.3.8",
+  "@pracht/adapter-static": "^0.1.0",
   "@pracht/adapter-vercel": "^0.2.8",
-  "@pracht/cli": "^1.9.0",
-  "@pracht/core": "^0.12.0",
-  "@pracht/vite-plugin": "^0.7.6",
+  "@pracht/cli": "^1.11.0",
+  "@pracht/core": "^0.14.0",
+  "@pracht/vite-plugin": "^0.9.0",
   "@tailwindcss/vite": "^4.1.0",
   "netlify-cli": "^21.6.0",
   tailwindcss: "^4.1.0",
@@ -87,6 +88,13 @@ const ADAPTERS = {
     packageName: "@pracht/adapter-vercel",
     short: "vercel",
   },
+  static: {
+    description: "Pure static export — deploy dist/client to any static host",
+    id: "static",
+    label: "Static export",
+    packageName: "@pracht/adapter-static",
+    short: "static",
+  },
 };
 
 const DEFAULT_DIRECTORY = "pracht-app";
@@ -407,7 +415,7 @@ export function parseArgs(argv) {
       const value = normalizeAdapter(arg.slice("--adapter=".length));
       if (!value) {
         throw new ValidationError(
-          `Invalid adapter: ${arg.slice("--adapter=".length)}. Use node, cf, netlify, or vercel.`,
+          `Invalid adapter: ${arg.slice("--adapter=".length)}. Use node, cf, netlify, vercel, or static.`,
         );
       }
       options.adapter = value;
@@ -462,6 +470,7 @@ async function promptForAdapter(readline) {
   console.log("  2. Cloudflare Workers");
   console.log("  3. Vercel");
   console.log("  4. Netlify");
+  console.log("  5. Static export (no server)");
 
   while (true) {
     const answer = await readline.question("Adapter (1): ");
@@ -471,7 +480,7 @@ async function promptForAdapter(readline) {
       return normalized;
     }
 
-    console.log("Choose 1/2/3/4 or node/cf/vercel/netlify.");
+    console.log("Choose 1/2/3/4/5 or node/cf/vercel/netlify/static.");
   }
 }
 
@@ -614,6 +623,10 @@ function normalizeAdapter(value) {
     return "netlify";
   }
 
+  if (normalized === "5" || normalized === "static" || normalized === "export") {
+    return "static";
+  }
+
   return null;
 }
 
@@ -690,11 +703,16 @@ async function buildProjectFiles({
       tailwind,
       versions,
     }),
-    "src/api/health.ts": createHealthRoute(adapter),
     "vite.config.ts": createViteConfig(adapter, router, tailwind),
     "tsconfig.json": createBaseTSConfig(adapter),
   };
 
+  // A static export has no server, so an API route would be a hard build
+  // error — the starter must not scaffold one it cannot build.
+  if (adapter.id !== "static") {
+    files["src/api/health.ts"] = createHealthRoute(adapter);
+  }
+
   if (agentTools) {
     files["AGENTS.md"] = createAgentInstructions({
       adapter,
@@ -803,6 +821,10 @@ function createPackageJson({ adapter, projectName, tailwind, versions }) {
     scripts.start = "node dist/server/server.js";
   }
 
+  if (adapter.id === "static") {
+    scripts.preview = "pracht preview";
+  }
+
   const devDependencies = {
     "@pracht/cli": versions["@pracht/cli"],
     "@pracht/vite-plugin": versions["@pracht/vite-plugin"],
@@ -858,6 +880,7 @@ function createViteConfig(adapter, router, tailwind) {
     cloudflare: { fn: "cloudflareAdapter", pkg: "@pracht/adapter-cloudflare" },
     netlify: { fn: "netlifyAdapter", pkg: "@pracht/adapter-netlify" },
     vercel: { fn: "vercelAdapter", pkg: "@pracht/adapter-vercel" },
+    static: { fn: "staticAdapter", pkg: "@pracht/adapter-static" },
   };
 
   const info = ADAPTER_IMPORTS[adapter.id] ?? ADAPTER_IMPORTS.node;
@@ -955,7 +978,9 @@ function createHomeRoute(adapter) {
     "    steps: [",
     '      "Edit src/routes/home.tsx to change this page.",',
     '      "Add more routes in src/routes.ts.",',
-    '      "Add API handlers in src/api/*.ts.",',
+    adapter.id === "static"
+      ? '      "Fetch live data from the browser — a static export runs no server.",'
+      : '      "Add API handlers in src/api/*.ts.",',
     "    ],",
     "  };",
     "}",
@@ -974,7 +999,9 @@ function createHomeRoute(adapter) {
     "        ))}",
     "      </ul>",
     '      <p style={{ marginTop: "24px" }}>',
-    "        Check <code>/api/health</code> for a simple API route.",
+    adapter.id === "static"
+      ? "        Run <code>pracht build</code>, then deploy <code>dist/client</code> anywhere."
+      : "        Check <code>/api/health</code> for a simple API route.",
     "      </p>",
     "    </section>",
     "  );",
@@ -1022,7 +1049,9 @@ function createPagesHomeRoute(adapter) {
     "    steps: [",
     '      "Edit src/pages/index.tsx to change this page.",',
     '      "Add more pages in src/pages/.",',
-    '      "Add API handlers in src/api/*.ts.",',
+    adapter.id === "static"
+      ? '      "Fetch live data from the browser — a static export runs no server.",'
+      : '      "Add API handlers in src/api/*.ts.",',
     "    ],",
     "  };",
     "}",
@@ -1041,7 +1070,9 @@ function createPagesHomeRoute(adapter) {
     "        ))}",
     "      </ul>",
     '      <p style={{ marginTop: "24px" }}>',
-    "        Check <code>/api/health</code> for a simple API route.",
+    adapter.id === "static"
+      ? "        Run <code>pracht build</code>, then deploy <code>dist/client</code> anywhere."
+      : "        Check <code>/api/health</code> for a simple API route.",
     "      </p>",
     "    </section>",
     "  );",
@@ -1410,7 +1441,12 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
     `- \`${runCmd} build\` — production build`,
   ];
 
-  if (adapter.id === "node" || adapter.id === "cloudflare" || adapter.id === "netlify") {
+  if (
+    adapter.id === "node" ||
+    adapter.id === "cloudflare" ||
+    adapter.id === "netlify" ||
+    adapter.id === "static"
+  ) {
     lines.push(`- \`${runCmd} preview\` — build and serve the production build locally`);
   }
 
@@ -1430,10 +1466,14 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
   lines.push("- `pracht generate route --path /about` — add a route");
   if (router !== "pages") {
     lines.push("- `pracht generate shell --name app` — add a shell");
-    lines.push("- `pracht generate middleware --name auth` — add middleware");
+    if (adapter.id !== "static") {
+      lines.push("- `pracht generate middleware --name auth` — add middleware");
+    }
   }
-  lines.push("- `pracht generate api --path /health --methods GET` — add an API route");
-  if (router !== "pages") {
+  if (adapter.id !== "static") {
+    lines.push("- `pracht generate api --path /health --methods GET` — add an API route");
+  }
+  if (router !== "pages" && adapter.id !== "static") {
     lines.push(
       "- `pracht generate capability --name notes.search --effect read --expose http` — add a capability (agent-callable operation)",
     );
@@ -1473,7 +1513,9 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
     lines.push("- `src/shells/` — shell components (layouts)");
   }
 
-  lines.push("- `src/api/` — API route handlers");
+  if (adapter.id !== "static") {
+    lines.push("- `src/api/` — API route handlers");
+  }
   lines.push(`- \`vite.config.ts\` — Vite config with the ${adapter.label} adapter`);
 
   if (tailwind) {
@@ -1576,6 +1618,21 @@ function createReadme({
     lines.push("Run the deploy command after linking or logging into your Vercel account.");
   }
 
+  if (adapter.id === "static") {
+    lines.push(`- \`${previewCommand}\``);
+    lines.push("");
+    lines.push(
+      "`pracht build` writes the whole site to `dist/client`. Upload that directory to any " +
+        "static host — there is no server to run. Configure the host to serve `index.html` " +
+        "for directory URLs and to use `404.html` as its error document.",
+    );
+    lines.push("");
+    lines.push(
+      "A static export runs no server, so API routes, middleware, and `ssr`/`isg` routes are " +
+        "build errors. Fetch live data from the browser instead, or switch to a serverful adapter.",
+    );
+  }
+
   lines.push("");
   lines.push("## Files");
   lines.push("");
@@ -1597,7 +1654,9 @@ function createReadme({
     lines.push("- `src/routes/not-found.tsx` is the not-found page, wired via `notFound`.");
   }
 
-  lines.push("- `src/api/health.ts` is a sample API route.");
+  if (adapter.id !== "static") {
+    lines.push("- `src/api/health.ts` is a sample API route.");
+  }
 
   if (packageManager === "pnpm") {
     lines.push(
@@ -1791,7 +1850,7 @@ Usage:
   create-pracht [directory] [options]
 
 Options:
-  --adapter=node|cf|netlify|vercel
+  --adapter=node|cf|netlify|vercel|static
                                Choose hosting adapter (default: node)
   --router=manifest|pages      Choose routing system (default: manifest)
   --template=minimal|tailwind  Choose starter template (minimal, or minimal + Tailwind CSS)