loadout-ai 0.3.1 → 0.4.0

package/docs/superpowers/specs/2026-07-19-relatable-readme-hero-design.md

@@ -0,0 +1,80 @@
+# Relatable README and Hero Design
+
+## Objective
+
+Make Viraj's current Loadout README more memorable to a first-time visitor without weakening its evidence boundaries. Replace the small slot mark with a clearly stronger original hero, add a concise human explanation of the loadout metaphor, correct canonical repository links, and document the actual GitHub Actions failure without pretending it is a code defect.
+
+## Verified starting point
+
+- Source: `VirajMishra1/loadout` default branch `main` at merge commit `194676910327176272ebe42982d13c6e8246f0aa`.
+- The README already presents the verified `Choose -> Inspect -> Preview -> Apply -> Undo` flow and bounded warnings about unpublished `0.3.2`, preview/apply identity, catalog evidence, native-agent execution, security, and persistence.
+- The failed upstream Actions job `88250042904` in run `29708871932` executed zero steps. Its sole annotation says the job did not start because recent account payments failed or the spending limit must be increased.
+- Because no runner step started, there is no failing repository command to reproduce locally. Verification must instead run the workflow's intended commands locally and report that this validates the code but cannot reproduce GitHub account billing state.
+- Canonical README/package links still point to the temporary `reddynitish/loadout` fork and must point to `VirajMishra1/loadout`.
+
+## README story
+
+Keep `## Why Loadout` in its current location after the verified product journey. Add one short paragraph before the existing evidence-backed benefits:
+
+> Skills, plugins, MCP servers, and agent settings tend to accumulate one experiment at a time. Eventually it becomes hard to remember what is installed, where it came from, or how to undo it. In a game, a loadout is the deliberate set of tools chosen before a mission. Loadout brings that same discipline to AI coding agents: inspect the available equipment, choose intentionally, apply it through managed changes, and remove or roll it back later.
+
+The final copy may be tightened for rhythm but must preserve these facts and must not introduce a founder narrative, generic marketing superlatives, universal safety, native-host execution, or stronger rollback guarantees than the implementation proves. Retain the three existing bullets for managed inventory, preview-first operations, and recoverable managed changes.
+
+## Hero composition
+
+Create `docs/assets/loadout-hero.svg` as a wide, dependency-free, theme-aware SVG and replace the README's small `loadout-mark.svg` reference only after rendered comparison shows the hero is materially stronger.
+
+The composition reads left to right:
+
+1. **Unmanaged edge:** a restrained cluster of loose extension/config tiles, crossing paths, and small labels sits outside a dashed management boundary. It is visibly disorganized but not cartoonishly chaotic.
+2. **Developer choice:** a simple, original geometric developer figure at a compact workbench reaches toward one extension tile. The figure is symbolic rather than a detailed character, avoiding any resemblance to Ponytail's artwork or composition.
+3. **Managed loadout:** five aligned equipment slots sit inside a clear rail. Selected slots use recognizable code-native symbols such as `>_`, a plug, linked nodes, or braces; the remaining slot can be empty. A small directional cue connects the chosen tile to the rail.
+4. **Outcome:** the organized rail is visually calmer and more regular than the unmanaged edge. The image communicates selection and control, not an unsupported claim that every external tool is safe.
+
+Use a wide `viewBox` suitable for a GitHub README hero, approximately 960 by 300. Use SVG paths and basic shapes only, with no raster content, scripts, animation, gradients, external fonts, remote references, or copied assets. Every visible symbol should remain legible when the hero is rendered near 720 pixels wide and at a smaller mobile width.
+
+Use `currentColor` plus an internal `prefers-color-scheme` fallback so strokes and restrained fills have adequate contrast on GitHub light and dark themes. Include one meaningful `<title>` and `<desc>`, `role="img"`, and matching `aria-labelledby`. The README `<img>` needs concise alt text describing the developer moving extension tiles from a messy group into organized loadout slots.
+
+The existing `docs/assets/loadout-mark.svg` remains available as a compact mark unless repository cleanup later proves it unused and removal is explicitly covered by tests and links. The task does not need to delete it.
+
+## Canonical repository corrections
+
+Update current canonical product metadata and visitor destinations from `reddynitish/loadout` to `VirajMishra1/loadout`:
+
+- README CI workflow badge and image URL.
+- README clone command.
+- README issue-tracker link.
+- `package.json` repository, homepage, and bugs URLs.
+- `docs/evidence/live-checks.schema.json` `$id`.
+- Tests/fixtures that intentionally assert canonical package metadata.
+
+Do not rewrite historical evidence that accurately identifies the fork or dated fork CI runs. Historical links in `docs/REPOSITORY_STABILIZATION.md` remain historical evidence, not canonical product metadata.
+
+## Check failure handling
+
+No workflow bypass is allowed. Do not delete, skip, weaken, or condition the required verification job. The smallest correct repository action is to leave CI logic intact and accurately report the external billing/spending-limit root cause.
+
+Before PR creation:
+
+- Reconfirm the failed check annotation and absence of job steps.
+- Run each intended required job command locally, including the exact `npm test -- --run` invocation.
+- Run `npm run verify`.
+- Run `npm run verify:full` because Playwright dependencies are available locally.
+- Treat any local failure as a real defect and fix it test-first; do not call the external billing annotation a locally reproduced failure.
+
+## Regression and rendering coverage
+
+Update README-focused tests only for intended structure/content changes:
+
+- require the new hero reference and genuine metaphor language;
+- require canonical Viraj badge/clone/issue destinations;
+- reject canonical README/package links to the temporary fork;
+- preserve all six generated marker pairs, current hierarchy, executable offline product flow, warnings, and truth-boundary assertions.
+
+Update package metadata tests for Viraj's canonical repository. Do not add a test that pretends GitHub billing can be reproduced locally.
+
+Validate all README relative targets and heading fragments, SVG XML/accessibility structure, forbidden external SVG content, and light/dark renders at desktop and mobile sizes. Review the complete README as a first-time visitor for hierarchy, clarity, and unsupported implications.
+
+## Delivery
+
+Commit implementation on `codex/relatable-readme-hero`, push it to Viraj's repository, and open a ready pull request against `main`. Include the Actions billing root cause, local command evidence, rendered hero evidence, and truth boundaries in the PR body. Do not merge the pull request.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadout-ai",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "private": false,
   "license": "MIT",
   "description": "Universal upgrade manager for AI coding agents",
@@ -16,7 +16,6 @@
     "README.md",
     "CHANGELOG.md",
     "MASTER_PLAN.md",
-    "SIMPLE_PLAN.md",
     "SECURITY.md",
     "LICENSE"
   ],
@@ -55,13 +54,18 @@
     "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",
     "test:package": "node scripts/package-smoke.mjs",
     "pretest:performance": "npm run build",
     "test:performance": "node scripts/scan-benchmark.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "check:evidence": "node scripts/check-catalog-attribution.mjs && node scripts/check-discovery-artifacts.mjs && node --import tsx scripts/check-release-claims.ts",
+    "readme:update": "node scripts/update-readme-facts.mjs",
+    "readme:check": "node scripts/update-readme-facts.mjs --check",
+    "check:readme-claims": "npm run build && node scripts/check-readme-claims.mjs",
+    "check:live": "node scripts/check-live-evidence.mjs",
+    "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:package && npm run test:performance",
+    "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"
   },
   "dependencies": {

package/SIMPLE_PLAN.md

@@ -1,44 +0,0 @@
-# Loadout plan — simple version
-
-Loadout's primary experience is CLI-first:
-
-```bash
-npx loadout-ai
-```
-
-It detects installed agents, scans the actual skills already present, and recommends a
-small Stable foundation. Maximum Library and Custom are explicit alternatives. It
-previews reviewed pinned sources, exact overlaps, capacity, and safety findings before
-one rollback-safe transaction. The dashboard is optional diagnostics.
-
-Loadout also provides the package-manager operations:
-
-- Find, install, update, remove, create, share, and synchronize AI-agent add-ons.
-- Work with skills, commands, rules, agents, plugins, and MCP tools.
-- Support Codex, Claude Code, Cursor, and more from one setup file.
-
-Loadout's four major advantages are:
-
-1. **Safety:** scan first, explain every change, block dangerous behavior, and never
-   touch unrelated files.
-2. **Recovery:** back up before changes and provide one-command undo.
-3. **Guidance:** check setup health and recommend tested add-on collections for the
-   user's project.
-4. **Optimization:** keep a broad reviewed library but expose only the best supported,
-   non-overlapping active set for the current agent and project.
-
-The original build order was:
-
-1. Finish the reliable package-manager foundation.
-2. Match OpenPackage's package types, sources, synchronization, and publishing.
-3. Add health checks, security scanning, safe updates, recommendations, and profiles.
-4. Keep the dashboard optional and prove every supported platform with tests.
-
-That foundation is now integrated on `main`. [MASTER_PLAN.md](./MASTER_PLAN.md) is the
-only canonical checklist; contributor branches and notes are historical inputs, not
-separate sources of project status. Phase 12 now tracks provenance for unmanaged
-skills, evidence-backed comparison, library-versus-active-set state, safe adoption and
-enable/disable, project activation, guided optimization, category evaluations, daily
-review queues, provider/MCP workflows, CLI polish, npm publication, and public-beta
-testing. Catalog expansion, legal review, keychains, additional adapters, and submission
-work remain explicit rather than hidden behind earlier checked implementation proofs.

package/docs/plans/2026-07-18-release-0.3.md

@@ -1,42 +0,0 @@
-# Loadout 0.3 Product-Hardening Plan
-
-## Goal
-
-Ship a user-testable CLI release with one-command cleanup, honest whole-profile update
-checks, explicit no-key MCP discovery, and a verified local dashboard.
-
-## Public contracts
-
-1. `loadout uninstall` is a preview. `loadout uninstall --yes` removes scheduled
-   Loadout jobs, runtime tools, managed agent files, disabled library copies, cache,
-   snapshots, and state while preserving unmanaged or modified files. `--remove-cli`
-   additionally runs the global npm uninstall.
-2. `loadout update` checks every tracked package and compares the last installed
-   Stable/Power/Maximum profile with the current trusted catalog. It never mutates by
-   default.
-3. `loadout update --yes` reapplies trusted profile changes and applies all
-   statically-safe active package updates; blocked, disabled, or failed updates are
-   reported and skipped. `--package <id> --yes` remains the precise path.
-4. Stable, Power, and Maximum are re-evaluated against the trusted catalog whenever
-   `update` runs. Discovery can nominate new candidates daily, but candidates cannot
-   enter a profile until immutable source, license, compatibility, and safety review
-   are recorded.
-5. `loadout mcp-recipe --no-key` lists reviewed recipes requiring no separately
-   billed AI/model API key. It includes GitHub read-only while separately disclosing
-   the GitHub token. `--credential-free` is the stricter zero-credential filter.
-6. `loadout dashboard` remains loopback-only and is verified by the browser E2E test.
-
-## Implementation sequence
-
-- [x] Add failing tests for uninstall preview/application and CLI help.
-- [x] Implement uninstall orchestration with dependency injection and path guards.
-- [x] Add failing tests for persisted profile state and profile drift reporting.
-- [x] Record setup mode in snapshot-restorable install state and include it in update.
-- [x] Add failing tests for bulk safe update selection and clear skipped results.
-- [x] Implement `update --yes`, retaining `--apply` as a compatible alias.
-- [x] Add and test Chrome DevTools as a pinned no-key MCP recipe.
-- [x] Add `mcp-recipe --no-key` and beginner-readable recipe output.
-- [x] Update README, test guide, master plan, changelog, completion, and version.
-- [ ] Run unit, lint, type, evidence, package, CLI E2E, performance, dashboard E2E,
-      and npm dry-run gates.
-- [ ] Review, commit, merge to main, push, tag, and publish to npm.

package/docs/superpowers/plans/2026-07-18-cli-ux-polish.md

@@ -1,86 +0,0 @@
-# CLI UX Polish Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use `executing-plans` to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make Loadout's everyday CLI path understandable for a first-time user while preserving its existing safe, advanced capabilities.
-
-**Architecture:** Keep the CLI as the primary interface. Add one concise, read-only `guide` command and a focused help footer; retain advanced commands but remove them from the first-screen help. Fix JSON output and package-scoped update previews as explicit public CLI contracts. Document a safe test journey and keep the dashboard as an optional local companion.
-
-**Tech Stack:** Node.js 20+, TypeScript, Commander, Vitest, framework-free local dashboard.
-
-## Global Constraints
-
-- Never mutate a user's agent configuration from a default or preview command.
-- Existing command names remain valid even if hidden from first-screen help.
-- Machine-readable commands must emit valid JSON when `--json` is accepted.
-- Do not require an API key or GitHub account for the core test journey.
-- Every behavior change gets a test before its production code.
-
----
-
-### Task 1: Define the beginner CLI contract
-
-**Files:**
-
-- Modify: `tests/cli-help.test.ts`
-- Modify: `src/cli.ts`
-
-**Interfaces:**
-
-- Produces: `loadout guide`, a read-only command that explains setup, discovery, project recommendations, recovery, dashboard, and help.
-
-- [x] **Step 1: Write failing CLI contract tests** for `loadout guide`, a focused top-level help footer, and retained access to an advanced command.
-- [x] **Step 2: Run** `npm test -- tests/cli-help.test.ts` **and confirm the new assertions fail.**
-- [x] **Step 3: Implement** `guide`, hide maintainer-only commands from first-screen help, and add a short help footer that points to the guide.
-- [x] **Step 4: Run** `npm test -- tests/cli-help.test.ts` **and confirm it passes.**
-- [ ] **Step 5: Commit** the focused CLI discoverability change.
-
-### Task 2: Repair machine-readable and scoped preview contracts
-
-**Files:**
-
-- Modify: `tests/cli-help.test.ts`
-- Modify: `tests/update.test.ts`
-- Modify: `src/cli.ts`
-- Modify: `src/core/update.ts`
-
-**Interfaces:**
-
-- `loadout catalog --json` returns a JSON array.
-- `loadout update --package <id>` plans only that managed package and rejects an unknown installed package clearly.
-
-- [x] **Step 1: Write failing tests** for catalog JSON and package-scoped update planning.
-- [x] **Step 2: Run the focused test files** and confirm the assertions fail for the existing implementation.
-- [x] **Step 3: Implement the smallest compatible fixes.**
-- [x] **Step 4: Run the focused tests** and confirm they pass.
-- [ ] **Step 5: Commit** the contract fixes separately.
-
-### Task 3: Record user testing and current product scope
-
-**Files:**
-
-- Create: `docs/USER_TEST_GUIDE.md`
-- Modify: `MASTER_PLAN.md`
-
-**Interfaces:**
-
-- The guide gives a real-profile-safe order of commands, says which commands change state, and gives rollback instructions.
-- `MASTER_PLAN.md` begins with the one authoritative unfinished-work section and moves stale immediate tasks out of the active path.
-
-- [x] **Step 1: Add a concise user testing guide** for daily use, discovery, optional dashboard, safe mutation, rollback, and advanced validation.
-- [x] **Step 2: Add the current remaining work section** and mark historic, non-essential ideas as deferred rather than pretending they are active product requirements.
-- [x] **Step 3: Run markdown and CLI smoke checks** to make sure command names match the real surface.
-- [ ] **Step 4: Commit** documentation separately.
-
-### Task 4: Validate the actual user journey
-
-**Files:**
-
-- Test: `tests/cli-help.test.ts`
-- Test: `tests/update.test.ts`
-- Test: `tests/dashboard.test.ts`
-
-- [x] **Step 1: Build and run** the CLI guide, catalog JSON, health, library, project recommendation preview, and dashboard endpoint checks without changing agent files.
-- [ ] **Step 2: Run** `npm run verify:full` **and inspect every failure if any.**
-- [ ] **Step 3: Review the diff for accidental profile/cache/secrets changes.**
-- [ ] **Step 4: Commit, then present the exact install/test/recovery commands to the user.**