loadout-ai 0.9.1 → 0.9.3

package/docs/superpowers/specs/2026-09-07-readme-and-unified-hero-design.md

@@ -0,0 +1,135 @@
+# README and unified hero design
+
+## Goal
+
+Make Loadout understandable to a first-time visitor in under 30 seconds, give
+that visitor a safe first success in under five minutes, and provide one
+shareable product image that explains the complete workflow.
+
+The target reader is a developer who uses at least one AI coding agent and may
+use Claude Code and Codex together. The README should assume no knowledge of
+Loadout's internal terminology.
+
+## Reference lessons
+
+- [Graphify](https://github.com/Graphify-Labs/graphify) leads with one concrete
+  outcome, reaches the install command immediately, shows what the command
+  produces, and moves detail below the first success.
+- [Wander Agent](https://github.com/VirajMishra1/wander-agent) uses plain
+  language, copyable examples, visible outcomes, and setup paths organized by
+  the tool the reader already uses.
+
+Loadout will adopt those information-design principles without copying their
+text or structure verbatim.
+
+## Unified hero image
+
+Create one 16:9, white-background, hand-drawn infographic in the visual style
+of the two current product diagrams. It must remain legible when rendered at
+960 pixels wide on GitHub and when used as an X link preview.
+
+The layout has two related lanes:
+
+1. The extension lifecycle: **Discover -> Curate -> Activate**.
+   - Discover: `skills • tools • MCP`
+   - Curate: `screened • pinned • reversible`
+   - Activate: `right tools for this repo`
+   - The curator skill is represented inside the Curate stage, not as a sixth
+     unrelated product concept.
+2. The two-agent workflow: **Claude Code <-> Loadout <-> Codex**.
+   - Handoff: `durable tasks + bundled context`
+   - Coordinate: `ownership • contracts • decisions`
+
+Use the exact headline `YOUR TOOLS. YOUR AGENTS. ONE LOADOUT.` and the exact footer
+`Preview every change • Roll back anytime • Full audit trail`.
+
+Use restrained purple, blue, orange, and green accents with dark readable
+lettering. Avoid gradients, tiny explanatory prose, fake UI screenshots,
+unsupported metrics, star counts, and absolute novelty claims. The image
+should communicate the combined workflow rather than claim that no related
+project exists.
+
+Generate the bitmap with the built-in image generator, inspect it for text and
+layout accuracy, and save the accepted result as a new versioned asset under
+`docs/assets/`. Preserve the existing two images as historical assets unless a
+later cleanup explicitly removes them.
+
+## README information architecture
+
+The README is a tutorial-first front page with reference material below it.
+Use this order:
+
+1. Centered project name, the truthful value proposition **Manage skills for
+   12 coding agents. Hand off and coordinate work between Claude Code and
+   Codex.**, badges, and the unified hero.
+2. **Try it in 30 seconds**: install Loadout, preview the Stable loadout, and
+   explain that the preview command changes no agent files. Do not imply that
+   the preceding global npm installation changes nothing.
+3. **What Loadout does**: five short capabilities—discover, curate, activate,
+   handoff, coordinate—with one outcome each.
+4. **Use Claude Code and Codex together**: a minimal handoff example followed
+   by a minimal coordination example. State clearly that this is structured
+   shared project state, not a merged context window or uninterrupted model
+   conversation.
+5. **Try these prompts**: plain-language requests a user can paste into an
+   agent after installing the curator and handoff skills.
+6. **Install and choose your agent**: the recommended npm installation first,
+   the preview and apply commands, then `loadout status` as a concrete success
+   check. Follow with concise agent-specific guidance and links to detailed
+   documentation.
+7. **Safety and trust**: preview-first behavior, pinned sources, secret-redacted
+   bounded bundles, snapshots, rollback, and the audit trail.
+8. **Proof and demo**: keep the clickable YouTube thumbnail because it is a
+   playable demonstration, not a second product explainer. Keep factual claims
+   tied to the existing evidence manifest and generated discovery block.
+9. **Reference**: compact command table, supported agents, profiles, and links
+   to full guides.
+10. **Community**: contribution, security, attribution, and license links.
+
+The README will use only the new unified product infographic. Existing product
+diagrams will no longer be embedded. The YouTube preview and small status
+badges are exempt because they serve navigation and proof rather than explain
+the product architecture.
+
+## Writing rules
+
+- Lead with the outcome, then show the command, then explain the machinery.
+- Use short sentences and familiar words.
+- Keep the recommended path visible; move edge cases to linked guides.
+- Prefer one realistic command block over several near-duplicates.
+- Explain `handoff` and `coordinate` separately before contrasting them.
+- Put the optional Loadout skill installation before natural-language prompts
+  that depend on those skills.
+- Do not describe coordination as shared memory, a merged context window, or
+  agents talking continuously.
+- Do not use hype words such as revolutionary, game-changing, or first-ever.
+- Keep the README within the existing 425-line test budget and aim materially
+  below it.
+
+## Validation
+
+- Update README tests to require exactly one local product explainer image and
+  its complete alt text while allowing the remote YouTube thumbnail and badges.
+- Preserve generated README marker pairs and evidence-backed claims.
+- Run the focused README test, README end-to-end journey, documented-command
+  check, evidence check, formatting check, and full project verification.
+- Render or inspect the new hero at full size and at the README display width;
+  reject it if any required text is misspelled or visually cramped.
+- Verify every documented command against the current CLI before publishing.
+
+## Out of scope
+
+- Changing Loadout runtime behavior or the coordination protocol.
+- Claiming market uniqueness or adding unverified benchmarks.
+- Removing detailed guides that advanced users already rely on.
+- Publishing a release or social post as part of this documentation change.
+
+## Two-agent review outcome
+
+A bounded Claude Code and Codex review agreed on the central changes: unify the
+product identity, move the safe preview above feature detail, remove repeated
+handoff demonstrations and the abridged transcript, show five capabilities in
+one compact section, and keep one explainer image. It also identified two copy
+risks now resolved by this spec: do not imply universal agent compatibility,
+and scope the “nothing changes” promise to the preview command rather than the
+global package installation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadout-ai",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "private": false,
   "license": "MIT",
   "description": "The package manager for AI coding agent extensions",

package/docs/DEMO_SCRIPT.md

@@ -1,152 +0,0 @@
-# Loadout demo and voiceover
-
-Target length: **2:35 to 2:50**. Record the real CLI, cut fetch waits and typing, and do
-not show the retired dashboard. The final YouTube upload must be public.
-
-## Before recording
-
-1. Close terminals that show tokens, private paths you do not want public, or unrelated
-   work. Increase terminal font size and use a window about 120 columns wide.
-2. Confirm the release and product health:
-
-   ```bash
-   npm install --global loadout-ai@0.9.0
-   hash -r
-   loadout --version
-   loadout health
-   ```
-
-3. Finish the remaining founder acceptance path before recording. Keep the useful
-   successful output in terminal history, but start the recording from a clean prompt.
-4. Rehearse the voiceover once. Use macOS Screenshot (`Shift-Command-5`) with your
-   microphone, OBS, or another recorder. Record at normal speed; speed the final cut
-   to 1.1x only if necessary.
-
-## Shot list and exact narration
-
-### 0:00 to 0:15: the problem
-
-**Screen:** README hero, then a terminal showing `loadout --version`.
-
-**Say:**
-
-> AI coding extensions are scattered across GitHub. You find a skill on X, an MCP
-> server on Reddit, copy it into one agent, and later have no idea where it came from
-> or how to undo it. I built Loadout: one local CLI to discover, inspect, install,
-> update, and roll back agent extensions across Codex, Claude Code, and other agents.
-
-### 0:15 to 0:50: one safe install
-
-**Screen:** Run the preview, then apply. Cut the fetch wait, not the result.
-
-```bash
-loadout setup --mode stable --agents codex,claude-code --api-access none
-loadout setup --mode stable --agents codex,claude-code --api-access none --yes
-```
-
-**Say:**
-
-> Stable selects thirty useful skill directories per agent from four pinned public
-> sources. The first run is a preview: it shows the sources, targets, credentials, and
-> safety findings without changing agent files. When I approve it, Loadout applies one
-> transaction and gives me a rollback snapshot. My ChatGPT and Claude subscriptions
-> are not treated as API keys, and normal skill setup does not need one.
-
-### 0:50 to 1:12: see what changed and undo it
-
-**Screen:**
-
-```bash
-loadout scan
-loadout status
-loadout rollback --list
-loadout rollback --snapshot <stable-snapshot-id>
-```
-
-**Say:**
-
-> Scan separates Loadout-managed skills from files I already had. Status keeps source
-> and version ownership, and rollback restores the exact pre-install snapshot while
-> preserving unrelated skills. I use the exact snapshot ID shown by the install, so
-> there is no ambiguity. Complete uninstall is available too.
-
-### 1:12 to 1:42: broad catalog, focused project
-
-**Screen:** Show the profile choices, catalog coverage, and a real project
-recommendation. These commands are read-only and do not require a prepared Maximum
-library.
-
-```bash
-loadout profiles
-loadout catalog --coverage
-loadout recommend --project . --agent codex
-```
-
-**Say:**
-
-> Loadout has three useful levels. Stable installs a bounded daily set. Power is
-> broader. Maximum keeps a large screened library disabled instead of dumping every
-> skill into every prompt. For this TypeScript CLI, the project recommender proposes
-> tools for documentation, testing, security, and MCP work without changing anything.
-
-### 1:42 to 2:05: MCP, tools, and custom skills
-
-**Screen:**
-
-```bash
-loadout mcp-recipe --credential-free
-loadout mcp-recipe playwright --agent codex
-loadout tool graphify --agents codex,claude-code
-loadout install --mode custom --package humanizer --agents codex
-```
-
-**Say:**
-
-> MCP servers and executable tools are never hidden inside a profile. Playwright is a
-> separately previewed MCP recipe; Graphify is a pinned runtime tool; and a catalog
-> skill such as Humanizer can be installed directly through Custom mode. Each path
-> discloses permissions and credentials before approval.
-
-### 2:05 to 2:28: hand work from Claude Code to Codex
-
-**Screen:**
-
-```bash
-loadout skills install loadout-handoff --yes
-loadout handoff codex "write tests for the auth module" --context "see src/auth.ts"
-loadout handoff
-```
-
-**Say:**
-
-> Loadout also gives Claude Code and Codex a tiny shared handoff log. Claude can leave
-> a bounded task with context, and Codex sees it when the next session checks its
-> inbox. It is intentionally a local file workflow—not a background service or a live
-> chat channel.
-
-### 2:28 to 2:48: close
-
-**Screen:** Return to the README hero and the handoff row in the workflow image.
-
-**Say:**
-
-> Loadout stays local and does not require an LLM API key to manage skills. One CLI
-> gives your coding agents a setup you can inspect, improve, pass work through, and
-> undo. Agent extensions, under control.
-
-## Final edit and upload
-
-- Remove loading screens, typing pauses, repeated commands, notifications, and secrets.
-- Keep terminal output readable at 1080p; do not use a synthetic dashboard or mock data.
-- Add a small title card: **Loadout: Agent extensions, under control.**
-- Export under three minutes and upload publicly to YouTube.
-- Watch the uploaded video once, confirm audio and text are legible, then paste the
-  exact public URL into the README.
-
-## Submission checklist
-
-- [ ] Public YouTube video is under three minutes and its URL opens signed out.
-- [ ] Voiceover shows preview, rollback, and Claude Code ↔ Codex handoff.
-- [ ] Repository and npm links open in a signed-out browser.
-- [ ] README installation and user-test paths match the published version.
-- [ ] No terminal frame exposes tokens, usernames, or private repository names.