loadout-ai 0.4.0 → 0.5.0

package/docs/FEATURE_TEST_MATRIX.md

@@ -112,26 +112,20 @@ Run the entire required gate with one command:
 npm run verify
 ```
 
-Use `npm run verify:full` when Playwright Chromium is installed and you also want the
-optional dashboard browser check. The individual stages are listed below for focused
-reruns and diagnosis.
-
-| Command                      | Coverage                                                                | Expected result                                    |
-| ---------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
-| `npm run format:check`       | Repository formatting                                                   | Exit 0; no files changed.                          |
-| `npm run lint`               | TypeScript lint rules                                                   | Exit 0.                                            |
-| `npm run typecheck`          | TypeScript contract                                                     | Exit 0.                                            |
-| `npm run check:evidence`     | Catalog/discovery attribution, README claims, and release boundaries    | Exit 0; no claim is silently promoted.             |
-| `npm test`                   | Unit, integration, native filesystem, safety, and regression suites     | All tests pass.                                    |
-| `npm run test:e2e:cli`       | Disposable scan → compare → optimize → apply → rollback journey         | Prints a successful CLI product flow.              |
-| `npm run test:e2e:readme`    | Isolated library/activation/manifest/card/rollback journey              | Prints README product flow success.                |
-| `npm run test:package`       | `npm pack`, install outside the checkout, packaged CLI install/rollback | Prints package smoke success.                      |
-| `npm run test:performance`   | Seven scans of 1,000 real on-disk skill directories                     | p95 remains below the enforced five-second budget. |
-| `npm run test:e2e:dashboard` | Loopback dashboard first-run browser test                               | Playwright passes; no real profile is used.        |
-
-The dashboard test needs a Playwright browser. If the browser executable is absent,
-run `npx playwright install chromium` once; that download is not a Loadout product
-side effect.
+`npm run verify:full` is an alias for the same CLI release gate. The individual stages
+are listed below for focused reruns and diagnosis.
+
+| Command                    | Coverage                                                                | Expected result                                    |
+| -------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------- |
+| `npm run format:check`     | Repository formatting                                                   | Exit 0; no files changed.                          |
+| `npm run lint`             | TypeScript lint rules                                                   | Exit 0.                                            |
+| `npm run typecheck`        | TypeScript contract                                                     | Exit 0.                                            |
+| `npm run check:evidence`   | Catalog/discovery attribution, README claims, and release boundaries    | Exit 0; no claim is silently promoted.             |
+| `npm test`                 | Unit, integration, native filesystem, safety, and regression suites     | All tests pass.                                    |
+| `npm run test:e2e:cli`     | Disposable scan → compare → optimize → apply → rollback journey         | Prints a successful CLI product flow.              |
+| `npm run test:e2e:readme`  | Isolated library/activation/manifest/card/rollback journey              | Prints README product flow success.                |
+| `npm run test:package`     | `npm pack`, install outside the checkout, packaged CLI install/rollback | Prints package smoke success.                      |
+| `npm run test:performance` | Seven scans of 1,000 real on-disk skill directories                     | p95 remains below the enforced five-second budget. |
 
 The focused regression contract for the v0.3.x profile lifecycle is:
 
@@ -361,11 +355,6 @@ and preserves matching active Stable units at the same reviewed commit; MCP-only
 packages remain explicit setup items. `--approve-risk` acknowledges displayed static
 findings but does not execute third-party repository scripts.
 
-`loadout demo --json` is a shorter N smoke test. It creates its own isolated profile,
-performs a real public-repository install and rollback, and must report that local
-agent configuration was untouched. Add `--keep` only when you intend to inspect and
-manually remove the printed demo directory.
-
 ## 5. Existing-skill provenance, adoption, comparison, and freshness (R/S/A)
 
 Copy one harmless skill into the disposable unmanaged profile, then inspect it:
@@ -716,16 +705,14 @@ systemd/cron facility selected on Linux. `LOADOUT_HOME` does not make the native
 scheduler disposable, so never skip the remove command. The lower-level `schedule`
 and `unschedule` commands remain available for job-specific control.
 
-Loopback services are X but do not require the dashboard for normal product use:
+The optional read-only loopback API can be checked separately:
 
 ```bash
 loadout serve --port 0
-loadout dashboard --port 0
 ```
 
-Run them separately, open the printed `127.0.0.1` URL, confirm status/health/catalog
-render from disposable state, and stop each with Ctrl-C. They must not bind a public
-interface.
+Confirm that it binds only to `127.0.0.1`, inspect the API response, and stop it with
+Ctrl-C. It must not bind a public interface.
 
 ## 11. Improvement-cycle records (S)
 
@@ -815,5 +802,5 @@ sections. Parenthesized numbers identify the track above.
   `catalog-verify`, `catalog-update` (8, 9).
 - MCP/conversion/sandbox: `mcp`, `inspect`, `evaluate`, `mcp-recipe`, `mcp-config`,
   `codex-mcp-config`, `convert`, `sandbox-run` (7).
-- Host/secondary surfaces: `completion`, `autopilot`, `schedule`, `unschedule`,
-  `serve`, `dashboard` (10).
+- Host/automation surfaces: `completion`, `autopilot`, `schedule`, `unschedule`,
+  `serve` (10).

package/docs/GITHUB_AUTHORIZATION.md

@@ -1,7 +1,7 @@
 # Optional GitHub authorization
 
 Public discovery remains anonymous. Private discovery is opt-in and begins only
-when the user explicitly connects GitHub from the local CLI or loopback dashboard.
+when the user explicitly connects GitHub from the local CLI.
 
 ## Authorization model
 
@@ -15,7 +15,7 @@ issues, pull-request write, or repository-write permission is requested.
 The app client ID, redirect URI, and application slug may be committed as public
 configuration. The private key and client secret cannot: they belong to a hosted
 broker or a user-controlled local credential manager. Loadout never asks the user to
-paste a token into a manifest, catalog, log, or dashboard URL.
+paste a token into a manifest, catalog, log, or command argument.
 
 ## Local flow and failure modes
 

package/docs/TESTING.md

@@ -27,7 +27,7 @@ snapshot back:
 npm run test:e2e:cli
 ```
 
-This test does not use the dashboard, network, mock command output, or any real agent
+This test does not use the network, mock command output, or any real agent
 profile. It is a required CI gate on Ubuntu; the manual cross-platform workflow runs
 the broader native filesystem suite.
 
@@ -67,9 +67,8 @@ is universally safe. The opt-in `LOADOUT_TEST_LIVE_CATALOG=1` extension separate
 checks the current pinned Stable sources and remains network-dependent.
 
 Run `npm run verify` for formatting, lint, types, deterministic evidence checks, all
-Vitest suites, both CLI journeys, package smoke, and the performance gate. Run
-`npm run verify:full` only when Playwright Chromium is installed and the optional
-dashboard browser test is also wanted.
+Vitest suites, both CLI journeys, package smoke, and the performance gate.
+`npm run verify:full` is retained as an alias for the same complete CLI gate.
 
 Current npm publication, the current pinned Stable repositories, and GitHub repository
 settings are external state. Check them separately with:
@@ -281,18 +280,6 @@ output must never contain the token value; the config should contain only
 explicit `--connect --approve-risk` verification path because an arbitrary MCP host
 cannot resolve Loadout's keychain reference by itself.
 
-## Optional dashboard
-
-The dashboard is a secondary inspection surface, not the onboarding requirement:
-
-```bash
-npx . dashboard
-```
-
-Open the printed loopback URL. CLI setup, updates, removal, discovery, and rollback all
-work without it. Browser automation is also optional and runs only when manually
-dispatched in CI; locally, use `npm run test:e2e:dashboard`.
-
 ## Final cleanup test
 
 ```bash

package/docs/USER_TEST_GUIDE.md

@@ -26,27 +26,29 @@ Loadout-managed skills from your own pre-existing skills. `health` checks local
 loadout catalog --json
 loadout candidate list --limit 10
 loadout recommend --project .
-loadout optimize --project .
+loadout optimize --project . --agents codex,claude-code --limit 30
 loadout tool
 loadout tool graphify
 ```
 
 Run the project commands from the project you care about, or replace `.` with its
-absolute path. `optimize` is still a preview until `--yes` is supplied. `tool
-graphify` is also a preview; Graphify is a reviewed runtime tool and does not
-need an OpenAI or Anthropic API key for its code-only install.
+absolute path. `recommend` labels ordinary skill libraries separately from MCP or
+runtime integrations that require explicit setup. `optimize` is still a preview
+until `--yes` is supplied. Its limit applies separately to every agent and includes
+both Loadout-managed and pre-existing unmanaged skills, so Claude and Codex can
+receive different numbers of additions. `tool graphify` is also a preview; Graphify
+is a reviewed runtime tool and does not need an OpenAI or Anthropic API key for its
+code-only install.
 
-## 3. Open the optional dashboard
+## 3. Understand the three scopes
 
 ```bash
-loadout dashboard
+loadout profiles
 ```
 
-Open the `http://127.0.0.1:PORT` address it prints. It never listens on the
-network. The dashboard shows status, health, installed packages, updates, local
-project recommendations, profiles, and the catalog. Its Apply and Undo buttons
-require an in-page preview, acknowledgement, and a private local session token.
-Stop the server with `Control-C`.
+Stable keeps the active set at 30. Power deliberately activates a larger toolkit.
+Maximum downloads the broadest screened skill library but keeps new entries disabled
+until project optimization or an explicit enable action selects them.
 
 ## 4. Preview and install a profile
 
@@ -57,13 +59,18 @@ confirmation before changing files. A mutation creates a snapshot first.
 # Recommended everyday skills
 loadout setup --mode stable --agents codex,claude-code
 
-# Broader daily-use selection (50 curated skill directories)
+# Broader daily-use selection (roughly 50 curated skills per agent)
 loadout setup --mode power --agents codex,claude-code
 
 # Download the broad reviewed library while keeping the active set controlled
 loadout setup --mode maximum --agents codex,claude-code
+loadout setup --mode maximum --agents codex,claude-code --details
 ```
 
+Maximum stores reviewed copies in Loadout's disabled library; it does not expose the
+whole catalog to each agent. Follow it with `loadout optimize --project .
+--agents codex,claude-code --limit 30` to preview a compact project-aware working set.
+
 At the API-access question, choose `None` unless you separately pay for a
 provider API. A ChatGPT Plus or Claude Pro subscription is not an API key. Core
 skill profiles do not require one; credentialed MCP and runtime operations stay
@@ -134,6 +141,21 @@ them.
 
 ```bash
 loadout mcp-recipe --no-key
+loadout mcp-recipe --credential-free
+
+# Preview, configure, verify, then remove Playwright for Codex
+loadout mcp-recipe playwright --agent codex
+loadout mcp-recipe playwright --agent codex --yes
+loadout mcp-recipe playwright --agent codex --verify
+loadout remove mcp-recipe:playwright:codex
+loadout remove mcp-recipe:playwright:codex --yes
+
+# Repeat independently for Claude Code
+loadout mcp-recipe playwright --agent claude-code
+loadout mcp-recipe playwright --agent claude-code --yes
+loadout mcp-recipe playwright --agent claude-code --verify
+loadout remove mcp-recipe:playwright:claude-code
+loadout remove mcp-recipe:playwright:claude-code --yes
 ```
 
 Expect Playwright MCP, Chrome DevTools MCP, and GitHub read-only. None requires a
@@ -161,7 +183,7 @@ cleanup deliberately deletes Loadout's snapshots, so it is the last lifecycle te
 ## Troubleshooting and recovery
 
 - **`loadout` is not found after installation:** confirm `npm install --global
-loadout-ai@0.4.0` completed, run `hash -r`, and confirm npm's global binary
+loadout-ai@0.5.0` completed, run `hash -r`, and confirm npm's global binary
   directory is on `PATH`. For a source checkout, run `npm run build` and `npm link`.
 - **A preview asks for `--approve-risk`:** read the reported scripts, domains,
   credentials, binaries, or instruction findings. If you accept that specific plan,
@@ -172,6 +194,10 @@ loadout-ai@0.4.0` completed, run `hash -r`, and confirm npm's global binary
   legacy snapshot without post-mutation evidence. Run `loadout health --explain` and
   inspect the affected path before deciding whether an explicit force option is
   appropriate; do not delete the path merely to make the command pass.
+- **Activation reports fewer additions for one agent:** this is expected when that
+  agent already has unmanaged or managed skills. `--limit` is a total per-agent
+  ceiling, not a request to add that many new skills. Recursively empty rollback
+  directories do not consume capacity and are safe for Loadout to reuse.
 - **A fetch, discovery, or update check fails:** retry only after checking network,
   proxy, DNS, and source-host access. Local inventory, library, health, rollback, and
   offline fixture tests remain separate; an unavailable live check is not a pass.

package/docs/evidence/readme-claims.json

@@ -214,14 +214,6 @@
         "tests/benchmark-campaign.test.ts"
       ]
     },
-    {
-      "id": "dashboard.local",
-      "section": "Current beta limits",
-      "summary": "The dashboard presents local Loadout data and does not establish hosted-service availability.",
-      "evidenceClass": "integration-verified",
-      "status": "bounded",
-      "evidence": ["src/dashboard.ts", "tests/dashboard.test.ts"]
-    },
     {
       "id": "uninstall.complete",
       "section": "Troubleshooting and uninstall",

package/docs/superpowers/plans/2026-07-20-loadout-readme-explainer.md

@@ -0,0 +1,116 @@
+# Loadout README Explainer Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Generate and integrate an original Loadout workflow infographic that accurately explains the preview-first, recoverable extension lifecycle.
+
+**Architecture:** A single project-owned PNG becomes the README hero while the existing SVG remains available. The README product-flow test locks the asset path and accessible description, and the normal verification suite guards product claims and repository integrity.
+
+**Tech Stack:** Built-in image generation, PNG asset, Markdown/HTML README, Vitest, npm verification scripts, GitHub Actions.
+
+## Global Constraints
+
+- Use the exact five-stage order: Choose, Inspect, Preview, Apply, Undo.
+- Name only checked-in supported agents: Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, Windsurf, plus “+ 5 more adapters”.
+- Use the exact footer: “Preview first · Managed changes · Snapshot-backed undo”.
+- Do not add numerical safety, performance, popularity, or compatibility claims.
+- Preserve `docs/assets/loadout-hero.svg`; create `docs/assets/loadout-workflow.png`.
+- Use the exact alt text from the approved design spec.
+
+---
+
+### Task 1: Lock the README integration contract
+
+**Files:**
+
+- Modify: `tests/readme-product-flow.test.ts`
+- Test: `tests/readme-product-flow.test.ts`
+
+**Interfaces:**
+
+- Consumes: the current README hero assertion.
+- Produces: a test contract for `./docs/assets/loadout-workflow.png` and the approved alt text.
+
+- [ ] **Step 1: Update the hero assertion**
+
+```ts
+expect(readme).toContain(
+  '<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">',
+);
+```
+
+- [ ] **Step 2: Run the focused test and verify red**
+
+Run: `npx vitest run tests/readme-product-flow.test.ts`
+
+Expected: FAIL because `README.md` still references `loadout-hero.svg`.
+
+### Task 2: Generate and validate the infographic
+
+**Files:**
+
+- Create: `docs/assets/loadout-workflow.png`
+- Preserve: `docs/assets/loadout-hero.svg`
+
+**Interfaces:**
+
+- Consumes: `docs/superpowers/specs/2026-07-20-loadout-readme-explainer-design.md` and the three supplied visual references.
+- Produces: a wide, readable, original PNG suitable for a 960-pixel README presentation.
+
+- [ ] **Step 1: Generate the project artwork**
+
+Use built-in image generation with the supplied images as style references and this content contract: title “Your Agent Extensions, Under Control”; Choose → Inspect → Preview → Apply → Undo; a Loadout inventory card; the seven named agents; “+ 5 more adapters”; footer “Preview first · Managed changes · Snapshot-backed undo”; warm white hand-drawn infographic; no unsupported claims, logos, watermarks, gradients, shadows, or garbled text.
+
+- [ ] **Step 2: Save the selected output**
+
+Copy the generated artifact to `docs/assets/loadout-workflow.png` without modifying `docs/assets/loadout-hero.svg`.
+
+- [ ] **Step 3: Inspect the saved PNG**
+
+Open the workspace asset at original detail and verify every required label, composition, padding, and legibility. If any required text is wrong, perform one targeted image edit and inspect again.
+
+### Task 3: Integrate and verify the README
+
+**Files:**
+
+- Modify: `README.md`
+- Test: `tests/readme-product-flow.test.ts`
+
+**Interfaces:**
+
+- Consumes: `docs/assets/loadout-workflow.png` and the test contract from Task 1.
+- Produces: the rendered README hero reference and accessible description.
+
+- [ ] **Step 1: Replace the README hero reference**
+
+```html
+<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"
+/>
+```
+
+- [ ] **Step 2: Run the focused test and verify green**
+
+Run: `npx vitest run tests/readme-product-flow.test.ts`
+
+Expected: 9 passed and 1 skipped, with zero failures.
+
+- [ ] **Step 3: Run the complete local gate**
+
+Run: `npm run verify`
+
+Expected: formatting, lint, type checking, evidence gates, 114 test files, CLI flow, README flow, package smoke, and performance checks all pass.
+
+- [ ] **Step 4: Commit and push**
+
+```bash
+git add README.md docs/assets/loadout-workflow.png tests/readme-product-flow.test.ts docs/superpowers/plans/2026-07-20-loadout-readme-explainer.md
+git commit -m "docs: add Loadout workflow explainer"
+git push origin main
+```
+
+- [ ] **Step 5: Verify remote CI**
+
+Run the normal push CI, then dispatch the full CI workflow on the final commit. Confirm the fast gate, Playwright diagnostics, and all six native OS/Node jobs complete successfully.