loadout-ai 0.5.9 → 0.6.0

package/README.md

@@ -34,7 +34,7 @@
 You need Node.js 20 or newer and Git.
 
 ```bash
-npm install --global loadout-ai@0.5.9
+npm install --global loadout-ai
 loadout setup --mode stable
 ```
 
@@ -54,23 +54,37 @@ Nothing changes until you approve it. If anything goes wrong, start with the
 
 ### Abridged terminal transcript
 
-This is an explicitly abridged transcript from a disposable, single-Codex Stable run. A literal `…` marks omitted fetch output; `<snapshot-id>` is a variable placeholder because snapshot IDs vary.
+This is an explicitly abridged transcript from a disposable Stable run. A literal `…` marks omitted fetch output; `<snapshot-id>` is a variable placeholder because snapshot IDs vary. Loadout auto-detects installed agents; `--agents` narrows the selection when needed.
 
 ```console
-$ loadout setup --mode stable --agents codex
+$ loadout setup --mode stable
 …
 Loadout: Stable Boost
-Detected agents: Codex
+Detected agents: Claude Code, Cursor, Codex
 Catalog selection: 4 repositories
 Ready to install: 4 skill repositories (30 agent skill directories)
 Preview complete; nothing was changed. Re-run with --yes to install this exact screened plan.
 
-$ loadout setup --mode stable --agents codex --yes
+$ loadout setup --mode stable --yes
 …
-Loadout installed 4 repositories for 1 agent(s). Snapshot: <snapshot-id>
+Loadout installed 4 repositories for 3 agent(s). Snapshot: <snapshot-id>
 
 $ loadout rollback
 Restored snapshot <snapshot-id>
+
+$ loadout route design the authentication system
+Phase:    plan
+Tier:     Frontier (deep reasoning)
+Models:   Claude Opus 5 ($5/$25)
+          GPT-5.6 Sol ($5/$30)
+Agents:   claude-code
+Why:      Architecture and decomposition need deep reasoning to avoid costly rework
+
+$ loadout doctor
+loadout doctor — HEALTHY
+Platform:   darwin
+State:      ~/.loadout ✓ writable
+Agents:     3 detected, 9 available
 ```
 
 The final preview sentence above is captured CLI wording. A later `--yes` invocation recomputes the plan from pinned sources and current agent and filesystem state; it does not persist or prove identity with the earlier preview.
@@ -106,9 +120,9 @@ everything into every prompt.
 | Hope updates do not break anything                             | Preview updates and protect every managed change with a snapshot |
 | Manually remember what was changed                             | Scan, reconcile, remove, roll back, or completely uninstall      |
 
-Loadout is local, open source, and preview-first. It does not need an OpenAI or
-Anthropic API key to manage skills. MCP servers and executable tools stay behind
-their own explicit setup and permission steps.
+Loadout is local, open source, and preview-first. It does not need an LLM API key
+to manage skills. MCP servers and executable tools stay behind their own explicit
+setup and permission steps.
 
 ### Demo
 
@@ -218,9 +232,9 @@ project choose a focused active set:
 
 ```bash
 loadout setup --mode maximum
-loadout recommend --project . --agent codex
-loadout optimize --project . --agents codex,claude-code --limit 30
-loadout optimize --project . --agents codex,claude-code --limit 30 --yes
+loadout recommend --project .
+loadout optimize --project . --limit 30
+loadout optimize --project . --limit 30 --yes
 ```
 
 This is the difference between “install everything” and “have everything ready.”
@@ -242,11 +256,11 @@ managed profile:
 
 ```bash
 
-# Install the reviewed Humanizer writing skill into Codex
-loadout install --mode custom --package humanizer --agents codex
+# Install the reviewed Humanizer writing skill
+loadout install --mode custom --package humanizer
 
-# Install the reviewed Obsidian skills explicitly
-loadout install --mode custom --package obsidian-skills --agents codex,claude-code
+# Install the reviewed Obsidian skills for specific agents
+loadout install --mode custom --package obsidian-skills --agents claude-code,cursor
 ```
 
 Run `loadout profiles` to compare every mode. MCP servers always use a separate
@@ -266,12 +280,9 @@ loadout mcp-recipe --credential-free
 Preview and configure one for the host you use:
 
 ```bash
-loadout mcp-recipe playwright --agent codex
-loadout mcp-recipe playwright --agent codex --yes
-loadout mcp-recipe playwright --agent codex --verify
-
 loadout mcp-recipe playwright --agent claude-code
 loadout mcp-recipe playwright --agent claude-code --yes
+loadout mcp-recipe playwright --agent claude-code --verify
 ```
 
 Configuration alone does not start the server. Test a real connection separately
@@ -282,12 +293,12 @@ variables or the OS keychain without printing their values.
 
 [Graphify](https://github.com/Graphify-Labs/graphify) is an optional codebase graph
 tool. It installs both a command and an agent skill, so Loadout keeps it separate from
-the normal profiles. It does not require an OpenAI or Anthropic API key:
+the normal profiles. It does not require an LLM API key:
 
 ```bash
-loadout tool graphify --agents codex,claude-code
-loadout tool graphify --agents codex,claude-code --yes --approve-risk
-loadout tool graphify --remove --agents codex,claude-code --yes --approve-risk
+loadout tool graphify
+loadout tool graphify --yes --approve-risk
+loadout tool graphify --remove --yes --approve-risk
 ```
 
 Executable tools remain an explicit choice instead of hiding inside a profile.
@@ -338,7 +349,7 @@ Loadout does not claim there is one universally “best” configuration. Recomm
 
 <!-- loadout:daily-discovery:start -->
 
-**Discovery snapshot (generated 2026-08-27):** [236 repositories observed](./docs/DISCOVERED.md), including 217 uncataloged review candidates and 19 repositories already in the inspected catalog.
+**Discovery snapshot (generated 2026-08-30):** [237 repositories observed](./docs/DISCOVERED.md), including 218 uncataloged review candidates and 19 repositories already in the inspected catalog.
 <!-- loadout:daily-discovery:end -->
 
 The checked-in discovery report proves only its dated snapshot, not the success of every scheduled run. Use `loadout discover --source all --queue`, `loadout review-queue`, and `loadout candidate inspect owner/repository` to inspect candidates before catalog promotion.
@@ -355,11 +366,11 @@ The checked-in discovery report proves only its dated snapshot, not the success
 
 <!-- loadout:current-limits:start -->
 
-- **6 catalog records** currently have `NOASSERTION` license status and need upstream-license review before a public release decision.
+- **4 catalog records** currently have `NOASSERTION` license status and need upstream-license review before a public release decision.
 
 <!-- loadout:current-limits:end -->
 
-The six records have an explicit public-release decision rather than an assumed
+The four records have an explicit public-release decision rather than an assumed
 license. Read [Upstream license decisions](./docs/UPSTREAM_LICENSE_DECISIONS.md) for
 the source-by-source record and the boundary applied to Power, Maximum, and Custom.
 
@@ -387,97 +398,43 @@ Configured paths and disposable filesystem lifecycle tests do not prove that nat
 
 Start at the top and stop whenever Loadout does everything you need.
 
-| Priority | What it does                                                    | Command                                                            |
-| -------: | --------------------------------------------------------------- | ------------------------------------------------------------------ |
-|        1 | Opens the beginner-friendly guided path                         | `loadout guide`                                                    |
-|        2 | Previews the recommended 30-skill daily setup                   | `loadout setup --mode stable`                                      |
-|        3 | Previews the broader Power setup                                | `loadout setup --mode power`                                       |
-|        4 | Downloads the broad screened library, disabled by default       | `loadout setup --mode maximum`                                     |
-|        5 | Shows Loadout-managed packages and active skills                | `loadout status`; `loadout library`                                |
-|        6 | Inventories skills across detected agents without changing them | `loadout scan`                                                     |
-|        7 | Explains what fits the current repository                       | `loadout recommend --project . --agent codex`                      |
-|        8 | Previews a bounded project-specific active set                  | `loadout optimize --project . --limit 30`                          |
-|        9 | Compares existing skills with reviewed catalog copies           | `loadout reconcile --refresh`                                      |
-|       10 | Checks managed active and disabled-library sources for changes  | `loadout update`                                                   |
-|       11 | Finds newly launched or newly popular candidates                | `loadout discover --source all --queue`                            |
-|       12 | Shows candidates waiting for deeper review                      | `loadout review-queue`                                             |
-|       13 | Lists MCP recipes and credential needs                          | `loadout mcp-recipe`; `loadout mcp-recipe --credential-free`       |
-|       14 | Previews an MCP configuration                                   | `loadout mcp-recipe playwright --agent codex`                      |
-|       15 | Lists and installs isolated runtime tools such as Graphify      | `loadout tool`; `loadout tool graphify --agents codex,claude-code` |
-|       16 | Lists snapshots or restores the latest managed change           | `loadout rollback --list`; `loadout rollback`                      |
-|       17 | Previews removal of one managed package                         | `loadout remove <package-id>`                                      |
-|       18 | Previews complete removal of Loadout-managed state              | `loadout uninstall`                                                |
-|       19 | Enables read-only daily discovery and update checks             | `loadout autopilot --yes`                                          |
-|       20 | Shows the complete CLI                                          | `loadout --help`; `loadout advanced`                               |
+| Priority | What it does                                                    | Command                                                      |
+| -------: | --------------------------------------------------------------- | ------------------------------------------------------------ |
+|        1 | Opens the beginner-friendly guided path                         | `loadout guide`                                              |
+|        2 | Previews the recommended 30-skill daily setup                   | `loadout setup --mode stable`                                |
+|        3 | Previews the broader Power setup                                | `loadout setup --mode power`                                 |
+|        4 | Downloads the broad screened library, disabled by default       | `loadout setup --mode maximum`                               |
+|        5 | Shows Loadout-managed packages and active skills                | `loadout status`; `loadout library`                          |
+|        6 | Inventories skills across detected agents without changing them | `loadout scan`                                               |
+|        7 | Explains what fits the current repository                       | `loadout recommend --project .`                              |
+|        8 | Previews a bounded project-specific active set                  | `loadout optimize --project . --limit 30`                    |
+|        9 | Compares existing skills with reviewed catalog copies           | `loadout reconcile --refresh`                                |
+|       10 | Checks managed active and disabled-library sources for changes  | `loadout update`                                             |
+|       11 | Finds newly launched or newly popular candidates                | `loadout discover --source all --queue`                      |
+|       12 | Shows candidates waiting for deeper review                      | `loadout review-queue`                                       |
+|       13 | Lists MCP recipes and credential needs                          | `loadout mcp-recipe`; `loadout mcp-recipe --credential-free` |
+|       14 | Previews an MCP configuration                                   | `loadout mcp-recipe playwright --agent claude-code`          |
+|       15 | Recommends the right model and agent for a task                 | `loadout route design the auth system`                       |
+|       16 | Shows the full model catalog with pricing                       | `loadout route --models`; `loadout route --cost`             |
+|       17 | Sends a task to another agent via file-based handoff            | `loadout handoff send codex "write tests for auth"`          |
+|       18 | Checks agent health, permissions, and setup                     | `loadout doctor`; `loadout doctor --verbose`                 |
+|       19 | Lists and installs isolated runtime tools such as Graphify      | `loadout tool`; `loadout tool graphify`                      |
+|       20 | Lists snapshots or restores the latest managed change           | `loadout rollback --list`; `loadout rollback`                |
+|       21 | Previews removal of one managed package                         | `loadout remove <package-id>`                                |
+|       22 | Previews complete removal of Loadout-managed state              | `loadout uninstall`                                          |
+|       23 | Enables read-only daily discovery and update checks             | `loadout autopilot --yes`                                    |
+|       24 | Shows the complete CLI                                          | `loadout --help`; `loadout advanced`                         |
 
 Most mutating commands are dry runs first. After reading the preview, add `--yes` to
 apply. Commands with executable or connection risk require the additional approval
 shown in their output.
 
-## Built with Codex and GPT-5.6
-
-Loadout was built during OpenAI Build Week by a three-person team working with Codex
-and GPT-5.6. Codex was not a chat box bolted onto the finished project. It was the
-engineering environment we used to plan, build, test, and repeatedly challenge the
-product while it was taking shape.
-
-### From a broad idea to a working product
-
-The starting idea was simple: one install that gives every coding agent the best
-extensions on GitHub. The difficult part was everything hidden inside that sentence.
-What counts as “best”? How much should stay active? What happens to skills a user
-already has? How do you update a repository without silently trusting new code? How
-do you undo changes across several agents?
-
-We used GPT-5.6 through Codex for the repo-wide reasoning behind those decisions.
-Together, we turned the idea into three distinct modes: a bounded Stable daily
-driver, a larger Power setup, and a Maximum library that keeps broad optionality
-without loading thousands of skills into every prompt.
-
-| Part of the build  | How we used Codex and GPT-5.6                                                                                                | What made it into Loadout                                                                                   |
-| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| Product planning   | Broke the original idea into testable user journeys and challenged unsafe assumptions                                        | Stable, Power, Maximum, Custom, project optimization, discovery, updates, and complete uninstall            |
-| Architecture       | Traced how catalogs, adapters, agent directories, manifests, and snapshots affect one another                                | A local TypeScript CLI with a shared catalog, 12 agent adapters, and snapshot-backed transactions           |
-| Ecosystem research | Compared repositories, checked source layouts and licenses, and separated popularity from evidence                           | 53 pinned catalog sources plus a discovery snapshot watching 240 repositories                               |
-| Implementation     | Wrote and refactored CLI commands, schemas, source fetchers, installers, active-set logic, and MCP configuration             | The published `loadout-ai` package and the commands documented above                                        |
-| Safety work        | Looked for scripts, hooks, binaries, credential references, target collisions, stale previews, and external edits            | Preview-first changes, quarantined skill units, explicit risk approval, drift protection, and rollback      |
-| Testing            | Generated adversarial cases, reproduced failures from real terminal sessions, and converted them into regression tests       | 632 passing tests, CLI and README end-to-end flows, package smoke tests, and a 1,000-skill performance gate |
-| Team integration   | Audited teammate branches, compared them with `main`, prepared focused pull requests, and checked what was actually complete | One public history instead of three disconnected prototypes                                                 |
-| Release work       | Verified npm contents, version behavior, GitHub metadata, documentation claims, and public CI                                | A public npm package, credited upstream catalog, release evidence, and a reproducible verification command  |
-
-### Real testing changed the code
-
-Codex was most useful when the neat plan met a messy laptop. A few examples:
-
-- A Graphify install appeared in Claude Code but vanished from Codex inventory
-  because the generated runtime skill and the normal skill scanner used different
-  Codex paths. The scan now recognizes managed runtime-tool skills explicitly.
-- Update checks repeatedly timed out on large repositories. We measured the real
-  clone cost, changed the update path to check remote commit metadata first, and only
-  fetch a full snapshot when a pinned source actually changed.
-- Existing unmanaged skills could occupy the same target as a Stable install.
-  Instead of overwriting them, Loadout now stops, scans, compares, and offers a
-  separate reconciliation path for exact or unambiguous matches.
-- ChatGPT and Claude subscriptions were easy to confuse with separately billed API
-  access. Setup now asks about API access explicitly, while credentialed MCP servers
-  remain separate from automatic skill installation.
-
-Those fixes came from a loop we repeated throughout the week: run the real command,
-paste the exact output into Codex, trace the behavior through the codebase, write a
-regression test, fix the smallest responsible layer, and run the full release gate.
-
-### What the team owned
-
-The humans chose the product direction, selected the tradeoffs, reviewed upstream
-projects, tested Loadout on real Codex and Claude Code profiles, approved risky
-operations, and made every release decision. GPT-5.6 helped with high-context design,
-debugging, and review; Codex handled the implementation loop and verification tools.
-Neither replaced human judgment about what should be installed on someone else's
-machine.
-
-Loadout itself does **not** call GPT-5.6 and does not require an OpenAI API key to
-manage skills. Codex and GPT-5.6 helped build the tool; they are not a hidden runtime
-dependency.
+## Built with Claude
+
+Loadout was designed and built by [Viraj Mishra](https://github.com/VirajMishra1) with Claude Code.
+
+Loadout itself does **not** call any LLM API and does not require an LLM API key
+to manage skills. Claude helped build the tool; it is not a hidden runtime dependency.
 
 ## Development