loadout-ai 0.5.3 → 0.5.4

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+## 0.5.4 - 2026-07-21
+
+### Added
+
+- Add `loadout reconcile` to compare complete existing skill trees with pinned
+  catalog units, group identical cross-agent mirrors, adopt exact matches without
+  rewriting them, and preview unambiguous outdated replacements separately.
+- Add immutable, licensed catalog records for the official Cloudflare Skills
+  collection and Humanizer, with direct upstream credit links.
+
+### Changed
+
+- Index safe skill siblings even when another unit in the same collection is
+  quarantined; repository metadata such as `.git`, caches, and `node_modules` is
+  excluded from the distributable security tree.
+- Scan both Codex's canonical `~/.agents/skills` directory and its current
+  `~/.codex/skills` compatibility directory while excluding host-bundled `.system`
+  skills.
+
+### Fixed
+
+- Preserve the exact existing host path and exact adopted skill unit during later
+  repository updates instead of broadening a collection or moving a Codex skill.
+- Verify every outdated reconciliation copy byte-for-byte before ownership state is
+  committed, with one rollback snapshot for the grouped transaction.
+
 ## 0.5.3 - 2026-07-21
 
 ### Fixed

package/MASTER_PLAN.md

@@ -294,6 +294,30 @@ merged `codex/relatable-readme-hero` remote branch remains safe to delete after
       surface runtime/MCP totals and missing targets, label runtime snapshots, and
       raise the default cold MCP handshake window to the tested 30 seconds. Release
       as `0.5.3` before continuing Graphify removal and discovery/update acceptance.
+- [x] `P18-40 [TERRA]` Scan both Codex's canonical and current compatibility skill
+      roots, exclude host-bundled `.system` entries, and count runtime-tool targets
+      once. The real founder preview now reports 47 visible skills: 13 Claude, 12
+      Codex, 11 Cursor, and 11 Windsurf.
+- [x] `P18-41 [TERRA]` Credit and pin the official Apache-2.0 Cloudflare Skills
+      collection and MIT Humanizer repository as catalog sources. Index safe siblings
+      independently so one quarantined unit cannot hide every valid skill in a large
+      collection.
+- [x] `P18-42 [TERRA]` Add grouped existing-skill reconciliation. Exact complete-tree
+      matches can be adopted without rewriting bytes; Git origins disambiguate
+      same-name candidates; outdated replacement remains explicit, risk-gated,
+      byte-verified, and one rollback-safe transaction.
+- [x] `P18-43 [TERRA]` Preserve an adopted skill's exact unit and existing host path
+      during future updates, including Codex compatibility-root installations. The
+      real read-only preview found eight exact groups, two unambiguous old groups,
+      and left two quarantined/unknown groups untouched. The complete local release
+      gate passes 114 test files with 616 passing tests and one intentional skip,
+      both CLI product journeys, package smoke, and a 1,000-skill scan at 1,422.7 ms
+      p95 across seven real CLI runs.
+- [ ] `P18-44 [HUMAN+TERRA]` Publish and install `loadout-ai@0.5.4`, run
+      `loadout reconcile --refresh`, adopt the eight exact groups, inspect the
+      Humanizer and Turnstile update findings before any replacement, then finish
+      read-only update/discovery, Graphify removal, complete uninstall, and clean
+      reinstall acceptance.
 
 ### Release 0.3 lifecycle hardening
 

package/README.md

@@ -26,7 +26,7 @@
 </p>
 
 > [!IMPORTANT]
-> Installation is version-pinned so the code you test matches these docs. The commands below target `loadout-ai@0.5.3`; review the preview before every apply.
+> Installation is version-pinned so the code you test matches these docs. The commands below target `loadout-ai@0.5.4`; review the preview before every apply.
 
 ## How it works
 
@@ -76,7 +76,7 @@ Skills, plugins, MCP servers, and agent settings tend to accumulate one experime
 You need Node.js 20 or newer and Git.
 
 ```bash
-npm install --global loadout-ai@0.5.3
+npm install --global loadout-ai@0.5.4
 loadout --version
 loadout guide
 ```
@@ -117,6 +117,29 @@ loadout rollback
 
 Stable currently selects 30 skill directories from four pinned, SPDX-identified, policy-selected public sources. Selection policy is evidence, not a claim that the sources are safe, trusted, human-reviewed, benchmarked, or the right choice for every user.
 
+## Manage skills you already have
+
+Loadout can compare existing Claude, Codex, Cursor, and other detected-agent skills
+with complete skill trees from pinned catalog sources:
+
+```bash
+# Read-only inventory and source/update comparison
+loadout scan
+loadout reconcile --refresh
+
+# Record ownership only for exact byte-for-byte matches; files are not rewritten
+loadout reconcile --yes
+
+# Preview old copies that have one unambiguous reviewed source
+loadout reconcile --replace-outdated
+```
+
+Unknown or ambiguous copies remain untouched. Replacing an outdated tree is a
+separate `--replace-outdated --yes` transaction, may require `--approve-risk`, and
+creates one rollback snapshot. Once adopted or replaced, `loadout update` tracks the
+exact upstream repository and skill unit while preserving the agent path already in
+use.
+
 ## Profiles
 
 | Profile     | Scope                                                                 |
@@ -170,13 +193,13 @@ tools always remain an explicit choice.
 
 <!-- loadout:catalog-coverage:start -->
 
-The bundled catalog currently contains **51 credited public repositories** across **38 categories**: **32 have skill components** and **19 are MCP-only**. All 51 are technically screened and pinned; 4 sources are selected by the bounded Stable policy. See every linked source, license status, component type, and pinned commit in **[Catalog and upstream credits](./docs/CATALOG.md)**.
+The bundled catalog currently contains **53 credited public repositories** across **39 categories**: **34 have skill components** and **19 are MCP-only**. All 53 are technically screened and pinned; 4 sources are selected by the bounded Stable policy. See every linked source, license status, component type, and pinned commit in **[Catalog and upstream credits](./docs/CATALOG.md)**.
 
 <!-- loadout:catalog-coverage:end -->
 
 <!-- loadout:evidence-stages:start -->
 
-Catalog maturity: **51 sourced**, **51 technically inspected**, and **4 selected for Stable**. Independent human-review attestations and signed comparative benchmarks are not yet published, so Loadout does not pretend static inspection proves usefulness. The pinned catalog remains usable today, and local outcomes can be recorded to improve later rankings. Definitions and promotion rules are in the [catalog policy](./docs/CATALOG_POLICY.md).
+Catalog maturity: **53 sourced**, **53 technically inspected**, and **4 selected for Stable**. Independent human-review attestations and signed comparative benchmarks are not yet published, so Loadout does not pretend static inspection proves usefulness. The pinned catalog remains usable today, and local outcomes can be recorded to improve later rankings. Definitions and promotion rules are in the [catalog policy](./docs/CATALOG_POLICY.md).
 
 <!-- loadout:evidence-stages:end -->
 
@@ -232,6 +255,7 @@ Configured paths and disposable filesystem lifecycle tests do not prove that nat
 | Guided read-only path              | `loadout guide`                             |
 | Preview or apply a profile         | `loadout setup --mode stable [--yes]`       |
 | List and inspect managed state     | `loadout list`; `loadout health --explain`  |
+| Compare/manage existing skills     | `loadout reconcile [--refresh]`             |
 | Browse or search                   | `loadout catalog`; `loadout search <words>` |
 | Recommend for a project            | `loadout recommend --project .`             |
 | Preview or apply updates           | `loadout update [--yes]`                    |
@@ -274,7 +298,7 @@ The repository's mixed README product-flow test uses an isolated build, disposab
 
 Keep changes scoped, add regression coverage for behavior changes, and run `npm run verify:full`. Report vulnerabilities through [SECURITY.md](./SECURITY.md), without credentials, private source, or unredacted state. General bugs and proposals belong in the [issue tracker](https://github.com/VirajMishra1/loadout/issues).
 
-The catalog contains 51 credited public repositories. Inclusion records discovery and attribution; it does not transfer ownership, imply endorsement, or relicense upstream work.
+The catalog contains 53 credited public repositories. Inclusion records discovery and attribution; it does not transfer ownership, imply endorsement, or relicense upstream work.
 
 ## License
 

package/catalog/packages.json

@@ -1172,5 +1172,52 @@
       ],
       "verifiedAt": "2026-07-21T08:45:00Z"
     }
+  },
+  {
+    "id": "cloudflare-skills",
+    "displayName": "Cloudflare Skills",
+    "repository": "cloudflare/skills",
+    "description": "Official agent skills for building on Cloudflare, Workers, Agents SDK, Durable Objects, Wrangler, and related platform services.",
+    "category": "cloud-platform",
+    "tier": "official",
+    "license": "Apache-2.0",
+    "components": ["skill", "plugin", "mcp"],
+    "operatingSystems": ["windows", "macos", "linux"],
+    "stars": 2443,
+    "pushedAt": "2026-07-13T22:00:33Z",
+    "source": {
+      "type": "github",
+      "url": "https://github.com/cloudflare/skills",
+      "defaultBranch": "main",
+      "commit": "70215303d44a81a0db3219428f4825b604fc6061",
+      "evidencePaths": [
+        "skills/cloudflare/SKILL.md",
+        "skills/agents-sdk/SKILL.md",
+        ".claude-plugin/plugin.json",
+        ".mcp.json"
+      ],
+      "verifiedAt": "2026-07-21T13:38:00Z"
+    }
+  },
+  {
+    "id": "humanizer",
+    "displayName": "Humanizer",
+    "repository": "blader/humanizer",
+    "description": "A writing skill that identifies common AI-generated prose patterns and rewrites text in a more natural voice.",
+    "category": "writing",
+    "tier": "community",
+    "license": "MIT",
+    "components": ["skill"],
+    "operatingSystems": ["windows", "macos", "linux"],
+    "stars": 30153,
+    "pushedAt": "2026-06-29T20:43:06Z",
+    "source": {
+      "type": "github",
+      "url": "https://github.com/blader/humanizer",
+      "defaultBranch": "main",
+      "commit": "1b48564898e999219882660237fde01bf4843a0f",
+      "evidencePaths": ["SKILL.md", "README.md", "LICENSE"],
+      "verifiedAt": "2026-07-21T13:38:00Z"
+    }
   }
 ]

package/dist/src/cli.js

@@ -50,6 +50,7 @@ import { compareSkill, formatSkillComparison } from "./core/skill-compare.js";
 import { applyActivationChange, buildLibraryStateReport, formatActivationPlan, formatLibrarySummary, formatLibraryStateReport, planActivationChange, } from "./core/active-set.js";
 import { applyProjectActivation, formatProjectActivation, planProjectActivation, } from "./core/active-policy.js";
 import { applySkillAdoption, formatAdoptionPlan, planSkillAdoption, } from "./core/adopt.js";
+import { applyReconcilePlan, buildReconcilePlan, formatReconcilePlan, } from "./core/reconcile.js";
 import { formatReviewQueue, mergeReviewQueue, readReviewQueue, setReviewDecision, } from "./core/review-queue.js";
 import { applyProviderModelSelection, defaultModelConfigurationPath, formatProviderModelConfiguration, planProviderModelSelection, readProviderModelConfiguration, requestOpenRouter, } from "./core/model-config.js";
 import { applyNativeScheduler, applyNativeSchedulerBundle, formatNativeScheduler, planNativeScheduler, } from "./core/scheduler.js";
@@ -263,7 +264,7 @@ async function runSetup(options) {
         reader?.close();
     }
 }
-const LOADOUT_VERSION = "0.5.3";
+const LOADOUT_VERSION = "0.5.4";
 function durableSchedulerLauncher() {
     return [
         join(dirname(process.execPath), process.platform === "win32" ? "npx.cmd" : "npx"),
@@ -1183,6 +1184,47 @@ program
         ? JSON.stringify(enriched, null, 2)
         : `${formatInstalledSkillInventory(enriched)}\n${formatProvenanceSummary(enriched)}`);
 });
+program
+    .command("reconcile")
+    .description("Match existing unmanaged skills to pinned sources, group mirrors, and preview safe ownership or updates")
+    .option("--agents <ids>", "comma-separated agent ids; defaults to detected agents")
+    .option("--refresh", "rebuild the inspected catalog skill index")
+    .option("--replace-outdated", "replace unambiguous outdated trees with their reviewed pinned source")
+    .option("--approve-risk", "approve the exact safety findings shown for outdated replacements")
+    .option("--yes", "apply the displayed transaction; otherwise preview")
+    .option("--json", "emit machine-readable output")
+    .action(async (options) => {
+    const detected = await detectAgents();
+    const requested = parseAgentSelection(options.agents);
+    const selected = requested?.length
+        ? detected.filter((agent) => requested.includes(agent.id) && agent.installed)
+        : detected.filter((agent) => agent.installed);
+    if (!selected.length)
+        throw new Error("No detected agent profile is available to reconcile");
+    const resolved = await resolveCatalogSkillIndex({
+        refresh: options.refresh,
+        build: {
+            catalog: await loadEffectiveCatalog(),
+            onProgress: options.refresh ? printProvenanceProgress : undefined,
+        },
+    });
+    if (!resolved.index)
+        throw new Error("No reviewed catalog skill index is available");
+    const plan = await buildReconcilePlan(selected, resolved.index);
+    if (!options.yes) {
+        console.log(options.json
+            ? JSON.stringify(plan, null, 2)
+            : `${formatReconcilePlan(plan)}\n\nDry run only. Re-run with --yes to adopt exact matches.${plan.summary.outdated ? " Add --replace-outdated to include the reviewed updates shown above." : ""}`);
+        return;
+    }
+    const result = await applyReconcilePlan(plan, {
+        replaceOutdated: options.replaceOutdated,
+        approveRisk: options.approveRisk,
+    });
+    console.log(options.json
+        ? JSON.stringify({ plan, result }, null, 2)
+        : `${formatReconcilePlan(plan)}\n\nReconciled ${result.adopted} exact group(s) and ${result.updated} outdated group(s). Snapshot: ${result.snapshotId}`);
+});
 program
     .command("adopt")
     .description("Take ownership of one explicitly selected installed skill without changing its bytes")

package/dist/src/core/cli-guide.js

@@ -4,6 +4,8 @@ START HERE
 
 1. See what Loadout currently manages
    loadout library
+   loadout scan
+   loadout reconcile
 
 2. Preview the recommended everyday setup
    loadout setup --mode stable
@@ -26,6 +28,9 @@ START HERE
 If you decide to install something, Loadout shows a preview first and creates a
 snapshot before changing managed files. Recover with: loadout rollback
 
+Reconcile is also read-only unless you add --yes. Exact matches can be managed
+without rewriting them; outdated replacements remain a separate explicit choice.
+
 Nothing above changes your agents. For the full maintainer/tooling surface, run:
 loadout advanced
 `.trim();

package/dist/src/core/completion.js

@@ -17,6 +17,7 @@ const commands = [
     "unadd",
     "list",
     "scan",
+    "reconcile",
     "status",
     "versions",
     "intelligence",

package/dist/src/core/paths.js

@@ -19,6 +19,7 @@ export const AGENT_DEFINITIONS = [
         // not exposed on the shell PATH. The shared Agent Skills root (~/.agents)
         // is also valid evidence when it already exists.
         detectionDirectories: [[".codex"], [".agents"]],
+        additionalSkillDirectories: [[".codex", "skills"]],
     },
     {
         id: "cursor",
@@ -181,6 +182,9 @@ export async function detectAgents(options = {}) {
         const path = platform === "win32" ? win32 : posix;
         const skillsDirectory = agentSkillsDirectory(definition.id, home, platform);
         const detectionDirectories = definition.detectionDirectories?.map((parts) => path.join(home, ...parts)) ?? [dirnameForDetection(skillsDirectory)];
+        const additionalSkillsDirectories = definition.additionalSkillDirectories
+            ?.map((parts) => path.join(home, ...parts))
+            .filter((directory) => directory !== skillsDirectory) ?? [];
         return {
             id: definition.id,
             displayName: definition.displayName,
@@ -190,6 +194,9 @@ export async function detectAgents(options = {}) {
                 : false) ||
                 (await Promise.all(detectionDirectories.map((directory) => directoryExists(directory)))).some(Boolean),
             skillsDirectory,
+            ...(additionalSkillsDirectories.length
+                ? { additionalSkillsDirectories }
+                : {}),
         };
     }));
 }

package/dist/src/core/provenance.js

@@ -105,7 +105,14 @@ export async function buildCatalogSkillIndex(options = {}) {
             });
             if (snapshot.commit.toLowerCase() !== pkg.source.commit.toLowerCase())
                 throw new Error(`resolved ${snapshot.commit}, expected ${pkg.source.commit}`);
-            const directories = await discoverSkillDirectories(snapshot.path);
+            const rejected = [];
+            const directories = await discoverSkillDirectories(snapshot.path, {
+                continueOnRejected: true,
+                onRejected: (skill) => rejected.push({
+                    name: skill.name ?? skill.targetName,
+                    reason: skill.reason,
+                }),
+            });
             const records = await Promise.all(directories.map(async (directory) => {
                 const content = await readFile(join(directory, "SKILL.md"), "utf8");
                 const description = cleanFrontmatterValue(content.match(/^description:\s*(.+)$/m)?.[1]);
@@ -131,9 +138,23 @@ export async function buildCatalogSkillIndex(options = {}) {
                 completed,
                 total: packages.length,
                 status: "ready",
-                message: `${pkg.displayName}: ${records.length} reviewed skill(s) indexed`,
+                message: `${pkg.displayName}: ${records.length} reviewed skill(s) indexed${rejected.length ? `; ${rejected.length} quarantined` : ""}`,
             });
-            return { records };
+            return {
+                records,
+                ...(rejected.length
+                    ? {
+                        failure: {
+                            packageId: pkg.id,
+                            repository: pkg.repository,
+                            error: `${rejected.length} skill unit(s) quarantined: ${rejected
+                                .map((item) => item.name)
+                                .sort()
+                                .join(", ")}`,
+                        },
+                    }
+                    : {}),
+            };
         }
         catch (error) {
             completed += 1;

package/dist/src/core/reconcile.js

@@ -0,0 +1,300 @@
+import { createHash } from "node:crypto";
+import { cp, lstat, readFile, readdir, rm } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { analyzeUpdateSafety } from "./safety.js";
+import { enrichInventoryWithProvenance, } from "./provenance.js";
+import { scanInstalledSkills } from "./skill-inventory.js";
+import { installStatePath, recordInstallBatch } from "./state.js";
+import { runMutationTransaction } from "./transaction.js";
+import { repositoryCachePath } from "./source.js";
+import { validateSkillDirectory } from "./skills.js";
+const issuedPlans = new WeakMap();
+const IGNORED_TREE_NAMES = new Set([".git", ".cache", "node_modules"]);
+function slug(value) {
+    return (value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 48) || "skill");
+}
+async function captureTree(root) {
+    const rootInfo = await lstat(root);
+    if (!rootInfo.isDirectory() || rootInfo.isSymbolicLink())
+        throw new Error(`Refusing unsafe reconciliation root: ${root}`);
+    const entries = [];
+    async function visit(directory) {
+        const children = (await readdir(directory, { withFileTypes: true })).sort((left, right) => left.name.localeCompare(right.name));
+        for (const child of children) {
+            if (IGNORED_TREE_NAMES.has(child.name))
+                continue;
+            const path = join(directory, child.name);
+            if (child.isSymbolicLink())
+                throw new Error(`Refusing symlink in reconciliation tree: ${path}`);
+            if (child.isDirectory())
+                await visit(path);
+            else if (child.isFile())
+                entries.push({
+                    path: relative(root, path).split(sep).join("/"),
+                    sha256: createHash("sha256")
+                        .update(await readFile(path))
+                        .digest("hex"),
+                });
+        }
+    }
+    await visit(root);
+    return entries;
+}
+function treeSignature(tree) {
+    return JSON.stringify(tree);
+}
+function uniqueFindings(findings) {
+    return [
+        ...new Map(findings.map((finding) => [
+            `${finding.severity}:${finding.category}:${finding.message}:${finding.paths.join(",")}:${finding.names?.join(",") ?? ""}`,
+            finding,
+        ])).values(),
+    ];
+}
+function planSignature(plan) {
+    return JSON.stringify(plan.items.map((item) => ({
+        name: item.name,
+        fingerprint: item.fingerprint,
+        status: item.status,
+        packageId: item.packageId,
+        candidate: item.candidate
+            ? [
+                item.candidate.packageId,
+                item.candidate.commit,
+                item.candidate.skillPath,
+            ]
+            : undefined,
+        installations: item.installations.map((installation) => ({
+            agent: installation.agent,
+            path: installation.path,
+            tree: installation.tree,
+        })),
+    })));
+}
+function candidateSource(candidate) {
+    return join(repositoryCachePath(candidate.repository, candidate.commit), candidate.skillPath);
+}
+async function itemFor(name, fingerprint, installations, index) {
+    const captured = await Promise.all(installations.map(async (installation) => ({
+        ...installation,
+        tree: await captureTree(installation.path),
+    })));
+    const namedCandidates = index.records.filter((record) => record.skillName.trim().toLowerCase() === name.toLowerCase());
+    const repositoryOrigins = new Set(installations
+        .flatMap((installation) => installation.repositoryOrigin ?? [])
+        .map((origin) => origin.toLowerCase()));
+    const hintedCandidates = namedCandidates.filter((record) => repositoryOrigins.has(record.repository.toLowerCase()));
+    const candidates = hintedCandidates.length
+        ? hintedCandidates
+        : namedCandidates;
+    const available = (await Promise.all(candidates.map(async (candidate) => {
+        const sourcePath = candidateSource(candidate);
+        try {
+            const tree = await captureTree(sourcePath);
+            return { candidate, sourcePath, tree };
+        }
+        catch {
+            return undefined;
+        }
+    }))).filter((item) => Boolean(item));
+    const exact = available.filter((entry) => captured.every((installation) => treeSignature(installation.tree) === treeSignature(entry.tree)));
+    const selected = exact.length === 1 ? exact[0] : available[0];
+    const packageId = selected
+        ? `adopted-${slug(selected.candidate.packageId)}-${slug(name)}-${fingerprint.slice(0, 8)}`
+        : undefined;
+    if (exact.length === 1 && selected)
+        return {
+            name,
+            fingerprint,
+            status: "exact",
+            installations: captured,
+            packageId,
+            candidate: selected.candidate,
+            sourcePath: selected.sourcePath,
+            safetyFindings: [],
+            approvalRequired: false,
+            reason: "Every installed file exactly matches one pinned catalog skill tree.",
+        };
+    if (available.length === 1 && selected) {
+        const safety = uniqueFindings((await Promise.all(captured.map((installation) => analyzeUpdateSafety(installation.path, selected.sourcePath)))).flatMap((analysis) => analysis.findings));
+        return {
+            name,
+            fingerprint,
+            status: "outdated",
+            installations: captured,
+            packageId,
+            candidate: selected.candidate,
+            sourcePath: selected.sourcePath,
+            safetyFindings: safety,
+            approvalRequired: safety.some((finding) => finding.severity === "blocking"),
+            reason: "One reviewed same-name upstream skill exists, but the installed tree differs.",
+        };
+    }
+    if (available.length > 1)
+        return {
+            name,
+            fingerprint,
+            status: "ambiguous",
+            installations: captured,
+            safetyFindings: [],
+            approvalRequired: false,
+            reason: `${available.length} reviewed same-name candidates exist; Loadout will not guess which source owns these bytes.`,
+        };
+    return {
+        name,
+        fingerprint,
+        status: "unknown",
+        installations: captured,
+        safetyFindings: [],
+        approvalRequired: false,
+        reason: "No reviewed same-name catalog source is available.",
+    };
+}
+export async function buildReconcilePlan(agents, index) {
+    const inventory = enrichInventoryWithProvenance(await scanInstalledSkills(agents), index, "cache");
+    const groups = new Map();
+    for (const skill of inventory.skills.filter((entry) => !entry.managed)) {
+        const key = `${skill.name.toLowerCase()}\0${skill.fingerprint}`;
+        const values = groups.get(key) ?? [];
+        values.push({
+            agent: skill.agent,
+            path: skill.path,
+            name: skill.name,
+            fingerprint: skill.fingerprint,
+            ...(skill.repositoryOrigin
+                ? { repositoryOrigin: skill.repositoryOrigin }
+                : {}),
+        });
+        groups.set(key, values);
+    }
+    const items = await Promise.all([...groups.values()].map((group) => itemFor(group[0].name, group[0].fingerprint, group.map(({ agent, path, repositoryOrigin }) => ({
+        agent,
+        path,
+        ...(repositoryOrigin ? { repositoryOrigin } : {}),
+    })), index)));
+    items.sort((left, right) => left.status.localeCompare(right.status) ||
+        left.name.localeCompare(right.name));
+    const count = (status) => items.filter((item) => item.status === status).length;
+    const plan = {
+        generatedAt: new Date().toISOString(),
+        items,
+        summary: {
+            existing: items.reduce((total, item) => total + item.installations.length, 0),
+            exact: count("exact"),
+            outdated: count("outdated"),
+            ambiguous: count("ambiguous"),
+            unknown: count("unknown"),
+            mirroredGroups: items.filter((item) => item.installations.length > 1)
+                .length,
+        },
+    };
+    issuedPlans.set(plan, { signature: planSignature(plan) });
+    return plan;
+}
+function installPlanFor(item, replace) {
+    if (!item.packageId || !item.candidate || !item.sourcePath)
+        throw new Error(`Reconciliation item '${item.name}' has no reviewed source`);
+    return {
+        packageId: item.packageId,
+        targetAgents: [...new Set(item.installations.map((entry) => entry.agent))],
+        warnings: [],
+        files: item.installations.map((installation) => ({
+            source: replace ? item.sourcePath : installation.path,
+            target: installation.path,
+            targetAgent: installation.agent,
+            componentType: "skill",
+            compatibility: "native",
+            skillName: item.name,
+        })),
+    };
+}
+async function assertPlanUnchanged(plan) {
+    const issued = issuedPlans.get(plan);
+    if (!issued || issued.signature !== planSignature(plan))
+        throw new Error("Reconciliation plan changed after preview; preview again.");
+    for (const item of plan.items)
+        for (const installation of item.installations)
+            if (treeSignature(await captureTree(installation.path)) !==
+                treeSignature(installation.tree))
+                throw new Error(`Existing skill changed after preview: ${installation.path}`);
+}
+export async function applyReconcilePlan(plan, options = {}) {
+    await assertPlanUnchanged(plan);
+    const exact = plan.items.filter((item) => item.status === "exact");
+    const outdated = options.replaceOutdated
+        ? plan.items.filter((item) => item.status === "outdated")
+        : [];
+    const selected = [...exact, ...outdated];
+    if (!selected.length)
+        throw new Error("No exact or explicitly selected outdated skills to reconcile");
+    const risky = outdated.filter((item) => item.approvalRequired);
+    if (risky.length && !options.approveRisk)
+        throw new Error(`Replacing ${risky.length} outdated skill group(s) requires --approve-risk after reviewing the reported findings.`);
+    const entries = selected.map((item) => ({
+        plan: installPlanFor(item, item.status === "outdated"),
+        metadata: {
+            repository: item.candidate.repository,
+            resolvedCommit: item.candidate.commit,
+            reviewed: true,
+        },
+    }));
+    const outdatedTargets = outdated.flatMap((item) => item.installations.map((installation) => installation.path));
+    const applied = await runMutationTransaction(async () => {
+        await assertPlanUnchanged(plan);
+        return {
+            targets: [...outdatedTargets, installStatePath()],
+            value: entries,
+        };
+    }, async (freshEntries, snapshot) => {
+        for (const entry of freshEntries.filter((candidate) => outdated.some((item) => item.packageId === candidate.plan.packageId)))
+            for (const file of entry.plan.files) {
+                await rm(file.target, { recursive: true, force: true });
+                await cp(file.source, file.target, {
+                    recursive: true,
+                    filter: (source) => !source.split(sep).some((part) => IGNORED_TREE_NAMES.has(part)),
+                });
+                await validateSkillDirectory(file.target);
+                if (treeSignature(await captureTree(file.target)) !==
+                    treeSignature(await captureTree(file.source)))
+                    throw new Error(`Exact reconciliation copy verification failed: ${file.target}`);
+            }
+        await recordInstallBatch(freshEntries, snapshot.id);
+    }, { label: "reconcile existing skills" });
+    return {
+        snapshotId: applied.snapshotId,
+        adopted: exact.length,
+        updated: outdated.length,
+    };
+}
+export function formatReconcilePlan(plan) {
+    const lines = [
+        "Existing skill reconciliation",
+        "",
+        `${plan.summary.existing} installed copy/copies in ${plan.items.length} unique version group(s)`,
+        `${plan.summary.exact} exact upstream match(es)`,
+        `${plan.summary.outdated} reviewed update candidate(s)`,
+        `${plan.summary.ambiguous} ambiguous group(s)`,
+        `${plan.summary.unknown} unknown group(s)`,
+        `${plan.summary.mirroredGroups} cross-agent mirror group(s)`,
+    ];
+    for (const item of plan.items) {
+        const marker = item.status === "exact"
+            ? "✓"
+            : item.status === "outdated"
+                ? "↑"
+                : item.status === "ambiguous"
+                    ? "?"
+                    : "·";
+        lines.push("", `${marker} ${item.name} — ${item.status} — ${item.installations.map((entry) => entry.agent).join(", ")}`, `  ${item.reason}`);
+        if (item.candidate)
+            lines.push(`  Source: ${item.candidate.repository}@${item.candidate.commit.slice(0, 12)} (${item.candidate.skillPath})`);
+        if (item.safetyFindings.length)
+            lines.push(`  Review: ${item.safetyFindings.length} safety-sensitive update finding(s)${item.approvalRequired ? "; explicit approval required" : ""}`, ...item.safetyFindings.map((finding) => `    - ${finding.severity}/${finding.category}: ${finding.message}${finding.paths.length ? ` [${finding.paths.slice(0, 3).join(", ")}${finding.paths.length > 3 ? ", …" : ""}]` : ""}`));
+    }
+    lines.push("", "Default apply adopts exact matches without changing their files.", "Outdated replacements require --replace-outdated and remain one rollback-safe transaction.");
+    return lines.join("\n");
+}

package/dist/src/core/skill-inventory.js

@@ -37,6 +37,7 @@ async function scanAgentSkills(agent, records, activations, runtimeTargets) {
     const primaryRoot = resolve(agent.skillsDirectory);
     const roots = [
         primaryRoot,
+        ...(agent.additionalSkillsDirectories ?? []).map((path) => resolve(path)),
         ...runtimeTargets
             .filter((target) => target.agent === agent.id)
             .map((target) => resolve(target.path))
@@ -72,11 +73,31 @@ async function scanAgentSkills(agent, records, activations, runtimeTargets) {
                 const path = join(directory, "SKILL.md");
                 const content = await readFile(path, "utf8");
                 const packageId = owningPackage(directory, agent.id, records, activations, runtimeTargets);
-                const sourceHints = [
+                let gitConfig = "";
+                try {
+                    const gitConfigPath = join(directory, ".git", "config");
+                    const gitConfigInfo = await lstat(gitConfigPath);
+                    if (gitConfigInfo.isFile() && !gitConfigInfo.isSymbolicLink())
+                        gitConfig = await readFile(gitConfigPath, "utf8");
+                }
+                catch {
+                    // Most installed skills are copied directories, not Git worktrees.
+                }
+                const originSection = gitConfig.match(/\[remote\s+["']origin["']\]([\s\S]*?)(?=\n\s*\[|$)/i)?.[1] ?? "";
+                const gitOrigins = [
                     ...new Set([
-                        ...content.matchAll(/https?:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]*[A-Za-z0-9_-])/g),
+                        ...originSection.matchAll(/https?:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]*[A-Za-z0-9_-])/g),
+                        ...originSection.matchAll(/git@github\.com:([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]*[A-Za-z0-9_-])/g),
                     ].map((match) => match[1].replace(/\.git$/, ""))),
                 ].sort();
+                const sourceHints = [
+                    ...new Set([
+                        ...[
+                            ...content.matchAll(/https?:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]*[A-Za-z0-9_-])/g),
+                        ].map((match) => match[1].replace(/\.git$/, "")),
+                        ...gitOrigins,
+                    ]),
+                ].sort();
                 skills.push({
                     agent: agent.id,
                     agentDisplayName: agent.displayName,
@@ -93,6 +114,9 @@ async function scanAgentSkills(agent, records, activations, runtimeTargets) {
                     managed: Boolean(packageId),
                     ...(packageId ? { packageId } : {}),
                     ...(sourceHints.length ? { sourceHints } : {}),
+                    ...(gitOrigins.length === 1
+                        ? { repositoryOrigin: gitOrigins[0] }
+                        : {}),
                 });
             }
             catch (error) {
@@ -106,6 +130,7 @@ async function scanAgentSkills(agent, records, activations, runtimeTargets) {
         }
         for (const child of children) {
             if (child.name === ".git" ||
+                child.name === ".system" ||
                 child.name === "node_modules" ||
                 child.name === ".cache")
                 continue;
@@ -113,7 +138,8 @@ async function scanAgentSkills(agent, records, activations, runtimeTargets) {
                 await visit(join(directory, child.name), depth + 1);
         }
     }
-    for (const root of [...new Set(roots)])
+    const scanRoots = [...new Set(roots)].filter((root, index, values) => !values.some((candidate, candidateIndex) => candidateIndex !== index && isInside(candidate, root)));
+    for (const root of scanRoots)
         await visit(root, 0);
     return {
         skills: skills.sort((left, right) => left.path.localeCompare(right.path)),
@@ -173,6 +199,9 @@ export async function scanInstalledSkills(agents) {
             unmanaged: entries.length - managed,
             overRecommendedLimit: entries.length > RECOMMENDED_ACTIVE_SKILLS,
             runtimeToolTargets: runtimeTargets.filter((target) => target.agent === agent.id).length,
+            ...(agent.additionalSkillsDirectories?.length
+                ? { additionalDirectories: [...agent.additionalSkillsDirectories] }
+                : {}),
         };
     });
     for (const summary of summaries.filter((item) => item.overRecommendedLimit))
@@ -201,7 +230,7 @@ export function formatInstalledSkillInventory(report) {
         "",
     ];
     for (const agent of report.agents)
-        lines.push(`${agent.detected ? "✓" : "○"} ${agent.displayName}: ${agent.total} skill(s) (${agent.managed} managed, ${agent.unmanaged} unmanaged)${agent.runtimeToolTargets ? `, including ${agent.runtimeToolTargets} runtime-tool skill(s)` : ""} — ${agent.directory}`);
+        lines.push(`${agent.detected ? "✓" : "○"} ${agent.displayName}: ${agent.total} skill(s) (${agent.managed} managed, ${agent.unmanaged} unmanaged)${agent.runtimeToolTargets ? `, including ${agent.runtimeToolTargets} runtime-tool skill(s)` : ""} — ${[agent.directory, ...(agent.additionalDirectories ?? [])].join(", ")}`);
     for (const warning of report.warnings)
         lines.push(`! ${warning}`);
     lines.push("", "Read-only scan complete. Unmanaged content was not changed or judged automatically.");

package/dist/src/core/skill-security.js

@@ -158,6 +158,7 @@ export async function scanSkillSecurity(skillRoot, options = {}) {
     const contents = new Map();
     const findings = [];
     let totalBytes = 0;
+    const ignoredDirectories = new Set([".git", ".cache", "node_modules"]);
     async function visit(directory, depth) {
         if (depth > 12) {
             findings.push(finding("tree-depth", "high", "size", "Skill tree exceeds the bounded inspection depth.", [normalizedPath(root, directory)]));
@@ -165,6 +166,8 @@ export async function scanSkillSecurity(skillRoot, options = {}) {
         }
         const entries = await readdir(directory, { withFileTypes: true });
         for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.isDirectory() && ignoredDirectories.has(entry.name))
+                continue;
             const absolute = join(directory, entry.name);
             const path = normalizedPath(root, absolute);
             const info = await lstat(absolute);

package/dist/src/core/update.js

@@ -265,12 +265,33 @@ export async function applyPackageUpdate(packageId, options = {}, runtime = {})
             .join(" ")}`);
     }
     const agents = installedAgents(await (runtime.detectAgents ?? detectAgents)(), record.targetAgents);
-    const plan = await (runtime.buildPlan ?? buildSkillPlan)(current.path, record.packageId, agents, units.length
+    let plan = await (runtime.buildPlan ?? buildSkillPlan)(current.path, record.packageId, agents, units.length
         ? {
             include: (skill) => units.some((unitId) => unitId.toLowerCase() === skill.name?.toLowerCase() ||
                 unitId.toLowerCase() === skill.targetName.toLowerCase()),
         }
         : {});
+    if (units.length) {
+        const activeTargets = new Map((state.activations ?? [])
+            .filter((activation) => activation.packageId === packageId &&
+            activation.installationState === "installed" &&
+            activation.activationState === "active" &&
+            activation.unitId)
+            .flatMap((activation) => activation.targets.map((target) => [
+            `${activation.agent}\0${activation.unitId.toLowerCase()}`,
+            target.activePath,
+        ])));
+        plan = {
+            ...plan,
+            files: plan.files.map((file) => {
+                const unitId = file.skillName ?? basename(file.target);
+                const target = file.targetAgent
+                    ? activeTargets.get(`${file.targetAgent}\0${unitId.toLowerCase()}`)
+                    : undefined;
+                return target ? { ...file, target } : file;
+            }),
+        };
+    }
     if (units.length) {
         const plannedUnits = [
             ...new Set(plan.files.map((file) => basename(file.target))),

package/docs/CATALOG.md

@@ -1,6 +1,6 @@
 # Catalog and upstream credits
 
-Loadout's bundled catalog indexes 51 public upstream repositories. This page gives every project a direct source link and exposes the exact reviewed revision used by Loadout.
+Loadout's bundled catalog indexes 53 public upstream repositories. This page gives every project a direct source link and exposes the exact reviewed revision used by Loadout.
 
 Thank you to every maintainer and contributor whose work appears here. Loadout does not own, endorse for its authors, or relicense these projects. Each project remains governed by its upstream license and current terms.
 
@@ -14,7 +14,7 @@ Thank you to every maintainer and contributor whose work appears here. Loadout d
 
 The machine-readable catalog remains the source of truth. Run `loadout catalog --coverage --json` to inspect coverage and `loadout capabilities` to inspect what each local agent adapter can actually manage.
 
-## All 51 credited repositories
+## All 53 credited repositories
 
 | Upstream source                                                                   | Loadout ID                       | Category                 | Reviewed components        | License status      | Reviewed revision                                                                                                       |
 | --------------------------------------------------------------------------------- | -------------------------------- | ------------------------ | -------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------- |
@@ -69,6 +69,8 @@ The machine-readable catalog remains the source of truth. Run `loadout catalog -
 | [Browserbase MCP Server](https://github.com/browserbase/mcp-server-browserbase)   | `browserbase-mcp-server`         | browser-automation       | `mcp`                      | `Apache-2.0`        | [`1e196b3d3c4d`](https://github.com/browserbase/mcp-server-browserbase/tree/1e196b3d3c4dc70944e0d19038dd9eb3608b207a)   |
 | [Bright Data MCP](https://github.com/brightdata/brightdata-mcp)                   | `bright-data-mcp`                | web-research             | `mcp`                      | `MIT`               | [`adbfdd49b880`](https://github.com/brightdata/brightdata-mcp/tree/adbfdd49b8805136662a264490118c2688da3e29)            |
 | [Obsidian Skills](https://github.com/kepano/obsidian-skills)                      | `obsidian-skills`                | knowledge-management     | `skill`, `plugin`          | `MIT`               | [`a1dc48e68138`](https://github.com/kepano/obsidian-skills/tree/a1dc48e68138490d522c04cbf5822214c6eb1202)               |
+| [Cloudflare Skills](https://github.com/cloudflare/skills)                         | `cloudflare-skills`              | cloud-platform           | `skill`, `plugin`, `mcp`   | `Apache-2.0`        | [`70215303d44a`](https://github.com/cloudflare/skills/tree/70215303d44a81a0db3219428f4825b604fc6061)                    |
+| [Humanizer](https://github.com/blader/humanizer)                                  | `humanizer`                      | writing                  | `skill`                    | `MIT`               | [`1b48564898e9`](https://github.com/blader/humanizer/tree/1b48564898e999219882660237fde01bf4843a0f)                     |
 
 ## Catalog maintenance
 

package/docs/USER_TEST_GUIDE.md

@@ -20,6 +20,34 @@ record for every skill, use `loadout library --all`. `scan` distinguishes
 Loadout-managed skills from your own pre-existing skills. `health` checks local drift only; add
 `--updates` only when you want it to contact the tracked public repositories.
 
+### Compare and manage pre-existing skills
+
+```bash
+# Refresh pinned source evidence and preview every existing unmanaged group
+loadout reconcile --refresh
+
+# Adopt only exact matches. This records provenance without rewriting skill files.
+loadout reconcile --yes
+
+# Preview old, unambiguous copies separately. Do not apply yet.
+loadout reconcile --replace-outdated
+```
+
+The preview groups identical copies shared by Claude, Codex, Cursor, and Windsurf.
+`exact` means the complete distributable tree matches one pinned catalog skill;
+`outdated` means one source is unambiguous but its tree differs; `ambiguous` and
+`unknown` are deliberately left unmanaged. Only after reviewing every displayed
+file, domain, script, environment, and instruction finding should you consider:
+
+```bash
+loadout reconcile --replace-outdated --yes --approve-risk
+```
+
+That replacement is one snapshot-backed transaction. Use `loadout rollback --list`
+and the printed snapshot ID to undo it. Later `loadout update` checks the tracked
+upstream repository for newer commits; it still previews and safety-checks changes
+instead of silently updating files.
+
 ## 2. Explore without installing
 
 ```bash
@@ -183,7 +211,7 @@ cleanup deliberately deletes Loadout's snapshots, so it is the last lifecycle te
 ## Troubleshooting and recovery
 
 - **`loadout` is not found after installation:** confirm `npm install --global
-loadout-ai@0.5.3` completed, run `hash -r`, and confirm npm's global binary
+loadout-ai@0.5.4` completed, run `hash -r`, and confirm npm's global binary
   directory is on `PATH`. For a source checkout, run `npm run build` and `npm link`.
 - **A preview asks for `--approve-risk`:** read the reported scripts, domains,
   credentials, binaries, or instruction findings. If you accept that specific plan,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadout-ai",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "private": false,
   "license": "MIT",
   "description": "Universal upgrade manager for AI coding agents",