@paramour-js/next 0.4.0 → 0.5.0

package/dist/commands/init.d.ts

@@ -1,4 +1,44 @@
 import { type CliIo } from "../cli-io.js";
+/** @internal `paramour init` flags — skill-drift test's source of truth. */
+export declare const INIT_OPTIONS: {
+    readonly "dry-run": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly force: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly help: {
+        readonly default: false;
+        readonly short: "h";
+        readonly type: "boolean";
+    };
+    readonly "no-agents-md": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "no-config": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "no-generate": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "no-script": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "no-skills": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "no-wrap": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+};
 /**
  * @internal `paramour init` — non-interactive by design: it runs straight
  * through with defaults and prints one status line per step. Exit codes: 0

package/dist/commands/init.js

@@ -5,25 +5,46 @@ import { NoRouteDirsError, resolveInputs } from "../cli-inputs.js";
 import { message, resolveIo } from "../cli-io.js";
 import { CONFIG_FILE_NAMES, loadConfigFile } from "../config.js";
 import { generate } from "../generate.js";
+import { findAgentsFile, upsertAgentsSection } from "../init/agents-md.js";
 import { addPackageScript, checkSetup, paramourConfigTemplate, } from "../init/scaffold.js";
 import { findNextConfig, manualSnippet, wrapNextConfigSource, } from "../init/wrap-next-config.js";
 import { scanRoutes } from "../scan.js";
+import { loadPackagedSkill } from "../skills/packaged.js";
+import { syncTarget } from "../skills/sync.js";
+import { detectTargets } from "../skills/targets.js";
+import { reportOrphans } from "./skills.js";
 const USAGE = [
     "Usage: paramour init [options]",
     "",
     "Set up paramour in this project: scaffold paramour.config.ts, wrap",
-    'next.config with withTypedRoutes, add a "paramour" script, and run the',
-    "first generate. Every step is idempotent and individually skippable.",
+    'next.config with withTypedRoutes, add a "paramour" script, run the',
+    "first generate, install agent skills for detected agent tools, and add",
+    "a paramour section to an existing AGENTS.md/CLAUDE.md. Every step is",
+    "idempotent and individually skippable.",
     "",
     "Options:",
-    "  --dry-run      report every step without writing anything",
-    "  --force        overwrite an existing paramour.config with the scaffold",
-    "  --help, -h     show this help",
-    "  --no-config    skip scaffolding paramour.config.ts",
-    "  --no-generate  skip the first generate",
-    "  --no-script    skip adding the package.json script",
-    "  --no-wrap      skip wrapping next.config",
+    "  --dry-run        report every step without writing anything",
+    "  --force          overwrite an existing paramour.config with the scaffold",
+    "  --help, -h       show this help",
+    "  --no-agents-md   skip the AGENTS.md/CLAUDE.md paramour section",
+    "  --no-config      skip scaffolding paramour.config.ts",
+    "  --no-generate    skip the first generate",
+    "  --no-script      skip adding the package.json script",
+    "  --no-skills      skip installing agent skills",
+    "  --no-wrap        skip wrapping next.config",
 ].join("\n");
+/** @internal `paramour init` flags — skill-drift test's source of truth. */
+export const INIT_OPTIONS = {
+    "dry-run": { default: false, type: "boolean" },
+    force: { default: false, type: "boolean" },
+    help: { default: false, short: "h", type: "boolean" },
+    "no-agents-md": { default: false, type: "boolean" },
+    "no-config": { default: false, type: "boolean" },
+    "no-generate": { default: false, type: "boolean" },
+    "no-script": { default: false, type: "boolean" },
+    "no-skills": { default: false, type: "boolean" },
+    "no-wrap": { default: false, type: "boolean" },
+};
 /**
  * @internal `paramour init` — non-interactive by design: it runs straight
  * through with defaults and prints one status line per step. Exit codes: 0
@@ -33,15 +54,10 @@ const USAGE = [
  */
 export async function runInit(argv, io) {
     const { stderr, stdout } = resolveIo(io);
-    const parsed = parseCommandFlags(argv, {
-        "dry-run": { default: false, type: "boolean" },
-        force: { default: false, type: "boolean" },
-        help: { default: false, short: "h", type: "boolean" },
-        "no-config": { default: false, type: "boolean" },
-        "no-generate": { default: false, type: "boolean" },
-        "no-script": { default: false, type: "boolean" },
-        "no-wrap": { default: false, type: "boolean" },
-    }, USAGE, { stderr, stdout });
+    const parsed = parseCommandFlags(argv, INIT_OPTIONS, USAGE, {
+        stderr,
+        stdout,
+    });
     if ("exit" in parsed)
         return parsed.exit;
     const flags = parsed.values;
@@ -67,7 +83,7 @@ export async function runInit(argv, io) {
         }
         else {
             // A .mjs/.json left behind would be shadowed by the scaffold under the
-            // ts-first discovery order (§7.2) — --force must truly replace it.
+            // ts-first discovery order — --force must truly replace it.
             if (existing !== undefined && existing !== "paramour.config.ts" && !dry) {
                 unlinkSync(join(projectRoot, existing));
             }
@@ -184,6 +200,82 @@ export async function runInit(argv, io) {
             }
         }
     }
+    // 5. Agent skills for detected agent tools. Detection-driven and
+    // non-interactive; init never invents an install location — with no
+    // tooling present, the explicit `paramour skills` command carries the
+    // intent its portable-location fallback needs.
+    if (!flags["no-skills"]) {
+        const detected = detectTargets(projectRoot);
+        if (detected.length === 0) {
+            stdout("  • no agent tooling detected — skipped agent skills (`paramour skills` installs to the portable .agents/skills/)");
+        }
+        else {
+            try {
+                const packaged = loadPackagedSkill();
+                for (const target of detected) {
+                    const result = syncTarget(target, packaged, { dry, force: false });
+                    if (result.written.length > 0) {
+                        stdout(`  ✔ ${dry ? "would install" : "installed"} agent skills → ${target.rel}`);
+                    }
+                    else if (result.skippedModified.length === 0) {
+                        stdout(`  • agent skills already up to date in ${target.rel}`);
+                    }
+                    if (result.skippedModified.length > 0) {
+                        stdout(`  ⚠ ${target.rel}: locally-modified skill files left as-is (\`paramour skills --force\` overwrites)`);
+                    }
+                    // A sync can also delete files (managed orphans from a previous
+                    // install); those must never happen silently, so reuse the exact
+                    // per-orphan wording `paramour skills` prints.
+                    reportOrphans(result, dry, stdout);
+                }
+            }
+            catch (error) {
+                // Same stance as the wrap step: a failed nicety degrades to a
+                // printed pointer, never a failed init.
+                stdout(`  ⚠ could not install agent skills (${message(error)}) — run \`paramour skills\``);
+            }
+        }
+    }
+    // 6. Marker-managed paramour section in AGENTS.md/CLAUDE.md, pointing
+    // agents at the skill step 5 installed. Append-only: init never creates
+    // the file — a root AGENTS.md is a detectTargets signal, so inventing one
+    // would change what the skills step sees on the next run. --force is
+    // deliberately not consulted: the markers delimit paramour-owned content,
+    // so refreshing it is unconditionally safe.
+    if (!flags["no-agents-md"]) {
+        const agentsFile = findAgentsFile(projectRoot);
+        if (agentsFile === undefined) {
+            stdout("  • no AGENTS.md or CLAUDE.md — skipped agents snippet");
+        }
+        else {
+            const name = basename(agentsFile);
+            let source;
+            try {
+                source = readFileSync(agentsFile, "utf8");
+            }
+            catch (error) {
+                // The skills-step stance: a failed nicety never fails init.
+                stdout(`  ⚠ could not read ${name} (${message(error)}) — skipped agents snippet`);
+            }
+            if (source !== undefined) {
+                const result = upsertAgentsSection(source);
+                if (result.status === "added") {
+                    write(agentsFile, result.text);
+                    stdout(`  ✔ ${dry ? "would append" : "appended"} paramour section to ${name}`);
+                }
+                else if (result.status === "updated") {
+                    write(agentsFile, result.text);
+                    stdout(`  ✔ ${dry ? "would update" : "updated"} paramour section in ${name}`);
+                }
+                else if (result.status === "unchanged") {
+                    stdout(`  • ${name} paramour section already up to date — skipped`);
+                }
+                else {
+                    stdout(`  ⚠ ${name} has an unterminated paramour marker — left as-is (remove or close the markers, then re-run)`);
+                }
+            }
+        }
+    }
     return finishWithSummary(projectRoot, artifactPath, stdout);
 }
 function countRoutes(routes) {

package/dist/commands/list.d.ts

@@ -1,4 +1,25 @@
 import { type CliIo } from "../cli-io.js";
+/** @internal `paramour list` flags — skill-drift test's source of truth. */
+export declare const LIST_OPTIONS: {
+    readonly "app-dir": {
+        readonly type: "string";
+    };
+    readonly help: {
+        readonly default: false;
+        readonly short: "h";
+        readonly type: "boolean";
+    };
+    readonly json: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "page-extensions": {
+        readonly type: "string";
+    };
+    readonly "pages-dir": {
+        readonly type: "string";
+    };
+};
 /**
  * @internal `paramour list`: the filesystem scan is authoritative for WHICH
  * routes exist (same engine as generate); discovered definitions overlay

package/dist/commands/list.js

@@ -23,6 +23,14 @@ const USAGE = [
     "  --page-extensions <list>  comma-separated, no leading dots (default: tsx,ts,jsx,js)",
     "  --pages-dir <dir>         pages directory (default: discovered pages/ or src/pages/)",
 ].join("\n");
+/** @internal `paramour list` flags — skill-drift test's source of truth. */
+export const LIST_OPTIONS = {
+    "app-dir": { type: "string" },
+    help: { default: false, short: "h", type: "boolean" },
+    json: { default: false, type: "boolean" },
+    "page-extensions": { type: "string" },
+    "pages-dir": { type: "string" },
+};
 /**
  * @internal `paramour list`: the filesystem scan is authoritative for WHICH
  * routes exist (same engine as generate); discovered definitions overlay
@@ -32,13 +40,10 @@ const USAGE = [
  */
 export async function runList(argv, io) {
     const { stderr, stdout } = resolveIo(io);
-    const parsed = parseCommandFlags(argv, {
-        "app-dir": { type: "string" },
-        help: { default: false, short: "h", type: "boolean" },
-        json: { default: false, type: "boolean" },
-        "page-extensions": { type: "string" },
-        "pages-dir": { type: "string" },
-    }, USAGE, { stderr, stdout });
+    const parsed = parseCommandFlags(argv, LIST_OPTIONS, USAGE, {
+        stderr,
+        stdout,
+    });
     if ("exit" in parsed)
         return parsed.exit;
     const flags = parsed.values;

package/dist/commands/skills.d.ts

@@ -0,0 +1,45 @@
+import { type CliIo } from "../cli-io.js";
+import { type TargetSyncResult } from "../skills/sync.js";
+/** @internal `paramour skills` flags — skill-drift test's source of truth. */
+export declare const SKILLS_OPTIONS: {
+    readonly check: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly "dry-run": {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly force: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly help: {
+        readonly default: false;
+        readonly short: "h";
+        readonly type: "boolean";
+    };
+    readonly json: {
+        readonly default: false;
+        readonly type: "boolean";
+    };
+    readonly tool: {
+        readonly multiple: true;
+        readonly type: "string";
+    };
+};
+/**
+ * @internal Per-orphan reporting for a sync: removals (deletions are the one
+ * thing a sync does that must never happen silently) and kept locally-modified
+ * orphans. Shared by `paramour skills` and `paramour init` so the two commands
+ * describe the same operation in the same words.
+ */
+export declare function reportOrphans(result: TargetSyncResult, dry: boolean, stdout: (line: string) => void): void;
+/**
+ * @internal `paramour skills` — the installer for the bundled agent skill.
+ * `--check` follows `check`'s exit class: 1 means "the installed copies do
+ * not reflect the installed package". A plain run treats refusing to clobber
+ * local edits as success (init's manual-fallback precedent): the refusal is
+ * printed, the fix (`--force`) is named, and nothing is broken.
+ */
+export declare function runSkills(argv: readonly string[], io: CliIo): number;

package/dist/commands/skills.js

@@ -0,0 +1,222 @@
+import { parseCommandFlags } from "../cli-args.js";
+import { message, resolveIo } from "../cli-io.js";
+import { loadPackagedSkill } from "../skills/packaged.js";
+import { auditTarget, FILE_STATUS_DETAIL, isOutdated, syncTarget, } from "../skills/sync.js";
+import { resolveTargets } from "../skills/targets.js";
+const USAGE = [
+    "Usage: paramour skills [options]",
+    "",
+    "Install the bundled Paramour agent skill into each detected agent tool's",
+    "skills directory (.agents/, .claude/, .codex/, .cursor/), stamping every",
+    "install with a .paramour-skills.json manifest so re-syncs are safe:",
+    "locally-modified files are never overwritten without --force. With no",
+    "tools detected, installs to the portable .agents/skills/.",
+    "",
+    "Exit codes: 0 success (including skipped local edits), 1 under --check",
+    "when any installed copy is missing or stale, 2 usage/operational errors.",
+    "",
+    "Options:",
+    "  --check      verify installed skills instead of writing; exit 1 when",
+    "               any copy is missing or stale; passes with nothing to",
+    "               check when no agent tooling is detected",
+    "  --dry-run    report what would be written without writing",
+    "  --force      overwrite locally-modified skill files",
+    "  --help, -h   show this help",
+    "  --json       machine-readable output",
+    "  --tool <t>   target tool(s): agents, claude, codex, cursor",
+    "               (repeatable or comma-separated; overrides detection)",
+].join("\n");
+/** @internal `paramour skills` flags — skill-drift test's source of truth. */
+export const SKILLS_OPTIONS = {
+    check: { default: false, type: "boolean" },
+    "dry-run": { default: false, type: "boolean" },
+    force: { default: false, type: "boolean" },
+    help: { default: false, short: "h", type: "boolean" },
+    json: { default: false, type: "boolean" },
+    tool: { multiple: true, type: "string" },
+};
+/**
+ * @internal Per-orphan reporting for a sync: removals (deletions are the one
+ * thing a sync does that must never happen silently) and kept locally-modified
+ * orphans. Shared by `paramour skills` and `paramour init` so the two commands
+ * describe the same operation in the same words.
+ */
+export function reportOrphans(result, dry, stdout) {
+    for (const orphan of result.removedOrphans) {
+        stdout(`      ${dry ? "would remove" : "removed"} ${orphan} — no longer part of the skill`);
+    }
+    for (const orphan of result.keptOrphans) {
+        stdout(`      left ${orphan} — locally modified and no longer part of the skill`);
+    }
+}
+/**
+ * @internal `paramour skills` — the installer for the bundled agent skill.
+ * `--check` follows `check`'s exit class: 1 means "the installed copies do
+ * not reflect the installed package". A plain run treats refusing to clobber
+ * local edits as success (init's manual-fallback precedent): the refusal is
+ * printed, the fix (`--force`) is named, and nothing is broken.
+ */
+export function runSkills(argv, io) {
+    const { stderr, stdout } = resolveIo(io);
+    const parsed = parseCommandFlags(argv, SKILLS_OPTIONS, USAGE, {
+        stderr,
+        stdout,
+    });
+    if ("exit" in parsed)
+        return parsed.exit;
+    const flags = parsed.values;
+    // --check never writes, so a write-shaping flag alongside it is a
+    // contradiction, not a no-op — reject loudly.
+    for (const conflicting of ["dry-run", "force"]) {
+        if (flags.check && flags[conflicting]) {
+            stderr(`paramour: --check cannot be combined with --${conflicting}`);
+            stderr(USAGE);
+            return 2;
+        }
+    }
+    const projectRoot = process.cwd();
+    const resolved = resolveTargets(projectRoot, flags.tool);
+    if ("error" in resolved) {
+        stderr(`paramour: ${resolved.error}`);
+        stderr(USAGE);
+        return 2;
+    }
+    let packaged;
+    try {
+        packaged = loadPackagedSkill();
+    }
+    catch (error) {
+        stderr(`paramour: bundled skill content unreadable: ${message(error)}`);
+        return 2;
+    }
+    try {
+        return flags.check
+            ? runCheck(resolved.targets, packaged, { fallback: resolved.fallback, json: flags.json }, stdout)
+            : runInstall(resolved.targets, packaged, {
+                dry: flags["dry-run"],
+                fallback: resolved.fallback,
+                force: flags.force,
+                json: flags.json,
+            }, stdout);
+    }
+    catch (error) {
+        stderr(`paramour: ${message(error)}`);
+        return 2;
+    }
+}
+/** Target-level `--check` verdict, doctor's status vocabulary. */
+function checkStatus(audit) {
+    const statuses = audit.files.map((file) => file.status);
+    if (statuses.some(isOutdated))
+        return "fail";
+    return statuses.some((status) => status === "modified") ? "warn" : "pass";
+}
+function reportInstall(result, dry, stdout) {
+    const { rel } = result.audit.target;
+    const freshInstall = result.audit.manifest === undefined;
+    if (result.written.length > 0) {
+        const verb = dry
+            ? freshInstall
+                ? "would install"
+                : "would update"
+            : freshInstall
+                ? "installed"
+                : "updated";
+        const count = `${String(result.written.length)} file${result.written.length === 1 ? "" : "s"}`;
+        stdout(`  ✔ ${rel} — ${verb} ${freshInstall ? `(${count})` : count}`);
+        if (!freshInstall)
+            stdout(`      ${result.written.join(", ")}`);
+    }
+    else if (result.skippedModified.length === 0) {
+        stdout(`  • ${rel} — up to date`);
+    }
+    if (result.skippedModified.length > 0) {
+        const count = result.skippedModified.length;
+        stdout(`  ⚠ ${rel} — ${String(count)} locally-modified file${count === 1 ? "" : "s"} left as-is (--force overwrites)`);
+        stdout(`      ${result.skippedModified.join(", ")}`);
+    }
+    reportOrphans(result, dry, stdout);
+}
+function runCheck(targets, packaged, options, stdout) {
+    // --check's verdict is about the detection result. With no agent tooling
+    // detected (and no explicit --tool), the only "target" is the invented
+    // portable fallback a bare install would use — a location this project
+    // never opted into, so auditing it can only ever fail. There is nothing
+    // to check, and nothing to check is a pass.
+    if (options.fallback) {
+        if (options.json) {
+            stdout(JSON.stringify({ fallback: true, status: "pass", targets: [] }, null, 2));
+        }
+        else {
+            stdout("  • no agent tooling detected — nothing to check");
+        }
+        return 0;
+    }
+    const audits = targets.map((target) => auditTarget(target, packaged));
+    const verdicts = audits.map(checkStatus);
+    const failed = verdicts.filter((verdict) => verdict === "fail").length;
+    const warned = verdicts.filter((verdict) => verdict === "warn").length;
+    const status = failed > 0 ? "fail" : warned > 0 ? "warn" : "pass";
+    if (options.json) {
+        stdout(JSON.stringify({
+            fallback: false,
+            status,
+            targets: audits.map((audit) => ({
+                files: audit.files,
+                rel: audit.target.rel,
+                tool: audit.target.tool,
+            })),
+        }, null, 2));
+        return failed > 0 ? 1 : 0;
+    }
+    const marks = { fail: "✖", pass: "✔", warn: "⚠" };
+    for (const [index, audit] of audits.entries()) {
+        const verdict = verdicts[index] ?? "pass";
+        const label = verdict === "pass"
+            ? "up to date"
+            : verdict === "warn"
+                ? "locally modified"
+                : audit.files.every((file) => file.status === "missing")
+                    ? "not installed (run `paramour skills`)"
+                    : "stale (run `paramour skills`)";
+        stdout(`  ${marks[verdict]} ${audit.target.rel} — ${label}`);
+        for (const file of audit.files) {
+            const detail = FILE_STATUS_DETAIL[file.status];
+            if (detail !== undefined)
+                stdout(`      ${file.relPath}: ${detail}`);
+        }
+    }
+    stdout("");
+    stdout(`skills: ${String(audits.length)} target${audits.length === 1 ? "" : "s"} — ${String(failed)} stale, ${String(warned)} modified`);
+    return failed > 0 ? 1 : 0;
+}
+function runInstall(targets, packaged, options, stdout) {
+    const results = targets.map((target) => syncTarget(target, packaged, { dry: options.dry, force: options.force }));
+    if (options.json) {
+        stdout(JSON.stringify({
+            dry: options.dry,
+            fallback: options.fallback,
+            status: results.some((result) => result.skippedModified.length > 0)
+                ? "warn"
+                : "ok",
+            targets: results.map((result) => ({
+                keptOrphans: result.keptOrphans,
+                rel: result.audit.target.rel,
+                removedOrphans: result.removedOrphans,
+                skippedModified: result.skippedModified,
+                tool: result.audit.target.tool,
+                written: result.written,
+            })),
+        }, null, 2));
+        return 0;
+    }
+    stdout(options.dry
+        ? "paramour skills (dry run — nothing written)"
+        : "paramour skills");
+    if (options.fallback) {
+        stdout("  → no agent tooling detected — installing to the portable .agents/skills/");
+    }
+    for (const result of results)
+        reportInstall(result, options.dry, stdout);
+    return 0;
+}

package/dist/config.d.ts

@@ -1,16 +1,16 @@
 /**
- * Shape of `paramour.config.{ts,mjs,json}` (§7.2 / TR7) — the CLI's config
- * file. Every field is optional; the CLI's precedence is flags → this file →
- * inference. `.ts`/`.mjs` files default-export this object.
+ * Shape of `paramour.config.{ts,mjs,json}` — the CLI's config file. Every
+ * field is optional; the CLI's precedence is flags → this file → inference.
+ * `.ts`/`.mjs` files default-export this object.
  */
 export interface ParamourConfig {
-    /** App dir, relative to the project root; default: joint discovery (PR8). */
+    /** App dir, relative to the project root; default: joint discovery. */
     appDir?: string;
-    /** Artifact path, relative to the project root (TR3 escape hatch). */
+    /** Artifact path, relative to the project root — the escape hatch. */
     outFile?: string;
     /** Page extensions, no leading dot; default: Next's four. */
     pageExtensions?: string[];
-    /** Pages dir, relative to the project root; default: joint discovery (PR8). */
+    /** Pages dir, relative to the project root; default: joint discovery. */
     pagesDir?: string;
     /**
      * Globs (relative to the project root) of modules exporting route
@@ -20,14 +20,21 @@ export interface ParamourConfig {
      */
     routeFiles?: string[];
 }
-/** @internal Discovery order at the project root (TR7) — first match wins. */
+/**
+ * @internal Every ParamourConfig key — the skill-drift test's source of
+ * truth. `satisfies Record<keyof ParamourConfig, true>` rejects a missing
+ * AND an extra key at compile time, so this roster cannot drift from the
+ * interface.
+ */
+export declare const PARAMOUR_CONFIG_KEYS: readonly string[];
+/** @internal Discovery order at the project root — first match wins. */
 export declare const CONFIG_FILE_NAMES: readonly ["paramour.config.ts", "paramour.config.mjs", "paramour.config.json"];
 /**
  * @internal Load and validate the project's config file, or `undefined`
  * when none exists. No upward traversal — the documented contract is three
- * filenames at the project root (TR7). jiti (the §7.2 loader carry-over) is
- * imported dynamically so only CLI runs that actually have a `.ts`/`.mjs`
- * config pay for it; `withTypedRoutes` users never execute it.
+ * filenames at the project root. jiti is imported dynamically so only CLI
+ * runs that actually have a `.ts`/`.mjs` config pay for it;
+ * `withTypedRoutes` users never execute it.
  */
 export declare function loadConfigFile(projectRoot: string): Promise<undefined | {
     config: ParamourConfig;

package/dist/config.js

@@ -1,6 +1,19 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-/** @internal Discovery order at the project root (TR7) — first match wins. */
+/**
+ * @internal Every ParamourConfig key — the skill-drift test's source of
+ * truth. `satisfies Record<keyof ParamourConfig, true>` rejects a missing
+ * AND an extra key at compile time, so this roster cannot drift from the
+ * interface.
+ */
+export const PARAMOUR_CONFIG_KEYS = Object.keys({
+    appDir: true,
+    outFile: true,
+    pageExtensions: true,
+    pagesDir: true,
+    routeFiles: true,
+});
+/** @internal Discovery order at the project root — first match wins. */
 export const CONFIG_FILE_NAMES = [
     "paramour.config.ts",
     "paramour.config.mjs",
@@ -9,9 +22,9 @@ export const CONFIG_FILE_NAMES = [
 /**
  * @internal Load and validate the project's config file, or `undefined`
  * when none exists. No upward traversal — the documented contract is three
- * filenames at the project root (TR7). jiti (the §7.2 loader carry-over) is
- * imported dynamically so only CLI runs that actually have a `.ts`/`.mjs`
- * config pay for it; `withTypedRoutes` users never execute it.
+ * filenames at the project root. jiti is imported dynamically so only CLI
+ * runs that actually have a `.ts`/`.mjs` config pay for it;
+ * `withTypedRoutes` users never execute it.
  */
 export async function loadConfigFile(projectRoot) {
     for (const name of CONFIG_FILE_NAMES) {