@paramour-js/next 0.4.1 → 0.7.0

package/dist/skills/manifest.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve, sep } from "node:path";
+export const MANIFEST_FILENAME = ".paramour-skills.json";
+/**
+ * CRLF-normalized sha256. Normalizing before hashing makes every status
+ * computation immune to a consumer repo's git `autocrlf` rewriting the
+ * installed markdown on checkout — a line-ending flip is not a content edit.
+ */
+export function hashContent(text) {
+    const digest = createHash("sha256")
+        .update(text.replaceAll("\r\n", "\n"))
+        .digest("hex");
+    return `sha256:${digest}`;
+}
+/**
+ * Read a target's manifest; `undefined` when absent or malformed. A corrupt
+ * manifest degrades to "no provenance": byte-identical files still audit as
+ * fresh and anything else audits as locally modified, which the installer
+ * refuses to overwrite without `--force` — the safe direction. A manifest
+ * containing any file key that could escape the skill directory is treated
+ * as corrupt the same way, since those keys become deletion paths in sync.
+ */
+export function readSkillManifest(skillDir) {
+    const path = join(skillDir, MANIFEST_FILENAME);
+    if (!existsSync(path))
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return undefined;
+    }
+    // Fields typed unknown, not Partial<SkillManifest> — the JSON is
+    // arbitrary bytes, and asserting the target shape up front would make
+    // these guards type-narrow the wrong way.
+    const candidate = parsed;
+    if (candidate.skill !== "paramour")
+        return undefined;
+    if (typeof candidate.version !== "string")
+        return undefined;
+    const files = candidate.files;
+    if (typeof files !== "object" || files === null || Array.isArray(files)) {
+        return undefined;
+    }
+    for (const [key, value] of Object.entries(files)) {
+        if (!isSafeManifestKey(key, skillDir))
+            return undefined;
+        if (typeof value !== "string")
+            return undefined;
+    }
+    return {
+        files: files,
+        skill: "paramour",
+        version: candidate.version,
+    };
+}
+/**
+ * Deterministic serialization: sorted file keys, two-space indent, LF,
+ * trailing newline, no timestamps — same doctrine as the generated artifact,
+ * so a re-run that changes nothing writes nothing.
+ */
+export function renderManifest(manifest) {
+    // Byte-order comparison, not localeCompare — locale collation varies by
+    // machine, and this file must be byte-identical wherever it is written.
+    const files = Object.fromEntries(Object.entries(manifest.files).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0));
+    const ordered = {
+        files,
+        skill: manifest.skill,
+        version: manifest.version,
+    };
+    return `${JSON.stringify(ordered, null, 2)}\n`;
+}
+/**
+ * Manifest keys are joined onto the skill directory and fed to the
+ * filesystem during sync — orphan removal in particular deletes the path a
+ * key names — so a tampered key like `"../../../src/index.ts"` would reach
+ * files far outside the install. Only a plain relative POSIX path that
+ * resolves strictly inside the skill directory is acceptable: no empty
+ * keys, no backslashes, no absolute paths (POSIX, Windows drive, or UNC),
+ * and the resolved path must sit under `resolve(skillDir)` followed by a
+ * separator so a sibling directory sharing the prefix does not slip
+ * through.
+ */
+function isSafeManifestKey(key, skillDir) {
+    if (key === "" || key.includes("\\"))
+        return false;
+    if (isAbsolute(key) || key.startsWith("/") || /^[A-Za-z]:/.test(key)) {
+        return false;
+    }
+    return resolve(skillDir, key).startsWith(resolve(skillDir) + sep);
+}

package/dist/skills/packaged.d.ts

@@ -0,0 +1,21 @@
+/** One file of the bundled skill, hashed and ready to install. */
+export interface PackagedFile {
+    content: string;
+    hash: string;
+    /** POSIX-relative to the skill root, e.g. `references/setup.md`. */
+    relPath: string;
+}
+/** The bundled skill as shipped in this package's `skills/` directory. */
+export interface PackagedSkill {
+    files: readonly PackagedFile[];
+    /** This package's own version — the value stamped into manifests. */
+    version: string;
+}
+/**
+ * Load the bundled skill content. Hashes are computed here, at read time,
+ * never committed — the changesets release flow bumps versions without a
+ * build step, so any committed hash would go stale on the first release.
+ * Throws when the bundled content is unreadable (an operational error: the
+ * package itself is broken).
+ */
+export declare function loadPackagedSkill(): PackagedSkill;

package/dist/skills/packaged.js

@@ -0,0 +1,32 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { hashContent } from "./manifest.js";
+// Two levels up is the package root from both `src/skills/` (vitest runs
+// the sources) and `dist/skills/` (the built CLI): tsc mirrors src/ into
+// dist/ at the same depth, so one relative URL serves both worlds.
+const PACKAGE_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+/**
+ * Load the bundled skill content. Hashes are computed here, at read time,
+ * never committed — the changesets release flow bumps versions without a
+ * build step, so any committed hash would go stale on the first release.
+ * Throws when the bundled content is unreadable (an operational error: the
+ * package itself is broken).
+ */
+export function loadPackagedSkill() {
+    const root = join(PACKAGE_ROOT, "skills", "paramour");
+    const files = readdirSync(root, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => {
+        const content = readFileSync(join(entry.parentPath, entry.name), "utf8");
+        return {
+            content,
+            hash: hashContent(content),
+            relPath: relative(root, join(entry.parentPath, entry.name)).replaceAll("\\", "/"),
+        };
+    })
+        // Byte-order, not localeCompare — locale collation varies by machine.
+        .sort((a, b) => a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0);
+    const manifest = JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8"));
+    return { files, version: manifest.version };
+}

package/dist/skills/sync.d.ts

@@ -0,0 +1,84 @@
+import { type SkillManifest } from "./manifest.js";
+import { type PackagedSkill } from "./packaged.js";
+import { type SkillTarget } from "./targets.js";
+/** One packaged file's audit against a target. */
+export interface FileAudit {
+    relPath: string;
+    status: FileStatus;
+}
+/**
+ * Per-file audit verdict, from three hashes: P (packaged), M (what the
+ * manifest recorded at last sync, possibly absent), I (installed on disk).
+ * - `fresh` — I equals P; nothing to do (identical unmanaged files are
+ *   adopted rather than flagged).
+ * - `missing` — no file on disk.
+ * - `stale` — I equals M but M differs from P: untouched locally, the
+ *   package moved on. Safe to overwrite.
+ * - `modified` — local edits relative to the current package (M equals P but
+ *   I differs, or no provenance at all). Never overwritten without --force.
+ * - `stale-modified` — all three differ: local edits on an outdated base.
+ *   Never overwritten without --force, but stale as far as `--check` cares.
+ */
+export type FileStatus = "fresh" | "missing" | "modified" | "stale" | "stale-modified";
+/**
+ * One human-readable detail line per file status, shared verbatim by
+ * `skills --check`, doctor, and init's summary so every surface describes
+ * the same state in the same words. `fresh` needs no line. Exhaustively
+ * typed: a new FileStatus member fails to compile until it gets an entry.
+ */
+export declare const FILE_STATUS_DETAIL: Record<FileStatus, string | undefined>;
+/** A manifest entry whose file is no longer part of the packaged skill. */
+export interface OrphanAudit {
+    /**
+     * True when the installed bytes still match the manifest record (or the
+     * file is already gone) — provably ours and untouched, so sync may remove
+     * it. False means local edits: sync leaves the file and stops tracking it.
+     */
+    managed: boolean;
+    relPath: string;
+}
+/** Everything `--check`, doctor, and the installer need about one target. */
+export interface TargetAudit {
+    files: FileAudit[];
+    manifest: SkillManifest | undefined;
+    orphans: OrphanAudit[];
+    target: SkillTarget;
+}
+/** What `syncTarget` did (or, under `dry`, would do) to one target. */
+export interface TargetSyncResult {
+    audit: TargetAudit;
+    /** Unmanaged orphans left on disk, no longer tracked by the manifest. */
+    keptOrphans: string[];
+    /** Managed orphans removed from disk. */
+    removedOrphans: string[];
+    /** Files with local edits, left as-is because `force` was off. */
+    skippedModified: string[];
+    /** Files written (created or overwritten). */
+    written: string[];
+}
+/** Audit one target without writing anything. */
+export declare function auditTarget(target: SkillTarget, packaged: PackagedSkill): TargetAudit;
+/**
+ * Whether a status means the installed copy no longer reflects the packaged
+ * skill — the single classifier behind `skills --check` failures, doctor's
+ * stale verdict, and init's summary line. `modified` is deliberate local
+ * tailoring, not drift, so it does not count. The lookup is exhaustively
+ * typed: a new FileStatus member fails to compile until it is classified.
+ */
+export declare function isOutdated(status: FileStatus): boolean;
+/**
+ * Install or re-sync one target: write missing/stale files, leave fresh
+ * ones alone, refuse to overwrite local edits unless `force`, then rewrite
+ * the manifest. Skipped modified files keep their previously recorded hash
+ * so a later audit can still tell `stale-modified` from `modified`; orphans
+ * are dropped from the manifest either way (a kept unmanaged orphan becomes
+ * the user's file — reported once here, never nagged about again). One
+ * exception to the manifest rewrite: when the target had no manifest,
+ * nothing was written, and every packaged file was refused as locally
+ * modified, no manifest is written either — that directory is the user's
+ * own work and must not be adopted as paramour-managed.
+ */
+export declare function syncTarget(target: SkillTarget, packaged: PackagedSkill, options: {
+    dry: boolean;
+    force: boolean;
+}): TargetSyncResult;

package/dist/skills/sync.js

@@ -0,0 +1,136 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { writeIfChanged } from "../emit.js";
+import { hashContent, MANIFEST_FILENAME, readSkillManifest, renderManifest, } from "./manifest.js";
+import {} from "./packaged.js";
+import {} from "./targets.js";
+/**
+ * One human-readable detail line per file status, shared verbatim by
+ * `skills --check`, doctor, and init's summary so every surface describes
+ * the same state in the same words. `fresh` needs no line. Exhaustively
+ * typed: a new FileStatus member fails to compile until it gets an entry.
+ */
+export const FILE_STATUS_DETAIL = {
+    fresh: undefined,
+    missing: "missing — run `paramour skills`",
+    modified: "locally modified",
+    stale: "packaged content changed — run `paramour skills`",
+    "stale-modified": "locally modified on an outdated base — `paramour skills --force` overwrites",
+};
+/** Audit one target without writing anything. */
+export function auditTarget(target, packaged) {
+    const manifest = readSkillManifest(target.skillDir);
+    const files = packaged.files.map((file) => {
+        const installedPath = join(target.skillDir, file.relPath);
+        if (!existsSync(installedPath)) {
+            return { relPath: file.relPath, status: "missing" };
+        }
+        const installed = hashContent(readFileSync(installedPath, "utf8"));
+        const recorded = manifest?.files[file.relPath];
+        const status = installed === file.hash
+            ? "fresh"
+            : recorded === undefined || recorded === file.hash
+                ? "modified"
+                : installed === recorded
+                    ? "stale"
+                    : "stale-modified";
+        return { relPath: file.relPath, status };
+    });
+    const packagedPaths = new Set(packaged.files.map((file) => file.relPath));
+    const orphans = Object.entries(manifest?.files ?? {})
+        .filter(([relPath]) => !packagedPaths.has(relPath))
+        .map(([relPath, recorded]) => {
+        const installedPath = join(target.skillDir, relPath);
+        const managed = !existsSync(installedPath) ||
+            hashContent(readFileSync(installedPath, "utf8")) === recorded;
+        return { managed, relPath };
+    });
+    return { files, manifest, orphans, target };
+}
+/**
+ * Whether a status means the installed copy no longer reflects the packaged
+ * skill — the single classifier behind `skills --check` failures, doctor's
+ * stale verdict, and init's summary line. `modified` is deliberate local
+ * tailoring, not drift, so it does not count. The lookup is exhaustively
+ * typed: a new FileStatus member fails to compile until it is classified.
+ */
+export function isOutdated(status) {
+    const outdated = {
+        fresh: false,
+        missing: true,
+        modified: false,
+        stale: true,
+        "stale-modified": true,
+    };
+    return outdated[status];
+}
+/**
+ * Install or re-sync one target: write missing/stale files, leave fresh
+ * ones alone, refuse to overwrite local edits unless `force`, then rewrite
+ * the manifest. Skipped modified files keep their previously recorded hash
+ * so a later audit can still tell `stale-modified` from `modified`; orphans
+ * are dropped from the manifest either way (a kept unmanaged orphan becomes
+ * the user's file — reported once here, never nagged about again). One
+ * exception to the manifest rewrite: when the target had no manifest,
+ * nothing was written, and every packaged file was refused as locally
+ * modified, no manifest is written either — that directory is the user's
+ * own work and must not be adopted as paramour-managed.
+ */
+export function syncTarget(target, packaged, options) {
+    const audit = auditTarget(target, packaged);
+    const statusOf = new Map(audit.files.map((file) => [file.relPath, file.status]));
+    const manifestFiles = {};
+    const skippedModified = [];
+    const written = [];
+    for (const file of packaged.files) {
+        const status = statusOf.get(file.relPath) ?? "missing";
+        if (status === "fresh") {
+            manifestFiles[file.relPath] = file.hash;
+            continue;
+        }
+        if ((status === "modified" || status === "stale-modified") &&
+            !options.force) {
+            skippedModified.push(file.relPath);
+            const recorded = audit.manifest?.files[file.relPath];
+            if (recorded !== undefined)
+                manifestFiles[file.relPath] = recorded;
+            continue;
+        }
+        if (!options.dry) {
+            writeIfChanged(join(target.skillDir, file.relPath), file.content);
+        }
+        manifestFiles[file.relPath] = file.hash;
+        written.push(file.relPath);
+    }
+    const keptOrphans = [];
+    const removedOrphans = [];
+    for (const orphan of audit.orphans) {
+        if (orphan.managed) {
+            if (!options.dry) {
+                rmSync(join(target.skillDir, orphan.relPath), { force: true });
+            }
+            removedOrphans.push(orphan.relPath);
+        }
+        else {
+            keptOrphans.push(orphan.relPath);
+        }
+    }
+    // Writing the manifest is what marks a directory as paramour-managed. A
+    // target with no prior manifest where nothing was written and every
+    // packaged file was refused as locally modified is a hand-authored
+    // directory that happens to share the path — dropping a manifest there
+    // would adopt it and have doctor report local edits forever. Anything
+    // written, any prior provenance, or an all-fresh byte-identical tree (the
+    // designed adoption case) still rewrites the manifest.
+    const wouldAdoptUserDir = audit.manifest === undefined &&
+        skippedModified.length > 0 &&
+        written.length === 0;
+    if (!options.dry && !wouldAdoptUserDir) {
+        writeIfChanged(join(target.skillDir, MANIFEST_FILENAME), renderManifest({
+            files: manifestFiles,
+            skill: "paramour",
+            version: packaged.version,
+        }));
+    }
+    return { audit, keptOrphans, removedOrphans, skippedModified, written };
+}

package/dist/skills/targets.d.ts

@@ -0,0 +1,29 @@
+/** One resolved install destination. */
+export interface SkillTarget {
+    /** POSIX display path, e.g. `.claude/skills/paramour`. */
+    rel: string;
+    /** Absolute path to the skill's install directory. */
+    skillDir: string;
+    tool: ToolId;
+}
+/** The agent tools the installer knows how to target. */
+export type ToolId = "agents" | "claude" | "codex" | "cursor";
+export declare const TOOL_IDS: readonly ToolId[];
+/** `resolveTargets` result when the inputs were valid. */
+export interface ResolvedTargets {
+    /** True when nothing was detected and the portable location was chosen. */
+    fallback: boolean;
+    targets: SkillTarget[];
+}
+/** Targets whose tool is present in the project, alphabetical by tool. */
+export declare function detectTargets(projectRoot: string): SkillTarget[];
+/**
+ * Resolve install destinations: explicit `--tool` values (repeatable and
+ * comma-splittable) override detection entirely; otherwise every detected
+ * tool is targeted; with nothing detected the portable `.agents/skills/`
+ * location is the fallback so a bare `paramour skills` always installs
+ * somewhere tools can find.
+ */
+export declare function resolveTargets(projectRoot: string, toolFlags: readonly string[] | undefined): ResolvedTargets | {
+    error: string;
+};

package/dist/skills/targets.js

@@ -0,0 +1,73 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+// Detection is directory presence only — no config parsing. Per-tool config
+// formats move monthly; the dot-directory at the project root is the one
+// signal that has stayed stable across the ecosystem. `agents` additionally
+// matches an AGENTS.md file, the portable convention's sibling marker.
+const TOOLS = {
+    agents: {
+        detect: (root) => isDirectory(join(root, ".agents")) || existsSync(join(root, "AGENTS.md")),
+        dir: ".agents",
+    },
+    claude: {
+        detect: (root) => isDirectory(join(root, ".claude")),
+        dir: ".claude",
+    },
+    codex: { detect: (root) => isDirectory(join(root, ".codex")), dir: ".codex" },
+    cursor: {
+        detect: (root) => isDirectory(join(root, ".cursor")),
+        dir: ".cursor",
+    },
+};
+export const TOOL_IDS = Object.keys(TOOLS);
+/** Targets whose tool is present in the project, alphabetical by tool. */
+export function detectTargets(projectRoot) {
+    return TOOL_IDS.filter((tool) => TOOLS[tool].detect(projectRoot)).map((tool) => toTarget(projectRoot, tool));
+}
+/**
+ * Resolve install destinations: explicit `--tool` values (repeatable and
+ * comma-splittable) override detection entirely; otherwise every detected
+ * tool is targeted; with nothing detected the portable `.agents/skills/`
+ * location is the fallback so a bare `paramour skills` always installs
+ * somewhere tools can find.
+ */
+export function resolveTargets(projectRoot, toolFlags) {
+    const requested = (toolFlags ?? [])
+        .flatMap((flag) => flag.split(","))
+        .map((id) => id.trim())
+        .filter((id) => id.length > 0);
+    if (requested.length > 0) {
+        for (const id of requested) {
+            if (!TOOL_IDS.includes(id)) {
+                return {
+                    error: `unknown --tool "${id}" (expected one of: ${TOOL_IDS.join(", ")})`,
+                };
+            }
+        }
+        const unique = TOOL_IDS.filter((tool) => requested.includes(tool)); /* dedupes and restores alphabetical order */
+        return {
+            fallback: false,
+            targets: unique.map((tool) => toTarget(projectRoot, tool)),
+        };
+    }
+    const detected = detectTargets(projectRoot);
+    if (detected.length > 0)
+        return { fallback: false, targets: detected };
+    return { fallback: true, targets: [toTarget(projectRoot, "agents")] };
+}
+function isDirectory(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function toTarget(projectRoot, tool) {
+    const { dir } = TOOLS[tool];
+    return {
+        rel: `${dir}/skills/paramour`,
+        skillDir: join(projectRoot, dir, "skills", "paramour"),
+        tool,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paramour-js/next",
-  "version": "0.4.1",
+  "version": "0.7.0",
   "type": "module",
   "exports": {
     ".": {
@@ -34,7 +34,7 @@
     "jiti": "^2.7.0",
     "magicast": "^0.3.5",
     "tinyglobby": "^0.2.15",
-    "paramour": "0.6.0"
+    "paramour": "0.7.0"
   },
   "peerDependencies": {
     "next": ">=15",
@@ -76,7 +76,8 @@
   },
   "files": [
     "bin",
-    "dist"
+    "dist",
+    "skills"
   ],
   "publishConfig": {
     "access": "public",

package/skills/paramour/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: paramour
+description: Type-safe routing for Next.js using the paramour and @paramour-js/next packages. Covers defining routes as route objects (defineAppRoute, definePagesRoute), typing params and searchParams with p.* codecs and the .optional()/.default()/.catch() modifiers, building typed links with href(), reading route state with typed hooks (useSearch, useRouteParams) and server parse surfaces (route.parse), wrapping next.config with withTypedRoutes, and using the paramour CLI (generate, check, init, list, doctor, skills). Load when working in a Next.js project that depends on paramour, when setting paramour up, or when migrating raw params/searchParams usage in an App Router or Pages Router project to validated, typed route objects.
+---
+
+# paramour
+
+Paramour is a type-safe routing companion for Next.js: each route is defined once as an importable route object whose params and search params are described by bidirectional wire codecs (parse AND serialize — Standard Schema validators plug in for validation, serialization is library-owned). Two packages: `paramour` (validation-agnostic core: `p.*` codec builders, `defineAppRoute`/`definePagesRoute`, `href`, decode/encode helpers) and `@paramour-js/next` (Next integration: `withTypedRoutes` config wrapper, App/Pages Router hooks, the `paramour` CLI).
+
+## Core rules (always apply)
+
+1. Import only from package barrels: `paramour`, `@paramour-js/next`, `@paramour-js/next/app`, `@paramour-js/next/pages`, `@paramour-js/next/testing`. Never import `dist/` or deep source paths.
+2. Codec modifier legality is type-state: illegal chains do not compile (the method's type becomes `never`) and throw at runtime for JS callers. The rules:
+   - `.optional()` and `.default()` apply only to a bare, unmodified single-value codec — at most ONE of the two, at most once. `.optional().default()`, `.default().optional()`, and any repeat are illegal.
+   - `.catch()` applies at most once and combines with either presence modifier in either order. It recovers parse failures of PRESENT wire values only — never absence.
+   - `p.array(...)` codecs take no `.optional()`/`.default()` (an absent key and `[]` are the same wire state). `.catch()` is allowed.
+   - Codecs in a `params:` config take no presence modifiers at all (`.optional()`/`.default()` are illegal there); `.catch()` is allowed.
+   - `p.csv(element)`/`p.array(element)` elements must be bare unmodified scalars: no modifiers, no csv inside csv, no array-arity element.
+   - `.default(value)` rejects values whose type includes a function; a function argument is always a factory (`.default(() => value)`).
+3. `paramour-env.d.ts` is a generated artifact. NEVER hand-edit it. Regenerate with `paramour generate` (dev server and builds wrapped by `withTypedRoutes` also regenerate it) and commit the result.
+4. After adding, renaming, moving, or deleting any route file or `defineAppRoute`/`definePagesRoute` call, run `paramour check`. Exit 1 means drift — run `paramour generate`, then commit the artifact with the route change.
+5. When converting an existing project, migrate ONE route per pass — define, wire, verify, commit — never a big-bang rewrite. See `references/migration.md`.
+6. Route objects are the currency: export them from a module and import them where needed. Never build a central string-keyed route registry.
+
+## Verification loop
+
+- `paramour list` — print every filesystem route with its params/search shape as the library sees it (`--json` for machine output). Warnings (route without a definition, definition without a route) exit 0.
+- `paramour generate` — (re)write `paramour-env.d.ts` from `app/` / `pages/`.
+- `paramour check` — verify the artifact is current. Exit 1 on drift or a missing artifact; never writes.
+- `paramour doctor` — diagnose setup (config validity, artifact freshness, next.config wrapping, version alignment, installed agent skills, tsconfig coverage). Exit 1 on any failing check; warnings exit 0.
+
+Also run the project's type check (`tsc --noEmit` or the build) after route changes — paramour's guarantees are compiler-enforced, so a wrong codec chain or a misspelled param surfaces there.
+
+## Task router
+
+Read exactly the reference file matching the task; each is self-contained.
+
+| Task                                                                                  | Read                      |
+| ------------------------------------------------------------------------------------- | ------------------------- |
+| Install paramour into a project that does not have it yet (init, config, first route) | `references/setup.md`     |
+| Convert existing raw `params`/`searchParams` code to paramour routes                  | `references/migration.md` |
+| Day-to-day work: write codecs, define routes, build links, use hooks                  | `references/authoring.md` |
+| Look up an export, hook, CLI flag, config option, or wire-format rule                 | `references/reference.md` |