@hashicorp/kits 0.1.3 → 0.1.5

package/dist/cli/install.js

@@ -6,18 +6,21 @@
  */
 import { ExitCode } from "./types.js";
 import * as clack from "@clack/prompts";
+import fs from "node:fs/promises";
 import path from "node:path";
 import pc from "picocolors";
 import { fetchSource, scanKits, filterKitsByName as filterDiscoveryKitsByName, getMissingKitNames as getDiscoveryMissingKitNames, NoFetcherError, SourceParseError, } from "../discovery/index.js";
 import { resolvePrimitiveReferences, PrimitivesRegistryLoader, validateCliEnvFlags, mergeEnvDefs, resolveEnvVarsFromConfig, } from "../resolution/index.js";
 import { hashMcpConfig } from "../core/mcp-instance.js";
 import { hashHookConfig } from "../core/hook-instance.js";
-import { readManifest } from "../manifest/read.js";
-import { writeManifest } from "../manifest/write.js";
-import { createEmptyManifest, } from "../manifest/types.js";
+import { readLockfile } from "../lockfile/read.js";
+import { writeLockfile } from "../lockfile/write.js";
+import { createEmptyLockfile, } from "../lockfile/types.js";
+import { readManifestFile } from "../manifest/read.js";
+import { hashManifest } from "../manifest/hash.js";
 import { getAdapterRegistry } from "../adapters/index.js";
 import { debugLog, enableDebugLogging, getDebugLogPath, checkDebugLogWritable, } from "../core/debug.js";
-import { expandPath } from "../adapters/file-operations.js";
+import { expandPath, remove } from "../adapters/file-operations.js";
 import { 
 // TUI components
 intro, outroSuccess, outroError, outroCancel, logInfo, logError, confirmInstallPlan, displayInstallPlanSummary, 
@@ -28,7 +31,7 @@ selectHarnesses, warnMissingHarnesses, displayNoHarnessesDetected, filterHarness
 // Kit selection
 selectKits, displayAvailableKits, displayKitsJson, displayNoKitsFound, displayMissingKits, filterKitsByName, 
 // Compatibility
-runCompatibilityCheck, buildCompatibilityMatrix, hasIncompatibilities, 
+runCompatibilityCheck, buildCompatibilityMatrix, hasIncompatibilities, getCompatiblePairs, 
 // Scope selection
 selectScope, 
 // Summary
@@ -77,12 +80,88 @@ function getScopeFromOptions(options) {
     }
     return null;
 }
+async function fileExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function deriveProjectRootFromManifestPath(manifestPath) {
+    const resolved = path.resolve(manifestPath);
+    const parentDir = path.basename(path.dirname(resolved));
+    if (parentDir === ".agents") {
+        return { projectRoot: path.dirname(path.dirname(resolved)) };
+    }
+    return {
+        projectRoot: path.dirname(resolved),
+        warning: "Project-scope kits.json is not under a .agents/ directory; using the manifest's parent directory as the project root.",
+    };
+}
+async function resolveManifestTarget(source) {
+    const expanded = expandPath(source);
+    try {
+        const stat = await fs.stat(expanded);
+        if (stat.isFile()) {
+            if (path.basename(expanded) !== "kits.json") {
+                return null;
+            }
+            const manifest = await readManifestFile(expanded);
+            return { manifestPath: expanded, manifest };
+        }
+        if (stat.isDirectory()) {
+            const nestedPath = path.join(expanded, ".agents", "kits.json");
+            if (await fileExists(nestedPath)) {
+                const manifest = await readManifestFile(nestedPath);
+                return { manifestPath: nestedPath, manifest };
+            }
+            const directPath = path.join(expanded, "kits.json");
+            if (await fileExists(directPath)) {
+                const manifest = await readManifestFile(directPath);
+                return { manifestPath: directPath, manifest };
+            }
+        }
+    }
+    catch {
+        // Not a local path; treat as repository source.
+    }
+    return null;
+}
+function buildLockedVersionMap(lockfile) {
+    const locked = new Map();
+    for (const harnessEntry of Object.values(lockfile.harnesses)) {
+        if (!harnessEntry)
+            continue;
+        for (const kit of Object.values(harnessEntry.kits)) {
+            for (const primitive of kit.primitives) {
+                if (!primitive.version)
+                    continue;
+                const key = `${primitive.type}:${primitive.name}`;
+                if (!locked.has(key)) {
+                    locked.set(key, primitive.version);
+                }
+            }
+        }
+    }
+    return locked;
+}
+function mergeMcpInstanceOverrides(base, overrides) {
+    const merged = { ...(base ?? {}) };
+    if (overrides) {
+        for (const [kitName, kitOverrides] of Object.entries(overrides)) {
+            merged[kitName] = { ...(merged[kitName] ?? {}), ...kitOverrides };
+        }
+    }
+    return merged;
+}
 /**
  * Run the install command.
  */
 export async function runInstall(source, options) {
     const isInteractive = !options.yes && !options.json;
-    let fetchResult;
+    const fetchResults = [];
     enableDebugLogging(options.debug ?? false);
     if (options.debug) {
         const debugCheck = checkDebugLogWritable();
@@ -104,11 +183,13 @@ export async function runInstall(source, options) {
             options: {
                 agent: options.agent,
                 kit: options.kit,
+                alias: options.alias,
                 list: options.list ?? false,
                 yes: options.yes ?? false,
                 dryRun: options.dryRun ?? false,
                 json: options.json ?? false,
                 verbose: options.verbose ?? false,
+                overwrite: options.overwrite ?? false,
                 global: options.global ?? false,
                 project: options.project ?? false,
                 envKeys: options.env ? Object.keys(options.env) : [],
@@ -116,12 +197,82 @@ export async function runInstall(source, options) {
             },
         },
     });
+    let manifestTarget = null;
+    try {
+        manifestTarget = await resolveManifestTarget(source);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json) {
+            console.log(JSON.stringify({ success: false, error: message }));
+        }
+        else {
+            console.error(`Error: ${message}`);
+        }
+        return { success: false, exitCode: ExitCode.ManifestError, error: message };
+    }
+    const manifestInstall = !!manifestTarget;
+    if (options.ci && options.ignoreLock) {
+        const message = "--ci and --ignore-lock cannot be used together.";
+        if (options.json) {
+            console.log(JSON.stringify({ success: false, error: message }));
+        }
+        else {
+            console.error(`Error: ${message}`);
+        }
+        return { success: false, exitCode: ExitCode.InvalidArguments, error: message };
+    }
+    if (options.alias && manifestInstall) {
+        const message = "--alias cannot be used with kits.json installs. Set installAs in the manifest instead.";
+        if (options.json) {
+            console.log(JSON.stringify({ success: false, error: message }));
+        }
+        else {
+            console.error(`Error: ${message}`);
+        }
+        return { success: false, exitCode: ExitCode.InvalidArguments, error: message };
+    }
+    if (options.ci && !manifestInstall) {
+        const message = "--ci is only valid for manifest-driven installs (kits.json).";
+        if (options.json) {
+            console.log(JSON.stringify({ success: false, error: message }));
+        }
+        else {
+            console.error(`Error: ${message}`);
+        }
+        return { success: false, exitCode: ExitCode.InvalidArguments, error: message };
+    }
+    if (options.ignoreLock && !manifestInstall) {
+        const message = "--ignore-lock is only valid for manifest-driven installs (kits.json).";
+        if (options.json) {
+            console.log(JSON.stringify({ success: false, error: message }));
+        }
+        else {
+            console.error(`Error: ${message}`);
+        }
+        return { success: false, exitCode: ExitCode.InvalidArguments, error: message };
+    }
     // Parse scope from options
     let scope = getScopeFromOptions(options);
-    const projectRoot = process.cwd();
+    let projectRoot = process.cwd();
+    let manifest = null;
+    let manifestPath = null;
+    let manifestHash = null;
+    let manifestWarning;
+    if (manifestInstall && manifestTarget) {
+        manifest = manifestTarget.manifest;
+        manifestPath = manifestTarget.manifestPath;
+        scope = manifest.scope;
+        if (scope === "project") {
+            const derived = deriveProjectRootFromManifestPath(manifestPath);
+            projectRoot = derived.projectRoot;
+            manifestWarning = derived.warning;
+        }
+        manifestHash = hashManifest(manifest);
+    }
     // In non-interactive mode, scope must be specified
     // Exception: --list flag doesn't require scope
-    if (!isInteractive && !scope && !options.list) {
+    if (!manifestInstall && !isInteractive && !scope && !options.list) {
         const message = "Scope is required in non-interactive mode. Use --global (-g) or --project (-p).";
         if (options.json) {
             console.log(JSON.stringify({ success: false, error: message }));
@@ -136,91 +287,222 @@ export async function runInstall(source, options) {
         if (isInteractive) {
             intro("@hashicorp/kits");
         }
-        // Fetch source
-        const fetchSpinner = isInteractive
-            ? startSpinner(`Fetching ${formatSource(source)}...`)
-            : undefined;
-        if (!fetchSpinner && options.verbose) {
-            console.error(`Fetching ${source}...`);
+        if (manifestInstall && (options.global || options.project)) {
+            const message = "Ignoring --global/--project flags because kits.json defines scope.";
+            if (isInteractive) {
+                logInfo(message);
+            }
+            else if (options.verbose) {
+                console.error(`Warning: ${message}`);
+            }
         }
-        try {
-            fetchResult = await fetchSource(source);
-            if (fetchSpinner) {
-                stopSpinnerSuccess(fetchSpinner, `Fetched ${formatSource(source)}`);
+        if (manifestInstall && options.kit && options.kit.length > 0) {
+            const message = "Ignoring --kit flags because kits.json defines kits to install.";
+            if (isInteractive) {
+                logInfo(message);
             }
             else if (options.verbose) {
-                console.error(`Fetched to ${fetchResult.localPath}`);
+                console.error(`Warning: ${message}`);
             }
-            void debugLog({
-                level: "info",
-                event: "install.fetch.success",
-                data: { localPath: fetchResult.localPath },
-            });
         }
-        catch (error) {
-            if (fetchSpinner) {
-                stopSpinnerError(fetchSpinner, "Failed to fetch source");
+        if (manifestWarning) {
+            if (isInteractive) {
+                logInfo(manifestWarning);
             }
-            if (error instanceof NoFetcherError || error instanceof SourceParseError) {
-                const message = error.message;
-                if (isInteractive) {
-                    logError(message);
-                    outroError("Installation failed");
+            else if (options.verbose) {
+                console.error(`Warning: ${manifestWarning}`);
+            }
+        }
+        const sourceDiscoveries = [];
+        const availableKits = [];
+        const registryBySource = new Map();
+        let selectedKits = [];
+        const sourcesToFetch = manifestInstall ? (manifest?.sources ?? []) : [{ source }];
+        if (manifestInstall && sourcesToFetch.length === 0) {
+            const message = "kits.json must include at least one source.";
+            if (isInteractive) {
+                logError(message);
+                outroError("Installation failed");
+            }
+            else if (options.json) {
+                console.log(JSON.stringify({ success: false, error: message }));
+            }
+            else {
+                console.error(`Error: ${message}`);
+            }
+            return { success: false, exitCode: ExitCode.ManifestError, error: message };
+        }
+        for (const sourceEntry of sourcesToFetch) {
+            const sourceValue = "source" in sourceEntry ? sourceEntry.source : sourceEntry;
+            const fetchSpinner = isInteractive
+                ? startSpinner(`Fetching ${formatSource(sourceValue)}...`)
+                : undefined;
+            if (!fetchSpinner && options.verbose) {
+                console.error(`Fetching ${sourceValue}...`);
+            }
+            let localFetch;
+            try {
+                localFetch = await fetchSource(sourceValue);
+                fetchResults.push(localFetch);
+                if (fetchSpinner) {
+                    stopSpinnerSuccess(fetchSpinner, `Fetched ${formatSource(sourceValue)}`);
                 }
-                else if (options.json) {
-                    console.log(JSON.stringify({ success: false, error: message }));
+                else if (options.verbose) {
+                    console.error(`Fetched to ${localFetch.localPath}`);
                 }
-                else {
-                    console.error(`Error: ${message}`);
+                void debugLog({
+                    level: "info",
+                    event: "install.fetch.success",
+                    data: { source: sourceValue, localPath: localFetch.localPath },
+                });
+            }
+            catch (error) {
+                if (fetchSpinner) {
+                    stopSpinnerError(fetchSpinner, "Failed to fetch source");
+                }
+                if (error instanceof NoFetcherError || error instanceof SourceParseError) {
+                    const message = error.message;
+                    if (isInteractive) {
+                        logError(message);
+                        outroError("Installation failed");
+                    }
+                    else if (options.json) {
+                        console.log(JSON.stringify({ success: false, error: message }));
+                    }
+                    else {
+                        console.error(`Error: ${message}`);
+                    }
+                    return { success: false, exitCode: ExitCode.SourceNotFound, error: message };
                 }
-                return { success: false, exitCode: ExitCode.SourceNotFound, error: message };
+                throw error;
             }
-            throw error;
-        }
-        // Scan for kits
-        const scanSpinner = isInteractive ? startSpinner("Scanning for kits...") : undefined;
-        let discovery = await scanKits(fetchResult.localPath, source);
-        if (scanSpinner) {
-            const kitCount = discovery.kits.length;
-            stopSpinnerSuccess(scanSpinner, `Found ${formatCount(kitCount, "kit")}`);
-        }
-        void debugLog({
-            level: "info",
-            event: "install.scan.success",
-            data: { kits: discovery.kits.map((kit) => kit.name) },
-        });
-        // Filter by requested kit names
-        if (options.kit && options.kit.length > 0) {
-            const missing = getDiscoveryMissingKitNames(discovery, options.kit);
-            if (missing.length > 0) {
-                const message = `Kit${missing.length === 1 ? "" : "s"} not found: ${missing.join(", ")}`;
-                if (isInteractive) {
-                    displayMissingKits(missing, discovery.kits);
-                    outroError("Installation failed");
+            const scanSpinner = isInteractive
+                ? startSpinner(`Scanning kits from ${formatSource(sourceValue)}...`)
+                : undefined;
+            const discovery = await scanKits(localFetch.localPath, sourceValue);
+            if (scanSpinner) {
+                const kitCount = discovery.kits.length;
+                stopSpinnerSuccess(scanSpinner, `Found ${formatCount(kitCount, "kit")}`);
+            }
+            void debugLog({
+                level: "info",
+                event: "install.scan.success",
+                data: { source: sourceValue, kits: discovery.kits.map((kit) => kit.name) },
+            });
+            const discoveredKits = discovery.kits.map((kit) => ({
+                ...kit,
+                source: sourceValue,
+                localPath: localFetch.localPath,
+            }));
+            availableKits.push(...discoveredKits);
+            let selectedForSource = [];
+            if (manifestInstall && "kits" in sourceEntry && sourceEntry.kits && sourceEntry.kits.length > 0) {
+                const requestedEntries = sourceEntry.kits.map(normalizeManifestKitEntry);
+                const requestedNames = requestedEntries.map((entry) => entry.name);
+                const missing = getDiscoveryMissingKitNames(discovery, requestedNames);
+                if (missing.length > 0) {
+                    const message = `Kit${missing.length === 1 ? "" : "s"} not found: ${missing.join(", ")}`;
+                    if (isInteractive) {
+                        displayMissingKits(missing, discovery.kits);
+                        outroError("Installation failed");
+                    }
+                    else if (options.json) {
+                        console.log(JSON.stringify({ success: false, error: message }));
+                    }
+                    else {
+                        console.error(`Error: ${message}`);
+                        console.error("Available kits: " + discovery.kits.map((k) => k.name).join(", "));
+                    }
+                    return { success: false, exitCode: ExitCode.KitNotFound, error: message };
                 }
-                else if (options.json) {
-                    console.log(JSON.stringify({ success: false, error: message }));
+                const kitIndex = new Map();
+                for (const kit of discovery.kits) {
+                    kitIndex.set(kit.name.toLowerCase(), kit);
                 }
-                else {
-                    console.error(`Error: ${message}`);
-                    console.error("Available kits: " + discovery.kits.map((k) => k.name).join(", "));
+                selectedForSource = requestedEntries.map((entry) => {
+                    const kit = kitIndex.get(entry.name.toLowerCase());
+                    if (!kit) {
+                        throw new Error(`Kit not found: ${entry.name}`);
+                    }
+                    return {
+                        ...kit,
+                        source: sourceValue,
+                        localPath: localFetch.localPath,
+                        installAs: entry.installAs ?? kit.name,
+                    };
+                });
+            }
+            else {
+                let kitsForSource = discovery.kits;
+                if (!manifestInstall && options.kit && options.kit.length > 0) {
+                    const missing = getDiscoveryMissingKitNames(discovery, options.kit);
+                    if (missing.length > 0) {
+                        const message = `Kit${missing.length === 1 ? "" : "s"} not found: ${missing.join(", ")}`;
+                        if (isInteractive) {
+                            displayMissingKits(missing, discovery.kits);
+                            outroError("Installation failed");
+                        }
+                        else if (options.json) {
+                            console.log(JSON.stringify({ success: false, error: message }));
+                        }
+                        else {
+                            console.error(`Error: ${message}`);
+                            console.error("Available kits: " + discovery.kits.map((k) => k.name).join(", "));
+                        }
+                        return { success: false, exitCode: ExitCode.KitNotFound, error: message };
+                    }
+                    kitsForSource = filterDiscoveryKitsByName(discovery, options.kit).kits;
                 }
-                return { success: false, exitCode: ExitCode.KitNotFound, error: message };
+                selectedForSource = kitsForSource.map((kit) => ({
+                    ...kit,
+                    source: sourceValue,
+                    localPath: localFetch.localPath,
+                    installAs: kit.name,
+                }));
+            }
+            selectedKits.push(...selectedForSource);
+            if (discovery.primitivesRegistry) {
+                const loader = new PrimitivesRegistryLoader(localFetch.localPath);
+                await loader.load();
+                registryBySource.set(sourceValue, loader);
+            }
+            else {
+                registryBySource.set(sourceValue, null);
             }
-            discovery = filterDiscoveryKitsByName(discovery, options.kit);
+            sourceDiscoveries.push({ source: sourceValue, localPath: localFetch.localPath, discovery });
         }
         // Handle --list flag
         if (options.list) {
             if (options.json) {
-                displayKitsJson(discovery.kits, discovery.source, discovery.repository);
+                if (sourceDiscoveries.length === 1) {
+                    const discovery = sourceDiscoveries[0].discovery;
+                    displayKitsJson(discovery.kits, discovery.source, discovery.repository);
+                }
+                else {
+                    const output = {
+                        sources: sourceDiscoveries.map((entry) => ({
+                            source: entry.discovery.source,
+                            repository: entry.discovery.repository,
+                            kits: entry.discovery.kits.map((kit) => ({
+                                name: kit.name,
+                                version: kit.manifest.version,
+                                description: kit.manifest.description,
+                                products: kit.manifest.products,
+                                requiredPrimitives: kit.requiredPrimitives,
+                                primitiveCounts: kit.primitiveCounts,
+                            })),
+                        })),
+                    };
+                    console.log(JSON.stringify(output, null, 2));
+                }
             }
             else {
-                displayAvailableKits(discovery.kits);
+                displayAvailableKits(availableKits);
             }
             return { success: true, exitCode: ExitCode.Success };
         }
         // Check if any kits were found
-        if (discovery.kits.length === 0) {
+        if (selectedKits.length === 0) {
             const message = "No kits found in repository";
             if (isInteractive) {
                 displayNoKitsFound();
@@ -235,21 +517,56 @@ export async function runInstall(source, options) {
             return { success: false, exitCode: ExitCode.KitNotFound, error: message };
         }
         // Interactive kit selection (stage 1)
-        let selectedKits = discovery.kits;
-        if (isInteractive && !options.kit) {
-            const result = await selectKits(discovery.kits, {
+        if (isInteractive && !manifestInstall && !options.kit) {
+            const result = await selectKits(selectedKits, {
                 showAvailable: false,
             });
             if (result.cancelled) {
                 outroCancel("Installation cancelled");
                 return { success: false, exitCode: ExitCode.InstallationFailed };
             }
-            selectedKits = filterKitsByName(discovery.kits, result.selected);
+            selectedKits = filterKitsByName(selectedKits, result.selected);
+        }
+        if (options.alias) {
+            if (selectedKits.length !== 1) {
+                const message = "--alias can only be used when installing a single kit.";
+                if (isInteractive) {
+                    logError(message);
+                    outroError("Installation failed");
+                }
+                else if (options.json) {
+                    console.log(JSON.stringify({ success: false, error: message }));
+                }
+                else {
+                    console.error(`Error: ${message}`);
+                }
+                return { success: false, exitCode: ExitCode.InvalidArguments, error: message };
+            }
+            selectedKits[0] = { ...selectedKits[0], installAs: options.alias };
+        }
+        const installAsIndex = new Map();
+        for (const kit of selectedKits) {
+            const existingSource = installAsIndex.get(kit.installAs);
+            if (existingSource && existingSource !== kit.source) {
+                const message = `Kit instance name "${kit.installAs}" is used by multiple selected kits (${existingSource}, ${kit.source}).`;
+                if (isInteractive) {
+                    logError(message);
+                    outroError("Installation failed");
+                }
+                else if (options.json) {
+                    console.log(JSON.stringify({ success: false, error: message }));
+                }
+                else {
+                    console.error(`Error: ${message}`);
+                }
+                return { success: false, exitCode: ExitCode.InstallationFailed, error: message };
+            }
+            installAsIndex.set(kit.installAs, kit.source);
         }
         void debugLog({
             level: "info",
             event: "install.kits.selected",
-            data: { kits: selectedKits.map((kit) => kit.name) },
+            data: { kits: selectedKits.map((kit) => ({ name: kit.name, installAs: kit.installAs })) },
         });
         // Detect harnesses
         const harnessSpinner = isInteractive ? startSpinner("Detecting AI harnesses...") : undefined;
@@ -269,7 +586,29 @@ export async function runInstall(source, options) {
         });
         // Filter by requested harnesses
         let targetHarnesses = detectedHarnesses;
-        if (options.agent && options.agent.length > 0) {
+        if (manifestInstall && manifest?.harnesses && manifest.harnesses.length > 0) {
+            if (options.agent && options.agent.length > 0) {
+                const message = "Ignoring --agent flags because kits.json defines harnesses.";
+                if (isInteractive) {
+                    logInfo(message);
+                }
+                else if (options.verbose) {
+                    console.error(`Warning: ${message}`);
+                }
+            }
+            const missing = getMissingHarnesses(detectedHarnesses, manifest.harnesses);
+            if (missing.length > 0) {
+                if (isInteractive) {
+                    warnMissingHarnesses(missing);
+                }
+                else if (options.verbose) {
+                    const label = missing.length === 1 ? "Harness" : "Harnesses";
+                    console.error(`Warning: ${label} not detected: ${missing.join(", ")}`);
+                }
+            }
+            targetHarnesses = filterHarnessesByName(detectedHarnesses, manifest.harnesses);
+        }
+        else if (options.agent && options.agent.length > 0) {
             const missing = getMissingHarnesses(detectedHarnesses, options.agent);
             if (missing.length > 0) {
                 if (isInteractive) {
@@ -299,7 +638,7 @@ export async function runInstall(source, options) {
         }
         // Interactive harness selection
         let selectedHarnesses = targetHarnesses;
-        if (isInteractive && !options.agent) {
+        if (isInteractive && !manifestInstall && !options.agent) {
             const result = await selectHarnesses(detectedHarnesses, {
                 showDetected: true,
                 includeAllOption: true,
@@ -340,20 +679,137 @@ export async function runInstall(source, options) {
             event: "install.scope.selected",
             data: { scope: effectiveScope, projectRoot },
         });
+        const lockfileRoot = effectiveScope === "project" ? projectRoot : undefined;
+        let lockfile = await readLockfile(effectiveScope, lockfileRoot);
+        const manifestInfo = manifestInstall && manifestPath && manifestHash
+            ? { path: manifestPath, hash: manifestHash }
+            : undefined;
+        const lockfileInSync = !!manifestInfo && !!lockfile && lockfile.manifest?.hash === manifestInfo.hash;
+        if (manifestInstall && options.ci && (!lockfile || !lockfileInSync)) {
+            const message = "Lockfile missing or out of sync with kits.json.";
+            if (options.json) {
+                console.log(JSON.stringify({ success: false, error: message }));
+            }
+            else {
+                console.error(`Error: ${message}`);
+            }
+            return { success: false, exitCode: ExitCode.LockfileOutOfSync, error: message };
+        }
+        if (!lockfile) {
+            lockfile = createEmptyLockfile(effectiveScope, lockfileRoot);
+        }
+        if (manifestInfo) {
+            lockfile.manifest = manifestInfo;
+        }
+        const lockedVersions = manifestInstall && lockfileInSync && !options.ignoreLock
+            ? buildLockedVersionMap(lockfile)
+            : undefined;
+        const outputSource = manifestInstall && manifestPath ? manifestPath : source;
+        const overwriteTargets = new Map();
+        const existingInstances = new Set();
+        for (const harness of selectedHarnesses) {
+            const harnessEntry = lockfile.harnesses[harness.name];
+            if (!harnessEntry)
+                continue;
+            for (const instanceName of Object.keys(harnessEntry.kits)) {
+                existingInstances.add(instanceName);
+            }
+        }
+        const usedInstanceNames = new Set(selectedKits.map((kit) => kit.installAs));
+        for (const kit of selectedKits) {
+            const collidingHarnesses = [];
+            const existingKits = [];
+            for (const harness of selectedHarnesses) {
+                const existing = lockfile.harnesses[harness.name]?.kits[kit.installAs];
+                if (!existing)
+                    continue;
+                collidingHarnesses.push(harness.name);
+                existingKits.push(existing);
+            }
+            if (collidingHarnesses.length === 0) {
+                continue;
+            }
+            if (!isInteractive) {
+                if (options.overwrite) {
+                    overwriteTargets.set(kit.installAs, new Set(collidingHarnesses));
+                    continue;
+                }
+                const message = `Kit instance "${kit.installAs}" already exists in the selected scope. Use --overwrite or choose a different --alias.`;
+                if (options.json) {
+                    console.log(JSON.stringify({ success: false, error: message }));
+                }
+                else {
+                    console.error(`Error: ${message}`);
+                }
+                return { success: false, exitCode: ExitCode.InstallationFailed, error: message };
+            }
+            const decision = await promptKitCollisionResolution({
+                kit,
+                harnesses: collidingHarnesses,
+                existing: existingKits,
+            });
+            if (decision === "cancel") {
+                outroCancel("Installation cancelled");
+                return { success: false, exitCode: ExitCode.InstallationFailed };
+            }
+            if (decision === "overwrite") {
+                overwriteTargets.set(kit.installAs, new Set(collidingHarnesses));
+                continue;
+            }
+            const newName = await promptForKitAlias(kit.installAs, usedInstanceNames, existingInstances);
+            if (!newName) {
+                outroCancel("Installation cancelled");
+                return { success: false, exitCode: ExitCode.InstallationFailed };
+            }
+            usedInstanceNames.delete(kit.installAs);
+            kit.installAs = newName;
+            usedInstanceNames.add(newName);
+        }
         // Compatibility check (after scope selection)
         const compatibilityHarnesses = selectedHarnesses.map((h) => ({
             ...h,
             supportedPrimitives: h.adapter.getSupportedPrimitives(effectiveScope),
         }));
-        let matrices = buildCompatibilityMatrix(selectedKits, compatibilityHarnesses);
+        const compatibilityKits = selectedKits.map((kit) => ({
+            ...kit,
+            name: kit.installAs,
+        }));
+        let matrices = buildCompatibilityMatrix(compatibilityKits, compatibilityHarnesses);
         let compatResult = {
             cancelled: false,
             choice: "proceed",
         };
         let compatiblePairs = [];
         let allowCompatibleOnly = false;
-        if (isInteractive) {
-            const compat = await runCompatibilityCheck(selectedKits, compatibilityHarnesses, effectiveScope, {
+        if (manifestInstall) {
+            const mode = manifest?.compatibility ?? "strict";
+            if (mode === "compatible-only") {
+                allowCompatibleOnly = true;
+                compatiblePairs = getCompatiblePairs(matrices);
+                if (compatiblePairs.length === 0) {
+                    const message = "No compatible kit-harness combinations for the selected scope";
+                    if (options.json) {
+                        console.log(JSON.stringify({ success: false, error: message }));
+                    }
+                    else {
+                        console.error(`Error: ${message}`);
+                    }
+                    return { success: false, exitCode: ExitCode.KitIncompatible, error: message };
+                }
+            }
+            else if (hasIncompatibilities(matrices)) {
+                const message = "No compatible kit-harness combinations for the selected scope";
+                if (options.json) {
+                    console.log(JSON.stringify({ success: false, error: message }));
+                }
+                else {
+                    console.error(`Error: ${message}`);
+                }
+                return { success: false, exitCode: ExitCode.KitIncompatible, error: message };
+            }
+        }
+        else if (isInteractive) {
+            const compat = await runCompatibilityCheck(compatibilityKits, compatibilityHarnesses, effectiveScope, {
                 showMatrix: options.verbose ?? false,
                 promptOnIncompatible: true,
             });
@@ -362,7 +818,7 @@ export async function runInstall(source, options) {
             compatiblePairs = compat.compatiblePairs;
             allowCompatibleOnly = compat.result.choice === "install-compatible";
         }
-        if (hasIncompatibilities(matrices)) {
+        if (!manifestInstall && hasIncompatibilities(matrices)) {
             void debugLog({
                 level: "warn",
                 event: "install.compatibility.failed",
@@ -405,13 +861,13 @@ export async function runInstall(source, options) {
         if (isInteractive && !options.dryRun) {
             const planKitNames = allowCompatibleOnly
                 ? new Set(compatiblePairs.map((pair) => pair.kit))
-                : new Set(selectedKits.map((kit) => kit.name));
+                : new Set(selectedKits.map((kit) => kit.installAs));
             const planHarnessNames = allowCompatibleOnly
                 ? new Set(compatiblePairs.map((pair) => pair.harness))
                 : new Set(selectedHarnesses.map((h) => h.name));
-            const planKits = selectedKits.filter((kit) => planKitNames.has(kit.name));
+            const planKits = selectedKits.filter((kit) => planKitNames.has(kit.installAs));
             const planHarnesses = selectedHarnesses.filter((h) => planHarnessNames.has(h.name));
-            displayInstallPlanSummary(planKits.map((kit) => ({ name: kit.name, version: kit.manifest.version })), planHarnesses.map((h) => ({ displayName: h.displayName })), effectiveScope);
+            displayInstallPlanSummary(planKits.map((kit) => ({ name: getKitDisplayName(kit), version: kit.manifest.version })), planHarnesses.map((h) => ({ displayName: h.displayName })), effectiveScope);
             const proceed = await confirmInstallPlan();
             if (proceed.cancelled || !proceed.proceed) {
                 outroCancel("Installation cancelled");
@@ -423,13 +879,14 @@ export async function runInstall(source, options) {
             if (options.json) {
                 const output = {
                     success: true,
-                    source,
+                    source: outputSource,
                     scope: effectiveScope,
                     harnesses: selectedHarnesses.map((h) => ({
                         name: h.name,
                         configPath: h.configPath || "",
                         kits: selectedKits.map((kit) => ({
                             name: kit.name,
+                            installAs: kit.installAs,
                             version: kit.manifest.version,
                             installed: [],
                         })),
@@ -442,21 +899,27 @@ export async function runInstall(source, options) {
                 console.log(JSON.stringify(output, null, 2));
             }
             else {
-                displayDryRunSummary(selectedKits.map((k) => ({ name: k.name, version: k.manifest.version })), selectedHarnesses.map((h) => ({ name: h.name, displayName: h.displayName })), { scope: effectiveScope, projectRoot });
+                displayDryRunSummary(selectedKits.map((k) => ({ name: getKitDisplayName(k), version: k.manifest.version })), selectedHarnesses.map((h) => ({ name: h.name, displayName: h.displayName })), { scope: effectiveScope, projectRoot });
             }
             return { success: true, exitCode: ExitCode.Success };
         }
         // Execute installation
-        const installResults = await executeInstallation(selectedKits, selectedHarnesses, discovery, source, {
+        const mergedMcpInstance = mergeMcpInstanceOverrides(manifest?.mcpInstanceOverrides, options.mcpInstance ?? {});
+        const installResults = await executeInstallation(selectedKits, selectedHarnesses, registryBySource, {
             isInteractive,
             verbose: options.verbose ?? false,
             json: options.json ?? false,
             scope: effectiveScope,
             projectRoot,
             env: options.env ?? {},
-            mcpInstance: options.mcpInstance ?? {},
+            mcpInstance: mergedMcpInstance,
+            overwriteTargets,
             allowCompatibleOnly,
             compatiblePairs: allowCompatibleOnly ? compatiblePairs : [],
+            lockfile,
+            outputSource,
+            ...(lockedVersions ? { lockedVersions } : {}),
+            ...(manifestInstall ? {} : { lockfileSource: source }),
         });
         if (!installResults.success) {
             const errorMsg = installResults.error || "Installation failed";
@@ -484,7 +947,7 @@ export async function runInstall(source, options) {
             data: {
                 scope: effectiveScope,
                 harnesses: selectedHarnesses.map((h) => h.name),
-                kits: selectedKits.map((k) => k.name),
+                kits: selectedKits.map((k) => ({ name: k.name, installAs: k.installAs })),
             },
         });
         if (options.json) {
@@ -514,10 +977,12 @@ export async function runInstall(source, options) {
         return { success: false, exitCode: ExitCode.InstallationFailed, error: message };
     }
     finally {
-        // Clean up fetched source
-        if (fetchResult?.cleanup) {
+        // Clean up fetched sources
+        for (const fetched of fetchResults) {
+            if (!fetched.cleanup)
+                continue;
             try {
-                await fetchResult.cleanup();
+                await fetched.cleanup();
             }
             catch {
                 // Ignore cleanup errors
@@ -728,9 +1193,73 @@ function resolveHookInstanceName(programName, primitiveOverride, kitName) {
     }
     return programName;
 }
+function normalizeManifestKitEntry(entry) {
+    if (typeof entry === "string") {
+        return { name: entry };
+    }
+    const normalized = { name: entry.name };
+    if (entry.installAs) {
+        normalized.installAs = entry.installAs;
+    }
+    return normalized;
+}
+function getKitDisplayName(kit) {
+    return kit.installAs === kit.name ? kit.name : `${kit.name} (as ${kit.installAs})`;
+}
 function buildPrimitiveKey(kitName, sourcePath) {
     return `${kitName}::${sourcePath}`;
 }
+function filterOverwriteKits(overwriteKits, kits) {
+    if (!overwriteKits || overwriteKits.size === 0) {
+        return new Set();
+    }
+    const allowed = new Set(kits.map((kit) => kit.installAs));
+    return new Set(Array.from(overwriteKits).filter((name) => allowed.has(name)));
+}
+async function promptKitCollisionResolution(options) {
+    const existingNames = Array.from(new Set(options.existing.map((entry) => entry.name)));
+    const existingHint = existingNames.length > 0 ? `Existing kit${existingNames.length === 1 ? "" : "s"}: ${existingNames.join(", ")}` : "";
+    const harnessLabel = options.harnesses.join(", ");
+    const choice = await clack.select({
+        message: `Kit instance "${options.kit.installAs}" already exists on ${harnessLabel}. ` +
+            (existingHint ? `${existingHint}. ` : "") +
+            "How would you like to proceed?",
+        options: [
+            { value: "overwrite", label: "Overwrite existing kit instance" },
+            { value: "rename", label: "Rename this install (alias)" },
+            { value: "cancel", label: "Cancel installation" },
+        ],
+    });
+    if (clack.isCancel(choice)) {
+        return "cancel";
+    }
+    return choice;
+}
+async function promptForKitAlias(currentName, usedNames, existingNames) {
+    while (true) {
+        const value = await clack.text({
+            message: `Enter a new instance name for "${currentName}":`,
+            placeholder: `${currentName}-alt`,
+        });
+        if (clack.isCancel(value)) {
+            return null;
+        }
+        const trimmed = String(value).trim();
+        if (!trimmed) {
+            clack.log.warn("Instance name cannot be empty.");
+            continue;
+        }
+        if (usedNames.has(trimmed)) {
+            clack.log.warn(`Instance name "${trimmed}" is already selected for this install.`);
+            continue;
+        }
+        if (existingNames.has(trimmed)) {
+            clack.log.warn(`Instance name "${trimmed}" is already installed for this scope.`);
+            continue;
+        }
+        return trimmed;
+    }
+}
 async function buildMcpPrimitiveInfoBySourcePath(resolvedByKit, cliEnvFlags, promptResults, instanceOverrides) {
     const infoBySourcePath = new Map();
     for (const [kitName, primitives] of resolvedByKit.entries()) {
@@ -857,38 +1386,144 @@ async function promptForMcpInstanceName(instanceName, usedNames) {
         return trimmed;
     }
 }
+async function removeOverwrittenKitsForHarness(harness, kitsToOverwrite, lockfile, scope, projectRoot, options) {
+    const harnessEntry = lockfile.harnesses[harness.name];
+    if (!harnessEntry || kitsToOverwrite.size === 0) {
+        return;
+    }
+    const mcpInstances = harnessEntry.mcpInstances;
+    const hookInstances = harnessEntry.hookInstances;
+    const mcpCandidates = new Set();
+    const hookCandidates = new Set();
+    for (const kitName of kitsToOverwrite) {
+        const kit = harnessEntry.kits[kitName];
+        if (!kit)
+            continue;
+        for (const primitive of kit.primitives) {
+            if (primitive.type === "mcp") {
+                const instanceName = primitive.instanceName ?? primitive.namespacedName;
+                if (instanceName) {
+                    mcpCandidates.add(instanceName);
+                }
+                continue;
+            }
+            if (primitive.type === "hooks") {
+                const instanceName = primitive.instanceName ?? primitive.namespacedName;
+                if (instanceName) {
+                    hookCandidates.add(instanceName);
+                }
+                continue;
+            }
+            const filePath = expandPath(primitive.installedPath);
+            try {
+                await remove(filePath);
+                if (options.verbose) {
+                    if (options.isInteractive) {
+                        clack.log.info(`  ✓ Removed ${primitive.namespacedName}`);
+                    }
+                    else {
+                        console.error(`  Removed: ${filePath}`);
+                    }
+                }
+            }
+            catch (error) {
+                if (options.verbose) {
+                    const msg = error instanceof Error ? error.message : String(error);
+                    if (options.isInteractive) {
+                        clack.log.warn(`  ⚠ Could not remove ${primitive.namespacedName}: ${msg}`);
+                    }
+                    else {
+                        console.error(`  Warning: Could not remove ${filePath}: ${msg}`);
+                    }
+                }
+            }
+        }
+    }
+    const mcpInstancesToRemove = [];
+    if (mcpInstances) {
+        for (const instanceName of mcpCandidates) {
+            const entry = mcpInstances[instanceName];
+            if (!entry)
+                continue;
+            entry.usedBy = entry.usedBy.filter((name) => !kitsToOverwrite.has(name));
+            if (entry.usedBy.length === 0) {
+                delete mcpInstances[instanceName];
+                mcpInstancesToRemove.push(instanceName);
+            }
+        }
+    }
+    if (mcpInstancesToRemove.length > 0) {
+        if (harness.adapter.removeMcpServers) {
+            await harness.adapter.removeMcpServers(mcpInstancesToRemove, scope, scope === "project" ? projectRoot : undefined);
+        }
+        else if (options.verbose) {
+            const warning = `  ⚠ Unable to remove MCP instances for ${harness.displayName} (adapter unavailable)`;
+            if (options.isInteractive) {
+                clack.log.warn(warning);
+            }
+            else {
+                console.error(warning);
+            }
+        }
+    }
+    const hookInstancesToRemove = [];
+    if (hookInstances) {
+        for (const instanceName of hookCandidates) {
+            const entry = hookInstances[instanceName];
+            if (!entry)
+                continue;
+            entry.usedBy = entry.usedBy.filter((name) => !kitsToOverwrite.has(name));
+            if (entry.usedBy.length === 0) {
+                delete hookInstances[instanceName];
+                hookInstancesToRemove.push(instanceName);
+            }
+        }
+    }
+    if (hookInstancesToRemove.length > 0) {
+        if (harness.adapter.removeHooks) {
+            await harness.adapter.removeHooks(hookInstancesToRemove, scope, scope === "project" ? projectRoot : undefined);
+        }
+        else if (options.verbose) {
+            const warning = `  ⚠ Unable to remove hook instances for ${harness.displayName} (adapter unavailable)`;
+            if (options.isInteractive) {
+                clack.log.warn(warning);
+            }
+            else {
+                console.error(warning);
+            }
+        }
+    }
+    for (const kitName of kitsToOverwrite) {
+        delete harnessEntry.kits[kitName];
+    }
+}
 /**
  * Execute the actual installation of kits to harnesses.
  */
-async function executeInstallation(kits, harnesses, discovery, source, options) {
-    const { isInteractive, verbose, scope, projectRoot, env, mcpInstance, allowCompatibleOnly = false, compatiblePairs = [], } = options;
-    // Load or create primitives registry loader
-    let registryLoader = null;
-    if (discovery.primitivesRegistry) {
-        registryLoader = new PrimitivesRegistryLoader(discovery.localPath);
-        await registryLoader.load();
-    }
+async function executeInstallation(kits, harnesses, registryBySource, options) {
+    const { isInteractive, verbose, scope, projectRoot, env, mcpInstance, overwriteTargets, allowCompatibleOnly = false, compatiblePairs = [], lockfile, lockedVersions, outputSource, lockfileSource, } = options;
     // Pre-pass: resolve all primitives to collect MCP env var definitions for validation
     const allResolvedPrimitives = [];
     const resolvedByKit = new Map();
     const resolutionFailures = [];
     for (const kit of kits) {
+        const registryLoader = registryBySource.get(kit.source) ?? null;
         if (registryLoader) {
-            const kitBasePath = path.join(discovery.localPath, kit.path);
-            const resolution = await resolvePrimitiveReferences(kit.manifest, registryLoader, kitBasePath);
+            const kitBasePath = path.join(kit.localPath, kit.path);
+            const resolution = await resolvePrimitiveReferences(kit.manifest, registryLoader, kitBasePath, lockedVersions, kit.installAs);
             if (resolution.errors.length > 0) {
                 resolutionFailures.push({
-                    kit: kit.name,
+                    kit: getKitDisplayName(kit),
                     errors: resolution.errors.map((e) => e.message),
                 });
                 continue;
             }
-            resolvedByKit.set(kit.name, resolution.primitives);
+            resolvedByKit.set(kit.installAs, resolution.primitives);
             allResolvedPrimitives.push(...resolution.primitives);
         }
         else {
-            const inlinePrimitives = resolveInlinePrimitivesOnly(kit, discovery.localPath);
-            resolvedByKit.set(kit.name, inlinePrimitives);
+            const inlinePrimitives = resolveInlinePrimitivesOnly(kit, kit.localPath, kit.installAs);
+            resolvedByKit.set(kit.installAs, inlinePrimitives);
             allResolvedPrimitives.push(...inlinePrimitives);
         }
     }
@@ -994,12 +1629,19 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
             applyPromptResultsToResolutions(envResolutions, promptResults);
         }
     }
-    // Read or create manifest for the specified scope
-    let manifest = await readManifest(scope, scope === "project" ? projectRoot : undefined);
-    if (!manifest) {
-        manifest = createEmptyManifest(scope, scope === "project" ? projectRoot : undefined);
+    if (lockfileSource) {
+        lockfile.source = lockfileSource;
+    }
+    const overwriteKitsByHarness = new Map();
+    if (overwriteTargets) {
+        for (const [kitName, harnessNames] of overwriteTargets.entries()) {
+            for (const harnessName of harnessNames) {
+                const existing = overwriteKitsByHarness.get(harnessName) ?? new Set();
+                existing.add(kitName);
+                overwriteKitsByHarness.set(harnessName, existing);
+            }
+        }
     }
-    manifest.source = source;
     const harnessResults = [];
     const skippedResults = [];
     const compatibleKitsByHarness = new Map();
@@ -1021,18 +1663,18 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
     const hookInstancesToInstallByHarness = new Map();
     for (const harness of harnesses) {
         const kitsToCheck = allowCompatibleOnly
-            ? kits.filter((kit) => compatibleKitsByHarness.get(harness.name)?.has(kit.name))
+            ? kits.filter((kit) => compatibleKitsByHarness.get(harness.name)?.has(kit.installAs))
             : kits;
         if (kitsToCheck.length === 0 || mcpInfoByPrimitiveKey.size === 0) {
             continue;
         }
         const desiredByName = new Map();
         for (const kit of kitsToCheck) {
-            const primitives = resolvedByKit.get(kit.name) ?? [];
+            const primitives = resolvedByKit.get(kit.installAs) ?? [];
             for (const primitive of primitives) {
                 if (primitive.type !== "mcp")
                     continue;
-                const key = buildPrimitiveKey(kit.name, primitive.sourcePath);
+                const key = buildPrimitiveKey(kit.installAs, primitive.sourcePath);
                 const info = mcpInfoByPrimitiveKey.get(key);
                 if (!info)
                     continue;
@@ -1042,8 +1684,8 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
                     kits: new Set(),
                     info,
                 };
-                entry.primitives.push({ primitive, kitName: kit.name });
-                entry.kits.add(kit.name);
+                entry.primitives.push({ primitive, kitName: kit.installAs });
+                entry.kits.add(kit.installAs);
                 byHash.set(info.configHash, entry);
                 desiredByName.set(info.instanceName, byHash);
             }
@@ -1059,8 +1701,11 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
                 };
             }
         }
-        const existingInstances = manifest.harnesses[harness.name]?.mcpInstances ?? {};
-        const usedInstanceNames = new Set(Object.keys(existingInstances));
+        const existingInstances = lockfile.harnesses[harness.name]?.mcpInstances ?? {};
+        const overwriteKits = filterOverwriteKits(overwriteKitsByHarness.get(harness.name), kitsToCheck);
+        const usedInstanceNames = new Set(Object.entries(existingInstances)
+            .filter(([, entry]) => entry.usedBy.some((name) => !overwriteKits.has(name)))
+            .map(([name]) => name));
         const assignments = new Map();
         const forkedInstances = new Map();
         const instancesToInstall = new Set();
@@ -1070,7 +1715,8 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
             let finalHash = candidate.info.configHash;
             let action = "install";
             const existing = existingInstances[instanceName];
-            if (existing) {
+            const existingUsers = existing?.usedBy.filter((name) => !overwriteKits.has(name)) ?? [];
+            if (existing && existingUsers.length > 0) {
                 if (existing.configHash === candidate.info.configHash) {
                     action = "reuse";
                     finalHash = existing.configHash;
@@ -1161,18 +1807,18 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
     }
     for (const harness of harnesses) {
         const kitsToCheck = allowCompatibleOnly
-            ? kits.filter((kit) => compatibleKitsByHarness.get(harness.name)?.has(kit.name))
+            ? kits.filter((kit) => compatibleKitsByHarness.get(harness.name)?.has(kit.installAs))
             : kits;
         if (kitsToCheck.length === 0 || hookInfoByPrimitiveKey.size === 0) {
             continue;
         }
         const desiredByName = new Map();
         for (const kit of kitsToCheck) {
-            const primitives = resolvedByKit.get(kit.name) ?? [];
+            const primitives = resolvedByKit.get(kit.installAs) ?? [];
             for (const primitive of primitives) {
                 if (primitive.type !== "hooks")
                     continue;
-                const key = buildPrimitiveKey(kit.name, primitive.sourcePath);
+                const key = buildPrimitiveKey(kit.installAs, primitive.sourcePath);
                 const info = hookInfoByPrimitiveKey.get(key);
                 if (!info)
                     continue;
@@ -1182,8 +1828,8 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
                     kits: new Set(),
                     info,
                 };
-                entry.primitives.push({ primitive, kitName: kit.name });
-                entry.kits.add(kit.name);
+                entry.primitives.push({ primitive, kitName: kit.installAs });
+                entry.kits.add(kit.installAs);
                 byHash.set(info.configHash, entry);
                 desiredByName.set(info.instanceName, byHash);
             }
@@ -1199,7 +1845,8 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
                 };
             }
         }
-        const existingInstances = manifest.harnesses[harness.name]?.hookInstances ?? {};
+        const existingInstances = lockfile.harnesses[harness.name]?.hookInstances ?? {};
+        const overwriteKits = filterOverwriteKits(overwriteKitsByHarness.get(harness.name), kitsToCheck);
         const assignments = new Map();
         const instancesToInstall = new Set();
         for (const [instanceName, byHash] of desiredByName) {
@@ -1207,7 +1854,8 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
             let action = "install";
             let finalHash = candidate.info.configHash;
             const existing = existingInstances[instanceName];
-            if (existing) {
+            const existingUsers = existing?.usedBy.filter((name) => !overwriteKits.has(name)) ?? [];
+            if (existing && existingUsers.length > 0) {
                 if (existing.configHash !== candidate.info.configHash) {
                     return {
                         success: false,
@@ -1240,7 +1888,7 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
     // Install to each harness
     for (const harness of harnesses) {
         const kitsToInstall = allowCompatibleOnly
-            ? kits.filter((kit) => compatibleKitsByHarness.get(harness.name)?.has(kit.name))
+            ? kits.filter((kit) => compatibleKitsByHarness.get(harness.name)?.has(kit.installAs))
             : kits;
         if (kitsToInstall.length === 0) {
             continue;
@@ -1256,6 +1904,10 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
             console.error(`Installing to ${harness.displayName}...`);
         }
         const kitResults = [];
+        const overwriteKits = filterOverwriteKits(overwriteKitsByHarness.get(harness.name), kitsToInstall);
+        if (overwriteKits && overwriteKits.size > 0) {
+            await removeOverwrittenKitsForHarness(harness, overwriteKits, lockfile, scope, projectRoot, { isInteractive, verbose });
+        }
         for (const kit of kitsToInstall) {
             // Check compatibility with scope (should already be validated)
             const compatibility = harness.adapter.checkCompatibility(kit.manifest, scope);
@@ -1270,12 +1922,12 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
                 };
             }
             // Use resolved primitives from pre-pass
-            const resolvedPrimitives = resolvedByKit.get(kit.name);
+            const resolvedPrimitives = resolvedByKit.get(kit.installAs);
             if (!resolvedPrimitives) {
                 return {
                     success: false,
                     exitCode: ExitCode.ResolutionFailed,
-                    error: `Resolution failed: no primitives resolved for ${kit.name}`,
+                    error: `Resolution failed: no primitives resolved for ${getKitDisplayName(kit)}`,
                 };
             }
             const mcpConfigPath = getMcpConfigPath(harness.adapter, scope, projectRoot);
@@ -1287,7 +1939,7 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
             const installedHookInstanceNames = new Set();
             for (const primitive of resolvedPrimitives) {
                 if (primitive.type === "mcp" && mcpAssignments) {
-                    const assignment = mcpAssignments.get(buildPrimitiveKey(kit.name, primitive.sourcePath));
+                    const assignment = mcpAssignments.get(buildPrimitiveKey(kit.installAs, primitive.sourcePath));
                     if (!assignment) {
                         primitivesForAdapter.push(primitive);
                         continue;
@@ -1304,7 +1956,7 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
                     continue;
                 }
                 if (primitive.type === "hooks" && hookAssignments) {
-                    const assignment = hookAssignments.get(buildPrimitiveKey(kit.name, primitive.sourcePath));
+                    const assignment = hookAssignments.get(buildPrimitiveKey(kit.installAs, primitive.sourcePath));
                     if (!assignment) {
                         primitivesForAdapter.push(primitive);
                         continue;
@@ -1322,6 +1974,9 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
                 }
                 primitivesForAdapter.push(primitive);
             }
+            const installManifest = kit.installAs === kit.manifest.name
+                ? kit.manifest
+                : { ...kit.manifest, name: kit.installAs };
             // Install the kit
             const installOptions = {
                 backup: true,
@@ -1338,10 +1993,11 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
             if (scope === "project") {
                 installOptions.projectRoot = projectRoot;
             }
-            const installResult = await harness.adapter.install(kit.manifest, primitivesForAdapter, installOptions);
+            const installResult = await harness.adapter.install(installManifest, primitivesForAdapter, installOptions);
             if (!installResult.success) {
                 skippedResults.push({
-                    kit: kit.name,
+                    kit: kit.installAs,
+                    name: kit.name,
                     harness: harness.name,
                     reason: installResult.error || "Installation failed",
                 });
@@ -1355,7 +2011,7 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
             }
             if (skippedMcpPrimitives.length > 0) {
                 for (const primitive of skippedMcpPrimitives) {
-                    const namespacedName = harness.adapter.getNamespacedName(kit.name, primitive.name);
+                    const namespacedName = harness.adapter.getNamespacedName(kit.installAs, primitive.name);
                     const status = {
                         type: primitive.type,
                         name: primitive.name,
@@ -1374,7 +2030,7 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
             }
             if (skippedHookPrimitives.length > 0) {
                 for (const primitive of skippedHookPrimitives) {
-                    const namespacedName = harness.adapter.getNamespacedName(kit.name, primitive.name);
+                    const namespacedName = harness.adapter.getNamespacedName(kit.installAs, primitive.name);
                     const status = {
                         type: primitive.type,
                         name: primitive.name,
@@ -1391,9 +2047,9 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
                     installResult.installedPrimitives.push(status);
                 }
             }
-            // Record in manifest
-            if (!manifest.harnesses[harness.name]) {
-                manifest.harnesses[harness.name] = { kits: {} };
+            // Record in lockfile
+            if (!lockfile.harnesses[harness.name]) {
+                lockfile.harnesses[harness.name] = { kits: {} };
             }
             const statusByKey = new Map();
             for (const status of installResult.installedPrimitives) {
@@ -1403,7 +2059,7 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
                 const key = `${primitive.type}:${primitive.name}`;
                 const status = statusByKey.get(key);
                 const namespacedName = status?.namespacedName
-                    ?? harness.adapter.getNamespacedName(kit.name, primitive.name);
+                    ?? harness.adapter.getNamespacedName(kit.installAs, primitive.name);
                 const installedPath = status?.destination
                     ?? (primitive.type === "mcp" ? mcpConfigPath : "");
                 const installed = {
@@ -1424,14 +2080,14 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
                     }
                 }
                 if (primitive.type === "mcp") {
-                    const assignment = mcpAssignments?.get(buildPrimitiveKey(kit.name, primitive.sourcePath));
+                    const assignment = mcpAssignments?.get(buildPrimitiveKey(kit.installAs, primitive.sourcePath));
                     if (assignment) {
                         installed.instanceName = assignment.instanceName;
                         installed.configHash = assignment.configHash;
                     }
                 }
                 if (primitive.type === "hooks") {
-                    const assignment = hookAssignments?.get(buildPrimitiveKey(kit.name, primitive.sourcePath));
+                    const assignment = hookAssignments?.get(buildPrimitiveKey(kit.installAs, primitive.sourcePath));
                     if (assignment) {
                         installed.instanceName = assignment.instanceName;
                         installed.configHash = assignment.configHash;
@@ -1440,69 +2096,71 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
                 return installed;
             });
             const installedKit = {
+                name: kit.name,
+                installAs: kit.installAs,
                 version: kit.manifest.version,
                 installedAt: new Date().toISOString(),
-                source,
+                source: kit.source,
                 primitives: installedPrimitives,
             };
-            manifest.harnesses[harness.name].kits[kit.name] = installedKit;
+            lockfile.harnesses[harness.name].kits[kit.installAs] = installedKit;
             if (mcpAssignments && mcpInfoByPrimitiveKey.size > 0) {
-                const harnessEntry = manifest.harnesses[harness.name];
+                const harnessEntry = lockfile.harnesses[harness.name];
                 if (!harnessEntry.mcpInstances) {
                     harnessEntry.mcpInstances = {};
                 }
                 for (const primitive of resolvedPrimitives) {
                     if (primitive.type !== "mcp")
                         continue;
-                    const assignment = mcpAssignments.get(buildPrimitiveKey(kit.name, primitive.sourcePath));
+                    const assignment = mcpAssignments.get(buildPrimitiveKey(kit.installAs, primitive.sourcePath));
                     if (!assignment)
                         continue;
                     const instanceName = assignment.instanceName;
                     const existingInstance = harnessEntry.mcpInstances[instanceName];
                     if (existingInstance) {
-                        if (!existingInstance.usedBy.includes(kit.name)) {
-                            existingInstance.usedBy.push(kit.name);
+                        if (!existingInstance.usedBy.includes(kit.installAs)) {
+                            existingInstance.usedBy.push(kit.installAs);
                         }
                         continue;
                     }
-                    const info = mcpInfoByPrimitiveKey.get(buildPrimitiveKey(kit.name, primitive.sourcePath));
+                    const info = mcpInfoByPrimitiveKey.get(buildPrimitiveKey(kit.installAs, primitive.sourcePath));
                     if (!info)
                         continue;
                     harnessEntry.mcpInstances[instanceName] = {
                         version: info.version,
                         configHash: assignment.configHash,
-                        usedBy: [kit.name],
+                        usedBy: [kit.installAs],
                         sourcePrimitive: info.primitiveName,
                         installedAt: new Date().toISOString(),
                     };
                 }
             }
             if (hookAssignments && hookInfoByPrimitiveKey.size > 0) {
-                const harnessEntry = manifest.harnesses[harness.name];
+                const harnessEntry = lockfile.harnesses[harness.name];
                 if (!harnessEntry.hookInstances) {
                     harnessEntry.hookInstances = {};
                 }
                 for (const primitive of resolvedPrimitives) {
                     if (primitive.type !== "hooks")
                         continue;
-                    const assignment = hookAssignments.get(buildPrimitiveKey(kit.name, primitive.sourcePath));
+                    const assignment = hookAssignments.get(buildPrimitiveKey(kit.installAs, primitive.sourcePath));
                     if (!assignment)
                         continue;
                     const instanceName = assignment.instanceName;
                     const existingInstance = harnessEntry.hookInstances[instanceName];
                     if (existingInstance) {
-                        if (!existingInstance.usedBy.includes(kit.name)) {
-                            existingInstance.usedBy.push(kit.name);
+                        if (!existingInstance.usedBy.includes(kit.installAs)) {
+                            existingInstance.usedBy.push(kit.installAs);
                         }
                         continue;
                     }
-                    const info = hookInfoByPrimitiveKey.get(buildPrimitiveKey(kit.name, primitive.sourcePath));
+                    const info = hookInfoByPrimitiveKey.get(buildPrimitiveKey(kit.installAs, primitive.sourcePath));
                     if (!info)
                         continue;
                     harnessEntry.hookInstances[instanceName] = {
                         version: info.version,
                         configHash: assignment.configHash,
-                        usedBy: [kit.name],
+                        usedBy: [kit.installAs],
                         sourcePrimitive: info.primitiveName,
                         installedAt: new Date().toISOString(),
                     };
@@ -1511,6 +2169,7 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
             // Build result for output
             kitResults.push({
                 name: kit.name,
+                installAs: kit.installAs,
                 version: kit.manifest.version,
                 installed: installResult.installedPrimitives.map((p) => {
                     const primitiveOutput = {
@@ -1526,7 +2185,7 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
                 }),
             });
             if (isInteractive) {
-                logInfo(`${formatKit(kit.name, kit.manifest.version)} ${pc.green("✓")}`);
+                logInfo(`${formatKit(getKitDisplayName(kit), kit.manifest.version)} ${pc.green("✓")}`);
             }
         }
         if (kitResults.length > 0) {
@@ -1537,20 +2196,20 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
             });
         }
     }
-    // Write manifest
+    // Write lockfile
     try {
-        await writeManifest(manifest, scope, scope === "project" ? projectRoot : undefined);
+        await writeLockfile(lockfile, scope, scope === "project" ? projectRoot : undefined);
     }
     catch (error) {
         return {
             success: false,
-            error: `Failed to write manifest: ${error instanceof Error ? error.message : String(error)}`,
+            error: `Failed to write lockfile: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
     // Build output
     const output = {
         success: true,
-        source,
+        source: outputSource,
         scope,
         harnesses: harnessResults,
         skipped: skippedResults,
@@ -1598,7 +2257,7 @@ async function executeInstallation(kits, harnesses, discovery, source, options)
 /**
  * Resolve inline primitives only (when no primitives registry exists).
  */
-function resolveInlinePrimitivesOnly(kit, localPath) {
+function resolveInlinePrimitivesOnly(kit, localPath, kitInstanceName) {
     const resolved = [];
     const kitBasePath = path.join(localPath, kit.path);
     for (const [type, primitives] of Object.entries(kit.manifest.primitives)) {
@@ -1608,7 +2267,7 @@ function resolveInlinePrimitivesOnly(kit, localPath) {
             // Only handle inline primitives
             if ("name" in primitive && "entrypoint" in primitive) {
                 resolved.push({
-                    kitName: kit.name,
+                    kitName: kitInstanceName,
                     name: primitive.name,
                     type: type,
                     sourcePath: path.resolve(kitBasePath, primitive.entrypoint),