@compilr-dev/sdk 0.29.1 → 0.29.3

package/dist/mcp-config.d.ts

@@ -7,6 +7,8 @@
  * File structure:
  *   { "mcpServers": { "name": { command?, url?, ... } } }
  */
+import { type ConfigValue } from './mcp/secrets.js';
+export type { ConfigValue };
 /**
  * Single MCP server entry in the config file.
  * If `command` is present → stdio transport.
@@ -15,12 +17,28 @@
 export interface MCPServerEntry {
     command?: string;
     args?: string[];
-    env?: Record<string, string>;
+    /**
+     * Passed to the process on start.
+     *
+     * ⚠️ A VALUE MAY BE A REFERENCE, NOT A STRING. `{ secret: 'mcp:github:GITHUB_TOKEN' }` means the
+     * real value lives in the host's encrypted store and never in this file — see `src/mcp/secrets`.
+     * Resolve with {@link resolveServerEntry} before handing anything to a server.
+     */
+    env?: Record<string, ConfigValue>;
     cwd?: string;
     url?: string;
-    headers?: Record<string, string>;
+    /** Same reference rule as {@link MCPServerEntry.env}. */
+    headers?: Record<string, ConfigValue>;
     disabled?: boolean;
     timeout?: number;
+    /**
+     * Tools NOT described to the model, by the server's own name for them.
+     *
+     * ⚠️ AN OPT-OUT LIST, SO A SERVER THAT GAINS A TOOL HAS IT ON. An opt-in list would silently hide
+     * every tool added by a later release. Absent means all tools are on. The tools stay on the
+     * server either way — this only decides what reaches the model's context.
+     */
+    disabledTools?: string[];
 }
 /**
  * Shape of the mcp.json config file.
@@ -41,11 +59,52 @@ export interface ResolvedMCPServer {
     url?: string;
     headers?: Record<string, string>;
     timeout?: number;
+    /**
+     * Secret references that could not be resolved. Non-empty means DO NOT CONNECT — see
+     * {@link canConnect}. The variables are named so a host can say which one and where it lives.
+     */
+    missingSecrets?: {
+        variable: string;
+        ref: string;
+    }[];
 }
+/**
+ * The outcome of reading an mcp.json, with "absent" kept distinct from "unreadable".
+ *
+ * ⚠️ THOSE TWO CANNOT SHARE AN ANSWER. Collapsing them to `{}` is what made adding a server to a
+ * hand-edited file DELETE the servers already in it — see {@link assertWritable}.
+ */
+export interface MCPConfigRead {
+    servers: Record<string, MCPServerEntry>;
+    /** Present when the file exists but could not be parsed. The servers are then unknown, not none. */
+    error: string | null;
+    exists: boolean;
+}
+/**
+ * Read an mcp.json, saying which of the three things happened: absent, readable, or broken.
+ *
+ * Prefer this over {@link readMCPConfigFile} anywhere the result could lead to a WRITE.
+ */
+export declare function readMCPConfig(filePath: string): MCPConfigRead;
 /**
  * Read and parse an mcp.json file. Returns empty record on any error.
+ *
+ * ⚠️ LENIENT, AND ONLY SAFE FOR READING. It cannot tell an absent file from a broken one. Use
+ * {@link readMCPConfig} when the answer might be written back.
  */
 export declare function readMCPConfigFile(filePath: string): Record<string, MCPServerEntry>;
+/**
+ * Throw unless this file can be safely rewritten.
+ *
+ * ⚠️ THE DATA-LOSS BUG THIS EXISTS FOR, MEASURED. `readMCPConfigFile` returns `{}` for a file it
+ * cannot parse. `saveMCPServerEntry` then wrote `{}` plus the one new server — so a user whose
+ * mcp.json had a comment in it saw no servers in the app, added one, and **lost the other two**.
+ * Silence, then deletion.
+ *
+ * A file we cannot read is a file we must not overwrite. The host shows the reason and the user
+ * fixes their file; we do not guess at its contents.
+ */
+export declare function assertWritable(filePath: string): Record<string, MCPServerEntry>;
 /**
  * Write servers to an mcp.json file (creates directory if needed).
  */
@@ -53,8 +112,19 @@ export declare function writeMCPConfigFile(filePath: string, servers: Record<str
 /**
  * Convert an MCPServerEntry to a ResolvedMCPServer.
  * Returns null if the entry is invalid (neither command nor url) or disabled.
+ *
+ * ⚠️ SECRET REFERENCES NEED `lookup`. Without one, a referenced value cannot be resolved and is
+ * reported in `missingSecrets` — it is never substituted with an empty string, because that turns
+ * a configuration problem into a 401 three layers away that nobody can trace back.
+ */
+export declare function resolveServerEntry(name: string, entry: MCPServerEntry, lookup?: (ref: string) => string | null): ResolvedMCPServer | null;
+/**
+ * Can this server be started without handing it a credential we could not find?
+ *
+ * Hosts check this before connecting. Connecting anyway produces an authentication failure that
+ * looks like a bad token rather than a missing one.
  */
-export declare function resolveServerEntry(name: string, entry: MCPServerEntry): ResolvedMCPServer | null;
+export declare function canConnect(server: ResolvedMCPServer): boolean;
 /**
  * Load and resolve MCP servers from one or more config file paths.
  * Later paths override earlier ones (by server name).

package/dist/mcp-config.js

@@ -9,26 +9,76 @@
  */
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { dirname } from 'path';
-// =============================================================================
-// File I/O
-// =============================================================================
+import { resolveValues } from './mcp/secrets.js';
 /**
- * Read and parse an mcp.json file. Returns empty record on any error.
+ * Read an mcp.json, saying which of the three things happened: absent, readable, or broken.
+ *
+ * Prefer this over {@link readMCPConfigFile} anywhere the result could lead to a WRITE.
  */
-export function readMCPConfigFile(filePath) {
+export function readMCPConfig(filePath) {
+    if (!existsSync(filePath))
+        return { servers: {}, error: null, exists: false };
+    let data;
     try {
-        if (!existsSync(filePath))
-            return {};
-        const data = readFileSync(filePath, 'utf-8');
-        const parsed = JSON.parse(data);
-        if (parsed.mcpServers && typeof parsed.mcpServers === 'object') {
-            return parsed.mcpServers;
-        }
-        return {};
+        data = readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        return { servers: {}, exists: true, error: `could not be read: ${String(err)}` };
     }
-    catch {
-        return {};
+    /*
+      An empty or whitespace-only file is a normal state — an editor that saved nothing, or a file
+      someone cleared — and treating it as corrupt would block every future write.
+    */
+    if (data.trim() === '')
+        return { servers: {}, error: null, exists: true };
+    let parsed;
+    try {
+        parsed = JSON.parse(data);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        /*
+          Comments are the common cause and worth naming: mcp.json looks like a config file people may
+          annotate, and every editor that speaks JSONC encourages it. Strict JSON is what the format is,
+          so we refuse clearly instead of stripping them — stripping would drop them on the next write.
+        */
+        const hint = /^\s*\/\/|\n\s*\/\/|\/\*/.test(data)
+            ? ' It looks like it contains comments; mcp.json must be strict JSON.'
+            : '';
+        return { servers: {}, exists: true, error: `is not valid JSON (${detail}).${hint}` };
     }
+    if (!parsed.mcpServers || typeof parsed.mcpServers !== 'object') {
+        // A valid JSON document with no `mcpServers` key is empty, not broken.
+        return { servers: {}, error: null, exists: true };
+    }
+    return { servers: parsed.mcpServers, error: null, exists: true };
+}
+/**
+ * Read and parse an mcp.json file. Returns empty record on any error.
+ *
+ * ⚠️ LENIENT, AND ONLY SAFE FOR READING. It cannot tell an absent file from a broken one. Use
+ * {@link readMCPConfig} when the answer might be written back.
+ */
+export function readMCPConfigFile(filePath) {
+    return readMCPConfig(filePath).servers;
+}
+/**
+ * Throw unless this file can be safely rewritten.
+ *
+ * ⚠️ THE DATA-LOSS BUG THIS EXISTS FOR, MEASURED. `readMCPConfigFile` returns `{}` for a file it
+ * cannot parse. `saveMCPServerEntry` then wrote `{}` plus the one new server — so a user whose
+ * mcp.json had a comment in it saw no servers in the app, added one, and **lost the other two**.
+ * Silence, then deletion.
+ *
+ * A file we cannot read is a file we must not overwrite. The host shows the reason and the user
+ * fixes their file; we do not guess at its contents.
+ */
+export function assertWritable(filePath) {
+    const read = readMCPConfig(filePath);
+    if (read.error !== null) {
+        throw new Error(`${filePath} ${read.error} Refusing to write, because saving would replace servers that are still in the file. Fix the file and try again.`);
+    }
+    return read.servers;
 }
 /**
  * Write servers to an mcp.json file (creates directory if needed).
@@ -47,32 +97,49 @@ export function writeMCPConfigFile(filePath, servers) {
 /**
  * Convert an MCPServerEntry to a ResolvedMCPServer.
  * Returns null if the entry is invalid (neither command nor url) or disabled.
+ *
+ * ⚠️ SECRET REFERENCES NEED `lookup`. Without one, a referenced value cannot be resolved and is
+ * reported in `missingSecrets` — it is never substituted with an empty string, because that turns
+ * a configuration problem into a 401 three layers away that nobody can trace back.
  */
-export function resolveServerEntry(name, entry) {
+export function resolveServerEntry(name, entry, lookup = () => null) {
     if (entry.disabled)
         return null;
     if (entry.command) {
+        const env = resolveValues(entry.env, lookup);
         return {
             name,
             transport: 'stdio',
             command: entry.command,
             args: entry.args,
-            env: entry.env,
+            env: Object.keys(env.values).length > 0 ? env.values : undefined,
             cwd: entry.cwd,
             timeout: entry.timeout,
+            missingSecrets: env.missing,
         };
     }
     if (entry.url) {
+        const headers = resolveValues(entry.headers, lookup);
         return {
             name,
             transport: 'http',
             url: entry.url,
-            headers: entry.headers,
+            headers: Object.keys(headers.values).length > 0 ? headers.values : undefined,
             timeout: entry.timeout,
+            missingSecrets: headers.missing,
         };
     }
     return null;
 }
+/**
+ * Can this server be started without handing it a credential we could not find?
+ *
+ * Hosts check this before connecting. Connecting anyway produces an authentication failure that
+ * looks like a bad token rather than a missing one.
+ */
+export function canConnect(server) {
+    return (server.missingSecrets ?? []).length === 0;
+}
 // =============================================================================
 // High-level helpers
 // =============================================================================
@@ -98,7 +165,7 @@ export function loadMCPServers(...configPaths) {
  * Save a single MCP server entry to a config file (add or overwrite by name).
  */
 export function saveMCPServerEntry(filePath, name, entry) {
-    const servers = readMCPConfigFile(filePath);
+    const servers = assertWritable(filePath);
     servers[name] = entry;
     writeMCPConfigFile(filePath, servers);
 }
@@ -106,7 +173,7 @@ export function saveMCPServerEntry(filePath, name, entry) {
  * Delete a single MCP server entry from a config file.
  */
 export function deleteMCPServerEntry(filePath, name) {
-    const servers = readMCPConfigFile(filePath);
+    const servers = assertWritable(filePath);
     const { [name]: _, ...rest } = servers;
     writeMCPConfigFile(filePath, rest);
 }

package/dist/skills/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Platform Skills — barrel export
  */
-export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker } from './types.js';
+export type { CustomSkill, CompilrSkillExtension, ForkedFromMarker, InstalledFromMarker, } from './types.js';
 export { RESERVED_MACRO_NAMES, isReservedMacroName } from './types.js';
 export { parseSkillMarkdown, loadSkillsFromDir, loadInstalledSkills } from './loader.js';
 export type { SkillEligibilityContext } from './resolver.js';
@@ -26,4 +26,6 @@ export type { SkillReachability } from './reachability.js';
 export { patchSkillFrontmatter } from './patch.js';
 export type { FrontmatterPatch } from './patch.js';
 export { readSkillFolder, unreadSkillFiles } from './folder.js';
+export { findInstallableSkills, normaliseSkillName, resolveInstallName, planInstall, describeInstallPlan, buildInstalledFromPatch, } from './install.js';
+export type { InstallCandidate, InstallPlanItem } from './install.js';
 export type { SkillFolderEntry } from './folder.js';

package/dist/skills/index.js

@@ -12,3 +12,4 @@ export { buildMacroInvocation } from './macro-invocation.js';
 export { skillReachability, isUnreachable } from './reachability.js';
 export { patchSkillFrontmatter } from './patch.js';
 export { readSkillFolder, unreadSkillFiles } from './folder.js';
+export { findInstallableSkills, normaliseSkillName, resolveInstallName, planInstall, describeInstallPlan, buildInstalledFromPatch, } from './install.js';

package/dist/skills/install.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Installing a skill someone else wrote.
+ *
+ * ⚠️ COPY, NEVER LINK. Skills load from exactly two directories, so *where the folder sits is its
+ * scope*. A reference would have no scope and would break the moment the source moved. A copy also
+ * means the edits are the user's own — which is the whole point of installing rather than reading.
+ *
+ * ⚠️ NOTHING AUTO-UPDATES, and that is deliberate. A copy has no link home. We record where it came
+ * from so a host can *tell* the user the source changed; we never reach back and change their file.
+ *
+ * Everything here is planned before a single byte is written. A source may hold dozens of skills
+ * (anthropics/skills does), two of them may want the same name, and a name may already be taken in
+ * the destination — the user sees every one of those resolutions *in advance*, as a name they can
+ * read, with the option to cancel. Silent resolution is the failure this module exists to avoid.
+ */
+import type { FrontmatterPatch } from './patch.js';
+import type { InstalledFromMarker } from './types.js';
+export interface InstallCandidate {
+    /** Folder name at the source. Not necessarily a legal skill name. */
+    folderName: string;
+    /** Absolute path of the folder holding SKILL.md. */
+    sourceDir: string;
+    /** From the file, so the selection list reads like the catalogue it will join. */
+    name: string;
+    description: string;
+    bodyLines: number;
+    /** Files beyond SKILL.md that will be copied along. */
+    extraFiles: number;
+    /**
+     * ⚠️ WE READ FRONTMATTER AND BODY ONLY. A skill that points at `references/` half-works and says
+     * nothing about it, so the count travels with the candidate and the host can warn before the copy
+     * rather than leaving it to a confused agent.
+     */
+    unreadFiles: number;
+}
+/**
+ * Every installable skill under `root`, depth-first to `maxDepth`.
+ *
+ * A folder holding SKILL.md IS a skill, so we never descend into one — its `references/` cannot
+ * contain skills, and a nested SKILL.md there would be part of the parent, not a sibling.
+ *
+ * Unreadable or unparseable folders are skipped rather than thrown: a source directory is someone
+ * else's, and one bad file must not make the other forty uninstallable.
+ */
+export declare function findInstallableSkills(root: string, maxDepth?: number): InstallCandidate[];
+/**
+ * A folder name turned into a legal skill name: lowercase, digits and hyphens, starting with a
+ * letter. Returns null when nothing legal survives, because inventing a name for someone else's
+ * skill is worse than refusing it.
+ */
+export declare function normaliseSkillName(folderName: string): string | null;
+/**
+ * The name this skill will actually land as, given what is already there.
+ *
+ * `pdf` when free, otherwise `pdf-2`, `pdf-3`… The suffix is plain and always appended, so the
+ * result is predictable from the inputs — and it is shown to the user before anything is written,
+ * which is what makes an ugly-but-honest name better than a clever one.
+ */
+export declare function resolveInstallName(desired: string, taken: Iterable<string>): string;
+export interface InstallPlanItem {
+    candidate: InstallCandidate;
+    /** The folder name it will be written as. */
+    finalName: string;
+    /** Set when the source folder name was not a legal skill name. */
+    renamedFrom: string | null;
+    /** Set when `finalName` differs from the wanted name because something already holds it. */
+    collidedWith: string | null;
+    /** Why it cannot be installed at all. When set, nothing about this item is written. */
+    blocked: string | null;
+    /** The built-in name it would have shadowed, which is why it was renamed. */
+    shadowedBuiltin: string | null;
+}
+/**
+ * What installing this selection would do, resolved in full before anything is written.
+ *
+ * ⚠️ COLLISIONS ACCUMULATE WITHIN THE BATCH. Two sources both called `pdf` collide with each other,
+ * not just with the destination — so each resolved name joins the taken set as it is decided.
+ * Getting this wrong means the second copy silently overwrites the first.
+ */
+export declare function planInstall(candidates: InstallCandidate[], existingNames: Iterable<string>): InstallPlanItem[];
+/**
+ * One sentence per resolution, for showing the user before they commit.
+ *
+ * Returns [] when nothing needs saying — which is the common case, and must not render as an empty
+ * warning box.
+ */
+export declare function describeInstallPlan(plan: InstallPlanItem[]): string[];
+/**
+ * The frontmatter edit that records where a skill came from.
+ *
+ * ⚠️ A PATCH, NOT A REWRITE (D-2). This runs on a file someone else wrote — their comments, key
+ * order and fields we have never modelled all have to survive being installed, or we have silently
+ * edited a stranger's skill on its way in.
+ */
+export declare function buildInstalledFromPatch(marker: InstalledFromMarker): FrontmatterPatch;

package/dist/skills/install.js

@@ -0,0 +1,214 @@
+/**
+ * Installing a skill someone else wrote.
+ *
+ * ⚠️ COPY, NEVER LINK. Skills load from exactly two directories, so *where the folder sits is its
+ * scope*. A reference would have no scope and would break the moment the source moved. A copy also
+ * means the edits are the user's own — which is the whole point of installing rather than reading.
+ *
+ * ⚠️ NOTHING AUTO-UPDATES, and that is deliberate. A copy has no link home. We record where it came
+ * from so a host can *tell* the user the source changed; we never reach back and change their file.
+ *
+ * Everything here is planned before a single byte is written. A source may hold dozens of skills
+ * (anthropics/skills does), two of them may want the same name, and a name may already be taken in
+ * the destination — the user sees every one of those resolutions *in advance*, as a name they can
+ * read, with the option to cancel. Silent resolution is the failure this module exists to avoid.
+ */
+import { readdirSync, statSync, readFileSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { isValidSkillName } from './paths.js';
+import { isReservedMacroName } from './types.js';
+import { parseSkillMarkdown } from './loader.js';
+import { readSkillFolder } from './folder.js';
+const SKIP_DIRS = new Set(['node_modules', '.git', '.github', 'dist', 'build', '__pycache__']);
+/**
+ * Every installable skill under `root`, depth-first to `maxDepth`.
+ *
+ * A folder holding SKILL.md IS a skill, so we never descend into one — its `references/` cannot
+ * contain skills, and a nested SKILL.md there would be part of the parent, not a sibling.
+ *
+ * Unreadable or unparseable folders are skipped rather than thrown: a source directory is someone
+ * else's, and one bad file must not make the other forty uninstallable.
+ */
+export function findInstallableSkills(root, maxDepth = 3) {
+    const out = [];
+    const visit = (dir, depth) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        if (entries.includes('SKILL.md')) {
+            const candidate = describeCandidate(dir);
+            if (candidate)
+                out.push(candidate);
+            return; // a skill is a leaf
+        }
+        if (depth >= maxDepth)
+            return;
+        for (const name of entries.sort()) {
+            if (SKIP_DIRS.has(name) || name.startsWith('.'))
+                continue;
+            try {
+                if (statSync(join(dir, name)).isDirectory())
+                    visit(join(dir, name), depth + 1);
+            }
+            catch {
+                /* unreadable entry — skip it, not the whole source */
+            }
+        }
+    };
+    visit(root, 0);
+    return out;
+}
+function describeCandidate(dir) {
+    let content;
+    try {
+        content = readFileSync(join(dir, 'SKILL.md'), 'utf-8');
+    }
+    catch {
+        return null;
+    }
+    const parsed = parseSkillMarkdown(content, dir);
+    if (!parsed)
+        return null;
+    const body = parsed.prompt.trim();
+    return {
+        folderName: basename(dir),
+        sourceDir: dir,
+        name: parsed.name,
+        description: parsed.description,
+        bodyLines: body === '' ? 0 : body.split('\n').length,
+        extraFiles: readSkillFolder(dir).length,
+        unreadFiles: readSkillFolder(dir).filter((f) => f.kind === 'reference' || f.kind === 'script')
+            .length,
+    };
+}
+/**
+ * A folder name turned into a legal skill name: lowercase, digits and hyphens, starting with a
+ * letter. Returns null when nothing legal survives, because inventing a name for someone else's
+ * skill is worse than refusing it.
+ */
+export function normaliseSkillName(folderName) {
+    const slug = folderName
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64)
+        .replace(/-+$/, '');
+    return isValidSkillName(slug) ? slug : null;
+}
+/**
+ * The name this skill will actually land as, given what is already there.
+ *
+ * `pdf` when free, otherwise `pdf-2`, `pdf-3`… The suffix is plain and always appended, so the
+ * result is predictable from the inputs — and it is shown to the user before anything is written,
+ * which is what makes an ugly-but-honest name better than a clever one.
+ */
+export function resolveInstallName(desired, taken) {
+    const used = new Set(taken);
+    if (!used.has(desired))
+        return desired;
+    for (let n = 2; n < 1000; n++) {
+        const next = `${desired}-${String(n)}`;
+        if (!used.has(next))
+            return next;
+    }
+    return `${desired}-${String(Date.now())}`;
+}
+/**
+ * What installing this selection would do, resolved in full before anything is written.
+ *
+ * ⚠️ COLLISIONS ACCUMULATE WITHIN THE BATCH. Two sources both called `pdf` collide with each other,
+ * not just with the destination — so each resolved name joins the taken set as it is decided.
+ * Getting this wrong means the second copy silently overwrites the first.
+ */
+export function planInstall(candidates, existingNames) {
+    const taken = new Set(existingNames);
+    return candidates.map((candidate) => {
+        const wanted = normaliseSkillName(candidate.folderName);
+        if (wanted === null) {
+            return {
+                candidate,
+                finalName: candidate.folderName,
+                renamedFrom: null,
+                collidedWith: null,
+                blocked: `"${candidate.folderName}" cannot become a skill name — rename the folder and try again.`,
+                shadowedBuiltin: null,
+            };
+        }
+        /*
+          ⚠️ A RESERVED NAME IS NOT A FREE NAME. Project and user scope outrank `sdk` in
+          resolveSkillPrompt, so installing someone's `design` would silently become /design in both
+          hosts and the collision detector would stay quiet — the same defect `skills:create` already
+          refuses. Renaming rather than blocking: the user still gets the skill, it just cannot
+          impersonate a built-in.
+        */
+        if (isReservedMacroName(wanted)) {
+            const renamed = resolveInstallName(`${wanted}-installed`, taken);
+            taken.add(renamed);
+            return {
+                candidate,
+                finalName: renamed,
+                renamedFrom: candidate.folderName === renamed ? null : candidate.folderName,
+                collidedWith: wanted,
+                blocked: null,
+                shadowedBuiltin: wanted,
+            };
+        }
+        const finalName = resolveInstallName(wanted, taken);
+        taken.add(finalName);
+        return {
+            candidate,
+            finalName,
+            renamedFrom: wanted === candidate.folderName ? null : candidate.folderName,
+            collidedWith: finalName === wanted ? null : wanted,
+            blocked: null,
+            shadowedBuiltin: null,
+        };
+    });
+}
+/**
+ * One sentence per resolution, for showing the user before they commit.
+ *
+ * Returns [] when nothing needs saying — which is the common case, and must not render as an empty
+ * warning box.
+ */
+export function describeInstallPlan(plan) {
+    const out = [];
+    for (const item of plan) {
+        if (item.blocked) {
+            out.push(item.blocked);
+        }
+        else if (item.shadowedBuiltin) {
+            out.push(`${item.shadowedBuiltin} is a built-in — installing it under that name would silently replace it everywhere, so this will land as ${item.finalName}.`);
+        }
+        else if (item.collidedWith && item.renamedFrom) {
+            out.push(`"${item.renamedFrom}" is not a legal skill name and ${item.collidedWith} is already here — it will land as ${item.finalName}.`);
+        }
+        else if (item.collidedWith) {
+            out.push(`A skill called ${item.collidedWith} already exists here — this will land as ${item.finalName}.`);
+        }
+        else if (item.renamedFrom) {
+            out.push(`"${item.renamedFrom}" is not a legal skill name — it will land as ${item.finalName}.`);
+        }
+    }
+    return out;
+}
+/**
+ * The frontmatter edit that records where a skill came from.
+ *
+ * ⚠️ A PATCH, NOT A REWRITE (D-2). This runs on a file someone else wrote — their comments, key
+ * order and fields we have never modelled all have to survive being installed, or we have silently
+ * edited a stranger's skill on its way in.
+ */
+export function buildInstalledFromPatch(marker) {
+    return {
+        installedFrom: {
+            source: marker.source,
+            skill: marker.skill,
+            installedAt: marker.installedAt,
+        },
+    };
+}

package/dist/skills/loader.js

@@ -93,6 +93,9 @@ export function parseSkillMarkdown(content, sourcePath, source) {
     if (meta['forkedFrom'] && typeof meta['forkedFrom'] === 'object') {
         skill.forkedFrom = meta['forkedFrom'];
     }
+    if (meta['installedFrom'] && typeof meta['installedFrom'] === 'object') {
+        skill.installedFrom = meta['installedFrom'];
+    }
     return skill;
 }
 /**

package/dist/skills/patch.d.ts

@@ -14,8 +14,19 @@
  *
  * Decision D-2: project-docs/.../compilr-dev-skills/implementation-plan.md
  */
-/** `undefined` leaves a key alone; `null` removes it; anything else sets it. */
-export type FrontmatterPatch = Record<string, string | number | boolean | null | undefined>;
+/**
+ * `undefined` leaves a key alone; `null` removes it; anything else sets it.
+ *
+ * A plain object becomes a nested block — the shape `forkedFrom` already has on disk:
+ *
+ *     installedFrom:
+ *       source: "/home/me/skills"
+ *       skill: "pdf"
+ *
+ * ⚠️ NOT A ONE-LINE FLOW MAPPING. `{ a: 1 }` passed as a string would sail past the 80-character
+ * threshold below, come back out as a block scalar, and parse as a STRING that reads like a map.
+ */
+export type FrontmatterPatch = Record<string, string | number | boolean | Record<string, string> | null | undefined>;
 /**
  * Apply `patch` to `content`'s frontmatter, leaving everything else byte-identical.
  *

package/dist/skills/patch.js

@@ -51,7 +51,17 @@ function keyBlockEnd(lines, start) {
         end--;
     return end;
 }
+/** YAML double-quoted scalar. Quoted always, so a value starting with `/` or `{` stays a string. */
+function quote(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
 function render(key, value) {
+    if (typeof value === 'object') {
+        const body = Object.entries(value)
+            .map(([k, v]) => `  ${k}: ${quote(v)}`)
+            .join('\n');
+        return body === '' ? `${key}: {}` : `${key}:\n${body}`;
+    }
     if (typeof value === 'string' && (value.includes('\n') || value.length > 80)) {
         const body = value
             .split('\n')