@paramour-js/next 0.4.0 → 0.5.0

package/skills/paramour/references/migration.md

@@ -0,0 +1,141 @@
+# Migration: converting raw params/searchParams to paramour
+
+## THE RULE
+
+Migrate INCREMENTALLY: one route per pass. For each pass — define the route object, convert that route's files, run `paramour check` plus the project type check, commit, then move to the next route. NEVER rewrite all routes at once. Paramour routes and raw `params`/`searchParams` access coexist without conflict, so a partially migrated app is a normal, stable state. If asked to "migrate the app", plan a route-by-route sequence and execute it as separate verified passes.
+
+Prerequisite: paramour is installed and `withTypedRoutes` is wired (otherwise do `references/setup.md` first — `npx paramour init` is safe to run on an existing project).
+
+## Worked example: one App Router route
+
+### Before
+
+```tsx
+// app/products/[id]/page.tsx
+export default async function ProductPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ id: string }>;
+  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
+}) {
+  const { id } = await params;
+  const sp = await searchParams;
+  const page = Number(sp.page ?? "1");
+  const sort = sp.sort === "desc" ? "desc" : "asc";
+  const q = typeof sp.q === "string" ? sp.q : undefined;
+  // ...
+}
+```
+
+### After
+
+1. Define the route object, colocated with the page:
+
+```ts
+// app/products/[id]/route.def.ts
+import { defineAppRoute, p } from "paramour";
+
+export const productRoute = defineAppRoute("/products/[id]", {
+  params: { id: p.integer() },
+  search: {
+    page: p.integer().default(1),
+    q: p.string().optional(),
+    sort: p.enum(["asc", "desc"]).default("asc"),
+  },
+});
+```
+
+2. Convert the page (and `generateMetadata`, which takes the same props):
+
+```tsx
+// app/products/[id]/page.tsx
+import type { RouteProps } from "paramour";
+import { productRoute } from "./route.def";
+
+export default async function ProductPage(props: RouteProps) {
+  const { params, search } = await productRoute.parse(props);
+  // params.id: number — search.page: number — search.sort: "asc" | "desc"
+  // search.q: string | undefined
+  // ...
+}
+```
+
+3. Verify: `paramour check` (the path already existed, so usually no artifact change), then `tsc --noEmit`. Commit.
+
+## Mapping decisions
+
+### Dynamic segments → `params:` codecs
+
+- `[id]` numeric in practice → `p.integer()`; otherwise keep `p.string()` (behavior-preserving — when unsure, `p.string()` first, tighten later).
+- `[...slug]` / `[[...slug]]` → the codec describes ONE segment element (usually `p.string()`); the array comes from the path shape. Decoded type is `Out[]`; an absent optional catch-all decodes to `[]`.
+- Presence modifiers are illegal in `params:` — optionality lives in the path grammar (`[[...slug]]`), not the codec.
+
+### searchParams reads → `search:` codecs
+
+- `sp.x ?? "default"` / `Number(sp.x ?? "1")` → codec with `.default(value)`. The decoded field is non-optional and the default value elides from built URLs.
+- "May be absent, no fallback" (`typeof sp.x === "string" ? sp.x : undefined`) → `.optional()`. Decoded as `T | undefined`.
+- Silent-coercion tolerance (old code shrugged off garbage, e.g. `Number(...)` producing `NaN` handled downstream) → add `.catch(fallback)` so a malformed PRESENT value falls back instead of failing the decode. `.catch()` never covers absence — combine with `.default()`/`.optional()` for that.
+- Multi-value keys (`sp.tags` handled as `string | string[]`) → `p.array()` for repeated keys (`?tags=a&tags=b`) or `p.csv()` for one comma-joined key (`?tags=a,b`). Match whichever wire form the app already emits.
+- Enumerated strings → `p.enum(["a", "b"])`; numbers → `p.number()`; booleans (`sp.flag === "true"`) → `p.boolean()`; dates → `p.isoDate()` (YYYY-MM-DD) or `p.timestamp()` (ISO UTC).
+
+### Behavior change to decide explicitly
+
+Raw code silently tolerated malformed URLs; `route.parse` THROWS `ParamsDecodeError`/`SearchDecodeError` on them. Pick one per route:
+
+- `parse` + a colocated `error.tsx` boundary (malformed URL renders the boundary), or
+- `safeParse` and branch on the result: `if (result.status === "error") notFound();` (or render a fallback), or
+- keep `parse` but add `.catch()` on the keys that used to be silently coerced.
+
+### Client components in the route
+
+Replace `useParams()` / `useSearchParams()` reads with the typed hooks:
+
+```tsx
+"use client";
+import { useRouteParams, useSearch } from "@paramour-js/next/app";
+import { productRoute } from "./route.def";
+
+export function Panel() {
+  const params = useRouteParams(productRoute); // SafeResult
+  const search = useSearch(productRoute);
+  if (params.status === "error" || search.status === "error") return null;
+  return <span>{search.data.q ?? ""}</span>;
+}
+```
+
+`useRouteParamsOrThrow`/`useSearchOrThrow` throw to the nearest error boundary instead of returning the error arm. Pages Router components use `@paramour-js/next/pages` (`useRouteParams`/`useSearch`, which add a `pending` status arm; server side, `route.parseContext(ctx)` in `getServerSideProps`).
+
+### Links into the migrated route
+
+Replace hand-built strings with `href` wherever the route is linked:
+
+```tsx
+// before
+<Link href={`/products/${id}?page=2`}>
+// after
+<Link href={href(productRoute, { params: { id }, search: { page: 2 } })}>
+```
+
+`href(...)` returns a string subtype — `next/link`, `router.push`, and `redirect` accept it unchanged. Convert the links you find; ones you miss keep working (they are just untyped strings) and can be converted in later passes.
+
+### Static generation
+
+`generateStaticParams` → build entries with `encodeStaticParams(route, { id: 42 })` from `paramour`, which returns the per-param wire-string record Next expects.
+
+## What NOT to touch in a pass
+
+- Other routes' raw `params`/`searchParams` access — leave it alone until that route's own pass.
+- Shared layouts/components serving unmigrated routes.
+- Unrelated search keys the page never read — do not "complete" the search config speculatively; declare only what the route actually uses (undeclared keys are ignored by decode and never emitted by encode).
+- Wire formats: do not change a param's URL spelling (e.g. csv ↔ repeated keys) while migrating; preserve existing URLs, change formats in a separate deliberate commit.
+
+## Per-route checklist
+
+1. Read every file of the route (page, layout if it reads params, generateMetadata, client components, links into it) and inventory each `params`/`searchParams` key and its fallback semantics.
+2. Create `route.def.ts` with `defineAppRoute` (or `definePagesRoute`): `params:` codec per dynamic segment, `search:` codec per read key with `.default()`/`.optional()`/`.catch()` matching the old semantics.
+3. Convert server access: props typed `RouteProps`; `route.parse(props)` / `parseParams` / `parseSearch` (or the `safeParse*` forms). Decide the malformed-URL story (error boundary vs safeParse vs `.catch()`).
+4. Convert the route's client components to `@paramour-js/next/app` (or `/pages`) hooks.
+5. Convert links into the route to `href(route, ...)`.
+6. Run `paramour check` (regenerate + commit the artifact if routes were added/renamed), then the type check and tests.
+7. Commit. Next route.

package/skills/paramour/references/reference.md

@@ -0,0 +1,96 @@
+# Reference: exports, CLI, config, wire format
+
+<!--
+  The tables and the "Key types" list in this file are drift-checked against
+  the package source by packages/next/test/skill-drift.test.ts. Keep each
+  cited export a single backtick token (`name` or `name(...)`) in the listed
+  column, flags spelled `--flag` in the Flags column, and wire-rule IDs in
+  their published S/P/D/CV/R/PP spelling.
+-->
+
+## `paramour` barrel exports
+
+Runtime values:
+
+| Export                                                                                               | Purpose                                                                                                         |
+| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `p`                                                                                                  | Codec builders: `string, integer, number, boolean, enum, isoDate, timestamp, json, csv, array, index, custom`   |
+| `defineAppRoute(path, config)`                                                                       | Define an App Router route object (`config: { params?, search? }`)                                              |
+| `definePagesRoute(path, config)`                                                                     | Define a Pages Router route object                                                                              |
+| `href(routeOrStaticPath, options?)`                                                                  | Build a typed link (`{ params?, search?, hash? }`); returns `Href` (string subtype)                             |
+| `buildPath(route, params)`                                                                           | Path portion only (`/a/b`), no query                                                                            |
+| `encodeParams(route, params)`                                                                        | Encoded path segments as `string[]`                                                                             |
+| `encodeStaticParams(route, params)`                                                                  | Per-param wire-string record for `generateStaticParams` / `getStaticPaths`                                      |
+| `decodeParams(route, source, opts?)`                                                                 | Sync params decode; throws `ParamsDecodeError`; `opts: { percentDecode?: boolean }` (default true — App Router) |
+| `decodeSearch(config, source, routePath?)`                                                           | Sync search decode; throws `SearchDecodeError`; unknown keys ignored                                            |
+| `safeDecodeParams` / `safeDecodeSearch`                                                              | `SafeResult`-returning twins of the two decoders                                                                |
+| `encodeSearch(config, input)`                                                                        | Decoded values → ordered wire pairs `[string, string][]` (default elision applied)                              |
+| `buildSearchString(pairs)`                                                                           | Pairs → `?…` string (`%20`, never `+`)                                                                          |
+| `searchToString(config, input)`                                                                      | `encodeSearch` + `buildSearchString`                                                                            |
+| `serializeValue(codec, label, value)`                                                                | One value through a codec's serializer, string contract enforced                                                |
+| `rawSearch(schema)` / `isRawSearch(config)`                                                          | Whole-object search escape hatch and its discriminant                                                           |
+| `standardSearchSchema(route)`                                                                        | Export a route's search config as a Standard Schema (tRPC input, TanStack `validateSearch`)                     |
+| `describeCodec(codec)` / `describeRoute(route)` / `formatCodecDescription(desc, style)`              | Reflection over codec/route metadata (powers `paramour list`)                                                   |
+| `ParamourError, ParseError, SerializeError, ParamsDecodeError, SearchDecodeError, SearchSourceError` | Error classes (brand-hardened `instanceof`)                                                                     |
+
+Key types: `Codec`, `AnyCodec`, `OutputOf`, `ParamCodec`, `Presence`, `PresenceOf`, `Arity`; `AppRoute`, `PagesRoute`, `Route`, `AnyRoute`, `AnyAppRoute`, `AnyPagesRoute`, `RouterKind`, `PagesContext`; `RouteProps`, `ParamsProps`, `SearchProps` (+ `*Input` sync-accepting forms) — annotate page/layout props with these; `InferRouteParams`, `SearchOutputOf`, `InferSearchInput`, `InferSearchOutput`, `InferStaticParams`, `InferHrefInput`, `HrefArgs`, `Href`, `StaticHrefOptions`; `SafeResult`, `RouteDecodeError`, `Issue`, `IssueReason`; `ParamsConfig`, `SearchConfig`, `ParamsSource`, `SearchSource`, `RawSearch`, `StandardSearchSchema`; `ParamourRegister` + `Registered*RoutePaths` (codegen augmentation targets); `CodecDescription`, `RouteDescription`, `ParamDescription`, `SearchDescription`, `CodecDefaultDescription`, `CodecFormatStyle`; `DecodeParamsOptions`.
+
+## `@paramour-js/next` exports
+
+| Entry point                       | Exports                                                                                                                                                                     |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@paramour-js/next`               | `withTypedRoutes(config, options?)` (`options: { outFile?, strict? }`), `RouteCollisionError`, types `WithTypedRoutesOptions`, `ParamourConfig`                             |
+| `@paramour-js/next/app`           | `useRouteParams`, `useRouteParamsOrThrow`, `useSearch`, `useSearchOrThrow` (all `(route, options?)` with `options: { select, equality?: "shallow" }`), type `SelectOptions` |
+| `@paramour-js/next/pages`         | `useRouteParams`, `useSearch` (return `RouterResult` = `SafeResult` + `{ status: "pending" }`), types `RouterResult`, `SelectOptions`                                       |
+| `@paramour-js/next/testing`       | `ParamourTestingProvider`, `withParamourTesting(options?)`, type `ParamourTestingOptions` (`isReady, mounted, onReplace, params, pathname, search`)                         |
+| `@paramour-js/next/devtools-seam` | Types-only seam contract consumed by `@paramour-js/devtools`; not needed in app code                                                                                        |
+
+## CLI (`paramour <command>`, bin shipped by `@paramour-js/next`)
+
+Exit-code contract for every command: `0` success; `1` ONLY a failed verification (`check` drift, `doctor` fail, `skills --check` missing/stale); `2` usage/config/operational errors.
+
+| Command    | Purpose                                                                                                          | Flags                                                                                                                                                                                                              |
+| ---------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `generate` | Write `paramour-env.d.ts` from route dirs                                                                        | `--app-dir <dir>`, `--pages-dir <dir>`, `--out-file <file>`, `--page-extensions <list>`, `--check`, `--watch`                                                                                                      |
+| `check`    | Verify the artifact is current; exit 1 on drift or missing; never writes                                         | `--app-dir`, `--pages-dir`, `--out-file`, `--page-extensions`                                                                                                                                                      |
+| `init`     | Set up paramour: scaffold config, wrap next.config, add script, first generate, agent skills + AGENTS.md snippet | `--dry-run`, `--force`, `--no-config`, `--no-generate`, `--no-script`, `--no-wrap`, `--no-skills`, `--no-agents-md`                                                                                                |
+| `list`     | Print every filesystem route with its params/search shape (evaluates route-definition modules)                   | `--json`, `--app-dir`, `--pages-dir`, `--page-extensions`                                                                                                                                                          |
+| `doctor`   | Diagnose setup: config validity, artifact freshness, next.config wrapping, versions, tsconfig                    | `--json`; exit 1 on any failing check, warnings exit 0                                                                                                                                                             |
+| `skills`   | Install/sync this agent skill into detected tool dirs (`.claude/`, `.cursor/`, …)                                | `--check` (verify only; exit 1 on missing/stale), `--dry-run`, `--force` (overwrite user-edited files), `--json`, `--tool <t>` (agents, claude, codex, cursor; repeatable or comma-separated, overrides detection) |
+
+All commands accept `--help`/`-h` and run against `process.cwd()` as the project root.
+
+## `paramour.config.{ts,mjs,json}` (project root; first match wins; all fields optional)
+
+Precedence: CLI flags → config file → discovery. Unknown keys are rejected (exit 2).
+
+| Field            | Default                     | Meaning                                                                                                |
+| ---------------- | --------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `appDir`         | discovered `app/`/`src/app` | App directory, relative to project root                                                                |
+| `pagesDir`       | discovered `pages/`…        | Pages directory                                                                                        |
+| `outFile`        | `paramour-env.d.ts`         | Artifact path (monorepo escape hatch); also settable on `withTypedRoutes`                              |
+| `pageExtensions` | `["tsx","ts","jsx","js"]`   | No leading dots                                                                                        |
+| `routeFiles`     | automatic content scan      | Globs of modules exporting route definitions — used by `list`/`doctor` only; generation never reads it |
+
+`.ts`/`.mjs` files default-export the object (`export default {...} satisfies ParamourConfig`).
+
+## Wire-format summary (numbered spec: docs/reference/wire-format on paramour.dev)
+
+| Family | Scope                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| S      | Byte layer: `%20` never `+` (S2); absence = omitted key, `""` = `key=` (S3); never bare `?flag` (S4); deterministic declaration order (S5); hash only from `href`'s explicit option, verbatim (S10)                                                                                                                                                                                          |
+| P      | Parse layer: duplicate values on a scalar codec are an error, catchable (P5); absent array key → `[]` (P6); unknown keys ignored and never validated (P8)                                                                                                                                                                                                                                    |
+| SS     | `rawSearch`: explicit wrapper only; schema sees every key on decode; encode is a raw pass-through, schema never runs; no elision/round-trip                                                                                                                                                                                                                                                  |
+| D      | Codec grammar: `.catch()` recovers parse failures never absence (D2); presence governs absence and every declared key appears in decode output (D4); params take no presence modifiers (D5); a catch-all codec describes one element (D6); value defaults elide (D8)                                                                                                                         |
+| CV     | `p.csv`: one comma-joined wire value; `""` ↔ `[]`; empty elements are parse failures; serialize rejects elements that are empty or contain commas                                                                                                                                                                                                                                            |
+| R      | Route segments: one segment per `[param]` (R1); catch-all elements encode independently, inner `/` → `%2F` (R2); optional catch-all elides, required `[]` is a `SerializeError` (R3); empty segment value is a `SerializeError` (R4); App Router param props arrive percent-ENCODED and core decodes them — Pages surfaces opt out via `percentDecode: false` (R5); no trailing slashes (R6) |
+| PP     | `p.array` typed elements by composition (PP1); `p.index` is 1-based on the wire, 0-based in memory (PP5)                                                                                                                                                                                                                                                                                     |
+
+Facts agents trip on:
+
+- Booleans serialize as exactly `true`/`false`; anything else fails to parse.
+- Dates: `p.isoDate` is `YYYY-MM-DD`; `p.timestamp` is full ISO UTC (`Z` only, offsets rejected); both reject impossible calendar dates.
+- Integers reject `1e3`, hex, whitespace, and unsafe-range values.
+- Arrays: `p.array` repeats the key (`?t=a&t=b`); `p.csv` packs one key (`?t=a,b`). Same in-memory `string[]`, two deliberate wire spellings — do not swap them casually.
+- Value-form `.default()` elides: building a URL with the default value emits nothing for that key; decoding the bare URL restores the default. Factory defaults never elide.
+- An href with no emitted pairs has no `?` at all; a fully elided optional catch-all leaves the bare base path (`/docs`, never `/docs/`).

package/skills/paramour/references/setup.md

@@ -0,0 +1,139 @@
+# Setup: adding paramour to a project (greenfield)
+
+## 1. Install both packages
+
+```sh
+npm install paramour @paramour-js/next
+# or
+pnpm add paramour @paramour-js/next
+# or
+yarn add paramour @paramour-js/next
+```
+
+Requirements: `next >= 15`, `react >= 18.2`, Node `>= 22.13` for the CLI. ESM-only packages.
+
+## 2. Run `npx paramour init`
+
+`init` is non-interactive and idempotent: it runs straight through with defaults and prints one status line per step. Steps:
+
+1. Scaffold `paramour.config.ts` at the project root (all fields commented-out defaults — deleting the file changes nothing). Skipped if any `paramour.config.{ts,mjs,json}` already exists; `--force` overwrites/replaces it.
+2. Wrap `next.config.*` with `withTypedRoutes` via an AST transform. If no next.config exists or the transform cannot apply safely, it prints a manual snippet to apply yourself — that is still a SUCCESS outcome (exit 0), not a failure.
+3. Add `"paramour": "paramour generate"` to `package.json` scripts.
+4. Run the first generate (skipped with a warning if no `app/` or `pages/` directory exists yet).
+5. Install the paramour agent skill files into detected agent tool directories (`.claude/`, `.cursor/`, etc.); skip with `--no-skills`.
+6. Append a marker-delimited (`<!-- paramour:start -->` … `<!-- paramour:end -->`) paramour section to an existing `AGENTS.md` (or, failing that, `CLAUDE.md`) pointing agents at the installed skill and the verify loop. Never creates the file; re-runs refresh the section in place; skip with `--no-agents-md`.
+
+Then a `setup:` detect-and-verify summary (route dirs found, both packages declared, tsconfig `include` covers the artifact) — these are warn-level and never change the exit code — and a final reminder to commit the artifact.
+
+Output marks to recognize:
+
+- `✔ created paramour.config.ts` / `✔ wrapped next.config.ts with withTypedRoutes` / `✔ added "paramour" script to package.json` / `✔ wrote paramour-env.d.ts (N routes)` — step performed.
+- `• ... already exists — skipped` / `• ... already wraps withTypedRoutes — skipped` / `• ... already up to date — skipped` — idempotent skip; fine.
+- `→ could not transform ... — apply this yourself:` followed by an indented snippet — apply the printed snippet manually, then continue; exit is still 0.
+- `⚠ no route directory yet — skipped generate` — create `app/` or `pages/`, then run `paramour generate`.
+
+Flags: `--dry-run` (report every step, write nothing), `--force` (overwrite an existing paramour.config), `--no-config`, `--no-generate`, `--no-script`, `--no-wrap`, `--no-skills`, `--no-agents-md`, `--help`/`-h`.
+
+## 3. Manual equivalent (when init cannot be used)
+
+Scaffold `paramour.config.ts` (optional — only needed to override discovery; every value shown is the default):
+
+```ts
+import type { ParamourConfig } from "@paramour-js/next";
+
+export default {
+  // appDir: "app",
+  // outFile: "paramour-env.d.ts",
+  // pageExtensions: ["tsx", "ts", "jsx", "js"],
+  // pagesDir: "pages",
+  // routeFiles: ["src/routes/**/*.ts"], // pin `paramour list`'s definition scan
+} satisfies ParamourConfig;
+```
+
+Wrap next.config:
+
+```ts
+import { withTypedRoutes } from "@paramour-js/next";
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {};
+
+export default withTypedRoutes(nextConfig);
+```
+
+`withTypedRoutes(config, options?)` regenerates the artifact once per production build (drift warns; `{ strict: true }` fails the build on drift instead) and runs a debounced regeneration watcher during `next dev`. `{ outFile: "..." }` relocates the artifact (monorepo escape hatch). Generation is never load-bearing: a missing route dir or an incidental failure warns and continues with stale types — the two exceptions that throw are an app↔pages route collision and a populated-but-ignored route dir.
+
+Add the script to `package.json`:
+
+```json
+{ "scripts": { "paramour": "paramour generate" } }
+```
+
+## 4. Define a first route
+
+Colocate a route definition next to its page (any module works; `route.def.ts` beside `page.tsx` is the common pattern):
+
+```ts
+// app/product/[id]/route.def.ts
+import { defineAppRoute, p } from "paramour";
+
+export const productRoute = defineAppRoute("/product/[id]", {
+  params: { id: p.integer() },
+  search: {
+    page: p.integer().default(1),
+    q: p.string().optional(),
+  },
+});
+```
+
+Use it in the page. Annotate props with paramour's `RouteProps` (Next's promised `params`/`searchParams` are structurally assignable to it):
+
+```tsx
+// app/product/[id]/page.tsx
+import type { RouteProps } from "paramour";
+import { productRoute } from "./route.def";
+
+export default async function ProductPage(props: RouteProps) {
+  // Throws ParamsDecodeError/SearchDecodeError on a malformed URL — pair
+  // with an error.tsx boundary, or use safeParse for a status-discriminated
+  // result instead of a throw.
+  const { params, search } = await productRoute.parse(props);
+  return (
+    <h1>
+      Product #{params.id} (page {search.page})
+    </h1>
+  );
+}
+```
+
+Build links to it from anywhere:
+
+```ts
+import { href } from "paramour";
+import { productRoute } from "@/app/product/[id]/route.def";
+
+const link = href(productRoute, { params: { id: 42 }, search: { q: "hi" } });
+// "/product/42?q=hi" — page=1 elides because it equals the default
+```
+
+## 5. Generate, verify, commit
+
+```sh
+npx paramour generate   # writes paramour-env.d.ts
+npx paramour check      # exit 0 = artifact current
+```
+
+Commit `paramour-env.d.ts` with the route change. The artifact is a pure `.d.ts` module augmentation (`declare module "paramour" { interface ParamourRegister { ... } }`) that turns `defineAppRoute`/`definePagesRoute` path literals and `href("/static/path")` strings into filesystem-verified unions. Ensure the project tsconfig `include` covers it (Next's default `**/*.ts` include does).
+
+## Exit codes (all CLI commands)
+
+- `0` — success, including init's printed manual-fallback snippets and idempotent skips.
+- `1` — ONLY "the thing you asked me to verify is not true": `check` (or `generate --check`) drift or missing artifact, `doctor` with a failing check, `skills --check` with missing/stale skill files.
+- `2` — usage/config/operational errors: unknown command or flag, invalid `paramour.config` (unknown key, dotted `pageExtensions` entry), no `package.json` for init, no route directory for generate, app↔pages route collisions.
+
+## Common failure modes
+
+- `paramour check` exit 1 saying `out of date` or `is missing`, with a route diff: run `paramour generate` and commit. If it says `content differs from generator output` with no route diff, someone hand-edited the artifact — regenerate, never edit.
+- Route collision (same path served by both `app/` and `pages/`): exit 2 from the CLI and a thrown error from `withTypedRoutes` — remove one of the duplicates; Next itself cannot build that state either.
+- `no route directory` from `paramour generate`: run from the project root (the directory holding `app/`/`pages/` or `src/app/`/`src/pages/`), or set `appDir`/`pagesDir` in `paramour.config.ts`.
+- Registered-path types not narrowing (any string accepted in `defineAppRoute`): the artifact is missing or not covered by tsconfig `include` — run `paramour doctor`.