loadout-ai 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## Unreleased
+
+### Added
+
+- Add the pinned MIT-licensed Obsidian Skills collection and recommend it only when an
+  Obsidian vault is detected.
+- Add host-aware reviewed MCP setup, verification, health, rollback, and removal for
+  Codex and Claude Code.
+
+### Changed
+
+- Remove the dashboard and disposable demo commands so the CLI is the single
+  authoritative product surface.
+- Define Stable as the bounded 30-skill default, Power as the intentionally larger
+  active toolkit, and Maximum as the broad disabled library with project activation.
+- Group Maximum quarantine, deferral, and risk output by default; retain every unit
+  under `setup --details`.
+- Refresh the dated GitHub discovery feed locally and present sourced, inspected,
+  Stable-selected, and future evidence stages without the misleading `0 discovered`
+  headline.
+- Gate project-aware activation by detected language, framework, provider, and
+  project role before scoring generic CLI, MCP, package, publish, or schema words.
+- Keep explicit skill pins as a deliberate override while treating the active-set
+  limit as a ceiling rather than filling it with ecosystem-mismatched candidates.
+
+### Fixed
+
+- Clean compiled output before every build and reject removed dashboard/demo files
+  from the packed artifact, preventing stale JavaScript from leaking into npm.
+- Add human-readable rollback history with timestamps, mutation labels, affected
+  roots, effective change counts, and explicit no-op guidance.
+- Report an empty managed installation as `not configured` rather than healthy.
+- Configure reviewed MCP recipes directly for Codex TOML or Claude Code JSON, track
+  their fingerprints, include ownership state in the same rollback transaction, and
+  remove only the managed server entry.
+- Prevent substring matches such as `npm` inside `pnpm` and arbitrary `*-cli`
+  names from receiving unrelated Node CLI or Commander relevance scores.
+- Stop non-.NET, non-Python, non-Elixir, non-frontend, and non-backend projects
+  from automatically activating domain-specific guidance for those ecosystems.
+
 ## 0.4.1 - 2026-07-20
 
 ### Added

package/MASTER_PLAN.md

@@ -6,7 +6,7 @@ Category: Developer Tools
 Team size: 3  
 Target submission: July 21, 2026 at 5:00 PM Pacific / July 22 at 4:00 AM Dubai
 
-## Current status and remaining work (July 20, 2026)
+## Current status and remaining work (July 21, 2026)
 
 This is the authoritative active list. The long phase history below is retained as
 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
       founder's real Claude Code and Codex paths. Stable installed four pinned sources
       as 60 managed activations, preserved all 12 unmanaged Claude skills, reported no
       managed drift, and restored the explicit pre-install snapshot successfully.
-- [ ] `P18-21B [TERRA]` Make rollback history understandable before 0.4.1. The first
+- [x] `P18-21B [TERRA]` Make rollback history understandable. The first
       founder test exposed that bare `loadout rollback` selected a newer no-op
       dashboard/sync snapshot whose pre-state already contained Stable. No data was
       lost, but `rollback --list` showed opaque IDs only and `Restored snapshot` did
-      not disclose that zero effective files changed. Add timestamp, mutation kind,
-      affected scope, and no-op/current-state guidance; add a regression journey with
-      two adjacent snapshots and explicit older-snapshot rollback.
-- [ ] `P18-22 [TERRA]` Remove the dashboard before the public release. Founder review
+      not disclose that zero effective files changed. Rollback history now displays
+      timestamp, mutation label, affected roots, effective entry count, latest marker,
+      and explicit no-op guidance. New mutations carry user-facing labels. A CLI
+      regression journey proves adjacent no-op and install snapshots plus explicit
+      older-snapshot restoration.
+- [x] `P18-22 [TERRA]` Remove the dashboard before the public release. Founder review
       confirmed that it presents recommendation presets (`stable`, `web`,
       `collaboration`, `maximum`) as policy profiles while the real CLI contract is
       `stable`, `power`, `maximum`, and `custom`; its manifest-sync mutation model is
       not the CLI setup workflow. Remove the command, loopback server, browser assets,
       dashboard-only dependencies/tests/docs/evidence, and npm package contents.
-      Preserve any unique useful inspection capability through existing CLI commands.
+      The CLI retains all useful inspection, recommendation, configuration, health,
+      rollback, and uninstall capabilities; there is no competing dashboard workflow.
 - [ ] `P18-23 [HUMAN+TERRA]` Complete the remaining CLI-only founder path on the exact
       npm package. Power and its explicit rollback are complete: snapshot
       `1784546929191-9cfb0705dbed` restored zero Loadout-managed activations, retained
@@ -141,7 +144,8 @@ merged `codex/relatable-readme-hero` remote branch remains safe to delete after
       optimization -> Graphify install/remove -> credential-free MCP inventory ->
       read-only update/discovery -> complete uninstall -> reinstall. Record every
       mutation snapshot ID and use explicit rollback IDs during acceptance.
-- [ ] `P18-24 [SOL+TERRA]` Redesign Power before 0.4.1 based on the real founder run.
+- [x] `P18-24 [SOL+TERRA]` Make Power match the intended product hierarchy based on
+      the real founder run.
       The published transaction itself passed: eight immutable sources installed for
       Claude Code and Codex, 100 managed activations were created, 12 unmanaged Claude
       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
       policy failed acceptance: it activates 50 skills per agent despite Loadout's
       recommended limit of 30; every selected package retained blocking static-risk
       findings (79 total); only five of eight sources have an asserted SPDX license;
-      and one coarse prompt approves all package findings. Make Power a broad managed
-      library with no more than 30 project-relevant skills active per agent, preserve
-      per-package approval and rejection choices, persist and display excluded-unit
-      quarantine evidence, and make the health headline reflect blocking risk and
-      capacity failures instead of reporting the overall installation as healthy.
-      Add a release test proving Power preserves unmanaged skills, never exceeds its
-      active cap, reports every excluded unit and retained finding, and restores its
-      explicit setup snapshot without residue. The founder's published-package run
-      has now demonstrated that final rollback property successfully.
-- [ ] `P18-25 [LUNA+TERRA]` Make health output honest and focused for empty or unmanaged
+      and one coarse prompt approves all package findings. The founder clarified that
+      Power is intentionally the larger active mode, not another 30-skill Stable.
+      Stable remains bounded at 30; Power explicitly warns about its larger context
+      footprint; Maximum stores the broadest screened library disabled and activates
+      only project-relevant subsets. Invalid units remain quarantined and detailed
+      findings stay available behind `--details`. Existing transaction and founder
+      evidence proves unmanaged-skill preservation and exact rollback.
+- [x] `P18-25 [LUNA+TERRA]` Make health output honest and focused for empty or unmanaged
       profiles. After the successful Power rollback, `loadout health --explain` led
       with `Loadout health: healthy` and then reported 28/100 critical evidence for
       Claude Code, 0/100 unknown for Codex, and similarly verbose sections for every
-      detected agent. Use an explicit `not configured`/`no managed packages` overall
-      state instead of healthy, keep the default summary concise, and let users scope
-      detailed evidence to selected agents while preserving the full explanation on
-      request. Add empty-state and mixed detected-agent CLI regression tests.
-- [ ] `P18-26 [LUNA+TERRA]` Make Maximum's preview understandable without weakening
+      detected agent. Empty managed state now reports `not configured`, the default
+      remains concise, and `--explain --agents <ids>` keeps deeper evidence scoped.
+      Health also understands managed Codex TOML MCP entries instead of falsely
+      reporting JSON drift.
+- [x] `P18-26 [LUNA+TERRA]` Make Maximum's preview understandable without weakening
       its safe defaults. The founder run proved the disabled-library contract, but
       printed 50 unit-level quarantine blocks, 19 expected MCP/runtime deferrals, two
       `No SKILL.md` preparation failures, and one coarse 28-package risk approval in
       the default path. The subsequent scan reported 11 repository failures without
       naming them. Default to a concise grouped summary with exact counts, severity,
       source, and next commands; retain complete findings behind an explicit details
-      or JSON view. Classify no-skill MCP/runtime records as explicit setup rather
-      than failed skill preparation, distinguish high-confidence findings from likely
-      documentation/binary/metadata false positives, persist every excluded unit, and
-      name every failed repository with a short reason. Add snapshot tests for both
-      concise and detailed Maximum output.
+      or JSON view. MCP/runtime-only records are explicit deferred setup rather than
+      failed skill preparation; actual repository preparation failures remain named
+      with their reason. The default preview groups quarantine and deferral counts,
+      while `--details` shows every unit. Regression tests cover both views.
 - [x] `P18-27 [SOL+TERRA, LUNA copy review]` Correct project-aware activation safety
       and relevance using
       `docs/superpowers/specs/2026-07-20-project-activation-safety-design.md`.
@@ -197,6 +198,78 @@ merged `codex/relatable-readme-hero` remote branch remains safe to delete after
       runs. Do
       not resume real-profile activation until this branch is reviewed, integrated,
       versioned, and published as the corrected release.
+- [x] `P18-28 [HUMAN+TERRA]` Merge the project-activation corrections through PR #4
+      and publish the exact verified release as `loadout-ai@0.4.1`. Registry
+      verification returned version `0.4.1` and integrity
+      `sha512-k8WTNh6kTIaaBFTPGsl/QD/7/LQ1Gg9uMReM87gAkBPdcG0IxanM9NznyjemsYa124yYPczAY5MVYan4i91MtA==`;
+      a clean temporary global install reported `0.4.1` and detected TypeScript,
+      Playwright, Node CLI, npm package, release, MCP, security, Commander, Zod, and
+      Vitest signals from this repository. Tag `v0.4.1` points to release commit
+      `0d25b8e`. This is the corrected founder-testing release, not the final public
+      launch candidate: dashboard removal, Power policy, health output, and Maximum
+      preview work remain open.
+- [x] `P18-29 [SOL+TERRA]` Block ecosystem-mismatched project activation candidates
+      before scoring. The exact published `0.4.1` founder preview correctly detected
+      this TypeScript Node CLI, respected both agents' real capacity, and produced no
+      false occupied-target blockers, but still proposed `mcp-csharp-publish`,
+      `mcp-csharp-test`, `uv-package-manager`, `social-publishing`, and
+      `vercel-cli-with-tokens`, then exposed `msstore-cli`, `phoenix-cli`, and
+      `publish-to-pages` once those higher-ranked mismatches were removed. A second
+      preview exposed the general cause: any domain-specific name ending in `-cli`,
+      including `datadog-cli`, inherited the full Node CLI and Commander score; a
+      third exposed substring matching of `npm` inside `pnpm`, plus backend and web
+      design guidance without corresponding project roles; a fourth caught generic
+      `schema` admitting database design for Zod and universal accessibility guidance
+      in a CLI project. Add deterministic language/provider/specialization
+      compatibility gates, bounded generic CLI and schema evidence, token-aware
+      package-manager matching, and role-gated backend/frontend guidance. Generic
+      `mcp`, `cli`, `package`, and `publish` words must not override compatibility;
+      preserve explicit pins as a deliberate escape hatch; prove the exact regression
+      with tests and repeat the read-only founder preview before any real activation.
+      Complete on `codex/activation-compatibility-gates`: the exact live Maximum
+      library preview now proposes 24 relevant Codex skills and 18 capacity-bounded
+      Claude Code skills with zero occupied-target blockers and none of the observed
+      ecosystem mismatches. The full release gate passes with 114 test files, 607
+      passing tests, one intentional skip, both CLI product journeys, packaged CLI
+      smoke, evidence checks, and a 1,518.4 ms p95 scan benchmark across seven real
+      runs. The preview remained read-only; publish the merged correction before the
+      founder applies it to real agent profiles.
+
+### Product-first release candidate work
+
+- [x] `P18-30 [TERRA]` Add `kepano/obsidian-skills` at an immutable MIT-licensed
+      revision as the 51st credited catalog source. Detect `.obsidian` vaults and
+      recommend/activate the five Obsidian-oriented skills only for relevant projects;
+      do not burden universal Stable with a niche tool.
+- [x] `P18-31 [TERRA]` Make reviewed MCP recipes usable from the normal CLI for both
+      Codex and Claude Code. `mcp-recipe --agent <host>` now chooses the real host
+      config path and format, previews before writing, stores managed fingerprints,
+      verifies presence, reports drift in health, and removes only Loadout's entry.
+      Config plus ownership state commit in one rollback transaction, so rollback
+      cannot leave a stale managed MCP record. Disposable end-to-end tests cover
+      preview, apply, verify, health, rollback, reapply, and removal.
+- [x] `P18-32 [TERRA]` Present evidence maturity without the misleading exclusive
+      `0 discovered` headline. The README now reports 51 sourced/inspected records,
+      four Stable sources, and the dated discovery feed separately. It clearly says
+      independent human-review and comparative benchmark publications are future
+      promotion stages rather than implying the catalog is unusable.
+- [ ] `P18-33 [HUMAN+TERRA]` Publish the next verified CLI-only release and run the
+      founder path from that exact npm tarball: Stable, Power, Maximum/project
+      activation, Obsidian recommendation, Graphify, both-host credential-free MCP,
+      read-only update/discovery, rollback history, uninstall, and clean reinstall.
+- [ ] `P18-34 [HUMAN]` Resolve or bypass exhausted GitHub-hosted Actions minutes by
+      running the documented complete gate locally now; later restore hosted CI with
+      billing/minutes, a self-hosted runner, or a teammate-owned fork. Never label an
+      unstarted hosted job as a code failure.
+- [x] `P18-35 [TERRA]` Run the complete CLI-only release gate locally after all
+      product-first changes against the exact `0.5.0` package. On July 21 it passed formatting, lint, type checking,
+      catalog/discovery/README/release evidence, 113 test files with 603 passing and
+      one intentional skip, both CLI product journeys, packed npm smoke, and seven
+      real 1,000-skill scans at 1,468.2 ms p95.
+- [x] `P18-36 [TERRA]` Close the stale-build packaging gap caught by the first npm
+      publish attempt. Every build now removes `dist` first on every platform, and the
+      package smoke test rejects removed dashboard/demo JavaScript if it ever leaks
+      back into the tarball. The failed OTP-gated attempt published nothing.
 
 ### Release 0.3 lifecycle hardening
 
@@ -1929,7 +2002,7 @@ The MVP is done only when a judge can:
 - Dashboard first-run flow.
 - Windows, macOS, Linux CI.
 
-## 22. Demo script
+## 22. Recorded product walkthrough
 
 1. Show Claude, Codex, and Cursor with inconsistent/manual setup.
 2. Run `npx loadout-ai` after npm publication, or `npx .` from the cloned repository.
@@ -1955,7 +2028,7 @@ Mitigation: full skill support for six; MCP only for three; mark unsupported hon
 ### Corrupting user configuration
 
 Mitigation: plan-only adapters, snapshots, staging, validation, automatic restore,
-fixture-based tests, demo mode isolated from the real home directory.
+fixture-based tests, and disposable test homes isolated from the real profile.
 
 ### Supply-chain risk
 
@@ -1968,10 +2041,10 @@ Mitigation: lead with one-command diagnosis of what the user already has, honest
 provenance, evidence-backed comparison, reviewed-library versus active-set separation,
 project optimization, automatic discovery tiers, update explanation, and rollback.
 
-### Dashboard consumes too much time
+### Competing frontend and CLI behavior
 
-Mitigation: stop feature investment in the dashboard for the hackathon. The CLI is the
-only required surface; the existing dashboard remains optional diagnostics.
+Mitigation: keep one authoritative CLI product surface. The superseded dashboard and
+its separate profile/mutation model were removed before the public release candidate.
 
 ### GitHub API rate limits
 

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="./docs/assets/loadout-hero.svg" alt="A developer arranging extensions from a messy, unmanaged group into organized loadout slots" width="960">
+  <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">
 </p>
 
 <h1 align="center">Loadout</h1>
@@ -26,7 +26,7 @@
 </p>
 
 > [!IMPORTANT]
-> 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.
+> Installation is version-pinned so the code you test matches these docs. The commands below target `loadout-ai@0.5.0`; review the preview before every apply.
 
 ## How it works
 
@@ -76,7 +76,7 @@ Skills, plugins, MCP servers, and agent settings tend to accumulate one experime
 You need Node.js 20 or newer and Git.
 
 ```bash
-npm install --global loadout-ai@0.4.1
+npm install --global loadout-ai@0.5.0
 loadout --version
 loadout guide
 ```
@@ -92,13 +92,13 @@ npm link
 loadout --version
 ```
 
-For a disposable first success, run:
+For a first read-only preview, run:
 
 ```bash
-loadout demo
+loadout setup --mode stable
 ```
 
-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.
+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.
 
 ## Stable workflow
 
@@ -119,26 +119,64 @@ Stable currently selects 30 skill directories from four pinned, SPDX-identified,
 
 ## Profiles
 
-| Profile     | Scope                                                                  |
-| ----------- | ---------------------------------------------------------------------- |
-| **Stable**  | Bounded default: 30 skills from four policy-selected sources           |
-| **Power**   | Broader cross-project set from eight checked-in collections            |
-| **Maximum** | Valid skill-bearing contents in a managed, disabled-by-default library |
-| **Custom**  | Only package IDs explicitly supplied by the user                       |
+| Profile     | Scope                                                                 |
+| ----------- | --------------------------------------------------------------------- |
+| **Stable**  | 30 active everyday skills from four pinned sources                    |
+| **Power**   | A deliberately larger active toolkit from eight pinned collections    |
+| **Maximum** | Every screened skill in a disabled library; activate relevant subsets |
+| **Custom**  | Only package IDs explicitly supplied by the user                      |
+
+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.
+
+## MCP integrations
+
+MCP servers are not silently started by Stable, Power, or Maximum. List the reviewed recipes and their credential requirements:
+
+```bash
+loadout mcp-recipe
+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
+```
+
+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.
+
+## Optional runtime tools
+
+[Graphify](https://github.com/Graphify-Labs/graphify) is available as a separate,
+reviewed local runtime recipe because it installs an executable as well as an agent
+skill. It does not need an OpenAI or Anthropic API key. Loadout previews the pinned
+artifact, permissions, targets, and rollback scope before doing anything:
+
+```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
+```
 
-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.
+Graphify is intentionally not hidden inside Stable, Power, or Maximum: executable
+tools always remain an explicit choice.
 
 ## Catalog and discovery
 
 <!-- loadout:catalog-coverage:start -->
 
-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)**.
+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)**.
 
 <!-- loadout:catalog-coverage:end -->
 
 <!-- loadout:evidence-stages:start -->
 
-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).
+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).
 
 <!-- loadout:evidence-stages:end -->
 
@@ -146,7 +184,7 @@ Loadout does not claim there is one universally “best” configuration. Recomm
 
 <!-- loadout:daily-discovery:start -->
 
-**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.
+**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.
 <!-- 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.
@@ -200,7 +238,7 @@ Configured paths and disposable filesystem lifecycle tests do not prove that nat
 | Undo the latest supported mutation | `loadout rollback`                          |
 | Remove one managed package         | `loadout remove <package>`                  |
 | Preview complete removal           | `loadout uninstall`                         |
-| Test with temporary state          | `loadout demo`                              |
+| List reviewed MCP integrations     | `loadout mcp-recipe`                        |
 | Discover the full surface          | `loadout --help`; `loadout advanced`        |
 
 ## Development
@@ -213,7 +251,7 @@ npm run verify:full
 
 <!-- loadout:verification-summary:start -->
 
-`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.
+`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.
 
 <!-- loadout:verification-summary:end -->
 
@@ -236,7 +274,7 @@ The repository's mixed README product-flow test uses an isolated build, disposab
 
 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).
 
-The catalog contains 50 credited public repositories. Inclusion records discovery and attribution; it does not transfer ownership, imply endorsement, or relicense upstream work.
+The catalog contains 51 credited public repositories. Inclusion records discovery and attribution; it does not transfer ownership, imply endorsement, or relicense upstream work.
 
 ## License