@paramour-js/next 0.4.1 → 0.7.0

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

@@ -20,6 +20,13 @@ export interface ParamourConfig {
      */
     routeFiles?: string[];
 }
+/**
+ * @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"];
 /**

package/dist/config.js

@@ -1,5 +1,18 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+/**
+ * @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",

package/dist/devtools-seam.d.ts

@@ -2,7 +2,7 @@ import type { AnyRoute, ParamsSource, RouterKind, SafeResult } from "paramour";
 /**
  * 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
+ * (`@paramour-js/devtools-panel`) reads out of. This module's JSDoc is the
  * CONTRACT OF RECORD for the slot — the panel never imports runtime code
  * from this package (its `./devtools-seam` exports entry is types-only, so
  * a runtime import fails module resolution); it attaches to the same

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
@@ -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/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/run-cli.d.ts

@@ -1,5 +1,7 @@
 import { type CliIo } from "./cli-io.js";
 export { type CliIo } from "./cli-io.js";
+type Command = (argv: readonly string[], io: CliIo) => Promise<number>;
+export declare const COMMANDS: Record<string, Command>;
 /**
  * @internal The CLI dispatcher, in-process testable: returns the exit
  * code instead of exiting. The exit-code contract holds across every

package/dist/run-cli.js

@@ -3,14 +3,17 @@ import { runDoctor } from "./commands/doctor.js";
 import { runGenerate } from "./commands/generate.js";
 import { runInit } from "./commands/init.js";
 import { runList } from "./commands/list.js";
+import { runSkills } from "./commands/skills.js";
 export {} from "./cli-io.js";
-// Alphabetical; the unknown-command message derives from these keys.
-const COMMANDS = {
+// Alphabetical; the unknown-command message derives from these keys, and the
+// skill-drift test pins them against the skill's CLI table.
+export const COMMANDS = {
     check: (argv, io) => runGenerate(argv, io, "check"),
     doctor: runDoctor,
     generate: (argv, io) => runGenerate(argv, io, "generate"),
     init: runInit,
     list: runList,
+    skills: (argv, io) => Promise.resolve(runSkills(argv, io)),
 };
 const USAGE = [
     "Usage: paramour <command> [options]",
@@ -21,6 +24,7 @@ const USAGE = [
     "  generate  generate paramour-env.d.ts from the app and pages directories",
     "  init      set up paramour in this project",
     "  list      print every route with its params/search shape",
+    "  skills    install or verify the bundled agent skill for detected agent tools",
     "",
     "Run `paramour <command> --help` for that command's options.",
 ].join("\n");

package/dist/skills/doctor.d.ts

@@ -0,0 +1,11 @@
+import type { DoctorCheck } from "../doctor/checks.js";
+/**
+ * Doctor's skills battery. Intent comes from manifest presence — doctor is
+ * passive and must not nag a project that never opted into skills — unlike
+ * `skills --check`, whose intent is the detection result (it is added to CI
+ * deliberately). Findings are warn-level, never fail: stale agent guidance
+ * degrades agent output but breaks nothing at build or runtime, and a fail
+ * here would flip doctor's exit to 1 in every consumer the day after every
+ * paramour release. The CI-fatal surface is `paramour skills --check`.
+ */
+export declare function skillsDoctorChecks(projectRoot: string): DoctorCheck[];

package/dist/skills/doctor.js

@@ -0,0 +1,71 @@
+import { message } from "../cli-io.js";
+import { loadPackagedSkill } from "./packaged.js";
+import { auditTarget, FILE_STATUS_DETAIL, isOutdated } from "./sync.js";
+import { detectTargets } from "./targets.js";
+/**
+ * Doctor's skills battery. Intent comes from manifest presence — doctor is
+ * passive and must not nag a project that never opted into skills — unlike
+ * `skills --check`, whose intent is the detection result (it is added to CI
+ * deliberately). Findings are warn-level, never fail: stale agent guidance
+ * degrades agent output but breaks nothing at build or runtime, and a fail
+ * here would flip doctor's exit to 1 in every consumer the day after every
+ * paramour release. The CI-fatal surface is `paramour skills --check`.
+ */
+export function skillsDoctorChecks(projectRoot) {
+    try {
+        const detected = detectTargets(projectRoot);
+        if (detected.length === 0) {
+            return [
+                {
+                    label: "skills: no agent tooling detected — skipped",
+                    status: "pass",
+                },
+            ];
+        }
+        const packaged = loadPackagedSkill();
+        const audits = detected
+            .map((target) => auditTarget(target, packaged))
+            .filter((audit) => audit.manifest !== undefined);
+        if (audits.length === 0) {
+            // Pass with an advisory label (check 1's "defaults in effect"
+            // precedent): declining skills is a legitimate steady state.
+            return [
+                {
+                    label: `skills: not installed (\`paramour skills\` installs agent skills for ${detected
+                        .map((target) => `${target.rel.split("/")[0] ?? ""}/`)
+                        .join(", ")})`,
+                    status: "pass",
+                },
+            ];
+        }
+        return audits.map((audit) => {
+            const detail = audit.files
+                .map((file) => {
+                const note = FILE_STATUS_DETAIL[file.status];
+                return note === undefined ? undefined : `${file.relPath}: ${note}`;
+            })
+                .filter((line) => line !== undefined);
+            if (detail.length === 0) {
+                return {
+                    label: `skills: ${audit.target.rel} is up to date`,
+                    status: "pass",
+                };
+            }
+            const outdated = audit.files.some((file) => isOutdated(file.status));
+            return {
+                detail,
+                label: `skills: ${audit.target.rel} ${outdated ? "is stale" : "has local edits"}`,
+                status: "warn",
+            };
+        });
+    }
+    catch (error) {
+        return [
+            {
+                detail: [message(error)],
+                label: "skills: could not audit installed skills",
+                status: "warn",
+            },
+        ];
+    }
+}

package/dist/skills/manifest.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The sidecar stamp `paramour skills` writes next to every installed copy.
+ * It lives inside the installed skill directory (not at the project root) so
+ * deleting a tool directory is a clean uninstall — no orphaned record keeps
+ * reporting the skill as missing after a deliberate removal. Skill loaders
+ * ignore dotfiles under progressive disclosure, so the installed skill files
+ * themselves stay byte-identical to the published ones.
+ */
+export interface SkillManifest {
+    /** POSIX-relative path → `sha256:<hex>` of the content last synced. */
+    files: Record<string, string>;
+    skill: "paramour";
+    /**
+     * The `@paramour-js/next` version that last wrote this manifest.
+     * Informational only: staleness truth is always hash comparison, so a
+     * version bump without content changes never reads as stale.
+     */
+    version: string;
+}
+export declare 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 declare function hashContent(text: string): string;
+/**
+ * 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 declare function readSkillManifest(skillDir: string): SkillManifest | undefined;
+/**
+ * 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 declare function renderManifest(manifest: SkillManifest): string;