create-pracht 0.6.2 → 0.7.0

package/skills/add-capabilities/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: add-capabilities
-version: 1.0.2
+version: 1.3.0
 description: |
   Expose an app operation as a typed pracht capability — one contract projected
-  into direct server calls, an HTTP endpoint, a WebMCP page tool, and a remote MCP
+  into direct server calls, an HTTP endpoint, a route-scoped WebMCP page tool, and a remote MCP
   tool — plus `defineApp({ agents })` trust config, typed clients,
   `<Form capability>`, and `pracht eval` scenarios.
   Use for "add a capability", "expose this to agents", "add an MCP tool", "add
@@ -27,10 +27,11 @@ projection runs the identical pipeline, so rules never diverge per transport:
 input validation → named middleware chain → run() → output validation
 ```
 
-Registration is opt-in and private by default: no loader or API route is ever
-inferred as a capability, and an app that registers none ships no capability
-dispatch surface (the build drops ~15 KB gzip of dispatch and verifier code).
-Other agent-facing surfaces such as `llms.txt` remain independent.
+Registration is opt-in and private by default; loaders and API routes are never
+inferred as capabilities, and an app with none ships no dispatch surface.
+
+Non-Pracht app: use `createCapabilityHost()` and the signal-owned WebMCP
+registrar. See <https://pracht.resynapse.dev/docs/standalone-capabilities>.
 
 ## Step 1: Decide the contract before writing code
 
@@ -41,8 +42,11 @@ Settle these with `AskUserQuestion` when the request is vague:
 - **Effect** — `read`, `write`, or `destructive`. This drives confirmation
   gating, client revalidation, and MCP annotations. Classify honestly.
 - **Exposure** — private (omit `expose`), `http`, `webmcp` (requires `http`),
-  `mcp`. Capabilities are manifest-router only; the pages router has no
-  manifest to register them in.
+  `mcp`.
+- **Router** — manifest apps use a `defineApp({ capabilities })` key; pages apps
+  auto-discover `src/capabilities/`, where each module declares
+  `name: "notes.search"` (or takes its file stem) and the name must map back to
+  its file with dots as hyphens (`notes-search.ts`). Step 4 covers the rest.
 - **Authorization** — which named middleware runs, and whether the endpoint
   requires a verified agent (`agentPolicy: "require"`).
 
@@ -65,11 +69,9 @@ pracht generate capability --name notes.search --effect read --expose http,webmc
   --description "Find notes whose title or body matches the query."
 ```
 
-The generator writes `src/capabilities/notes-search.ts` with `expose`,
-`effect`, and `input` as inline literals and registers the name in the
-manifest. `--description` is required whenever `--expose` is set — that text is
-the contract an agent reads. It refuses the combinations the runtime rejects
-anyway. The MCP `generate_capability` tool does the same thing.
+The generator writes and registers `src/capabilities/notes-search.ts`.
+`--description` is required with `--expose`; the MCP `generate_capability` tool
+has the same contract.
 
 If dispatch answers `500 internal_error` and `pracht inspect capabilities`
 prints capabilities as `unreadable`, the package is missing — that is the
@@ -128,9 +130,10 @@ Schema rules that bite:
   could widen what an exposed capability accepts.
 - Inputs and outputs are JSON data only. `File`, `Blob`, `Date`, `Map`,
   `undefined`, and cycles are rejected — keep uploads in API routes.
-- `expose`, `effect`, and (for webmcp) `input` must be **inline literals**: the
-  browser projection is built by static analysis, and an imported constant or
-  spread fails the build.
+- `expose` and `effect` must be **inline literals**. `input` and `output` may be
+  Standard Schema + Standard JSON Schema validators such as Zod 4. Pracht
+  derives the supported JSON subset server-side and runs the validator; async
+  validation, defaults, and transforms work without adding it to WebMCP.
 - MCP exposure additionally requires both schemas rooted at `type: "object"`.
 - Annotate `run()` with `CapabilityRunArgs<Input>` so TypeScript still infers
   the output; `defineCapability<Input>` alone leaves the output `unknown`.
@@ -139,6 +142,8 @@ Schema rules that bite:
 
 ```ts
 // src/routes.ts
+import { defineApp, route } from "@pracht/core";
+
 export const app = defineApp({
   capabilities: {
     "notes.search": () => import("./capabilities/notes-search.ts"),
@@ -151,10 +156,31 @@ export const app = defineApp({
     // Remote MCP endpoint; without this, `expose.mcp` serves nothing.
     mcp: { serverInfo: { name: "notes", version: "1.0.0" }, instructions: "…" },
   },
-  routes: [/* … */],
+  routes: [
+    route("/notes", "./routes/notes.tsx", {
+      // expose.webmcp makes it eligible; this makes it active on this page.
+      capabilities: ["notes.search"],
+    }),
+  ],
 });
 ```
 
+Pages apps have no manifest: the same `capabilities` come from
+`src/capabilities/` and the same `agents` object is `export const agents` in
+`src/pages/_app.config.ts`. Activate WebMCP tools on each page that needs them:
+
+```ts
+// src/pages/notes.tsx
+export const CAPABILITIES = ["notes.search"];
+```
+
+`CAPABILITIES` must be an inline array of non-empty registered names and cannot
+appear on `_app` or `404`. In a manifest, group capability lists are additive.
+Unknown names, capabilities without `expose.webmcp`, and activation on
+`hydration: "none"` routes are rejected. Initial hydration registers the matched
+route's set; every committed client navigation replaces it, so never assume a
+tool exposed on one page persists globally.
+
 Each `agents` sub-option is independent — add only what the app uses. Web Bot
 Auth `policy: "require"` gates capability HTTP endpoints (not pages or API
 routes) with `401 agent_required`; `agentPolicy: "require"` on a capability
@@ -216,30 +242,14 @@ Rules to hold the user to:
   body that MCP dispatch reads next.
 - **The principal is `context.tokenAuth`** — a frozen `{ subject, scopes?,
   clientId?, claims? }`, alongside `context.agent`. Use it in named middleware
-  and `run()` for per-user authorization; the framework only authenticates. It
-  lives on a fresh request-local overlay, leaving an adapter's reused base
-  context unchanged. Frozen and sealed ordinary contexts work; native built-ins
-  such as `Map` and `Date` must be wrapped in an ordinary context. `claims` is
-  frozen shallowly, but the complete principal is request-local so nested
-  mutations cannot become stale auth on a later request. The capability audit
-  event does not carry it yet, so capture it in named middleware or capability
-  code and send it to the same audit sink if MCP calls must be attributable to
-  an account. Nested capability calls rebind this field to the transport-verified
-  principal, so caller-supplied composition context cannot replace it.
+  and `run()` for authorization; the framework only authenticates. Nested calls
+  retain the transport-verified principal. Capture it separately when audit
+  events must identify the account.
 - `resource` must be the endpoint's **real deployed URL**: absolute, free of
-  query/fragment, free of a non-root trailing slash, and exactly matching the
-  served endpoint's public path — deploy base included, e.g.
-  `https://app.example.com/app/mcp` for an app mounted at `/app/`.
-  `resolveApp()` and `pracht verify` reject otherwise. The metadata document
-  then lands at the origin root with the base inside the suffix
-  (`/.well-known/oauth-protected-resource/app/mcp`); pracht derives it. Require
-  HTTPS outside loopback development, and reject authorization-server issuers
-  with query strings or fragments. For `mcp.path: "/"`, the resource is the
-  deployed app root, including its base; at the origin root use slashless
-  `https://app.example.com`. Authenticated requests whose URL is not
-  exactly this identifier are redirected to it with `308` before token
-  verification. Scope values must use OAuth's printable ASCII grammar (no
-  spaces, controls, non-ASCII, quotes, or backslashes).
+  query/fragment and exactly matching the deployed MCP path, including the app
+  base (`https://app.example.com/app/mcp`). Use HTTPS outside loopback.
+  `resolveApp()` and `pracht verify` reject malformed values and scope strings;
+  mismatched authenticated request URLs redirect to the canonical resource.
 - The bare `/.well-known/oauth-protected-resource` path is reserved for
   discovery and cannot be used as `mcp.path`. Production adapters route both
   metadata forms ahead of copied static files.
@@ -266,19 +276,18 @@ See `docs/REMOTE_MCP.md` for the metadata document and the full `verify` recipe.
 
 Be honest about what this buys, and say so to the user
 (`docs/AGENT_TRUST.md`): stateless HMAC cannot prevent replay inside the TTL,
-the calling agent can hand the token straight back to itself, and without Web
-Bot Auth or `setCapabilityApprovalPrincipalResolver()` both phases run as
-`"anonymous"`. Register a `CapabilityApprovalStore` for exactly-once commits,
-and `confirmation: { mode: "human" }` for a real human decision — that mode
-fails closed without both a store and an authenticated principal.
+the calling agent can hand the token back to itself, and without Web Bot Auth
+or `setCapabilityApprovalPrincipalResolver()` both phases run as `"anonymous"`.
+Register a `CapabilityApprovalStore` for exactly-once commits, and
+`confirmation: { mode: "human" }` for a real human decision — that mode fails
+closed without both a store and an authenticated principal.
 
 `createSqlApprovalStore({ execute })` from `@pracht/core/server` is the
-first-party durable store — no driver dependency, one implementation for
-Postgres, Cloudflare D1, and SQLite/Turso. Pass a parameterized-query function
-and run the migration from `docs/AGENT_TRUST.md`; use `dialect: "postgres"` for
-`$1` placeholders. `createMemoryApprovalStore()` is for tests and development
-only. A non-SQL backend needs atomic conditional writes (Durable Objects,
-Redis — not Cloudflare KV).
+first-party durable store — one implementation for Postgres, Cloudflare D1, and
+SQLite/Turso. Pass a parameterized-query function and run the migration from
+`docs/AGENT_TRUST.md`; use `dialect: "postgres"` for `$1` placeholders.
+`createMemoryApprovalStore()` is for tests only. A non-SQL backend needs atomic
+conditional writes (Durable Objects, Redis — not Cloudflare KV).
 
 ### Destructive over remote MCP
 
@@ -286,18 +295,18 @@ Off by default. To serve one:
 
 1. `agents: { mcp: { destructive: true } }` in `defineApp()`.
 2. Register an approval store from a server entry or a capability module, so it
-   exists before the graph is served. This is not optional — a token handed to
-   the committing agent must be consumable exactly once. The endpoint refuses
-   to serve at all when the store, `PRACHT_CONFIRMATION_SECRET`, or (in human
-   mode) any resolvable principal is missing; `pracht verify` warns when it
-   cannot find the registration in the configured source directories.
+   exists before the graph is served — a token handed to the committing agent
+   must be consumable exactly once. The endpoint refuses to serve at all when
+   the store, `PRACHT_CONFIRMATION_SECRET`, or (in human mode) any resolvable
+   principal is missing; `pracht verify` warns when it cannot find the
+   registration in the configured source directories.
 3. The flow is unchanged; only the channel differs. Prepare answers
    `isError: true` with the token in `_meta["io.pracht/error"]`, and the commit
    repeats `tools/call` with identical `arguments` plus
    `_meta["io.pracht/confirmation"]`.
 
 Nested `invokeCapability()` under an MCP tool still refuses destructive callees
-unless the tool being served is a destructive capability that already cleared
+unless the served tool is itself a destructive capability that already cleared
 prepare/commit.
 
 ## Step 6: Call it
@@ -314,6 +323,8 @@ import { capabilities, useCapability } from "virtual:pracht/capabilities";
 const result = await capabilities.notes.search({ query: "roadmap" });
 ```
 
+Unresolvable in TS? Add `"@pracht/vite-plugin/virtual"` to tsconfig `types`.
+
 ```tsx
 // One contract for the human form and the agent tool.
 <Form capability="notes.create" onCapabilityResult={(result) => { /* … */ }}>
@@ -341,49 +352,45 @@ pracht eval --start "pracht preview"
 
 Once the declaration exists the compiler rejects unknown names, bad input,
 browser calls to private capabilities, destructive calls without
-`prepare`/`confirm`, and runtime-computed names (assert
-`as HttpCapabilityName`). Re-run `pracht typegen --check` in CI.
+`prepare`/`confirm`, and computed names (assert `as HttpCapabilityName`).
+Re-run `pracht typegen --check` in CI.
 
 `pracht eval` runs JSON scenarios against the live app and exits 1 on a failed
-expectation — the repeatable answer to "can an agent actually finish this
-task?". Steps can reference earlier results
-(`$steps[0].error.confirmationToken`) and a scenario-level `signAs` block signs
+expectation. Steps can reference earlier results
+(`$steps[0].error.confirmationToken`); a scenario-level `signAs` block signs
 every step as a verified agent.
 
-A scenario targets the HTTP projection by default; set scenario-level
-`"transport": "mcp"` to run the same steps over the app's remote MCP endpoint
-(`initialize` handshake, then one `tools/call` per step, tool names mapped
-`notes.search` → `notes_search`). Write one of each for any capability with
-`expose.mcp` — passing over HTTP does not prove an MCP host can reach it.
+A scenario targets HTTP by default; scenario-level `"transport": "mcp"` runs
+the same steps over the remote MCP endpoint (`initialize`, then one
+`tools/call` per step, names mapped `notes.search` → `notes_search`). Write one
+of each for any `expose.mcp` capability — passing over HTTP does not prove an
+MCP host can reach it.
 If `agents.mcp.auth` protects the endpoint, add scenario-level
-`"mcpHeaders": { "authorization": "Bearer …" }`; it applies to `initialize`
-and every later request. Inject test tokens in CI instead of committing real
-credentials. Step-level `headers.authorization` overrides it for one call.
-Expectations are portable: `expect.status` is the capability dispatch status on
-both transports, so the same `{ "ok": false, "status": 400, "errorCode":
-"invalid_input" }` holds either way.
-
-Three MCP limits fail loudly rather than silently: a step for a capability
-without `expose.mcp`, a step header other than `authorization` (the projection
-forwards nothing else), and a destructive step whose app has not enabled
-`agents.mcp.destructive` with an approval store. For an exposed destructive MCP
-tool, `confirm` completes the same prepare/commit round trip as HTTP; the token
-travels in the call's `_meta["io.pracht/confirmation"]` field.
+`"mcpHeaders": { "authorization": "Bearer …" }`; it applies to `initialize` and
+every later request, and step-level `headers.authorization` overrides it for
+one call. Inject test tokens in CI. Expectations are portable: `expect.status`
+is the capability dispatch status on both transports.
+
+Three MCP limits fail loudly: a step for a capability without `expose.mcp`, a
+step header other than `authorization` (the projection forwards nothing else),
+and a destructive step whose app has not enabled `agents.mcp.destructive` with
+an approval store. For an exposed destructive MCP tool, `confirm` completes the
+same prepare/commit round trip as HTTP, with the token in the call's
+`_meta["io.pracht/confirmation"]`.
 
 `createCapabilityTestHost()` from `@pracht/core` covers the same pipeline in
-unit tests without a server.
+unit tests, without a server.
 
-WebMCP specifics `pracht verify` checks for you: tool names must fit the
-spec's grammar (1–128 ASCII `[a-zA-Z0-9_.-]`); an effective
-`agentPolicy: "require"` makes a page tool dead (unsigned browser fetches
-always 401 — warned); descriptions have advisory budgets (~500 chars per
-tool, ~150 per schema parameter). Hosts: the ChatGPT desktop browser enables
-the API itself, but stable Chrome/Edge visitors only get
-`document.modelContext` if the page head carries an origin-trial token — the
-capabilities page on the docs site shows the shell `head()` recipe.
+WebMCP specifics `pracht verify` checks: tool names must fit the spec's
+grammar (1–128 ASCII `[a-zA-Z0-9_.-]`); an effective `agentPolicy: "require"`
+makes a page tool dead (unsigned browser fetches always 401 — warned);
+descriptions have advisory budgets (~500 chars per tool, ~150 per schema
+parameter). Hosts: the ChatGPT desktop browser enables the API itself, but
+stable Chrome/Edge visitors only get `document.modelContext` if the page head
+carries an origin-trial token — the docs site's capabilities page shows the
+shell `head()` recipe.
 
-For an audit of what the whole agent surface currently exposes, run
-`/audit-agent-surface`.
+To audit what the whole agent surface exposes, run `/audit-agent-surface`.
 
 ## Rules
 
@@ -394,16 +401,20 @@ For an audit of what the whole agent surface currently exposes, run
 2. Never widen a schema (drop `required`, open `additionalProperties`, raise a
    `maximum`) without saying so — `pracht plan` reports it as a widening of the
    agent-reachable surface for a reason.
-3. Keep `expose`, `effect`, and `input` as inline literals.
-4. Put authentication, authorization, and rate limiting in named middleware —
+3. Keep `expose` and `effect` inline; reuse a Standard JSON Schema validator for
+   `input`/`output` when the app already has one.
+4. Treat `expose.webmcp` as eligibility, not activation. Add the capability to
+   only the manifest routes/groups or Pages `CAPABILITIES` exports where an
+   in-page agent should see it.
+5. Put authentication, authorization, and rate limiting in named middleware —
    the framework ships no rate limiting, no write-idempotency helper, and no
    result-size budget. Bound outputs with a `limit` input and a schema
    `maximum`.
-5. Design `write` inputs to be safely repeatable; agents retry, and only
+6. Design `write` inputs to be safely repeatable; agents retry, and only
    `destructive` calls are token-gated.
-6. Never register an app-wide approval endpoint or UI without your own
+7. Never register an app-wide approval endpoint or UI without your own
    authorization — who may approve is an application decision.
-7. Re-run `pracht typegen` after changing a schema, name, or exposure, and
+8. Re-run `pracht typegen` after changing a schema, name, exposure, or route activation, and
    `pracht verify` before committing.
 
 $ARGUMENTS

package/skills/add-observability/SKILL.md

@@ -169,53 +169,26 @@ slowest loaders (cross-reference with `audit-bundles` perf hotspots).
 
 ## Step 4: Web Vitals on the client
 
-```bash
-pnpm add web-vitals
-```
-
-Create `src/client/vitals.ts` — export a function, **no module-level
-side effects**:
-
-```ts
-import { onCLS, onINP, onLCP, onFCP, onTTFB, type Metric } from "web-vitals";
-
-function send(metric: Metric) {
-  navigator.sendBeacon?.(
-    "/api/telemetry/vitals",
-    JSON.stringify({ name: metric.name, value: metric.value, id: metric.id, path: location.pathname }),
-  );
-}
-
-export function reportVitals() {
-  onCLS(send);
-  onINP(send);
-  onLCP(send);
-  onFCP(send);
-  onTTFB(send);
-}
-```
-
-Do NOT import this statically from a shell: shells render on the **server**
-too, so module-level `onCLS(...)` calls would execute during SSR. The primary
-pattern is a lazy `import()` inside an effect, guarded by `useIsHydrated`
-(exported from `@pracht/core`), placed in a shell or top-level component:
+Use the framework hook from a component mounted by a shared shell:
 
 ```tsx
-import { useIsHydrated } from "@pracht/core";
-import { useEffect } from "preact/hooks";
+import { useWebVitals } from "@pracht/core";
 
 export function Vitals() {
-  const hydrated = useIsHydrated();
-  useEffect(() => {
-    if (!hydrated) return;
-    void import("../client/vitals").then((m) => m.reportVitals());
-  }, [hydrated]);
+  useWebVitals((metric) => {
+    navigator.sendBeacon?.(
+      "/api/telemetry/vitals",
+      JSON.stringify({ name: metric.name, value: metric.value, id: metric.id, path: location.pathname }),
+    );
+  });
   return null;
 }
 ```
 
-This keeps `web-vitals` out of the critical bundle (lazy chunk) and only
-starts observers after hydration has fully settled.
+The hook is safe during SSR, lazy-loads `web-vitals` after mount, and shares a
+single observer set across callers. No separate dependency, hydration guard,
+or client-only module is needed, and apps that never call it ship no metrics
+runtime.
 
 ## Step 5: Beacon endpoint
 

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

@@ -1,6 +1,6 @@
 ---
 name: audit-agent-surface
-version: 1.0.4
+version: 1.1.0
 description: |
   Inventory what agents can reach in a pracht app — capability exposure (HTTP,
   WebMCP, remote MCP), `agents` trust config, the destructive-confirmation gate,
@@ -59,10 +59,17 @@ middleware → `agentPolicy`. A capability reported as `unreadable` means
 `@pracht/capabilities` is not installed; treat it as an `error` and stop
 reasoning about its policy until it loads.
 
-Cross-check `inspect agents` against the manifest's `agents` block. It reads
-resolved app and production `llmsTxt` config, including computed branches. A
-`null` `llmsTxt.enabled` means an older plugin: report unknown and recommend an
-upgrade. Use resolved `mcp.auth`; `null` means framework-level OAuth is open.
+Cross-check `inspect agents` against the app's `agents` config: the manifest's
+`agents` block, or the `agents` export of `src/pages/_app.config.ts` when
+`inspect` reports `"mode": "pages"`. It reads resolved app and production
+`llmsTxt` config, including computed branches. `llmsTxt.enabled: null` means an older
+plugin: report unknown and recommend upgrading. Use resolved
+`mcp.auth`; `null` means framework OAuth is open.
+
+Where capabilities are declared differs by router; what they expose does not.
+A pages app registers every module in `src/capabilities/` — read that
+directory, not a `capabilities` key. A pages app is not surface-free just
+because it has no `src/routes.ts`.
 
 ## Step 2: Exposure vs. intent
 
@@ -277,16 +284,16 @@ staleness, so trust it only when verify passes.
 
 When the app is supposed to have none:
 
-- Confirm the manifest registers no `capabilities` and no `agents`. That lets
-  the build define the surface away (~15 KB gzip of an example server bundle).
+- Confirm no `capabilities` and no `agents` are registered (pages apps: no
+  `src/capabilities/`, no `_app.config.ts`). That lets the build define the
+  surface away (~15 KB gzip in an example server bundle).
 - Analysis is one-sided: a spread, a regex literal, or otherwise opaque syntax
   in the manifest leaves the define unset and keeps the runtime in the bundle.
   Flag manifest constructs that defeat the static read.
-- Confirm `llmsTxt` is off if the app should not advertise itself, and that no
-  route sets `markdown: true`.
-- `create-pracht --no-agent-tools` controls the *scaffolded developer* tooling
-  (`.mcp.json`, skills) — it has nothing to do with the deployed agent surface.
-  Do not conflate them in the report.
+- Confirm `llmsTxt` is off if the app should not advertise itself, and no route
+  sets `markdown: true`.
+- `create-pracht --no-agent-tools` controls *scaffolded developer* tooling
+  (`.mcp.json`, skills), not the deployed agent surface. Do not conflate them.
 
 ## Step 8: Report
 
@@ -324,12 +331,10 @@ Severities:
 3. Do not treat client-declared signals as trust: the `webmcp` transport marker
    is informational, and only MCP dispatch state is trustworthy for
    attributing nested effects.
-4. Distinguish `pracht mcp` (the development-time stdio server exposing the app
+4. Distinguish `pracht dev-mcp` (the development-time stdio server exposing the app
    *graph* to coding agents) from the deployed `/mcp` endpoint exposing the app's
    *operations*. They have different threat models.
-5. State the framework guarantee before each finding so the reader can tell an
-   opt-out from a hole.
-6. Pair with `/audit-auth`, `/audit-csrf`, and `/audit-secrets` — this skill
+5. Pair with `/audit-auth`, `/audit-csrf`, and `/audit-secrets` — this skill
    owns agent reachability, not general request authorization.
 
 $ARGUMENTS

package/skills/audit-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit-auth
-version: 1.2.4
+version: 1.4.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
@@ -24,8 +24,18 @@ redirect `Response`. What the framework does NOT decide is *which* routes get
 an auth gate — that is app wiring, and this skill audits it.
 
 The pracht auth pattern (see `examples/docs/src/routes/docs/recipes-auth.md`):
-middleware checks the session, short-circuits with a redirect on absence, and
-forwards user info via request headers; loaders downstream read the headers.
+middleware loads the session onto `context.session` and short-circuits with a
+redirect when there is no user; loaders downstream read `context.session`.
+
+`@pracht/session` is the first-party implementation. Two of its exports map
+straight onto the Gate/Augmenter classification below — `requireSession()` is
+a Gate, `sessionMiddleware()` is an Augmenter — so a project using it can be
+classified from the factory name without reading the middleware body. A
+project that hand-rolls its session instead is not automatically wrong, but
+check it for the things the package handles: an expiry inside the signed
+payload (not only `Max-Age`), a constant-time or `crypto.subtle.verify`
+signature check, `HttpOnly`/`Secure`/`SameSite`, and encryption if the cookie
+carries anything beyond an opaque id.
 
 Prerequisites: `pracht inspect` requires a vite config that registers the
 pracht plugin.
@@ -40,19 +50,38 @@ MCP: when the pracht MCP server is registered (docs/MCP.md), prefer its
 `inspect_routes`/`inspect_api`/`inspect_build`/`doctor`/`verify` tools over
 shelling out.
 
-Middleware is registered by name in the app manifest —
-`defineApp({ middleware: { auth: () => import("./middleware/auth.ts") } })` —
-and `inspect` reports those names, not files. Read the name→file map from
-`src/routes.ts` (or the configured manifest) to resolve each name, then read
-each middleware file and classify it:
+`inspect` reports middleware names, not files. Resolve them according to the
+app's router mode, then read each middleware file and classify it:
+
+- **Manifest router:** read the name→file map from `src/routes.ts` (or the
+  configured manifest), where middleware is registered through
+  `defineApp({ middleware: { auth: () => import("./middleware/auth.ts") } })`.
+- **Pages router:** when the Vite config sets `pagesDir`, the generated name
+  `"pages"` resolves to the root `<pagesDir>/_middleware.ts` (or `.tsx`, `.js`,
+  or `.jsx`). It applies to every page route and never wraps API routes. There
+  is no `src/routes.ts` manifest to inspect unless the app has ejected. Follow
+  imports and re-exports into underscore-reserved helpers such as
+  `<pagesDir>/_server/auth.ts`; Pracht excludes those helpers from client
+  route/shell registries, but a direct import from client code still bundles
+  them and should be treated as a server-code leak.
+
+Then classify each resolved middleware module:
 
 - **Gate** — on auth failure, returns a short-circuit `Response`
   (`redirect("/login", { request })`, or a 401/403 `Response`) WITHOUT calling
-  `next()`; on success, `return next()`.
-- **Augmenter** — mutates request headers/context with user info, then always
-  returns `next()`. Never short-circuits.
+  `next()`; on success, `return next()`. `requireSession()` from
+  `@pracht/session` is one.
+- **Augmenter** — puts user info on `context` (or, in older code, on request
+  headers), then always returns `next()`. Never short-circuits.
+  `sessionMiddleware()` is one.
 - **Other** — non-auth middleware (rate limit, logging, CORS, etc.).
 
+Flag any middleware that writes identity onto `args.request.headers`: the
+client controls request headers, so a loader reading `x-user-id` back out is
+trusting attacker-supplied input, and the write throws outright on Cloudflare
+Workers where the incoming `Request` is immutable. Identity belongs on
+`context`.
+
 The "Augmenter" category is the silent killer: it makes loaders *think*
 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
@@ -63,7 +92,8 @@ to handle it. Flag every loader downstream of an Augmenter that doesn't.
 A route is "expected protected" if any of:
 
 - It has `auth`/`session`/`requireUser`/similar middleware applied.
-- Its loader reads `x-user-id`/`x-user-email`/`getSession`/equivalent.
+- Its loader reads `context.session`, `getSession`, or (legacy)
+  `x-user-id`/`x-user-email`.
 - It lives under conventional protected paths: `/dashboard*`, `/admin*`,
   `/account*`, `/settings*`, `/app*` (ask the user to confirm the
   convention if unclear).
@@ -80,6 +110,13 @@ For each expected-protected route:
 3. Confirm the gate runs **before** any other middleware that depends on
    identity (order matters).
 4. If only an Augmenter is present, mark as `augmented-only`.
+5. For pages-router routes, inspect `render` too. A root pages Gate on an
+   `ssg` or `isg` route does not protect the static document per visitor:
+   document middleware runs during build/revalidation with a sanitized request,
+   while later route-state requests are separate live requests. Unless an
+   independently verified platform/CDN edge gate protects the document, report
+   the route as `error` / `unprotected-static` and recommend `ssr`/`spa` for
+   session-gated pages.
 
 ## Step 4: Check the API surface
 
@@ -138,6 +175,22 @@ SPA route loaders.
 
 ## Step 6: Session cookie sanity
 
+With `@pracht/session`, check the configuration rather than the mechanics:
+`cookie.secrets` read from `serverEnv` (never a literal), the storage built
+inside a function rather than at module scope (Workers env is request-scoped),
+a `__Host-` cookie name unless subdomain sharing is required, and `sameSite`
+matching the app's embedding needs. A `store` is required for logout to
+invalidate a session anywhere other than the browser that asked.
+
+Then check the **login path for `session.regenerate()`**, called after
+credentials verify and before the user is written onto the session. Its
+absence is session fixation: with a store, an attacker who can plant a cookie
+for the host keeps a valid pointer to the session that becomes authenticated.
+Flag it as `error`/`fixation` on any store-backed app; on a cookie-only app it
+is `info` (the cookie carries the sealed data, not a pointer), but still worth
+adding before the app grows a store. Audit every other privilege change the
+same way — 2FA completion, role assumption, impersonation.
+
 Cross-reference with `audit-csrf`: the same cookies that authorize the user
 are the CSRF target. Recommend running `audit-csrf` after this skill.
 
@@ -151,9 +204,12 @@ Severity is the primary scale; the verdict is a secondary domain label:
 - `error` / `unprotected` — no auth middleware on a route the user expects
   protected.
 - `error` / `inconsistent` — UI route is gated; sibling API is not.
+- `error` / `unprotected-static` — a pages-router SSG/ISG document relies on
+  request/session middleware without an independent per-request edge gate.
 - `warn` / `augmented-only` — middleware reads session but never blocks;
   loader must handle null user.
 - `warn` / `client-only` — server allows; client hides UI.
+- `error` / `fixation` — store-backed session, no `regenerate()` at login.
 - `info` / `protected` — gate confirmed.
 - `info` / `public-by-design` — deliberately exposed (login, signup,
   marketing).

package/skills/audit-bundles/SKILL.md

@@ -108,7 +108,7 @@ For each route chunk over 50 KB gz, run `pracht inspect build --json` plus
 - Grep the chunk source for known heavy module headers (`moment`, `lodash`,
   `chart.js`, `three`, `@stripe/stripe-js`, etc.).
 - For each, recommend: (a) tree-shakeable alternative, (b) dynamic import
-  inside an event handler, (c) lazy-load via `lazy()` from `preact-suspense`.
+  inside an event handler, (c) lazy-load via `lazy()` from `@pracht/core`.
 
 ## Step 6: Prefetch strategy
 

package/skills/audit-shells/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: audit-shells
-version: 1.1.1
+version: 1.3.0
 description: |
   Audit pracht shells: missing `Loading()` on SPA routes, `<html>`/`<head>`/
   `<body>` rendered inside a shell, shells that never render `children`, unused
@@ -103,10 +103,17 @@ JSON first:
   JSON has no shell registry of its own, so "unused" means "registered in
   `defineApp` but referenced by no route or group".
 - **Pages apps** (`mode: "pages"`): there is no `defineApp` shell registry.
-  The shell is `src/pages/_app.tsx`, auto-registered under the name `"pages"`
-  and applied to every route (see docs/ROUTING.md). "Unused shells" analysis
-  does not apply; instead verify `_app.tsx` (if present) shows up as the
-  resolved shell on every route.
+  Each `_app` file is auto-registered — `src/pages/_app.tsx` as `"pages"`,
+  `src/pages/blog/_app.tsx` as `"pages:blog"` — and owns the routes in its
+  directory subtree (see docs/ROUTING.md). Shells **replace**, they do not
+  nest: the nearest `_app` above a route is the only one that renders it, so a
+  directory shell must carry its own `head()`/`headers()` rather than inherit
+  the parent's. "Unused shells" analysis does not apply; instead check
+  `pracht inspect routes --json` and confirm each route's `shell` is the
+  nearest `_app` you expect, and that no directory you meant to scope is
+  silently falling back to `"pages"`. An `_app` inside an underscore-reserved
+  tree (`src/pages/_components/_app.tsx`) is a plain helper, and two `_app`
+  files in one directory are a build, `doctor`, and `verify` error.
 
 Then report: