@vibe-agent-toolkit/cli 0.2.0-rc.11 → 0.2.0-rc.12

package/dist/commands/claude/plugin/install.js

@@ -11,69 +11,162 @@
  * When present, copies the pre-built directory tree to ~/.claude/plugins/
  * and updates Claude's plugin registry files. When absent, falls back to
  * copying dist/skills/ to ~/.claude/skills/.
+ *
+ * Every lane resolves what it installs from (staging an archive under $TMPDIR first),
+ * then calls {@link planInstall} and {@link executeInstall}: ONE plan of tree changes —
+ * the marketplace copy, each plugin's cache, each skill, everything `vat.replaces`
+ * removes — and the registry edit that agrees with it, applied as one transaction.
  */
-import { existsSync, lstatSync, readdirSync, readFileSync, cpSync } from 'node:fs';
-import { mkdir, mkdtemp, rm, symlink } from 'node:fs/promises';
+import { readdirSync } from 'node:fs';
+import fs from 'node:fs/promises';
 import { basename } from 'node:path';
 import { readDeclaredSkillName } from '@vibe-agent-toolkit/agent-skills';
-import { getClaudeUserPaths, installPlugin, uninstallPlugin } from '@vibe-agent-toolkit/claude-marketplace';
-import { ExitCode } from '@vibe-agent-toolkit/schema';
-import { direntKindFollowingSync, isPathAbsentError, isSingleFsSegment, normalizedTmpdir, toForwardSlash, safePath } from '@vibe-agent-toolkit/utils';
+import { getClaudeUserPaths, linkDevSkills, PLUGIN_KEY_INVALID_CODE, planPackageInstall, requirePluginInstallNames, } from '@vibe-agent-toolkit/claude-marketplace';
+import { buildReport, createRegistryIssue, toFindings } from '@vibe-agent-toolkit/schema';
+import { applyTreePlan, classifyFsFault, copyTree, direntKindFollowingSync, everywhere, forEachInOrder, fsBoundary, isPathAbsentError, isSingleFsSegment, isTreeChangeResidue, isVatError, pathPresent, planTreeChanges, proveTreeReadable, requireConfirmedAbsent, safePath, TREE_DEST_NOT_OWNED_CODE, withFsFault, withFsFaultSync, } from '@vibe-agent-toolkit/utils';
+import { ARCHIVE_LIMITS, extractArchive } from '@vibe-agent-toolkit/utils/archive';
 import { safeExecSync } from '@vibe-agent-toolkit/utils/process';
-import AdmZip from 'adm-zip';
 import { Command } from 'commander';
-import * as tar from 'tar';
-import { handleCommandError } from '../../../utils/command-error.js';
+import { CommandRefusalError, refusalCodeOf } from '../../../utils/command-refusal.js';
+import { endWithRefusal, endWithReport, leftoverIssue, NOTHING_FINISHED } from '../../../utils/document-writer.js';
+import { extractSkillZip, inStaging, installLinks, installUnit, occupiedRefusal, skillCopyChange } from '../../../utils/install-plan.js';
 import { createLogger } from '../../../utils/logger.js';
-import { detectSource, downloadNpmPackage, isGlobalNpmInstall, readPackageJsonVatMetadata, writeYamlHeader, } from './helpers.js';
+import { requireInputPath } from '../../../utils/project-root-policy.js';
+import { detectSource, downloadNpmPackage, isGlobalNpmInstall, readPackageJson, readPackageJsonVatMetadata, } from './helpers.js';
+import { keptForSiblingFindings } from './kept-findings.js';
 /** Relative path within a VAT npm package to its pre-built plugin structure. */
 const PLUGIN_MARKETPLACES_SUBPATH = safePath.join('dist', '.claude', 'plugins', 'marketplaces');
-const PACKAGE_JSON = 'package.json';
+/** `vat claude plugin install` has no `--strict`: a warning never fails it. */
+const GATE = { strict: false };
+/** One install source resolved per run — the `--npm-postinstall` lane included. */
+const INSTALL_SOURCES = 1;
 /**
- * List immediate subdirectory names inside a directory, following links.
- * Returns empty array when the directory does not exist.
+ * Where the child `vat build`'s streams go. Its stdout is sent straight to
+ * this process's stderr (fd 2): this verb's stdout carries only its own
+ * report, and a PIPE would buffer the build's document under spawnSync's
+ * 1 MiB `maxBuffer` — a larger one kills the child with ENOBUFS.
+ */
+const BUILD_CHILD_STDIO = ['inherit', 2, 'inherit'];
+/** A fresh run of `options`, nothing done yet. */
+function newInstallRun(options, logger) {
+    return { options, logger, dryRun: options.dryRun === true, source: undefined, skills: [], issues: [], roots: { source: [], environment: [] } };
+}
+/** The classifier over the run's trees: a fault's side is decided by the path it names. */
+function boundaryOf(run) {
+    return fsBoundary({ source: run.roots.source, environment: run.roots.environment }, { origin: 'content' });
+}
+/**
+ * One tree the run is about to copy ({@link installUnit}): a staged one as it is, one in the
+ * operator's own directory as its real path once no link in it leads outside it.
  *
- * Followed on purpose: a `--dev` install puts a plugin or marketplace here AS
- * a symlink, and `Dirent.isDirectory()` is false for a link — so every dev
- * install was invisible to the listing that uninstalls, lists and re-installs.
+ * @param dir - The tree: a skill, a marketplace or a plugin directory
+ * @param side - The side the lane resolved its package on
+ * @param what - What the tree is, for a refusal
  */
-function listSubdirectories(dir) {
-    if (!existsSync(dir))
-        return [];
-    return readdirSync(dir, { withFileTypes: true })
-        .filter(d => direntKindFollowingSync(dir, d) === 'directory')
-        .map(d => d.name);
+function unitOf(run, dir, side, what) {
+    // A lane that installs from the operator's directory names it before it plans anything.
+    const [root] = run.roots.source;
+    if (side !== 'environment' && root === undefined)
+        throw new Error('install lane planned a copy before naming its source directory');
+    return installUnit({ root: root ?? dir, side }, dir, what);
+}
+/** Name the source the run installs from. */
+function setSource(run, label, type, symlink = false) {
+    run.source = { label, type, symlink };
+}
+/** The run as an outcome, or `undefined` before any lane named its source. */
+function outcomeOf(run) {
+    if (run.source === undefined)
+        return undefined;
+    return { source: run.source.label, sourceType: run.source.type, symlink: run.source.symlink, skills: run.skills, issues: run.issues };
+}
+/** The report's `data` for an outcome. */
+function installData(outcome, dryRun) {
+    return { source: outcome.source, sourceType: outcome.sourceType, dryRun, symlink: outcome.symlink, skills: outcome.skills };
+}
+/**
+ * What finished before a refusal: every skill already installed, and every
+ * finding already made — or {@link NOTHING_FINISHED} when there is none.
+ */
+export function installFinished(outcome, dryRun) {
+    if (outcome === undefined || (outcome.skills.length === 0 && outcome.issues.length === 0))
+        return NOTHING_FINISHED;
+    return { examined: INSTALL_SOURCES, findings: toFindings(outcome.issues), data: installData(outcome, dryRun) };
+}
+/** A source FILE argument (a .zip, a .tgz): absent is the invocation's mistake, refused the input's. */
+function assertSourceFile(path) {
+    requireInputPath(path, path, { origin: 'argument', message: `Path does not exist: ${path}` }, everywhere('source'));
+}
+/** The skills `--name` selects from a package's declared list; naming one it lacks is the invocation's mistake. */
+function selectSkills(skills, name, packageName) {
+    if (name === undefined)
+        return [...skills];
+    const selected = skills.filter((skill) => skill === name);
+    if (selected.length === 0) {
+        throw new CommandRefusalError('USAGE_INVALID', `Skill "${name}" not found in package ${packageName}. Available: ${skills.join(', ')}`);
+    }
+    return selected;
 }
 /**
- * Register a plugin in the Claude plugin registry, logging a warning on failure.
+ * List immediate subdirectory names inside a directory of the PACKAGE being
+ * installed, on `side` (the operator's tree, or VAT's staging when it was extracted
+ * there), following links. An empty array when the directory is absent — believed
+ * only when its parent's listing agrees; a directory the OS will not list (or an
+ * entry it will not stat) is a fault on `side`, naming it.
+ *
+ * Followed on purpose: a built plugin tree may hold a plugin or a skill AS a
+ * symlink, and `Dirent.isDirectory()` is false for a link.
+ *
+ * A tree-change leftover (`.<name>.vat-staged-*`, what a killed build leaves beside
+ * what it was replacing) is never one of them: it is not a marketplace, a plugin or a skill.
  */
-async function registerPlugin(mpName, pluginName, pluginDir, version, packageName, paths, logger) {
+function listSubdirectories(dir, side, within) {
+    const ctx = { side, action: 'list the package directory', path: dir };
+    let entries;
     try {
-        await installPlugin({
-            marketplaceName: mpName,
-            pluginName,
-            pluginDir,
-            version,
-            source: { source: 'npm', package: packageName, version },
-            paths,
-        });
-        logger.info(`   Registered plugin ${pluginName}@${mpName} in Claude plugin registry`);
+        entries = readdirSync(dir, { withFileTypes: true });
     }
     catch (error) {
-        logger.info(`   Warning: Could not register plugin ${pluginName}: ${String(error)}`);
+        if (!isPathAbsentError(error))
+            throw classifyFsFault(error, ctx);
+        requireConfirmedAbsent(dir, error, { action: ctx.action, path: dir }, { follows: true, sideOf: everywhere(side) });
+        return [];
     }
+    return withFsFaultSync(ctx, () => entries.filter((d) => !isTreeChangeResidue(d.name) && direntKindFollowingSync(dir, d, within) === 'directory').map((d) => d.name));
 }
 /**
- * Install from a pre-built plugin tree: read package.json, copy tree, output success.
- * Shared between npm and local install paths to avoid duplication.
+ * Refuse, before anything under ~/.claude changes, a package whose plugin tree
+ * or `vat.replaces` names something that cannot be installed or removed: a
+ * plugin or marketplace directory, the package version, a replaced plugin, or a
+ * replaced flat skill that is not one path segment (or a dot-led version). Each
+ * came from the PACKAGE, so the refusal is the input's (`INPUT_UNREADABLE`), not
+ * the invocation's. (`vat.replaces`' SHAPE was already refused by `readPackageJson`.)
  */
-async function installPluginTreeAndExit(rootDir, marketplacesDir, sourceLabel, sourceType, startTime, logger, dryRun) {
-    const pkgRaw = readFileSync(safePath.join(rootDir, PACKAGE_JSON), 'utf-8');
-    const packageJson = JSON.parse(pkgRaw);
-    const installedSkills = await copyPluginTree(marketplacesDir, packageJson, logger, dryRun);
-    const duration = Date.now() - startTime;
-    outputInstallSuccess(installedSkills, sourceLabel, sourceType, duration, logger, dryRun);
-    process.exit(ExitCode.OK);
+function assertPackagePluginNames(marketplacesDir, marketplaceNames, packageJson, version, side, within) {
+    const check = (names, origin) => {
+        try {
+            requirePluginInstallNames({ ...names, version });
+        }
+        catch (error) {
+            if (!isVatError(error, PLUGIN_KEY_INVALID_CODE))
+                throw error;
+            throw new CommandRefusalError('INPUT_UNREADABLE', `Package ${packageJson.name} cannot be installed, nothing was changed: ${error.message} (${origin}).`, { cause: error });
+        }
+    };
+    for (const skillName of packageJson.vat?.replaces?.flatSkills ?? []) {
+        if (!isSingleFsSegment(skillName)) {
+            throw new CommandRefusalError('INPUT_UNREADABLE', `Package ${packageJson.name} cannot be installed, nothing was changed: the legacy flat skill "${skillName}" it ` +
+                'replaces (package.json vat.replaces.flatSkills) must be a single path segment (no separators, not "." or "..").');
+        }
+    }
+    for (const marketplaceName of marketplaceNames) {
+        for (const pluginName of listSubdirectories(safePath.join(marketplacesDir, marketplaceName, 'plugins'), side, within)) {
+            check({ marketplaceName, pluginName }, 'its built plugin tree and package.json version');
+        }
+        for (const pluginName of packageJson.vat?.replaces?.plugins ?? []) {
+            check({ marketplaceName, pluginName }, 'package.json vat.replaces.plugins');
+        }
+    }
 }
 /**
  * Convert a skill name to a filesystem-safe path segment.
@@ -95,7 +188,7 @@ function skillNameToFsPath(name) {
  */
 export function assertSkillEntryName(name, origin) {
     if (!isSingleFsSegment(name)) {
-        throw new Error(`Refusing to install "${name}" (${origin}): a skill name must be a single path segment ` +
+        throw new CommandRefusalError('INPUT_UNREADABLE', `Refusing to install "${name}" (${origin}): a skill name must be a single path segment ` +
             `(no separators, not "." or "..").`);
     }
     return name;
@@ -107,7 +200,7 @@ export function createPluginInstallCommand() {
         .argument('[source]', 'Source to install from (npm:package, ZIP file, or directory path)')
         .option('-s, --skills-dir <path>', 'Claude skills directory', getClaudeUserPaths().skillsDir)
         .option('-n, --name <name>', 'Custom name for installed skill (default: auto-detect from source)')
-        .option('-f, --force', 'Overwrite existing skill if present', false)
+        .option('-f, --force', 'Overwrite an existing skill, or a marketplace directory VAT did not install from this package', false)
         .option('--dry-run', 'Preview installation without creating files', false)
         .option('--npm-postinstall', 'Run as npm postinstall hook (internal use)', false)
         .option('-d, --dev', 'Development mode: symlink skills from dist/skills/ (rebuilds reflected immediately)')
@@ -125,6 +218,29 @@ Description:
   the pre-built directory tree is copied to ~/.claude/plugins/ (dumb copy).
   Otherwise, falls back to copying dist/skills/ to ~/.claude/skills/.
 
+  A marketplace directory already at ~/.claude/plugins/marketplaces/<name> is
+  replaced only when VAT installed it from this same package (its .vat-marketplace
+  marker says so; for an install made by a VAT older than the marker, the
+  known_marketplaces.json entry naming this package does). Anything else there — a
+  marketplace Claude Code added, or one another package installed — is refused
+  with nothing changed; --force replaces it. So is a marketplace name whose
+  known_marketplaces.json entry another source registered, with no directory
+  (or an empty one) there.
+
+  Archives (.zip, .tgz, an npm tarball) are judged whole before anything is
+  written: one holding a symbolic or hard link, a device, a name that leaves the
+  archive (absolute, ".."), one name twice (or twice once letter case is
+  folded), or more than 50,000 entries / 256 MiB expanded is refused. A skill
+  ZIP holds SKILL.md at its top level, or exactly one top-level folder with
+  SKILL.md directly inside. A local directory may hold links, but only
+  relative ones to something that exists inside the plugin or skill being
+  installed, reached through no other link.
+
+  One transaction: the marketplace copy, each plugin's cache, each skill, the
+  registry files and everything vat.replaces removes change together, or not at
+  all. --dry-run prints the plan, one line per change ([dry-run] create|replace|
+  remove|keep|subsumed <what> <path>), and changes nothing.
+
   Supported sources:
   - npm package: npm:@scope/package-name
   - Local ZIP file: ./path/to/skill.zip
@@ -132,15 +248,44 @@ Description:
   - npm postinstall: --npm-postinstall (automatic during global install)
   - Dev mode: --dev (symlinks from dist/skills/)
 
-Output:
-  - status: success/error
-  - source: Original source
-  - sourceType: npm/local/zip/npm-postinstall/dev
+Output (YAML report on stdout):
+  - status: ok, findings (a warning below), or error when the run could not install
+  - examined: install sources resolved (1; a --npm-postinstall that skips is ok, skills: [])
+  - data.source / data.sourceType: what was installed from (npm/local/zip/tgz/dev/npm-postinstall)
+  - data.dryRun, data.symlink (true for --dev)
+  - data.skills[]: { name, installPath, sourcePath } — sourcePath is the --dev link target, else null
+  - findings: COMPONENT_DECLARED_BUT_MISSING (warning) for a --dev plugin skill whose build is missing;
+    TREE_CLEANUP_INCOMPLETE (warning), its link the path, when the install is complete but a
+    previous tree it replaced (left as .<name>.vat-staged-*.previous beside it) or its
+    $TMPDIR staging directory could not be removed;
+    PLUGIN_KEPT_SIBLING_UNEXAMINED (warning), its link the directory, for a plugin
+    vat.replaces kept because a directory it may be could not be examined
 
 Exit Codes:
-  0 - Installation successful
-  1 - Installation error (invalid source, skill exists, etc.)
-  2 - System error
+  0 - Installed (a warning does not fail the run)
+  2 - The run could not install: a missing or unknown source, a skill that exists
+      without --force (an EMPTY directory there is replaced without it), a marketplace
+      directory VAT did not install from this package (without --force), an unknown
+      --target, a plain directory with no SKILL.md (USAGE_INVALID); --target claude.ai (NOT_IMPLEMENTED); an unreadable
+      source (a package directory it cannot list, or a named pipe, socket or
+      device in the package, refused unopened, included), a link in a local
+      directory that leads outside what is being installed, a .zip, .tgz or
+      npm tarball VAT does not accept (see Archives above; not an archive,
+      or an entry that does not inflate, included), a ZIP not laid out
+      as a skill ZIP, a registry file that is not JSON, a
+      package whose vat.replaces is not { plugins?: string[], flatSkills?: string[] },
+      whose plugin or marketplace directory, version, vat.replaces.plugins or
+      vat.replaces.flatSkills entry is not one path segment (or whose version
+      begins with ".") (INPUT_UNREADABLE); npm pack failing, a full $TMPDIR during
+      its download included (EXTERNAL_API_FAILED); --build whose vat build failed,
+      a staging copy under $TMPDIR it could not create or extract into (full,
+      read-only, out of descriptors), a destination under ~/.claude (or -s) it
+      cannot examine or write (RUN_INCOMPLETE). Every such refusal changes
+      nothing under ~/.claude. Only a tree vat.replaces removes that the OS will
+      not delete once the registry is written refuses after the install
+      (RUN_INCOMPLETE naming it), and then lists the installed skills. A plugin
+      vat.replaces names that is the just-installed plugin on disk (Old -> old on a
+      case-insensitive filesystem) loses only its registry entry.
 
 Example:
   $ vat claude plugin install --dev                        # Symlink all skills from cwd
@@ -150,370 +295,464 @@ Example:
 `);
     return command;
 }
+/**
+ * Build the report. Pure: no file system, no `process.exit`.
+ *
+ * @param outcome - What the install run did
+ * @param dryRun - Whether anything was actually written
+ * @param durationMs - How long the run took
+ */
+export function buildPluginInstallReport(outcome, dryRun, durationMs) {
+    return buildReport({
+        examined: INSTALL_SOURCES,
+        findings: toFindings(outcome.issues),
+        data: installData(outcome, dryRun),
+        gate: GATE,
+        durationMs,
+    });
+}
+/** Refuse a `--target` this verb cannot install to. */
+function assertInstallTarget(target) {
+    if (target === 'code')
+        return;
+    if (target === 'claude.ai') {
+        throw new CommandRefusalError('NOT_IMPLEMENTED', 'claude.ai org provisioning API not yet confirmed as public. Use the claude.ai admin console to upload a .zip manually, '
+            + 'or vat claude org skills install for workspace-scoped skill management.');
+    }
+    throw new CommandRefusalError('USAGE_INVALID', `Unsupported --target "${target}": use code (default) or claude.ai.`);
+}
+/** Route the invocation to the lane that installs it. */
+async function runInstall(source, run) {
+    const { options, logger } = run;
+    assertInstallTarget(options.target ?? 'code');
+    // --build implies --dev
+    if (options.build || options.dev) {
+        await handleDevInstall(run);
+        return;
+    }
+    if (options.npmPostinstall) {
+        await handleNpmPostinstall(run);
+        return;
+    }
+    // Regular install - source is required
+    if (!source) {
+        throw new CommandRefusalError('USAGE_INVALID', 'Source argument required. Use npm:package, ./dir, ./file.zip or ./file.tgz');
+    }
+    const sourceType = detectSource(source);
+    logger.debug(`Detected source type: ${sourceType}`);
+    switch (sourceType) {
+        case 'npm':
+            return handleNpmInstall(source, run);
+        case 'local':
+            return handleLocalInstall(source, run);
+        case 'zip':
+            return handleZipInstall(source, run);
+        case 'tgz':
+            return handleTgzInstall(source, run);
+        case 'npm-postinstall':
+        case 'dev':
+            // detectSource never returns these for a positional source: each is a flag.
+            throw new Error(`${sourceType} source type is handled by its own flag`);
+    }
+}
+/** The human half, on stderr; a run that placed no skill gets no check mark. */
+function logInstallOutcome(outcome, dryRun, logger) {
+    const count = outcome.skills.length;
+    if (count === 0) {
+        logger.info(dryRun ? '\n⚠️ Dry-run: the source holds no skill to install' : '\n⚠️ Nothing installed: the source holds no skill');
+        return;
+    }
+    if (outcome.symlink) {
+        logger.info(dryRun ? `\n✅ Dry-run complete: ${count} skill(s) would be symlinked` : `\n✅ Dev-installed ${count} skill(s) via symlink`);
+        if (!dryRun)
+            logger.info(`   After rebuilding, run /reload-plugins in Claude Code`);
+        return;
+    }
+    if (dryRun) {
+        logger.info(`\n✅ Dry-run complete: ${count} skill(s) would be installed`);
+        return;
+    }
+    logger.info(`\n✅ Installed ${count} skill(s)`);
+    logger.info(`\n💡 Run 'vat claude plugin list' to verify installation`);
+    logger.info(`   Restart Claude Code or run /reload-plugins to use the new skill`);
+}
 async function installCommand(source, options) {
     const logger = createLogger(options.debug ? { debug: true } : {});
     const startTime = Date.now();
+    const run = newInstallRun(options, logger);
+    const { dryRun } = run;
+    let outcome;
     try {
-        // Handle --target claude.ai stub
-        const target = options.target ?? 'code';
-        if (target === 'claude.ai') {
-            // Write separator directly — cannot use writeYamlHeader() which outputs status: success
-            process.stdout.write(`---\n`);
-            process.stdout.write(`status: not-available\n`);
-            process.stdout.write(`reason: "claude.ai org provisioning API not yet confirmed as public"\n`);
-            process.stdout.write(`requestedTarget: claude.ai\n`);
-            process.stdout.write(`guidance: "Use claude.ai admin console to upload a .zip manually, or use --target api.anthropic.com for workspace-scoped skill management"\n`);
-            process.exit(ExitCode.ERROR);
-        }
-        // Handle --build (implies --dev)
-        if (options.build) {
-            options.dev = true;
-        }
-        // Handle --dev flag
-        if (options.dev) {
-            await handleDevInstall(options, logger, startTime);
-            return;
-        }
-        // Handle --npm-postinstall flag
-        if (options.npmPostinstall) {
-            await handleNpmPostinstall(options, logger, startTime);
-            return;
-        }
-        // Regular install - source is required
-        if (!source) {
-            throw new Error('Source argument required. Use npm:package, ./dir, or ./file.zip');
-        }
-        // Detect source type
-        const sourceType = detectSource(source);
-        logger.debug(`Detected source type: ${sourceType}`);
-        // Route to appropriate handler
-        switch (sourceType) {
-            case 'npm': {
-                await handleNpmInstall(source, options, logger, startTime);
-                break;
-            }
-            case 'local': {
-                await handleLocalInstall(source, options, logger, startTime);
-                break;
-            }
-            case 'zip': {
-                await handleZipInstall(source, options, logger, startTime);
-                break;
-            }
-            case 'tgz': {
-                await handleTgzInstall(source, options, logger, startTime);
-                break;
-            }
-            case 'npm-postinstall': {
-                throw new Error('npm-postinstall source type should be handled by --npm-postinstall flag');
-            }
-            case 'dev': {
-                throw new Error('dev source type should be handled by --dev flag');
-            }
-        }
+        await runInstall(source, run);
+        outcome = outcomeOf(run);
+        // Every lane names its source before it can return; reaching here without one is a defect.
+        if (outcome === undefined)
+            throw new Error('install lane returned without naming its source');
     }
     catch (error) {
-        handleCommandError(error, logger, startTime, 'PluginInstall');
-    }
+        // A raw filesystem fault is classified by the path it names against the run's trees;
+        // anything already coded or classified passes through as it is.
+        const refusal = boundaryOf(run).classify(error, 'install the plugin', 'destination');
+        // Whatever installed before the refusal is still reported.
+        endWithRefusal('claude plugin install', refusalCodeOf(refusal), refusal, 'yaml', GATE, installFinished(outcomeOf(run), dryRun));
+    }
+    logInstallOutcome(outcome, dryRun, logger);
+    endWithReport('claude plugin install', buildPluginInstallReport(outcome, dryRun, Date.now() - startTime), 'yaml');
 }
-/**
- * Handle npm package installation
- */
-async function handleNpmInstall(source, options, logger, startTime) {
-    const packageName = source.startsWith('npm:') ? source.slice(4) : source;
-    logger.info(`📥 Installing skill from npm: ${packageName}`);
-    // Create temp directory
-    const tempDir = await mkdtemp(safePath.join(normalizedTmpdir(), 'vat-install-npm-'));
-    try {
-        // Download and extract npm package
-        logger.info('   Downloading package...');
-        const extractedPath = downloadNpmPackage(packageName, tempDir);
-        // If the package ships a pre-built plugin tree, install via dumb copy.
-        const marketplacesDir = safePath.join(extractedPath, PLUGIN_MARKETPLACES_SUBPATH);
-        const hasPlugin = !options.userInstallWithoutPlugin && existsSync(marketplacesDir);
-        if (hasPlugin) {
-            logger.info('   Plugin detected — installing via Claude plugin system');
-            await installPluginTreeAndExit(extractedPath, marketplacesDir, `npm:${packageName}`, 'npm', startTime, logger, options.dryRun);
-        }
-        // No plugin tree — install skills directly to ~/.claude/skills/
-        const { skills } = await readPackageJsonVatMetadata(extractedPath);
-        if (skills.length === 0) {
-            throw new Error(`No skills found in package ${packageName}`);
-        }
-        // Filter by --name if specified
-        const skillNames = options.name
-            ? skills.filter(s => s === options.name)
-            : skills;
-        if (skillNames.length === 0) {
-            throw new Error(`Skill "${options.name ?? ''}" not found in package ${packageName}. ` +
-                `Available: ${skills.join(', ')}`);
-        }
-        const skillsDir = options.skillsDir ?? getClaudeUserPaths().skillsDir;
-        for (const skillName of skillNames) {
-            const skillPath = safePath.join(extractedPath, 'dist', 'skills', skillNameToFsPath(skillName));
-            await installSkillFromPath(skillPath, skillName, options, logger);
+// --- the one plan -----------------------------------------------------------------------------
+/** The input kind of a package's built plugin tree. */
+const PLUGIN_TREE = 'plugin-tree';
+/** One skill copied into the skills directory: absent build is the invocation's mistake. */
+function skillCopy(run, side, skill) {
+    const { path: skillPath, name: skillName, within } = skill;
+    // The source declares a skill whose build is absent or unreadable: absent is the
+    // invocation's mistake, as for every path argument; unreadable is classified on its side —
+    // the operator's tree, or VAT's own staging an archive was extracted into.
+    if (!pathPresent(skillPath, { follow: within }, everywhere(side), 'confirmed')) {
+        throw new CommandRefusalError('USAGE_INVALID', `Skill "${skillName}" has no build to install. Path does not exist: ${skillPath}`);
+    }
+    const skillsDir = run.options.skillsDir ?? getClaudeUserPaths().skillsDir;
+    // The declared name is author-controlled (SKILL.md `name:`, package.json `vat.skills[]`) and
+    // `--force` replaces whatever is at this path.
+    const installPath = safePath.join(skillsDir, assertSkillEntryName(skillName, 'skill name'));
+    return {
+        change: skillCopyChange({ name: skillName, source: unitOf(run, skillPath, side, 'the skill directory'), dest: installPath }, side, run.options.force === true),
+        skill: { name: skillName, installPath, sourcePath: null },
+    };
+}
+function planSkills(run, side, skills) {
+    const copies = skills.map((skill) => skillCopy(run, side, skill));
+    return { changes: copies.map((copy) => copy.change), registry: null, replaced: [], skills: copies.map((copy) => copy.skill), issues: [] };
+}
+/** Entries of a plugin other than its skills: what `--dev` copies (it links each skill instead). */
+const notSkills = (relative) => relative !== 'skills';
+/** Entries of a marketplace other than its plugins: what `--dev` copies before building each plugin. */
+const notPlugins = (relative) => relative !== 'plugins';
+/** Entries of a marketplace other than a plugin's skills: what a `--dev` install reads of it. */
+const notPluginSkills = (relative) => !/^plugins\/[^/]+\/skills$/.test(relative);
+/** The `--dev` links of one plugin: each skill its tree declares and `dist/skills/` holds; each one it does not, a finding. */
+function devPlugin(plugin, rootDir) {
+    const skillsDir = safePath.join(plugin.srcPluginDir, 'skills');
+    const result = { plugin, hasSkills: pathPresent(skillsDir, { follow: rootDir }, everywhere(plugin.side), 'confirmed'), links: [], skills: [], issues: [] };
+    for (const name of listSubdirectories(skillsDir, plugin.side, rootDir)) {
+        const target = safePath.resolve(rootDir, 'dist', 'skills', name);
+        if (!pathPresent(target, { follow: rootDir }, everywhere(plugin.side), 'confirmed')) {
+            result.issues.push(createRegistryIssue('COMPONENT_DECLARED_BUT_MISSING', `Plugin "${plugin.pluginName}" declares skill "${name}", but it is not built — it was not linked. Run vat build, then re-install.`, { location: safePath.relative(rootDir, target) }));
+            continue;
         }
-        const duration = Date.now() - startTime;
-        outputInstallSuccess(skillNames.map(name => ({
-            name,
-            installPath: safePath.join(skillsDir, name),
-        })), `npm:${packageName}`, 'npm', duration, logger, options.dryRun);
-        process.exit(ExitCode.OK);
-    }
-    finally {
-        await rm(tempDir, { recursive: true, force: true });
+        result.links.push({ name, target });
+        result.skills.push({ name: `${plugin.pluginName}:${name}`, installPath: safePath.join(plugin.destPluginDir, 'skills', name), sourcePath: target });
     }
+    return result;
 }
 /**
- * Handle local directory installation
+ * Fill `relative` under the staged directory (`''`: the directory itself) with one `--dev` plugin: its non-skill content copied, and a link per built
+ * skill to `dist/skills/<name>`, so a rebuild is picked up live.
  */
-async function handleLocalInstall(source, options, logger, startTime) {
-    const sourcePath = safePath.resolve(source);
-    logger.info(`📥 Installing skill from directory: ${sourcePath}`);
-    const skillsDir = options.skillsDir ?? getClaudeUserPaths().skillsDir;
-    // Check for pre-built plugin tree first
-    const marketplacesDir = safePath.join(sourcePath, PLUGIN_MARKETPLACES_SUBPATH);
-    if (!options.userInstallWithoutPlugin && existsSync(marketplacesDir)) {
-        await installPluginTreeAndExit(sourcePath, marketplacesDir, `local:${sourcePath}`, 'local', startTime, logger, options.dryRun);
-    }
-    // Check if directory contains package.json with vat.skills
-    const packageJsonPath = safePath.join(sourcePath, 'package.json');
-    const hasPackageJson = existsSync(packageJsonPath);
-    let installed;
-    if (hasPackageJson) {
-        const { packageJson, skills } = await readPackageJsonVatMetadata(sourcePath);
-        const skillNames = options.name ? skills.filter(s => s === options.name) : skills;
-        if (skillNames.length === 0) {
-            throw new Error(`Skill "${options.name ?? ''}" not found in package ${packageJson.name}. ` +
-                `Available: ${skills.join(', ')}`);
-        }
-        for (const skillName of skillNames) {
-            const skillPath = safePath.join(sourcePath, 'dist', 'skills', skillNameToFsPath(skillName));
-            await installSkillFromPath(skillPath, skillName, options, logger);
-        }
-        installed = skillNames.map(name => ({ name, installPath: safePath.join(skillsDir, name) }));
-    }
-    else {
-        // Plain skill directory. The package.json branch above installs each skill
-        // under its declared name; do the same here rather than under whatever the
-        // source directory happens to be called.
-        const skillName = options.name ??
-            readDeclaredSkillName(safePath.join(sourcePath, 'SKILL.md')) ??
-            basename(sourcePath);
-        await installSkillFromPath(sourcePath, skillName, options, logger);
-        installed = [{ name: skillName, installPath: safePath.join(skillsDir, skillName) }];
-    }
-    const duration = Date.now() - startTime;
-    outputInstallSuccess(installed, `local:${sourcePath}`, 'local', duration, logger, options.dryRun);
-    process.exit(ExitCode.OK);
+async function writeDevPlugin(dev, staged, relative) {
+    await copyTree(dev.plugin.srcPluginDir, staged, relative, { links: installLinks(dev.plugin.side), side: dev.plugin.side, onto: 'fresh', filter: notSkills });
+    if (dev.hasSkills)
+        await linkDevSkills(relative === '' ? staged : safePath.join(staged, relative), dev.links);
+}
+/** The plugins one marketplace of the package ships, each as the tree its cache is copied from, with where it goes under `paths`. */
+function pluginsOf(run, side, srcMpDir, marketplaceName, destMpDir, rootDir) {
+    return listSubdirectories(safePath.join(srcMpDir, 'plugins'), side, rootDir).map((pluginName) => ({
+        side,
+        marketplaceName,
+        pluginName,
+        // Its own unit: the cache holds this plugin alone, so a link from it into a sibling plugin would leave the copy.
+        srcPluginDir: unitOf(run, safePath.join(srcMpDir, 'plugins', pluginName), side, 'the plugin directory'),
+        destPluginDir: safePath.join(destMpDir, 'plugins', pluginName),
+    }));
+}
+/** One marketplace of a copy install: the package's tree copied whole, and each plugin's cache copied from it. */
+function copiedMarketplace(marketplaceName, srcMpDir, plugins, side, rootDir) {
+    const skills = plugins.flatMap((plugin) => listSubdirectories(safePath.join(plugin.srcPluginDir, 'skills'), side, rootDir).map((name) => ({ name, installPath: safePath.join(plugin.destPluginDir, 'skills', name), sourcePath: null })));
+    return {
+        install: {
+            marketplaceName,
+            write: (staged) => copyTree(srcMpDir, staged, '', { links: installLinks(side), side, onto: 'fresh' }),
+            reads: [srcMpDir],
+            // A `write` fill, not a `copy`: the planner proves every `copy` source again, and the whole package was
+            // proven readable once already ({@link planPluginTree}). The holding check still sees it (`reads`).
+            plugins: plugins.map(({ pluginName, srcPluginDir }) => ({
+                pluginName,
+                cacheFill: { from: 'write', write: (staged) => copyTree(srcPluginDir, staged, '', { links: installLinks(side), side, onto: 'fresh' }), reads: [srcPluginDir] },
+            })),
+        },
+        skills,
+        issues: [],
+    };
+}
+/** One marketplace of a `--dev` install: its non-plugin content copied, each plugin built with links, the cache built the same way. */
+function devMarketplace(marketplaceName, srcMpDir, plugins, rootDir, side) {
+    const linked = plugins.map((plugin) => devPlugin(plugin, rootDir));
+    return {
+        install: {
+            marketplaceName,
+            write: async (staged) => {
+                await copyTree(srcMpDir, staged, '', { links: installLinks(side), side, onto: 'fresh', filter: notPlugins });
+                // In order: each plugin is built into the one staged tree, and the first refusal stops the fill.
+                await forEachInOrder(linked, (dev) => writeDevPlugin(dev, staged, `plugins/${dev.plugin.pluginName}`));
+            },
+            reads: [srcMpDir],
+            plugins: linked.map((dev) => ({
+                pluginName: dev.plugin.pluginName,
+                cacheFill: { from: 'write', write: (staged) => writeDevPlugin(dev, staged, ''), reads: [dev.plugin.srcPluginDir] },
+            })),
+        },
+        skills: linked.flatMap((each) => each.skills),
+        issues: linked.flatMap((each) => each.issues),
+    };
 }
 /**
- * Handle ZIP file installation
+ * Plan a plugin-tree install: every marketplace the package ships replaced whole (with
+ * VAT's marker), each plugin's cache, each `vat.replaces` plugin's cache and flat skill
+ * removed, and the registry edit — one plan. Every name is checked and the whole source
+ * proven readable before anything is decided. A marketplace directory already there is
+ * replaced only when VAT installed it from this very package, or under `force` (`--force`).
  */
-async function handleZipInstall(source, options, logger, startTime) {
-    const sourcePath = safePath.resolve(source);
-    logger.info(`📥 Installing skill from ZIP: ${sourcePath}`);
-    if (!existsSync(sourcePath)) {
-        throw new Error(`ZIP file not found: ${sourcePath}`);
-    }
-    const skillName = options.name ?? basename(sourcePath, '.zip');
-    const { installPath } = await prepareInstallation(skillName, options);
-    if (!options.dryRun) {
-        logger.info('   Extracting ZIP...');
-        const zip = new AdmZip(sourcePath);
-        zip.extractAllTo(installPath, /* overwrite */ true);
-    }
-    const duration = Date.now() - startTime;
-    outputInstallSuccess([{ name: skillName, installPath }], sourcePath, 'zip', duration, logger, options.dryRun);
-    process.exit(ExitCode.OK);
+async function planPluginTree(run, input, mode) {
+    const { rootDir, packageJson, side } = input;
+    const force = run.options.force === true;
+    const marketplacesDir = safePath.join(rootDir, PLUGIN_MARKETPLACES_SUBPATH);
+    const paths = getClaudeUserPaths();
+    const version = packageJson.version ?? '0.0.0';
+    const marketplaceNames = listSubdirectories(marketplacesDir, side, rootDir);
+    assertPackagePluginNames(marketplacesDir, marketplaceNames, packageJson, version, side, rootDir);
+    // Each marketplace as the tree it is copied from, before anything reads it: one in the operator's
+    // own directory with a link leading out of it is the package's refusal (INPUT_UNREADABLE).
+    const marketplaces = marketplaceNames.map((mpName) => ({ mpName, srcMpDir: unitOf(run, safePath.join(marketplacesDir, mpName), side, 'the marketplace directory') }));
+    // Every file of the package, before anything changes — dry run or real: a file the
+    // install cannot read is the package's refusal (INPUT_UNREADABLE).
+    const proof = mode === 'dev' ? { links: installLinks(side), side, filter: notPluginSkills } : { links: installLinks(side), side };
+    // In order: the first unreadable entry named is the first marketplace's, deterministically.
+    await forEachInOrder(marketplaces, ({ srcMpDir }) => proveTreeReadable(srcMpDir, proof));
+    const built = marketplaces.map(({ mpName, srcMpDir }) => {
+        const plugins = pluginsOf(run, side, srcMpDir, mpName, safePath.join(paths.marketplacesDir, mpName), rootDir);
+        return mode === 'dev' ? devMarketplace(mpName, srcMpDir, plugins, rootDir, side) : copiedMarketplace(mpName, srcMpDir, plugins, side, rootDir);
+    });
+    const replaces = packageJson.vat?.replaces;
+    const shipped = new Set(built.flatMap(({ install }) => install.plugins.map(({ pluginName }) => `${pluginName}@${install.marketplaceName}`)));
+    const planned = planPackageInstall({
+        marketplaces: built.map((each) => each.install),
+        version,
+        source: { source: 'npm', package: packageJson.name, version },
+        replacedPluginKeys: marketplaceNames.flatMap((mp) => (replaces?.plugins ?? []).map((plugin) => `${plugin}@${mp}`)),
+        force,
+        paths,
+    });
+    const flatSkills = (replaces?.flatSkills ?? []).map((name) => ({
+        op: 'remove',
+        dest: safePath.join(paths.skillsDir, assertSkillEntryName(name, 'vat.replaces.flatSkills')),
+        // The package says it replaces this legacy install: whatever is there goes.
+        ownership: { kind: 'force' },
+        label: `legacy flat skill ${name}`,
+    }));
+    return {
+        changes: [...planned.changes, ...flatSkills],
+        registry: planned.registry,
+        replaced: planned.replaced.map((each) => ({ ...each, reinstalled: shipped.has(each.pluginKey) })),
+        skills: built.flatMap((each) => each.skills),
+        issues: built.flatMap((each) => each.issues),
+    };
 }
 /**
- * Handle npm tarball (.tgz / .tar.gz) installation.
- * npm pack format: all package files are under a `package/` subdirectory in the tarball.
- * Extracts to a temp directory then delegates to the local install path.
+ * Plan an install of `input`, with no side effect: the tree changes, the registry edit,
+ * and what the run reports once they are done. `mode` is `dev` only for a plugin tree
+ * whose skills are linked, not copied (`--dev`).
  */
-async function handleTgzInstall(source, options, logger, startTime) {
-    const sourcePath = safePath.resolve(source);
-    logger.info(`📥 Installing skill from tarball: ${sourcePath}`);
-    if (!existsSync(sourcePath)) {
-        throw new Error(`Tarball not found: ${sourcePath}`);
-    }
-    const tempDir = await mkdtemp(safePath.join(normalizedTmpdir(), 'vat-install-tgz-'));
-    try {
-        logger.info('   Extracting tarball...');
-        await tar.extract({ file: sourcePath, cwd: tempDir });
-        // npm pack tarballs extract under package/ subdirectory
-        const packageDir = safePath.join(tempDir, 'package');
-        const extractedDir = existsSync(packageDir) ? packageDir : tempDir;
-        // Delegate to local install logic
-        const marketplacesDir = safePath.join(extractedDir, PLUGIN_MARKETPLACES_SUBPATH);
-        if (!options.userInstallWithoutPlugin && existsSync(marketplacesDir)) {
-            await installPluginTreeAndExit(extractedDir, marketplacesDir, sourcePath, 'tgz', startTime, logger, options.dryRun);
-        }
-        // Fallback: skills-only install
-        const { skills } = await readPackageJsonVatMetadata(extractedDir);
-        const skillsDir = options.skillsDir ?? getClaudeUserPaths().skillsDir;
-        const skillNames = options.name ? skills.filter(s => s === options.name) : skills;
-        for (const skillName of skillNames) {
-            const skillPath = safePath.join(extractedDir, 'dist', 'skills', skillNameToFsPath(skillName));
-            await installSkillFromPath(skillPath, skillName, options, logger);
+function planInstall(run, input, mode) {
+    if (input.kind === PLUGIN_TREE)
+        return planPluginTree(run, input, mode);
+    // A skills lane plans synchronously; a refusal still rejects the returned promise.
+    return Promise.resolve().then(() => planSkills(run, input.side, input.kind === 'skills'
+        ? input.skillNames.map((name) => ({ path: safePath.join(input.rootDir, 'dist', 'skills', skillNameToFsPath(name)), name, within: input.rootDir }))
+        // The skill directory IS the input (the operator's own, or VAT's staging of an archive): its own `within`.
+        : [{ path: input.skillPath, name: input.skillName, within: input.skillPath }]));
+}
+/** A package directory's plugin tree, as the input of {@link planInstall}. */
+function pluginTree(side, rootDir, packageJson) {
+    return { kind: PLUGIN_TREE, side, rootDir, packageJson };
+}
+/** What the decided plan did with each replaced plugin: a warning per directory kept, and a finding per one kept for an unexaminable sibling. */
+function replacedOutcome(run, planned, plan) {
+    const decided = planned.replaced.flatMap(({ pluginKey, index, reinstalled }) => {
+        const change = plan.changes[index];
+        return change === undefined ? [] : [{ pluginKey, change, reinstalled }];
+    });
+    for (const { pluginKey, change, reinstalled } of decided) {
+        // A key the package installs again stays registered: nothing to warn about.
+        if (change.action === 'keep' && change.existing !== 'absent' && !reinstalled) {
+            run.logger.warn(`   Plugin "${pluginKey}" is removed from the registry, but ${change.change.dest} is kept (${change.reason ?? 'kept'})`);
         }
-        const duration = Date.now() - startTime;
-        outputInstallSuccess(skillNames.map(name => ({ name, installPath: safePath.join(skillsDir, name) })), sourcePath, 'tgz', duration, logger, options.dryRun);
-        process.exit(ExitCode.OK);
-    }
-    finally {
-        await rm(tempDir, { recursive: true, force: true });
     }
+    return keptForSiblingFindings(decided.flatMap(({ change }) => (change.action === 'keep' && change.unexaminedSibling !== undefined ? [{ path: change.change.dest, sibling: change.unexaminedSibling }] : [])));
+}
+/** Record what the run did: called once the transaction committed, or once a dry run is planned. */
+function record(run, planned, findings) {
+    run.skills.push(...planned.skills);
+    run.issues.push(...planned.issues, ...findings);
 }
 /**
- * Prepare destination for a dev symlink: remove any existing entry if --force.
- * Throws if the path exists and --force was not passed.
+ * Carry out a planned install as ONE transaction: every tree staged and swapped, then the
+ * registry written (`afterSwap`); a failure before the registry is written puts every tree
+ * and registry file back. Under `--dry-run` the plan's lines are printed and nothing changes.
+ * What the run installed is recorded the moment the registry is written, so a failure after
+ * that (a replaced tree the OS will not delete) reports it.
  */
-async function prepareDevSymlinkDest(destPath, skillFsName, options) {
-    // The probe is the ONLY thing whose failure may read as "nothing there". A
-    // refusal on the probe, or a failed removal, stays loud: this used to catch
-    // everything and recognise its own throw by the words in its message.
+async function executeInstall(run, planned) {
+    let plan;
     try {
-        lstatSync(destPath);
+        plan = await planTreeChanges(planned.changes);
     }
     catch (error) {
-        if (isPathAbsentError(error))
-            return;
-        throw error;
-    }
-    if (!options.force) {
-        throw new Error(`Skill "${skillFsName}" already installed at ${destPath}.\n` +
-            `Use --force to overwrite.`);
-    }
-    if (!options.dryRun) {
-        await rm(destPath, { recursive: true, force: true });
-    }
+        throw notOwnedRefusal(occupiedRefusal(error));
+    }
+    const findings = replacedOutcome(run, planned, plan);
+    const prefix = run.dryRun ? '[dry-run] ' : '';
+    for (const line of plan.describe())
+        run.logger.info(`   ${prefix}${line}`);
+    if (run.dryRun) {
+        record(run, planned, findings);
+        return;
+    }
+    const { warnings } = await applyTreePlan(plan, {
+        afterSwap: async () => {
+            await planned.registry?.apply();
+            record(run, planned, findings);
+        },
+    });
+    for (const { path, message } of warnings)
+        leftover(run, leftoverIssue(message, path));
+}
+/** A marketplace directory VAT cannot prove it installed from this package, as the invocation's refusal saying how to proceed; anything else as itself. */
+function notOwnedRefusal(error) {
+    if (!isVatError(error, TREE_DEST_NOT_OWNED_CODE))
+        return error;
+    return new CommandRefusalError('USAGE_INVALID', `${error.message}. Nothing was changed. Uninstall what is there first — \`vat claude plugin uninstall <plugin>@<marketplace>\` when VAT installed it, Claude Code's /plugin when it did — or pass --force to replace it.`, { cause: error });
+}
+/** A leftover of a complete install, as a warning naming it. */
+function leftover(run, issue) {
+    run.logger.warn(`   ${issue.message}`);
+    run.issues.push(issue);
+}
+/** Plan and execute `input`: every lane's last step. */
+async function install(run, input, mode) {
+    await executeInstall(run, await planInstall(run, input, mode));
+}
+/** Run `work` in a fresh `$TMPDIR` staging directory (VAT's own: `environment`), disposed of after: see {@link inStaging}. */
+function stagedIn(run, prefix, work) {
+    return inStaging(prefix, async (dir) => {
+        run.roots.environment.push(dir);
+        await work(dir);
+    }, (issue) => leftover(run, issue));
 }
+// --- the lanes --------------------------------------------------------------------------------
 /**
- * Symlink a single skill directory from dist/skills/{name} into the plugin tree.
- * Returns install info, or null when the skill is not built (skips with a warning).
+ * The package at `rootDir`, as `readPackageJson` is told of it: its side, and what the user named —
+ * the directory itself, or, where `rootDir` is VAT's staging (`environment`: a staging directory
+ * under $TMPDIR names nothing they have), the archive or npm spec the run was given.
  */
-async function symlinkDevSkill(skillFsName, destSkillsDir, cwd, pluginName, options, logger) {
-    const srcSkillPath = safePath.resolve(cwd, 'dist', 'skills', skillFsName);
-    const destSkillPath = safePath.join(destSkillsDir, skillFsName);
-    if (!existsSync(srcSkillPath)) {
-        logger.info(`   Warning: skill not built at ${srcSkillPath} — skipping symlink`);
-        return null;
-    }
-    await prepareDevSymlinkDest(destSkillPath, skillFsName, options);
-    if (!options.dryRun) {
-        try {
-            // eslint-disable-next-line local/no-bare-symlink-in-tests -- eyes open: `handleDevInstall` refuses win32 upstream, so the Windows privilege hazard the rule names cannot be reached here.
-            await symlink(srcSkillPath, destSkillPath, 'dir');
-        }
-        catch (error) {
-            // ⚠️ POSIX-only in practice: `handleDevInstall` throws on win32 before
-            // this call chain begins, so Windows-specific handling here would be dead
-            // code — an earlier revision added exactly that. Making `--dev` work on
-            // Windows means changing that guard (a junction needs no elevation), not
-            // this catch. Not falling back to a copy either — dev mode exists so a
-            // rebuild is picked up live, and a copy would quietly stop that.
-            //
-            // ⚠️ This throws mid-loop, after `devInstallMarketplace` already removed
-            // the previous marketplace directory and `devInstallPlugin` copied the
-            // non-skill content. Earlier skills are linked, later ones are not, and
-            // `registerPlugin` never runs — so the tree is on disk but unregistered.
-            // Recoverable by re-running, which starts over.
-            const detail = error instanceof Error ? error.message : String(error);
-            throw new Error(`Could not symlink ${skillFsName} to ${destSkillPath}: ${detail}\n` +
-                'Check that the destination directory is writable. This install is now ' +
-                'incomplete — re-run the same command to start over.');
-        }
-    }
-    logger.info(`   Symlinked: ${safePath.relative(cwd, destSkillPath)} → ${srcSkillPath}`);
-    return {
-        name: `${pluginName}:${skillFsName}`,
-        installPath: destSkillPath,
-        sourcePath: srcSkillPath,
-    };
+function packageOf(run, rootDir, side) {
+    const named = side === 'environment' && run.source !== undefined ? `The package ${run.source.label}` : `The package directory ${rootDir}`;
+    return { side, label: named };
+}
+/** A package directory's install: its plugin tree, or (none, or `--user-install-without-plugin`) its declared skills. */
+async function installPackageDir(run, rootDir, side) {
+    if (run.options.userInstallWithoutPlugin !== true && pathPresent(safePath.join(rootDir, PLUGIN_MARKETPLACES_SUBPATH), { follow: rootDir }, everywhere(side), 'confirmed')) {
+        run.logger.info('   Plugin detected — installing via Claude plugin system');
+        await install(run, pluginTree(side, rootDir, await readPackageJson(rootDir, packageOf(run, rootDir, side))), 'copy');
+        return;
+    }
+    const { packageJson, skills } = await readPackageJsonVatMetadata(rootDir, packageOf(run, rootDir, side));
+    await install(run, { kind: 'skills', side, rootDir, skillNames: selectSkills(skills, run.options.name, packageJson.name) }, 'copy');
 }
 /**
- * Symlink all skill directories from a plugin's source skills dir into the destination.
+ * Handle npm package installation
  */
-async function symlinkPluginSkills(srcPluginDir, destPluginDir, pluginName, cwd, options, logger) {
-    const installed = [];
-    const srcSkillsDir = safePath.join(srcPluginDir, 'skills');
-    if (!existsSync(srcSkillsDir)) {
-        return installed;
-    }
-    const destSkillsDir = safePath.join(destPluginDir, 'skills');
-    if (!options.dryRun) {
-        await mkdir(destSkillsDir, { recursive: true });
-    }
-    // Followed: a skill directory that is itself a link is still a skill to link.
-    const skillEntries = readdirSync(srcSkillsDir, { withFileTypes: true })
-        .filter(d => direntKindFollowingSync(srcSkillsDir, d) === 'directory');
-    for (const skillEntry of skillEntries) {
-        const result = await symlinkDevSkill(skillEntry.name, destSkillsDir, cwd, pluginName, options, logger);
-        if (result) {
-            installed.push(result);
-        }
-    }
-    return installed;
+async function handleNpmInstall(source, run) {
+    const { logger } = run;
+    const packageName = source.startsWith('npm:') ? source.slice(4) : source;
+    setSource(run, `npm:${packageName}`, 'npm');
+    logger.info(`📥 Installing skill from npm: ${packageName}`);
+    await stagedIn(run, 'vat-install-npm-', async (tempDir) => {
+        logger.info('   Downloading package...');
+        const extractedPath = await downloadNpmPackage(packageName, tempDir);
+        await installPackageDir(run, extractedPath, 'environment');
+    });
 }
 /**
- * Dev-install a single plugin: copy non-skill content, symlink skills, register.
+ * Handle local directory installation
  */
-async function devInstallPlugin(ctx, cwd, options, logger) {
-    const { mpName, pluginName, srcPluginDir, destPluginDir, packageName, version, paths } = ctx;
-    if (!options.dryRun) {
-        await mkdir(destPluginDir, { recursive: true });
-    }
-    // Copy non-skill entries (e.g. .claude-plugin/)
-    for (const entry of readdirSync(srcPluginDir, { withFileTypes: true })) {
-        if (entry.name !== 'skills' && !options.dryRun) {
-            const srcEntry = safePath.join(srcPluginDir, entry.name);
-            const destEntry = safePath.join(destPluginDir, entry.name);
-            cpSync(srcEntry, destEntry, { recursive: true, force: true });
-        }
-    }
-    const installed = await symlinkPluginSkills(srcPluginDir, destPluginDir, pluginName, cwd, options, logger);
-    // Register plugin in Claude plugin registry
-    if (!options.dryRun) {
-        await registerPlugin(mpName, pluginName, destPluginDir, version, packageName, paths, logger);
-    }
-    return installed;
+async function handleLocalInstall(source, run) {
+    const { options, logger } = run;
+    const sourcePath = safePath.resolve(source); // The operator's own argument: every probe beneath it passes it as `within`.
+    setSource(run, `local:${sourcePath}`, 'local');
+    run.roots.source.push(sourcePath);
+    logger.info(`📥 Installing skill from directory: ${sourcePath}`);
+    // A package: its pre-built plugin tree, or each skill its vat.skills declares.
+    const marketplacesDir = safePath.join(sourcePath, PLUGIN_MARKETPLACES_SUBPATH);
+    if ((!options.userInstallWithoutPlugin && pathPresent(marketplacesDir, { follow: sourcePath }, everywhere('source'), 'confirmed')) || pathPresent(safePath.join(sourcePath, 'package.json'), { follow: sourcePath }, everywhere('source'), 'confirmed')) {
+        await installPackageDir(run, sourcePath, 'source');
+        return;
+    }
+    // Plain skill directory: it must hold a SKILL.md, or any directory would
+    // install as a skill. A source that names nothing keeps its own refusal below.
+    if (pathPresent(sourcePath, { follow: sourcePath }, everywhere('source'), 'confirmed') && !pathPresent(safePath.join(sourcePath, 'SKILL.md'), { follow: sourcePath }, everywhere('source'), 'confirmed')) {
+        throw new CommandRefusalError('USAGE_INVALID', `No SKILL.md found at the root of: ${sourcePath}`);
+    }
+    // The package.json branch above installs each skill under its declared name;
+    // do the same here rather than under whatever the source directory is called.
+    const skillName = options.name ??
+        readDeclaredSkillName(safePath.join(sourcePath, 'SKILL.md')) ??
+        basename(sourcePath);
+    await install(run, { kind: 'skill-dir', side: 'source', skillPath: sourcePath, skillName }, 'copy');
 }
 /**
- * Dev-install a single marketplace: reset dir, copy non-plugin content, install each plugin.
+ * Handle ZIP file installation
  */
-async function devInstallMarketplace(mpName, srcMpDir, packageInfo, cwd, options, logger) {
-    const paths = getClaudeUserPaths();
-    const destMpDir = safePath.join(paths.marketplacesDir, mpName);
-    const installed = [];
-    if (!options.dryRun) {
-        await rm(destMpDir, { recursive: true, force: true });
-        await mkdir(destMpDir, { recursive: true });
-    }
-    logger.info(`   Marketplace: ${mpName} → ${destMpDir}`);
-    // Copy non-plugin content (e.g. .claude-plugin/marketplace.json)
-    for (const entry of readdirSync(srcMpDir, { withFileTypes: true })) {
-        if (entry.name !== 'plugins' && !options.dryRun) {
-            const srcEntry = safePath.join(srcMpDir, entry.name);
-            const destEntry = safePath.join(destMpDir, entry.name);
-            cpSync(srcEntry, destEntry, { recursive: true, force: true });
-        }
-    }
-    const pluginsDir = safePath.join(srcMpDir, 'plugins');
-    for (const pluginName of listSubdirectories(pluginsDir)) {
-        const results = await devInstallPlugin({
-            mpName,
-            pluginName,
-            srcPluginDir: safePath.join(pluginsDir, pluginName),
-            destPluginDir: safePath.join(destMpDir, 'plugins', pluginName),
-            packageName: packageInfo.name,
-            version: packageInfo.version,
-            paths,
-        }, cwd, options, logger);
-        installed.push(...results);
-    }
-    return installed;
+async function handleZipInstall(source, run) {
+    const { options, logger } = run;
+    const sourcePath = safePath.resolve(source);
+    setSource(run, sourcePath, 'zip');
+    run.roots.source.push(sourcePath);
+    logger.info(`📥 Installing skill from ZIP: ${sourcePath}`);
+    assertSourceFile(sourcePath);
+    // Extracted to staging first, through the one archive primitive: an archive it refuses — an
+    // entry that does not inflate, a link, two entries one name — is refused with nothing under
+    // ~/.claude changed.
+    await stagedIn(run, 'vat-install-zip-', async (tempDir) => {
+        logger.info('   Extracting ZIP...');
+        const extracted = safePath.join(tempDir, 'skill');
+        await withFsFault({ side: 'environment', action: 'create the staging directory', path: extracted }, () => fs.mkdir(extracted));
+        // The one extraction of a skill ZIP, shared with `vat skills install` and the org upload: the
+        // skill is at the top level or in the single top-level folder, installed under the name its SKILL.md declares.
+        const skillPath = await extractSkillZip(sourcePath, extracted);
+        const skillName = options.name ?? readDeclaredSkillName(safePath.join(skillPath, 'SKILL.md')) ?? basename(sourcePath, '.zip');
+        await install(run, { kind: 'skill-dir', side: 'environment', skillPath, skillName }, 'copy');
+    });
+}
+/**
+ * Handle npm tarball (.tgz / .tar.gz) installation.
+ * npm pack format: all package files are under a `package/` subdirectory in the tarball.
+ * Extracts to a temp directory then installs the plugin tree, or the declared skills.
+ */
+async function handleTgzInstall(source, run) {
+    const { logger } = run;
+    const sourcePath = safePath.resolve(source);
+    setSource(run, sourcePath, 'tgz');
+    run.roots.source.push(sourcePath);
+    logger.info(`📥 Installing skill from tarball: ${sourcePath}`);
+    assertSourceFile(sourcePath);
+    await stagedIn(run, 'vat-install-tgz-', async (tempDir) => {
+        logger.info('   Extracting tarball...');
+        // One entry at a time: when the extraction throws, nothing is still being written under the staging.
+        await extractArchive({ file: sourcePath, side: 'source' }, tempDir, { format: 'tar', limits: ARCHIVE_LIMITS });
+        // npm pack tarballs extract under package/ subdirectory
+        const packageDir = safePath.join(tempDir, 'package');
+        await installPackageDir(run, pathPresent(packageDir, { follow: tempDir }, everywhere('environment'), 'confirmed') ? packageDir : tempDir, 'environment');
+    });
 }
 /**
  * Handle development mode installation via plugin tree (symlinks).
@@ -522,292 +761,113 @@ async function devInstallMarketplace(mpName, srcMpDir, packageInfo, cwd, options
  * - Copies non-skill content (.claude-plugin/ dirs) to ~/.claude/plugins/
  * - For each skill directory under plugins/{plugin}/skills/{name}/, creates a
  *   symlink to the corresponding dist/skills/{name}/ directory
- * - Registers each plugin in the Claude plugin registry (same as copyPluginTree)
+ * - Registers each plugin in the Claude plugin registry
  *
- * Skills appear in Claude Code as {plugin}:{skill} instead of the flat {skill} name.
+ * Each marketplace is ONE replace, built whole in staging and swapped in: the installed
+ * marketplace is never deleted first. Skills appear in Claude Code as {plugin}:{skill}.
  */
-async function handleDevInstall(options, logger, startTime) {
+async function handleDevInstall(run) {
+    const { options, logger } = run;
     if (process.platform === 'win32') {
-        throw new Error('--dev (symlink) not supported on Windows.\n' +
+        throw new CommandRefusalError('NOT_IMPLEMENTED', '--dev (symlink) not supported on Windows.\n' +
             'Use copy mode (omit --dev) or WSL for development.');
     }
     // --cwd only applies to --dev mode; other paths (npm postinstall, etc.) use process.cwd()
-    const cwd = options.cwd ? safePath.resolve(options.cwd) : process.cwd();
+    const cwd = options.cwd ? safePath.resolve(options.cwd) : process.cwd(); // The operator's own: every probe beneath it passes it as `within`.
+    run.roots.source.push(cwd);
     if (options.build) {
         runBuild(cwd, logger);
     }
     // Check for pre-built plugin tree
     const marketplacesDir = safePath.join(cwd, PLUGIN_MARKETPLACES_SUBPATH);
-    if (!existsSync(marketplacesDir)) {
-        throw new Error(`Plugin tree not found at ${marketplacesDir}\n` +
+    if (!pathPresent(marketplacesDir, { follow: cwd }, everywhere('source'), 'confirmed')) {
+        throw new CommandRefusalError('USAGE_INVALID', `Plugin tree not found at ${marketplacesDir}\n` +
             `Run: vat build first (builds the plugin tree)`);
     }
-    // Read package.json for package name/version
-    const pkgRaw = readFileSync(safePath.join(cwd, PACKAGE_JSON), 'utf-8');
-    const packageJson = JSON.parse(pkgRaw);
+    const packageJson = await readPackageJson(cwd, packageOf(run, cwd, 'source'));
+    setSource(run, packageJson.name, 'dev', true);
     logger.info(`📥 Dev-installing plugin tree from ${packageJson.name}`);
-    const packageInfo = { name: packageJson.name, version: packageJson.version ?? '0.0.0' };
-    const installed = [];
-    // Remove old plugins/flat skills this package replaces, before installing
-    if (packageJson.vat?.replaces) {
-        const paths = getClaudeUserPaths();
-        const marketplaceNames = listSubdirectories(marketplacesDir);
-        await executeReplaces(packageJson.vat.replaces, marketplaceNames, paths, options.dryRun ?? false, logger);
-    }
-    for (const mpName of listSubdirectories(marketplacesDir)) {
-        const srcMpDir = safePath.join(marketplacesDir, mpName);
-        const results = await devInstallMarketplace(mpName, srcMpDir, packageInfo, cwd, options, logger);
-        installed.push(...results);
-    }
-    const duration = Date.now() - startTime;
-    outputDevSuccess(installed, packageJson.name, duration, logger, options.dryRun);
-    process.exit(ExitCode.OK);
+    await install(run, pluginTree('source', cwd, packageJson), 'dev');
 }
 /**
- * Shell out to vat build (skills + claude plugin tree)
+ * Shell out to `vat build` (skills + claude plugin tree) in `cwd`.
+ *
+ * Its stdout goes to this process's stderr ({@link BUILD_CHILD_STDIO}), never
+ * through a buffered pipe. A build that exits non-zero, or one that cannot be
+ * started, stops the install before anything is installed: `RUN_INCOMPLETE`.
+ *
+ * @throws A `RUN_INCOMPLETE` {@link CommandRefusalError}
  */
-function runBuild(cwd, logger) {
+export function runBuild(cwd, logger) {
     logger.info('🔨 Building first (skills + plugin tree)...');
     const binPath = safePath.resolve(safePath.join(import.meta.dirname, '../../../../bin/vat.js'));
-    safeExecSync('node', [binPath, 'build'], {
-        cwd,
-        stdio: ['inherit', 'inherit', 'inherit'],
-    });
+    try {
+        safeExecSync(process.execPath, [binPath, 'build'], { cwd, stdio: BUILD_CHILD_STDIO });
+    }
+    catch (error) {
+        const why = isVatError(error, 'COMMAND_EXECUTION')
+            ? 'vat build failed — its output above says why'
+            : `vat build could not be run: ${String(error)}`;
+        throw new CommandRefusalError('RUN_INCOMPLETE', `${why} (in ${cwd}), so nothing was installed.`, { cause: error });
+    }
     logger.info('');
 }
 /**
  * Handle npm postinstall hook
  */
-async function handleNpmPostinstall(options, logger, startTime) {
+async function handleNpmPostinstall(run) {
+    const { options, logger } = run;
     logger.info(`📥 Running npm postinstall hook`);
+    // The postinstall lane resolves its source (the package directory) whether or
+    // not it installs: a skip is an answer, `ok` with no skills — never a failure
+    // inside `npm install -g`.
+    const cwd = process.cwd(); // The package npm runs us in: every probe beneath it passes it as `within`.
+    setSource(run, cwd, 'npm-postinstall');
+    run.roots.source.push(cwd);
     if (!isGlobalNpmInstall()) {
         logger.info('   Skipping: Not a global npm install');
-        process.exit(ExitCode.OK);
+        return;
     }
-    const cwd = process.cwd();
-    // Check for pre-built plugin tree (dist/.claude/plugins/marketplaces/)
-    const marketplacesDir = safePath.join(cwd, PLUGIN_MARKETPLACES_SUBPATH);
-    const hasPluginTree = existsSync(marketplacesDir);
     if (!options.userInstallWithoutPlugin) {
-        if (hasPluginTree) {
-            const pkgRaw = readFileSync(safePath.join(cwd, PACKAGE_JSON), 'utf-8');
-            const packageJson = JSON.parse(pkgRaw);
-            logger.info(`   Package: ${packageJson.name}@${packageJson.version ?? 'unknown'}`);
-            logger.info(`   Plugin tree detected — copying to ~/.claude/plugins/`);
-            const installedSkills = await copyPluginTree(marketplacesDir, packageJson, logger, options.dryRun);
-            const duration = Date.now() - startTime;
-            logger.info(`✅ Installed plugin from ${packageJson.name} (${installedSkills.length} skill(s))`);
-            logger.info(`   Duration: ${duration}ms`);
-        }
-        else {
+        // Check for pre-built plugin tree (dist/.claude/plugins/marketplaces/)
+        const marketplacesDir = safePath.join(cwd, PLUGIN_MARKETPLACES_SUBPATH);
+        if (!pathPresent(marketplacesDir, { follow: cwd }, everywhere('source'), 'confirmed')) {
             logger.info(`   No plugin tree found at dist/.claude/plugins/marketplaces/`);
             logger.info(`   Run 'vat build' to generate plugin artifacts before publishing.`);
             logger.info(`   Skipping install — no skills registered.`);
+            return;
         }
-        process.exit(ExitCode.OK);
+        const packageJson = await readPackageJson(cwd, packageOf(run, cwd, 'source'));
+        logger.info(`   Package: ${packageJson.name}@${packageJson.version ?? 'unknown'}`);
+        logger.info(`   Plugin tree detected — copying to ~/.claude/plugins/`);
+        await install(run, pluginTree('source', cwd, packageJson), 'copy');
+        return;
     }
     // --user-install-without-plugin: install skills directly to ~/.claude/skills/
-    const { packageJson, skills } = await readPackageJsonVatMetadata(cwd);
-    logger.info(`   Package: ${packageJson.name}@${packageJson.version}`);
+    const { packageJson, skills } = await readPackageJsonVatMetadata(cwd, packageOf(run, cwd, 'source'));
+    logger.info(`   Package: ${packageJson.name}@${packageJson.version ?? 'unknown'}`);
     logger.info(`   Skills found: ${skills.length}`);
-    for (const skillName of skills) {
-        const skillPath = safePath.join(cwd, 'dist', 'skills', skillNameToFsPath(skillName));
-        await installSkillFromPath(skillPath, skillName, options, logger);
-    }
-    const duration = Date.now() - startTime;
-    logger.info(`✅ Installed ${skills.length} skill(s) from ${packageJson.name}`);
-    logger.info(`   Duration: ${duration}ms`);
-    process.exit(ExitCode.OK);
-}
-/**
- * Execute vat.replaces cleanup before installing the new plugin.
- *
- * Removes old plugin registrations and legacy flat-skill installs that this
- * package now supersedes. Runs before the new plugin is copied/symlinked so
- * Claude Code never sees stale duplicate entries.
- *
- * Idempotent — uninstallPlugin handles "not found" gracefully.
- */
-export async function removeFlatSkill(skillPath, logger) {
-    logger.info(`   Removing legacy flat skill: ${toForwardSlash(skillPath)}`);
-    await rm(skillPath, { recursive: true, force: true });
-}
-export function logFlatSkillRemoval(skillPath, logger) {
-    logger.info(`   [dry-run] Would remove legacy flat skill: ${toForwardSlash(skillPath)}`);
-}
-export async function removeOldPlugins(oldPlugins, marketplaceNames, paths, dryRun, logger) {
-    for (const mp of marketplaceNames) {
-        for (const oldPlugin of oldPlugins ?? []) {
-            const pluginKey = `${oldPlugin}@${mp}`;
-            if (dryRun) {
-                logger.info(`   [dry-run] Would uninstall old plugin: ${pluginKey}`);
-            }
-            else {
-                logger.info(`   Removing old plugin: ${pluginKey}`);
-                await uninstallPlugin({ pluginKey, paths, dryRun: false });
-            }
-        }
-    }
-}
-export async function executeReplaces(replaces, marketplaceNames, paths, dryRun, logger) {
-    // Remove old plugin entries from all marketplaces this package ships into
-    await removeOldPlugins(replaces.plugins, marketplaceNames, paths, dryRun, logger);
-    // Remove legacy flat-skill installs from ~/.claude/skills/<name>
-    for (const skillName of replaces.flatSkills ?? []) {
-        // The entry comes from the INSTALLED package's package.json, and this is
-        // an `rm -rf` with no flag in front of it: `"../victim"` used to remove a
-        // sibling of the skills dir (with the default paths, `"../.."` is $HOME).
-        const skillPath = safePath.join(paths.skillsDir, assertSkillEntryName(skillName, 'vat.replaces.flatSkills'));
-        let pathExists = false;
-        try {
-            lstatSync(skillPath); // throws if path itself doesn't exist (doesn't follow symlinks)
-            pathExists = true;
-        }
-        catch (error) {
-            // Path doesn't exist — nothing to remove. One the OS refuses to examine
-            // is not "nothing to remove": the legacy install is still there and a
-            // silent skip leaves it beside its replacement.
-            if (!isPathAbsentError(error))
-                throw error;
-        }
-        if (pathExists) {
-            if (dryRun) {
-                logFlatSkillRemoval(skillPath, logger);
-            }
-            else {
-                await removeFlatSkill(skillPath, logger);
-            }
-        }
-    }
-}
-/**
- * Copy pre-built plugin tree to ~/.claude/plugins/ and update registry.
- *
- * This is a "dumb copy" — the dist/.claude/plugins/marketplaces/ tree mirrors
- * the target ~/.claude/plugins/marketplaces/ structure exactly. No path rewriting,
- * no assembly, no skill resolution. Just recursive copy + registry update.
- */
-async function copyPluginTree(marketplacesDir, packageJson, logger, dryRun) {
-    const paths = getClaudeUserPaths();
-    const version = packageJson.version ?? '0.0.0';
-    const marketplaceNames = listSubdirectories(marketplacesDir);
-    const installedSkills = [];
-    // Remove any old plugins/flat skills this package replaces, before installing
-    if (packageJson.vat?.replaces) {
-        await executeReplaces(packageJson.vat.replaces, marketplaceNames, paths, dryRun ?? false, logger);
-    }
-    for (const mpName of marketplaceNames) {
-        const srcMpDir = safePath.join(marketplacesDir, mpName);
-        const destMpDir = safePath.join(paths.marketplacesDir, mpName);
-        // Replace the marketplace directory entirely so skills removed from the
-        // package do not persist in the user's Claude installation.
-        logger.info(`   Copying marketplace: ${mpName} → ${destMpDir}`);
-        await rm(destMpDir, { recursive: true, force: true });
-        await mkdir(destMpDir, { recursive: true });
-        cpSync(srcMpDir, destMpDir, { recursive: true, force: true });
-        // Register each plugin and collect installed skill names
-        for (const pluginName of listSubdirectories(safePath.join(srcMpDir, 'plugins'))) {
-            const pluginDir = safePath.join(destMpDir, 'plugins', pluginName);
-            await registerPlugin(mpName, pluginName, pluginDir, version, packageJson.name, paths, logger);
-            const skillNames = listSubdirectories(safePath.join(srcMpDir, 'plugins', pluginName, 'skills'));
-            for (const skillName of skillNames) {
-                installedSkills.push({
-                    name: skillName,
-                    installPath: safePath.join(destMpDir, 'plugins', pluginName, 'skills', skillName),
-                });
-            }
-        }
-    }
-    return installedSkills;
-}
-/**
- * Prepare plugins directory and check for conflicts
- */
-async function prepareInstallation(skillName, options) {
-    const skillsDir = options.skillsDir ?? getClaudeUserPaths().skillsDir;
-    // The declared name is author-controlled (SKILL.md `name:`, package.json
-    // `vat.skills[]`) and `--force` turns this path into an `rm -rf`.
-    const installPath = safePath.join(skillsDir, assertSkillEntryName(skillName, 'skill name'));
-    let exists = false;
-    try {
-        lstatSync(installPath);
-        exists = true;
-    }
-    catch (error) {
-        // Does not exist. A refusal is not that: it used to read as "free", and
-        // the extraction that followed then met the same refusal without a name.
-        if (!isPathAbsentError(error))
-            throw error;
-    }
-    if (exists && !options.force) {
-        throw new Error(`Skill already exists at ${installPath}. Use --force to overwrite.`);
-    }
-    if (exists && options.force && !options.dryRun) {
-        await rm(installPath, { recursive: true, force: true });
-    }
-    if (!options.dryRun) {
-        await mkdir(skillsDir, { recursive: true });
-    }
-    return { skillsDir, installPath };
-}
-/**
- * Install skill from a path to plugins directory
- */
-async function installSkillFromPath(skillPath, skillName, options, logger) {
-    if (!existsSync(skillPath)) {
-        throw new Error(`Skill path not found: ${skillPath}`);
-    }
-    const { installPath } = await prepareInstallation(skillName, options);
-    if (!options.dryRun) {
-        logger.info(`   Installing ${skillName}...`);
-        cpSync(skillPath, installPath, { recursive: true, force: true });
-    }
-}
-/**
- * Output success YAML for dev install
- */
-function outputDevSuccess(installed, packageName, duration, logger, dryRun) {
-    writeYamlHeader(dryRun);
-    process.stdout.write(`sourceType: dev\n`);
-    process.stdout.write(`package: "${packageName}"\n`);
-    process.stdout.write(`skillsInstalled: ${installed.length}\n`);
-    process.stdout.write(`symlink: true\n`);
-    process.stdout.write(`skills:\n`);
-    for (const skill of installed) {
-        process.stdout.write(`  - name: ${skill.name}\n`);
-        process.stdout.write(`    installPath: ${skill.installPath}\n`);
-        process.stdout.write(`    sourcePath: ${skill.sourcePath}\n`);
-    }
-    process.stdout.write(`duration: ${duration}ms\n`);
-    if (dryRun) {
-        logger.info(`\n✅ Dry-run complete: ${installed.length} skill(s) would be symlinked`);
-    }
-    else {
-        logger.info(`\n✅ Dev-installed ${installed.length} skill(s) via symlink`);
-        logger.info(`   After rebuilding, run /reload-plugins in Claude Code`);
-    }
-}
-/**
- * Output success YAML for install
- */
-function outputInstallSuccess(skills, source, sourceType, duration, logger, dryRun) {
-    writeYamlHeader(dryRun);
-    process.stdout.write(`source: ${source}\n`);
-    process.stdout.write(`sourceType: ${sourceType}\n`);
-    process.stdout.write(`skillsInstalled: ${skills.length}\n`);
-    process.stdout.write(`skills:\n`);
-    for (const skill of skills) {
-        process.stdout.write(`  - name: ${skill.name}\n`);
-        process.stdout.write(`    installPath: ${skill.installPath}\n`);
-    }
-    process.stdout.write(`duration: ${duration}ms\n`);
-    if (dryRun) {
-        logger.info(`\n✅ Dry-run complete: ${skills.length} skill(s) would be installed`);
-    }
-    else {
-        logger.info(`\n✅ Installed ${skills.length} skill(s)`);
-        logger.info(`\n💡 Run 'vat claude plugin list' to verify installation`);
-        logger.info(`   Restart Claude Code or run /reload-plugins to use the new skill`);
-    }
+    await install(run, { kind: 'skills', side: 'source', rootDir: cwd, skillNames: skills }, 'copy');
 }
+/** Test-facing seam: the pure decisions of this module, reached by its unit tests. */
+export const __internal = {
+    assertInstallTarget,
+    assertPackagePluginNames,
+    boundaryOf,
+    executeInstall,
+    leftover,
+    logInstallOutcome,
+    newInstallRun,
+    notPlugins,
+    notPluginSkills,
+    notSkills,
+    outcomeOf,
+    planInstall,
+    record,
+    replacedOutcome,
+    selectSkills,
+    setSource,
+    skillNameToFsPath,
+    stagedIn,
+};
 //# sourceMappingURL=install.js.map