loadout-ai 0.4.1 → 0.5.0

package/dist/src/core/codex-mcp.js

@@ -16,6 +16,49 @@ function tomlString(value) {
 function tableHeader(name) {
     return `[mcp_servers.${tomlString(name)}]`;
 }
+function tablePrefix(name) {
+    return `[mcp_servers.${tomlString(name)}`;
+}
+export function codexMcpServerBlock(content, name) {
+    safeName(name);
+    const lines = content.match(/.*(?:\n|$)/g)?.filter(Boolean) ?? [];
+    const header = tableHeader(name);
+    const start = lines.findIndex((line) => line.trim() === header);
+    if (start < 0)
+        return undefined;
+    const prefix = tablePrefix(name);
+    let end = start + 1;
+    while (end < lines.length) {
+        const trimmed = lines[end].trim();
+        if (trimmed.startsWith("[") && !trimmed.startsWith(`${prefix}.`))
+            break;
+        end += 1;
+    }
+    return lines.slice(start, end).join("");
+}
+export function codexMcpServerFingerprint(content, name) {
+    const block = codexMcpServerBlock(content, name);
+    return block ? createHash("sha256").update(block).digest("hex") : undefined;
+}
+export function removeCodexMcpServerBlock(content, name) {
+    const block = codexMcpServerBlock(content, name);
+    if (!block)
+        return content;
+    return content.replace(block, "").replace(/\n{3,}/g, "\n\n");
+}
+export async function writeCodexMcpConfigContent(path, content) {
+    const target = resolve(path);
+    await mkdir(dirname(target), { recursive: true });
+    const temporary = join(dirname(target), `.${basename(target)}.loadout-${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, content, { mode: 0o600 });
+        await rename(temporary, target);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
 export function defaultCodexMcpConfigPath() {
     return join(userHome(), ".codex", "config.toml");
 }
@@ -73,7 +116,7 @@ export async function planCodexMcpConfig(path, server, name = server.name) {
 async function snapshotPath(id) {
     return join(loadoutHome(), "mcp-snapshots", `${id}.json`);
 }
-export async function applyCodexMcpConfigPlan(plan) {
+export async function applyCodexMcpConfigPlan(plan, options = {}) {
     const applied = await runMutationTransaction(async () => {
         let content = "";
         let existed = true;
@@ -100,10 +143,10 @@ export async function applyCodexMcpConfigPlan(plan) {
         };
         const stored = await snapshotPath(snapshot.id);
         return {
-            targets: [plan.path, stored],
+            targets: [plan.path, stored, ...(options.extraTargets ?? [])],
             value: { plan, snapshot, stored },
         };
-    }, async ({ plan: freshPlan, snapshot, stored }) => {
+    }, async ({ plan: freshPlan, snapshot, stored }, transactionSnapshot) => {
         await mkdir(dirname(freshPlan.path), { recursive: true });
         const temporary = join(dirname(freshPlan.path), `.${basename(freshPlan.path)}.loadout-${randomUUID()}.tmp`);
         try {
@@ -111,12 +154,13 @@ export async function applyCodexMcpConfigPlan(plan) {
             await rename(temporary, freshPlan.path);
             await mkdir(dirname(stored), { recursive: true });
             await writeFile(stored, JSON.stringify(snapshot), { mode: 0o600 });
+            await options.afterApply?.(snapshot, transactionSnapshot);
         }
         catch (error) {
             await rm(temporary, { force: true });
             throw error;
         }
         return snapshot;
-    });
-    return applied.result;
+    }, { label: `configure Codex MCP ${plan.serverName}` });
+    return { ...applied.result, rollbackSnapshotId: applied.snapshotId };
 }

package/dist/src/core/completion.js

@@ -16,8 +16,6 @@ const commands = [
     "add",
     "unadd",
     "list",
-    "demo",
-    "test-drive",
     "scan",
     "status",
     "versions",
@@ -86,7 +84,6 @@ const commands = [
     "outcomes",
     "remove",
     "uninstall",
-    "dashboard",
     "serve",
     "completion",
 ];

package/dist/src/core/health.js

@@ -4,6 +4,7 @@ import { managedFileReadPath } from "./active-set.js";
 import { detectAgents } from "./paths.js";
 import { readInstallState } from "./state.js";
 import { buildUpdatePlan } from "./update.js";
+import { codexMcpServerFingerprint } from "./codex-mcp.js";
 async function drift(record, activations) {
     const changed = [];
     for (const file of record.files) {
@@ -20,8 +21,10 @@ async function drift(record, activations) {
     }
     return changed;
 }
-async function mcpDrift(configPath, serverName, expected) {
+async function mcpDrift(configPath, serverName, expected, configFormat = "json") {
     try {
+        if (configFormat === "codex-toml")
+            return (codexMcpServerFingerprint(await readFile(configPath, "utf8"), serverName) !== expected);
         const config = JSON.parse(await readFile(configPath, "utf8"));
         return (createHash("sha256")
             .update(JSON.stringify(config.mcpServers?.[serverName] ?? null))
@@ -42,7 +45,7 @@ export async function buildHealthReport(options = {}) {
                 : Promise.resolve([]),
     ]);
     const drifted = (await Promise.all(state.installs.map((record) => drift(record, state.activations ?? [])))).flat();
-    const driftedMcpServers = (await Promise.all((state.mcpInstalls ?? []).map((entry) => mcpDrift(entry.configPath, entry.serverName, entry.fingerprint)))).filter(Boolean).length;
+    const driftedMcpServers = (await Promise.all((state.mcpInstalls ?? []).map((entry) => mcpDrift(entry.configPath, entry.serverName, entry.fingerprint, entry.configFormat)))).filter(Boolean).length;
     const findings = [];
     if (!agents.some((agent) => agent.installed))
         findings.push({
@@ -96,11 +99,14 @@ export async function buildHealthReport(options = {}) {
             message: `${errors.length} update check(s) could not be completed.`,
             fix: "Check connectivity and retry.",
         });
+    const configured = state.installs.length > 0 || (state.mcpInstalls ?? []).length > 0;
     const status = findings.some((finding) => finding.level === "error")
         ? "unhealthy"
-        : findings.some((finding) => finding.level === "warning")
-            ? "attention"
-            : "healthy";
+        : !configured
+            ? "not-configured"
+            : findings.some((finding) => finding.level === "warning")
+                ? "attention"
+                : "healthy";
     return {
         status,
         generatedAt: new Date().toISOString(),
@@ -114,13 +120,15 @@ export async function buildHealthReport(options = {}) {
     };
 }
 export function formatHealthReport(report) {
-    const icon = report.status === "healthy"
-        ? "✓"
-        : report.status === "attention"
-            ? "!"
-            : "✗";
+    const icon = report.status === "not-configured"
+        ? "•"
+        : report.status === "healthy"
+            ? "✓"
+            : report.status === "attention"
+                ? "!"
+                : "✗";
     const lines = [
-        `${icon} Loadout health: ${report.status}`,
+        `${icon} Loadout health: ${report.status === "not-configured" ? "not configured" : report.status}`,
         `Packages: ${report.installedPackages} installed, ${report.updatesChecked ? `${report.updatesAvailable} update(s)` : "updates not checked (use --updates)"}, ${report.driftedFiles} drifted file(s), ${report.driftedMcpServers} drifted MCP server(s)`,
     ];
     for (const finding of report.findings)

package/dist/src/core/install.js

@@ -209,7 +209,7 @@ export async function applySkillInstall(plan, metadata, options = {}) {
             }
         await recordInstall(freshPlan, snapshot.id, metadata);
         await options.verifyBeforeCommit?.(snapshot.id);
-    });
+    }, { label: `install ${plan.packageId}` });
     return applied.snapshotId;
 }
 /** Apply all selected packages as one filesystem transaction and one state update. */
@@ -278,7 +278,7 @@ export async function applySkillInstallBatch(entries, extraSnapshotPaths = [], o
         await recordInstallBatch(freshEntries, snapshot.id);
         await recordManagedProfileReconciliation(reconciliation);
         await options.afterRecord?.();
-    });
+    }, { label: `install ${entries.length} skill repositories` });
     return applied.snapshotId;
 }
 /**
@@ -343,7 +343,7 @@ export async function applySkillLibraryBatch(entries, options = {}) {
         }
         await recordLibraryInstallBatch(freshEntries, snapshot.id);
         await options.afterRecord?.();
-    });
+    }, { label: `download ${entries.length} repositories to Maximum library` });
     return applied.snapshotId;
 }
 export function snapshotPath(snapshotId, environment = process.env, platform = process.platform) {

package/dist/src/core/mcp-recipes.js

@@ -93,8 +93,7 @@ function recipeServer(recipe, sourcePath, credentialEnvironment = {}) {
         warnings: [],
     };
 }
-export async function planMcpRecipe(recipeId, configPath, options = {}) {
-    const recipe = findMcpRecipe(recipeId);
+function credentialEnvironmentForRecipe(recipeId, recipe, options) {
     const environment = options.environment ?? process.env;
     const credentialEnvironment = {};
     for (const name of Object.keys(options.credentialReferences ?? {}))
@@ -114,13 +113,23 @@ export async function planMcpRecipe(recipeId, configPath, options = {}) {
         }
         if (!/^[A-Z_][A-Z0-9_]*$/.test(reference.name))
             throw new Error(`Invalid environment reference for ${name}; use an uppercase variable name, never a credential value.`);
-        if (!reference.name || !environment[reference.name]) {
+        if (!environment[reference.name]) {
             if (options.requireResolvedCredentials)
-                throw new Error(`Environment credential reference '${reference.name || "(empty)"}' for ${name} did not resolve.`);
+                throw new Error(`Environment credential reference '${reference.name}' for ${name} did not resolve.`);
             continue;
         }
         credentialEnvironment[name] = reference.name;
     }
+    return credentialEnvironment;
+}
+/** Build the exact reviewed server entry without writing or launching it. */
+export function buildMcpRecipeServer(recipeId, sourcePath, options = {}) {
+    const recipe = findMcpRecipe(recipeId);
+    return recipeServer(recipe, sourcePath, credentialEnvironmentForRecipe(recipeId, recipe, options));
+}
+export async function planMcpRecipe(recipeId, configPath, options = {}) {
+    const recipe = findMcpRecipe(recipeId);
+    const credentialEnvironment = credentialEnvironmentForRecipe(recipeId, recipe, options);
     const config = await planMcpConfig(configPath, recipeServer(recipe, recipe.source, credentialEnvironment));
     return {
         recipe,

package/dist/src/core/mcp.js

@@ -221,7 +221,7 @@ export function summarizeMcpConfigPlan(plan) {
 async function snapshotPath(id) {
     return join(loadoutHome(), "mcp-snapshots", `${id}.json`);
 }
-export async function applyMcpConfigPlan(plan) {
+export async function applyMcpConfigPlan(plan, options = {}) {
     const applied = await runMutationTransaction(async () => {
         await mkdir(dirname(plan.path), { recursive: true });
         let existed = true;
@@ -246,16 +246,17 @@ export async function applyMcpConfigPlan(plan) {
         };
         const stored = await snapshotPath(snapshot.id);
         return {
-            targets: [plan.path, stored],
+            targets: [plan.path, stored, ...(options.extraTargets ?? [])],
             value: { plan, snapshot, stored },
         };
-    }, async ({ plan: freshPlan, snapshot, stored }) => {
+    }, async ({ plan: freshPlan, snapshot, stored }, transactionSnapshot) => {
         await writeMcpConfigPlan(freshPlan);
         await mkdir(dirname(stored), { recursive: true });
         await writeFile(stored, JSON.stringify(snapshot), { mode: 0o600 });
+        await options.afterApply?.(snapshot, transactionSnapshot);
         return snapshot;
-    });
-    return applied.result;
+    }, { label: `configure MCP ${plan.serverName}` });
+    return { ...applied.result, rollbackSnapshotId: applied.snapshotId };
 }
 /** Write an already-reviewed plan atomically; transaction callers own snapshot/rollback. */
 export async function writeMcpConfigPlan(plan) {

package/dist/src/core/model-config.js

@@ -57,7 +57,7 @@ export async function applyProviderModelSelection(plan) {
     }, async (configuration) => {
         await ensureDirectory(dirname(plan.path));
         await writeFileAtomically(plan.path, `${JSON.stringify(configuration, null, 2)}\n`);
-    });
+    }, { label: `configure model ${plan.selection.id}` });
     return applied.snapshotId;
 }
 export function formatProviderModelConfiguration(configuration) {

package/dist/src/core/portable.js

@@ -125,6 +125,6 @@ export async function applyPortableImport(source, manifestPath = "loadout.json",
             await Promise.all(temporary.map((path) => rm(path, { force: true })));
         }
         return plan;
-    });
+    }, { label: "import portable loadout" });
     return { plan: applied.result, snapshotId: applied.snapshotId };
 }

package/dist/src/core/recommend.js

@@ -1,6 +1,6 @@
 import { readFile, readdir } from "node:fs/promises";
 import { basename, resolve } from "node:path";
-import { STABLE_BOOST_PACKAGE_IDS } from "./profiles.js";
+import { POWER_SKILL_ALLOWLIST, STABLE_BOOST_PACKAGE_IDS } from "./profiles.js";
 import { packageOutcomeAdjustment, projectTaskFamilies, } from "./outcomes.js";
 const SIGNAL_FILES = new Set([
     "package.json",
@@ -8,6 +8,7 @@ const SIGNAL_FILES = new Set([
     "requirements.txt",
     "go.mod",
     "Cargo.toml",
+    "mix.exs",
     "Gemfile",
     "pom.xml",
     "build.gradle",
@@ -15,8 +16,10 @@ const SIGNAL_FILES = new Set([
     "next.config.mjs",
     "vite.config.ts",
     "playwright.config.ts",
+    "vercel.json",
     "SECURITY.md",
     ".git",
+    ".obsidian",
 ]);
 /** Additive machine-readable boundary for every rule-selected recommendation list. */
 export const RECOMMENDATION_BOUNDARY = Object.freeze({
@@ -31,6 +34,7 @@ const SIGNAL_LABELS = {
     release: "release automation",
     mcp: "MCP tooling",
     security: "security policy",
+    "obsidian-vault": "Obsidian vault",
     commander: "Commander",
     zod: "Zod",
     vitest: "Vitest",
@@ -44,6 +48,7 @@ const SIGNAL_DISPLAY_ORDER = [
     "release",
     "mcp",
     "security",
+    "obsidian-vault",
     "commander",
     "zod",
     "vitest",
@@ -98,6 +103,12 @@ export async function scanProject(root = process.cwd()) {
                 tools.add("commander");
             if (deps.zod)
                 tools.add("zod");
+            if (deps.express ||
+                deps.fastify ||
+                deps.koa ||
+                deps.hono ||
+                deps["@nestjs/core"])
+                roles.add("backend");
             if (pkg.bin)
                 roles.add("node-cli");
             if (pkg.publishConfig || pkg.private === false)
@@ -119,6 +130,8 @@ export async function scanProject(root = process.cwd()) {
         languages.add("go");
     if (files.includes("Cargo.toml"))
         languages.add("rust");
+    if (files.includes("mix.exs"))
+        languages.add("elixir");
     if (files.includes("Gemfile"))
         languages.add("ruby");
     if (files.includes("pom.xml") || files.includes("build.gradle"))
@@ -133,6 +146,8 @@ export async function scanProject(root = process.cwd()) {
     }
     if (files.includes("SECURITY.md"))
         roles.add("security");
+    if (files.includes(".obsidian"))
+        roles.add("obsidian-vault");
     return {
         root: absolute,
         languages: [...languages],
@@ -168,6 +183,8 @@ export function recommendPackages(signals, catalog) {
         add("playwright-mcp", "Browser verification is useful for this web-capable project.", signals.frameworks.includes("playwright") ? "high" : "medium");
     if (signals.files.includes(".git"))
         add("github-mcp-server", "A Git repository was detected; GitHub tools may help with issues and pull requests.", "medium");
+    if (signals.roles.includes("obsidian-vault"))
+        add("obsidian-skills", "An Obsidian vault was detected; these reviewed skills cover its open Markdown, Bases, and JSON Canvas formats.", "high");
     return result;
 }
 function confidenceRank(confidence) {
@@ -215,34 +232,33 @@ export function personalizeRecommendations(recommendations, signals, outcomes, a
 }
 export const TESTED_PROFILES = {
     stable: {
-        description: "Loadout policy selection: 30 skills from four pinned, SPDX-identified sources with no extra static-risk approvals.",
+        description: "30 active skills from four pinned sources: the bounded everyday starting point.",
         packages: [...STABLE_BOOST_PACKAGE_IDS],
     },
-    web: {
-        description: "Planning, documentation, interface guidance, and browser verification for web projects.",
-        packages: ["superpowers", "context7", "ui-ux-pro-max", "playwright-mcp"],
-    },
-    collaboration: {
-        description: "Engineering workflow plus GitHub collaboration tools.",
-        packages: ["superpowers", "context7", "github-mcp-server"],
+    power: {
+        description: "A deliberately larger active toolkit selected from eight pinned skill collections; expect higher agent context use.",
+        packages: Object.keys(POWER_SKILL_ALLOWLIST),
     },
     maximum: {
-        description: "Broad inspected toolkit; always review MCP permissions before applying.",
-        packages: [
-            "superpowers",
-            "context7",
-            "playwright-mcp",
-            "ui-ux-pro-max",
-            "github-mcp-server",
-        ],
+        description: "The broadest screened catalog: skills enter the disabled library and MCP/runtime integrations remain explicit.",
+        packages: [],
+    },
+    custom: {
+        description: "Only the package IDs you explicitly pass to setup or upgrade.",
+        packages: [],
     },
 };
 export function profileManifestPackages(profile, catalog) {
     const selected = TESTED_PROFILES[profile];
     if (!selected)
         throw new Error(`Unknown profile '${profile}'. Choose: ${Object.keys(TESTED_PROFILES).join(", ")}`);
+    if (profile === "custom")
+        throw new Error("Custom profiles require explicit package IDs; use setup --mode custom --package <id>");
     const byId = new Map(catalog.map((pkg) => [pkg.id, pkg]));
-    return selected.packages.map((id) => {
+    const packageIds = profile === "maximum"
+        ? catalog.filter((pkg) => !pkg.archived).map((pkg) => pkg.id)
+        : selected.packages;
+    return packageIds.map((id) => {
         const pkg = byId.get(id);
         if (!pkg)
             throw new Error(`Profile '${profile}' references missing catalog package '${id}'`);

package/dist/src/core/remove.js

@@ -3,6 +3,7 @@ import { readFile, rm } from "node:fs/promises";
 import { forgetInstall, installStatePath, readInstallState } from "./state.js";
 import { writeMcpConfigPlan } from "./mcp.js";
 import { runMutationTransaction } from "./transaction.js";
+import { codexMcpServerFingerprint, removeCodexMcpServerBlock, writeCodexMcpConfigContent, } from "./codex-mcp.js";
 export async function planRemove(packageId) {
     const state = await readInstallState();
     const record = state.installs.find((entry) => entry.packageId === packageId);
@@ -28,11 +29,26 @@ export async function planRemove(packageId) {
     const modified = files.filter((file) => file.status === "modified");
     const mcpServers = await Promise.all(trackedMcp.map(async (entry) => {
         try {
+            if (entry.configFormat === "codex-toml") {
+                const content = await readFile(entry.configPath, "utf8");
+                const fingerprint = codexMcpServerFingerprint(content, entry.serverName);
+                return {
+                    configPath: entry.configPath,
+                    serverName: entry.serverName,
+                    configFormat: "codex-toml",
+                    status: !fingerprint
+                        ? "missing"
+                        : fingerprint === entry.fingerprint
+                            ? "unchanged"
+                            : "modified",
+                };
+            }
             const config = JSON.parse(await readFile(entry.configPath, "utf8"));
             if (!config.mcpServers || !(entry.serverName in config.mcpServers))
                 return {
                     configPath: entry.configPath,
                     serverName: entry.serverName,
+                    configFormat: "json",
                     status: "missing",
                 };
             const fingerprint = createHash("sha256")
@@ -41,6 +57,7 @@ export async function planRemove(packageId) {
             return {
                 configPath: entry.configPath,
                 serverName: entry.serverName,
+                configFormat: "json",
                 status: fingerprint === entry.fingerprint
                     ? "unchanged"
                     : "modified",
@@ -50,6 +67,7 @@ export async function planRemove(packageId) {
             return {
                 configPath: entry.configPath,
                 serverName: entry.serverName,
+                configFormat: entry.configFormat ?? "json",
                 status: "missing",
             };
         }
@@ -96,11 +114,19 @@ export async function applyRemove(plan, options = {}) {
         for (const file of existing)
             await rm(file, { force: true });
         for (const configPath of configPaths) {
+            const relevant = fresh.mcpServers.filter((entry) => entry.configPath === configPath && entry.status !== "missing");
+            if (relevant.some((entry) => entry.configFormat === "codex-toml")) {
+                let content = await readFile(configPath, "utf8");
+                for (const entry of relevant)
+                    content = removeCodexMcpServerBlock(content, entry.serverName);
+                await writeCodexMcpConfigContent(configPath, content);
+                continue;
+            }
             const current = JSON.parse(await readFile(configPath, "utf8"));
             const servers = {
                 ...(current.mcpServers ?? {}),
             };
-            const removals = fresh.mcpServers.filter((entry) => entry.configPath === configPath && entry.status !== "missing");
+            const removals = relevant;
             for (const entry of removals)
                 delete servers[entry.serverName];
             await writeMcpConfigPlan({
@@ -116,6 +142,6 @@ export async function applyRemove(plan, options = {}) {
             });
         }
         await forgetInstall(plan.packageId);
-    });
+    }, { label: `remove ${plan.packageId}` });
     return applied.snapshotId;
 }

package/dist/src/core/runtime-tool-recipe.js

@@ -205,11 +205,11 @@ export const runtimeToolRecipeSchema = z
         .strict(),
     snapshotRoots: z
         .array(z.enum(["{runtimeRoot}", "{agentTargets}"]))
-        .refine((values) => values.includes("{runtimeRoot}") && values.includes("{agentTargets}"), "runtime and agent targets must both be snapshotted"),
+        .refine((values) => values.includes("{agentTargets}"), "agent targets must be snapshotted"),
     removal: z
         .object({
         strategy: z.literal("restore-preinstall-snapshot"),
-        runtimeRoot: z.literal("restore-preinstall-state"),
+        runtimeRoot: z.literal("remove-managed-runtime"),
     })
         .strict(),
     generatedFiles: generatedFilesSchema,

package/dist/src/core/runtime-tools.js

@@ -147,10 +147,10 @@ export const GRAPHIFY_RECIPE = deepFreeze(parseRuntimeToolRecipe({
         "kiro-cli": { path: [".kiro", "skills", "graphify"] },
     },
     timeouts: { commandMs: 300_000 },
-    snapshotRoots: ["{runtimeRoot}", "{agentTargets}"],
+    snapshotRoots: ["{agentTargets}"],
     removal: {
         strategy: "restore-preinstall-snapshot",
-        runtimeRoot: "restore-preinstall-state",
+        runtimeRoot: "remove-managed-runtime",
     },
     generatedFiles: {
         requiredRelativePaths: ["SKILL.md"],
@@ -402,12 +402,24 @@ export async function applyRuntimeToolPlan(plan, options) {
         await restoreSnapshot(snapshot, {
             requireUnchangedPostMutationState: true,
         });
+        await rm(installed.runtimeRoot, { recursive: true, force: true });
         delete state.tools[plan.recipe.id];
         await writeState(state, plan.stateHome);
         return { action: "remove", snapshotId: snapshot.id };
     }
     if (state.tools[plan.recipe.id])
         throw new Error(`${plan.recipe.displayName} is already managed by Loadout`);
+    try {
+        await access(plan.runtimeRoot);
+        throw new Error(`${plan.recipe.displayName} runtime path already exists outside managed state: ${plan.runtimeRoot}`);
+    }
+    catch (error) {
+        if (!error ||
+            typeof error !== "object" ||
+            !("code" in error) ||
+            error.code !== "ENOENT")
+            throw error;
+    }
     let snapshot;
     try {
         const snapshotRoots = plan.recipe.snapshotRoots.flatMap((root) => root === "{runtimeRoot}"
@@ -453,8 +465,7 @@ export async function applyRuntimeToolPlan(plan, options) {
     catch (error) {
         if (snapshot)
             await restoreSnapshot(snapshot).catch(() => undefined);
-        else
-            await rm(plan.runtimeRoot, { recursive: true, force: true });
+        await rm(plan.runtimeRoot, { recursive: true, force: true });
         throw error;
     }
 }

package/dist/src/core/snapshot.js

@@ -10,6 +10,7 @@ export async function createSnapshot(paths, options = {}) {
             .digest("hex")
             .slice(0, 12)}`,
         createdAt: new Date().toISOString(),
+        ...(options.label ? { label: options.label } : {}),
         roots: normalizedRoots,
         files: [],
     };
@@ -154,6 +155,22 @@ export async function listSnapshotIds() {
         throw error;
     }
 }
+function changedEntryCount(before, after) {
+    if (!after)
+        return undefined;
+    const previous = new Map(before.map((file) => [file.path, file]));
+    const next = new Map(after.map((file) => [file.path, file]));
+    return [...new Set([...previous.keys(), ...next.keys()])].filter((path) => JSON.stringify(previous.get(path)) !== JSON.stringify(next.get(path))).length;
+}
+export function summarizeSnapshot(snapshot) {
+    return {
+        id: snapshot.id,
+        createdAt: snapshot.createdAt,
+        label: snapshot.label ?? "managed change",
+        roots: snapshot.roots.length,
+        changedEntries: changedEntryCount(snapshot.files, snapshot.postMutationFiles),
+    };
+}
 const SNAPSHOT_ID = /^\d{10,}-[a-f0-9]{12}$/;
 function isSnapshotId(value) {
     return SNAPSHOT_ID.test(value);
@@ -186,6 +203,9 @@ export function validateSnapshot(value) {
     if (typeof value.createdAt !== "string" ||
         !Number.isFinite(Date.parse(value.createdAt)))
         throw new Error("Snapshot creation time is invalid");
+    if (value.label !== undefined &&
+        (typeof value.label !== "string" || value.label.trim().length === 0))
+        throw new Error("Snapshot label is invalid");
     if (!Array.isArray(value.roots) ||
         value.roots.length === 0 ||
         !value.roots.every((root) => typeof root === "string" && root.length > 0))

package/dist/src/core/state.js

@@ -302,6 +302,15 @@ export async function recordInstallTransaction(entries, mcpEntries, snapshotId)
     await writeInstallState(state);
     return { installs, mcpInstalls };
 }
+/** Record one externally formatted but Loadout-managed MCP entry. */
+export async function recordMcpInstall(record) {
+    const state = await readInstallState();
+    state.mcpInstalls = [
+        ...(state.mcpInstalls ?? []).filter((entry) => entry.packageId !== record.packageId),
+        record,
+    ];
+    await writeInstallState(state);
+}
 export async function forgetInstall(packageId) {
     const state = await readInstallState();
     const installs = state.installs.filter((entry) => entry.packageId !== packageId);

package/dist/src/core/sync.js

@@ -343,6 +343,6 @@ export async function applySyncPlan(plan, lockPath = "loadout.lock", options = {
             await writeMcpConfigPlan(entry.plan);
         await recordInstallTransaction(freshPlan.packages, freshPlan.mcpPlans, snapshot.id);
         await writeLockfile(freshPlan.resolvedManifest ?? (await readManifest(freshPlan.manifest)), lockPath);
-    });
+    }, { label: "synchronize loadout manifest" });
     return { snapshotId: applied.snapshotId, lockfile: lockPath };
 }

package/dist/src/core/transaction.js

@@ -123,13 +123,14 @@ export async function withMutationLock(operation) {
  * global lock. Network/source preparation should happen before this boundary;
  * every state-dependent precondition belongs in `prepare`.
  */
-export async function runMutationTransaction(prepare, mutate) {
+export async function runMutationTransaction(prepare, mutate, options = {}) {
     const mutationLock = await acquireMutationLock();
     let transaction;
     try {
         const prepared = await prepare();
         const snapshot = await createSnapshot(prepared.targets, {
             persist: false,
+            label: options.label,
         });
         transaction = await beginTransaction(snapshot, prepared.targets, {
             mutationLock,

package/dist/src/shared/schemas.js

@@ -275,6 +275,7 @@ export const installRecordSchema = z
     files: z.array(fileHashSchema),
     snapshotId: text,
     installedAt: text,
+    configFormat: z.enum(["json", "codex-toml"]).optional(),
     staticAssessment: z
         .object({
         status: z.enum(["clear", "warning", "blocking"]),