loadout-ai 0.6.0 → 0.8.0

package/dist/src/core/{cli-guide.js → reporting/cli-guide.js}

@@ -1,42 +1,41 @@
 /** Plain-language entry points for people using the CLI, not maintaining it. */
 export const BEGINNER_GUIDE = `
-START HERE
+Loadout — manage the skills, tools, and MCP servers your AI agents use.
 
-1. See what Loadout currently manages
-   loadout library
-   loadout scan
-   loadout reconcile
+FIRST TIME
 
-2. Preview the recommended everyday setup
-   loadout setup --mode stable
-   loadout profiles
+  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
 
-3. Find additions that fit the project in this folder
-   loadout recommend --project .
-   loadout optimize --project .
+IN A PROJECT
 
-4. Check for safer updates and new discoveries
-   loadout health
-   loadout alerts
-   loadout candidate list --limit 10
+  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
 
-5. See reviewed MCP integrations and their credential needs
-   loadout mcp-recipe
-   loadout mcp-recipe --credential-free
-   loadout mcp-recipe playwright --agent claude-code
+WHILE YOU WORK
 
-If you decide to install something, Loadout shows a preview first and creates a
-snapshot before changing managed files. Recover with: loadout rollback
+  loadout route                     your model policy: hard / normal / cheap
+  loadout route <describe a task>   which of those it looks like, and what to use
+  loadout handoff codex "..."       give a task to your other agent
 
-Reconcile is also read-only unless you add --yes. Exact matches can be managed
-without rewriting them; outdated replacements remain a separate explicit choice.
+USE IT INSIDE YOUR AGENT
 
-Setup reconciles the complete selected profile. To add one catalog package without
-retiring the current managed profile, use:
-   loadout install --mode custom --package <id>
+  loadout skills install loadout-router --yes
 
-Nothing above changes your agents. For the full maintainer/tooling surface, run:
-loadout advanced
+  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",
@@ -44,8 +43,8 @@ export const ADVANCED_GUIDE = [
     "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, badge",
-    "Integrations: mcp-recipe, mcp-config, credentials, models, handoff, convert",
+    "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.",
@@ -64,29 +63,18 @@ export const HIDDEN_FROM_FIRST_SCREEN = new Set([
     "import",
     "audit",
     "create",
-    "pack",
-    "publish",
     "add",
     "unadd",
     "share",
     "card",
-    "badge",
-    "compare-loadouts",
     "search",
     // analytics / evidence / discovery
     "report",
-    "outcomes",
-    "outcome",
-    "improve",
-    "improve-feedback",
-    "compare",
     "versions",
     "skill-audit",
-    "capabilities",
     "candidate",
     "discover",
     "review-queue",
-    "review",
     "inspect",
     "propose",
     "evaluate",
@@ -97,11 +85,7 @@ export const HIDDEN_FROM_FIRST_SCREEN = new Set([
     "completion",
     "mcp-recipe",
     "mcp-config",
-    "codex-mcp-config",
-    "sandbox-run",
     "convert",
-    "canary",
-    "serve",
     // lifecycle extras
     "plan",
     "adopt",

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

@@ -0,0 +1,90 @@
+let registry = [];
+/** Called once at startup with the assembled program. */
+export function registerCompletionCommands(tree) {
+    registry = tree
+        .filter((entry) => entry.name && entry.name !== "help")
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+export function completionCommands() {
+    return registry.map((entry) => entry.name);
+}
+export function completionSubcommands(name) {
+    return registry.find((entry) => entry.name === name)?.subcommands ?? [];
+}
+export function renderShellCompletion(shell) {
+    const words = completionCommands().join(" ");
+    switch (shell) {
+        case "bash":
+            return `# Loadout command completion
+_loadout() {
+  local current="\${COMP_WORDS[COMP_CWORD]}"
+  local commands="${words}"
+  if [[ COMP_CWORD -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "$commands" -- "$current") )
+  elif [[ COMP_CWORD -eq 2 && "\${COMP_WORDS[1]}" == "models" ]]; then
+    COMPREPLY=( $(compgen -W "${completionSubcommands("models").join(" ")}" -- "$current") )
+  elif [[ COMP_CWORD -eq 2 && "\${COMP_WORDS[1]}" == "credentials" ]]; then
+    COMPREPLY=( $(compgen -W "${completionSubcommands("credentials").join(" ")}" -- "$current") )
+  elif [[ COMP_CWORD -eq 2 && "\${COMP_WORDS[1]}" == "candidate" ]]; then
+    COMPREPLY=( $(compgen -W "${completionSubcommands("candidate").join(" ")}" -- "$current") )
+  fi
+}
+complete -F _loadout loadout
+`;
+        case "zsh":
+            return `#compdef loadout
+typeset -a commands model_commands credential_commands candidate_commands
+commands=(${completionCommands()
+                .map((command) => `'${command}'`)
+                .join(" ")})
+model_commands=(${completionSubcommands("models")
+                .map((command) => `'${command}'`)
+                .join(" ")})
+credential_commands=(${completionSubcommands("credentials")
+                .map((command) => `'${command}'`)
+                .join(" ")})
+candidate_commands=(${completionSubcommands("candidate")
+                .map((command) => `'${command}'`)
+                .join(" ")})
+if (( CURRENT == 2 )); then
+  _describe 'command' commands
+elif (( CURRENT == 3 )) && [[ $words[2] == models ]]; then
+  _describe 'models command' model_commands
+elif (( CURRENT == 3 )) && [[ $words[2] == credentials ]]; then
+  _describe 'credentials command' credential_commands
+elif (( CURRENT == 3 )) && [[ $words[2] == candidate ]]; then
+  _describe 'candidate command' candidate_commands
+fi
+`;
+        case "fish":
+            return [
+                ...completionCommands().map((command) => `complete -c loadout -f -n '__fish_use_subcommand' -a ${command}`),
+                ...completionSubcommands("models").map((command) => `complete -c loadout -f -n '__fish_seen_subcommand_from models' -a ${command}`),
+                ...completionSubcommands("credentials").map((command) => `complete -c loadout -f -n '__fish_seen_subcommand_from credentials' -a ${command}`),
+                ...completionSubcommands("candidate").map((command) => `complete -c loadout -f -n '__fish_seen_subcommand_from candidate' -a ${command}`),
+            ]
+                .join("\n")
+                .concat("\n");
+        case "powershell":
+            return `Register-ArgumentCompleter -Native -CommandName loadout -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $elements = @($commandAst.CommandElements | ForEach-Object { $_.Extent.Text })
+  $candidates = if ($elements.Count -ge 2 -and $elements[1] -eq 'models') { @(${completionSubcommands("models")
+                .map((command) => `'${command}'`)
+                .join(", ")}) } elseif ($elements.Count -ge 2 -and $elements[1] -eq 'credentials') { @(${completionSubcommands("credentials")
+                .map((command) => `'${command}'`)
+                .join(", ")}) } elseif ($elements.Count -ge 2 -and $elements[1] -eq 'candidate') { @(${completionSubcommands("candidate")
+                .map((command) => `'${command}'`)
+                .join(", ")}) } else { @(${completionCommands()
+                .map((command) => `'${command}'`)
+                .join(", ")}) }
+  $candidates | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+}
+`;
+    }
+}
+export function parseCompletionShell(value) {
+    if (["bash", "zsh", "fish", "powershell"].includes(value))
+        return value;
+    throw new Error("Supported shells: bash, zsh, fish, powershell");
+}

package/dist/src/core/{doctor.js → reporting/doctor.js}

@@ -1,7 +1,7 @@
 import { access, constants } from "node:fs/promises";
 import { dirname } from "node:path";
-import { detectAgents, directoryExists, loadoutHome, userHome, } from "./paths.js";
-import { inspectAgents } from "./agent-inspection.js";
+import { detectAgents, directoryExists, loadoutHome, userHome, } from "../agents/paths.js";
+import { countComponentUnits, 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.
@@ -65,10 +65,7 @@ export async function runDoctor() {
 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 allIssues = [...report.issues, ...installed.flatMap((a) => a.issues)];
     const grade = allIssues.length === 0 && installed.length > 0
         ? "HEALTHY"
         : allIssues.length <= 2
@@ -86,13 +83,11 @@ export function formatDoctorReport(report, options = {}) {
     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 skillCount = entry.inventory.components.reduce((sum, component) => sum + countComponentUnits(component), 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(", ")}`);
+            lines.push(`  ✓ ${entry.agent.displayName}`, `    ${entry.agent.skillsDirectory}`, `    ${skillCount} skills | supports: ${supported.join(", ")}`);
             if (entry.issues.length) {
                 for (const issue of entry.issues)
                     lines.push(`    ⚠ ${issue}`);

package/dist/src/core/{freshness-alerts.js → reporting/freshness-alerts.js}

@@ -1,11 +1,11 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { writeFileAtomically } from "./atomic-file.js";
-import { loadEffectiveCatalog } from "./catalog.js";
-import { ensureDirectory, loadoutHome } from "./paths.js";
-import { readInstallState } from "./state.js";
-import { buildUpdatePlan } from "./update.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { loadEffectiveCatalog } from "../catalog/catalog.js";
+import { ensureDirectory, loadoutHome } from "../agents/paths.js";
+import { readInstallState } from "../workspace/state.js";
+import { buildUpdatePlan } from "../install/update.js";
 const decisionsPath = () => join(loadoutHome(), "alert-decisions.json");
 function alertId(packageId, kind, evidence) {
     return `${packageId}-${kind}-${createHash("sha256")

package/dist/src/core/{health.js → reporting/health.js}

@@ -1,12 +1,12 @@
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
-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";
-import { listInstalledRuntimeToolSkillTargets, listInstalledRuntimeTools, } from "./runtime-tools.js";
+import { managedFileReadPath } from "../workspace/active-set.js";
+import { detectAgents } from "../agents/paths.js";
+import { readInstallState } from "../workspace/state.js";
+import { buildUpdatePlan } from "../install/update.js";
+import { codexMcpServerFingerprint } from "../agents/codex-mcp.js";
+import { listInstalledRuntimeToolSkillTargets, listInstalledRuntimeTools, } from "../agents/runtime-tools.js";
 async function drift(record, activations) {
     const changed = [];
     for (const file of record.files) {

package/dist/src/core/{loadout-card.js → reporting/loadout-card.js}

@@ -1,4 +1,4 @@
-import { buildLocalAgentHealthScores } from "./health-score-evidence.js";
+import { buildLocalAgentHealthScores } from "../agents/health-score-evidence.js";
 import { buildHealthReport, gradeHealth } from "./health.js";
 import { buildPrivacySafeReport, } from "./share-report.js";
 export async function buildLoadoutCard(options = {}) {

package/dist/src/core/{readme-claims.js → reporting/readme-claims.js}

@@ -1,4 +1,4 @@
-import { formatSchemaError, readmeClaimManifestSchema, } from "../shared/schemas.js";
+import { formatSchemaError, readmeClaimManifestSchema, } from "../../shared/schemas.js";
 export { readmeClaimManifestSchema };
 /** Parse the versioned index of evidence for material README statements. */
 export function parseReadmeClaimManifest(value) {

package/dist/src/core/{readme-facts.js → reporting/readme-facts.js}

@@ -1,5 +1,5 @@
-import { supportedAdapterNames } from "./adapters.js";
-import { buildCatalogCoverage } from "./catalog-coverage.js";
+import { supportedAdapterNames, } from "../agents/adapters.js";
+import { buildCatalogCoverage } from "../catalog/catalog-coverage.js";
 function profileFacts(allowlist) {
     return {
         sources: Object.keys(allowlist).length,

package/dist/src/core/{share-report.js → reporting/share-report.js}

@@ -1,7 +1,7 @@
 import { dirname } from "node:path";
-import { writeFileAtomically } from "./atomic-file.js";
-import { ensureDirectory } from "./paths.js";
-import { readInstallState } from "./state.js";
+import { writeFileAtomically } from "../install/atomic-file.js";
+import { ensureDirectory } from "../agents/paths.js";
+import { readInstallState } from "../workspace/state.js";
 export function parsePrivacySafeLoadoutReport(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error("Privacy-safe Loadout report must be an object");

package/dist/src/core/{upgrade.js → reporting/upgrade.js}

@@ -1,11 +1,11 @@
-import { buildAdapterCapabilityGaps, } from "./adapters.js";
-import { applyPreparedCatalogInstall, formatPreparedCatalogInstall, prepareCatalogInstall, } from "./catalog-install.js";
-import { DEFAULT_ACTIVE_SKILL_LIMIT } from "./active-limit.js";
-import { loadEffectiveCatalog } from "./catalog.js";
+import { buildAdapterCapabilityGaps, } from "../agents/adapters.js";
+import { applyPreparedCatalogInstall, formatPreparedCatalogInstall, prepareCatalogInstall, } from "../install/catalog-install.js";
+import { DEFAULT_ACTIVE_SKILL_LIMIT } from "../workspace/active-limit.js";
+import { loadEffectiveCatalog, } from "../catalog/catalog.js";
 import { buildHealthReport, formatHealthReport } from "./health.js";
-import { buildLocalAgentHealthScores } from "./health-score-evidence.js";
-import { formatRecommendations, personalizeRecommendations, recommendPackages, scanProject, } from "./recommend.js";
-import { readLocalOutcomes } from "./outcomes.js";
+import { buildLocalAgentHealthScores } from "../agents/health-score-evidence.js";
+import { formatRecommendations, personalizeRecommendations, recommendPackages, scanProject, } from "../workspace/recommend.js";
+import { readLocalOutcomes, } from "../workspace/outcomes.js";
 /**
  * Builds the complete first-run preview without changing agent or Loadout state.
  * Network access is limited to the same immutable catalog preparation performed by

package/dist/src/core/routing/first-party-skills.js

@@ -0,0 +1,118 @@
+import { cp, rm, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { detectAgents } from "../agents/paths.js";
+export const FIRST_PARTY_SKILLS = [
+    {
+        id: "loadout-router",
+        displayName: "Loadout Router",
+        summary: "Lets an agent pick the right model tier for a task and hand work to another agent",
+    },
+    {
+        id: "loadout-curator",
+        displayName: "Loadout Curator",
+        summary: "Lets an agent decide which skills and MCP servers should be active for the current repository",
+    },
+];
+/**
+ * Locate the bundled `skills/` directory. Resolution walks upward so it works
+ * both from `src/` under tsx and from `dist/src/` in the published package.
+ */
+export async function bundledSkillsRoot() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 5; depth += 1) {
+        const candidate = join(dir, "skills");
+        try {
+            if ((await stat(candidate)).isDirectory())
+                return candidate;
+        }
+        catch {
+            // Keep walking toward the package root.
+        }
+        dir = dirname(dir);
+    }
+    throw new Error("Bundled skills directory not found; this build may be incomplete.");
+}
+export function findFirstPartySkill(id) {
+    const skill = FIRST_PARTY_SKILLS.find((item) => item.id === id);
+    if (!skill)
+        throw new Error(`Unknown Loadout skill '${id}'. Available: ${FIRST_PARTY_SKILLS.map((s) => s.id).join(", ")}`);
+    return skill;
+}
+async function directoryExists(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build a preview of where one first-party skill would be installed. Nothing is
+ * written; the caller decides whether to apply.
+ */
+export async function planFirstPartySkill(id, options = {}) {
+    const skill = findFirstPartySkill(id);
+    const source = join(await bundledSkillsRoot(), skill.id);
+    if (!(await directoryExists(source)))
+        throw new Error(`Bundled skill '${skill.id}' is missing from this build.`);
+    const detected = options.detected ?? (await detectAgents());
+    const installed = detected.filter((agent) => agent.installed);
+    const requested = options.agents?.length
+        ? installed.filter((agent) => options.agents.includes(agent.id))
+        : installed;
+    const targets = [];
+    for (const agent of requested) {
+        const destination = join(agent.skillsDirectory, skill.id);
+        targets.push({
+            agent: agent.id,
+            displayName: agent.displayName,
+            destination,
+            replacing: await directoryExists(destination),
+        });
+    }
+    return { skill, source, targets };
+}
+export async function applyFirstPartySkill(plan) {
+    for (const target of plan.targets) {
+        // Replace wholesale so a reinstall cannot leave files from an older
+        // version of the skill behind.
+        if (target.replacing)
+            await rm(target.destination, { recursive: true });
+        await cp(plan.source, target.destination, { recursive: true });
+    }
+}
+export async function removeFirstPartySkill(plan) {
+    for (const target of plan.targets)
+        if (target.replacing)
+            await rm(target.destination, { recursive: true });
+}
+export function formatFirstPartySkillList(installedIds = new Set()) {
+    const lines = ["Skills that ship with Loadout:", ""];
+    for (const skill of FIRST_PARTY_SKILLS) {
+        const marker = installedIds.has(skill.id) ? "✓" : "○";
+        lines.push(`  ${marker} ${skill.id} — ${skill.summary}`);
+    }
+    lines.push("", "Install with: loadout skills install <id> --yes", "These teach your agents to use Loadout from inside a conversation.");
+    return lines.join("\n");
+}
+export function formatFirstPartySkillPlan(plan) {
+    if (!plan.targets.length)
+        return `No installed agents detected, so '${plan.skill.id}' has nowhere to go. Install an agent first.`;
+    const lines = [`${plan.skill.displayName} (${plan.skill.id})`, ""];
+    for (const target of plan.targets)
+        lines.push(`  ${target.replacing ? "replace" : "install"} → ${target.destination}  [${target.displayName}]`);
+    return lines.join("\n");
+}
+/** Which first-party skills are already present for at least one agent. */
+export async function installedFirstPartySkills(detected) {
+    const agents = (detected ?? (await detectAgents())).filter((agent) => agent.installed);
+    const found = new Set();
+    for (const skill of FIRST_PARTY_SKILLS)
+        for (const agent of agents)
+            if (await directoryExists(join(agent.skillsDirectory, skill.id))) {
+                found.add(skill.id);
+                break;
+            }
+    return found;
+}