loadout-ai 0.4.1 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/CHANGELOG.md +55 -0
  2. package/MASTER_PLAN.md +113 -33
  3. package/README.md +57 -19
  4. package/catalog/discovered.json +8422 -6957
  5. package/catalog/packages.json +26 -0
  6. package/dist/src/cli.js +140 -68
  7. package/dist/src/core/active-policy.js +48 -8
  8. package/dist/src/core/active-set.js +1 -1
  9. package/dist/src/core/adopt.js +1 -1
  10. package/dist/src/core/catalog-coverage.js +2 -1
  11. package/dist/src/core/catalog-install.js +23 -8
  12. package/dist/src/core/cli-guide.js +5 -2
  13. package/dist/src/core/codex-mcp.js +49 -5
  14. package/dist/src/core/completion.js +0 -3
  15. package/dist/src/core/health.js +28 -12
  16. package/dist/src/core/install.js +3 -3
  17. package/dist/src/core/mcp-recipes.js +13 -4
  18. package/dist/src/core/mcp.js +6 -5
  19. package/dist/src/core/model-config.js +1 -1
  20. package/dist/src/core/portable.js +1 -1
  21. package/dist/src/core/recommend.js +34 -18
  22. package/dist/src/core/remove.js +33 -5
  23. package/dist/src/core/runtime-tool-recipe.js +2 -2
  24. package/dist/src/core/runtime-tools.js +15 -4
  25. package/dist/src/core/snapshot.js +20 -0
  26. package/dist/src/core/state.js +9 -0
  27. package/dist/src/core/sync.js +1 -1
  28. package/dist/src/core/transaction.js +2 -1
  29. package/dist/src/core/uninstall.js +11 -1
  30. package/dist/src/shared/schemas.js +1 -0
  31. package/docs/CATALOG.md +3 -2
  32. package/docs/DISCOVERED.md +253 -255
  33. package/docs/FEATURE_TEST_MATRIX.md +19 -32
  34. package/docs/GITHUB_AUTHORIZATION.md +2 -2
  35. package/docs/TESTING.md +3 -16
  36. package/docs/USER_TEST_GUIDE.md +23 -9
  37. package/docs/assets/loadout-workflow.png +0 -0
  38. package/docs/evidence/readme-claims.json +0 -8
  39. package/docs/superpowers/plans/2026-07-20-loadout-readme-explainer.md +116 -0
  40. package/docs/superpowers/specs/2026-07-20-loadout-readme-explainer-design.md +55 -0
  41. package/package.json +4 -6
  42. package/dashboard/app.js +0 -607
  43. package/dashboard/index.html +0 -249
  44. package/dashboard/styles.css +0 -384
  45. package/dist/src/core/demo.js +0 -136
  46. package/dist/src/dashboard.js +0 -421
package/CHANGELOG.md CHANGED
@@ -1,5 +1,60 @@
1
1
  # Changelog
2
2
 
3
+ ## Unreleased
4
+
5
+ ## 0.5.1 - 2026-07-21
6
+
7
+ ### Fixed
8
+
9
+ - Remove disabled Maximum-library copies during package removal and complete
10
+ uninstall without inspecting or deleting unrelated skills that later occupy the
11
+ original agent path.
12
+ - Describe a disabled-only Maximum library as ready with nothing active, including
13
+ explicit active and disabled skill counts, instead of calling it a healthy active
14
+ installation.
15
+ - Name modified managed paths in blocked complete-uninstall previews so users can
16
+ review real drift before deciding whether to force removal.
17
+
18
+ ## 0.5.0 - 2026-07-21
19
+
20
+ ### Added
21
+
22
+ - Add the pinned MIT-licensed Obsidian Skills collection and recommend it only when an
23
+ Obsidian vault is detected.
24
+ - Add host-aware reviewed MCP setup, verification, health, rollback, and removal for
25
+ Codex and Claude Code.
26
+
27
+ ### Changed
28
+
29
+ - Remove the dashboard and disposable demo commands so the CLI is the single
30
+ authoritative product surface.
31
+ - Define Stable as the bounded 30-skill default, Power as the intentionally larger
32
+ active toolkit, and Maximum as the broad disabled library with project activation.
33
+ - Group Maximum quarantine, deferral, and risk output by default; retain every unit
34
+ under `setup --details`.
35
+ - Refresh the dated GitHub discovery feed locally and present sourced, inspected,
36
+ Stable-selected, and future evidence stages without the misleading `0 discovered`
37
+ headline.
38
+ - Gate project-aware activation by detected language, framework, provider, and
39
+ project role before scoring generic CLI, MCP, package, publish, or schema words.
40
+ - Keep explicit skill pins as a deliberate override while treating the active-set
41
+ limit as a ceiling rather than filling it with ecosystem-mismatched candidates.
42
+
43
+ ### Fixed
44
+
45
+ - Clean compiled output before every build and reject removed dashboard/demo files
46
+ from the packed artifact, preventing stale JavaScript from leaking into npm.
47
+ - Add human-readable rollback history with timestamps, mutation labels, affected
48
+ roots, effective change counts, and explicit no-op guidance.
49
+ - Report an empty managed installation as `not configured` rather than healthy.
50
+ - Configure reviewed MCP recipes directly for Codex TOML or Claude Code JSON, track
51
+ their fingerprints, include ownership state in the same rollback transaction, and
52
+ remove only the managed server entry.
53
+ - Prevent substring matches such as `npm` inside `pnpm` and arbitrary `*-cli`
54
+ names from receiving unrelated Node CLI or Commander relevance scores.
55
+ - Stop non-.NET, non-Python, non-Elixir, non-frontend, and non-backend projects
56
+ from automatically activating domain-specific guidance for those ecosystems.
57
+
3
58
  ## 0.4.1 - 2026-07-20
4
59
 
5
60
  ### Added
package/MASTER_PLAN.md CHANGED
@@ -6,7 +6,7 @@ Category: Developer Tools
6
6
  Team size: 3
7
7
  Target submission: July 21, 2026 at 5:00 PM Pacific / July 22 at 4:00 AM Dubai
8
8
 
9
- ## Current status and remaining work (July 20, 2026)
9
+ ## Current status and remaining work (July 21, 2026)
10
10
 
11
11
  This is the authoritative active list. The long phase history below is retained as
12
12
  an archival engineering record, not a second active plan and not a command to build
@@ -116,20 +116,23 @@ merged `codex/relatable-readme-hero` remote branch remains safe to delete after
116
116
  founder's real Claude Code and Codex paths. Stable installed four pinned sources
117
117
  as 60 managed activations, preserved all 12 unmanaged Claude skills, reported no
118
118
  managed drift, and restored the explicit pre-install snapshot successfully.
119
- - [ ] `P18-21B [TERRA]` Make rollback history understandable before 0.4.1. The first
119
+ - [x] `P18-21B [TERRA]` Make rollback history understandable. The first
120
120
  founder test exposed that bare `loadout rollback` selected a newer no-op
121
121
  dashboard/sync snapshot whose pre-state already contained Stable. No data was
122
122
  lost, but `rollback --list` showed opaque IDs only and `Restored snapshot` did
123
- not disclose that zero effective files changed. Add timestamp, mutation kind,
124
- affected scope, and no-op/current-state guidance; add a regression journey with
125
- two adjacent snapshots and explicit older-snapshot rollback.
126
- - [ ] `P18-22 [TERRA]` Remove the dashboard before the public release. Founder review
123
+ not disclose that zero effective files changed. Rollback history now displays
124
+ timestamp, mutation label, affected roots, effective entry count, latest marker,
125
+ and explicit no-op guidance. New mutations carry user-facing labels. A CLI
126
+ regression journey proves adjacent no-op and install snapshots plus explicit
127
+ older-snapshot restoration.
128
+ - [x] `P18-22 [TERRA]` Remove the dashboard before the public release. Founder review
127
129
  confirmed that it presents recommendation presets (`stable`, `web`,
128
130
  `collaboration`, `maximum`) as policy profiles while the real CLI contract is
129
131
  `stable`, `power`, `maximum`, and `custom`; its manifest-sync mutation model is
130
132
  not the CLI setup workflow. Remove the command, loopback server, browser assets,
131
133
  dashboard-only dependencies/tests/docs/evidence, and npm package contents.
132
- Preserve any unique useful inspection capability through existing CLI commands.
134
+ The CLI retains all useful inspection, recommendation, configuration, health,
135
+ rollback, and uninstall capabilities; there is no competing dashboard workflow.
133
136
  - [ ] `P18-23 [HUMAN+TERRA]` Complete the remaining CLI-only founder path on the exact
134
137
  npm package. Power and its explicit rollback are complete: snapshot
135
138
  `1784546929191-9cfb0705dbed` restored zero Loadout-managed activations, retained
@@ -141,7 +144,8 @@ merged `codex/relatable-readme-hero` remote branch remains safe to delete after
141
144
  optimization -> Graphify install/remove -> credential-free MCP inventory ->
142
145
  read-only update/discovery -> complete uninstall -> reinstall. Record every
143
146
  mutation snapshot ID and use explicit rollback IDs during acceptance.
144
- - [ ] `P18-24 [SOL+TERRA]` Redesign Power before 0.4.1 based on the real founder run.
147
+ - [x] `P18-24 [SOL+TERRA]` Make Power match the intended product hierarchy based on
148
+ the real founder run.
145
149
  The published transaction itself passed: eight immutable sources installed for
146
150
  Claude Code and Codex, 100 managed activations were created, 12 unmanaged Claude
147
151
  skills were preserved, duplicate targets were resolved, six rejected skill
@@ -149,35 +153,32 @@ merged `codex/relatable-readme-hero` remote branch remains safe to delete after
149
153
  policy failed acceptance: it activates 50 skills per agent despite Loadout's
150
154
  recommended limit of 30; every selected package retained blocking static-risk
151
155
  findings (79 total); only five of eight sources have an asserted SPDX license;
152
- and one coarse prompt approves all package findings. Make Power a broad managed
153
- library with no more than 30 project-relevant skills active per agent, preserve
154
- per-package approval and rejection choices, persist and display excluded-unit
155
- quarantine evidence, and make the health headline reflect blocking risk and
156
- capacity failures instead of reporting the overall installation as healthy.
157
- Add a release test proving Power preserves unmanaged skills, never exceeds its
158
- active cap, reports every excluded unit and retained finding, and restores its
159
- explicit setup snapshot without residue. The founder's published-package run
160
- has now demonstrated that final rollback property successfully.
161
- - [ ] `P18-25 [LUNA+TERRA]` Make health output honest and focused for empty or unmanaged
156
+ and one coarse prompt approves all package findings. The founder clarified that
157
+ Power is intentionally the larger active mode, not another 30-skill Stable.
158
+ Stable remains bounded at 30; Power explicitly warns about its larger context
159
+ footprint; Maximum stores the broadest screened library disabled and activates
160
+ only project-relevant subsets. Invalid units remain quarantined and detailed
161
+ findings stay available behind `--details`. Existing transaction and founder
162
+ evidence proves unmanaged-skill preservation and exact rollback.
163
+ - [x] `P18-25 [LUNA+TERRA]` Make health output honest and focused for empty or unmanaged
162
164
  profiles. After the successful Power rollback, `loadout health --explain` led
163
165
  with `Loadout health: healthy` and then reported 28/100 critical evidence for
164
166
  Claude Code, 0/100 unknown for Codex, and similarly verbose sections for every
165
- detected agent. Use an explicit `not configured`/`no managed packages` overall
166
- state instead of healthy, keep the default summary concise, and let users scope
167
- detailed evidence to selected agents while preserving the full explanation on
168
- request. Add empty-state and mixed detected-agent CLI regression tests.
169
- - [ ] `P18-26 [LUNA+TERRA]` Make Maximum's preview understandable without weakening
167
+ detected agent. Empty managed state now reports `not configured`, the default
168
+ remains concise, and `--explain --agents <ids>` keeps deeper evidence scoped.
169
+ Health also understands managed Codex TOML MCP entries instead of falsely
170
+ reporting JSON drift.
171
+ - [x] `P18-26 [LUNA+TERRA]` Make Maximum's preview understandable without weakening
170
172
  its safe defaults. The founder run proved the disabled-library contract, but
171
173
  printed 50 unit-level quarantine blocks, 19 expected MCP/runtime deferrals, two
172
174
  `No SKILL.md` preparation failures, and one coarse 28-package risk approval in
173
175
  the default path. The subsequent scan reported 11 repository failures without
174
176
  naming them. Default to a concise grouped summary with exact counts, severity,
175
177
  source, and next commands; retain complete findings behind an explicit details
176
- or JSON view. Classify no-skill MCP/runtime records as explicit setup rather
177
- than failed skill preparation, distinguish high-confidence findings from likely
178
- documentation/binary/metadata false positives, persist every excluded unit, and
179
- name every failed repository with a short reason. Add snapshot tests for both
180
- concise and detailed Maximum output.
178
+ or JSON view. MCP/runtime-only records are explicit deferred setup rather than
179
+ failed skill preparation; actual repository preparation failures remain named
180
+ with their reason. The default preview groups quarantine and deferral counts,
181
+ while `--details` shows every unit. Regression tests cover both views.
181
182
  - [x] `P18-27 [SOL+TERRA, LUNA copy review]` Correct project-aware activation safety
182
183
  and relevance using
183
184
  `docs/superpowers/specs/2026-07-20-project-activation-safety-design.md`.
@@ -197,6 +198,85 @@ merged `codex/relatable-readme-hero` remote branch remains safe to delete after
197
198
  runs. Do
198
199
  not resume real-profile activation until this branch is reviewed, integrated,
199
200
  versioned, and published as the corrected release.
201
+ - [x] `P18-28 [HUMAN+TERRA]` Merge the project-activation corrections through PR #4
202
+ and publish the exact verified release as `loadout-ai@0.4.1`. Registry
203
+ verification returned version `0.4.1` and integrity
204
+ `sha512-k8WTNh6kTIaaBFTPGsl/QD/7/LQ1Gg9uMReM87gAkBPdcG0IxanM9NznyjemsYa124yYPczAY5MVYan4i91MtA==`;
205
+ a clean temporary global install reported `0.4.1` and detected TypeScript,
206
+ Playwright, Node CLI, npm package, release, MCP, security, Commander, Zod, and
207
+ Vitest signals from this repository. Tag `v0.4.1` points to release commit
208
+ `0d25b8e`. This is the corrected founder-testing release, not the final public
209
+ launch candidate: dashboard removal, Power policy, health output, and Maximum
210
+ preview work remain open.
211
+ - [x] `P18-29 [SOL+TERRA]` Block ecosystem-mismatched project activation candidates
212
+ before scoring. The exact published `0.4.1` founder preview correctly detected
213
+ this TypeScript Node CLI, respected both agents' real capacity, and produced no
214
+ false occupied-target blockers, but still proposed `mcp-csharp-publish`,
215
+ `mcp-csharp-test`, `uv-package-manager`, `social-publishing`, and
216
+ `vercel-cli-with-tokens`, then exposed `msstore-cli`, `phoenix-cli`, and
217
+ `publish-to-pages` once those higher-ranked mismatches were removed. A second
218
+ preview exposed the general cause: any domain-specific name ending in `-cli`,
219
+ including `datadog-cli`, inherited the full Node CLI and Commander score; a
220
+ third exposed substring matching of `npm` inside `pnpm`, plus backend and web
221
+ design guidance without corresponding project roles; a fourth caught generic
222
+ `schema` admitting database design for Zod and universal accessibility guidance
223
+ in a CLI project. Add deterministic language/provider/specialization
224
+ compatibility gates, bounded generic CLI and schema evidence, token-aware
225
+ package-manager matching, and role-gated backend/frontend guidance. Generic
226
+ `mcp`, `cli`, `package`, and `publish` words must not override compatibility;
227
+ preserve explicit pins as a deliberate escape hatch; prove the exact regression
228
+ with tests and repeat the read-only founder preview before any real activation.
229
+ Complete on `codex/activation-compatibility-gates`: the exact live Maximum
230
+ library preview now proposes 24 relevant Codex skills and 18 capacity-bounded
231
+ Claude Code skills with zero occupied-target blockers and none of the observed
232
+ ecosystem mismatches. The full release gate passes with 114 test files, 607
233
+ passing tests, one intentional skip, both CLI product journeys, packaged CLI
234
+ smoke, evidence checks, and a 1,518.4 ms p95 scan benchmark across seven real
235
+ runs. The preview remained read-only; publish the merged correction before the
236
+ founder applies it to real agent profiles.
237
+
238
+ ### Product-first release candidate work
239
+
240
+ - [x] `P18-30 [TERRA]` Add `kepano/obsidian-skills` at an immutable MIT-licensed
241
+ revision as the 51st credited catalog source. Detect `.obsidian` vaults and
242
+ recommend/activate the five Obsidian-oriented skills only for relevant projects;
243
+ do not burden universal Stable with a niche tool.
244
+ - [x] `P18-31 [TERRA]` Make reviewed MCP recipes usable from the normal CLI for both
245
+ Codex and Claude Code. `mcp-recipe --agent <host>` now chooses the real host
246
+ config path and format, previews before writing, stores managed fingerprints,
247
+ verifies presence, reports drift in health, and removes only Loadout's entry.
248
+ Config plus ownership state commit in one rollback transaction, so rollback
249
+ cannot leave a stale managed MCP record. Disposable end-to-end tests cover
250
+ preview, apply, verify, health, rollback, reapply, and removal.
251
+ - [x] `P18-32 [TERRA]` Present evidence maturity without the misleading exclusive
252
+ `0 discovered` headline. The README now reports 51 sourced/inspected records,
253
+ four Stable sources, and the dated discovery feed separately. It clearly says
254
+ independent human-review and comparative benchmark publications are future
255
+ promotion stages rather than implying the catalog is unusable.
256
+ - [ ] `P18-33 [HUMAN+TERRA]` Publish the next verified CLI-only release and run the
257
+ founder path from that exact npm tarball: Stable, Power, Maximum/project
258
+ activation, Obsidian recommendation, Graphify, both-host credential-free MCP,
259
+ read-only update/discovery, rollback history, uninstall, and clean reinstall.
260
+ - [ ] `P18-34 [HUMAN]` Resolve or bypass exhausted GitHub-hosted Actions minutes by
261
+ running the documented complete gate locally now; later restore hosted CI with
262
+ billing/minutes, a self-hosted runner, or a teammate-owned fork. Never label an
263
+ unstarted hosted job as a code failure.
264
+ - [x] `P18-35 [TERRA]` Run the complete CLI-only release gate locally after all
265
+ product-first changes against the exact `0.5.0` package. On July 21 it passed formatting, lint, type checking,
266
+ catalog/discovery/README/release evidence, 113 test files with 603 passing and
267
+ one intentional skip, both CLI product journeys, packed npm smoke, and seven
268
+ real 1,000-skill scans at 1,468.2 ms p95.
269
+ - [x] `P18-36 [TERRA]` Close the stale-build packaging gap caught by the first npm
270
+ publish attempt. Every build now removes `dist` first on every platform, and the
271
+ package smoke test rejects removed dashboard/demo JavaScript if it ever leaks
272
+ back into the tarball. The failed OTP-gated attempt published nothing.
273
+ - [x] `P18-37 [TERRA]` Fix the founder-discovered disabled-library uninstall bug.
274
+ Removal now resolves each managed file to its disabled Maximum-library copy,
275
+ never an unmanaged skill that later occupies the original active path. A
276
+ regression test preserves the replacement bytes, the real founder state now
277
+ previews an unblocked removal of 29 packages/2,316 disabled records, and health
278
+ reports `library ready (nothing active)` with explicit counts. Release as
279
+ `0.5.1` before continuing the complete-uninstall acceptance step.
200
280
 
201
281
  ### Release 0.3 lifecycle hardening
202
282
 
@@ -1929,7 +2009,7 @@ The MVP is done only when a judge can:
1929
2009
  - Dashboard first-run flow.
1930
2010
  - Windows, macOS, Linux CI.
1931
2011
 
1932
- ## 22. Demo script
2012
+ ## 22. Recorded product walkthrough
1933
2013
 
1934
2014
  1. Show Claude, Codex, and Cursor with inconsistent/manual setup.
1935
2015
  2. Run `npx loadout-ai` after npm publication, or `npx .` from the cloned repository.
@@ -1955,7 +2035,7 @@ Mitigation: full skill support for six; MCP only for three; mark unsupported hon
1955
2035
  ### Corrupting user configuration
1956
2036
 
1957
2037
  Mitigation: plan-only adapters, snapshots, staging, validation, automatic restore,
1958
- fixture-based tests, demo mode isolated from the real home directory.
2038
+ fixture-based tests, and disposable test homes isolated from the real profile.
1959
2039
 
1960
2040
  ### Supply-chain risk
1961
2041
 
@@ -1968,10 +2048,10 @@ Mitigation: lead with one-command diagnosis of what the user already has, honest
1968
2048
  provenance, evidence-backed comparison, reviewed-library versus active-set separation,
1969
2049
  project optimization, automatic discovery tiers, update explanation, and rollback.
1970
2050
 
1971
- ### Dashboard consumes too much time
2051
+ ### Competing frontend and CLI behavior
1972
2052
 
1973
- Mitigation: stop feature investment in the dashboard for the hackathon. The CLI is the
1974
- only required surface; the existing dashboard remains optional diagnostics.
2053
+ Mitigation: keep one authoritative CLI product surface. The superseded dashboard and
2054
+ its separate profile/mutation model were removed before the public release candidate.
1975
2055
 
1976
2056
  ### GitHub API rate limits
1977
2057
 
package/README.md CHANGED
@@ -1,5 +1,5 @@
1
1
  <p align="center">
2
- <img src="./docs/assets/loadout-hero.svg" alt="A developer arranging extensions from a messy, unmanaged group into organized loadout slots" width="960">
2
+ <img src="./docs/assets/loadout-workflow.png" alt="Loadout workflow: choose extensions, inspect sources, preview changes, apply through a managed snapshot, and undo safely across supported AI coding agents." width="960">
3
3
  </p>
4
4
 
5
5
  <h1 align="center">Loadout</h1>
@@ -26,7 +26,7 @@
26
26
  </p>
27
27
 
28
28
  > [!IMPORTANT]
29
- > Installation is version-pinned so the code you test matches these docs. The commands below target `loadout-ai@0.4.1`; review the preview before every apply.
29
+ > Installation is version-pinned so the code you test matches these docs. The commands below target `loadout-ai@0.5.1`; review the preview before every apply.
30
30
 
31
31
  ## How it works
32
32
 
@@ -76,7 +76,7 @@ Skills, plugins, MCP servers, and agent settings tend to accumulate one experime
76
76
  You need Node.js 20 or newer and Git.
77
77
 
78
78
  ```bash
79
- npm install --global loadout-ai@0.4.1
79
+ npm install --global loadout-ai@0.5.1
80
80
  loadout --version
81
81
  loadout guide
82
82
  ```
@@ -92,13 +92,13 @@ npm link
92
92
  loadout --version
93
93
  ```
94
94
 
95
- For a disposable first success, run:
95
+ For a first read-only preview, run:
96
96
 
97
97
  ```bash
98
- loadout demo
98
+ loadout setup --mode stable
99
99
  ```
100
100
 
101
- The demo uses temporary state and cleans it up; it does not write to your normal agent configuration. See the [user test guide](./docs/USER_TEST_GUIDE.md) if linking, `PATH`, networking, risk approval, or rollback needs attention.
101
+ Nothing is installed until you explicitly approve the preview. See the [user test guide](./docs/USER_TEST_GUIDE.md) if linking, `PATH`, networking, risk approval, or rollback needs attention.
102
102
 
103
103
  ## Stable workflow
104
104
 
@@ -119,26 +119,64 @@ Stable currently selects 30 skill directories from four pinned, SPDX-identified,
119
119
 
120
120
  ## Profiles
121
121
 
122
- | Profile | Scope |
123
- | ----------- | ---------------------------------------------------------------------- |
124
- | **Stable** | Bounded default: 30 skills from four policy-selected sources |
125
- | **Power** | Broader cross-project set from eight checked-in collections |
126
- | **Maximum** | Valid skill-bearing contents in a managed, disabled-by-default library |
127
- | **Custom** | Only package IDs explicitly supplied by the user |
122
+ | Profile | Scope |
123
+ | ----------- | --------------------------------------------------------------------- |
124
+ | **Stable** | 30 active everyday skills from four pinned sources |
125
+ | **Power** | A deliberately larger active toolkit from eight pinned collections |
126
+ | **Maximum** | Every screened skill in a disabled library; activate relevant subsets |
127
+ | **Custom** | Only package IDs explicitly supplied by the user |
128
+
129
+ Run `loadout profiles` to compare them and `loadout setup --mode <profile>` to preview one. Stable limits context. Power trades more context for broader always-available capability. Maximum gives you the largest library without injecting thousands of skills into every prompt; `loadout optimize --project .` chooses a relevant working set. MCP-only entries stay on a separate approval path.
130
+
131
+ ## MCP integrations
132
+
133
+ MCP servers are not silently started by Stable, Power, or Maximum. List the reviewed recipes and their credential requirements:
134
+
135
+ ```bash
136
+ loadout mcp-recipe
137
+ loadout mcp-recipe --credential-free
138
+ ```
139
+
140
+ Preview and configure one for the host you use:
141
+
142
+ ```bash
143
+ loadout mcp-recipe playwright --agent codex
144
+ loadout mcp-recipe playwright --agent codex --yes
145
+ loadout mcp-recipe playwright --agent codex --verify
146
+
147
+ loadout mcp-recipe playwright --agent claude-code
148
+ loadout mcp-recipe playwright --agent claude-code --yes
149
+ ```
150
+
151
+ Configuration does not launch the server. A real bounded handshake requires the separate `--connect --approve-risk` action. Credentialed recipes accept environment or keychain references, never secret values in command output.
152
+
153
+ ## Optional runtime tools
154
+
155
+ [Graphify](https://github.com/Graphify-Labs/graphify) is available as a separate,
156
+ reviewed local runtime recipe because it installs an executable as well as an agent
157
+ skill. It does not need an OpenAI or Anthropic API key. Loadout previews the pinned
158
+ artifact, permissions, targets, and rollback scope before doing anything:
159
+
160
+ ```bash
161
+ loadout tool graphify --agents codex,claude-code
162
+ loadout tool graphify --agents codex,claude-code --yes --approve-risk
163
+ loadout tool graphify --remove --agents codex,claude-code --yes --approve-risk
164
+ ```
128
165
 
129
- Preview choices with `loadout profiles` and `loadout setup --mode <profile>`. Maximum counts are computed from pinned contents after validation and duplicate resolution; MCP-only entries stay on a separate approval path.
166
+ Graphify is intentionally not hidden inside Stable, Power, or Maximum: executable
167
+ tools always remain an explicit choice.
130
168
 
131
169
  ## Catalog and discovery
132
170
 
133
171
  <!-- loadout:catalog-coverage:start -->
134
172
 
135
- The bundled catalog currently contains **50 credited public repositories** across **37 categories**: **31 have skill components** and **19 are MCP-only**. All 50 are technically screened and pinned; 4 sources are selected by the bounded Stable policy. See every linked source, license status, component type, and pinned commit in **[Catalog and upstream credits](./docs/CATALOG.md)**.
173
+ The bundled catalog currently contains **51 credited public repositories** across **38 categories**: **32 have skill components** and **19 are MCP-only**. All 51 are technically screened and pinned; 4 sources are selected by the bounded Stable policy. See every linked source, license status, component type, and pinned commit in **[Catalog and upstream credits](./docs/CATALOG.md)**.
136
174
 
137
175
  <!-- loadout:catalog-coverage:end -->
138
176
 
139
177
  <!-- loadout:evidence-stages:start -->
140
178
 
141
- Catalog evidence-stage counts: **0 benchmarked**, **0 discovered**, **0 human-reviewed**, **46 inspected**, **4 policy-selected**. Stage definitions and Stable selection criteria are in the [catalog policy](./docs/CATALOG_POLICY.md).
179
+ Catalog maturity: **51 sourced**, **51 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).
142
180
 
143
181
  <!-- loadout:evidence-stages:end -->
144
182
 
@@ -146,7 +184,7 @@ Loadout does not claim there is one universally “best” configuration. Recomm
146
184
 
147
185
  <!-- loadout:daily-discovery:start -->
148
186
 
149
- **Discovery snapshot (generated 2026-07-17):** [242 repositories observed](./docs/DISCOVERED.md), including 219 uncataloged review candidates and 23 repositories already in the inspected catalog.
187
+ **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.
150
188
  <!-- loadout:daily-discovery:end -->
151
189
 
152
190
  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.
@@ -200,7 +238,7 @@ Configured paths and disposable filesystem lifecycle tests do not prove that nat
200
238
  | Undo the latest supported mutation | `loadout rollback` |
201
239
  | Remove one managed package | `loadout remove <package>` |
202
240
  | Preview complete removal | `loadout uninstall` |
203
- | Test with temporary state | `loadout demo` |
241
+ | List reviewed MCP integrations | `loadout mcp-recipe` |
204
242
  | Discover the full surface | `loadout --help`; `loadout advanced` |
205
243
 
206
244
  ## Development
@@ -213,7 +251,7 @@ npm run verify:full
213
251
 
214
252
  <!-- loadout:verification-summary:start -->
215
253
 
216
- `verify` invokes `format:check`, `lint`, `typecheck`, `check:evidence`, `test`, `test:e2e:cli`, `test:e2e:readme`, `test:package`, `test:performance` in that order. Use `npm run verify:full` to include the optional Playwright dashboard check.
254
+ `verify` invokes `format:check`, `lint`, `typecheck`, `check:evidence`, `test`, `test:e2e:cli`, `test:e2e:readme`, `test:package`, `test:performance` in that order. `npm run verify:full` is an alias for the same complete CLI release gate.
217
255
 
218
256
  <!-- loadout:verification-summary:end -->
219
257
 
@@ -236,7 +274,7 @@ The repository's mixed README product-flow test uses an isolated build, disposab
236
274
 
237
275
  Keep changes scoped, add regression coverage for behavior changes, and run `npm run verify:full`. Report vulnerabilities through [SECURITY.md](./SECURITY.md), without credentials, private source, or unredacted state. General bugs and proposals belong in the [issue tracker](https://github.com/VirajMishra1/loadout/issues).
238
276
 
239
- The catalog contains 50 credited public repositories. Inclusion records discovery and attribution; it does not transfer ownership, imply endorsement, or relicense upstream work.
277
+ The catalog contains 51 credited public repositories. Inclusion records discovery and attribution; it does not transfer ownership, imply endorsement, or relicense upstream work.
240
278
 
241
279
  ## License
242
280