@paramour-js/next 0.4.1 → 0.7.0

package/skills/paramour/references/authoring.md

@@ -0,0 +1,113 @@
+# Authoring: codecs, routes, links, hooks
+
+## `p.*` codec builders (import `{ p }` from `"paramour"`)
+
+Wire grammars are strict and anchored — no `Number()` coercion, no whitespace, no hex, no `1e3` for integers. Every parse failure is a `ParseError` (recoverable per-key with `.catch()`); every serialize failure is a `SerializeError` at link-build time.
+
+<!--
+  The Builder column below is drift-checked against Object.keys(p) by
+  packages/next/test/skill-drift.test.ts — keep each row's first cell a
+  single `p.name(...)` backtick token.
+-->
+
+| Builder              | Decoded type     | Wire behavior                                                                                                                                                                                                                                  | Options                                                                                             |
+| -------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `p.string(schema?)`  | `string`         | Verbatim text. Empty string is a real value (`key=`), not absence.                                                                                                                                                                             | Optional Standard Schema `<string, string>` refinement (runs on parse AND serialize)                |
+| `p.integer(schema?)` | `number`         | `/^-?\d+$/`, safe-integer range.                                                                                                                                                                                                               | Optional Standard Schema `<number, number>`                                                         |
+| `p.number(schema?)`  | `number`         | Decimal/scientific notation, finite only.                                                                                                                                                                                                      | Optional Standard Schema `<number, number>`                                                         |
+| `p.boolean()`        | `boolean`        | Exactly `"true"` / `"false"`.                                                                                                                                                                                                                  | —                                                                                                   |
+| `p.enum(members)`    | union of members | Exact member match. `p.enum(["asc", "desc"])` decodes to `"asc" \| "desc"`.                                                                                                                                                                    | Non-empty readonly string tuple                                                                     |
+| `p.isoDate()`        | `Date`           | `YYYY-MM-DD`, real calendar dates only (rejects `2026-02-30`); serializes UTC date part.                                                                                                                                                       | —                                                                                                   |
+| `p.timestamp()`      | `Date`           | ISO 8601 UTC only (`...T..:..:..[.mmm]Z`, offsets rejected); serializes `Date#toISOString()`.                                                                                                                                                  | —                                                                                                   |
+| `p.json(schema)`     | schema output    | `JSON.parse` then schema; serialize re-validates then `JSON.stringify`.                                                                                                                                                                        | Standard Schema (required)                                                                          |
+| `p.index(schema?)`   | `number`         | 1-based on the wire, 0-based in memory: `?page=1` ↔ `0`. Wire `< 1` is a parse failure; negative in-memory index is a `SerializeError`.                                                                                                        | Optional Standard Schema `<number, number>` (validates the 0-based value)                           |
+| `p.csv(element?)`    | `E[]`            | ONE wire value, comma-joined (`?tags=a,b`). Empty wire string is `[]`; `a,,b` / trailing comma are parse failures; serializing an element that is empty or contains a comma is a `SerializeError`. Arity "single" — full modifier set applies. | Optional element codec (default `p.string()`); element must be an unmodified scalar, no nested csv  |
+| `p.array(element?)`  | `E[]`            | Repeated keys (`?tags=a&tags=b`). Absent ≡ `[]` — so NO `.optional()`/`.default()`; `.catch()` recovers the whole list.                                                                                                                        | Optional element codec (default `p.string()`); element must be an unmodified scalar, not arity-many |
+| `p.custom({ ... })`  | `Out`            | Your bidirectional transform. Thrown foreign errors are rebranded `ParseError`/`SerializeError`.                                                                                                                                               | `{ parse: (raw: string) => Out; serialize: (value: Out) => string; label?: string }`                |
+
+## Modifier chains
+
+| Modifier                        | Effect on decode                                                     | Effect on href input | Effect on URL                                                                                      |
+| ------------------------------- | -------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------- |
+| (none — required)               | Absent key is a decode issue                                         | Key required         | Always emitted when building                                                                       |
+| `.optional()`                   | Absent → `undefined`; field type `T \| undefined`                    | Key omittable        | Omitted key emits nothing                                                                          |
+| `.default(value)`               | Absent → default; field type stays `T`                               | Key omittable        | Value equal to the default ELIDES (compared by serialized wire form) — one canonical URL per state |
+| `.default(() => value)`         | Absent → factory result; field type stays `T`                        | Key omittable        | NEVER elides (a time-varying factory would swallow explicit values)                                |
+| `.catch(v)` / `.catch(() => v)` | A PRESENT value that fails parsing → fallback. Never covers absence. | No change            | No change                                                                                          |
+
+Legality (compile-time type-state — illegal calls type as `never`; runtime throws for JS):
+
+- Legal: `p.integer()`, `.optional()`, `.default(1)`, `.catch(0)`, `.optional().catch(0)`, `.catch(0).optional()`, `.default(1).catch(0)`, `.catch(0).default(1)`, `p.csv().default([])`, `p.array().catch([])`.
+- Illegal: `.optional().default(...)`, `.default(...).optional()`, `.optional().optional()`, `.default(...).default(...)`, `.catch(...).catch(...)`, `p.array().optional()`, `p.array().default(...)`, any modifier on a csv/array ELEMENT (`p.csv(p.string().optional())`), `p.csv(p.csv())`, `p.array(p.array())`, and `.default(value)` where the value's type includes a function member (use the factory form).
+- `params:` codecs additionally forbid `.optional()`/`.default()` (path optionality comes from `[[...slug]]`); `.catch()` is fine.
+
+Value vs factory `.default()`: value defaults are serialized eagerly at definition time (an invalid default fails immediately) and participate in URL elision; factory defaults are invoked per decode (fresh reference per call — use for mutable objects) and never elide. Array value defaults are handed out as fresh shallow copies per decode.
+
+## Defining routes
+
+```ts
+import { defineAppRoute, definePagesRoute, p } from "paramour";
+
+export const productRoute = defineAppRoute("/product/[id]", {
+  params: { id: p.integer() },
+  search: { page: p.index().default(0), tags: p.csv() },
+});
+
+export const docsRoute = defineAppRoute("/docs/[[...slug]]", {
+  params: { slug: p.string() }, // codec describes ONE segment element
+});
+
+export const aboutRoute = defineAppRoute("/about", {}); // static: params rejected
+
+export const blogRoute = definePagesRoute("/blog/[slug]", {
+  params: { slug: p.string() },
+  search: { preview: p.boolean().optional() },
+});
+```
+
+Rules:
+
+- Path literal is checked against the generated registry (`paramour-env.d.ts`); pre-generation any literal compiles. Exactly one codec per dynamic segment name; extra or misspelled `params:` keys fail to compile.
+- `[...slug]` / `[[...slug]]` decode to `Out[]` (absent optional catch-all → `[]`); the codec is per-element, `.catch()` recovery is element-wise.
+- Pages routes forbid a search key shadowing a path param name (Next merges `query`, path params win).
+- Whole-object escape hatch: `search: rawSearch(zodSchema)` hands the entire search object to one Standard Schema — schema sees every key on decode; encode is a raw pass-through of wire strings (no round-trip, no elision). Prefer codec maps.
+
+## Server-side reads
+
+App Router (async, props-based): `route.parse(props)`, `route.parseParams(props)`, `route.parseSearch(props)` — throw `ParamsDecodeError`/`SearchDecodeError` on malformed URLs (params decode first) — plus `safeParse`/`safeParseParams`/`safeParseSearch` returning `SafeResult` (`status: "success" | "error"`). Annotate page props as `RouteProps` (or `ParamsProps`/`SearchProps` for layouts/halves) from `paramour`; `generateMetadata` takes the same props.
+
+Pages Router (sync, context-based): `route.parseContext(ctx)` / `route.safeParseContext(ctx)` with a `getServerSideProps` or `getInitialProps` context (`{ params?, query }`). NOT `getStaticProps` (no query string) — decode `ctx.params` with `safeDecodeParams(route, ctx.params ?? {})` there.
+
+Standalone sync decoders (middleware, route handlers, anywhere holding a source): `decodeParams`/`decodeSearch` (throwing) and `safeDecodeParams`/`safeDecodeSearch` (SafeResult), all from `paramour`.
+
+## Typed links
+
+```ts
+import { href } from "paramour";
+
+href(productRoute, { params: { id: 42 }, search: { tags: ["a", "b"] } });
+// "/product/42?tags=a,b"
+href(aboutRoute); // "/about" — options omittable when nothing is required
+href(productRoute, { params: { id: 1 }, hash: "reviews" }); // "#reviews" appended verbatim
+href("/about", { hash: "team" }); // string form: registered STATIC paths only
+```
+
+`href` returns `Href` — a string subtype accepted by `next/link`, `router.push`, `redirect` unchanged. Required params/search make the options argument required; defaulted/optional/array keys are omittable. Serialization failures (bad value, empty segment, required catch-all given `[]`) throw `SerializeError` at link-build time. Lower-level pieces: `buildPath(route, params)`, `searchToString(config, input)`, `encodeStaticParams(route, params)` for `generateStaticParams`/`getStaticPaths`.
+
+## Client hooks
+
+App Router — `import { useRouteParams, useRouteParamsOrThrow, useSearch, useSearchOrThrow } from "@paramour-js/next/app"` (client components only; app-branded routes only, compile-enforced):
+
+- `useRouteParams(route)` / `useSearch(route)` → `SafeResult`: branch on `result.status === "error"` before touching `result.data`. No loading state; SSR-consistent.
+- `useRouteParamsOrThrow(route)` / `useSearchOrThrow(route)` → decoded value, throwing the decode error to the nearest error boundary.
+- All four accept optional `{ select: (value) => U, equality?: "shallow" }` — a projection with result-equality stabilization so unrelated URL churn (e.g. `utm_*`) does not produce new references.
+
+Pages Router — `import { useRouteParams, useSearch } from "@paramour-js/next/pages"` (pages-branded routes only):
+
+- Return `RouterResult` = `SafeResult` plus a `{ status: "pending" }` arm for the pre-`isReady` first render of a statically optimized page. Handle all three statuses. No `OrThrow` variants exist, by design. Same `{ select }` option.
+
+Testing — `import { ParamourTestingProvider, withParamourTesting } from "@paramour-js/next/testing"`: overrides the hooks' framework reads without mocking `next/*` modules. `withParamourTesting({ pathname: "/product/42", params: { id: "42" }, search: "?q=hi" })` is testing-library's `wrapper`; options also cover `isReady`, `mounted`, `onReplace`, `params: null`.
+
+## Errors
+
+All library throws are `ParamourError` subclasses (brand-hardened `instanceof`): `ParseError` (one wire value failed its grammar/schema; `.catch()`-recoverable), `SerializeError` (link-build time), `ParamsDecodeError`/`SearchDecodeError` (aggregate, `.issues: Issue[]` with `key`/`message`/`reason`/`expected`/`wire`), `SearchSourceError` (malformed source under a declared key). `safeParse*`/`safeDecode*`/hooks convert only the decode errors into the error arm — contract violations stay thrown.

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-panel`; 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`.