loadout-ai 0.5.9 → 0.7.0

package/dist/src/core/{registry.js → catalog/registry.js}

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import { cp, lstat, mkdir, readFile, readdir, rm, writeFile, } from "node:fs/promises";
 import { join, relative, resolve, sep } from "node:path";
-import { loadoutHome } from "./paths.js";
+import { loadoutHome } from "../agents/paths.js";
 import { analyzeUpdateSafety } from "./safety.js";
 const NAME = /^[a-z0-9][a-z0-9._-]*$/;
 const VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/;

package/dist/src/core/{skill-compare.js → catalog/skill-compare.js}

@@ -1,5 +1,5 @@
 import { basename } from "node:path";
-import { explainCatalogScore } from "./ranking.js";
+import { explainCatalogScore } from "../discovery/ranking.js";
 const STOP_WORDS = new Set([
     "a",
     "an",

package/dist/src/core/{skill-inventory.js → catalog/skill-inventory.js}

@@ -1,9 +1,9 @@
 import { createHash } from "node:crypto";
 import { lstat, readFile, readdir } from "node:fs/promises";
 import { join, relative, resolve, sep } from "node:path";
-import { DEFAULT_ACTIVE_SKILL_LIMIT } from "./active-limit.js";
-import { readInstallState } from "./state.js";
-import { listInstalledRuntimeToolSkillTargets, } from "./runtime-tools.js";
+import { DEFAULT_ACTIVE_SKILL_LIMIT } from "../workspace/active-limit.js";
+import { readInstallState } from "../workspace/state.js";
+import { listInstalledRuntimeToolSkillTargets, } from "../agents/runtime-tools.js";
 const MAX_SCAN_DEPTH = 6;
 function cleanFrontmatterValue(value) {
     if (!value)

package/dist/src/core/{skills.js → catalog/skills.js}

@@ -1,6 +1,6 @@
 import { cp, lstat, readdir, readFile, rm } from "node:fs/promises";
 import { dirname, join, relative, resolve, sep } from "node:path";
-import { ensureDirectory } from "./paths.js";
+import { ensureDirectory } from "../agents/paths.js";
 import { assertSkillSecurity, scanSkillSecurity } from "./skill-security.js";
 export async function discoverSkillDirectories(root, options = {}) {
     const result = [];

package/dist/src/core/{candidate-intelligence.js → discovery/candidate-intelligence.js}

@@ -4,13 +4,13 @@ import { readFile, stat } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
-import { writeFileAtomically } from "./atomic-file.js";
-import { loadEffectiveCatalog, validateCatalog } from "./catalog.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { loadEffectiveCatalog, validateCatalog } from "../catalog/catalog.js";
 import { evaluatePackage } from "./evaluate.js";
-import { inspectPackage } from "./package.js";
-import { ensureDirectory, loadoutHome } from "./paths.js";
-import { fetchRepositorySnapshot, normalizeRepository, } from "./source.js";
-import { safeTerminalText } from "./terminal.js";
+import { inspectPackage } from "../install/package.js";
+import { ensureDirectory, loadoutHome } from "../agents/paths.js";
+import { fetchRepositorySnapshot, normalizeRepository, } from "../install/source.js";
+import { safeTerminalText } from "../reporting/terminal.js";
 const dossierDirectory = () => join(loadoutHome(), "candidates");
 const sourceVerifiedDossiers = new WeakMap();
 function installabilityFor(components) {

package/dist/src/core/{discovery-connector.js → discovery/discovery-connector.js}

@@ -1,7 +1,7 @@
 import { readFile, stat } from "node:fs/promises";
 import { dirname } from "node:path";
-import { writeFileAtomically } from "./atomic-file.js";
-import { ensureDirectory } from "./paths.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { ensureDirectory } from "../agents/paths.js";
 export class ConnectorRequestError extends Error {
     status;
     retryAfterSeconds;

package/dist/src/core/{evaluate.js → discovery/evaluate.js}

@@ -1,5 +1,5 @@
-import { inspectPackage } from "./package.js";
-import { analyzeUpdateSafety } from "./safety.js";
+import { inspectPackage } from "../install/package.js";
+import { analyzeUpdateSafety } from "../catalog/safety.js";
 function statusFor(findings) {
     if (findings.some((finding) => finding.category === "secret" || finding.category === "instruction"))
         return "blocked";

package/dist/src/core/{mcp-registry-discovery.js → discovery/mcp-registry-discovery.js}

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { ConnectorRequestError, fetchBoundedJson, rateLimitFromHeaders, readDiscoveryConnectorCache, writeDiscoveryConnectorCache, } from "./discovery-connector.js";
-import { loadoutHome } from "./paths.js";
+import { loadoutHome } from "../agents/paths.js";
 const SOURCE = "official-mcp-registry";
 const API = "https://registry.modelcontextprotocol.io/v0.1/servers";
 const ATTRIBUTION = "https://registry.modelcontextprotocol.io/docs";

package/dist/src/core/{observations.js → discovery/observations.js}

@@ -1,8 +1,8 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-import { fetchGitHubReleaseMetadata, } from "./github.js";
-import { writeFileAtomically } from "./atomic-file.js";
-import { loadoutHome } from "./paths.js";
+import { fetchGitHubReleaseMetadata, } from "../runtime/github.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { loadoutHome } from "../agents/paths.js";
 const MAX_OBSERVATIONS_PER_REPOSITORY = 90;
 function observationPath(repository) {
     return join(loadoutHome(), "observations", `${repository.replace("/", "__")}.json`);

package/dist/src/core/{review-queue.js → discovery/review-queue.js}

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { writeFileAtomically } from "./atomic-file.js";
-import { ensureDirectory, loadoutHome } from "./paths.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { ensureDirectory, loadoutHome } from "../agents/paths.js";
 const queuePath = () => join(loadoutHome(), "review-queue.json");
 function isQueue(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
@@ -13,7 +13,7 @@ function isQueue(value) {
         record.items.every((item) => item &&
             typeof item === "object" &&
             typeof item.repository === "string" &&
-            ["pending", "shortlisted", "ignored"].includes(item.decision)));
+            ["pending", "shortlisted", "ignored", "promoted"].includes(item.decision)));
 }
 export async function readReviewQueue() {
     try {
@@ -102,7 +102,9 @@ function decisionPriority(decision) {
         return 0;
     if (decision === "pending")
         return 1;
-    return 2;
+    if (decision === "ignored")
+        return 2;
+    return 3;
 }
 function compareQueueItems(left, right) {
     return (Number(left.alreadyCataloged) - Number(right.alreadyCataloged) ||
@@ -191,6 +193,9 @@ export async function setReviewDecision(repository, decision) {
     await writeFileAtomically(queuePath(), `${JSON.stringify(queue, null, 2)}\n`);
     return item;
 }
+export async function markPromoted(repository) {
+    return setReviewDecision(repository, "promoted");
+}
 export function formatReviewQueue(queue) {
     const visible = queue.items.filter((item) => !item.alreadyCataloged);
     return [

package/dist/src/core/{skills-sh-discovery.js → discovery/skills-sh-discovery.js}

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { ConnectorRequestError, fetchBoundedJson, rateLimitFromHeaders, readDiscoveryConnectorCache, writeDiscoveryConnectorCache, } from "./discovery-connector.js";
-import { loadoutHome } from "./paths.js";
+import { loadoutHome } from "../agents/paths.js";
 const SOURCE = "skills-sh";
 const API = "https://skills.sh/api/v1/skills";
 const ATTRIBUTION = "https://skills.sh/docs/api";

package/dist/src/core/{adopt.js → install/adopt.js}

@@ -1,9 +1,9 @@
 import { createHash } from "node:crypto";
 import { lstat, readFile, readdir } from "node:fs/promises";
 import { basename, isAbsolute, join, posix, relative, sep } from "node:path";
-import { enrichInventoryWithProvenance } from "./provenance.js";
-import { scanInstalledSkills } from "./skill-inventory.js";
-import { installStatePath, recordInstall } from "./state.js";
+import { enrichInventoryWithProvenance } from "../catalog/provenance.js";
+import { scanInstalledSkills } from "../catalog/skill-inventory.js";
+import { installStatePath, recordInstall } from "../workspace/state.js";
 import { runMutationTransaction } from "./transaction.js";
 const issuedAdoptionPlans = new WeakMap();
 function safeRelativePath(root, path) {

package/dist/src/core/{catalog-install.js → install/catalog-install.js}

@@ -1,13 +1,13 @@
-import { DEFAULT_ACTIVE_SKILL_LIMIT } from "./active-limit.js";
-import { loadEffectiveCatalog } from "./catalog.js";
-import { detectAgents } from "./paths.js";
-import { isStableSkillSelected, isPowerSkillSelected, resolveCatalogProfile, } from "./profiles.js";
+import { DEFAULT_ACTIVE_SKILL_LIMIT } from "../workspace/active-limit.js";
+import { loadEffectiveCatalog, } from "../catalog/catalog.js";
+import { detectAgents } from "../agents/paths.js";
+import { isStableSkillSelected, isPowerSkillSelected, resolveCatalogProfile, } from "../catalog/profiles.js";
 import { applySkillLibraryBatch, applySkillInstallBatch, buildSkillPlan, installedAgents, planManagedProfileReconciliation, } from "./install.js";
 import { fetchRepositorySnapshot, } from "./source.js";
-import { analyzeInstallPlanSafety, } from "./safety.js";
-import { formatModelApiAccess } from "./access.js";
-import { recordInstalledProfile } from "./profile-state.js";
-import { readInstallState } from "./state.js";
+import { analyzeInstallPlanSafety, } from "../catalog/safety.js";
+import { formatModelApiAccess, } from "../routing/access.js";
+import { recordInstalledProfile } from "../workspace/profile-state.js";
+import { readInstallState } from "../workspace/state.js";
 async function parallelMap(values, concurrency, worker) {
     const results = new Array(values.length);
     let cursor = 0;
@@ -240,11 +240,11 @@ export function formatPreparedCatalogInstall(prepared, options = {}) {
     const quarantined = prepared.skipped.filter((item) => item.kind === "quarantined");
     const retired = prepared.reconciliation?.obsoleteUnits ?? [];
     const modeLabel = prepared.selection.mode === "maximum"
-        ? "Maximum Library"
+        ? "Maximum"
         : prepared.selection.mode === "power"
-            ? "Power Boost"
+            ? "Power"
             : prepared.selection.mode === "stable"
-                ? "Stable Boost"
+                ? "Stable"
                 : "Custom";
     const lines = [
         `Loadout: ${modeLabel}`,

package/dist/src/core/{file-lock.js → install/file-lock.js}

@@ -1,7 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { mkdir, open, readFile, rename, rm, stat, utimes, } from "node:fs/promises";
 import { dirname } from "node:path";
-import { ensureDirectory } from "./paths.js";
+import { ensureDirectory } from "../agents/paths.js";
 const wait = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
 function parseOwner(content) {
     try {

package/dist/src/core/{install.js → install/install.js}

@@ -1,12 +1,12 @@
 import { existsSync } from "node:fs";
 import { cp, lstat, rm } from "node:fs/promises";
 import { basename, dirname, isAbsolute, join, posix, relative, win32, } from "node:path";
-import { ensureDirectory, loadoutHome } from "./paths.js";
-import { planAdapterSkillInstall } from "./adapters.js";
-import { applySkillPlan, detectInstallConflicts } from "./skills.js";
-import { activationLibraryPath, installStatePath, recordInstall, recordInstallBatch, recordLibraryInstallBatch, readInstallState, hashDirectory, writeInstallState, } from "./state.js";
+import { ensureDirectory, loadoutHome } from "../agents/paths.js";
+import { planAdapterSkillInstall } from "../agents/adapters.js";
+import { applySkillPlan, detectInstallConflicts } from "../catalog/skills.js";
+import { activationLibraryPath, installStatePath, recordInstall, recordInstallBatch, recordLibraryInstallBatch, readInstallState, hashDirectory, writeInstallState, } from "../workspace/state.js";
 import { runMutationTransaction } from "./transaction.js";
-import { inspectTargetOccupancy } from "./target-occupancy.js";
+import { inspectTargetOccupancy } from "../workspace/target-occupancy.js";
 export function installedAgents(agents, requested) {
     const available = agents.filter((agent) => agent.installed);
     if (!requested || requested.length === 0)

package/dist/src/core/{package.js → install/package.js}

@@ -1,8 +1,8 @@
 import { readFile, readdir } from "node:fs/promises";
 import { dirname, join, relative, resolve } from "node:path";
-import { discoverSkillDirectories } from "./skills.js";
-import { discoverMcpManifests } from "./mcp.js";
-import { discoverResources } from "./components.js";
+import { discoverSkillDirectories } from "../catalog/skills.js";
+import { discoverMcpManifests } from "../runtime/mcp.js";
+import { discoverResources } from "../catalog/components.js";
 const portableRelative = (root, path) => relative(root, path).split(/[\\/]/).join("/") || ".";
 function frontmatter(path) {
     return readFile(join(path, "SKILL.md"), "utf8").then((content) => {

package/dist/src/core/{reconcile.js → install/reconcile.js}

@@ -1,13 +1,13 @@
 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 { analyzeUpdateSafety } from "../catalog/safety.js";
+import { enrichInventoryWithProvenance, } from "../catalog/provenance.js";
+import { scanInstalledSkills } from "../catalog/skill-inventory.js";
+import { installStatePath, recordInstallBatch } from "../workspace/state.js";
 import { runMutationTransaction } from "./transaction.js";
 import { repositoryCachePath } from "./source.js";
-import { validateSkillDirectory } from "./skills.js";
+import { validateSkillDirectory } from "../catalog/skills.js";
 const issuedPlans = new WeakMap();
 const IGNORED_TREE_NAMES = new Set([".git", ".cache", "node_modules"]);
 function slug(value) {

package/dist/src/core/{remove.js → install/remove.js}

@@ -1,10 +1,10 @@
 import { createHash } from "node:crypto";
 import { readFile, rm } from "node:fs/promises";
-import { forgetInstall, installStatePath, readInstallState } from "./state.js";
-import { writeMcpConfigPlan } from "./mcp.js";
+import { forgetInstall, installStatePath, readInstallState, } from "../workspace/state.js";
+import { writeMcpConfigPlan } from "../runtime/mcp.js";
 import { runMutationTransaction } from "./transaction.js";
-import { managedFileReadPath } from "./active-set.js";
-import { codexMcpServerFingerprint, removeCodexMcpServerBlock, writeCodexMcpConfigContent, } from "./codex-mcp.js";
+import { managedFileReadPath } from "../workspace/active-set.js";
+import { codexMcpServerFingerprint, removeCodexMcpServerBlock, writeCodexMcpConfigContent, } from "../agents/codex-mcp.js";
 export async function planRemove(packageId) {
     const state = await readInstallState();
     const record = state.installs.find((entry) => entry.packageId === packageId);

package/dist/src/core/{snapshot.js → install/snapshot.js}

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, writeFile, mkdir, readdir, rename, rm, lstat, } from "node:fs/promises";
 import { dirname, join, resolve, sep } from "node:path";
-import { loadoutHome, ensureDirectory, userHome } from "./paths.js";
+import { loadoutHome, ensureDirectory, userHome } from "../agents/paths.js";
 export async function createSnapshot(paths, options = {}) {
     const normalizedRoots = [...new Set(paths.map((path) => resolve(path)))];
     const snapshot = {

package/dist/src/core/{source.js → install/source.js}

@@ -4,7 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { loadoutHome, ensureDirectory } from "./paths.js";
+import { loadoutHome, ensureDirectory } from "../agents/paths.js";
 const execFileAsync = promisify(execFile);
 async function enforceRepositoryBounds(root, options) {
     if (options.maxBytes === undefined && options.maxFiles === undefined)

package/dist/src/core/{sync.js → install/sync.js}

@@ -1,17 +1,17 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { dirname, resolve, sep } from "node:path";
-import { loadEffectiveCatalog } from "./catalog.js";
+import { loadEffectiveCatalog } from "../catalog/catalog.js";
 import { installedAgents } from "./install.js";
-import { orderManifestPackages, readManifest, writeLockfile, } from "./manifest.js";
-import { detectAgents, userHome } from "./paths.js";
+import { orderManifestPackages, readManifest, writeLockfile, } from "../workspace/manifest.js";
+import { detectAgents, userHome } from "../agents/paths.js";
 import { fetchGitSnapshot, fetchRepositorySnapshot } from "./source.js";
-import { addRootFileExports, buildUniversalPackagePlan } from "./components.js";
-import { analyzeInstallPlanSafety, } from "./safety.js";
-import { fetchRemoteRegistryPackage, packPackage, resolveRegistryPackage, } from "./registry.js";
-import { discoverMcpManifests, planMcpConfigBatch, writeMcpConfigPlan, } from "./mcp.js";
-import { applySkillPlan, detectInstallConflicts } from "./skills.js";
-import { installStatePath, readInstallState, recordInstallTransaction, } from "./state.js";
+import { addRootFileExports, buildUniversalPackagePlan, } from "../catalog/components.js";
+import { analyzeInstallPlanSafety, } from "../catalog/safety.js";
+import { fetchRemoteRegistryPackage, packPackage, resolveRegistryPackage, } from "../catalog/registry.js";
+import { discoverMcpManifests, planMcpConfigBatch, writeMcpConfigPlan, } from "../runtime/mcp.js";
+import { applySkillPlan, detectInstallConflicts } from "../catalog/skills.js";
+import { installStatePath, readInstallState, recordInstallTransaction, } from "../workspace/state.js";
 import { runMutationTransaction } from "./transaction.js";
 function registrySourceKey(source) {
     if (source.type === "registry")

package/dist/src/core/{transaction.js → install/transaction.js}

@@ -1,7 +1,7 @@
 import { lstat, mkdir, readdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { join } from "node:path";
-import { ensureDirectory, loadoutHome } from "./paths.js";
+import { ensureDirectory, loadoutHome } from "../agents/paths.js";
 import { createSnapshot, readSnapshot, recordSnapshotPostMutationState, restoreSnapshot, } from "./snapshot.js";
 import { acquireFileLock, withFileLock, } from "./file-lock.js";
 export const transactionRoot = () => join(loadoutHome(), "staging");

package/dist/src/core/{uninstall.js → install/uninstall.js}

@@ -2,11 +2,11 @@ import { execFile } from "node:child_process";
 import { readdir, rm, rmdir } from "node:fs/promises";
 import { dirname, parse, resolve } from "node:path";
 import { promisify } from "node:util";
-import { loadoutHome } from "./paths.js";
+import { loadoutHome } from "../agents/paths.js";
 import { applyRemove, planRemove } from "./remove.js";
-import { applyRuntimeToolPlan, listInstalledRuntimeTools, planRuntimeTool, } from "./runtime-tools.js";
-import { applyNativeSchedulerBundle, planNativeScheduler, } from "./scheduler.js";
-import { readInstallState } from "./state.js";
+import { applyRuntimeToolPlan, listInstalledRuntimeTools, planRuntimeTool, } from "../agents/runtime-tools.js";
+import { applyNativeSchedulerBundle, planNativeScheduler, } from "../runtime/scheduler.js";
+import { readInstallState } from "../workspace/state.js";
 export async function buildUninstallPlan(dependencies = {}) {
     const stateHome = loadoutHome();
     const state = await readInstallState();

package/dist/src/core/{update.js → install/update.js}

@@ -3,11 +3,11 @@ import { basename, join } from "node:path";
 import { fetchRepositorySnapshot, resolveRepositoryHead } from "./source.js";
 import { repositoryCachePath } from "./source.js";
 import { diffRepositorySnapshots } from "./diff.js";
-import { hashDirectory, readInstallState } from "./state.js";
-import { analyzeUpdateSafety } from "./safety.js";
-import { detectAgents, loadoutHome } from "./paths.js";
+import { hashDirectory, readInstallState } from "../workspace/state.js";
+import { analyzeUpdateSafety } from "../catalog/safety.js";
+import { detectAgents, loadoutHome } from "../agents/paths.js";
 import { applySkillInstall, buildSkillPlan, installedAgents, } from "./install.js";
-import { discoverSkillDirectories, validateSkillDirectory, } from "./skills.js";
+import { discoverSkillDirectories, validateSkillDirectory, } from "../catalog/skills.js";
 function managedUnitIds(state, packageId) {
     return [
         ...new Set((state.activations ?? [])

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

@@ -0,0 +1,103 @@
+/** Plain-language entry points for people using the CLI, not maintaining it. */
+export const BEGINNER_GUIDE = `
+Loadout — manage the skills, tools, and MCP servers your AI agents use.
+
+FIRST TIME
+
+  loadout doctor                    which agents you have, and whether they are healthy
+  loadout setup --mode stable       preview 30 reviewed skills (nothing changes)
+  loadout setup --mode stable --yes install them
+
+IN A PROJECT
+
+  loadout recommend --project .     what this codebase actually needs
+  loadout optimize --project .      propose an active set for it
+  loadout status                    health grade and what is managed
+
+WHILE YOU WORK
+
+  loadout route <describe a task>   which model tier fits, and what it costs
+  loadout route --conserve <task>   cheaper tiers when you are low on quota
+  loadout handoff send codex "..."  give a task to your other agent
+
+USE IT INSIDE YOUR AGENT
+
+  loadout skills install loadout-router --yes
+
+  Then just ask your agent "which model should I use for this?" instead of
+  coming back here.
+
+KEEPING CURRENT
+
+  loadout health                    safer updates and local drift
+  loadout alerts                    archived, stale, or changed sources
+
+Every command that writes previews first and snapshots before it changes
+anything. Undo with: loadout rollback
+
+More commands: loadout advanced
+`.trim();
+export const ADVANCED_GUIDE = [
+    "ADVANCED COMMANDS",
+    "",
+    "Hidden from the first screen so daily use stays focused.",
+    "",
+    "Discovery:    candidate, discover, review-queue, evaluate, skill-audit",
+    "Sharing:      init, lock, export, import, share, card",
+    "Integrations: mcp-recipe, mcp-config, credentials, models, handoff, skills, convert",
+    "Lifecycle:    plan, adopt, uninstall, profiles, autopilot, tool, watch",
+    "",
+    "`loadout <command> --help` for options. Mutations preview first or require --yes.",
+].join("\n");
+/**
+ * The first-screen help shows only the everyday core (~24 commands). Everything
+ * else stays fully available and runnable, just omitted from the default help so
+ * the surface reads as a focused product rather than a tool dump. `loadout
+ * advanced` lists the hidden surface; `loadout <command> --help` documents each.
+ */
+export const HIDDEN_FROM_FIRST_SCREEN = new Set([
+    // manifests, authoring, sharing
+    "init",
+    "lock",
+    "export",
+    "import",
+    "audit",
+    "create",
+    "add",
+    "unadd",
+    "share",
+    "card",
+    "search",
+    // analytics / evidence / discovery
+    "report",
+    "versions",
+    "skill-audit",
+    "candidate",
+    "discover",
+    "review-queue",
+    "inspect",
+    "propose",
+    "evaluate",
+    // integrations / credentials / runtime
+    "credentials",
+    "models",
+    "handoff",
+    "completion",
+    "mcp-recipe",
+    "mcp-config",
+    "convert",
+    // lifecycle extras
+    "plan",
+    "adopt",
+    "uninstall",
+    "profiles",
+    "autopilot",
+    "tool",
+    "watch",
+    "schedule",
+    "unschedule",
+    "alert-ignore",
+    "alert-pin",
+    "alert-unpin",
+    "alert-pins",
+]);

package/dist/src/core/reporting/doctor.js

@@ -0,0 +1,141 @@
+import { access, constants } from "node:fs/promises";
+import { dirname } from "node:path";
+import { detectAgents, directoryExists, loadoutHome, userHome, } from "../agents/paths.js";
+import { inspectAgents } from "../agents/agent-inspection.js";
+async function writable(path) {
+    // A not-yet-created directory is healthy when any existing ancestor is
+    // writable; this handles first-run paths such as ~/.agents/skills.
+    let candidate = path;
+    while (true) {
+        try {
+            await access(candidate, constants.W_OK);
+            return true;
+        }
+        catch {
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                return false;
+            candidate = parent;
+        }
+    }
+}
+export async function runDoctor() {
+    const home = userHome();
+    const stateHome = loadoutHome();
+    const loadoutHomeExists = await directoryExists(stateHome);
+    const loadoutHomeWritable = await writable(stateHome);
+    const agents = await detectAgents();
+    const inventories = await inspectAgents(agents);
+    const diagnosedAgents = await Promise.all(agents.map(async (agent, index) => {
+        const exists = await directoryExists(agent.skillsDirectory);
+        const canWrite = await writable(agent.skillsDirectory);
+        const issues = [];
+        if (!agent.installed)
+            issues.push(`Install or configure ${agent.displayName} to enable it.`);
+        if (!exists)
+            issues.push("Skills directory does not exist yet; Loadout will create it during install.");
+        if (!canWrite)
+            issues.push("Skills directory is not writable; check permissions or choose another home.");
+        return {
+            agent,
+            inventory: inventories[index],
+            skillsRootExists: exists,
+            writable: canWrite,
+            issues,
+        };
+    }));
+    const issues = [];
+    if (!loadoutHomeExists)
+        issues.push("Loadout state directory does not exist yet; it will be created on first install.");
+    if (!loadoutHomeWritable)
+        issues.push("Loadout state directory is not writable; check LOADOUT_HOME permissions.");
+    if (!diagnosedAgents.some(({ agent }) => agent.installed)) {
+        issues.push("No supported agent executable was detected on PATH.");
+    }
+    return {
+        platform: process.platform,
+        userHome: home,
+        loadoutHome: stateHome,
+        loadoutHomeExists,
+        loadoutHomeWritable,
+        agents: diagnosedAgents,
+        issues,
+    };
+}
+export function formatDoctorReport(report, options = {}) {
+    const installed = report.agents.filter((a) => a.agent.installed);
+    const notInstalled = report.agents.filter((a) => !a.agent.installed);
+    const allIssues = [...report.issues, ...installed.flatMap((a) => a.issues)];
+    const grade = allIssues.length === 0 && installed.length > 0
+        ? "HEALTHY"
+        : allIssues.length <= 2
+            ? "OK"
+            : "NEEDS ATTENTION";
+    const lines = [
+        `loadout doctor — ${grade}`,
+        "",
+        `Platform:   ${report.platform}`,
+        `State:      ${report.loadoutHome} ${report.loadoutHomeExists ? "✓" : "⚠ not created"} ${report.loadoutHomeWritable ? "writable" : "⚠ not writable"}`,
+        `Agents:     ${installed.length} detected, ${notInstalled.length} available`,
+        "",
+    ];
+    // --- Detected agents: compact summary ---
+    if (installed.length) {
+        lines.push("DETECTED AGENTS");
+        for (const entry of installed) {
+            const skillCount = entry.inventory.components
+                .filter((c) => c.scanned && c.directoryExists)
+                .reduce((sum, c) => sum + c.entries.length, 0);
+            const supported = entry.inventory.components
+                .filter((c) => c.compatibility === "native" || c.compatibility === "adapted")
+                .map((c) => c.type);
+            lines.push(`  ✓ ${entry.agent.displayName}`, `    ${entry.agent.skillsDirectory}`, `    ${skillCount} items | supports: ${supported.join(", ")}`);
+            if (entry.issues.length) {
+                for (const issue of entry.issues)
+                    lines.push(`    ⚠ ${issue}`);
+            }
+            if (options.verbose) {
+                for (const component of entry.inventory.components) {
+                    if (component.compatibility === "unsupported")
+                        continue;
+                    const detail = component.scanned
+                        ? component.directoryExists
+                            ? `${component.entries.length} items`
+                            : "not created"
+                        : (component.note ?? "—");
+                    lines.push(`    ${component.type}: ${detail}`);
+                }
+            }
+        }
+        lines.push("");
+    }
+    // --- Not installed: one-liner ---
+    if (notInstalled.length) {
+        lines.push(`NOT DETECTED: ${notInstalled.map((a) => a.agent.displayName).join(", ")}`, "");
+    }
+    // --- Issues ---
+    if (allIssues.length) {
+        lines.push("ISSUES");
+        for (const issue of allIssues)
+            lines.push(`  ⚠ ${issue}`);
+        lines.push("");
+    }
+    // --- Next steps ---
+    lines.push("NEXT STEPS");
+    if (allIssues.length) {
+        lines.push("  Fix the issues above, then run `loadout doctor` again.");
+    }
+    else if (installed.length === 0) {
+        lines.push("  Install an AI coding agent (Claude Code, Codex, Cursor, etc.),", "  then run `loadout doctor` again.");
+    }
+    else {
+        lines.push("  loadout status        see what's managed", "  loadout setup         install a curated skill set", "  loadout route         find the right model for your task", "  loadout health        check for updates");
+    }
+    return lines.join("\n");
+}
+/**
+ * Legacy-compatible verbose format. Used when --verbose is passed.
+ */
+export function formatDoctorReportVerbose(report) {
+    return formatDoctorReport(report, { verbose: true });
+}