loadout-ai 0.5.8 → 0.6.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## Unreleased
 
+## 0.5.9 - 2026-07-21
+
+### Fixed
+
+- Preserve active Stable skills when preparing Maximum Library by reserving their
+  managed targets before ordinary overlap deferral, while retaining fail-closed
+  commit, quarantine, and missing-source validation.
+- Run the canonical `npm run verify` release gate on ordinary pushes and pull
+  requests so CI cannot silently omit evidence, README-flow, or package checks.
+
+### Changed
+
+- Use one shared 30-skill recommended active-set limit in planning, inventory,
+  upgrade guidance, CLI defaults, and public workflow documentation.
+- Clearly archive superseded dashboard-era release notes and keep the public launch
+  checklist aligned with completed demo work and the current CLI-only product.
+
 ## 0.5.8 - 2026-07-21
 
 ### Fixed

package/MASTER_PLAN.md

@@ -13,7 +13,7 @@ history** is evidence of how the product was built, not unfinished launch scope.
 
 ### Product complete
 
-- [x] Publish the CLI as `loadout-ai@0.5.8`; keep the product usable without cloning
+- [x] Publish the CLI as `loadout-ai`; keep the product usable without cloning
       this repository or providing an OpenAI/Anthropic API key.
 - [x] Ship Stable, Power, Maximum, and Custom profiles with preview-first apply,
       snapshots, drift protection, explicit rollback, removal, and complete uninstall.
@@ -46,10 +46,10 @@ history** is evidence of how the product was built, not unfinished launch scope.
 
 ### Submission work
 
-- [ ] Record the real CLI demo using `docs/DEMO_SCRIPT.md`; keep it under three
+- [x] Record the real CLI demo using `docs/DEMO_SCRIPT.md`; keep it under three
       minutes, include a voiceover, upload it publicly to YouTube, and verify the URL.
-- [ ] Replace the README demo placeholder with the final YouTube link.
-- [ ] In the voiceover, explain what Loadout does and how Codex and GPT-5.6 were used.
+- [x] Replace the README demo placeholder with the final YouTube link.
+- [x] In the voiceover, explain what Loadout does and how Codex and GPT-5.6 were used.
 - [ ] Run `/feedback` in Codex, copy the resulting session ID, and enter it in Devpost.
 - [x] Confirm the public repository URL is accessible to Devpost and OpenAI.
 - [x] Confirm all team invitations are accepted. Both teammates are collaborators and
@@ -72,12 +72,12 @@ These are not launch blockers and should not be rebuilt before submission:
 - Restoring GitHub-hosted Actions capacity before submission; the full gate can run
   locally, and the latest completed `main` CI is already passing.
 
-## Archived current-status diary (historical, not active scope)
+## Archived implementation diary (historical, not active scope)
 
-This section preserves the chronological implementation and founder-testing record.
-Its unchecked boxes may describe older release numbers, superseded acceptance paths,
-external research, or intentionally deferred work. They are not active launch tasks;
-use the launch finish line above.
+Everything below this heading is a frozen chronological implementation record. Its
+dashboard references, old release numbers, unchecked boxes, and superseded acceptance
+paths describe earlier product states; they are neither current capabilities nor
+active launch tasks. Use only the launch finish line above for current status.
 
 ### Implemented product work
 

package/README.md

@@ -34,7 +34,7 @@
 You need Node.js 20 or newer and Git.
 
 ```bash
-npm install --global loadout-ai@0.5.8
+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,19 +120,25 @@ 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
 
-**Demo video coming here.** The release walkthrough will show the real path, not a
-mock UI: Stable install, cross-agent inventory, project optimization, update and
-discovery checks, MCP setup, Graphify, rollback, and complete uninstall. The exact
-under-three-minute [recording and voiceover script](./docs/DEMO_SCRIPT.md) is public.
+<p align="center">
+  <a href="https://www.youtube.com/watch?v=opNqJKX7xMw">
+    <img src="https://img.youtube.com/vi/opNqJKX7xMw/maxresdefault.jpg" alt="Watch the 72-second Loadout demo" width="880">
+  </a>
+</p>
+
+**[Watch the 72-second Loadout demo on YouTube](https://www.youtube.com/watch?v=opNqJKX7xMw).**
+It shows the real CLI product, including profiles, project-aware selection,
+discovery, explicit integrations, and snapshot-backed rollback. The exact
+[recording and voiceover script](./docs/DEMO_SCRIPT.md) is public.
 
-For now, the [end-to-end acceptance guide](./docs/USER_TEST_GUIDE.md) contains the same
-commands you can run yourself.
+The [end-to-end acceptance guide](./docs/USER_TEST_GUIDE.md) contains the commands
+you can run yourself.
 
 ## Stable workflow
 
@@ -212,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.”
@@ -236,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
@@ -260,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
@@ -276,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.
@@ -324,7 +341,7 @@ The bundled catalog currently contains **53 credited public repositories** acros
 
 <!-- loadout:evidence-stages:start -->
 
-Catalog maturity: **53 sourced**, **53 technically inspected**, and **4 selected for Stable**. Independent human-review attestations and signed comparative benchmarks are not yet published, so Loadout does not pretend static inspection proves usefulness. The pinned catalog remains usable today, and local outcomes can be recorded to improve later rankings. Definitions and promotion rules are in the [catalog policy](./docs/CATALOG_POLICY.md).
+Catalog maturity: **53 sourced**, **53 technically inspected**, and **4 selected for Stable**. Independent human-review attestations are not yet published, so Loadout does not pretend static inspection proves usefulness. The pinned catalog remains usable today, and local outcomes can be recorded to improve later rankings. Definitions and promotion rules are in the [catalog policy](./docs/CATALOG_POLICY.md).
 
 <!-- loadout:evidence-stages:end -->
 
@@ -332,7 +349,7 @@ Loadout does not claim there is one universally “best” configuration. Recomm
 
 <!-- loadout:daily-discovery:start -->
 
-**Discovery snapshot (generated 2026-07-21):** [240 repositories observed](./docs/DISCOVERED.md), including 216 uncataloged review candidates and 24 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.
@@ -341,7 +358,7 @@ The checked-in discovery report proves only its dated snapshot, not the success
 
 - A pinned commit identifies source bytes; it does not prove safety, correct licensing, usefulness, or future compatibility.
 - Static inspection reports scripts, hooks, binaries, domains, credential references, and unsupported components. It is not a security audit.
-- No bundled source is called benchmarked until isolated real trials, signed evidence, and human approval exist.
+- No bundled source is called proven until human review and recorded local outcomes support it; static inspection alone never earns that label.
 - Project recommendations read bounded local metadata. The documented local flow does not upload project source.
 - Catalog fetches, discovery, update checks, and optional live checks use the network where stated.
 - MCP servers and executable tools have separate preview and approval paths because they can use credentials, start processes, or contact services.
@@ -349,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.
 
@@ -381,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       | 625 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