create-pracht 0.3.0 → 0.4.1

package/skills/pracht-debug/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: pracht-debug
+version: 1.3.0
+description: |
+  Pracht framework-aware debugging. Systematically investigates route matching,
+  loader/API route errors, rendering issues, middleware, API routes, HMR, and build
+  problems. Uses pracht's architecture knowledge to find root causes fast.
+  Use when asked to "debug this", "fix this bug", "why is this broken",
+  "blank page", "hydration mismatch", or "404 on my route".
+  Proactively suggest when the user reports errors or unexpected behavior
+  in a pracht application.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Debug
+
+Framework-aware debugging for pracht applications — a full-stack Preact framework built on Vite.
+
+The user will describe a symptom (error, unexpected behavior, blank page, etc.). Investigate systematically using the checklist below, stopping when you find the root cause.
+
+Before deep manual inspection, prefer running `pracht verify` (add `--changed` to scope the checks to git-changed files) for a fast agent loop or `pracht doctor` when the problem could be caused by broader broken app wiring or missing files.
+When another agent/tool needs the framework's resolved graph, prefer `pracht inspect routes --json`, `pracht inspect api --json`, or `pracht inspect build --json` over reconstructing it from source files. Prerequisites: `pracht inspect` needs the pracht plugin registered in the project's vite config, and `pracht inspect build` needs a prior `pracht build`.
+If the pracht MCP server is registered (docs/MCP.md), prefer the `inspect_routes`/`inspect_api`/`doctor`/`verify` MCP tools over shelling out — same payloads, structured results.
+While the dev server is running, `GET /_pracht` serves a devtools page with the same resolved route/API graph (raw JSON at `/_pracht.json`) — useful when you have a browser or `curl` handy but no CLI access. Dev SSR responses also carry a `Server-Timing` header (`mw`, `loader`, `render` durations in ms) — check it in the browser Network panel or with `curl -sI` to see which phase makes a route slow.
+
+## Iron Law
+
+**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
+
+## Debugging Checklist
+
+Work through these in order, stopping when you find the root cause:
+
+### 1. Route matching
+
+- Run `pracht verify --changed` first if you want a cheap changed-file confidence check.
+- Run `pracht doctor` if the route might be missing, miswired, or pointing at a missing module across the project.
+- For machine-readable route wiring, run `pracht inspect routes --json`. With a running dev server, `curl http://localhost:5173/_pracht.json` returns the same graph.
+- Read `src/routes.ts` — is the route defined? Is the path correct?
+- Check for typos in file paths (the manifest uses relative paths like `"./routes/home.tsx"`).
+- For dynamic segments, verify bracket syntax: `route("/users/:id", ...)` in manifest, `[id].ts` in filenames.
+- Grep for the route path across the manifest and check `matchAppRoute()` logic if needed.
+
+### 2. Typed route/link issues
+
+- If `<Link route="...">`, `href("...")`, or route-object `useNavigate()` fails to typecheck, run `pracht typegen --check` to detect stale generated files.
+- Run `pracht inspect routes --json` and confirm the route id exists. If it is a fallback id, remember path changes can rename it.
+- Check generated `src/pracht.d.ts` for inferred params. `:id`, `*`, and `:path*` params are required; extra params should fail at typecheck time.
+- If runtime navigation throws `Unknown pracht route id "..."`, in dev the error includes a `Did you mean "..."?` suggestion and the list of registered route ids (production builds tree-shake this and throw the bare error) — check for a typo first, then ensure `pracht typegen` was run and the component is rendered inside the pracht route tree.
+- For unexpected URLs, reproduce with `href(routeId, options)` and compare against the route's resolved path and params.
+
+### 3. Loader / API route errors
+
+- For slow pages, read the dev `Server-Timing` response header (`mw`/`loader`/`render` in ms) to see which phase dominates before reading code.
+- Read the route module's `loader` function or the matching API route handler.
+- Check that `loader` returns serializable data (no functions, no circular refs).
+- Check that API route handlers return `Response` objects and branch on `request.method` when using a default export.
+- Look for unhandled promise rejections or thrown errors.
+- Verify `LoaderArgs` destructuring matches what the framework provides: `{ request, params, context, signal, url, route }`.
+
+### 4. Rendering issues
+
+- **Blank page**: Check if the route has `render: "spa"` (no SSR content expected) vs `"ssr"`.
+- **Hydration mismatch**: In dev, pracht surfaces a fixed-position red banner at the top of the page listing each mismatched component (via Preact's `options.__m` hook). Compare server-rendered HTML vs client component output. Common causes:
+  - Date/time rendering differences
+  - Browser-only APIs used during SSR (`window`, `document`, `localStorage`)
+  - Conditional rendering based on client state
+- **Missing shell**: Referencing an unregistered shell name throws at manifest resolution — `Unknown shell "..." for route "...". Did you mean "..."? Registered shells: ...` — and shows up in the dev error overlay as soon as the server loads the manifest. Verify the shell is registered in `defineApp({ shells: { ... } })` and assigned to the route/group.
+- **404 page**: Route not matched — check manifest wiring (step 1). In `pracht dev`, unmatched navigations render a dev-only 404 page listing every registered route with its render mode; compare the requested path against that table. The route table is also printed on dev-server startup and available via `pracht inspect routes`. Apps that declare `defineApp({ notFound })` render their own 404 page instead (in dev and production alike), so the route table is not shown — check `pracht inspect routes` directly. A 404 on a URL you *do* expect to work usually means the loader threw `notFound()`, not that matching failed.
+
+### 5. Middleware issues
+
+- Verify middleware is registered in `defineApp({ middleware: { ... } })`. An
+  unregistered name (on a route, group, or `api.middleware`) throws at manifest
+  resolution — `Unknown middleware "..." for route "...". Did you mean "..."? Registered middleware: ...`
+- Verify middleware is applied to the route/group: `middleware: ["name"]`.
+- Middleware is wrap-around: it must always return a `Response`, either by
+  calling `await next()` (to continue down the chain) or short-circuiting.
+- Common bugs:
+  - Forgetting `return next()` → `Middleware "..." did not return a Response`
+  - Calling `next()` twice → `Middleware "..." called next() multiple times`
+  - Mutating a non-object `context` → mutations don't propagate; always pass
+    an object as the request context.
+- Middleware runs server-side only, wrapping loaders and API handlers.
+
+### 6. API route issues
+
+- API routes live in `src/api/` and are auto-discovered (no manifest entry needed).
+- For machine-readable API inventory, run `pracht inspect api --json`.
+- File path maps to URL: `src/api/health.ts` → `/api/health`, `src/api/users/[id].ts` → `/api/users/:id`.
+- Each file exports named HTTP method handlers (`GET`, `POST`, etc.) or one default handler.
+- Missing method handler → 405 response when there is no default handler.
+- Default handlers receive the same route args and can branch on `request.method`.
+- Handlers must return `Response` objects.
+
+### 7. Vite plugin / HMR issues
+
+- Check `vite.config.ts` — is `pracht()` plugin included?
+- Virtual modules: `virtual:pracht/client` (hydration), `virtual:pracht/server` (SSR), `virtual:pracht/islands-client` (islands hydration).
+- HMR: changes to `src/routes.ts` restart the dev server (`server.restart()`, not a browser-side full reload); changes to route/shell/middleware/API/server/islands files invalidate the server module.
+- If HMR seems broken, check that the file is in one of the watched directories (`src/routes/`, `src/shells/`, `src/middleware/`, `src/api/`, `src/server/`, `src/islands/`).
+
+### 8. Build / deployment issues
+
+- `pracht build` runs client + server builds, then prerenders SSG/ISG routes.
+- `pracht preview` builds and serves the production output locally (Node runs `dist/server/server.js`, Cloudflare delegates to `wrangler dev`).
+- `pracht inspect build --json` reports the resolved adapter target plus client/CSS/JS manifests from the latest build output (requires a prior `pracht build`).
+- Check `dist/client/` for client assets and `dist/server/` for server bundle.
+- ISG manifest: `dist/server/isg-manifest.json`. On Cloudflare the build also copies it to `dist/client/_pracht/isg.json` for the worker runtime to read via the assets binding.
+- Adapter mismatch: ensure `pracht({ adapter: nodeAdapter() })` or `cloudflareAdapter()` matches deployment target.
+
+## Key Files
+
+| File                  | Purpose                                               |
+| --------------------- | ----------------------------------------------------- |
+| `src/routes.ts`       | App manifest — all route/shell/middleware definitions |
+| `vite.config.ts`      | Vite config with `pracht()` plugin                    |
+| `src/routes/*.tsx`    | Route modules (loader, Component)                     |
+| `src/shells/*.tsx`    | Shell layout components                               |
+| `src/middleware/*.ts` | Server-side middleware                                |
+| `src/api/*.ts`        | API route handlers                                    |
+
+## Framework Internals
+
+- `handlePrachtRequest()` dispatches: API routes → middleware → loader → render → HTML assembly
+- Route state JSON: returned when `x-pracht-route-state-request` header is present (client-side navigation)
+- Hydration state: injected as `window.__PRACHT_STATE__` in the HTML
+- Client router: `initClientRouter()` intercepts link clicks and fetches route state JSON
+
+## Rules
+
+1. Always read the relevant source files before diagnosing.
+2. Start with the most likely cause based on the symptom, not a full audit.
+3. When you find the root cause, explain _why_ it breaks and fix it.
+4. If wiring looks suspicious, run `pracht verify` first, then `pracht doctor` if you need the full-project view. If running the dev server or tests would help, do so (`pracht dev`, `pnpm test`, `pnpm e2e`).
+5. After fixing, verify the fix works (run relevant test or check dev server output).
+6. Never say "this should fix it." Verify and prove it.
+
+$ARGUMENTS

package/skills/pracht-deploy/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: pracht-deploy
+version: 1.1.0
+description: |
+  Pracht deployment guide. Walks through adapter configuration, building, and
+  deploying to Node.js, Cloudflare Workers, or Vercel. Handles wrangler config,
+  Docker and production checklist.
+  Use when asked to "deploy", "set up deployment", "configure adapter",
+  "deploy to cloudflare", "deploy to vercel", or "production build".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Deploy
+
+Guided adapter setup and deployment for pracht applications.
+
+## Step 1: Determine the target
+
+Read `vite.config.ts` and `package.json` first — don't assume the current adapter.
+Ask the user where they want to deploy if not already clear from their message.
+
+If the pracht MCP server is registered (docs/MCP.md), prefer the `inspect_build`/`doctor`/`verify` MCP tools over shelling out. Note: `inspect_build` (like `pracht inspect build`) needs a prior `pracht build`, and `pracht inspect` requires the pracht plugin registered in the vite config.
+
+## Supported Adapters
+
+| Adapter            | Package                      | Status |
+| ------------------ | ---------------------------- | ------ |
+| Node.js            | `@pracht/adapter-node`       | Stable |
+| Cloudflare Workers | `@pracht/adapter-cloudflare` | Stable |
+| Vercel             | `@pracht/adapter-vercel`     | Stable |
+
+---
+
+## Node.js Deployment
+
+### Setup
+
+1. Ensure `@pracht/adapter-node` is installed.
+2. In `vite.config.ts`:
+   ```ts
+   import { pracht } from "@pracht/vite-plugin";
+   import { nodeAdapter } from "@pracht/adapter-node";
+   export default { plugins: [pracht({ adapter: nodeAdapter() })] };
+   ```
+
+### Build
+
+```bash
+pracht build
+```
+
+Produces:
+
+- `dist/client/` — static assets (JS, CSS, prerendered HTML)
+- `dist/server/server.js` — Node server entry
+- `dist/server/isg-manifest.json` — ISG revalidation config (if ISG routes exist)
+- `dist/client/.vite/manifest.json` — asset manifest for script/style injection
+
+### Run
+
+```bash
+node dist/server/server.js
+```
+
+Port 3000 by default. For a local production smoke test, `pracht preview` builds and runs the server in one step (`--port <n>`, `--skip-build` to reuse an existing build). For production: reverse proxy (nginx, Caddy), process manager (PM2, systemd), `NODE_ENV=production`.
+
+### Docker
+
+```dockerfile
+FROM node:22-alpine
+WORKDIR /app
+COPY dist/ dist/
+COPY package.json .
+EXPOSE 3000
+CMD ["node", "dist/server/server.js"]
+```
+
+---
+
+## Cloudflare Workers Deployment
+
+### Setup
+
+1. Ensure `@pracht/adapter-cloudflare` is installed.
+2. In `vite.config.ts`:
+   ```ts
+   import { pracht } from "@pracht/vite-plugin";
+   import { cloudflareAdapter } from "@pracht/adapter-cloudflare";
+   export default { plugins: [pracht({ adapter: cloudflareAdapter() })] };
+   ```
+
+### Build & Deploy
+
+```bash
+pracht build
+npx wrangler deploy
+```
+
+To smoke-test the built worker locally first, run `pracht preview` — it builds and then delegates to `wrangler dev`, which serves the wrangler config's `main` entry, `dist/server/worker.js`.
+
+### Wrangler Configuration
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "my-pracht-app",
+  "main": "dist/server/worker.js",
+  "compatibility_date": "2024-01-01",
+  "assets": {
+    "binding": "ASSETS",
+    "directory": "dist/client",
+    "run_worker_first": true,
+  },
+}
+```
+
+`"binding": "ASSETS"` and `"run_worker_first": true` are required. Without the binding, the worker's `env.ASSETS` resolves to nothing and the runtime silently falls back to `null` — headers and ISG manifests load empty, so SSG serving, ISG revalidation, and per-route headers all silently no-op. The canonical config lives at `examples/cloudflare/wrangler.jsonc`. If you rename the binding with `assetsBinding` (below), the wrangler `binding` value must match.
+
+### Bindings (KV, D1, R2)
+
+```ts
+export async function loader({ context }: LoaderArgs) {
+  const value = await context.env.MY_KV.get("key");
+  return { value };
+}
+```
+
+### Custom Assets Binding
+
+```ts
+pracht({ adapter: cloudflareAdapter({ assetsBinding: "STATIC" }) });
+```
+
+### ISG via Workers Caching
+
+ISG works out of the box: without any cache option, the default worker-managed path serves the build-time snapshot, detects staleness, and regenerates pages in the background via the Workers Cache API — per colo — and `POST /__pracht/revalidate` triggers on-demand regeneration. Enabling `cache: true` moves ISG from that per-colo worker-managed path to edge-tier Workers Caching, on both sides:
+
+```ts
+pracht({ adapter: cloudflareAdapter({ cache: true }) });
+```
+
+```jsonc
+// wrangler.jsonc
+{ "cache": { "enabled": true } }
+```
+
+Before enabling it, audit ISG URLs for unbounded query strings. Workers Caching
+keys the exact path and query string, including parameter order and trailing
+slashes; use a bounded query allowlist/canonical redirect or an uncached gateway
+with a pathname-only `cf.cacheKey`, and normalize `Accept` there for routes that
+export markdown. See `docs/ADAPTERS.md#cache-key-cardinality`.
+
+Time-revalidated ISG pages then render on demand, are cached at the edge for
+their `revalidate` window (stale pages served instantly while the Worker
+re-renders in the background), and can be purged early with `purgeCache()` from
+`@pracht/adapter-cloudflare/cache`. Webhook-only ISG routes keep their
+build-time snapshots and the worker-managed path either way.
+
+---
+
+## Vercel Deployment
+
+### Setup
+
+1. Ensure `@pracht/adapter-vercel` is installed.
+2. In `vite.config.ts`:
+   ```ts
+   import { pracht } from "@pracht/vite-plugin";
+   import { vercelAdapter } from "@pracht/adapter-vercel";
+   export default { plugins: [pracht({ adapter: vercelAdapter() })] };
+   ```
+
+### Build & Deploy
+
+```bash
+pracht build
+npx vercel deploy --prebuilt
+```
+
+Produces: `.vercel/output/config.json`, `.vercel/output/static/`, `.vercel/output/functions/render.func/server.js`
+
+---
+
+## Deployment Checklist
+
+1. **Build**: Run `pracht build` and verify `dist/` output.
+2. **Environment variables**: Ensure secrets/config needed by loaders are available at runtime.
+3. **Static assets**: Verify `dist/client/` contains prerendered HTML for SSG routes (and ISG routes — except time-revalidated ISG routes on Cloudflare with Workers Caching enabled, which render on demand; webhook-only ISG routes keep their build-time snapshots).
+4. **ISG routes**: Confirm the ISG manifest (`dist/server/isg-manifest.json`; on Cloudflare also `dist/client/_pracht/isg.json`) exists if using incremental static generation.
+5. **API routes**: Test API endpoints work in the production runtime. For Node.js, run `pracht preview` (or `node dist/server/server.js`).
+6. **Middleware**: Verify auth/redirect middleware behaves correctly in production.
+
+## Rules
+
+1. Read `vite.config.ts` and `package.json` before giving advice.
+2. Run `pracht build` to verify the build succeeds before deploying.
+3. Smoke-test the production runtime before pushing to production. For Node.js and Cloudflare, run `pracht preview`.
+4. If the user needs an adapter that isn't installed, help them add it (`pnpm add @pracht/adapter-*`).
+5. Don't push to production without the user's explicit confirmation.
+
+$ARGUMENTS

package/skills/pracht-scaffold/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: pracht-scaffold
+version: 1.1.0
+description: |
+  Pracht code scaffolding. Prefer the framework-native CLI generators
+  (`pracht generate route|shell|middleware|api`) and only fall back to manual
+  edits when the CLI flags cannot express the requested shape. Knows pracht
+  conventions (Preact idioms, render modes, route manifest).
+  Use when asked to "scaffold", "generate a route", "create a new page",
+  "add middleware", "add an API route", or "create a shell".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Scaffold
+
+Generate pracht framework modules with correct types, exports, and manifest wiring.
+
+## First Choice
+
+Use the CLI first:
+
+```bash
+pracht generate route --path /dashboard --render ssr
+pracht generate shell --name app
+pracht generate middleware --name auth
+pracht generate api --path /health --methods GET,POST
+```
+
+`pracht generate route` supports the full flag matrix below — do not fall back to manual edits for shapes it already covers:
+
+| Flag               | Meaning                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------ |
+| `--path` (required) | Route path, e.g. `/dashboard` or `/blog/:slug`                                       |
+| `--render`         | Render mode: `ssr` (default), `spa`, `ssg`, or `isg`                                 |
+| `--shell`          | Registered shell name (manifest apps only)                                           |
+| `--middleware`     | Registered middleware names, comma-separated (manifest apps only)                    |
+| `--loader`         | Include a `loader` export                                                            |
+| `--error-boundary` | Include an `ErrorBoundary` export                                                    |
+| `--static-paths`   | Include `getStaticPaths` (added automatically for dynamic `ssg`/`isg` paths)         |
+| `--title`          | Page title used in the `head()` export                                               |
+| `--revalidate`     | ISG revalidation window in seconds (`isg` only, default 3600)                        |
+| `--json`           | Machine-readable output                                                              |
+
+`generate shell` and `generate middleware` take `--name`; `generate api` takes `--path` and `--methods` (comma-separated). All subcommands accept `--json`.
+
+- `--shell`/`--middleware` names must already be registered in the app manifest — the CLI errors otherwise. Generate the shell/middleware first, then the route that references it.
+- If the pracht MCP server is registered (docs/MCP.md), call the `generate_route`/`generate_shell`/`generate_middleware`/`generate_api` MCP tools instead of Bash — same behavior, structured results.
+- Add `--json` when another agent/tool needs machine-readable output.
+- `generate route` also emits a Playwright smoke test in `e2e/` when the app has a Playwright setup (`playwright.config.*` or an `e2e/` directory). Pass `--no-test` to skip it, `--test` to force it. Keep the generated test — it is the output-level proof the route works.
+- Use `pracht inspect routes --json` or `pracht inspect api --json` to confirm current wiring before manual edits when the existing graph matters. `pracht inspect` requires the pracht plugin registered in the project's vite config.
+- If the app has typed routes (`src/pracht-routes.ts` / `.d.ts`) or the user asks for typed links, run `pracht typegen` after adding or renaming routes.
+- If the app commits `.pracht/app-graph.json`, run `pracht plan --write` after changing routes and include the refreshed snapshot — `pracht verify` fails when it is stale.
+- If `src/routes.ts` declares `constraints:`, respect them (e.g. put new `/app/**` routes behind the required middleware). Never delete or weaken a constraint to make `pracht verify` pass — that is a policy change the user must approve.
+- If the CLI can express the request, do not reimplement the scaffold by hand.
+- Only edit files manually when the CLI cannot cover the requested shape.
+
+The user will describe what they want to create. Parse their request and generate the appropriate module(s). Always ask if anything is ambiguous (e.g. render mode, shell assignment).
+
+## What You Can Scaffold
+
+| Kind       | Directory         | Key exports                                                          | Example                        |
+| ---------- | ----------------- | -------------------------------------------------------------------- | ------------------------------ |
+| Route      | `src/routes/`     | `loader`, `head`, `Component`, `ErrorBoundary`, `getStaticPaths`     | `src/routes/blog.tsx`          |
+| Shell      | `src/shells/`     | `Shell`, `head`                                                      | `src/shells/marketing.tsx`     |
+| Middleware | `src/middleware/` | `middleware`                                                         | `src/middleware/rate-limit.ts` |
+| API route  | `src/api/`        | Named HTTP method handlers (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) or one default method dispatcher           | `src/api/users/[id].ts`        |
+
+## Templates (manual fallback)
+
+Use these only when the CLI cannot express the requested shape.
+
+### Route
+
+```tsx
+export function head() {
+  return { title: "Page Title" };
+}
+
+export function Component() {
+  return <section>{/* route UI */}</section>;
+}
+```
+
+- Include a `loader` only when the route needs server data (matches the CLI, which omits it unless `--loader` is passed):
+
+  ```tsx
+  import type { LoaderArgs, RouteComponentProps } from "@pracht/core";
+
+  export async function loader(_args: LoaderArgs) {
+    return {
+      /* loader data */
+    };
+  }
+
+  export function Component({ data }: RouteComponentProps<typeof loader>) {
+    return <section>{/* route UI */}</section>;
+  }
+  ```
+
+- Include `ErrorBoundary` only if requested.
+- Include `getStaticPaths` only for SSG/ISG routes with dynamic segments.
+- Use `RouteComponentProps<typeof loader>` for typed `data` prop.
+
+### Shell
+
+```tsx
+import type { ShellProps } from "@pracht/core";
+
+export function Shell({ children }: ShellProps) {
+  return (
+    <div class="shell-name">
+      <nav>{/* navigation */}</nav>
+      <main>{children}</main>
+    </div>
+  );
+}
+
+export function head() {
+  return { title: "Shell Title" };
+}
+```
+
+### Middleware
+
+Middleware wraps the rest of the request via `next()`:
+
+```ts
+import { redirect, type MiddlewareFn } from "@pracht/core";
+
+export const middleware: MiddlewareFn = async ({ context, request }, next) => {
+  // Mutate context, validate auth, etc.
+  // - Call `return next()` to continue
+  // - Return `redirect("/path", { request })` to short-circuit with a redirect
+  // - Return any `Response` to short-circuit
+  // - Wrap `await next()` in try/catch/finally for tracing/logging
+  return next();
+};
+```
+
+### API Route
+
+```ts
+import type { ApiRouteArgs } from "@pracht/core";
+
+export function GET({ params, url }: ApiRouteArgs) {
+  return Response.json({
+    /* response data */
+  });
+}
+```
+
+- Only include the HTTP methods the user needs.
+- Use a default export only when the user wants to branch on `request.method` manually.
+- Use `request.json()`, `request.formData()`, etc. for body parsing.
+- Always return `Response` objects (typically `Response.json()`).
+- Dynamic segments use bracket syntax in filenames: `[id].ts`, `[...slug].ts`.
+
+## Wiring Into the Manifest (manual fallback only)
+
+The CLI generators wire the manifest themselves: `pracht generate route` inserts the `route(...)` call into `src/routes.ts` (adding `route`/`timeRevalidate` imports as needed), and `generate shell`/`generate middleware` upsert their registry entries. **Do not re-edit the manifest after a successful `pracht generate` run.**
+
+Only when you created module files by hand, update `src/routes.ts` to register the new module:
+
+- **Routes**: Add a `route("/path", () => import("./routes/filename.tsx"), { id: "name", render: "ssr" })` call inside the appropriate group or at the top level. Plain strings like `"./routes/filename.tsx"` also work.
+- **Shells**: Add to the `shells` record: `shellName: () => import("./shells/filename.tsx")` (or `"./shells/filename.tsx"`).
+- **Middleware**: Add to the `middleware` record: `mwName: () => import("./middleware/filename.ts")` (or `"./middleware/filename.ts"`).
+- **API routes**: No manifest change needed — auto-discovered from `src/api/` by the Vite plugin.
+
+Available render modes: `"ssr"` (default), `"ssg"` (static at build), `"isg"` (incremental static with `revalidate: timeRevalidate(seconds)`), `"spa"` (client-only).
+
+Import `timeRevalidate` from `"@pracht/core"` when using ISG.
+
+## Rules
+
+1. Prefer `pracht generate ...` over manual edits.
+2. Read the project's existing `src/routes.ts` to determine current shells, middleware, and route structure before adding when the CLI cannot finish the job on its own.
+3. Place files in the conventional directories (`src/routes/`, `src/shells/`, `src/middleware/`, `src/api/`).
+4. Keep generated code minimal — only include exports the user actually needs.
+5. Use Preact idioms: `class` not `className`, functional components, `import type` for type-only imports.
+6. When route ids/paths change in a typed-routes app, run `pracht typegen` and include the generated route files.
+7. Finish with `pracht verify` (and `pracht plan --write` when the app commits an app-graph snapshot).
+8. After scaffolding, summarize what was created and how it was wired.
+
+$ARGUMENTS