loadout-ai 0.5.5 → 0.5.7

package/CHANGELOG.md

@@ -2,6 +2,39 @@
 
 ## Unreleased
 
+## 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
+
+- Resolve each repository's default-branch commit with a lightweight Git metadata
+  request before downloading files, deduplicate shared sources, and reuse exact
+  cached changed revisions for safety review.
+- Give changed repositories a bounded 120-second review window while keeping remote
+  commit checks at 30 seconds, so large reviewed sources do not produce permanent
+  false connectivity warnings under four-way concurrency.
+
+### Fixed
+
+- Complete update checks for large sources such as Scientific Agent Skills and
+  Awesome Copilot without weakening static diff analysis, activating disabled skills,
+  or treating a timed-out clone as a GitHub outage.
+
 ## 0.5.5 - 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.6`; 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
+
+- [ ] Install the exact public npm release in a fresh terminal and run the final short
+      path: Humanizer Custom preview/apply/scan/rollback, read-only update/discovery,
+      complete uninstall, and clean reinstall. Stable, Power, Maximum, project
+      optimization, Graphify, and both-host Playwright MCP lifecycles have already
+      been exercised on the founder's real profiles.
+- [ ] Decide whether to rename the GitHub repository from `loadout` to `loadout-ai`.
+      If approved, rename it before recording and update canonical links; keep the
+      product name **Loadout** and npm package/CLI identity `loadout-ai` / `loadout`.
+- [ ] Make the six unresolved upstream-license decisions explicit. Do not silently
+      convert `NOASSERTION` into a license claim because a repository is popular.
+
+### 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.
+- [ ] Confirm the repository URL is accessible to Devpost and OpenAI.
+- [ ] Confirm all team invitations are accepted, 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
 
@@ -328,6 +394,14 @@ merged `codex/relatable-readme-hero` remote branch remains safe to delete after
       managed drift, and no active adopted-skill update. Release this correction
       before the remaining Graphify removal, discovery, uninstall, and reinstall
       acceptance steps.
+- [x] `P18-46 [TERRA]` Eliminate the repeated large-repository timeout exposed by the
+      published `0.5.5` founder check. Resolve remote HEAD metadata before fetching
+      content, download only changed revisions that require static safety analysis,
+      reuse immutable cached snapshots, and allow those bounded reviews 120 seconds.
+      The real 40-record Maximum state now completes with 19 disabled-library
+      changes, 21 current packages, zero active updates, and zero unavailable checks;
+      both previously failing large repositories complete without changing or
+      activating any agent-visible skill.
 
 ### Release 0.3 lifecycle hardening
 
@@ -2127,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.5`; review the preview before every apply.
+## Install
+
+You need Node.js 20 or newer and Git.
+
+```bash
+npm install --global loadout-ai@0.5.7
+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?**—and 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.5
-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:
+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.
 
-```bash
-git clone https://github.com/VirajMishra1/loadout.git
-cd loadout
-npm ci
-npm run build
-npm link
-loadout --version
-```
+### Demo
 
-For a first read-only preview, run:
+**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.
 
-```bash
-loadout setup --mode stable
-```
-
-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
+```
+
+### 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
 
-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.
+# 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)**.
@@ -250,20 +375,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       | 620 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 +495,7 @@ 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)
+- [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.5";
+const LOADOUT_VERSION = "0.5.7";
 function durableSchedulerLauncher() {
     return [
         join(dirname(process.execPath), process.platform === "win32" ? "npx.cmd" : "npx"),
@@ -909,7 +909,7 @@ program
     .option("--agents <ids>", "limit explained scores to selected agent ids")
     .action(async (options) => {
     if (options.updates && !options.json)
-        console.error("Checking managed repositories (4 at a time, 30s per network operation)…");
+        console.error("Checking repository commits (4 at a time; changed sources may take up to 120s for safety review)…");
     const report = await buildHealthReport({
         updates: options.updates
             ? () => buildUpdatePlan(undefined, {
@@ -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) {
@@ -2857,7 +2858,7 @@ program
         profile = await evaluateInstalledProfile(catalog);
     }
     if (!options.json)
-        console.error("Checking managed repositories (4 at a time, 30s per network operation)…");
+        console.error("Checking repository commits (4 at a time; changed sources may take up to 120s for safety review)…");
     let plans = await buildUpdatePlan(undefined, {
         packageId: options.package,
         onProgress: options.json

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/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/source.js

@@ -144,6 +144,36 @@ export function normalizeRepository(input) {
     }
     return value;
 }
+export function parseRepositoryHead(repository, output) {
+    const commit = output
+        .split(/\r?\n/)
+        .map((line) => line.split(/\s+/))
+        .find((parts) => parts[1] === "HEAD" && /^[0-9a-f]{40}$/i.test(parts[0]))?.[0];
+    if (!commit)
+        throw new Error(`Git returned an invalid default-branch HEAD for ${repository}`);
+    return commit;
+}
+/** Resolve the public default-branch commit without downloading repository files. */
+export async function resolveRepositoryHead(input, options = {}) {
+    const repository = normalizeRepository(input);
+    const gitEnvironment = await isolatedGitEnvironment(loadoutHome());
+    const url = `https://github.com/${repository}.git`;
+    try {
+        const { stdout } = await execFileAsync("git", ["ls-remote", "--symref", "--", url, "HEAD"], {
+            maxBuffer: 1024 * 1024,
+            timeout: options.timeoutMs,
+            env: gitEnvironment,
+        });
+        return {
+            repository,
+            commit: parseRepositoryHead(repository, stdout),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not resolve ${repository}: ${message}`);
+    }
+}
 function normalizeRef(ref) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(ref) ||
         ref.includes("..") ||

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/core/update.js

@@ -1,6 +1,6 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
-import { fetchRepositorySnapshot } from "./source.js";
+import { fetchRepositorySnapshot, resolveRepositoryHead } from "./source.js";
 import { repositoryCachePath } from "./source.js";
 import { diffRepositorySnapshots } from "./diff.js";
 import { hashDirectory, readInstallState } from "./state.js";
@@ -85,21 +85,39 @@ async function analyzeManagedUpdate(oldRoot, newRoot, unitIds) {
     };
 }
 /** Builds a read-only update plan from persisted installs and live GitHub snapshots. */
-export async function buildUpdatePlan(resolver = async (repository) => fetchRepositorySnapshot(repository, { timeoutMs: 30_000 }), options = {}) {
+export async function buildUpdatePlan(resolver, options = {}) {
     const state = await readInstallState();
     const records = options.packageId
         ? state.installs.filter((record) => record.packageId === options.packageId)
         : state.installs;
     const results = new Array(records.length);
+    const lightweightResolver = resolver ??
+        options.resolveHead ??
+        ((repository) => resolveRepositoryHead(repository, { timeoutMs: 30_000 }));
     const resolutions = new Map();
     const resolveOnce = (repository) => {
         const existing = resolutions.get(repository);
         if (existing)
             return existing;
-        const pending = resolver(repository);
+        const pending = lightweightResolver(repository);
         resolutions.set(repository, pending);
         return pending;
     };
+    const changedSnapshots = new Map();
+    const fetchChangedOnce = (repository, commit) => {
+        const key = `${repository}\0${commit.toLowerCase()}`;
+        const existing = changedSnapshots.get(key);
+        if (existing)
+            return existing;
+        const pending = options.fetchChangedSnapshot
+            ? options.fetchChangedSnapshot(repository)
+            : fetchRepositorySnapshot(repository, {
+                ref: commit,
+                timeoutMs: 120_000,
+            });
+        changedSnapshots.set(key, pending);
+        return pending;
+    };
     let cursor = 0;
     let completed = 0;
     const workers = Array.from({
@@ -139,9 +157,16 @@ export async function buildUpdatePlan(resolver = async (repository) => fetchRepo
                     let diff;
                     let safetyFindings;
                     let approvalRequired = false;
-                    if (!same && current.path) {
+                    let currentPath = current.path;
+                    if (!same && !currentPath && !resolver) {
+                        const fetched = await fetchChangedOnce(record.repository, current.commit);
+                        if (fetched.commit.toLowerCase() !== current.commit.toLowerCase())
+                            throw new Error(`Resolved ${current.commit}, but fetched ${fetched.commit} for safety review`);
+                        currentPath = fetched.path;
+                    }
+                    if (!same && currentPath) {
                         const oldPath = repositoryCachePath(record.repository, record.resolvedCommit);
-                        const analysis = await analyzeManagedUpdate(oldPath, current.path, managedUnitIds(state, record.packageId));
+                        const analysis = await analyzeManagedUpdate(oldPath, currentPath, managedUnitIds(state, record.packageId));
                         diff = analysis.diff;
                         safetyFindings = analysis.safetyFindings;
                         approvalRequired = analysis.approvalRequired;

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,155 @@
+# Loadout demo and voiceover
+
+Target length: **2:35–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.7
+   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–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–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–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–1:42 — broad library, focused project
+
+**Screen:** Use the already downloaded Maximum library from the acceptance run. Show
+the first part of `library`, then run the two read-only commands.
+
+```bash
+loadout library
+loadout recommend --project . --agent codex
+loadout optimize --project . --agents codex,claude-code --limit 30
+```
+
+**Say:**
+
+> Maximum does not dump thousands of skills into every prompt. It keeps the broad
+> screened catalog disabled, detects this TypeScript CLI project, and proposes a
+> focused active set for each agent. That is the core idea: discover broadly, activate
+> narrowly, and keep every change reversible.
+
+### 1:42–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–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–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/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.5` completed, run `hash -r`, and confirm npm's global binary
+loadout-ai@0.5.7` 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.5",
+  "version": "0.5.7",
   "private": false,
   "license": "MIT",
   "description": "Universal upgrade manager for AI coding agents",