loadout-ai 0.5.9 → 0.7.0

package/docs/UPSTREAM_LICENSE_DECISIONS.md

@@ -1,31 +1,38 @@
 # Upstream license decisions
 
-Reviewed on July 21, 2026 for the public release catalog.
+Reviewed on July 21, 2026 for the public release catalog. Re-reviewed on August 30,
+2026: two of the original six records had identifiable repository-wide licenses and
+were updated in `catalog/packages.json`; four remain `NOASSERTION`.
 
 Loadout records `NOASSERTION` when it cannot identify one repository-wide SPDX
 license from the inspected source. Popularity, an official publisher, or a public
 GitHub repository does not replace a license grant.
 
-## Release decision
+## Resolved out of NOASSERTION (August 30, 2026)
 
-The six records below remain in the credited catalog as source metadata. Loadout
+| Catalog record | Upstream source                                                 | Recorded decision                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| -------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Vercel Skills  | [vercel-labs/skills](https://github.com/vercel-labs/skills)     | Updated `license` to `MIT`. The repository now carries a root `LICENSE` file (MIT, Vercel, Inc., 2026) and GitHub's license API confirms `mit`. No longer `NOASSERTION`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| Sentry MCP     | [getsentry/sentry-mcp](https://github.com/getsentry/sentry-mcp) | Updated `license` to `FSL-1.1-ALv2`. The root `LICENSE.md` is the Functional Source License 1.1, Apache-2.0 Future License — a single, identifiable repository-wide license, just not one GitHub's detector classifies as a standard OSS license. **This is not a permissive OSI license**: it forbids "Competing Use" (offering the software, or a substitute for it, as a competing commercial product or service) until it converts to Apache-2.0 two years after each release. Sentry MCP is not part of Stable and should stay out of any default/non-custom mode; Power, Maximum, or Custom selections must show this restriction before fetch, not just a generic "review upstream terms" notice. |
+
+## Remaining NOASSERTION (four records)
+
+The four records below remain in the credited catalog as source metadata. Loadout
 does not copy their source into the npm package, claim ownership, or assign them a
 license. A selected profile may fetch a pinned upstream snapshot only after showing
 the user a preview. MCP configuration and executable tools remain separate explicit
 actions.
 
-None of these six records is part of Stable. Stable continues to use four sources
+None of these four records is part of Stable. Stable continues to use four sources
 with identified SPDX licenses. People who select Power, Maximum, or a Custom package
 must review the linked upstream terms before using content marked `NOASSERTION`.
 
-| Catalog record                 | Upstream source                                                                 | Recorded decision                                                                                                                   |
-| ------------------------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| OpenAI Skills Catalog          | [openai/skills](https://github.com/openai/skills)                               | Retain the pinned catalog pointer with `NOASSERTION`; no repository-wide root license was identified.                               |
-| Anthropic Skills               | [anthropics/skills](https://github.com/anthropics/skills)                       | Retain the pinned catalog pointer with `NOASSERTION`; no repository-wide root license was identified.                               |
-| Vercel Agent Skills            | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)         | Retain the pinned catalog pointer with `NOASSERTION`; no repository-wide root license was identified.                               |
-| Vercel Skills                  | [vercel-labs/skills](https://github.com/vercel-labs/skills)                     | Retain the pinned catalog pointer with `NOASSERTION`; no repository-wide root license was identified.                               |
-| Sentry MCP                     | [getsentry/sentry-mcp](https://github.com/getsentry/sentry-mcp)                 | Retain the pinned catalog pointer with `NOASSERTION`; the root license file is not identified as a standard SPDX license by GitHub. |
-| Model Context Protocol Servers | [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | Retain the pinned catalog pointer with `NOASSERTION`; the root license file is not identified as a standard SPDX license by GitHub. |
+| Catalog record                 | Upstream source                                                                 | Recorded decision                                                                                                                                                                                                                                                                                                                                                  |
+| ------------------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| OpenAI Skills Catalog          | [openai/skills](https://github.com/openai/skills)                               | Retain `NOASSERTION`; the repository has no root `LICENSE` file of any kind.                                                                                                                                                                                                                                                                                       |
+| Anthropic Skills               | [anthropics/skills](https://github.com/anthropics/skills)                       | Retain `NOASSERTION`; the repository has no root `LICENSE` file of any kind.                                                                                                                                                                                                                                                                                       |
+| Vercel Agent Skills            | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)         | Retain `NOASSERTION`; the repository has no root `LICENSE` file of any kind.                                                                                                                                                                                                                                                                                       |
+| Model Context Protocol Servers | [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | Retain `NOASSERTION`; the root `LICENSE` file itself states the project is mid-transition from MIT to Apache-2.0 — new/relicensed contributions are Apache-2.0, contributions whose authors have not consented to relicensing remain MIT. No single SPDX identifier covers the whole repository, so this is a genuine mixed-license case, not a missing-file case. |
 
 This is a transparent product policy decision, not legal advice or a claim that the
 upstream material may be redistributed under Loadout's MIT license. Each upstream

package/docs/evidence/readme-claims.json

@@ -21,7 +21,7 @@
       "status": "proven",
       "evidence": [
         "catalog/packages.json",
-        "src/core/catalog-coverage.ts",
+        "src/core/catalog/catalog-coverage.ts",
         "tests/catalog-coverage.test.ts"
       ]
     },
@@ -31,7 +31,7 @@
       "summary": "Stable selection is defined by the checked-in policy and allowlist.",
       "evidenceClass": "policy-selected",
       "status": "proven",
-      "evidence": ["src/core/profiles.ts", "tests/profiles.test.ts"]
+      "evidence": ["src/core/catalog/profiles.ts", "tests/profiles.test.ts"]
     },
     {
       "id": "selection.power",
@@ -39,7 +39,7 @@
       "summary": "Power selection is defined by the checked-in policy and allowlist.",
       "evidenceClass": "policy-selected",
       "status": "proven",
-      "evidence": ["src/core/profiles.ts", "tests/profiles.test.ts"]
+      "evidence": ["src/core/catalog/profiles.ts", "tests/profiles.test.ts"]
     },
     {
       "id": "selection.maximum",
@@ -47,7 +47,10 @@
       "summary": "Maximum selection keeps optional components in Loadout's managed library rather than activating every component.",
       "evidenceClass": "integration-verified",
       "status": "bounded",
-      "evidence": ["src/core/active-set.ts", "tests/active-set.test.ts"]
+      "evidence": [
+        "src/core/workspace/active-set.ts",
+        "tests/active-set.test.ts"
+      ]
     },
     {
       "id": "agents.support",
@@ -56,7 +59,7 @@
       "evidenceClass": "integration-verified",
       "status": "bounded",
       "evidence": [
-        "src/core/adapters.ts",
+        "src/core/agents/adapters.ts",
         "tests/adapters.test.ts",
         "tests/adapter-conformance.test.ts"
       ]
@@ -79,7 +82,7 @@
       "evidenceClass": "integration-verified",
       "status": "proven",
       "evidence": [
-        "src/core/install.ts",
+        "src/core/install/install.ts",
         "tests/transaction.test.ts",
         "tests/install.test.ts"
       ]
@@ -90,7 +93,7 @@
       "summary": "Update workflows present a bounded local plan before an explicit apply step.",
       "evidenceClass": "integration-verified",
       "status": "proven",
-      "evidence": ["src/core/update.ts", "tests/update.test.ts"]
+      "evidence": ["src/core/install/update.ts", "tests/update.test.ts"]
     },
     {
       "id": "updates.saved-profile",
@@ -99,8 +102,8 @@
       "evidenceClass": "integration-verified",
       "status": "proven",
       "evidence": [
-        "src/core/profile-state.ts",
-        "src/core/update.ts",
+        "src/core/workspace/profile-state.ts",
+        "src/core/install/update.ts",
         "tests/profile-state.test.ts",
         "tests/update.test.ts"
       ]
@@ -111,7 +114,7 @@
       "summary": "Managed installation treats recursively empty leftover skill directories as unoccupied while retaining collision protection for files and symlinks.",
       "evidenceClass": "integration-verified",
       "status": "proven",
-      "evidence": ["src/core/install.ts", "tests/install.test.ts"]
+      "evidence": ["src/core/install/install.ts", "tests/install.test.ts"]
     },
     {
       "id": "rollback.snapshot",
@@ -120,7 +123,7 @@
       "evidenceClass": "integration-verified",
       "status": "proven",
       "evidence": [
-        "src/core/snapshot.ts",
+        "src/core/install/snapshot.ts",
         "tests/snapshot.test.ts",
         "tests/transaction.test.ts"
       ]
@@ -131,7 +134,7 @@
       "summary": "Recommendations expose bounded repository and local evidence rather than universal quality claims.",
       "evidenceClass": "unit-verified",
       "status": "bounded",
-      "evidence": ["src/core/recommend.ts", "tests/recommend.test.ts"]
+      "evidence": ["src/core/workspace/recommend.ts", "tests/recommend.test.ts"]
     },
     {
       "id": "trust.stages",
@@ -140,7 +143,7 @@
       "evidenceClass": "structural",
       "status": "proven",
       "evidence": [
-        "src/core/profiles.ts",
+        "src/core/catalog/profiles.ts",
         "tests/profiles.test.ts",
         "docs/CATALOG_POLICY.md"
       ]
@@ -152,7 +155,7 @@
       "evidenceClass": "integration-verified",
       "status": "proven",
       "evidence": [
-        "src/core/github-discovery.ts",
+        "src/core/discovery/github-discovery.ts",
         "tests/daily-discovery.test.ts",
         "tests/review-queue.test.ts"
       ]
@@ -177,7 +180,7 @@
       "status": "proven",
       "evidence": [
         "src/cli.ts",
-        "src/core/mcp-recipes.ts",
+        "src/core/runtime/mcp-recipes.ts",
         "tests/cli-help.test.ts",
         "tests/mcp-recipes.test.ts"
       ]
@@ -188,7 +191,7 @@
       "summary": "MCP configuration uses explicit plans and keeps credentials outside persisted shared manifests.",
       "evidenceClass": "integration-verified",
       "status": "proven",
-      "evidence": ["src/core/mcp.ts", "tests/mcp-config.test.ts"]
+      "evidence": ["src/core/runtime/mcp.ts", "tests/mcp-config.test.ts"]
     },
     {
       "id": "manifests.portability",
@@ -197,7 +200,7 @@
       "evidenceClass": "structural",
       "status": "proven",
       "evidence": [
-        "src/core/manifest.ts",
+        "src/core/workspace/manifest.ts",
         "src/shared/schemas.ts",
         "tests/manifest.test.ts"
       ]
@@ -209,8 +212,8 @@
       "evidenceClass": "integration-verified",
       "status": "bounded",
       "evidence": [
-        "src/core/uninstall.ts",
-        "src/core/remove.ts",
+        "src/core/install/uninstall.ts",
+        "src/core/install/remove.ts",
         "tests/uninstall.test.ts"
       ]
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadout-ai",
-  "version": "0.5.9",
+  "version": "0.7.0",
   "private": false,
   "license": "MIT",
   "description": "Universal upgrade manager for AI coding agents",
@@ -11,6 +11,7 @@
   "files": [
     "dist/src",
     "catalog",
+    "skills",
     "docs",
     "README.md",
     "CHANGELOG.md",

package/skills/loadout-curator/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: loadout-curator
+description: Decide which agent skills, MCP servers, and tools should be active for the current repository, and keep that set current. Use when the user asks what skills they should install, why an agent is missing context about their stack, whether their setup is up to date, or when starting work in an unfamiliar codebase.
+---
+
+# Loadout Curator
+
+Match the active skill set to the repository in front of you. Too few skills and
+the agent lacks context; too many and every prompt carries weight it does not
+need.
+
+This skill wraps the `loadout` CLI so the catalog, provenance, and safety
+findings stay current rather than being copied into this file.
+
+## Prerequisite
+
+```bash
+loadout --version
+```
+
+If that fails, tell the user to install it (`npm install --global loadout-ai`)
+and stop; do not guess at catalog contents.
+
+## Starting work in a repository
+
+Read what the codebase actually is before suggesting anything:
+
+```bash
+loadout recommend --project .
+```
+
+This prints detected signals (languages, frameworks, test runners) and
+rule-based suggestions with a confidence label. The signals are the useful part
+— they tell you what the repository is without you reading every file.
+
+Report the detected stack first, then the suggestions worth acting on. Skip
+low-confidence suggestions unless the user asks for the full list.
+
+`recommend` reads the project and the catalog. It does not prove quality, and it
+says so; repeat that framing rather than presenting suggestions as verified.
+
+## Proposing an active set
+
+```bash
+loadout optimize --project .
+```
+
+This proposes which already-downloaded library skills should be active here.
+Use it when the user has a Maximum-mode library, or after `recommend` shows the
+project needs something different from what is on.
+
+Present the proposal as a diff in plain words — what turns on, what turns off,
+and why — before the user approves. Both commands are read-only until `--yes`.
+
+## Installing something new
+
+```bash
+loadout setup --mode custom --package <id>        # preview
+loadout setup --mode custom --package <id> --yes  # apply
+```
+
+Never run the `--yes` form on your own initiative. Show the preview, summarize
+what it adds and to which agents, and let the user approve. Loadout snapshots
+before writing, and `loadout rollback` undoes the last apply — say so, because
+it lowers the cost of trying something.
+
+If the preview reports safety findings (scripts, network domains, instruction
+overrides), read them out specifically. Do not summarize a finding as "minor."
+
+## Checking whether the setup is current
+
+```bash
+loadout status     # health grade and what is managed
+loadout health     # safer updates and local drift
+loadout alerts     # archived, stale, or changed upstream sources
+```
+
+Run these when the user asks whether their setup is up to date, or when an agent
+behaves oddly and stale or drifted skills could explain it.
+
+`alerts` reporting an archived upstream is worth raising unprompted — an
+archived source will not receive fixes.
+
+## Inspecting before trusting
+
+For a source not yet in the catalog:
+
+```bash
+loadout inspect --repository <owner/name>
+```
+
+This clones at an immutable commit and classifies what it finds. Use it when the
+user asks about a repository you cannot otherwise vouch for. Report what it
+actually contains rather than what its README claims.
+
+## Judgment this skill does not replace
+
+- A large active set is not automatically wrong; a monorepo touching several
+  stacks legitimately needs more than a single-purpose service.
+- Detected signals describe dependencies, not intent. A repository with a test
+  runner installed but no tests still needs testing skills.
+- The catalog is a review queue with provenance, not a quality ranking. High
+  star counts are evidence of popularity only.
+- Never enable an MCP server that needs credentials without walking the user
+  through what it will access first.

package/skills/loadout-router/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: loadout-router
+description: Choose the right model tier and agent for a coding task, and hand work off between Claude Code and Codex. Use when the user asks which model to use, mentions running low on usage or quota, wants to save tokens or cost, asks whether to switch to Opus/Sonnet/Haiku or a GPT tier, or wants to delegate a task to another agent.
+---
+
+# Loadout Router
+
+Route each coding task to the cheapest model that still does it well, and hand
+work between agents when a different one is better suited.
+
+This skill wraps the `loadout` CLI, so the model catalog and pricing stay
+current with the installed version rather than going stale in this file.
+
+## Prerequisite
+
+Check once per session:
+
+```bash
+loadout --version
+```
+
+If that fails, tell the user to install it (`npm install --global loadout-ai`)
+and answer from general knowledge instead of guessing at specifics.
+
+## Choosing a model
+
+Run the router with the task described in plain words:
+
+```bash
+loadout route <task description>
+```
+
+It classifies the task into one of six phases — plan, implement, review, test,
+debug, document — and prints the recommended tier, the models in that tier with
+current prices, which of the user's installed agents can run them, and a cheaper
+fallback with its tradeoff.
+
+Report the recommendation and the reason. Name the actual model, not just the
+tier. If the output lists a `Conserve:` alternative, mention it only when the
+user cares about cost or quota, otherwise it is noise.
+
+When the user is explicit about the phase, skip classification:
+
+```bash
+loadout route --phase review
+```
+
+## When the user is low on usage
+
+If the user mentions running out, being rate limited, conserving quota, or
+stretching a plan, add `--conserve`:
+
+```bash
+loadout route --conserve <task description>
+```
+
+This drops each phase one tier and prints the tradeoff you are accepting. Say
+what is being given up — "shallower architectural reasoning, so review the plan
+more carefully" — rather than presenting it as a free win.
+
+Neither Claude Code nor Codex exposes remaining quota programmatically, so never
+claim to know how much the user has left. `--conserve` is a user-driven choice,
+not a measurement.
+
+## Comparing models and cost
+
+```bash
+loadout route --models
+loadout route --models --provider anthropic
+loadout route --models --tier fast
+loadout route --cost
+```
+
+Use these when the user asks what is available or what something costs. Prices
+are per-million-token list rates; actual spend depends on prompt size, so give
+ratios ("roughly 4x cheaper") rather than predicting a dollar total.
+
+## Handing work to another agent
+
+When a different agent suits the task better — or the user asks to delegate —
+use the handoff log. Check it is set up:
+
+```bash
+loadout handoff status
+```
+
+If uninitialized, run `loadout handoff init` first. Then send the task:
+
+```bash
+loadout handoff send codex "write unit tests for the auth module" --context "see src/auth.ts"
+```
+
+Put anything the receiving agent needs into `--context`: file paths, the
+decision you already made, what you deliberately left out. The other agent has
+none of this conversation.
+
+Sending a task is a real side effect on a shared file. Confirm with the user
+before sending unless they asked for the handoff themselves.
+
+## Reading your own inbox
+
+At the start of a session, and after finishing a task, check whether another
+agent left you work:
+
+```bash
+loadout handoff inbox claude-code
+```
+
+If it lists tasks, work them in order and run the `loadout handoff done <id>`
+command it prints for each one. If it reports none, continue as normal and do
+not mention it.
+
+## Judgment this skill does not replace
+
+- A "simple" task in an unfamiliar or high-risk area still deserves a stronger
+  model. The classifier reads keywords, not stakes.
+- Security-sensitive, migration, and data-loss paths are worth frontier tier
+  regardless of what phase they classify as.
+- If the user has already chosen a model, do not argue unless the choice is
+  clearly wrong for the work.

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

@@ -1,118 +0,0 @@
-/** Plain-language entry points for people using the CLI, not maintaining it. */
-export const BEGINNER_GUIDE = `
-START HERE
-
-1. See what Loadout currently manages
-   loadout library
-   loadout scan
-   loadout reconcile
-
-2. Preview the recommended everyday setup
-   loadout setup --mode stable
-   loadout profiles
-
-3. Find additions that fit the project in this folder
-   loadout recommend --project .
-   loadout optimize --project .
-
-4. Check for safer updates and new discoveries
-   loadout health
-   loadout alerts
-   loadout candidate list --limit 10
-
-5. See reviewed MCP integrations and their credential needs
-   loadout mcp-recipe
-   loadout mcp-recipe --credential-free
-   loadout mcp-recipe playwright --agent codex
-
-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.
-
-Setup reconciles the complete selected profile. To add one catalog package without
-retiring the current managed profile, use:
-   loadout install --mode custom --package <id>
-
-Nothing above changes your agents. For the full maintainer/tooling surface, run:
-loadout advanced
-`.trim();
-export const ADVANCED_GUIDE = [
-    "ADVANCED COMMANDS",
-    "",
-    "These remain available, but are hidden from the first screen so daily use stays simple.",
-    "",
-    "Discovery and evidence: candidate, discover, review-queue, compare, evaluate, capabilities, skill-audit.",
-    "Manifests and sharing: init, add, unadd, lock, export, import, audit, create, pack, publish, share, card, badge.",
-    "Integrations and safety: mcp-recipe, mcp-config, codex-mcp-config, credentials, models, sandbox-run, canary, convert.",
-    "Lifecycle extras: plan, adopt, uninstall, profiles, versions, outcomes, improve, autopilot, tool, watch, schedule, unschedule, serve.",
-    "",
-    "Use `loadout <command> --help` for exact options. Every mutation-capable command previews first or requires --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",
-    "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",
-    // integrations / credentials / runtime
-    "credentials",
-    "models",
-    "completion",
-    "mcp-recipe",
-    "mcp-config",
-    "codex-mcp-config",
-    "sandbox-run",
-    "convert",
-    "canary",
-    "serve",
-    // lifecycle extras
-    "plan",
-    "adopt",
-    "uninstall",
-    "profiles",
-    "autopilot",
-    "tool",
-    "watch",
-    "schedule",
-    "unschedule",
-    "alert-ignore",
-    "alert-pin",
-    "alert-unpin",
-    "alert-pins",
-]);

package/dist/src/core/doctor.js

@@ -1,95 +0,0 @@
-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";
-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) {
-    const lines = [
-        "Loadout doctor",
-        `Platform: ${report.platform}`,
-        `User home: ${report.userHome}`,
-        `State home: ${report.loadoutHome}`,
-    ];
-    lines.push(`State status: ${report.loadoutHomeExists ? "present" : "not created"} (${report.loadoutHomeWritable ? "writable" : "not writable"})`, "", "Agents:");
-    for (const entry of report.agents) {
-        const status = entry.agent.installed ? "detected" : "not found";
-        lines.push(`  ${entry.agent.installed ? "✓" : "○"} ${entry.agent.displayName}: ${status}`, `    skills: ${entry.agent.skillsDirectory} (${entry.skillsRootExists ? "present" : "will be created"}, ${entry.writable ? "writable" : "not writable"})`);
-        for (const component of entry.inventory.components) {
-            const detail = component.scanned
-                ? `${component.directoryExists ? `${component.entries.length} filesystem item(s)` : "not created"}${component.directory ? ` at ${component.directory}` : ""}`
-                : (component.note ?? "not inspected");
-            lines.push(`    ${component.type}: ${component.compatibility}; ${detail}`);
-        }
-        for (const warning of entry.inventory.warnings)
-            lines.push(`    ! ${warning}`);
-        for (const issue of entry.issues)
-            lines.push(`    ! ${issue}`);
-    }
-    if (report.issues.length) {
-        lines.push("", "Recommendations:");
-        for (const issue of report.issues)
-            lines.push(`  ! ${issue}`);
-    }
-    else
-        lines.push("", "No global blocking issues found.");
-    return lines.join("\n");
-}