loadout-ai 0.5.6 → 0.5.8

package/CHANGELOG.md

@@ -2,6 +2,29 @@
 
 ## Unreleased
 
+## 0.5.8 - 2026-07-21
+
+### Fixed
+
+- Make `install --mode custom` genuinely additive: it now keeps existing managed
+  skills active and does not replace the saved profile.
+
+## 0.5.7 - 2026-07-21
+
+### Changed
+
+- Explain that `setup --mode custom` reconciles the complete selected profile, while
+  `install --mode custom --package <id>` adds a package without retiring the current
+  managed profile.
+- Show package-by-package progress during complete uninstall and stop calling an
+  approved `uninstall --yes` operation a dry run.
+
+### Fixed
+
+- Preserve pre-existing skill trees that users explicitly adopted into Loadout when
+  removing one package or completely uninstalling Loadout. Removal now forgets
+  ownership and leaves adopted bytes in place, including legacy `adopted-*` records.
+
 ## 0.5.6 - 2026-07-21
 
 ### Changed

package/MASTER_PLAN.md

@@ -6,12 +6,78 @@ 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 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
-every speculative system before users can test Loadout. Completed implementation
-plans and contributor-specific plans have been consolidated here and removed.
+## Launch finish line (authoritative, July 21, 2026)
+
+This is the only active checklist. Everything under **Archived implementation
+history** is evidence of how the product was built, not unfinished launch scope.
+
+### Product complete
+
+- [x] Publish the CLI as `loadout-ai@0.5.8`; keep the product usable without cloning
+      this repository or providing an OpenAI/Anthropic API key.
+- [x] Ship Stable, Power, Maximum, and Custom profiles with preview-first apply,
+      snapshots, drift protection, explicit rollback, removal, and complete uninstall.
+- [x] Detect and manage skills across supported agent adapters while preserving
+      unrelated and unmanaged files.
+- [x] Ship a 53-source pinned catalog, daily read-only discovery/update checks,
+      existing-skill reconciliation, and project-aware recommendation/optimization.
+- [x] Credit and support the MIT Humanizer and Obsidian Skills sources. Humanizer is
+      available through Custom mode; Obsidian is recommended for detected vaults.
+- [x] Ship three explicit MCP recipes for Playwright, Chrome DevTools, and read-only
+      GitHub, plus the separately reviewed Graphify runtime-tool recipe.
+- [x] Remove the conflicting dashboard and make the CLI the only product surface.
+- [x] Publish clear npm setup, testing, upstream attribution, trust boundaries, and a
+      detailed account of how Codex and GPT-5.6 were used in the README.
+- [x] Pass the complete local release gate and the latest hosted CI run on `main`.
+- [x] Preserve pre-existing adopted skills during removal and complete uninstall;
+      distinguish additive Custom installation from whole-profile Custom setup, and
+      show truthful progress during large approved uninstalls.
+
+### Final founder acceptance
+
+- [x] Install the exact public npm release, verify `loadout --version`, and scan the
+      founder's restored real profiles. Stable, Power, Maximum, project optimization,
+      Humanizer, Graphify, both-host Playwright MCP lifecycles, rollback, complete
+      uninstall, and clean reinstall were exercised during founder acceptance.
+- [x] Keep the GitHub repository name `loadout`. The product remains **Loadout** and
+      the npm package/CLI identities remain `loadout-ai` / `loadout`.
+- [x] Record explicit decisions for all six `NOASSERTION` sources in
+      `docs/UPSTREAM_LICENSE_DECISIONS.md` without inventing a license claim.
+
+### Submission work
+
+- [ ] Record the real CLI demo using `docs/DEMO_SCRIPT.md`; keep it under three
+      minutes, include a voiceover, upload it publicly to YouTube, and verify the URL.
+- [ ] Replace the README demo placeholder with the final YouTube link.
+- [ ] In the voiceover, explain what Loadout does and how Codex and GPT-5.6 were used.
+- [ ] Run `/feedback` in Codex, copy the resulting session ID, and enter it in Devpost.
+- [x] Confirm the public repository URL is accessible to Devpost and OpenAI.
+- [x] Confirm all team invitations are accepted. Both teammates are collaborators and
+      there are no pending repository invitations.
+- [ ] Select **Developer Tools**, complete the edited Devpost description, and submit
+      rather than leaving a draft.
+
+### Deliberately not part of this submission
+
+These are not launch blockers and should not be rebuilt before submission:
+
+- A dashboard or second frontend surface.
+- Hosted accounts, GitHub OAuth, cloud sync, analytics, or enterprise administration.
+- Automatic installation of newly discovered projects or arbitrary third-party
+  installer execution.
+- A universal quality score, fabricated benchmark results, or automatic claims that
+  stars prove safety or usefulness.
+- A production-hosted signed intelligence service, a second executable runtime tool,
+  speculative adapter features without user demand, or ten external user studies.
+- Restoring GitHub-hosted Actions capacity before submission; the full gate can run
+  locally, and the latest completed `main` CI is already passing.
+
+## Archived current-status diary (historical, not active scope)
+
+This section preserves the chronological implementation and founder-testing record.
+Its unchecked boxes may describe older release numbers, superseded acceptance paths,
+external research, or intentionally deferred work. They are not active launch tasks;
+use the launch finish line above.
 
 ### Implemented product work
 
@@ -2135,7 +2201,7 @@ small PRs, no long-lived branches.
 
 ## 25. Immediate next tasks
 
-Use the `Current remaining work` section at the top of this document. The next action
-is founder acceptance testing with `docs/USER_TEST_GUIDE.md`; do not add a new hosted
-service, provider dependency, or frontend surface until an observed user-testing issue
-justifies it.
+Use **Launch finish line** at the top of this document. The next actions are the short
+founder acceptance remainder, the recorded demo, `/feedback`, and Devpost submission.
+Do not add a hosted service, provider dependency, dashboard, or speculative feature
+before the deadline.

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <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">
+  <img src="./docs/assets/loadout-workflow.png" alt="Loadout discovers skills, tools, and MCP servers, keeps them in a screened library, matches an active set to each project, and manages them across AI coding agents." width="960">
 </p>
 
 <h1 align="center">Loadout</h1>
@@ -7,36 +7,50 @@
 <p align="center"><strong>Agent extensions, under control.</strong></p>
 
 <p align="center">
-  A local CLI for inspecting, previewing, installing, and undoing managed extensions for AI coding agents.
+  <strong>The package manager for your AI coding setup.</strong><br>
+  Discover broadly. Activate the right tools for each project. Stay current without starting over.
 </p>
 
 <p align="center">
   <a href="https://github.com/VirajMishra1/loadout/actions/workflows/ci.yml"><img src="https://github.com/VirajMishra1/loadout/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="https://www.npmjs.com/package/loadout-ai"><img src="https://img.shields.io/npm/v/loadout-ai?color=cb3837&amp;logo=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/loadout-ai"><img src="https://img.shields.io/npm/dm/loadout-ai?color=cb3837&amp;label=downloads" alt="npm downloads"></a>
+  <a href="https://github.com/VirajMishra1/loadout"><img src="https://img.shields.io/github/stars/VirajMishra1/loadout?style=flat&amp;logo=github" alt="GitHub stars"></a>
   <a href="./package.json"><img src="https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&amp;logoColor=white" alt="Node.js 20 or newer"></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
 </p>
 
 <p align="center">
-  <a href="#how-it-works">How it works</a> ·
   <a href="#install">Install</a> ·
+  <a href="#why-loadout">Why Loadout</a> ·
   <a href="#profiles">Profiles</a> ·
+  <a href="#catalog-and-discovery">Discover</a> ·
   <a href="#trust-and-limits">Trust</a> ·
-  <a href="#command-reference">Commands</a> ·
-  <a href="#development">Development</a>
+  <a href="#command-reference">Commands</a>
 </p>
 
-> [!IMPORTANT]
-> Installation is version-pinned so the code you test matches these docs. The commands below target `loadout-ai@0.5.6`; review the preview before every apply.
+## Install
+
+You need Node.js 20 or newer and Git.
+
+```bash
+npm install --global loadout-ai@0.5.8
+loadout setup --mode stable
+```
+
+The second command detects your agents and previews the 30-skill Stable loadout.
+Nothing changes until you approve it. If anything goes wrong, start with the
+[user test guide](./docs/USER_TEST_GUIDE.md).
 
 ## How it works
 
 **Choose -> Inspect -> Preview -> Apply -> Undo**
 
-1. **Choose** a bounded profile or explicit packages.
-2. **Inspect** pinned source and catalog metadata separately before setup.
-3. **Preview** detected agents, aggregate repository, directory, and collision counts, warnings, skipped entries, and package IDs needing approval without changing agent target files.
-4. **Apply** by rerunning with `--yes`; Loadout recomputes from current state before using a snapshot-backed transaction.
-5. **Undo** the latest supported mutation with drift checks that protect later edits.
+1. **Choose** Stable, Power, Maximum, or your own package list.
+2. **Inspect** where each extension comes from and what it can do.
+3. **Preview** every planned change without changing agent files.
+4. **Apply** with `--yes`; Loadout saves a rollback snapshot first.
+5. **Undo** with `loadout rollback` if you change your mind.
 
 ### Abridged terminal transcript
 
@@ -61,47 +75,70 @@ Restored snapshot <snapshot-id>
 
 The final preview sentence above is captured CLI wording. A later `--yes` invocation recomputes the plan from pinned sources and current agent and filesystem state; it does not persist or prove identity with the earlier preview.
 
-Preview may populate Loadout's own cache; it leaves agent target files unchanged. Review its aggregate counts, warnings, skipped entries, and package IDs needing approval before deciding whether to run a later apply command.
+Preview may fill Loadout's private download cache, but it does not change your agent
+files. Review the summary and warnings before approving an apply command.
 
 ## Why Loadout
 
-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.
+Loadout started with a frustrating question: **why does improving an AI coding agent
+still mean opening twenty GitHub tabs?**
 
-- **One managed inventory.** List installed packages, inspect drift, and track what Loadout owns across configured agent paths.
-- **Preview by default.** Setup, updates, removal, MCP recipes, and uninstall expose a plan before their supported writes.
-- **Recoverable changes.** Snapshots and managed-file hashes support rollback while refusing to overwrite later user edits.
+Useful skills, plugins, MCP servers, and settings arrive one experiment at a time.
+Soon it is hard to remember what is installed, where it came from, whether something
+better launched yesterday, or how to undo a change. The name comes from games, where
+your loadout is the set of tools you choose for the mission. This does the same for AI
+coding agents without making you rebuild the setup for every agent and every project.
 
-## Install
+Most extension tools begin with a repo you already know. Loadout begins one step
+earlier: **what is actually worth knowing?** It stays with you after installation.
 
-You need Node.js 20 or newer and Git.
+Loadout watches a much wider catalog than it activates. You can keep thousands of
+technically screened skill copies in the disabled Maximum library, discover new projects as
+they appear, and let each codebase pull a focused active set instead of dumping
+everything into every prompt.
 
-```bash
-npm install --global loadout-ai@0.5.6
-loadout --version
-loadout guide
-```
+| The usual workflow                                             | The Loadout workflow                                             |
+| -------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Find recommendations across feeds and bookmarks                | Watch one growing discovery catalog                              |
+| Open every repo and guess whether to trust it                  | Inspect pinned sources, licenses, components, and risk findings  |
+| Copy skills separately into Claude, Codex, Cursor, and friends | Apply one reviewed selection across detected agents              |
+| Let every skill compete for context forever                    | Keep a bounded daily set or activate skills for this project     |
+| Hope updates do not break anything                             | Preview updates and protect every managed change with a snapshot |
+| Manually remember what was changed                             | Scan, reconcile, remove, roll back, or completely uninstall      |
 
-For source development instead:
-
-```bash
-git clone https://github.com/VirajMishra1/loadout.git
-cd loadout
-npm ci
-npm run build
-npm link
-loadout --version
-```
+Loadout is local, open source, and preview-first. It does not need an OpenAI or
+Anthropic API key to manage skills. MCP servers and executable tools stay behind
+their own explicit setup and permission steps.
 
-For a first read-only preview, run:
+### Demo
 
-```bash
-loadout setup --mode stable
-```
+**Demo video coming here.** The release walkthrough will show the real path, not a
+mock UI: Stable install, cross-agent inventory, project optimization, update and
+discovery checks, MCP setup, Graphify, rollback, and complete uninstall. The exact
+under-three-minute [recording and voiceover script](./docs/DEMO_SCRIPT.md) is public.
 
-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.
+For now, the [end-to-end acceptance guide](./docs/USER_TEST_GUIDE.md) contains the same
+commands you can run yourself.
 
 ## Stable workflow
 
+### Stable Boost: install the essentials and start building
+
+Stable is the recommended daily driver: **30 selected skill directories from four
+pinned public sources**, installed into each agent you choose. It covers planning,
+implementation, debugging, testing, documentation, code review, frontend work,
+performance, Git, shipping, and more without turning every discovered skill on.
+
+| Included source                                                        | What Stable takes from it                                     | GitHub                                                                                                                                            |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Superpowers](https://github.com/obra/superpowers)                     | Planning, execution, testing, review, verification            | [![GitHub stars](https://img.shields.io/github/stars/obra/superpowers?style=flat&label=stars)](https://github.com/obra/superpowers)               |
+| [Context7](https://github.com/upstash/context7)                        | Current documentation and MCP workflows                       | [![GitHub stars](https://img.shields.io/github/stars/upstash/context7?style=flat&label=stars)](https://github.com/upstash/context7)               |
+| [Addy Osmani Agent Skills](https://github.com/addyosmani/agent-skills) | Engineering, frontend, debugging, performance, docs, shipping | [![GitHub stars](https://img.shields.io/github/stars/addyosmani/agent-skills?style=flat&label=stars)](https://github.com/addyosmani/agent-skills) |
+| [Agent Skills Marketplace](https://github.com/wshobson/agents)         | Architecture, review, error handling, JavaScript, Python      | [![GitHub stars](https://img.shields.io/github/stars/wshobson/agents?style=flat&label=stars)](https://github.com/wshobson/agents)                 |
+
+Every row links directly to the upstream project. Loadout does not claim ownership
+or endorsement; it pins, credits, screens, and selects from their public work.
+
 ```bash
 # Preview for detected agents
 loadout setup --mode stable
@@ -109,18 +146,20 @@ loadout setup --mode stable
 # Recompute from current state and apply after reviewing the preview
 loadout setup --mode stable --yes
 
-# Inspect managed state, then undo the latest supported mutation
-loadout list
-loadout health --explain
+# Inspect managed state, then undo the install if needed
+loadout status
+loadout scan
 loadout rollback
 ```
 
-Stable currently selects 30 skill directories from four pinned, SPDX-identified, policy-selected public sources. Selection policy is evidence, not a claim that the sources are safe, trusted, human-reviewed, benchmarked, or the right choice for every user.
+Stable is Loadout's strongest general starting point, not a claim that one setup is
+best for every person or project. Run `loadout profiles stable --json` when you want
+the machine-readable selection.
 
 ## Manage skills you already have
 
-Loadout can compare existing Claude, Codex, Cursor, and other detected-agent skills
-with complete skill trees from pinned catalog sources:
+Already have skills? Loadout can compare them with exact catalog copies and manage
+the ones it can identify confidently:
 
 ```bash
 # Read-only inventory and source/update comparison
@@ -134,26 +173,84 @@ loadout reconcile --yes
 loadout reconcile --replace-outdated
 ```
 
-Unknown or ambiguous copies remain untouched. Replacing an outdated tree is a
-separate `--replace-outdated --yes` transaction, may require `--approve-risk`, and
-creates one rollback snapshot. Once adopted or replaced, `loadout update` tracks the
-exact upstream repository and skill unit while preserving the agent path already in
-use.
+Unknown or ambiguous copies stay untouched. Replacing an old copy is a separate,
+previewed transaction with its own rollback snapshot. Managed copies can then be
+checked by `loadout update` without moving them to a different agent path.
 
 ## Profiles
 
-| 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                      |
+Loadout is opinionated when you want it to be and precise when you do not.
+
+### Power Boost: a larger cross-project toolkit
+
+Power draws a skill-level allowlist from eight major collections. The prepared set
+is deduplicated and invalid units are quarantined, so the final count can be lower
+than the raw allowlist. In current acceptance testing it prepared about 50 active
+skills per agent.
+
+| Included source                                                          | Focus                                                     | GitHub                                                                                                                                                                      |
+| ------------------------------------------------------------------------ | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Anthropic Skills](https://github.com/anthropics/skills)                 | Documents, frontend, MCP building, web testing            | [![GitHub stars](https://img.shields.io/github/stars/anthropics/skills?style=flat&label=stars)](https://github.com/anthropics/skills)                                       |
+| [OpenAI Skills](https://github.com/openai/skills)                        | CLI, docs, browser work, images, security                 | [![GitHub stars](https://img.shields.io/github/stars/openai/skills?style=flat&label=stars)](https://github.com/openai/skills)                                               |
+| [Vercel Agent Skills](https://github.com/vercel-labs/agent-skills)       | React, web design, composition, deployment                | [![GitHub stars](https://img.shields.io/github/stars/vercel-labs/agent-skills?style=flat&label=stars)](https://github.com/vercel-labs/agent-skills)                         |
+| [Superpowers](https://github.com/obra/superpowers)                       | Planning, debugging, testing, collaboration               | [![GitHub stars](https://img.shields.io/github/stars/obra/superpowers?style=flat&label=stars)](https://github.com/obra/superpowers)                                         |
+| [UI UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | UI systems, slides, styling, product design               | [![GitHub stars](https://img.shields.io/github/stars/nextlevelbuilder/ui-ux-pro-max-skill?style=flat&label=stars)](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) |
+| [Context7](https://github.com/upstash/context7)                          | Current documentation and MCP workflows                   | [![GitHub stars](https://img.shields.io/github/stars/upstash/context7?style=flat&label=stars)](https://github.com/upstash/context7)                                         |
+| [Agent Skills Marketplace](https://github.com/wshobson/agents)           | Architecture, testing, APIs, TypeScript, Python           | [![GitHub stars](https://img.shields.io/github/stars/wshobson/agents?style=flat&label=stars)](https://github.com/wshobson/agents)                                           |
+| [Awesome Copilot](https://github.com/github/awesome-copilot)             | Codebase knowledge, plans, browser and security workflows | [![GitHub stars](https://img.shields.io/github/stars/github/awesome-copilot?style=flat&label=stars)](https://github.com/github/awesome-copilot)                             |
+
+```bash
+loadout setup --mode power
+```
 
-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.
+### Maximum Library: download broadly, activate intelligently
+
+Maximum is for explorers. It downloads every non-archived, technically screened
+skill component in the catalog into Loadout's **disabled local library**. Disabled
+means cached and available, not injected into agent context. Then let the current
+project choose a focused active set:
+
+```bash
+loadout setup --mode maximum
+loadout recommend --project . --agent codex
+loadout optimize --project . --agents codex,claude-code --limit 30
+loadout optimize --project . --agents codex,claude-code --limit 30 --yes
+```
+
+This is the difference between “install everything” and “have everything ready.”
+The first overloads agents; the second gives you a large library with a small,
+relevant active loadout.
+
+### Custom: take exact control
+
+Use `setup` when the listed packages should become the complete managed profile for
+the selected agents. Packages from the previous managed profile that are not listed
+will be retired, and the preview names every retirement:
+
+```bash
+loadout setup --mode custom --package superpowers --package context7
+```
+
+Use `install` when you only want to add a package without replacing the current
+managed profile:
+
+```bash
+
+# Install the reviewed Humanizer writing skill into Codex
+loadout install --mode custom --package humanizer --agents codex
+
+# Install the reviewed Obsidian skills explicitly
+loadout install --mode custom --package obsidian-skills --agents codex,claude-code
+```
+
+Run `loadout profiles` to compare every mode. MCP servers always use a separate
+approval step. Obsidian skills are also proposed automatically when `recommend` or
+`optimize` detects an Obsidian vault; they are not added to the universal Stable set.
 
 ## MCP integrations
 
-MCP servers are not silently started by Stable, Power, or Maximum. List the reviewed recipes and their credential requirements:
+Profiles never start MCP servers silently. First list the available recipes and see
+which ones need credentials:
 
 ```bash
 loadout mcp-recipe
@@ -171,14 +268,15 @@ 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.
+Configuration alone does not start the server. Test a real connection separately
+with `--connect --approve-risk`. Loadout can reference credentials from environment
+variables or the OS keychain without printing their values.
 
 ## 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:
+[Graphify](https://github.com/Graphify-Labs/graphify) is an optional codebase graph
+tool. It installs both a command and an agent skill, so Loadout keeps it separate from
+the normal profiles. It does not require an OpenAI or Anthropic API key:
 
 ```bash
 loadout tool graphify --agents codex,claude-code
@@ -186,11 +284,38 @@ loadout tool graphify --agents codex,claude-code --yes --approve-risk
 loadout tool graphify --remove --agents codex,claude-code --yes --approve-risk
 ```
 
-Graphify is intentionally not hidden inside Stable, Power, or Maximum: executable
-tools always remain an explicit choice.
+Executable tools remain an explicit choice instead of hiding inside a profile.
 
 ## Catalog and discovery
 
+### GitHub moves every day. Your loadout should not stand still.
+
+The catalog is not a frozen “top 50” list. Loadout separates **discovery** from
+**installation** so a viral repo can be noticed quickly without being trusted
+blindly. Candidates enter a review queue; catalog entries are pinned and inspected;
+only the bounded Stable policy gets the strongest automatic recommendation.
+
+```bash
+# Find candidates across configured discovery sources
+loadout discover --source all --queue
+
+# Inspect the queue and one candidate before promotion
+loadout review-queue
+loadout candidate inspect owner/repository
+
+# Check whether managed active or disabled-library sources changed
+loadout update
+loadout health --updates
+```
+
+Daily checks are opt-in and read-only. They tell you what changed; they do not
+silently rewrite your agents:
+
+```bash
+loadout autopilot --yes
+loadout autopilot --status
+```
+
 <!-- loadout:catalog-coverage:start -->
 
 The bundled catalog currently contains **53 credited public repositories** across **39 categories**: **34 have skill components** and **19 are MCP-only**. All 53 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)**.
@@ -228,6 +353,10 @@ The checked-in discovery report proves only its dated snapshot, not the success
 
 <!-- loadout:current-limits:end -->
 
+The six records have an explicit public-release decision rather than an assumed
+license. Read [Upstream license decisions](./docs/UPSTREAM_LICENSE_DECISIONS.md) for
+the source-by-source record and the boundary applied to Power, Maximum, and Custom.
+
 Read the [security policy](./SECURITY.md), [catalog policy](./docs/CATALOG_POLICY.md), and [credential and update policy](./docs/CREDENTIAL_AND_UPDATE_POLICY.md) before trusting third-party content.
 
 ## Agent support
@@ -250,20 +379,99 @@ Configured paths and disposable filesystem lifecycle tests do not prove that nat
 
 ## Command reference
 
-| Job                                | Command                                     |
-| ---------------------------------- | ------------------------------------------- |
-| Guided read-only path              | `loadout guide`                             |
-| Preview or apply a profile         | `loadout setup --mode stable [--yes]`       |
-| List and inspect managed state     | `loadout list`; `loadout health --explain`  |
-| Compare/manage existing skills     | `loadout reconcile [--refresh]`             |
-| Browse or search                   | `loadout catalog`; `loadout search <words>` |
-| Recommend for a project            | `loadout recommend --project .`             |
-| Preview or apply updates           | `loadout update [--yes]`                    |
-| Undo the latest supported mutation | `loadout rollback`                          |
-| Remove one managed package         | `loadout remove <package>`                  |
-| Preview complete removal           | `loadout uninstall`                         |
-| List reviewed MCP integrations     | `loadout mcp-recipe`                        |
-| Discover the full surface          | `loadout --help`; `loadout advanced`        |
+Start at the top and stop whenever Loadout does everything you need.
+
+| Priority | What it does                                                    | Command                                                            |
+| -------: | --------------------------------------------------------------- | ------------------------------------------------------------------ |
+|        1 | Opens the beginner-friendly guided path                         | `loadout guide`                                                    |
+|        2 | Previews the recommended 30-skill daily setup                   | `loadout setup --mode stable`                                      |
+|        3 | Previews the broader Power setup                                | `loadout setup --mode power`                                       |
+|        4 | Downloads the broad screened library, disabled by default       | `loadout setup --mode maximum`                                     |
+|        5 | Shows Loadout-managed packages and active skills                | `loadout status`; `loadout library`                                |
+|        6 | Inventories skills across detected agents without changing them | `loadout scan`                                                     |
+|        7 | Explains what fits the current repository                       | `loadout recommend --project . --agent codex`                      |
+|        8 | Previews a bounded project-specific active set                  | `loadout optimize --project . --limit 30`                          |
+|        9 | Compares existing skills with reviewed catalog copies           | `loadout reconcile --refresh`                                      |
+|       10 | Checks managed active and disabled-library sources for changes  | `loadout update`                                                   |
+|       11 | Finds newly launched or newly popular candidates                | `loadout discover --source all --queue`                            |
+|       12 | Shows candidates waiting for deeper review                      | `loadout review-queue`                                             |
+|       13 | Lists MCP recipes and credential needs                          | `loadout mcp-recipe`; `loadout mcp-recipe --credential-free`       |
+|       14 | Previews an MCP configuration                                   | `loadout mcp-recipe playwright --agent codex`                      |
+|       15 | Lists and installs isolated runtime tools such as Graphify      | `loadout tool`; `loadout tool graphify --agents codex,claude-code` |
+|       16 | Lists snapshots or restores the latest managed change           | `loadout rollback --list`; `loadout rollback`                      |
+|       17 | Previews removal of one managed package                         | `loadout remove <package-id>`                                      |
+|       18 | Previews complete removal of Loadout-managed state              | `loadout uninstall`                                                |
+|       19 | Enables read-only daily discovery and update checks             | `loadout autopilot --yes`                                          |
+|       20 | Shows the complete CLI                                          | `loadout --help`; `loadout advanced`                               |
+
+Most mutating commands are dry runs first. After reading the preview, add `--yes` to
+apply. Commands with executable or connection risk require the additional approval
+shown in their output.
+
+## Built with Codex and GPT-5.6
+
+Loadout was built during OpenAI Build Week by a three-person team working with Codex
+and GPT-5.6. Codex was not a chat box bolted onto the finished project. It was the
+engineering environment we used to plan, build, test, and repeatedly challenge the
+product while it was taking shape.
+
+### From a broad idea to a working product
+
+The starting idea was simple: one install that gives every coding agent the best
+extensions on GitHub. The difficult part was everything hidden inside that sentence.
+What counts as “best”? How much should stay active? What happens to skills a user
+already has? How do you update a repository without silently trusting new code? How
+do you undo changes across several agents?
+
+We used GPT-5.6 through Codex for the repo-wide reasoning behind those decisions.
+Together, we turned the idea into three distinct modes: a bounded Stable daily
+driver, a larger Power setup, and a Maximum library that keeps broad optionality
+without loading thousands of skills into every prompt.
+
+| Part of the build  | How we used Codex and GPT-5.6                                                                                                | What made it into Loadout                                                                                   |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Product planning   | Broke the original idea into testable user journeys and challenged unsafe assumptions                                        | Stable, Power, Maximum, Custom, project optimization, discovery, updates, and complete uninstall            |
+| Architecture       | Traced how catalogs, adapters, agent directories, manifests, and snapshots affect one another                                | A local TypeScript CLI with a shared catalog, 12 agent adapters, and snapshot-backed transactions           |
+| Ecosystem research | Compared repositories, checked source layouts and licenses, and separated popularity from evidence                           | 53 pinned catalog sources plus a discovery snapshot watching 240 repositories                               |
+| Implementation     | Wrote and refactored CLI commands, schemas, source fetchers, installers, active-set logic, and MCP configuration             | The published `loadout-ai` package and the commands documented above                                        |
+| Safety work        | Looked for scripts, hooks, binaries, credential references, target collisions, stale previews, and external edits            | Preview-first changes, quarantined skill units, explicit risk approval, drift protection, and rollback      |
+| Testing            | Generated adversarial cases, reproduced failures from real terminal sessions, and converted them into regression tests       | 625 passing tests, CLI and README end-to-end flows, package smoke tests, and a 1,000-skill performance gate |
+| Team integration   | Audited teammate branches, compared them with `main`, prepared focused pull requests, and checked what was actually complete | One public history instead of three disconnected prototypes                                                 |
+| Release work       | Verified npm contents, version behavior, GitHub metadata, documentation claims, and public CI                                | A public npm package, credited upstream catalog, release evidence, and a reproducible verification command  |
+
+### Real testing changed the code
+
+Codex was most useful when the neat plan met a messy laptop. A few examples:
+
+- A Graphify install appeared in Claude Code but vanished from Codex inventory
+  because the generated runtime skill and the normal skill scanner used different
+  Codex paths. The scan now recognizes managed runtime-tool skills explicitly.
+- Update checks repeatedly timed out on large repositories. We measured the real
+  clone cost, changed the update path to check remote commit metadata first, and only
+  fetch a full snapshot when a pinned source actually changed.
+- Existing unmanaged skills could occupy the same target as a Stable install.
+  Instead of overwriting them, Loadout now stops, scans, compares, and offers a
+  separate reconciliation path for exact or unambiguous matches.
+- ChatGPT and Claude subscriptions were easy to confuse with separately billed API
+  access. Setup now asks about API access explicitly, while credentialed MCP servers
+  remain separate from automatic skill installation.
+
+Those fixes came from a loop we repeated throughout the week: run the real command,
+paste the exact output into Codex, trace the behavior through the codebase, write a
+regression test, fix the smallest responsible layer, and run the full release gate.
+
+### What the team owned
+
+The humans chose the product direction, selected the tradeoffs, reviewed upstream
+projects, tested Loadout on real Codex and Claude Code profiles, approved risky
+operations, and made every release decision. GPT-5.6 helped with high-context design,
+debugging, and review; Codex handled the implementation loop and verification tools.
+Neither replaced human judgment about what should be installed on someone else's
+machine.
+
+Loadout itself does **not** call GPT-5.6 and does not require an OpenAI API key to
+manage skills. Codex and GPT-5.6 helped build the tool; they are not a hidden runtime
+dependency.
 
 ## Development
 
@@ -291,8 +499,8 @@ The repository's mixed README product-flow test uses an isolated build, disposab
 - [Daily discovery snapshot](./docs/DISCOVERED.md)
 - [Candidate inspection and promotion](./docs/CANDIDATE_INTELLIGENCE.md)
 - [Credential and update policy](./docs/CREDENTIAL_AND_UPDATE_POLICY.md)
-- [Repository stabilization record](./docs/REPOSITORY_STABILIZATION.md)
-- [Engineering plan](./MASTER_PLAN.md) and [changelog](./CHANGELOG.md)
+- [Upstream license decisions](./docs/UPSTREAM_LICENSE_DECISIONS.md)
+- [Changelog](./CHANGELOG.md)
 
 ## Contributing, security, and attribution
 

package/dist/src/cli.js

@@ -264,7 +264,7 @@ async function runSetup(options) {
         reader?.close();
     }
 }
-const LOADOUT_VERSION = "0.5.6";
+const LOADOUT_VERSION = "0.5.8";
 function durableSchedulerLauncher() {
     return [
         join(dirname(process.execPath), process.platform === "win32" ? "npx.cmd" : "npx"),
@@ -1020,11 +1020,12 @@ program
     .option("--remove-cli", "also uninstall the global loadout-ai npm command")
     .action(async (options) => {
     const plan = await buildUninstallPlan();
-    console.log(formatUninstallPlan(plan));
+    console.log(formatUninstallPlan(plan, { applying: Boolean(options.yes) }));
     if (!options.yes)
         return;
     const result = await applyUninstall(plan, undefined, {
         force: options.force,
+        onProgress: (message) => console.log(`→ ${message}`),
     });
     console.log(`Removed ${result.removedPackages} managed package(s), ${result.removedRuntimeTools} runtime tool(s), daily jobs, cache, library, and Loadout state.`);
     if (options.removeCli) {
@@ -2710,6 +2711,7 @@ program
         const prepared = await prepareCatalogInstall(setupSelection(options.mode, packageIds), {
             requestedAgents: parseAgentSelection(options.agents),
             onProgress: printSetupProgress,
+            additive: options.mode === "custom",
         });
         console.log(formatPreparedCatalogInstall(prepared, {
             details: options.details,

package/dist/src/core/adopt.js

@@ -195,6 +195,7 @@ export async function applySkillAdoption(plan, options = {}) {
     }, async (freshPlan, snapshot) => {
         await options.beforeRecord?.();
         await recordInstall(freshPlan.installPlan, snapshot.id, {
+            ownershipOrigin: "adopted",
             ...(freshPlan.repository ? { repository: freshPlan.repository } : {}),
             ...(freshPlan.resolvedCommit
                 ? { resolvedCommit: freshPlan.resolvedCommit }

package/dist/src/core/catalog-install.js

@@ -179,7 +179,7 @@ export async function prepareCatalogInstall(selection, options = {}) {
         });
         return false;
     });
-    const reconciliation = selection.mode === "maximum"
+    const reconciliation = selection.mode === "maximum" || options.additive
         ? {
             obsoleteActivationKeys: [],
             obsoletePackageIds: [],
@@ -189,6 +189,7 @@ export async function prepareCatalogInstall(selection, options = {}) {
         : await planManagedProfileReconciliation(usableEntries);
     return {
         selection,
+        additive: options.additive ?? false,
         resolution,
         agents,
         entries: usableEntries,
@@ -217,6 +218,8 @@ export function formatPreparedCatalogInstall(prepared, options = {}) {
         `Separately billed model API access: ${formatModelApiAccess(prepared.access)} (ChatGPT and Claude subscriptions do not count as API access)`,
         "Automatic skill setup does not require an OpenAI, Anthropic, or OpenRouter API key; credentialed MCP/runtime integrations remain explicit and deferred.",
     ];
+    if (prepared.additive)
+        lines.push("Additive install: existing managed skills will stay active.");
     if (directoriesPerAgent > RECOMMENDED_ACTIVE_SKILL_LIMIT)
         lines.push(`Capacity notice: about ${directoriesPerAgent} skill directories per agent exceeds Stable's ${RECOMMENDED_ACTIVE_SKILL_LIMIT}-skill bound.${prepared.selection.mode === "maximum" ? " Maximum stores them in the disabled library; optimize or activate a project-relevant working set." : prepared.selection.mode === "power" ? " Power is the explicit larger active mode; choose Stable or project optimization when lower context use matters." : " Use project-aware activation for a smaller working set."}`);
     if (failures.length)
@@ -263,11 +266,15 @@ export async function applyPreparedCatalogInstall(prepared, options = {}) {
         })
         : applySkillInstallBatch(prepared.entries, [], {
             replaceManagedTargets: true,
-            reconcileManagedTargets: true,
+            reconcileManagedTargets: !prepared.additive,
             ...(prepared.reconciliation
                 ? { expectedReconciliation: prepared.reconciliation }
                 : {}),
-            afterRecord: () => recordInstalledProfile(prepared).then(() => undefined),
+            ...(prepared.additive
+                ? {}
+                : {
+                    afterRecord: () => recordInstalledProfile(prepared).then(() => undefined),
+                }),
         });
 }
 export function formatCatalogApplyGuidance(riskApprovalRequired) {

package/dist/src/core/cli-guide.js

@@ -31,6 +31,10 @@ snapshot before changing managed files. Recover with: loadout rollback
 Reconcile is also read-only unless you add --yes. Exact matches can be managed
 without rewriting them; outdated replacements remain a separate explicit choice.
 
+Setup reconciles the complete selected profile. To add one catalog package without
+retiring the current managed profile, use:
+   loadout install --mode custom --package <id>
+
 Nothing above changes your agents. For the full maintainer/tooling surface, run:
 loadout advanced
 `.trim();

package/dist/src/core/reconcile.js

@@ -237,6 +237,7 @@ export async function applyReconcilePlan(plan, options = {}) {
     const entries = selected.map((item) => ({
         plan: installPlanFor(item, item.status === "outdated"),
         metadata: {
+            ownershipOrigin: "adopted",
             repository: item.candidate.repository,
             resolvedCommit: item.candidate.commit,
             reviewed: true,

package/dist/src/core/remove.js

@@ -11,6 +11,12 @@ export async function planRemove(packageId) {
     const trackedMcp = (state.mcpInstalls ?? []).filter((entry) => entry.packageId === packageId);
     if (!record && !trackedMcp.length)
         throw new Error(`Package is not managed by Loadout: ${packageId}`);
+    // Older releases encoded reconciled/adopted ownership in the generated id.
+    // Preserve that compatibility so upgrading Loadout protects already-adopted
+    // user content even before the new explicit state field has been written.
+    const preserveFiles = Boolean(record &&
+        (record.ownershipOrigin === "adopted" ||
+            record.packageId.startsWith("adopted-")));
     const files = await Promise.all((record?.files ?? []).map(async (file) => {
         const managedPath = managedFileReadPath(packageId, file.path, state.activations ?? []);
         try {
@@ -28,7 +34,9 @@ export async function planRemove(packageId) {
             return { path: managedPath, status: "missing" };
         }
     }));
-    const modified = files.filter((file) => file.status === "modified");
+    const modified = preserveFiles
+        ? []
+        : files.filter((file) => file.status === "modified");
     const mcpServers = await Promise.all(trackedMcp.map(async (entry) => {
         try {
             if (entry.configFormat === "codex-toml") {
@@ -76,6 +84,11 @@ export async function planRemove(packageId) {
     }));
     const modifiedMcp = mcpServers.filter((entry) => entry.status === "modified");
     const warnings = [
+        ...(preserveFiles
+            ? [
+                "This package adopted pre-existing files; removal will forget Loadout ownership and preserve those files in place.",
+            ]
+            : []),
         ...(modified.length
             ? [`${modified.length} managed file(s) were modified outside Loadout.`]
             : []),
@@ -89,6 +102,7 @@ export async function planRemove(packageId) {
         warnings.push("Removal is blocked unless --force is used.");
     return {
         packageId,
+        preserveFiles,
         files,
         mcpServers,
         blocked: modified.length > 0 || modifiedMcp.length > 0,
@@ -103,17 +117,18 @@ export async function applyRemove(plan, options = {}) {
         const existing = fresh.files
             .filter((file) => file.status !== "missing")
             .map((file) => file.path);
+        const removableFiles = fresh.preserveFiles ? [] : existing;
         const configPaths = [
             ...new Set(fresh.mcpServers
                 .filter((entry) => entry.status !== "missing")
                 .map((entry) => entry.configPath)),
         ];
         return {
-            targets: [...existing, ...configPaths, installStatePath()],
-            value: { fresh, existing, configPaths },
+            targets: [...removableFiles, ...configPaths, installStatePath()],
+            value: { fresh, removableFiles, configPaths },
         };
-    }, async ({ fresh, existing, configPaths }) => {
-        for (const file of existing)
+    }, async ({ fresh, removableFiles, configPaths }) => {
+        for (const file of removableFiles)
             await rm(file, { force: true });
         for (const configPath of configPaths) {
             const relevant = fresh.mcpServers.filter((entry) => entry.configPath === configPath && entry.status !== "missing");
@@ -143,7 +158,9 @@ export async function applyRemove(plan, options = {}) {
                 proposed: { ...current, mcpServers: servers },
             });
         }
-        await forgetInstall(plan.packageId);
+        await forgetInstall(plan.packageId, {
+            dropActivations: fresh.preserveFiles,
+        });
     }, { label: `remove ${plan.packageId}` });
     return applied.snapshotId;
 }

package/dist/src/core/state.js

@@ -145,6 +145,9 @@ async function createInstallRecord(plan, snapshotId, metadata = {}) {
     const files = (await Promise.all([...new Set(plan.files.map((file) => file.target))].map(hashDirectory))).flat();
     return {
         packageId: plan.packageId,
+        ...(metadata.ownershipOrigin
+            ? { ownershipOrigin: metadata.ownershipOrigin }
+            : {}),
         ...(metadata.repository ? { repository: metadata.repository } : {}),
         ...(metadata.resolvedCommit
             ? { resolvedCommit: metadata.resolvedCommit }
@@ -311,7 +314,7 @@ export async function recordMcpInstall(record) {
     ];
     await writeInstallState(state);
 }
-export async function forgetInstall(packageId) {
+export async function forgetInstall(packageId, options = {}) {
     const state = await readInstallState();
     const installs = state.installs.filter((entry) => entry.packageId !== packageId);
     const mcpInstalls = (state.mcpInstalls ?? []).filter((entry) => entry.packageId !== packageId);
@@ -323,13 +326,15 @@ export async function forgetInstall(packageId) {
         installs,
         ...(state.profile ? { profile: state.profile } : {}),
         mcpInstalls,
-        activations: (state.activations ?? []).map((entry) => entry.packageId === packageId
-            ? {
-                ...entry,
-                installationState: "removed",
-                activationState: "disabled",
-                updatedAt: new Date().toISOString(),
-            }
-            : entry),
+        activations: options.dropActivations
+            ? (state.activations ?? []).filter((entry) => entry.packageId !== packageId)
+            : (state.activations ?? []).map((entry) => entry.packageId === packageId
+                ? {
+                    ...entry,
+                    installationState: "removed",
+                    activationState: "disabled",
+                    updatedAt: new Date().toISOString(),
+                }
+                : entry),
     });
 }

package/dist/src/core/uninstall.js

@@ -85,19 +85,25 @@ export async function applyUninstall(plan, dependencies = {}, options = {}) {
     if (fresh.blocked && !options.force)
         throw new Error(`Complete uninstall is blocked because managed files were modified. Review them, or re-run with --force. ${fresh.warnings.join(" ")}`);
     for (const id of fresh.runtimeTools) {
+        options.onProgress?.(`Removing runtime tool: ${id}`);
         const runtimePlan = await planRuntimeTool(id, {
             action: "remove",
             stateHome: fresh.stateHome,
         });
         await applyRuntimeToolPlan(runtimePlan, { approveRisk: true });
     }
-    for (const packagePlan of fresh.packages)
+    for (const [index, packagePlan] of fresh.packages.entries()) {
+        options.onProgress?.(`${packagePlan.preserveFiles ? "Forgetting adopted ownership" : "Removing managed package"} [${index + 1}/${fresh.packages.length}]: ${packagePlan.packageId}`);
         await applyRemove(packagePlan, { force: options.force });
+    }
     await removeEmptyManagedDirectories(fresh.packages);
-    if (fresh.schedulers.length)
+    if (fresh.schedulers.length) {
+        options.onProgress?.("Removing daily read-only schedules");
         await (dependencies.unschedule
             ? dependencies.unschedule(fresh.schedulers)
             : applyNativeSchedulerBundle(fresh.schedulers));
+    }
+    options.onProgress?.("Deleting Loadout cache, library, history, and state");
     await rm(fresh.stateHome, { recursive: true, force: true });
     return {
         removedPackages: fresh.packages.length,
@@ -112,7 +118,7 @@ export async function uninstallGlobalCli() {
         windowsHide: true,
     });
 }
-export function formatUninstallPlan(plan) {
+export function formatUninstallPlan(plan, options = {}) {
     const modifiedPaths = plan.packages.flatMap((entry) => entry.files
         .filter((file) => file.status === "modified")
         .map((file) => file.path));
@@ -137,7 +143,13 @@ export function formatUninstallPlan(plan) {
         "",
         ...plan.warnings.map((warning) => `Warning: ${warning}`),
         "",
-        "Dry run only. Re-run with `loadout uninstall --yes` to remove Loadout-managed data.",
-        "Add `--remove-cli` to also uninstall the global npm command.",
+        ...(options.applying
+            ? [
+                "Approved removal is starting. Large libraries can take several minutes; progress will be shown below.",
+            ]
+            : [
+                "Dry run only. Re-run with `loadout uninstall --yes` to remove Loadout-managed data.",
+                "Add `--remove-cli` to also uninstall the global npm command.",
+            ]),
     ].join("\n");
 }

package/dist/src/shared/schemas.js

@@ -269,6 +269,7 @@ const fileHashSchema = z.object({ path: text, sha256 });
 export const installRecordSchema = z
     .object({
     packageId: text,
+    ownershipOrigin: z.enum(["installed", "adopted"]).optional(),
     repository: optionalText,
     resolvedCommit: optionalText,
     targetAgents: z.array(agentIdSchema),

package/docs/DEMO_SCRIPT.md

@@ -0,0 +1,156 @@
+# 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.5.8
+   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:25: today and tomorrow
+
+**Screen:**
+
+```bash
+loadout update
+loadout discover --limit 5
+```
+
+**Say:**
+
+> Update checks managed pinned sources without silently changing them. Discovery
+> watches a wider ecosystem and queues new projects for review, so something going
+> viral can be noticed quickly without being trusted blindly.
+
+### 2:25 to 2:48: Codex, GPT-5.6, and close
+
+**Screen:** README section “Built with Codex and GPT-5.6”, then return to the hero.
+
+**Say:**
+
+> We used Codex and GPT-5.6 throughout the build: architecture, threat modelling,
+> cross-platform implementation, repo-wide debugging, tests, and the real founder
+> acceptance loop. Those tests caught rollback, project-scope, inventory, and update
+> bugs on my actual Codex and Claude profiles. Loadout itself stays local and does not
+> require an OpenAI API key. One command gives your AI agents a loadout you can
+> understand, improve, and undo.
+
+## 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 README and Devpost.
+
+## Submission checklist
+
+- [ ] Public YouTube video is under three minutes and its URL opens signed out.
+- [ ] Voiceover explains the product, Codex usage, and GPT-5.6 usage.
+- [ ] `/feedback` was run in Codex and the session ID is in Devpost.
+- [ ] Repository URL is accessible to Devpost and OpenAI.
+- [ ] README has npm setup and the judge testing path.
+- [ ] Every teammate has accepted the Devpost invitation.
+- [ ] Category is **Developer Tools**.
+- [ ] Submission is submitted, not left as a draft.

package/docs/SUBMISSION_COPY.md

@@ -0,0 +1,90 @@
+# Devpost submission copy
+
+Edit this in your own voice before submitting. Replace the video placeholder and
+check every link while signed out.
+
+## Project name
+
+Loadout
+
+## Tagline
+
+One CLI to discover, install, update, and undo the best extensions for your AI coding
+agents.
+
+## Category
+
+Developer Tools
+
+## Short category and project answer
+
+We are building for the Developer Tools category. Loadout is a local CLI that finds,
+screens, installs, updates, and rolls back skills, MCP servers, and runtime tools
+across Codex, Claude Code, Cursor, and other coding agents, with project-aware
+recommendations and a daily read-only discovery feed.
+
+## Project description
+
+Improving an AI coding agent still means hunting through GitHub, Reddit, X, and
+bookmarks, then copying files into several different agent directories. A week later,
+you may not remember where a skill came from, whether a better option has appeared,
+or how to remove it safely.
+
+Loadout turns that mess into one local CLI. Stable installs a bounded 30-skill daily
+setup from four pinned public sources. Power prepares a broader toolkit. Maximum
+keeps thousands of screened skill copies in a disabled local library, then recommends
+a focused active set for the current project. Custom mode installs one exact package
+without replacing the rest of your setup.
+
+Every change is previewed first. Loadout records source and version ownership, checks
+for collisions and risky files, protects user edits, and creates a rollback snapshot
+before it changes managed files. MCP servers and executable tools remain separate,
+explicit choices. The normal skill workflow does not require an OpenAI or Anthropic
+API key.
+
+The bundled catalog credits 53 pinned public repositories. A generated discovery
+snapshot currently watches 240 repositories, including 216 candidates that have not
+been promoted into the catalog. Loadout treats popularity as a reason to inspect a
+project, not proof that it is safe or useful.
+
+We built Loadout with Codex and GPT-5.6 during OpenAI Build Week. We used Codex for
+architecture, implementation, repository research, threat modelling, cross-platform
+work, and the founder testing loop. Real tests on Codex and Claude Code exposed bugs
+in rollback history, update performance, project activation, MCP configuration,
+runtime-tool inventory, and adopted-skill removal. Each reproducible failure became a
+regression test. The current release passes 625 tests, packaged CLI journeys, public
+CI, and a 1,000-skill performance gate.
+
+Loadout is published on npm and the code is public. The dashboard was deliberately
+removed because it duplicated the CLI and made the product harder to understand. The
+result is the product we wanted to use ourselves: one command-line control layer for
+the extensions around every AI coding agent.
+
+## Links
+
+- GitHub: https://github.com/VirajMishra1/loadout
+- npm: https://www.npmjs.com/package/loadout-ai
+- Release: https://github.com/VirajMishra1/loadout/releases/tag/v0.5.8
+- Demo: PASTE_PUBLIC_YOUTUBE_URL_HERE
+
+## Judge testing path
+
+```bash
+npm install --global loadout-ai@0.5.8
+loadout --version
+loadout guide
+loadout setup --mode stable
+```
+
+The Stable command previews first. It changes nothing until the reviewer approves
+the plan. The README and user test guide cover rollback, Maximum, project
+recommendations, MCP recipes, Graphify, discovery, and complete uninstall.
+
+## Final fields to verify
+
+- Category is Developer Tools.
+- All three teammates appear on the Devpost submission.
+- The public YouTube URL works while signed out.
+- The Codex `/feedback` session ID is present.
+- The GitHub, npm, and video links are correct.
+- The submission is submitted, not saved as a draft.

package/docs/UPSTREAM_LICENSE_DECISIONS.md

@@ -0,0 +1,32 @@
+# Upstream license decisions
+
+Reviewed on July 21, 2026 for the public `0.5.8` release.
+
+Loadout records `NOASSERTION` when it cannot identify one repository-wide SPDX
+license from the inspected source. Popularity, an official publisher, or a public
+GitHub repository does not replace a license grant.
+
+## Release decision
+
+The six records below remain in the credited catalog as source metadata. Loadout
+does not copy their source into the npm package, claim ownership, or assign them a
+license. A selected profile may fetch a pinned upstream snapshot only after showing
+the user a preview. MCP configuration and executable tools remain separate explicit
+actions.
+
+None of these six records is part of Stable. Stable continues to use four sources
+with identified SPDX licenses. People who select Power, Maximum, or a Custom package
+must review the linked upstream terms before using content marked `NOASSERTION`.
+
+| Catalog record                 | Upstream source                                                                 | Recorded decision                                                                                                                   |
+| ------------------------------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| OpenAI Skills Catalog          | [openai/skills](https://github.com/openai/skills)                               | Retain the pinned catalog pointer with `NOASSERTION`; no repository-wide root license was identified.                               |
+| Anthropic Skills               | [anthropics/skills](https://github.com/anthropics/skills)                       | Retain the pinned catalog pointer with `NOASSERTION`; no repository-wide root license was identified.                               |
+| Vercel Agent Skills            | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills)         | Retain the pinned catalog pointer with `NOASSERTION`; no repository-wide root license was identified.                               |
+| Vercel Skills                  | [vercel-labs/skills](https://github.com/vercel-labs/skills)                     | Retain the pinned catalog pointer with `NOASSERTION`; no repository-wide root license was identified.                               |
+| Sentry MCP                     | [getsentry/sentry-mcp](https://github.com/getsentry/sentry-mcp)                 | Retain the pinned catalog pointer with `NOASSERTION`; the root license file is not identified as a standard SPDX license by GitHub. |
+| Model Context Protocol Servers | [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) | Retain the pinned catalog pointer with `NOASSERTION`; the root license file is not identified as a standard SPDX license by GitHub. |
+
+This is a transparent product policy decision, not legal advice or a claim that the
+upstream material may be redistributed under Loadout's MIT license. Each upstream
+project keeps its own copyright and terms.

package/docs/USER_TEST_GUIDE.md

@@ -211,7 +211,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.5.6` completed, run `hash -r`, and confirm npm's global binary
+loadout-ai@0.5.8` 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loadout-ai",
-  "version": "0.5.6",
+  "version": "0.5.8",
   "private": false,
   "license": "MIT",
   "description": "Universal upgrade manager for AI coding agents",