@paramour-js/next 0.4.0 → 0.5.0

package/dist/devtools-seam.d.ts

@@ -1,6 +1,6 @@
 import type { AnyRoute, ParamsSource, RouterKind, SafeResult } from "paramour";
 /**
- * The devtools observation seam (design-12 DT5): a dependency-free global
+ * The devtools observation seam: a dependency-free global
  * slot the hooks push decode observations into and the devtools panel
  * (`@paramour-js/devtools`) reads out of. This module's JSDoc is the
  * CONTRACT OF RECORD for the slot — the panel never imports runtime code
@@ -10,7 +10,7 @@ import type { AnyRoute, ParamsSource, RouterKind, SafeResult } from "paramour";
  *
  * - Slot key: `Symbol.for("paramour.devtools.seam")` — the realm-global
  *   symbol registry, the same cross-copy identity idiom as core's error
- *   brands (RL6): a second physical copy of this module (dual-package
+ *   brands: a second physical copy of this module (dual-package
  *   hazard, bundler duplication) mints the SAME symbol and lands on the
  *   same slot. Either side — hooks or panel — may create the slot; both
  *   sides are create-if-absent.
@@ -24,14 +24,14 @@ import type { AnyRoute, ParamsSource, RouterKind, SafeResult } from "paramour";
  *   `add` — same JS thread, so nothing can be emitted between the read and
  *   the add. Emitters push to `buffer` (FIFO-capped at
  *   {@link OBSERVATION_BUFFER_CAP}) and then invoke every listener.
- * - Production (DT6): every emit call site sits behind
+ * - Production: every emit call site sits behind
  *   `process.env.NODE_ENV !== "production"`, which Next's compilers
  *   constant-fold; with the package's `sideEffects: false` the then-dead
  *   import of this module is dropped entirely. The emitted JS here imports
  *   NOTHING (the one `paramour` import is type-only) — load-bearing for
  *   that erasure.
  */
-/** The `Symbol.for("paramour.devtools.seam")` slot shape — the DT5 contract. */
+/** The `Symbol.for("paramour.devtools.seam")` slot shape — the seam contract. */
 export interface ParamourDevtoolsSeam {
     /** Capped FIFO; oldest dropped past the cap. Replay = read it. */
     readonly buffer: ParamourObservation[];
@@ -43,12 +43,12 @@ export interface ParamourDevtoolsSeam {
      */
     readonly version: 1;
 }
-/** Discriminant naming which hook reported (design-12 DT4). */
+/** Discriminant naming which hook reported. */
 export type ParamourHookId = "app.useRouteParams" | "app.useRouteParamsOrThrow" | "app.useSearch" | "app.useSearchOrThrow" | "pages.useRouteParams" | "pages.useSearch";
 /**
- * Navigation capability captured from the EMITTING hook's router (design-12
- * DT8): the panel commits URL edits through this, so it never guesses which
- * router is live and never imports Next. The panel passes ONLY the
+ * Navigation capability captured from the EMITTING hook's router: the panel
+ * commits URL edits through this, so it never guesses which router is live
+ * and never imports Next. The panel passes ONLY the
  * serialized search string (`""` or `"?…"`); the hook resolves it against
  * its OWN current pathname — `usePathname()` (App) / `asPath`'s path part
  * (Pages), both basePath-/locale-relative, which is what `replace()`
@@ -60,18 +60,18 @@ export type ParamourHookId = "app.useRouteParams" | "app.useRouteParamsOrThrow"
  */
 export type ParamourNavigate = (search: string) => void;
 /**
- * One hook decode, reported on decode CHANGE (design-12 DT4) — and
+ * One hook decode, reported on decode CHANGE — and
  * re-reported when the hook's resolution base moves under an unchanged
  * decode (a layout surviving `/product/1?q=a` → `/product/2?q=a`), so the
  * captured `navigate`/`pathname` never go stale while the hook is mounted.
  */
 export type ParamourObservation = ParamourParamsObservation | ParamourSearchObservation;
 /**
- * Pre-`select` decode result (design-12 DT12): the hook's full `SafeResult`
- * — the error arm carries the LIVE `ParamsDecodeError`/`SearchDecodeError`
- * with its `issues` — never the user's `select` projection. `pending` is
- * the Pages-only third state (DT11). Generic-erased on purpose: the panel
- * treats `data` structurally.
+ * Pre-`select` decode result: the hook's full `SafeResult` — the error arm
+ * carries the LIVE `ParamsDecodeError`/`SearchDecodeError` with its
+ * `issues` — never the user's `select` projection. `pending` is the
+ * Pages-only third state. Generic-erased on purpose: the panel treats
+ * `data` structurally.
  */
 export type ParamourObservationResult = SafeResult<unknown> | {
     readonly status: "pending";
@@ -84,7 +84,7 @@ export interface ParamourParamsObservation extends ParamourObservationBase {
 /**
  * Search decode: wire is decode-time `[key, value]` pairs in wire order —
  * order is load-bearing for repeated keys (P5/S5), and pairs round-trip
- * losslessly into the panel's raw-wire editing (DT8).
+ * losslessly into the panel's raw-wire editing.
  */
 export interface ParamourSearchObservation extends ParamourObservationBase {
     readonly kind: "search";
@@ -106,7 +106,7 @@ interface ParamourObservationBase {
     readonly pathname: string;
     readonly result: ParamourObservationResult;
     /**
-     * The LIVE route object (DT5: same JS context, no serialization) — the
+     * The LIVE route object (same JS context, no serialization) — the
      * panel calls `describeRoute`, the route's own codecs, and
      * `buildSearchString` on it directly.
      */
@@ -115,7 +115,7 @@ interface ParamourObservationBase {
 }
 /**
  * 128: replay only needs the pre-panel-mount window. One observation per
- * decode CHANGE per hook (DT4) means even a long pre-open session is dozens
+ * decode CHANGE per hook means even a long pre-open session is dozens
  * of entries, not thousands; the panel keys on route, so depth beyond
  * "every route seen recently" adds nothing — the cap mostly bounds how many
  * live route/result references the buffer retains.
@@ -123,8 +123,8 @@ interface ParamourObservationBase {
 export declare const OBSERVATION_BUFFER_CAP = 128;
 /**
  * Pushes one observation and notifies listeners. The internal production
- * early-return is belt-and-suspenders under DT6 (every call site is ALSO
- * guarded, which is what the bundler erases); it makes the guard directly
+ * early-return is belt-and-suspenders (every call site is ALSO guarded,
+ * which is what the bundler erases); it makes the guard directly
  * unit-testable and keeps a future unguarded call site failing safe.
  */
 export declare function emitObservation(observation: ParamourObservation): void;

package/dist/devtools-seam.js

@@ -1,6 +1,6 @@
 /**
  * 128: replay only needs the pre-panel-mount window. One observation per
- * decode CHANGE per hook (DT4) means even a long pre-open session is dozens
+ * decode CHANGE per hook means even a long pre-open session is dozens
  * of entries, not thousands; the panel keys on route, so depth beyond
  * "every route seen recently" adds nothing — the cap mostly bounds how many
  * live route/result references the buffer retains.
@@ -10,8 +10,8 @@ const SEAM_KEY = Symbol.for("paramour.devtools.seam");
 const globalSlots = globalThis;
 /**
  * Pushes one observation and notifies listeners. The internal production
- * early-return is belt-and-suspenders under DT6 (every call site is ALSO
- * guarded, which is what the bundler erases); it makes the guard directly
+ * early-return is belt-and-suspenders (every call site is ALSO guarded,
+ * which is what the bundler erases); it makes the guard directly
  * unit-testable and keeps a future unguarded call site failing safe.
  */
 export function emitObservation(observation) {

package/dist/doctor/checks.js

@@ -8,6 +8,7 @@ import { tsconfigCheck } from "../init/scaffold.js";
 import { detectWrapState, findNextConfig } from "../init/wrap-next-config.js";
 import { discoverRouteDefinitions, routeKey, } from "../list/discover-route-defs.js";
 import { scanRoutes } from "../scan.js";
+import { skillsDoctorChecks } from "../skills/doctor.js";
 /**
  * @internal The check battery, in report order. Each check degrades
  * independently — doctor exists to diagnose broken setups, so a throwing
@@ -34,7 +35,7 @@ export async function runDoctorChecks(projectRoot) {
             status: "fail",
         });
     }
-    // 2. Route directories resolve (PR8 discovery, config dirs honored).
+    // 2. Route directories resolve (joint discovery, config dirs honored).
     let inputs;
     try {
         inputs = await resolveInputs({}, projectRoot, config);
@@ -135,7 +136,10 @@ export async function runDoctorChecks(projectRoot) {
     }
     // 5. Version alignment between the two packages.
     checks.push(versionCheck(projectRoot));
-    // 6. tsconfig covers the artifact (init's warn-level heuristic).
+    // 6. Installed agent skills reflect this package's bundled content —
+    // upgrade-adjacent like the version check, hence its neighbor.
+    checks.push(...skillsDoctorChecks(projectRoot));
+    // 7. tsconfig covers the artifact (init's warn-level heuristic).
     // resolve, not join — an absolute outFile must win, as it does in
     // resolveInputs.
     const artifactPath = inputs?.artifactPath ??
@@ -146,7 +150,7 @@ export async function runDoctorChecks(projectRoot) {
         label: `tsconfig: ${coverage.label}`,
         status: coverage.ok ? "pass" : "warn",
     });
-    // 7. Route-definition discovery health (list's engine).
+    // 8. Route-definition discovery health (list's engine).
     checks.push(await discoveryCheck(projectRoot, config, routes));
     return checks;
 }

package/dist/emit.d.ts

@@ -2,34 +2,34 @@
 export interface WriteIfChangedResult {
     /**
      * Prior file content, or `null` when the file did not exist — the input
-     * for TR4's drift warning (which paths appeared/disappeared).
+     * for the drift warning (which paths appeared/disappeared).
      */
     previousContent: null | string;
     /**
-     * `false` on a byte-identical no-op — the signal `--check` (TR7) and the
-     * watch loop (TR5) hang off.
+     * `false` on a byte-identical no-op — the signal `--check` and the watch
+     * loop hang off.
      */
     written: boolean;
 }
-/** Input of {@link emitArtifact} — one union per router (PR9). */
+/** Input of {@link emitArtifact} — one union per router. */
 export interface EmitRoutes {
     appRoutes: readonly string[];
     pagesRoutes: readonly string[];
 }
 /**
- * Artifact text for the per-router route unions (TR3/PR9): deterministic —
- * sorted, deduped, LF-only, trailing newline, no timestamps. Sorting/deduping
+ * Artifact text for the per-router route unions: deterministic — sorted,
+ * deduped, LF-only, trailing newline, no timestamps. Sorting/deduping
  * happens here as well as in the scanner so byte-identity never depends on
  * who the caller was. Always the leading-pipe multiline union form, even for
  * one path — one shape, no count-dependent formatting. An empty union omits
- * its member entirely (TR3's absent-not-`never` rule, applied per router in
- * PR9): a pages-only project keeps world-A's permissive `string` fallback
- * for `defineAppRoute`, and vice versa.
+ * its member entirely (absent, not `never`, applied per router): a
+ * pages-only project keeps world-A's permissive `string` fallback for
+ * `defineAppRoute`, and vice versa.
  */
 export declare function emitArtifact(routes: EmitRoutes): string;
 /**
- * Compare-before-write (TR3): a no-op regeneration must not touch the file —
- * that property is what prevents TS-server churn, watch-loop feedback, and
- * concurrent-generator races (TR6).
+ * Compare-before-write: a no-op regeneration must not touch the file — that
+ * property is what prevents TS-server churn, watch-loop feedback, and
+ * concurrent-generator races.
  */
 export declare function writeIfChanged(filePath: string, content: string): WriteIfChangedResult;

package/dist/emit.js

@@ -2,14 +2,14 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 const HEADER = "// Generated by @paramour-js/next. Do not edit — regenerate with `paramour generate`.";
 /**
- * Artifact text for the per-router route unions (TR3/PR9): deterministic —
- * sorted, deduped, LF-only, trailing newline, no timestamps. Sorting/deduping
+ * Artifact text for the per-router route unions: deterministic — sorted,
+ * deduped, LF-only, trailing newline, no timestamps. Sorting/deduping
  * happens here as well as in the scanner so byte-identity never depends on
  * who the caller was. Always the leading-pipe multiline union form, even for
  * one path — one shape, no count-dependent formatting. An empty union omits
- * its member entirely (TR3's absent-not-`never` rule, applied per router in
- * PR9): a pages-only project keeps world-A's permissive `string` fallback
- * for `defineAppRoute`, and vice versa.
+ * its member entirely (absent, not `never`, applied per router): a
+ * pages-only project keeps world-A's permissive `string` fallback for
+ * `defineAppRoute`, and vice versa.
  */
 export function emitArtifact(routes) {
     const members = ["appRoutes", "pagesRoutes"].flatMap((member) => {
@@ -21,22 +21,22 @@ export function emitArtifact(routes) {
         // contain a quote or backslash (Linux/macOS), which unescaped would emit
         // invalid TS or silently declare the wrong route. JSON string escaping is
         // a subset of TS string-literal escaping (output stays valid TS) and is
-        // deterministic, so TR3's byte-identity guarantee holds.
+        // deterministic, so the byte-identity guarantee holds.
         return [
             `    ${member}:`,
             `${sorted.map((path) => `      | ${JSON.stringify(path)}`).join("\n")};`,
         ];
     });
     if (members.length === 0) {
-        // TR3: no routes yet → NO members (explicitly not `never`, which would
+        // No routes yet → NO members (explicitly not `never`, which would
         // make every route-constructor call an error). The empty merge keeps
-        // the documented world-A `string` fallback (RL8).
+        // the documented world-A `string` fallback.
         return [
             HEADER,
             'import "paramour";',
             "",
             'declare module "paramour" {',
-            "  // TR3: empty merge — no routes discovered yet; the pre-generation",
+            "  // Empty merge — no routes discovered yet; the pre-generation",
             "  // `string` fallback stays in effect.",
             "  // eslint-disable-next-line @typescript-eslint/no-empty-object-type",
             "  interface ParamourRegister {}",
@@ -57,9 +57,9 @@ export function emitArtifact(routes) {
     ].join("\n");
 }
 /**
- * Compare-before-write (TR3): a no-op regeneration must not touch the file —
- * that property is what prevents TS-server churn, watch-loop feedback, and
- * concurrent-generator races (TR6).
+ * Compare-before-write: a no-op regeneration must not touch the file — that
+ * property is what prevents TS-server churn, watch-loop feedback, and
+ * concurrent-generator races.
  */
 export function writeIfChanged(filePath, content) {
     const previousContent = existsSync(filePath)
@@ -67,7 +67,7 @@ export function writeIfChanged(filePath, content) {
         : null;
     if (previousContent === content)
         return { previousContent, written: false };
-    // TR3's outFile escape hatch may point into a not-yet-existing directory.
+    // The outFile escape hatch may point into a not-yet-existing directory.
     mkdirSync(dirname(filePath), { recursive: true });
     writeFileSync(filePath, content);
     return { previousContent, written: true };

package/dist/generate.d.ts

@@ -1,11 +1,11 @@
 /**
- * The shared generation engine (TR9): `withTypedRoutes` and the CLI drive
- * these same functions, so wrapper and `paramour generate` cannot drift on
- * what a pass produces. Everything here is @internal — not barrel API.
+ * The shared generation engine: `withTypedRoutes` and the CLI drive these
+ * same functions, so wrapper and `paramour generate` cannot drift on what a
+ * pass produces. Everything here is @internal — not barrel API.
  */
 /** Result of {@link checkArtifact}. */
 export interface CheckResult {
-    /** App-router drift — split per router so the report names it (PR9). */
+    /** App-router drift — split per router so the report names it. */
     app: RouterDrift;
     /** `true` when the artifact file does not exist at all. */
     missingFile: boolean;
@@ -14,7 +14,7 @@ export interface CheckResult {
     /** `true` on a byte-identical artifact — the only non-drift state. */
     upToDate: boolean;
 }
-/** Inputs to one generation/check pass; either dir may be absent (PR1). */
+/** Inputs to one generation/check pass; either dir may be absent. */
 export interface GenerateInputs {
     appDir?: string | undefined;
     artifactPath: string;
@@ -29,10 +29,10 @@ export interface GenerateResult {
     pagesRoutes: string[];
     /** Prior artifact content, `null` when the file did not exist. */
     previousContent: null | string;
-    /** `false` on a byte-identical no-op (TR3 write-if-changed). */
+    /** `false` on a byte-identical no-op (write-if-changed). */
     written: boolean;
 }
-/** One router's appeared/disappeared route paths (TR4/TR7 drift). */
+/** One router's appeared/disappeared route paths. */
 export interface RouterDrift {
     /** Routes on disk (scan) that the artifact lacks. */
     appeared: string[];
@@ -40,25 +40,25 @@ export interface RouterDrift {
     disappeared: string[];
 }
 /**
- * `--check` (TR7): scan to memory and byte-compare against disk — never
- * writes. A missing artifact is drift, not an error: that is exactly the
- * CI-degrades-to-world-A case the committed file exists to prevent (TR3).
+ * `--check`: scan to memory and byte-compare against disk — never writes. A
+ * missing artifact is drift, not an error: that is exactly the
+ * CI-degrades-to-world-A case the committed file exists to prevent.
  */
 export declare function checkArtifact(inputs: GenerateInputs): CheckResult;
 /**
  * Per-router drift of a completed {@link generate} pass against the artifact
- * it replaced — the wrapper's build-phase drift report (TR4).
+ * it replaced — the wrapper's build-phase drift report.
  */
 export declare function diffGenerated(result: GenerateResult): {
     app: RouterDrift;
     pages: RouterDrift;
 };
 /**
- * The `  + /new (app)` / `  - /old (pages)` lines of a drift report
- * (TR4/TR7) — each line names the router its path moved in (PR9).
+ * The `  + /new (app)` / `  - /old (pages)` lines of a drift report — each
+ * line names the router its path moved in.
  */
 export declare function formatRouteDiff(app: RouterDrift, pages: RouterDrift): string[];
-/** One generation pass: scan → emit → write-if-changed (TR3). */
+/** One generation pass: scan → emit → write-if-changed. */
 export declare function generate(inputs: GenerateInputs): GenerateResult;
 /**
  * Per-router route paths in a previously emitted artifact; both empty for a

package/dist/generate.js

@@ -3,17 +3,17 @@ import { emitArtifact, writeIfChanged } from "./emit.js";
 import { scanRoutes } from "./scan.js";
 /**
  * Reads the per-router unions back out of a previously emitted artifact for
- * drift diffs (TR4/TR7). Only ever applied to text this package generated
- * (TR3 deterministic form), so line-anchored matches on the member headers
- * and union members are exact, not heuristic. `\s*$` on both tolerates a
+ * drift diffs. Only ever applied to text this package generated (its
+ * deterministic form), so line-anchored matches on the member headers and
+ * union members are exact, not heuristic. `\s*$` on both tolerates a
  * CRLF-resaved artifact.
  */
 const MEMBER_HEADER = /^\s*(appRoutes|pagesRoutes):\s*$/;
 const UNION_MEMBER = /^\s*\| "(.*)";?\s*$/;
 /**
- * `--check` (TR7): scan to memory and byte-compare against disk — never
- * writes. A missing artifact is drift, not an error: that is exactly the
- * CI-degrades-to-world-A case the committed file exists to prevent (TR3).
+ * `--check`: scan to memory and byte-compare against disk — never writes. A
+ * missing artifact is drift, not an error: that is exactly the
+ * CI-degrades-to-world-A case the committed file exists to prevent.
  */
 export function checkArtifact(inputs) {
     const routes = scanRoutes(inputs, inputs.pageExtensions);
@@ -39,7 +39,7 @@ export function checkArtifact(inputs) {
 }
 /**
  * Per-router drift of a completed {@link generate} pass against the artifact
- * it replaced — the wrapper's build-phase drift report (TR4).
+ * it replaced — the wrapper's build-phase drift report.
  */
 export function diffGenerated(result) {
     const previous = parseArtifactRoutes(result.previousContent);
@@ -49,8 +49,8 @@ export function diffGenerated(result) {
     };
 }
 /**
- * The `  + /new (app)` / `  - /old (pages)` lines of a drift report
- * (TR4/TR7) — each line names the router its path moved in (PR9).
+ * The `  + /new (app)` / `  - /old (pages)` lines of a drift report — each
+ * line names the router its path moved in.
  */
 export function formatRouteDiff(app, pages) {
     return [
@@ -60,7 +60,7 @@ export function formatRouteDiff(app, pages) {
         ...pages.disappeared.map((path) => `  - ${path} (pages)`),
     ];
 }
-/** One generation pass: scan → emit → write-if-changed (TR3). */
+/** One generation pass: scan → emit → write-if-changed. */
 export function generate(inputs) {
     const routes = scanRoutes(inputs, inputs.pageExtensions);
     return {
@@ -92,7 +92,7 @@ export function parseArtifactRoutes(previousContent) {
             continue;
         }
         // Any other line ends the member block — union members are contiguous
-        // in the TR3 deterministic form.
+        // in the deterministic emitted form.
         current = undefined;
     }
     return { appRoutes, pagesRoutes };

package/dist/init/agents-md.d.ts

@@ -0,0 +1,32 @@
+export declare const AGENTS_MARKER_START = "<!-- paramour:start -->";
+export declare const AGENTS_MARKER_END = "<!-- paramour:end -->";
+/**
+ * @internal The marker-managed section init appends to an agent
+ * instructions file. Install-dir-agnostic on purpose: the skill lands in
+ * `.claude/`, `.cursor/`, or the portable `.agents/` depending on what
+ * `detectTargets` found, and this snippet must stay true for all of them.
+ */
+export declare function agentsSnippet(): string;
+/**
+ * @internal The instructions file the snippet goes into: AGENTS.md first
+ * (the cross-tool convention), CLAUDE.md as the fallback, never both (tools
+ * that read both would see duplicated content, and projects keeping both
+ * usually mirror them — one marker-managed copy is the single source of
+ * truth). Never creates a file: a root AGENTS.md is a `detectTargets`
+ * detection signal, so init inventing one would change what the skills
+ * step sees on the next run.
+ */
+export declare function findAgentsFile(projectRoot: string): string | undefined;
+/**
+ * @internal Add or refresh the marker-delimited paramour section. Pure
+ * string→string (the `addPackageScript` pattern) so the write/dry-run
+ * decision stays with the caller. Re-runs reconcile the section to the
+ * current snippet — the markers exist precisely to delimit
+ * paramour-managed content; prose outside them is never touched. A start
+ * marker without an end marker is the one state left alone: repairing it
+ * would mean guessing where the user's own text begins.
+ */
+export declare function upsertAgentsSection(text: string): {
+    status: "added" | "unchanged" | "unterminated" | "updated";
+    text: string;
+};

package/dist/init/agents-md.js

@@ -0,0 +1,78 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+export const AGENTS_MARKER_START = "<!-- paramour:start -->";
+export const AGENTS_MARKER_END = "<!-- paramour:end -->";
+/**
+ * @internal The marker-managed section init appends to an agent
+ * instructions file. Install-dir-agnostic on purpose: the skill lands in
+ * `.claude/`, `.cursor/`, or the portable `.agents/` depending on what
+ * `detectTargets` found, and this snippet must stay true for all of them.
+ */
+export function agentsSnippet() {
+    return [
+        AGENTS_MARKER_START,
+        "",
+        "## paramour",
+        "",
+        "This project uses paramour for type-safe routing. The paramour agent",
+        "skill (installed by `paramour skills` into detected agent-tool skills",
+        "directories) documents codecs, route definitions, hooks, and the CLI —",
+        "read it before route work.",
+        "",
+        "After changing routes: run `paramour generate`, verify with `paramour",
+        "check` (exit 0 = artifact current), inspect shapes with `paramour list`,",
+        "and commit `paramour-env.d.ts`.",
+        "",
+        AGENTS_MARKER_END,
+    ].join("\n");
+}
+/**
+ * @internal The instructions file the snippet goes into: AGENTS.md first
+ * (the cross-tool convention), CLAUDE.md as the fallback, never both (tools
+ * that read both would see duplicated content, and projects keeping both
+ * usually mirror them — one marker-managed copy is the single source of
+ * truth). Never creates a file: a root AGENTS.md is a `detectTargets`
+ * detection signal, so init inventing one would change what the skills
+ * step sees on the next run.
+ */
+export function findAgentsFile(projectRoot) {
+    for (const name of ["AGENTS.md", "CLAUDE.md"]) {
+        const path = join(projectRoot, name);
+        if (existsSync(path))
+            return path;
+    }
+    return undefined;
+}
+/**
+ * @internal Add or refresh the marker-delimited paramour section. Pure
+ * string→string (the `addPackageScript` pattern) so the write/dry-run
+ * decision stays with the caller. Re-runs reconcile the section to the
+ * current snippet — the markers exist precisely to delimit
+ * paramour-managed content; prose outside them is never touched. A start
+ * marker without an end marker is the one state left alone: repairing it
+ * would mean guessing where the user's own text begins.
+ */
+export function upsertAgentsSection(text) {
+    const start = text.indexOf(AGENTS_MARKER_START);
+    if (start === -1) {
+        const base = text === "" || text.endsWith("\n") ? text : `${text}\n`;
+        const separator = base === "" ? "" : "\n";
+        return {
+            status: "added",
+            text: `${base}${separator}${agentsSnippet()}\n`,
+        };
+    }
+    const end = text.indexOf(AGENTS_MARKER_END, start);
+    if (end === -1)
+        return { status: "unterminated", text };
+    const current = text.slice(start, end + AGENTS_MARKER_END.length);
+    const snippet = agentsSnippet();
+    if (current === snippet)
+        return { status: "unchanged", text };
+    return {
+        status: "updated",
+        text: text.slice(0, start) +
+            snippet +
+            text.slice(end + AGENTS_MARKER_END.length),
+    };
+}

package/dist/init/scaffold.js

@@ -1,6 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, relative } from "node:path";
 import { resolveRouteDirs } from "../scan.js";
+import { loadPackagedSkill } from "../skills/packaged.js";
+import { auditTarget, isOutdated } from "../skills/sync.js";
+import { detectTargets } from "../skills/targets.js";
 /**
  * Insert `"paramour": "paramour generate"` into a package.json's scripts,
  * preserving the file's own indentation and trailing-newline choice.
@@ -58,6 +61,7 @@ export function checkSetup(projectRoot, artifactPath) {
     }
     checks.push(dependenciesCheck(projectRoot));
     checks.push(tsconfigCheck(projectRoot, artifactPath));
+    checks.push(...skillsSetupCheck(projectRoot));
     return checks;
 }
 /** The starter `paramour.config.ts` — every field commented-out defaults. */
@@ -205,6 +209,56 @@ function dependenciesCheck(projectRoot) {
             ok: false,
         };
 }
+/**
+ * Agent-skills summary line — only for projects with agent tooling; an
+ * agent-free project gets no line at all, keeping the summary signal-dense.
+ */
+function skillsSetupCheck(projectRoot) {
+    try {
+        const detected = detectTargets(projectRoot);
+        if (detected.length === 0)
+            return [];
+        const packaged = loadPackagedSkill();
+        const audits = detected
+            .map((target) => auditTarget(target, packaged))
+            .filter((audit) => audit.manifest !== undefined);
+        if (audits.length === 0) {
+            return [
+                {
+                    detail: "run `paramour skills`",
+                    label: "agent skills: not installed",
+                    ok: false,
+                },
+            ];
+        }
+        // Local edits are legitimate tailoring, not drift — only missing/stale
+        // content makes the line a warning.
+        const outdated = audits.filter((audit) => audit.files.some((file) => isOutdated(file.status)));
+        if (outdated.length > 0) {
+            return [
+                {
+                    detail: "run `paramour skills` to re-sync",
+                    label: `agent skills: ${outdated
+                        .map((audit) => audit.target.rel)
+                        .join(", ")} out of date`,
+                    ok: false,
+                },
+            ];
+        }
+        return [
+            {
+                label: `agent skills: ${audits
+                    .map((audit) => audit.target.rel)
+                    .join(", ")} up to date`,
+                ok: true,
+            },
+        ];
+    }
+    catch {
+        // A broken skills probe must not break the warn-level summary.
+        return [];
+    }
+}
 /**
  * String-aware trailing-comma removal over comment-free JSONC — a flat
  * regex would also rewrite `,}`/`,]` inside string literals (glob patterns).

package/dist/list/discover-route-defs.d.ts

@@ -37,10 +37,10 @@ export interface RouteDefinition {
  * its text mentions a define constructor (grep-then-load). `routeFiles`
  * config globs replace the default patterns when the heuristic misfires.
  *
- * jiti evaluates matched files (the §7.2 loader carry-over). Known limits,
- * both handled by the per-module degrade: tsconfig `paths` aliases are not
- * resolved (a future improvement could feed them into jiti's `alias`
- * option), and `server-only`-style imports throw outside Next.
+ * jiti evaluates matched files (the loader carry-over from config loading).
+ * Known limits, both handled by the per-module degrade: tsconfig `paths`
+ * aliases are not resolved (a future improvement could feed them into jiti's
+ * `alias` option), and `server-only`-style imports throw outside Next.
  */
 export declare function discoverRouteDefinitions(projectRoot: string, options?: {
     routeFiles?: readonly string[] | undefined;

package/dist/list/discover-route-defs.js

@@ -23,10 +23,10 @@ const MAX_PREFILTER_BYTES = 512 * 1024;
  * its text mentions a define constructor (grep-then-load). `routeFiles`
  * config globs replace the default patterns when the heuristic misfires.
  *
- * jiti evaluates matched files (the §7.2 loader carry-over). Known limits,
- * both handled by the per-module degrade: tsconfig `paths` aliases are not
- * resolved (a future improvement could feed them into jiti's `alias`
- * option), and `server-only`-style imports throw outside Next.
+ * jiti evaluates matched files (the loader carry-over from config loading).
+ * Known limits, both handled by the per-module degrade: tsconfig `paths`
+ * aliases are not resolved (a future improvement could feed them into jiti's
+ * `alias` option), and `server-only`-style imports throw outside Next.
  */
 export async function discoverRouteDefinitions(projectRoot, options = {}) {
     // Dynamic imports, same stance as config.ts: only commands that actually