loadout-ai 0.4.1 → 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

@@ -40,17 +40,15 @@ receive different numbers of additions. `tool graphify` is also a preview; Graph
 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
 
@@ -61,11 +59,12 @@ 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
@@ -142,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
@@ -169,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.1` 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,

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.

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

@@ -0,0 +1,55 @@
+# Loadout README Explainer Design
+
+## Purpose
+
+Create one original README infographic that lets a first-time visitor understand Loadout in a few seconds: it turns a deliberate extension selection into a previewed, managed, and recoverable setup across supported AI coding agents.
+
+The illustration may take broad inspiration from the supplied `code-review-graph` references—white space, hand-drawn lines, rounded cards, arrows, and a restrained multicolor palette—but must not reproduce their composition, wording, icons, or product claims.
+
+## Selected Direction
+
+Use a horizontal control-loop composition titled **“Your Agent Extensions, Under Control”**.
+
+The center of the image contains five connected stages, in this exact order:
+
+1. **Choose** — select a profile or packages.
+2. **Inspect** — check pinned source and metadata.
+3. **Preview** — see the plan before agent files change.
+4. **Apply** — install through a managed snapshot.
+5. **Undo** — roll back while protecting later edits.
+
+The stages form a gentle left-to-right arc, with a return arrow from Undo toward Choose to suggest an intentional, repeatable lifecycle rather than a one-way installer.
+
+Below the control loop, a single **Loadout** inventory card fans out to compact agent cards. Use only names supported by the checked-in adapter matrix: **Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, and Windsurf**. A final small card reading **“+ 5 more adapters”** represents the remaining supported targets without overcrowding the graphic.
+
+The footer contains the short summary **“Preview first · Managed changes · Snapshot-backed undo”**. Do not include numerical safety, performance, popularity, or compatibility claims.
+
+## Visual Language
+
+- Wide README-friendly raster infographic, approximately 16:9.
+- Warm white background with generous breathing room.
+- Loose hand-drawn marker lines and slightly imperfect rounded rectangles.
+- Dark charcoal headings and outlines.
+- Blue for selection and agent destinations, purple for inspection, orange for preview, green for apply, and coral for undo.
+- Soft pastel fills with high-contrast text.
+- No logos, mascots, screenshots, terminal chrome, photorealism, gradients, shadows, watermarks, or decorative clutter.
+- All text must be legible at a README display width of 960 pixels.
+
+## Repository Integration
+
+- Save the final project asset as `docs/assets/loadout-workflow.png`.
+- Keep the existing `docs/assets/loadout-hero.svg`; do not overwrite or delete it.
+- Replace the top README image reference with the new PNG.
+- Use this alt text: **“Loadout workflow: choose extensions, inspect sources, preview changes, apply through a managed snapshot, and undo safely across supported AI coding agents.”**
+- Keep the existing centered 960-pixel presentation.
+
+## Validation
+
+The finished work is acceptable only if:
+
+- the five stage labels and their order are accurate and readable;
+- every named agent appears in the checked-in adapter capability matrix;
+- no unsupported safety or performance claim is introduced;
+- the PNG exists in the repository and the README references it with the specified alt text;
+- visual inspection confirms a clean, original composition without clipped or garbled text;
+- README product-flow tests, formatting, linting, type checking, evidence gates, unit tests, CLI flow, README flow, package smoke, performance checks, and remote CI all pass after integration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadout-ai",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "private": false,
   "license": "MIT",
   "description": "Universal upgrade manager for AI coding agents",
@@ -10,7 +10,6 @@
   },
   "files": [
     "dist/src",
-    "dashboard",
     "catalog",
     "docs",
     "README.md",
@@ -41,17 +40,17 @@
     "node": ">=20"
   },
   "scripts": {
+    "clean": "node scripts/clean-dist.mjs",
+    "prebuild": "npm run clean",
     "build": "tsc -p tsconfig.json",
     "prepack": "npm run build",
     "dev": "tsx src/cli.ts",
-    "dashboard": "tsx src/dashboard.ts",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "lint": "eslint src tests vitest.config.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:e2e": "npm run test:e2e:cli",
-    "test:e2e:dashboard": "playwright test",
     "pretest:e2e:cli": "npm run build",
     "test:e2e:cli": "node scripts/cli-product-flow.mjs",
     "test:e2e:readme": "node scripts/readme-product-flow.mjs",
@@ -66,7 +65,7 @@
     "check:evidence": "node scripts/check-catalog-attribution.mjs && node scripts/check-discovery-artifacts.mjs && npm run check:readme-claims && node --import tsx scripts/check-release-claims.ts",
     "feed:build": "node --import tsx scripts/build-intelligence-feed.ts",
     "verify": "npm run format:check && npm run lint && npm run typecheck && npm run check:evidence && npm test -- --run && npm run test:e2e:cli && npm run test:e2e:readme && npm run test:package && npm run test:performance",
-    "verify:full": "npm run verify && npm run test:e2e:dashboard"
+    "verify:full": "npm run verify"
   },
   "dependencies": {
     "commander": "^12.1.0",
@@ -74,7 +73,6 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
-    "@playwright/test": "^1.61.1",
     "@types/node": "^22.10.0",
     "eslint": "^9.39.5",
     "eslint-config-prettier": "^10.1.8",