vigiles 9.0.0 → 9.1.0

package/dist/audit-score.d.ts

@@ -4,9 +4,12 @@
  * A single structural-health number (the leaderboard's `scoreReport`) ranks
  * plugins, but it hides WHERE a harness is weak. This buckets the SAME
  * deterministic findings into four categories — Truthfulness, Triggering,
- * Structure, Tested — each a 0–100 ring, with a weighted overall. Same
- * detectors, no re-detection (one-detector-no-drift); all deterministic, no
- * execution. (Safety — "do your hooks actually block?" — is NOT an `audit` ring:
+ * Structure, Tested — each a 0–100 ring, as a DIAGNOSTIC breakdown beneath one
+ * headline `overall` = `100 − Σ(all graded penalties)` (the SAME summed model as
+ * the leaderboard's single health number, via the shared `computeIntegrityScore`
+ * — so the two surfaces never disagree). Same detectors, no re-detection
+ * (one-detector-no-drift); all deterministic, no execution. (Safety — "do your
+ * hooks actually block?" — is NOT an `audit` ring:
  * it requires executing your hooks, which needs cross-platform confinement
  * that isn't shipped yet, so it lives in the `vigiles/testing` API via
  * `guardrail-check`/`assertBlocksDisasters`, where you opt in explicitly.)
@@ -23,11 +26,25 @@ export interface CategoryScore {
     readonly score: number | null;
     /** Relative weight in the overall (equal by default — tune later). */
     readonly weight: number;
+    /**
+     * Advisory categories are shown but EXCLUDED from the overall grade. An untested
+     * surface (or any best-practice gap) is a HARDENING signal, not a broken harness
+     * — it must never drag the grade down, so `audit` doesn't read as F on a clean
+     * repo that simply hasn't written tests yet. The grade reflects what's BROKEN.
+     */
+    readonly advisory?: boolean;
     /** Human-readable deductions / notes, worst first; empty when clean. */
     readonly findings: readonly string[];
 }
 export interface AuditScore {
-    /** Weighted average over the ASSESSABLE categories (n/a excluded). 0 when empty. */
+    /**
+     * The headline score — `100 − Σ(all graded penalties)`, clamped to [0,100]
+     * (the SAME summed model as the leaderboard's single health number, computed by
+     * the shared {@link computeIntegrityScore}, so the two surfaces never disagree).
+     * The per-category rings below are a DIAGNOSTIC breakdown, not the headline: a
+     * plugin whose only issue is Structure −30 shows Structure 70 in the breakdown
+     * AND overall 70 (averaging the rings would dilute that to ~90). 0 when empty.
+     */
     readonly overall: number;
     readonly grade: PluginScore["grade"];
     readonly categories: readonly CategoryScore[];
@@ -35,10 +52,13 @@ export interface AuditScore {
     readonly empty: boolean;
 }
 /**
- * Bucket a scan report into the four deterministic Lighthouse categories with a
- * weighted overall. n/a categories are excluded from the overall, never scored 0.
+ * Bucket a scan report into the four deterministic Lighthouse categories as a
+ * DIAGNOSTIC breakdown, with the headline `overall` = `100 − Σ(all graded
+ * penalties)` (the shared summed model — NOT the average of the rings — so it
+ * equals the leaderboard's single health number). The advisory Tested ring and
+ * any n/a ring are shown but excluded from the headline.
  */
 export declare function auditScore(report: ScanReport): AuditScore;
-/** Render the category rings + the weighted overall for the terminal. */
+/** Render the category rings (diagnostic) + the summed overall for the terminal. */
 export declare function formatAuditScore(s: AuditScore): string;
 //# sourceMappingURL=audit-score.d.ts.map

package/dist/audit-score.js

@@ -8,9 +8,12 @@ exports.formatAuditScore = formatAuditScore;
  * A single structural-health number (the leaderboard's `scoreReport`) ranks
  * plugins, but it hides WHERE a harness is weak. This buckets the SAME
  * deterministic findings into four categories — Truthfulness, Triggering,
- * Structure, Tested — each a 0–100 ring, with a weighted overall. Same
- * detectors, no re-detection (one-detector-no-drift); all deterministic, no
- * execution. (Safety — "do your hooks actually block?" — is NOT an `audit` ring:
+ * Structure, Tested — each a 0–100 ring, as a DIAGNOSTIC breakdown beneath one
+ * headline `overall` = `100 − Σ(all graded penalties)` (the SAME summed model as
+ * the leaderboard's single health number, via the shared `computeIntegrityScore`
+ * — so the two surfaces never disagree). Same detectors, no re-detection
+ * (one-detector-no-drift); all deterministic, no execution. (Safety — "do your
+ * hooks actually block?" — is NOT an `audit` ring:
  * it requires executing your hooks, which needs cross-platform confinement
  * that isn't shipped yet, so it lives in the `vigiles/testing` API via
  * `guardrail-check`/`assertBlocksDisasters`, where you opt in explicitly.)
@@ -19,13 +22,9 @@ exports.formatAuditScore = formatAuditScore;
  * overall — never a false 0. Pure over the `ScanReport`, so it's fully testable.
  */
 const leaderboard_js_1 = require("./leaderboard.js");
-// Per-item penalties — mirror the leaderboard's weights so the category view and
-// the single health number stay consistent (broken-at-runtime costs most).
-const W_MISSING_HOOK = 15;
-const W_NO_DESCRIPTION = 10;
-const W_DANGLING_REF = 8;
-const W_OVERLAP = 8; // a description collision → the wrong skill fires
-const W_NO_CONTRACT = 5;
+// Per-item penalties are the SHARED leaderboard weights (imported above) so the
+// category rings and the single health number can never drift. W_UNTESTED is
+// audit-only — untested surfaces are advisory (shown, never scored into overall).
 const W_UNTESTED = 3;
 /** Apply deductions to a 100 base, clamped to [0,100], collecting non-zero labels. */
 function scoreFrom(deductions) {
@@ -48,12 +47,12 @@ function truthfulness(r) {
     const { score, findings } = scoreFrom([
         {
             n: r.danglingRefs.length,
-            weight: W_DANGLING_REF,
+            weight: leaderboard_js_1.W_DANGLING_REF,
             label: "broken intra-plugin reference(s)",
         },
         {
             n: missingHooks,
-            weight: W_MISSING_HOOK,
+            weight: leaderboard_js_1.W_MISSING_HOOK,
             label: "hook script(s) missing (never run)",
         },
     ]);
@@ -64,12 +63,12 @@ function triggering(r) {
     const { score, findings } = scoreFrom([
         {
             n: noDesc,
-            weight: W_NO_DESCRIPTION,
+            weight: leaderboard_js_1.W_NO_DESCRIPTION,
             label: "skill(s) with no usable description (can't trigger)",
         },
         {
             n: r.descriptionOverlaps.length,
-            weight: W_OVERLAP,
+            weight: leaderboard_js_1.W_OVERLAP,
             label: "near-identical skill description(s) (wrong one fires)",
         },
     ]);
@@ -83,47 +82,47 @@ function structure(r) {
     const { score, findings } = scoreFrom([
         {
             n: deadTools,
-            weight: W_DANGLING_REF,
+            weight: leaderboard_js_1.W_DANGLING_REF,
             label: "agent tool(s) that don't exist (typo / never-available)",
         },
         {
             n: deadMcpTools,
-            weight: W_DANGLING_REF,
+            weight: leaderboard_js_1.W_DANGLING_REF,
             label: "agent MCP tool(s) whose server isn't declared",
         },
         {
             n: r.hookEventIssues.length,
-            weight: W_MISSING_HOOK,
+            weight: leaderboard_js_1.W_MISSING_HOOK,
             label: "hook(s) on an unknown event (never fire)",
         },
         {
             n: r.mcpIssues.length,
-            weight: W_DANGLING_REF,
+            weight: leaderboard_js_1.W_DANGLING_REF,
             label: "MCP server(s) that can't start (no command/url)",
         },
         {
             n: r.mcpHookIssues.length,
-            weight: W_DANGLING_REF,
+            weight: leaderboard_js_1.W_DANGLING_REF,
             label: "mcp_tool hook(s) incomplete / undeclared server",
         },
         {
             n: r.frontmatterIssues.length,
-            weight: W_NO_DESCRIPTION,
+            weight: leaderboard_js_1.W_NO_DESCRIPTION,
             label: "surface(s) missing required frontmatter",
         },
         {
             n: r.frontmatterValueIssues.length,
-            weight: W_NO_CONTRACT,
+            weight: leaderboard_js_1.W_NO_CONTRACT,
             label: "agent(s) with an invalid model/color (silent fallback)",
         },
         {
             n: deadDisallowed,
-            weight: W_NO_CONTRACT,
+            weight: leaderboard_js_1.W_NO_CONTRACT,
             label: "disallowedTools typo(s) that block nothing",
         },
         {
             n: noContract,
-            weight: W_NO_CONTRACT,
+            weight: leaderboard_js_1.W_NO_CONTRACT,
             label: "agent(s) inherit all tools (no contract)",
         },
     ]);
@@ -133,26 +132,29 @@ function tested(r) {
     const { score, findings } = scoreFrom([
         { n: r.untested, weight: W_UNTESTED, label: "untested surface(s)" },
     ]);
-    return { key: "Tested", score, weight: 1, findings };
+    // ADVISORY: untested surfaces are a hardening gap, not breakage — shown, but
+    // excluded from the overall grade (so a clean-but-untested repo isn't graded F).
+    return { key: "Tested", score, weight: 1, advisory: true, findings };
 }
-function isEmptyMachine(r) {
-    const surfaces = r.skills.length +
-        r.agents.length +
-        r.hooks.length +
-        r.inlineHooks +
-        r.commands;
-    // An instruction-only repo (just a CLAUDE.md/AGENTS.md, no plugin surface) is
-    // NOT empty — the scan records `instructions` precisely so it isn't graded
-    // F/0 "no loadable surface". Only a dir with NO instruction file AND no
-    // surface is the empty machine.
-    return surfaces === 0 && !r.mcp && !r.instructions;
+/**
+ * An instruction-only repo (just a CLAUDE.md/AGENTS.md, no plugin surface) is NOT
+ * empty — the scan records `instructions` precisely so it isn't graded F/0 "no
+ * loadable surface". Only a dir with NO instruction file AND no surface is empty.
+ * (The shared `isEmptyMachine` ignores `instructions`; audit additionally treats
+ * an instruction file as a surface.)
+ */
+function isEmptyAudit(r) {
+    return (0, leaderboard_js_1.isEmptyMachine)(r) && !r.instructions;
 }
 /**
- * Bucket a scan report into the four deterministic Lighthouse categories with a
- * weighted overall. n/a categories are excluded from the overall, never scored 0.
+ * Bucket a scan report into the four deterministic Lighthouse categories as a
+ * DIAGNOSTIC breakdown, with the headline `overall` = `100 − Σ(all graded
+ * penalties)` (the shared summed model — NOT the average of the rings — so it
+ * equals the leaderboard's single health number). The advisory Tested ring and
+ * any n/a ring are shown but excluded from the headline.
  */
 function auditScore(report) {
-    if (isEmptyMachine(report)) {
+    if (isEmptyAudit(report)) {
         const categories = [
             "Truthfulness",
             "Triggering",
@@ -177,11 +179,11 @@ function auditScore(report) {
         structure(report),
         tested(report),
     ];
-    const assessable = categories.filter((c) => c.score !== null);
-    const totalWeight = assessable.reduce((s, c) => s + c.weight, 0);
-    const overall = totalWeight === 0
-        ? 0
-        : Math.round(assessable.reduce((s, c) => s + c.score * c.weight, 0) / totalWeight);
+    // The headline is the SUMMED model (the shared integrity score), NOT the average
+    // of the rings — averaging would let a real problem in one category be diluted
+    // by clean siblings. The rings above stay a diagnostic breakdown; Tested
+    // (advisory) is never summed in (untested surfaces don't drag the grade).
+    const { score: overall } = (0, leaderboard_js_1.computeIntegrityScore)((0, leaderboard_js_1.reportDeductions)(report));
     return { overall, grade: (0, leaderboard_js_1.gradeFor)(overall), categories, empty: false };
 }
 // A 22-cell bar gauge ("ring" in the terminal; the real rings are the HTML).
@@ -202,14 +204,15 @@ function bar(score) {
     const filled = Math.round((score / 100) * BAR_CELLS);
     return "█".repeat(filled) + "░".repeat(BAR_CELLS - filled);
 }
-/** Render the category rings + the weighted overall for the terminal. */
+/** Render the category rings (diagnostic) + the summed overall for the terminal. */
 function formatAuditScore(s) {
     const lines = ["Harness audit", ""];
     for (const c of s.categories) {
         const glyph = bandGlyph(c.score);
         const label = c.key.padEnd(13);
         const num = (c.score === null ? "n/a" : String(c.score)).padStart(4);
-        lines.push(`  ${glyph} ${label} ${num}  ${bar(c.score)}`);
+        const tag = c.advisory ? "  · advisory (not graded)" : "";
+        lines.push(`  ${glyph} ${label} ${num}  ${bar(c.score)}${tag}`);
         if (c.findings.length > 0) {
             lines.push(`       └ ${c.findings.join("; ")}`);
         }

package/dist/cli.js

@@ -1219,6 +1219,100 @@ function targetHasHash(absPath) {
  * target by `setupPillar1`. The full onboarding (both layers, deps, CI, plugin)
  * is `setup()`.
  */
+/** Classify an adoption target by its path: a `SKILL.md` is a skill, a file under
+ * an `agents/` dir is a subagent, everything else is an instruction file. Used to
+ * pick the right adopt function so `init --target=skills/x/SKILL.md` (the
+ * per-surface path the audit report points at) makes a `skill()`/`agent()` spec. */
+function surfaceKind(target) {
+    if (/^SKILL\.md$/i.test((0, node_path_1.basename)(target)))
+        return "skill";
+    if (/(^|[/\\])agents[/\\]/.test(target))
+        return "agent";
+    return "instruction";
+}
+function logAdoptedSurface(target, specPath, label, unmappedKeys) {
+    const note = unmappedKeys.length > 0
+        ? ` (review the // NOTE — unmapped frontmatter: ${unmappedKeys.join(", ")})`
+        : "";
+    console.log(`Adopted ${label} ${target} → ${specPath}${note}. ` +
+        `Run \`vigiles compile\` and review the diff.`);
+}
+/** Discover existing skill (`skills/<x>/SKILL.md`) and subagent (`agents/<x>.md`)
+ * surfaces — under the bare or `.claude/` roots — that don't yet have a spec, so
+ * bare `vigiles init` creates a spec for EVERY surface it can, not just the
+ * instruction file. Shallow (top-level only) so it never walks node_modules or a
+ * vendored plugin. CC paths are intentional here — `init` is the one composition
+ * point allowed to know them (see adapter-aware-lint-rules). */
+function discoverAdoptableSurfaces(cwd) {
+    const out = [];
+    const unspecced = (rel) => (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, rel)) &&
+        !(0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, `${rel}.spec.ts`));
+    for (const root of ["skills", ".claude/skills"]) {
+        const abs = (0, node_path_1.resolve)(cwd, root);
+        if (!(0, node_fs_1.existsSync)(abs))
+            continue;
+        for (const e of (0, node_fs_1.readdirSync)(abs, { withFileTypes: true })) {
+            const rel = `${root}/${e.name}/SKILL.md`;
+            if (e.isDirectory() && unspecced(rel))
+                out.push(rel);
+        }
+    }
+    for (const root of ["agents", ".claude/agents"]) {
+        const abs = (0, node_path_1.resolve)(cwd, root);
+        if (!(0, node_fs_1.existsSync)(abs))
+            continue;
+        for (const e of (0, node_fs_1.readdirSync)(abs, { withFileTypes: true })) {
+            const rel = `${root}/${e.name}`;
+            if (e.isFile() && e.name.endsWith(".md") && unspecced(rel))
+                out.push(rel);
+        }
+    }
+    return out;
+}
+/** The full adoptable-surface list `audit` reports: the instruction file (when it
+ * exists hand-written, no spec) PLUS every skill/subagent surface without a spec.
+ * Same notion `init` adopts; surfaced in the AuditReport + the terminal nudge so
+ * the report's "Create spec" / "Create all specs" affordances have their paths.
+ * Composition-root only — CC paths are intentional here (like discoverAdoptableSurfaces). */
+function discoverAdoptableForAudit(root, instructionFile) {
+    const out = [];
+    const instrAbs = (0, node_path_1.resolve)(root, instructionFile);
+    if ((0, node_fs_1.existsSync)(instrAbs) &&
+        !targetHasHash(instrAbs) &&
+        !(0, node_fs_1.existsSync)((0, node_path_1.resolve)(root, `${instructionFile}.spec.ts`))) {
+        out.push(instructionFile);
+    }
+    out.push(...discoverAdoptableSurfaces(root));
+    return out;
+}
+/** The terminal "adoptable surfaces" nudge — N un-spec'd surfaces + the create-all
+ * command and up to ~5 per-surface commands (then "+K more"). "" when nothing to
+ * adopt (a fully spec-managed repo says nothing). */
+function formatAdoptableNudge(surfaces) {
+    if (surfaces.length === 0)
+        return "";
+    const n = surfaces.length;
+    const lines = [
+        `ℹ ${String(n)} surface${n === 1 ? "" : "s"} not yet spec-managed — create specs with \`npx vigiles init\``,
+        `  (or one at a time: \`npx vigiles init --target=<path>\`)`,
+    ];
+    const shown = surfaces.slice(0, 5);
+    for (const s of shown)
+        lines.push(`    • npx vigiles init --target=${s}`);
+    const more = n - shown.length;
+    if (more > 0)
+        lines.push(`    • +${String(more)} more`);
+    return lines.join("\n");
+}
+/** A small, terse behavioral nudge — the deterministic read can't tell whether a
+ * skill actually FIRES. "" when there are no model-invocable skills. */
+function formatTriggerNudge(triggerableSkills) {
+    if (triggerableSkills <= 0)
+        return "";
+    const n = triggerableSkills;
+    return (`ℹ Do your ${String(n)} skill${n === 1 ? "" : "s"} actually fire? The deterministic read can't tell — ` +
+        `run \`audit\` interactively to measure, or test with \`measureTriggerRate\` (vigiles/testing).`);
+}
 function scaffoldSpec(args) {
     const targetFlag = args.find((a) => a.startsWith("--target="));
     const target = targetFlag ? targetFlag.split("=")[1] : "CLAUDE.md";
@@ -1237,11 +1331,24 @@ function scaffoldSpec(args) {
     const targetAbs = (0, node_path_1.resolve)(process.cwd(), target);
     if ((0, node_fs_1.existsSync)(targetAbs) && !targetHasHash(targetAbs)) {
         const md = (0, node_fs_1.readFileSync)(targetAbs, "utf-8");
-        const { source, tier, sectionCount } = (0, adopt_js_1.adoptMarkdown)(md, (0, node_path_1.basename)(target));
         (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(specAbs), { recursive: true });
-        (0, node_fs_1.writeFileSync)(specAbs, source);
-        console.log(`Adopted ${target} → ${specPath} (${tier}, ${String(sectionCount)} section${sectionCount === 1 ? "" : "s"}). ` +
-            `Run \`vigiles compile\` and review the diff; the \`/strengthen\` skill upgrades prose to verified rules.`);
+        const kind = surfaceKind(target);
+        if (kind === "skill") {
+            const { source, unmappedKeys } = (0, adopt_js_1.adoptSkill)(md, (0, node_path_1.basename)((0, node_path_1.dirname)(target)));
+            (0, node_fs_1.writeFileSync)(specAbs, source);
+            logAdoptedSurface(target, specPath, "skill", unmappedKeys);
+        }
+        else if (kind === "agent") {
+            const { source, unmappedKeys } = (0, adopt_js_1.adoptAgent)(md, (0, node_path_1.basename)(target, ".md"));
+            (0, node_fs_1.writeFileSync)(specAbs, source);
+            logAdoptedSurface(target, specPath, "subagent", unmappedKeys);
+        }
+        else {
+            const { source, tier, sectionCount } = (0, adopt_js_1.adoptMarkdown)(md, (0, node_path_1.basename)(target));
+            (0, node_fs_1.writeFileSync)(specAbs, source);
+            console.log(`Adopted ${target} → ${specPath} (${tier}, ${String(sectionCount)} section${sectionCount === 1 ? "" : "s"}). ` +
+                `Run \`vigiles compile\` and review the diff; the \`/strengthen\` skill upgrades prose to verified rules.`);
+        }
         return;
     }
     // The compiled output is derived from the spec FILE path; the spec's `target`
@@ -1768,9 +1875,15 @@ async function setupPillar1(detected, targetValue, harnesses) {
     // An explicit --target is honoured as-is; otherwise collapse a CLAUDE.md⇄
     // AGENTS.md mirror (symlink or synced) to one canonical spec, then redirect
     // into a sync tool's source slot when one would own the output.
-    const targets = targetValue
+    const instructionTargets = targetValue
         ? determineTargets(detected, targetValue, harnesses)
         : redirectSyncToolTargets(cwd, collapseMirroredTargets(determineTargets(detected, targetValue, harnesses), (0, compose_js_1.detectInstructionMirror)(cwd)));
+    // Bare `init` (no explicit --target) also adopts every existing skill +
+    // subagent surface — "create all the specs it can", not just the instruction
+    // file. An explicit --target stays scoped to that one surface.
+    const targets = targetValue
+        ? instructionTargets
+        : [...instructionTargets, ...discoverAdoptableSurfaces(cwd)];
     // Create specs. An existing hand-written target is faithfully ADOPTED into a
     // spec (scaffoldSpec() does the convert), not clobbered with a blank one — so the
     // compile below reproduces it (the user reviews the diff). A greenfield target
@@ -4383,9 +4496,15 @@ async function main() {
                 // HTML renders, `--json` emits, and (later) a hosted dashboard ingests.
                 // Built ONCE; the rings + fix list are read off it. Pure deterministic —
                 // nothing executes to produce it.
+                // Surfaces that exist but aren't spec-managed yet — the same notion
+                // `init` adopts (layout-driven instruction file + skill/subagent sweep).
+                // Surfaced in the AuditReport (the report's "Create spec" command-emit
+                // buttons read it) and the terminal nudge below.
+                const adoptableSurfaces = discoverAdoptableForAudit(root, adapter.layout.instructionFile);
                 const auditReport = (0, audit_report_js_1.buildAuditReport)(report, {
                     harness: adapter.name,
                     vigilesVersion: getVersion(),
+                    adoptableSurfaces,
                 });
                 const sc = auditReport.score;
                 const plan = (0, optimize_js_1.optimize)(report);
@@ -4404,6 +4523,18 @@ async function main() {
                     const fixes = (0, optimize_js_1.formatRecommendations)(plan);
                     if (fixes)
                         console.log("\n" + fixes);
+                    // Adoption nudge: surfaces that exist but aren't spec-managed yet, with
+                    // the create-all + per-surface `init` commands (the JSON carries the
+                    // data in `adoptable` instead — the terminal stays human-readable).
+                    const adoptNudge = formatAdoptableNudge(adoptableSurfaces);
+                    if (adoptNudge)
+                        console.log("\n" + adoptNudge);
+                    // A small behavioral nudge — the deterministic read can't tell whether
+                    // skills actually FIRE; point at the interactive measure + the API.
+                    const fireNudge = formatTriggerNudge(report.skills.filter((s) => s.hasDescription && !s.userInvoked)
+                        .length);
+                    if (fireNudge)
+                        console.log("\n" + fireNudge);
                 }
                 // ONE read-vs-run decision for the EXECUTING checks (live MCP + skill
                 // firing). A plain `audit` is a deterministic READ; these run only on

package/dist/core/adopt.d.ts

@@ -18,6 +18,7 @@
  * vs `enforce()` is deliberately NOT guessed here — that cross-referencing is
  * `strengthen`'s separate, later job; adoption is lossless transcription.
  */
+import { type SkillSpec, type AgentSpec } from "./spec.js";
 export type AdoptTier = "structured" | "raw";
 export interface AdoptResult {
     /** Generated `.spec.ts` source (compiles back to ~the original file). */
@@ -62,4 +63,31 @@ export declare function adoptToSpec(markdown: string, target: string): AdoptedSp
  * (the deliverable `init` writes).
  */
 export declare function adoptMarkdown(markdown: string, target: string): AdoptResult;
+export interface AdoptSurfaceResult {
+    /** Generated `.spec.ts` source. */
+    source: string;
+    kind: "skill" | "agent";
+    /**
+     * The parsed spec object the source builds — exposed so a round-trip test can
+     * feed it straight to `compileSkill`/`compileAgent` without evaluating the
+     * generated TS (the same split as `adoptToSpec`/`renderSpecSource`).
+     */
+    spec: SkillSpec | AgentSpec;
+    /**
+     * Frontmatter keys present in the source that the typed spec has no field for
+     * — emitted as a `// NOTE:` comment in the source so nothing is lost silently.
+     */
+    unmappedKeys: string[];
+}
+/**
+ * Adopt an existing SKILL.md into a `skill()` spec. The body is carried verbatim
+ * (skills are freeform markdown — `##` headings stay in the body), so a clean
+ * skill round-trips below the integrity header.
+ *
+ * @param markdown the SKILL.md content
+ * @param dirName  the skill's directory name — the CC fallback for `name` when
+ *   frontmatter omits it
+ */
+export declare function adoptSkill(markdown: string, dirName: string): AdoptSurfaceResult;
+export declare function adoptAgent(markdown: string, fileBase: string): AdoptSurfaceResult;
 //# sourceMappingURL=adopt.d.ts.map