# Docs

- [What is Paramour?](/docs): A type-safe routing companion for the Next.js App Router.
- Getting Started
  - [Getting Started](/docs/getting-started): Install paramour in a fresh Next.js app and build your first fully typed route, end to end.
- Concepts
  - [Codecs & the Type-State API](/docs/concepts/codecs): Bidirectional wire converters with compile-time modifier rules.
  - [Route Objects as Currency](/docs/concepts/route-objects): Imported objects, not string registries — tree-shaking stays perfect.
  - [Serialization & the Wire Format](/docs/concepts/serialization): Explicit, predictable URL serialization owned by the library.
  - [Standard Schema & BYO Validator](/docs/concepts/standard-schema): Bring Zod, Valibot, ArkType — any Standard Schema validator.
  - [The Generated Route Registry](/docs/concepts/registry): paramour generate turns your filesystem routes into a compile-time union.
- Guides
  - [Defining Routes](/docs/guides/defining-routes): Static, dynamic, and catch-all routes with defineAppRoute.
  - [Search Params in the App Router](/docs/guides/search-params): Validated, serializable search params with codec modifiers.
  - [Hooks](/docs/guides/hooks): useRouteParams and useSearch for the App and Pages routers.
  - [CLI Workflows](/docs/guides/cli): generate, check, init, list, doctor, and skills.
  - [nuqs Adapter](/docs/guides/nuqs): Derive nuqs parsers from a route's search codecs.
  - [Devtools Panel](/docs/guides/devtools): Observe route parsing live with the TanStack Devtools panel.
  - [Testing](/docs/guides/testing): Unit-test client components that call the hooks — without mocking next/navigation.
  - [AI Agents](/docs/guides/ai-agents): The bundled agent skill, the AGENTS.md snippet, and llms.txt — how coding agents learn paramour.
- Reference
  - paramour (core)
    - [paramour (core)](/docs/reference/core): API reference for the core package — codecs, routes, href, serialization helpers, reflection, and errors.
    - [p.* builders](/docs/reference/core/p-builders): Every built-in codec — wire grammars, accept/reject behavior, and schema slots.
    - [Codec & modifiers](/docs/reference/core/codecs): The Codec interface, createCodec, the three modifiers, and the type-state rules.
    - [defineAppRoute & definePagesRoute](/docs/reference/core/routes): The route constructors, their parse surfaces, and the route and registry types.
    - [href & path building](/docs/reference/core/href): Typed link building with href and the Href brand, plus the standalone path helpers.
    - [Search helpers](/docs/reference/core/search): Standalone search-param decoding and encoding, the rawSearch escape hatch, and Standard Schema interop.
    - [describeCodec & describeRoute](/docs/reference/core/describe): The reflection API — codecs and routes as plain, serializable data.
    - [Errors](/docs/reference/core/errors): The ParamourError hierarchy, brand-based instanceof, and the Issue shape shared by every failed decode.
  - @paramour-js/next
    - [@paramour-js/next](/docs/reference/next): Entry points — withTypedRoutes, the router hooks, the testing provider, the devtools seam, and the paramour CLI.
    - [withTypedRoutes](/docs/reference/next/with-typed-routes): The Next config wrapper — plus WithTypedRoutesOptions, ParamourConfig, and RouteCollisionError.
    - [App Router hooks](/docs/reference/next/app-hooks): useRouteParams, useSearch, their OrThrow variants, and SelectOptions — from @paramour-js/next/app.
    - [Pages Router hooks](/docs/reference/next/pages-hooks): useRouteParams, useSearch, RouterResult, and SelectOptions — from @paramour-js/next/pages.
    - [Testing provider](/docs/reference/next/testing): ParamourTestingProvider, withParamourTesting, and ParamourTestingOptions — from @paramour-js/next/testing.
    - CLI
      - [paramour CLI](/docs/reference/next/cli): Invocation, configuration precedence, and the exit-code contract shared by all six commands.
      - [paramour generate](/docs/reference/next/cli/generate): Generate paramour-env.d.ts from the app and pages directories.
      - [paramour check](/docs/reference/next/cli/check): Verify the committed artifact is current — exit 1 on drift, never writes.
      - [paramour init](/docs/reference/next/cli/init): Non-interactive project setup — config scaffold, next.config wrap, package script, first generate, agent skills, AGENTS.md snippet.
      - [paramour list](/docs/reference/next/cli/list): Print every filesystem route with its params/search shape.
      - [paramour doctor](/docs/reference/next/cli/doctor): Diagnose the project's paramour setup — one pass, one report.
      - [paramour skills](/docs/reference/next/cli/skills): Install or verify the bundled agent skill for detected agent tools.
  - [@paramour-js/nuqs](/docs/reference/nuqs): The nuqs adapter API.
  - [@paramour-js/devtools](/docs/reference/devtools): Devtools panel API and the observation-seam contract.
  - [@paramour-js/eslint-plugin](/docs/reference/eslint-plugin): The ESLint plugin — find every raw string href paramour never sees.
  - [Wire-Format Spec](/docs/reference/wire-format): The normative, numbered rules for paramour's URL serialization.
- Migrate
  - [Migrating from next-typesafe-url](/docs/migrate): What changes, what stays, and how the migration runs.
  - [Concept Map](/docs/migrate/concept-map): Every next-typesafe-url concept and its paramour equivalent.
  - [Step-by-Step Guide](/docs/migrate/guide): Migrate route by route with both libraries installed.
  - [Differences](/docs/migrate/differences): What behaves differently, what paramour lacks, what it adds.