@boopkit/cli 0.6.12 → 0.6.14

package/dist/lib/scaffold.js

@@ -37,10 +37,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.renderTemplate = renderTemplate;
+exports.getTemplatesDir = getTemplatesDir;
+exports.profileHasTemplates = profileHasTemplates;
 exports.scaffoldKernel = scaffoldKernel;
 exports.hashFile = hashFile;
+exports.hashContent = hashContent;
 exports.copyCapabilityFiles = copyCapabilityFiles;
 exports.linkSkillsToClaude = linkSkillsToClaude;
+exports.createSkillProjectFiles = createSkillProjectFiles;
+exports.hasOfferedRules = hasOfferedRules;
+exports.readSkillProjectTemplate = readSkillProjectTemplate;
 exports.getBoopkitVersion = getBoopkitVersion;
 exports.formatUnpinnedDependencyWarning = formatUnpinnedDependencyWarning;
 exports.mergePackageJson = mergePackageJson;
@@ -68,19 +74,33 @@ function renderTemplate(templateContent, variables) {
     const compiled = handlebars_1.default.compile(templateContent, { noEscape: true });
     return compiled(variables);
 }
+function getKernelTemplatesDir() {
+    return path.join((0, config_1.getBoopRoot)(), 'src', 'templates', 'kernel');
+}
 /**
- * Get the path to the kernel templates directory.
+ * Resolve the template directory `boop init` renders for a profile.
+ *
+ * A profile that ships its own `profiles/<name>/templates/` folder gets that
+ * folder, which must be complete on its own — nothing is merged from the kernel.
+ * Every other profile falls back to `src/templates/kernel/`. The fallback is
+ * what keeps `web-app`, which ships no templates/ folder, scaffolding exactly
+ * what it always has.
  */
-function getTemplatesDir() {
-    return path.join((0, config_1.getBoopRoot)(), 'src', 'templates', 'kernel');
+function getTemplatesDir(profileName) {
+    return profileHasTemplates(profileName) ? getProfileTemplatesDir(profileName) : getKernelTemplatesDir();
+}
+function profileHasTemplates(profileName) {
+    return fs.existsSync(getProfileTemplatesDir(profileName));
+}
+function getProfileTemplatesDir(profileName) {
+    return path.join((0, config_1.getBoopRoot)(), 'profiles', profileName, 'templates');
 }
 /**
- * Copy and render all kernel templates into a target directory.
- * Creates directories as needed. Does not overwrite existing files
- * unless overwrite is true.
+ * Copy and render every file in a templates directory (the kernel templates
+ * by default) into a target directory. Creates directories as needed. Does
+ * not overwrite existing files unless overwrite is true.
  */
-function scaffoldKernel(targetDir, variables, overwrite = false) {
-    const templatesDir = getTemplatesDir();
+function scaffoldKernel(targetDir, variables, overwrite = false, templatesDir = getKernelTemplatesDir()) {
     const written = [];
     function processDir(srcDir, destDir) {
         if (!fs.existsSync(destDir)) {
@@ -101,12 +121,13 @@ function scaffoldKernel(targetDir, variables, overwrite = false) {
                 if (!overwrite && fs.existsSync(destPath)) {
                     continue;
                 }
-                const content = fs.readFileSync(srcPath, 'utf-8');
-                // Only render .hbs files through Handlebars
-                const rendered = entry.name.endsWith('.hbs')
-                    ? renderTemplate(content, variables)
-                    : content;
-                fs.writeFileSync(destPath, rendered, 'utf-8');
+                // Only .hbs files are text by contract; anything else may be binary, so copy its bytes untouched
+                if (entry.name.endsWith('.hbs')) {
+                    fs.writeFileSync(destPath, renderTemplate(fs.readFileSync(srcPath, 'utf-8'), variables), 'utf-8');
+                }
+                else {
+                    fs.copyFileSync(srcPath, destPath);
+                }
                 written.push(path.relative(targetDir, destPath));
             }
         }
@@ -118,7 +139,13 @@ function scaffoldKernel(targetDir, variables, overwrite = false) {
  * Compute SHA-256 hash of a file's content.
  */
 function hashFile(filePath) {
-    const content = fs.readFileSync(filePath);
+    return hashContent(fs.readFileSync(filePath));
+}
+/**
+ * The hash `hashFile` records, for content that is not on disk — a past version
+ * read from git, or a file inside a downloaded package.
+ */
+function hashContent(content) {
     const hash = crypto.createHash('sha256').update(content).digest('hex');
     return `sha256:${hash}`;
 }
@@ -226,6 +253,60 @@ function linkSkillsToClaude(targetDir, only) {
     }
     return linked;
 }
+/**
+ * Give every skill folder under `<targetDir>/skills/` that lacks one a
+ * `PROJECT.md`, where the project records how it applies the skill. Each boop
+ * `SKILL.md` opens by pointing at it; the file being present is the backstop
+ * for an agent that skipped the pointer.
+ *
+ * The file is the project's: boop never hashes it, so `boop update` can never
+ * report it, and an existing one is never opened for writing.
+ *
+ * Returns the relative paths of the files created.
+ */
+function createSkillProjectFiles(targetDir) {
+    const skillsDir = path.join(targetDir, 'skills');
+    if (!fs.existsSync(skillsDir))
+        return [];
+    const template = readSkillProjectTemplate();
+    const created = [];
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        // A symlinked skill folder is someone else's. In the boop repository each one
+        // points into a capability package, from which a PROJECT.md would ship to every project.
+        if (!entry.isDirectory())
+            continue;
+        const filePath = path.join(skillsDir, entry.name, 'PROJECT.md');
+        if (fs.lstatSync(filePath, { throwIfNoEntry: false }))
+            continue;
+        fs.writeFileSync(filePath, template, { flag: 'wx' });
+        created.push(path.join('skills', entry.name, 'PROJECT.md'));
+    }
+    return created;
+}
+/**
+ * Whether a skill's PROJECT.md has rules under "Offered to boop" — anything in
+ * that section beyond the template's own explanation of it.
+ */
+function hasOfferedRules(projectFilePath) {
+    if (!fs.existsSync(projectFilePath))
+        return false;
+    const section = offeredToBoopSection(fs.readFileSync(projectFilePath, 'utf-8'));
+    if (section === null)
+        return false;
+    const explanation = new Set((offeredToBoopSection(readSkillProjectTemplate()) ?? '').split('\n').map(line => line.trim()));
+    return section.split('\n').some(line => line.trim() !== '' && !explanation.has(line.trim()));
+}
+function offeredToBoopSection(text) {
+    const heading = /^##[ \t]+Offered to boop[ \t]*$/m.exec(text);
+    if (!heading)
+        return null;
+    const rest = text.slice(heading.index + heading[0].length);
+    const nextHeading = rest.search(/^#{1,2}[ \t]/m);
+    return nextHeading === -1 ? rest : rest.slice(0, nextHeading);
+}
+function readSkillProjectTemplate() {
+    return fs.readFileSync(path.join((0, config_1.getBoopRoot)(), 'src', 'templates', 'skill-project', 'PROJECT.md'), 'utf-8');
+}
 /**
  * Copy capability files from the capabilities/ source tree (test fixtures only).
  */

package/dist/lib/skill-edits.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The mechanical half of splitting a drifted skill: find each skill whose
+ * SKILL.md the project edited, recover the text boop installed, list every
+ * edit, and write one plan per skill for an agent to decide. Nothing here
+ * decides where an edit belongs.
+ */
+import { FindOriginalTextOptions } from './original-text';
+import { BoopManifest } from './project';
+/** Where plans are written, relative to the project. Everything in `.boop/` but config.json is gitignored. */
+export declare const SKILL_EDITS_DIR: string;
+/** One continuous change between a base text and the project's copy, as line ranges. */
+export interface Edit {
+    /** Lines [baseStart, baseEnd) of the base text that the project replaced */
+    baseStart: number;
+    baseEnd: number;
+    /** Lines [projectStart, projectEnd) of the project's copy that replace them */
+    projectStart: number;
+    projectEnd: number;
+}
+/** A blank decision, for the agent following the triage skill to fill in. */
+export interface EditDecision {
+    /** keep | offer | drop */
+    decision: null;
+    /** For a kept edit: adds | narrows | overrides */
+    kind: null;
+    /** For a kept or offered edit: the edit rewritten as a rule that stands alone */
+    rule: null;
+    /** For a dropped edit: why */
+    reason: null;
+}
+export interface SkillEditPlanData {
+    skill: string;
+    capability: string;
+    path: string;
+    original: {
+        source: 'none';
+    } | ({
+        source: 'git';
+        commit: string;
+    }) | ({
+        source: 'npm';
+        package: string;
+        version: string;
+    });
+    /** True when the original could not be found, so every difference from boop's copy needs a decision */
+    comparedWithoutOriginal: boolean;
+    /** Whether boop has changed the skill since the project installed it; unknown without the original */
+    boopChanged: boolean | null;
+    /** As they were when the plan was written, so applying it can refuse a plan made for other text */
+    hashes: {
+        installed: string;
+        project: string;
+        boop: string;
+    };
+    decisions: Record<string, EditDecision>;
+}
+export type SkillEditOutcome = {
+    kind: 'written';
+    skill: string;
+    planPath: string;
+    edits: number;
+    boopChanged: boolean | null;
+    comparedWithoutOriginal: boolean;
+    replacedStale: boolean;
+} | {
+    kind: 'kept';
+    skill: string;
+    planPath: string;
+} | {
+    kind: 'hand-split';
+    skill: string;
+    relativePath: string;
+    upstreamPath?: string;
+};
+/**
+ * Find every skill edited in SKILL.md across the project's capabilities and
+ * write a plan for each to `.boop/skill-edits/<skill-name>.md`.
+ *
+ * A plan already written for the current project copy and boop copy is left
+ * alone, because it may hold decisions. One written for other text is backed
+ * up and rewritten. A skill boop has no stored hash for gets no plan.
+ */
+export declare function writeSkillEditPlans(projectDir: string, manifest: BoopManifest, options?: FindOriginalTextOptions): SkillEditOutcome[];
+/**
+ * The edits that turn `base` into `project`: each maximal run of lines that
+ * are not part of a longest common subsequence of the two.
+ */
+export declare function diffLines(base: string[], project: string[]): Edit[];

package/dist/lib/skill-edits.js

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * The mechanical half of splitting a drifted skill: find each skill whose
+ * SKILL.md the project edited, recover the text boop installed, list every
+ * edit, and write one plan per skill for an agent to decide. Nothing here
+ * decides where an edit belongs.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SKILL_EDITS_DIR = void 0;
+exports.writeSkillEditPlans = writeSkillEditPlans;
+exports.diffLines = diffLines;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
+const original_text_1 = require("./original-text");
+const safe_io_1 = require("./safe-io");
+const install_layout_1 = require("./install-layout");
+const update_1 = require("./update");
+/** Where plans are written, relative to the project. Everything in `.boop/` but config.json is gitignored. */
+exports.SKILL_EDITS_DIR = path.join('.boop', 'skill-edits');
+/**
+ * Find every skill edited in SKILL.md across the project's capabilities and
+ * write a plan for each to `.boop/skill-edits/<skill-name>.md`.
+ *
+ * A plan already written for the current project copy and boop copy is left
+ * alone, because it may hold decisions. One written for other text is backed
+ * up and rewritten. A skill boop has no stored hash for gets no plan.
+ */
+function writeSkillEditPlans(projectDir, manifest, options = {}) {
+    const outcomes = [];
+    for (const capability of manifest.capabilities) {
+        const plan = (0, update_1.planCapabilityUpdate)(projectDir, capability, manifest);
+        for (const action of plan?.actions ?? []) {
+            if (action.fileKind !== 'skill' || action.action !== 'skip')
+                continue;
+            const skill = path.basename(path.dirname(action.relativePath));
+            if (!action.storedHash) {
+                // Untracked; a copy identical to boop's holds nothing to split
+                if (action.currentHash && action.currentHash !== action.newHash) {
+                    outcomes.push({ kind: 'hand-split', skill, relativePath: action.relativePath, upstreamPath: action.upstreamPath });
+                }
+                continue;
+            }
+            if (action.drift !== 'project-only' && action.drift !== 'both-changed')
+                continue;
+            outcomes.push(writePlan(projectDir, capability, skill, action, plan.packageDir, options));
+        }
+    }
+    return outcomes;
+}
+function writePlan(projectDir, capability, skill, action, packageDir, options) {
+    const planRelPath = path.join(exports.SKILL_EDITS_DIR, `${skill}.md`);
+    const planPath = path.join(projectDir, planRelPath);
+    const hashes = { installed: action.storedHash, project: action.currentHash, boop: action.newHash };
+    const existing = readPlanHashes(planPath);
+    if (existing && existing.project === hashes.project && existing.boop === hashes.boop) {
+        return { kind: 'kept', skill, planPath: planRelPath };
+    }
+    const projectText = fs.readFileSync(path.join(projectDir, action.relativePath), 'utf-8');
+    const boopText = fs.readFileSync(boopCopyPath(packageDir, action.relativePath), 'utf-8');
+    const original = (0, original_text_1.findOriginalText)(projectDir, action.relativePath.split(path.sep).join('/'), hashes.installed, options);
+    const baseText = original.found ? original.content : boopText;
+    const baseLines = baseText.split('\n');
+    const projectLines = projectText.split('\n');
+    const edits = diffLines(baseLines, projectLines);
+    const boopChanged = original.found ? action.drift === 'both-changed' : null;
+    const data = {
+        skill,
+        capability,
+        path: action.relativePath.split(path.sep).join('/'),
+        original: original.found ? sourceFields(original.source) : { source: 'none' },
+        comparedWithoutOriginal: !original.found,
+        boopChanged,
+        hashes,
+        decisions: Object.fromEntries(edits.map((_, i) => [editId(i), { decision: null, kind: null, rule: null, reason: null }])),
+    };
+    const body = original.found
+        ? renderBody(data, edits, baseLines, projectLines, boopText.split('\n'))
+        : renderBody(data, edits, baseLines, projectLines, null);
+    fs.mkdirSync(path.dirname(planPath), { recursive: true });
+    const replacedStale = existing !== null;
+    if (replacedStale)
+        (0, safe_io_1.createBackup)(planPath);
+    fs.writeFileSync(planPath, gray_matter_1.default.stringify(body, data));
+    return {
+        kind: 'written',
+        skill,
+        planPath: planRelPath,
+        edits: edits.length,
+        boopChanged,
+        comparedWithoutOriginal: !original.found,
+        replacedStale,
+    };
+}
+/** The hashes an existing plan was written against, or null when there is no readable plan. */
+function readPlanHashes(planPath) {
+    if (!fs.existsSync(planPath))
+        return null;
+    try {
+        return (0, gray_matter_1.default)(fs.readFileSync(planPath, 'utf-8')).data.hashes ?? {};
+    }
+    catch {
+        return {};
+    }
+}
+function boopCopyPath(packageDir, relativePath) {
+    // planCapabilityUpdate hashed this file, so its placement exists
+    return (0, install_layout_1.capabilityPlacementsFromDir)(packageDir).find(p => p.dest === relativePath).source;
+}
+function sourceFields(source) {
+    return source.kind === 'git'
+        ? { source: 'git', commit: source.commit }
+        : { source: 'npm', package: source.package, version: source.version };
+}
+function editId(index) {
+    return `edit-${index + 1}`;
+}
+/**
+ * The edits that turn `base` into `project`: each maximal run of lines that
+ * are not part of a longest common subsequence of the two.
+ */
+function diffLines(base, project) {
+    const edits = [];
+    let baseAt = 0;
+    let projectAt = 0;
+    for (const [i, j] of [...matchLines(base, project), [base.length, project.length]]) {
+        if (i > baseAt || j > projectAt) {
+            edits.push({ baseStart: baseAt, baseEnd: i, projectStart: projectAt, projectEnd: j });
+        }
+        baseAt = i + 1;
+        projectAt = j + 1;
+    }
+    return edits;
+}
+/** Index pairs of the lines two texts share, in order: a longest common subsequence. */
+function matchLines(a, b) {
+    // Most edits leave long runs at both ends untouched, which keeps the table small
+    let prefix = 0;
+    while (prefix < a.length && prefix < b.length && a[prefix] === b[prefix])
+        prefix++;
+    let suffix = 0;
+    while (suffix < a.length - prefix && suffix < b.length - prefix && a[a.length - 1 - suffix] === b[b.length - 1 - suffix])
+        suffix++;
+    const n = a.length - prefix - suffix;
+    const m = b.length - prefix - suffix;
+    // lcs[x][y]: length of the common subsequence of a's middle from x and b's middle from y
+    const width = m + 1;
+    const lcs = new Uint32Array((n + 1) * (m + 1));
+    for (let x = n - 1; x >= 0; x--) {
+        for (let y = m - 1; y >= 0; y--) {
+            lcs[x * width + y] = a[prefix + x] === b[prefix + y]
+                ? lcs[(x + 1) * width + y + 1] + 1
+                : Math.max(lcs[(x + 1) * width + y], lcs[x * width + y + 1]);
+        }
+    }
+    const pairs = [];
+    for (let k = 0; k < prefix; k++)
+        pairs.push([k, k]);
+    let x = 0;
+    let y = 0;
+    while (x < n && y < m) {
+        if (a[prefix + x] === b[prefix + y]) {
+            pairs.push([prefix + x, prefix + y]);
+            x++;
+            y++;
+        }
+        else if (lcs[(x + 1) * width + y] >= lcs[x * width + y + 1]) {
+            x++;
+        }
+        else {
+            y++;
+        }
+    }
+    for (let k = suffix; k > 0; k--)
+        pairs.push([a.length - k, b.length - k]);
+    return pairs;
+}
+/**
+ * What boop now ships in place of base lines [start, end): the smallest
+ * region around them bounded on each side by a line boop kept, so a change
+ * boop made just beside an edit is shown with it.
+ */
+function boopRegion(matches, upstreamLength, baseLength, start, end) {
+    let before = [-1, -1];
+    let after = [baseLength, upstreamLength];
+    for (const pair of matches) {
+        if (pair[0] < start)
+            before = pair;
+        else if (pair[0] >= end) {
+            after = pair;
+            break;
+        }
+    }
+    return { baseStart: before[0] + 1, baseEnd: after[0], upstreamStart: before[1] + 1, upstreamEnd: after[1] };
+}
+function renderBody(data, edits, base, project, upstream) {
+    const baseLabel = upstream ? 'The text boop installed' : 'boop ships now';
+    const out = [
+        `# Edits to ${data.path}`,
+        '',
+        upstream
+            ? `This project's copy differs from the text boop installed in ${edits.length} place${edits.length === 1 ? '' : 's'}. ` +
+                `Each is shown below with boop's own changes to the same text, so you can see where boop has since covered an edit.`
+            : `boop could not find the text it installed, in this project's git history or in the published versions of its package, ` +
+                `so this plan compares the project's copy with what boop ships now. That comparison cannot tell this project's edits ` +
+                `from boop's own changes: every difference below needs a decision, including ones boop made.`,
+        '',
+        `Record a decision for every edit under \`decisions\` in the frontmatter, following the ${update_1.TRIAGE_SKILL} skill: ` +
+            '`keep` with a `rule` and a `kind` (`adds`, `narrows` or `overrides`), `offer` with a `rule`, or `drop` with a `reason`.',
+    ];
+    const upstreamMatches = upstream ? matchLines(base, upstream) : [];
+    edits.forEach((edit, index) => {
+        out.push('', `## ${editId(index)}`, '', locationLine(edit, base, baseLabel));
+        out.push('', `**${baseLabel}:**`, '', ...textBlock(base.slice(edit.baseStart, edit.baseEnd), 'this project added the text below'));
+        out.push('', "**This project's copy:**", '', ...textBlock(project.slice(edit.projectStart, edit.projectEnd), 'this project removed the text above'));
+        if (upstream) {
+            const region = boopRegion(upstreamMatches, upstream.length, base.length, edit.baseStart, edit.baseEnd);
+            const before = base.slice(region.baseStart, region.baseEnd);
+            const after = upstream.slice(region.upstreamStart, region.upstreamEnd);
+            out.push('', '**boop now ships:**', '');
+            if (before.join('\n') === after.join('\n')) {
+                out.push('_boop has not changed this text._');
+            }
+            else {
+                if (region.baseStart !== edit.baseStart || region.baseEnd !== edit.baseEnd) {
+                    out.push(`_boop's change reaches past this edit. This is what boop now ships in place of ${lineRange(region.baseStart, region.baseEnd)} of the installed text:_`, '');
+                }
+                out.push(...textBlock(after, 'boop removed this text'));
+            }
+        }
+    });
+    return out.join('\n') + '\n';
+}
+function locationLine(edit, base, baseLabel) {
+    const label = baseLabel.charAt(0).toLowerCase() + baseLabel.slice(1);
+    const where = edit.baseEnd > edit.baseStart
+        ? `${capitalize(lineRange(edit.baseStart, edit.baseEnd))} of ${label}.`
+        : edit.baseStart === 0 ? `At the start of ${label}.` : `After line ${edit.baseStart} of ${label}.`;
+    const preceding = base.slice(0, edit.baseStart).reverse().find(line => line.trim() !== '');
+    return preceding ? `${where} It follows:\n\n> ${preceding.trim()}` : where;
+}
+/** Lines [start, end), numbered from 1 */
+function lineRange(start, end) {
+    return end - start === 1 ? `line ${start + 1}` : `lines ${start + 1}–${end}`;
+}
+function capitalize(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}
+/** Lines in a code fence longer than any backtick run inside them, or a note when there are none. */
+function textBlock(lines, whenEmpty) {
+    if (lines.every(line => line === '')) {
+        return lines.length === 0 ? [`_(none: ${whenEmpty})_`] : ['_(blank lines only)_'];
+    }
+    const longestRun = Math.max(0, ...lines.flatMap(line => (line.match(/`+/g) ?? []).map(run => run.length)));
+    const fence = '`'.repeat(Math.max(3, longestRun + 1));
+    return [fence, ...lines, fence];
+}

package/dist/lib/update.d.ts

@@ -6,11 +6,17 @@
  */
 import { BoopManifest } from './project';
 export type FileState = 'match' | 'modified' | 'missing';
+/**
+ * How a locally modified file stands against the base (what boop shipped last)
+ * and upstream (what boop ships now). Only 'both-changed' is a conflict.
+ */
+export type Drift = 'project-only' | 'both-changed' | 'already-upstream';
+export type FileKind = 'skill' | 'reference' | 'code';
 export interface FileUpdateAction {
     /** Relative path from project root */
     relativePath: string;
     /** What will happen to this file */
-    action: 'overwrite' | 'skip' | 'add' | 'deprecate' | 'migrate';
+    action: 'overwrite' | 'skip' | 'add' | 'deprecate' | 'migrate' | 'record-hash';
     /** Why this action was chosen */
     reason: string;
     /** Stored hash from config */
@@ -19,8 +25,23 @@ export interface FileUpdateAction {
     currentHash?: string;
     /** New hash from package */
     newHash?: string;
-    /** For migrate actions: the old file path being replaced */
+    /** For migrate actions, and a folder file held back by an edited old one: the old file path being replaced */
     oldPath?: string;
+    /** For an edited old single-file skill: the skill folder that replaces it */
+    replacedBy?: string;
+    /** For a file whose hash differs from its stored base: how it stands against upstream */
+    drift?: Drift;
+    /** What sort of file this is, from its destination path */
+    fileKind?: FileKind;
+    /** What whoever ran the update should do about this file, when the report lists it */
+    instruction?: string;
+    /** boop's current copy of the file, when the instruction points at it */
+    upstreamPath?: string;
+}
+export interface FileInstruction {
+    relativePath: string;
+    instruction: string;
+    upstreamPath?: string;
 }
 export interface UpdatePlan {
     capability: string;
@@ -52,7 +73,13 @@ export interface UpdateResult {
     migrated: string[];
     /** Count of files unchanged in both package and locally */
     unchangedCount: number;
+    /** What to do about the files this update skipped or replaced, where the report says anything */
+    instructions: FileInstruction[];
 }
+/** The skill that splits a drifted SKILL.md — keep in step with the folder name boop-rm2l.8 gives it */
+export declare const TRIAGE_SKILL = "boop-skills-edit-triage";
+/** What to do about skills edited in SKILL.md, for a report that counts them */
+export declare const SKILL_EDITS_INSTRUCTION = "Move each skill's edits into the PROJECT.md beside it: run `boop migrate-skill-edits` and follow the boop-skills-edit-triage skill.";
 /**
  * Compare a file's current hash against a stored hash.
  */
@@ -71,6 +98,15 @@ export declare function executeUpdatePlan(plan: UpdatePlan, options?: {
     restore?: boolean;
     prune?: boolean;
 }): UpdateResult;
+/**
+ * Count the skills a capability's project copy has edited in SKILL.md, and how
+ * many of those boop has changed since — from the same comparison `boop update`
+ * makes. Null when there are none, or the capability has no package to compare with.
+ */
+export declare function countSkillEdits(targetDir: string, capabilityName: string, projectManifest: BoopManifest): {
+    edited: number;
+    changesWaiting: number;
+} | null;
 /**
  * Format an update result as a human-readable summary line.
  */