create-pracht 0.7.1 → 0.7.3

package/fallback-versions.json

@@ -0,0 +1,20 @@
+{
+  "@pracht/adapter-cloudflare": "^0.8.1",
+  "@pracht/adapter-netlify": "^0.3.1",
+  "@pracht/adapter-node": "^0.5.1",
+  "@pracht/adapter-static": "^0.2.1",
+  "@pracht/adapter-vercel": "^0.4.1",
+  "@pracht/capabilities": "^0.6.1",
+  "@pracht/cli": "^1.16.0",
+  "@pracht/content": "^0.2.0",
+  "@pracht/core": "^0.20.0",
+  "@pracht/i18n": "^0.1.6",
+  "@pracht/image": "^0.5.0",
+  "@pracht/markdown": "^0.1.5",
+  "@pracht/openapi": "^0.2.7",
+  "@pracht/preact-ssr-precompile": "^0.1.4",
+  "@pracht/query": "^0.1.1",
+  "@pracht/session": "^0.1.3",
+  "@pracht/test": "^0.3.1",
+  "@pracht/vite-plugin": "^0.15.0"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pracht",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Interactive and scriptable starter CLI for creating full-stack Preact apps with Pracht.",
   "keywords": [
     "pracht",
@@ -30,6 +30,7 @@
     "bin",
     "src",
     "skills",
+    "fallback-versions.json",
     "README.md"
   ],
   "type": "module",
@@ -40,6 +41,6 @@
     "provenance": true
   },
   "scripts": {
-    "build": "node ./scripts/sync-skills.js"
+    "build": "node ./scripts/sync-skills.js && node ./scripts/sync-versions.js"
   }
 }

package/skills/add-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-auth
-version: 2.1.0
+version: 2.1.1
 description: |
   Wire session-based auth into a pracht app with `@pracht/session`: encrypted
   cookie sessions, gate middleware, login/logout/signup API routes, `<Form>`
@@ -170,23 +170,40 @@ Workers, measure a login against the plan's CPU limit.
 
 ## Step 5: Auth API routes
 
+`src/server/redirects.ts` — the one gate for every request-derived redirect
+target. Never use a `startsWith("/") && !startsWith("//")` prefix check: URL
+parsing turns `\` into `/`, so `/\evil.com` passes it and lands off-origin.
+
+```ts
+export function safeRedirectPath(value: unknown, 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;
+  }
+}
+```
+
 `src/api/auth/login.ts`:
 
 ```ts
 import { redirect, type ApiRouteArgs } from "@pracht/core";
 
+import { safeRedirectPath } from "../../server/redirects.ts";
 import { sessions } from "../../server/session.ts";
 import { verifyCredentials } from "../../server/users.ts";
 
-export async function POST({ request }: ApiRouteArgs) {
+export async function POST({ request, url }: ApiRouteArgs) {
   const form = await request.formData();
   const email = String(form.get("email") ?? "");
   const password = String(form.get("password") ?? "");
 
   // The redirect field is user input — gate it, or this is an open redirect.
-  const requested = String(form.get("redirect") ?? "/dashboard");
-  const target =
-    requested.startsWith("/") && !requested.startsWith("//") ? requested : "/dashboard";
+  const target = safeRedirectPath(form.get("redirect"), url, "/dashboard");
 
   const user = await verifyCredentials(email, password);
   if (!user) {
@@ -226,11 +243,12 @@ export async function POST({ request }: ApiRouteArgs) {
 ```tsx
 import { Form, type LoaderArgs, type RouteComponentProps } from "@pracht/core";
 
+import { safeRedirectPath } from "../server/redirects.ts";
+
 export async function loader({ url }: LoaderArgs) {
-  const requested = url.searchParams.get("redirect") ?? "/dashboard";
   return {
     error: url.searchParams.get("error") === "1",
-    redirect: requested.startsWith("/") && !requested.startsWith("//") ? requested : "/dashboard",
+    redirect: safeRedirectPath(url.searchParams.get("redirect"), url, "/dashboard"),
   };
 }
 

package/skills/add-content/SKILL.md

@@ -180,6 +180,15 @@ the *authoring guide* for coding agents; `pracht llms --write` drops it in the
 app root, which is exactly the confusing filename collision to avoid in an app
 that publishes its own index.
 
+For agents, link entries to Markdown and split the full text by section:
+`` link: (document) => `${document.path}.md` `` (only when those URLs exist,
+e.g. via `rawContentArtifacts()`), and `fullPath: "/llms-guides.txt"` on a
+section to emit a file with just its pages (with `origin` set, each page gets
+a `Source:` line with its page URL; `sort` orders a section's entries). Section files and
+`/llms-full.txt` are listed under a trailing `## Optional` heading; a section
+that matches nothing emits no file. Duplicate or file/directory-colliding
+artifact paths throw when the helper is defined.
+
 Localization trap: a string `section.match` is compared against the
 **locale-neutral** route, so `match: "/docs"` indexes only the default locale
 while `rawContentArtifacts()` publishes every translation. Pass a `match`

package/skills/add-db/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: add-db
-version: 1.2.0
+version: 1.2.1
 description: |
   Wire Drizzle ORM into a pracht app: pick the target (D1, PlanetScale, Neon,
   Supabase, Turso, Postgres, MySQL, SQLite), then generate driver setup, schema,
@@ -93,11 +93,13 @@ export const db = drizzle(pool, { schema });
 ```
 
 For Cloudflare D1, register the Cloudflare context type once via the `Register`
-augmentation (the pattern in
-`examples/docs/src/routes/docs/recipes-fullstack-cloudflare.md`):
+augmentation. Keep the `import`: without it the file is a global script and the
+declaration replaces `@pracht/core`'s types instead of extending them.
 
 ```ts
 // src/env.d.ts
+import "@pracht/core";
+
 declare module "@pracht/core" {
   interface Register {
     context: {

package/skills/add-images/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: add-images
-version: 1.0.1
+version: 1.1.0
 description: |
   Wire `@pracht/image`: the CLS-safe zero-runtime `<Image>`, the loader for your
-  target (sharp endpoint, Cloudflare, Vercel, passthrough), `?pracht` build-time
+  target (sharp endpoint, Cloudflare, Vercel, Netlify, passthrough), `?pracht` build-time
   imports with blur placeholders, prebuilt WebP variants, and the optimization
   endpoint's security settings.
   Use for "add images", "optimize images", "responsive images", "next/image
@@ -39,6 +39,7 @@ pracht inspect build --json   # adapterTarget (requires a prior `pracht build`)
 | Node | `defaultLoader` + the built-in endpoint | needs `sharp`; put a CDN in front |
 | Cloudflare | `cloudflareLoader` | Image Resizing must be enabled on the zone; sharp does not run on Workers |
 | Vercel | `vercelLoader` | needs an `images` section in the project config; Vercel only serves widths listed in `images.sizes` |
+| Netlify | `netlifyLoader` | Image CDN; remote sources need `images.remote_images` in `netlify.toml`; no sharp endpoint |
 | Static host | `passthroughLoader` | no image service — srcset is omitted |
 | Any target, no runtime service | `?pracht&pracht-static` imports | prebuilt WebP variants, no loader involved |
 
@@ -76,9 +77,22 @@ configureImage({
 
 `createDefaultLoader("/my/endpoint")` builds a default-style loader for a custom
 endpoint path. Root-absolute endpoints pick up Vite's deploy `base`
-automatically; provider loaders (`cloudflareLoader`, `vercelLoader`)
+automatically; provider loaders (`cloudflareLoader`, `vercelLoader`, `netlifyLoader`)
 deliberately stay at the origin root.
 
+For Netlify, use `configureImage({ loader: import.meta.env.DEV ?
+passthroughLoader : netlifyLoader })` so `pracht dev` renders original images.
+Import both loaders from `@pracht/image`. For remote sources, merge the
+allowed URL patterns into the existing `netlify.toml`:
+
+```toml
+[images]
+remote_images = ['https://images\.example\.com/.*']
+```
+
+Local source files need no image-service configuration; Netlify negotiates
+the output format and caches resized images. Skip the Node endpoint step.
+
 ## Step 4: Render images
 
 ```tsx

package/skills/add-observability/SKILL.md

@@ -48,6 +48,12 @@ but trivial.
 
 ## Step 2: Server error tracking
 
+Pracht already prints one line per 5xx to the server console — phase, route id,
+source file, request path, message, and the stack — so the app is not silent
+before any of this is wired. What that default does not give you is a request
+id, a duration, the successful requests, or delivery to a sink off the box.
+Say so when the user only wants "errors in my logs": they may already have it.
+
 ### Sentry path (Node adapter)
 
 The pattern below uses `@sentry/node` and works on the **Node adapter only**
@@ -274,10 +280,13 @@ Key properties to state when scaffolding this:
 - Delivery snapshots the registered sinks before callbacks run. Adding or
   replacing a sink from inside a callback takes effect on the next dispatch,
   so the current event is never delivered twice to one name.
-- On Cloudflare Workers, a batching exporter must flush within the request or
-  be handed the execution context by app code
-  (`context.executionContext.waitUntil(exporter.flush())`). Pracht does not
-  call `ctx.waitUntil()` for a sink.
+- A sink's returned promise is handed to the request's `waitUntil()`, so an
+  `async` sink finishes after the response on every adapter (Cloudflare
+  `ctx.waitUntil`, Netlify/Vercel `context.waitUntil`, Node's shutdown drain)
+  and its rejection is reported. A batching exporter that flushes on its own
+  schedule should be flushed from middleware with
+  `args.waitUntil(exporter.flush())` — never reach for
+  `context.executionContext.waitUntil`.
 - Audit events cover *dispatch* only. A cross-origin 403, an unknown-capability
   404, and an unknown MCP tool name all return before dispatch and emit
   nothing, so do not build a reconnaissance alert on these events — use the

package/skills/audit-agent-surface/SKILL.md

@@ -238,17 +238,18 @@ With `agents.mcp.auth`, check:
 ## Step 5: The discovery surface
 
 - `llmsTxt` in the vite config: every listed path is a URL the app *invites* an
-  agent to fetch. Cross-check the `exclude` list against routes behind auth
-  middleware, internal tooling, and deliberate error routes — nothing about a
-  middleware tells the framework whether it gates or merely logs, so an
-  auth-gated route missing from `exclude` is a `warn` (see `docs/LLMS_TXT.md`).
+  agent to fetch. An auth-gated route missing from `exclude` is a `warn`: the
+  framework cannot tell a gating middleware from a logging one.
   Capabilities appear there with their effect class; destructive ones are
   annotated `requires confirmation`.
 - A collection-driven `llmsTxtArtifacts()` (see `/add-content`) is a second
-  generator with its own coverage — compare what each publishes.
+  generator; compare what each publishes.
 - Routes exporting `markdown` or declaring `markdown: true` serve a Markdown
   representation to agents. Confirm the Markdown variant is not more permissive
   than the HTML page (it carries `Vary: Accept`, so it is separately cached).
+  SSG routes with a `markdown` export and no middleware also publish it as
+  `dist/client/<path>.md` (off with `markdownFiles: false`); confirm each
+  file is meant for every visitor.
 - An enabled OpenAPI document (`/openapi.json`, `dist/client/openapi.json`) is
   public unless the host protects it — check descriptions and examples for
   internal hostnames or credentials, and that "Try it out" mutation endpoints

package/skills/audit-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit-auth
-version: 1.4.0
+version: 1.5.0
 description: |
   Find pracht routes that look protected but aren't: missing auth middleware,
   middleware that augments context but never gates, client-only checks, and
@@ -87,6 +87,13 @@ auth is enforced because `request.headers.get('x-user-id')` returns a value
 when present, but unauthenticated requests just get `null` and the loader has
 to handle it. Flag every loader downstream of an Augmenter that doesn't.
 
+A shell `loader` that redirects anonymous users is **not** a gate either. A
+client that already holds the shell's data sends `x-pracht-shell-data: <shell>`
+on route-state requests and the server skips the shell loader, so the route's
+data comes back without it running. Flag any shell whose loader is the only
+thing between an anonymous request and the routes under it; the gate belongs
+in middleware.
+
 ## Step 2: Identify protected routes
 
 A route is "expected protected" if any of:
@@ -165,6 +172,27 @@ target. From `pracht inspect api --json`:
 - Common bug: dashboard route is protected by middleware, but
   `POST /api/items` is not — attacker bypasses the UI entirely.
 
+### Server islands
+
+Every module in `src/server-islands/` (or `pracht({ serverIslandsDir })`) is
+reachable at `GET /__pracht/server-island` with the visitor's cookies, for any
+page whose route or shell lists it in `export const serverIslands = [...]` —
+with that route's middleware
+(see <https://pracht.resynapse.dev/docs/server-islands#security>). Map each
+server island to the routes that list it, directly or through their shell.
+
+- Flag a server island listed by both gated and ungated routes whose loader
+  returns user-specific data without checking `context` itself — `error`: the
+  ungated route serves it to anyone.
+- Flag pages that gate a server island only at render time
+  (`{isAdmin && <AdminStats />}` behind a loader check, not middleware) —
+  `error`: the endpoint runs it for anyone who passes that route's middleware.
+- Flag server island loaders that pick *whose* data to load from `props`
+  (`userId`, `orderId`, `accountId`) — the caller controls the query string
+  (`error`, IDOR). Identity must come from `context`.
+- Flag server island loaders with side effects (writes, sends) — the endpoint is
+  a `GET` (`warn`).
+
 ## Step 5: Client/server enforcement parity
 
 Grep client components for patterns like `if (!user) return <Login />`. For

package/skills/audit-bundles/SKILL.md

@@ -56,6 +56,14 @@ reference with `dist/client/.vite/manifest.json` for chunk metadata
 (file, imports, dynamicImports, css, isEntry) — needed for vendor fan-in
 analysis (Step 4) and CSS sizing, which the analyze report does not cover.
 
+Size CSS from the `cssManifest` this command reports, never from
+`dist/client/.vite/manifest.json`. A `hydration: "none"` or `"islands"` route is
+absent from the client manifest by construction, so reading it directly reports
+no CSS for a page whose document links a stylesheet — under-reporting exactly
+the routes pracht recommends. `inspect` merges `dist/server/css-manifest.json`,
+the build's own record, over the client manifest; an older build without that
+file is client-only, and the CSS column should say so rather than read as zero.
+
 ## Step 3: Interpret per-route payload
 
 From the Step 1 JSON, report:
@@ -191,6 +199,13 @@ rel="stylesheet">` tags on static pages, and the build warns.
 `build.cssCodeSplit: false` is rejected outright — there is no `index.html` to
 link the single stylesheet it produces, so every page would ship without one.
 
+When a route's CSS is small and the site is entered cold — a static export, a
+content site arriving from search — the stylesheet link is often the only
+render-blocking request left on a page that ships no JavaScript. Report
+`pracht({ inlineCss: true })` as a suggestion there, with the cost: the same
+bytes in every document and no shared stylesheet cache. An app whose visitors
+move between pages should keep the link.
+
 ## Step 7: Report
 
 Three sections:

package/skills/audit-headers/SKILL.md

@@ -121,6 +121,10 @@ into `speculation` (they emit an inline
    `<script id="pracht-state" type="application/json">` — it does not need
    `'unsafe-inline'`. Do not add `'unsafe-inline'` unless the app truly emits
    executable inline scripts and the tradeoff is documented.
+5. Routes with `streaming: true` emit executable inline scripts for deferred
+   data and boundary swaps. Under a nonce policy, return the request nonce as
+   `scriptNonce` from the shell `head()` and allow it in `script-src`; it also
+   covers the speculation rules script.
 
 Output a draft CSP referencing `docs/CSP.md` and explain what each origin is
 for. Do not hand the user a CSP that breaks their site — present as draft.

package/skills/audit-islands/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit-islands
-version: 1.0.1
+version: 1.1.0
 description: |
   Audit pracht hydration: over-hydrated routes that should be `hydration:
   "islands"` or `"none"`, dead interactivity outside the islands directory,
@@ -89,9 +89,22 @@ there is no wrapper to mark a component elsewhere as an island.
 Island props are serialized to JSON in the HTML. At each island call site on
 an islands route, flag props that are functions, symbols, bigints, class
 instances (`Date`, `Map`, ...), JSX elements, or circular — rendering throws a
-descriptive error naming the offending prop path. Passing children into an
-island from a server component also throws (unsupported in v1): move the
-content inside the island or pass a serializable prop.
+descriptive error naming the offending prop path. Children passed into an
+island are fine: markup renders once on the server as static HTML, and plain
+text arrives as a string value. Flag:
+
+- a render function passed as children (it throws);
+- children the island expects to re-render or pass props into, and islands
+  among the children that read context the outer island provides (the browser
+  gives them the default) — those belong inside the island or need a prop;
+- an island that splits markup children with `toChildArray`, `Children.map`, or
+  `Children.count` (tabs, carousels): it receives one opaque node, so labels
+  belong in props and panels are toggled through a ref (`hidden`);
+- an island that renders `children` inside `<p>`, `<a>`, or `<button>` while
+  call sites pass block elements, links, or buttons (the dev server throws
+  when it sees this), or raw HTML in children that may be malformed: the
+  browser moves those nodes out of the slot and the island is left unhydrated
+  with a console error.
 
 ### 3d. Hydration strategy tuning (`info`)
 
@@ -115,7 +128,28 @@ navigation to, from, and between them is full-document (MPA-style), and
 route-state prefetching is skipped for them. Flag apps that rely on
 client-side state surviving navigation across such routes (in-memory stores,
 module-level caches shared between pages) — every navigation is a fresh
-document.
+document, unless `pracht({ client: { islandsNavigation: true } })` is set. With
+it, links between islands pages (and from them to `none` pages) swap the page
+into the same document and an island rendered with identical props on both
+pages keeps its state; module state survives too. Still flag state that must
+survive a link to a full-hydration route, a reload, or a browser without the
+Navigation API, since those remain full loads. Page-change animation does not need the client router: with
+`defineApp({ viewTransitions: true })` these documents carry a
+`@view-transition` rule and animate as cross-document view transitions, so
+flag only apps that load extra JavaScript to animate such navigations.
+
+### 3g. Personal data in islands on cached pages (`warn`)
+
+Island props on an `ssg`/`isg` route are fixed at build or regeneration time
+and shared by every visitor. Flag islands that exist only to fetch per-visitor
+content after load (a hand-rolled `fetch` of the session, cart, or "signed in
+as" data in `useEffect`) and islands whose props look personal. Suggest a
+server island instead (`src/server-islands/`, see
+<https://pracht.resynapse.dev/docs/server-islands>): its
+loader runs per request with the route's middleware context, and it may
+contain islands, which hydrate once the server island is swapped in. On
+full-hydration pages islands inside a server island stay static HTML — flag those
+(`warn`) if they are expected to be interactive.
 
 ## Step 4: Report
 
@@ -139,5 +173,7 @@ finding.
    routes.
 4. Verify hydration in a running app via `html[data-pracht-islands-hydrated="true"]`
    (set after all `load` islands hydrate) and per-island `data-hydrated="true"`.
+   Server islands report `html[data-pracht-server-islands-ready="true"]` once every server
+   island fetch the page started has settled, on every hydration mode.
 
 $ARGUMENTS

package/skills/audit-loaders/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit-loaders
-version: 1.1.1
+version: 1.2.0
 description: |
   Audit pracht route loaders for serializability, leaked secrets, unsafe
   `loaderCache`, browser-only API use, and missing `AbortSignal` plumbing.
@@ -38,13 +38,22 @@ manifest (`RouteConfig.loader`); the inspect JSON surfaces that as
 `loaderFile` (null when the loader lives in the route module itself). Reading
 only `file` misses every externalized loader.
 
+Shells can export a `loader` too. Read each distinct `shellFile` from the same
+JSON and audit its `loader` like a route's: its return value reaches the
+browser as `shellData` on every page under that shell.
+
 ## Step 2: Run the five checks
 
 For each `loader` (and `getStaticPaths` when present):
 
 ### 2a. Serializability
 
-Flag returns that contain any of:
+Skip this check for `hydration: "islands"` and `"none"` routes: they ship no
+loader data. Otherwise, check `vite.config.*` for
+`pracht({ client: { richData: true } })` first.
+
+Without `richData` (the default), loader data is `JSON.stringify`'d while the
+component's types still promise the original. Flag returns that contain any of:
 
 | Construct                    | Why it breaks                       |
 | ---------------------------- | ----------------------------------- |
@@ -57,6 +66,13 @@ Flag returns that contain any of:
 | `bigint`                     | `JSON.stringify` throws             |
 | `undefined` in arrays/object | Drops keys; arrays become `null`    |
 
+With `richData`, `Date`, `Map`, `Set`, `URL`, `RegExp`, `bigint`, `undefined`,
+and shared or circular references arrive intact: do not flag them. Flag
+functions, symbols, typed arrays, and class instances without `toJSON()`
+(`Error` included) instead: each fails the request with a 500 naming the path,
+in production too. A class instance with `toJSON()` arrives as its output, so
+its type lies.
+
 A bare promise in loader data is always a bug — it serializes to `{}`. The fix
 is `defer(promise)`, which marks the field as deferred and is read in the
 component with `use()` inside a `<Suspense>` boundary. Flag a bare promise as an
@@ -73,7 +89,8 @@ Two `defer()` rules worth checking while you are in the loader:
   behind a getter. An unresolved marker throws during serialization.
 
 Recommend converting to `string` (ISO for dates), plain arrays, or plain objects
-before return.
+before return, or turning on `client.richData` when an app returns many dates
+or maps.
 
 ### 2b. Secret leaks
 

package/skills/audit-redirects/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit-redirects
-version: 1.1.1
+version: 1.1.2
 description: |
   Find open redirects in pracht loaders, middleware, and navigation. The framework
   rejects unsafe schemes and CRLF at both ends, but a hand-rolled 3xx Response
@@ -86,16 +86,18 @@ For each request-derived target, look for one of:
 | Gate                                   | Safe? |
 | -------------------------------------- | ----- |
 | Hardcoded allowlist of paths/origins   | Yes   |
-| `target.startsWith('/')` AND `!target.startsWith('//')` | Yes — same-origin path only |
 | `new URL(target, base).origin === url.origin`           | Yes — origin comparison |
+| `target.startsWith('/')` AND `!target.startsWith('//')` | **Bypassable** (`/\evil.example`) |
 | `new URL(target).hostname === expected` | Yes if `expected` is trusted |
 | No check                                | **Open redirect** |
 | `target.includes(domain)` (substring)   | **Bypassable** (`evil.com#yourdomain.com`) |
 | Regex without anchors                   | **Likely bypassable** |
 
-`startsWith('/')` alone is **not** sufficient — `//evil.example/path` parses
-as a protocol-relative URL and most browsers treat it as cross-origin. Require
-both `startsWith('/')` AND `!startsWith('//')`, or use `URL` parsing.
+Prefix checks are **not** sufficient. `//evil.example/path` is
+protocol-relative, and URL parsing turns `\` into `/` and strips tabs and
+newlines, so `/\evil.example` and `/\t/evil.example` pass
+`startsWith('/') && !startsWith('//')` yet land on another origin. Only an
+origin comparison after `new URL(target, url)` is a real gate.
 
 Remember: `redirect()`'s built-in validation covers scheme and CRLF only — it
 happily redirects to any well-formed `http(s)` origin, so Class A sites still
@@ -118,9 +120,21 @@ Severity is the primary scale; the verdict is a secondary domain label:
 For each `open`/`risky` finding, propose a fix snippet, e.g.:
 
 ```ts
-const raw = url.searchParams.get("redirect") ?? "/dashboard";
-const safe = raw.startsWith("/") && !raw.startsWith("//") ? raw : "/dashboard";
-return redirect(safe, { request });
+function safeRedirectPath(value: unknown, 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;
+  }
+}
+
+return redirect(safeRedirectPath(url.searchParams.get("redirect"), url, "/dashboard"), {
+  request,
+});
 ```
 
 ## Step 5: Cross-check with the framework guards

package/skills/audit-secrets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit-secrets
-version: 1.1.1
+version: 1.2.0
 description: |
   Detect environment variables and secrets reaching the client bundle via loader
   return values, hydration state, or server-only modules imported from client code
@@ -74,8 +74,9 @@ risk in the report.
 
 ## Step 3: Module import boundaries
 
-Grep client-rendered files (route components, shells, anything imported from
-them) for imports of:
+Grep client-rendered files (route components, shells, the app root registered
+as `defineApp({ root })` or `pages/_root.tsx`, anything imported from them) for
+imports of:
 
 - `node:*` builtins
 - `@pracht/adapter-*`
@@ -87,12 +88,22 @@ The Vite plugin strips the server-only exports `loader`, `head`, `headers`,
 query (`middleware` is not a route-file export — middleware lives in the
 manifest); see the client module transform notes in `docs/ARCHITECTURE.md`
 and `docs/ENV.md`. But a component that imports `../server/db` will still
-pull `db` into the client bundle. Flag those imports.
+pull `db` into the client bundle. Flag those imports. The app root's browser
+copy loses only `dehydrate` and the imports nothing else uses; `setup()`,
+`Root`, `hydrate()`, and everything they import ship. A `dehydrate` bound in
+the same destructuring as those (`export const { setup, Root, dehydrate,
+hydrate } = createRoot(…)`) or reached through `export *` ships with them, so
+flag a server-only value passed into that call. A root whose other code calls
+or re-exports `dehydrate` ships whole; flag its server-only imports too.
 
 ## Step 4: Hidden surfaces
 
 Check for accidental exposure outside loaders:
 
+- The app root's `dehydrate()` snapshot: it lands in `pracht-state` as `root`
+  and in every route-state response, like loader data. For `@pracht/query`
+  that is every successful query cached during the request, so flag a
+  `queryFn` or `setQueryData` in a loader that caches a secret-bearing value.
 - `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 enter `dist/server/headers-manifest.json`; every serverful

package/skills/audit-shells/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit-shells
-version: 1.3.0
+version: 1.4.0
 description: |
   Audit pracht shells: missing `Loading()` on SPA routes, `<html>`/`<head>`/
   `<body>` rendered inside a shell, shells that never render `children`, unused
@@ -92,6 +92,22 @@ route `headers()`). Optional, but if present:
 - Flag shells whose `headers()` returns `undefined` unconditionally — delete
   the export.
 
+### 2g. `loader` export
+
+Shells may export `loader(args)` for layout-level data, read with
+`useShellData()` in the shell and its routes. If present:
+- Run the audit-loaders checks on it: its return value is serialized into
+  every page under the shell (`shellData` in the hydration state and the
+  route-state JSON).
+- `useShellData()` returns `undefined` while the shell renders without its
+  data (SPA loading state, an error boundary after the shell loader failed).
+  Flag a shell that dereferences it unguarded.
+- Flag a shell loader used as an auth gate (redirecting anonymous users) with
+  no gating middleware on its routes: navigations inside the shell ask the
+  server to skip it. Gate in middleware.
+- Flag several routes under one shell whose loaders each fetch the same
+  layout-level value (the current user): that belongs in the shell loader.
+
 ## Step 3: Coverage and waste
 
 Shell registration is mode-aware — check the `mode` field from the Step 1

package/skills/migrate-nextjs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: migrate-nextjs
-version: 1.7.0
+version: 1.8.1
 description: |
   Migrate a Next.js app to pracht: App or Pages Router pages, layouts, middleware,
   API routes, data fetching, and metadata — plus React→Preact, `className`→`class`,
@@ -74,7 +74,7 @@ automatic**:
 | ------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------- |
 | `pages/` directory              | `pagesDir` plugin option                                        | Auto-discovers routes from the file system                            |
 | `app/page.tsx`                  | `src/routes/*.tsx` + `route()` in manifest                      | File is a module; wiring is explicit                                  |
-| `app/layout.tsx`                | `src/shells/*.tsx` + `shells` in `defineApp` (pages: `_app.tsx` per directory) | Named shells; a directory `_app` replaces its parent instead of nesting |
+| `app/layout.tsx`                | `src/shells/*.tsx` + `shells` in `defineApp` (pages: `_app.tsx` per directory) | Named shells; a directory `_app` replaces its parent. Layout data: shell `loader` + `useShellData()` |
 | `app/loading.tsx`               | `Loading` export on the shell                                   | SSR placeholder for SPA routes until the client router takes over     |
 | `app/error.tsx`                 | `ErrorBoundary` export in route module                          | Same concept, different wiring                                        |
 | `app/not-found.tsx`             | `notFound:` in `defineApp` (or `pages/404.tsx` in pagesDir mode) | Not a route — never matches a URL, so it cannot shadow static assets  |
@@ -87,7 +87,7 @@ automatic**:
 | `"use client"` (few, mostly-server app) | `hydration: "islands"` + `src/islands/`                 | Only islands ship JS; see Phase 4                                     |
 | `revalidatePath` / `res.revalidate()` | `webhookRevalidate()` + `POST /__pracht/revalidate`       | On-demand ISG; combinable with `timeRevalidate(seconds)`              |
 | `useRouter()` (next/navigation) | `useNavigate()`                                                 | Takes a path, or `{ route: "id" }` after `pracht typegen`             |
-| `useSearchParams()`             | `useSearchParams()`                                             | Reactive read-only params; SSG gets the browser query after hydration, loaders use `url.searchParams` |
+| `useSearchParams()`             | `useSearchParams()`                                             | Reactive read-only params; SSG gets the browser query after hydration. For validated, typed values export a `search` schema and read `args.search` / `useSearch()` |
 | `useParams()`                   | `useParams()`                                                   | Direct equivalent; also `params` in loader args                       |
 | `next/link` `<Link>`            | `<Link route="..." params={{…}}>` or plain `<a>`               | Prefer typed `<Link>` after `pracht typegen`; the router intercepts same-origin anchors |
 | `next/link` `prefetch={false}`  | `<Link prefetch="none">`                                        | Default `"intent"` (hover/focus); also `"viewport"`, `"render"`       |
@@ -337,8 +337,8 @@ and fix errors iteratively.
 | `next`          | `@pracht/core` + `@pracht/cli` + `@pracht/vite-plugin` + a target adapter    |
 | `next/image`    | `@pracht/image`                                                              |
 | `react`, `react-dom` | `preact`                                                                |
-| `next/font/local` | `defineFont()` from `@pracht/core` — register via `head() { return { fonts: [font] } }`, use `font.className`/`font.style` |
-| `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/font/local` | Import WOFF2 with `?url&no-inline` into [`defineFont()`](https://pracht.resynapse.dev/docs/fonts); register `head().fonts`, apply `font.className`/`font.style` |
+| `next/font/google` | Self-host WOFF2 in `src/fonts/`, then follow `next/font/local`; 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 a custom solution                                            |

package/skills/pracht-debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pracht-debug
-version: 1.4.0
+version: 1.5.0
 description: |
   Framework-aware debugging for pracht: route matching, loader and API errors,
   rendering and hydration, middleware, HMR, and build failures — root cause first.
@@ -33,6 +33,7 @@ Reach for these before deep manual inspection:
 | ---- | --- |
 | `pracht verify` (`--changed` to scope to git-changed files) | Fast confidence check |
 | `pracht doctor` | Broader broken wiring or missing files |
+| `pracht docs <topic>` / `pracht docs --search <query>` | Docs bundled with the installed CLI — check documented behavior before calling it a bug. Older CLIs lack the command; read https://pracht.resynapse.dev/llms.txt instead |
 | `pracht inspect routes\|api\|build --json` | The resolved graph — never reconstruct it from source |
 | `GET /_pracht` (JSON at `/_pracht.json`) | Same graph from a running dev server, no CLI needed |
 | `Server-Timing` on dev SSR responses | `mw` / `loader` / `render` durations in ms — which phase is slow |
@@ -92,7 +93,9 @@ Work in order; stop at the root cause.
 ### 3. Loader / API errors
 
 - On slow pages, read `Server-Timing` before reading code.
-- Loaders must return serializable data — no functions, no circular refs.
+- Loaders must return serializable data — no functions, no circular refs. A
+  `Date` arrives as a string unless `pracht({ client: { richData: true } })` is
+  set; with it, an unsupported value fails with an error naming its path.
 - API handlers must return `Response` objects, and a default export must branch
   on `request.method`.
 - Look for unhandled rejections or thrown errors.

package/skills/pracht-deploy/SKILL.md

@@ -75,6 +75,14 @@ step (`--port <n>`, `--skip-build` to reuse a build).
   `Accept-Encoding`, streaming for dynamic bodies, an in-memory LRU for static
   assets). Behind a proxy or CDN that already compresses, set
   `nodeAdapter({ compression: false })` to avoid doing it twice.
+- The generated server drains on `SIGTERM`/`SIGINT`: it stops accepting
+  connections and waits for in-flight requests and `args.waitUntil()` work up
+  to `nodeAdapter({ shutdownTimeoutMs })` (default 10s). Keep it below the
+  process manager's kill grace period. A custom `createNodeRequestHandler()`
+  server calls `await handler.drain(ms)` after `server.close()` instead.
+- Background work after the response is `args.waitUntil(promise)` on every
+  adapter — do not wire `executionContext.waitUntil` (Cloudflare) or the
+  platform context yourself.
 
 Docker:
 
@@ -280,8 +288,11 @@ SSG loaders run only at build time and must produce HTML plus valid JSON route
 state; dynamic SSG routes must export `getStaticPaths()`. Only
 manifest-registered capabilities participate, and every registered capability
 module must load successfully so exposure validation fails 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.
+`notFound` page may set `hydration: "islands"` or `"none"` to keep the client
+router out of `404.html` — the router is there only to replace the build URL
+with the visitor's, so a 404 that does not name the requested URL pays nothing
+for it. `staticAdapter({ fallback })` still requires full hydration there,
+because that document is built from the not-found page's route state.
 
 **Deploy base.** Sub-path deploys (GitHub Pages *project* sites, S3 key
 prefixes) set Vite `base` to that path. CDN and document-relative bases (`""`,

package/skills/pracht-scaffold/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pracht-scaffold
-version: 1.4.0
+version: 1.5.0
 description: |
   Scaffold pracht code with the native generators (`pracht generate
   route|shell|middleware|api`), falling back to manual edits only when the CLI
@@ -49,7 +49,9 @@ If the CLI can express the request, do not reimplement the scaffold by hand.
 | `--revalidate`      | ISG window in seconds (`isg` only, default 3600)                             |
 | `--json`            | Machine-readable output                                                      |
 
-`generate shell` and `generate middleware` take `--name`; `generate api` takes
+`generate shell` and `generate middleware` take `--name`; `generate shell
+--loader` adds a shell `loader` export read in the shell with `useShellData()`
+(layout-level data such as the signed-in user). `generate api` takes
 `--path` and `--methods`. All subcommands accept `--json` — use it when another
 agent or tool consumes the output. When the pracht MCP server is registered
 (docs/MCP.md), call the `generate_route`/`generate_shell`/`generate_middleware`/
@@ -82,8 +84,8 @@ agent or tool consumes the output. When the pracht MCP server is registered
 
 | Kind       | Directory         | Key exports                                                                      |
 | ---------- | ----------------- | -------------------------------------------------------------------------------- |
-| Route      | `src/routes/`     | `loader`, `head`, `Component`, `ErrorBoundary`, `getStaticPaths`                 |
-| Shell      | `src/shells/`     | `Shell`, `head`                                                                  |
+| Route      | `src/routes/`     | `loader`, `head`, `Component`, `ErrorBoundary`, `getStaticPaths`, `search`       |
+| Shell      | `src/shells/`     | `Shell`, `loader` (read with `useShellData()`), `head`, `headers`, `Loading`, `ErrorBoundary` |
 | Middleware | `src/middleware/` | `middleware`                                                                     |
 | API route  | `src/api/`        | Named method handlers (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) or one default dispatcher |
 

package/skills/pre-deploy/SKILL.md

@@ -93,6 +93,14 @@ For a PR deploy, `pracht report --base origin/main` produces a markdown summary
   true })` is set; application code should still observe the public base in
   `request.url`, and the proxy must own the bare-base redirect (`/app` →
   `/app/`).
+- If the app registers background work with `args.waitUntil()`, the process
+  manager sends `SIGTERM` (not `SIGKILL`) on stop and its grace period exceeds
+  `nodeAdapter({ shutdownTimeoutMs })` (default 10s); otherwise that work is
+  cut off on every deploy. A custom server entry must call `handler.drain()`
+  itself.
+- Background work still reaching for `context.executionContext.waitUntil` or a
+  platform context should move to the portable `args.waitUntil()` — the
+  platform-specific call is undefined on every other adapter.
 
 ### Cloudflare Workers (`@pracht/adapter-cloudflare`)
 
@@ -197,10 +205,11 @@ must do and what the build cannot enforce.
 - 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; publish `.md` files under `public/` if a raw-markdown corpus
-  matters.
+- A static host cannot negotiate `Accept`, so agents read an SSG page's
+  Markdown at `/<path>.md` (written by the build for routes with a `markdown`
+  export and no middleware). Check the host serves `.md` as
+  `text/markdown; charset=utf-8` — nginx's stock `mime.types` lacks it — and
+  read the build note naming Markdown-capable pages that got no file.
 - Sub-path deploys (GitHub Pages *project* site, S3 key prefix) need Vite
   `base` set to that path (`base: "/my-project/"`), matching the deploy path
   exactly — a mismatch 404s every asset. Then confirm no hand-written

package/skills/tune-render-mode/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tune-render-mode
-version: 1.1.1
+version: 1.2.0
 description: |
   Recommend the right render mode (ssg, isg, ssr, spa) per route from what each
   loader actually does, then apply the change after confirmation.
@@ -53,6 +53,18 @@ For each route:
    anything personalized** → **`ssr`**
    - Auth dashboards, anything user-specific, anything that varies by user
      identity at request time.
+   - **Unless only a small part of the page is personal** (a cart count,
+     "signed in as …", a recommendation strip) and the rest is shared: then
+     recommend **`ssg`/`isg`** for the route plus a **server island** for
+     the personal part (see branch 5b).
+
+5b. **Personal data is confined to a small, self-contained part of the page**
+   → keep the route **`ssg`/`isg`** and move that part into `src/server-islands/`:
+   a default-export component plus a `loader` that reads `context` instead of
+   the page loader, used as JSX with a `fallback`. See
+   <https://pracht.resynapse.dev/docs/server-islands>. Not available on the static
+   adapter. Server island props are untrusted input — the server island loader must
+   authorize from `context` itself.
 
 6. **Heavy client interactivity, no SEO need, auth-gated** → **`spa`**
    - Internal admin tools, post-login dashboards where the first paint can be a
@@ -108,6 +120,9 @@ Examples of recommendations:
   request — cannot be prerendered." (`error`)
 - `spa` → `ssr` when route has SEO-relevant `head()` and unauthenticated
   visitors should see content. (`warn`)
+- `ssr` → `isg(600)` + server island when the loader reads the session only for a
+  header greeting or cart badge: "move the personal part into
+  `src/server-islands/`; the page itself is shared." (`info`)
 
 ## Step 3b: Consider the hydration mode too
 
@@ -124,7 +139,8 @@ field (absent from the JSON), grep the manifest for `hydration:` (pages apps:
   box, newsletter form) → `hydration: "islands"` with the widgets moved to
   `src/islands/`.
 - Caveats: islands routes use MPA-style full-document navigation (no client
-  router), island props must be JSON-serializable, and `render: "spa"` cannot
+  router) unless `client.islandsNavigation` swaps islands pages in place,
+  island props must be JSON-serializable, and `render: "spa"` cannot
   combine with `"islands"`/`"none"`.
 
 ## Step 3c: Consider streaming for slow SSR routes
@@ -190,6 +206,8 @@ Apply the edits only after the user confirms.
 1. Never silently change render modes. Always present the recommendation and
    the exact diff first; apply only after explicit user approval.
 2. If a route uses `auth` middleware, default to `ssr` — auth implies cookies.
+   The exception is middleware that only *reads* the session for a small
+   personal part of an otherwise public page: that is the server island case (5b).
 3. All three adapters support ISG — the mechanisms differ. Confirm which
    adapter is in play, then use this capability table:
 

package/skills/typed-routes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typed-routes
-version: 1.1.1
+version: 1.3.0
 description: |
   Add or maintain pracht typed routes: run typegen, adopt route-id based links and
   navigation, and replace hard-coded hrefs with generated helpers.
@@ -79,6 +79,10 @@ when `src/pracht.d.ts` does not exist. In CI, prefer:
 pracht typegen --check
 ```
 
+The check compares declarations, not bytes, so generated files reformatted by
+the project's formatter still read as up to date and regenerating leaves them
+formatted. Do not add them to a formatter ignore list on that account.
+
 ## Step 3: Replace string navigation where it matters
 
 ### Components
@@ -149,6 +153,46 @@ loader type their data as `undefined`. The id must be the active route: a
 mismatch throws (with a descriptive message in dev), so a shell or island that
 needs another route's data must receive it as props instead.
 
+Shell loaders register the same way: `useShellData("app")` types the result
+from the `app` shell's `loader` for every shell a route renders under. It is
+typed `| undefined` because the shell can render without its data (the SPA
+loading state), and naming a shell the active route does not use throws.
+
+### Search params
+
+A route that reads its query string should export a `search` schema (any
+Standard Schema validator) instead of parsing `url.searchParams` by hand.
+Typegen then types `search` on `<Link>`, `navigate()`, and `href()` from the
+schema's input, and `useSearch(routeId)` returns its output:
+
+```tsx
+import { Link, useSearch, type LoaderArgs, type SearchArgs } from "@pracht/core";
+import * as z from "zod";
+
+export const search = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  q: z.string().optional(),
+});
+
+export async function loader(args: LoaderArgs & SearchArgs<typeof search>) {
+  return listProducts(args.search); // { page: number; q?: string }
+}
+
+export function Component() {
+  const { page, q } = useSearch("products");
+  return <Link route="products" search={{ page: page + 1, q }}>Next</Link>;
+}
+```
+
+- Values arrive as strings (arrays for repeated keys): coerce with
+  `z.coerce.*`, and give optional params defaults so the bare URL is valid. A
+  key that may repeat is a plain string when it appears once — accept both.
+- A rejected query answers 400 and renders the route's `ErrorBoundary` with
+  `error.issues`; client navigation does the same.
+- SSG/ISG routes are prerendered with an empty query, so the schema must
+  accept one; loaders there only ever see the defaults.
+- Keep `useSearchParams()` for raw access; it is unchanged.
+
 ### API routes
 
 After typegen, `apiFetch()` type-checks API calls end to end — paths,
@@ -182,8 +226,11 @@ Generated param types accept `RouteParamInput = string | number | boolean`
 - `:path*` requires `params: { path: RouteParamInput }`.
 - Routes with no dynamic segments should omit `params`.
 - Missing and extra params should fail at typecheck time.
-- `search` currently accepts `string`, `URLSearchParams`, or an object of
-  primitive values/arrays; route-specific search schemas can be added later.
+- `search` is typed by the route module's `search` schema input when it
+  exports one: unknown keys and wrong value types fail, keys whose input
+  cannot come from a string (`z.number()`) fail, and a required key makes
+  `search` itself required. Routes without a schema accept `string`,
+  `URLSearchParams`, or an object of primitive values/arrays.
 
 ## Step 5: Verify
 

package/skills/upgrade-pracht/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: upgrade-pracht
-version: 1.1.0
+version: 1.3.0
 description: |
   Upgrade the `@pracht/*` packages safely: inventory installed versions, read the
   changelogs between installed and target, map breaking changes to real usage,
@@ -120,6 +120,9 @@ pnpm up '@pracht/core@<v>' '@pracht/cli@<v>' '@pracht/vite-plugin@<v>' <adapters
 
 Upgrade every installed `@pracht/*` package in the same command. Apply the
 agreed code migrations with minimal diffs, one changelog entry at a time.
+Then read the page behind each changed API with `pracht docs <topic>`, which
+serves the docs bundled with the newly installed CLI. A CLI without that
+command predates it; use https://pracht.resynapse.dev/llms.txt instead.
 
 ## Step 6: Verification ladder
 
@@ -130,12 +133,17 @@ pracht doctor --json          # wiring still valid
 pracht typegen --check        # generated route types up to date?
 pracht typegen                # regenerate if --check failed or routes changed
 pracht verify --json          # framework-aware checks
+pnpm typecheck                # both tsconfig programs, if the app has the script
 pracht build                  # full production build (budgets included)
 pnpm test                     # the app's own suite
 ```
 
 `pracht doctor`, `verify`, and `typegen --check` exit non-zero on failure, so
-they gate CI cleanly.
+they gate CI cleanly. Act on doctor *warnings* too: `pnpm up` never touches
+files `create-pracht` wrote, so a warning is how an older scaffold learns it
+needs a config change — for example adding `"src/**/*.d.ts"` to the
+`include` of `tsconfig.client.json`, without which typed route hooks are
+`unknown` in client code and `<Link route>` accepts any string.
 
 ## Step 7: Rollback note
 

package/src/index.js

@@ -5,6 +5,8 @@ import { basename, dirname, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
+import { loadFallbackVersionRanges } from "./versions.js";
+
 export class ValidationError extends Error {
   constructor(message) {
     super(message);
@@ -12,22 +14,6 @@ export class ValidationError extends Error {
   }
 }
 
-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.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",
-  typescript: "^6.0.0",
-  vercel: "^56.5.0",
-};
-
 /**
  * Cloudflare `compatibility_date` for scaffolded apps.
  *
@@ -105,6 +91,24 @@ function readFileSyncSafe(path) {
 
 const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
 
+// Used only when the registry lookup fails. The `@pracht/*` ranges are the
+// versions this create-pracht was built alongside (see src/versions.js).
+const FALLBACK_VERSION_RANGES = {
+  "@tailwindcss/vite": "^4.1.0",
+  "netlify-cli": "^21.6.0",
+  tailwindcss: "^4.1.0",
+  typescript: "^6.0.0",
+  vercel: "^56.5.0",
+  ...loadFallbackVersionRanges(PACKAGE_ROOT),
+};
+
+// The Node floor every pracht package declares, read from this package's own
+// engines field so a bump lands in scaffolded apps without a second edit.
+const NODE_MINIMUM = (
+  JSON.parse(readFileSyncSafe(resolve(PACKAGE_ROOT, "package.json"))).engines?.node ?? ">=22.18"
+).replace(/^\D*/, "");
+const NODE_MAJOR = NODE_MINIMUM.split(".")[0];
+
 // The published package bundles a copy of the repo skills (see
 // scripts/sync-skills.js); inside the monorepo we fall back to the source.
 const SKILL_DIRS = [resolve(PACKAGE_ROOT, "skills"), resolve(PACKAGE_ROOT, "../../skills")];
@@ -225,7 +229,7 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  const { pnpmWorkspaceNotice } = await scaffoldProject({
+  const { pnpmWorkspaceNotice, versionFallbacks } = await scaffoldProject({
     adapter: ADAPTERS[resolvedAdapter],
     agentSkills,
     agentTools: resolvedAgentTools,
@@ -289,6 +293,7 @@ export async function run(argv = process.argv.slice(2)) {
         pnpmWorkspaceNotice,
         router: resolvedRouter,
         tailwind: resolvedTailwind,
+        versionFallbacks,
       }),
     );
   } else {
@@ -303,6 +308,7 @@ export async function run(argv = process.argv.slice(2)) {
       router: resolvedRouter,
       skipInstall: options.skipInstall,
       tailwind: resolvedTailwind,
+      versionFallbacks,
     });
   }
 }
@@ -319,7 +325,7 @@ export async function scaffoldProject({
   targetDir,
 }) {
   const packageName = toPackageName(basename(targetDir));
-  const { files, pnpmWorkspaceNotice } = await buildProjectFiles({
+  const { files, pnpmWorkspaceNotice, versionFallbacks } = await buildProjectFiles({
     adapter,
     agentSkills,
     agentTools,
@@ -347,7 +353,7 @@ export async function scaffoldProject({
   // AGENTS.md (and the CLAUDE.md alias pointing at it) are agent tooling too —
   // `--no-agent-tools` means a project with none of it, not "all of it except
   // the instruction files". README.md carries the same commands for humans.
-  if (!agentTools) return { pnpmWorkspaceNotice };
+  if (!agentTools) return { pnpmWorkspaceNotice, versionFallbacks };
 
   try {
     await symlink("AGENTS.md", resolve(targetDir, "CLAUDE.md"));
@@ -359,7 +365,7 @@ export async function scaffoldProject({
     }
   }
 
-  return { pnpmWorkspaceNotice };
+  return { pnpmWorkspaceNotice, versionFallbacks };
 }
 
 export function getPackageManager(userAgent = process.env.npm_config_user_agent ?? "") {
@@ -676,7 +682,13 @@ function normalizeAdapter(value) {
   return null;
 }
 
+/**
+ * Latest published ranges for `packageNames`. `fallbacks` lists the packages
+ * whose registry lookup failed and got the bundled range instead; a scaffold
+ * that asked for no lookup (`remote: false`) reports none.
+ */
 async function resolveVersions(packageNames, { remote = true } = {}) {
+  const fallbacks = [];
   const entries = await Promise.all(
     packageNames.map(async (name) => {
       const fallback = FALLBACK_VERSION_RANGES[name] ?? "latest";
@@ -684,11 +696,13 @@ async function resolveVersions(packageNames, { remote = true } = {}) {
       try {
         return [name, `^${await fetchLatestVersion(name)}`];
       } catch {
+        fallbacks.push(name);
         return [name, fallback];
       }
     }),
   );
-  return Object.fromEntries(entries);
+  const versions = Object.fromEntries(entries);
+  return { fallbacks: fallbacks.sort().map((name) => `${name}@${versions[name]}`), versions };
 }
 
 async function buildProjectFiles({
@@ -720,7 +734,9 @@ async function buildProjectFiles({
     packagesToResolve.push("tailwindcss", "@tailwindcss/vite");
   }
 
-  const versions = await resolveVersions(packagesToResolve, { remote: resolveRemoteVersions });
+  const { fallbacks: versionFallbacks, versions } = await resolveVersions(packagesToResolve, {
+    remote: resolveRemoteVersions,
+  });
   const policyMajor = pnpmMajor ?? 11;
   const ancestorWorkspace =
     targetDir && packageManager === "pnpm" ? findAncestorPnpmWorkspace(targetDir) : null;
@@ -733,6 +749,11 @@ async function buildProjectFiles({
     : null;
 
   const files = {
+    // Build images (Cloudflare Pages, Netlify, most CI) pick a Node version
+    // from this file; without it they choose their own default, which is
+    // routinely older than pracht's `engines.node` and fails the build on a
+    // missing modern built-in rather than on a version mismatch.
+    ".nvmrc": `${NODE_MAJOR}\n`,
     ".gitignore":
       "dist\nnode_modules\n.netlify\n.wrangler\n.vercel\n.env*\n!.env.example\n.dev.vars\n# Keep .pracht/app-graph.json committed — it is the `pracht plan` snapshot.\n",
     "README.md": createReadme({
@@ -821,7 +842,7 @@ async function buildProjectFiles({
     files["pnpm-workspace.yaml"] = createPnpmWorkspaceConfig(adapter, tailwind, policyMajor);
   }
 
-  return { files, pnpmWorkspaceNotice };
+  return { files, pnpmWorkspaceNotice, versionFallbacks };
 }
 
 function createMcpConfig() {
@@ -888,7 +909,8 @@ function createPackageJson({ adapter, projectName, tailwind, versions }) {
     "@pracht/cli": versions["@pracht/cli"],
     "@pracht/vite-plugin": versions["@pracht/vite-plugin"],
     preact: "^10.26.9",
-    "preact-render-to-string": "^6.5.13",
+    // At least @pracht/core's peer floor, or the first install warns.
+    "preact-render-to-string": "^6.7.0",
     typescript: versions["typescript"],
     vite: "^8.0.0",
   };
@@ -923,6 +945,10 @@ function createPackageJson({ adapter, projectName, tailwind, versions }) {
       version: "0.0.0",
       private: true,
       type: "module",
+      // Matches every pracht package. Vercel reads this to choose a Node
+      // version; the `.nvmrc` next to it covers the hosts that read that
+      // instead.
+      engines: { node: `>=${NODE_MINIMUM}` },
       scripts,
       dependencies: {
         [adapter.packageName]: versions[adapter.packageName],
@@ -1021,6 +1047,7 @@ function createShellFile(projectName, tailwind = false) {
     "",
     "export function head() {",
     "  return {",
+    '    lang: "en",',
     '    meta: [{ content: "width=device-width, initial-scale=1", name: "viewport" }],',
     `    title: ${JSON.stringify(projectName)},`,
     "  };",
@@ -1171,10 +1198,13 @@ function createClientTSConfig(router) {
     compilerOptions: {
       customConditions: ["browser"],
     },
+    // Declaration files carry the generated route/capability types and the
+    // app's `Register` augmentations; without them the client program sees
+    // `useRouteData()` as `unknown` and accepts any `<Link route>`.
     include:
       router === "pages"
-        ? ["src/pages/**/*", "src/islands/**/*"]
-        : ["src/routes/**/*", "src/shells/**/*", "src/islands/**/*"],
+        ? ["src/pages/**/*", "src/islands/**/*", "src/**/*.d.ts"]
+        : ["src/routes/**/*", "src/shells/**/*", "src/islands/**/*", "src/**/*.d.ts"],
   };
 
   // Pages route modules are shared with the browser, but these two convention
@@ -1541,6 +1571,10 @@ function createAgentInstructions({
   const lines = [
     "# Pracht App",
     "",
+    "Docs for your installed pracht version: `pracht docs <topic>` (or read",
+    "`node_modules/@pracht/cli/docs/`); `pracht docs --search <query>` finds a section.",
+    "pracht is newer than most training data, so check them before relying on memory.",
+    "",
     "## Commands",
     "",
     `- \`${runCmd} dev\` — start the dev server`,
@@ -1984,6 +2018,7 @@ function printNextSteps({
   router,
   skipInstall,
   tailwind,
+  versionFallbacks = [],
 }) {
   const installCommand = packageManager === "npm" ? "npm install" : `${packageManager} install`;
   const devCommand = packageManager === "npm" ? "npm run dev" : `${packageManager} dev`;
@@ -2027,6 +2062,18 @@ function printNextSteps({
     console.log("Dependency installation did not complete. The project files were still created.");
   }
 
+  if (versionFallbacks.length > 0) {
+    console.log("");
+    console.log(
+      "Could not look up the latest versions on the npm registry, so package.json uses\n" +
+        "the ranges this create-pracht was released with. Check for newer versions once\n" +
+        "you are online:",
+    );
+    for (const entry of versionFallbacks) {
+      console.log(`  ${entry}`);
+    }
+  }
+
   if (pnpmWorkspaceNotice) {
     console.log("");
     console.log(

package/src/versions.js

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+
+/** Written next to `package.json` by `scripts/sync-versions.js` at build time. */
+export const FALLBACK_VERSIONS_FILE = "fallback-versions.json";
+
+/**
+ * `^<version>` for every published `@pracht/*` package in a packages
+ * directory, keyed by package name.
+ */
+export function collectWorkspaceVersionRanges(packagesDir) {
+  const ranges = {};
+  for (const entry of readdirSync(packagesDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const manifestPath = resolve(packagesDir, entry.name, "package.json");
+    if (!existsSync(manifestPath)) continue;
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    if (manifest.private || !manifest.name?.startsWith("@pracht/") || !manifest.version) continue;
+    ranges[manifest.name] = `^${manifest.version}`;
+  }
+  return Object.fromEntries(Object.entries(ranges).sort(([a], [b]) => a.localeCompare(b)));
+}
+
+/**
+ * The `@pracht/*` ranges a scaffold falls back to when the registry lookup
+ * fails. Inside the monorepo they come straight from the sibling packages, so
+ * a checkout never goes stale; a published copy reads the file its build
+ * wrote from those same siblings.
+ */
+export function loadFallbackVersionRanges(packageRoot) {
+  const packagesDir = resolve(packageRoot, "..");
+  try {
+    const core = JSON.parse(readFileSync(resolve(packagesDir, "framework/package.json"), "utf-8"));
+    if (core.name === "@pracht/core") return collectWorkspaceVersionRanges(packagesDir);
+  } catch {
+    // Not a checkout of the monorepo.
+  }
+  try {
+    return JSON.parse(readFileSync(resolve(packageRoot, FALLBACK_VERSIONS_FILE), "utf-8"));
+  } catch {
+    return {};
+  }
+}