loadout-ai 0.2.3 → 0.4.0

package/docs/REPOSITORY_STABILIZATION.md

@@ -0,0 +1,190 @@
+# Repository stabilization record
+
+Status date: 2026-07-19. This document records evidence gathered while consolidating
+the repository. `MASTER_PLAN.md` is the only active plan; this is an audit record, not
+a second backlog.
+
+## Starting synchronization inventory
+
+The investigation fetched all visible branches and tags before making cleanup
+decisions. The starting GitHub default was `main` at
+`189cb7a0e918860fc37bb92639126b93b387abec` (`v0.3.2`).
+
+| Local branch/worktree                             | Starting head | Tracking state                                              | Starting disposition                        |
+| ------------------------------------------------- | ------------- | ----------------------------------------------------------- | ------------------------------------------- |
+| `codex/readme-truth`, `/tmp/loadout-readme-truth` | `ee8d548`     | 29 ahead of `origin/main`, clean                            | Preserve and integrate                      |
+| `dev/nitish`, user checkout                       | `69b8fe7`     | one ahead of `origin/dev/nitish`; untracked `.superpowers/` | Preserve user state and safety requirements |
+| local `main`                                      | `d2a11d8`     | 101 behind `origin/main`                                    | Fast-forward after integration              |
+| local `develop`, `dev/amartya`, `dev/viraj`       | `d2a11d8`     | stale or merged                                             | Remove after final-main verification        |
+
+No local commit was treated as remote merely because it existed in a worktree.
+
+## Failure ledger
+
+| Failure                                                                                           | Reproduction/evidence                                                                                                                                                                                                                                                                                                                                            | Root cause/classification                                                                   | Resolution/status                                                                                                                                                                    |
+| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Risky setup preview omitted `--approve-risk`                                                      | Prepared risky catalog plan printed an incomplete rerun command                                                                                                                                                                                                                                                                                                  | Product guidance defect                                                                     | Fixed in `1f62a1b`; regression test derives guidance from the prepared plan                                                                                                          |
+| Unknown command ran default onboarding                                                            | Unknown positional top-level command reached the root action                                                                                                                                                                                                                                                                                                     | CLI routing defect                                                                          | Fixed in `1f62a1b`; unknown commands fail non-zero while bare invocation remains valid                                                                                               |
+| Explicit rollback could erase later user changes                                                  | Persisted snapshots recorded only pre-mutation bytes                                                                                                                                                                                                                                                                                                             | Product data-safety defect                                                                  | Fixed in `1f62a1b`; committed post-state is checked before user-requested rollback                                                                                                   |
+| Dashboard and special-file rollback bypasses                                                      | Default dashboard restore omitted the guard; nested FIFOs/sockets/devices were skipped                                                                                                                                                                                                                                                                           | Product data-safety defect                                                                  | Fixed in `6fd1a2c`; dashboard and unsupported-entry regressions pass                                                                                                                 |
+| `dev/nitish` adoption preview covered only `SKILL.md` while ownership covered the whole directory | Deletion review traced preview through apply and `recordInstall`; auxiliary drift, cloned-plan forgery, and review over-attribution were reproducible                                                                                                                                                                                                            | Product ownership/integrity defect; valuable safety intent existed only on the stale branch | Fixed in the current architecture by `186daa0`, `09e0e0c`, `3f2cafe`, and `10d6109`; focused and full verification pass                                                              |
+| Fresh-clone live Stable rollback refused on `state.json`                                          | `npm run check:live -- --stable-install` installed four pinned packages, then refused the Stable snapshot because later state differed                                                                                                                                                                                                                           | Product transaction-boundary defect plus invalid non-LIFO evidence-flow ordering            | `5f8e38e` records profile state inside the catalog transaction and rolls Stable back before unrelated fixture transactions; exact state and managed-root drift checks remain enabled |
+| Windows snapshot-root test used a POSIX fixture                                                   | CI run `29502017220` executed at `41b53e0`; Windows reported “absolute normalized path” before the test's expected “filesystem root” message                                                                                                                                                                                                                     | Test portability defect, not a runtime rollback failure                                     | `c5fe192` changed the fixture to the host filesystem root; rerun `29502324100` passed                                                                                                |
+| Recent GitHub CI and discovery runs did not start                                                 | Earlier blocked runs plus CI runs [`29691581581`](https://github.com/VirajMishra1/loadout/actions/runs/29691581581) and [`29692535521`](https://github.com/VirajMishra1/loadout/actions/runs/29692535521) have no executed steps; both CI annotations say the job was not started because recent account payments failed or the spending limit must be increased | GitHub account billing/spending-limit condition                                             | External failure; no product-test result was produced                                                                                                                                |
+| `loadout-ai@0.3.2` unavailable                                                                    | npm registry version list ends at `0.3.1`; bounded live evidence records the same result                                                                                                                                                                                                                                                                         | Package publication                                                                         | Not verified; publish and test the exact tarball externally                                                                                                                          |
+| `main` protection unavailable                                                                     | GitHub branch-protection endpoint returns 404                                                                                                                                                                                                                                                                                                                    | Repository setting/authorization                                                            | Absent or not observable; requires owner decision                                                                                                                                    |
+
+Internal failed-transaction recovery deliberately restores the pre-mutation snapshot
+without the later-drift guard. The guard applies to user-requested CLI, dashboard, and
+runtime-tool rollback. Legacy snapshots fail closed for those explicit paths.
+
+## Recent Viraj commits and GitHub Actions
+
+The recent Viraj changes were inspected as code and exercised locally; commit messages
+were not used as proof.
+
+| Commit    | Implemented area                                                                                     | Main/Actions evidence                                                                                                                                                                       |
+| --------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `817c38f` | Public-beta CLI, package, credential, catalog, and release foundation                                | In `main`; CI run `29486160804` passed                                                                                                                                                      |
+| `9798f1c` | Continuous discovery, generated catalog evidence, and snapshot hardening                             | In `main`; CI run `29491118338` passed                                                                                                                                                      |
+| `6994d4e` | Candidate intelligence, signed catalog release, locking, and transaction hardening                   | In `main`; CI run `29497632211` passed                                                                                                                                                      |
+| `41b53e0` | Stable profile, daily autopilot, and release workflow                                                | In `main`; CI run `29502017220` failed on the Windows-only test fixture described above                                                                                                     |
+| `c5fe192` | Host-portable snapshot root guard test                                                               | In `main`; CI rerun `29502324100` passed                                                                                                                                                    |
+| `4e93f5d` | Cross-platform release-matrix documentation                                                          | In `main`; CI run `29502646004` passed                                                                                                                                                      |
+| `05e52a4` | Expanded Stable profile and reviewed Graphify recipe                                                 | In `main`; CI run `29505093720` passed                                                                                                                                                      |
+| `f7f53fa` | Release-work documentation clarification                                                             | In `main`; CI run `29505532691` was cancelled after a newer push; no product failure was produced                                                                                           |
+| `e35b8ff` | Upgrade, health-score, benchmark-campaign, and discovery foundation                                  | In `main`; CI run `29508916710` passed                                                                                                                                                      |
+| `3cb5505` | Trust, intelligence, benchmark, import, and skill-security systems                                   | In `main`; CI run `29520771134` passed                                                                                                                                                      |
+| `8e80ab4` | npm beta metadata and package-smoke adjustment                                                       | In `main`; CI run `29522705571` passed                                                                                                                                                      |
+| `1fe9890` | Codex Desktop installation detection                                                                 | In `main`; CI run `29524710934` and discovery run `29557150915` passed                                                                                                                      |
+| `e4e469e` | Credential-aware setup, Maximum quarantine, and managed update scoping                               | In `main`; CI run `29583273859` passed                                                                                                                                                      |
+| `ebb8133` | Unit-level Power quarantine and onboarding rewrite                                                   | In `main`; CI run `29585379546` passed                                                                                                                                                      |
+| `88466ef` | npm `0.2.0` verification documentation                                                               | In `main`; CI run `29586111523` passed                                                                                                                                                      |
+| `cf406e8` | Safe Stable/profile setup reruns                                                                     | In `main`; CI run `29588415904` passed                                                                                                                                                      |
+| `a016c0f` | Exact managed-profile reconciliation                                                                 | In `main`; CI run `29590309101` passed                                                                                                                                                      |
+| `33225ef` | Large rollback-snapshot validation                                                                   | In `main`; CI run `29591059217` passed                                                                                                                                                      |
+| `15f36e3` | Pinned Graphify generated fallback                                                                   | In `main`; CI run `29591567247` passed                                                                                                                                                      |
+| `16b8a7e` | Beginner and advanced CLI routing                                                                    | In `main`; covered by current CLI tests                                                                                                                                                     |
+| `31cb755` | Saved-profile updates and complete uninstall                                                         | In `main`; its CI job never started because of billing                                                                                                                                      |
+| `56ab3af` | Separation of model API keys from service credentials                                                | In `main`; its CI job never started because of billing                                                                                                                                      |
+| `189cb7a` | Recursively empty skill-directory recovery                                                           | In `main`; its CI job never started because of billing                                                                                                                                      |
+| `e74ba16` | Consolidated README truth, lifecycle hardening, safety fixes, adoption integrity, and cleanup record | Integrated into remote `main`; CI run [`29692535521`](https://github.com/VirajMishra1/loadout/actions/runs/29692535521) failed before steps because of the billing/spending-limit condition |
+| `5f8e38e` | Transactional installed-profile state and valid live Stable rollback ordering                        | Integrated into remote `main`; verified again from a fresh clone                                                                                                                            |
+
+Earlier green runs prove their own commits only. They do not prove later commits that
+GitHub never executed. Current local verification and future post-integration Actions
+must remain separately reported.
+
+## Branch cleanup observations during consolidation
+
+At the 2026-07-19 consolidation checkpoint, there was one merged PR:
+[#1](https://github.com/VirajMishra1/loadout/pull/1), `dev/nitish` into `develop`,
+merged as `69594f2`; its recorded Linux, macOS, and Windows Node 20/22 jobs passed.
+The authenticated query at that checkpoint returned no open PRs.
+
+| Branch                                    | Unique work relative to starting `origin/main`                                                                                                    | Final result                                                                     |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `codex/readme-truth`                      | README evidence, adapter/product-flow coverage, release hardening, safety fixes, and consolidation                                                | Integrated into `main`; local and remote branch deleted                          |
+| `dev/nitish`                              | Its one real adoption-integrity gap is fully reimplemented and tested by `186daa0`, `09e0e0c`, `3f2cafe`, and `10d6109`; no valuable work remains | Local and remote branch deleted; unrelated `.superpowers/` preserved and ignored |
+| `codex/cli-ux-polish`                     | None; tip `31cb755` is in main                                                                                                                    | Local and remote branch deleted                                                  |
+| `codex/fix-large-snapshot-validation`     | None; tip `33225ef` is in main                                                                                                                    | Local and remote branch deleted                                                  |
+| `codex/fix-profile-reconciliation`        | None; tip `a016c0f` is in main                                                                                                                    | Local and remote branch deleted                                                  |
+| `codex/fix-stable-rerun`                  | None; tip `cf406e8` is in main                                                                                                                    | Local and remote branch deleted                                                  |
+| `codex/harden-graphify-generated-install` | None; tip `15f36e3` is in main                                                                                                                    | Local and remote branch deleted                                                  |
+| `dev/amartya`                             | Integrated through `6161c48` and later follow-ups                                                                                                 | Local and remote branch deleted                                                  |
+| `dev/viraj`                               | Old main ancestor                                                                                                                                 | Local and remote branch deleted                                                  |
+| `develop`                                 | Old integration ancestor                                                                                                                          | Local and remote branch deleted                                                  |
+
+Cleanup completed only after the integrated work reached remote `main` and the open-PR
+list was empty. At that checkpoint, Git exposed only local `main`, `origin/main`, and
+the retained release tags. The `/tmp/loadout-readme-truth` worktree had been removed.
+The user's untracked `.superpowers/` directory remained present and ignored by
+`.gitignore`; no user artifact was deleted.
+
+## Planning and dead-file consolidation
+
+`MASTER_PLAN.md` is authoritative because Viraj created it, maintained it across the
+project history, linked it from README, and explicitly labeled its top section as the
+active list. The removed files were unreferenced or self-described historical plans
+whose implementation/status had moved elsewhere.
+
+| Removed file                                         | Evidence for deletion                                   | Preserved outcome                                            |
+| ---------------------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------ |
+| `NITISH_MASTER_PLAN.md`                              | Unreferenced; stale `dev/nitish`/`develop` policy       | Durable safety work is in the master plan and implementation |
+| `SIMPLE_PLAN.md`                                     | Duplicate summary that named `MASTER_PLAN.md` canonical | README retains the user-facing summary                       |
+| `docs/plans/2026-07-18-release-0.3.md`               | Completed code plan with stale merge/publish boxes      | External publication remains explicit in the master plan     |
+| `docs/superpowers/plans/2026-07-18-cli-ux-polish.md` | Implemented on main; stale commit/verify boxes          | Founder testing remains explicit in the master plan          |
+| README truth implementation plan and design          | Implemented, reviewed, and encoded by tests/evidence    | Current status is in the master plan and release evidence    |
+
+Operational contracts such as `docs/TESTING.md`, `docs/FEATURE_TEST_MATRIX.md`,
+`docs/RELEASE_REVIEW.md`, policy documents, and machine-readable evidence remain.
+
+## README research and redesign evidence
+
+The redesign research is recorded at immutable commits rather than mutable default
+branches:
+
+| Repository | Immutable README reference                                                                                      |
+| ---------- | --------------------------------------------------------------------------------------------------------------- |
+| Ponytail   | [`16f2980`](https://github.com/DietrichGebert/ponytail/blob/16f29800fd2681bdf24f3eb4ccffe38be3baec6b/README.md) |
+| uv         | [`1535a67`](https://github.com/astral-sh/uv/blob/1535a6767e5ebd77eac2ace0f6cf1a3edc5f681c/README.md)            |
+| bat        | [`7895139`](https://github.com/sharkdp/bat/blob/78951393e29bfd2f2a45f4326b9d2bb5e737dd2a/README.md)             |
+| fzf        | [`b163463`](https://github.com/junegunn/fzf/blob/b163463079e6254b8582b05acefcf187ec160d9b/README.md)            |
+| ripgrep    | [`227381d`](https://github.com/BurntSushi/ripgrep/blob/227381db0ee83dfa4341f1e27ff9617c0f5ad992/README.md)      |
+| mise       | [`126e775`](https://github.com/jdx/mise/blob/126e7755cc22e36c3d206b650de613951146b5e3/README.md)                |
+| Gum        | [`716d8b5`](https://github.com/charmbracelet/gum/blob/716d8b5d0221558f944b5a078dbbcca8572534fb/README.md)       |
+| Starship   | [`8f28dfc`](https://github.com/starship/starship/blob/8f28dfcb1ca3242fba00a3cf98c10ee24605c3ed/README.md)       |
+
+`docs/README_RESEARCH.md` records the adopted principles and rejected patterns. The
+front page should present the bounded product journey and link to evidence, not repeat
+an exhaustive manual. In particular, the complete adapter table belongs in
+`docs/FEATURE_TEST_MATRIX.md`, not on the front page. A compact front-page support
+summary must continue to distinguish configured target paths and disposable
+filesystem tests from unverified native-agent recognition and execution.
+
+## Dated external observations before the README redesign
+
+These observations were captured on 2026-07-19 before README-redesign work began.
+They are a historical checkpoint, not claims about repository state when this document
+is later read.
+
+- GitHub repository: the private fork was `reddynitish/loadout`; its default branch
+  was `main` at `18757d4`. The earlier `VirajMishra1/loadout` observations in this
+  record describe the upstream repository at the time of consolidation.
+- Branches and PRs: `codex/readme-redesign` was the local work branch; the
+  authenticated check found no open pull requests in the fork at that time.
+- npm: the registry exposed versions through `0.3.1`; `0.3.2` was not verified as
+  published.
+- GitHub Actions: fork CI run
+  [`29704170975`](https://github.com/reddynitish/loadout/actions/runs/29704170975) passed
+  for `main` at `18757d4`. The upstream billing-blocked runs above were historical
+  evidence only and did not describe the fork's CI capability.
+- Branch protection: the authenticated protection endpoint returned HTTP 403 stating
+  that the private repository requires GitHub Pro or public visibility for the
+  feature. Protection was unavailable under the observed repository plan; this was
+  not a product-runtime result.
+- Native application consumption of every configured adapter path was unverified;
+  disposable filesystem lifecycle evidence did not establish native-host support.
+
+## Local verification after consolidation
+
+On 2026-07-19, `npm run verify:full` completed successfully on macOS with Node 25.4.0:
+
+- formatting, lint, type checking, build, catalog/discovery evidence, README claims,
+  and release claims passed;
+- 112 Vitest files passed with 589 tests passing and one intentionally skipped;
+- CLI and README product flows passed;
+- packaged CLI smoke passed;
+- the 1,000-skill scan benchmark passed at 240.5 ms p95 across seven CLI runs; and
+- both desktop Chromium and mobile Chromium dashboard tests passed.
+
+The fresh-clone live Stable gate also installed four pinned packages and completed
+state and filesystem rollback assertions at `5f8e38e`. An initially considered
+state-ignore fix was rejected during independent review because restoring an old
+registry while leaving later package files could orphan installations. The final fix
+keeps exact `state.json` and managed-root drift protection, includes installed-profile
+state in transaction post-evidence, and uses strict LIFO ordering in the live flow.
+
+An npm dry-run contained 137 entries, included this record and `MASTER_PLAN.md`, and
+excluded every deleted plan. These local results do not substitute for GitHub Actions,
+the unpublished `0.3.2` npm tarball, native-host acceptance, or branch protection.

package/docs/TESTING.md

@@ -31,6 +31,56 @@ This test does not use the dashboard, network, mock command output, or any real
 profile. It is a required CI gate on Ubuntu; the manual cross-platform workflow runs
 the broader native filesystem suite.
 
+The README journey is a separate deterministic gate. It compiles an isolated build,
+installs a local reviewed fixture into disposable Loadout/user homes, checks its
+manifest, lock, hashes, privacy card, activation, and rollback, then deletes the
+fixture and build:
+
+```bash
+npm run test:e2e:readme
+```
+
+### README product-flow verification contract
+
+The README gate is a mixed core-integration/CLI flow, not a claim that two complete
+native-agent journeys run end to end. It deliberately:
+
+- compiles into an isolated temporary build instead of trusting the repository's
+  existing `dist` tree;
+- redirects Loadout state, user-home, and project paths to disposable directories;
+- uses a checked-in offline fixture, so its normal result does not depend on the
+  network or mutable upstream repositories;
+- calls the core planner and installer directly to verify fixture planning, library
+  installation, manifest and lock generation, recorded hashes, and audit state; and
+- starts CLI subprocesses to verify optimize preview/apply, privacy-safe card
+  rendering, and rollback restoration through the packaged command boundary.
+
+The executable outcome assertions also require isolated-build and offline-fixture
+mode, created state directories, persisted install records, file hashes, snapshots,
+library transitions, manifest/lock consistency, an unmanaged sentinel that survives,
+and byte restoration after rollback.
+
+These checks prove Loadout's behavior against disposable filesystem targets. They do
+not prove that every native agent recognizes or executes an installed skill, that a
+live catalog is reachable, that the current npm package is published, or that third-party content
+is universally safe. The opt-in `LOADOUT_TEST_LIVE_CATALOG=1` extension separately
+checks the current pinned Stable sources and remains network-dependent.
+
+Run `npm run verify` for formatting, lint, types, deterministic evidence checks, all
+Vitest suites, both CLI journeys, package smoke, and the performance gate. Run
+`npm run verify:full` only when Playwright Chromium is installed and the optional
+dashboard browser test is also wanted.
+
+Current npm publication, the current pinned Stable repositories, and GitHub repository
+settings are external state. Check them separately with:
+
+```bash
+npm run check:live -- --npm --stable-install --github
+```
+
+Each requested check reports `verified`, `failed`, or `not-verified`; missing access is
+not converted into a pass.
+
 ## 1. Build the exact npm package entry point
 
 ```bash
@@ -199,8 +249,20 @@ write to the detected real agent profiles. After npm publication, replace `npx .
 
 ## 8. Test credential-gated MCP configuration without exposing a key
 
-The Playwright recipe has no service credential. The GitHub read-only recipe does and
-must refuse `--yes` until its declared environment reference resolves:
+List the reviewed recipes that need no separately billed AI/model API key:
+
+```bash
+npx . mcp-recipe --no-key
+```
+
+This includes Playwright, Chrome DevTools, and GitHub read-only. The first two have no
+service credential. GitHub read-only needs a GitHub token and must refuse `--yes`
+until its declared environment reference resolves. Use `--credential-free` for the
+stricter zero-credential list:
+
+```bash
+npx . mcp-recipe --credential-free
+```
 
 ```bash
 npx . mcp-recipe github-readonly --config "$TEST_HOME/mcp.json" --yes
@@ -230,3 +292,14 @@ npx . dashboard
 Open the printed loopback URL. CLI setup, updates, removal, discovery, and rollback all
 work without it. Browser automation is also optional and runs only when manually
 dispatched in CI; locally, use `npm run test:e2e:dashboard`.
+
+## Final cleanup test
+
+```bash
+npx . uninstall
+npx . uninstall --yes
+```
+
+The first command is a dry run. The second removes only Loadout-managed agent files,
+runtime tools, native jobs, state, snapshots, and cache; it leaves the locally invoked
+package itself alone. Use `--remove-cli` only when testing a global npm install.

package/docs/USER_TEST_GUIDE.md

@@ -0,0 +1,202 @@
+# Test Loadout on your own machine
+
+This is the short, safe route through the product. Start in a normal terminal.
+The first group only reads local state or prepares a preview; it does not replace
+agent files. A preview can download reviewed source into Loadout's cache, but it
+does not activate skills or change an agent configuration.
+
+## 1. Get oriented
+
+```bash
+loadout guide
+loadout library
+loadout scan
+loadout health
+```
+
+`library` is the concise provenance view: it shows active skills and disabled
+reviewed-library copies per agent. For the full source-package and upstream-repository
+record for every skill, use `loadout library --all`. `scan` distinguishes
+Loadout-managed skills from your own pre-existing skills. `health` checks local drift only; add
+`--updates` only when you want it to contact the tracked public repositories.
+
+## 2. Explore without installing
+
+```bash
+loadout catalog --json
+loadout candidate list --limit 10
+loadout recommend --project .
+loadout optimize --project .
+loadout tool
+loadout tool graphify
+```
+
+Run the project commands from the project you care about, or replace `.` with its
+absolute path. `optimize` is still a preview until `--yes` is supplied. `tool
+graphify` is also a preview; Graphify is a reviewed runtime tool and does not
+need an OpenAI or Anthropic API key for its code-only install.
+
+## 3. Open the optional dashboard
+
+```bash
+loadout dashboard
+```
+
+Open the `http://127.0.0.1:PORT` address it prints. It never listens on the
+network. The dashboard shows status, health, installed packages, updates, local
+project recommendations, profiles, and the catalog. Its Apply and Undo buttons
+require an in-page preview, acknowledgement, and a private local session token.
+Stop the server with `Control-C`.
+
+## 4. Preview and install a profile
+
+Use this order. Each setup command previews first; interactive setup asks for
+confirmation before changing files. A mutation creates a snapshot first.
+
+```bash
+# Recommended everyday skills
+loadout setup --mode stable --agents codex,claude-code
+
+# Broader daily-use selection (50 curated skill directories)
+loadout setup --mode power --agents codex,claude-code
+
+# Download the broad reviewed library while keeping the active set controlled
+loadout setup --mode maximum --agents codex,claude-code
+```
+
+At the API-access question, choose `None` unless you separately pay for a
+provider API. A ChatGPT Plus or Claude Pro subscription is not an API key. Core
+skill profiles do not require one; credentialed MCP and runtime operations stay
+explicit.
+
+For unattended use only after reviewing a preview, the equivalent is:
+
+```bash
+loadout setup --mode stable --agents codex,claude-code --yes
+```
+
+Do not add `--approve-risk` unless the displayed preview identifies a specific
+reviewed finding and you understand it.
+
+## 5. Test a change and recover
+
+```bash
+# Preview Graphify, then install only if the preview looks right
+loadout tool graphify --agents codex,claude-code
+loadout tool graphify --agents codex,claude-code --yes --approve-risk
+
+# Check the exact current state
+loadout library
+loadout health
+
+# Restore a prior snapshot if you do not like the result
+loadout rollback --list
+loadout rollback
+
+# Or remove only Graphify and restore its pre-install agent state
+loadout tool graphify --remove --agents codex,claude-code --yes --approve-risk
+```
+
+`rollback` restores a whole Loadout snapshot. The tool-specific remove command
+is narrower and is preferable when you only want to undo that one runtime tool.
+
+## 6. Test daily discovery and updates
+
+```bash
+loadout alerts
+loadout update
+loadout update --package superpowers
+loadout autopilot
+```
+
+`update --package` checks only the named tracked package. The default is a
+read-only diff and safety plan. Apply only after review:
+
+```bash
+loadout update --package superpowers --apply
+loadout update --yes
+```
+
+`autopilot` previews two native daily read-only jobs (updates and discovery).
+Enable or remove both explicitly:
+
+```bash
+loadout autopilot --time 09:00 --yes
+loadout autopilot --remove --yes
+```
+
+The daily update job re-evaluates your saved Stable, Power, or Maximum profile and
+checks every managed package, but never supplies `--yes`. Daily discovery can add
+interesting repositories to the review queue; it cannot silently promote or install
+them.
+
+## 7. Test MCP choices without a model API key
+
+```bash
+loadout mcp-recipe --no-key
+```
+
+Expect Playwright MCP, Chrome DevTools MCP, and GitHub read-only. None requires a
+separately billed AI/model API key. GitHub read-only still discloses that it needs a
+GitHub token; use `loadout mcp-recipe --credential-free` to exclude every service
+credential too. Browser configuration and real connection testing remain explicit.
+Graphify is a separate runtime tool, not an MCP server.
+
+## 8. Preview complete cleanup
+
+```bash
+loadout uninstall
+```
+
+Read the package, runtime, scheduler, and state summary. The preview changes nothing.
+At the very end of testing, remove all Loadout-managed data while keeping the CLI:
+
+```bash
+loadout uninstall --yes
+```
+
+To remove the npm command too, use `loadout uninstall --yes --remove-cli`. Complete
+cleanup deliberately deletes Loadout's snapshots, so it is the last lifecycle test.
+
+## Troubleshooting and recovery
+
+- **`loadout` is not found after installation:** confirm `npm install --global
+loadout-ai@0.4.0` completed, run `hash -r`, and confirm npm's global binary
+  directory is on `PATH`. For a source checkout, run `npm run build` and `npm link`.
+- **A preview asks for `--approve-risk`:** read the reported scripts, domains,
+  credentials, binaries, or instruction findings. If you accept that specific plan,
+  use the exact rerun command Loadout prints. The flag is not a general safety
+  guarantee and should not be added routinely.
+- **Rollback or removal is refused:** preserve the current files. Refusal can mean a
+  managed path changed, disappeared, changed type, gained content, or belongs to a
+  legacy snapshot without post-mutation evidence. Run `loadout health --explain` and
+  inspect the affected path before deciding whether an explicit force option is
+  appropriate; do not delete the path merely to make the command pass.
+- **A fetch, discovery, or update check fails:** retry only after checking network,
+  proxy, DNS, and source-host access. Local inventory, library, health, rollback, and
+  offline fixture tests remain separate; an unavailable live check is not a pass.
+- **You need diagnostics:** run `loadout doctor`, `loadout health --explain`, and
+  `loadout status`. Redact usernames, local paths, repository names, tokens, and agent
+  state before sharing output.
+- **You need complete removal:** first preview with `loadout uninstall`, then use
+  `loadout uninstall --yes` to remove managed agent files, runtime tools, scheduled
+  jobs, cache, snapshots, and state. Add `--remove-cli` only for a global npm install.
+  Unmanaged content is preserved, and modified managed files can make cleanup refuse
+  until you explicitly review the command's force path.
+
+## 9. Advanced surface
+
+The first help screen deliberately focuses on daily use. Existing advanced
+commands have not been removed:
+
+```bash
+loadout advanced
+loadout candidate --help
+loadout mcp-recipe --help
+loadout <command> --help
+```
+
+Avoid running registry publishing, signing, sandbox, credential, or arbitrary
+MCP configuration commands on your main profile as part of routine user testing.
+They are package-author or integration workflows, not required to use Loadout's
+core product.