@boopkit/cli 0.6.9 → 0.6.10

package/README.md

@@ -67,7 +67,7 @@ Capabilities can declare `requires` relationships (e.g. `users-and-accounts` req
 
 ## Profiles
 
-A profile is where a project starts. Today there's one; more will follow as the common shapes of AI-first products become clearer.
+A profile names a set of capabilities. Two ship today.
 
 ### `web-app`
 
@@ -75,6 +75,16 @@ Full-stack web application — Express + Handlebars + Tailwind CSS + PostgreSQL
 
 Ships with application capabilities (`web`, `api`, `services`, `database`), development skills (`coding`, `testing`, `project-mgmt`, `product-design`, `skills`, `workflows`), and the `hello` demo capability.
 
+This is the profile `boop init` scaffolds from — it carries a kernel, so there is an application to write.
+
+### `development`
+
+The development capabilities on their own (`coding`, `testing`, `project-mgmt`, `product-design`, `skills`, `workflows`) — no web layer, no API layer, no database.
+
+For a project with no application domain boop has anything to say about: a CLI, a library, a data pipeline. Those share no application layers at all, but they are developed the same way.
+
+It carries no kernel — no runtime, no port, no deploy target — so there is nothing for `boop init` to scaffold and `boop init --profile development` is refused. Use it by naming it as the `profile` in an existing project's `.boop/config.json`, or reach for `boop add` on the capabilities you want. Boop's own repository is the first project to declare it.
+
 List profiles with `boop list profiles`.
 
 ## Available Capabilities
@@ -119,10 +129,10 @@ Adding a capability installs its skills into your project's `skills/` directory.
 - **`coding`** — boop-coding-beads-flow, boop-coding-development, boop-coding-commit-changes, boop-coding-review-changes, boop-coding-debugging
 - **`product-design`** — boop-product-design-engineering-design, boop-product-design-feature-documentation, boop-product-design-feature-requirements, boop-product-design-reference-integration, boop-product-design-thought-partnership, boop-writing-technical-prose, boop-writing-documents, boop-writing-semantic-line-breaks
 - **`project-mgmt`** — boop-project-mgmt-beads-planning, boop-project-mgmt-engineering-planning
-- **`skills`** — boop-skill-authoring, boop-skills-discovery, boop-skills-agent-surface-design, boop-get-smart, boop-so-what
+- **`skills`** — boop-skill-authoring, boop-skills-discovery, boop-skills-agent-surface-design, boop-get-smart, boop-so-what, boop-skills-hyperlinking
 - **`testing`** — boop-testing-tdd-light, boop-testing-testing-express-web, boop-testing-testing
 - **`ux`** — boop-ux-purpose-judgement, boop-ux-visual-judgement, boop-ux-eval-and-refine-workflow, boop-ux-app-ui-dev-workflow
-- **`workflows`** — boop-feature-dev-workflow, boop-light-dev-workflow, boop-refactor-dev-workflow, boop-test-audit-workflow, boop-architecture-audit-workflow, boop-issue-sweep-workflow, boop-website-dev-workflow, boop-design-handoff-workflow, boop-knowledge-backfill
+- **`workflows`** — boop-feature-dev-workflow, boop-light-dev-workflow, boop-refactor-dev-workflow, boop-test-audit-workflow, boop-architecture-audit-workflow, boop-issue-sweep-workflow, boop-website-dev-workflow, boop-design-handoff-workflow, boop-knowledge-backfill, boop-stray-disposition
 
 **Application capabilities**
 

package/dist/capability-versions.json

@@ -1,21 +1,21 @@
 {
-  "@boopkit/cap-api": "0.4.2",
+  "@boopkit/cap-api": "0.4.4",
   "@boopkit/cap-background-jobs": "0.4.2",
   "@boopkit/cap-cloud-storage": "0.4.0",
   "@boopkit/cap-coding": "0.4.4",
   "@boopkit/cap-database": "0.4.3",
   "@boopkit/cap-email": "0.4.2",
-  "@boopkit/cap-hello": "0.4.0",
-  "@boopkit/cap-noticeboard": "0.4.0",
-  "@boopkit/cap-oauth-client": "0.1.0",
+  "@boopkit/cap-hello": "0.4.1",
+  "@boopkit/cap-noticeboard": "0.4.1",
+  "@boopkit/cap-oauth-client": "0.1.1",
   "@boopkit/cap-product-design": "0.6.7",
-  "@boopkit/cap-project-mgmt": "0.4.5",
+  "@boopkit/cap-project-mgmt": "0.4.9",
   "@boopkit/cap-services": "0.4.2",
-  "@boopkit/cap-skills": "0.5.3",
-  "@boopkit/cap-testing": "0.5.3",
-  "@boopkit/cap-users": "0.4.4",
+  "@boopkit/cap-skills": "0.5.4",
+  "@boopkit/cap-testing": "0.5.6",
+  "@boopkit/cap-users": "0.6.0",
   "@boopkit/cap-ux": "0.2.2",
-  "@boopkit/cap-web": "0.5.3",
-  "@boopkit/cap-workflows": "0.1.0",
+  "@boopkit/cap-web": "0.5.4",
+  "@boopkit/cap-workflows": "0.2.0",
   "@boopkit/logger": "0.4.0"
 }

package/dist/cli.js

@@ -91,6 +91,7 @@ program
     .option('--prune', 'Remove deprecated scaffold files from disk (creates .bak backup)')
     .option('--skip-npm', 'Skip npm update (only re-scaffold from installed versions)')
     .option('--tag <tag>', 'Use a specific npm dist-tag instead of major-version pinning (e.g. beta)')
+    .option('--fix-scripts', 'Rewrite package.json scripts that contradict shipped runner settings')
     .option('--json', 'Output structured JSON')
     .action(update_1.runUpdate);
 program

package/dist/commands/init.js

@@ -71,8 +71,21 @@ function runInit(name, options) {
         process.exitCode = 1;
         return;
     }
+    // --- Guard: a profile with no kernel has no application to scaffold ---
+    // `boop init` exists to write a running project from kernel templates. A
+    // profile that names only development capabilities (profiles/development/)
+    // has no runtime, port or deploy target to render them with, so refuse here
+    // rather than emit a project that cannot start.
+    if (!profile.kernel) {
+        console.error(`Error: Profile "${profileName}" carries no kernel, so there is nothing to scaffold.`);
+        console.error('It declares capabilities for a project that already exists: name it as the "profile" in that');
+        console.error(`project's .boop/config.json, or run \`boop add\` for the capabilities you want.`);
+        process.exitCode = 1;
+        return;
+    }
+    const kernel = profile.kernel;
     // --- Node version check ---
-    const requiredNodeVersion = profile.kernel.nodeVersion;
+    const requiredNodeVersion = kernel.nodeVersion;
     if (requiredNodeVersion && !process.env.BOOP_SKIP_VERSION_CHECK) {
         const minVersion = requiredNodeVersion.replace(/^[>=^~]+/, '');
         const currentMajor = parseInt(process.versions.node.split('.')[0], 10);
@@ -126,14 +139,14 @@ function runInit(name, options) {
     // --- Scaffold kernel ---
     const variables = {
         projectName: name,
-        port: profile.kernel.port,
-        scripts: profile.kernel.scripts,
-        nodeVersion: profile.kernel.nodeVersion ?? '>=18.0.0',
+        port: kernel.port,
+        scripts: kernel.scripts,
+        nodeVersion: kernel.nodeVersion ?? '>=18.0.0',
         ...hookVars,
     };
     const kernelFiles = (0, scaffold_1.scaffoldKernel)(targetDir, variables);
     // --- Merge kernel dependencies ---
-    (0, scaffold_1.mergePackageJson)(targetDir, profile.kernel.dependencies, profile.kernel.devDependencies, undefined, { skipBackup: true });
+    (0, scaffold_1.mergePackageJson)(targetDir, kernel.dependencies, kernel.devDependencies, undefined, { skipBackup: true });
     // --- Create minimal manifest so capability hash storage can find config.json ---
     (0, project_1.writeProjectManifest)(targetDir, {
         name,
@@ -183,7 +196,7 @@ function runInit(name, options) {
         (0, scaffold_1.scaffoldKernel)(targetDir, variables, true);
         // Re-scaffolding overwrites package.json (template has empty deps),
         // so re-merge kernel deps + cap package deps that were added earlier.
-        (0, scaffold_1.mergePackageJson)(targetDir, profile.kernel.dependencies, profile.kernel.devDependencies, undefined, { skipBackup: true });
+        (0, scaffold_1.mergePackageJson)(targetDir, kernel.dependencies, kernel.devDependencies, undefined, { skipBackup: true });
         (0, scaffold_1.mergePackageJson)(targetDir, undefined, undefined, capDeps, { skipBackup: true });
     }
     // Post-install conflict check (when preflight was deferred)

package/dist/commands/list.js

@@ -35,7 +35,11 @@ function listProfilesCommand() {
     for (const p of profiles) {
         console.log(`  ${p.name}`);
         console.log(`    ${p.description}`);
-        console.log(`    runtime: ${p.kernel.runtime} | deploy: ${p.kernel.deploy} | port: ${p.kernel.port}`);
+        // A profile with no application domain carries no kernel, so there is no
+        // runtime line to print for it.
+        if (p.kernel) {
+            console.log(`    runtime: ${p.kernel.runtime} | deploy: ${p.kernel.deploy} | port: ${p.kernel.port}`);
+        }
         const grouped = new Map();
         for (const capName of p.defaultCapabilities) {
             const cap = (0, capability_1.getCapability)(capName);

package/dist/commands/update.d.ts

@@ -6,5 +6,6 @@ export interface UpdateOptions {
     json?: boolean;
     skipNpm?: boolean;
     tag?: string;
+    fixScripts?: boolean;
 }
 export declare function runUpdate(capabilityName: string | undefined, options: UpdateOptions): void;

package/dist/commands/update.js

@@ -41,6 +41,7 @@ const project_1 = require("../lib/project");
 const capability_1 = require("../lib/capability");
 const update_1 = require("../lib/update");
 const scaffold_1 = require("../lib/scaffold");
+const stale_scripts_1 = require("../lib/stale-scripts");
 function runUpdate(capabilityName, options) {
     const targetDir = process.cwd();
     // Must be in a boop project
@@ -95,8 +96,9 @@ function runUpdate(capabilityName, options) {
     }
     // Dry run: show plans and exit
     if (options.dryRun) {
+        const stale = detectStaleScripts(targetDir);
         if (options.json) {
-            console.log(JSON.stringify({ capabilities: plans }, null, 2));
+            console.log(JSON.stringify({ capabilities: plans, staleScripts: stale }, null, 2));
             return;
         }
         for (const plan of plans) {
@@ -114,6 +116,9 @@ function runUpdate(capabilityName, options) {
                 console.log(`  ${icon} ${action.relativePath} — ${action.reason}`);
             }
         }
+        if (stale.length > 0) {
+            console.log(`\n${(0, stale_scripts_1.formatStaleScriptWarning)(stale)}`);
+        }
         return;
     }
     // Execute updates
@@ -141,9 +146,21 @@ function runUpdate(capabilityName, options) {
     if (!options.dryRun) {
         (0, scaffold_1.linkSkillsToClaude)(targetDir);
     }
+    // A script that contradicts the settings a capability now ships survives the
+    // update, because scripts are only merged when absent. Say so, or fix it on
+    // request. See lib/stale-scripts.ts for why this is a warning and not a prompt.
+    const stale = detectStaleScripts(targetDir);
+    const fixedScripts = options.fixScripts ? (0, stale_scripts_1.rewriteStaleRunnerScripts)(targetDir, stale) : [];
+    const remainingStale = options.fixScripts
+        ? stale.filter((f) => !fixedScripts.some((a) => a.name === f.name))
+        : stale;
     // Output
     if (options.json) {
-        console.log(JSON.stringify({ capabilities: results }, null, 2));
+        console.log(JSON.stringify({
+            capabilities: results,
+            staleScripts: remainingStale,
+            fixedScripts,
+        }, null, 2));
         return;
     }
     console.log(`\n${'─'.repeat(40)}`);
@@ -182,6 +199,29 @@ function runUpdate(capabilityName, options) {
             }
         }
     }
+    for (const fixed of fixedScripts) {
+        console.log(`\n\x1b[32m✓\x1b[0m package.json script "${fixed.name}" rewritten: ${fixed.command} → ${fixed.rewritten}`);
+    }
+    if (remainingStale.length > 0) {
+        console.log(`\n${(0, stale_scripts_1.formatStaleScriptWarning)(remainingStale)}`);
+    }
+}
+/**
+ * Read the project's package.json scripts and return those that contradict the
+ * runner settings the capabilities now ship. Missing or unreadable package.json
+ * is not an error here — this check is advisory and must never fail an update.
+ */
+function detectStaleScripts(targetDir) {
+    const pkgPath = path.join(targetDir, 'package.json');
+    if (!fs.existsSync(pkgPath))
+        return [];
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        return (0, stale_scripts_1.findStaleRunnerScripts)(pkg.scripts);
+    }
+    catch {
+        return [];
+    }
 }
 /**
  * Diagnose why no update plans were generated and return a specific message.

package/dist/lib/capability.d.ts

@@ -5,6 +5,17 @@ import { CapabilityMetadata } from './config';
  * Returns null if not found.
  */
 export declare function getPackageDir(name: string, searchPaths?: string[]): string | null;
+/**
+ * The capability name a package directory ships — the name a project's
+ * `.boop/config.json` records for it.
+ *
+ * Usually that is the directory name minus `cap-`, but the two are allowed to
+ * differ and `capability.json` is the authority: `packages/cap-users` ships
+ * `users-and-accounts`. Reading the directory alone is a pure filesystem
+ * lookup, so it works against a source tree that has never been built or
+ * installed — which is what the installed-layout generator needs.
+ */
+export declare function capabilityNameForPackageDir(pkgDir: string): string;
 /**
  * Look up a capability in the baked-in catalog by name.
  * Returns the catalog entry (with package field) or null if not found.

package/dist/lib/capability.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getPackageDir = getPackageDir;
+exports.capabilityNameForPackageDir = capabilityNameForPackageDir;
 exports.getCatalogEntry = getCatalogEntry;
 exports.listCapabilities = listCapabilities;
 exports.getCapability = getCapability;
@@ -59,6 +60,31 @@ function getPackageDir(name, searchPaths) {
         return findPackageDirByCapabilityName(name, paths);
     }
 }
+/**
+ * The capability name a package directory ships — the name a project's
+ * `.boop/config.json` records for it.
+ *
+ * Usually that is the directory name minus `cap-`, but the two are allowed to
+ * differ and `capability.json` is the authority: `packages/cap-users` ships
+ * `users-and-accounts`. Reading the directory alone is a pure filesystem
+ * lookup, so it works against a source tree that has never been built or
+ * installed — which is what the installed-layout generator needs.
+ */
+function capabilityNameForPackageDir(pkgDir) {
+    const capJsonPath = path.join(pkgDir, 'capability.json');
+    if (fs.existsSync(capJsonPath)) {
+        try {
+            const { name } = JSON.parse(fs.readFileSync(capJsonPath, 'utf-8'));
+            if (typeof name === 'string' && name.length > 0)
+                return name;
+        }
+        catch {
+            // An unreadable capability.json is not worth failing over here; the
+            // directory name is the same answer in every case but the mismatches.
+        }
+    }
+    return path.basename(pkgDir).replace(/^cap-/, '');
+}
 /**
  * Read capability metadata from a package's capability.json.
  * Returns null if the package is not found or has no capability.json.

package/dist/lib/config.d.ts

@@ -14,7 +14,12 @@ export interface ProfileMetadata {
     name: string;
     description: string;
     defaultCapabilities: string[];
-    kernel: KernelConfig;
+    /**
+     * Optional: every field of KernelConfig parameterises the scaffolding of a
+     * running web process, so a profile with no application domain (see
+     * `profiles/development/`) has no honest values to put here and omits it.
+     */
+    kernel?: KernelConfig;
 }
 export interface CapabilityScript {
     cmd: string;

package/dist/lib/install-layout.d.ts

@@ -0,0 +1,86 @@
+/**
+ * The single answer to "where does a file land when it is installed".
+ *
+ * `boop add` copies a capability's files into a project and `boop init` copies a
+ * profile's reference pages; before this module the mapping from source file to
+ * destination path was written out twice — once read-only inside `planAdd`, once
+ * while copying inside `copyFromPackage` — so the two could disagree about what a
+ * project receives and nothing would notice. Everything here is a pure read: it
+ * looks at a package or profile directory and returns `Placement[]`. It never
+ * writes, never needs a `targetDir`, and never touches `.boop/`.
+ *
+ * Three consumers depend on it: `copyFromPackage` (src/lib/scaffold.ts),
+ * `planAdd` (src/lib/preflight.ts) and `tools/generate-installed-layout.ts`,
+ * which materialises the installed layout inside the boop repository itself.
+ * Adding a fourth answer to this question is the defect this module exists to
+ * prevent.
+ */
+/** `skill` files land under `skills/`; `scaffold` files land wherever the package's scaffold tree says. */
+export type PlacementKind = 'skill' | 'scaffold';
+/**
+ * What ships a file. `hand-authored` is not an installable thing — it labels a
+ * file that already exists in a tree the mirror writes into, so a collision with
+ * one can be reported with the same machinery.
+ */
+export type PlacementOwnerKind = 'capability' | 'profile' | 'hand-authored';
+export interface Placement {
+    /** 'cap-database', 'web-app', or 'skills/boop-dolt-recovery' — the thing that ships this file. */
+    owner: string;
+    ownerKind: PlacementOwnerKind;
+    /** Absolute path of the file inside the package or profile directory. */
+    source: string;
+    /** Where it lands, POSIX-relative to the project root, e.g. 'skills/boop-database-prisma/SKILL.md'. */
+    dest: string;
+    kind: PlacementKind;
+}
+/** Two or more different sources claiming one destination. */
+export interface PlacementCollision {
+    dest: string;
+    placements: Placement[];
+}
+export declare class PlacementCollisionError extends Error {
+    readonly collisions: PlacementCollision[];
+    constructor(collisions: PlacementCollision[]);
+}
+/** How a collision names each side: the owner, and for hand-authored files, that nothing ships it. */
+export declare function describePlacementOwner(placement: Placement): string;
+/**
+ * Placements for an already-resolved capability package directory.
+ *
+ * `capabilityPlacements` delegates here once it has resolved a name to a package;
+ * the generator calls it directly because it walks `packages/cap-*` on disk and
+ * has no need of npm module resolution (and must not require a build).
+ */
+export declare function capabilityPlacementsFromDir(pkgDir: string): Placement[];
+/**
+ * Every file a capability ships and where it lands in a project.
+ *
+ * Resolves the capability the way `boop add` does — the installed package first,
+ * then the `capabilities/` source tree that only test fixtures still use.
+ */
+export declare function capabilityPlacements(capabilityName: string, searchPaths?: string[]): Placement[];
+/**
+ * Every file a profile ships and where it lands, mirroring `boop init`
+ * (src/commands/init.ts) — today that is the profile's reference pages.
+ */
+export declare function profilePlacements(profileName: string, repoRoot?: string): Placement[];
+/**
+ * The directory-level view of a skill's placements: one entry per skill folder.
+ *
+ * The mirror materialises a skill as a single link to its folder rather than a
+ * link per file, and this derives that view from the same placement list rather
+ * than re-deriving `skills/<name>` from a package layout a second time.
+ */
+export declare function skillDirectoryPlacements(placements: Placement[]): Placement[];
+/** Every destination claimed by two or more different source files. */
+export declare function findPlacementCollisions(placements: Placement[]): PlacementCollision[];
+/**
+ * Throw if any destination is claimed twice.
+ *
+ * The install path would not throw — `safeCopyDir` applies `onConflict: 'skip'`
+ * per file, so a second claimant silently half-merges into the first. That is
+ * fine to warn about while installing one capability into a project and fatal
+ * when writing a mirror of the whole library, which is why this is a separate
+ * assertion rather than something `planAdd` inherits.
+ */
+export declare function assertNoPlacementCollisions(placements: Placement[]): void;

package/dist/lib/install-layout.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * The single answer to "where does a file land when it is installed".
+ *
+ * `boop add` copies a capability's files into a project and `boop init` copies a
+ * profile's reference pages; before this module the mapping from source file to
+ * destination path was written out twice — once read-only inside `planAdd`, once
+ * while copying inside `copyFromPackage` — so the two could disagree about what a
+ * project receives and nothing would notice. Everything here is a pure read: it
+ * looks at a package or profile directory and returns `Placement[]`. It never
+ * writes, never needs a `targetDir`, and never touches `.boop/`.
+ *
+ * Three consumers depend on it: `copyFromPackage` (src/lib/scaffold.ts),
+ * `planAdd` (src/lib/preflight.ts) and `tools/generate-installed-layout.ts`,
+ * which materialises the installed layout inside the boop repository itself.
+ * Adding a fourth answer to this question is the defect this module exists to
+ * prevent.
+ */
+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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlacementCollisionError = void 0;
+exports.describePlacementOwner = describePlacementOwner;
+exports.capabilityPlacementsFromDir = capabilityPlacementsFromDir;
+exports.capabilityPlacements = capabilityPlacements;
+exports.profilePlacements = profilePlacements;
+exports.skillDirectoryPlacements = skillDirectoryPlacements;
+exports.findPlacementCollisions = findPlacementCollisions;
+exports.assertNoPlacementCollisions = assertNoPlacementCollisions;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const config_1 = require("./config");
+const capability_1 = require("./capability");
+class PlacementCollisionError extends Error {
+    constructor(collisions) {
+        super(`Placement collision:\n${collisions.map(describeCollision).join('\n')}`);
+        this.name = 'PlacementCollisionError';
+        this.collisions = collisions;
+    }
+}
+exports.PlacementCollisionError = PlacementCollisionError;
+/** How a collision names each side: the owner, and for hand-authored files, that nothing ships it. */
+function describePlacementOwner(placement) {
+    return placement.ownerKind === 'hand-authored'
+        ? `${placement.owner} (hand-authored, no owner)`
+        : placement.owner;
+}
+function describeCollision(collision) {
+    const owners = collision.placements.map(describePlacementOwner).join(' and ');
+    return `  ${collision.dest} — claimed by ${owners}`;
+}
+function toPosix(relPath) {
+    return relPath.split(path.sep).join('/');
+}
+/** Every file under `dir`, absolute, depth-first, sorted for a stable placement order. */
+function walkFiles(dir) {
+    const found = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory() || (entry.isSymbolicLink() && fs.statSync(full).isDirectory())) {
+            found.push(...walkFiles(full));
+        }
+        else {
+            found.push(full);
+        }
+    }
+    return found;
+}
+/**
+ * `<skillsDir>/<skill-name>/**` → `skills/<skill-name>/**`.
+ * Only directories are skills; a loose file beside them ships nothing.
+ */
+function skillPlacements(skillsDir, owner, ownerKind) {
+    if (!fs.existsSync(skillsDir))
+        return [];
+    const placements = [];
+    for (const entry of fs.readdirSync(skillsDir).sort()) {
+        const skillDir = path.join(skillsDir, entry);
+        if (!fs.statSync(skillDir).isDirectory())
+            continue;
+        for (const source of walkFiles(skillDir)) {
+            placements.push({
+                owner,
+                ownerKind,
+                source,
+                dest: `skills/${entry}/${toPosix(path.relative(skillDir, source))}`,
+                kind: 'skill',
+            });
+        }
+    }
+    return placements;
+}
+/**
+ * `<scaffoldDir>/**` → `<destPrefix>**`, preserving the tree.
+ * The scaffold directory mirrors the target project's own layout.
+ */
+function scaffoldPlacements(scaffoldDir, owner, ownerKind, destPrefix = '') {
+    if (!fs.existsSync(scaffoldDir))
+        return [];
+    return walkFiles(scaffoldDir).map(source => ({
+        owner,
+        ownerKind,
+        source,
+        dest: destPrefix + toPosix(path.relative(scaffoldDir, source)),
+        kind: 'scaffold',
+    }));
+}
+/**
+ * Placements for an already-resolved capability package directory.
+ *
+ * `capabilityPlacements` delegates here once it has resolved a name to a package;
+ * the generator calls it directly because it walks `packages/cap-*` on disk and
+ * has no need of npm module resolution (and must not require a build).
+ */
+function capabilityPlacementsFromDir(pkgDir) {
+    const pkgJsonPath = path.join(pkgDir, 'package.json');
+    if (!fs.existsSync(pkgJsonPath))
+        return [];
+    const boopkit = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).boopkit;
+    if (!boopkit)
+        return [];
+    const owner = path.basename(pkgDir);
+    const placements = [];
+    if (boopkit.skillsDir) {
+        placements.push(...skillPlacements(path.join(pkgDir, boopkit.skillsDir), owner, 'capability'));
+    }
+    if (boopkit.scaffoldDir) {
+        placements.push(...scaffoldPlacements(path.join(pkgDir, boopkit.scaffoldDir), owner, 'capability'));
+    }
+    return placements;
+}
+function isCapabilityPackage(pkgDir) {
+    const pkgJsonPath = path.join(pkgDir, 'package.json');
+    if (!fs.existsSync(pkgJsonPath))
+        return false;
+    return JSON.parse(fs.readFileSync(pkgJsonPath, 'utf-8')).boopkit?.capability === true;
+}
+/**
+ * Every file a capability ships and where it lands in a project.
+ *
+ * Resolves the capability the way `boop add` does — the installed package first,
+ * then the `capabilities/` source tree that only test fixtures still use.
+ */
+function capabilityPlacements(capabilityName, searchPaths) {
+    const pkgDir = (0, capability_1.getPackageDir)(capabilityName, searchPaths);
+    if (pkgDir && isCapabilityPackage(pkgDir)) {
+        return capabilityPlacementsFromDir(pkgDir);
+    }
+    const capDir = path.join((0, config_1.getBoopRoot)(), 'capabilities', capabilityName);
+    if (!fs.existsSync(capDir))
+        return [];
+    const owner = `cap-${capabilityName}`;
+    return [
+        ...skillPlacements(path.join(capDir, 'skills'), owner, 'capability'),
+        ...scaffoldPlacements(path.join(capDir, 'files'), owner, 'capability'),
+    ];
+}
+/**
+ * Every file a profile ships and where it lands, mirroring `boop init`
+ * (src/commands/init.ts) — today that is the profile's reference pages.
+ */
+function profilePlacements(profileName, repoRoot) {
+    const profileDir = path.join(repoRoot ?? (0, config_1.getBoopRoot)(), 'profiles', profileName);
+    return scaffoldPlacements(path.join(profileDir, 'reference'), profileName, 'profile', 'reference/');
+}
+/**
+ * The directory-level view of a skill's placements: one entry per skill folder.
+ *
+ * The mirror materialises a skill as a single link to its folder rather than a
+ * link per file, and this derives that view from the same placement list rather
+ * than re-deriving `skills/<name>` from a package layout a second time.
+ */
+function skillDirectoryPlacements(placements) {
+    // Keyed by folder *and* source, so two capabilities shipping the same skill
+    // name stay two placements and the collision check can still see them.
+    const folders = new Map();
+    for (const placement of placements) {
+        if (placement.kind !== 'skill')
+            continue;
+        const [, skillName] = placement.dest.split('/');
+        const dest = `skills/${skillName}`;
+        // The file's path within its skill folder is the same suffix in source and dest,
+        // so trimming it from the source yields the folder the link must point at.
+        const withinSkill = placement.dest.slice(dest.length + 1);
+        const source = placement.source.slice(0, placement.source.length - withinSkill.length - 1);
+        folders.set(`${dest}\u0000${source}`, { ...placement, source, dest });
+    }
+    return [...folders.values()];
+}
+/** Every destination claimed by two or more different source files. */
+function findPlacementCollisions(placements) {
+    const byDest = new Map();
+    for (const placement of placements) {
+        const claimants = byDest.get(placement.dest) ?? [];
+        claimants.push(placement);
+        byDest.set(placement.dest, claimants);
+    }
+    const collisions = [];
+    for (const [dest, claimants] of byDest) {
+        const sources = new Set(claimants.map(p => p.source));
+        if (sources.size > 1)
+            collisions.push({ dest, placements: claimants });
+    }
+    return collisions.sort((a, b) => a.dest.localeCompare(b.dest));
+}
+/**
+ * Throw if any destination is claimed twice.
+ *
+ * The install path would not throw — `safeCopyDir` applies `onConflict: 'skip'`
+ * per file, so a second claimant silently half-merges into the first. That is
+ * fine to warn about while installing one capability into a project and fatal
+ * when writing a mirror of the whole library, which is why this is a separate
+ * assertion rather than something `planAdd` inherits.
+ */
+function assertNoPlacementCollisions(placements) {
+    const collisions = findPlacementCollisions(placements);
+    if (collisions.length > 0)
+        throw new PlacementCollisionError(collisions);
+}