create-pracht 0.4.2 → 0.6.0

package/README.md

@@ -15,12 +15,17 @@ 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, sample API route, runnable project README, TypeScript typecheck script, and 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.
-- Seeds the pracht Claude Code skills into `.claude/skills/` and writes a `.mcp.json` registering the `pracht mcp` server (yes-default prompt; skipped with `--no-agent-tools`).
+- Every standalone pnpm scaffold includes a narrow lifecycle-script policy for
+  its required native dependencies in `pnpm-workspace.yaml`:
+  `onlyBuiltDependencies` for pnpm 10 or `allowBuilds` for pnpm 11. All adapters
+  allow `esbuild`, Cloudflare also allows `workerd`, and Tailwind starters also
+  allow `@tailwindcss/oxide`.
+- Seeds the pracht Claude Code skills into `.claude/skills/`, writes a `.mcp.json` registering the `pracht mcp` server, and writes `AGENTS.md` (yes-default prompt; all of it skipped with `--no-agent-tools`, which leaves a project with no agent files at all).
 - Initializes a git repository with an initial commit (skipped with `--no-git`, when git is unavailable, or when the target is already inside a repository).
 - `--dry-run` uses pinned fallback versions and does not require npm registry access.
 
@@ -30,17 +35,21 @@ npm run dev
 node ./packages/start/bin/create-pracht.js
 node ./packages/start/bin/create-pracht.js my-app --adapter=node --skip-install
 node ./packages/start/bin/create-pracht.js my-app --adapter=vercel --skip-install
+node ./packages/start/bin/create-pracht.js my-app --adapter=netlify --skip-install
+node ./packages/start/bin/create-pracht.js my-app --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|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.
-- `--agent-tools` / `--no-agent-tools` — seed the Claude Code skills and `.mcp.json` (or skip them) without going through the prompt.
+- `--agent-tools` / `--no-agent-tools` — seed the Claude Code skills, `.mcp.json`, and `AGENTS.md`/`CLAUDE.md` (or skip all of them) without going through the prompt.
 - `--no-git` — skip `git init` and the initial commit.
 - `--skip-install` — skip dependency installation.
 - `--yes`, `-y` — accept defaults (node adapter, manifest router, no Tailwind, agent tooling on) and skip all prompts.
@@ -53,11 +62,14 @@ node ./packages/start/bin/create-pracht.js my-app --adapter=node --no-tailwind -
 - `vite.config.ts`
 - `src/routes.ts`
 - `src/routes/home.tsx`
+- `src/routes/not-found.tsx` — the app's 404 page, wired via `notFound` in the manifest (pages scaffolds get `src/pages/404.tsx`, which pracht wires automatically)
 - `src/shells/public.tsx`
-- `src/api/health.ts`
+- `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`)
+- `AGENTS.md` (plus a `CLAUDE.md` symlink pointing at it) — project conventions for coding
+  agents (unless `--no-agent-tools`; `README.md` documents the same commands for humans)
 
 The skills are copied from the repo's [skills/](../../skills/README.md) directory into this
 package at build/publish time (`scripts/sync-skills.js`), so the published npm tarball is
@@ -76,6 +88,12 @@ Cloudflare scaffolds also include:
 
 - `wrangler.jsonc`
 
+Standalone pnpm scaffolds for every adapter include `pnpm-workspace.yaml` with
+the version-appropriate lifecycle policy. When the new app belongs to an
+ancestor pnpm workspace, that workspace owns the policy instead: the generated
+README and completion message list the exact entries to add and no nested
+workspace file is created.
+
 ## Generated Scripts
 
 - `dev` -> `pracht dev`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pracht",
-  "version": "0.4.2",
+  "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